[RFC]: 统一特性管理（MA/MindSpeed 双端 FEATURES_LIST 合并）整体方案设计

状态 (Status): Implemented
作者 (Authors): TBD
创建日期 (Created): 2026-08-11
更新日期 (Updated): 2026-08-12
相关 Issue/PR: 无

1. 概述

1.1 简介

本方案将当前分别位于 MegatronAdaptor（MA，Megatron 适配器）与 MindSpeed 两套 FEATURES_LIST 的特性管理（Features Manager，特性管理组件）统一为 MA FeaturesManager 上的单一特性清单：MindSpeed 不再维护独立的特性清单与补丁应用覆写，而是把自身特性（含 MindSpeed 独有的特性参数）以追加方式注册进 MA 的特性管理体系；补丁归属仍按层级隔离（MA 特性 → MA PatchesManager，MindSpeed 特性 → MindSpeedPatchesManager）。

本文档描述：双端现状问题、统一后的总体架构与执行流程、技术选型、核心机制（补丁管理器路由、增量应用、分层移除）、两侧具体改动明细、接口设计与风险分析。

1.2 动机

• 两套管理体系，重复维护：MA 的 FeaturesManager 与 MindSpeed 的 MindSpeedFeaturesManager 各自持有 FEATURES_LIST（子类以同名类属性遮蔽父类列表），参数注册、参数校验、补丁应用、补丁移除等生命周期管理需要在两侧各维护一份，特性迁移（MA 架构拆分自 MindSpeed）时同一特性在两处重复实现。
• 特性重复实现：ProfilerDefaultFeature、ProfileFeature、NPUDeterministicFeature、NPUDataDumpFeature 四个 functional 特性在 MA 与 MindSpeed 各有一份（MA 版由 MindSpeed 迁出）；NpuEnhancementFeature 与 MA MegatronBasicFeature 各自向 megatron.training.arguments.parse_args/validate_args 注册一层 wrapper。
• 重复参数注册已构成运行时缺陷风险：MindSpeed 部署时 megatron 的 parse_args 上叠加两层 wrapper（MA 层 + MindSpeed 层），两层分别遍历各自清单向同一个 ArgumentParser 注册特性参数。megatron parser 使用默认 conflict_handler='error'，四个重复特性注册的同名参数（--profile-level、--npu-datadump、--npu-deterministic 等）会触发 argparse.ArgumentError。
• 参数面分裂与双缓存隐患：两侧 get_mindspeed_args 各自解析一次命令行，MA 入口得到的 args 命名空间缺少 MindSpeed 特性参数，参数语义被入口顺序隐式割裂；且两侧各持有一个模块级 _MINDSPEED_ARGS 缓存，MindSpeed 代码（如 patch_features）与 MA 内部代码各调一次会得到两个内容相同但彼此独立的 Namespace，repatch() 若在兜底路径修改其中一个，另一个感知不到。
• 不做会怎样：每新增/迁移一个特性都必须在两个清单、两套参数注册中双份维护并保持同步；四个重复特性的同名参数在 megatron parser 上重复注册的问题随部署路径变化随时显性化；MindSpeed 基于 MA 的架构拆分迁移无法收敛。

1.3 目标

Goals

• 单一特性清单：FeaturesManager.FEATURES_LIST 成为唯一清单，MindSpeed 特性以追加（add_features）方式注册进同一清单。
• MindSpeed 特性参数（含独有参数，如 --optimization-level）统一经由 FeaturesManager 的注册/校验流程生效。
• 补丁归属保持分层：MA 特性补丁注册到 MA PatchesManager，MindSpeed 特性补丁注册到 MindSpeedPatchesManager，保留"移除 MindSpeed 层可恢复 MA 层"的语义。
• 保持两阶段入口执行语义（MA 入口先行、MindSpeed 入口随后）与 repatch() 语义不变。
• 兼容第三方继承契约（tests_extend/unit_tests/mindspeed/test_third_party_feature_override.py 全部断言继续通过）。
• 删除 MindSpeed 侧四个重复 functional 特性文件，消除重复实现。
• 参数工具归一：MindSpeed args_utils.py 改为从 MA 重导出，两侧共用同一 parser 与同一 _MINDSPEED_ARGS 缓存，消除双缓存不一致隐患。

Non-Goals

• 不清理 NpuEnhancementFeature 中与 MA MegatronBasicFeature 重复的其他补丁注册（_compile_dependencies、get_device_wrapper、get_device_arch_version 等，保持现有双层叠加、MindSpeed 层生效的现状）。
• 不修改 MindSpeed 内 38+ 个 from mindspeed.args_utils import ... 的调用点（归一经 MindSpeed 模块重导出实现，调用面零改动）。
• 不修改 MA PatchesManager（保持 staticmethod 封闭形态）与 Patch 的行为语义；MindSpeed MindSpeedPatchesManager 保持独立实现，仅导入复用 MA 的 Patch 类。
• 不改变 import mindspeed.megatron_adaptor 的用户接入方式。
• 不改动遗留参数路径 mindspeed/arguments.py 中的参数注册主体，仅适配其引用的基础特性清单。

2. 用例分析

2.1 特性注册与应用场景

场景	功能点	关键指标/约束
MA 独立部署	import megatron_adaptor 自动安装并应用 MA 内置 7 个特性	行为与现状一致；全部补丁注册到 MA PatchesManager
MindSpeed 部署	import mindspeed.megatron_adaptor 后 MA 特性与 MindSpeed 特性全部生效	每个特性的补丁恰好注册并应用一次，无 the patch of xxx exist ! 重复注册异常；MindSpeed 特性补丁全部位于 MindSpeedPatchesManager
第三方仓库继承替换	子类 manager（自带 FEATURES_LIST）+ 替换特性实例	test_third_party_feature_override.py 全部断言通过；MA 清单与 MA 补丁注册表不受影响
repatch（如 TTP 二阶段）	repatch(args) 移除 MindSpeed 层补丁并按新 args 重新应用	MA 层补丁保持不变；仅 MindSpeed 特性被重新注册/应用

2.2 参数注册与校验场景

场景	功能点	关键指标/约束
megatron parse_args 路径	特性参数注册	全部特性（MA+MindSpeed）参数仅注册一次；无 argparse.ArgumentError；--profile-level、--npu-datadump、--optimization-level 等均可用
megatron validate_args 路径	特性参数三段式校验（pre → megatron 原生 → post → validate）	每个特性的校验方法仅执行一次（单层 wrapper 负责），无保存/恢复类校验的重复执行；参数打印日志行为不变
yaml_arguments.validate_yaml 路径	MA 层校验 wrapper	由 MA MegatronBasicFeature 直接注册，基于统一清单执行一次完整校验（同时修复 MA standalone yaml 模式的校验缺口）
TransformerConfig.__post_init__ 路径	MindSpeed 层校验 wrapper	行为不变（MA 特性当前无校验实现，暴露到该路径无副作用）
MindSpeed 独立参数解析	mindspeed.args_utils.get_mindspeed_args（重导出自 MA）	解析结果包含全部特性（MA+MindSpeed）的参数面；与 MA 入口共用同一 parser 与同一 _MINDSPEED_ARGS 缓存
遗留路径 mindspeed/arguments.py	process_args 基础特性清单注册	清单不再包含重复 functional 特性；conflict_handler='resolve' 容忍与统一清单的重复

2.3 DFX 要求

类别	要求
兼容性	两阶段入口、repatch、第三方继承契约行为等价；MindSpeedFeaturesManager 符号与继承关系保留
可维护性	特性清单与参数注册单一入口；新增特性仅在一侧一处注册，杜绝双份维护
可靠性	消除 megatron parser 上同名参数重复注册的 argparse.ArgumentError 缺陷风险
可测试性	既有契约测试与单测无需重写即可覆盖核心语义；离线（无 NPU）可验证注册/应用/移除流程

3. 方案设计

3.1 总体方案

import mindspeed.megatron_adaptor
│
├─① mindspeed/__init__.py ── import megatron_adaptor
│     └─ MA 入口 patch_features()（megatron_adaptor/megatron_adaptor.py）
│           ├─ FeaturesManager.FEATURES_LIST ← MA 内置 7 特性
│           │   （features_manager/__init__.py 导入时经 set_default_features_list 安装）
│           ├─ get_mindspeed_args()：注册 MA 特性参数并解析 CLI
│           └─ apply_features_pre_patches / apply_features_patches
│                 └─ MA 特性 → feature.patch_manager == MA PatchesManager
│                    （注册、应用并置"已应用"标志）
│
└─② mindspeed/megatron_adaptor.py ── patch_features()
      ├─ mindspeed/features_manager/__init__.py 导入时：
      │     FeaturesManager.add_feature(create_features_list())
      │     └─ MindSpeed 特性【追加】进同一 FEATURES_LIST
      ├─ get_mindspeed_args()：注册全部特性（MA+MS）参数并解析 CLI
      └─ apply_features_pre_patches / apply_features_patches
            ├─ MA 特性：已置"已应用"标志 → 跳过（不重复注册）
            └─ MindSpeed 特性 → feature.patch_manager == MindSpeedPatchesManager
               （注册、应用并置"已应用"标志）

megatron parse_args / validate_args 被调用时（MA MegatronBasicFeature 注册的单层 wrapper）
└─ FeaturesManager.register_features_args / pre_validate / post_validate / validate
      └─ 遍历统一清单，每个特性恰好注册/校验一次

编号执行流程：

1. mindspeed/__init__.py 导入 megatron_adaptor，MA 包 __init__ 安装内置特性清单并执行 MA 入口 patch_features()；
2. MA 入口解析 CLI（此时清单仅含 MA 特性），对满足 is_need_apply 的 MA 特性经其 patch_manager 注册并应用补丁，同时置位各特性的应用状态标志；
3. mindspeed/megatron_adaptor.py 导入触发 mindspeed.features_manager.__init__，将 MindSpeed 特性追加到同一清单；
4. MindSpeed 入口 get_mindspeed_args() 以完整清单注册参数并解析 CLI；
5. MindSpeed 入口再次调用 apply：带"已应用"标志的 MA 特性被跳过，MindSpeed 特性经 MindSpeedPatchesManager 注册并应用；
6. 训练脚本调用 megatron parse_args/validate_args 或 yaml 入口 validate_yaml 时，仅由 MA MegatronBasicFeature 注册的单层 wrapper 基于统一清单完成参数注册与三段式校验（覆盖 CLI 与 yaml 两个入口）；MindSpeed 层仅保留参数打印薄 wrapper。

3.2 技术选型

方案	描述	优势	劣势	是否采用
A. 共享清单 + 按特性路由补丁管理器 + 增量应用	单一 FEATURES_LIST 落在 MA FeaturesManager；每个特性经 patch_manager 属性声明补丁归属；apply 以"已应用"标志跳过重复	改动最小；两阶段入口与 repatch 语义完全保留；第三方契约不受影响；消除重复注册	特性基类新增应用状态标志	✅ 采用
B. MindSpeed 抑制 MA 自动执行、单入口全量应用	MindSpeed 导入时抑制 MA 的 patch_features 自动执行，由 MindSpeed 入口一次性组装全量清单并应用	单次应用、无需状态标志	import megatron_adaptor 的任何子模块导入都会先执行其包 __init__，无法在常规导入顺序内完成抑制，需向 MA 引入环境变量/配置开关；且改变 import mindspeed 的即时补丁行为，波及面大	❌
C. 保持双清单，仅提供统一注册门面	保留 MindSpeedFeaturesManager.FEATURES_LIST，另加同步 API	无机制改动	双清单、双份维护的根因未消除，重复参数注册风险仍在	❌

选型理由：方案 A 以最小机制变更（特性级补丁管理器路由 + 应用状态标志）达成单一清单目标，完整保留现有两阶段入口、repatch 分层移除与第三方继承契约，风险可控、可离线验证。

3.3 功能与性能设计

3.3.1 组件职责

组件	仓库	职责（统一后）
FeaturesManager	MA	唯一特性清单持有者；清单管理（set/add，add_feature 兼容单个特性或列表）、按特性路由的 pre/main 补丁应用、参数注册与三段式校验、全量移除
MindSpeedFeaturesManager	MindSpeed	FeaturesManager 的兼容薄子类：不再持有独立清单、不再覆写 apply；仅覆写 remove_patches 为 MindSpeed 层范围移除
MindSpeedFeature（MA 基类）	MA	特性基类：新增 patch_manager 属性（默认 MA PatchesManager）与应用状态标志
MindSpeedFeature（MindSpeed 子类）	MindSpeed	覆写 patch_manager → MindSpeedPatchesManager；保留 parser 辅助方法
PatchesManager	MA	补丁注册与注册表，实现与 staticmethod 形态保持不变（封闭、不可继承扩展）
MindSpeedPatchesManager	MindSpeed	独立实现（不继承 MA），持有独立 patches_info 注册表；删除本地重复的 Patch 类，改为导入复用 MA 的 Patch
megatron_adaptor.utils.args_utils	MA	参数工具唯一实现：特性参数解析（get_mindspeed_args）、全量参数获取（get_full_args，ContextVar 缓存优先）、未知参数归集；不变
mindspeed.args_utils	MindSpeed	参数工具薄重导出模块：add_args/parser_unknown_args/get_mindspeed_args/get_full_args/set_full_args 全部自 MA 重导出，不再持有本地实现与本地 _MINDSPEED_ARGS 缓存

3.3.2 核心机制

（1）按特性路由补丁管理器

# MA: megatron_adaptor/features_manager/mindspeed_feature.py
class MindSpeedFeature:
    @property
    def patch_manager(self):
        from megatron_adaptor.patches.patch_manager import PatchesManager
        return PatchesManager

# MindSpeed: mindspeed/features_manager/feature.py
class MindSpeedFeature(MAFeature):
    @property
    def patch_manager(self):
        from mindspeed.patch_utils import MindSpeedPatchesManager
        return MindSpeedPatchesManager

特性实现签名不变（register_patches(self, patch_manager, args) 等仍接收管理器参数），由管理器传入 feature.patch_manager，既有全部特性实现零改动。

（2）增量应用与应用状态标志

# MA: FeaturesManager
@classmethod
def apply_features_patches(cls, args):
    patch_managers = []
    for feature in cls.FEATURES_LIST:
        if not feature.is_need_apply(args) or feature.patches_applied:
            continue
        feature.register_patches(feature.patch_manager, args)
        feature.patches_applied = True
        if feature.patch_manager not in patch_managers:
            patch_managers.append(feature.patch_manager)
    for patch_manager in patch_managers:
        patch_manager.apply_patches()

apply_features_pre_patches 同构（使用 pre_patches_applied 标志与 pre_register_patches）。两阶段入口下：MA 入口应用 MA 特性并置位；MindSpeed 入口再次 apply 时 MA 特性被跳过，仅应用新追加的 MindSpeed 特性，避免向补丁注册表重复注册（set_patch_func 对重复替换会抛 RuntimeError）。

（3）分层移除与 repatch

# MA: FeaturesManager（全量语义：复位所有标志，移除清单涉及的全部补丁管理器）
@classmethod
def remove_patches(cls):
    for feature in cls.FEATURES_LIST:
        feature.pre_patches_applied = False
        feature.patches_applied = False
    for patch_manager in {feature.patch_manager for feature in cls.FEATURES_LIST}:
        patch_manager.remove_patches()

# MindSpeed: MindSpeedFeaturesManager（分层语义：仅移除 MindSpeed 层）
@classmethod
def remove_patches(cls):
    from mindspeed.patch_utils import MindSpeedPatchesManager
    for feature in cls.FEATURES_LIST:
        if feature.patch_manager is MindSpeedPatchesManager:
            feature.pre_patches_applied = False
            feature.patches_applied = False
    MindSpeedPatchesManager.remove_patches()

repatch(args) 调用 MindSpeedFeaturesManager.remove_patches() 后重新 apply：MA 特性标志未复位 → 跳过；MindSpeed 特性标志复位 → 按新 args 重新注册应用。与现状语义一致。

3.3.3 适配项明细

MA 侧改动

#	文件	改动
1	megatron_adaptor/features_manager/mindspeed_feature.py	__init__ 新增 pre_patches_applied/patches_applied 标志；新增 patch_manager 属性（默认 MA PatchesManager）
2	megatron_adaptor/features_manager/features_manager.py	add_feature 归一为兼容单个特性或列表入参（删除原 add_features）；apply_features_pre_patches/apply_features_patches 改为按特性路由 + 已应用跳过的增量应用；remove_patches() 改为复位全部标志并移除清单涉及的全部补丁管理器；add_feature/set_features_list 末尾调用 reset_mindspeed_args() 使参数缓存失效（惰性导入，无循环依赖）
3	megatron_adaptor/utils/args_utils.py	新增 reset_mindspeed_args()：清单变更后将 _MINDSPEED_ARGS 置 None，使下一次 get_mindspeed_args() 按最新清单重新解析；顺带删除未使用的 _GLOBAL_ARGS 导入（F401）
4	megatron_adaptor/features_manager/megatron/megatron_basic.py	新增向 megatron.training.yaml_arguments.validate_yaml 注册 validate_args_wrapper：yaml 路径的特性校验归 MA 层所有（统一清单校验覆盖全部入口），并修复 MA standalone yaml 模式不校验特性参数的缺口
5	megatron_adaptor/patches/patch_manager.py、features_manager/__init__.py、入口	不变

MindSpeed 侧改动

#	文件	改动
1	mindspeed/features_manager/feature.py	覆写 patch_manager 属性 → MindSpeedPatchesManager
2	mindspeed/features_manager/features_manager.py	删除 FEATURES_LIST = [] 遮蔽与 apply 覆写；仅保留 remove_patches 覆写（MindSpeed 层范围移除 + 复位 MS 特性标志）
3	mindspeed/features_manager/__init__.py	create_features_list() 移除 4 个重复 functional 特性；set_default_features_list() 由 set_features_list（整体替换）改为 FeaturesManager.add_feature(...)（追加，入参为列表）；模块级基础清单 FEATURES_LIST 移除 ProfilerDefaultFeature 条目（其余 5 项保留，供遗留 mindspeed/arguments.py 使用）
4	mindspeed/features_manager/functional/{profile,profiler_default,npu_datadump,npu_deterministic}.py	删除（已核实仅被 features_manager/__init__.py 引用；其底层实现模块 mindspeed/functional/** 不在本次范围）
5	mindspeed/patch_utils.py	删除本地重复的 Patch 类定义（约 90 行），改为 from megatron_adaptor.patches.patch_manager import Patch 复用；MindSpeedPatchesManager 保持独立 staticmethod 实现与独立注册表（不继承 MA PatchesManager）；保留 is_megatron_training_available。管理器主体与 MA 逐字相同的约 50 行为有意保留的隔离设计：注册表必须独立，继承复用需 classmethod 分发，存在子类静默共享注册表与实现被覆写的风险，经评估后否决，接受该冻结重复
6	mindspeed/features_manager/npu_enhancement/npu_enhancement.py	_register_non_mcore_patches 不再向 megatron.training.arguments.parse_args/validate_args 注册 MindSpeed 的参数注册/校验 wrapper；validate_args 与 validate_yaml 均改注册"仅打印"薄 wrapper；yaml 校验 wrapper 由 MA 层注册，MindSpeed 不再跨层代注册；保留两处 _print_args 注册（4 个对称的 MindSpeed 自有注册）
7	mindspeed/core/megatron_basic/arguments_basic.py	删除与 MA 重复的死代码（extra_args_provider_decorator/parse_args_wrapper/validate_args_wrapper）；新增 print_after_validate_wrapper（内层校验完成后调用 _print_args("arguments", args, True)）；文件仅保留 MindSpeed 特有的打印与 TransformerConfig 类 wrapper
8	mindspeed/megatron_adaptor.py	不变（apply 走继承的增量实现；repatch 不变）
9	mindspeed/args_utils.py	改为薄重导出模块：删除 add_args/parser_unknown_args/get_mindspeed_args/get_full_args 本地实现与本地 _MINDSPEED_ARGS 缓存，全部自 megatron_adaptor.utils.args_utils 重导出（并顺带重导出 set_full_args）。全仓 38+ 个 from mindspeed.args_utils import ... 调用点零改动。两处细微行为变化（均可接受）：①兜底日志文案与频次跟随 MA 实现（use megatron_adaptor arguments、LOG.warning 非 once 语义）；②parser description 显示 MegatronAdaptor Arguments（仅外观）

3.3.4 参数解析与校验横切流程（统一后挂点）

挂点	wrapper 归属	行为
megatron.training.arguments.parse_args	仅 MA（MegatronBasicFeature）	FeaturesManager.register_features_args(parser)：统一清单全量特性参数注册一次
megatron.training.arguments.validate_args	MA 校验 wrapper + MindSpeed 打印薄 wrapper	MA 层执行统一清单三段式校验一次；MindSpeed 层仅在内层返回后打印参数
megatron.training.arguments._print_args	MindSpeed	抑制原生打印（仅 after_validate=True 时打印），不变
megatron.training.yaml_arguments.validate_yaml	MA 校验 wrapper + MindSpeed 打印薄 wrapper	MA MegatronBasicFeature 直接注册 validate_args_wrapper 做统一清单三段式校验一次（先注册在内层），MindSpeed 叠加打印 wrapper
TransformerConfig.__post_init__ 等	MindSpeed（NpuEnhancementFeature）	统一清单三段式校验；MA 特性当前均无校验实现，等价无操作
两侧 get_mindspeed_args	统一为 MA 单实现（MindSpeed 重导出）	全进程单一 parser 与单一 _MINDSPEED_ARGS 缓存；任意入口解析均含全部特性参数面；MindSpeed 侧顺带获得 ContextVar 缓存能力

3.4 安全隐私与 DFX 设计

类别	设计
兼容性	MindSpeedFeaturesManager 符号、继承关系与第三方子类用法保留；两阶段入口与 repatch 行为等价；第三方契约测试无需修改
可维护性	特性清单与参数注册收敛为单一入口（MA features_manager/__init__.py + MindSpeed features_manager/__init__.py 追加）；新增特性不再需要双份注册
可靠性	单一 wrapper 层注册参数，消除 megatron parser 同名参数重复注册导致的 argparse.ArgumentError；增量应用标志防止补丁重复注册异常
可测试性	离线可验证：清单合并、按特性路由、增量跳过、分层移除；既有 test_third_party_feature_override.py 覆盖第三方契约

3.5 编程与调用设计

3.5.1 编程模型基本设计

约束	说明（可验收设计）
特性实现不感知归属	特性仍通过 register_patches/pre_register_patches 的入参使用补丁管理器；归属由基类 patch_manager 属性决定。验收：既有全部特性实现零改动
注册入口唯一	MA 特性在 MA features_manager/__init__.py 注册；MindSpeed 特性在 MindSpeed features_manager/__init__.py 经 add_feature 追加（传入列表）。验收：全仓库对 FEATURES_LIST 的整体替换仅存于 MA 默认安装
校验方法容忍多种 args 载体	validate_args 等可能接收完整 args 或 TransformerConfig 实例；新增校验逻辑须用 getattr 防御。验收：新增 MA 特性校验在 post_init 路径不抛属性异常
禁止特性内直接改清单	特性实现不得增删 FeaturesManager.FEATURES_LIST。验收：代码评审约束

3.5.2 接口定义与设计

3.5.2.1 MindSpeedFeature.patch_manager

• 接口描述：声明该特性的补丁归属管理器，导入期即可求值，供 FeaturesManager 应用阶段路由。
• 接口原型：

@property
def patch_manager(self):
    ...

• 输入/输出参数：

参数名称	输入/输出	类型	描述	取值范围
self	输入	MindSpeedFeature 实例	特性实例	-

• 返回参数：补丁管理器类（MA 基类返回 PatchesManager；MindSpeed 子类返回 MindSpeedPatchesManager；第三方可覆写）。
• 异常处理：无（惰性导入，导入失败抛出原始 ImportError）。
• 约束说明：必须返回具有 register_patch/apply_patches/remove_patches 接口的类；不得返回实例级可变对象。
• 调用参考代码：

from megatron_adaptor.features_manager.mindspeed_feature import MindSpeedFeature

class MyFeature(MindSpeedFeature):
    def register_patches(self, patch_manager, args):
        patch_manager.register_patch("some.module.func", my_replacement)

assert MyFeature("my-feature").patch_manager is not None

3.5.2.2 FeaturesManager.add_feature

• 接口描述：向统一特性清单追加特性，兼容单个特性实例或特性列表两种入参；供 MindSpeed 等上层仓库注册自身特性，也供第三方仓库逐个注册；导入 megatron_adaptor.features_manager 后可用。
• 接口原型：

@classmethod
def add_feature(cls, feature: Union[MindSpeedFeature, List[MindSpeedFeature]]) -> None: ...

• 输入/输出参数：

参数名称	输入/输出	类型	描述	取值范围
feature	输入	MindSpeedFeature 或 List[MindSpeedFeature]	单个特性实例，或待追加的特性实例列表	MindSpeedFeature 子类实例（或其列表）

• 返回参数：无（原地修改 cls.FEATURES_LIST）。
• 异常处理：无显式异常；传入非特性实例将在后续 apply 阶段以 AttributeError 显性化。
• 约束说明：须在 MA 默认清单安装之后调用（任意 megatron_adaptor.features_manager 子模块导入即完成安装）；同一进程内重复追加同一特性会导致重复注册，调用方需保证幂等（MindSpeed 侧仅在包 __init__ 中调用一次）。
• 调用参考代码：

from megatron_adaptor.features_manager.features_manager import FeaturesManager

# 追加单个特性
FeaturesManager.add_feature(MyFeature())
# 追加特性列表
FeaturesManager.add_feature([MyFeature(), AnotherFeature()])
assert any(isinstance(f, MyFeature) for f in FeaturesManager.FEATURES_LIST)

3.5.2.3 FeaturesManager.apply_features_patches（语义更新）

• 接口描述：遍历统一清单，为未应用且满足 is_need_apply(args) 的特性经其 patch_manager 注册补丁并应用；已应用特性跳过。apply_features_pre_patches 同构。
• 接口原型：

@classmethod
def apply_features_patches(cls, args) -> None: ...

• 输入/输出参数：

参数名称	输入/输出	类型	描述	取值范围
args	输入	argparse.Namespace	特性开关与 optimization_level 来源	含 CLI 解析结果

• 返回参数：无。
• 异常处理：特性 register_patches 内部异常原样抛出；对同一特性重复调用不会触发补丁重复注册异常（标志跳过）。
• 约束说明：两阶段入口可各调用一次；repatch 前须先调用对应层级的 remove_patches 复位标志。
• 调用参考代码：

from argparse import Namespace
from megatron_adaptor.features_manager.features_manager import FeaturesManager

FeaturesManager.apply_features_patches(Namespace(optimization_level=2))
FeaturesManager.apply_features_patches(Namespace(optimization_level=2))  # 第二次全跳过，无异常

3.5.2.4 MindSpeedFeaturesManager.remove_patches（分层语义）

• 接口描述：仅移除 MindSpeed 层补丁（MindSpeedPatchesManager）并复位 MindSpeed 特性的应用标志，MA 层补丁与其标志不受影响；repatch 依赖该语义。
• 接口原型：

@classmethod
def remove_patches(cls) -> None: ...

• 输入/输出参数：无。
• 返回参数：无。
• 异常处理：无（无已注册补丁时为空操作）。
• 约束说明：与 FeaturesManager.remove_patches（全量移除清单涉及的所有管理器）语义不同，MindSpeed 侧 repatch 必须使用本方法。
• 调用参考代码：

from mindspeed.features_manager.features_manager import MindSpeedFeaturesManager

MindSpeedFeaturesManager.remove_patches()  # 仅 MindSpeed 层被移除，MA 层实现恢复可见

3.5.3 编程手册设计

不新增文档文件；实施时同步更新既有文档中的注册入口描述：MindSpeed docs/zh/user-guide/feature_development.md（特性注册到统一清单、MindSpeed 侧追加方式）与 MA docs/introduction.md（清单共享说明）。

4. 缺点和风险

风险类别	描述	应对措施
行为变化	清单顺序变为 MA 特性在前、MindSpeed 特性在后，校验与注册顺序变化	MA 特性当前均无校验实现；单层 wrapper 内按清单顺序执行，MindSpeed 内部相对顺序不变；以既有单测回归
行为变化	MA 特性首次暴露于 TransformerConfig.__post_init__ 校验路径	现有 MA 特性 pre/post/validate 均为空实现，无影响；编程模型中新增"校验须容忍 TransformerConfig 载体"约束
状态管理	应用状态标志若未正确复位，特性将在 repatch 后被错误跳过	FeaturesManager.remove_patches 全量复位、MindSpeedFeaturesManager.remove_patches 按归属复位；以 repatch 相关测试验证
缓存一致性	统一参数缓存后，MA 入口先行解析并缓存的 args 仅含 MA 特性参数面，MindSpeed 特性追加进清单后若沿用该缓存将缺失 --optimization-level 等新注册参数，导致 MindSpeed 特性 is_need_apply 覆写版（直接属性访问）抛 AttributeError	add_feature/set_features_list 末尾调用 reset_mindspeed_args() 使缓存失效，MindSpeed 入口以完整清单重新解析（生命周期内清空一次、重新解析一次，训练期全部命中缓存）
兼容性	第三方继承契约因结构变化失效	保留 MindSpeedFeaturesManager 子类与第三方自带 FEATURES_LIST 的用法；运行 test_third_party_feature_override.py 验证
删除文件	四个 MindSpeed functional 特性文件存在未识别引用	已核实仅 mindspeed/features_manager/__init__.py 引用；随本次改动同步更新引用并删除
遗留路径	mindspeed/arguments.py 基础清单与统一清单重复注册	该路径 parser 使用 conflict_handler='resolve' 容忍重复；基础清单收窄后重复面更小
打印行为	validate_args 路径参数打印依赖 MindSpeed 薄 wrapper 与 _print_args 补丁的三参签名	保留 _print_args 补丁注册；薄 wrapper 在内层校验完成后以 after_validate=True 调用打印
行为变化	MindSpeed 复用 MA Patch 后，remove_patch 的恢复扫描会额外跳过模块名含 megatron_adaptor 的模块	已核实 MindSpeed 无任何以 megatron_adaptor.* 为目标的补丁注册；对 megatron.*/mindspeed.* 目标补丁的移除行为两版一致
行为变化	参数工具归一后兜底日志文案/频次与 parser description 外观变化	仅影响日志文案与 --help 类报错的 description 展示，无功能影响，已在适配项明细注明
兼容性	第三方若直接导入 mindspeed.args_utils 或 monkeypatch 其符号	mindspeed.args_utils 模块与其公开符号全部保留（重导出实现），from mindspeed.args_utils import get_full_args 等用法不受影响；已核实 MindSpeed 测试无针对 args_utils 的 monkeypatch