# Hooks 入门指南

学习如何通过注册 shell 命令来自定义和扩展 CodeBuddy Code 的行为

> 建议先阅读 [Hook 参考指南](./hooks.md)，了解所有事件、输入输出结构与安全要求。本指南聚焦于实际操作演练与常见示例，帮助你迅速在 CodeBuddy Code 项目中启用 Hooks 功能。
> **注意**：Hook 功能目前处于 **Beta** 阶段，仍在持续打磨，请留意后续版本更新。

name: code-reviewer
description: 代码审查 Skill，执行前检查 Bash 命令白名单
context: fork
agent: Explore
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: ${CODEBUDDY_SKILL_DIR}/scripts/check-bash.sh
          timeout: 5
  Stop:  # 自动重写为 SubagentStop
    - hooks:
        - type: command
          command: echo "review done at $(date)" >> ${CODEBUDDY_PROJECT_DIR}/.cbc-review.log
---

请审查 $ARGUMENTS 涉及的代码...
```

**启用前**：在 `~/.codebuddy/settings.json` 中开启闸门（默认关闭，所有非内置来源的 frontmatter hooks 都会被静默跳过）：

```json
{
  "allowUntrustedFrontmatterHooks": true
}
```

更详细的字段语义、安全闸门与作用域规则见 [Skills 文档 - 在 Skill 中配置 Hooks](./skills.md#在-skill-中配置-hooks) 与 [Hook 参考指南 - Frontmatter Hooks](./hooks.md#agent--skill-frontmatter-hooks)。

## 最佳实践与建议

1. **小步验证**：先从日志类 hook 入手再逐步添加高风险操作。
2. **控制超时**：默认 60 秒，如脚本存在长时间任务请确保及时输出或拆分处理。
3. **使用 matcher 过滤**：合理设置 `matcher` 可减少无关 hook 执行次数。
4. **统一脚本目录**：建议在项目根创建 `.codebuddy/hooks/` 目录集中管理脚本并纳入版本控制。
5. **重视安全**：
   * 避免在 hook 中直接使用未验证的用户输入。
   * 对外部命令使用绝对路径，防止 PATH 劫持。
   * 结合 `/hooks` 面板的安全确认机制，确保所有 hook 均被审核运行。
6. **与 MCP 工具配合**：MCP 工具名称形如 `mcp__<server>__<tool>`,可在 `matcher` 中通过正则整批控制,如 `mcp__github__.*`。
7. **面板是权威入口**：任何外部文件修改都需要在面板确认后生效，务必完成该步骤。
8. **Python 脚本调用**：始终使用 `python3 your_script.py` 而不是直接执行 `.py` 文件，因为 Windows Git Bash 环境下不一定能正确识别 Python 脚本的 shebang 行。
9. **Windows 兼容性**：Hook 命令在 Windows 上通过 Git Bash 执行。请确保命令使用 bash 语法，且避免依赖 cmd.exe 或 PowerShell 特有的语法。

## 了解更多

* 关于 hooks 的参考文档，请参阅 [Hook 参考指南](./hooks.md)。
* 有关全面的安全最佳实践和安全指南，请参阅 Hook 参考指南中的[安全注意事项](./hooks.md#安全注意事项)。
* 有关故障排除步骤和调试技术，请参阅 Hook 参考指南中的[调试](./hooks.md#调试)部分。

---

现在你已掌握在 CodeBuddy Code 中启用 hooks 的核心流程。更多事件字段细节、决策控制和安全注意事项请查阅 [Hook 参考指南](./hooks.md)。祝你构建出既强大又安全的自动化工作流！
