使用 Antigravity 和 Spec-kit 进行规范驱动的 ADK 智能体开发

1. 简介

为现有代理添加功能（一种新的数据库支持功能）通常意味着要编写样板代码、连接集成，并使所有内容与代码库中已有的模式保持一致。Antigravity 可加速此流程的每个阶段：它会分析您的代码库以构建所需的上下文，生成结构化规范和实现方案供您审核，并执行代码更改 - 所有这些都以领域知识为指导，而领域知识可帮助您捕获可重用的技能和强制执行不可协商原则的项目章程。此 Codelab 介绍了一种通过引入新周期来大幅提升规范文档的 Antigravity 规范驱动开发范式，其中大量参考了 spec-kit

构建内容

一个本地运行的餐厅礼宾应用，通过完整的 SDD 周期添加了预订功能：

• 预订 - 宾客预订餐桌和查看预订，由新的 MCP Toolbox 数据库工具和 Cloud SQL reservations 表提供支持
• （挑战）- 为代理开发自己的界面
• （挑战）- 在 Antigravity 代理的帮助下部署到 Google Cloud

起始代码提供了一个可正常运行的 ADK 代理，该代理具有菜单搜索（通过 MCP Toolbox 进行关键字搜索和语义搜索）和饮食偏好跟踪（通过 ToolContext 进行）功能。您无需手动编写应用代码即可扩展它，Antigravity 会根据您的规范处理实现。

学习内容

• 如何引导项目上下文，以便 Antigravity 了解现有代码库
• 如何创建封装领域知识的反重力技能（例如，ADK Codelab 模式）以供重复使用
• 如何在规划和分析期间设置 SDD 工作流验证的项目章程
• 如何在 Antigravity 中使用规范驱动开发 (SDD) 工作流来系统地添加功能
• 如何通过 MCP Toolbox 使用新的数据库支持的工具来扩展 ADK 智能体

前提条件

• 本地机器上安装了 Google Antigravity 和 git
• 启用了试用结算账号的 Google Cloud 账号
• 如果您之前完成了 4 个必备的 ADK Codelab（或具备同等知识），将有助于了解应用场景背景：
• 使用 ADK 构建 AI 智能体：基础知识
• 使用 ADK 构建 AI 智能体：配备工具
• 使用 ADK 和 CloudSQL 构建持久性 AI 智能体
• 在 Cloud Run 上部署、管理和观测 ADK 智能体
• 将数据库作为工具：使用 ADK、MCP Toolbox 和 Cloud SQL 构建智能体 RAG

2. 设置您的环境

重要提示：

本教程需要具有有效结算账号的 Google Cloud 项目。如果您还没有结算账号，请按照以下步骤获取可用于本教程的试用结算账号：

1. 打开无痕式窗口
2. 如果您要加入研讨会，通常会在研讨会中提供兑换门户网站网址；否则，您可以前往此试用结算账号兑换门户网站
3. 使用您的个人 Gmail 账号登录（Google Workspace / 其他电子邮件地址无法使用！）
4. 按照分步兑换说明操作

此步骤会克隆初始代码库、通过 Google Cloud 进行身份验证、预配 Cloud SQL 数据库，并准备本地 Antigravity 环境。

注意：此 Codelab 完全在本地机器上的 Google Antigravity 中运行。设置包括使用 gcloud CLI 命令进行手动身份验证

克隆初始代码库

在 Antigravity（或系统终端）中打开一个终端。克隆配套代码库并进入相应目录：

git clone https://github.com/alphinside/sdd-adk-antigravity-starter.git sdd-adk-agents-agy
cd sdd-adk-agents-agy

在 Antigravity 中打开克隆的代码库。文件->打开文件夹->选择克隆的目录 sdd-adk-agents-agy

移除上游远程。SDD 工作流会为功能规范创建 Git 分支，移除远程代码库可防止意外推送到初始代码库：

git remote remove origin

重要提示：此 Codelab 中的 SDD 工作流使用 git 分支来整理功能规范。移除 origin 远程库可确保您的本地分支和提交保持本地状态。如果您想备份自己的工作，请添加自己的遥控器：git remote add origin <your-repo-url>

安装必要工具

运行前提条件脚本。它会检查（并在缺失时安装）git、curl、gcloud、uv、Python 3.12 和 MCP 工具箱：

bash scripts/setup_prerequisites.sh

注意：下载所有前提条件需要一段时间，请打开新标签页继续执行下一部分，同时等待下载完成

向 Google Cloud 进行身份验证

运行两个身份验证命令。两者都会打开浏览器以进行 OAuth：

gcloud auth login
gcloud auth application-default login

注意：在第二个 OAuth 命令中，当系统提示您选择权限时。检查所有选项

注意：请务必使用您用于申请试用结算账号的电子邮件地址进行身份验证

由于您是在本地使用 Antigravity，因此需要手动进行身份验证。auth login 对 gcloud CLI 进行身份验证。application-default login 对应用使用的 Google Cloud SDK 进行身份验证 - ADK 的 Vertex AI 调用和 Cloud SQL Python 连接器都依赖于应用默认凭据。

设置您的 Google Cloud 项目

在运行项目设置脚本之前，将位置变量写入 .env：

echo "GOOGLE_CLOUD_LOCATION=global" > .env
echo "REGION=us-central1" >> .env

• GOOGLE_CLOUD_LOCATION=global 用于 Vertex AI / Gemini API 调用。
• REGION=us-central1 用于 Cloud SQL 和其他 GCP 基础架构

下载并运行项目设置脚本。它会创建或验证具有试用结算功能的 Google Cloud 项目，并将项目 ID 保存到 .env，然后获取该项目 ID：

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

bash setup_verify_trial_project.sh && source .env

启用必需的 API：

gcloud services enable \
  aiplatform.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  cloudresourcemanager.googleapis.com

注意：启用 API 可能需要一点时间。您只需为每个项目执行一次此操作。

预配 Cloud SQL

设置数据库密码并将其添加到 .env：

export DB_PASSWORD=codelabpassword
echo "DB_PASSWORD=${DB_PASSWORD}" >> .env

重要提示：上述硬编码的密码仅用于教程目的。在生产环境中，请使用 Secret Manager 等服务安全地存储凭据，并在运行时引用它们，切勿将明文密钥提交到源代码控制系统。

创建 Cloud SQL 实例：

gcloud sql instances create restaurant-db \
  --database-version=POSTGRES_17 \
  --edition=ENTERPRISE \
  --region=${REGION} \
  --availability-type=ZONAL \
  --tier=db-custom-1-3840 \
  --root-password=${DB_PASSWORD} \
  --enable-google-ml-integration \
  --database-flags cloudsql.enable_google_ml_integration=on &

db-custom-1-3840 层级是 Vertex AI ML 集成所需的最低层级。借助 --enable-google-ml-integration 标志，Cloud SQL 可以直接从 SQL 调用 Gemini 嵌入模型，从而实现语义搜索功能。

注意：此命令大约需要 5 分钟，将在后台运行。让它在此终端标签页中保持运行状态，并打开一个新的终端标签页以执行后续步骤。

安装依赖项

打开新的终端标签页。确保您仍位于克隆的代码库项目目录中，然后重新加载环境变量：

source .env

我们将使用 uv 作为 Python 项目管理器。uv 是一个用 Rust 编写的快速 Python 软件包和项目管理器（文档）。此 Codelab 使用它是因为它速度快且简单易用。安装 Python 依赖项：

uv sync

然后，使用项目配置更新 ADK 代理的 .env 文件：

cat > restaurant_concierge/.env <<EOF
GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True
EOF

现在，我们应该拥有所有必需的入门级 ADK 代理代码库，可以开始工作了。现在，在等待一切就绪的同时，我们将在下一部分中详细介绍 Antigravity 和规范驱动的开发

3. 探索起始代码并了解规范驱动型开发

此步骤将介绍起始代码结构、引入规范驱动开发方法、为数据库植入初始数据，并在您开始扩展基本代理之前验证其是否正常运行。

项目结构

在 Antigravity 编辑器中打开克隆的代码库项目，并查看目录布局：

sdd-adk-agents-agy/
├── .agents/
│   ├── workflows/                 # SDD slash commands (/speckit.*) – manual trigger
│   │   ├── speckit.specify.md
│   │   ├── speckit.clarify.md
│   │   ├── speckit.plan.md
│   │   ├── speckit.tasks.md
│   │   ├── speckit.analyze.md
│   │   ├── speckit.implement.md
│   │   ├── speckit.checklist.md
│   │   └── speckit.constitution.md
│   ├── skills/                   # Antigravity skills (loaded on demand, agent determined)
│   │   ├── adk-agent-development/
│   │   │   ├── SKILL.md     # ADK patterns
│   │   │   └── examples/
│   │   │       ├── basic_agent.py
│   │   │       ├── Dockerfile
│   │   │       ├── server.py
│   │   │       ├── stateful_agent.py
│   │   │       ├── toolbox_agent.py
│   │   │       ├── tools_agent.py
│   │   │       └── tools.yaml
│   │   └── repo-research/
│   │       └── SKILL.md     # Repo analysis 
│   └── rules/               # Always-active context
├── .specify/                # spec-kit SDD templates and memory
│   ├── memory/constitution.md
│   ├── templates/
│   └── scripts/
├── restaurant_concierge/    # ADK agent package
│   ├── __init__.py
│   ├── agent.py             # LlmAgent + ToolContext tools + Toolbox integration
│   └── .env                 # Vertex AI configuration
├── server.py                # FastAPI server wrapping the agent
├── tools.yaml               # MCP Toolbox tool definitions
├── scripts/                 # Setup scripts
└── pyproject.toml

关键文件

代理应用文件

• restaurant_concierge/agent.py - 核心代理。一个 LlmAgent，可将 MCP Toolbox 数据库工具与基于 ToolContext 的饮食偏好跟踪功能相结合。智能体从工具箱服务器加载所有工具，并添加两个使用 ToolContext 管理状态的 Python 函数 (save_dietary_preference, get_dietary_preferences)。
• tools.yaml - MCP Toolbox 工具定义。定义了三个菜单搜索工具：关键字搜索 (search_menu)、通过 pgvector 进行的语义搜索 (semantic_search_menu) 和类别过滤条件 (get_menu_by_category)。目前还没有预订工具，您稍后会添加这些工具
• server.py - 一个最小的 FastAPI 服务器，展示了如何以 FastAPI 对象的形式访问 ADK。ADK 中的 get_fast_api_app() 提供内置端点，包括用于 SSE 流式传输和会话管理 API 的 /run_sse。

Antigravity 文件

• .agents/skills/adk-agent-development/SKILL.md - 一项预配置的技能（由 Antigravity 生成），包含所有四项 ADK Codelab 中的精简参考模式。该页面目前处于非活动状态（缺少 YAML 前言），您需要稍后更新该页面。当 Antigravity 检测到与 ADK 代理功能及其示例相关的工作时，会自动加载此技能 - 这是 Antigravity 在稍后规划预订功能时所依据的知识
• .agents/skills/repo-research/SKILL.md - 一项技能，可教导 Antigravity 如何以增量方式分析代码库并生成结构化的项目上下文文档。它采用 4 阶段方法：表面扫描（仅限目录树）、配置文件和元数据文件、入口点和数据模型，然后进行有针对性的深入分析 - 每个阶段都会在继续下一个阶段之前停止并写入发现的结果。与 ADK 技能一样，在您稍后添加 YAML 前言之前，它处于无效状态。激活后，调用该工具以生成 .agents/rules/project-context.md，这是一份全面的初始配置文档，涵盖架构、运行时依赖项、API 接口和网域词汇表。

规范驱动的开发：从 Antigravity 的内置规划到结构化 SDD

AI 编码助理可让您轻松根据提示生成代码。风险：您用一句话描述了一项功能，助理写了数百行代码，您接受了它，因为它看起来没问题。这种方法有时称为“凭感觉编码” - 您凭感觉进行引导，根据输出是否有效来接受或拒绝输出。对于原型和临时脚本，它的速度很快。当代码库变大、功能相互交互或您在几周后重新查看代码时，如果无法重构做出某项决定的原因，就会出现问题。

规范驱动开发 (SDD) 为此循环添加了结构。在生成任何代码之前，您需要编写规范：功能的作用、服务对象、成功标准。AI 助理会根据该规范工作，您在查看其输出时也是如此。规范成为意图的单一可信来源。如果代码与规范不一致，您可以在审核时发现。如果要求发生变化，您需要先更新规范，然后再重新生成。决策有据可查，而非临时起意。

这种权衡是实际存在的：与振动编码相比，SDD 在每个特征上的速度较慢。您先编写文档，然后再编写代码。但回报会不断增加 - 代码库的每次未来更改都有上下文，每次 AI 生成的实现都有可审核的合同，您可以通过指向规范来让协作者（人类或 AI）加入项目，而无需凭记忆解释决策。

Antigravity 已经遵循规范驱动的开发原则。当您将代理设置为规划模式时，它会在编写任何代码之前生成两个制品：

• 实施计划 - 建议的技术方法、文件更改和架构决策的概览
• 任务列表 - 工作项的结构化细分

Antigravity 会要求您在执行之前查看并批准这些制品。这种先规划再实现的循环是规范驱动型开发的核心：规范指导代码，而不是反过来。

此 Codelab 基于 spec-kit（GitHub 提供的一个规范驱动型开发框架）进一步完善了这一基础，提供了一个有主见的受版本控制的工作流。每个功能都经过精心设计的流水线，其中每个制品都是一个独立的文档，您可以在 git 中查看、修改和跟踪。该流水线包含两个可选的质量门控阶段（明确和分析），可在问题成为实现问题之前发现它们：

阶段	工件	用途
/speckit.specify	spec.md	定义要构建的内容（面向用户，与技术无关）
/speckit.clarify （可选）	更新时间：spec.md	找出未明确指定的区域，提出有针对性的澄清问题，将答案重新编码到规范中
/speckit.plan	plan.md、data-model.md、research.md	设计如何构建（技术方法、数据模型、研究）
/speckit.tasks	tasks.md	将计划分解为有序的、可操作的步骤
/speckit.analyze （可选）	分析报告	在实施之前，检查任务是否存在风险、缺口或缺失的极端情况
/speckit.implement	代码更改	执行任务，并逐一勾选

每个制品都以文件形式持久保存在 specs/<feature-branch>/ 中，在 Git 中进行版本控制，并且可重复使用。如果对话中断，或者您想稍后重新查看决策，规范文档始终存在，不会埋没在聊天记录中。

注意：Antigravity 内置制品在界面中具有优势，可让用户对生成的制品（甚至是图片！）。因此，在本教程中，我们将修改原始 spec-kit 提示，以在 implement 阶段与内置制品集成

启动代码库在 .agents/workflows/ 中包含这些 SDD 工作流，在 .specify/templates/ 中包含模板。您稍后将使用这些功能来为代理添加功能。

4. 完成 Cloud SQL 设置并确保基本代理正常运行

切换回正在运行 Cloud SQL 创建命令的终端标签页。完成后，验证实例是否已准备就绪：

gcloud sql instances describe restaurant-db --format="value(state)"

如果输出显示 RUNNABLE，请继续操作。如果显示 PENDING_CREATE，请稍等片刻，然后重新运行该命令。

向 Cloud SQL 服务账号授予对 Vertex AI 的访问权限（数据库内嵌函数需要此权限）：

SERVICE_ACCOUNT=$(gcloud sql instances describe restaurant-db --format="value(serviceAccountEmailAddress)")

gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" \
  --quiet

创建数据库：

gcloud sql databases create restaurant_db --instance=restaurant-db

您应该会看到如下所示的输出

Creating Cloud SQL database...done.
Created database [restaurant_db].
instance: restaurant-db
name: restaurant_db
project: <your-project-id>

检查点：您的 .env 文件包含 GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION、REGION 和 DB_PASSWORD。Cloud SQL 实例 �3 正在运行。restaurant-dbtoolbox 可在您的 PATH 中找到（由 setup_prerequisites.sh 安装）。Python 依赖项已安装。

为数据库播种

加载环境变量并运行数据库种子脚本以创建架构并插入 16 个菜单项：

source .env
uv run python scripts/seed_db.py

预期输出：

Creating extensions...
Creating menu_items table...
Inserting 16 menu items...
Seeded 16 menu items.
Done.

生成用于语义搜索的向量嵌入：

uv run python scripts/generate_embeddings.py

预期输出：

Generating embeddings for 16 menu items...
Generated embeddings for 16 menu items.

此示例使用 Cloud SQL 的内置 embedding() 函数（通过 google_ml_integration 扩展程序）直接从 SQL 调用 gemini-embedding-001。3072 维向量存储在 menu_items 的 embedding 列中，无需应用端嵌入代码。

测试基础代理

将 MCP Toolbox 作为后台进程启动：

set -a; source .env; set +a # Export env variables to child process
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

该工具箱通过 HTTP 提供数据库工具。代理在 http://127.0.0.1:5000 连接到它。

启动 ADK 开发者界面：

uv run adk web .

在浏览器中打开开发者界面。然后，使用以下提示测试代理：

What appetizers do you have?

检查：代理查询数据库并返回菜单项

I'm vegetarian

检查：智能体将饮食偏好保存在智能体状态中

Can I make a reservation for tomorrow?

检查：智能体无法处理此问题（目前还没有预订工具）

按 Ctrl+C 两次，停止 ADK 开发者界面。让 Toolbox 在后台运行 - 您稍后会再次使用它

检查点：基本代理正常运行 - 菜单搜索（关键字 + 语义）和饮食偏好设置功能正常运行。预留请求失败，因为不存在预留工具。您了解项目结构以及您将要填补的空白。

5. 使用 Antigravity 引导项目上下文

现在，我们来模拟一种“更接近”日常工作的条件：

• 管理不善的代码库
• README 已过时
• 文档不会频繁更新

注意：如果此症状与您的状况不符，请认为自己非常幸运

在这种情况下，我们通常要做的第一件事是创建有关我们希望 Antigravity 处理的项目的地图或上下文。此步骤展示了一种方法示例，该方法通过创建分析代码库并生成项目上下文文档的技能，使 Antigravity 能够深入了解现有代码库。

它还会设置项目章程，即 SDD 工作流验证所依据的不可协商的原则。这些信息共同为 Antigravity 提供了后续 SDD 周期所需的上下文和限制

Antigravity 上下文层次结构

Antigravity 使用了三个级别的上下文，每个级别都有不同的范围：

• 规则 (.agents/rules/)：始终处于有效状态的指令。此工作区中的每次对话都会显示它们（如果您已启用）。使用规则来提供项目范围内的上下文，例如架构决策、编码标准或技术堆栈信息。
• 技能 (.agents/skills/)：按需获取知识。Antigravity 仅在当前任务与技能的 description 字段匹配时加载技能。使用技能获取特定领域的参考资料。
• 工作流 (.agents/workflows/)：通过 / 命令触发的已保存提示。使用工作流来处理可重复的多步流程，例如 SDD 流水线。

注意：该项目目前有工作流（SDD 流水线）和技能（ADK 代理开发），但没有规则。project-context.md 规则可让 Antigravity 持久了解代码库，包括所用的技术、文件的组织方式、目前已构建的内容。

激活技能

起始代码库在 .agents/skills/ 中包含两个预先编写的技能。它们包含详细说明，但以 TODO(codelab) 注释开头，而不是必需的 YAML 前言。如果没有前言，Antigravity 就无法发现这些内容。

反重力技能需要在文件顶部包含一个 YAML 前言块，其中包含两个字段：

• name - 技能的唯一标识符
• description - Antigravity 在决定为给定请求加载哪个技能时会与此自然语言摘要进行匹配

打开

.agents/skills/adk-agent-development/SKILL.md

在编辑器中。将顶部的两行 TODO(codelab) 注释替换为以下前言：

---
name: adk-agent-development
description: Comprehensive guide for building, developing, and deploying AI agents using Google's Agent Development Kit (ADK) with Gemini models, covering agent creation, tools, state management, persistence, deployment, and database integration via MCP Toolbox.
---

注意：ADK 智能体开发技能包含来自五个 ADK Codelab 的精简模式和示例 - 智能体结构、工具类型、状态管理、部署

打开

.agents/skills/repo-research/SKILL.md

在编辑器中。将顶部的两行 TODO(codelab) 注释替换为以下前言：

---
name: repo-research
description: Analyze a repository's structure, technologies, and patterns to create or update a project context document. Use when asked to research, analyze, or understand a codebase.
---

注意：请详细阅读 repo-research SKILL.md。以下是一个用于分析代码库的示例提示，请注意，增量更新规则有意保持保守。如果在研究过程中 Antigravity 的上下文用完或对话中断，目前为止发现的所有内容都已保存到文件中。重新调用技能后，系统会从上次中断的位置继续，而不会丢失进度。

警告！分析大型代码库可能会快速耗尽您的配额！

验证这两个技能是否都具有有效的前言：

head -4 .agents/skills/adk-agent-development/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md

每个都应显示用 --- 分隔符封装的 name: 和 description: 字段。如果分隔符或字段缺失，Antigravity 将无法识别该技能。

这两项技能都是按需加载的 - Antigravity 会根据 description 字段将您的请求与完整指令进行匹配，只有在相关时才会提取完整指令。

生成项目上下文

确保规则目录存在：

mkdir -p .agents/rules

在 Antigravity 的代理管理器/聊天框中（在编辑器模式下按 ctrl + L），开始新的对话。Type:

Research this repository and create a project context document

Antigravity 会将您的请求与 repo-research 技能相匹配，并开始系统地分析代码库。它会读取配置文件、源代码和文档，然后根据自己的发现填充项目上下文模板。

完成后，在编辑器中打开 .agents/rules/project-context.md。其中包含有关项目的具体信息：技术堆栈（Python 3.12、ADK、MCP Toolbox、Cloud SQL）、项目结构、数据模型（包含 pgvector 的 menu_items 表）和外部集成。

提示：项目背景文档会随着项目的发展而不断完善。您可以重新运行技能，以使用新添加的内容更新上下文。增量更新规则可确保保留现有内容，并附加而非覆盖新技术、实体和集成。

对于有针对性的更新，请使用具体提示：“研究数据库架构并更新项目上下文”或“使用新的工具定义更新项目上下文”。每次调用都会添加到现有文档中。

设置项目章程

在规划和分析期间，SDD 工作流会在 .specify/memory/constitution.md 中引用项目章程。/speckit.plan 工作流会针对该文件运行“宪法检查”，并将违规行为标记为“严重”。/speckit.analyze如果章程留空，仅包含占位符令牌，这些检查将没有可供验证的内容，因此计划和分析将在没有安全防护的情况下运行。

章程定义了不可协商的项目原则。这是一个由单个开发者维护的小型代码库，因此章程应反映该范围 - 保持简单、一致，避免过度设计。

在 Antigravity 的代理管理器中，开始新的对话。运行宪法工作流：

/speckit.constitution This is a small restaurant concierge ADK agent maintained by one developer. Set 3 principles: (1) All database operations go through MCP Toolbox tool definitions in tools.yaml — no raw SQL in Python code, no ORM. (2) Session state uses ADK ToolContext — no custom state management, no external state stores. (3) Keep it simple — follow existing file and naming conventions exactly.

Antigravity 会使用具体原则填充宪法模板，分配版本 (1.0.0)，并跨 SDD 模板运行一致性检查。

在 .specify/memory/constitution.md 中查看生成的宪法。验证这三项原则是否已明确列出。

注意：该章程特意只保留了 3 项原则，以供单人开发者参考。/speckit.constitution 工作流支持增量修订 - 再次运行该工作流并添加更多原则，它会自动处理版本控制。对于团队项目，您需要添加有关代码审核、测试规范、可观测性和 API 版本控制的原则。

检查点： .agents/rules/project-context.md 存在，其中包含有关代码库的具体信息。.agents/skills/repo-research/SKILL.md 演示了如何使用 YAML 前言、指令和冲突解决来创建技能。.specify/memory/constitution.md 包含计划和分析工作流验证所依据的三个项目原则。您了解三级上下文层次结构：规则（始终处于有效状态）、技能（按需）和工作流（斜杠命令）。

6. SDD 周期 - 添加预留功能

此步骤将介绍完整的 SDD 周期，以向餐厅礼宾代理添加预订功能。您将通过每个阶段（指定、阐明、规划、任务、分析、实施）来驱动 Antigravity，并观察每个制品如何在前一个制品的基础上构建。这是本 Codelab 的核心学习体验。

重要提示！Antigravity 是一款 AI 助理，其生成的制品（规范、计划、任务、代码）可能与本教程中的描述有所不同。文件名、确切的 SQL 架构和代码结构可能会有所不同。这是正常现象，也是 AI 辅助开发的一部分。SDD 工作流可确保您在每个制品成为代码之前对其进行审核，因此请自行判断是否接受、修改或重新生成任何不符合您预期的输出。

指定功能

在 Antigravity 的代理管理器中，开始新的对话。输入 /speckit.specify 工作流命令，并附上功能说明：

/speckit.specify Add reservation booking capability to the restaurant concierge agent. Guests should be able to make a table reservation by providing their name, party size, date, and time. They should also be able to check existing reservations. The agent should confirm reservation details before booking and handle special requests (e.g., "window seat", "birthday celebration").

Antigravity 会创建功能分支、生成规范文档并运行质量验证。如果 Antigravity 提出澄清问题，请根据上述功能说明回答这些问题。

注意：完成规范后，Antigravity 可能会显示“制定技术方案”或“明确规范要求”等移交任务。这些是下一个工作流阶段（/speckit.plan 或 /speckit.clarify）的提示

该规范侧重于“内容”和“原因”，而不是“方法”。它描述了用户体验（“Guest can book a reservation by providing their name, party size, date, and time”），但未提及 SQL 表、tools.yaml 或 ADK API。实现细节在规划阶段确定。

查看 specs/<branch-name>/spec.md 中生成的规范。验证它是否捕获了功能要求和成功标准。

澄清规范（可选）

运行澄清工作流程，以识别和解决规范中未明确指定的区域：

/speckit.clarify

Antigravity 会扫描规范，查找模糊不清之处、缺失的验收标准和未充分指定的要求。它会提出有针对性的澄清问题，每个问题都可以用简短的选择或短语回答。您的回答会直接编码回规范中，从而在规划开始之前提高规范的精确度。

提示：澄清步骤是可选的，但建议您针对复杂功能执行此步骤。对于简单的规范，请直接跳到规划阶段。

规划实施

运行规划工作流：

/speckit.plan

Antigravity 通过两个阶段生成技术方案：

1. 研究阶段 - 解决有关现有代码库的未知问题，生成 research.md
2. 设计阶段 - 创建 data-model.md（预订实体定义）并更新 project-context.md

在规划时，Antigravity 应使用 adk-agent-development 技能。查看关键制品：

• specs/<branch-name>/plan.md - 技术方法：要修改哪些文件，要遵循哪些模式
• specs/<branch-name>/data-model.md - 预留实体定义（列、类型、关系）
• specs/<branch-name>/research.md - 做出的决定和理由

生成任务

运行任务工作流

/speckit.tasks

Antigravity 会将方案分解为 specs/<branch-name>/tasks.md 中的有序任务列表。任务遵循严格的清单格式，包含 ID、优先级标记和文件路径，例如：

- [ ] [T001] [P] Create reservations table schema in scripts/seed_db.py
- [ ] [T002] [P] Add create_reservation tool to tools.yaml
- [ ] [T003] [P] Add list_reservations tool to tools.yaml
- [ ] [T004] [P] Update agent instruction in restaurant_concierge/agent.py

任务分为以下阶段：设置 → 基础 → 用户故事 → 润色。扫描任务列表，了解将创建和修改哪些内容。

分析任务（可选）

运行分析工作流，查看任务是否存在风险和缺口：

/speckit.analyze

Antigravity 会根据规范和计划检查任务列表，查找缺失的极端情况、可能冲突的任务，或规范的要求与计划的工作之间的差距。在实施之前解决严重问题。

提示：当任务列表较长或功能涉及多个子系统时，分析步骤最为有用。对于预订等重点功能，快速扫描就足够了。

7. 实现

运行实现工作流：

/speckit.implement

Antigravity 提交最终的实施计划和任务制品。查看并批准该请求，然后继续

提示：您可以直接发表评论！此操作只能通过 Antigravity 内置制品完成

Antigravity 会执行任务，并在完成每项任务后将其勾选。完成后，系统会显示完整的演练

测试代码更改

实现完成后，验证是否已进行关键更改。确切的文件名和内容可能会有所不同，但应存在与 tools.yaml 和 agent.py 中类似的模式：

# Verify reservation tools were added to tools.yaml
grep -i "reservation" tools.yaml

您将看到类似于以下内容的输出

...
get_reservations_by_name:
      Retrieve all reservations for a guest by their name. Uses case-insensitive
      SELECT id, guest_name, party_size, reservation_datetime, special_requests, created_at
      FROM reservations
      ORDER BY reservation_datetime DESC
...

对于 agent.py

# Verify agent instruction was updated
grep -i "reservation" restaurant_concierge/agent.py

# Check what files changed
git diff --name-only

您可能会看到如下变化

...
- **Table Reservations**: Help guests book a table or check their existing reservations.
## Reservation Booking Rules
When a guest wants to make a reservation, collect ALL of the following before confirming:
**IMPORTANT**: Before calling `book_reservation`, you MUST:
- Only call `book_reservation` after the guest says "yes" or "confirm"
## Checking Reservations
When a guest asks to check their reservations:
- Use `get_reservations_by_name` to find their bookings
        book_reservation,
...

注意：如果 grep 未返回任何匹配项，则实现可能使用了不同的命名。检查 git diff 以查看完整的更改集，并验证是否已添加与预留相关的逻辑。

这些更改应该会影响种子数据库脚本，我们来尝试执行它

source .env
uv run python scripts/seed_db.py

更新后的脚本应在 reservations 表尚不存在时创建该表。您应该会看到输出，确认已创建新表（现有 menu_items 数据已保留）。

注意：Antigravity 可能已创建单独的迁移脚本（例如，scripts/create_reservations.py)，而不是更新 seed_db.py。检查 git diff --name-only 中是否有 scripts/ 中的任何新脚本，并运行这些脚本。

如果到目前为止一切顺利，我们就可以在 ADK 代理 Dev 界面上测试该功能了。重启 Toolbox 以选取 tools.yaml 中的新工具定义。停止所有现有的 Toolbox 进程，然后启动一个全新的进程：

pkill -f toolbox 2>/dev/null
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

启动 ADK 开发者界面：

uv run adk web .

在浏览器中打开 http://localhost:8000，然后使用以下提示进行测试：

I'd like to book a table for 4 people on Friday at 7pm under the name Timmy

检查：代理应确认预订详细信息并创建预订

Do I have any upcoming reservations?

检查：代理应列出您刚刚创建的预留

现在，按 Ctrl+C 两次，停止 ADK 开发者界面。

检查点：代理处理预订和查找。您已完成完整的 SDD 周期：指定 → 明确 → 规划 → 任务 → 分析 → 实现 → 测试。每个阶段都在 specs/<branch-name>/ 中生成了一个版本化工件。

8. 挑战（可选）

现在，您已了解完整的 SDD 工作流程。测试一下：

• 运行第二个 SDD 周期，为餐厅礼宾服务构建一个网络聊天界面，这次没有分步指南。
• 将代理部署到 Cloud Run 以用于生产场景

提示

• 项目没有前端框架。Antigravity 应建议使用纯 HTML/CSS/JS - 如果它建议使用 React 或类似技术，请引导它走向简单（您的宪法中的“保持简单”原则应能发现这一点）。
• ADK 服务器公开了 /run_sse 以用于流式传输，并公开了 /apps/{app_name}/users/{user_id}/sessions 以用于会话管理。Antigravity 会从项目上下文中发现这些内容。
• 实现后，使用 uv run uvicorn server:app --host 0.0.0.0 --port 8080（而非 adk web）启动服务器，以便静态文件装载正常运行。
• 在 http://localhost:8080/static/index.html 进行测试。
• 参考 Codelab 已展示如何部署和持久化 ADK 代理，请向 Antigravity 提供相关参考！

9. 恭喜！

您已通过 Antigravity 的 SDD 工作流扩展了餐厅礼宾 ADK 代理，使其具备预订功能，而无需手动编写应用代码。

您构建的内容

• 一个餐厅礼宾 ADK 代理，具有菜单搜索、语义搜索、饮食偏好跟踪和预订功能
• 一种用于代码库研究的 Antigravity 技能，可生成和维护项目上下文文档
• 在规划和分析期间强制执行不可协商原则的项目章程
• 完整的 SDD 周期，展示了指定 → 澄清 → 规划 → 任务 → 分析 → 实现工作流

要点回顾

• 如何在 Antigravity 中使用规范驱动开发工作流，以系统地向现有代码库添加功能
• 如何创建 Antigravity 技能，将领域知识打包以便在对话中重复使用
• 如何引导项目上下文，以便 Antigravity 针对架构、模式和技术选择做出明智的决策
• 如何设置 SDD 工作流验证的项目章程
• 如何通过 MCP Toolbox 使用新的数据库支持的工具来扩展 ADK 智能体

清理

停止所有正在运行的本地进程 (Toolbox)：

pkill -f toolbox 2>/dev/null

删除 Cloud SQL 实例，以免持续产生费用：

gcloud sql instances delete restaurant-db --quiet

（可选）删除整个项目：

gcloud projects delete $GOOGLE_CLOUD_PROJECT

重要提示：您可以使用以下命令在有限的时间内撤消此删除操作：gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}