常见错误与排障

按症状归类。每一条都来自本教程编写与验证过程中的真实踩坑（Demo 与 mini-harness 的代码里都留着修复痕迹）。

• dsh / Demo 相关
  • 插件一直 PENDING 不执行
  • failed to import loader entry … Cannot find module
  • MISSING_CREDENTIAL: llm-deepseek: no API key …
  • 覆盖某行配置后行为异常
  • MODULE_TYPELESS_PACKAGE_JSON 警告
  • 改完插件不生效
• mini-harness 相关
  • SSE 只收到第一条事件就断开
  • 模型"说了一堆话"但组装结果为空
  • service "xxx" 已经被注册
  • 工具循环后 turn 提前结束
  • 前端 404 /api
  • 真实模型 401 / 404
• 通用心智工具

dsh / Demo 相关

插件一直 PENDING 不执行

现象：--dump-config 里能看到你的插件行，但运行时毫无动静。

原因：inject 声明的服务名拼错，或提供该服务的插件没被挂载。PENDING 不是错误，是"等待依赖"。

排查：

1. 对照核心包地图确认服务名（llm、tools、sessions、agents、systemPrompt——注意 systemPrompt 的驼峰）；
2. 用 --dump-config 确认提供该服务的行存在。

failed to import loader entry … Cannot find module

现象：patch 里的本地插件加载失败。

原因：Loader 的 baseUrl 是 profile 目录（$DSH_HOME/profiles/<profile>/），相对路径从那里解析，不是从 patch 文件或当前目录。

修复：按 Demo 路线图 的路径约定写 ../../../plugins/xxx.ts，或改绝对路径。

MISSING_CREDENTIAL: llm-deepseek: no API key …

现象：headless 任务报缺密钥。

原因：patch 没生效（忘带 --patch、路径错、DSH_HOME 指错），默认路由仍是 deepseek-official。

排查：--dump-config | grep -A2 agent-default-model 看 provider 是否已是 mock。

覆盖某行配置后行为异常

现象：patch 覆盖后插件缺字段报错或行为变了。

原因：id 定向 patch 整行替换 config，没有深合并。只写一个字段会把其余字段全丢。

修复：复述要保留的所有字段（原理篇 8.3）。

MODULE_TYPELESS_PACKAGE_JSON 警告

现象：跑 Demo 5–8 时 Node 打印 module type 警告。

修复：无害。或给 plugins/ 目录加 {"type":"module"} 的 package.json。

改完插件不生效

现象：改了插件代码重跑还是旧行为。

说明：headless 是一次性进程，重新运行命令即可；不存在缓存。如果是 web 模式，确认改的是被挂载的那份文件、且客户端插件（dsh.client 行）需要 pnpm run dev:web 重新构建。

mini-harness 相关

SSE 只收到第一条事件就断开

原因：用 req.on('close') 关闭流。req 的 close 在请求体被 express.json() 消费后就会触发。

修复：改用 res.on('close')（代码见第五步）。

模型"说了一堆话"但组装结果为空

原因：适配器只发 text-delta，没发 block-end。BlockAssembler 只认 block-end 冻结块。

修复：在 finish 前发出所有打开块的 block-end（协议义务，见第二步）。

service "xxx" 已经被注册

原因：同一个服务被加载两次——包括"插件在 start 里 provide 服务，触发的唤醒逻辑又把它自己拉起来一次"这类重入。

修复：启动前先置 starting 状态排除重入（mini-harness 的 plugin.ts 有注释说明）；真实 Cordis 用 fiber 状态机解决同一问题。

工具循环后 turn 提前结束

原因：用 while (pending.length > 0) 驱动 turn，工具循环后 pending 为空导致提前退出。

修复：区分"无新消息但需继续"（空数组）与"turn 结束"（null）两种状态（第三步）。

前端 404 /api

原因：Vite 代理没生效（后端没起、端口不一致）。

排查：后端 4317 是否在跑（curl http://127.0.0.1:4317/api/health）；前端是否从 5174 启动。

真实模型 401 / 404

原因：OPENAI_API_KEY 未设置；OPENAI_BASE_URL 拼错（注意要不要带 /v1）。

排查：先 curl 一次同一端点确认密钥与 URL，再启动 server。

通用心智工具

1. 先 dump 后猜：任何配置问题先 --dump-config，组合树会告诉你每行来自哪一层。
2. 日志即真相：行为问题先看会话日志（read-session.mjs / 事件面板），模型看到什么、工具返回什么全在里面。
3. 读错误码：NO_ADAPTER（路由没有适配器）、DUPLICATE_ADAPTER（重复注册）、MISSING_CREDENTIAL（缺密钥）——dsh 的错误码是稳定的诊断语言。
4. PENDING 是线索不是静默：等待中的插件要么依赖没满足，要么名字写错。