从设计者角度理解源码·方法篇：机制、原型与提问协议

这是《从设计者角度理解源码》系列的一篇"元文章"：它不讲某个模块怎么实现，只讲读源码这件事本身该怎么做。

案例全部来自同系列的 Hook 设计的两种答案——那篇给的是"填好的表"，本篇给的是"怎么用这张表"。

引言

先讲一个很常见的困境。

你遇到了一个自己喜欢的框架，想认真学它的核心技术。但它暂时用不上——手上没有项目要用它，也不确定半年后会不会用。你只有周末，两天，可能还得留半天陪家人。

于是你打开源码，读了两小时，关掉，第二天想起来昨天读了什么——说不出来。

再过一周，你只记得"它有个 hook 机制，挺精巧的"，但精巧在哪、为什么精巧、如果让你用你会不会用——全忘了。

这不是你不努力，是方法把一个"可解决的问题"变成了"不可解决的问题"。

本文想改的不是你的动力，是方法。核心主张只有一句：

道不是细节的替代品，道是细节的沉淀物。

你不能跳过细节去拿道，但你可以在每个细节上只追问三次，让道自己浮出来。

一、先分清你要哪一种"学会"

"学会一个框架"是一个含糊的说法。它至少是三种完全不同的目标，而三种的学法、跳过什么、退出条件都不一样。

这三种最容易被混着来，于是产出最差：

• 用 A 的方式学 B：去配环境、跑 demo，跑通了但说不清为什么这样设计
• 用 C 的方式学 A：专挑最炫的部分看，结果该用的地方不会用
• 用 B 的方式学 C：非要归纳出体系，其实只是想看个爽

所以第一步不是打开源码，是写下一句话："我这次是 A / B / C。"

五分钟，省一个周末。

二、为什么"只讲道"一定会失败

很多人（包括我自己）都有过这个念头：

"别让我钻细节，直接告诉我底层原理和设计思想，那些才是核心价值。"

这个念头有一半是对的——可迁移的价值确实在"为什么"，不在"是什么"。27 个事件名一年后会忘，"拒绝必须单调"能记十年。

但它有一个致命的前提错误："如果不这么做会怎样"这类问题，逻辑上无法脱离机制回答。

一个具体的例子

问：Claude Code 的 hook 为什么要用 exit code 2 表示阻断，而不是在 JSON 里写个 "blocked": true？

只讲道的版本：

因为要兼容简单脚本，降低门槛。

这句话你说它对，它确实对；但它推不出任何东西。你无法据此判断"那我的系统该不该也加一个退出码通道"，因为你不知道"不加会怎样"。

讲机制的版本：

因为脚本可能崩在解析 JSON 之前。那一刻它连一行合法输出都没有，但操作系统一定记录了退出码。如果没有带外通道，宿主就分不清"它拒绝了"和"它挂了"——而这两种情况的处理方式完全相反。

这句话推出了一条可迁移的原则：结构化数据可能缺失，进程状态一定存在；所以关键判定要有带外通道。

同一个问题，两种答法，差别不在"深不深"，在于"能不能用"。

结论：道不能跳过细节，道只能从细节里提炼。

想要判断力，就必须付出"看机制"的成本。区别只在于——你可以用更省的方式看。

三、三层粒度：决定、机制、原型

"机制"这个词被用烂了，因为它的粒度太模糊。一个系统里到底有几个"机制"？说三个也对，说三十个也对。

我后来用三个层级来卡住它：

三个校准测试

判断一个东西是"机制"还是"决定"，用这三条：

第三条最实用。 举个例子：

• "用 zod 校验" / "把 tool_input 定义成 z.unknown()" / "校验失败时把 schema 塞进错误信息"
• 这三个会一起变吗？会。如果约束从"跨进程弱类型"变成"同进程强类型"，它们会一起消失。
• → 所以它们属于同一个机制：契约校验。

再看反例：

• "工具类 hook 默认超时 10 分钟" / "SessionEnd 超时 1.5 秒"
• 这两个会一起变吗？不会。它们只是同一个机制的两个参数。
• → 所以它们是决定，不是机制。

一个真实的数量对比

用这个粒度回看 Claude Code 的 hook 系统。如果按"决定"数，能数出几十个；按"机制"数，只有 5 个：

6 个观察点 → 5 个机制。 数量立刻可控了。

这就是为什么"机制太多学不完"通常是个假问题——多数时候是数错了层，把决定当成了机制。

四、真假道：四条判别

机制之上还有一层"道"。但"道"这个词太容易变成正确的废话（"要解耦"、"要有扩展性"）。所以需要判别式。

一条最狠的判据：如果你说不出"它在什么情况下不成立"，那它就不是道，是口号。

一个旁证：成熟机制的名字，长成"问题的形状"

你注意过没有，真正被广泛复用的机制，名字几乎都是问题的形态：

没有人给机制起名叫 XXManager、XXHandler。 那些是实现的形状，不是问题的形状。

所以检验你有没有抓到机制，有个土办法：你能不能给它起一个"问题式"的名字。

如果你只能说"它里面有个 processHookJSONOutput 函数"，那是技术点；如果你能说"它把所有执行器的输出归一成一个意图结构"，那才是机制——因为"归一"是一个问题，不是一段代码。

五、八个原型

真正解决"太多"的，是最上面那层。

机制有两类：原型（prototype）和实例（instance）。原型只有 8 个，跨所有系统通用；实例则无穷多，每个框架各做一次。

下面这张表，就是那 8 个问题。每个管理系统扩展点的框架，都必须回答它们；框架之间的差别，只是答案不同。

怎么用这张表：

1. 读第一个框架：把四列填满。填不满说明没读全；同一行填出好几个答案，说明还停在"决定"层。
2. 读第二个框架：只填后两列。"和上一个差在哪"那一格，会自动变成你的判据。
3. 读第三个框架：你会发现很多格子是重复的——重复的那几条，就是真道。

这也是为什么我建议"读两个系统比读一个系统读两遍更值"：单一系统会产生虚假的一般性。

举例：CC 的 hook 跨进程，你很容易得出"hook 就该设计成子进程 + JSON"。但看 DSH 就会知道——那是产品定位的产物，不是普遍规律。 只读一个系统，你会把偶然学成必然，而带着错误规律去设计，比不懂更危险。

六、提问协议：三段循环

现在进入最实操的部分。

很多人以为顺序是"先读源码，读一部分之后再开始提问"。这个顺序是反的，而且"读一部分"本身是个坏起点。

6.1 为什么"随便读一部分"最差

你会随机停在某处：一个函数、一个字段、一段注释。此时你既没有全局坐标，也没有完整链条，于是能问出的问题只有一种：

"这段代码是干嘛的？"

这是最低价值的问题——它只能换来一句注释，下一段还要再问一遍。你会陷入"逐段翻译"，读五千行，记住零个机制。

你要的不是"读一部分"，是"跑通一条链"。

一条链 = 从"谁调用它"到"结果回到哪去"的完整路径。可能只有两百行，但它给你的是形状，不是碎片。

6.2 阶段 0：三十分钟扫出"种子"（不是读，是定位）

只做三件事：

只要这三样，不要更多。 三十分钟到了就停。

有了种子，你才有提问的词汇。没有词汇的问题，问出来也是空转。

6.3 阶段 1：先问五个"不需要代码"的问题

这一批必须在读代码前问，因为它建立的是"战略坐标"。答完，你对形态就有了预判——后面读代码就是"验证预判"，而不是"被动接受"。

这五个问题的价值在于：它们的答案会"预测"后面的设计。

比如第 4 问：如果你判断"它全是用户自己写的脚本，一定会崩"，你就能预判出 fail-open——后面读到 non_blocking_error 时，不是"哦原来如此"，而是"果然如此"。

预判对了，记忆才牢；预判错了，那个错点就是你真正的知识边界。

6.4 阶段 2：读一条链，然后问六个"需要代码"的问题

现在才打开代码。但只走一条链（比如 PreToolUse 从触发到结果回流），别横着读。

这六个问题的共同点：答案都是"一个机制"，不是"一段代码"。

而且它们都能被证伪——你答完之后，可以写一个测试去验证。可验证的问题才是真问题。

6.5 阶段 3：拿第二个系统来问两个"战略问题"

举例：CC 的 hook 跨进程。看 DSH 之后你才能问出："如果扩展者可信，还需要跨进程吗？"答案：不需要，于是就有了瀑布式中间件。这一问，把"CC 的做法"升级成了"一个带条件的判据"。

6.6 好问题的唯一判据

判据一句话：好问题的答案，应该能落成"一行代码 / 一个字段 / 一张表"。

落不成的，就是还没提对。

七、一个周末的六小时

把上面那套压成时间表。总投入六小时，产出 1~2 个机制。

为什么挑"② 见过但不知细节"

• ① 太陌生 → 会在基础概念上耗掉半天
• ③ 已经懂了 → 收益低
• ② 是收益最高的区域：你有一点直觉，但经不起追问。这种"半懂"状态一旦钻透，记忆最深、迁移最快。

什么机制值得一个周末

三个判据，满足两个就上：

按这个标准：hook 的契约设计 ✅；waterfall 中间件 ✅；"它怎么算 token" ❌；"它的配置文件长什么样" ❌。

八、反干扰：范围契约与"不做清单"

"烂尾"的原因几乎从来不是"做不出来"，而是"顺手多做了一个"。

所以开工前先写一张明确不做的清单，贴在文件顶上：

本项目的边界（写死，不加）：
- 只用 Node 内置模块，零依赖
- 单进程，不做 server，不做 UI，只 console.log
- 不做持久化、不做配置热加载、不做插件市场
- 只做三个事件（PreToolUse / PostToolUse / Stop）
- 只做 command 执行器，不做 http / prompt / agent
- 不做反向 RPC（那是下一阶段，永远不做）
- 目标：能通过 fixtures，能和参考实现对比

"不做清单"比"要做清单"更重要。

再加三条纪律：

1. 时间盒：每晚 90 分钟，到点就停，留一句"明天从哪继续"
2. 每步一次提交：commit message 写"这一步我学到了什么"
3. 每步追加一行到 NOTES.md：写你"原本以为会怎样、实际怎样"

九、"用不上"怎么办：自己造反馈

暂时用不上最大的损失不是"学不到"，是没有反馈。

你写了个 hook，它能跑，你就知道自己对了；你读了个机制，没有任何东西能告诉你"你到底懂没懂"。

解药只有一个：自己造反馈。 最便宜的形式是"预测—验证"：

1. 挑 3 个边界场景（比如：hook 超时了会怎样？两个 hook 冲突谁赢？不信任工作区时 hook 会跑吗？）
2. 先写下你的预测（不许查）
3. 再去看代码 / 跑一下
4. 记下你猜错的地方

你猜错的那几条，就是你真正的知识边界。 这比读十遍源码都准，而且只要一小时。

而且这个动作有个额外好处：它把"读"变成了"赌"。赌输了会疼，疼了才记得住。

十、结语

回到开头那个困境：想学一个暂时用不上的框架，时间只有周末。

诚实的答案是：你不可能"精通"它。 一个成熟框架有几十个机制，一个周末连目录都看不完。这是客观的，不用纠结。

但你完全可以做到：带走 1~2 个机制，外加一套判据。

所以别问"我该怎么学这个框架"，问：

"这个周末，我要带走哪一个机制？"

一个周末一个机制，一年五十个。这已经是普通人能做到的上限——而且足够让你在两三年后，面对一个新框架时，看一眼就知道它的骨架和取舍。

最后把整篇压缩成三句：

道不是细节的替代品，是细节的沉淀物。

机制不是"一段代码"，是"提对了的问题 + 被约束逼出来的答案"。

原型只有八个，实例无穷多；你该记的是那八个问题，不是四十个答案。