附录 A
附录 A · 按问题查
正文是线性讲的,但真实的问题不线性。这一份按你遇到的问题查。 全表 30 条症状,每条都指向正文里能直接跳转的坐标(章号 + 具体函数或文件)。
一、对话跑不动
| 现象 | 先看 | 去哪章 |
|---|---|---|
| 发消息没反应 | bus.deliver() 的串行链是否卡住 |
Q03 |
| 卡在「思考中」不动 | llmInFlight 是否为真 |
Q04 |
| 一直循环调工具 | toolUseBlocks.length 与回合上限 |
Q04 |
| 回合数用完就停 | max_turns 与 turn-budget.ts |
Q04 |
| Stop 钩子发了消息却没下一轮 | request('stop_hook') 是否被拒 |
Q04 |
最快的排查入口是 Q03 讲的 deliver():所有事件都从那里过。
在 deliver 里打一行日志打上 name 与 queryId,就能看到接力卡在哪一棒。
二、请求内容不对
| 现象 | 先看 | 去哪章 |
|---|---|---|
| 模型看不到某个文件内容 | 七步装配里哪步丢了 | Q05 |
| 工具结果和调用对不上 | ensureToolResultPairing |
Q06 |
| 历史消息被莫名丢掉 | normalizeMessagesForAPI 的七道工序 |
Q06 |
| 压缩后行为变差 | 压缩分区归一化 | Q06 Q10 |
| prompt 缓存命中率低 | 工具 ID 重写是否保持确定性 | Q06 |
Q06 的一句话总结:消息进 API 前要过七道工序,每一步都可能丢东西。 排查时逐道打印,看哪道之后内容少了。
三、工具用不了
| 现象 | 先看 | 去哪章 |
|---|---|---|
| 模型说「没有这个工具」 | 注册表四个缓存 / MCP 连接状态 | Q07 Q18 |
| 工具被拒但没弹窗 | runChecker 返回 deny |
Q08 |
| 弹窗了但点了允许还是被拒 | 钩子来源的 ask 优先级 | Q08 |
| MCP 工具参数错位 | 键名反向映射 | Q18 |
| MCP 服务器一个报错拖垮全部 | 幽灵 required | Q18 |
| 自定义工具参数校验不通过 | parameterSchema 与 build 的边界 |
Q15 |
四、上下文或记忆出问题
| 现象 | 先看 | 去哪章 |
|---|---|---|
| 记忆没被加载 | 三层记忆的哪层 | Q09 |
| 外部导入被拦 | 两道闸 | Q09 |
| 压缩反复失败 | 14 种原因里的哪一种 | Q10 |
| 压缩熔断后再也不压 | 熔断器不落盘 | Q10 |
| 子代理看不到主会话的上下文 | Agent 隔离边界 | Q12 |
五、权限与钩子
| 现象 | 先看 | 去哪章 |
|---|---|---|
| 钩子写了没生效 | 29 个事件里挂错了吗 | Q08 |
| 多个钩子冲突 | deny > ask > allow |
Q16 |
| 钩子改参后权限又弹一次 | 改参会触发复查 | Q16 |
| 审计钩子拖慢对话 | 同步写文件 | Q16 |
六、CI 里跑不起来
| 现象 | 先看 | 去哪章 |
|---|---|---|
| 交互模式莫名变成一次性 | TTY 丢失 | Q19 |
| 需要审批的工具全被拒 | 没有权限通道 | Q19 |
| 退出码 1 但看不出原因 | 是 is_error 还是 error_max_turns |
Q19 |
| 输出文件里混进颜色码 | ANSI 未剥离 | Q19 |
| 大重构跑到一半就停 | 回合上限 | Q19 |
七、怎么自己往下读
这本书覆盖到「能动手」的程度。要继续深入,按这个顺序:
- 先跑一遍验证脚本。
qw-examples/check/下 20 个脚本, 每个都输出了本章的可数事实。跑一遍比读一遍记得牢。 - 挑一个你最关心的模块,读它的测试。测试比实现更能说明「设计意图」—— 实现告诉你「怎么做的」,测试告诉你「必须保证什么」。
- 改一处,看谁崩。这是最快的理解方式。 Q15–Q19 每章都给了「改一处试试」的具体动作。
最后一句提醒:这份快照是 1.0.0-preview,代码在动。 遇到行号对不上,按函数名搜,别按行号。