夜雨聆风AI编程三卷书 v1.0 发布后的第一篇深度文 · 关于「源码核实」是什么意思
写在前面
市面上的 AI 编程教程，绝大多数都是抄出来的。
抄什么？抄官方 README、抄 changelog、抄别人的博客、抄 ChatGPT 给的总结。
我做这本书的时候，本来也想抄。因为快——一周内能抄出 10 万字。但抄到第三章我停下来了。
原因很现实：几乎每抄一段，我都发现跟实际工具行为对不上。
文档说 A，工具实际做 B，社区博客说 C，ChatGPT 总结说 D。四份说法没有一份能跟我自己跑出来的结果对上。
那一刻我决定换路线：从抄文档改为读源码。这本书的整体节奏从此变慢了 5 倍，但价值翻了不止 5 倍。
下面这一篇，把我整本书最核心的"源码核实方法论"完整讲一遍——配一个真实的案例。读完你会知道为什么 AI 编程不能再靠"换个 prompt 再试一次"了。
一、为什么必须读源码
我先给你看一组反差。
我整理三卷书第二卷《工作流》的过程中，每一个我以为是「bug」的 AI 工具行为，最后都被源码追踪证明：
不是 bug，是行为变了，文档没更新。
具体来说，31 个深度陷阱里：
- 17 个
是工具升级后行为静默改了，文档慢了 1-3 个月才追上 - 9 个
是社区流传的"hack"——其实根本不存在那个配置项 - 5 个
是用户自己理解错了 prompt / context / agent 之间的关系 - 0 个
真的是工具 bug
0。
这个比例让我重新思考"AI 编程"这个领域的认知结构：
唯一靠谱的真相来源——源码。
源码不会骗你。文档可能落后，issue 可能误判，博客可能道听途说，git log 不会。
二、5 步源码诊断法
写完 31 个陷阱后，我把每次的排查过程提炼成一个可复用的诊断套路。这是这本书第二卷的核心框架。
任何时候 AI 工具行为反常，按这 5 步走：
第 1 步 · 症状采集
不要写"它失败了"。记录确切的、可复现的现象：
完整命令（含所有参数 / 标志） 触发条件（什么时候开始出错的） 错误输出全文（不要省略，省略的部分往往最关键） 重试 N 次的结果（每次都一样？还是随机？）
这一步看起来无聊，但80% 的人在这里就跳过——直接进入"猜测 + 重试"循环。这就是为什么大多数 AI 编程问题排查不了。
第 2 步 · 文档对照
打开工具官方文档，逐字对照你看到的行为：
官方说"会自动 X"——你的实测是不是真的自动 X？ 官方说"不会做 Y"——你看到的是不是 Y？ 文档版本号跟你装的版本号一致吗？（这一点 90% 的人会忽略）
文档跟现象对不上 → 进入第 3 步。
第 3 步 · 误判收集
去 GitHub Issues / Reddit / V2EX / Twitter 搜你看到的现象。
收集 4-5 种流行的解释——重点是找出它们互相矛盾的地方：
有人说原因是 A，有人说是 B 有人说要改配置 X，有人说改配置 Y 有人 swear 这个 hack 管用，有人说完全不管用
矛盾点 = 真相不在表面。这一步明确告诉你：社区也没搞清楚，必须自己读源码。
第 4 步 · 源码追踪
这是最慢、也最值钱的一步。
打开工具的 GitHub repo，按这个顺序找：
- entry point
— 你的命令最终调到哪个文件 / 函数 - dispatch 路径
— 这个函数往下又调用谁 - 关键决策点
— 在哪一行做了"是否 X"的判断 - 环境依赖
— 这个决策依赖哪些环境变量 / 配置 / 状态
通常 1-3 小时能追完。关键不是追多深，是追到「决策点」——找到那个 if (condition) { do_A() } else { do_B() }，你就赢了。
第 5 步 · git log 时间线
找到决策点后，看这一行 / 这个函数的 git blame：
- 什么时候改的
？ 改之前是什么逻辑？ commit message 怎么说？
这一步通常解释为什么文档没更新——改动是个内部 PR，commit message 一句"refactor sandbox handling"，根本没意识到这是个 breaking change。
5 步走完，真相通常跟所有社区讨论都不一样，但可以解释所有现象。
三、一个真实案例（节选自卷二第 5 章）
让我用一个具体陷阱演示这套方法。
症状：用 Codex CLI --full-auto 跑长任务，90% 的命令一气呵成，10% 卡在中间等确认。社区把这个叫"Codex CLI 的 --full-auto 是 bug"。
5 步走完之后我发现：
不是 bug。
--full-auto的语义在 2025 年某个版本悄悄变了——从"任何情况都不问"改成"在 sandbox 内不问，sandbox 外照样问"。文档版本号跟代码版本号脱节了 2 个月。
最干净的修复不是"再试一次"，也不是"换个 prompt"，是显式开启 sandbox mode。这是社区流行的 4 种"修法"里没有人提到的那一种——因为前面那些人都没读源码。
完整 6 轮源码追踪过程（哪个文件 / 哪个函数 / 哪段 commit / 怎么交叉印证）在三卷书第二卷《工作流》第 5 章，约 4000 字。这里只展示方法论。
这种案例，整本书第二卷里有 31 个。每一个都按上面 5 步走完。
四、《AI 编程实战三卷书》v1.0 已发布
如果上面这套方法论对你有启发，欢迎完整读三卷书：
📖 在线阅读
https://book.aibuzhiyu.com/ —— CDN 加速 mdbook 完整在线版
📥 PDF 下载 + GitHub
github.com/jnMetaCode/ai-coding-trilogy —— 三卷分卷 PDF，CC BY-NC-SA 4.0 协议
🌐 完整内容矩阵
aibuzhiyu.com —— 10 工具 / 28 章 / 31 陷阱 / 215 专家角色 / 6 开源仓 (10k+ ⭐)
三卷分别给谁
| 卷一 · 入门 | ||
| 卷二 · 工作流 | ||
| 卷三 · 架构 |
写在最后
我做这本书不是为了卖。
永久免费——CC BY-NC-SA 4.0 允许个人 / 公司内部学习 / 团队培训 / 课堂使用，禁止贩卖。
如果它真的帮到你，麻烦在以下任一地方留个痕：
⭐ GitHub 给 ai-coding-trilogy 一个 star（让算法多推给其他人） 💬 朋友圈或群里转发这篇——尤其是身边那种**"AI 工具试了一圈感觉都怪怪的"的朋友** 📨 关注公众号 「AI 不止语」 回复 群进读者群
工具会过时，方法论不会。
读源码，做核实，永久免费——给真心想用 AI 把活儿干好的人。
📖 在线读 : book.aibuzhiyu.com 🌐 官 网 : aibuzhiyu.com ⭐ GitHub : ai-coding-trilogy
