ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 的 capturedFormatVersion:缺失即格式 v0,跨版本引用怎么读

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话引用capturedFormatVersion版本兼容
升级后读旧引用记录,发现字段不存在,该当成未知还是当成某个旧版本?本文讲 capturedFormatVersion 缺失即 v0、它与记录自身 version 的区别,以及按版本分支读取的写法。

升级之后读一条旧引用记录,可能发现 capturedFormatVersion 根本不存在。 这时有两种直觉解读:未知格式,或者某个旧版本。DSH plugin(DSH插件) 的答案很明确:缺失就是已发布的格式 v0。

DSH plugin 字段缺失时的两个错误结论

两个结论方向相反,但都会把旧记录读错。(来源) 现场:

text
记录:kind: 'session-reference', form: 'recall', version: 1
references[0]:没有 capturedFormatVersion

第一种错误:当成未知格式,直接拒绝读取,用户看到「引用记录不可用」。

第二种错误:当成当前格式,用最新解析逻辑硬解,字段含义对不上却没人发现。

第一种是过度保守,第二种是过度乐观。正确做法是按 v0 解释,并只使用 v0 保证存在的字段。

DSH plugin 的两条版本线

两个版本号各有归属,混用会让兼容判断失效。(来源) 对照:

版本描述对象谁负责升级缺失时
记录自身 version持久 source 的结构记录格式演进按已知最低版本处理
capturedFormatVersion源会话捕获时的格式源会话格式演进视为格式 v0

第一列常被误认为「一个版本号管全部」。实际上它们演进节奏不同:记录结构可能升级,而源会话格式没变。

这也是为什么一条记录里可以出现 version: 1 与 capturedFormatVersion: 2 并存。

你在判断兼容性时,两个都要看:记录结构决定怎么读这条记录,捕获版本决定怎么解释里面的源会话内容。

DSH plugin 的 v0 到底是什么

v0 是一个已发布格式,不是占位符。(来源) 三点含义:

  1. 它有确定的字段集合与语义,读取逻辑可以完整实现;
  2. 缺失等于 v0,所以不需要额外标记「这是老记录」;
  3. 它不是「未知」,因此不应该触发拒绝读取。

把 v0 当成未知,等于把一个可处理的状态变成一个错误状态。

反过来,把 v0 当成「最新格式的简化版」也错:v0 的字段可能比当前少,硬套当前结构会得到空值,然后被误读成「内容为空」。

DSH plugin 按版本分支读取的写法

先分派,再解析;未知版本明确失败。(来源) 骨架:

text
const format = ref.capturedFormatVersion ?? 0; // 缺失即 v0
switch (format) {
  case 0: return parseV0(ref);
  case 1: return parseV1(ref);
  default: throw new UnsupportedCapturedFormat(format);
}

三个细节值得强调:

  • ?? 0 而不是 || 之外的复杂判断,避免把 0 当成假值绕过;
  • 分支里只读该版本保证存在的字段,不做跨版本猜测;
  • 默认分支必须抛错,不能 return parseLatest(ref)。

最后一条是防御性设计:静默按最新格式解析,会把「记录比我新」伪装成「记录有点怪」。

DSH plugin 跨版本读取与整库迁移的分界

迁移改存储,版本分支改读取,两者不能互相替代。(来源) 分工:

场景该做什么
记录由旧实现写入按 v0 分支读取
整库结构升级走迁移流程
记录由更新实现写入识别为不支持并报错

第一条不需要写数据,只需要读得对。

第二条不该顺手把 capturedFormatVersion 补成当前值,那会抹掉源会话的真实来源版本。

第三条是很多实现的盲区:只考虑了向后兼容,没考虑向前兼容。

DSH plugin 版本读取的验证

三条用例,覆盖缺失、当前与未来。 步骤:

  1. 去掉 capturedFormatVersion,确认走 v0 分支且结果与显式写 0 一致;
  2. 写入当前版本,确认走对应分支,字段解析完整;
  3. 写入一个更大的版本号,确认明确报错,而不是静默成功。

第 1 步的「与显式写 0 一致」很重要:它证明缺失处理的是一条真实路径,而不是碰巧没崩。

第 3 步用来防止默认分支被写成「回退到最新」。

再补一条回归:同一份记录连续读两次,结果应完全一致。版本分派如果依赖全局可变状态,第二次读取可能换分支。

版本读对之后,坐标也要读对。读 DSH plugin 的 capturedThroughSeq 属于源 generation;整库升级的场景,读 DSH plugin 升级后怎么做会话迁移;想先看持久记录结构,读 DSH plugin 的 recall 记录怎么读。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 引用记录里没有 capturedFormatVersion,是数据损坏了吗?

不是,DSH plugin 把缺失按已发布的格式 v0 处理。DSH plugin 不会把它解释成「未知版本」,读取方也不需要因此拒绝这条记录。

DSH plugin 的 capturedFormatVersion 和记录里的 version 是同一个东西吗?

不是,DSH plugin 的 version 与 capturedFormatVersion 描述两个不同对象。version 描述记录自身结构,capturedFormatVersion 描述被引用源会话在捕获时的格式。DSH plugin 把两者分开记录,升级时也不会互相替代。

DSH plugin 读到比当前实现更新的 capturedFormatVersion 该怎么办?

不要静默按最新格式硬解,DSH plugin 会把它识别为不支持的版本。这种情况说明记录由更新的实现写入,DSH plugin 的正确做法是识别为不支持的版本并明确报错,而不是猜字段含义。

DSH plugin 做整库迁移时,需要给旧引用补写 capturedFormatVersion 吗?

不需要为了让字段存在而补写,DSH plugin 的缺失本身就是 v0。缺失本身就是 v0 的有效表达;DSH plugin 的记录语义以捕获时为准,补写反而会掩盖真实的来源版本。

相关术语

capturedFormatVersion
capturedFormatVersion 记录被引用源会话在捕获时的格式版本,用于跨版本读取时选择解释方式。— DeepSeek Harness 官方参考 - 会话引用
格式 v0
格式 v0 是 capturedFormatVersion 缺失时对应的已发布格式,不是未知状态。— DeepSeek Harness 官方参考 - 会话引用
记录自身 version
记录自身 version 描述持久 source 的结构版本,与源会话格式版本是两条独立版本线。— session-reference/src/types.ts
版本分支读取(version branching)
版本分支读取是按记录的格式版本选择对应解析逻辑,而不是统一用当前实现硬解。— DeepSeek Harness 官方参考 - 会话引用

来源