使用智能体流水线和 Antigravity 大规模自动化实现旧版系统现代化改造

1. 了解您的现代化改造之旅

大规模自动化旧版系统现代化改造 这个全面的 Codelab 是直接从架构深入分析文章（如何使用 Antigravity 和多智能体编排实现现代化改造自动化）中衍生出的实践配套实验。虽然我们使用经典的 Node.js 框架交换作为具体演示工具，但您将在此处掌握的核心设计模式、目录结构和智能体编排流程完全与语言无关，并且普遍适用于任何大规模的旧版现代化改造项目。

与仅在单个文件中自动补全行的标准编码助理不同，您将学习如何利用 Google Antigravity 的智能体优先功能来编排由专业 AI 子智能体组成的自主团队。这些智能体可以独立对旧版代码库进行逆向工程、编写严谨的测试套件、自动搭建现代架构，并使用 Reflexion 循环自行纠正编译器错误，而您作为高级架构师，可以保持绝对控制权。

学习内容

  • 工作流映射：如何正确分类和分离确定性设置任务与复杂的启发式重构挑战。
  • 技能架构：如何使用渐进式披露和 YAML 路由元数据构建可扩展的智能体技能包。
  • 编排设计模式：如何通过链接路由器、计划和执行以及 Reflexion 设计模式来推动大规模重构。
  • 严格的输入/输出合同：如何在多阶段逆向工程和目标自动搭建流水线中强制执行清晰的输入/技能/输出边界。
  • 对等验证：如何在 Chrome 网络浏览器中利用 Antigravity 的浏览器子智能体执行并排对等测试。

构建内容

您将编排一个完全自动化的 Greenfield 重构流水线，该流水线采用标志性的过时旧版 Express 和 Mongoose CRUD 单体式应用（“madhums 演示”），并将其从头开始自主重建为严格类型的 Next.js 应用路由器应用，该应用由 MongoDB、严格的 Zod 验证和无障碍 ShadCN 界面组件提供支持。

所需条件

  • 在本地安装 Google Antigravity IDE （可在 antigravity.google 上获取）。
    • 在本地安装 Node.js (v18+) 。
  • 用于自动界面验证的 Chrome 浏览器 。
  • 克隆开源的 modernizing-expressjs 演示单体式代码库。

2. 设置现代化改造环境

在让自主智能体处理老旧的旧版代码库之前，我们必须建立一个干净、高度稳定的单体式代码库环境。为 AI 助理提供干净的基准，可确保其完全专注于生成高质量的现代代码，而不是浪费令牌来解决十年前的软件包漏洞或编译器不匹配问题。

旧版 Express 与现代 Next.js 架构映射

组件

旧套装

现代替换

基本原理

架构

Express 单体式应用

Next.js 应用路由器

将逻辑分离到服务器组件中，以优化渲染和 React 服务器组件 (RSC) 性能。

数据逻辑

Mongoose (ODM)

MongoDB + Zod

将隐式 ORM 钩子替换为显式、类型安全的 Zod 架构和原始驱动程序性能。

语言

CommonJS / JavaScript

TypeScript (ESM)

强制执行编译时安全性并迁移到现代模块标准。

前端

Pug/EJS（服务器视图）

ShadCN 界面 + Tailwind

从僵化的模板转向可组合、无障碍且实用性优先的设计系统。

Auth

Passport.js

NextAuth

通过内置支持 Edge 和现代提供商来实现会话管理现代化。

安全

手动中间件

Zod（严格验证）

在整个堆栈中实现数据验证的“单一可信来源”。

初始化现代化改造中心

我们的第一个确定性操作是克隆隔离的单体式代码库结构。这会将只读的旧版代码与我们的新 Greenfield 目标代码库分开，确保不会意外更改原始应用。

打开 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

观看此简短的视频演示，了解如何以确定性的方式准备和隔离单体式代码库环境：

3. 设计 AI 智能体技能包和模式

编写强大的智能体技能与编写标准聊天提示从根本上不同。编写技能包时，您是在设计一个模块化软件，底层 LLM 将自主执行该软件。为防止智能体产生幻觉或遇到“上下文窗口税”，我们引入了开源 Greenfield 编排技能包，作为由两个不可协商的原则（简洁性和渐进式披露）驱动的可扩展编写模板。

使用 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 智能体管理器聊天面板中，输入以下自定义斜杠命令，然后按 Enter 键：

/orchestrating-greenfield-migration

现在，观察您的终端控制台。您将看到主智能体读取其系统提示，将您的请求与编排器的元数据匹配，输出 5 阶段核对清单，并立即开始并行调度专业的“审核员”子智能体。

输入/技能/输出指令合同

在第 1 阶段，智能体执行受以下指令合同约束的严格逆向工程流水线：

使用的输入：位于 legacy-app/ 内的只读旧版源代码文件。

调用的技能：

技能

说明

auditing-api-contracts

跟踪旧版路由以记录确切的 JSON 响应信封。

auditing-data-models

解构 Mongoose 架构以提取关系、必填字段和默认值。

auditing-business-logic

记录隐式副作用、Passport 身份验证流程和中间件规则。

auditing-ui-archeology

扫描旧版 Pug 模板以映射高级“界面意图”（导航栏、表单）。

生成的工件：直接生成到 docs/ 文件夹中的高度结构化 Markdown 规范

工件

说明

docs/API_Contracts.md

本文档详细介绍了旧版 Express 应用的逆向工程 API 表面积。在现代化改造的 Next.js 应用中重建路由时，请使用此目录来确保严格的对等性。

docs/Business_Logic_Rules.md

本文档记录了旧版 Express 应用在身份验证 (AuthN)、授权 (AuthZ)、全局中间件、会话管理和副作用方面的已验证行为、配置和严格规则。

docs/Data_Models.md

本文档全面分析了 legacy-app/app/models/ 中的旧版 Mongoose 架构，并提供了使用原生 MongoDB 和 Zod 的类型安全现代数据访问层的蓝图。

docs/UI_Inventory.md

本文档详细分析了 legacy-app 中的旧版基于 Pug 的用户界面，并概述了 modern-app 中现代的组件驱动型 Next.js 前端架构的蓝图。

观看此实时终端捕获，了解自主逆向工程审核的实际操作：

5. 第 2 阶段和第 3 阶段 - TDD 测试工具和绿地后端基架

在对旧版应用进行全面审核和记录后，主编排器将继续自动搭建现代目标后端。此阶段引入了我们工具包中最强大的智能体设计模式：由严格的测试驱动开发 (TDD) 驱动的闭环 Reflexion （自我反思）。

使用 Reflexion 循环驱动自我修复代码

编写现代代码很简单；确保其完美编译并符合严格的验证约束需要闭环评估。编排器通过将测试输出直接传回子智能体的上下文窗口来自主处理此问题：

  1. 第 2 阶段（TDD 设置）：编排器调用 generating-api-tests 子智能体，该子智能体读取 docs/API_Contracts.md 并编写详尽的 Vitest 集成测试套件，断言确切所需的 HTTP 状态代码和 JSON 有效负载。正如 TDD 中所预期的那样，这些测试最初会失败。
  2. 第 3 阶段（后端自动搭建）：自动搭建子智能体开始编写现代 Next.js 路由处理程序和严格的 Zod 验证架构。
  3. 自我纠正循环：当确定性的 Vitest 测试工具评估新代码并返回失败（例如，预期返回 422 验证错误，但返回了 500）时，智能体不会崩溃。它会反思客观的错误输出，重新打开目标路由处理程序，修复 Zod 架构有效负载结构，然后再次运行测试。它会自主迭代，直到获得退出代码 0。

输入/技能/输出指令合同

使用的输入：逆向工程规范工件 (docs/API_Contracts.md、docs/Data_Models.md)。

调用的技能：

技能

说明

generating-api-tests

生成失败的 Vitest 集成套件。

scaffolding-nextjs-foundation

初始化基本 Next.js 应用路由器布局。

scaffolding-test-foundation

配置本地 Vitest 测试运行程序环境。

scaffolding-data-layer

将旧的 Mongoose 模型转换为 MongoDB + Zod 架构。

scaffolding-api-routes

将 Express 路由重建为 Next.js 路由处理程序和模块化路由防护。

生成的输出：初始失败的 Vitest 测试套件、完全类型的 Zod 架构、功能正常的 Next.js 路由处理程序，以及干净的通过测试的测试套件执行。

观察 TDD 测试工具的自动生成：

观察自我纠正 Reflexion 循环自动搭建目标后端的实时执行情况：

6. 第 4 阶段 - 自动搭建现代前端（界面组件）

在后端验证层完全强化并通过集成测试后，主编排器会将上下文切换为现代化改造视觉呈现。命令式服务器渲染模板将被弃用，取而代之的是高度无障碍、实用性优先的组件设计系统。

将界面意图转换为可组合的视图

前端子智能体不会尝试逐行翻译 CSS，而是读取提取的“界面意图”清单，并将结构元素直接映射到高保真现代等效项。

输入/技能/输出指令合同

使用的输入：逆向工程前端清单工件 (docs/UI_Inventory.md)。

调用的技能：

技能

说明

scaffolding-ui-components

将 UI_Component_Inventory.md 工件转换为现代 ShadCN + Tailwind 组件和完全自动搭建的 Next.js 页面。

生成的输出：使用高度无障碍的 ShadCN 界面组件和 Tailwind CSS 实用程序布局构建的可用于生产用途 Next.js 前端页面。

观看现代化改造的前端视图层的自主生成：

7. 第 5 阶段 - 验证和对抗性审核

我们的重构流水线以严格的质量检查结束。主编排器从静态代码分析过渡到主动运行时环境测试，主动尝试破坏新的目标应用，以证明与旧版基准的绝对功能对等性。

执行双标签页测试和浏览器启动

验证阶段利用 Antigravity 的集成视觉和 DOM 功能来自主证明成功，而无需您手动点击表单：

  1. 并排对等：auditing-parity 子智能体指示本地运行程序同时启动旧版 Express 单体式应用和现代化改造的 Next.js 应用，验证相同的视觉呈现和数据渲染。
  2. 对抗性安全探测：编排器调用 adversarial-verification 子智能体，该子智能体启动 Antigravity 浏览器子智能体。此专业智能体直接启动浏览器，输入内容、提交表单，并探测安全回归、损坏的会话 Cookie 或未处理的边缘情况。
  3. 生成审核跟踪记录：浏览器子智能体会自动记录其会话启动的 WebP 视频捕获，并将其直接附加到最终迁移报告中，作为可验证的 "工作证明"。

输入/技能/输出指令合同

使用的输入：在本地运行时环境中并排运行的旧版应用和现代应用。

调用的技能：

技能

说明

auditing-parity

执行运行时并排验证检查。

adversarial-verification

使用自动浏览器启动探测逻辑缺陷和功能回归。

生成的输出：全面的功能对等性审核跟踪记录，以及确认完全成功的录制浏览器会话视频。

观察自动浏览器子智能体主动验证现代化改造的应用：

8. 迁移后生产就绪情况和后续步骤

恭喜！您已成功编排高度先进的自主智能体重构流水线，从头开始现代化改造旧版单体式应用，学习了普遍适用的、高度可转移的技能，例如渐进式披露、计划和执行核对清单，以及自我修复 Reflexion 循环。

准备部署到生产环境

在 Next.js 应用经过全面验证和审核后，您就可以继续进行生产集成。考虑实施以下行业标准后续步骤：

  • 增量路由：部署反向代理（例如 Strangler Fig 模式），以将流量从旧版 Express 应用增量路由到现代目标。
  • SEO 保留：将旧版 Express 路由映射到 Next.js 永久重定向 (_redirects.yaml)，以保留现有域名权威性。
  • 数据流式传输：从静态数据库种子迁移到使用严格的 Zod 架构在运行时安全验证的实时生产数据流式传输。
  • 可观测性：将命令式日志记录实用程序替换为结构化 OpenTelemetry 框架。

深入了解现代化改造专业知识

如需探索驱动此流水线的完整底层代码库、自定义技能指令和详尽的理论原理，请务必阅读完整的父文章：

加入智能体构建者社区

希望这些普遍适用的重构模式和智能体流水线对您有所帮助。如需及时了解未来的开源技能包、深入的技术内容和即将举行的会议演讲活动，请通过以下专业渠道关注我：

与我们分享您的想法

智能体编排的哪些方面最让您兴奋？

对抗性浏览器验证 自主重构循环 可扩展技能架构 多智能体编排 通用语言无关性

感谢您使用 Google Antigravity 构建应用！