megatron-impact-mapper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Megatron Impact Mapper

Megatron 影响映射器

Resolve the correct MindSpeed branch context and map each relevant Megatron event onto concrete MindSpeed implementation targets. This skill is the gatekeeper for implementation-oriented migration generation.

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

Hard Gate

硬性门槛

Do not generate migration patches until branch alignment is explicit.

Use one of these alignment sources:

user-supplied mapping
a known rule in branch-alignment.md
a repository-local document or commit that states the mapping clearly

If none of these is available, stop at an impact report.

在分支对齐明确之前，请勿生成迁移补丁。

可使用以下任一对齐来源：

用户提供的映射关系
branch-alignment.md中的已知规则
代码库内明确说明映射关系的文档或提交记录

若以上来源均不可用，则仅生成影响报告即可停止操作。

Core Rules

核心规则

Treat
```
MindSpeed branch <-> Megatron branch
```
alignment as mandatory for strict migration mode.
Use only official repositories as the source of truth for first-pass analysis.
Distinguish between
```
strict migration mode
```
and
```
exploration mode
```
.
For
```
megatron main
```
, prefer exploration mode unless the user explicitly chooses a compatible MindSpeed baseline for comparison.
Separate three outcomes: already adapted, likely adaptable but missing, not worth adapting now.
Do not stop at "candidate paths" when a feature is clearly migration-worthy. Break the feature into implementation targets that correspond to the upstream implementation units.

在严格迁移模式下，
```
MindSpeed分支 <-> Megatron分支
```
的对齐是强制要求。
首次分析仅以官方代码库为可信来源。
区分
```
严格迁移模式
```
和
```
探索模式
```
。
对于
```
megatron main
```
分支，优先使用探索模式，除非用户明确选择兼容的MindSpeed基线进行对比。
区分三种结果：已适配、可适配但未实现、当前不值得适配。
当某个功能明显值得迁移时，不要停留在“候选路径”阶段。将该功能拆解为与上游实现单元对应的实现目标。

Workflow

工作流程

Resolve the MindSpeed branch.
Resolve the mapped Megatron baseline branch.
Compare the baseline against the target Megatron branch or change-set.
For each relevant Megatron event, search for corresponding MindSpeed modules, wrappers, configs, launch paths, and tests.
Map upstream implementation units onto local implementation targets.
Produce an impact report with confidence, rationale, and implementation scope.
Allow handoff to migration generation only for high-confidence impact items.

确定MindSpeed分支。
确定对应的Megatron基线分支。
将基线与目标Megatron分支或变更集进行对比。
针对每个相关的Megatron事件，搜索对应的MindSpeed模块、包装器、配置文件、启动路径和测试用例。
将上游实现单元映射到本地MindSpeed实现目标。
生成包含置信度、理由和实现范围的影响报告。
仅针对高置信度的影响项，才可移交至迁移生成环节。

Required Output

要求输出

Produce an

impact_report

with:

json

{
  "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"]
    }
  ]
}

生成一份

impact_report

，格式如下：

json

{
  "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"]
    }
  ]
}

Decision Rules

决策规则

If alignment is unresolved: report only.
If alignment is resolved but implementation targets are weakly supported: report plus implementation plan, not direct edits.
If alignment and implementation targets are both high confidence: allow migration patch generation.
If an item has only one touched local file but the upstream event clearly spans multiple implementation units, mark the uncovered units explicitly instead of pretending the feature is fully mapped.

若分支对齐未解决：仅生成报告。
若分支对齐已解决，但实现目标的支持性较弱：生成报告及实现计划，不直接进行编辑。
若分支对齐和实现目标均为高置信度：允许生成迁移补丁。
若某个项仅涉及一个本地文件，但上游事件明显涵盖多个实现单元，需明确标记未覆盖的单元，而非假装该功能已完全映射。

References

参考资料

Read branch-alignment.md before doing any strict migration work.
Read mindspeed-focus-areas.md when searching for candidate adaptation paths.
Run resolve_branch_alignment.py to deterministically classify a branch pair as
```
strict
```
,
```
exploration
```
, or
```
unresolved
```
.
Run scan_mindspeed_paths.py to search the official MindSpeed repository on a specific branch for likely adaptation points using feature names, file names, symbols, or config keys.
Run map_implementation_targets.py to convert upstream implementation units into local MindSpeed implementation targets before patch generation.
Hand off only approved items to $megatron-migration-generator.

在进行任何严格迁移工作前，阅读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。