ops-tune-workbench-plugin 0.0.0-stage → 0.0.1-beta.2

package/skills/tool-ops-tune/ops-verdict/references/io-contracts.md

@@ -0,0 +1,94 @@
+# 输入/输出数据契约（cases.csv / case_candidate / calibration_data）
+
+> 三个此前无 schema 的数据契约（检视 F21）：输入侧 cases.csv 只有「shape/dtype/attrs」
+> 一句话；输出侧 case_candidate.json / calibration_data.json 只在 Step 5 被点名要求
+> 产出。E 级回灌与校准回路（27 年两个核心回路）的输入格式由此定型，与现有 7 个
+> 数据契约同一写法（对齐 USAGE.md §5 契约表）。
+
+## 1. cases.csv（输入：测试用例清单）
+
+最小字段（带表头的一行一 case；多余列允许，逐 case 透传进报告）：
+
+| 列 | 必需 | 类型 | 说明 |
+|----|------|------|------|
+| `case_id` | ✅ | string | 全局唯一（报告逐 case 追溯的锚点） |
+| `shape` | ✅ | string | 如 `8448x4096`（多维用 x 分隔） |
+| `dtype` | ✅ | string | `fp16` / `fp32` / `bf16` / … |
+| `attrs` | — | string | 算子属性（如 `axis=-1,keepdim=true`；无属性留空） |
+| `ref_impl` | — | string | 标杆调用描述（P0-1 标杆双路径：非空时 collect_cases.py 该 case 跑 system 变体；如 `aclnnGelu` / `torch.nn.functional.gelu`） |
+
+```csv
+case_id,shape,dtype,attrs
+c01,8448x4096,fp16,
+c02,4096x4096,fp16,
+c03,1024x1024,bf16,axis=-1,keepdim=true
+```
+
+> >20 个 case 取前 20 并告知用户截断（A1 铁律）；截断必须发生在读入侧，
+> 不得静默丢弃。
+
+## 2. case_candidate.json（输出：E 级案例回灌条目）
+
+Step 5 产出，回灌 ops-mechanism 案例库的候选（经评审后入库）：
+
+| 字段 | 必需 | 说明 |
+|------|------|------|
+| `schema` | ✅ | `opstune.case-candidate/1.0` |
+| `operator` | ✅ | 算子名 |
+| `scene_fingerprint` | ✅ | 口径指纹（soc/shape/dtype/cann_version…，取自 scope.json） |
+| `bound_rule` | ✅ | 命中的 rule_id（证据绑定） |
+| `mechanism` | ✅ | 实施的机制名 |
+| `speedup_measured` | ✅ | 实测加速比（comparison.md 的 KEEP 轮） |
+| `speedup_est` | ✅ | 候选方案卡的预估值（校准对照） |
+| `precision` | ✅ | `pass`（fail 的轮次禁止产出条目） |
+| `rollback_happened` | ✅ | bool（是否有回滚；回滚原因写入 notes） |
+| `notes` | — | 适用边界 / 警示（如「仅 fp16 大 shape 验证」） |
+| `generated_at` | ✅ | ISO 8601 |
+
+```json
+{
+  "schema": "opstune.case-candidate/1.0",
+  "operator": "gelu",
+  "scene_fingerprint": {"soc": "a5", "shape": "8448x4096", "dtype": "fp16", "cann_version": "8.3.0"},
+  "bound_rule": "L1_VEC_BOUND",
+  "mechanism": "ub-fusion",
+  "speedup_measured": 1.53,
+  "speedup_est": [1.1, 1.3],
+  "precision": "pass",
+  "rollback_happened": false,
+  "notes": "cast-heavy 反证命中场景；仅 fp16 大 shape 验证",
+  "generated_at": "2026-10-14T12:00:00"
+}
+```
+
+## 3. calibration_data.json（输出：预估-实测校准对照）
+
+Step 5 产出，27-2 预估-实测校准回路的输入：
+
+| 字段 | 必需 | 说明 |
+|------|------|------|
+| `schema` | ✅ | `opstune.calibration/1.0` |
+| `operator` | ✅ | 算子名 |
+| `entries[]` | ✅ | 每轮一条：`mechanism` / `bound_rule` / `speedup_est`（区间）/ `speedup_measured` / `verdict`（KEEP/REVERT/噪声带内）/ `round` |
+| `generated_at` | ✅ | ISO 8601 |
+
+```json
+{
+  "schema": "opstune.calibration/1.0",
+  "operator": "gelu",
+  "entries": [
+    {"round": 1, "mechanism": "ub-fusion", "bound_rule": "L1_VEC_BOUND",
+     "speedup_est": [1.1, 1.3], "speedup_measured": 1.53, "verdict": "KEEP"},
+    {"round": 2, "mechanism": "mte2-preload", "bound_rule": "L1_MTE2_BOUND",
+     "speedup_est": [1.2, 2.0], "speedup_measured": 0.98, "verdict": "REVERT"}
+  ],
+  "generated_at": "2026-10-14T12:00:00"
+}
+```
+
+## 纪律
+
+- 三个契约的示例文件必须通过各自 schema 校验（jsonschema 或等价手工断言）；
+- `speedup_measured` 只能来自 delta_compare 的 KEEP 轮（噪声带内/REVERT/精度 fail
+  的数字禁止作为「实测收益」写入 case_candidate，但 REVERT 条目照常进 calibration
+  ——负样本是校准的输入）。

package/skills/tool-ops-tune/ops-verdict/references/rule-schema.md

@@ -0,0 +1,130 @@
+# 规则 Schema 规范（opstune.rules/1.0）
+
+> 规则是判定引擎的唯一知识形态。每条规则 = 触发条件（指标+阈值）+ 反证 + 置信度 + 机制路由，
+> 声明式 YAML 承载，`verdict.py` 解释执行。设计对标业界领先 GPU Profiling 工具 Guided Analysis 的
+> 「规则-Section 绑定契约 + REQUIRED/OPTIONAL 分级」，阈值取自真机调优实践标定。
+
+## 顶层字段
+
+```yaml
+schema: opstune.rules/1.0     # 固定
+layer: L1                     # L3 卡间 / L2 核间 / L1 单核 / L0 指令
+title: 单核流水判定
+soc: [a2, a3, a5]             # 适用芯片域（过滤语义：不含目标 soc 则整包跳过）
+requires_experiment:          # （可选）实验数据前置（如 MC² 隔离测试）
+  kind: isolation_test
+  outputs: [t_comm_us, t_compute_us, m_rows]
+metrics: { ... }              # 指标词汇表（见下）
+rules: [ ... ]                # 规则列表
+```
+
+## 指标词汇表（metrics）
+
+规则-指标绑定契约的解析层。**规则只能引用词汇表中声明过的指标**——未声明的引用在加载
+时应视为配置错误。
+
+```yaml
+metrics:
+  mte2_ratio:                       # 指标名（规则 condition 中引用）
+    source: pipe                    # pipe | scalar | derived
+    columns: [aic_mte2_ratio, aiv_mte2_ratio, ai_mte2_ratio, "Mte2Utilization(%)", ...]
+    normalize: ratio_to_pct         # 0~1.5 视为比例 ×100（双版本字段口径兼容）
+    group: pipe                     # 参与主导 pipe 排序与串行指纹求和
+  mte2_active_bw_pct_of_peak:
+    source: scalar                  # 由调用方 --scalar 提供
+  r_value:
+    source: derived                 # 引擎内置计算（如 R = T_compute/T_comm）
+```
+
+- `source: pipe`：从 PipeUtilization.csv 逐行取候选列（按序首个可解析者），per-row 取
+  aic/aiv 双列最大值，跨行算 mean/max 双统计。**判定用 mean，max 仅识别长尾**（单核峰值
+  不代表全 kernel —— 实测纪律）。
+- `source: scalar`：调用方提供（带宽百分比、物理核数、隔离测试值……）。缺失时引用它的
+  规则按 REQUIRED/OPTIONAL 语义处理。
+- `source: derived`：引擎衍生（`__max_pipe_mean`、`__pipe_sum_mean`、`__tail_ratio`、
+  `__imbalance_pct`、`__two_cluster_gap_pct`、`r_value`、`__mte2_pollution_gap`、
+  `dominant_time_us`、`__occupancy_pct`、`__head_overhead_pct` 等）。
+
+**加载校验（机制化，违规启动即 exit 3）**：`verdict.py` 加载规则包后强制校验——
+
+| # | 校验 | 说明 |
+|---|------|------|
+| V1 | 引用完整性 | condition / watch / counter_evidence / severity / metrics_required 引用的指标必须在词汇表或 derived 白名单内——**未声明的引用是配置错误**（不是运行时静默 unevaluated） |
+| V2 | 路由目标存在 | `routing.on_hit` 的 disable_rule 目标必须存在于规则宇宙（本次加载包 + 同目录其余规则包；disable 语义是跨包的） |
+| V3 | 区间无重叠 | 同一指标的多条档位类规则（如 L3 R 值五档）区间不得重叠——同一值双命中即矛盾 |
+| V4 | optional 语义 | **`metrics_optional` 仅用于反证；condition 中引用的指标必须 required**。引擎对 condition 内任何 None 一律 INSUFFICIENT_DATA（三值逻辑），不存在「可选指标缺失时跳过该叶子继续求值」的降级机制——把 optional 指标写进 condition 的规则永远无法 HIT |
+
+## 规则字段
+
+```yaml
+- id: L1_MTE2_BOUND                # 全局唯一（跨包路由引用，如 disable_rule）
+  name: MTE2 搬入瓶颈               # 人读名
+  priority: 10                      # 升序求值（数字小先评估）
+  parent: L1_MEMORY_SATURATION      # （预留）DAG 父节点，M2 启用权重传播
+  threshold_source: "[msprof-doc] >80% 直接判 / 最大且 >70%"
+  metrics_required: [mte2_ratio]            # 绑定契约：缺失 → SKIPPED（不触发不误报）
+  metrics_optional: [mte2_active_bw_pct_of_peak]  # 缺失 → 反证标 unevaluated；禁止进 condition（V4）
+  condition:                       # 触发条件（三值逻辑：True/False/None=证据不足）
+    any:
+      - {metric: mte2_ratio, agg: mean, op: gt, value: 80}
+      - all:
+          - {metric: mte2_ratio, agg: mean, op: gt, value: 70}
+          - {metric: mte2_ratio, agg: rank, op: eq, value: 1}   # rank=1 即「8 pipe 中占比最大」
+  watch:                           # 未达判定线的观察档（NOT_HIT 时提示）
+    condition: {metric: mte2_ratio, agg: mean, op: gt, value: 50}
+    note: MTE2 占比 50~70%，暂非主导，已具备搬运优化价值
+  severity:                        # 分档：critical / moderate / light
+    metric: mte2_ratio             # 按指标值分档（或 default: light）
+    bands: [{min: 85, level: critical, note: ...}, {min: 70, level: moderate}]
+    default: light
+  counter_evidence:                # 反证条目（防误判的第二道闸）
+    - id: true-bandwidth-saturation
+      condition: {metric: mte2_active_bw_pct_of_peak, agg: value, op: gt, value: 80}
+      note: active_bw 已达理论 80%+：真带宽饱和，优化方向是数据量/复用而非搬运组织
+      action: annotate             # annotate（记录）| reroute（改道机制，M2）
+  confidence: high                 # high / medium / low（规则级先验）
+  speedup_range: [1.2, 2.0]        # 预估加速比区间（机制路由排序依据；校准闭环回写）
+  speedup_source: "🟡 首期标定值"
+  mechanism_refs:                  # 机制路由入口（ops-mechanism 内文档路径）
+    - ops-mechanism:references/optimize/data-copy.md
+  routing:                         # （可选）命中副作用
+    on_hit: [disable_rule, L1_MTE2_BOUND]   # 禁用指定规则（跨包生效）
+    reroute_to: ops-mechanism:references/optimize/mc2.md
+```
+
+## 条件语义（三值逻辑）
+
+| 节点 | True | False | None（证据不足） |
+|------|------|-------|----------------|
+| `all: [...]` | 全部 True | 任一 False | 有 None 无 False |
+| `any: [...]` | 任一 True | 全部 False | 有 None 无 True |
+
+- **None 不冒充 False**：条件无法评估时规则置 `INSUFFICIENT_DATA` 并提示补采，绝不因
+  数据缺失而判「无 bound」。
+- `value` 支持复合引用：`{metric: time_mean_us, factor: 1.25}`（另一指标 × 系数）。
+- `op` 集合：`gt / gte / lt / lte / eq / between [lo,hi] / gt_ratio / lt_ratio`。
+
+## 路由副作用
+
+`routing.on_hit` 在命中时生效（按 priority 顺序，跨规则包传播）：
+
+- `disable_rule`：禁用后续同批规则 —— 用例：`L3_MTE2_POLLUTED` 命中后禁用
+  `L1_MTE2_BOUND`（MTE2 ratio 被通信等待污染，单核访存优化无效，改道通信掩盖策略）。
+- `reroute_to`：改写 finding 的机制路由目标（M2 启用 DAG 权重传播后扩展为 GLOBAL/LOCAL
+  加速比语义，对标 NCU 父子规则）。
+
+## 扩展流程（贡献一条新规则）
+
+1. 在对应层规则包 YAML 追加规则（阈值必须带 `threshold_source`；无来源实测支撑的标 🟡）。
+2. 在 `fixtures/` 造已知答案的输入（CSV 或标量），在 `evals/run_evals.py` 加断言用例
+   （正例 + 至少一个反例/边界）。
+3. `python3 evals/run_evals.py` 全绿 → 合入。
+4. 知识组评审：阈值来源、soc 适用域、反证完整性（缺反证的 BOUND 类规则不允许合入）。
+
+## 纪律（实测教训沉淀）
+
+- **判定只出自规则**：任何「看起来像 bound」但不在规则库中的结论，Agent 不得输出为判定，
+  只能作为 `INSUFFICIENT_DATA` 下的假设并注明缺失指标。
+- **阈值不可无源合入**：`threshold_source` 为空或 🟡 的规则在评审中降级为 watch 档。
+- **跨芯片域**：规则包 `soc` 过滤是硬边界；A2/A3/A5 阈值差异通过分包或（M2）规则内
+  soc 覆写承载，禁止静默复用。

package/skills/tool-ops-tune/ops-verdict/references/scope-schema.md

@@ -0,0 +1,61 @@
+# scope.json 契约（opstune.scope/1.0）
+
+> Phase 0「意图与边界」的输出载体，调优计划的口径真源。字段名与
+> `snapshot.py` / `delta_compare.py` 的 HARD_KEYS **严格同名同义**——口径互锁
+> （12 HARD + 2 机制变量）的上游真源，不同执行者生成的 scope.json 不再漂移。
+
+## 字段清单
+
+| 字段 | 来源 | 说明 |
+|------|------|------|
+| `schema` | 固定 | `opstune.scope/1.0` |
+| `operator` | Phase 0 | 算子名（人读） |
+| `op` | HARD | 与 snapshot `--op` 同义（口径指纹字段） |
+| `soc` | HARD | `a2` / `a3` / `a5` |
+| `mode` | HARD | `board` / `sim` |
+| `timing_method` | HARD | 五选一：`event` / `sim` / `msprof` / `msprof_task_duration` / `profiler_summary` |
+| `baseline_kind` | HARD | `system`（对标系统算子）/ `self_before_after`（自前后对比） |
+| `cann_version` | HARD | CANN 版本号 |
+| `device_id` | HARD | 采集设备 ID |
+| `shape` | HARD | 代表 case 的 shape |
+| `dtype` | HARD | 数据类型 |
+| `format` | HARD | `ND` / `NZ` / … |
+| `warmup` | HARD | 冷跑剔除轮数 |
+| `repeat` | HARD | 稳态采样轮数 |
+| `tiling_key` | 机制变量 | 优化本身可能改变（WARN 级记录） |
+| `block_dim` | 机制变量 | 同上 |
+| `scene` | Phase 0 | `single` / `mc2` / `fa` / `regression` / `qa`（场景分类判据见 task-prompts Step 0） |
+| `cases_csv` | 输入 | 测试用例文件路径 |
+| `code_dir` | 输入 | 算子源码目录 |
+| `performance_goal` | 输入 | 性能目标（可为 null） |
+| `max_rounds` | 输入 | 轮数上限 |
+| `precision_gate` | Phase 0 预检 | `{total, pass, fail, tolerance}`——fail≠0 禁止进入调优 |
+| `generated_at` | 生成时间 | ISO 8601 |
+
+## 最小示例
+
+```json
+{
+  "schema": "opstune.scope/1.0",
+  "operator": "gelu",
+  "op": "gelu", "soc": "a5", "mode": "board",
+  "timing_method": "event", "baseline_kind": "self_before_after",
+  "cann_version": "8.3.0", "device_id": "0",
+  "shape": "8448x4096", "dtype": "fp16", "format": "ND",
+  "warmup": 5, "repeat": 20,
+  "tiling_key": null, "block_dim": null,
+  "scene": "single",
+  "cases_csv": "cases/gelu_cases.csv",
+  "code_dir": "/path/to/gelu_project",
+  "performance_goal": "kernel_avg_us < 100",
+  "max_rounds": 1,
+  "precision_gate": {"total": 12, "pass": 12, "fail": 0, "tolerance": "工程现有 ut 容差"},
+  "generated_at": "2026-10-14T12:00:00"
+}
+```
+
+## 纪律
+
+- 12 HARD 字段与 `delta_compare.py` 的 `HARD_KEYS` 一一对应：任一变化必须重建基线
+  （跨口径比较禁令，A4 铁律）。
+- `precision_gate.fail != 0` 的 scope 禁止进入 Step 1（第一道精度门禁）。

package/skills/tool-ops-tune/ops-verdict/references/soc-spec.yaml

@@ -0,0 +1,140 @@
+# soc-spec.yaml — SoC 峰值标尺表（REVIEW2 G3 / 整改 P0-3）
+#
+# 目的：「还差多远」的客观标尺。MTE2 真假 bound 二分（data-copy.md 公式需要 GM 峰值
+# 带宽）与 NEAR_LIMIT 停止决策的第二证据源（距峰值 X% 读数）此前无可计算来源——本表补上。
+#
+# 溯源纪律（与规则包 threshold_source 同款）：
+#   [cann-ini]        本机 CANN 安装 platform_config/*.ini 静态配置（结构参数真源；
+#                     采集于 CANN 9.0.0 aarch64-linux，2026-10-15）
+#   [npu-arch-guide]  npu-arch SKILL 架构指南（算力公式推导 / 公开资料与经验值）
+#   [cann-bench]      cann-bench 仓 t_hw 模型元数据（950DT 4.1 / 950PR 1.65 TB/s 口径）
+#   [tuning-practice] 一线调优实践实测
+#   🟡                未实测标定（首期工程标定值）——判定引用时须在报告携带该标志
+#
+# 单位：gm_bw_gbps = GB/s；*_tflops = TFLOPS（FMA 计 2 FLOP）；容量 KB/MB/GB 二进制口径。
+# 消费方：
+#   verdict.py --soc-spec        active_bw 占峰值换算（反证标量）+ 距峰值读数
+#   facts_bridge.py（ops-collect）峰值换算（mte2_active_bw_pct_of_peak 等）
+#   tiling_candidates.py（ops-family）核数 / UB / L1 / L0 容量约束
+# 使用规则：reference 为判定默认值；调用方知道实际 SKU 时应从 skus 解析精确值
+#   （npu-smi 型号 → skus.sku 匹配）。本表不搬用其他工具的 910B 峰值表（训练卡口径
+#   来源不同，数值仅作交叉验证：910B3 fp16 294.91 与本表公式推导一致）。
+schema: opstune.soc-spec/1.0
+
+socs:
+  a2:
+    name: Ascend910B（Atlas A2 训练/推理）
+    arch: DAV_2201
+    skus:   # 调用方按实际 SKU 解析；reference 为典型口径
+      - {sku: Ascend910B1, ai_core_cnt: 24, vector_core_cnt: 48, freq_mhz: 1850, cube_fp16_tflops: 363.8, l2_mb: 192, memory_gb: 64, source: "[cann-ini] Ascend910B1.ini"}
+      - {sku: Ascend910B2, ai_core_cnt: 24, vector_core_cnt: 48, freq_mhz: 1800, cube_fp16_tflops: 353.9, l2_mb: 192, memory_gb: 64, source: "[cann-ini] Ascend910B2.ini"}
+      - {sku: Ascend910B2C, ai_core_cnt: 24, vector_core_cnt: 48, freq_mhz: 1800, cube_fp16_tflops: 353.9, l2_mb: 192, memory_gb: null, source: "[cann-ini] Ascend910B2C.ini"}
+      - {sku: Ascend910B3, ai_core_cnt: 20, vector_core_cnt: 40, freq_mhz: 1800, cube_fp16_tflops: 294.9, l2_mb: 192, memory_gb: 64, source: "[cann-ini] Ascend910B3.ini（本仓开发机实测设备，npu-smi 25.5.0）"}
+      - {sku: Ascend910B4, ai_core_cnt: 20, vector_core_cnt: 40, freq_mhz: 1500, cube_fp16_tflops: 245.8, l2_mb: 96, memory_gb: 32, source: "[cann-ini] Ascend910B4.ini"}
+    buffer:                      # 同架构子型号一致 [cann-ini]
+      l1_kb: 512
+      l0a_kb: 64
+      l0b_kb: 64
+      l0c_kb: 128
+      ub_kb: 192
+      bt_kb: 1
+    sparsity_42: true            # [cann-ini] sparsity=1（支持 4:2 稀疏）
+    reference:                   # 判定默认参考值（典型口径 = 910B2）
+      ai_core_cnt: {value: 24, source: "[cann-ini] B1/B2；B3/B4 为 20（按 skus 解析实际值）"}
+      vector_core_cnt: {value: 48, source: "[cann-ini] B1/B2；B3/B4 为 40"}
+      gm_bw_gbps:
+        value: 1600
+        source: "[npu-arch-guide] 公开资料/经验值"
+        verified: false
+        note: "🟡 未实测标定；上板标定后回写。与 [cann-bench] 的 950PR 读带宽 1.65 TB/s
+               属不同芯片，未互证"
+      cube_peak_tflops:
+        fp16: {value: 353.9, source: "[npu-arch-guide] 4096×24×1800×2/1e6"}
+        bf16: {value: 353.9, source: "[npu-arch-guide] Cube bf16 与 fp16 同速率"}
+        int8: {value: 707.8, source: "[cann-ini DtypeMKN 16,32,16] = fp16 × 2"}
+        int4: {value: 1415.6, source: "[cann-ini DtypeMKN 16,64,16] = fp16 × 4"}
+        fp32: {value: null, note: "HF32 通路速率未标定 🟡"}
+        fp8: {value: null, note: "A2 不支持"}
+      vector_peak_tflops:
+        fp16: {value: 22, source: "[npu-arch-guide] 🟡 公开资料/经验值", verified: false}
+        fp32: {value: null, note: "未标定 🟡"}
+      head_overhead_us:
+        value: 21
+        source: "[tuning-practice] A2 满核头开销 ~20-21us 实测"
+    derived_formula:
+      cube_fp16_tflops: "4096 × ai_core_cnt × freq_mhz × 2 / 1e6"
+
+  a3:
+    name: Ascend910_93（Atlas A3 训练/推理）
+    arch: DAV_2201
+    note: 与 a2 同为 DAV_2201——buffer / DtypeMKN / 峰值公式与 a2 一致；差异在 SKU 裁剪。
+    skus:
+      - {sku: Ascend910_9362, ai_core_cnt: 20, vector_core_cnt: 40, freq_mhz: 1500, cube_fp16_tflops: 245.8, l2_mb: 168, memory_gb: null, source: "[cann-ini] Ascend910_9362.ini"}
+      - {sku: Ascend910_9372, ai_core_cnt: 20, vector_core_cnt: 40, freq_mhz: 1800, cube_fp16_tflops: 294.9, l2_mb: 192, memory_gb: null, source: "[cann-ini] Ascend910_9372.ini"}
+      - {sku: Ascend910_9381, ai_core_cnt: 24, vector_core_cnt: 48, freq_mhz: 1800, cube_fp16_tflops: 353.9, l2_mb: 192, memory_gb: 64, source: "[cann-ini] Ascend910_9381.ini"}
+      - {sku: Ascend910_9382, ai_core_cnt: 24, vector_core_cnt: 48, freq_mhz: 1800, cube_fp16_tflops: 353.9, l2_mb: 192, memory_gb: null, source: "[cann-ini] Ascend910_9382.ini"}
+      - {sku: Ascend910_9391, ai_core_cnt: 24, vector_core_cnt: 48, freq_mhz: 1850, cube_fp16_tflops: 363.8, l2_mb: 192, memory_gb: 64, source: "[cann-ini] Ascend910_9391.ini"}
+      - {sku: Ascend910_9392, ai_core_cnt: 24, vector_core_cnt: 48, freq_mhz: 1850, cube_fp16_tflops: 363.8, l2_mb: 192, memory_gb: null, source: "[cann-ini] Ascend910_9392.ini"}
+    buffer: {l1_kb: 512, l0a_kb: 64, l0b_kb: 64, l0c_kb: 128, ub_kb: 192, bt_kb: 1}
+    sparsity_42: true
+    reference:
+      ai_core_cnt: {value: 24, source: "[cann-ini] 典型 SKU（93_81/82）；20 核变体见 skus"}
+      vector_core_cnt: {value: 48, source: "[cann-ini] 同上"}
+      gm_bw_gbps:
+        value: 1600
+        source: "沿用 a2 参考值（同 DAV_2201）"
+        verified: false
+        note: "🟡 未单独标定——a3 与 a2 结构同源，暂共用标尺；上板标定后独立回写"
+      cube_peak_tflops:
+        fp16: {value: 353.9, source: "[npu-arch-guide] 4096×24×1800×2/1e6（典型 24 核 @1800）"}
+        bf16: {value: 353.9, source: "同 fp16"}
+        int8: {value: 707.8, source: "[cann-ini DtypeMKN] fp16 × 2"}
+        int4: {value: 1415.6, source: "[cann-ini DtypeMKN] fp16 × 4"}
+        fp32: {value: null, note: "HF32 未标定 🟡"}
+        fp8: {value: null, note: "A3 不支持"}
+      vector_peak_tflops:
+        fp16: {value: 22, source: "[npu-arch-guide] 🟡（同 a2 口径）", verified: false}
+      head_overhead_us: {value: 21, source: "[tuning-practice] 同 a2 口径（未单独标定 🟡）"}
+    derived_formula:
+      cube_fp16_tflops: "4096 × ai_core_cnt × freq_mhz × 2 / 1e6"
+
+  a5:
+    name: Ascend950（Atlas A5：950DT 训练 / 950PR 推理）
+    arch: DAV_3510
+    skus:
+      - {sku: Ascend950PR_957b, ai_core_cnt: 28, vector_core_cnt: 56, freq_mhz: 1650, cube_fp16_tflops: 378.5, l2_mb: 112, memory_gb: 112, source: "[cann-ini] Ascend950PR_957b.ini（PCIE 典型）"}
+      - {sku: Ascend950PR_9589, ai_core_cnt: 32, vector_core_cnt: 64, freq_mhz: 1650, cube_fp16_tflops: 432.5, l2_mb: 128, memory_gb: 128, source: "[cann-ini] Ascend950PR_9589.ini（Server 典型）"}
+      - {sku: Ascend950PR_9599, ai_core_cnt: 36, vector_core_cnt: 72, freq_mhz: 1800, cube_fp16_tflops: 530.8, l2_mb: 128, memory_gb: 128, source: "[cann-ini] Ascend950PR_9599.ini"}
+      - {sku: Ascend950DT_950x, ai_core_cnt: 8, vector_core_cnt: 16, freq_mhz: 1650, cube_fp16_tflops: 108.1, l2_mb: 32, memory_gb: 24, source: "[cann-ini] Ascend950DT_950x.ini（Decode 卡）"}
+    buffer:                      # 同架构子型号一致 [cann-ini]
+      l1_kb: 512
+      l0a_kb: 64
+      l0b_kb: 64
+      l0c_kb: 256
+      ub_kb: 248
+      bt_kb: 4
+    sparsity_42: false           # [cann-ini] sparsity=0（不再支持 4:2）
+    reference:                   # 判定默认参考值（典型口径 = 950PR PCIE 957b）
+      ai_core_cnt: {value: 28, source: "[cann-ini] 957b；Server 9589 为 32 / 9599 为 36（按 skus 解析）"}
+      vector_core_cnt: {value: 56, source: "[cann-ini] 957b；9589 为 64 / 9599 为 72"}
+      gm_bw_gbps:
+        value: 1400
+        source: "[npu-arch-guide] 950PR PCIE 公开资料/经验值"
+        verified: false
+        note: "🟡 未实测标定。[cann-bench] t_hw 模型采用 1.65 TB/s（读带宽口径）、950DT
+               4.1 TB/s——两源未对齐，本表取保守值 1400；上板标定后回写。
+               勘误：L2 规则包旧注释「A5 约 48 AIV/28 AIC」与 ini 不符
+               （957b 实为 56 AIV / 28 AIC），以本表为准"
+      cube_peak_tflops:
+        fp16: {value: 378.5, source: "[npu-arch-guide] 4096×28×1650×2/1e6"}
+        bf16: {value: 378.5, source: "同 fp16"}
+        int8: {value: 757.0, source: "[cann-ini DtypeMKN 16,32,16] = fp16 × 2"}
+        fp8: {value: 757.0, source: "[cann-ini DtypeMKN DT_FLOAT8_E4M3FN 16,32,16] = fp16 × 2"}
+        mxfp4: {value: 1514.0, source: "[npu-arch-guide] Server 口径比例（= fp16 × 4）🟡"}
+        fp32: {value: null, note: "HF32 通路未标定 🟡"}
+      vector_peak_tflops:
+        fp16: {value: 47, source: "[npu-arch-guide] 950PR PCIE 🟡 公开资料/经验值（基准 23.7T × 双发 2）", verified: false}
+        fp32: {value: null, note: "未标定 🟡"}
+      head_overhead_us: {value: null, note: "A5 头开销参考值未实测标定 🟡（待首个真实调优沉淀）"}
+    derived_formula:
+      cube_fp16_tflops: "4096 × ai_core_cnt × freq_mhz × 2 / 1e6"

package/skills/tool-ops-tune/ops-verdict/rules/L0-instruction.yaml

@@ -0,0 +1,67 @@
+# L0 指令/源码层判定规则包：PC 采样 stall 枚举（A5 PcSampling / 仿真）
+#
+# 阈值来源：
+#   [tuning-practice] 无 Roofline 产物时不得推断 Roofline Bound
+#   [msprof-doc]     icache_miss_rate >15% 需关注（msprof 官方文档口径）
+# M2 阶段扩展：SIMT/VF 档（divergence_stack_spill / register_bank_conflict / warp_level_sync）
+schema: opstune.rules/1.0
+layer: L0
+title: 指令级判定（PC 采样 / 仿真）
+soc: [a2, a3, a5]
+
+metrics:
+  icache_miss_rate:
+    source: scalar
+    description: ICache 缺失率（PipeUtilization ai*_icache_miss_rate）
+  top_stall_pct:
+    source: scalar
+    description: PC 采样 top stall 枚举占比
+  l2_hit_rate:
+    source: scalar
+    description: L2Cache.csv ai*_total_hit_rate(%)
+
+rules:
+  - id: L0_ICACHE_MISS
+    name: ICache 缺失率高
+    priority: 10
+    threshold_source: "[msprof-doc] >15% 需关注"
+    metrics_required: [icache_miss_rate]
+    metrics_optional: []
+    condition: {metric: icache_miss_rate, agg: value, op: gt, value: 15}
+    severity: {default: moderate}
+    confidence: medium
+    speedup_range: [1.0, 1.1]
+    speedup_source: 🟡 首期标定值
+    mechanism_refs:
+      - ops-mechanism:references/optimize/api-usage.md
+
+  - id: L0_L2_LOW_HIT
+    name: L2 命中率低
+    priority: 20
+    threshold_source: "[tuning-practice] ai*_total_hit_rate <50%"
+    metrics_required: [l2_hit_rate]
+    metrics_optional: []
+    condition:
+      all:
+        - {metric: l2_hit_rate, agg: value, op: gte, value: 0}
+        - {metric: l2_hit_rate, agg: value, op: lt, value: 50}
+    severity: {default: moderate}
+    confidence: medium
+    speedup_range: [1.1, 1.4]
+    speedup_source: "[tuning-practice] L2 CacheMode 方法，🟡 待校准"
+    mechanism_refs:
+      - ops-mechanism:references/optimize/memory-hierarchy.md
+
+  - id: L0_STALL_DOMINANT
+    name: stall 主因枚举（占位，M2 启用）
+    priority: 30
+    threshold_source: 🟡 PcSampling 字段口径 M1 末期标定
+    metrics_required: [top_stall_pct]
+    metrics_optional: []
+    condition: {metric: top_stall_pct, agg: value, op: gt, value: 40}
+    severity: {default: moderate}
+    confidence: low
+    speedup_range: [1.0, 1.2]
+    speedup_source: 🟡 待标定
+    mechanism_refs:
+      - ops-mechanism:references/optimize/pipeline.md