DSH plugin 的 capturedThroughSeq:源 generation 坐标,不是当前会话位置
在 DSH plugin(DSH插件) 里,把 capturedThroughSeq 当成本会话的消息序号,是跨会话引用里最容易犯的一次坐标错位。 它记录的是快照读到源会话原始 generation 的哪个位置;离开源会话身份,这个数字什么也不代表。
DSH plugin 一次坐标错位的现场
症状很像「引用错位」,实际是两组序号被混用了。(来源) 现场:
当前会话 seq 到 120
引用快照 capturedThroughSeq = 87
宿主拿 87 去当前会话定位 → 落在一条毫不相关的消息上
没有人写错代码,只是默认了「seq 是全局的」。
一旦这个假设成立,后续所有回溯、跳转、diff 都会偏。
判断方法很简单:问这个数字属于哪个会话。答不上来,就说明用错了。
DSH plugin 的两份 seq 空间
每个会话有自己的序号空间,跨会话没有大小关系。(来源) 对照:
| 维度 | 源会话 generation | 当前会话 |
|---|---|---|
| 谁分配序号 | 源会话自己 | 当前会话自己 |
capturedThroughSeq 属于谁 | 源会话 | 不属于 |
| 能否跨会话比较大小 | 不能 | 不能 |
| 有效前提 | 带上源 sessionId | 带上当前 sessionId |
表格最后一行是关键:序号不是独立主键,它必须和会话身份成对出现。
这也是为什么持久记录里 sessionId 与 capturedThroughSeq 写在同一个 reference 项里,而不是分开存两张表。
DSH plugin 官方给的三条读法
三条约束,分别管归属、解释和缺省。(来源) 内容:
- 属于源 generation — 坐标在源会话的序号空间内有效;
- 绝不重解释 — 不会被当作所在会话的 seq;
- 可选 — 字段可能缺省,缺省时不能假设存在。
第 2 条是硬约束,不是建议。任何「把源 seq 换算成当前 seq」的公式都缺少依据。
第 3 条常被忽略:用 0 或 -1 表示「没有坐标」,会让下游把它当成一个真实位置。缺失就该是缺失。
DSH plugin 坐标、压缩与计数的联合判断
三个字段回答三个不同问题,缺一个就会误判。(来源) 决策表:
| 想知道 | 看哪个字段 |
|---|---|
| 读到源会话哪个位置 | capturedThroughSeq |
| 源端是否已经少了内容 | compacted |
| 少了多少 | originalMessages / retainedMessages / omittedMessages |
| 本次是否又省略了 | truncated |
典型误区是只看坐标就宣布「引用到了第 87 条」。如果源会话压缩过,第 87 条之后的历史并不等于「原始第 87 条之后」。
另一个误区是只看计数就推断位置。计数说明规模,不说明边界。
正确顺序:先用坐标定位边界,再用 compacted 判断这段边界是否已经被压缩改写过,最后用计数确认缺口大小。
DSH plugin 跨会话拼接时该怎么存
坐标与会话身份绑定存储,不做任何换算。(来源) 三条做法:
- 存成
(sessionId, capturedThroughSeq)对,读取时成对取出; - 展示时注明来源会话,例如「来源 A,读到第 87 条」;
- 需要跳到源会话时,用源 sessionId 打开,再按坐标定位。
第三条是唯一安全的跳转方式。先切会话,再定位;不要先在当前会话里找,再试图纠正。
如果产品需要「引用段落」的可点击锚点,锚点里应该同时编码会话身份和坐标,而不是只存一个数字。
还有一条:日志里打印坐标时也带上会话身份。只打一个 seq=87,半年后没人能判断它属于谁。
DSH plugin 坐标读法的验证
三步加一个反例,确认坐标没有被重解释。 步骤:
- 引用一个源会话,记录
capturedThroughSeq与源sessionId; - 用源会话身份打开该坐标,确认落在快照的末条消息上;
- 用当前会话身份打开同一个数字,确认结果与第 2 步不同(或明确无此位置)。
第 3 步是反例断言:如果两边结果相同,说明你的宿主在某处做了隐式重解释,或者两个会话恰好同构,需要换一组数据再测。
再补一个缺省用例:构造一个没有坐标的引用,确认宿主展示「位置未知」,而不是显示第 0 条。
坐标理清之后,下一步是格式版本。读 DSH plugin 的 capturedFormatVersion 缺失即 v0;想理解源端缺口,读 DSH plugin 引用已压缩的源会话;想先看持久记录结构,读 DSH plugin 的 recall 记录怎么读。
来源:DeepSeek Harness 官方参考 - 会话引用、session-reference/src/types.ts
常见问题
不是,DSH plugin 的 capturedThroughSeq 属于源会话的原始 generation。它属于被引用会话的原始 generation,记录快照读到源会话的哪个位置。DSH plugin 明确不会把它重新解释为所在会话的 seq。
不能,DSH plugin 的 seq 必须和 sessionId 成对使用。不同会话各有自己的 generation 与序号空间,大小比较没有意义。DSH plugin 的坐标必须和 sessionId 成对使用,离开会话身份的 seq 只是一个孤立数字。
DSH plugin 允许坐标缺省,因为有些引用场景拿不到明确坐标,例如源会话信息不完整或记录来自较旧格式。DSH plugin 允许该字段缺省,此时不能假设坐标存在,也不能用 0 当占位。
DSH plugin 的坐标仍然属于源 generation,不会因为压缩被改写成本会话的序号。DSH plugin 用 compacted 与消息计数描述缺口,坐标负责说明读到哪,两者要一起读。
相关术语
- capturedThroughSeq
- capturedThroughSeq 是持久 source 中的可选序号,表示引用快照读到被引用会话原始 generation 的哪个位置。— DeepSeek Harness 官方参考 - 会话引用
- generation
- generation 是会话历史的版本空间,序号在该空间内有效,跨会话不通用。— DeepSeek Harness 官方参考 - 会话引用
- seq 重解释
- seq 重解释是把源会话的序号当成当前会话序号使用,属于明确的越界读法。— session-reference/src/types.ts
- 跨会话拼接(cross-session splicing)
- 跨会话拼接是把多个引用快照放进同一条消息上下文,各段坐标仍归属各自源会话。— DeepSeek Harness 官方参考 - 会话引用
来源
- DeepSeek Harness 官方参考 - 会话引用· deepseek-ai
- session-reference/src/types.ts· deepseek-ai