[Bug] pnpm dsh web 从源码启动时工具调用全线崩溃：tsx/esm 加载 TS 源码与插件加载编译产物导致 TOOL_RUNTIME_SCHEDULER Symbol 分裂 （Cannot read properties of undefined (reading 'prepare')）

[World-sudo]

🔍 问题摘要

从 monorepo 源码仓库使用 pnpm dsh web（内部执行 node --import tsx/esm apps/cli/src/bin.ts web）启动 DSH 时，会出现一条完整的故障链：

模块被加载成两份物理副本
    → TOOL_RUNTIME_SCHEDULER Symbol 分裂
    → ctx.tools[Symbol] 为 undefined
    → 首次工具调用崩溃：Cannot read properties of undefined (reading 'prepare')
    → 孤儿 tool_calls 残留，会话永久毒化
    → DeepSeek API 持续返回：tool calls need immediate results

核心诱因是 TOOL_RUNTIME_SCHEDULER 使用 module-local 的 Symbol() 定义：每个物理模块副本在求值时都会创建一个独立 Symbol 实例，描述字符串相同但引用不相等。只要 @deepseek-ai/dsh-tools 被解析到两个不同文件（例如主进程走 src/index.ts、插件走 lib/index.js），Agent Loop 用其中一份的 Symbol 去读 ctx.tools[...] 就必然得到 undefined。

---

🔄 复现步骤

1. git clone https://github.com/deepseek-ai/deepseek-harness.git
2. cd deepseek-harness && pnpm install && pnpm build
3. 让 @deepseek-ai/dsh-tools 出现两份物理副本（任选其一）：
   • 安装声明 @deepseek-ai/dsh-tools 为 dependencies 的第三方插件（pnpm 物化出第二份副本）；或
   • 任何绕过 tsconfig paths 的解析路径（原生 Node 解析 / 指向 lib/index.js 的插件）
4. 启动：pnpm dsh web
5. 新建会话，发送触发工具调用的消息（如 用 pwsh 执行 echo hello）
6. 首次工具调用立即崩溃：Cannot read properties of undefined (reading 'prepare')
7. 重新发送任意消息，得到：DeepSeek Messages tool calls need immediate results（会话已毒化）

---

🔬 根因分析

核心根因：同一包的两份物理副本 → 两个不同 Symbol

TOOL_RUNTIME_SCHEDULER 定义在 packages/core/tools/src/index.ts:463：

export const TOOL_RUNTIME_SCHEDULER: unique symbol = Symbol('@deepseek-ai/dsh-tools.scheduler')

Agent Loop 通过该 Symbol 读取 ToolRuntime（packages/core/agent-loop/src/tool-calls.ts:170）：

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

而 ToolRuntime 实例把调度器挂在同一个 Symbol 键上（packages/core/tools/src/index.ts:798）：

readonly [TOOL_RUNTIME_SCHEDULER]: ToolRuntimeScheduler = { ... }

两份副本的分工时：

角色	模块解析路径	加载方式
主进程（Agent Loop）	packages/core/tools/src/index.ts	tsx/esm 转译
插件（经 Node 常规解析）	packages/core/tools/lib/index.js	原生 Node

即使两个文件源码完全一致，Symbol() 也会各自创建一个实例。主进程用 TS 版 Symbol 读 ctx.tools[Symbol] 得到 undefined，访问 .prepare() 即崩溃。

可复现的验证证据

在同一个 Node 进程中先后加载两份副本（node --import tsx/esm）：

const src = await import('@deepseek-ai/dsh-tools')                                   // → src/index.ts
const lib = await import('file:///.../packages/core/tools/lib/index.js')             // → lib/index.js
console.log(src.TOOL_RUNTIME_SCHEDULER === lib.TOOL_RUNTIME_SCHEDULER)

状态	输出
修复前（Symbol()）	false
修复后（Symbol.for()）	true

并且修复后，用任一副本的 Symbol 去查另一副本注册的调度器都能命中（undefined → 正常对象），即崩溃点消除。

与已有讨论的区别

社区已有多个关于 prepare 崩溃的讨论（见文末引用），多数聚焦 pnpm 物化出第二份物理副本。本报告补充的是一份最小、可离线复现的判定脚本（上面的两行 import 对比），它不依赖安装第三方插件即可证明 Symbol 分裂是否存在，也可用于回归验证。

顺带一提：仓库自身的测试配置已经意识到这个风险——vitest.config.ts:18-19 明确注释 paths must win over package exports so built lib/ never loads a second module-singleton copy。本次修复把这个"靠解析配置规避"的约束，在类型层面不改变公开 API 的前提下收敛到符号本身。

---

🛠️ 建议修复方向

方案一：TOOL_RUNTIME_SCHEDULER 改用 Symbol.for()（根除 Symbol 分裂）

export const TOOL_RUNTIME_SCHEDULER: unique symbol = Symbol.for('@deepseek-ai/dsh-tools.scheduler') as typeof TOOL_RUNTIME_SCHEDULER

Symbol.for() 使用全局 Symbol 注册表，跨模块实例返回同一个 Symbol。即使两份副本同时被加载，两边也能通过同一个键访问 ToolRuntime。

关于 as typeof TOOL_RUNTIME_SCHEDULER：Symbol.for() 的返回类型是 symbol 而非 unique symbol，因此需要断言。这里断言回 typeof TOOL_RUNTIME_SCHEDULER 是刻意的——它保留了 unique symbol 类型，公开 API 的 .d.ts 输出与修复前逐字节相同（export declare const TOOL_RUNTIME_SCHEDULER: unique symbol 与 readonly [TOOL_RUNTIME_SCHEDULER]: ToolRuntimeScheduler 均不变），因此不会波及消费者或生成的 API 目录。该写法与仓库内既有惯例一致（vendor/cordis/src/utils.ts:60-72 的 Symbol.for('cordis.effect') as typeof Context.effect、packages/typert/protocol/src/owned-value.ts、packages/subagent/subagent/src/internal.ts）。

方案二：统一 pnpm dsh web 的模块解析路径

让 tsx/esm 的 resolve hook 强制将 @deepseek-ai/* 解析到同一份实现（src 或 lib），或改用 node apps/cli/lib/bin.js 作为默认入口。这治标——vitest.config.ts 已在用同样手段规避。

方案三：错误路径中闭合挂起的工具调用

在结束轮次的错误路径中，写入 turn/end 之前先闭合挂起的工具调用，复用 interruptedTurnClosers 的合成 tool/result 生成逻辑。

方案四：listArtifacts 对坏文件宽容

单个会话文件的 header 读取/校验失败应被逐文件捕获，记录警告并跳过，而不是让整个 list() 抛错。

---

🖥️ 环境信息

项	值
DSH 版本	0.1.6-alpha.2
Node.js	v24.18.0
pnpm	11.7.0
操作系统	Windows 11 (10.0.26200)
启动命令	pnpm dsh web → node --import tsx/esm apps/cli/src/bin.ts web
对照启动命令	node apps/cli/lib/bin.js web

---

✅ 本次验证结果

补丁改动为单文件单行（packages/core/tools/src/index.ts:463）。

检查项	命令 / 方式	结果
类型检查（含全仓依赖图）	tsc -b --force packages/core/tools/tsconfig.json	✅ 通过（exit 0，无错误）
公开 API 类型是否变化	对比 lib/types/index.d.ts 声明	✅ 逐字节相同（仍为 unique symbol）
工具调用调度器单测	vitest run packages/core/agent-loop/tests/tool-calls.spec.ts	✅ 21/21 通过
源码启动路径端到端工具调用	pnpm dsh --profile headless "用 pwsh 执行 echo hello"	✅ 实际执行，输出 hello（exit 0）
编译产物启动路径端到端工具调用	node apps/cli/lib/bin.js --profile headless "用 pwsh 执行 echo hello"	✅ 实际执行，输出 hello（exit 0）
崩溃场景（两份副本）是否消除	同进程加载 src 与 lib 两份副本比对 Symbol	✅ 由 false 变为 true

需要说明的是：GUI（浏览器）内的逐次点击验证本次未执行，上表两条端到端结果是在 headless profile 下、经真实模型与真实工具执行取得的，与 pnpm dsh web 共用同一条工具调用与调度器代码路径。

---

🔗 参考修复分支

已在 fork 中验证 Symbol.for() 方案可修复此问题：

• Fork 分支：https://github.com/World-sudo/deepseek-harness/tree/fix/symbol-for-tool-scheduler
• Commit：9b11327538
• 补丁文件：见下方代码块

补丁文件

From 9b11327538587304f3dc6925e74e686cda02d19d Mon Sep 17 00:00:00 2001
From: Always <180764030+World-sudo@users.noreply.github.com>
Date: Fri, 18 Sep 2026 21:32:27 +0800
Subject: [PATCH] fix(tools): use Symbol.for() for TOOL_RUNTIME_SCHEDULER to
 survive module duplication

The TOOL_RUNTIME_SCHEDULER symbol is a module-local Symbol, which creates
a separate instance for each physical module copy. When running from source
with tsx/esm, the main process loads packages/core/tools/src/index.ts while
plugins load packages/core/tools/lib/index.js, causing ctx.tools[Symbol]
to be undefined and crashing on .prepare().

Using Symbol.for() registers the symbol in the global registry, ensuring
both the main process and plugins access the same symbol instance even
when loaded from different physical files.

Verified with:
- pnpm dsh web (tsx entry)
- node apps/cli/lib/bin.js web (compiled entry)
Both now execute tool calls correctly.
---
 packages/core/tools/src/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index 6be7be61e2..951c413a4d 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -460,7 +460,7 @@ export interface ToolRuntimeScheduler {
  * Scheduler entry point omitted from the generated named service API.
  * @internal
  */
-export const TOOL_RUNTIME_SCHEDULER: unique symbol = Symbol('@deepseek-ai/dsh-tools.scheduler')
+export const TOOL_RUNTIME_SCHEDULER: unique symbol = Symbol.for('@deepseek-ai/dsh-tools.scheduler') as typeof TOOL_RUNTIME_SCHEDULER
 
 /** Canonical error code for cancellation after a tool body was invoked. */
 export const TOOL_ABORTED = 'ABORTED'
-- 
2.50.1.windows.1

如维护者需要采纳，可 cherry-pick 该 commit 或应用补丁文件。

---

📎 相关讨论引用

编号	关联点
#2078	Symbol.for 一行修复方案：重复副本下的 Symbol 键不匹配
#4667	prepare 崩溃在工具派发时发生（ctx.tools 存在但 Symbol 槽为 undefined）
#2660	安装声明 @deepseek-ai/dsh-tools 为 dependencies 的插件后所有工具调用崩溃（模块双实例）
#3708	工具调用污染问题全貌
#2661	调度器错误残留孤儿 tool_calls，现有 interruptedTurnClosers 覆盖不到
#1473	单个损坏会话文件阻止 dsh web 启动
#2590	单个损坏会话文件导致宿主进程崩溃循环，zstd 帧布局未文档化
#5514	dsh-messages-sanitizer：自动修复孤立 tool_calls

[World-sudo]

此项目由deepseekv4.1修复（莫名喜感），经测试可以正常运行，启动命令：node apps\cli\lib\bin.js web （！！此为临时解决方案！！）

[cheesecake4392]

你这问题我也遇到了，今天整了3个多小时才解决......