migrate-hardhat2-to-hardhat3

此技能会分 六个连续阶段完成 V2→V3 迁移。默认由单个 Agent 从头到尾执行——这种方式适用于小型和中型项目（以及在 1M-token 上下文窗口下最多约有 150 个 .ts 测试文件的大型项目）。对于规模更大的项目，或在较小上下文窗口（约 200k tokens）下迁移非简单项目，请将文件较多的阶段（阶段 4 和 5）分派给子 Agent，避免单个上下文在迁移过程中溢出（参见 references/migration-conventions.md 中的“可选：分派给子 Agent”）。

开始之前

1. 阅读 references/migration-conventions.md——每个阶段都要遵循的规则（不得使用 VCS 命令、检测包管理器、确定范围、关卡、变更呈现方式和可选的并行执行模式）。阅读后再继续。
2. 检测包管理器（检查锁文件），并在整个迁移过程中使用同一个包管理器。
3. 选择执行模式。 估算上下文窗口大小和项目规模（统计 .ts 测试文件），并根据约定文档中的阈值，选择单个 Agent（默认）或分派给子 Agent。如果无法判断当前使用的是哪种上下文窗口，请按较小的窗口处理。大多数项目使用单个 Agent 即可。
4. 阶段必须严格按顺序执行——每个阶段都依赖前一阶段的输出。每个阶段完成后，都要停在用户确认点，等待批准后再继续。按以下顺序呈现确认点：
   • 已完成的步骤——刚完成阶段的标题（例如 阶段 1 — 项目设置）及其变更：列出已修改的文件，并逐字列出任何意外变更（参见约定文档中的核心规则 5）。
   • 建议的提交消息——已完成阶段对应的确认点提交消息。
   • 下一步——后续阶段的标题（例如 阶段 2 — 配置）及其将执行操作的一句话说明；阶段 6 完成后则写“迁移已完成”。

阶段

按照各阶段指南执行每个阶段。每个阶段都以一个关卡结束；移动到下一阶段前，请使用以下清单确认该阶段确实已完成。

阶段 1 — 项目设置 → 阶段指南

根据模板创建 .env，更新 tsconfig.json 以使用 ESM，并转换 package.json（ESM 标志、V2→V3 依赖项替换、脚本）。

• 阶段报告所有关卡均已通过
• npx hardhat --version 可运行，并输出 3.x 版本（例如 3.9.0）
• 确认点提交：[CHECK] HH3 project setup: env, tsconfig, package.json

阶段 2 — 配置 → 阶段指南

将 hardhat.config.ts 重写为 V3 声明式 defineConfig（插件、网络、自定义任务、solidity、verify、测试设置）。

• 阶段报告所有关卡均已通过
• 确认点提交：[CHECK] HH3 config: declarative defineConfig (solidity, networks, plugins, tasks, verify)

阶段 3 — Solidity 测试 → 阶段指南

将 .t.sol 测试文件迁移到 V3 约定。可能需要修改 config（例如设置 paths.tests.solidity 来调整 Solidity 测试文件的位置，或设置 paths.sources.solidity，以便将测试合约作为源文件编译）。

• npx hardhat test solidity 通过且无错误（或因没有 Solidity 测试而跳过）
• 确认点提交：[CHECK] HH3 solidity test migration

阶段 4 — 源文件 → 阶段指南

将所有 .ts（以及任何 CommonJS .js）源文件从 CJS 转为 ESM，并将 V2 API 调用更新为 V3（以及修复 TypeChain 导入）。

• 阶段报告所有关卡均已通过
• npx tsc --noEmit 通过且无错误
• npx hardhat test solidity 仍然通过（回归检查——源文件变更可能会导致 Solidity 测试失败）
• 确认点提交：[CHECK] HH3 source file migration: ESM conversion, V3 API updates, and TypeChain import fixes

阶段 5 — 修复测试 → 阶段指南

确保 .ts 测试套件在 V3 下全部通过。

• npx tsc --noEmit 仍以零错误通过
• 每个测试文件都单独通过（npx hardhat test {file}）
• npx hardhat test solidity 仍然通过（回归检查——测试辅助工具/配置修复可能会导致 Solidity 测试失败）
• 检查点提交：[CHECK] HH3 test suite fix-up: all tests passing under V3

阶段 6 — 验证脚本 → 阶段指南

交互式：用户选择要验证的 package.json 脚本；技能会逐个运行并修复。

• 报告阶段所有门槛均已通过
• npx tsc --noEmit 仍以零错误通过
• 检查点提交：[CHECK] HH3 script validation: all package.json scripts passing

完成

停止并告知用户迁移已完成。