Feature Description / 功能描述

随着真实训练案例增多，单一 Skill 已难以承载完整诊断流程，主要存在以下问题：

1. 训练精度异常实际包含不同证据前提和分析路径：
   • E01：自身重复稳定、与外部标杆相比，正向首先出现有限值偏差；
   • E02：自身重复稳定、正向基本对齐，反向梯度或 GradNorm 首先出现有限值偏差；
   • E04：NaN、Inf 或 Overflow；
   • E08：固定输入、权重、随机性和确定性设置后，受控重复运行仍不一致。
2. E04 不要求外部标杆，E08 应使用自身受控重复运行作为比较对象，不能继续沿用“统一要求基线”的入口。
3. 实际定位不仅包含算子 Dump，还涉及问题受理、症状路由、环境预检、范围缩减、多节点作业与产物汇集、采集有效性检查、单变量验证和独立复核。
4. 全量 Dump、同步、串行下发、模型剪裁等操作可能改变时序或使症状消失。若缺少证据门禁，容易把无代表性的采集结果或首个下游异常误判为根因。
5. 单算子脚本不复现不能直接排除候选。问题还可能依赖整网通信/计算并发、内存竞争、多流关系或上下文状态。

因此，建议新增 model-train-precision-diagnose Plugin，将训练精度诊断从单一 Skill 升级为多 Agent 编排流程，并将不同症状的分析能力拆分为独立、可复用的 Skills。

申请目标

申请进入 plugins-community，本需求：

• 将公共受理、路由、预检、缩圈、证据门禁和复核能力提升到 Plugin 编排层；
• 将 E01/E02、E04、E08 的症状方法分别沉淀为三个独立 Skill；
• 允许其他 Plugin 或 Agent 单独复用底层 Skill；
• 保留 OOM分析、日志分析等既有能力边界，不纳入本 Plugin。

Use Case / 应用场景

面向在 PyTorch on Ascend NPU 环境中排查以下问题的模型开发、框架适配和精度定位人员：

• Loss、Logits、激活、梯度或 GradNorm 与标杆存在有限值偏差；
• 训练过程中出现 NaN、Inf 或 Overflow；
• 相同输入、权重及配置下，重复运行结果不一致；
• 大规模多节点训练中，需要缩小到 Node、Rank、Step、Module、API 或 Tensor 边界；
• Dump 改变原始症状，需要评估观察者效应或并发竞争。

本 Plugin 不处理推理精度、OOM、性能调优、非 PyTorch 训练。

Expected Behavior / 期望行为

Plugin 工作流：

Primary
  ↓
model-train-precision-diagnose Plugin 编排入口（AGENTS.md，mode: primary）
  ├─ 创建 Case：precision_diagnosis/<case-id>/，初始化六个固定记录文件
  └─ 统一负责用户交互、风险确认、全局状态和最终交付
  ↓
Intake Agent（收集并确认基础信息）
  ├─ 确认集群拓扑、实际生效的训练入口与启动命令、docker/conda 等运行环境
  ├─ 确认症状、复现性、标杆状态、共享存储以及调度/逐节点启动方式
  └─ 关键字段未知时：Plugin 编排入口汇总问题向用户确认，再回到 Intake 更新记录
  ↓
Symptom Router Agent（只选择一个路由）
  ├─ E04：NaN/Inf/Overflow，优先级最高
  ├─ E08：受控的同环境重复运行不一致，以 A/B 两次运行互为天然标杆
  ├─ E01/E02：稳定复现且与外部标杆存在有限值正向/反向偏差
  └─ unsupported：参数更新异常、Checkpoint 续训不齐等未覆盖症状
  ↓
Preflight Agent（只读预检）
  ├─ 按 target/golden 检查数据、逐 Node 软件栈与实际加载路径、代码/配置哈希
  ├─ 检查模型与训练配置、环境变量、权重及并行/随机性契约
  └─ 生成 preflight_record.md；发现的差异先记为假设，不直接判定根因
  ↓
Plugin 编排入口：集群执行就绪门禁
  ├─ EXECUTION_READY：条件齐备，可在用户批准实验矩阵后执行
  ├─ HANDOFF_READY：由用户执行，收到完整回传证据后继续
  ├─ OFFLINE_ONLY：只分析既有产物
  └─ EXECUTION_BLOCKED：停止新实验，转入证据不足复核
  ↓
Scope Reducer Agent（通用范围缩小方法）
  ├─ 设计单变量缩圈矩阵，缩小集群、模型和运行条件
  ├─ Plugin 编排入口对启动训练、改代码/配置、压测、较大 dump 等动作统一请求用户确认
  └─ 已是最小复现、用户拒绝或资源不足时，记录跳过/拒绝/阻塞，不伪造结果
  ↓
一个命中路由的 Symptom Diagnostic Agent
  ├─ E01/E02 → Numerical Mismatch Agent → model-train-precision-numerical-mismatch Skill
  ├─ E04     → Nonfinite Agent          → model-train-precision-nonfinite Skill
  ├─ E08     → Determinism Agent        → model-train-precision-determinism Skill
  ├─ unsupported → 不派发 Symptom Agent，记录范围外并交 Reviewer
  └─ 症状 Agent 共同行为
       ├─ 优先验证 Preflight 的单一差异；闭环后可直接进入 Reviewer
       ├─ 未闭环时执行症状专属采集、完整性/复现门禁与结果分析
       └─ 最小算子/通信脚本不复现时：记录反证 → Plugin 编排入口 → Scope Reducer → 原 Symptom Agent
  ↓
Reviewer Agent（只读独立复核）
  ├─ 核验记录、实验矩阵、执行/采集证据、dump 与分析完整性、回退及修复后复跑
  └─ 生成 final_report.md，按证据给出最高可支持的配置/环境/Node/Rank/Step/Module/API/Tensor 粒度结论
  ↓
Plugin 编排入口向用户交付结论、证据路径、风险与最小下一步

1. 减少错误路由

   明确 E04、E08、E01/E02 的优先级和证据前提，避免把传播后的 Loss NaN、重复运行不一致或无标杆偏差混入错误流程。

2. 建立可审计的证据链

   从 Intake、Preflight、Scope Reduction 到症状诊断和 Reviewer，统一记录实验变量、复现窗口、产物完整性、回退结果和结论可信度，区分：

   • verified root cause
   • strong candidate
   • insufficient evidence

3. 支持真实的大规模训练场景

   允许从集群症状逐步缩小到 Node、Rank、Step、Module/API/Tensor，同时约束多节点作业执行、产物汇集和分析门禁。

4. 控制 Dump 观察者效应

   Dump 完整不等于原症状仍然存在。只有执行证据完整、产物有效且插桩后症状复现，才能进入 compare 或 overflow_check。

5. 处理最小脚本不复现

   单算子负结果不会直接排除候选。流程可返回最后稳定复现的整网基线，通过单变量同步、串行下发、拓扑或模型剪裁继续缩圈。

6. 沉淀可复用能力

   三个症状 Skill 可独立复用；Plugin 负责角色分工、权限确认、状态流转和最终复核，符合渐进式披露原则。

Additional Information / 附加信息