Antigravity 是 Google 推出的智能体优先（agent-first）的开发平台。它和传统"AI 代码补全"的区别是：

• 代码补全：你写代码，AI 帮你补下一行。
• Antigravity：你描述要做什么，AI 智能体自己规划、写代码、运行命令、打开浏览器测试，最后把结果和证据交给你审核。

打个比方：代码补全像一个坐在旁边提醒你的同事；Antigravity 像一个你可以派活的工程师，你负责提需求、审方案、验收结果。

2.0 版本之后，Antigravity 不再只是一个 IDE，而是一整套产品：

三者共享同一个智能体引擎，所以在一个地方学会的概念，在其他地方基本通用。

后面所有章节都围绕这几个概念展开，先有个整体印象：

进阶为什么要分 Skills、Rules、Workflows 三种？ 核心是上下文管理。模型的上下文窗口有限，塞进太多无关指令会变慢、变贵，还容易被干扰（业内叫"上下文腐烂"）。所以：始终需要的放 Rules，按需使用的放 Skills（平时只露出一行描述），需要人主动触发的流程放 Workflows。第 7、8、9 章会详细展开。

1. 打开下载页 https://antigravity.google/download，下载对应操作系统的安装包。
2. 运行安装程序，会看到两个登录选项：
   • Continue with Google：用个人 Google 账号登录，个人 Gmail 有免费的入门额度；如果你订阅了 Google AI Pro / Ultra，会自动享有对应的额度。本手册用这个。
   • Use business account：企业场景，组织有 Google Cloud 项目并购买了许可证，或者用 Google Cloud 项目加 Agent Platform 按量付费。
3. 点 Continue with Google，完成登录后点 Open Antigravity。
4. 接下来会让你选主题、选择要安装的 Google 插件（可以先全部跳过）、同意服务条款。点 Finish，进入主界面。

1. 主界面右上角有个 Install Antigravity IDE 按钮，点它会跳到下载页（也可以直接访问上面的下载页）。
2. 点 Download。这里可以选择：下载你常用编辑器（VS Code、Zed、JetBrains 等）的 Antigravity 插件，或者下载独立的 Antigravity IDE 安装包。
3. 运行安装程序，用同一个 Google 账号登录，所有步骤保持默认即可。
4. 装好后，Dock 栏里会有两个图标：**Antigravity 2.0（白色背景）**和 Antigravity IDE（黑色网格背景）。

注意Linux 用户：如果用的是 .tar.gz 安装包，启动器会直接配置好完整的 IDE 环境，应用菜单里只有一个图标，同时负责代码工作区和后台智能体管理。

检查点打开 Antigravity 2.0，右上角按钮显示 Open Antigravity IDE（而不是 Install IDE），说明两个都装好了。主界面左下角是 Settings，右侧面板显示 Select Project。

什么是项目

Antigravity 采用以项目为中心的设计：智能体能访问哪些文件、能用哪些工具、有哪些权限，都由项目决定。

• 一个项目可以包含一个或多个文件夹，比如同时包含前端仓库和后端仓库，让智能体看到完整的上下文。
• 每个项目有独立的智能体设置，可以给不同项目配置不同的安全策略。

动手

1. 在电脑上创建一个文件夹：$HOME/agy2-projects/my-first-project（不一定要是空文件夹）。
2. 在 Antigravity 左侧导航栏的 Projects 区域，点 Create New Project，再选 New Project。
3. 在弹出的文件选择器里选中刚才的文件夹。
4. 想添加更多文件夹的话，点该项目的 Project settings，用 Add Folder 添加。现在不需要，直接点 Create，然后关闭设置页。

进阶项目设置的继承关系：每个项目会从全局 Settings 继承默认配置，包括产物审核策略、允许的工具、MCP 服务器配置等，然后可以在项目级别单独覆盖。好处是每个项目的上下文和工具都能保持精简，只给它需要的东西。

1. 点 Start first conversation。
2. 观察对话界面：可以选择模型，可以通过 +、@、/ 添加额外的上下文或命令。左侧项目列表里会出现 my-first-project，它就是当前智能体工作的项目。
3. 跟智能体打个招呼，再让它帮你找点新闻，比如"给我一些今天的科技新闻"。

刚才的所有消息属于同一个对话线程，它显示在左侧对应项目的下面。

1. 重命名：点对话旁边的三个点 → Rename，改成 conv-introduction。
2. 新建对话：点项目名旁边的 +（New Conversation in Project），开一个全新的对话。
3. 在新对话里输入：Give me some sports news from across the world
4. 把这个对话重命名为 conv-sportsnews。现在同一个项目下有两个对话了。
5. 左上角的 Conversation History 可以查看所有历史对话；顶部的 New Conversation 可以在当前项目或新项目里开对话。

进入方式：左侧项目旁边的齿轮图标 → Project Settings（也可以从主界面的 Settings 进入）。

建议先把整个设置页从头到尾浏览一遍。最重要的几项：

进阶怎么平衡安全和效率：所有操作都要批准最安全，但会频繁打断你。一个常见做法是：练习项目和个人项目放宽（比如产物审核设为 Always Proceed），生产相关项目收紧，并且用项目级 MCP 白名单限制它能碰的外部系统。

在对话框输入 / 会弹出可用命令。桌面版最常用的三个：

动手：让智能体上网

输入：

/browser 访问一个新闻网站，告诉我今天的头条新闻

智能体会启动一个浏览器子智能体，尝试和 Chrome 建立调试会话，并先征求你的许可。允许之后，它会打开网站、抓取新闻，把结果返回给你。

注意/browser 要求 Chrome 是系统默认浏览器，否则无法启动调试会话。

除了 /schedule 命令，也可以在主界面的 Schedule 入口管理定时任务。

动手

1. 点 Schedule → New，创建一个任务：每天下午 6 点提醒我开会。填好后点 Add Scheduled Task。
2. 再建一个：每 20 分钟提醒我休息一下。
3. 现在列表里有两个任务，试试停用和删除。

进阶定时任务远不止提醒。任务内容就是一段提示词，可以写得很详细，也可以调用工具（通过 MCP 访问外部系统）。例如：每天早上自动汇总 GitHub 上新开的 issue；每周五生成一次依赖安全扫描报告。

为什么需要产物

以前 AI 说"bug 修好了"，你得自己读代码才能确认。Antigravity 用产物来解决这个"信任缺口"：智能体主动拿出证据，证明它做了什么、做对了没有。

产物不一定每次都有。智能体会根据任务复杂度、是否使用了 /plan 等因素决定要不要生成。

动手：完整走一遍"计划 → 执行 → 验收"

1. 新建一个对话，输入：

   /plan Design a Node application that I can run from the command line to get me the latest news from Google.
   

2. 智能体会生成第一个产物：实施计划。

3. 点右上角的 **Auxiliary Pane（辅助面板）**开关，会看到"1 Artifact"，点 Implementation Plan 查看详情。

4. 确认没问题后点 Proceed。执行过程中可能会请求权限，允许即可。

5. 完成后，智能体会提示任务已完成并通过验证。你还能看到 Walkthrough 和文件 diff。

6. 不需要打开 IDE，直接点 package.json、index.js 就能查看内容并加评论。

注意有时看不到 Proceed 按钮，智能体直接就开始执行了。这和你的审核策略设置有关，见 1.6。

进阶在产物上加批注是 Antigravity 很有特色的交互：不用在聊天框里描述"第三步改成……"，直接在计划的对应位置写批注，智能体会读取并修改。第 8、9 章会大量用到这个能力，连图片上都可以批注。

需要完整的编辑器时：

1. 打开辅助面板，点 Open IDE。
2. 启动时可能会弹出一个警告，这是正常的，点 Yes。
3. IDE 里有文件树、编辑器和 Agent Panel（智能体面板），可以在面板里让智能体解释、生成或修复代码。

IDE 常用操作（后面章节会用到）：

IDE 界面的六个主要区域：

进阶IDE 里的智能体能跨三个界面工作：在编辑器里写代码给你看；在终端里执行命令（会征求你同意）；在浏览器里运行并测试你的 Web 应用。你还可以同时开多个智能体并行工作：一个重构认证逻辑，一个写单元测试，一个在后台调研某个库。

Antigravity CLI 是 Antigravity 的轻量级终端界面，命令是 agy。它和桌面版有一样的核心能力：多步推理、跨文件编辑、调用工具、保存对话历史。好处是不用离开终端，减少来回切换，特别适合远程服务器和 SSH 场景。

本章用一个 Python Web 应用做练习：把数字转换成罗马数字。

1. 打开 Google Cloud Console，点搜索栏右边的图标激活 Cloud Shell，点 Continue，如果提示授权就点 Authorize。

2. 在终端里启用 Agent Platform API：

   gcloud services enable aiplatform.googleapis.com
   

3. 克隆练习项目：

   git clone https://github.com/gitrey/calendar-app-lab
   cd calendar-app-lab
   

4. 点 Cloud Shell Editor 打开编辑器，打开 calendar-app-lab 文件夹，再在编辑器里新开一个终端。

1. 安装：

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

2. 看安装器的输出，执行它给出的命令，把 agy 加入 PATH。示例如下，你的用户名会不一样，以实际输出为准：

   echo 'export PATH="/home/student_01_7c9be0de109d/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
   

3. 确认在项目根目录，然后启动：

   cd ~/calendar-app-lab
   agy
   

4. 登录流程：

   • 选择 Use a Google Cloud project
   • 点 Click here to authenticate（或复制完整 URL 到浏览器新标签页打开），按步骤生成验证码
   • 回到终端粘贴验证码，设置 Google Cloud 项目
   • Location 设为 global
   • 选一个配色方案，点 Next
   • 接受服务条款和数据使用条款

5. 验证安装：

   /config
   

   选择 Color Scheme，确认可以修改。再看看可用的模型：

   /model
   

注意

• 提示 agy 找不到：没有执行第 2 步的 PATH 命令。
• 一定要在项目根目录启动 agy，它会以当前目录作为工作范围。

接手新项目时，先让智能体给你讲一遍：

Explain this codebase to me, including its overall architecture, key dependencies, and the main entry points for the application.

它会总结整体架构、关键依赖和主入口。你也可以追问某个文件或某个复杂函数的作用。

Setup a local virtual environment and run this app locally.

智能体会创建虚拟环境、安装依赖，并启动应用。过程中会请求执行命令，确认工具调用即可。应用启动后，点输出里的链接打开预览，输入 25 回车，应该看到 XXV。

进阶 CLI 很擅长处理"跑不起来"的问题：它能生成 requirements.txt 或 Dockerfile，读懂报错堆栈，告诉你是缺包还是版本冲突，并给出准确的 pip install 命令。

给所有 Python 文件加上详细的 docstring：

Add detailed docstrings to all files.

更新 .gitignore：

Update .gitignore: add __pycache__ and .venv folders.

查看改动有两种方式：在编辑器里切到 Source Control 视图，或者直接在 CLI 里输入：

/diff

/goal 是 CLI 的一个重要命令：一直工作，直到目标完全达成。

/goal Generate unit tests for @calendar.py

@calendar.py 表示引用这个文件。智能体会写测试、运行、发现失败就修，反复循环直到全部通过。接受工具调用后查看结果，再到 Source Control 里看最新改动。

注意AI 生成的测试往往只覆盖了基本路径。它能给出不错的初始断言和 mock，但边界情况要你自己审核，确认测试真的有意义，而不是只证明代码"能跑"。

进阶/goal 适合"完成标准能被机器验证"的任务，比如测试全绿、lint 无报错、构建成功。完成标准越明确，/goal 越可靠。完成标准模糊的任务（比如"把代码写得优雅点"）不适合用它。

告诉智能体你担心什么，它会针对性地检查：

Are there any bugs in the conversion logic? Check if negative numbers are handled properly.

它能发现条件处理错误、潜在逻辑漏洞、差一错误（off-by-one）等问题。你把代码的预期行为讲得越清楚，它越容易找到细微的偏差。

1. 让智能体先规划，把 UI 改成用 Bootstrap：

   /plan Refactor UI to use Bootstrap library
   

2. 用 /artifacts 查看实施计划。

3. 批准计划，开始实施，过程中确认工具调用。

4. 启动应用：

   Start the application
   

5. 刷新页面查看新界面。

6. 再加上错误处理：

   Implement error handling to display an error page when issues occur.
   

7. 刷新页面，访问一个不存在的地址（比如 /convert1），应该看到错误页。

把转换请求存在内存里，并加一个历史记录页面：

/goal Store requests in memory and create a page to display conversion history. Add links on all pages to view the history.

执行过程中，随时可以用这个命令查看上下文窗口用了多少：

/context

在聊天里审核并接受改动，然后在应用里提交几次转换，打开历史记录页面确认。

CLI 有一个异步子智能体框架：主智能体可以把并行工作、后台调研、系统测试分派出去，不会阻塞你当前的对话。

/grill-me 会在实施前像面试一样问你一系列问题，把模糊的需求问清楚：

/grill-me Refactor UI to use Bootstrap library

示例输出（每个问题都带推荐选项，也可以选 Write-in 自己写）：

Question 1/1: How would you like to structure the user flow and design theme for this Roman Numeral converter?

> 1. (Recommended) Keep the multi-page template structure with the majestic, imperial glassmorphic dark theme.
  2. Convert the flow into a modern Single-Page Application (SPA) using AJAX/Fetch, rendering results dynamically on the same page.
  3. Adopt a standard minimalist Bootstrap light/dark theme with corporate colors (blue primary, clean white cards) instead of the
imperial-themed style.
  4. Write-in...
.
.
Question 1/1: Which visual theme and color palette would you prefer for the Roman Numerals Converter?

> 1. (Recommended) Sleek Dark Mode with Glassmorphism: Deep space/midnight background, glowing neon blue/purple
gradients, and semi-transparent frosted-glass cards.
  2. Roman Antique / Golden-Ivory theme: Warm cream/marble background, rich gold highlights, deep crimson/burgundy
accents, and elegant serif typography.
  3. Clean Modern Tech: Slate gray and vibrant emerald green accents, minimalist clean white cards, and smooth micro-
interactions.
  4. Write-in...
.
.
Question 1/1: Which interactive features would you like to incorporate to make this a premium user experience? (Select
all that apply)

> 1. [ ] (Recommended) Dynamic Live Validation: Instantly validate input (range 1-3999) as the user types with helper
messages.
  2. [ ] (Recommended) "Surprise Me" Button: Instantly generates a random integer and converts it to its Roman numeral
counterpart.
  3. [ ] (Recommended) Quick-Copy Clipboard Button: A one-click button to copy the roman numeral result with a
toast/notification checkmark.
  4. [ ] (Recommended) Interactive Reference Table: A beautiful Cheat Sheet showing standard Roman numeral symbols (I, V,
X, etc.) with responsive hover effects.
  5. [ ] Keep it extremely minimal with only the conversion card.
  6. Write-in.

进阶/plan 和 /grill-me 怎么选：/plan 是"我想好了，你出方案给我审"；/grill-me 是"我还没想清楚，你先帮我把需求问明白"。需求越模糊、改动越大，越应该先用 /grill-me。

/goal Analyze README.md file and update it with latest codebase changes.

完成后用 Markdown 预览模式打开 README.md 检查。

先退出当前的 agy 会话，或者新开一个终端，然后运行：

agy -p "Explain the architecture of this codebase"

-p 表示直接传入提示词，执行完就退出，不需要人工交互。这样就能把 CLI 集成进自动化流程：代码分析、生成文档、CI/CD 流水线里的质量检查等。

简单操作不用绕道 AI，用 ! 前缀直接执行 shell 命令：

! git status

CLI 和桌面版一样可以扩展，详细内容见后面的章节：

练习结束后，删除 Google Cloud 项目或其中创建的资源，避免继续产生费用。

**MCP（Model Context Protocol，模型上下文协议）**是连接智能体和外部系统的标准协议。没有 MCP 时，智能体只能读写你本地的文件；有了 MCP，它可以：

• 列出、部署 Cloud Run 服务
• 读取 Stitch 里的设计稿
• 创建 GitHub PR、更新 Jira 工单
• 查询最新的技术文档

MCP 服务器分两种：本地（在你电脑上启动一个进程，用 command 配置）和远程（连接一个 URL，用 serverURL 配置）。

1. 打开 Settings → Customizations，找到 MCP 服务器配置区域，进入 Installed MCP Servers。

2. 点 Open MCP Config 会打开配置文件 $HOME/.gemini/config/mcp_config.json，一开始是空的。熟悉配置格式的话，也可以直接编辑这个文件。

3. 点 Add MCP，会看到大量预置的 MCP 服务器，尤其是各种 Google Cloud 服务，一键安装。

4. 找到 Google Cloud Run，点 Add。

5. 安装后它会出现在列表里，并显示它提供的所有工具。可以单独开关某个工具，也可以整体开关这个服务器。

6. 再点 Open MCP Config，会看到配置文件里多了这一段：

   {
    "mcpServers": {
      "cloudrun": {
        "command": "npx",
        "args": [
          "-y",
          "@google-cloud/cloud-run-mcp"
        ]
      }
    }
   }
   

7. 测试：在对话里输入一个需要用到它的请求，智能体会自动找到并使用 Cloud Run MCP：

   Build and deploy a Cloud Run service
   

IDE 里有两个入口：

• MCP 商店：智能体面板顶部的 "..." 菜单 → MCP Servers，搜索并点 Install。（Agent Manager 里也能找到 MCP Servers 入口。）
• 手动编辑配置：智能体面板右上角的 "..." → MCP → Manage MCP servers → View Raw Config，会打开 mcp_config.json。编辑后记得保存。

CLI 有两级配置：

动手：接入 context7（查询最新技术文档）

1. 退出当前的 agy 会话（或新开一个终端），创建配置文件：

   echo '{
       "mcpServers": {
           "context7": {
               "serverURL": "https://mcp.context7.com/mcp"
           }
       }
   }' > ~/.gemini/antigravity-cli/mcp_config.json
   

   注意> 会覆盖整个文件。如果你已经配置过其他 MCP 服务器，不要直接运行这条命令，而是用编辑器打开文件，把 context7 这一段合并进 mcpServers 里。

2. 启动 agy，查看已配置的 MCP 服务器：

   /mcp
   

3. 测试：

   Use context7 tools to look up how to implement flex grid in react mui library
   

   批准工具调用后查看结果。

下面是一份可以直接参考的多服务器配置：

{
    "mcpServers": {
        "Snyk Security Scanner": {
            "command": "snyk",
            "args": [
                "mcp",
                "-t",
                "stdio",
                "--experimental"
            ],
            "env": {}
        },
        "atlassian": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "https://mcp.atlassian.com/v1/sse"
            ]
        },
        "playwright": {
            "command": "npx",
            "args": [
                "@playwright/mcp@latest"
            ]
        },
        "github": {
            "command": "npx",
            "args": [
                "-y",
                "@modelcontextprotocol/server-github"
            ],
            "env": {
                "GITHUB_PERSONAL_ACCESS_TOKEN": "******"
            }
        }
    }
}

注意 配置里的 token、API key 是敏感信息，不要把配置文件提交到代码仓库。

进阶MCP 不是越多越好。每个 MCP 服务器的工具描述都会占用上下文，工具多了智能体也更容易选错。建议：全局只放通用的，项目级通过 MCP 白名单（桌面版）或 .agents/mcp_config.json（CLI）按需开启。

Stitch 生成设计稿 ──MCP──> Antigravity 读取"设计 DNA"（颜色、字体、布局）
                                │
                                ▼
                     生成 DESIGN.md → 写 React + Tailwind 代码
                                │
                                ▼
                  内置浏览器预览 → 对照设计稿修正

Stitch 是 Google 基于 Gemini 的 UI 设计工具，用自然语言就能生成高保真界面。在这个流程里，Stitch 的设计稿是视觉上的唯一标准，智能体照着它写代码。

1. 打开 https://stitch.withgoogle.com。

2. 在主界面的 Start a new design 里选择 Web（针对浏览器布局优化）。

3. 点提示框里的模型下拉菜单（默认显示 3.0 Flash），切换到 Gemini 3，以获得更好的推理和布局效果。

4. 在 "Describe your design" 输入框里填：

   Design a modern SaaS landing page for a space-tech startup called LaunchPad. Use a midnight blue and neon purple palette. Include a hero section with a 'Get Started' button, a 3-column features grid, and a glassmorphism pricing table.
   

5. 点模型选择器旁边的箭头图标开始生成。

6. 生成后，在顶部给项目命名为 LaunchPad。可以用右侧的聊天栏继续微调某些元素。

想快速开始的话，也可以直接用 Stitch 里 "Try these prompts" 区域的示例。

1. 在 Stitch 右上角点头像 → Stitch settings。
2. 找到 API key 区域，点 Create key。
3. 立即复制并妥善保存这个 key，下一步要用。

1. 打开 Antigravity IDE，进入 Agent Manager（CMD+E / CTRL+E 切换）。
2. 点 + Open Workspace → Open New Workspace，命名为 LaunchPad-Project，选一个本地文件夹。

单独建工作区的好处：智能体有一个明确的根目录来生成文件，不会弄乱其他项目。

1. 在新工作区里，回到 Agent Manager，选择 MCP Servers（或者从编辑器智能体面板顶部的 "..." 打开 MCP 商店）。

2. 搜索 Stitch，点 Install。

3. 提示时粘贴刚才的 Stitch API key。

4. 验证：在智能体对话里输入：

   List my Stitch projects.
   

   检查点返回了 LaunchPad，说明连接成功。

进阶为什么要用 MCP 而不是截图或复制代码：有了 MCP，智能体能直接拿到设计的结构化元数据（精确的色值、字体、间距、布局规则），不需要你手动导出设计 token 或复制十六进制色值。而且后面修正时，它可以随时回去重新读取设计稿。

Use the Stitch MCP to fetch the 'LaunchPad' project. Extract the color palette and typography, then generate a DESIGN.md file in my root directory.

打开生成的 DESIGN.md，检查智能体提取的色值和布局规则。

进阶DESIGN.md 的作用：它把设计规范固化成项目里的一个文件，后续所有生成和修改都能参照它，也方便人工审核和修改。这和第 6、9 章"规范驱动开发"的思路一致：先把规范写成文档，再让智能体照着做。

I want to build this full website now. Use React and Tailwind CSS. Ensure the components are modular. Once finished, run the dev server and show it to me in the integrated browser.

观察智能体的工作过程：它会在终端里搭建项目骨架，在编辑器里写组件，最后在内置浏览器里打开预览。

把内置浏览器里的效果和 Stitch 原始设计对比。如果有不一致（比如按钮内边距、字重），直接告诉智能体：

The 'Get Started' button padding is slightly off. Refer back to the Stitch design and update the Tailwind classes.

智能体会重新读取设计稿并修正。

• 用 Stitch + Gemini 3 一句话生成高保真设计
• 用 API key 配置 MCP，让 Antigravity 直接读取设计
• 智能体提取设计规范，生成模块化的 React + Tailwind 网站
• 用内置浏览器预览，对照设计稿迭代修正

从"提示词加打补丁"到"规范驱动"

很多人用 AI 写代码的方式是：随手写一句需求，AI 生成一堆代码，看着差不多就接受，不对再补一句……这叫 "prompt-and-patch"（提示词加打补丁），也有人叫 "vibe coding"（凭感觉编程）。写原型很快，但项目一大、功能一多，或者过几周回头看，就说不清当初为什么这么做了。

**规范驱动开发（Spec-Driven Development，SDD）**的做法是：先把需求、设计、验收标准写成结构化的规范文档，再让 AI 按规范生成代码。 它借鉴了瀑布模型中严谨的设计阶段，但因为 AI 实现和测试都很快，整个过程依然是敏捷迭代的：快速得到反馈，再用反馈完善文档。

核心理念

工程师的角色从**"写代码的人"转变为"系统架构师"。人的主要职责是把问题和解决方案描述清楚。这份文档是唯一事实来源（Single Source of Truth）**，AI 根据它来生成、验证和完善代码。

SDD 生命周期

三条运作原则

1. 设计和实现是一个循环：第 1–5 步不是一次性走完，而是持续循环。因为第 4、5 步基本自动化了，团队可以把精力集中在前三步。发现 bug 或需求变更时，改的是规范，不是代码，然后重新跑一遍循环。
2. 模块要小：SDD 要应用在细粒度的模块上，而不是一整块巨大的系统。
   • 隔离：某个模块验证失败，只需要重新编写这个模块的规范并重新生成。
   • 可扩展：模块小、定义清楚，能减少 AI 的幻觉，让上下文窗口保持聚焦。
3. 质量控制：系统规范是蓝图，测试规范是裁判。测试规范保证生成的代码始终符合预定的质量要求，整个过程也可以接入现有的 CI/CD 流水线。

进阶Antigravity 本身就内置了 SDD 的影子：/plan 生成的实施计划和任务清单，加上你的审批，就是"先规范、后实现"。本章用一份结构化需求体验 SDD 的核心；第 9 章会用 spec-kit 把它做成完整的工程化流程。

智能体需要用浏览器自动测试应用，先做两个设置：

1. 点右上角齿轮图标 → Open Antigravity User Settings。
2. 左侧点 Agent，在 ARTIFACT 区域把 Review Policy 设为 Always Proceed。
3. 左侧点 Browser，确认 Enable Browser Tools 已开启。

注意 Always Proceed 表示产物不等你审核就直接执行，这里是为了练习更流畅。正式项目建议改回需要审核。

1. 在电脑上建一个文件夹 Gallery（比如放在桌面）。
2. 在 Antigravity 里点 Open Folder，选中 Gallery，会在这个文件夹里打开一个新工作区。
3. 如果智能体面板没打开，点 Toggle Agent Pane。
4. 在智能体面板里输入下面的需求。需求写得越清楚，结果越好。

英文版（已修正原文中 "photo granary" 的错字）：

Create a photo gallery with following specs.

1. Visual Design & Layout
Title: The gallery must prominently display the title "My photo gallery" at the top.
Modern Grid: Images will be arranged in a responsive grid that spans the full width of the browser.
Clean Aesthetic: Use a minimalist design with consistent spacing (margins/padding) between photos and no heavy borders or shadows.
Image Scaling: Photos will automatically adjust their size to fit any screen (mobile to desktop) while maintaining their focus using modern CSS cropping techniques.

2. Photo Content
Quantity: The page will feature a total of 20 photos.
Nature Themes: The collection will include a diverse range of nature photography:
Landscape: Mountains, deserts, and forests.
Water: Waterfalls, oceans, and lakes.
Atmosphere: Northern lights, sunsets, and starry skies.
Macro: Close-ups of flowers, leaves, and moss.
Generate all the needed photos

3. Core Functionality (The "Lightroom" Effect)
Full-Screen View: Clicking any photo triggers a "Lightbox" mode where the background dims and the selected image appears in high resolution at the center of the screen.
Manual Navigation:
Right Arrow: Swaps the current view to the next image.
Left Arrow: Swaps the current view to the previous image.
Infinite Loop: Navigation is continuous; moving "next" from the 20th photo returns the user to the 1st photo.
Exit Strategy: Users can exit the full-screen view by clicking a "Close" button or tapping the dimmed area outside the image.

4. Technical Constraints (Strict)
Vanilla JavaScript Only: Absolutely no external libraries or frameworks (like jQuery, React, or Bootstrap). All logic must be written in raw, standard JavaScript.
Native HTML & CSS: Use only the built-in capabilities of modern web browsers to handle the layout and animations.
Zero Dependencies: The app should function perfectly as a standalone project with no need to download or link to outside scripts.

5. Perform the following tests
Open the App in a web browser
Click on the images and see the image opens in the lightbox
Check the navigation

中文版（效果相同，可以直接用）：

按以下规范创建一个相册网页。

1. 视觉设计与布局
标题：页面顶部醒目显示标题 "My photo gallery"。
现代网格：图片以响应式网格排列，铺满浏览器全宽。
简洁风格：极简设计，图片之间间距一致，不使用粗边框或阴影。
图片缩放：使用现代 CSS 裁剪技术（如 object-fit），图片在手机到桌面各种屏幕上自动适配，同时保持主体居中。

2. 图片内容
数量：共 20 张图片。
自然主题：
风景：山脉、沙漠、森林。
水景：瀑布、海洋、湖泊。
天象：极光、日落、星空。
微距：花朵、树叶、苔藓特写。
生成所有需要的图片。

3. 核心功能（灯箱效果）
全屏查看：点击任意图片进入"灯箱"模式，背景变暗，选中的图片以高分辨率显示在屏幕中央。
手动切换：右箭头切换到下一张，左箭头切换到上一张。
无限循环：在第 20 张点"下一张"回到第 1 张。
退出方式：点击"关闭"按钮，或点击图片外的暗色区域退出全屏。

4. 技术约束（严格遵守）
只用原生 JavaScript：禁止使用任何外部库或框架（如 jQuery、React、Bootstrap）。
只用原生 HTML 和 CSS：布局和动画只用现代浏览器的内置能力。
零依赖：作为独立项目完整运行，不需要下载或引用任何外部脚本。

5. 执行以下测试
在浏览器中打开应用
点击图片，确认在灯箱中打开
检查左右切换功能

5. 点 Run。智能体会先展示实施计划。
6. 按提示确认：执行命令时点 Run，保存代码时点 Accept all。智能体会自动调用图片生成模型（Nano Banana）生成图片，并用选定的大模型写代码。
7. 代码生成后，智能体会自己打开浏览器测试，并把测试结果告诉你。
8. 如果提示，点 Accept All 保存智能体面板里生成的所有代码。
9. 在 Explorer 里会看到生成的代码，包括 index.html。
10. 自己验证一下：右键 index.html，复制文件路径，粘贴到浏览器地址栏打开。

拆解这份需求：为什么它有效

进阶写好需求的两个关键：一是写约束。不写的话，AI 很可能顺手引入 React 和一堆依赖。二是写验收方法。写了测试步骤，AI 才能形成"实现 → 测试 → 修正"的闭环，而不是写完就交差。这两点在任何 AI 编程任务里都适用。

准备环境

1. 打开 https://console.cloud.google.com，在左上角复制你的项目 ID。
2. 在 Antigravity 里打开终端：Terminal → New Terminal。
3. 设置环境变量，把 YOUR CLOUD PROJECT 换成你的项目 ID。

Windows PowerShell 用户先以管理员身份打开 PowerShell，运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

然后按你的系统选择：

问题：上下文饱和与工具膨胀

大模型是通才，但它不知道你项目的具体背景和团队规范。最直接的办法是把所有规范、所有工具一股脑塞给它，但这会导致：

• 上下文饱和（Context Saturation）：即使上下文窗口很大，塞进四五万 token 用不上的工具描述，也会导致响应变慢、费用增加。
• 工具膨胀（Tool Bloat）：工具太多，模型容易选错。
• 上下文腐烂（Context Rot）：无关信息太多，模型被干扰，表现变差。

解决方案：渐进式披露

Agent Skills 最早由 Anthropic 提出，是一种轻量、开放的格式，现在 Antigravity、Claude Code 等多个工具都支持。核心思路是渐进式披露（Progressive Disclosure）：

1. 一开始，模型只看到每个 Skill 的一行简介（相当于一份菜单）。
2. 只有当你的请求和某个 Skill 的简介匹配时，才加载它的完整指令和脚本。

例如，你让智能体重构认证中间件，它会加载安全相关的 Skill，而不会加载无关的 CSS 构建流程。上下文始终精简、快速、省钱。

Skill 的两个特点

• 按需加载：系统提示词始终存在，而 Skill 只在智能体判断相关时才加载。项目里有几十种工具时，这种选择性加载对性能和推理准确性至关重要。
• 能力扩展：Skill 不只是指令，还能附带 Python 或 Bash 脚本，让智能体在本地或网络上执行复杂的多步操作，从"只会生成文本"变成"会用工具"。

目录结构

my-skill/
├── SKILL.md      # 必需：元数据 + 指令
├── scripts/      # 可选：Python、Bash 或 Node 脚本
│   ├── run.py
│   └── util.sh
├── references/   # 可选：文档或模板
│   └── api-docs.md
└── assets/       # 可选：图片、logo 等静态资源

这个结构把逻辑（scripts）、指令（SKILL.md）和知识（references）分开，和常规的软件工程实践一致。

SKILL.md 的两部分

第一部分：YAML 头信息（frontmatter）

这是唯一会被智能体"路由器"索引的部分。你发出请求时，智能体会把请求和所有 Skill 的 description 做语义匹配。

---
name: database-inspector
description: Use this skill when the user asks to query the database, check table schemas, or inspect user data in the local PostgreSQL instance.
---

description 怎么写：

• 差："Database tools"，太模糊，永远不会被正确触发
• 好："Executes read-only SQL queries against the local PostgreSQL database to retrieve user or transaction data. Use this for debugging data states"

好的 description 要说清楚：做什么动作、作用于什么对象、什么场景下使用。

第二部分：Markdown 正文

正文就是"保存在文件里的提示词工程"。Skill 被激活时，这部分内容会注入智能体的上下文。建议包含四块：

1. 目标（Goal）：这个 Skill 要达成什么
2. 步骤（Instructions）：一步一步的逻辑
3. 示例（Examples）：输入输出示例，引导模型的表现
4. 约束（Constraints）："禁止"规则，比如"不准执行 DELETE 查询"

正文示例：

Database Inspector

Goal
To safely query the local database and provide insights on the current data state.

Instructions
- Analyze the users natural language request to understand the data need.
- Formulate a valid SQL query.
 - CRITICAL: Only SELECT statements are allowed.
- Use the script scripts/query_runner.py to execute the SQL.
 - Command: python scripts/query_runner.py "SELECT * FROM..."
- Present the results in a Markdown table.

Constraints
- Never output raw user passwords or API keys.
- If the query returns > 50 rows, summarize the data instead of listing it all.

脚本集成

Skill 最强大的能力之一是把执行交给脚本。有些事 LLM 做不了或做不可靠，比如运行二进制程序、复杂数学计算、对接老系统。脚本放在 scripts/ 目录，SKILL.md 里用相对路径引用。

注意全局路径在官方资料里不完全一致：入门 lab 说 ~/.gemini/config/skills/ 对所有产品（包括 CLI）都生效，Skills lab 后半部分又说 CLI 的全局目录是 ~/.gemini/antigravity-cli/skills/。最可靠的做法是放在项目级目录 .agents/skills/，两边都能识别。需要全局共享时，按下面的方法验证是否生效。

怎么确认 Skill 已加载：

• 桌面版 / IDE：问智能体 What skills are available?
• CLI：输入 /skills

这是一个纯指令 Skill，只需要一个 SKILL.md。

1. 在项目文件夹（比如 $HOME/agy2-projects/my-skills-project）里创建目录：

   mkdir -p .agents/skills/code-review
   

2. 在 .agents/skills/code-review/ 下创建 SKILL.md：

   ---
   name: code-review
   description: Reviews code changes for bugs, style issues, and best practices. Use when reviewing PRs or checking code quality.
   ---
   
   # Code Review Skill
   
   When reviewing code, follow these steps:
   
   ## Review checklist
   
   1. **Correctness**: Does the code do what it's supposed to?
   2. **Edge cases**: Are error conditions handled?
   3. **Style**: Does it follow project conventions?
   4. **Performance**: Are there obvious inefficiencies?
   
   ## How to provide feedback
   
   - Be specific about what needs to change
   - Explain why, not just what
   - Suggest alternatives when possible
   

3. 在这个项目里开一个对话，问 What skills are available?，应该能看到 code-review。

4. 创建一个故意写得有问题的文件 demo_bad_code.py：

   import time
   
   def get_user_data(users, id):
      # Find user by ID
      for u in users:
          if u['id'] == id:
               return u
      return None
   
   def process_payments(items):
      total = 0
      for i in items:
          # Calculate tax
          tax = i['price'] * 0.1
          total = total + i['price'] + tax
          time.sleep(0.1) # Simulate slow network call
   
      return total
   
   def run_batch():
      users = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
      items = [{'price': 10}, {'price': 20}, {'price': 100}]
   
      u = get_user_data(users, 3)
      print("User found: " + u['name']) # Will crash if None
   
      print("Total: " + str(process_payments(items)))
   
   if __name__ == "__main__":
      run_batch()
   

5. 新开一个对话，输入：

   review the @demo_bad_code.py file
   

检查点智能体识别出 code-review Skill，加载它，然后按清单逐项审查。它应该指出：get_user_data 找不到用户时返回 None，run_batch 直接访问 u['name'] 会崩溃（id 3 不存在）；循环里的 time.sleep 有性能问题；参数名 id 遮蔽了内置函数等。

下面四个例子来自示例仓库，分别展示一种设计模式。先准备好：

1. 克隆示例仓库：

   git clone https://github.com/rominirani/antigravity-skills
   

2. 进入 antigravity-skills/skills_tutorial 目录，把下面四个文件夹复制到你项目的 .agents/skills/ 下：

   • git-commit-formatter
   • license-header-adder
   • database-schema-validator
   • json-to-pydantic

3. 验证：桌面版问 What skills are available?，CLI 输入 /skills，应该能看到这 4 个。

级别 1：纯指令模式（git-commit-formatter）

场景：开发者经常写敷衍的提交信息，比如 "wip"、"fix bug"、"updates"。靠人去执行 Conventional Commits 规范很繁琐，经常忘。把规则写进 Skill，让智能体来执行。

结构：

git-commit-formatter/
└── SKILL.md  (只有指令)

SKILL.md：

---
name: git-commit-formatter
description: Formats git commit messages according to Conventional Commits specification. Use this when the user asks to commit changes or write a commit message.
---

Git Commit Formatter Skill

When writing a git commit message, you MUST follow the Conventional Commits specification.

Format
`<type>[optional scope]: <description>`

Allowed Types
- **feat**: A new feature
- **fix**: A bug fix
- **docs**: Documentation only changes
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, etc)
- **refactor**: A code change that neither fixes a bug nor adds a feature
- **perf**: A code change that improves performance
- **test**: Adding missing tests or correcting existing tests
- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation

Instructions
1. Analyze the changes to determine the primary `type`.
2. Identify the `scope` if applicable (e.g., specific component or file).
3. Write a concise `description` in an imperative mood (e.g., "add feature" not "added feature").
4. If there are breaking changes, add a footer starting with `BREAKING CHANGE:`.

Example
`feat(auth): implement login with google`

动手（需要本机装好 Git）：

1. 建一个测试仓库：

   Create a folder named git_test in the workspace, initialize a git repository inside it, and create an initial file auth.py with def login(): pass. Stage this file and make an initial commit.
   

   提交时 Skill 会被触发，输出类似：

    1. Created folder and initialized git repository:
        • Directory: git_test
        • Initialized empty Git repository in git_test/.git/
    2. Created initial file:
        • File: auth.py
        • Defined: auth.py:1-2
    3. Staged and committed changes:
        • Commit message: feat(auth): add initial login function
   

2. 改一下代码：

   In the git_test folder, modify auth.py to add Google Login functionality.
   

3. 提交：

   Stage the changes in the git_test folder and commit them. Make sure to format the commit message using the Conventional Commits skill.
   

   智能体会运行 git add auth.py，分析 diff，判断这是 auth 模块的新功能，生成类似 feat(auth): implement google login 的提交信息，再执行 git commit。

4. 查看历史：

   Show me the git log in the git_test folder.
   

   智能体会运行 git log -n 5，你能看到格式规范的提交记录。

适用场景：规范类、格式类的要求，规则能用几段话说清楚。

级别 2：引用资料模式（license-header-adder）

场景：公司项目的每个源文件都要加一段 20 行的 Apache 2.0 许可证头。如果把这段文字直接写进 SKILL.md：一是每次加载都浪费 token；二是模型可能把法律文本抄错。更好的做法是把大段固定文本放进单独的文件，需要时才让智能体去读。

结构：

license-header-adder/
├── SKILL.md
└── resources/
   └── HEADER_TEMPLATE.txt  (大段文本放这里)

SKILL.md：

---
name: license-header-adder
description: Adds the standard open-source license header to new source files. Use involves creating new code files that require copyright attribution.

只靠三种 Markdown 文件，就能搭出一条自动化流水线：

外加两个用于交接的文件夹：

• production_artifacts/：角色之间交接文档的地方，比如产品经理写好的需求文档放这里，工程师从这里读取
• app_build/：生成的应用代码，和 AI 指令文件分开

流水线流程：

你的想法
   │
   ▼
@pm 写技术规范 ──> 等你审批 ──(你在文档里批注要求返工)──┐
   │                ▲                                  │
   │                └──────────────────────────────────┘
   ▼ (你回复 Approved)
@engineer 按规范写代码 → app_build/
   │
   ▼
@qa 审查并修复 bug
   │
   ▼
@devops 安装依赖、启动服务，给你访问链接

进阶为什么要拆成多个角色：如果让一个 AI 同时当架构师、程序员、测试和运维，它很容易顾此失彼。拆开后每个阶段只专注一件事：产品经理只管需求，工程师只管写代码，测试只管找 bug。

1. 打开 Antigravity IDE，进入 Agent Manager。
2. 点 + Open Workspace → Open New Workspace，命名为 skills-codelab，选择一个本地文件夹。
3. 切到编辑器视图，创建以下目录结构（在工作区根目录下）：

mkdir -p .agents/workflows .agents/skills
mkdir production_artifacts app_build

完成后的结构：

<工作区根目录>/
├── .agents/
│   ├── workflows/
│   └── skills/
├── production_artifacts/
└── app_build/

注意 原 lab 的命令里先执行了 mkdir skills-codelab && cd skills-codelab，如果你的工作区本身就叫 skills-codelab，这样会建出两层嵌套的同名文件夹，Antigravity 可能读不到 .agents/。确保 .agents/ 在 Antigravity 打开的那个根目录下。

.agents/ 是 Antigravity 原生识别的特殊目录，放在这里的文件会扩展智能体的内置行为。

创建 .agents/agents.md：

桌面版 / IDE

CLI

spec-kit（第 9 章）

一个完整项目的 .agents/ 目录参考：

.agents/
├── agents.md              # 角色定义（可选）
├── mcp_config.json        # 项目级 MCP（CLI）
├── rules/                 # 始终生效
│   └── project-context.md
├── skills/                # 按需加载
│   └── <技能名>/
│       ├── SKILL.md
│       ├── scripts/
│       ├── references/
│       └── examples/
└── workflows/             # 斜杠命令
    └── <命令名>.md

1. 大任务先 /plan 或 /grill-me：在方案阶段纠错，成本最低。
2. 用产物验收，不要只听智能体说"做完了"：看计划、看 diff、看 Walkthrough、看截图。
3. 在产物上直接批注：比在聊天框里描述"第三步改成……"更准确。
4. 需求里写约束和验收方法：约束防止 AI 自作主张，验收方法让 AI 能自己测试。
5. 能被机器验证的目标交给 /goal：比如测试全绿、构建成功。
6. 反复叮嘱的话写成 Skill 或 Rule：写一次，永久生效。
7. 确定性的事交给脚本：不让模型凭感觉判断。
8. 按项目限制 MCP 和权限：上下文更干净，风险更小。
9. 复杂功能走 SDD：出问题时改规范，而不是直接改代码。
10. AI 生成的测试要人工审：它往往只覆盖了基本路径。

1. 智能体会在你的机器上真实执行命令：安装依赖、启动服务、修改文件。不熟悉的命令要看清楚再批准。
2. Always Proceed 和 Accept all 会跳过你的审核，只在练习或可信项目里使用。
3. 不要盲目运行 curl ... | bash 或 curl ... | python3：先下载、看内容，再执行。
4. 敏感信息：密码、API key、token 不要写进代码或提交到仓库；MCP 配置文件里的 token 也一样。生产环境用 Secret Manager。
5. 公开访问：Cloud Run 的 --allow-unauthenticated 意味着任何人都能访问，正式环境要加访问控制。
6. 用完删除云资源：Cloud Run 服务、Cloud SQL 实例，或者直接删除整个练习项目。

1. 登录 Google Cloud Console。没有 Google 账号的话先注册一个。
2. 点左上角的项目选择器，创建新项目或选择已有项目。三个概念要分清：
   • 项目名称（Project name）：显示用的名字，随时可以改。
   • 项目 ID（Project ID）：全局唯一，创建后不能修改，删除后也不能再被使用。大多数命令里用的是它，通常记作 PROJECT_ID。
   • 项目编号（Project number）：系统分配的数字，部分 API 会用到。
3. 用个人 Gmail 的话，位置选 "No organization" 即可。

在 计费页面 为项目开启计费。新用户可以参加 300 美元免费试用。完成本手册的练习花费很少，甚至不花钱。

在 Cloud Shell 或本地终端里：