使用钩子将 Gemini CLI 定制为你的工作流
Source: Google Developers Blog
2026年1月28日
Tailor Gemini CLI to Your Workflow with Hooks
在代理时代，提高效率不仅仅是更快地编写代码；更在于构建能够适应您特定环境的自定义工具。无论您需要：
- 注入自定义项目上下文
- 强制执行严格的安全策略
- 自动化测试工作流
通用的“一刀切”代理往往难以满足需求。
这就是我们推出 Gemini CLI hooks 的原因——一种强大的新方式，能够 控制 并 自定义 代理循环，让您在不触碰源码的情况下，定制 Gemini CLI 的行为。
视频演示: (Insert video embed or link here)
什么是 Hook？
Hooks 是脚本或程序，Gemini CLI 在其生命周期的特定预定义点运行它们。把它们想象成 AI 助手的“中间件”。通过 hooks，您可以在代理循环中同步注入自定义逻辑，从而能够：
- 添加上下文 – 在模型处理请求之前插入相关信息（例如最近的 Git 提交、Jira 任务或本地文档）。
- 验证操作 – 在执行可能危险的操作之前进行审查并阻止，循环直至满足要求，提升模型性能。
- 强制策略 – 自动应用全组织的安全和合规规则。
- 记录与优化 – 跟踪工具使用情况并动态调整工具选择，以在提升准确性的同时降低 token 成本。
- 发送通知 – 当 Gemini CLI 处于空闲、等待输入或需要工具确认时收到警报。
通过配置 hooks，您可以将 Gemini CLI 定制为任何项目的需求。当事件触发时，CLI 会暂停，直至您的 hook 完成，确保始终遵循您的自定义逻辑。这为在 Gemini CLI 之上以任何方式构建提供了可能。
引人注目的示例：自动化机密扫描
钩子最实用的用途之一是创建安全防护网。借助 BeforeTool 钩子，你可以阻止 AI 意外将敏感数据（如 API 密钥或密码）写入代码库。
要查看 Gemini CLI 中所有可用的钩子事件类型，请参考官方文档。
钩子脚本（.gemini/hooks/block-secrets.sh）
#!/usr/bin/env bash
# Read hook input from stdin
input=$(cat)
# Extract content being written using jq
content=$(echo "$input" | jq -r '.tool_input.content // .tool_input.new_string // ""')
# Check for common secret patterns
if echo "$content" | grep -qE 'api[_-]?key|password|secret|AKIA[0-9A-Z]{16}'; then
# Return structured denial to the agent
cat <<EOF
{
"action": "deny",
"reason": "Potential secret detected"
}
EOF
fi阅读更多： 扩展文档 – 钩子
钩子可以实现的功能
- 自动化 – 在 Gemini 工作流的关键节点自动运行自定义逻辑。
- 可扩展性 – 将可复用的行为打包进扩展本身。
- 零配置 – 安装扩展后会自动注册其钩子。
实际案例
| 扩展 | 使用的钩子 | 功能说明 |
|---|---|---|
| Ralph – 病毒式 “Ralph 循环” | AfterAgent | 拦截代理的完成信号并强制持续的迭代循环，使 Gemini 在处理棘手问题时保持工作并在每次尝试之间刷新上下文。 |
| galz10pickle‑rick – 带有软件开发生命周期的 Ralph 循环 | AfterAgent（以及其他） | 实现更结构化的迭代开发流程，在保持相同循环机制的同时加入角色和幽默元素。 |
为什么这很重要
钩子将 Gemini CLI 从 被动助理 转变为 不知疲倦的自主工作者，能够：
- 持续攻克困难任务。
- 在迭代之间自动刷新上下文。
- 遵循自定义工作流（例如开发生命周期、数据处理管道）。
通过在扩展中嵌入钩子，开发者可以交付复杂的即插即用自动化功能，提升 Gemini 的能力，而无需用户额外操作。
入门
Hooks 在 Gemini CLI 中默认启用，版本 v0.26.0+ 起。通过运行以下命令更新到最新版本：
npm install -g @google/gemini-cli@latest想深入了解并开始构建你的第一个 hook，请查阅我们的官方文档：
- Introduction to hooks – 核心概念和事件概览。
- Writing Your First Hook – 完整示例。
- Hooks Technical Reference – 每种事件类型的详细输入输出模式。
- Best Practices & Security – 性能优化和威胁缓解策略。
今天就动手试试吧，并在我们的 GitHub 仓库 或社交平台上告诉我们你是如何将 Gemini CLI 适配到工作流中的！
你也可以关注 Gemini CLI on X，获取最新动态和公告。