deepseek-harness/packages/spill/spill-local/README.zh.md

@deepseek-ai/dsh-spill-local

English | 中文

@deepseek-ai/dsh-spill 存储 seam 的本地文件系统 实现。它注册为 ctx.spillStore，将工具过大的文本持久化到私有的会话级文件；定位信息是文件路径，取回指引会告诉模型对该路径使用 read 或 grep。

存储布局

文件存放在 <root>/session-<hash>/​<random>-<safeName>：

• root：使用配置中的 root（解析为绝对路径）；如果省略，则在操作系统临时目录下延迟创建每进程私有（0700）目录。可预测且全球可读的根目录会让其他本地用户读取 spill 工具输出，或在其中预置符号链接。
• session-<hash>：短 sha256(sessionId) 前缀，用于将一个会话的 spill 文件归组，以便未来的清理操作可按会话删除。
• <random>-<safeName>：不可预测的十六进制前缀（防止在共享根目录中预置符号链接），加上经过清理的调用方 suggestedName，使其成为单个安全路径段（防路径遍历；与 JSONL 持久化后端的 encodeSegment 一致）。写入操作为排他且仅所有者可读写（open(path, 'wx', 0o600)）：如果路径已经存在，无论是否为符号链接，操作都会失败，因此预置的目标无法重定向写入。

配置

键	默认值	含义
root	私有 0700 临时目录	spill 文件的根目录。进行设置可将它们保存在已知位置。

saveText 在发生真实存储故障（权限、ENOSPC）时拒绝；spill 策略会将该拒绝作为尽力而为的失败，并保留内联结果。词汇见 seam README，设计见工具输出 spill Agent Note。

模型体验

通过渲染本地路径以及 read/grep 取回指引的 spill 消费方间接影响模型。

KV 缓存影响

不直接导致失效；指定的消费方负责其引起的任何请求前缀变更。

已知限制与待完成工作

• 本地 spill 文件会持续存在，直到外部清理为止：该后端不提供会话生命周期删除或按时间保留的策略，因为已持久化、已恢复和 fork 后的会话可能仍在引用某个路径。
• 定位信息需要与其位于同一文件系统的消费方：远程或虚拟部署需要另一个 SpillStore 后端，其定位信息和取回指引在该环境中有明确含义。