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

圖:本站根據 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 自動格式化

圖:本站根據 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 充值,實時價格與售後邊界(封號不在質保範圍)以對應商品頁為準。
0 條評論
還沒有評論,來搶沙發~