使用钩子定制 Gemini CLI 以适配你的工作流

Source: Google Developers Blog

请提供您希望翻译的正文内容，我将为您翻译成简体中文并保留原有的格式。

介绍

JAN. 28, 2026

在代理时代，提高效率不仅仅是更快地编写代码；更在于构建能够适应特定环境的定制工具。无论你需要：

• 注入自定义项目上下文
• 强制执行严格的安全策略
• 自动化测试工作流

通用的“一刀切”代理往往难以满足需求。

这正是我们推出 Gemini CLI hooks 的原因——一种强大的新方式来 控制 和 自定义 代理循环，让你在不触碰 Gemini CLI 源代码的前提下，定制其行为。

注意： 原内容引用了一个无法显示的视频。如果你有视频需要嵌入，请使用以下 Markdown 语法：

[![Gemini CLI Hooks Demo](https://img.youtube.com/vi/VIDEO_ID/0.jpg)](https://www.youtube.com/watch?v=VIDEO_ID)

将 VIDEO_ID 替换为相应的 YouTube 标识符。

什么是 Hook？

Hook 是 Gemini CLI 在其生命周期的特定预定义点执行的脚本或程序。可以把它们看作是 AI 助手的“中间件”。通过 Hook，您可以注入在代理循环中同步运行的自定义逻辑，从而实现以下功能：

• 添加上下文 – 在模型处理请求之前插入相关信息（例如最近的 Git 提交、Jira 任务或本地文档）。
• 验证操作 – 在执行可能危险的操作之前进行审查并阻止，循环迭代直至满足要求，提升模型表现。
• 强制策略 – 自动应用全组织范围的安全与合规规则。
• 记录与优化 – 跟踪工具使用情况，并动态调整工具选择，以在提升准确度的同时降低 token 成本。
• 发送通知 – 当 Gemini CLI 处于空闲、等待输入或需要工具确认时发送警报。

通过配置 Hook，您可以根据任何项目的需求定制 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
fi

• 钩子参考 –

什么是 Hook

Hook 为 Gemini CLI 扩展打开了新一波可能性。通过利用生命周期事件（例如 AfterAgent），扩展可以自动修改或扩展 Gemini 的行为。

示例：Ralph 扩展

• 仓库：
• 技术手段： 通过使用 AfterAgent Hook 实现 “Ralph 循环”。
• 工作原理：
  1. Hook 拦截代理的完成信号。
  2. 它将代理强制回到一个持续的、迭代的循环中。
  3. Gemini CLI 在每次尝试之间刷新上下文，防止长时间会话中出现 “上下文腐化”。

结果： Gemini CLI 成为一个 不知疲倦的自主工作者，会一直工作直到任务真正完成。

示例：Galz10pickle‑Rick 扩展

• 链接：
• 技术手段： 一个更严格、迭代的软件开发生命周期版本的 Ralph 循环，融合了角色特色和幽默感。

要点： 通过在扩展中封装 Hook，开发者可以交付复杂的、自我维持的工作流，将 Gemini CLI 从被动助理转变为主动、长期运行的自动化引擎。阅读文档并立即开始构建自己的 Hook‑enabled 扩展吧。

入门

Hooks 在 Gemini CLI 中默认已启用（自 v0.26.0+ 起）。运行以下命令即可更新到最新版本：

npm install -g @google/gemini-cli@latest

想要深入了解并开始构建你的第一个 Hook，请查阅我们的官方文档：

• Hooks 简介 – 核心概念与事件概览。
• 编写你的第一个 Hook – 完整示例。
• Hooks 技术参考 – 每种事件类型的详细输入输出模式。
• 最佳实践与安全 – 性能优化与威胁缓解策略。

今天就动手试试吧，并在我们的 GitHub 仓库 或社交平台上告诉我们你是如何将 Gemini CLI 贴合到工作流中的！

你也可以关注 Gemini CLI 的 X 账号，获取最新新闻和公告。