DSH plugin 的 spill 存储契约:保存请求、定位符与检索指引到底怎么配合才顺
工具结果被外溢后,模型手上只剩一个定位符——它既不是路径,也不是访问控制凭证。 DSH plugin 的 spill 存储是一条可选能力 seam:只负责把文本原样存下来,再给你一个面向模型的手柄。谁决定外溢、谁负责预览,都不在这一层。 DSH插件 做自定义工具时,先把模型看到的和存储留住的这两份内容分开。
spill 是可选能力,不归循环主干
存储和决策被刻意分开:存储保真,决策在消费方。(来源) 三个事实:
- Service Definition 是
dsh-spill,即ctx.spillStore;本地 Service Provider 是dsh-spill-local。 - 消费方是工具结果策略与会话引用,不是 agent 循环本身。
- 预览与 spill 决策由消费方负责,存储则原样保存所提供的文本。
这意味着你不能指望“存进去就自动变聪明”。要不要外溢、外溢后给模型看哪一段、截断多少,都是消费方的策略问题。存储层唯一要做的是:保存完整内容,返回可用的定位符与检索指引。
保存请求的三个字段各有边界
owner 管归档、source 管溯源、suggestedName 只管命名提示,三者都不是访问控制。(来源)
SaveTextSpill 包含四项:owner、source、suggestedName 与 content。
owner— 保存时的存储命名空间,只有sessionId一个字段。它让后端把产物归档到产出会话下,但真正面向模型的手柄是返回的SpillLocator。source— 描述性生产者来源,绝不是访问控制。工具来源是{ kind: 'tool', toolName, callId, label },会话引用来源是{ kind: 'session-reference', sessionId, label }。suggestedName— 调用方建议的基础名,比如web_fetch.txt。后端会把它清理成单一安全路径段,它是提示,永远不是路径。
content 是完整的 UTF-8 文本。注意“完整”二字:拼接、截断、摘要都不该发生在保存前,否则模型按定位符取回时看到的就是残缺内容。
fork 语义也在这层定义:被 fork 的会话继承 seed 日志里已经出现的定位符,那些产物不会被复制或重新归属;fork 之后产生的 spill 使用子会话 id。如果你在调整 fork 逻辑,不要试图迁移旧产物。
结果是定位符加检索指引,不是路径
SpillRef 只有三个字段,但 locator 是不透明值,消费方不该解析它。(来源)
interface SpillRef {
locator: SpillLocator
bytes: number
retrievalHint: string
}
locator 是品牌化的面向模型句柄。本地后端把它渲染成文件系统路径;远程或数据库后端可以渲染 URI、键或命令 token。官方要求消费方把它当作不透明值,用 retrievalHint 渲染,而不是假定 read 始终是正确的检索机制。
bytes 是精确字节数,适合做展示或预算提示,不要拿它反推字符数。retrievalHint 才是“怎么取”的答案:本地后端会提示在该路径上用 read 或 grep。
还有一个容易被忽略的边界:保留期清理可以连同其他旧会话产物一起使旧定位符失效,而 spill seam 不定义逐会话的清理策略。定位符长期有效不是契约的一部分,需要长期保存的内容应当另存。
服务只有 saveText,失败必须拒绝
抽象服务只有一个方法,失败时拒绝,降级由调用方决定。(来源)
SpillStore 定义在 packages/spill/spill/src/index.ts,唯一操作是 saveText(input) → Promise<SpillRef>。它在实际存储失败时拒绝,包括权限不足、ENOSPC、后端不可用。
这条拒绝语义很重要:seam 不吞错,也不替你想降级方案。策略消费方把拒绝当作尽力而为的信号——保留原始内联结果,而不是让一个原本成功的工具调用变成 isError。
同时也要清楚它不负责什么:保留策略、工具结果替换、检索与搜索 API,都不在这条 seam 里。想加“按会话定期清理”或“定位符索引”,那是另一个能力,不要塞进 saveText。
实现层面还有一条约束:一个上下文里只能有一个实现,加载第二个会按 Cordis 的标准重复服务行为抛错。所以要替换后端,正确做法是替换插件,而不是并行加载。
本地后端的落盘细节
路径由后端自己拼,安全属性靠目录权限与排他写入。(来源)
dsh-spill-local 写入 <root>/session-<hash>/<random>-<safeName>:
- 根目录 — 已配置或延迟创建的私有目录,权限
0700; - 会话子目录 — 采用
sha256(sessionId),避免 id 里的特殊字符进路径; - 文件名 — 随机前缀加清理后的安全名,保证不碰撞;
- 写入方式 — 排他且仅所有者可访问,即
open(path, 'wx', 0o600),防止预先植入的符号链接把写入重定向到别处。
这套细节解释了两个现象:为什么同名建议不会互相覆盖(随机前缀),以及为什么你无法从建议名推回真实路径(清理加随机)。它的 locator 是本地路径,retrievalHint 则告知模型在该路径上使用 read 或 grep。
消费方职责:预览与决策不在存储层
外溢策略是独立插件的事,存储只提供地址。(来源)
策略消费方 dsh-spill-policy 会把超过 maxInlineTokens 的图文结果替换为“按原顺序保留的首尾内容 + spill 地址”。这个过程是尽力而为的:保存失败时保留原始内联结果,而不会把成功的调用变成 isError。
从插件作者角度,这段描述给出一个清晰的责任线:
- 你的插件决定何时外溢、保留哪些首尾内容、给模型看多少;
- 存储层只保证保存完整文本、返回定位符与检索指引;
- 模型的检索动作由
retrievalHint指导,不由你硬编码read。
如果你在做自定义工具,先想清楚“模型看到的内容”和“存储里的内容”是不是同一份。外溢场景下它们本来就不该相同:模型看摘要,存储留全文。
验证:保存一段文本并按定位符取回
验证要点不是“文件存在”,而是“字节一致、指引可用、失败可降级”。(来源) 五步:
- 构造含中文与 emoji 的
content,调saveText,记录返回的bytes。 - 用
retrievalHint指示的方式取回内容,断言与原文逐字节一致。 - 传入带
../的suggestedName,断言落盘文件名被清理为单一安全段。 - 用两个不同
sessionId保存同名内容,断言落在不同会话子目录且互不覆盖。 - 模拟存储不可用(如只读根目录),断言
saveText拒绝,且调用方保留内联结果。
如果第 1 步的 bytes 与你的预期差了,通常是按字符数算了。中文与 emoji 在 UTF-8 下占多个字节,bytes 只承诺字节数。
想理解外溢与上下文压力的关系,可以对照Token 计量与上下文压力;截断定位符的具体形态,见会话引用截断。
一句话收束: spill 只存不决策,owner 管归档、source 管溯源、suggestedName 只是提示,定位符不透明、检索看 retrievalHint,失败就让调用方降级。
常见问题
不会,DSH plugin 的 spill 只负责保存。DSH plugin 明确把预览与 spill 决策交给消费方,存储层只把调用方给的文本原样持久化并返回定位符。
不会,DSH plugin 只把它当命名提示。DSH plugin 的后端会把它清理成单一安全路径段,生成的名称来自它但绝不等于它。
不应该,DSH plugin 的策略消费方按尽力而为处理。DSH plugin 在保存失败时保留原始内联结果,不会把一个原本成功的调用变成 isError。
不能,DSH plugin 把定位符定义为不透明值。DSH plugin 的本地后端可能渲染成文件系统路径,远程后端可能是 URI、键或命令 token,消费方应当用 retrievalHint 渲染而不是解析。
相关术语
- SaveTextSpill
- SaveTextSpill 是 spill 保存请求,包含 owner、source、suggestedName 与完整 content 四项。— packages/spill/spill/src/types.ts
- SpillRef
- SpillRef 是一次保存的结果,包含不透明定位符 locator、精确字节数 bytes 与后端检索指引 retrievalHint。— packages/spill/spill/src/types.ts
- SpillOwner
- SpillOwner 是保存时的存储命名空间,只有 sessionId,用于让后端按产出会话归档。— packages/spill/spill/src/types.ts
- retrievalHint
- retrievalHint 是后端给出的、面向模型的检索提示,消费方用它渲染定位符,而不是假定 read 总是正确机制。— packages/spill/spill/src/types.ts
来源
- DeepSeek Harness 官方参考 - spill 存储· deepseek-ai
- packages/spill/spill/src/types.ts· deepseek-ai