Hooks
Gemini CLI hooks 的事件、配置、JSON I/O、退出码、安全边界和管理命令。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| Hooks | 钩子 | 在事件上自动运行的检查。 |
| 触发事件 | event | hook 挂在哪个生命周期点。 |
| 失败语义 | exit | 返回决定放行 / 阻断。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你为 Gemini CLI 设计一个短小可靠的 Hook。
你是 Gemini CLI Hook 设计顾问。
【角色】
Gemini CLI Hook 设计顾问，按最小够用、安全合规优先的原则给可落地方案，每条结论都落到能照做的步骤或示例，不停留在空泛建议。
【输入】
- 想在什么时机自动检查什么：___
- 触发事件：___
- 不通过该警告还是阻断：___
- 个人还是全 repo：___
- 经验水平：___
【工作流程】
1. 确认适合用 hook
2. 选触发事件和加载位置
3. 设计短小的检查逻辑
4. 写对失败语义
5. 给测试
【输出规范】
▌一、是否适合 hook
▌二、事件 + 加载位置
▌三、检查逻辑
▌四、失败语义 + 测试
【硬约束】
- hook 必须短、可调试、失败明确
- 敏感路径 / 危险命令默认阻断
- 全 repo 的 hook 谨慎
- 不要替我臆测情况或编造不存在的配置，信息不全先问清
- 不确定的配置或接口一律以官方文档为准，禁止照搬过时写法Hooks 是 Gemini CLI agent loop 里的同步拦截点。它允许你在不改 CLI 源码的情况下，注入上下文、校验工具调用、记录审计日志或阻断危险动作。
Hooks 会以当前用户权限执行命令。陌生项目的项目级 hooks 必须先审查，不要直接信任。
典型用途
- 会话开始时加载项目状态。
- 模型请求前补充或过滤上下文。
- 工具执行前检查参数。
- 工具执行后解析结果。
- 对输出做脱敏或审计。
- 按策略禁用部分工具。
常见事件
常见事件包括 SessionStart、SessionEnd、BeforeAgent、AfterAgent、BeforeModel、AfterModel、BeforeToolSelection、BeforeTool、AfterTool、PreCompress、Notification。其中 BeforeTool 和 AfterTool 最常用于工具参数校验、结果过滤和审计记录。
配置位置
优先级从高到低：
- 项目配置：
.gemini/settings.json - 用户配置：
~/.gemini/settings.json - 系统配置：
/etc/gemini-cli/settings.json - extensions 内置 hooks
配置通常写在 hooks.BeforeTool、hooks.AfterTool 等事件下，用 matcher 匹配工具，再指定 hook 的 name、type、command、timeout。安全检查脚本可以放在 $GEMINI_PROJECT_DIR/.gemini/hooks/。
JSON 规则
Hook 通过 stdin 接收 JSON，通过 stdout 返回 JSON。
stdout 只能输出最终 JSON，不能夹杂 echo、日志或调试文本。调试信息写到 stderr。
退出码
0 表示成功且 stdout JSON 会被解析；2 表示系统级阻断，目标动作中止；其他退出码会作为非致命警告处理，原流程通常继续。
管理命令
常用命令包括 /hooks panel、/hooks enable-all、/hooks disable-all、/hooks enable <name>、/hooks disable <name>。
安全边界
Hooks 会以当前用户权限执行任意命令。陌生项目里的项目级 hooks 不能直接信任，尤其不要让 hooks 读取密钥、上传文件或静默执行部署。
| Hook 类型 | 适合做什么 | 不适合做什么 |
|---|---|---|
BeforeTool | 校验命令、路径、MCP 参数 | 大型网络请求 |
AfterTool | 记录审计、解析失败原因 | 修改真实产物 |
BeforeModel | 注入少量上下文 | 拼接大文件 |
AfterAgent | 最终 QA、总结检查 | 高频重活 |
性能和调试
Hooks 是同步执行的，慢 hook 会拖慢 agent loop。高频事件不要做网络请求或大文件扫描；确实需要时，缓存结果并用 matcher 缩小触发范围。只想做最终质量检查时，用 AfterAgent，不要在 AfterModel 的每个输出片段上做重活。
调试 hook 时，先用样例 JSON 手动运行脚本，确认 stdout 是合法 JSON、退出码符合预期。复杂 hook 单独写日志文件，不要把调试文本写到 stdout。
验收方式
至少测试三条路径：允许、阻断、脚本异常。允许路径返回 {"decision":"allow"} 或空 JSON；阻断路径要给出可读原因；脚本异常不能静默放过高风险工具。项目级 hook 被 git pull 改动后，也要确认 CLI 会重新提示信任。
接下来去哪
Headless mode
hooks 稳定后，继续看脚本和 CI 的非交互式运行。
Policy engine
权限边界优先写 policy，hooks 用于补充校验和审计。
Automation
准备把 hooks 放入流水线时，继续看自动化脚本设计。