16 · 故障排查与综合练习¶
16.1 错误先定位在哪层¶
flowchart TD
E[任务失败] --> L{哪个边界?}
L --> C[CLI / 配置 / 资源加载]
L --> A[认证 / 模型协议]
L --> T[工具参数 / 执行 / 权限]
L --> S[会话 / 分支 / 压缩]
L --> U[界面 / 事件完成判断]
C --> D[检查 diagnostics 与路径]
A --> K[检查 provider API 和凭据来源]
T --> R[检查 toolResult isError 与实际状态]
S --> P[检查 canonical branch projection]
U --> F[检查 agent_settled 与订阅顺序]
16.2 常见问题¶
| 现象 | 首先核对 | 正确方向 |
|---|---|---|
| npm 包或导入找不到 | 包名与 1.0 exports | 使用 earendil-works；provider 子路径 |
| SDK tools 类型报错 | 是否传了旧工具对象 | tools 为名称列表 |
| 模型不可用 | provider 是否配置认证 | 环境变量、auth.json、runtime |
| 兼容服务器 400 | API type 与工具支持 | 区分 completions / responses |
| skill 没加载 | frontmatter、description、diagnostics | /skill:name 强制 |
| 项目配置没生效 | trust 与工作目录 | 非交互显式 --approve |
| MCP 已配置但 SDK 没工具 | extensionFactories 与 bindExtensions | 显式加内建扩展 |
| 某工具经 Code Mode 仍可用 | exposure / callable 与 direct active 不同 | 用真正授权和 hidden 策略 |
| 修改 state.messages 恢复失败 | SessionManager 才是权威 | 正式 restore/import |
| agent_end 后又有输出 | 自动重试或 before_settle | 等 agent_settled |
| 连续请求报 already processing | 并发调用同 session | queue 或显式 steer/followUp |
| terminate 没停 | 批次是否全部 terminate | 检查所有 finalized outcomes |
| 写入后取消但文件已改 | 取消不回滚 | 查真实状态，必要时恢复 |
| edit 找不到 oldText | 版本、行尾、唯一匹配 | 先 read，再最小匹配 |
| 脚本失败却已操作外部系统 | Code Mode 不回滚工具副作用 | 幂等工具与业务事务 |
16.3 专门给 1.0 的排错提示¶
不要用多年前 API 片段当类型事实。运行 npm run check，读取 node_modules 里的 .d.ts 和对应源文件，确认导出名。Faux 工厂叫 fauxProvider()，不是从命名习惯猜一个 createFauxProvider()。
1.0 npm Coding Agent 有 shrinkwrap 固定传递依赖。普通 root overrides 未必覆盖其锁定版本；课程保存 npm audit 原始结果，不在不核对实际依赖树时声称修复。网站静态发布不运行这些 npm 包，示例依赖需要按升级风险另行管理。
16.4 八个练习¶
- 给 search_notes 加入大小写和空白处理，测试空查询与无匹配。
- 写
list_tags工具，返回明确 schema；让模型依据 tags 检索。 - 增加一个故意失败工具，观察模型下一轮是否收到 isError。
- 给一个副作用工具设 sequential，比较同批次事件顺序。
- 为 SessionManager 建两个分支，解释 getEntries 与 getBranch 差别。
- 写 skill 和 prompt 使用同主题，比较加载成本和输出差异。
- 接一个你自己的 MCP server，观察 direct/deferred/codemode 的工具声明。
- 实现结构化任务状态与 artifact 验收，不依赖模型自称完成。
16.5 练习参考判断¶
第 1 题：不要把无匹配当工具异常，模型应说证据不足。第 3 题：返回错误文字但不标 isError 的实现不合格。第 4 题：sequential 是批次级影响，不仅这个工具单独排队。第 5 题：完整树和 active path 是两个对象。第 7 题：默认 MCP codemode 不把全部工具预先塞进 prompt。第 8 题：至少检查实际输出存在、来源和格式。
16.6 综合项目：自己的 Agent 研究台¶
完成一个应用，输入仓库路径和问题，输出中文 Markdown，包含版本、职责、调用链、状态、失败、测试和未验证内容。
验收：显式 tools；不任意执行下载代码；保存会话；可取消；最终 artifact 自动查路径；20 道真实问题，至少比较事实、引用、耗时和费用；不同用户无交叉记录。
你可以先用 SDK CLI 完成，再加网页。只有这条流程验证以后，才考虑长期 Goal 与子 Agent。
16.7 自测问题¶
- harness 和 model 的边界是什么？
- 为什么完整 toolCall 结束前不能执行？
- tool completion 顺序和 transcript 顺序为什么不同？
- SDK 恢复为什么不能只赋 messages？
- project trust 为什么不是沙箱？
- Code Mode 失败后为什么外部操作可能已完成？
- Durable 的 replay safe 为什么不等于 exactly-once？
- 你自己的「任务已完成」由什么独立证据判断？
能结合一个真实案例回答这些问题，你已经掌握构建自己 Agent 的关键设计边界。