升级到0.1.7-alpha.2后提示： 本轮运行失败format v4 message requires a producer-owned source kind

[ttkttka]

升级到0.1.7-alpha.2后提示：“本轮运行失败format v4 message requires a producer-owned source kind”，请问该怎么修复？

[1420079678-ctrl]

我按当前 master 的源码把这条错误追到底了。结论先说：这不是数据损坏，也不是你升级姿势的问题——是你机器上某个生产方在 v4 下仍然写「退役包装」{"kind":"plugin"}。下面给出机制、一条能直接跑的取证命令，和两条修复路径。凡是我没在你机器上复现的，我都标出来。

这条检查到底拒绝什么

packages/session/session-format-v3-to-v4/src/message-sources.ts 里，同一个谓词同时管读和写：

if (!isSessionFormatJsonObject(value) || typeof value['kind'] !== 'string'
    || value['kind'].length === 0 || value['kind'] === 'plugin')
  throw new SessionFormatError('format v4 message requires a producer-owned source kind')

被拒的只有这几种：source 缺失 / 不是对象 / kind 不是非空字符串 / kind === 'plugin'。同包的单元测试把集合钉死了：

for (const source of [null, [], {}, { kind: '' }, { kind: 1 }, { kind: 'plugin', plugin: 'compact' }])
  expect(() => restore(source)).toThrow(/producer-owned source kind/)

检查覆盖每一个声明的消息槽——user/message、system/message、assistant/message、tool/result、agent/inbox/spliced 的 inserted、session/title-llm-request 的 messages；并且读（decodeRow → assertV4SourceRowAdmission）和写（encodeCurrentEvent）两侧都会抛，所以你看到的是「本轮运行失败」而不是一条解析警告。（external/event 的 source 不在检查范围内——测试里明确写了它不抛。）

为什么旧日志通常没事，而你有事

v3→v4 迁移会自动重写旧包装，所以绝大多数人升级后不会遇到它。测试里的正例（restore(source, 3)）：

{"kind":"plugin","plugin":"acme"}  →  {"kind":"plugin:acme"}      // 其余字段原样保留

而 rewritePluginSource 用的映射是 producerKind()：第一方同名生产方保留原名（tool-jobs、user-approval、plan-mode、time-context、schedule 等 24 个），@deepseek-ai/dsh-system-prompt + role: 'system' 变成 system-prompt，其余一律变成 plugin:<名字>。所以 plugin:<name> 就是规范形式（测试第 30–35 行确认 plugin:acme 会被原样接纳）。

推论（这一条是推断，不是我在你机器上验证的）：既然 v3 行会被迁移，那么一条在 v4 admission 时仍带 kind:'plugin' 的行，就不是迁移没跑到，而是v4 时代仍在写退役语法的生产方写出来的。我在官方 master 里全文搜过写 kind: 'plugin' 的地方，一处都没有——所以它几乎可以确定是你环境里的第三方插件（或你自己手工构造的事件）。要我押注的话，优先查那些会往 inbox 注入消息、或自己构造 user/message 的插件。

取证：直接找出是哪个生产方

别用 Select-String 去搜会话日志——它们是多帧 zstd（session.jsonl.zstd，魔数 28 B5 2F FD），普通单帧解压器只解第一帧，后面的行根本读不到，「没搜到」是假的。下面这段只用 Node 内置 zstdDecompressSync，逐帧扫、按 assertV4SourceRowAdmission 同一批消息槽判定：

// node scan.mjs "$env:DSH_HOME/sessions"      （Node 24 内置 zstd）
import fs from 'node:fs'; import path from 'node:path'; import zlib from 'node:zlib'
const MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd])
const walk = (p, out = []) => { const s = fs.statSync(p)
  if (s.isFile()) { if (/\.jsonl(\.zstd)?$/.test(p)) out.push(p); return out }
  for (const e of fs.readdirSync(p, { withFileTypes: true })) walk(path.join(p, e.name), out); return out }
const frames = (b) => { const o = []; let i = b.indexOf(MAGIC); while (i !== -1) { o.push(i); i = b.indexOf(MAGIC, i + 4) } return o }
const decode = (b) => { const o = frames(b); if (!o.length) return ''
  return o.map((s, k) => { const e = k + 1 < o.length ? o[k + 1] : b.length
    try { return zlib.zstdDecompressSync(b.subarray(s, e)).toString('utf8') } catch { return '' } }).join('') }
const SLOTS = { 'user/message': (d) => [d], 'system/message': (d) => [d.message], 'assistant/message': (d) => [d.message],
  'tool/result': (d) => [d.message], 'agent/inbox/spliced': (d) => d.inserted, 'session/title-llm-request': (d) => d.messages }
const hits = new Map()
for (const file of walk(process.argv[2])) {
  for (const line of decode(fs.readFileSync(file)).split('\n')) {
    const t = line.trim(); if (!t.startsWith('{')) continue
    let row; try { row = JSON.parse(t) } catch { continue }
    const pick = SLOTS[row?.type]; if (!pick) continue
    const msgs = pick(row.data ?? {}); if (!Array.isArray(msgs)) continue
    for (const m of msgs) { if (m?.source?.kind !== 'plugin') continue
      const who = typeof m.source.plugin === 'string' ? m.source.plugin : '<没有 plugin 字段>'
      hits.set(who, (hits.get(who) ?? 0) + 1) }
  }
}
console.log(hits.size ? [...hits].sort((a, b) => b[1] - a[1])
  : '没有 kind=plugin 的消息——这条规则不会拒你这些日志。')

我在一台真实的 0.1.6-alpha.2 机器上跑过这个思路（会话日志 12k 行、7879 帧）：它准确报出了 85 条退役包装，并按生产方分组（tool-jobs 76、repeat-tool-reminder 4、user-approval 2、@deepseek-ai/dsh-system-prompt 2、dsh-session-title-llm 1）。在你的 0.1.7-alpha.2 上跑，它给出的那个名字就是需要迁移的插件。

两条出路

① 立刻恢复工作：拒绝是按行、在 admission 时发生的。新开一个会话不会重新准入那批坏行，所以先开新会话就能干活；旧会话仍可作历史阅读，但别指望在那个 turn 上续聊。若你必须救回那个会话，机械修复与 rewritePluginSource 同构：把 {"kind":"plugin","plugin":"X"} 改成 {"kind":"plugin:X"}（若 X 是上面那 24 个第一方同名生产方之一，则直接用 X），其余字段一律不动。动手前先备份——V4 路径是 validation: 'current'，修坏了会变成解析错误，而不是干净的拒绝。

② 真正修掉它：生产方必须写 producer-owned 的 kind——第三方就是 plugin:<它自己的名字>，第一方用原身份。如果第 ② 步查出的名字是第一方（tool-jobs / user-approval / time-context / schedule 这类），那是一条值得单独开的 bug：RELEASED_SAME_NAME_PRODUCERS 这张表存在的意义正是让它们保住身份，v4 时代还在写包装就是漏迁移。

把取证脚本报出的那个 plugin 值贴出来就够了（不用贴会话内容），映射到正确 kind 是机械的，我可以直接给你那一行替换。顺带一句：{ kind: 'acme' }、{ kind: 'source:acme' } 这类非 plugin 前缀的直接 kind 也是合法的——被拒的从来只有 'plugin' 这一个值。

[1420079678-ctrl]

补充一条横向结论：这不是个例，而是所有「按 v3 写法注入消息」的第三方插件在 0.1.7 上都会遇到的版本边界问题——v3 的白名单只认 'plugin'，v4 又只拒 'plugin'，两个版本没有任何共同可用的字面量。

我把两边的源码与实测数据整理成了一份完整报告（含 v3 SOURCE_KINDS 白名单与 v4 拒绝集合的逐行出处、以及一台真实 0.1.6 机器上扫出的 85 条退役包装按生产方分组的结果）：

→ #7556

上面第 ② 步的取证脚本正是为定位这类问题写的；如果你在自己机器上跑到某个第一方名字（tool-jobs、user-approval、time-context、schedule 这类），那更值得单独报出来。

[ZaynJarvis]

这样做 plugin 太难跟进了，有兼容双版本的建议做法吗

[1420079678-ctrl]

有，而且这个不用绕：普通注入消息只需要记一个写法 —— { kind: 'plugin:<你的插件名>' }，它在两个版本上都成立。

先给证据，再给做法。我在同一条帖子里更正过一次自己的结论，最终以宿主自己的判定为准（encodeCurrentEvent 就是 JSONL 写入调用的那个函数，一台 0.1.6 机器上实测）：

槽位	{ kind:'plugin', plugin:'X' }	{ kind:'plugin:X' }
user/message	接受	接受
agent/inbox/spliced	接受	接受
system/message	接受	拒绝 — system message requires plugin source

原因是 v3 那份 SOURCE_KINDS 白名单挂在 assertEvent(event, 2) 上，而它在 version === 3 时直接 return，只约束 v2→v3 迁移，不校验原生 v3 写入。所以旧包装并不是「v3 的要求」，只是当年所有人的写法。

建议做法（三步，都是机械替换）

1. 把 source 收敛到一个 helper，别在每处写字面量。 下次格式再变，只改一行：

// v4 要求的 producer-owned 形式；v3 的原生写入路径同样接受
const injectedSource = (name: string) => ({ kind: `plugin:${name}` })

agent.inject(createUserMessage({
  source: injectedSource('@acme/my-plugin'),
  content: [{ type: 'text', text: note }],
}))

2. 身份字符串沿用它原来在 plugin 字段里的值，只把它拼进 kind，并把 plugin 字段去掉。这样它和迁移器对历史行算出来的值逐字一致 —— 老行被改写后与新写入是同一种来源，你的来源统计不会断代。别顺手改成包名之外的东西，那会让同一插件在日志里有两个身份。

3. 第三方用 plugin:<自己的名字>，不要借用第一方名字（goal / time-context / plan-mode / subagent-report 这 24 个）。借用既是冒名，也会让按来源做的统计失真。

唯一需要版本感知的那一格

system/message 是例外，两代没有共同写法：v3 的 assertSystem 明确要求 kind === 'plugin' 加非空 plugin 字符串，v4 又拒 'plugin'。

推荐做法是不要写这个槽位。 绝大多数注入走 user/message 或 inbox；我这边五个注入点（心跳简报、本体感觉、记忆召回、队员投递）没有一个需要 system/message。确实非写不可，就只能按宿主代际分支（会话头的 version）或写一层 try/catch 回退 —— 但这属于边缘情况，不该成为你迁移的前置条件。

自己验一遍（不用信我的结论）

把这段存成 probe.mjs，指着你机器上已安装的 catalog 跑：

// node probe.mjs <已安装路径>/session-format-catalog/lib/index.js
const { sessionFormatCatalog } = await import(process.argv[2])
const msg = (source) => ({ id: 'p', role: 'user', source, content: [{ type: 'text', text: 'p' }] })
const cases = [
  ['user   旧', { type: 'user/message', seq: 1, time: 1, surfaceOp: 'append', data: msg({ kind: 'plugin', plugin: 'x' }) }],
  ['user   新', { type: 'user/message', seq: 1, time: 1, surfaceOp: 'append', data: msg({ kind: 'plugin:x' }) }],
  ['inbox  新', { type: 'agent/inbox/spliced', seq: 1, time: 1, data: { inserted: [msg({ kind: 'plugin:x' })] } }],
]
for (const [label, event] of cases) {
  try { sessionFormatCatalog.encodeCurrentEvent(event); console.log('通过 ', label) }
  catch (error) { console.log('拒绝 ', label, '→', error.message) }
}

在 0.1.6 上它应该打出「通过/通过/通过」，在 0.1.7 上旧的那条会变成拒绝 —— 两个版本各跑一次，你的迁移是否正确当场就知道。

关于「太难跟进」

这句我不反驳。v3→v4 对插件作者没有过渡窗口：官方 master 里第一方生产者全迁完了，树外插件只能自己发现，而且唯一能提示你的是一句运行时错误（新会话能开、老会话能读，只有写入那一刻才炸）。短期能做的就是上面那一步 —— 一行改完、两个版本都对；长期该由宿主提供一个生产者 helper（把拼 kind 这件事从插件手里拿走），我在同一份报告里提了这一点，也把「system/message 才是唯一不通用槽位」这个更正补在了那里。

把你构造 source 的那几处贴出来（或只给插件名 + 现在写的值），我可以直接把逐行替换结果给你。