Antigravity 实战：交付一个真实编码任务

这篇能做出什么

读完并跟着做完，你会得到一条完整的闭环：在一个付费档账号下，把 Gemini 4 Argon 接入 Antigravity，用它把一个小需求拆成三路并行任务，交给多个智能体同时开工，然后走一遍代码评审 → 合并 → 回滚 → 额度盘点。

具体交付物是一个真实可跑的仓库改动，以常见的 Node.js + TypeScript 服务为例：

• 新增 GET /health 端点，返回服务状态、运行时长、时间戳
• 补一组接口测试，npm test 全绿
• 更新 README 的环境变量说明
• 一个用于隔离并行改动的 git worktree 工作流
• 一份可复用的任务卡模板和回滚命令清单

整个过程不依赖任何特定版本号，凡是涉及档位名称、模型开关、额度上限的地方，一律以官方文档和官方页面的当前版本为准。

前置条件清单

动手前把这些准备好，能省掉大半的卡壳时间：

1. 一个可登录的账号，以及可用的付费档订阅。 免费档通常不给高并发或长任务的额度，具体哪个档位包含 Gemini 4 Argon 的调用权限、包含多少额度，看官方订阅页面的当前说明。

2. 一台能装桌面应用的机器。 Antigravity 走的是本地 IDE 路线，需要能开图形界面；纯 SSH 的服务器不适合。

3. 基础工具链： Git、Node.js（LTS 版本）、一个包管理器。用系统自带的或 nvm 装的都行。

4. 一个练习仓库。 建议用一个自己写的、体量不大的仓库。没有的话，五分钟建一个：

```bash

mkdir demo-api && cd demo-api

git init

npm init -y

npm i express

npm i -D typescript tsx vitest supertest @types/express @types/supertest

npx tsc --init

```

5. 至少一次干净的提交。 智能体需要基线来对比 diff，工作区里一堆未提交的改动会让你后面分不清哪些是它写的。

```bash

printf "node_modules/\ndist/\n.env\n" > .gitignore

git add -A && git commit -m "chore: init demo-api"

```

第 1 步：开通付费档，先确认两件事

进入账号的订阅页面，选一个付费档，然后在页面上确认两件事：这个档位能不能选到 Gemini 4 Argon，以及额度是按请求数、按 token，还是按月封顶。

这一步别只看价格。真正影响体验的是限流方式：按 token 计的档位，跑长任务时容易被中途掐断；按请求数计的档位，遇到需要反复读文件的大仓库会吃亏。把额度上限和重置周期记在备忘录里，后面第 9 步要用。

档位名称和权益范围会调整，以官方页面的当前版本为准。

第 2 步：装好 Antigravity 并登录

从官方渠道下载安装包，装完后用同一个账号登录。登录成功后先做一次连通性检查：

1. 打开设置里的模型选项，确认列表里能看到 Gemini 4 Argon。

2. 新建一个空会话，发一句 "回复 ok"，确认有正常返回。

3. 如果模型列表里没有目标模型，先退出重登，再确认订阅是否已生效——订阅状态同步有时不是瞬时的。

不要在 IDE 里硬编码 API Key。需要 Key 的场景，用环境变量：

```bash

export GEMINI_API_KEY="你的密钥"

```

同理，.env 一定要进 .gitignore，避免智能体读文件时把密钥带进上下文。

第 3 步：建工作区，先喂规则文件

在 Antigravity 里打开上一步的仓库目录，把它作为一个工作区。建完工作区别急着派活，先放一个规则文件，告诉智能体这个项目的边界。常见约定是 AGENTS.md 或同类的规则文件，放在仓库根目录：

```markdown

项目约定

技术栈

• Node.js + TypeScript，ESM
• Express 做 HTTP 层，Vitest 做测试

必须遵守

• 不新增运行时依赖，确有必要先说明理由
• 不修改 package-lock.json
• 所有新增文件放在 src/ 下
• 提交前必须跑通 npm test 和 npx tsc --noEmit

常用命令

• 启动开发服务：npm run dev
• 跑测试：npm test
• 类型检查：npx tsc --noEmit

```

这个文件的价值在第 4 步会体现出来：智能体每次开工都会读它，你就不用在每个任务卡里重复讲一遍项目规矩。

第 4 步：把需求写成"可验收"的任务卡

派给智能体的东西，写得像给外包同事的工单，而不是一句"帮我加个健康检查"。任务卡至少写清楚：目标、验收标准、可改范围、禁止事项。

````markdown

任务卡：新增 /health 端点

目标

提供一个无需鉴权的健康检查接口，供负载均衡和监控探活使用。

验收标准

• [ ] GET /health 返回 200
• [ ] 响应体包含 status、uptime、timestamp 三个字段
• [ ] uptime 为进程已运行秒数（数值）
• [ ] timestamp 为 ISO 8601 字符串
• [ ] npm test 全绿
• [ ] npx tsc --noEmit 无报错

可改范围

• src/routes/health.ts（新建）
• src/app.ts（仅注册路由）
• tests/health.test.ts（新建）

禁止

• 不改 package.json 与 lock 文件
• 不引入鉴权中间件
• 不改动其他路由

````

判断任务卡合不合格有个简单标准：如果你把这张卡给一个不熟悉项目的人，他能不能自己判断做完没做完。 能，就说明验收标准写够了。

第 5 步：用 worktree 做隔离，并行派给多个智能体

并行智能体出问题的原因，多半是两个智能体同时改同一个文件。别指望它们自己协调，用 Git 的 worktree 从文件系统层面把工作区隔离开：

```bash

在仓库根目录执行

git worktree add ../demo-api-health -b feature/health-endpoint

git worktree add ../demo-api-tests -b feature/health-tests

git worktree add ../demo-api-docs -b feature/health-docs

```

三个目录各自是独立工作区，互不干扰。然后在 Antigravity 里为三路分别开窗口或会话：

派活时把任务卡整段贴进去，并在末尾加一句约束：

```text

先输出你的实施计划（改哪些文件、每步做什么），等我确认后再动手写代码。

```

这句约束能挡掉不少"自信地改错地方"的情况。三路同时跑起来后，直观感受是并行度上来了，但要注意：并行度越高，冲突概率和额度消耗速度也越高，前期建议两到三路。

第 6 步：盯进度，该接管就接管

智能体跑起来后不要放着不管，重点看三个信号：

1. 它有没有偏离可改范围。 一旦看到它在动 package.json 或删除你原有代码，立刻中止，把 diff 恢复掉。

2. 它是不是在同一个错误上打转。 连续三次尝试同样的失败命令，说明上下文里有误导信息，这时候人工介入比等它自己绕出来快。

3. 中途有没有需要你拍板的选择。 比如"要不要给 /health 加缓存头"，这类决策它不该替你定。

接管的时候直接给具体指令，不要用"再试一次"这种模糊说法。有用的说法是这样：

```text

刚才的失败原因是 tsconfig 的 moduleResolution 配置和 ESM 不匹配。

不要改 tsconfig。改为在 import 语句里补 .js 后缀，然后重跑 npm test。

```

第 7 步：代码评审，先看 diff 再看解释

智能体说"已完成"不等于完成了。评审从 diff 开始，而不是从它的总结开始：

```bash

cd ../demo-api-health

git diff main...feature/health-endpoint --stat

git diff main...feature/health-endpoint

```

按这个清单过一遍：

• 范围：改动的文件是否落在任务卡允许的范围内，有没有顺手改无关代码
• 依赖：package.json 和 lock 文件有没有被悄悄改动
• 边界：/health 有没有被加鉴权、被加了意料之外的缓存
• 测试：测试是真的在断言行为，还是只断言"返回值不是 undefined"这类空话
• 可读性：命名、错误处理、注释是否符合项目原有风格

然后自己手动跑一遍，不要只信它贴的终端输出：

```bash

npm run dev &

curl -s http://localhost:3000/health | jq .

```

期望看到类似这样的结构：

```json

{

"status": "ok",

"uptime": 12.34,

"timestamp": "2025-01-01T00:00:00.000Z"

}

```

测试也要在干净环境里重跑一次：

```bash

npm ci && npm test && npx tsc --noEmit

```

三路都通过后，按依赖顺序合并：先合实现（A），再把测试（B）和文档（C）rebase 到最新主干上合并。

第 8 步：回滚，把代价控制在一次命令内

回滚的关键是动手前就知道怎么退。按改动状态分三种情况：

还没提交，只想丢掉工作区的改动：

```bash

cd ../demo-api-health

git restore .

git clean -fd

```

已经提交但还没合并，想整个放弃这条分支：

```bash

git switch main

git branch -D feature/health-endpoint

git worktree remove ../demo-api-health

```

已经合并进主干，要撤掉某一次提交：

```bash

git switch main

git log --oneline -5 # 找到目标提交的哈希

git revert <commit-hash> # 生成一个反向提交，保留历史

```

用 git revert 而不是 git reset --hard 回滚已推送的历史，原因是前者不会改写公共历史，团队里其他人的分支不会因此断掉。

如果智能体已经动了 lock 文件或者删了你没提交的本地改动，先别急着找它恢复，用编辑器自带的本地历史或 IDE 的时间线功能翻一下，通常比重新生成快。

第 9 步：成本与额度观测

最后回到订阅页面，把这一轮的消耗和产出对一下账。建议每次任务结束后记录四列：

积累几轮之后，你会看出哪些类型的任务值得并行、哪些任务写清楚任务卡之后返工率明显下降。几个通用的省钱习惯：

• 让智能体先给计划再动手。 计划阶段消耗的额度远低于它跑偏之后重来的消耗。
• 小任务不要开并行。 三路并行适合互不重叠的改动；单个文件的改动并行只会制造冲突。
• 上下文只喂必要的。 大仓库先用 AGENTS.md 描述结构，不要让它全量扫描。
• 长任务中途截断。 发现方向不对就中止重发任务卡，比让它跑完再回滚划算。

额度单位、计量方式和重置周期以官方页面为准，不同档位的口径可能不一样。

常见坑与排错

智能体改了任务卡范围外的文件。

说明规则文件没被读到，或任务卡里"可改范围"写得不够具体。检查 AGENTS.md 是否在仓库根目录、格式是否被识别；在任务卡里把允许修改的文件路径逐条列出，不要写"相关文件"。

两路并行改出了冲突。

典型原因是没做 worktree 隔离，或两路任务本身重叠。养成开工前先确认工作目录的习惯，pwd 一下不亏。

测试通过，但手工请求挂了。

测试里用了 mock 覆盖了真实的 Express 实例，或者端口写死导致冲突。要求测试走真实的 app 实例，端口用 0 让系统分配。

命令一直失败但看不出原因。

多半是环境差异：Node 版本、包管理器、依赖没装全。先在终端手动跑一遍同样的命令，确认环境本身没问题，再让智能体接手。

额度突然跑光。

常见于让智能体反复全量读取大文件，或者让它自己跑长时间的构建。给它明确的"只读这几个文件"限制，长命令改由你自己跑。

回滚之后发现本地改动也没了。

git clean -fd 和 git restore . 都会丢掉未提交内容。派活之前先提交一次，是最省事的保险。

下一步建议

跑通这一轮之后，可以从三个方向加深：

1. 把任务卡模板沉淀下来。 把"目标 / 验收标准 / 可改范围 / 禁止事项"做成仓库里的模板文件，下次直接复制填空，返工率会明显下降。

2. 尝试多轮迭代型任务。 比如"重构现有模块并保证测试全绿"，这类任务对规则文件和验收标准的要求更高，是检验工作流是否扎实的好场景。

3. 把 CI 接进来。 在流水线里跑 npm ci && npm test && npx tsc --noEmit，让机器而不是你来当合并前的最后一道闸。智能体再能写，最终把关的仍然是自动化检查和你的评审。