ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 的 prepare:从 content 与 references 到可读内容加一个聚合上下文

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话引用prepare上下文
prepare 是会话引用真正读取日志的入口:四个入参、两个返回值、引用自身会被拒。本文按调用时序讲清每一步的输入形态、失败条件与验证方式。

在 DSH plugin(DSH插件) 里,prepare 是会话引用里唯一真正读日志的一步:它接收可读内容与结构化引用,返回同一份内容加最多一个聚合上下文。 调不通时,问题通常不在读取,而在入参形态或引用关系。

DSH plugin 调了 prepare 却没有上下文

先分清「没有引用」和「引用失败」。(来源) 三种现场:

text
情况 A  references 为空            -> 正常返回,无 additionalContext
情况 B  references 有值但读取失败   -> 抛错,带稳定错误码
情况 C  references 指向当前会话     -> 拒绝,返回自引用错误

只有 A 是「成功但没有内容」。B、C 都是可以定位的失败。

很多接入把 A 当失败,于是不断重试或补默认值,反而把真正的问题盖住。

DSH plugin prepare 的四个入参

四个参数,各管一段。(来源) 对照:

参数形态职责
agentAgent请求方身份,用于排序与自引用判断
contentContentBlock[]已归一化的可读消息内容
referencesSessionReferenceInput[]按 mention 顺序的源会话
signalAbortSignal,可选本次 turn 的取消边界

content 的「已归一化」由你的宿主负责:把输入框里的富文本、mention 标记整理成可读块,再交给 prepare。

references 的每一项只需要 sessionId 与可选 label,不需要完整路径或标题。

DSH plugin prepare 的返回值只有两部分

一个可读内容,一个可选上下文,没有第三个字段。(来源) 结构:

字段是否必有说明
content是移除 mention token 后的内容块
additionalContext否聚合后的不可信上下文

additionalContext 是 UserMessage 形态,不是 system。这一点决定了它在模型侧的角色:参考材料,而不是指令。

没有引用内容时,字段直接不出现,而不是给一个空对象。宿主应按「存在与否」判断,而不是按「是否为空数组」。

DSH plugin 为什么拒绝引用自身

因为自引用既无意义又会递归。(来源) 两个原因:

  1. 语义 — 让当前会话参考自己,等于把已有内容再喂一遍;
  2. 实现 — 读取与写入落在同一份日志上,容易形成不一致的快照。

官方在方法说明里写明:指向 agent 自身的引用会被拒绝。宿主应该在选择阶段就过滤,而不是等 prepare 报错。

提前过滤的好处是用户不会选到一个必然失败的候选。

DSH plugin 一条消息只聚合一次

多个引用合成一个上下文,不是每个引用一段。(来源) 规则:

  • prepare 对一条已接受的消息做快照;
  • 所有引用的材料聚合为一个 additionalContext;
  • 顺序通过持久 source 里的 inputIndex 保留;
  • 压缩、截断发生在聚合过程中,并记录事实。

这条规则解释了为什么返回类型里没有「contexts 数组」。宿主不需要自己拼接多段上下文。

如果 UI 想按会话分段展示,那是展示层的事,不应该要求 prepare 返回多段。

DSH plugin prepare 调用时序的验证

四步,从空到多,逐层加引用。 步骤:

  1. references 传空,确认返回内容且无 additionalContext;
  2. 传一个有效会话,确认上下文存在;
  3. 传三个会话,确认仍只有一个上下文,且 inputIndex 顺序与传入一致;
  4. 传当前会话自身,确认返回自引用错误。

第 3 步是聚合断言:如果出现三段上下文,说明调用方在循环里多次调用了 prepare。

第 4 步是边界断言:错误码应该可读,而不是笼统的「引用失败」。

如果宿主把引用放在消息附件里,也应该在调用前解析成 references;prepare 只接受显式引用,不从附件文本里猜测用户想引用谁。

调用方也不该在 prepare 前后自己删除正文里的 mention;那会让字节保留的边界变得模糊,排查时也看不出是谁改的。

prepare 通了之后,下一步是预算。读 DSH plugin 会话引用的预算与 64 KiB 回退;想看截断时返回什么,读 DSH plugin 会话引用被截断后的字段;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

来源:DeepSeek Harness 官方参考 - 会话引用、session-reference/src/index.ts

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 调了 prepare 却没有任何附加上下文,是接口坏了吗?

先看 references 是否为空,这是 DSH plugin 返回空上下文的最常见原因。DSH plugin 的 prepare 只为传入的结构化引用读取会话,空数组会正常返回但没有 additionalContext;这不是异常,而是没有引用内容。

DSH plugin 的 prepare 为什么拒绝引用当前会话自己?

自引用在 DSH plugin 里没有意义,还会让上下文递归。DSH plugin 在 prepare 里对指向 agent 自身的引用直接拒绝,返回稳定的自引用错误码。

DSH plugin 引用多个会话时,会为每个会话生成一段上下文吗?

不会,DSH plugin 对一条消息最多返回一个聚合上下文。DSH plugin 对一条已接受的消息最多返回一个聚合上下文,把多个引用的材料合在一起;引用顺序通过 inputIndex 记录在持久 source 里。

DSH plugin 的 content 需要宿主先移除 mention 吗?

不需要,DSH plugin 的 prepare 会移除 mention token。宿主传入的应是已归一化的可读内容,提前删除反而会丢失用于定位的标记。

相关术语

prepare
prepare 是会话引用解析器的核心方法,读取被引用会话的日志并准备可读内容与聚合上下文。— session-reference/src/index.ts
PreparedReferencedMessage
PreparedReferencedMessage 是 prepare 的返回类型,包含可读内容与可选的聚合附加上下文。— DeepSeek Harness 官方参考 - 会话引用
additionalContext
additionalContext 是 prepare 生成的聚合上下文,以 UserMessage 形态出现,没有引用时可以不存在。— DeepSeek Harness 官方参考 - 会话引用
inputIndex
inputIndex 是持久 source 中记录引用顺序的字段,用于还原用户在一条消息里选择的先后。— DeepSeek Harness 官方参考 - 会话引用

来源