安装登录与第一次任务：提问、修 Bug、审阅 diff、提交

为什么是 Antigravity CLI

Antigravity CLI（命令名 agy）是 Google Antigravity 平台的终端形态，和 Antigravity 2.0 桌面端、IDE 共用同一套 Agent 引擎。Google 官方说明：自 2026 年 6 月 18 日起，个人 Google 账号、Google AI Pro 与 Ultra 用户不能再用「Login with Google」登录 Gemini CLI，官方建议迁移到 Antigravity 系列。原来用 Gemini CLI 的个人用户，现在就该学这一个。

你将得到什么

• 一个能在终端直接运行的 agy 命令，并用 agy --version、agy --help、agy models 验证
• 已登录的 Antigravity CLI（Google 账号或 Gemini API Key 二选一）
• 一个练习用的 Python 小项目，以及 agy 帮你读代码、跑测试、修 Bug、审阅改动、提交 Git 的完整一轮

开始前准备

• 账号（二选一）：
  • Google 账号：免费账号即可用，配额每周刷新；Google AI Pro / Ultra 配额更高，每 5 小时刷新、另有周上限（见官方 Plans 页）。账号须年满 18 岁并通过年龄验证。
  • Gemini API Key：在 Google AI Studio 创建，请求直接走 Gemini API、按 API 计费，适合脚本与 CI。
• 地区：Antigravity 只在官方 FAQ 列出的国家和地区可用（2026-10-08 核对：中国大陆、香港、澳门不在列表中）。以 Google 服务条款页上显示的账号所属国家为准。
• 系统：macOS、Linux、Googlebook 或 Windows（PowerShell / CMD）。
• 工具：git 与 python3。本课练习只用 Python 自带的 unittest，无需安装依赖。

核心事实（先记住）

步骤 1：安装 Antigravity CLI

按你的系统任选其一。

macOS、Linux、Googlebook：

curl -fsSL https://antigravity.google/cli/install.sh | bash

Windows PowerShell：

irm https://antigravity.google/cli/install.ps1 | iex

Windows CMD（行尾的 ^ 是 CMD 续行符，两行一起粘贴）：

curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd ^
  && install.cmd && del install.cmd

安装脚本会读取最新版本号、下载并校验安装包，然后把二进制放好。编辑部 2026-10-08 在 Linux 上实测的关键输出：

✓ Latest available version: 1.3.1
✓ Download complete and checksum verified.
✅ Antigravity CLI binary placed successfully at /home/you/.local/bin/agy

升级：重新运行同一条安装命令即可，CLI 也带有 agy update 子命令。官网 changelog 页面会稍晚于实际发布，版本号以 agy --version 为准。

步骤 2：验证安装

新开一个终端窗口再执行：

agy --version

对照结果（数字会随更新变化）：

1.3.1

再看一眼帮助，确认后面要用到的参数都在：

agy --help

对照结果（节选，为便于阅读压缩了列宽并截短了说明）：

Usage of agy:
  -c               Short alias for --continue
  --dangerously-skip-permissions
                   Auto-approve all tool permission requests
  --mode           Set the agent execution mode for this session
                   (accept-edits, plan)
  --model          Model for the current CLI session
  --output-format  Output format for print mode
                   (text, json, stream-json) (default text)
  -p               Short alias for --print
  --sandbox        Run in a sandbox with terminal restrictions enabled

同一份帮助的末尾还会列出子命令，如 models、mcp、plugin、update、changelog。

如果提示 agy: command not found，说明 ~/.local/bin 不在 PATH 中。把下面这行加到 ~/.bashrc 或 ~/.zshrc 末尾，再重新加载：

export PATH="$HOME/.local/bin:$PATH"

source ~/.zshrc

（用 bash 的话把最后一条换成 source ~/.bashrc。）

步骤 3：登录

方式 A：Google 账号（推荐个人使用）

在任意目录运行：

agy

• 本机：CLI 先尝试读取系统钥匙串（macOS 钥匙串、Linux Secret Service、Windows 凭据管理器）里已保存的登录信息；没有就自动打开浏览器，登录 Google 账号即可。
• SSH 远程机器：CLI 无法打开浏览器，会打印一个 https://accounts.google.com/... 授权链接。把链接复制到你本机浏览器打开并登录，页面会显示一串授权码，复制回远程终端粘贴并回车。

远程机器上看到的提示类似这样（链接很长，这里省略）：

Authentication required. Please visit the URL to log in:
  https://accounts.google.com/o/oauth2/auth?...
Waiting for authentication (timeout 60s)...
Or, paste the authorization code here and press Enter:

退出登录在会话里输入 /logout，它会清掉钥匙串中的令牌。

方式 B：Gemini API Key（适合脚本与 CI）

只设环境变量不会生效，必须同时在设置文件里指定提供方。

第一步，写入设置文件（文件已存在时，只需把 "modelProvider": "gemini" 加进现有 JSON）：

mkdir -p ~/.gemini/antigravity-cli
echo '{ "modelProvider": "gemini" }' > ~/.gemini/antigravity-cli/settings.json

第二步，导出 Key（在 https://aistudio.google.com/app/api-keys 创建）：

export GEMINI_API_KEY="你的-api-key"

第三步，运行 agy。界面顶部原本显示账号邮箱的位置会显示 Gemini API key。

注意三点：

• CLI 只读环境变量 GEMINI_API_KEY，GOOGLE_API_KEY 和 .env 文件都不会被读取。
• 设置了 modelProvider 却没导出 Key 时，CLI 直接退出。编辑部实测的报错原文：

modelProvider is set to "gemini" in settings.json, but the GEMINI_API_KEY environment variable is not set. Set GEMINI_API_KEY to your Gemini API key, or remove "modelProvider" from settings.json to use the default backend.

• 启动时只检查 Key 是否为空；Key 无效要到第一次对话才报错（API key not valid）。想换回账号登录，删除 modelProvider 后重启 CLI。

步骤 4：准备练习项目

建一个带两个 Bug 的小项目：mean([]) 会除以零，median() 对偶数个元素算错。

mkdir -p ~/kun-agy-demo && cd ~/kun-agy-demo
git init

创建 stats.py：

cat > stats.py <<'PY'
def mean(values):
    return sum(values) / len(values)


def median(values):
    s = sorted(values)
    mid = len(s) // 2
    return s[mid]
PY

创建 test_stats.py：

cat > test_stats.py <<'PY'
import unittest

from stats import mean, median


class TestStats(unittest.TestCase):
    def test_mean(self):
        self.assertEqual(mean([1, 2, 3, 4]), 2.5)

    def test_mean_empty(self):
        with self.assertRaises(ValueError):
            mean([])

    def test_median_odd(self):
        self.assertEqual(median([3, 1, 2]), 2)

    def test_median_even(self):
        self.assertEqual(median([4, 1, 3, 2]), 2.5)


if __name__ == "__main__":
    unittest.main()
PY

先自己跑一次测试，确认 Bug 存在：

python3 -m unittest -v

对照结果（节选，Python 3.13 实测）：

test_mean (test_stats.TestStats.test_mean) ... ok
test_mean_empty (test_stats.TestStats.test_mean_empty) ... ERROR
test_median_even (test_stats.TestStats.test_median_even) ... FAIL
test_median_odd (test_stats.TestStats.test_median_odd) ... ok
...
ZeroDivisionError: division by zero
...
AssertionError: 3 != 2.5
FAILED (failures=1, errors=1)

把初始状态提交一次，方便后面对比：

git add . && git commit -m "init: stats demo with bugs"

步骤 5：第一次会话——只读提问

在项目目录启动：

cd ~/kun-agy-demo
agy

在输入框里输入（@ 会弹出文件路径补全，按 Tab 选中）：

读一下 @stats.py 和 @test_stats.py，说明每个函数的作用，
并指出哪些测试会失败、原因是什么。先不要改任何文件。

示例提示词分成了两行方便阅读，整段粘贴进输入框即可；手动输入时用 Shift+Enter 或 Ctrl+J 换行，Enter 发送。

对照结果：回答应指出 mean([]) 触发 ZeroDivisionError（测试期望 ValueError），以及 median() 在元素个数为偶数时只取了中间偏右的一个数（[1, 2, 3, 4] 返回 3，测试期望 2.5）。措辞每次会不同，看结论即可。

以 ! 开头的输入会直接作为终端命令执行，不经过 Agent。试一下：

!python3 -m unittest

你会在会话里看到和步骤 4 相同的 FAILED (failures=1, errors=1)。

步骤 6：让它修 Bug，并审阅改动

继续在同一会话输入：

修复 stats.py：空列表时 mean() 和 median() 都抛出 ValueError；
偶数个元素时 median() 返回中间两个数的平均值。
改完运行 python3 -m unittest -v 验证。

在默认（default）模式下，Agent 每次要写文件，都会先停下来显示带语法高亮的 diff：

• 按 y 接受并写入磁盘，按 n 拒绝
• 按 f 打开全屏 diff，逐块查看
• 按 Ctrl+G 用你的 $EDITOR 手动修改
• 直接在输入框写新要求并回车，等于拒绝这次修改并告诉它怎么改

它要运行 python3 -m unittest -v 时，会弹出命令确认：按 y 允许、n 拒绝。

对照结果：测试最终应全部通过：

test_mean (test_stats.TestStats.test_mean) ... ok
test_mean_empty (test_stats.TestStats.test_mean_empty) ... ok
test_median_even (test_stats.TestStats.test_median_even) ... ok
test_median_odd (test_stats.TestStats.test_median_odd) ... ok

----------------------------------------------------------------------
Ran 4 tests in 0.000s

OK

一个参考的正确实现如下（Agent 写法可能不同，只要测试全绿即可）：

def mean(values):
    if not values:
        raise ValueError("mean() requires at least one value")
    return sum(values) / len(values)


def median(values):
    if not values:
        raise ValueError("median() requires at least one value")
    s = sorted(values)
    mid = len(s) // 2
    if len(s) % 2 == 0:
        return (s[mid - 1] + s[mid]) / 2
    return s[mid]

再输入 /diff 打开交互式 diff 查看器，复查这一轮改了什么：Tab 在 VCS（工作区改动）/ Turn（按轮次）/ Commit（提交历史）三种视图间切换；Esc 先返回文件列表，再按一次退出。

步骤 7：提交，并认识常用操作

确认无误后提交（可以在会话里用 !，也可以退出后在终端执行）：

!git add -A && git commit -m "fix: mean/median edge cases"

再记住几个最常用的操作：

在 default 模式等你确认文件改动时，按 Shift+Tab 会立即切到 accept-edits 并批准所有待处理的改动。只在你信任当前任务时这样做。

最后输入 /exit（或在空输入框按 Ctrl+D）退出。

模型与配额

在终端运行 agy models 可以看到当前账号可用的模型标识，后面用 --model 固定模型时就填这里的值。编辑部 2026-10-08 用 Gemini API Key 实测，列表为：

gemini-3.8-flash-high    Gemini 3.8 Flash (High)
gemini-3.8-flash-medium  Gemini 3.8 Flash (Medium)
gemini-3.8-flash-low     Gemini 3.8 Flash (Low)
gemini-3.7-flash-high    Gemini 3.7 Flash (High)
...
gemini-3.1-pro-high      Gemini 3.1 Pro (High)
gemini-3.1-pro-low       Gemini 3.1 Pro (Low)

用 Google 账号登录时，模型选择器里还可能出现 Claude 等第三方模型。按官方 Models 页（2026-10-08）：Claude Sonnet 5.5 / Opus 5.5 只对 Google AI Pro（非试用）和 Ultra 开放；Claude Sonnet 4.6、Opus 4.6 与 GPT-OSS-120b 将于 2026 年 11 月 2 日移除。

常见问题

本课来源

• https://antigravity.google/docs/cli/overview
• https://antigravity.google/docs/cli/install
• https://antigravity.google/docs/getting-started?tab=cli
• https://antigravity.google/docs/cli/using
• https://antigravity.google/docs/cli/modes
• https://antigravity.google/docs/cli/reference
• https://antigravity.google/docs/cli/troubleshooting
• https://antigravity.google/docs/plans
• https://antigravity.google/docs/models
• https://antigravity.google/docs/faq
• https://developers.google.com/gemini-code-assist/resources/available-locations