结论先说
- 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 条评论
还没有评论,来抢沙发~