SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场migrate-hardhat2-to-hardhat3

migrate-hardhat2-to-hardhat3

编程与开发

查看项目

更新于 10-16 10:05

技能介绍

用途

该技能用于把 Hardhat V2 项目系统化迁移到 Hardhat V3。它覆盖核心变更（ESM、声明式配置、hooks 系统、网络连接）以及完整的迁移流程，将整个迁移拆分为六个顺序执行的阶段。

主要能力

迁移以六个严格顺序执行的阶段进行，每个阶段依赖前一个阶段的输出，且每个阶段结束后需在用户检查点等待批准后方可继续。检查点包含三部分：已完成的阶段标题与变更文件列表（异常文件需原样呈现）、建议的提交信息、以及下一阶段的标题与一行说明（Phase 6 后为“迁移完成”）。

六个阶段及各自的验证门槛如下：

  • Phase 1 — Project Setup：从模板创建 .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。
  • Phase 2 — Config：将 hardhat.config.ts 重写为 V3 声明式 defineConfig（plugins、networks、自定义 tasks、solidity、verify、test 设置）。门槛：阶段报告所有门槛通过。检查点提交信息：[CHECK] HH3 config: declarative defineConfig (solidity, networks, plugins, tasks, verify)。
  • Phase 3 — Solidity Tests：将 .t.sol 测试文件迁移到 V3 约定。可能需要配置变更（例如用 paths.tests.solidity 重新定位 Solidity 测试文件，或在测试合约必须作为 sources 编译时使用 paths.sources.solidity）。门槛：npx hardhat test solidity 零错误通过（或跳过——无 Solidity 测试）。检查点提交信息：[CHECK] HH3 solidity test migration。
  • Phase 4 — Source Files：将所有 .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。
  • Phase 5 — Test Fix-Up：使 .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。
  • Phase 6 — Script Validation：交互式，用户挑选 package.json 脚本来验证；技能逐个运行并修复。门槛：阶段报告所有门槛通过；npx tsc --noEmit 仍零错误通过。检查点提交信息：[CHECK] HH3 script validation: all package.json scripts passing。

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

使用方式

开始前必须执行以下步骤：

  1. 阅读 references/migration-conventions.md——每个阶段都依赖的规则（禁止 VCS 命令、包管理器检测、作用域、门槛、变更呈现以及可选的并行执行模型）。未阅读前不要继续。
  2. 检测包管理器（检查 lockfile），并在整个迁移过程中记住它。
  3. 选择执行模式。估算上下文窗口和项目规模（统计 .ts 测试文件数），依据约定文档中的阈值选择单 agent（默认）还是子 agent 分派。如果无法判断处于哪个窗口，按较小的那个假设。大多数项目保持单 agent。

执行时，按各阶段指南逐个运行阶段。每个阶段以门槛结束，用对应清单确认该阶段真正完成后再继续。

适用场景

适合需要把 Hardhat V2 项目升级到 Hardhat V3 的开发者。默认单 agent 模式处理中小型项目，在 1M token 上下文窗口中可覆盖约 150 个 .ts 测试文件的大型项目；超出该规模，或在较小上下文环境（约 200k token）下超过简单项目时，可将文件密集的阶段（4 和 5）分派给子 agent，以避免单个上下文在迁移中途溢出（参见 references/migration-conventions.md 中的 “Optional: sub-agent fan-out”）。

限制

资料未提供官方文档正文、具体命令以外的安装方式、收费或价格、平台支持范围、迁移耗时或成功率的量化数据。迁移涉及硬性前提（阅读约定文档、检测包管理器、选择执行模式），且每阶段必须等待用户批准。部分细节（如具体 API 变更清单、TypeChain 修复的完整范围）需参考各阶段指南与约定文档，资料中未展开。