modernize-move

技能：modernize-move

检测并将过时的 Move V1 语法、模式和 API 更新为 Move V2+。通过分层转换并在每层后进行测试验证，确保正确性。

核心原则

每次现代化都必须遵守以下五条规则：

1. 必须具备测试安全网 原因：现代化必须保持行为不变。没有测试就没有安全网。如果不存在测试，请先调用 generate-tests 技能，在进行任何更改之前创建全面的测试。

2. 先分析，再修改 原因：用户必须准确了解将要更改的内容并确认范围。切勿擅自修改代码。提交完整的分析报告并等待确认。

3. 按层级顺序执行 原因：语法更改（第 1 层）风险为零。API 迁移（第 3 层）会改变语义。始终先应用最安全的更改，让风险较高的更改建立在干净且经过验证的基础上。

4. 每层后都进行验证 原因：如果测试失败，你就能准确知道是哪个层级导致的。回退该层并在继续之前进行调查。切勿在基线已损坏时应用下一层。

5. 保留错误代码值 原因：测试会使用 #[expected_failure(abort_code = N)]。更改数值会导致测试静默失败。创建命名常量时，其数值 MUST 与原始字面值相同。

何时使用此技能

• 将 Move V1 合约升级为 V2 语法
• 将 public(friend) 迁移为 package fun
• 将 vector::borrow 转换为索引表示法
• 将带计数器的 while 循环转换为 for 范围循环
• 使用标准库内联函数（vector::for_each_ref、vector::map、vector::fold 等）和 lambda 替换手动向量迭代
• 用命名常量替换魔法 abort 数字
• 将旧版 coin/TokenV1 迁移到现代 fungible_asset/Digital Assets
• 将 EventHandle 转换为 #[event] 模式
• 将自定义有符号整数变通方案升级为原生 i8-i256 类型

何时不使用此技能

• 从头编写新合约 — 使用 write-contracts
• 修复 bug 或添加功能 — 现代化是结构层面的，而非功能层面的
• 优化 gas 用量 — 使用 analyze-gas-optimization
• 安全审计 — 使用 security-audit（在现代化之后运行）

工作流

阶段 1：分析合约

入口： 用户提供要现代化的 Move 合约或项目。

操作：

1. 读取所有合约源文件（sources/ 中的 .move 文件）
2. 根据 detection-rules.md 中的检测规则扫描 V1 模式：
   • 搜索第 1 层模式（语法）——置信度最高、最常见
   • 搜索第 2 层模式（可见性、错误、事件）
   • 搜索第 3 层模式（API 迁移）——标记以供人工审查
3. 交叉检查相互关联的模式（T3-09+T3-10）
4. 对每项发现进行分类：行号、规则 ID、模式名称、建议更改、层级、置信度
5. 编制分析报告

出口： 分析报告已准备好供展示。

阶段 2：展示分析（GATE 1）

入口： 分析报告已完成。

操作：

1. 按以下格式向用户展示完整的分析报告：

## Modernization Analysis Report

### Summary
- Tier 1 (Syntax): X findings
- Tier 2 (Visibility & Errors): X findings
- Tier 3 (API Migrations): X findings

### Findings

| # | File:Line | Rule | Pattern | Proposed Change | Tier | Confidence |
|---|-----------|------|---------|-----------------|------|------------|
| 1 | src/mod.move:15 | T1-01 | vector::borrow | → index notation | 1 | High |
| ... | ... | ... | ... | ... | ... | ... |

### Tier 3 Warnings (if any)
- T3-03: coin → fungible_asset migration is a major rewrite (X locations)

2. 请用户选择范围：
   • syntax-only（仅第 1 层）——零风险，只让语法更简洁
   • standard（第 1 层 + 第 2 层）——推荐的默认选项，包含语法、可见性和错误常量
   • full（所有层级）——包含 API 迁移，风险较高
3. 指出任何需要重大重写的第 3 层项目
4. 如果范围包含第 3 层，请询问用户的部署背景：
   • Compatible — 升级已部署的合约。即使范围包含破坏性更改，也会排除这些更改。标记为 ⚠ Breaking 的规则将跳过。
   • Fresh deploy — 新部署或愿意重新部署。所选范围内的所有更改都会应用，包括破坏性更改。

出口： 用户已确认范围（如果包含第 3 层，也已确认部署背景）。确认之前不得继续。

第 3 阶段：建立测试安全网

入口条件： 用户已确认范围。

操作：

1. 搜索现有测试：
   • 源文件中的 #[test_only] 模块
   • *_tests.move 文件
   • tests/ 目录
2. 如果未找到测试：停止并调用 generate-tests 技能，先创建全面的测试，然后返回此处
3. 运行 aptos move test，建立通过的基线
4. 记录基线：测试数量，以及是否全部通过

退出条件： 所有测试均通过。已记录基线。如果现代化之前测试就失败，先停止并处理测试失败——不要在测试套件存在问题时进行现代化。

第 4 阶段：应用转换（带反馈循环）

入口条件： 已建立测试基线。

操作——按层级顺序应用：

第 1 层（如果在范围内——始终应用）：

1. 根据 transformation-guide.md 应用所有第 1 层语法更改
2. 运行 aptos move test
3. 如果测试失败 → 撤销所有第 1 层更改，调查具体是哪项更改导致失败，修复后重试

第 2 层（如果范围为 standard 或 full）： 4. 根据转换指南应用所有第 2 层更改 5. 运行 aptos move test 6. 如果测试失败 → 撤销所有第 2 层更改，调查并修复

第 3 层（仅当范围为 full 时）： 7. 一次应用一项第 3 层更改（不要一次性全部应用）

• 如果部署上下文为 compatible：跳过任何标记为 ⚠ Breaking 的规则。将其加入跳过列表，并注明原因 “存在破坏性更改，compatible 模式下不予应用。”
• 如果部署上下文为 fresh deploy：正常应用范围内的所有规则。

8. 每应用一项第 3 层更改后，都运行 aptos move test
9. 如果测试失败 → 撤销该项更改，将其记为已跳过，然后继续处理下一项第 3 层内容

退出条件： 已应用所有批准的更改，且所有测试均通过。

第 5 阶段：最终验证

入口条件： 已应用所有转换。

操作：

1. 运行 aptos move test --coverage
2. 验证测试覆盖率 >= 基线（应保持不变或有所提升）
3. 生成现代化摘要报告：

## Modernization Summary

### Changes Applied
- Tier 1: X changes (syntax)
- Tier 2: X changes (visibility & errors)
- Tier 3: X changes (API migrations)

### Changes Skipped
- [List any skipped items with reasons]

### Test Results
- Tests: X passing (baseline: Y)
- Coverage: X% (baseline: Y%)

### Files Modified
- [List of modified files]

退出条件： 已向用户呈现报告。

现代化范围速查表

范围	层级	风险	使用场景
syntax-only	第 1 层	零	仅清理语法，不进行语义更改
standard	第 1+2 层	低	默认。 语法 + 可见性 + 错误常量
full	第 1+2+3 层	中-高	全面迁移，包括 API 更改

分层速查

层级	变化内容	风险	示例
1 — 语法	代码写法不同，编译结果相同	零	vector::borrow(&v, i) → v[i]，x = x + 1 → x += 1，while (i < n) { ... i += 1 } → for (i in 0..n) { ... }
2 — 可见性与错误	语义相同，声明更简洁	低	public(friend) → package fun，魔法数字 → E_* 常量
3 — API 迁移	API 不同，预期行为相同。大多数属于破坏性变更。	中-高	coin → fungible_asset，SmartTable → BigOrderedMap，EventHandle → #[event]，手动循环 → 使用 lambda 的标准库 v.for_each_ref()/v.map()/v.fold()

完整规则目录（3 个层级共 22 条规则）请参阅 detection-rules.md。

应拒绝的合理化说法

合理化说法	错误原因
“测试通过了，所以现代化改造是正确的”	测试验证的是行为，而非代码质量。也要手动审查变更。
“这个合约很简单，跳过分析吧”	简单合约也可能存在微妙的模式。务必先分析。
“一次完成所有层级，节省时间”	如果测试失败，你就无法确定是哪项变更导致的。务必分层进行。
“接收者风格的调用看起来没问题”	必须确认目标函数声明了 self。误报很常见。
“错误常量可以使用新的名称和值”	现有测试依赖精确的数值。请保留原值。
“没有测试，但这些变更是安全的”	没有测试就没有安全网。先生成测试。
“第 3 层变更是可选的，可以跳过测试”	每项变更都需要验证。第 3 层风险最高——应该增加测试，而不是减少。

成功标准

• 在进行任何修改之前，先提交分析报告
• 用户确认现代化改造范围
• 变更前建立测试基线
• 每个层级的变更完成后，测试均通过
• 保留所有错误代码的数值
• 未经用户确认 full 范围，不应用第 3 层变更
• 用户选择兼容模式时，不包含破坏性变更
• 生成现代化改造摘要报告
• 测试覆盖率维持在基线水平或更高

参考索引

文件	内容
detection-rules.md	完整的 V1 模式检测目录（3 个层级共 22 条规则）
transformation-guide.md	每条规则的转换前后代码、安全检查和边缘情况
MOVE_V2_SYNTAX.md	完整的 V2 语法参考
OBJECTS.md	现代对象模型模式
ADVANCED_TYPES.md	枚举、有符号整数、幻影类型

相关技能： generate-tests、write-contracts、security-audit