DSH plugin 的 capturedFormatVersion:缺失即格式 v0,跨版本引用怎么读
升级之后读一条旧引用记录,可能发现 capturedFormatVersion 根本不存在。 这时有两种直觉解读:未知格式,或者某个旧版本。DSH plugin(DSH插件) 的答案很明确:缺失就是已发布的格式 v0。
DSH plugin 字段缺失时的两个错误结论
两个结论方向相反,但都会把旧记录读错。(来源) 现场:
记录: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 是一个已发布格式,不是占位符。(来源) 三点含义:
- 它有确定的字段集合与语义,读取逻辑可以完整实现;
- 缺失等于 v0,所以不需要额外标记「这是老记录」;
- 它不是「未知」,因此不应该触发拒绝读取。
把 v0 当成未知,等于把一个可处理的状态变成一个错误状态。
反过来,把 v0 当成「最新格式的简化版」也错:v0 的字段可能比当前少,硬套当前结构会得到空值,然后被误读成「内容为空」。
DSH plugin 按版本分支读取的写法
先分派,再解析;未知版本明确失败。(来源) 骨架:
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 版本读取的验证
三条用例,覆盖缺失、当前与未来。 步骤:
- 去掉
capturedFormatVersion,确认走 v0 分支且结果与显式写 0 一致; - 写入当前版本,确认走对应分支,字段解析完整;
- 写入一个更大的版本号,确认明确报错,而不是静默成功。
第 1 步的「与显式写 0 一致」很重要:它证明缺失处理的是一条真实路径,而不是碰巧没崩。
第 3 步用来防止默认分支被写成「回退到最新」。
再补一条回归:同一份记录连续读两次,结果应完全一致。版本分派如果依赖全局可变状态,第二次读取可能换分支。
版本读对之后,坐标也要读对。读 DSH plugin 的 capturedThroughSeq 属于源 generation;整库升级的场景,读 DSH plugin 升级后怎么做会话迁移;想先看持久记录结构,读 DSH plugin 的 recall 记录怎么读。
来源:DeepSeek Harness 官方参考 - 会话引用、session-reference/src/types.ts
常见问题
不是,DSH plugin 把缺失按已发布的格式 v0 处理。DSH plugin 不会把它解释成「未知版本」,读取方也不需要因此拒绝这条记录。
不是,DSH plugin 的 version 与 capturedFormatVersion 描述两个不同对象。version 描述记录自身结构,capturedFormatVersion 描述被引用源会话在捕获时的格式。DSH plugin 把两者分开记录,升级时也不会互相替代。
不要静默按最新格式硬解,DSH plugin 会把它识别为不支持的版本。这种情况说明记录由更新的实现写入,DSH plugin 的正确做法是识别为不支持的版本并明确报错,而不是猜字段含义。
不需要为了让字段存在而补写,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 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- session-reference/src/types.ts· deepseek-ai