ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 的 recall 记录:kind、form、version 与 references 数组各是什么

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话引用recall持久记录
会话引用会在持久记录里留下 kind、form、version 与 references。本文逐个解释这三个枚举值与十一个引用字段,说明它们如何支撑回溯与审计。

在 DSH plugin(DSH插件) 里,一条会话引用记录不是「一段文本」,而是一份结构化事实:kind 说明它是什么,form 说明材料从哪来,version 说明记录怎么读,references 说明读了哪些会话、读到哪。 四个部分合起来,才支撑得起回溯。

DSH plugin 落盘记录里的三个枚举值

先认值,再看数组。(来源) 记录开头通常是:

json
{
  "kind": "session-reference",
  "form": "recall",
  "version": 1,
  "references": []
}

三个值分别回答不同问题:这条记录是什么、材料形态是什么、结构版本是多少。

把它们当成「元数据装饰」的人,往往会在下游解析时把三个概念混成一个。

DSH plugin 的 kind 与 form 各管什么

kind 管记录类型,form 管材料来源。(来源) 对照:

字段取值回答的问题
kindsession-reference这是不是跨会话引用
formrecall材料是不是从别的会话日志提取的

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 记录怎么用于回溯

从坐标出发,再看缺口,最后按顺序重放。(来源) 三步:

  1. 用 capturedThroughSeq 定位源 generation 中的位置;
  2. 用 compacted 与三类消息计数判断缺口来自源端还是本次;
  3. 用 inputIndex 还原引用顺序。

第一步容易犯错:把坐标当成当前会话的 seq。官方明确它属于源会话的原始 generation。

第二步决定你能不能解释「为什么少了一段」。第三步只影响展示顺序,不影响读取内容。

DSH plugin 记录结构的验证

四项断言,覆盖枚举、版本与数组。 步骤:

  1. 引用一次后读记录,确认 kind、form、version 取值正确;
  2. 确认每个引用都有 sessionId 与 inputIndex;
  3. 确认 version 与 capturedFormatVersion 没有互相覆盖;
  4. 引用两个会话,确认 inputIndex 为 0、1 且与选择顺序一致。

第 3 项是回归重点:升级记录结构时,最容易把两个版本字段合并。

第 4 项验证顺序,不要只看数组长度。

记录结构清楚后,下一步是源端压缩。读 DSH plugin 引用已压缩的源会话;想看坐标怎么读,读 DSH plugin 的 capturedThroughSeq;想先看全貌,读 DSH plugin 怎么完整实现会话引用。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 落盘记录里的 kind: session-reference 是做什么用的?

DSH plugin 用 kind 标识这条记录属于跨会话引用,而不是普通用户消息。DSH plugin 用 kind 区分记录类型,下游可以据此选择解析方式,不必猜结构。

DSH plugin 的 form: recall 和普通上下文有什么区别?

DSH plugin 的 recall 表示材料是从另一个会话日志中提取的。DSH plugin 用 form 说明上下文来源形态,让读取方知道这段内容不是当前会话原生产生的。

DSH plugin 记录里的 version: 1 是源会话的格式版本吗?

不是,DSH plugin 的 version 是这条 source 记录自身的版本。源会话格式版本记录在每个引用的 capturedFormatVersion 里,两者不要混。

DSH plugin 的 references 数组为什么每个引用都有 inputIndex?

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 官方参考 - 会话引用

来源