Hooks 与确定性门禁

提示词是建议，Hook 是程序化门禁。只要某条规则必须执行，就不能只依赖模型记忆。

Hook 适合做什么

• 工具调用前校验参数和路径；
• 文件修改后格式化；
• 任务结束前运行窄范围测试；
• 阻止访问密钥、生产配置和工作区外路径；
• 记录工具调用、审批和退出原因。

生命周期模型

具体事件名随 Harness 不同而不同，设计时应先查官方事件表，再把逻辑映射到本地工具。

一个测试门禁的伪配置

hooks:
  after_file_write:
    - command: gofmt -w ${changed_go_files}
    - command: git diff --check
  before_finish:
    - command: go test ./...
      required: true
  before_tool:
    - command: check-path --inside-workspace ${path}
      on_failure: deny

不要直接把未经转义的模型输出拼到 Shell 字符串中。真实实现必须使用参数数组、允许命令白名单和工作目录约束。

审批门禁

高风险操作应先产生计划，再请求批准：

操作：删除 3 个迁移文件
原因：清理已废弃的实验功能
影响：回滚历史版本可能失败
替代方案：保留文件并增加弃用标记
需要：用户明确批准

审批记录至少包含操作者、时间、目标、参数摘要和结果，不记录密钥原文。

Hook 与 CI 的分工

本地 Hook 提供快速反馈，CI 提供可信的最终门禁。不要把 CI 的唯一安全检查放在一个开发者可以轻易关闭的本地 Hook 中。

常见问题

• Hook 不执行：确认事件名称、配置加载路径和退出码。
• Hook 误拦截：把检查输入和规则版本记录到日志。
• 自动修复循环：限制重试次数，失败后交给人工。
• 生成文件被覆盖：标记生成源文件，禁止直接编辑产物。

练习

1. 为 Java 项目设计“修改实体后必须运行迁移检查”的 Hook。
2. 设计一个最多自动重试两次的格式化失败策略。
3. 列出三项必须由 CI 而非本地 Hook 负责的检查。