Antigravity agy 无头审查调用实战:second-opinion 技能中的 Antigravity 代码审查指南

原创2026-10-09 18:23:331,927 阅读
文章标签:AI 技能/插件人工智能应用安全静态分析SAST漏洞扫描

Antigravity agy 无头审查调用实战:second-opinion 技能中的 Antigravity 代码审查指南

导读

本文围绕 Trail of Bits second-opinion 技能中的 Antigravity 调用路径,完整解析 agy CLI 的 print(无头)模式命令、模型选择与回退策略、参数大小限制、权限边界以及结果可靠性判定,并对照仓库中的 SKILL.md、review-input.md 等文档给出可复制的实战方案。读完本文,你将掌握如何用 agy 对未提交变更、分支 diff 和指定 commit 发起外部独立代码审查,并在失败时准确区分"审查失败"与"审查完成但无发现"。

背景:Antigravity 在 second-opinion 技能中的位置

second-opinion 是 skills 仓库 中提供独立外部代码审查的 Claude Code 技能,支持 OpenAI Codex、Google Antigravity 与 Gemini CLI 三条审查路径。其中 Antigravity(可执行文件为 agy)是未指定 Google CLI 时的默认路径,这一点在 SKILL.md 中明确:技能会优先选择 Antigravity,只有用户显式指定 Gemini CLI 时才走 Gemini 路径;若 Gemini 账号返回 UNSUPPORTED_CLIENT,则说明该账号已迁移至 Antigravity,需征得用户同意后再切换 CLI。

本技能的核心定位是产出审查发现(findings),不应用修复、不把审查结果发布到远程服务。Antigravity 路径通过 agy 的 print 模式以散文(prose)文本形式返回审查结果,与 Codex 的 JSON 结构化结果形成互补。同一份捕获的 diff 会同时发送给两个 provider,以保证对比覆盖相同的变更内容(见 review-input.md)。

核心调用命令:agy print 模式

Antigravity 的调用方式由 antigravity-invocation.md 给出。前提是 prompt_file(提示词文件)、output_file(输出文件)与 stderr_log(诊断日志文件)已经用 mktemp 在 checkout 目录之外创建完毕,然后以单个加引号参数的形式把准备好的 prompt 传入:

PATH="$HOME/.local/bin:$PATH" agy \
  --model gemini-3.1-pro-high \
  --output-format text \
  --disable-slash-commands \
  -p="$(cat "$prompt_file")" \
  > "$output_file" 2> "$stderr_log"

这条命令的要点逐条拆解如下:

  • PATH="$HOME/.local/bin:$PATH":agy 默认安装在用户本地 ~/.local/bin 目录下,先将其加入 PATH 再执行,避免出现"Executable missing"(找不到可执行文件)的假失败。
  • --model gemini-3.1-pro-high:显式指定默认模型。默认模型是 gemini-3.1-pro-high;如果用户显式指定了某个模型,必须保留用户的模型选择,不能擅自改回默认值。
  • --output-format text:以文本格式输出,足够满足本技能"散文式审查对比"的需求。
  • --disable-slash-commands:禁用斜杠命令展开,防止 prompt 中携带的 diff 内容被误解析成 CLI 斜杠命令。
  • -p="$(cat "$prompt_file")":把 prompt 文件内容作为单个参数传入。注意 -p= 与它的值之间不能有空格,且 -p= 要放在其他 flags 之后。
  • 重定向 > "$output_file" 2> "$stderr_log":标准输出(审查结果)与标准错误(诊断信息)分离保存,便于后续分别读取。

关于 flag 位置有一个严格的语法约束:-p= 必须保持与值紧贴(attached),其余 flags 放在它之前。这与 Gemini 路径的 --prompt + stdin 传参方式不同——Antigravity 走的是参数形式。

模型选择与回退:agy models

agy 的默认模型是 gemini-3.1-pro-high,但不同账号可访问的模型集合可能不同。当默认模型不可用时:

  1. 不要猜测:直接运行 agy models 列出当前账号可以访问的全部模型。
  2. 从列表中选择一个可用模型替代默认值,并在结果中披露实际使用的模型。
  3. 若用户显式指定了模型但该模型不可用,则报告失败并请求用户提供替代模型,而不是悄悄换模型。

这一点与 Codex 路径的处理逻辑一致:Codex 在默认模型不可用且用户未锁定模型时,允许重试一次 gpt-5.6 并披露替换;而显式指定的模型不可用属于模型授权(entitlement)失败,需要请求替换(见 codex-invocation.md)。Antigravity 路径同样遵循"默认可替换、显式须确认"的原则。

版本兼容性与 stdin 模式的演进

原文档明确记录了一个重要的兼容性事实:上述参数形式在之前测试过的 CLI 1.1.21 上同样可用。这意味着只要环境安装的是该版本或更新版本,-p= 参数形式就是可靠的调用方式。

同时需要注意能力的演进:当前 Antigravity 无头模式(headless mode)的官方文档已支持 stdin 输入和 schema 强制,因此旧客户端在 stdin 和 JSON 方面的限制不应再被视为当前版本的既定约束。换句话说:

  • 若旧资料声称"agy 不支持 stdin 或 JSON 输出",那是针对旧版本的历史限制,不代表当前行为;
  • 本技能仅需文本输出(--output-format text)即可完成审查对比,无需扩展插件。

参数大小限制:不要丢弃 patch 内容

命令行参数受操作系统参数大小上限约束。当 prompt 作为参数传入时,如果提示词(通常包含完整 diff)超过系统参数大小限制,处理原则是:

  1. 优先改用已安装版本官方文档所支持的 stdin 模式,把 prompt 通过 stdin 喂给 agy;
  2. 或者请求缩小审查范围(如只审查部分文件、缩小 diff);
  3. 严禁为省空间而删减 patch 文件中的内容——被丢弃的变更将导致审查覆盖不全,产生虚假的"无发现"结论。

权限设置:不用 plan 模式,不跳过权限检查

Antigravity 路径的权限原则非常明确:

  • 在最终响应中请求审查发现,不要在中间过程创建计划(plan)产物;
  • 不要使用 plan 模式,也不要使用 --dangerously-skip-permissions 这类跳过权限的开关;
  • 保留用户的权限设置。无头模式本身并不会让工作区变成只读——它只是取消了交互提示,不等于自动获得了对工作区的全部访问权。

如果审查过程中需要执行命令或读取文件而权限不足,这属于审查覆盖缺口(coverage gap),应如实上报,而不能通过开启自动批准来强行跑完审查(SKILL.md 同样强调"不要为了跑审查而开启写入自动批准")。

结果可靠性判定:exit code 不等于审查完成

这是 Antigravity 路径最关键的经验教训:

当前无头模式下,agy 可能在拒绝某个工具调用后仍然以退出码 0 正常退出。

因此:

  • 仅凭退出码为 0 不能证明审查已完成,必须同时读取 output_file(结果)与 stderr_log(诊断);
  • 若输出缺失、工具被拒、上下文不完整,应作为覆盖缺口上报;
  • "创建了计划产物"或"请求用户批准继续"都不是完成的审查——只有最终响应中返回了审查发现才算完成。

这一判定标准与 SKILL.md 的全局要求一致:非零退出码、输出缺失、无效 JSON、权限拒绝导致无法检查、请求批准计划等,都算未完成的审查,应报告失败与部分结果;仅对已诊断出可恢复原因的情况重试,不要在鉴权或配额失败后循环切换 provider。

失败处理速查表

原文档给出了 Antigravity 路径的失败响应表,完整继承如下:

失败类型 标准响应
可执行文件缺失 检查 ~/.local/bin 目录,然后报告 CLI 官方安装指南(Getting Started)中的安装步骤
空 prompt 使用上文所述紧贴的 -p= 参数形式传入
未知模型 用 agy models 列出可用模型,并请求用户指定替代模型
鉴权、配额或超时错误 报告失败,并保留任何部分输出

结合 README.md 可知,Antigravity 的安装与鉴权走官方 CLI 安装指南,可执行文件为 agy。若缺失可执行文件或账号未配置,属于一次失败的审查尝试:当同时请求了 Codex 与 Antigravity 两个 provider 时,应继续使用可用的一方,并明确标识被跳过的一方。

实战整合:从 diff 捕获到结果上报的完整流程

将上述要点串联起来,一次完整的 Antigravity 审查包含四个阶段:

阶段一:捕获变更(复用共享的 diff) 在仓库根目录运行 Git 命令生成 patch 文件,并包含未跟踪文件。核心命令在 review-input.md 中给出:

范围 Patch 命令
未提交的跟踪变更 git diff --no-ext-diff --no-textconv HEAD --,再追加未跟踪文件
分支对已解析基线的对比 git diff --no-ext-diff --no-textconv "$base"...HEAD --
指定的已解析 commit git show --format= --root --first-parent --no-ext-diff --no-textconv "$commit" --

未跟踪文件用 NUL 分隔列表(git ls-files --others --exclude-standard -z)配合 git diff --no-index -- /dev/null "$file" 逐个追加,这样路径中的空格与换行都不会丢失(详见 review-input.md)。临时文件全部放在 checkout 之外,确保"审查自己的输出"永远不会混入未提交变更。

阶段二:构造 prompt 文件 prompt 文件包含审查指令、用户指定的 focus(安全/性能等)、适用的项目约定与捕获的 diff,并按"用户需求 → 项目约定 → diff"的顺序加清晰标签。对 Antigravity 文本审查,额外要求评估材料并主动说明何时需要更多上下文(见 review-input.md)。写入 prompt 时应使用文件写入工具或加引号的 heredoc,绝不把 diff 文本粘贴进会展开的 shell 命令。

阶段三:执行 agy 调用 以单引号参数形式执行前文的命令。若两个 provider 都被请求,且工具接口支持并发,则并发运行;前台 Bash 审查时设置 timeout: 600000 以允许最多十分钟,有后台执行或轮询能力时优先使用以保持进度可见(SKILL.md)。注意 shell 变量不跨调用持久化,后续调用需把变量重新赋值为已保存的文件路径。

阶段四:读取结果并判定成败 同时读取 output_file 与 stderr_log。只有确认最终响应中携带了审查发现,才算完成;缺失上下文或检查被拒按覆盖缺口上报。展示结果时标注 provider、实际使用的模型、严重级别、文件与行号、影响以及建议的修正,低严重级别缺陷也要保留可见。

与其他 provider 路径的协同

second-opinion 的三条路径共享同一份捕获的 diff 与同一套"完成才算完成"的判定哲学,但调用方式不同,选型建议如下:

Provider 调用方式 输出形态 备注
Antigravity(agy) print 模式,-p= 参数传 prompt 散文文本 未指定 Google CLI 时的默认路径;无需扩展
Gemini CLI(gemini) --prompt + stdin 传 prompt 散文文本 仅限仍支持的账号;UNSUPPORTED_CLIENT 时迁移到 Antigravity
Codex(codex exec) stdin 传 prompt,--output-schema 强约束 JSON 结构化发现 无需 MCP server;sandbox 只读 + --ephemeral

Gemini 路径的细节见 gemini-invocation.md,Codex 路径见 codex-invocation.md。三者共同的纪律是:保留用户显式指定的模型与权限设置,绝不通过跳过权限或删减 patch 来换取一次"看似成功"的审查。对两份完成的审查做对比总结时,应指出一致与分歧之处,但不能把一致视为正确性的证明,且需区分外部发现与你自行补充的评估。

登录后查看全文
skills