[Bug] 所有工具调用都报 "Cannot read properties of undefined (reading 'prepare')" — ToolRuntime 调度器未注册（rc.6）

[Jaffett]

分类: Bug 反馈
dsh 版本: 0.1.0-rc.6（全新安装：先清空 npm 缓存再 npx @deepseek-ai/dsh web）
Node: v22.22.3 / npm 10.9.8
系统: WSL2（Ubuntu / Linux），process.platform === 'linux'
可在以下环境稳定复现: 完全干净安装、默认 web profile、默认 standard 预设、patch 配置为空

---

问题概述

所有面向模型的工具调用（bash、jobs、fs、web、todo、subagent、ralph、workflow——全部）都能被模型正确选中，但一执行就崩溃：

Cannot read properties of undefined (reading 'prepare')

工具已注册、模型能看到（它会用正确参数调用 bash），但 agent 循环执行时 tools 服务上的调度器（scheduler）是 undefined。在无任何自定义插件的全新安装上即可复现。

复现步骤

1. npx @deepseek-ai/dsh web（全新安装）
2. 打开 http://127.0.0.1:3080，新建会话（工作区如 /tmp）
3. 发送：运行 bash echo hello（或任何会触发工具调用的消息）
4. 模型返回 bash 工具调用：{"command": "echo hello", ...}
5. 工具行显示已停止，本轮以 本轮运行失败 Cannot read properties of undefined (reading 'prepare') 结束
6. 轨迹页显示：bash {...} → interrupted

观察到的现象

• 模型能看到完整工具目录并正确调用工具。
• 所有工具失败方式完全一致——bash、jobs、fs、web、todo、subagent、workflow 全是 undefined.prepare。
• 插件清单（设置 → 插件 → 插件列表）显示所有 tool-* 条目在进程级为已停用，但它们的底层服务（bash-sandbox、jobs-local、subprocess-local、fs-sandbox、system-prompt、tools）都是已挂载、已启用。
• pwsh-sandbox 在 Linux 上显示停用是正常的（预期行为）。

根因分析（源码级）

Agent 循环通过 tools 服务调用调度器：

@deepseek-ai/dsh-agent-loop/lib/index.js:193

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

ctx.tools 能解析，但 ctx.tools[TOOL_RUNTIME_SCHEDULER] 是 undefined → 抛 undefined.prepare。

调度器是 ToolRuntime 服务的类字段：

@deepseek-ai/dsh-tools/lib/index.js:2557

[TOOL_RUNTIME_SCHEDULER] = {
    prepare: (exec) => this.prepareScheduledExecution(exec),
    dispatch: (exec) => this.dispatchScheduledExecution(exec),
    finalize: (exec, result) => this.finalizeScheduledExecution(exec, result),
    finish: (exec, result) => this.finishScheduledExecution(exec, result)
};

服务以 tools 名注册（dsh-tools/lib/index.js:2585 super(ctx, "tools")）。

如果 ToolRuntime 被实例化，ctx.tools[TOOL_RUNTIME_SCHEDULER] 必然有值。它是 undefined 而 ctx.tools 又能解析，说明 ToolRuntime 在 agent/会话域从未被实例化——但 tools 这个名字却能解析到（否则报错会是 "ctx.tools is undefined"）。

ToolRuntime 声明 static inject = ["systemPrompt"]（dsh-tools/lib/index.js:2547）。systemPrompt 服务（@deepseek-ai/dsh-system-prompt，lib/index.js:162 super(ctx, "systemPrompt")）在清单中显示已挂载/已启用。我们的推测：在会话域中 systemPrompt 注入未成功解析（或作用域/顺序问题阻止了 ToolRuntime 实例化），导致循环拿到一个没有调度器字段的残缺 tools 服务——这与清单中所有 tool-* 显示停用而宿主服务启用的情况一致。

我们试过的方法（均无效）

1. 全新安装 — rm -rf ~/.npm/_npx/* 后 npx @deepseek-ai/dsh web → 依旧崩溃。
2. 默认 standard 预设不动、cordis.patch.yml 清空 → 依旧崩溃。
3. 换不同工作区（/tmp 等）→ 依旧崩溃。
4. 新建会话 vs 恢复会话 → 两种都崩。
5. 在 profile 里安装 @deepseek-ai/dsh-tool-ralph → 引发别的错误（恢复会话时 tool-ralph: waiting for workflows，之后又出现 duplicate loader entry id: tool-ralph）；卸载并恢复默认后 undefined.prepare 依旧存在。
6. 自定义插件（dsh-plan-debate）注入 "workflowEngine" → 报 pending (waiting for service: workflowEngine)。@deepseek-ai/dsh-workflow 通过 super(ctx, "workflowEngine")（dsh-workflow/lib/index.js:61）提供服务，但只在预设的隔离 delegation 域内——挂载在根域的消费者无法解析到它。可能与工具插件的域/注入作用域问题同源。

给维护者的额外发现

• ralph 包版本不一致：npm 上 @deepseek-ai/dsh-tool-ralph 的 latest 是 0.0.1-rc.1，但 dsh@0.1.0-rc.6 内置的是 0.1.0-rc.6。用户单独安装会拿到错误的（更旧的）版本——我们最初就是这么中招的。
• 插件清单"进程级停用"与"会话级启用"的区分容易误导——要么在清单中反映真实会话激活状态，要么在 UI 上说明进程级停用是预期的。

预期行为

• 工具调用正常执行（bash 能跑、结果返回、回合正常结束）。
• 插件清单反映真实的会话级激活状态，或明确说明进程级"停用"是预期的。

非常乐意提供日志 / 会话 JSONL / 配合跑诊断。感谢这个 harness，期待 rc.7！🙌

[argszero]

先给结论：你的复现质量很高，但机制结论需要修正——源码证据不支持"ToolRuntime 未被实例化 / systemPrompt 注入失败导致残缺 tools 服务"的假设；这个报错更可能是我们已知家族的第四次报告（#1337、#1633、#1665 同签名），而干净安装能复现恰恰说明这次是发布打包层面的变体。

1. 源码证据：ctx.tools 能解析 ⇒ 它必然是 ToolRuntime 实例

• 全仓只有一处 super(ctx, 'tools')（packages/core/tools/src/index.ts:827）——没有第二个服务用 'tools' 名字注册，不存在"残缺 tools 服务"。
• 调度器是类字段初始化器（:796 readonly [TOOL_RUNTIME_SCHEDULER]: ToolRuntimeScheduler = {...}）——只要 ToolRuntime 被构造，字段必然存在，与 systemPrompt 注入无关。
• 所以 ctx.tools 解析成功 + ctx.tools[TOOL_RUNTIME_SCHEDULER] 为 undefined 只剩一种机制：ctx.tools 是另一份物理拷贝的 dsh-tools 构造的实例。TOOL_RUNTIME_SCHEDULER 是 unique symbol（tools/src/index.ts:466），每份拷贝在磁盘上求值都得到不同的 Symbol 实例——agent-loop 用自己拷贝的 Symbol 去索引外来拷贝实例的字段 → undefined → undefined.prepare。

2. 干净安装为什么会有两份拷贝（打包层面，已核实）

• npm 上 @deepseek-ai/dsh-base@0.1.0-rc.6 把 @deepseek-ai/dsh-tools 声明为普通 dependency（^0.1.0-rc.6），而所有 tool-* 插件把它声明为 peerDependency。npm 7+ 自动安装 peer，且 npm 的 hoisting 是路径相关的——同一版本也可能在顶层和嵌套位置各出现一次（node_modules/@deepseek-ai/dsh-tools 与 node_modules/<某包>/node_modules/@deepseek-ai/dsh-tools）。agent-loop（应用闭包）与 tool 插件条目（loader 解析）若分别命中两个路径 → 两个 Symbol。
• npm 上还存在旧行 0.0.1-rc.5 的 dsh-tools，旧行插件（如 dsh-tool-bash@0.0.1-rc.5）peer 它。任何装到旧行插件的 profile 都会得到第二份拷贝——这正是你发现的 ralph 版本不一致（npm latest 0.0.1-rc.1 vs 内置 0.1.0-rc.6）的同一根源。
• 补充：本地 master（rc.5 时代）的 loadProfile/resolveBundleDir（app-boot/src/profile.ts:344-359）是"安装锚优先"解析，理论上干净安装单拷贝；rc.6 的实际安装树是否出现两拷贝需要现场确认。

3. 决定性诊断（请在 rc.6 机器上跑，30 秒定位）

# 找到应用闭包里的 dsh-tools 拷贝数
find ~/.npm/_npx -type d -name dsh-tools 2>/dev/null
# 在 profile 目录看 dsh-tools 是否是符号链接、指向哪
ls -la ~/.dsh/profiles/web/node_modules/@deepseek-ai/ | grep dsh-tools

# 关键：两个解析点是否命中同一物理文件
node -e "
const path=require('path');
const fs=require('fs');
const fromLoop=require.resolve('@deepseek-ai/dsh-tools',{paths:[path.dirname(require.resolve('@deepseek-ai/dsh-agent-loop/package.json'))]});
const fromBash=require.resolve('@deepseek-ai/dsh-tools',{paths:[path.dirname(require.resolve('@deepseek-ai/dsh-tool-bash/package.json'))]});
console.log('loop ->', fromLoop);
console.log('bash ->', fromBash);
console.log('same path:', fromLoop===fromBash, '| same realpath:', fs.realpathSync(fromLoop)===fs.realpathSync(fromBash));
"

若两个 realpath 不同 → 两拷贝实锤，机制确认。若相同 → 排除拷贝机制，我再帮你从 loader 的条目解析顺序查（那就要看 rc.6 实际发布树了）。

4. 你观察里另两个点

• "插件清单 tool-* 进程级停用但服务已挂载"：这是 inventory 的会话级挂载误报——工具条目是在会话作用域挂载的，进程级清单看不到。你观察到模型能看到全部工具，恰恰证明它们都在运行，不是停用。
• workflowEngine 只在预设隔离的 delegation 域内、根域消费者 pending：这是一个独立且真实的作用域隔离 bug，与工具崩溃无关，建议单独开一帖（值得维护者单独修）。

5. 家族连接 + 修复方向

四次报告（#1337 Windows+插件、#1633 Windows+插件、#1665 Windows、#1677 干净安装）同签名。两个既有 PR 蓝图（apps/cli/src/plugin.ts reconcile 加核心包名单臂拦截顶层 dsh-tools/cordis 依赖；tool-calls.ts:169 加防御检查 + 合成 tool result 收尾）之外，这次新增第三条：打包侧修正——dsh-base 的 dsh-tools 依赖改为 peer（与 tool 插件一致），并审计 npm 发布图里是否残留旧行 0.0.1-rc.5 引用。请把诊断输出贴回来，如果确认两拷贝，我可以在帖子里把打包修复写成可直接提交的 diff 草案。

[Jaffett]

感谢 @argszero 的机制分析，诊断已在 rc.6 机器上跑完，确认两拷贝（实为三份）：

诊断输出

=== 1. dsh-tools 拷贝数 ===
~/.npm/_npx/<npx-cache-id>/node_modules/@deepseek-ai/dsh-tools
~/.dsh/profiles/web/node_modules/@deepseek-ai/dsh-tools      ← profile 独立拷贝
~/.hermes/node/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-tools  ← 全局 dsh 内嵌

=== 2. profile 里 dsh-tools ===
drwxrwxr-x 3 <user> <user> 4096 Aug 15 10:11 dsh-tools     ← 真实目录，非软链

=== 3. Symbol 对比（关键） ===
profile TOOL_RUNTIME_SCHEDULER: Symbol(@deepseek-ai/dsh-tools.scheduler)
npx     TOOL_RUNTIME_SCHEDULER: Symbol(@deepseek-ai/dsh-tools.scheduler)
global  TOOL_RUNTIME_SCHEDULER: Symbol(@deepseek-ai/dsh-tools.scheduler)

profile === npx:   false
profile === global: false
npx === global:    false

三个物理拷贝，三个不同的 unique Symbol —— 完全符合你的机制判断：agent-loop 用 npx 拷贝的 Symbol 索引 profile 拷贝构造的 tools 实例 → undefined → undefined.prepare。

干净安装为什么会有第二份拷贝（本次现场确认）

干净安装确实只有 npx 缓存一份（上面 find 只有一个），但我们 profile 里装了一个自定义插件 dsh-plan-debate，它的 package.json 把 @deepseek-ai/dsh-tools 声明为普通 dependency（"^0.1.0-rc.6"），pnpm 因此在 profile 里独立 materialize 了第二份 dsh-tools（0.1.0-rc.6，非软链）。

注意：之前那份"完全干净、零 patch、零自定义插件"的复现报告可能不准确——我们最初的复现环境其实带着这个自定义插件。所以更精确的结论是：任何在 profile 里以普通 dependency 引入 dsh-tools 的插件都会触发（tool 插件用 peer 是对的，第三方插件容易踩这个坑）。

另外全局还装了一份 dsh（~/.hermes/node/lib/node_modules/@deepseek-ai/dsh，rc.6），如果用户 PATH 里有全局 dsh 也会引入第三份。

修复方向（呼应你提的第三条）

打包侧修正（dsh-base 改 peer）能解决官方包带来的拷贝；但第三方插件以普通 dependency 声明 dsh-tools 时仍会触发。建议在 tool-calls.ts:169 的防御检查之外，loader 侧可以考虑对 @deepseek-ai/dsh-tools / @deepseek-ai/cordis 做 single-instance 强制（或用真实路径而非 Symbol 判断）。

如果需要我们贴 session JSONL 或任何其他信息，随时说。再次感谢快速响应！

[Electricitysheep]

ToolRuntime 调度器未注册——和 #1515/#783 是同一族（dsh-tools 相关：插件安装/依赖解析后工具调度器状态异常）。

排查：确认 dsh-tools 只存在一份（无二次 materialize），必要时清 npm 缓存重装。完整机制见第 3 章：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/03-profiles.md

[Shizuku-keop]

补充一条来自社区整理的打包侧修复建议（与上方三拷贝诊断对应）：

根因（打包层面）

• npm 上 @deepseek-ai/dsh-base 将 @deepseek-ai/dsh-tools 声明为普通 dependency（^0.1.0-rc.6）；
• 而所有 tool-* 插件把它声明为 peerDependency；
• npm 7+ 的 peer 自动安装 + 路径相关 hoisting → 同一版本可能在顶层与嵌套位置各出现一次 → 两份 TOOL_RUNTIME_SCHEDULER unique Symbol → agent-loop 用自己拷贝的 Symbol 索引外来实例字段 → undefined.prepare。

建议修复方向（三条可选，可叠加）

1. 打包侧（治本）：dsh-base 的 dsh-tools 依赖改为 peerDependency（与 tool 插件一致），并审计 npm 发布图是否残留旧行 0.0.1-rc.5 引用；
2. cli 侧：apps/cli/src/plugin.ts reconcile 加核心包名单，臂拦截顶层重复的 dsh-tools/cordis 依赖；
3. 防御侧：tool-calls.ts 的调度器调用加防御检查 + 合成 tool result 收尾，避免裸 undefined.prepare 崩溃。

如果需要，社区可以把第 1 条（dsh-base package.json 依赖声明）整理成可直接合并的 PR。

[Shizuku-keop]

补充：第 1 条修复（dsh-base 的 dsh-tools 依赖改 peer）已整理为可合并的 commit，供维护者直接取用（本仓库禁用了 PR 功能，故以分支形式提供）：

• 分支：https://github.com/Shizuku-keop/deepseek-harness/tree/fix/dsh-base-dsh-tools-peer
• Commit：72cac94 — ix(dsh-base): declare @deepseek-ai/dsh-tools as peerDependency to avoid duplicate copies of the TOOL_RUNTIME_SCHEDULER symbol`n- 改动：packages/bundle/base/package.json — 将 @deepseek-ai/dsh-tools 从 dependencies 移入 peerDependencies（与所有 tool-* 插件声明方式对齐）

如采纳，直接 cherry-pick 或合并该分支即可。

[Shizuku-keop]

@argszero @Electricitysheep 您好，关于本贴的 undefined.prepare 问题，社区已将打包侧修复整理为可直接合并的 commit，正式请求官方采纳：

修复内容

将 packages/bundle/base/package.json 中的 @deepseek-ai/dsh-tools 从 dependencies 移入 peerDependencies（与所有 tool-* 插件声明方式对齐），避免 npm 安装时出现两份 TOOL_RUNTIME_SCHEDULER unique Symbol。

取用方式（任选其一）

• 分支：https://github.com/Shizuku-keop/deepseek-harness/tree/fix/dsh-base-dsh-tools-peer
• commit：72cac94a09f5448037c478fe08b8adc5d42043b6
• fork master：41d6634（领先官方 2 commit、behind 0、无冲突，可直接快进合并）

已验证

• cherry-pick 可干净应用（官方基线 b150a55 上 patch 应用成功，JSON 有效）
• 官方 master 文件与 patch 上下文逐字一致，无冲突风险

后续建议

1. 审计 npm 发布图是否残留旧行 0.0.1-rc.5 的 dsh-tools 引用；
2. tool-calls.ts 调度器调用加防御检查，避免未来打包回归再次以 undefined.prepare 形式崩溃。

感谢团队排查，期待合并。

[Shizuku-keop]

@argszero @Electricitysheep Request to the maintainers: please enable the Pull Request channel for this repository.

We have a ready-to-merge fix for this exact issue (undefined.prepare / duplicate TOOL_RUNTIME_SCHEDULER copies):

• Branch: Shizuku-keop/deepseek-harness → fix/dsh-base-dsh-tools-peer
• Commit: 72cac94a09f5448037c478fe08b8adc5d42043b6
• Change: move @deepseek-ai/dsh-tools from dependencies to peerDependencies in packages/bundle/base/package.json (+2/-1, cherry-pick verified against official baseline)

Currently the repository has Pull Requests disabled (has_pull_requests: false), so the standard contribution flow is unavailable and code changes can only be discussed here. Enabling PRs would let the community submit fixes through the normal review process.

Thank you!