1. 确定现代化改造之旅的方向
这篇全面的 Codelab 是直接从架构深度剖析文章如何使用 Antigravity 和多代理编排实现现代化自动化中派生出来的实践配套实验。虽然我们使用经典的 Node.js 框架交换作为具体的演示载体，但您将在此处掌握的核心设计模式、目录结构和代理编排流程完全与语言无关，可普遍适用于任何大规模的旧版现代化项目。
与仅在单个文件中自动补全代码行的标准编码助理不同，您将学习如何利用 Google Antigravity 的智能体优先功能来编排由专业 AI 子智能体组成的自主团队。这些智能体可以独立对旧版代码库进行逆向工程、编写严谨的测试套件、搭建现代架构，并使用反思循环自我修正编译器错误，而您作为高级架构师可以保持绝对控制权。
学习内容
- 工作流映射：如何正确分类并分离确定性设置任务与复杂的启发式重构挑战。
- 技能架构：如何使用逐步披露和 YAML 路由元数据来构建可扩展的代理技能包。
- 编排设计模式：如何通过串联 Router、Plan-and-Execute 和 Reflexion 设计模式来推动大规模重构。
- 严格的输入/输出合同：如何在多阶段逆向工程和目标支架流水线中强制执行清晰的输入/技能/输出边界。
- 对等性验证：如何利用 Antigravity 的浏览器子代理在 Chrome 网络浏览器中执行并排对等性测试。
构建内容
您将编排一个完全自动化的绿地重构流水线，该流水线将采用标志性的过时旧版 Express 和 Mongoose CRUD 单体式应用（“madhums 演示版”）并从头开始自主重建，将其转换为由 MongoDB、严格的 Zod 验证和可访问的 ShadCN 界面组件支持的严格类型化 Next.js App Router 应用。
所需条件
- 本地安装的 Google Antigravity IDE（可在 antigravity.google 中使用）。
- 本地已安装 Node.js (v18+)。
- 用于自动执行界面验证的 Chrome 浏览器。
- 开源 modernizing-expressjs 演示 monorepo 的克隆。
2. 设置现代化环境
在让自主代理处理过时的旧版代码库之前，我们必须建立一个干净且高度稳定的单代码库环境。为 AI 助理提供干净的基准可确保它完全专注于生成高质量的现代代码，而不是浪费令牌来应对存在了十年的软件包漏洞或编译器不匹配问题。
旧版 Express 与现代 Next.js 架构的对应关系
组件 | 旧套装 | 现代替代方案 | 基本原理 |
架构 | Express Monolith | Next.js 应用路由器 | 将逻辑分离到服务器组件中，以优化渲染和 React 服务器组件 (RSC) 性能。 |
数据逻辑 | Mongoose (ODM) | MongoDB + Zod | 将隐式 ORM 钩子替换为显式、类型安全的 Zod 架构和原始驱动程序性能。 |
语言 | CommonJS / JavaScript | TypeScript (ESM) | 强制执行编译时安全并改用现代模块标准。 |
前端 | Pug/EJS（服务器视图） | ShadCN UI + Tailwind | 从僵化的模板转向可组合、无障碍且实用至上的设计系统。 |
身份验证 | Passport.js | NextAuth | 通过内置支持 Edge 和现代提供商的功能，实现会话管理现代化。 |
安全 | 手动中间件 | Zod（严格验证） | 在整个堆栈中实现“单一可信来源”的数据验证。 |
初始化现代化改造中心
我们的第一个确定性操作是克隆隔离的单体代码库结构。这会将只读的旧版代码与新的绿地目标代码库分开，确保不会意外更改原始应用。
打开 Antigravity 终端，然后运行以下设置命令：
git clone https://github.com/GoogleCloudPlatform/devrel-demos.git cd devrel-demos/other/modernizing-expressjs
克隆完成后，直接在 Antigravity IDE 探索器中打开 modernizing-expressjs 文件夹。您将看到以下隔离布局：
/modernizing-expressjs/ ├── .agents/ # Skills metadata and checklists │ └── skills/ ├── docs/ # Target directory for reverse-engineered markdown artifacts ├── legacy-app/ # Read-only root of the legacy Express monolith ├── modern-app/ # Greenfield target repository for the Next.js rewrite ├── GEMINI.md # Project-wide agent constitution └── README.md # Companion documentation
观看这段简短的视频演示，了解如何确定性地准备和隔离您的 monorepo 环境：
3. 设计 AI 智能体技能包和模式
编写可靠的智能体技能与编写标准聊天提示从根本上来说是不同的。编写技能包时，您是在设计一个模块化软件，底层 LLM 将自主执行该软件。为防止智能体产生幻觉或遇到“上下文窗口税”，我们推出了开源的 Greenfield Orchestration Skill Pack，这是一个可扩展的编写模板，遵循两个不可协商的原则：简洁性和逐步披露。
使用 YAML 元数据路由逐步揭示游戏内容
我们不会将所有目标规则都放入单个庞大的系统提示中，而是将指令分布在各个目录中。每个技能目录都包含一个 SKILL.md 入口点，该入口点封装在 YAML 路由前言块中。
打开 .agents/skills/orchestrating-greenfield-migration/SKILL.md 并检查路由器元数据：
---
name: orchestrating-greenfield-migration
description: >
Manages the end-to-end modernization of legacy Express
monoliths into Next.js architectures. Orchestrates subagents
for auditing, scaffolding, and verification. Use when starting
or managing a greenfield rewrite project.
---
对规划和执行模式进行硬编码
为防止自主代理出现漂移、被有趣的旧版中间件分散注意力或尝试未经授权的数据库交换，我们通过将规划和执行模式直接硬编码到指令中，来替换标准的开放式规划。
检查嵌入在主编排器中的字面 Markdown 核对清单：
### Phase 1: The AI audit (reverse engineering)
Dispatch subagents to produce specifications while identifying project-specific test scenarios.
* [ ] Init `docs/verification/Verification_Plan.md` to create baseline template.
* [ ] Run `auditing-data-models` -> Append Data Integrity Stress-Tests.
* [ ] Run `auditing-api-contracts` -> Append API Parity & Edge Case Probes.
* [ ] Run `auditing-business-logic` -> Append Logic & Authorization Stress-Tests.
* [ ] Run `auditing-ui-archeology` -> Append Interaction & Layout Targets.
通过将工作流格式化为包含内嵌技能参考的明确核对清单，代理会将此确切的路线图复制到其任务计划中，并将其锁定为“仅执行”模式，以便系统地勾选复选框并在需要时调用高度专业化的子代理。
4. 第 1 阶段 - 对旧版单体应用进行逆向工程（审核）
我们已准备好触发主要编排序列！我们的第一个主要阶段是从旧版单体应用中提取业务规则、数据架构和 API 载荷，并将它们存储为干净的 Markdown 制品，同时抛弃了长达十年的命令式技术债务。
触发自主重构序列
在 Antigravity Agent Manager 对话面板中，输入以下自定义斜杠命令，然后按 Enter 键：
/orchestrating-greenfield-migration
现在，观察终端控制台。您将看到主代理读取其系统提示，将您的请求与编排器的元数据进行匹配，输出 5 阶段清单，并立即开始并行调度专业的“审核员”子代理。
输入/技能/输出教学合同
在第 1 阶段，代理会执行严格的反向工程流水线，并受以下指令合同约束：
消耗的输入：位于 legacy-app/ 内的只读旧版源代码文件。
调用的技能：
技能 | 说明 |
| 跟踪旧版路由，以记录确切的 JSON 响应信封。 |
| 对 Mongoose 架构进行解构，以提取关系、必填字段和默认值。 |
| 记录了隐式副作用、Passport 身份验证流程和中间件规则。 |
| 扫描旧版 Pug 模板，以映射高级“界面意图”（导航栏、表单）。 |
生成的制品：直接生成到 docs/ 文件夹中的高度结构化 Markdown 规范
工件 | 说明 |
| 本文档详细介绍了旧版 Express 应用的逆向工程 API 表面积。在现代化 Next.js 应用中重建路由时，请使用此目录来确保严格的对等性。 |
| 本文档记录了旧版 Express 应用在身份验证 (AuthN)、授权 (AuthZ)、全局中间件、会话管理和副作用方面的已验证行为、配置和严格规则。 |
| 本文档全面分析了 |
| 本文档详细分析了 |
观看此终端实时捕获画面，了解自主逆向工程审核的实际运作情况：
5. 第 2 阶段和第 3 阶段 - TDD 框架和全新后端脚手架
在对旧版应用进行全面审核和记录后，主编排器会继续搭建现代目标后端。此阶段引入了我们工具包中最强大的代理式设计模式：由严格的测试驱动开发 (TDD) 驱动的闭环 Reflexion（自我反思）。
使用 Reflexion 循环驱动自我修复代码
编写现代代码非常简单；但要确保代码能够完美编译并顺利通过严格的验证限制，需要进行闭环评估。编排器通过将测试输出直接传递回子代理的上下文窗口来自动处理此问题：
- 阶段 2（TDD 设置）：编排器调用
generating-api-tests子代理，该子代理读取docs/API_Contracts.md并写入详尽的 Vitest 集成测试套件，以断言确切所需的 HTTP 状态代码和 JSON 载荷。正如 TDD 中所预期的那样，这些测试最初会失败。 - 第 3 阶段（后端框架）：框架子代理开始编写新式 Next.js 路由处理程序和严格的 Zod 验证架构。
- 自我纠正循环：当确定性 Vitest 框架评估新代码并返回失败结果（例如，预期的
422验证错误返回了500）时，智能体不会崩溃。它会反思目标错误输出，重新打开目标路由处理程序，修复 Zod 架构载荷结构，然后再次运行测试。它会自主迭代，直到实现0的退出代码。
输入/技能/输出教学合同
消耗的输入：逆向工程规范制品（docs/API_Contracts.md、docs/Data_Models.md）。
调用的技能：
技能 | 说明 |
| 生成失败的 Vitest 集成套件。 |
| 初始化基本 Next.js 应用路由器布局。 |
| 配置本地 Vitest 测试运行器环境。 |
| 将旧版 Mongoose 模型转换为 MongoDB + Zod 架构。 |
| 将 Express 路由重新构建为 Next.js 路由处理程序和模块化路由保护机制。 |
生成的输出：初始失败的 Vitest 测试套件、完全类型化的 Zod 架构、功能性 Next.js 路由处理程序，以及干净的通过测试的测试套件执行。
观察 TDD 测试框架的自动生成：
观察自我修正的 Reflexion 循环实时执行，为目标后端搭建框架：
6. 第 4 阶段 - 搭建现代前端（界面组件）
在后端验证层完全强化并顺利通过集成测试后，主编排器会转移上下文以实现视觉呈现的现代化。舍弃了命令式服务器渲染模板，转而采用高度无障碍的实用程序优先组件设计系统。
将界面意图转换为可组合的视图
前端子代理不会尝试逐行翻译 CSS，而是读取提取的“界面意图”清单，并将结构化元素直接映射到高保真度的现代等效项。
输入/技能/输出教学合同
消耗的输入：逆向工程前端制品清单 (docs/UI_Inventory.md)。
调用的技能：
技能 | 说明 |
| 将 |
生成的输出：使用高度无障碍的 ShadCN 界面组件和 Tailwind CSS 实用程序布局构建的、可用于生产用途的 Next.js 前端页面。
观看现代化前端视图层的自主生成过程：
7. 第 5 阶段 - 验证和对抗性审核
我们的重构流水线以严格的质量扫描结束。主编排器从静态代码分析过渡到主动运行时环境测试，主动尝试破坏新的目标应用，以证明其与旧版基准的绝对功能对等性。
执行双标签页测试和浏览器促动
验证阶段利用 Antigravity 的集成式视觉和 DOM 功能来自动证明成功，无需您手动点击表单：
- 并排对比：
auditing-parity子代理指示本地运行程序同时启动旧版 Express 单体式应用和现代化 Next.js 应用，以验证它们是否具有相同的视觉呈现效果和数据呈现效果。 - 对抗性安全探测：编排器调用
adversarial-verification子代理，后者启动 Antigravity 浏览器子代理。这种专用智能体可直接驱动浏览器，在输入框中输入内容、提交表单，并探测安全回归、损坏的会话 Cookie 或未处理的极端情况。 - 生成审核轨迹：浏览器子代理会自动记录会话操作的 WebP 视频捕获，并将其直接附加到最终迁移报告中，作为可验证的“工作证明”。
输入/技能/输出教学合同
消耗的输入：在本地运行时环境中并行运行的旧版应用和现代应用。
调用的技能：
技能 | 说明 |
| 执行运行时并排验证检查。 |
| 使用自动化浏览器操作来探测逻辑缺陷和功能回归。 |
生成的输出：全面的功能对等性审核跟踪记录，以及确认完全成功的已录制浏览器会话视频。
观察自动化浏览器子代理主动验证现代化应用：
8. 迁移后的生产环境就绪情况和后续步骤
恭喜！您已成功编排了一个高度先进的自主智能体重构流水线，从头开始对旧版单体应用进行现代化改造，并学习了通用且高度可迁移的技能，例如逐步披露、计划与执行清单和自我修复反思循环。
为生产部署做准备
在 Next.js 应用完全通过验证和审核后，您就可以开始进行生产环境集成。不妨考虑实施以下行业标准后续步骤：
- 增量路由：部署反向代理（例如绞杀榕模式），以将流量从旧版 Express 应用逐步路由到新版目标。
- 搜索引擎优化 (SEO) 保留：将旧版 Express 路由映射到 Next.js 永久重定向 (
_redirects.yaml)，以保留现有域名权威性。 - 数据流式传输：从静态数据库初始配置迁移到实时生产数据流式传输，在运行时使用严格的 Zod 架构进行安全验证。
- 可观测性：使用结构化 OpenTelemetry 框架替换命令式日志记录实用程序。
深入了解现代化改造
如需探索此流水线的完整底层代码库、自定义技能指令和详尽的理论依据，请务必阅读完整的父文章以及其他多智能体编排内容。
加入 Agentic Builder 社区
希望这些通用重构模式和智能体流水线对您有所帮助。请通过以下专业渠道关注我，及时了解未来的开源技能包、深入的技术内容和即将到来的会议演讲：
- 在 LinkedIn 上关注：linkedin.com/in/jamesor
- 在 X（Twitter）上关注：x.com/JamesOR
与我们分享您的想法
智能体编排最让您兴奋的地方是什么？
感谢您使用 Google Antigravity 进行构建！