megatron-migration-generator

Megatron 迁移生成器

只有在上游变更分析和影响映射将工作范围缩小到一组置信度较高的条目后，才为 MindSpeed 生成面向实现的迁移产物。目标是以对应的上游提交为主要参考，将上游功能移植到 MindSpeed，而不是给出一条简短的补丁提示。

默认输出模式

默认采用 report + patch，并以中文生成最终 Markdown 交付内容，除非用户明确要求使用其他语言环境。

不要默认直接编辑代码或自动提交。 默认提供以实现为先的软件包，而不是最精简的补丁草案。

支持的模式

1. report 仅生成迁移报告。
2. patch 生成迁移报告和完整的实现参考软件包。默认按功能使用独立文件夹，其中包含 full.patch、拆分后的 patches/、上游参考元数据、实现检查清单，以及明确列出的未覆盖范围。
3. apply 编辑本地工作区，但不创建提交。仅在对齐程度和影响置信度较高时使用。
4. commit 仅在用户明确要求且补丁审查通过后使用。不要将其作为首次处理的默认模式。

入口条件

仅当满足以下所有条件时才继续：

• 已知 MindSpeed 分支。
• 已知 Megatron 基础分支。
• 已知 Megatron 目标分支或变更集。
• 已有相关影响条目。
• 每个值得迁移的条目都包含上游提交引用，以及足以区分配置、运行时、包装器和测试工作的实现范围信息。

如果缺少任何条件，请停止并询问或推导缺失的前置条件，而不是猜测。

工作流

1. 阅读影响报告。
2. 将高置信度条目与推测性条目区分开。
3. 对每个高置信度条目，说明： 上游事件、 上游提交及变更文件、 上游实现单元、 本地适配目标、 预期代码变更、 不确定性。
4. 生成： 一个整合后的 migration_report.md 如需后续传递，则生成 impact_report.json 作为精简摘要索引的 candidate_patch.md 一个 features/ 目录，其中每个迁移条目各有一个子文件夹，且每个文件夹都包含： 用于完整本地实现草案的 full.patch 按实现单元组织的拆分补丁系列 patches/ 作为兼容性入口补丁的 candidate.patch README.md、checklist.md、package_manifest.json 和 upstream_reference.json
5. 如果处于 apply 模式，只编辑获准的文件，并清楚说明所做的更改。

安全规则

• 不要在没有影响报告的情况下，直接根据原始提交历史生成迁移代码。
• 在探索模式下避免直接编辑。
• 当目标为 megatron main 时，将代码输出描述为候选适配草案，而不是保证兼容的迁移。
• 优先生成补丁产物而不是提交，因为在分支对齐仍在变化时，补丁更易于审查且更安全。
• 如果上游提交涉及配置、运行时逻辑、包装器和测试，不要把单个本地文件编辑视为完整的功能迁移。
• 如果无法根据现有输入完成完整迁移软件包，请明确记录未覆盖的实现单元、遗漏范围和后续手动处理事项，不要假装功能已经完成。

静态验证

验证应保持轻量且仅限本地：

• 补丁可干净应用
• 路径存在
• 名称和参数符合本地代码结构
• 在可用时进行基本语法或 lint 级检查
• 软件包说明哪些上游实现单元已移植，哪些仍待移植

不要暗示已验证训练正确性、性能或数值精度。

参考资料

• 选择输出形式前，请阅读 migration-modes.md。
• 生成声称代表功能实现的迁移包前，请阅读 implementation-first-package.md。
• 请阅读 report-template.md，了解预期的整合版 Markdown 交付物结构。报告语言默认使用中文。
• 完成影响映射后，如果希望将已知功能提交扩展为更完整的多文件补丁系列，而不是保留为单文件占位内容，请运行 synthesize_full_patch_series.py。
• 手动完善之前，请运行 render_migration_artifacts.py，将 impact_report.json 转换为可供审阅的报告和补丁计划产物。