Spill Storage zh

Spill 存储

上游工具输出溢出存储在 Edge 中的适配。

上游参考：Spill 存储文档

上游提供了什么

Spill 存储是一项可选能力接缝，用于持久化大型工具输出并返回带检索指引的模型可见定位符。包含三个包：

• dsh-spill — 服务定义：SpillStore 抽象类，包含单个 saveText() 方法。
• dsh-spill-local — 上游提供者：保存到本地文件系统。
• dsh-spill-policy — 消费者：将超过 maxInlineBytes 的工具结果替换为预览摘要和 spill 引用。

当工具输出超过策略阈值时，SpillPolicy 调用 ctx.spillStore.saveText() 存储完整内容，替换为截断预览 + retrievalHint（告诉模型如何读取溢出文件）。

Edge 改了什么

替换件 SpillStore → VFS

EdgeVfsSpillStore 继承上游 SpillStore 抽象类。不写本地文件系统（dsh-spill-local），而是写入 Cloudflare Computer VFS 的 /workspace/.spill/{name}_{callId}.txt。VFS writer 在 turn 期间绑定，turn 结束后解绑。

直接复用 SpillPolicy

SpillPolicy 原封安装，maxInlineBytes: 32_768。策略消费者、检索提示生成和预览截断完全是上游代码。

Edge 没有改什么

• SpillStore 接口（saveText 契约）
• SpillPolicy 阈值和预览行为
• SpillRef/SpillLocator 结构
• 模型可见的检索提示

性能特征

写入路径

saveText() 执行两个 VFS 操作：mkdir('/workspace/.spill', { recursive: true }) 和 writeFile(path, content)。均委托给 Computer VFS 后端。mkdir 在每个 session 的首次调用后是幂等的。

Spill 大小

工具输出超过 32 KB 时触发 spill。典型的溢出输出是 bash 命令结果（大目录列表、构建日志、测试输出）。完整内容写入 VFS；事件日志中只有截断预览。

架构总结

组件	分类	Edge 代码
EdgeVfsSpillStore	替换	约 30 行（继承 SpillStore，写入 VFS）
SpillPolicy	复用	一行 ctx.plugin() 调用

关键观察：Spill 存储是教科书级的最小替换件——上游抽象类定义契约，Edge 提供 30 行 VFS 实现，上游策略消费者无需修改即可工作。