Qwen Code 源码级教程
附录 A

附录 A · 按问题查

826 字 · 0 行代码 · 0 块 · 约 5 分钟

正文是线性讲的,但真实的问题不线性。这一份按你遇到的问题查。 全表 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

七、怎么自己往下读

这本书覆盖到「能动手」的程度。要继续深入,按这个顺序:

  1. 先跑一遍验证脚本。qw-examples/check/ 下 20 个脚本, 每个都输出了本章的可数事实。跑一遍比读一遍记得牢。
  2. 挑一个你最关心的模块,读它的测试。测试比实现更能说明「设计意图」—— 实现告诉你「怎么做的」,测试告诉你「必须保证什么」。
  3. 改一处,看谁崩。这是最快的理解方式。 Q15–Q19 每章都给了「改一处试试」的具体动作。

最后一句提醒:这份快照是 1.0.0-preview,代码在动。 遇到行号对不上,按函数名搜,别按行号。