megatron-impact-mapper

Megatron 影响映射器

确定正确的 MindSpeed 分支上下文，并将每个相关的 Megatron 事件映射到具体的 MindSpeed 实现目标。此技能是生成面向实现的迁移内容的把关环节。

严格门槛

明确分支对齐关系之前，不要生成迁移补丁。

使用以下任一对齐依据：

1. 用户提供的映射
2. branch-alignment.md 中的已知规则
3. 明确说明映射关系的仓库本地文档或提交

如果以上依据均不可用，请仅提供影响报告。

核心规则

• 严格迁移模式必须将 MindSpeed branch <-> Megatron branch 对齐视为必要条件。
• 首轮分析仅使用官方仓库作为事实来源。
• 区分 strict migration mode 和 exploration mode。
• 对于 megatron main，优先使用探索模式，除非用户明确选择了兼容的 MindSpeed 基线进行比较。
• 将结果分为三类： 已适配， 可能适配但尚未实现， 目前不值得适配。
• 如果某项功能显然值得迁移，不要止步于“候选路径”。应将该功能拆分为与上游实现单元相对应的实现目标。

工作流

1. 确定 MindSpeed 分支。
2. 确定映射的 Megatron 基线分支。
3. 将基线与目标 Megatron 分支或变更集进行比较。
4. 针对每个相关的 Megatron 事件，搜索对应的 MindSpeed 模块、封装器、配置、启动路径和测试。
5. 将上游实现单元映射到本地实现目标。
6. 生成影响报告，说明置信度、理由和实现范围。
7. 仅允许高置信度的影响项进入迁移生成阶段。

必需输出

生成 impact_report，其中包含：

{
  "mindspeed_branch": "master",
  "megatron_base_branch": "core_v0.12.1",
  "megatron_target_branch": "core_v0.15.3",
  "mode": "strict",
  "items": [
    {
      "event_title": "Add feature X",
      "status": "likely_missing",
      "confidence": 0.78,
      "candidate_paths": ["mindspeed/path_a.py", "mindspeed/path_b.py"],
      "reason": "Short factual rationale",
      "primary_commit": "sha1",
      "upstream_changed_files": ["megatron/path_a.py", "megatron/path_b.py"],
      "implementation_targets": [
        {
          "name": "Expose config on MindSpeed side",
          "source_unit": "Expose new config flag",
          "candidate_paths": ["mindspeed/arguments.py"],
          "required_change": "Add argument or YAML surface",
          "confidence": 0.82
        },
        {
          "name": "Port runtime behavior",
          "source_unit": "Add runtime behavior",
          "candidate_paths": ["mindspeed/training.py", "mindspeed/core/training.py"],
          "required_change": "Recreate the training shutdown logic locally",
          "confidence": 0.67
        }
      ],
      "covered_units": ["Expose config on MindSpeed side"],
      "missing_units": ["Port runtime behavior"]
    }
  ]
}

决策规则

• 如果对齐关系尚未确定：仅提供报告。
• 如果对齐关系已确定，但实现目标的依据较弱：提供报告和实现计划，不直接修改。
• 如果对齐关系和实现目标都具有高置信度：允许生成迁移补丁。
• 如果某项仅涉及一个本地文件，但上游事件显然涵盖多个实现单元，请明确标出尚未覆盖的单元，不要将该功能说成已完整映射。

参考资料

• 开始任何严格迁移工作前，请阅读 branch-alignment.md。
• 搜索候选适配路径时，请阅读 mindspeed-focus-areas.md。
• 运行 resolve_branch_alignment.py，以确定性方式将分支对分类为 strict、exploration 或 unresolved。
• 运行 scan_mindspeed_paths.py，根据功能名称、文件名、符号或配置键，在指定分支的官方 MindSpeed 仓库中搜索可能的适配点。
• 生成补丁前，运行 map_implementation_targets.py，将上游实现单元转换为本地 MindSpeed 实现目标。
• 仅将获准的项目移交给 $megatron-migration-generator。