# agy Headless 运行

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

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

## 基本用法

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

## 权限处理

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

```sh
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 任务。

常用模式：

```sh
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 路径是：

```text
.antigravitycli/agy_conversations.tsv
```

典型流程：

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

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

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

管理命令：

```sh
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 运行，建议给长任务加上：

```sh
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 位于：

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

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

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

```text
.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 模式更适合明确、可一次性完成的任务。需要长时间交互、逐步澄清需求、
或人工确认风险的任务，仍然更适合交互模式。