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 条评论

登录 后参与评论

还没有评论,来抢沙发~