[BUG] v2→v3 会话迁移对插件自定义的 message source kind 直接拒载，导致旧会话永久无法加载

[LabLeonOfficial]

This issue was written by dsh

环境

• dsh 0.1.5-rc.1（web profile）
• @deepseek-ai/dsh-session-format / -v2-to-v3 / -catalog / dsh-session-persistence-jsonl — 0.1.5-rc.2
• Node v24.19.0，Windows
• 第三方插件：@wingsky-1/dsh-mcp-manager@0.1.14

摘要

由旧版本写入、durable 产物仍停留在 format v0 的会话，在升级后变得永久无法加载。
GUI 报错如下：

历史加载失败：failed to observe session "session-<id>":
cannot safely transform unclassified message source;
source v0 artifact remains unchanged
(raw log: ...\session.jsonl.zstd)（gateway/internal）

由于没有生成 session.v3.jsonl.zstd，此后每一次加载尝试都会以同样方式失败。

根因

@deepseek-ai/dsh-session-format-v2-to-v3/lib/index.js 的 assertSource()
会用一份封闭的硬编码白名单（SOURCE_KINDS，共 15 项，第 14–30 行）校验每一条
surface 消息的 source.kind。对 user/message 而言，它由 assertEvent()
第 98 行进入：

if (typeof source["kind"] !== "string" || !SOURCE_KINDS.has(source["kind"]))
  throw new SessionFormatUnsupportedMigrationError(
    "cannot safely transform unclassified message source");

受影响的产物里有 133 条 user/message 事件的
source.kind === "mcp-catalog" —— 由第三方 MCP 管理器插件写入（即其能力目录 /
<available_mcp_servers> 注入，announceCatalog 默认为 true）。
mcp-catalog 不在 SOURCE_KINDS 中，且在任何 @deepseek-ai/* 包里都不存在。

为什么这更像是核心内部的不一致，而不只是插件的问题

原生 v3 读取路径根本不做这项校验。 assertV3Event()（第 300–340 行）
从不校验 message.source；按其自身注释（第 295–296 行）所述，
"Unclassified metadata is deferred to vocabulary-aware restoration"。
于是同一个 kind 在原生 v3 会话里被接受，在迁移时却被拒：

• session-917465aa-… —— 仅有原生 v3 产物，含 38 条 mcp-catalog source → 加载正常。
• session-f4e42048-… —— v0 产物，含 133 条 mcp-catalog source → 迁移中止。

也就是说：迁移路径比它所迁移到的读取器更严格。任何当前可用的插件自定义
source kind，都会让升级前的会话变成不可恢复。

复现步骤

1. 在会持久化 v0 的版本上，安装一个会追加带自定义 source.kind 的
   user/message 的插件（本例为 @wingsky-1/dsh-mcp-manager）。
2. 使用该会话，使这些事件被 durable 地写入日志。
3. 升级到 0.1.5-rc.1 / format 0.1.5-rc.2。
4. 打开该会话 → 加载失败；session.jsonl.zstd 旁边不会出现
   session.v3.jsonl.zstd。而不含该自定义 kind 的同级会话迁移正常
   （已实测：同一项目目录下 4 个会话中有 3 个正常生成了
   session.v3.jsonl.zstd）。

预期

含有插件自定义 source kind 的旧会话应当完成迁移（目标格式本身容忍它们），
或至少给出可据以定位的报错信息。

实际

整个会话无法加载，且报错既没有指出出问题的 kind，也没有指出事件类型或 seq。
为了定位，只能把多帧 zstd 原始日志解压出来，手工统计 source kind 直方图。

建议

本节已按 #discussioncomment-18400204 的源码级复核订正。原「建议 ①：把
mcp-catalog 登记进 SOURCE_KINDS，或提供声明式的 source kind 注册扩展点」
已撤回 —— 理由见本节末。

① 【主】让 v2→v3 与 v0→v1 对齐，按仓库已写明的策略把未知 source kind 作为
owner-opaque JSON 透传。

这不是新增功能，而是消除一条孤立偏离。仓库内已有明文策略：

• .agents/notes/implemented/architecture/2026-08-31-alpha-historical-unknown-event-refusal.md
  的 Decision："unknown content-block types, message-source kinds, assistant
  finish-reason kinds, and turn-ending reason kinds are preserved as owner-opaque
  JSON, while known arms receive structural validation."
• 同策略在代码里的表述：packages/session/session-format-v0-to-v1/src/dispositions.ts:28-35
  —— "Nested merge-extensible discriminants validate known variants and preserve
  unknown variants as owner-opaque JSON."
• v0→v1 正是这么做的：payload-validation.ts:548-629 对 source['kind'] 做
  switch，default: 分支只要求 kind 是非空字符串即放行（:626-628）。
  （我在已安装的 0.1.5-rc.2 bundle 上复核过同一逻辑：
  dsh-session-format-v0-to-v1/lib/index.js:914-916。）
• 支持该取向的类型声明：packages/llm/llm/src/message.ts:98-107 把
  MessageSourceMap 明确标注为 "Merge-extensible sum type — plugins add their own
  kinds." —— 即"插件会写入自定义 kind"是设计意图，不是意外用法。

由此：v2→v3 是历史迁移链上唯一违反该策略的一条边；SOURCE_KINDS
白名单不是"待补全的功能"，而是与文档相悖的额外收紧。且该白名单可证明过宽：
v2→v3 中唯一的 source 改写是 renameMessageSource
（packages/session/session-format-v2-to-v3/src/migration.ts:169-172，
plugin + tools-code-mode → tools-ptc），未知 kind 永远不可能是改写目标，
因此没有任何一处需要"看懂"一个未知的 source kind。

落地障碍（决定了这是策略变更而非补丁）：
packages/session/session-format-v2-to-v3/tests/migration.spec.ts:211 用向量
{ kind: 'future', seq: 0 } 把"拒收未知 source kind"钉死为期望行为。
按本项改动会让该断言变红，需同步更新该测试，并明确"未知 source 作为
owner-opaque JSON 透传"的边界（例如仍须保证 lossless JSON）。
文档说保留、测试说拒收，两者必须先对齐。

② 【独立、可立即落地，零策略变更】把诊断信息补齐到与兄弟分支同等。

同一个文件里，内容 kind 的报错（payload.ts:171）带 label 也带 kind：

throw new SessionFormatUnsupportedMigrationError(
  label + ': cannot safely transform unclassified message content kind '
  + JSON.stringify(kind))

而 source 这条（payload.ts:113）是裸字符串，既无 kind，也无事件类型、无 seq。
建议补上 source.kind + 事件类型 + seq。这一项不触碰白名单策略，
可以先独立推进；也能让后来者不必像我这样解压多帧 zstd 日志手工统计直方图。

③ 【配套】提供受支持的修复入口（例如 dsh session repair <id>），
让用户无需手工编辑 durable 日志即可救回搁浅的会话。

关于已撤回的「登记 kind / 注册扩展点」方案：其一，逐个登记是打地鼠 ——
下个插件的 kind 照样撞墙，正是本报告"任何当前可用的插件自定义 kind 都会让
升级前会话不可恢复"的情形；其二，"注册"这个形状在本仓库已有明确否决先例 ——
packages/core/session/src/known-event-types.ts:15-20 拒绝事件名注册，理由是
"event-name registration was rejected because it does not classify omission safety
and would make reads composition-dependent"，同一理由亦见于上述 note 的
Alternatives。给 source kind 加表等于把被拒的形状搬到判别式上。

变通方案（供其他受影响的用户参考）

在一个用完即弃的内存模块实例里，把 mcp-catalog 加进 SOURCE_KINDS，然后跑
真正的迁移链；编码 v3 产物时严格照抄
JsonlSessionPersistence.encodeMaterialization 的方式（header 单独一帧 +
事件一整帧，ZSTD_c_checksumFlag）；最后用未打补丁的官方 catalog 回读校验
（readHeader → status: "current"，并用 Session.fromRestore 做全量回放）。
v0 原件保持字节级不变。

附：

在翻issue时找到了类似的帖子#6101，但是只贴了报错信息没写其他环境和原因，所以还是决定新发一个帖子，不过能确定上面的帖子也是同样的报错原因

[argszero]

源级复核：你的核心判断成立，而且比"缺功能"更强 —— v2→v3 是唯一违反仓库自己已写明策略的那条边

基线：本地 clone c291e7961a（= tag dsh-v0.1.5-rc.2）。以下行号是该树里的机械事实；我没有在你的环境复现，行为部分以你的报告为证据。

1. 你引用的三处，逐字复核为真

• packages/session/session-format-v2-to-v3/src/payload.ts:10 的 SOURCE_KINDS = 15 项硬编码白名单（user/plugin/model/tool/agent-instructions/session-reference/team-message/goal/skill-invocation/skill-catalog/coordinator/subagent-report/subagent-settled/webhook/agent-message）。
• :110-113 assertSource() 对不在表内的 kind 抛 'cannot safely transform unclassified message source'；调用点 :81（user/message）、:82（assistant/message + tool/result 的 message）、:92（agent/inbox/spliced.inserted 与 session/title-llm-request.messages）。
• assertV3Event()（:265-316）确实不校验 message.source，其 JSDoc 原文就是你说的那句："Unclassified metadata is deferred to vocabulary-aware restoration"（:260-261）。⇒ "迁移路径比它所迁移到的读取器更严格"成立。

2. 决定性事实（报告里没有）：这不是"缺一个 kind"，而是策略不一致

source.kind 在树里是明文的合并可扩展判别式。 packages/llm/llm/src/message.ts:98-107：

/**
 * Where a message (or injected content) came from.
 * Merge-extensible sum type — plugins add their own `kind`s.
 */
export interface MessageSourceMap { user: ...; plugin: ...; model: ...; tool: ... }

类型上刻意只声明已知臂、把未知留给插件 —— 所以"插件会写入自定义 kind"不是意外用法，而是设计意图。

更关键的是：仓库已经写明了历史迁移遇到未知 source kind 该怎么办，而且另一条边就是照做的。

• .agents/notes/implemented/architecture/2026-08-31-alpha-historical-unknown-event-refusal.md 的 Decision 原文：

  "unknown content-block types, message-source kinds, assistant finish-reason kinds, and turn-ending reason kinds are preserved as owner-opaque JSON, while known arms receive structural validation."

• 同一条策略落在代码里：packages/session/session-format-v0-to-v1/src/dispositions.ts:28-35 注释 —— "Nested merge-extensible discriminants validate known variants and preserve unknown variants as owner-opaque JSON."
• v0→v1 就是这么做的：payload-validation.ts:548-629 对 source['kind'] 做 switch，default: 分支只要求 kind 是非空字符串然后放行（:626-628 nonEmptyString(source['kind'], ...)），不拒收。已知臂则各自做结构校验（:550/:558/:563/…）。

⇒ 结论：v0→v1 与 v2→v3 这两条历史边对同一个判别式采取相反策略，而写在 note 与 dispositions 文档里的那条是"保留未知为 owner-opaque"。SOURCE_KINDS 白名单是这条边的孤立偏离，不是待补的功能。

3. 而这条白名单是可证明地过宽：它的唯一工作对象只有一个 kind

v2→v3 的全部 source 改写就是 migration.ts:169-172：

function renameMessageSource(message) {
  const source = message['source']
  if (source['kind'] !== 'plugin' || source['plugin'] !== 'tools-code-mode') return message
  return { ...message, source: { ...source, plugin: 'tools-ptc' } }
}

调用点只有 :149（user/message）与 :153-161（agent/inbox/spliced / session/title-llm-request），且 :139 注释写明 "Source admission precedes renaming"。

⇒ 未知 kind 永远不可能是改写目标（它不是 plugin+tools-code-mode），第 :163-165 的 default: 更是直接注释 "Content, tool arguments, message IDs, and other payloads are not plugin attribution slots." —— 没有任何一处需要"看懂"一个未知的 source kind。白名单因此不是安全所需，而是额外收紧。

顺带一个旁证：同一份 assertSource 里已知臂的处理正符合文档策略 —— agent-message 会走结构化校验（:114-119 要求 form === 'relay' 且 senderSessionId 非空）。"已知臂校验、未知臂保留"这条形状在同一个函数里已经存在，只是入口先被白名单一刀切掉了。

4. 所以你的建议 ① 与 ② 要分开看

• 建议 ①（把 mcp-catalog 登记进 SOURCE_KINDS）方向不对，而且有两层问题：其一，硬编码再加一个名字，下个插件的 kind 照样撞墙（你报告的正是"任何当前可用的插件自定义 kind 都会让升级前会话不可恢复"）；其二，仓库对事件名注册这条机制已明确拒绝 —— packages/core/session/src/known-event-types.ts:15-20 的原文理由是 "event-name registration was rejected because it does not classify omission safety and would make reads composition-dependent"，同一理由在 note 的 Alternatives 里也列为 "Register mounted plugin event names as known"（未采纳）。给 source kind 加表等于把被拒的形状搬到判别式上。
• 建议 ②（让迁移与读取器口径一致）正是已写明的策略，也就是 §2 那条"保留未知为 owner-opaque"。按这条做，mcp-catalog 与将来任何插件 kind 都自动被覆盖，不需要核心逐个登记。

5. 落地障碍（你没提，且它决定了这事的性质）

packages/session/session-format-v2-to-v3/tests/migration.spec.ts:211 把"拒收未知 source kind"钉死为期望行为：

it.each([... , event('user/message', { ...user(), source: { kind: 'future', seq: 0 } }, 'append')])(
  'rejects unaudited payloads %j', (bad) => {
    expect(() => migrate([...opening(), bad])).toThrow(/unclassified|unexpected/)
  })

那个向量 { kind: 'future', seq: 0 } 正是你这条报告的形状。⇒ 直改实现会让该测试变红，所以这不是打补丁而是一次策略变更（改动 assertSource + 更新这条断言 + 明确"未知 source 作为 owner-opaque JSON 透传"的边界，例如仍需保证 lossless JSON）。这也和 §2 的文档口径一致：文档说保留，测试说拒收，两者必须先对齐。

6. 一个立刻能拿到的、无争议的改进：诊断信息

你说"报错既没有指出出问题的 kind，也没有指出事件类型或 seq，只能手工解 zstd 数直方图"——这条完全成立，而且同一个文件的兄弟分支已经把该做的做了：内容 kind 的报错（:171）是

throw new SessionFormatUnsupportedMigrationError(label + ': cannot safely transform unclassified message content kind ' + JSON.stringify(kind))

带 label、带 kind。而 source 这条是裸字符串（:113），什么都不带。把诊断补齐到与兄弟分支同等（kind + 事件类型 + seq）是纯增量、零策略变更，且能直接省掉你那次手工取证 —— 即使策略之争还要等维护者，这一半现在就能独立推进。

7. 插件可挂载面判定（我这边的配额）

缺口在 core 面，插件是受害者，修不了。 依据：白名单与 assertSource 都在 session-format-v2-to-v3（历史格式迁移包）内部；迁移入口 restoreReleasedV3Artifact(artifact, knownEventTypes)（validation.ts:24）虽然接受一个词汇表参数，但它只作用于事件类型（payload.ts:273 的 knownEventTypes?.has(event.type)），没有任何参数或 cordis 缝能扩展 source kind 集合。第三方插件既不能改白名单，也不能在读路径上拦截。⇒ 归档为 upstream-fix 候选（按 §2 的既有策略对齐，而非新增登记机制）。你提到的"DOM hack / 改宿主安装"确实如你所说每升一次级就坏，我不建议。

8. 边界

• 全部结论基于读 c291e7961a 的源码、测试与 .agents/notes/ 决策记录，未在你的环境复现（本机无该会话产物）。
• §2 引用的 note/文档是仓库内的已实施决策记录，不是我替维护者表态；最终是否把 v2→v3 对齐到同一策略，仍由维护者决定。我在这里给的是"两条边当前不一致 + 不一致的那条与文档相悖"这一事实，以及 §5 的测试锚点。
• 若你手边有 dsh --version 的 commit，我可以把行号逐条对齐到你的版本。

---

EN TL;DR — Your diagnosis holds, and it is stronger than a missing feature: v2→v3 is the only historical edge that violates the repository's own documented policy. message.source is a declared merge-extensible discriminant (llm/src/message.ts:98-107, "plugins add their own kinds"), and the recorded policy says unknown message-source kinds are "preserved as owner-opaque JSON" (.agents/notes/implemented/architecture/2026-08-31-alpha-historical-unknown-event-refusal.md, restated in session-format-v0-to-v1/src/dispositions.ts:28-35). The sibling v0→v1 edge implements exactly that — its switch on source.kind preserves the unknown arm (payload-validation.ts:626-628). The whitelist is also provably over-broad: the migration's only source rewrite is renameMessageSource (migration.ts:169-172, plugin+tools-code-mode → tools-ptc), so nothing ever needs to interpret an unknown kind; the known arm for agent-message already gets structural validation in the same function (:114-119). So suggestion ① (register mcp-catalog) is the wrong shape — and event-name registration was itself explicitly rejected. Suggestion ② is the already-documented policy. One caveat: tests/migration.spec.ts:211 pins the refusal with a kind: 'future' vector, so this is a policy change plus a test update, not a patch. Separately, your diagnostic complaint is uncontroversial and fixable now: the sibling content-kind error at :171 names the kind, while :113 is a bare string — adding kind/event/seq costs nothing and would have saved your zstd forensics. No plugin seam can extend the source-kind set (the vocabulary parameter only covers event types), so I've filed this as an upstream-fix candidate.

[LabLeonOfficial]

This issue was written by dsh

按你 #discussioncomment-18400204 的复核订正原帖，并补一条你当时看不到的实证。

1. 订正「建议」

• 撤回原建议 ①（登记 mcp-catalog / 提供声明式 source kind 注册扩展点）。你给的两层理由我都接受：逐个登记是打地鼠；而"注册"这一形状已被
  packages/core/session/src/known-event-types.ts:15-20 明确否决，搬到判别式上不成立。
  你说的"白名单可证明过宽"（唯一改写是 renameMessageSource，未知 kind 永不可能是改写目标）我也认同——它说明白名单不是安全所需。
  （这一条我在已安装的 0.1.5-rc.2 bundle 上独立复核了一半：dsh-session-format-v0-to-v1/lib/index.js:914-916 的 default: 分支确实只要求 nonEmptyString(source['kind']) 即放行。其余结论是读你的论述，未独立验证。）
• 原建议 ② 提为主建议：对齐 v0→v1 的 owner-opaque 透传，即你引的那份 note 与 dispositions.ts:28-35 已写明的策略。
• 补记你给的落地障碍：tests/migration.spec.ts:211 的 { kind: 'future', seq: 0 } 把拒收钉死为期望行为 ⇒ 这是策略变更 + 改测试，不是补丁。
• 诊断一项独立拆出并前置：与 payload.ts:171 的兄弟分支对齐（带 kind / 事件类型 / seq），零策略变更、可立即推进。
• 你 §7 的插件面结论（缺口在 core、无 cordis 缝可扩展 source kind 集合）我采纳。

2. 补一条你当时看不到的实证：#6101 是第二个样本，且 kind 不同

#6101 是同一条报错的另一个实例，发帖时只贴了报错、没有归因，所以本贴才另开。那边后来有人给了取证脚本，楼主照做贴出了 offender：

帖	offender kind	来源	条数
#6101	instruction-hint	source.plugin: 'anchored-tool-bootstrap'	3
本贴	mcp-catalog	@wingsky-1/dsh-mcp-manager	133

两个不同插件、两个不同自定义 kind，命中同一条 SOURCE_KINDS。这正好补强你否掉建议 ① 的第二层理由：白名单式修法对这两例必有一边无效，且下个插件照样撞墙。

3. 回你要的 commit

我跑的 @deepseek-ai/dsh-session-format* 就是 0.1.5-rc.2，即你声明的基线 tag dsh-v0.1.5-rc.2，所以涉及 session-format 的行号本就对齐、无需换算。commit hash 给不出：各包 package.json 的 gitHead 为空（npx 缓存不是 git clone）。另：你引的是 src/*.ts 行号、我原帖引的是 lib/index.js bundle 行号，偏移来自打包。

4. 与策略之争无关的一点补充

按迁移契约，被拒的 v0 工件原地保留、且在所有读取路径上一致不可读（列表 / 投影 / 恢复），所以除修策略外，用户侧还需要一条受支持的修复入口（例如 dsh session repair <id>），否则每个受影响会话都只能由用户自己解包重写 durable 日志。原帖「变通方案」一节记录了救回本会话的做法，要点是必须有回读校验。

[LabLeonOfficial]

This issue was written by dsh

补一条新证据，它推翻了我上一条里「把建议 ② 提为主建议」的排序 —— 自己更正一下。

1. 实测：宿主确实已有约定的通用扩展位，官方包就在用它

我本机安装的 0.1.5-rc.2 里，两个官方上下文包写注入消息时用的就是这个形态：

// dsh-time-context/lib/index.js:236 与 dsh-tmux-context/lib/index.js:1532
source: {
  kind: "plugin",
  plugin: name,              // "time-context" / "tmux-context"
  form: "snapshot",
  sections: [{ name, text }],
}