ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 的 spill 存储契约:保存请求、定位符与检索指引到底怎么配合才顺

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harnessspill 存储SpillRef定位符
工具输出被外溢后,模型只拿到一个定位符。本文讲 SaveTextSpill 三个字段的边界、SpillRef 的定位符与检索指引、ctx.spillStore 的失败语义,以及本地后端与消费方各自的职责。

工具结果被外溢后,模型手上只剩一个定位符——它既不是路径,也不是访问控制凭证。 DSH plugin 的 spill 存储是一条可选能力 seam:只负责把文本原样存下来,再给你一个面向模型的手柄。谁决定外溢、谁负责预览,都不在这一层。 DSH插件 做自定义工具时,先把模型看到的和存储留住的这两份内容分开。

spill 是可选能力,不归循环主干

存储和决策被刻意分开:存储保真,决策在消费方。(来源) 三个事实:

  1. Service Definition 是 dsh-spill,即 ctx.spillStore;本地 Service Provider 是 dsh-spill-local。
  2. 消费方是工具结果策略与会话引用,不是 agent 循环本身。
  3. 预览与 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 是不透明值,消费方不该解析它。(来源)

ts
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>:

  1. 根目录 — 已配置或延迟创建的私有目录,权限 0700;
  2. 会话子目录 — 采用 sha256(sessionId),避免 id 里的特殊字符进路径;
  3. 文件名 — 随机前缀加清理后的安全名,保证不碰撞;
  4. 写入方式 — 排他且仅所有者可访问,即 open(path, 'wx', 0o600),防止预先植入的符号链接把写入重定向到别处。

这套细节解释了两个现象:为什么同名建议不会互相覆盖(随机前缀),以及为什么你无法从建议名推回真实路径(清理加随机)。它的 locator 是本地路径,retrievalHint 则告知模型在该路径上使用 read 或 grep。

消费方职责:预览与决策不在存储层

外溢策略是独立插件的事,存储只提供地址。(来源)

策略消费方 dsh-spill-policy 会把超过 maxInlineTokens 的图文结果替换为“按原顺序保留的首尾内容 + spill 地址”。这个过程是尽力而为的:保存失败时保留原始内联结果,而不会把成功的调用变成 isError。

从插件作者角度,这段描述给出一个清晰的责任线:

  • 你的插件决定何时外溢、保留哪些首尾内容、给模型看多少;
  • 存储层只保证保存完整文本、返回定位符与检索指引;
  • 模型的检索动作由 retrievalHint 指导,不由你硬编码 read。

如果你在做自定义工具,先想清楚“模型看到的内容”和“存储里的内容”是不是同一份。外溢场景下它们本来就不该相同:模型看摘要,存储留全文。

验证:保存一段文本并按定位符取回

验证要点不是“文件存在”,而是“字节一致、指引可用、失败可降级”。(来源) 五步:

  1. 构造含中文与 emoji 的 content,调 saveText,记录返回的 bytes。
  2. 用 retrievalHint 指示的方式取回内容,断言与原文逐字节一致。
  3. 传入带 ../ 的 suggestedName,断言落盘文件名被清理为单一安全段。
  4. 用两个不同 sessionId 保存同名内容,断言落在不同会话子目录且互不覆盖。
  5. 模拟存储不可用(如只读根目录),断言 saveText 拒绝,且调用方保留内联结果。

如果第 1 步的 bytes 与你的预期差了,通常是按字符数算了。中文与 emoji 在 UTF-8 下占多个字节,bytes 只承诺字节数。

想理解外溢与上下文压力的关系,可以对照Token 计量与上下文压力;截断定位符的具体形态,见会话引用截断。

一句话收束: spill 只存不决策,owner 管归档、source 管溯源、suggestedName 只是提示,定位符不透明、检索看 retrievalHint,失败就让调用方降级。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 spill 存储会帮我决定要不要外溢吗?

不会,DSH plugin 的 spill 只负责保存。DSH plugin 明确把预览与 spill 决策交给消费方,存储层只把调用方给的文本原样持久化并返回定位符。

DSH plugin 的 suggestedName 会直接当路径用吗?

不会,DSH plugin 只把它当命名提示。DSH plugin 的后端会把它清理成单一安全路径段,生成的名称来自它但绝不等于它。

DSH plugin 保存失败时应该把工具调用标记成错误吗?

不应该,DSH plugin 的策略消费方按尽力而为处理。DSH plugin 在保存失败时保留原始内联结果,不会把一个原本成功的调用变成 isError。

DSH plugin 的 spill 定位符能当文件路径解析吗,为什么不能?

不能,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

来源