qe-aqe-v2-v3-migration

AQE v2 到 v3 迁移技能

<default_to_action> 从 v2 迁移到 v3 时：

1. 分析当前的 v2 安装
2. 在进行任何更改前备份所有数据
3. 迁移配置、记忆和模式
4. 验证迁移是否成功
5. 提供回滚说明

未经用户明确确认，切勿删除 v2 数据。 </default_to_action>

快速参考

迁移命令

# When v3 becomes main release, just update the package
npm install agentic-qe@latest

# Run migration
aqe migrate

# Or use this skill
/aqe-v2-v3-migration

迁移内容

组件	v2 位置	v3 位置	自动迁移
记忆数据库	.agentic-qe/memory.db	.aqe/agentdb/	是
配置	.agentic-qe/config.json	.aqe/config.json	是
模式	.agentic-qe/patterns/	.aqe/reasoning-bank/	是
缓存	.agentic-qe/cache/	.aqe/cache/	可选
日志	.agentic-qe/logs/	.aqe/logs/	否（重新开始）

---

迁移检查清单

迁移前

• 确认 v2 安装存在（.agentic-qe/ 目录）
• 检查 v2 版本：aqe --version（应为 2.x.x）
• 备份当前数据：npm run backup（在 v2 项目中）
• 记录所有自定义配置
• 记录当前测试数量和覆盖率

迁移期间

• 更新到 v3：npm install agentic-qe@latest
• 运行迁移：aqe migrate
• 查看迁移报告
• 验证数据是否正确迁移

迁移后

• 运行 v3 测试：aqe test
• 检查覆盖率：aqe coverage
• 验证模式是否已加载：aqe patterns list
• 使用 Claude Code 测试 MCP 集成

---

架构变更（v2 → v3）

从单体架构转向 DDD

v2 Structure:                    v3 Structure:
├── src/mcp/tools/              ├── src/domains/
│   ├── test-*.ts (40+ tools)   │   ├── test-generation/
│   └── ...                     │   ├── test-execution/
├── src/core/agents/            │   ├── coverage-analysis/
│   ├── mixed agents            │   ├── quality-assessment/
│   └── ...                     │   ├── defect-intelligence/
└── src/core/memory/            │   ├── requirements-validation/
    └── scattered impls         │   ├── code-intelligence/
                                │   ├── security-compliance/
                                │   ├── contract-testing/
                                │   ├── visual-accessibility/
                                │   ├── chaos-resilience/
                                │   └── learning-optimization/
                                ├── src/kernel/
                                │   ├── event-bus.ts
                                │   └── coordinator.ts
                                └── src/mcp/
                                    └── domain-handlers.ts

主要 API 变更

v2 API	v3 API	说明
aqe init	aqe init	二进制文件不同
aqe.generateTests()	testGeneration.generate()	基于领域
aqe.analyzeGaps()	coverageAnalysis.findGaps()	现在为 O(log n)
memory.store()	agentDB.store()	使用 HNSW 索引
patterns.learn()	reasoningBank.record()	包含判定结果

---

配置迁移

v2 配置格式

{
  "version": "2.8.2",
  "memory": {
    "path": ".agentic-qe/memory.db",
    "type": "sqlite"
  },
  "agents": {
    "enabled": ["test-generator", "coverage-analyzer"]
  }
}

v3 配置格式

{
  "version": "3.0.0",
  "kernel": {
    "eventBus": "in-memory",
    "coordinator": "queen"
  },
  "domains": {
    "test-generation": { "enabled": true },
    "test-execution": { "enabled": true },
    "coverage-analysis": {
      "enabled": true,
      "algorithm": "hnsw",
      "dimensions": 128
    }
  },
  "memory": {
    "backend": "agentdb",
    "path": ".aqe/agentdb/",
    "hnsw": {
      "M": 16,
      "efConstruction": 200
    }
  },
  "learning": {
    "reasoningBank": true,
    "sona": true
  }
}

---

记忆迁移

从 SQLite 迁移到 AgentDB

// v2: Direct SQLite access
import Database from 'better-sqlite3';
const db = new Database('.agentic-qe/memory.db');
const patterns = db.prepare('SELECT * FROM patterns').all();

// v3: AgentDB with HNSW
import { AgentDB } from 'agentic-qe';
const db = new AgentDB('.aqe/agentdb/');
await db.initialize({ dimensions: 128, M: 16 });

// Migration script transfers and indexes
for (const pattern of v2Patterns) {
  await db.store({
    key: pattern.id,
    value: pattern.data,
    embedding: await generateEmbedding(pattern.data),
    metadata: { migratedFrom: 'v2', originalId: pattern.id }
  });
}

---

重大变更

必须更新

1. 导入路径

   // v2
   import { AgenticQE } from 'agentic-qe';
   
   // v3 (when v3 becomes main release, package name is still 'agentic-qe')
   import { TestGenerationDomain } from 'agentic-qe/domains';
   

2. CLI 命令

   # v2
   aqe test --parallel
   
   # v3
   aqe test --workers=4 --topology=mesh
   

3. MCP 服务

   # v2
   claude mcp add aqe -- npx aqe-mcp
   
   # v3 (same CLI name, enhanced capabilities)
   claude mcp add aqe -- npx aqe mcp
   

已弃用（将显示警告）

• aqe.runTests() → 使用特定领域的方法
• 直接访问记忆 → 使用 AgentDB API
• 平铺的 Agent 列表 → 使用领域协调器

---

回滚说明

如果迁移失败或需要还原：

# 1. v3 does NOT modify v2 data
# Your .agentic-qe/ folder is untouched

# 2. Downgrade to v2
npm install [email protected]
rm -rf .aqe/

# 3. Continue using v2
aqe --version  # Should show 2.x.x

---

Agent 协调示例

启动迁移 Agent

// Use Task tool to spawn migration agents in parallel
Task({
  prompt: "Analyze v2 memory.db and extract all patterns",
  subagent_type: "researcher",
  description: "Analyze v2 patterns"
});

Task({
  prompt: "Convert v2 config to v3 format",
  subagent_type: "coder",
  description: "Convert config"
});

Task({
  prompt: "Validate migration results",
  subagent_type: "tester",
  description: "Validate migration"
});

---

故障排除

常见问题

问题	原因	解决方案
"Cannot find .agentic-qe/"	未安装 v2	先运行 aqe init
"Memory migration failed"	SQLite 已损坏	使用备份：npm run backup:restore
"HNSW index error"	维度不匹配	在配置中设置 dimensions: 128
"Pattern not found"	未迁移	重新运行：aqe migrate --patterns

调试模式

# Run migration with debug output
DEBUG=aqe:migrate aqe migrate

# Check migration logs
cat .aqe/logs/migration.log

---

支持

• 迁移问题：提交 issue，并添加 [v2-v3-migration] 标签
• 文档：迁移指南
• Discord：#v3-migration 频道

---

版本兼容性矩阵

v2 版本	v3 版本	迁移支持
2.8.x	3.0.x	完全支持
2.7.x	3.0.x	完全支持
2.6.x	3.0.x	部分支持（仅配置）
2.5.x 及以下	3.0.x	手动迁移

---

技能版本：1.0.0 | 最后更新：2026-01-11