msModelSlim 离群值抑制适配

本 skill 在基础模型适配完成后，负责所选离群值抑制算法的 Adapter 接口适配、安装、验证及独立门禁。它使用当前环境已安装的 msModelSlim fast_ops_grapher 提取模型执行图，并让 Agent 根据目标模型源码和已注册 Adapter 生成模型专用的 final-logits capture patch。选定算法分别从干净浮点 checkpoint 开始，只执行一个 anti-outlier processor，再比较同一 patch 采集的变换前后最终 logits。

实现离群值抑制接口前，先阅读 接口快速参考。该参考给出当前 msModelSlim 的 AdapterConfig、Smooth subgraph 和 QuaRot map 的最小实现；接口契约以当前 安装包/源码为准，模型映射以当前模型真实 forward 为准。不要从历史提交或其它模型 Adapter 复制路径和旋转表。

定位与边界

• 不生成 capability matrix、JSON handoff、processor chain、候选阶梯或调优策略。
• 用户未指定算法时处理默认 4 项；用户明确给出算法列表时以该列表为准，不自行增加、组合或替换。
• 允许 anti-outlier processor 执行算法自身必需的校准 forward，但不执行独立量化、任务精度评测或保存量化权重。
• 不修改 PipelineInterface、ModelAdapter 基类或 msModelSlim 公共接口。
• 不在 skill 的 scripts/ 中维护模型 patch、模型注册表或按模型名分支的 finalizer。
• 不根据 model_type 名称猜测 final norm、head、residual、MTP、视觉融合或 TP gather。
• 所选算法的 Adapter 接口与映射只修改 msModelSlim 源码，执行 bash install.sh 后验证当前环境导入的实现；不得直接修改 site-packages。
• Agent 无法可靠生成或验证 patch 时，logits 门禁为 UNSUPPORTED，不得使用通用 norm/head 回退。

前置证据门禁

在 PATCH、processor 与 logits 门禁前，先在 msModelSlim 源码完成所选算法需要的 Adapter 接口与映射并重新安装，再检查当前已安装实现。已有接口可直接验证；缺失或错误时在本阶段 修复源码，不修改 site-packages。 基础适配证据满足以下条件之一：

• 复用与当前 checkpoint identity、Adapter entry point 和版本匹配的已有适配验证产物；
• 没有可复用产物时，执行本流程需要的定向接口检查，确认 Adapter 已注册且可由 PluginModelFactory 创建，handle_dataset、init_model 以及所选 Runner/processor 实际需要的接口可用。

不得因为缺少某个特定 skill 的验证报告而停止，也不要求重跑与本流程无关的完整回归。 运行 scripts/validate_anti_outlier_interfaces.py --model-type <name> --model-path <checkpoint> --source-root <msmodelslim_checkout> --output-dir <workdir> --algorithm <algorithm>，核对源码与 已安装 Adapter 一致，并按接口保存与当前 checkpoint 匹配的证据。 前置记录必须说明证据来源、实际检查项和 checkpoint identity。所选算法需要的接口 及映射必须在 PATCH 生成、processor 执行前检查；缺失或失败时记录该算法的 INTERFACE_VALIDATION_FAILED，不启动其门禁，其他接口已通过的算法仍可继续。

默认算法

默认实现并验证以下 4 项；用户明确给出算法列表时只验证该子集：

1. quarot
2. flex_smooth_quant
3. flex_awq_ssz
4. iter_smooth

参数只读取当前已安装 msModelSlim 自带的 expert_experience.yaml 中对应的 *_default 项，不在 msAgent 复制默认配置。 必须保留 flex_awq_ssz_default 的 qconfig；它只用于算法内部误差评估，不表示执行量化。

接口映射验证按 Adapter 接口去重：quarot 使用 QuaRotInterface， flex_smooth_quant 与 flex_awq_ssz 共享一次 FlexSmoothQuantInterface 验证， iter_smooth 使用 IterSmoothInterface。共享结果写入 interface_validation.<interface-name>.json，算法运行记录引用文件及 hash。 接口验证通过不代表对应 processor 的 logits 门禁通过；每个算法仍须独立解析配置并执行。

Agent 生成的 patch

Agent 必须交叉核对模型 config.json、实际 modeling_*.py、Adapter 的 handle_dataset/init_model/generate_model_forward、逐层加载与设备迁移能力，以及本次 输入实际覆盖的分支。patch 默认写入输出目录：

<output_dir>/patches/final_logits_capture.<model_type>.py

文件必须导出以下元数据和固定签名：

PATCH_METADATA = {
    "schema": "msagent.anti_outlier_logits_capture_patch/v1",
    "model_type": "<model_type>",
    "adapter_class": "<module>:<qualified-class-name>",
    "checkpoint_identity": "<stable identity>",
    "logits_scope": "full_sequence",  # 或 last_token
    "dtype_casts": [],  # 存在显式 cast 时记录 boundary/from/to
}


def capture_final_logits(self, model, inputs, device):
    ...

self 必须是当前 Adapter 实例。patch 不得创建 Adapter、调用 init_model()、重新加载 checkpoint 或替换当前模型参数；输入必须来自当前 Adapter 的 handle_dataset。它必须使用 torch.no_grad() 无梯度推理、正确处理模型特有的最终输出语义，并在 lazy/meta 模型上复用 Adapter 的逐层加载能力。捕获过程可能懒加载或替换持久模型参数，因此不得用 torch.inference_mode() 包裹该过程，以免后续 processor/after forward 遇到无版本计数的 inference tensor。

PATCH 必须根据真实 forward 检查 norm、残差和后续算子的 dtype。norm 内部允许使用 FP32 计算；当 FP32 激活进入要求 BF16 的算子时，在该算子的输入边界显式 cast 到实际需要的 dtype，不得全局转换持久模型参数或跳过层。before/after 使用同一份 PATCH、同一 cast 规则， 在 PATCH_METADATA.dtype_casts、patch 验证与报告中记录转换位置及前后 dtype。 PATCH 只覆盖 final-logits 捕获；若错误 发生在 processor 的校准 forward，必须记录 PROCESSOR_FAILED 并由该 forward 的所属 适配阶段处理，不能声称 PATCH 已修复校准路径。

工作流

1. 先按 接口快速参考 确认当前接口签名和最小映射，再在 msModelSlim 源码完成所选算法接口与映射，重新安装，再检查 Adapter、安装版本、 checkpoint identity 和逐接口证据一致。修复后仍不通过的算法在此停止，其他算法继续。
2. 使用已安装 msModelSlim 的官方 fast_ops_grapher Extractor 调用 extract_dag() 和 graph.format("dot")。每个选定算法保留 anti_outlier_graph.<algorithm>.dot；拓扑相同时 记录共享 hash，动态分支记录 dummy input 和覆盖限制。
3. 阅读模型源码、配置、Adapter 和官方图，核对 anti-outlier 映射、source/target、subgraph、 channel dimension、路径、重复/冲突条目及输入覆盖限制。
4. 生成并保存模型专用 final_logits_capture.<model_type>.py，所有选定算法复用同一份已验证 patch。
5. 在 processor 执行前验证 patch：语法、导入、固定签名、目标 model/Adapter/checkpoint identity， 以及固定输入下的有限值、shape/dtype 稳定性和相同 seed 可重复性。在有可信正式输出或小模型 fixture 时做交叉校验；结果按算法写入 final_logits_patch_validation.<algorithm>.json， 避免后一次运行覆盖前一次门禁的 hash。各项仍使用同一 PATCH 文件及 SHA256。
6. 引用前置阶段的映射验证结果，共享 Flex 接口只引用一次验证，并为每个算法记录引用关系。 接口验证文件必须包含与本次运行完全一致的 checkpoint identity；缺失 identity 或来自其他 checkpoint 的证据均无效。不得将共享接口 PASS 当作两个算法的 processor/logits PASS。
7. 对每项选定算法从同一原始浮点 checkpoint 初始化干净模型，使用固定输入采集变换前最终 logits， 只添加当前一个 processor，再用同一模型、输入、seed 和 patch 采集变换后最终 logits。不得复用上一算法修改过的模型。
8. 调用 scripts/apply_one_anti_outlier.py 时必须提供 --logits-capture-patch <generated_patch.py>。公开方法 apply_one_anti_outlier_and_record_logits(algorithm, model_path, fixed_input, output_dir) 也必须通过可选参数接收同一 patch，以及匹配的 --interface-validation <interface_validation.json> 证据。脚本动态加载并校验 patch，只对当前 Adapter 实例临时绑定 capture_final_logits，通过官方 runner.add_processor(...) 与 runner.run(...) 执行 processor；--runner auto 保持 msModelSlim 单设备的 layer_wise 语义，只有显式选择 model_wise 时才完整加载模型。不推断或回退到通用 final norm/head。运行记录必须在开始时创建， 且在失败时仍落盘。
9. 对每项调用 scripts/compare_final_logits.py --algorithm <algorithm> --run-record <run.json> --fp-logits <final_logits.before.<algorithm>.npy> --anti-outlier-logits <final_logits.after.<algorithm>.npy> --output <output_dir>/final_logits_comparison.<algorithm>.json。 比较脚本只消费 logits 和 provenance，核对 processor、patch SHA256、checkpoint identity、 输入摘要、before/after 路径及 quantization_run: false。PASS/FAIL 只使用最后位置的 Top-1 一致性与 Top-5 overlap；JS divergence、raw-logits cosine、逐元素容差及误差分位数只作为 诊断信息，不单独阻断结果。
10. 汇总 anti_outlier_report.md，逐项说明 patch 来源与 hash、接口验证引用、干净模型/单 processor 事实、before/after provenance、DOT 链接和失败阶段。

逐算法门禁完成后，报告每项算法的通过或失败状态，并撤回本次新增且仅供失败算法 使用的 Adapter 代码。共享接口或映射仍被通过的算法使用时保留；源码变更后重新安装并 验证。保留失败证据以继续修复，不修改已发布版本。本阶段不生成或修改 Practice YAML。

独立运行状态

每个算法必须独立留痕。失败不得阻止其他已选算法继续执行。运行记录至少区分：

• PATCH_UNSUPPORTED
• INTERFACE_VALIDATION_FAILED
• PATCH_VALIDATION_FAILED
• BEFORE_CAPTURE_FAILED
• PROCESSOR_FAILED
• AFTER_CAPTURE_FAILED
• COMPARISON_FAILED
• PASS

只有 patch 验证通过、processor 实际执行、比较脚本 provenance 校验通过且数值结果通过时， 该算法的 logits 门禁才算 PASS。

输出

• patches/final_logits_capture.<model_type>.py
• final_logits_patch_validation.<algorithm>.json
• interface_validation.<interface-name>.json
• anti_outlier_graph.<algorithm>.dot
• final_logits.before.<algorithm>.npy
• final_logits.after.<algorithm>.npy
• anti_outlier_run.<algorithm>.json
• final_logits_comparison.<algorithm>.json
• anti_outlier_report.md

DOT 只表示本次输入覆盖的模型执行路径，不代表 processor 执行轨迹。未执行、失败或 UNSUPPORTED 的算法必须在运行记录和人类可读报告中说明具体阶段与原因。