ai-agent-migrate

AI 驱动的代码迁移 CLI 工具

支持 Vue2→Vue3、React Class→Hooks、JS→TS 等迁移场景

English Version

项目简介

ai-agent-migrate 是一个独立的 CLI 代码迁移工具，通过 AST + LLM 混合驱动实现智能代码迁移。

• AST 优先：60-70% 的工作量通过 AST 解析器处理（快速、免费、准确）
• LLM 兜底：30-40% 的工作量通过 LLM 处理语义复杂的转换
• 不依赖 Claude Code：独立发布到 npm，开箱即用
• MIT 许可：完全开源，可自由使用

支持的迁移场景

| 迁移类型 | 说明 | 状态 | |---------|------|------| | Vue 2 → Vue 3 | Options API → Composition API | 🚧 MVP 开发中 | | React Class → Hooks | 类组件 → Hooks 组件 | 🚧 计划中 | | JavaScript → TypeScript | JS 代码添加类型注解 | 🚧 计划中 | | CommonJS → ESM | require → import/export | 🚧 计划中 | | Angular → React | 框架迁移 | 📋 已规划 | | jQuery → Vue 3 | 框架迁移 | 📋 已规划 | | Python 2 → 3 | 版本升级 | 📋 已规划 |

核心特性

🎯 智能混合策略

• AST 解析器：使用 babel、jscodeshift、ts-morph 处理确定性转换
• LLM 驱动：处理需要语义理解的复杂转换
• 成本优化：AST 处理免费，LLM 按需调用

🔒 安全可靠

• 自动备份：迁移前自动创建 tar.gz 备份
• Dry Run 模式：预览变更，不修改文件
• Rollback 支持：一键回滚到迁移前状态
• 权限控制：配置文件权限设置为 600

🤖 多 LLM 提供商支持

| 提供商 | 价格 | 推荐度 | |--------|------|--------| | DeepSeek | ¥1/百万tokens | ⭐ 推荐 | | Kimi/Moonshot | ¥12/百万tokens | 🌟 国内 | | GLM/智谱 | ¥12/百万tokens | 🌟 国内 | | Claude | $3/百万tokens | 🌍 国际 | | OpenAI | $5/百万tokens | 🌍 国际 |

📋 完整的工作流

1. init - 初始化 LLM 配置
2. analyze - 分析项目，推荐迁移方案
3. plan - 生成迁移计划（不执行）
4. migrate - 执行迁移
5. upgrade - 升级依赖
6. report - 查看迁移报告
7. rollback - 回滚迁移

安装

# 全局安装
npm install -g ai-agent-migrate

# 或使用 pnpm
pnpm add -g ai-agent-migrate

# 或使用 yarn
yarn global add ai-agent-migrate

快速开始

1. 初始化配置

ai-agent-migrate init

交互式选择 LLM 提供商并输入 API Key。

2. 分析项目

ai-agent-migrate analyze ./your-project

工具会分析项目结构，推荐合适的迁移方案。

3. 生成迁移计划

ai-agent-migrate plan vue2 vue3 ./your-project

查看将要执行的迁移操作，但不实际修改文件。

4. 执行迁移

ai-agent-migrate migrate vue2 vue3 ./your-project

⚠️ 重要：执行前会自动创建备份，可以随时回滚！

5. 查看报告

ai-agent-migrate report

查看迁移统计、成本、问题等信息。

6. 回滚（如需要）

ai-agent-migrate rollback

一键恢复到迁移前的状态。

CLI 命令

# 查看帮助
ai-agent-migrate --help

# 查看版本
ai-agent-migrate --version

# 通用选项
ai-agent-migrate -d               # --dry-run: 模拟运行
ai-agent-migrate -y               # --yes: 跳过确认
ai-agent-migrate -v               # --verbose: 详细日志
ai-agent-migrate -f json          # --format: 输出格式

配置文件

配置文件位置：~/.ai-agent-migrate/config.json

{
  "llm": {
    "provider": "deepseek",
    "apiKey": "sk-xxxxx"
  },
  "budget": {
    "maxCost": 10.0,
    "currency": "CNY"
  },
  "maxConcurrency": 4,
  "maxFileSize": 1048576
}

环境变量

# 覆盖配置文件中的 API Key
export AI_MIGRATE_API_KEY=sk-xxxxx

# 覆盖配置文件中的 Provider
export AI_MIGRATE_PROVIDER=deepseek

开发

# 克隆仓库
git clone https://github.com/peterfei/ai-agent-migrate.git
cd ai-agent-migrate

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

# 链接到全局（开发模式）
npm link

# 取消链接
npm unlink -g ai-agent-migrate

🧪 测试指南

快速测试

使用内置的测试项目快速验证功能：

# 1. 构建项目
npm run build

# 2. 分析测试项目
ai-agent-migrate analyze tests/fixtures/vue2-simple-project

# 3. 生成迁移计划
ai-agent-migrate plan vue2 vue3 tests/fixtures/vue2-simple-project --output test-plan.json

# 4. Dry Run 模式（不修改文件）
ai-agent-migrate migrate vue2 vue3 tests/fixtures/vue2-simple-project --dry-run

# 5. 执行实际迁移
ai-agent-migrate migrate vue2 vue3 tests/fixtures/vue2-simple-project

# 6. 验证迁移结果
cat tests/fixtures/vue2-simple-project/src/App.vue

完整测试流程

# 一键完整测试
npm run build && \
ai-agent-migrate analyze tests/fixtures/vue2-simple-project && \
ai-agent-migrate migrate vue2 vue3 tests/fixtures/vue2-simple-project --dry-run && \
ai-agent-migrate migrate vue2 vue3 tests/fixtures/vue2-simple-project

创建自定义测试项目

# 创建测试目录
mkdir test-vue2-project
cd test-vue2-project

# 创建 package.json
cat > package.json << 'EOF'
{
  "name": "vue2-test",
  "version": "1.0.0",
  "dependencies": {
    "vue": "^2.6.14"
  }
}
EOF

# 创建 Vue 2 组件
mkdir src
cat > src/App.vue << 'EOF'
<template>
  <div>
    <h1>{{ message }}</h1>
    <button @click="increment">{{ count }}</button>
  </div>
</template>

<script>
export default {
  data() {
    return {
      message: 'Hello Vue 2',
      count: 0
    }
  },
  methods: {
    increment() {
      this.count++
    }
  }
}
</script>
EOF

# 执行迁移
ai-agent-migrate migrate vue2 vue3 .

# 查看迁移结果
cat src/App.vue

单元测试

# 运行所有测试
npm test

# 运行单元测试
npm run test:unit

# 运行集成测试
npm run test:integration

# 监视模式
npm run test:watch

# 覆盖率报告
npm run test:ci

验证迁移质量

# 检查迁移前后的变化
git diff tests/fixtures/vue2-simple-project/src/App.vue

# 验证备份文件
ls -lh tests/fixtures/vue2-simple-project/.ai-agent-migrate/backups/

# 查看迁移统计
ai-agent-migrate report

测试检查清单

Vue 2 → Vue 3 迁移验证：

• [ ] <script> 改为 <script setup>
• [ ] data() 改为 ref() / reactive()
• [ ] methods 改为普通函数
• [ ] this.xxx 改为 xxx.value
• [ ] 生命周期钩子更新

React Class → Hooks 迁移验证：

• [ ] Class 组件改为函数组件
• [ ] this.state 改为 useState()
• [ ] 生命周期改为 useEffect()

测试报告示例

迁移完成后会显示：

✅ 迁移完成！

📊 迁移统计:
   总文件数: 1
   完成文件: 1
   跳过文件: 0

⏱️  总耗时: 3 分钟
💰 总成本: ¥0.0056
📦 备份位置: tests/fixtures/.../backup-xxx.tar.gz

故障排除

# 如果命令未找到
npm link

# 如果构建失败
rm -rf node_modules dist && npm install && npm run build

# 如果迁移失败
ai-agent-migrate rollback  # 回滚更改

# 查看详细日志
ai-agent-migrate migrate vue2 vue3 . --verbose

项目架构

ai-agent-migrate/
├── src/
│   ├── commands/          # CLI 命令实现
│   ├── core/
│   │   ├── engine/        # 迁移引擎（AST + LLM）
│   │   ├── providers/     # LLM 提供商适配器
│   │   └── analyzer/      # 项目分析器
│   ├── migrations/        # 迁移处理器
│   └── utils/             # 工具函数
├── templates/
│   ├── migration-rules/   # AST 转换规则
│   └── prompts/           # LLM 提示词模板
└── tests/
    ├── unit/              # 单元测试
    └── fixtures/          # 测试项目

技术栈

• 语言: TypeScript 5.x
• CLI 框架: Commander.js
• AST 解析: @babel/parser, jscodeshift, ts-morph
• LLM SDK: @anthropic-ai/sdk, openai
• 验证: Zod
• 测试: Jest + ts-jest
• 引擎: Node.js >= 18

贡献指南

欢迎贡献！请查看 CONTRIBUTING.md 了解详情。

开源协议

MIT

Made with ❤️ by peterfei