session event "system/message" is not surface-eligible and cannot carry surfaceOp —— 成因、排查方法与修复

[XingbinChen]

以下由DeepSeek-V4.1-Flash分析并生成。

1. 现象

升级dsh版本后，在 dsh --profile web 的浏览器 UI 中（以及终端日志里）出现：

session event "system/message" is not surface-eligible and cannot carry surfaceOp

无法查看旧的对话记录，而且无法选择模型。

环境：

• dsh --version → 0.1.5-rc.1
• 安装来源：npm i -g @deepseek-ai/dsh，安装在 %USERPROFILE%\..\nodejs（普通 Node 全局目录）
• 触发路径：web profile；此前用 marketplace 装过若干 out-of-tree 插件（dsh-context、dsh-better-sidebar、@linxin666/dsh-client-ui-git-graph、dsh-client-ui-skill-explorer），报错发生在插件装卸期间 / host 升级前后
• 关键特征：host 自身能正常启动（dsh --profile web --no-open --port 8099 无报错、UI 正常加载、控制台 0 error），错误只在插件参与时才出现

2. 这条报错的确切来源

全仓库只有一处抛出该字符串（packages/core/session/src/surface.ts，surfaceOpOf()）：

const SURFACE_EVENT_TYPES = new Set<string>([
  'system/message',      // ← 只有较新版本才有这一项
  'user/message',
  'assistant/message',
  'tool/result',
])

if (!isSurfaceEligibleType(event.type)) {
  // Unknown ignorable records retain opaque metadata without affecting history.
  if (!KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable === true) return
  if (raw.surfaceOp !== undefined) {
    throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry surfaceOp`)
  }
  ...
}

validateSurfaceMetadata()（同文件）由这些路径调用：

• Session.append() 与 seed/restore 校验：packages/core/session/src/index.ts
• foldSurface()：会话回放 / snapshot / session-query
• wire 校验：packages/api/session-controller/src/client/session-wire-event.ts（浏览器端历史分页与 live 帧）

结论：抛出这句话的那个 @deepseek-ai/dsh-session 副本，其 SURFACE_EVENT_TYPES 里没有 system/message。 也就是说——事件本身没写错，是读取/校验它的那份库太旧。

3. system/message 什么时候变成 surface 事件的

system/message 是在 commit ee956c720d（2026-09-06，"refactor(session): represent the system prompt as surface node zero"） 才加入 SurfaceEventType 的（设计说明：.agents/notes/implemented/architecture/2026-09-02-system-prompt-as-surface-node.md）。在那之前，系统提示词存放在 log-only 的 request/header.system 里，system/message 根本不存在。

已发布版本的运行时集合（核对各 tag 的 packages/core/session/src/surface.ts）：

版本	SURFACE_EVENT_TYPES
0.1.1-rc.2、0.1.2-rc.1、0.1.3-alpha.1/2 及更早	user/message、assistant/message、tool/result（3 个）
0.1.5-alpha.1、0.1.5-alpha.2、0.1.5-rc.1、0.1.5-rc.2	上述 3 个 + system/message（4 个）

所以：旧库读到新 host 写出的 system/message（带 surfaceOp）时，必然抛这句。

4. 排查方法（逐步可复现）

4.1 先确认 host 本身是新的

dsh --version
npm ls -g @deepseek-ai/dsh-session

如果 host 已是 0.1.5-*，那问题就不在安装本身，而在第二份旧副本。

4.2 枚举机器上所有 dsh-session 副本及其版本

Get-ChildItem -Path "$env:USERPROFILE\.dsh", "$(npm root -g)" -Recurse -Directory -Filter dsh-session -ErrorAction SilentlyContinue |
  Where-Object { $_.FullName -like "*@deepseek-ai*" } |
  ForEach-Object { "{0}  =>  {1}" -f $_.FullName, (Get-Content "$($_.FullName)\package.json" -Raw | ConvertFrom-Json).version }

本次排查结果（问题实例）：

%USERPROFILE%\.dsh\profiles\node_modules\@deepseek-ai\dsh-session                    0.1.5-rc.2
%USERPROFILE%\.dsh\profiles\web\node_modules\@deepseek-ai\dsh-session                0.1.2-rc.1   ← 元凶
<global node_modules>\@deepseek-ai\dsh\node_modules\@deepseek-ai\dsh-session         0.1.5-rc.2

注意：%USERPROFILE%\.dsh\profiles\<profile>\node_modules 里还有整套同代的旧依赖（dsh-llm、dsh-settings、dsh-invariants、dsh-brand、dsh-scope … 均为 0.1.2-rc.1），不只是 dsh-session。

4.3 直接验证哪份副本会抛错

确认旧副本里没有 system/message：

Select-String -Path "$env:USERPROFILE\.dsh\profiles\web\node_modules\@deepseek-ai\dsh-session\lib\index.js" -Pattern 'SURFACE_EVENT_TYPES' -Context 0,4
# 输出里只有 "user/message" "assistant/message" "tool/result"

再用它跑一次最小复现（<copy> = 上面那个目录）：

// node --input-type=module -e "<此脚本>" file:///C:/Users/<you>/.dsh/profiles/web/node_modules/@deepseek-ai/dsh-session/lib/index.js
const mod = await import(process.argv[process.argv.length - 1])
const event = {
  type: 'system/message', seq: 0, time: 1,
  data: { turn: 1, step: 1, message: { role: 'system', content: [] } },
  surfaceOp: 'append',
}
try {
  mod.foldSurface([event])
  console.log('NO ERROR')
} catch (e) {
  console.log('THROWN:', e.message)
}

输出：

THROWN: session event "system/message" is not surface-eligible and cannot carry surfaceOp

同一份副本用新版（0.1.5-rc.2）跑则不会抛错——至此定位完成。

4.4 确认插件解析路径是否被 profile 目录遮盖

node -e "const r=require('module').createRequire('C:/Users/<you>/.dsh/profiles/web/x.js');console.log(r.resolve('@deepseek-ai/dsh-session/package.json'))"

问题状态下指向 ...\profiles\web\node_modules\...（旧），修复后指向安装目录（新）。

为什么 host 不受影响：dsh.profile.bundles 里的包优先从安装目录解析，所以 dsh-base / dsh-web-app 走的是 0.1.5-rc.2；而 out-of-tree 插件从 profile 目录解析，就会拿到 profile 私有的旧副本。这正是"host 启动正常、插件一参与就报错"的原因。

4.5 查 marketplace 的兼容性日志（成因佐证）

%USERPROFILE%\.dsh\profiles\web\.dsh-market\log.ndjson：

{"level":"warn","event":"install-compat","detail":"dsh-context: introduced host-compatibility risks — @deepseek-ai/dsh-session@>=0.1.2-rc.1 vs 0.1.1-rc.2; @deepseek-ai/dsh-settings@>=0.1.2-rc.1 vs 0.1.1-rc.2"}
{"level":"warn","event":"update-compat","detail":"dsh-better-sidebar@0.19.0 declares ^0.1.5-rc.1; this host is 0.1.2-rc.1 — refused before installing"}
{"level":"warn","event":"update-compat","detail":"dsh-better-sidebar: introduced host-compatibility risks — @deepseek-ai/dsh-session@^0.1.5-rc.1 vs 0.1.2-rc.1; ..."}

日志明确显示：装插件时 host 还是 0.1.1-rc.2 / 0.1.2-rc.1，而插件声明的依赖是 >=0.1.2-rc.1 / ^0.1.5-rc.1，于是插件把一整代旧的 dsh-session 拉进了 profile。

5. 根因

插件私有依赖闭包与 host 版本错配，且旧副本在 profile 目录里 shadow 掉了安装里的新副本。

完整链条：

1. system/message 只在 host ≥ 0.1.5-alpha.1 时才是 surface 事件；旧版 @deepseek-ai/dsh-session（≤ 0.1.3-alpha.2）的 SURFACE_EVENT_TYPES 只有 3 个类型。
2. 插件被安装时，pnpm/npm 会把插件声明的 dsh-session 装进 %USERPROFILE%\.dsh\profiles\<profile>\node_modules；插件代码从该目录解析模块，优先拿到这一份。
3. 之后 host 升级（日志中确实存在 0.1.1-rc.2 → 0.1.2-rc.1 → 0.1.5-rc.1 的迁移），开始按新规则写/发 system/message（surface node 0，带 surfaceOp）。
4. 插件侧仍是旧 dsh-session，validateSurfaceMetadata / foldSurface / wire 校验拒绝 system/message + surfaceOp → 抛出该错误。
5. 卸载插件后依赖子树没有被清理，profiles\web\node_modules 里的旧代闭包原地留存（pnpm-lock.yaml 的 importers 已经是空的，但目录还在，旁边还留着 npm 的 package-lock.json），于是即便插件已卸载，后续任何从 profile 目录解析 dsh-session 的代码仍会踩到旧副本。

为什么会出现"另装一份旧版"而不是复用 host 的：semver prerelease 规则。^0.1.3-alpha.2 只匹配 0.1.3-alpha.2 及之后同一 major.minor.patch 元组的预发布版本，不匹配 0.1.5-rc.2。所以按旧范围解析时只能下载旧的同代版本，形成新旧共存。

补充说明：机器上并不存在"多个 dsh 安装"。D:\Environments\nodejs 只是 nvm D:\Programs\nvm\v24.15.0 的 junction，指向同一个安装；真正多出来的只是 profile 目录里的那份插件依赖。

6. 解决方案

6.1 立即修复：清掉 profile 里的旧依赖残留

插件已经卸载（package.json / patch 里都没有引用了），node_modules 属可再生状态，直接删：

Remove-Item -Recurse -Force "$env:USERPROFILE\.dsh\profiles\web\node_modules"

若插件仍在使用，正确做法是让整棵树同代：先 dsh plugin --profile web prune（转发到 pnpm），或直接删掉 profile 的 node_modules 后重装插件。

6.2 验证修复

# 1) 只剩安装里那一份
Get-ChildItem -Path "$env:USERPROFILE\.dsh", "$(npm root -g)" -Recurse -Directory -Filter dsh-session -ErrorAction SilentlyContinue |
  Where-Object { $_.FullName -like "*@deepseek-ai*" } |
  ForEach-Object { "{0} => {1}" -f $_.FullName, (Get-Content "$($_.FullName)\package.json" -Raw | ConvertFrom-Json).version }

# 2) profile 目录现在解析到安装里那份（路径应为 <global node_modules>\@deepseek-ai\dsh\node_modules\...）
node -e "const r=require('module').createRequire('C:/Users/<you>/.dsh/profiles/web/x.js');console.log(r.resolve('@deepseek-ai/dsh-session/package.json'))"

# 3) 启动一次
dsh --profile web --no-open --port 8099

本次实测：清理后只剩一份 0.1.5-rc.2；profile 解析指向安装目录；dsh --profile web 启动正常，浏览器打开 UI 并切换 workspace，控制台 0 error。

6.3 日常更新顺序（避免复发）

1. 先升 host：npm i -g @deepseek-ai/dsh@<channel>（latest / next / alpha），重启 dsh。
2. 再更新插件；marketplace 弹出的 refused before installing / host-compatibility risks 是保护，不是 bug —— 出现就先去升 host。
3. 跨代更新（如 0.1.2 → 0.1.5）时清一次 profile 的 node_modules，不要让两代共存。
4. 收工后按 6.2 的第 1、2 条各验一次。
5. 排查入口固定：%USERPROFILE%\.dsh\profiles\<profile>\.dsh-market\log.ndjson。

附：一句话结论

system/message 是 0.1.5-alpha.1 起才进入 surface 的事件类型；当 profile 目录里残留着旧代 @deepseek-ai/dsh-session（本例 0.1.2-rc.1）时，插件会优先加载旧库，用旧规则校验新 host 写出的事件，于是抛出 not surface-eligible and cannot carry surfaceOp。删掉 %USERPROFILE%\.dsh\profiles\<profile>\node_modules 里的旧依赖闭包即可，之后保持 host 先于插件更新。