ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 的 capturedThroughSeq:源 generation 坐标,不是当前会话位置

插件开发发布于 2026-11-10作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness会话引用capturedThroughSeq跨会话
跨会话拼接时把引用坐标当成本会话 seq,是定位错乱的常见起点。本文讲 capturedThroughSeq 属于源 generation、为什么不能重解释,以及和压缩、消息计数一起该怎么读。

在 DSH plugin(DSH插件) 里,把 capturedThroughSeq 当成本会话的消息序号,是跨会话引用里最容易犯的一次坐标错位。 它记录的是快照读到源会话原始 generation 的哪个位置;离开源会话身份,这个数字什么也不代表。

DSH plugin 一次坐标错位的现场

症状很像「引用错位」,实际是两组序号被混用了。(来源) 现场:

text
当前会话 seq 到 120
引用快照 capturedThroughSeq = 87
宿主拿 87 去当前会话定位 → 落在一条毫不相关的消息上

没有人写错代码,只是默认了「seq 是全局的」。

一旦这个假设成立,后续所有回溯、跳转、diff 都会偏。

判断方法很简单:问这个数字属于哪个会话。答不上来,就说明用错了。

DSH plugin 的两份 seq 空间

每个会话有自己的序号空间,跨会话没有大小关系。(来源) 对照:

维度源会话 generation当前会话
谁分配序号源会话自己当前会话自己
capturedThroughSeq 属于谁源会话不属于
能否跨会话比较大小不能不能
有效前提带上源 sessionId带上当前 sessionId

表格最后一行是关键:序号不是独立主键,它必须和会话身份成对出现。

这也是为什么持久记录里 sessionId 与 capturedThroughSeq 写在同一个 reference 项里,而不是分开存两张表。

DSH plugin 官方给的三条读法

三条约束,分别管归属、解释和缺省。(来源) 内容:

  1. 属于源 generation — 坐标在源会话的序号空间内有效;
  2. 绝不重解释 — 不会被当作所在会话的 seq;
  3. 可选 — 字段可能缺省,缺省时不能假设存在。

第 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 坐标读法的验证

三步加一个反例,确认坐标没有被重解释。 步骤:

  1. 引用一个源会话,记录 capturedThroughSeq 与源 sessionId;
  2. 用源会话身份打开该坐标,确认落在快照的末条消息上;
  3. 用当前会话身份打开同一个数字,确认结果与第 2 步不同(或明确无此位置)。

第 3 步是反例断言:如果两边结果相同,说明你的宿主在某处做了隐式重解释,或者两个会话恰好同构,需要换一组数据再测。

再补一个缺省用例:构造一个没有坐标的引用,确认宿主展示「位置未知」,而不是显示第 0 条。

坐标理清之后,下一步是格式版本。读 DSH plugin 的 capturedFormatVersion 缺失即 v0;想理解源端缺口,读 DSH plugin 引用已压缩的源会话;想先看持久记录结构,读 DSH plugin 的 recall 记录怎么读。

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

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 capturedThroughSeq 是不是当前会话的消息序号?

不是,DSH plugin 的 capturedThroughSeq 属于源会话的原始 generation。它属于被引用会话的原始 generation,记录快照读到源会话的哪个位置。DSH plugin 明确不会把它重新解释为所在会话的 seq。

DSH plugin 里两个会话的 seq 能不能直接比较大小?

不能,DSH plugin 的 seq 必须和 sessionId 成对使用。不同会话各有自己的 generation 与序号空间,大小比较没有意义。DSH plugin 的坐标必须和 sessionId 成对使用,离开会话身份的 seq 只是一个孤立数字。

DSH plugin 的 capturedThroughSeq 为什么是可选的?

DSH plugin 允许坐标缺省,因为有些引用场景拿不到明确坐标,例如源会话信息不完整或记录来自较旧格式。DSH plugin 允许该字段缺省,此时不能假设坐标存在,也不能用 0 当占位。

DSH plugin 里源会话压缩之后,capturedThroughSeq 会指向压缩后的位置吗?

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

来源