[dsh] profile 内出现第二份核心包 → Symbol/instanceof 跨实例失效 → 工具派发崩溃（reading 'prepare'）

[skppao1415]

dsh 0.1.5-rc.2：profile 内出现第二份核心包 → Symbol/instanceof 跨实例失效 → 工具派发崩溃（Cannot read properties of undefined (reading 'prepare')）

English: When a profile's node_modules contains a second physical copy of @deepseek-ai/dsh-tools (anything that triggers pnpm install in the profile, e.g. the plugin manager UI, does this), module-private Symbols no longer match across copies. ctx.tools[TOOL_RUNTIME_SCHEDULER] becomes undefined, and every tool call dies with Cannot read properties of undefined (reading 'prepare') — an error message that points nowhere near the real cause.

环境

• @deepseek-ai/dsh 0.1.5-rc.2（npm 全局安装，Node v26.7.0，Linux）
• profile web，挂载若干第三方 bundle 与本地插件（含官方插件管理 UI dsh-web-plugin-manager）
• profile 的 pnpm-workspace.yaml 使用 nodeLinker: hoisted，且 profiles/web/package.json 显式声明了若干 @deepseek-ai/* 核心包

复现步骤

1. 让 profile 树里出现 harness 核心包的第二份实体（本机实测：在 profile 里执行一次 pnpm install 即可，例如通过插件管理 UI 安装/升级插件）：

   ~/.dsh/profiles/web/node_modules/@deepseek-ai/dsh-tools/     ← 实体副本 B（pnpm 创建）
   <dsh 安装目录>/node_modules/@deepseek-ai/dsh-tools/          ← harness 副本 A
   

2. 在 web profile 里发起一轮对话并触发任意工具调用（例如 bash）。

实际结果

会话事件（~/.dsh/sessions/<cwd>/session-<id>/session.v3.jsonl.zstd）：

{"type":"tool/call","name":"bash","arguments":"{\"command\":\"ls -la ~/.dsh/\"}"}
{"type":"turn/end","data":{"turn":3,"reason":{"kind":"error",
  "error":{"message":"Cannot read properties of undefined (reading 'prepare')","code":"UNKNOWN"}}}}

模型回复与工具调用都正常生成，只在这一步崩。同一个 harness 用 dsh --profile headless 跑同样的 bash 工具正常，说明不是工具本身的问题。

根因

1. @deepseek-ai/dsh-tools/lib/index.js:2430：

   TOOL_RUNTIME_SCHEDULER = Symbol('@deepseek-ai/dsh-tools.scheduler')
   // 注释：Scheduler entry point omitted from the generated named service API

2. @deepseek-ai/dsh-agent-loop/lib/index.js:588：

   const prepared = await ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec);

3. Symbol() 是模块实例私有的。profile 内的第三方插件 import '@deepseek-ai/dsh-tools' 解析到副本 B，harness 解析到副本 A：

   $ node -e "…同时 import 两份副本，比较导出的 Symbol 与类…"
   两个 Symbol 是否同一个: false
   ToolRuntime 类是否同一个: false
   
   require.resolve('@deepseek-ai/dsh-tools', {paths:['~/.dsh/profiles/web/node_modules/<第三方插件>/lib']})
     → ~/.dsh/profiles/web/node_modules/@deepseek-ai/dsh-tools/lib/index.js        (B)
   harness（dsh-agent-loop）
     → <dsh>/node_modules/@deepseek-ai/dsh-tools/lib/index.js                        (A)
   

   于是 A 侧构造的 ctx.tools 上永远查不到 A 的 Symbol → undefined.prepare。

4. 受影响的不止这一个 Symbol：ToolRuntime 等类的 instanceof 同样跨实例失效（实测两份类不相等）。凡"对象跨插件/harness 边界传递 + 用 Symbol/instanceof 判定"的地方都会出问题。

说明：web app 只把错误 message/code 存进会话事件，拿不到调用栈；但模块实例分裂与解析路径已用上面两条命令直接证实，且在把副本归一后符号层面恢复一致。

期望行为（任一即可）

1. 统一模块实例：profile 内插件解析 @deepseek-ai/* 核心包时应解析到与 harness 完全相同的那一份（例如走 .dsh-module-fallback 机制，或安装时以 peer + 符号链接处理，而不是复制实体）；
2. 或对这类跨实例 API 使用 Symbol.for('@deepseek-ai/dsh-tools.scheduler')／全局注册表，使跨实例也能命中；
3. 最低限度：ctx.tools[TOOL_RUNTIME_SCHEDULER] 缺失时应抛明确错误（如 "tools service comes from a different @deepseek-ai/dsh-tools instance"），而不是让 undefined.prepare 掩盖真因——目前这个字符串在任何日志里都不出现，用户完全无从下手。

用户侧规避（本机已把符号层面验证通过）

把 profile 里与 harness 同名的核心包换成指向 harness 的符号链接（@deepseek-ai/dsh-tools、dsh-session、dsh-llm、cordis、schemastery 等 13 个），保留 harness 里没有的客户端包（dsh-client-ui-primitives、dsh-client-ui-slots）。之后：

两个 Symbol 是否同一个: true
ToolRuntime 类是否同一个: true

注意：任何一次 pnpm install（含插件管理 UI）都会把实体副本装回来，问题复发。

[skppao1415]

更新：端到端验证通过（2026-09-12）

Hi maintainers — an end-to-end confirmation of the instance split, plus a browser-free repro recipe that may be useful for your own e2e tests.

方式：起一个 dsh web（web profile 全量插件 + 修复后的 node_modules），用 HTTP API 直接驱动一次真实回合：POST /api/session/create → POST /api/session/prompt，全程不经过浏览器。

结果（修复后）：

16:53:47  tool/call    bash {"command":"echo dsh-tool-ok","description":"Echo test string"}
16:53:48  tool/result  "dsh-tool-ok\n"    isError=false
16:53:49  turn/end     {"kind":"completed"}

对比修复前（同一路径）：

tool/call  bash ...
turn/end   {"kind":"error","error":{"message":"Cannot read properties of undefined (reading 'prepare')","code":"UNKNOWN"}}

静态证据：对 web profile 的 795 个解析基点（profiles/*/node_modules 下所有包 + 本地插件 + 自定义 preset）逐个解析核心包，@deepseek-ai/dsh-tools、@deepseek-ai/dsh-session、@deepseek-ai/dsh-llm、@deepseek-ai/cordis 各只剩 1 个物理实体（790 个基点全部命中 harness 安装目录里的同一个文件），Symbol 与 ToolRuntime 类在两半之间必然同源。

无浏览器复现脚本

BASE=http://127.0.0.1:3080

# ① 用启动日志里的 token 换签名 cookie（303 + Set-Cookie）
curl -s -c /tmp/jar.txt "$BASE/?token=<LAUNCH_TOKEN>"

# ② 建会话
curl -s -b /tmp/jar.txt -X POST "$BASE/api/session/create" -H 'content-type: application/json' \
  -d '{"type":"client-request","rpcId":"11111111-1111-4111-8111-111111111111","method":"session/create",
       "payload":{"args":{"request":{"cwd":"/tmp/probe","agentPreset":"standard"}}}}'

# ③ 发消息，触发一次真实工具调用
curl -s -b /tmp/jar.txt -X POST "$BASE/api/session/prompt" -H 'content-type: application/json' \
  -d '{"type":"client-request","rpcId":"33333333-3333-4333-8333-333333333333","method":"session/prompt",
       "payload":{"args":{"request":{"requestId":"44444444-4444-4444-8444-444444444444",
       "sessionId":"<SESSION_ID>","mode":"queue",
       "content":[{"type":"text","text":"请用 bash 工具执行：echo dsh-tool-ok"}]}}}}'

顺带的文档小坑：一元 Remote 调用似乎只能走路径形式 POST /api/<namespace>/<method>；把端点写在包体的 method 字段里 POST /api 会得到 404 not found（ClientRequest.method 目前只在路径形式下被校验）。

[skppao1415]

补充：这些实体副本从哪来（以及上游文档中对应的规则）

本机时间线：

时间	事件
09-12 12:49	升级 dsh 到 0.1.5-rc.2
09-12 14:20	profile 内发生一次 pnpm install（profiles/web/package.json 与 pnpm-lock.yaml 在同一秒被重写；插件管理 UI 的安装流程会触发它）
—	之后 profiles/web/node_modules/@deepseek-ai/ 下出现实体目录（dsh-tools、dsh-session、dsh-llm、cordis …），与 harness 安装目录里的同名包构成两份物理实体
09-12 16:07	出现本报告描述的工具派发崩溃

@deepseek-ai/dsh-app-boot 关于 profile 模块回退的文档（README.md §Design notes）写着：

A selected external bundle absent from the installation closure receives a profile-local .dsh-module-fallback link; existing pnpm entries win, projected links are excluded from later closure discovery, and cleanup removes only dsh-owned links.

即 fallback 不会覆盖已存在的 pnpm 条目。因此只要在 profile 里跑过一次 pnpm install，这些实体副本就会永久留下（而对 harness 自身包来说，它们本应来自 installation closure），从而命中跨实例问题。

可能的修复落点：

1. 属于 installation closure 的核心包（@deepseek-ai/*）不应被 profile 内的 pnpm 条目遮蔽；
2. 或对这类跨实例 API 使用 Symbol.for('@deepseek-ai/dsh-tools.scheduler') / 全局注册表；
3. 至少应在 boot 阶段检测"同一个包解析出多个实体"并 fail loud —— 现在只有 dsh-client-modules 在 client 侧检查 resolves from multiple active Loader sources，host 侧（工具派发）没有任何检查，最终表现为 undefined.prepare。

[PerryLink]

我把你指的三处代码逐一对照了宿主源码，三条都成立，另外补两条你可能还没看到的。

1. 逐条核实

你的引用	源码实况
dsh-tools/lib/index.js:2430 用 Symbol('@deepseek-ai/dsh-tools.scheduler')	packages/core/tools/src/index.ts:459：export const TOOL_RUNTIME_SCHEDULER: unique symbol = Symbol('@deepseek-ai/dsh-tools.scheduler') —— 是 Symbol()，不是 Symbol.for()	✅
dsh-agent-loop/lib/index.js:588 无保护取用	packages/core/agent-loop/src/tool-calls.ts:170：const prepared = await ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec)	✅
受影响的不止一处	同文件 :153 finalize、:154 finish 也是裸取用，同一个 undefined 同样会在那里抛	✅ 补充
注册侧	packages/core/tools/src/index.ts:789：readonly [TOOL_RUNTIME_SCHEDULER]: ToolRuntimeScheduler = {	✅

2. 你观察到的「每次 pnpm install 就把副本装回来」有明确的设计条款

这一条让整份报告从「推测」变成「可解释」。宿主确实有模块后备机制，但它的优先级写在 packages/boot/app-boot/src/profile.ts:535-543：

Missing packages carried only by selected bundles are linked through a profile-owned directory into that profile's node_modules; pnpm-managed entries remain authoritative, and another profile's links cannot change its resolution.

以及 packages/boot/app-boot/README.md:89：

A selected external bundle absent from the installation closure receives a profile-local .dsh-module-fallback link; existing pnpm entries win.

⇒ 后备链接只在「安装闭包没有这个包」时才生效。而插件管理 UI 触发的那次 pnpm install 让 profile 的 node_modules 里出现了真实条目，existing pnpm entries win 就把它保留了 —— 于是实体副本 B 出现，Symbol() 的模块实例私有性立刻变成可观察的失效。你「手动换成符号链接、但任何一次 pnpm install 都会复发」的描述与这条完全吻合。

所以你的期望 1（统一模块实例）不是「加个机制」，而是调整这条已存在的优先级规则（让 dsh 自有核心包在 profile 内也解析到安装的那一份），代价是需要判断哪些包可以安全地这么做。

3. 关于你给的三条期望

• 第 3 条（缺失时抛明确错误，如 "tools service comes from a different @deepseek-ai/dsh-tools instance"）成本最低、无兼容风险，而且收益直接：现在这个字符串在任何日志里都不出现，用户完全无从下手 —— 你的报告本身就是这条必要性的证据。
• 第 2 条（Symbol.for）要注意它改变的是全仓该符号的身份语义：Symbol.for 走全局注册表，任何加载到同一 realm 的副本都会命中同一个 key。这既是修法也是风险面，值得单独权衡。
• 第 1 条影响面最大（关系到模块解析与 peer 语义）。

4. 我没能核实的部分

我只能核实代码路径与后备机制的设计条款 —— 你本机那两份实体副本（A/B）以及 require.resolve 的两条输出，我无法复现。上面第 2 节是与你的观察一致的机制解释，不是我对你机器的独立测量。若要把它推到「已确证的上游缺陷」，最有说服力的一步是给一个最小复现：空 profile → 触发一次插件安装（产生实体副本）→ 一次工具调用，把 Symbol 比较与 require.resolve 输出一并贴出。你这个 case 已经离得很近了。

（本次核对基于 0.1.5-rc.2 的源码。）

[skppao1415]

谢谢核对，你补的两处都对：agent-loop/lib/index.js 的 :576 finalize/finish、:588 prepare、:592 dispatch 是同一形态；dsh-tools/lib/index.js:2578 那里它就是个实例字段，四处刚好一一对上。

最小复现跑了（隔离 DSH_HOME，没动现有环境；profile 里一次安装 → 一次 bash 调用）。同一环境只改「有没有副本」这一项：

13 个副本在场 → turn/end error："Cannot read properties of undefined (reading 'prepare')"
换成符号链接 → tool/result isError=false（'dsh-tool-ok\n'），turn/end completed

底层也对上了：

Symbol 同一性 harness vs 副本 : false（归一化后 true）；ToolRuntime 类同一性 : false
harness 侧 Symbol → object，副本侧 Symbol → undefined
require.resolve:
  …/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-tools/lib/index.js
  /tmp/dsh-repro-home/profiles/web/node_modules/@deepseek-ai/dsh-tools/lib/index.js
pnpm 同一 manifest：hoisted 出实体目录、isolated 出 .pnpm 符号链接；全新 profile 一次 install 就出 15 个实体目录

顺带一提：触发条件不只是用户手跑 pnpm —— dsh plugin --profile <p> add <pkg> 这条官方安装路径自己就会跑 pnpm install，配上你引的 profile.ts:535-543，等于每次装插件都可能把副本带回来，派发侧完全不检查。fail-loud 在这里不只是报错清楚一点，而是能拦住「装个插件把工具系统静默打坏」。

优先级我同意你的排法。复现脚本如果需要的话我可以贴出来

[PerryLink]

两点都复核过, 你的补充成立, 而且它把触发面显著扩大了.

1. dsh plugin --profile <p> add <pkg> 确实自己跑 pnpm: apps/cli/src/args.ts:190-201 把 plugin 命令定义为"剩余参数原样转发给 profile 目录内的 pnpm", apps/cli/src/plugin.ts:134-138 用 spawnSync('pnpm', args, { cwd: profileDir }) 执行. 所以每 add 一次 = 在 profile 里完整 install 一次, 不依赖用户手动跑 pnpm. 你引的 profile.ts:535-543 在当前 master 逐字命中(healProfilesModuleFallback 的注释段, "pnpm-managed entries remain authoritative"), 不是旧版行号; 该规则落地代码在 profile.ts:258-268(条目已存在即保留) 与 :611-645(后备闭包只补安装闭包缺失的包).

2. 于是触发面 = 官方 add/update 命令 + 你观察到的插件管理 UI 安装流程 + 手动 install, 而不只是手动 pnpm. 派发侧确实完全不检查: 全仓 "resolves from multiple active Loader sources" 只出现在 client 侧(packages/client/modules/src/index.ts:924), host 侧没有同类检测. 附带一点: 后备机制本意是共享单一 cordis 实例(profile.ts:145-148 注释), 而"pnpm 条目获胜"这条优先级在官方 install 路径存在的前提下, 恰好给设计意图留了个口子.

3. 根因仍是之前答过的两条: TOOL_RUNTIME_SCHEDULER 是模块私有 Symbol(packages/core/tools/src/index.ts:459, Symbol() 非 Symbol.for), 两份物理副本间必然不同一; agent-loop 四处裸取 ctx.tools[TOOL_RUNTIME_SCHEDULER](packages/core/agent-loop/src/tool-calls.ts:153 finalize / :154 finish / :170 prepare / :174 dispatch), 副本在场即 undefined.prepare. 触发面扩大后, 你的 fail-loud(或统一解析)建议的优先级应该再往前提.