DSH plugin 的 prepare:从 content 与 references 到可读内容加一个聚合上下文
在 DSH plugin(DSH插件) 里,prepare 是会话引用里唯一真正读日志的一步:它接收可读内容与结构化引用,返回同一份内容加最多一个聚合上下文。 调不通时,问题通常不在读取,而在入参形态或引用关系。
DSH plugin 调了 prepare 却没有上下文
先分清「没有引用」和「引用失败」。(来源) 三种现场:
情况 A references 为空 -> 正常返回,无 additionalContext
情况 B references 有值但读取失败 -> 抛错,带稳定错误码
情况 C references 指向当前会话 -> 拒绝,返回自引用错误
只有 A 是「成功但没有内容」。B、C 都是可以定位的失败。
很多接入把 A 当失败,于是不断重试或补默认值,反而把真正的问题盖住。
DSH plugin prepare 的四个入参
四个参数,各管一段。(来源) 对照:
| 参数 | 形态 | 职责 |
|---|---|---|
agent | Agent | 请求方身份,用于排序与自引用判断 |
content | ContentBlock[] | 已归一化的可读消息内容 |
references | SessionReferenceInput[] | 按 mention 顺序的源会话 |
signal | AbortSignal,可选 | 本次 turn 的取消边界 |
content 的「已归一化」由你的宿主负责:把输入框里的富文本、mention 标记整理成可读块,再交给 prepare。
references 的每一项只需要 sessionId 与可选 label,不需要完整路径或标题。
DSH plugin prepare 的返回值只有两部分
一个可读内容,一个可选上下文,没有第三个字段。(来源) 结构:
| 字段 | 是否必有 | 说明 |
|---|---|---|
content | 是 | 移除 mention token 后的内容块 |
additionalContext | 否 | 聚合后的不可信上下文 |
additionalContext 是 UserMessage 形态,不是 system。这一点决定了它在模型侧的角色:参考材料,而不是指令。
没有引用内容时,字段直接不出现,而不是给一个空对象。宿主应按「存在与否」判断,而不是按「是否为空数组」。
DSH plugin 为什么拒绝引用自身
因为自引用既无意义又会递归。(来源) 两个原因:
- 语义 — 让当前会话参考自己,等于把已有内容再喂一遍;
- 实现 — 读取与写入落在同一份日志上,容易形成不一致的快照。
官方在方法说明里写明:指向 agent 自身的引用会被拒绝。宿主应该在选择阶段就过滤,而不是等 prepare 报错。
提前过滤的好处是用户不会选到一个必然失败的候选。
DSH plugin 一条消息只聚合一次
多个引用合成一个上下文,不是每个引用一段。(来源) 规则:
- prepare 对一条已接受的消息做快照;
- 所有引用的材料聚合为一个
additionalContext; - 顺序通过持久 source 里的
inputIndex保留; - 压缩、截断发生在聚合过程中,并记录事实。
这条规则解释了为什么返回类型里没有「contexts 数组」。宿主不需要自己拼接多段上下文。
如果 UI 想按会话分段展示,那是展示层的事,不应该要求 prepare 返回多段。
DSH plugin prepare 调用时序的验证
四步,从空到多,逐层加引用。 步骤:
references传空,确认返回内容且无additionalContext;- 传一个有效会话,确认上下文存在;
- 传三个会话,确认仍只有一个上下文,且
inputIndex顺序与传入一致; - 传当前会话自身,确认返回自引用错误。
第 3 步是聚合断言:如果出现三段上下文,说明调用方在循环里多次调用了 prepare。
第 4 步是边界断言:错误码应该可读,而不是笼统的「引用失败」。
如果宿主把引用放在消息附件里,也应该在调用前解析成 references;prepare 只接受显式引用,不从附件文本里猜测用户想引用谁。
调用方也不该在 prepare 前后自己删除正文里的 mention;那会让字节保留的边界变得模糊,排查时也看不出是谁改的。
prepare 通了之后,下一步是预算。读 DSH plugin 会话引用的预算与 64 KiB 回退;想看截断时返回什么,读 DSH plugin 会话引用被截断后的字段;想先看全貌,读 DSH plugin 怎么完整实现会话引用。
来源:DeepSeek Harness 官方参考 - 会话引用、session-reference/src/index.ts
常见问题
先看 references 是否为空,这是 DSH plugin 返回空上下文的最常见原因。DSH plugin 的 prepare 只为传入的结构化引用读取会话,空数组会正常返回但没有 additionalContext;这不是异常,而是没有引用内容。
自引用在 DSH plugin 里没有意义,还会让上下文递归。DSH plugin 在 prepare 里对指向 agent 自身的引用直接拒绝,返回稳定的自引用错误码。
不会,DSH plugin 对一条消息最多返回一个聚合上下文。DSH plugin 对一条已接受的消息最多返回一个聚合上下文,把多个引用的材料合在一起;引用顺序通过 inputIndex 记录在持久 source 里。
不需要,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 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- session-reference/src/index.ts· deepseek-ai