Antigravity Hooks(hooks.json)生命週期鉤子怎麼配:PreToolUse 攔截與自動 Lint

寫在 GEMINI.md 裏的規則偶爾被忽略怎麼辦?本文按 Google Antigravity 官方文檔詳解 .agents/hooks.json 生命週期鉤子語法、PreToolUse 強制攔截危險命令與 PostToolUse 自動運行格式化腳本。

NNathaniel bigo··原創首發·AI 輔助撰寫
10 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 免費帳號 帳號

結論先說

  1. Rules 是給大模型看的軟約束,Hooks 是由底座確定性執行的硬閘門:把配置文件放在 .agents/hooks.json,無論模型怎麼想,到了指定節點都會雷打不動拉起你的外部腳本。
  2. 工具級事件(PreToolUse / PostToolUse)必須套一層 matcher 正則分組:其餘四類會話級事件(如 SessionStart、PreInvocation)則直接寫平鋪處理器列表,結構不能搞混。
  3. 鉤子腳本通過 stdin 讀入駝峰 JSON,並向 stdout 打印 JSON 結果:PreToolUse 必須返回 decision(可選 allow、deny、ask、force_ask),還能用 overwrite 頂層改寫工具入參;PostToolUse 跑完收尾後輸出 {} 即可。
  4. 想臨時關掉某組鉤子不用刪代碼:在對應頂層鉤子對象裏加一行 "enabled": false 就能一鍵停用。
  5. 帳號配套與跨平台編程訂閱入口:運行 agy 命令行、SDK 與多子代理並發依賴正常可用的谷歌帳號與充裕模型配額,帳號準備見本站 谷歌帳號說明頁,免境外卡開通終端編程會員見 Claude Code 訂閱頁 與 AI 會員充值總覽。

Antigravity 六類生命週期鉤子事件

圖:本站根據 Antigravity Hooks 官方文檔 整理的示意圖

本文根據 Google Antigravity 官方生命週期鉤子文檔(antigravity.google/docs/hooks)整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是軟件介面截圖。本站(bigolab.com)不是 Google 官方網站。

適用於誰

  • 在規則文件裏寫了「每次改完代碼跑 ESLint」「嚴禁執行某類數據庫腳本」,但想把軟提示升級成代碼級硬性強制執行的開發者;
  • 想在智能體調用終端命令前自動攔截高危參數、甚至動態改寫命令參數的團隊技術負責人;
  • 配了 hooks.json 卻報錯或沒觸發,卡在 matcher 層級和 JSON 駝峰字段格式上的人。

一、hooks.json 完整語法與六類事件結構

鉤子配置文件預設放在工作區的 .agents/hooks.json(或本機全局 ~/.gemini/config/hooks.json)。頂層每個鍵名都是你自定義的鉤子組名稱,多個插件或層級的同名事件會按順序合併執行,單個處理器預設超時時間為 30 秒:

json
{
  "block-dangerous-sql": {
    "PreToolUse": [
      {
        "matcher": "run_command",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ./scripts/hooks/guard_cmd.py",
            "timeout": 10
          }
        ]
      }
    ]
  },
  "auto-format-after-edit": {
    "PostToolUse": [
      {
        "matcher": "edit_file|write_file",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ./scripts/hooks/post_lint.py",
            "timeout": 20
          }
        ]
      }
    ]
  },
  "inject-turn-reminder": {
    "enabled": true,
    "PreInvocation": [
      {
        "type": "command",
        "command": "python3 ./scripts/hooks/remind.py"
      }
    ]
  }
}

注意看上面 PreToolUse 和 PreInvocation 的層級差別:只有針對具體工具的 PreToolUse 與 PostToolUse 需要外包一層 {"matcher": "正則", "hooks": [...]}(匹配全部工具寫 "*");其餘事件直接在數組裏放 command 對象。命令的工作目錄固定為 hooks.json 所在的文件夾(Unix 下通過 sh -c 執行,Windows 下通過 cmd /c 執行)。

如果你平時把 Antigravity 與終端主力工具混搭使用,也可以對照閱讀 Antigravity 終端沙箱與權限策略;需要準備合規個人谷歌帳號或開通雙工具編碼會員時,可分別查看 谷歌帳號購買頁 與 Claude Code 訂閱服務。

二、編寫 PreToolUse 攔截腳本與 PostToolUse 自動格式化

配置 PreToolUse 與自動格式化四步

圖:本站根據 Antigravity 官方輸入輸出契約 整理的示意圖

官方文檔特別強調:鉤子腳本從標準輸入(stdin)收到的 JSON 載荷一律採用 camelCase(小駝峰) 命名(例如 conversationId、toolCall、hookEventName、cwd)。下面給出兩個直接可用的腳本示例:

1. PreToolUse:攔截含 DROP TABLE 或強制推送的終端命令

儲存為 scripts/hooks/guard_cmd.py:

python
import sys, json, re

payload = json.load(sys.stdin)
cmd = payload.get("toolCall", {}).get("args", {}).get("CommandLine", "")

if re.search(r"drop\s+table|push\s+--force", cmd, re.I):
    print(json.dumps({
        "decision": "deny",
        "reason": "團隊安全鉤子攔截:禁止通過智能體執行刪表或強制推送命令。"
    }, ensure_ascii=False))
else:
    print(json.dumps({"decision": "allow"}))

除了硬攔截(deny)和直接放行(allow),你還可以返回 "decision": "force_ask"(忽略歷史緩存強制每次彈窗讓開發者點確認),或者附加 "overwrite": {"CommandLine": "改寫後的安全命令"} 對工具頂層參數做淺層覆蓋。

2. PostToolUse:每次改完文件自動跑 Prettier 格式化

儲存為 scripts/hooks/post_lint.py:

python
import sys, json, subprocess

payload = json.load(sys.stdin)
target_path = payload.get("toolCall", {}).get("args", {}).get("Path", "")

if target_path.endswith((".ts", ".tsx")) and not payload.get("error"):
    subprocess.run(["npx", "prettier", "--write", target_path], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)

# 官方契約要求 PostToolUse 向 stdout 輸出空 JSON 對象
print("{}")

記住最後一行 print("{}") 不能省,也不要把格式化工具的雜亂日誌直接打到標準輸出(stdout),否則會破壞底座解析 JSON 返回值的格式要求。常駐代碼風格軟約束怎麼配合撰寫見 Antigravity Rules 規則與預算指南。

常見問題

問:在自定義插件裏放 hooks.json 為什麼沒加載出來?

答:按官方插件規範,原生插件必須把 hooks.json 直接放在插件根目錄(即 plugins/<插件名>/hooks.json),放在子文件夾 hooks/hooks.json 下不會被運行時自動發現。

問:腳本里的 cwd 字段和腳本實際運行的當前目錄是一回事嗎?

答:不一樣。進程運行時的工作目錄是 hooks.json 所在的目錄(方便你用相對路徑調旁邊的輔助文件);而 stdin JSON 裏傳進來的 "cwd" 字段才是智能體當前操作的目標代碼目錄。

問:在 agy 命令行裏怎麼快速查看當前掛載了哪些鉤子?

答:啟動終端 agy 後直接輸入斜槓指令 /hooks 即可查看和管理當前生效的鉤子列表;三種客戶端的安裝與入口差別見 Google Antigravity 下載與形態介紹。

問:如果鉤子腳本本身寫錯了拋出異常或者超過 30 秒沒返回會怎樣?

答:當腳本超時(預設 30 秒,可在處理器裏通過 timeout 字段按秒調整)或向標準輸出打印了非合法的 JSON 文本時,底座會判定該鉤子執行出錯並在步驟結果中記錄異常,可能導致被保護的工具調用無法正常繼續。上線團隊共享鉤子前,建議先在終端手動用 echo '{"toolCall":{"name":"run_command","args":{"CommandLine":"ls"}}}' | python3 ./scripts/hooks/guard_cmd.py 自測一遍輸出是否為合法單行 JSON。

問:跑多子代理和終端工具時沒有合規谷歌帳號或海外信用卡怎麼辦?

答:可在 本站充值中心 通過支付寶、微信支付或 AlipayHK 即買即發獲取 谷歌電郵成品號,或免上號自助兌換 Claude Pro 自助卡密 與 Claude Max 充值,實時價格與售後邊界(封號不在質保範圍)以對應商品頁為準。

相關教學

Nathaniel 的更多內容

  1. 01

    獨立開發者用 ChatGPT + Codex 跑通產品全流程:市場驗證、PRD、原型到代碼上線覆盤清單

    單人做獨立產品最容易陷入「閉門寫兩個月代碼上線零用戶」或「AI 寫到一半目錄越改越崩」。本文整理「ChatGPT 負責市場驗證、PRD 與覆盤 + Codex 負責工程實現與測試」的五階段雙軌流程,附起手提示詞與 7 項上線覆盤清單。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成規範文件命名規則、整理混亂目錄樹與合併零散發票抬頭清單腳本

    面對滿桌面的「新建文件夾」「最終版2」和上百張零散電子發票,手工改名抄台帳耗時又容易漏重。本文分享先脫敏取樣、再用 ChatGPT 生成帶預演和回滾日誌的本地 Python 腳本,離線安全完成目錄整理與發票抬頭合併去重的實戰流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外電郵營銷(EDM)受眾分層文案、A/B 主題行測試與防進垃圾箱自檢

    做海外獨立站或出海 SaaS 電郵營銷(EDM),最怕千人一面群發被直接送進垃圾箱。本文結合 Gmail/Yahoo 批量發件人規範,梳理用 ChatGPT 設計受眾分層文案、批量生成 A/B 主題行矩陣並開展發前垃圾詞與合規自檢的實戰提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫 Notion Formula 2.0 公式、Obsidian Dataview 查詢與 Airtable 自動化腳本

    給 Notion 數據庫寫多條件 Formula 2.0 公式、給 Obsidian 寫 Dataview 動態看板,或在 Airtable 裏寫自動化腳本,經常因為一個小括號或類型不匹配報錯半天。本文整理三大工具的通用上下文喂料規範與三套直接可複製的生成提示詞。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 處理複雜 JSON / YAML / XML 字段映射、格式轉換與校驗規則編寫實戰

    對接第三方 API、遷移 Kubernetes 配置或解析政企 XML 報文時,手工對照幾百行嵌套字段既慢又容易漏掉空值與類型邊界。本文整理用 ChatGPT 完成字段映射表梳理、生成確定性轉換腳本以及編寫 JSON Schema / Pydantic / XSD 校驗規則的實戰流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 準備本科/碩士畢業論文答辯:提煉答辯 PPT 結構、模擬導師犀利追問與 3 分鐘自述稿

    畢業論文寫完後,要在 3–5 分鐘內講清研究價值並頂住答辯評委的連環追問並不輕鬆。本文整理在嚴格遵守高校學術規範的前提下,用 ChatGPT 提煉答辯 PPT 結構、打磨 3 分鐘口語自述稿並開展模擬導師犀利追問的排練流程與提示詞。

    ChatGPT0

同產品的其他教學

  1. 01

    用 ChatGPT 速讀英文產品手冊、開源文檔與 GitHub Issue 並沉澱團隊中文內訓手冊

    團隊引入海外 SaaS 工具或開源框架時,全英文文檔晦澀冗長、真正的坑全藏在幾十頁 GitHub Issue 討論裏。本文分享速讀拆解英文手冊、歸類 Issue 排障庫以及重構團隊中文內訓 SOP 的完整實戰流程。

    ChatGPT其他 AI 工具0
  2. 02

    用 ChatGPT 寫油猴腳本(Tampermonkey)與瀏覽器書籤小工具解決網頁繁瑣重複操作實戰

    每天在後台系統裏重複勾選幾十個複選框、手工複製網頁表格或清理遮擋閱讀的側邊欄,既枯燥又浪費時間。本文分享不會寫 JS 也能用 F12 配合 ChatGPT 寫出油猴腳本與書籤小工具的完整實戰流程。

    ChatGPT其他 AI 工具0
  3. 03

    用 ChatGPT 寫高質素 SQL 窗口函數(RANK / LAG / SUM OVER)做留存與漏斗分析實戰

    做用戶留存率、復購間隔與有序轉化漏斗時,多層自連接既難讀又拖垮數據庫,窗口函數則是高效解法。本文整理數據庫方言喂數規範、CTE 分層提示詞以及用內置沙盒先驗證再上線的完整實戰流程。

    ChatGPT其他 AI 工具0
  4. 04

    ChatGPT 連接 Canva、Figma、Linear、Jira、Dropbox 等第三方應用搜不到數據或授權失效怎麼辦

    在 ChatGPT 接入 Canva、Figma、Linear、Jira 或 Dropbox 後,明明顯示已連接卻搜不到文件工單,或老提示授權失效怎麼辦?本文拆解帳號錯綁、OAuth 範圍漏選、權限繼承與管理員攔截 5 步排障法。

    ChatGPT其他 AI 工具0
  5. 05

    Anthropic Contextual Retrieval(上下文增強檢索)是什麼、怎麼實現:給文檔塊自動補背景摘要結合緩存降失誤率

    長文檔切成小塊後丟了公司名、年份和主語指代導致 RAG 頻頻搜錯?本文按 Anthropic 官方技術文章詳解 Contextual Retrieval 原理、官方公開評測失誤率下降 49% 至 67% 的組合架構,以及用 Claude 提示詞緩存低成本批量生成切片背景的完整 Python 代碼。

    Claude其他 AI 工具0
  6. 06

    RAG 知識庫回答不準怎麼調優:切片大小(Chunking)、BM25 + 向量混合檢索與 Rerank 重排序三步排查法

    搭好的 RAG 企業知識庫一問具體型號、報錯碼或跨行表格就答非所問?本文按 OpenAI 與 Anthropic 官方檢索文檔,給出先隔離檢索與生成故障、再按結構化切片(Chunking)、BM25 加向量混合召回(RRF)與 Rerank 重排序逐層調優的三步法。

    Claude其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~