agy Headless 运行

agy（Antigravity CLI）可以以 headless / 非交互方式运行。这个模式适合 CI/CD、自动化脚本，或需要把单次任务结果直接写到标准输出的场景。

核心入口是 --print，也可以使用 -p 或 --prompt。它接受一个单次 prompt，运行完成后将结果打印到 stdout，然后退出。

基本用法

agy -p "请读取当前目录下的 package.json 文件，并总结其中的依赖项"

权限处理

在没有交互界面的环境中，文件读写、命令执行等操作可能等待用户授权。受控环境 中可以使用：

agy -p "请检查当前项目的测试失败原因" --dangerously-skip-permissions

--dangerously-skip-permissions 会自动跳过权限确认。它适合隔离的 runner 或可信工作区；不要在不可信仓库、共享机器、或未隔离的自动化环境中默认开启。

常用参数

• --print-timeout：设置 --print 模式的最长等待时间。默认通常是 5 分钟； 复杂任务可以调大，例如 --print-timeout 10m。
• --add-dir /path/to/project：在不切换当前目录的情况下，让 agy 访问额外 工作区。
• --conversation <UUID>：让 headless 任务基于指定历史对话继续执行。
• --continue：让 agy 复用最近一次 conversation。
• --log-file /path/to/log：让 agy 写出底层运行日志，便于排查 headless 任务是否仍在活动。
• --watchdog-timeout 30m：在外层 wrapper 设置 idle timeout；如果 stdout、 agy --log-file 或 transcript 都没有活动，才会终止进程。
• --readme：打印编译期嵌入到 Mix task 中的 README，供 agent 快速读取 当前 task 的完整使用边界。

Mix Task 封装

这个 package 提供 mix agy，用于把常见的 headless agy 交互模式包装成 可重复调用的 headless 任务。

常用模式：

mix agy --readme
mix agy --mode plan /path/to/implementation_plan.md --dry-run
mix agy --mode walkthrough /path/to/walkthrough.md --timeout 10m
mix agy --mode commit-review /path/to/walkthrough.md --skip-permissions
mix agy --conversation-name release-review --log-file auto --mode plan /path/to/implementation_plan.md

--dry-run 只打印将要执行的命令和 prompt，不调用 agy。默认不会传 --dangerously-skip-permissions；只有显式使用 --skip-permissions 时才会启用。

支持的模式包括：

• plan：读取 implementation plan，回答 open questions，并收紧工程边界。
• walkthrough：读取 walkthrough，并对照当前项目状态做实现 review。
• review：通用文件/代码 review。
• refine：精修 Markdown 或设计说明。
• commit-review：review、修复、验证并创建聚焦 commit。
• ask：把文件作为上下文回答额外问题。

Conversation 管理

mix agy 支持把常用的 agy conversation 绑定到当前项目内的稳定名称， 避免每次手动复制 UUID。默认 registry 路径是：

.antigravitycli/agy_conversations.tsv

典型流程：

mix agy --mode plan implementation_plan.md --save-conversation release-review
mix agy --conversation-name release-review --mode walkthrough walkthrough.md

也可以直接复用 agy 自己的最近一次 conversation：

mix agy --continue --mode ask --prompt "继续上一轮 review"

管理命令：

mix agy --list-conversations
mix agy --forget-conversation release-review

--conversation <UUID> 仍然可以直接传原始 UUID；如果传入的值正好是已保存的 名称，task 会先把它解析为对应 UUID。--save-conversation NAME 在真实运行 成功后写入 registry；--dry-run 只打印命令和 prompt，不会修改 registry。

共享日志

为了让外层 wrapper 和使用者同时观察同一次 headless 运行，建议给长任务加上：

mix agy --conversation-name release-review --log-file auto --watchdog-timeout 30m --mode plan implementation_plan.md

mix agy 会默认开启 wrapper audit log。这个日志不依赖 agy 成功初始化 conversation；只要外层进程启动，它就会记录：

• RUN-START、工作目录、命令形状和 watchdog 配置；
• agy 的 stdout/stderr 流；
• 周期性 RUN-WAIT heartbeat；
• agy --log-file 或 transcript 增长时的 RUN-ACTIVITY heartbeat；
• RUN-END、退出码或 watchdog timeout。

默认 wrapper log 位于：

.antigravitycli/logs/<timestamp>-<mode>.run.log

可以用 --run-log PATH 指定路径，或用 --run-log none 关闭 wrapper 日志。

--log-file auto 仍然会额外把 agy --log-file 指向项目内忽略提交的底层日志：

.antigravitycli/logs/<timestamp>-<mode>.log

任务开始前，mix agy 会打印两类可追踪入口：

• Wrapper run log：外层 wrapper 写出的审计日志，最可靠；
• agy log file：由 agy --log-file 写出的底层运行日志，如果启用；
• agy transcript：agy 原生 conversation transcript，通常位于 ~/.gemini/antigravity-cli/brain/<conversation-id>/.system_generated/logs/transcript.jsonl。

这些路径都可以直接用 tail -f 观察。对于明确绑定了 --conversation 或 --conversation-name 的任务，transcript 路径在任务启动前就能确定；对于全新 conversation，先用 --save-conversation NAME 保存，再从 registry 复用。

边界：agy transcript 和 agy --log-file 都属于被观察对象内部日志。如果 agy 在初始化、鉴权、网络请求或 runtime 启动阶段阻塞，它们可能不写入任何 内容。因此长任务应以 wrapper audit log 作为首要观察面，再把 transcript 作为 更细粒度的语义审计。wrapper 的 watchdog 也会把 transcript 和 agy --log-file 的增长视为活动，避免在模型没有 stdout 但仍在读写代码时误杀进程。

使用边界

Headless 模式更适合明确、可一次性完成的任务。需要长时间交互、逐步澄清需求、 或人工确认风险的任务，仍然更适合交互模式。