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 放入流水線時，繼續看自動化指令碼設計。