Hooks 钩子系统

引言：精细控制 Agent 行为

CodeBuddy 的 Hooks 功能允许你在 AI Agent 执行的关键节点插入自定义脚本，实现对 Agent 行为的精细控制。Hook 机制完全兼容 Claude Code Hooks 规范，提供了一种强大且灵活的扩展方式。

本章将深入讲解 Hooks 的7种事件、配置方法和最佳实践。

---

1. Hooks 核心概念

1.1 什么是 Hooks

官方定义：Hook 功能允许您在 AI Agent 执行的关键节点插入自定义脚本，实现对 Agent 行为的精细控制。

核心价值：

• 工具拦截：在工具执行前后进行验证、修改或阻止
• 上下文注入：在会话不同阶段动态注入额外上下文
• 精细控制：对 Agent 行为进行细粒度的定制

1.2 与 CI/CD 的区别

维度	Hooks	CI/CD
触发时机	Agent 执行关键节点	代码提交/部署
控制对象	Agent 行为	构建/部署流程
配置方式	settings.json	流水线配置

---

2. 七种 Hook 事件

2.1 SessionStart - 会话启动

触发时机：会话开始时（每个新会话只触发一次）

用途：

• 初始化项目环境
• 注入项目特定上下文
• 设置会话级别的配置
• 加载项目规范和文档

输入数据 (stdin JSON):

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.txt",
  "cwd": "/project/path",
  "hook_event_name": "SessionStart"
}

2.2 SessionEnd - 会话结束

触发时机：会话结束时

用途：

• 清理资源
• 保存会话状态
• 生成会话摘要

2.3 PreToolUse - 工具执行前

触发时机：工具执行前

用途：

• 验证工具参数
• 修改工具输入
• 阻止危险操作

输入数据 (stdin JSON):

{
  "session_id": "abc123",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/test"
  },
  "hook_event_name": "PreToolUse"
}

输出控制：

• exit code 0：允许执行
• exit code 1：阻止执行
• exit code 2：阻止执行并显示错误

2.4 PostToolUse - 工具执行后

触发时机：工具执行后

用途：

• 处理工具输出
• 注入额外上下文
• 记录执行日志

输入数据 (stdin JSON):

{
  "session_id": "abc123",
  "tool_name": "Bash",
  "tool_input": {
    "command": "ls -la"
  },
  "tool_output": "total 0\ndrwxr-xr-x  2 user  staff  64 Jan  1 00:00 .",
  "hook_event_name": "PostToolUse"
}

2.5 UserPromptSubmit - 用户输入提交

触发时机：用户提交输入时

用途：

• 预处理用户输入
• 注入额外上下文
• 过滤敏感信息

2.6 Stop - Agent 停止响应

触发时机：Agent 停止响应时

用途：

• 清理资源
• 保存状态
• 生成摘要

2.7 PreCompact - 上下文压缩前

触发时机：上下文压缩前

用途：

• 保存重要上下文
• 自定义压缩策略
• 注入压缩提示

---

3. 配置方法

3.1 配置文件位置

Hooks 配置存储在 .codebuddy/settings.json 文件中：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/script.py",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

3.2 配置字段说明

字段	说明
matcher	正则表达式，匹配工具名
hooks	Hook 数组
type	Hook 类型（command）
command	要执行的命令
timeout	超时时间（毫秒）

3.3 Matcher 匹配

matcher 支持正则表达式，用于匹配工具名：

{
  "matcher": "Bash|Shell"  // 匹配 Bash 或 Shell 工具
}

---

4. 输入输出协议

4.1 stdin JSON 输入

Hook 脚本通过 stdin 接收 JSON 格式的输入数据：

{
  "session_id": "abc123",
  "tool_name": "Bash",
  "tool_input": {
    "command": "ls -la"
  },
  "hook_event_name": "PreToolUse"
}

4.2 stdout JSON 输出

Hook 脚本通过 stdout 返回 JSON 格式的输出：

{
  "permissionDecision": "allow",
  "modifiedInput": {
    "command": "ls -la /safe/path"
  },
  "additionalContext": "This is a safe operation",
  "continue": true
}

4.3 exit code 规范

exit code	含义
0	允许执行
1	阻止执行
2	阻止执行并显示错误

---

5. 实战示例

5.1 阻止危险命令

#!/usr/bin/env python3
import json
import sys

data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "")

# 阻止 rm -rf 命令
if "rm -rf" in command:
    print(json.dumps({
        "permissionDecision": "deny",
        "reason": "Blocked dangerous command: rm -rf"
    }))
    sys.exit(1)

# 允许执行
print(json.dumps({"permissionDecision": "allow"}))
sys.exit(0)

5.2 注入项目上下文

#!/usr/bin/env python3
import json
import sys

data = json.load(sys.stdin)

# 读取项目规范
with open("PROJECT_RULES.md", "r") as f:
    rules = f.read()

print(json.dumps({
    "additionalContext": rules,
    "continue": true
}))
sys.exit(0)

5.3 修改工具参数

#!/usr/bin/env python3
import json
import sys

data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "")

# 自动添加 --safe 参数
if "rm" in command and "--safe" not in command:
    command = command.replace("rm", "rm --safe")

print(json.dumps({
    "permissionDecision": "allow",
    "modifiedInput": {"command": command}
}))
sys.exit(0)

---

6. 最佳实践

6.1 性能优化

• 并行执行：多个 Hook 自动并行执行
• 自动去重：相同命令自动去重，避免重复执行
• 超时控制：设置合理的超时时间

6.2 安全最佳实践

• 最小权限：仅授予必要的权限
• 输入验证：验证所有输入数据
• 错误处理：完善的错误处理机制

6.3 调试技巧

• 日志记录：记录 Hook 执行日志
• 测试模式：先在测试环境验证
• 渐进式部署：逐步启用 Hook

---

7. 常见问题

7.1 Hook 不生效怎么办？

1. 检查配置文件格式是否正确
2. 检查 matcher 是否匹配
3. 检查 exit code 是否正确
4. 查看日志输出

7.2 如何调试 Hook？

1. 先在命令行手动执行 Hook 脚本
2. 检查 stdin 输入是否正确
3. 检查 stdout 输出是否正确
4. 检查 exit code 是否正确

7.3 Hook 会影响性能吗？

• Hook 会增加少量延迟
• 通过并行执行和超时控制优化性能
• 避免在 Hook 中执行耗时操作

---

总结

Hooks 是 CodeBuddy 的精细控制机制，通过在 Agent 执行关键节点插入自定义脚本，实现对 Agent 行为的精细控制。掌握7种事件和输入输出协议，能让你的开发流程更加可控和安全。

金句：Hooks 的核心价值是精细控制——在 Agent 执行的关键节点插入自定义逻辑，实现对 Agent 行为的细粒度定制。