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

package/skills/tool-ops-tune/docs//347/237/245/350/257/206/345/272/223/350/247/204/350/214/203.md

@@ -0,0 +1,103 @@
+# 知识库规范（tool-ops-tune 知识分类与标准化说明）
+
+> 本文档是套件内全部知识资产的分类标准与入库契约：知识分几类、每类怎么组织、
+> 入库门槛是什么、如何被路由到。配套 schema 细则见 `ops-verdict/references/`
+> 下三份契约文档（rule-schema / io-contracts / scope-schema）。
+> **公共纪律**：新增知识必须先声明路由入口（机制卡索引 / 族分类表 /
+> mechanism_refs）——无入口的知识不可被路由到，等于不存在；「暂未收录」
+> 显式返回并计数（缺口感知回路输入），禁止静默空结果。
+
+## 1. 知识分类（按消费时机与形态）
+
+| 类别 | 形态 | 落点 | 消费时机 | 交付状态 |
+|------|------|------|---------|---------|
+| K1 判定规则 | YAML 规则包（脚本求值） | ops-verdict/rules/ | Phase 2 判定 | ✅ L0-L3 四包 24 条 |
+| K2 优化机制卡 | 机制卡（固定八要素） | ops-mechanism/references/optimize/ | Phase 3 判定后路由 | 🟡 随优化卡片 PR |
+| K3 算子族与模板 | A/B 双型文档 + 代码模板 | ops-family/references/<族>/ | Phase 3-4 实施时 | 🟡 随算子族 PR |
+| K4 案例证据 | 案例卡（A-E 证据分级） | ops-mechanism/cases/ | Phase 3 同型检索 | 🟡 随优化卡片 PR |
+| K5 外部知识引用 | 引用清单 + 版本锁定（不落副本） | 规划中 adapters/ | 需要事实时运行时探测 | 🟡 框架期落地 |
+
+**K1-K4 与 K5 的分界**：经验性知识（指标→瓶颈→机制因果，不随 API 演进失效）自建沉淀；
+事实性知识（芯片参数 / API 签名 / 官方示例 / 理论标尺，随芯片代际演进）一律引用
+CANN 生态真源（devkit 文档 / cann-bench metadata / 官方算子仓），本仓只存引用清单
+与版本锁定——运行时探测优先（`GetCurNpuArch()` / `GetCoreNumA*` / 本机 `--help`）。
+
+## 2. K1 判定规则：书写规范
+
+规则 = 数据不是代码。新规则 = 一个 YAML 条目 + fixture + 断言用例，零引擎代码改动。
+
+**必填要素**（完整 schema 见 `ops-verdict/references/rule-schema.md`）：
+
+| 要素 | 要求 |
+|------|------|
+| `id` / `layer` / `priority` | 全局唯一（跨包路由引用）；layer ∈ L0-L3；priority 升序求值 |
+| `soc: [a2, a3, a5]` | 芯片域硬过滤；跨芯片阈值差异禁止静默复用 |
+| `metrics_required` / `metrics_optional` | 绑定契约：REQUIRED 缺失 → SKIPPED（未采集不判定）；OPTIONAL 缺失 → 降级（反证标 unevaluated） |
+| `condition` | any/all 递归三值逻辑（None=证据不足 → INSUFFICIENT_DATA，不冒充「无 bound」） |
+| `threshold_source` | 每条阈值可溯源：`[msprof-doc]`（官方文档口径）/ `[tuning-practice]`（实践实测）/ `[mc2-practice]`（多卡实测）/ 🟡（首期标定值）；**无来源合入评审降级 watch 档** |
+| `counter_evidence` | **BOUND 类规则必须带反证条目**（防误判第二道闸），否则不允许合入 |
+| `severity` bands / `confidence` / `speedup_range` | 分档 + 置信度 + 预估收益区间（校准闭环回写） |
+| `mechanism_refs` | 机制路由入口（判定→机制契约）；指向 ops-mechanism 卡片路径 |
+| `routing.on_hit` | （可选）路由副作用：命中后禁用其它规则/改道机制路由，跨规则包传播 |
+
+**合入门槛**：`threshold_source` 必填（无实测来源标 🟡）+ fixture 已知答案输入 +
+断言用例（正例 + 至少一个反例/边界）+ 回归全绿。
+
+## 3. K2 优化机制卡：固定八要素
+
+| 要素 | 说明 |
+|------|------|
+| 原理 | 为什么这个机制能消除该瓶颈（硬件层因果链） |
+| 适用前提 | 判定证据特征（对应 rule_id + 指标窗口）；架构/容量约束（L1/L0/UB 预算） |
+| 预期收益 | speedup_range + 可行性系数（校准闭环回写） |
+| 架构限制 | soc 适用域、代际差异（A2/A3/A5 分支） |
+| 精度风险 | 语义保持类 / 语义变更类分级；语义变更必须写额外验证用例 |
+| 验证命令 | 精度全量 + 同口径性能的具体命令形态 |
+| 回滚条件 | 劣化/噪声带/精度失败的处置路径 |
+| 模板资产 | 可拷贝代码模板路径（对接 ops-family）或「无货架参考」标注 |
+
+**合入门槛**：八要素写全 + 挂到对应规则的 `mechanism_refs`（rule_id 索引表同步）+
+收益区间无实测来源时标 🟡 + 评审通过。
+
+## 4. K4 案例卡：字段与 A-E 证据分级
+
+固定字段：`算子类别 / DSL / 类型（PR|非PR）/ 来源可信度 / 来源链接 + 验证日期 /
+瓶颈证据（rule_id 对应）/ 优化机制 / 原文性能数字 / 适用范围与警示`。
+
+| 等级 | 来源 | 可写入 | 禁止 |
+|------|------|--------|------|
+| A | 官方已合并 PR/MR，含测试表 | 机制、适用平台、原文数字、精度结果 | 把某 shape 收益泛化到全场景 |
+| B | 官方 PR/MR，无数字 | 代码机制、文件路径、平台分支 | 推算或补写加速比 |
+| C | 官方 Wiki/指南/sample | 推荐流程、可运行案例、原文数字 | 把教程数字当目标设备峰值 |
+| D | 社区/二手材料 | 仅作线索与背景，明确警示 | 作为唯一验收证据 |
+| E | 本工作流实测回灌 | 机制可信度等同 A；speedup 绑定口径指纹 | 外推到其他口径 |
+
+**检索纪律**：最多取 3 个同型案例；PR 未公开数字统一写「原文未附量化数字」；
+**反例与收益案例同等收录**（警示列必填）；无同型案例走降级策略（证据链 + 机制卡
+驱动、实施细节自行推导并提高验证强度、报告标注「无同型案例」、沉淀 E 级候选）。
+
+## 5. K3 算子族与模板：入库要求
+
+- 建族目录 `ops-family/references/<family>/` → 判 A 型（单实现调参）或 B 型
+  （多实现选型，必须含选型决策树）→ guide + 模板链路 → 族分类表更新；
+- 模板（.h/.cpp/.template）抄自官方示例的标来源与许可证头；**查到模板必须直接
+  拷贝 + 最小适配，禁止参考重写**（模板优先纪律 T1-T5，编排层同款）；
+- 更新策略：追上游引用重拷（上游变了 → 重新评估拷贝版本），不在本仓独立分叉；
+- 资产计数防漂移：族表模板数与实际文件数的一致性由静态断言守护（随测试框架 PR
+  挂 CI）。
+
+## 6. 知识缺口计数（缺口感知回路输入）
+
+任何子域遇到「暂未收录」必须显式返回并落盘计数（`ops-family/references/
+knowledge_gaps.json` 形态，随算子族 PR 交付），禁止静默空结果——缺口数据是
+后续知识排产的唯一依据。
+
+## 7. 阈值变更流程（全类别公共）
+
+```
+改 YAML/机制卡 → 回归全绿 → 阈值带来源标注 → 人审 → 合入
+```
+
+- 无来源合入评审降级 watch 档；缺反证的 BOUND 类规则不允许合入；
+- 自进化回路（案例回流 / 校准闭环 / 阈值进化 / 缺口感知）只产生建议不直接生效；
+  证据分级不可逆（E 级不覆盖官方 A 级）；数据脱敏；基线库版本化。

package/skills/tool-ops-tune/evals/evals.json

@@ -0,0 +1,242 @@
+{
+  "skill_name": "tool-ops-tune",
+  "eval_mode": "text",
+  "evals": [
+    {
+      "id": 1,
+      "title": "verdict-entry-routing",
+      "prompt": "我有一份 msprof 导出的 PipeUtilization.csv，想知道这个算子的瓶颈是什么，帮我判定。",
+      "expected_output": "应加载 tool-ops-tune 套件并路由到 ops-verdict 判定引擎：说明判定只出自脚本（LLM 只解释不判定），引导使用 ops-verdict/scripts/verdict.py 以规则包 + CSV 输入产出 verdict.json 判定书；判定书每条命中带证据数值、阈值溯源、反证评估与机制路由。不凭经验直接给出瓶颈结论。",
+      "expectations": [
+        {
+          "type": "contains",
+          "pattern": "verdict",
+          "description": "路由到判定引擎入口"
+        },
+        {
+          "type": "contains",
+          "pattern": "规则",
+          "description": "说明按规则包判定"
+        },
+        {
+          "type": "contains",
+          "pattern": "证据",
+          "description": "强调判定带证据可审计"
+        },
+        {
+          "type": "not_contains",
+          "pattern": "我猜测",
+          "description": "不凭空猜测瓶颈"
+        },
+        {
+          "type": "skill_activated",
+          "pattern": "tool-ops-tune",
+          "description": "确认激活算子调优套件"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "title": "collect-mode-routing",
+      "prompt": "我要给一个 fork 多进程绑卡的 MC² 融合算子做性能采集，应该用什么命令？",
+      "expected_output": "路由到 ops-collect 采集编排：MC²/fork 多 rank 场景必须走 collect_board.sh --mode mc2（msprof --aic-mode=task-based），禁止 msprof op（对 fork 行为未定义、数据不可靠）；已有 collection_manifest.json 的目录禁止重复采集；MC² 禁 host 侧计时，性能数据出自 op_summary 的 Task Duration。",
+      "expectations": [
+        {
+          "type": "contains",
+          "pattern": "mc2",
+          "description": "给出 MC² 专用采集模式"
+        },
+        {
+          "type": "contains",
+          "pattern": "task-based",
+          "description": "说明 msprof task-based 强制"
+        },
+        {
+          "type": "contains",
+          "pattern": "manifest",
+          "description": "提及采集契约与防重采"
+        },
+        {
+          "type": "not_contains",
+          "pattern": "msprof op 采集",
+          "description": "不推荐对 fork 程序用 msprof op"
+        },
+        {
+          "type": "skill_activated",
+          "pattern": "tool-ops-tune",
+          "description": "确认激活算子调优套件"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "title": "verdict-before-mechanism-discipline",
+      "prompt": "还没做性能采集，你先看看优化机制文档，猜一下我的算子可能是什么瓶颈？",
+      "expected_output": "拒绝在无证据时猜测瓶颈：证据先行是套件纪律——判定之前禁止加载机制卡/案例猜瓶颈。正确路径是先采集（ops-collect 模式路由）再判定（verdict.py 规则求值），判定书 findings 的 mechanism_refs 才是机制路由入口。条件三值逻辑下数据不足只会得到 INSUFFICIENT_DATA，不会冒充结论。",
+      "expectations": [
+        {
+          "type": "contains",
+          "pattern": "证据",
+          "description": "强调证据先行"
+        },
+        {
+          "type": "contains",
+          "pattern": "先采集",
+          "description": "给出正确路径：先采集再判定"
+        },
+        {
+          "type": "contains",
+          "pattern": "机制",
+          "description": "说明机制卡判定后才加载"
+        },
+        {
+          "type": "not_contains",
+          "pattern": "可能是 MTE2",
+          "description": "不给出猜测性瓶颈结论"
+        },
+        {
+          "type": "skill_activated",
+          "pattern": "tool-ops-tune",
+          "description": "确认激活算子调优套件"
+        }
+      ]
+    },
+    {
+      "id": 4,
+      "title": "comparison-gate-semantics",
+      "prompt": "优化后性能从 100us 提升到 97us，快 3%，这轮优化应该 KEEP 吧？",
+      "expected_output": "3% 在 ±5% 噪声带内：不判收益也不判劣化，处置是 repeat 翻倍复测（同步重采基线与优化侧、重建两侧快照后再比）；仍带内则按无稳定收益处置。不得把噪声带内的变化当收益宣称——这是口径铁律。且任何比较前 delta_compare 会做口径与精度双门禁（不一致 exit 2）。",
+      "expectations": [
+        {
+          "type": "contains",
+          "pattern": "噪声带",
+          "description": "识别 3% 在 ±5% 带内"
+        },
+        {
+          "type": "contains",
+          "pattern": "复测",
+          "description": "给出 repeat 翻倍复测处置"
+        },
+        {
+          "type": "contains",
+          "pattern": "不",
+          "description": "明确不判收益"
+        },
+        {
+          "type": "not_contains",
+          "pattern": "建议保留",
+          "description": "不直接建议 KEEP"
+        },
+        {
+          "type": "skill_activated",
+          "pattern": "tool-ops-tune",
+          "description": "确认激活算子调优套件"
+        }
+      ]
+    },
+    {
+      "id": 5,
+      "title": "insufficient-data-honesty",
+      "prompt": "verdict.json 显示 verdict 是 INSUFFICIENT_DATA，全部规则 SKIPPED，这说明我的算子没有瓶颈吗？",
+      "expected_output": "不是。INSUFFICIENT_DATA 表示指标未采齐（绑定契约：REQUIRED 缺失 → SKIPPED，未采集不判定），不是「无瓶颈」。应按 skipped[].missing 列表补采（≤2 轮），仍缺则如实上报禁止猜测式判定。NO_BOUND_FOUND 才是数据完整但无命中的语义。",
+      "expectations": [
+        {
+          "type": "contains",
+          "pattern": "不是",
+          "description": "纠正「无瓶颈」误读"
+        },
+        {
+          "type": "contains",
+          "pattern": "补采",
+          "description": "给出按 missing 补采的路径"
+        },
+        {
+          "type": "contains",
+          "pattern": "SKIPPED",
+          "description": "解释绑定契约语义"
+        },
+        {
+          "type": "not_contains",
+          "pattern": "没有瓶颈",
+          "description": "不确认错误结论"
+        },
+        {
+          "type": "skill_activated",
+          "pattern": "tool-ops-tune",
+          "description": "确认激活算子调优套件"
+        }
+      ]
+    },
+    {
+      "id": 6,
+      "title": "single-mechanism-iron-law",
+      "prompt": "为了节省时间，这一轮能不能同时改双缓冲和 tiling 切分两个优化？",
+      "expected_output": "不能：单变量铁律——每轮只改一个可归因机制，多机制混入导致收益无法归因（KEEP 了无法归因的收益）。diff_audit 机器闸门会比对实际改动与方案卡声明范围，超范围判 UNATTRIBUTABLE 禁止进 KEEP 仲裁。两机制应分两轮，各自对照同口径基线。",
+      "expectations": [
+        {
+          "type": "contains",
+          "pattern": "单变量",
+          "description": "引用单变量铁律"
+        },
+        {
+          "type": "contains",
+          "pattern": "归因",
+          "description": "说明归因失效原因"
+        },
+        {
+          "type": "contains",
+          "pattern": "diff_audit",
+          "description": "提及机器闸门"
+        },
+        {
+          "type": "not_contains",
+          "pattern": "可以同时",
+          "description": "不允许多机制并行"
+        },
+        {
+          "type": "skill_activated",
+          "pattern": "tool-ops-tune",
+          "description": "确认激活算子调优套件"
+        }
+      ]
+    },
+    {
+      "id": 7,
+      "title": "npucompute-rep-db-channel-routing",
+      "prompt": "我有一份 npu-compute 采集的 .npu-rep 报告（950 平台），想直接接入调优判定，应该怎么消费？",
+      "expected_output": "路由到 ops-collect 的 npu-compute DB 格式通道（Roadmap #4）：.npu-rep 是单文件结构化报告，解包后含 7 个 Section CSV、Summary.jsonl 与 summary.db（SQLite：Section 表 + PcSampling + FieldUnitMap）。消费链为 facts_bridge.py --source auto（DB SQL 优先 AVG+NULL-skip 下推、Summary.jsonl OpInfoSummary 产出 task_duration/block_dim、PcSampling 产出 top_stall_pct——L0_STALL_DOMINANT 的首个生产者）→ verdict.py --db summary.db（FieldUnitMap 自动还原列名）。旧版无 summary.db 的报告可用 csv_to_db.py 升级；性能收益与双通道等价性用 db_bench.py 验证（等价性是门禁，提速比按负载如实呈现）。",
+      "expectations": [
+        {
+          "type": "contains",
+          "pattern": "npu-compute",
+          "description": "识别 npu-compute 报告形态"
+        },
+        {
+          "type": "contains",
+          "pattern": "summary.db",
+          "description": "路由到 DB 格式通道"
+        },
+        {
+          "type": "contains",
+          "pattern": "facts_bridge",
+          "description": "标量生产走 facts_bridge DB 通道"
+        },
+        {
+          "type": "contains",
+          "pattern": "top_stall",
+          "description": "PcSampling → top_stall_pct 生产者"
+        },
+        {
+          "type": "not_contains",
+          "pattern": "逐个手算",
+          "description": "不让 LLM 手工解析 CSV/SQL"
+        },
+        {
+          "type": "skill_activated",
+          "pattern": "tool-ops-tune",
+          "description": "确认激活算子调优套件"
+        }
+      ]
+    }
+  ]
+}

package/skills/tool-ops-tune/ops-collect/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: ops-collect
+description: NPU 性能采集编排。统一采集入口：上板（msprof 7 组指标 / npu-compute DB 格式 / quick / MC² task-based 多 rank）、MC² 隔离测试编排（T_comm/T_compute → R 值）、采集块 manifest 契约（已有 manifest 禁止重复采集）。负责把「能采但采不到」变成「按路由采对」，并保证采集产物可直接喂 ops-verdict 判定引擎。触发：性能采集、profiling、基线数据采集、MC² 采集、隔离测试、补采指标时使用。
+---
+
+# 性能采集编排（collect）
+
+> 采集的职责边界：只负责「采对、采全、口径留痕」，不做判定（ops-verdict）、不做解释
+>（ops-mechanism）。底层工具全部复用本仓/官方（msprof / msprof op / msopprof /
+> npu-compute / cannsim），本 SKILL 不重做采集器，只做模式路由与契约落盘。
+
+## 采集模式路由（先探测本机帮助，再选命令）
+
+```
+用户输入（可执行文件 + 用例）
+  │
+  ├─ MC² / fork 多 rank 算子？（fork 多子进程绑卡 + SHMEM UDMA / BarrierAll / CrossCoreFlag）
+  │    ├─ 是 → collect_board.sh --mode mc2
+  │    │        msprof --aic-mode=task-based（msprof op 对 fork 行为未定义，数据不可靠，禁用）
+  │    │        MC² 调优另需隔离测试 → isolation_test.py（T_comm/T_compute → R）
+  └─ 否 → 单卡路径
+       ├─ 950/A5 且本机 npu-compute --list-sets 可用
+       │     → collect_board.sh --mode npu-compute（DB 格式采集，Roadmap #4：
+       │        .npu-rep 单文件报告含 7 Section CSV + summary.db；PmSampling 等
+       │        Section 以 --sections 追加，本机 --list-sections 为门禁）
+       ├─ 本机 msprof op --help 可用 → msprof op 采集（含 Roofline/KernelScale 等能力按本机帮助）
+       └─ 仅 msprof 可用 → collect_board.sh --mode standard（7 组 aic-metrics 顺序采集）
+  │
+  └─ 无 NPU / 需指令级 → cannsim 仿真路径（A5 单卡 AI Core；MC²/HCCL 不支持）
+```
+
+三条硬规则：
+
+1. **先探测再选命令**：所有可选参数以本机 `--help` / `--list-sets` 为门禁，禁止把一台
+   A5 beta 环境的参数复制到 A2/A3（跨版本绝对规则禁令）。
+2. **已有 `collection_manifest.json` 的目录禁止重复采集**：只允许重解析（verdict.py）
+   或换新目录重采。重复 replay 破坏稳态且浪费设备时间。
+3. **MC² 禁 host 侧计时**：std::chrono/gettimeofday 含 launch 开销且精度不足，一切
+   性能数据必须出自 msprof `op_summary` 的 `Task Duration(us)`（npu-compute 通道为
+   `Summary.jsonl` OpInfoSummary 的同名字段）。
+
+## 脚本清单
+
+| 脚本 | 职责 |
+|------|------|
+| `scripts/collect_board.sh` | 上板采集统一入口（standard / quick / timing / mc2 / npu-compute 五模式）+ manifest 落盘；timing 模式跑 event 计时 harness 并归档 result.json（P0-2）；npu-compute 模式采集 .npu-rep 并解包（探测门禁 + 伪 Green 断言，Roadmap #4） |
+| `scripts/collect_cases.py` | **逐 case 采集编排 + 标杆双路径**（P0-1，A1 铁律工具化）：cases.csv + exe [--ref-exe] → 逐 case×variant 调 collect_board → `perf_data.csv`（batch_pipeline `--from-collect` 直接输入）+ 逐 case manifest 归档；case 间串行同卡同口径；防重采闸门（已有 manifest 跳过）；`--cases-subset` 定向补采；failed/partial 如实进 collect_summary（伪 Green 防护） |
+| `scripts/isolation_test.py` | MC² 隔离测试编排：T_comm/T_compute（逐 rank 稳态均值，跨 rank max）+ mte2_ratio_full/pure / rank_imbalance / mask_ratio → R 值与 --scalar 串 → 喂 verdict |
+| `scripts/facts_bridge.py` | 采集产物 → verdict `--scalar` 串（G2 桥接）：L2Cache/Arithmetic/ResourceConflict/OpBasicInfo 提取 + soc-spec 峰值换算，产出 `mte2_active_bw_pct_of_peak` / `l2_hit_rate` / `vec_fp32_ratio` 等——L0 规则与 L1 反证的标量生产者；missing 列表即补采闭环真源；**DB 双源**（P1-6）：CSV OpBasicInfo 缺失时 sqlite（`ai_core_op_summary.db` task_time）备位 task 级时长（等价查询固化在脚本，ns→us 换算 + DB 口径注记防混比；`--no-db` 关闭）；**npu-compute DB 通道**（Roadmap #4）：`--source auto` 按目录特征判源，npu-compute 解包目录逐指标 DB SQL 优先（AVG+NULL-skip 下推）→ CSV 补位，`Summary.jsonl` OpInfoSummary 产出 task_duration/block_dim，PcSampling 产出 `top_stall_pct`（L0_STALL_DOMINANT 的首个生产者） |
+| `scripts/csv_to_db.py` | **CSV→summary.db 转换器**（Roadmap #4）：npu-compute 列名规范化规则移植（单位后缀拆 FieldUnitMap / 词法规范化 / NA→NULL / 类型推断），旧版 .npu-rep（无 DB）与任意 CSV 产物目录升级为 DB 格式消费；写入后回读行数校验 fail loud |
+| `scripts/db_bench.py` | **CSV vs DB 消费性能基准**（Roadmap #4「查询更快」的验证载体）：W1 facts 标量提取 / W2 verdict 全表加载 / W3 分析查询批 / W4 PcSampling（DB 独有）四负载逐项测中位耗时 + 提速比；**等价性门禁**（W1-W3 双通道数值必须一致，不等 exit 1）；提速数字如实逐负载呈现（全表 dict 化 DB 更慢就写慢，不粉饰） |
+| `scripts/jsonl_to_cases.py` | **JSONL 用例适配**（P1-5，G11）：生态内 JSONL 用例（torch-ops-profiler 规范）→ cases.csv（A1 铁律输入契约）；转换规则全落脚本（dtype 归一 / attrs 拼接 / CSV 转义），歧义行 skipped 列明原因不猜测 |
+| `scripts/collect_sim.sh` | **仿真路径采集编排**（P1-1，G7）：cannsim record（精度+性能仿真）→ report（trace_core*.json）→ mode=sim 的 collection_manifest 归档；cannsim 探测门禁（不可用明确报错）；sim 数字与上板禁混比（snapshot timing_method=sim 专用） |
+
+**自动化分级**（如实宣称）：
+- 宿主程序自带模式开关（环境变量）→ **全自动**（env 模式：脚本注入开关、三轮采集、
+  产出完整 verdict --scalar 串）；
+- 宿主无开关（真实 MC² 工程常态）→ **半自动 from-prof**：Agent 在源码副本上注释
+  通信/计算 process 并手工 msprof 后，把两份产物目录交给 `--switch-mode from-prof`
+  收敛（开关参数支持 K=V 形式注入自定义开关）。
+- 源码副本定向注释自动化（识别通信/计算 process 注释点）为 26-1 前置工作项。
+
+## npu-compute DB 格式通道（Roadmap #4）
+
+npu-compute（950/A5 采集器，本仓 `npu_tools/npu_compute`）原生产出 `.npu-rep`
+单文件报告，解包后含 7 个 Section CSV + `Summary.jsonl` + **`summary.db`**
+（SQLite：7 个 Section 表 + `PcSampling` + `FieldUnitMap` 单位表）。
+本套件从本 PR 起打通 DB 格式消费链：
+
+| 环节 | 路径 | 说明 |
+|------|------|------|
+| 采集 | `collect_board.sh --mode npu-compute` | `--set full` 底座 + `--sections` 追加（`--list-sections` 门禁）；产物断言 + manifest 落账 |
+| 标量生产 | `facts_bridge.py --source auto` | npu-compute 目录逐指标 **DB SQL 优先**（AVG+NULL-skip 下推）→ CSV 补位；`Summary.jsonl` OpInfoSummary → task_duration/block_dim；**PcSampling → top_stall_pct**（L0_STALL_DOMINANT 首个生产者） |
+| 判定输入 | `verdict.py --db <summary.db>` | 列名规范化由 FieldUnitMap 自动还原（`aiv_time` → `aiv_time(us)`），下游规则求值零改动 |
+| 旧报告升级 | `csv_to_db.py` | 旧版 .npu-rep（无 summary.db）CSV 目录一键升级为 DB 格式 |
+| 性能验证 | `db_bench.py` | 四负载 CSV vs DB 实测（等价性门禁 + 提速比） |
+
+**口径纪律**：
+- summary.db 是同一次采集 CSV 的入库副本（单次采集双格式）——**数值口径等价，
+  可安全互通**（与 msprof DB 双源的「task 级 vs op 级口径差异」不同，后者
+  sources 注记禁止混比）。
+- 列名规范化差异：DB 侧 `aic_time(us)` → `aic_time`（单位入 FieldUnitMap），
+  `GM_to_L1_datas(KB)` → `gm_to_l1_datas`；大写通路名（GM/L0C/UB）在 DB 中小写。
+- `NA` → SQL `NULL`（不适用≠零）；`AVG/COUNT(列)` 自动排除 NULL。
+- PcSampling 是 **DB 独有数据源**（无 CSV 对应物）——只对 SIMT 指令采样，
+  纯 SIMD 算子无此表（如实 missing，不静默造 0）。
+- 提速数字分口径如实看待（db_bench 实测，本仓开发机）：facts 标量聚合与
+  多查询分析 DB 显著更快（聚合下推省去全表 dict 化）；**verdict 全表 dict 化
+  DB 更慢**（行对象化开销 > csv.DictReader）——选通道按消费形态，不迷信单一
+  结论；等价性门禁保证换通道不改判定数值。
+
+## 采集块 manifest 契约（opstune.collection/1.0）
+
+每次采集输出 `collection_manifest.json` —— 采集块的唯一真源：
+
+```json
+{
+  "mode": "standard",
+  "exe": "./build/demo", "args": "8448 4096 4096",
+  "device_id": "1", "ranks": 1, "kernel_name": null,
+  "blocks": [
+    {"name": "PipeUtilization", "status": "ok", "path": "PROF_PipeUtilization_20261014_..."},
+    {"name": "L2Cache", "status": "failed", "path": "...", "note": "msprof 退出非 0"}
+  ]
+}
+```
+
+- `status`：`ok / partial / failed / skipped`（采集块状态机）。
+- 判定引擎按 manifest 定位 CSV；failed 块在 verdict 侧表现为 REQUIRED 缺失 → SKIPPED
+  （绑定契约兜底：采不到就不判，不静默编造）。
+- **禁止伪 Green**：任何块失败必须在报告中如实呈现，不得从产物清单里悄悄抹掉。
+
+## MC² 隔离测试纪律（isolation_test.py 编排，纪律由本节承载）
+
+1. 隔离测试在**源码副本**进行（`{code_dir}_diag/`），注释通信或计算 process，测完丢弃
+   代码副本、保留 profiling 产物。
+2. tileCnt=1（无流水线）条件下分别测纯通信 / 纯计算。
+3. 稳态：循环 ≥10 次，前 5 warm-up，取后 5 均值；**跨 rank 取 max**（木桶效应——所有
+   rank 经 BarrierAll/CrossCoreFlag 同步，整体性能由最慢 rank 决定）。
+4. R = T_compute / T_comm → 五档 bound（verdict.py L3 规则包消费）。
+5. 掩盖率 =（融合前耗时 − 融合后耗时）/ min(T_comm, T_compute)，上限 1.0。
+
+## 计时口径（供 snapshot.py --timing-method 选择）
+
+| 情形 | 规则 |
+|------|------|
+| 工程自带 benchmark | 视为正式 benchmark，按优先级采信 |
+| 无计时设施 | **拷计时 harness 货架**（ops-family 子域 `references/common/timing_harness/`，C++ aclrtEvent 与 torch event 两模板，随算子族 PR 交付；`collect_board.sh --mode timing` 直跑归档）——属测量设施而非优化变量，原基线源码先备份 |
+| 长 kernel（ms 级）无 event | 允许 Task Duration 作基线，报告注明口径 |
+| 短 kernel（µs 级） | launch 开销掩盖收益：harness 模板内置 stream 内多 launch 单 event 对计时；仍不可归因用 profiler device duration 辅助并注明 |
+| 冷跑/稳态 | 首跑含初始化与缓存预热（实测可差 25%）：固定 warmup 剔除，稳态 ≥3 次取中位（harness 模板已固化此结构） |
+| profiling 构建 | 保持 Release；源码映射只加调试信息，禁 -O0（优化级别变化使前后数据不可比） |
+| 频率漂移（DVFS） | **可选锁频**（P2-2）：`npu-smi set -t freq-lock`（需 root；采集期固定频率消除 DVFS 爬升噪声）。**副作用如实标注**：锁频数字与出厂默认频率下的性能不可直接外推，报告须注明「锁频口径」；无 root 权限时按 warmup 爬升 + 多轮稳态中位数缓解（本仓默认路径，不强制锁频） |
+
+## 设备选择（P2-2/G20 ①）
+
+`collect_board.sh` 选卡逻辑：**结构化解析优先**——`npu-smi info -t usages -i <id>`
+的 `Aicore Usage Rate(%)` 字段判定（< 50% 视为可用），对 npu-smi 输出格式变化
+免疫；结构化解析失败（版本差异）才退化到 `npu-smi info` 表字面匹配并 stderr
+提示。选卡后注入 `ASCEND_RT_VISIBLE_DEVICES`（口径指纹 device_id 源头保真）。
+
+## 参考文档
+
+| 文件 | 内容 |
+|------|------|
+| [`references/tool-routing.md`](references/tool-routing.md) | msprof / msprof op / msopprof / cannsim / torch_npu.profiler 选择决策树与跨版本能力矩阵 |

package/skills/tool-ops-tune/ops-collect/references/tool-routing.md

@@ -0,0 +1,86 @@
+# 采集工具路由决策树（跨版本能力矩阵）
+
+> 硬规则：**先探测本机帮助，再选命令**。本矩阵是选型起点而非命令来源——所有参数、
+> 指标名、能力开关以本机 `msprof op --help` / `msopprof --help` / `npu-compute
+> --list-sets` 实际输出为门禁。禁止使用「MC² 永远不能用 msprof op」这类跨版本
+> 绝对规则（新版已支持时可用，旧版或不稳定时回退完整 msprof）。
+
+## 决策树
+
+```
+① 判算子形态
+   MC²/fork 多 rank ──────────────→ msprof --aic-mode=task-based（本机 msOpProf 明确支持
+                                    多设备/通算流水时也可用 msprof op，否则回退）
+   单卡算子 ──→ ②
+② 判芯片与采集格式
+   950/A5 且本机 npu-compute 可用 → npu-compute（DB 格式采集，Roadmap #4：
+                                    --set full + --sections 追加按 --list-sections 门禁；
+                                    编排：ops-collect/scripts/collect_board.sh --mode npu-compute
+                                    → .npu-rep → --import 解包 → summary.db（含 PcSampling）
+                                    → facts_bridge DB 通道 / verdict --db）
+   其他 / npu-compute 不可用 ──→ ③
+③ 判分析深度
+   只要 kernel 时间/加速比 ────────→ quick 路径（1 轮 Task Duration）
+   要瓶颈判定 ──→ ④
+④ 判芯片与本机能力（--help 探测）
+   A2/A3：MemoryDetail / TimelineDetail 可用 → 按疑点选配
+   A5：PipeTimeline / PcSampling 可用 → 优先评估（pipe 重叠 / 指令热点）
+   通用底座：7 组 aic-metrics 顺序采集（PipeUtilization 为判定引擎主输入）
+⑤ 无卡 / 指令级下钻 ──────────────→ cannsim（仅 A5 单卡 AI Core；MC²/HCCL 不支持）
+                                    编排：ops-collect/scripts/collect_sim.sh（P1-1）
+                                    record → report(trace_core*.json) → mode=sim manifest
+                                    → trace_bubble.py（overlap/top_stall/bubble 标量）
+⑥ torch 生态 ────────────────────→ torch_npu.profiler（JSONL 用例，warmup/active 固定 5）
+                                      JSONL → cases.csv 入口：ops-collect/scripts/jsonl_to_cases.py
+                                      （P1-5；schedule 5/5 由 torch 侧基准脚本持有，
+                                       产物兼容性评估后接入 verdict 链路——当前标注
+                                       🟡 评估中，未接入主判定链）
+⑦ 集群视角（scene=cluster，P2-4 规划态）→ msprof advisor（集群/通信分析路径；
+                                      本机 --help 为门禁同款纪律）。范围边界：本仓
+                                      只消费「判定引擎可读的集群级证据」（快慢 rank /
+                                      host 下发阻塞），深度集群分析是 Hermes 主场；
+                                      算子域聚焦不变
+```
+
+## 工具能力矩阵（以本机帮助为最终门禁）
+
+| 能力 | msprof | msprof op / msopprof | npu-compute | cannsim | torch_npu.profiler |
+|------|--------|---------------------|---------|---------|--------------------|
+| MC² 多 rank | ✅ task-based | 🟡 依版本（探测后用） | ❌（单进程直调形态） | ❌ | ❌ |
+| 7 组 aic-metrics | ✅ | ✅（多轮 replay 内置） | ✅（--set full 一次采集，无需多轮 replay） | 部分（PipeUtilization+ResourceConflictRatio 默认） | 汇总级 |
+| Roofline | ✅（组合 Default） | 🟡 依版本 | —（OpInfoSummary 带理论算力/带宽与实测利用率读数） | — | — |
+| KernelScale / Occupancy | ✅ | ✅ | ✅（逐核） | ✅（逐核） | — |
+| 指令级 / 源码行 | — | Source（-g） | —（PmSampling 指令地址采样 + objdump/symbolizer 定位） | ✅（code_exe/instr_exe） | — |
+| A5 PipeTimeline / PcSampling | — | ✅（A5） | ✅（PipeTrace.json + summary.db PcSampling 表） | — | — |
+| **DB 格式产物** | msprof_*.db（task_time，P1-6 双源） | — | ✅ **summary.db**（7 Section 表 + PcSampling + FieldUnitMap） | — | — |
+| 通算流水图（MC² timeline） | 🟡 | 🟡（MC2/LCCL parser，依版本） | — | — | — |
+
+## 产物 → 消费映射
+
+| 产物 | 消费方 |
+|------|--------|
+| `PROF_*/mindstudio_profiler_output/op_summary_*.csv`（PipeUtilization） | verdict.py `--csv` |
+| `OpBasicInfo.csv`（Task Duration / Block Dim / 频率） | facts_bridge.py（→ `task_duration_us` / `block_dim` 标量）+ L2 头开销判定 |
+| `ArithmeticUtilization / L2Cache / ResourceConflictRatio` | facts_bridge.py（→ L0 规则 + L1 反证标量：`l2_hit_rate` / `vec_fp32_ratio` / `vec_total_cflt_ratio`） |
+| 7 组产物根目录 | facts_bridge.py `--manifest`（一条命令产出 verdict.py `--scalar` 串；含峰值换算，读 soc-spec.yaml） |
+| `PROF_*/device_*/sqlite/ai_core_op_summary.db`（task_time 表） | facts_bridge.py **DB 双源**（P1-6）：CSV OpBasicInfo 缺失时备位 task 级时长；等价查询固化在脚本（不让 LLM 拼 SQL）；DB 口径 ≠ op 级 Task Duration，禁混比 |
+| npu-compute `.npu-rep` → 解包目录（7 Section CSV + Summary.jsonl） | facts_bridge.py `--source auto`（npu-compute 通道：Summary.jsonl OpInfoSummary → task_duration/block_dim；CSV 补位） |
+| npu-compute 解包目录 **`summary.db`**（Roadmap #4） | facts_bridge.py DB 通道（逐指标 AVG+NULL-skip 下推，DB 是 CSV 同数据入库副本可互通）+ verdict.py `--db`（FieldUnitMap 还原列名，规则求值零改动）+ db_bench.py（性能验证） |
+| `summary.db` **`PcSampling` 表**（DB 独有，无 CSV 对应物） | facts_bridge.py → `top_stall_pct` 标量（**L0_STALL_DOMINANT 的首个生产者**；仅 SIMT 指令采样，纯 SIMD 算子无此表如实 missing） |
+| 旧版 .npu-rep（无 summary.db）| csv_to_db.py 升级为 DB 格式消费（列名规范化规则与 npu-compute 入库一致） |
+| isolation_test.py 的 `iso_result.json` | verdict.py `--scalar t_comm_us,t_compute_us` |
+| `collection_manifest.json` | 报告/复盘定位产物；防重复采集闸门 |
+
+## 高频踩坑（一线实测）
+
+- `--kernel-name` 仅 application 形态有效；不指定时部分版本只采第一个算子——多 kernel
+  程序必须显式过滤并核对 `OpBasicInfo.csv` 全 kernel 清单（部分结果禁止调优）。
+- C++ mangled 匿名命名空间符号（`_ZN12_GLOBAL__N_1...`）导致 `--kernel-name` 采集为空：
+  去掉过滤全量采集，从 OpBasicInfo 抄真实 kernel 名。
+- 采集日志有 libprofapi ERROR 但 CSV 正常 → 工具链噪声，**以产出检查为准**不凭 ERROR 行判失败。
+- fork 多进程只采到每进程第一个 kernel → msopprof 对 fork 不完整：标 partial，改
+  SHMEMI_PROF 或完整 msprof。
+- 输出目录权限与软链检查会直接报错：先确认目录可写、无跨设备软链。
+- 短 kernel 同时保存 host event 计时：绝对性能以 event 为主，msOpProf 用于结构诊断。
+- 采集失败分流表（GLIBCXX / aic-ascend950-ops-info.ini / tiling 改动 fault 等）见
+  ops-tuning-agent workflows/troubleshooting.md。