banma-migrator - 项目详情

迁移流水线

点击放大

核心中间产物：page-logic.json

贯穿全流程的唯一数据契约

page-logic.json 是整个流水线的枢纽，由 Extract Logic Agent 生成，被后续所有 Agent 消费。它将 Vue2 的运行时语义转换为与框架无关的结构化描述，彻底解耦「解析阶段」与「生成阶段」，支持断点续跑与局部重试。

page-logic.json — 结构示意

{
  "meta": {
    "sourcePath": "src/views/OrderList.vue",
    "componentName": "OrderList"
  },
  "state": [
    { "name": "list",       "type": "Order[]",  "initial": "[]" },
    { "name": "loading",    "type": "boolean",  "initial": "false" },
    { "name": "pagination", "type": "Pagination","initial": "{}" }
  ],
  "apis": [
    {
      "name": "fetchOrderList",
      "method": "GET",
      "url": "/api/order/list",
      "params": ["pageNo", "pageSize", "status"],
      "onSuccess": "list = data.list; pagination = data.page",
      "onError":   "message.error(msg)"
    }
  ],
  "lifecycle": {
    "mounted": ["fetchOrderList"]
  },
  "events": [
    {
      "name": "handlePageChange",
      "params": ["page"],
      "body": "pagination.current = page; fetchOrderList()"
    }
  ],
  "computed": [
    { "name": "isEmpty", "deps": ["list"], "expr": "list.length === 0" }
  ]
}

meta 源文件路径与组件名，用于生成 FSD 目录结构

state 所有响应式状态，直接映射为 store 的 state 定义

apis 接口调用描述，包含参数、成功/失败处理逻辑，映射为 api 层函数

lifecycle 生命周期钩子映射，mounted → useEffect，destroyed → cleanup

events 事件处理函数，映射为 store action 或组件内 handler

computed 计算属性，映射为 useMemo / selector

输出结构：Feature-Sliced Design

graph LR subgraph "Vue2 输入结构（单文件耦合）" V["OrderList.vue
─────────────
template（UI）
script（逻辑+状态+API）
style（样式）"] end subgraph "React 输出结构（FSD 分层）" direction TB UI["ui/
OrderList.tsx
OrderListItem.tsx
（纯渲染，无业务逻辑）"] MODEL["model/
store.ts
（Zustand store）
selectors.ts"] API["api/
orderApi.ts
（接口封装）
types.ts"] UI -->|"调用"| MODEL MODEL -->|"调用"| API end V -->|"banma-migrator"| UI V -->|"banma-migrator"| MODEL V -->|"banma-migrator"| API style V fill:#fee2e2,stroke:#ef4444 style UI fill:#ede9fe,stroke:#8b5cf6 style MODEL fill:#fef3c7,stroke:#f59e0b style API fill:#d1fae5,stroke:#10b981

ui/ — 纯渲染层

React 组件只负责 JSX 渲染，通过 props 接收数据，通过 callback 触发事件，不直接调用 API，不持有业务状态。

model/ — 状态层

Zustand store 持有页面状态，action 封装业务逻辑，selector 封装派生数据。UI 层通过 hook 订阅，与渲染解耦。

api/ — 接口层

所有 HTTP 请求集中在 api 层，包含请求参数类型、响应类型、错误处理。model 层通过 import 调用，不直接 fetch。

三层验证闭环

flowchart LR subgraph "第一层：Logic 校验" L1["page-logic.json
JSON Schema 验证"] L2["字段完整性
类型合法性
依赖关系检查"] L1 --> L2 end subgraph "第二层：链路测试" T1["Mock API 环境
运行生成的测试"] T2["接口调用路径
参数格式
状态流转"] T1 --> T2 end subgraph "第三层：行为等价测试" E1["旧页面（Vue2）
作为 Oracle"] E2["新页面（React）
相同操作序列"] E3["API 参数对比
响应处理对比
评分 ≥ 0.9 通过"] E1 -->|"对比"| E2 --> E3 end L2 -->|"通过"| T1 T2 -->|"通过"| E1 E3 -->|"不通过"| FIX["回退 Gen UI
重新生成"] style L1 fill:#fef3c7,stroke:#f59e0b style T1 fill:#ede9fe,stroke:#8b5cf6 style E1 fill:#fee2e2,stroke:#ef4444 style E2 fill:#d1fae5,stroke:#10b981 style FIX fill:#f1f5f9,stroke:#94a3b8

11 Agent 分工与上下文隔离

01–03

解析组

Parse / Extract / Validate — 只读源文件，输出 page-logic.json，不接触目标框架代码

04–06

生成组（逻辑层）

Types / Store / API — 以 page-logic.json 为唯一输入，生成框架无关的逻辑层代码

07

UI 生成

Gen UI — 以 template AST + page-logic.json 双输入，生成 React 组件，只引用逻辑层 hook

08–09

验证组

Tests / Review — 生成测试、执行验证、综合评分，决定是否触发回退重试

10

修复组

Fix Lint — 独立处理 ESLint / TypeScript 编译错误，不修改业务逻辑

11

等价测试

Equivalence — 驱动旧/新页面执行相同操作序列，捕获 API 调用差异并评分

每个 Agent 拥有独立的 CLAUDE.md 上下文文件，只加载当前步骤所需的信息，避免长上下文导致的注意力漂移。Agent 间通过文件系统（page-logic.json、生成产物）传递数据，不共享内存状态。