[修复方案] 源码启动 prepare 崩溃：profile 解析锚点未规范化导致 tsx 跳过 paths（fork 分支 + 回归测试 + 端到端验证）

[coldxiangyu163]

概要

源码启动（pnpm dsh）在存在构建产物时，第一次工具调用即整轮失败：Cannot read properties of undefined (reading 'prepare')。我们在本地定位到完整根因，给出最小修复（4 行）与回归测试，并做了端到端验证。

由于仓库当前不接受外部 PR（见 CONTRIBUTING.md），修复放在 fork 分支供维护者取用。

本问题与以下报告同源： #6974、#7011、#7030、#7035、#7039。

根因

同一进程加载了两份 @deepseek-ai/dsh-tools：

• CLI 侧（apps/cli/src/bin.ts 的 ESM 图）经 node --import tsx/esm + tsconfig paths → packages/core/tools/src/index.ts
• profile 插件侧经 packages/boot/app-boot/src/profile-resolution/ 的原生解析 → packages/core/tools/lib/index.js

TOOL_RUNTIME_SCHEDULER 定义为 Symbol('@deepseek-ai/dsh-tools.scheduler')（packages/core/tools/src/index.ts:463，不是 Symbol.for），两份模块各持有一个 symbol，因此 packages/core/agent-loop/src/tool-calls.ts:170 取 ctx.tools[TOOL_RUNTIME_SCHEDULER] 得到 undefined，.prepare(...) 抛错 —— 与 #7039 的现场一致（ctx.tools[TOOL_RUNTIME_SCHEDULER] === undefined、两个 Symbol 描述相同但 !==）。

触发条件：工作树存在 lib/ 构建产物。没有构建产物时同一路径直接 ERR_MODULE_NOT_FOUND（apps/cli/node_modules/@deepseek-ai/dsh-agent-instructions/node_modules/@deepseek-ai/dsh-tools/lib/index.js）—— 也就是源码启动在这两种状态下都不健康。

引入点：9ddef327a4 feat: resolution mode link to runtime 把非打包 CLI 的默认 resolution mode 从 link 翻到 runtime（随 #4471 合入 master）；此后源码启动会同时挂载 src 与 lib 两个平面 —— 与 #7030 的分析一致。

链路细节：profile 的 ESM 后备解析把 pnpm 符号链接下的 node_modules/.../package.json 当作 declaring 锚点交给 Node/tsx；tsx 对 parentURL 含 /node_modules/ 的请求不应用 tsconfig paths（tsx@4.22.4 的 !parentURL.includes("/node_modules/") 判据），于是插件走包 exports 的 lib/，而 CLI 走 paths 的 src/。

修复

packages/boot/app-boot/src/profile-resolution/resolver.ts 的 ESM fallback 路由，把 anchor 规范化为真实路径后再交给已有 loader hooks：

- const routedParent = pathToFileURL(route.kind === 'fallback' ? route.entry.declarer : route.parent).href
+ const routedParent = pathToFileURL(route.kind === 'fallback' ? canonicalPath(route.entry.declarer) : route.parent).href

pnpm 的 node_modules/@deepseek-ai/dsh-tools 是符号链接；真实锚点不再包含 /node_modules/，tsx 的 paths 投影因此对 workspace 插件生效，profile 与 CLI 落到同一份 src 单例（Symbol 自然同一）。

约束：不新增平面开关、不复制 tsconfig 解析器、不改包 exports、不动 vendor；普通 Node 仍走包 exports。worker 线程解析（worker-bootstrap.ts）复用同一 installProfileResolution，自动获得同一修复。

验证

• A 有构建产物：pnpm run build 退出 0 → pnpm dsh --profile headless "…" 退出 0，tool/call → 成功 tool/result → turn/end: completed。
• B 无构建产物：pnpm run clean（删除 308 项，确认 tools/agent-loop/app-boot/CLI 的 lib/ 不存在）后同一命令退出 0，输出当天日期。
• C 回归：修复前新增测试真实退出 1（2 failed：sameInstance: false 且 URL 落到 lib/；无产物 ERR_MODULE_NOT_FOUND）；修复后 68 passed，resolver.ts statements/branches/functions/lines 均 100%。
• D 相邻面：pnpm run typecheck、pnpm run lint、pnpm run test packages/boot/app-boot apps/cli scripts/run-gates.spec.ts（460 passed / 1 skipped）、test:e2e apps/cli/tests/built-bin.e2e.ts（3 passed）、test:snapshot snapshots/session/headless.snapshot.ts -t bash-tool-turn（1 passed）、test:docs（20 checks）、doc-sync（41 checks）全部通过。
• 原句端到端复测：用最初触发故障的整句（「2026-2028年中国创新药发展趋势，多agent调研，子agent调研结果落地文件方便主agent读取，最终形成一个完整报告」）真实启动：7 次 tool/call 全部成功，tool-workflow/run-start + 5 × tool-workflow/agent-start、5 个子会话目录落盘，turn/end 错误计数 0。
• 独立只读 Review：未发现 BLOCKER / SHOULD / NIT（复核 diff、tsx 判据、worker bootstrap 复用路径、gate 注册与证据日志）。

临时缓解（在修复合入前）：用构建入口启动（#7039 提到的 pnpm exec node apps/cli/lib/bin.js web）可避免双实例。

已知范围外残留：pnpm run clean 后 typert-loader 会对 6 个未生成的 lib/typert.host.js 输出非致命警告；该 loader 直接拼接生成产物路径，不经过本次修复的 bare-package ESM 后备解析，本修复未涉及。

代码位置（fork 分支）

由于仓库暂不接受外部 PR，修复放在 fork 分支：

• 分支 diff：coldxiangyu163/deepseek-harness@master...fix/profile-resolution-source
• commit：coldxiangyu163@2b628e1
• 改动 6 个文件：packages/boot/app-boot/src/profile-resolution/resolver.ts(+3/−1)、新增 packages/boot/app-boot/tests/profile-resolution-source.spec.ts(+107)、scripts/run-gates.ts(+1，接入 Node compatibility smoke gate)、packages/boot/app-boot/README.md / README.zh.md / README.i18n.yaml。

如果维护者愿意接收，我可以按仓库要求调整形态（分支名、commit 拆分、文档位置）或补任何缺失的验证。

[WXY-YXW996]

独立复现确认 + 补丁验证通过。我们在看到这个帖子之前，从症状出发独立排查到了同一处，结论与你一致；这里补一组来自另一台机器的数据，供维护者参考。

环境：dsh 0.1.6-alpha.2（master，ddefc45fbc）／Node v24.21.0 ／ pnpm 11.7.0 ／ tsx 4.22.4 ／ Linux 6.18.33.2-microsoft-standard-WSL2（存在 lib/ 构建产物）。

一、独立复现的现场数据

除了 ctx.tools[TOOL_RUNTIME_SCHEDULER] === undefined、两个 Symbol 描述相同但 !== 之外，我们额外量了一个点：运行时那把键到底是哪一份副本铸造的。做法是把两份都显式加载，再和 ctx.tools 上的实际键做 === 比对：

const viaBare  = await import('@deepseek-ai/dsh-tools')   // tsx + paths -> src/index.ts
const viaEntry = await import(pathToFileURL(resolve('packages/core/tools', entryFromPackageJson)).href)  // -> lib/index.js
const live = Object.getOwnPropertySymbols(ctx.tools)
  .find(s => s.description === '@deepseek-ai/dsh-tools.scheduler')
// live === viaBare.TOOL_RUNTIME_SCHEDULER ? 'src 副本' : 'lib 副本'

修复前：

own symbols on ctx.tools : [ 'Symbol(cordis.tracker)', 'Symbol(@deepseek-ai/dsh-tools.scheduler)' ]
scheduler key came from  : lib 副本（package.json entry）
TOOL_RUNTIME_SCHEDULER in ctx.tools? false

这与你说的"插件侧走包 exports 的 lib/、CLI 侧走 paths 的 src/"完全吻合。

你提到的几条判据我们也在本地逐一核对过，均属实：resolver.ts:693 的 routedParent 行、tsx 4.22.4 dist 中的 o&&r.parsedTsconfig&&!s.parentURL?.includes("/node_modules/")、提交 9ddef327a4，以及 canonicalPath 已存在于同文件（124 行），因此该补丁未引入新依赖。

二、补丁单独验证

在干净 master 上只应用 resolver.ts 这一行改动（不含任何其他修改）：

scheduler key came from  : src 副本（tsconfig-alias）
TOOL_RUNTIME_SCHEDULER in ctx.tools? true
ctx.tools[TOOL_RUNTIME_SCHEDULER]  : { prepare, dispatch, finalize, finish }

撤销该行后立即回到 false。插件侧确实被拉回到与 CLI 侧同一份 src 单例。

相邻面：npx vitest run packages/boot/app-boot packages/core/agent-loop packages/core/tools → 47 文件 / 1086 用例全部通过；pnpm run build 退出 0，重新构建后复现检查仍为通过。

另外确认你提到的临时缓解有效：改用构建入口启动不出现双实例。

三、一个附带的数据点

我们最初尝试过把 packages/core/tools/src/index.ts:463 的 Symbol(...) 改成 Symbol.for(...)，症状同样消失（vendor/cordis/src/utils.ts 里所有跨边界符号本来就一律用 Symbol.for）。但那只是让契约能容忍两份副本，双重加载依然存在（same module instance 仍为 false）；你这个补丁是从源头消除重复，方向更正确。提出来仅作为参考：若维护者希望对这类跨包符号键多一层防护，两者并不冲突。

四、补充：这条路径上的非工具型报错

顺带一提，TOOL_RUNTIME_SCHEDULER 似乎是仓库里唯一一个用裸 Symbol() 创建、且作为跨包（经裸包名）共享对象属性键的符号；其余模块级 Symbol() 要么模块私有，要么只在本包内经相对路径引用，不受影响。这或许可以解释为什么故障集中表现为工具调用整轮失败。

需要的话我可以提供那份不依赖 API key、浏览器和会话的复现脚本（启动 profile 后直接判定 TOOL_RUNTIME_SCHEDULER in ctx.tools），或在其他环境上补测。

[fieldnote-ops]

补一条防复发建议（结论不重复，仅供维护者取舍）：

• CI 缺口：[修复方案] 源码启动 prepare 崩溃：profile 解析锚点未规范化导致 tsx 跳过 paths（fork 分支 + 回归测试 + 端到端验证） #7048 描述的两种状态都能通过 CI，因为 .github/workflows/e2e.yml 的 e2e 作业固定 DSH_EXAMPLE_MODE=lib（走构建产物、天然单平面）；keyless 的源向量测试 apps/cli/tests/source-launch.compat.spec.ts 此前只断言 argv 拒绝，packages/test-support/loader-smoke 的 fixture 在 src/lib 两种模式下都会通过。本机实测：apps/cli/tests/agent-team-headless.e2e.ts（默认 src 模式、keyless）在未修复的 master 上失败（Cannot read properties of undefined (reading 'prepare')），打上源向量修复后通过。把它以 src 模式纳入 keyless 作业，是能拦住同类回归的最小门禁。

• 若一并采纳 Symbol.for 加固：它会移动 packages/core/tools/src/index.ts 的绝对行号，docs/config-catalog.md（656→659）与 docs/persistence-schema.json（682→685）随之过期；这两个 catalog 嵌的是行号引用，pnpm run test:docs 不含对应 verify，必须重跑 gen-config-catalog / gen-persistence-catalog 与 pnpm run doc-sync。加固在 pnpm run build 全量重建后仍成立：混合平面下工具派发恢复，改前必报同一错误。