讲师指南¶

研讨会讲师内部指南。请勿与参与者分享。

概述¶

这是一个关于 Antigravity CLI 的 5 个模块、约 7 小时的动手实践研讨会。它专为开发者受众设计：包括正在评估或采用 Antigravity CLI 的工程师、技术主管和解决方案架构师。

Gemini CLI 停用时间：2026 年 6 月 18 日

Gemini CLI 将于 2026 年 6 月 18 日 结束生命周期。当参与者询问有关迁移的问题时，请引导他们使用 agy plugin import gemini —— 这是主要的迁移路径。所有 Gemini CLI 插件都可以通过一条命令完成迁移。

交付形式¶

形式	模块	时长
⚡ 闪电	模块 1 + 模块 2 重点	1.5 小时
📋 半天	模块 1 + 2	2.5 小时
📦 全天	模块 1–4	~5.5 小时
🏗️ 扩展	全部 5 个模块 + 开放实验	7 小时

研讨会前检查清单¶

[ ] 参与者已安装并验证 Antigravity CLI （参见 setup.md）
[ ] 已分发身份验证详细信息（特定于当前场次 — 请与 agy-cli 团队确认）
[ ] 参与者已安装 Git 并准备了合适的演示代码库
[ ] 讲师已在当前 agy-cli 版本上端到端地跑通了所有练习
[ ] 屏幕共享/投影已测试
[ ] 对于模块 2：确认参与者可以运行 dotnet 或 mvn（或使用提供的容器）
[ ] 对于模块 3：确认 pip install google-antigravity 和 gcloud auth application-default login 可以正常工作
[ ] 对于模块 5：确认已安装 uv 和 agents-cli（uvx google-agents-cli setup）

身份验证是第一大故障点

请务必在会议开始前 30 分钟运行研讨会前的身份验证检查：

agy --print "Say READY" --print-timeout 30s

如果参与者无法获得响应，请在开始前停止并进行调试。

逐模块授课说明¶

模块 1 — SDLC 生产力提升 (75 分钟)¶

核心信息： agy 替代了在陌生代码库中导航的脑力负担。它不是自动补全——它是一位你可以询问任何问题的高级工程师。

先演示，后练习。 在要求参与者尝试自己的代码库之前，先在你自己的代码库上进行 1.1 节（代码理解）的现场演示。
常见阻力： 参与者试图编写完美的提示词。鼓励使用自然语言。“告诉我 auth 是如何工作的”比“请解释此代码库的身份验证架构”更好。
AGENTS.md 时刻： 1.5 节是一个高价值的演示。在屏幕上现场创建一个 AGENTS.md，并展示下一个会话如何立即变得更智能。
插件导入演示（1.7 节）： 现场运行 agy plugin import gemini——视觉输出非常引人注目。注意：自定义主题在导入期间会被静默丢弃，并且无法迁移。如果参与者问为什么他们的主题没有带过来，这是预期行为——没有错误，该组件只是被跳过了。

模块 2 — 遗留代码库现代化 (90 分钟)¶

核心信息： 严格模式 + 自主引导将长达一周的迁移变成一个结构化的下午。代理编写自己的上下文，然后执行它。

现场演示脚本（推荐）：

克隆 .NET 或 Java 目标仓库（为节省时间已提前完成）
进入严格模式：/permissions strict
运行调查提示词——向参与者展示代理读取整个代码库的过程
让代理生成一个 AGENTS.md——大声读出来以展示它捕获了真实的上下文
ctrl+g——在编辑器中打开生成的计划，进行一次可见的编辑以展示人工控制
切换到 request-review，仅执行阶段 1
展示 /rewind——如果出现任何问题，则撤销该阶段
演示总时长：约 15 分钟，然后由参与者自己动手操作
常见问题： “它可以完成整个迁移吗？”——可以，但价值在于审查和引导，而不仅仅是看着它运行。鼓励他们编辑计划。
讲师时间把控提示： 阶段 0–1 加起来每个参与者大约需要 20 分钟。让他们在您巡视指导时完成阶段 2。

模块 3 — 使用 SDK 构建 AGY 代理 (90 分钟)¶

核心信息： CLI 是为个人准备的。SDK 代理是整个团队都可以调用的专家服务。

环境设置关卡： 在开始之前，确保每个人都安装了 google-antigravity，并且 Vertex AI 或 AI Studio 身份验证正常工作。这是最常见的障碍。
adk web . 时刻： 一旦参与者让他们的第一个代理在浏览器 UI 中运行起来，气氛就会改变——他们会看到它对他们的工具做出响应。
模型选择表： 强调使用 Flash-lite 进行生成，使用 Pro 进行编排。成本意识是一项特性，而不是妥协。
练习 11（流水线）： asyncio.gather + START_SUBAGENT 多代理模式是关键的架构洞察。在他们开始之前，花 5 分钟解释子代理是如何组合的。

模块 5 — 使用 agents-cli 构建 ADK 代理 (75 分钟)¶

核心信息： agents-cli 将您的编码代理变成 ADK 专家。7 阶段生命周期（脚手架 → 构建 → 评估 → 部署）是代理从演示走向生产环境的关键。

环境设置关卡： 确保已安装 uv 和 agents-cli。运行 agents-cli info 进行验证。
评估循环是教学的关键时刻。 在阶段 4（评估）上花些时间——这是区分玩具和生产级代理的关键。让参与者看到分数不达标，然后进行迭代。
google-adk ≠ google-antigravity： 模块 3 使用 google-antigravity（Antigravity SDK）。模块 5 使用 google-adk（ADK）。它们是不同的包。agents-cli scaffold 会自动管理正确的依赖项。
练习 12 节奏把控： 第 1–2 部分进展很快（脚手架 + 构建）。第 3–4 部分（评估 + 修复循环）是花费时间的地方。强调 5–10 次迭代是正常的。

模块 4 — 多代理与高级模式 (60 分钟)¶

核心信息： 子代理 + /btw 是质的飞跃。这是 agy 成为编排器而不仅仅是聊天机器人的地方。

子代理演示是令人惊叹的时刻。 现场生成两个代理，展示它们同时运行。
/btw 演示： 开始一个较长的任务（重构一个文件），然后在任务中途使用 /btw。向参与者展示在合并注入的笔记时，光标仍在继续移动。
调度： 从概念上描述该模式，不要进行现场演示（延迟会使其在工作坊中显得很尴尬）。

常见学员问题¶

问题	解答
"agy 使用什么模型？"	使用 `/model` 查看和切换。请参阅模型文档。
"这与 Gemini CLI 有什么不同？"	agy 桥接了来自 Gemini CLI 和 Claude 的插件，具有原生的子代理编排功能，以及 `/btw` 任务中途引导功能。Gemini CLI 将于 2026 年 6 月 18 日停止支持（EOL）。
"我可以使用自己的 API 密钥吗？"	agy 使用基于浏览器的 Google 登录。企业级用户连接 GCP 项目。请参阅企业级文档。
"代码会发送给 Google 吗？"	有关数据处理的详细信息，请参阅常见问题解答 (FAQ)。
"钩子怎么处理？"	agy-cli 通过 `hooks.json` 支持钩子。请参阅钩子文档。
"对话日志存储在哪里？"	`~/.gemini/antigravity/conversations/`
"我的 Gemini CLI 主题没有导入。"	这是符合预期的 —— 在执行 `agy plugin import gemini` 期间，自定义主题会被静默丢弃。技能、MCP 服务器和代理会结转过来。
"我可以将 SDK 代理部署到 Cloud Run 吗？"	可以 —— 使用 `adk deploy cloud_run`。请参阅模块 3 第 3.6 节。

研讨会期间的故障排除¶

症状	解决方法
`agy: command not found`	检查 PATH。运行 `which agy` 或 `which agy-cli`。
身份验证错误 / 401	会话凭据可能已过期。重新分发身份验证信息。
`agy plugin list` 错误	检查 `~/.gemini/antigravity/` 是否存在
响应缓慢	检查网络。空闲后的首次运行可能会因为工作区索引而变慢。
子代理未生成	确认参与者处于交互模式（而不是 `--print`）
`google-adk` 导入错误 (M3)	确保 venv 已激活：`source .venv/bin/activate`
Vertex AI 403 (M3)	运行 `gcloud auth application-default login` 并确认已设置 `GOOGLE_CLOUD_PROJECT`

研讨会后¶

使用标准的研讨会反馈表收集反馈
记录观察到的任何 agy-cli 错误或意外行为 — 报告给 agy-cli 团队
任何需要变通方法的练习都应在 CONTRIBUTING.md 中标记，以便更新文档