DSH plugin 的 recall 记录:kind、form、version 与 references 数组各是什么
在 DSH plugin(DSH插件) 里,一条会话引用记录不是「一段文本」,而是一份结构化事实:kind 说明它是什么,form 说明材料从哪来,version 说明记录怎么读,references 说明读了哪些会话、读到哪。 四个部分合起来,才支撑得起回溯。
DSH plugin 落盘记录里的三个枚举值
先认值,再看数组。(来源) 记录开头通常是:
{
"kind": "session-reference",
"form": "recall",
"version": 1,
"references": []
}
三个值分别回答不同问题:这条记录是什么、材料形态是什么、结构版本是多少。
把它们当成「元数据装饰」的人,往往会在下游解析时把三个概念混成一个。
DSH plugin 的 kind 与 form 各管什么
kind 管记录类型,form 管材料来源。(来源) 对照:
| 字段 | 取值 | 回答的问题 |
|---|---|---|
kind | session-reference | 这是不是跨会话引用 |
form | recall | 材料是不是从别的会话日志提取的 |
kind 决定下游用哪套 schema 解析;form 决定内容的语义标签。
一个类比:kind 是文件类型,form 是内容来源。两者都必要,但不可互换。
DSH plugin 的 version 是谁的版本
是记录自身结构的版本,不是源会话格式。(来源) 这点最容易混:
| 字段 | 位置 | 含义 |
|---|---|---|
version: 1 | 记录顶层 | 这条 source 记录的结构版本 |
capturedFormatVersion | 每个引用内 | 被引用会话的格式版本 |
前者决定「怎么解析这条记录」,后者决定「怎么读源会话」。
把两者混用,会在升级后出现「记录能读、内容读错」的问题。
DSH plugin references 数组的十一个字段
每个被引用会话一条,字段分五组。(来源) 对照:
| 分组 | 字段 |
|---|---|
| 身份 | sessionId、label |
| 坐标 | capturedFormatVersion、capturedThroughSeq |
| 源端状态 | compacted |
| 快照事实 | originalMessages、retainedMessages、omittedMessages、omittedBytes、truncated |
| 顺序 | inputIndex |
五组分别回答:引用谁、读到哪、源端有没有压缩、本次缺了多少、原来排第几。
字段多,但每组只服务一个判断,不需要一次全用上。
DSH plugin 记录怎么用于回溯
从坐标出发,再看缺口,最后按顺序重放。(来源) 三步:
- 用
capturedThroughSeq定位源 generation 中的位置; - 用
compacted与三类消息计数判断缺口来自源端还是本次; - 用
inputIndex还原引用顺序。
第一步容易犯错:把坐标当成当前会话的 seq。官方明确它属于源会话的原始 generation。
第二步决定你能不能解释「为什么少了一段」。第三步只影响展示顺序,不影响读取内容。
DSH plugin 记录结构的验证
四项断言,覆盖枚举、版本与数组。 步骤:
- 引用一次后读记录,确认
kind、form、version取值正确; - 确认每个引用都有
sessionId与inputIndex; - 确认
version与capturedFormatVersion没有互相覆盖; - 引用两个会话,确认
inputIndex为 0、1 且与选择顺序一致。
第 3 项是回归重点:升级记录结构时,最容易把两个版本字段合并。
第 4 项验证顺序,不要只看数组长度。
记录结构清楚后,下一步是源端压缩。读 DSH plugin 引用已压缩的源会话;想看坐标怎么读,读 DSH plugin 的 capturedThroughSeq;想先看全貌,读 DSH plugin 怎么完整实现会话引用。
来源:DeepSeek Harness 官方参考 - 会话引用、session-reference/src/types.ts
常见问题
DSH plugin 用 kind 标识这条记录属于跨会话引用,而不是普通用户消息。DSH plugin 用 kind 区分记录类型,下游可以据此选择解析方式,不必猜结构。
DSH plugin 的 recall 表示材料是从另一个会话日志中提取的。DSH plugin 用 form 说明上下文来源形态,让读取方知道这段内容不是当前会话原生产生的。
不是,DSH plugin 的 version 是这条 source 记录自身的版本。源会话格式版本记录在每个引用的 capturedFormatVersion 里,两者不要混。
DSH plugin 用 inputIndex 还原用户在一条消息里选择会话的先后。DSH plugin 在聚合多个引用时保留顺序,inputIndex 让下游能按原顺序展示或重放。
相关术语
- SessionReferenceSource
- SessionReferenceSource 是会话引用的持久记录类型,描述来源会话、捕获坐标与快照事实。— session-reference/src/types.ts
- form: recall
- form: recall 表示该段材料是从另一个会话日志中提取的上下文形态。— DeepSeek Harness 官方参考 - 会话引用
- version: 1
- version: 1 是 source 记录自身的结构版本,用于下游判断如何解析这条记录。— session-reference/src/types.ts
- inputIndex
- inputIndex 是引用在原始输入中的顺序编号,用于保留用户选择的先后关系。— DeepSeek Harness 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- session-reference/src/types.ts· deepseek-ai