一、三种形态

command：跑一条 shell 命令，看退出码和输出。完全确定，零 token，二十毫秒量级。 prompt：把上下文交给模型评一次，让它回一个判断。基本确定，一千二百 token 左右，接近一秒。 agent：派一个子智能体，多轮查证，甚至给出修改方案。不太确定，九千 token 起，十几秒。

三者的差别不只是成本，还有「同一个输入会不会给同一个答案」。command 永远一样，agent 每次可能不同。 对钩子来说，确定性本身就是一种价值：钩子的作用是保证，一个每次答案不一样的保证不算保证。

二、六项检查，三种各能判几项

规则类的四项——命令里有 rm -rf、改了 .env、提交信息少于十个字、 文件里有 TODO 注释——command 全都能判。 语义类的两项——这次改动有没有引入逻辑错误、新代码有没有覆盖异常分支——命令判不了， 因为命令不会理解代码。 prompt 和 agent 六项都能判。所以从「能力」看，越往上越强。

但成本差得远：一次 prompt 一千二、一次 agent 九千。agent 是 prompt 的七倍多。 而 command 不花 token。挂在一个一次会话触发九次的事件上，这个差别会被放大九倍。

三、阶梯怎么选

第一级先问：这条规则能不能用一行命令写出来？能，就用 command。 第二级：能用一段话描述判断标准、但没法写成规则的，用 prompt。比如「这次改动有没有引入逻辑错误」。 第三级：需要看多个文件、跑测试、甚至给修改方案，才用 agent。

顺序不能反。上来就派 agent 是这套体系里最贵的浪费——九成所谓的「智能检查」，其实一行 grep 就够了。 还有一个中间态值得注意：能用规则判、但规则很长的情况。 这时候仍然优先 command，把规则写进脚本，别写进提示词。脚本可以被 review、可以被测。

四、prompt 和 agent 的真正区别

prompt 是单次评估：给它一段上下文，它回一个判断。它看不到更多文件，也不能去查证。 agent 是多轮：它能读文件、跑命令、拿证据，然后才下结论。 所以区别不是「谁更聪明」，是「能不能去查」。需要证据的用 agent，凭上下文就能判的用 prompt。

大部分「检查代码质量」的活其实属于后者：改动就在上下文里，不需要再去翻仓库。 真正需要 agent 的场合很少：判断「这个改动会不会影响别的模块」——那就得去读别的模块。

五、动手 Demo：同六项检查，三种处理器各判一遍

六项检查：四项能用规则判、两项需要理解代码。三种处理器逐个过一遍，看各能判几项。 再算成本：每次多少 token、多少毫秒。

CHECKS = [(u"命令里有 rm -rf", u"规则"), (u"改了 .env 文件", u"规则"),
          (u"这次改动引入了逻辑错误", u"语义"), (u"新代码没有覆盖异常分支", u"语义")]

cmd = u"能" if kind == u"规则" else u"不能"   # 命令不懂代码

实跑输出：

--------------------------------------------------------------------
同六项检查，三种处理器各判一遍
--------------------------------------------------------------------

  钩子的处理器有三种：跑一条命令、让模型评一次、派一个子智能体去查证。
  三者的确定性、成本、能力依次上升。

  ① 三种处理器
  --------------------------------------------------------------------
| 类型 | 做什么 | 确定性 | 能力 |
|---|---|---|---|
| command | 跑一条 shell 命令 | 完全确定 | 只能判规则 |
| prompt | 把上下文交给模型评一次 | 基本确定 | 能判语义 |
| agent | 派子智能体多轮查证 | 不太确定 | 能查证、能给方案 |


  ② 六项检查，三种各能判几项
  --------------------------------------------------------------------
| 检查项 | 性质 | command | prompt | agent |
|---|---|---|---|---|
| 命令里有 rm -rf | 规则 | 能 | 能 | 能 |
| 改了 .env 文件 | 规则 | 能 | 能 | 能 |
| 提交信息少于十个字 | 规则 | 能 | 能 | 能 |
| 文件里有 TODO 注释 | 规则 | 能 | 能 | 能 |
| 这次改动引入了逻辑错误 | 语义 | 不能 | 能 | 能 |
| 新代码没有覆盖异常分支 | 语义 | 不能 | 能 | 能 |

  规则类的四项 command 能判，语义类的两项判不了——命令不会理解代码。prompt 和 agent 六项都能判。

  ③ 成本差多少
  --------------------------------------------------------------------
| 处理器 | 每次 token | 每次耗时（毫秒） | 相对成本 |
|---|---:|---:|---:|
| command | 0 | 20 | 0 |
| prompt | 1200 | 900 | 2 |
| agent | 9000 | 12000 | 21 |

  一次 prompt 大约一千二 token，一次 agent 大约九千。
  agent 是 prompt 的七倍多，是 command 的无穷倍——command 不花 token。

  ④ 阶梯怎么选
  --------------------------------------------------------------------
  第一级先问：这条规则能不能用一行命令写出来？能，就用 command。
  它零 token、二十毫秒，而且永远同一个答案。
  第二级：能用一段话描述判断标准，但没法写成规则的，用 prompt。
  比如「这次改动有没有引入逻辑错误」。
  第三级：需要看多个文件、跑测试、甚至给出修改方案，才用 agent。
  ! 顺序不能反。
  上来就派 agent 是这套体系里最贵的浪费——九成所谓的「智能检查」，其实一行 grep 就够了。

①三种形态的确定性和能力：command 完全确定、只能判规则；prompt 基本确定、能判语义； agent 不太确定、能查证。 对钩子来说确定性本身就是价值——钩子的作用是保证，一个每次答案不一样的保证不算保证。 ②六项检查里规则类四项 command 全判，语义类两项判不了。prompt 和 agent 六项都能判。 ③成本那张表：command 零 token、二十毫秒；prompt 一千二、九百毫秒；agent 九千、一万二毫秒。 agent 是 prompt 的七倍多 token、十几倍耗时；而 command 完全不花 token。 挂在一个一次会话触发九次的事件上，这个差别会被放大九倍。 ④阶梯的顺序不能反：先问能不能用一行命令写出来，能就用 command；能用一段话描述判断标准的用 prompt； 需要看多个文件、跑测试的才用 agent。 上来就派 agent 是这套体系里最贵的浪费——九成所谓的「智能检查」，其实一行 grep 就够了。

30 秒实验

1. 给「文件里有 TODO 注释」配一个 prompt 处理器，重跑第 ③ 步。 它多花多少 token，换来什么 command 拿不到的东西？
2. 把 agent 那次改成「先跑测试再看改动」，重跑一遍。它比 prompt 多查到的东西，值不值那七倍 token？
3. 假设某个钩子一次会话触发九次，分别用三种处理器，算一次会话的总成本。差距是多少？

常见误区

1. 上来就派 agent 做检查。九成所谓的「智能检查」一行 grep 就够，用 agent 是纯浪费。
2. 用 prompt 判能用规则判的事。prompt 每次答案可能不同，而规则类判断需要每次都一样。
3. 需要查证据的场合用 prompt。它只能看上下文，不能读别的文件、不能跑命令。
4. 把长规则写进提示词而不是脚本。脚本能被 review、能被测，提示词不能。
5. 忽略确定性这个维度，只看「能不能判出来」。钩子要的是保证，不是「通常判得对」。

处理器会选了，下一节看钩子跟主循环之间那套说话方式：返回值怎么写才生效。

• ☐ （本篇完，下一篇 5.5 hookSpecificOutput：与 Claude 交流的协议）

相关笔记

• 五种模式：五种分工形状
• 返回值协议：返回值协议
• Claude Code 橙皮书 · 索引
• 🐎 Claude Code 实战 · 索引