第 08 章 · 四层递进与确定性护栏

本篇目标：把「建议」升级成「强制」。 一句话：规则文件约 70% 被遵循，hook 是 100%。社区

8.1 四层递进：不要一次上齐

社区 单人 / 团队 Harness 的通行分层（aiworkflowpro、amux 等指南的共同骨架）：

顺序不可跳。每一层都依赖下层已经稳定；四层一起上，出问题时无法定位是哪层的锅。社区反复出现的教训是「过度设计控制流」——为当前模型弱点写的复杂 pipeline，下一次模型升级就报废。

社区 一条克制的工具原则（Cat Wu）：除非一个工具被证明能提升效果或准确率，否则不要加。工具更少 = Harness 更可控。第 09 章给出成本量化。

8.2 Guides / Sensors 四象限

社区 Böckeler 的框架按两个轴切分：Guide 事前引导，Sensor 事后反馈；每类再分确定性 / 推断性。

两条结论：

1. 只有一半会失败：只有 sensors，Agent 会重复犯错；只有 guides，你永远不知道规则有没有生效。
2. 能确定性就别用模型判断：「A test gives the same answer every time and costs nothing to rerun」。推断性 sensor 自身还需要被评估，且应固定 temperature=0。

判据 10：任何「必须 100% 生效」的约束，落在左侧（computational）。落在右侧的规则只是概率性建议。

8.3 Hooks：从建议到强制的机制

官方 Claude Agent SDK 的 hook 事件，按阶段分组（这是目前公开最完整的参考实现）：

Hook 类型：command（shell，JSON 走 stdin/stdout）、http、mcp_tool、prompt、agent。

三个可直接改用的模式

① PreToolUse 拦截危险写操作 官方

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "if echo \"$TOOL_INPUT\" | grep -qi '\\.env'; then echo 'BLOCKED: .env 不允许写入' >&2; exit 2; fi"
      }]
    }]
  }
}

注意 matcher 的边界：只匹配 Write|Edit 时，用 Bash 写 .env 不会触发。要覆盖子进程，必须同时配 sandbox 的文件系统 deny 规则。官方 权限与沙箱是互补的两层：权限管「哪些工具/文件/域名」，沙箱管「OS 级 Bash 与其子进程」。

② PostToolUse 注入失败信号 社区

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{ "type": "command", "command": "npx tsc --noEmit 2>&1 | head -20" }]
    }]
  }
}

社区 Addy Osmani 概括得好："success is silent, failures are verbose"。通过时模型什么都听不到（零延迟），失败时错误文本被注入 loop，模型自纠。

③ Stop 前定义「Done」 社区

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "prompt",
        "prompt": "结束前确认：(1) 测试是否通过？不确定就跑一次。(2) typecheck 是否通过？(3) 是否改动了任务范围外的文件？任一为否，继续工作。"
      }]
    }]
  }
}

判据 11：「Done 必须是一个可判定的状态，不是一种感觉」。没有硬退出条件，Agent 要么过度扩张，要么在测试还是红的时候宣布完成。这与第 15 章 Terminal Bench 2.0 的 self-verification middleware 是同一个机制。

8.4 在 DSH 里的等价物

官方 docs/architecture.md 的扩展点表，可以直接对上：

官方 提醒：waterfall 类监听器必须调用 next() 委托，否则截断流水线——这是写 DSH 插件时最常见的「加了插件后什么都不动」的原因。

8.5 反模式清单

8.6 本章产出与验收

核心产出：一个 settings.json（或 DSH 对应 patch），含至少 1 条 PreToolUse 阻断、1 条 PostToolUse 反馈、1 条 Stop 自检；以及一次「故意违规被拦下」的截图。

验收点：

• 能用 exit code 2 真的阻断一次危险操作，并确认模型收到了阻断原因
• 能解释为什么 matcher 只写 Write|Edit 挡不住 Bash 写文件
• 能把一条现有 AGENTS.md 规则，升级成确定性 hook
• 能说出 waterfall 监听器忘记 next() 会发生什么
• 能指出自己 Harness 里哪条 gate 是多余的

延伸阅读