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

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "ops-tune-workbench-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-beta.2",
+  "description": "算子调优工作台插件（dsh 底座）：工具桥（采集编排 / 产物导入 / verdict 判定 / 基线对比 / 技能入口）+ 可视化面板（结果列表 / 报告视图 / 采集配置）+ 内置 tool-ops-tune 技能",
+  "type": "module",
+  "main": "lib/host.js",
+  "exports": {
+    ".": {
+      "default": "./lib/host.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "skills",
+    "cordis.patch.yml",
+    "NOTICE.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-api-workspace-files",
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-locale",
+        "remote.workspaceFiles",
+        "remote.session"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "node build.mjs"
+  },
+  "engines": {
+    "dsh": ">=0.2.1-rc.2 <0.3.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-tools": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-util-crypto": "0.2.2-rc.1",
+    "esbuild": "^0.25.0"
+  },
+  "devDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "license": "MIT"
+}

package/skills/tool-ops-tune/INSTALL.md

@@ -0,0 +1,52 @@
+# tool-ops-tune 安装与使用指导
+
+本文说明将 tool-ops-tune 套件加载到三种 AI 助手（opencode、Claude Code、Codex）的安装方式、前置依赖、加载验证与使用示例。套件为「单入口 skill + 五子域」形态：`SKILL.md` 是唯一注册入口，五个子域（ops-collect / ops-verdict / ops-mechanism / ops-family / ops-report）以子目录形态由入口按调优阶段路由加载（渐进式披露——判定之前不加载机制卡，证据先行）。安装即把整个 `skills/tool-ops-tune/` 目录放到对应助手的技能目录，无需额外注册或编译。
+
+## 前置依赖
+
+- 安装技能本身无依赖。要完整走通调优流程，需在目标环境具备 CANN 软件包工具链：`msprof`（性能采集）、`npu-smi`（设备查询），且 Python ≥ 3.8 + PyYAML（判定引擎唯一硬依赖）。
+- 纯判定 / 判定书解读无需 NPU：已有 msprof 导出的 CSV 即可直接喂 `ops-verdict/scripts/verdict.py`（套件 `fixtures/` 内置样本可直接体验）。
+- `agent/` 编排层（五阶段自动调优）需要支持多 agent 的 AI 编程工具；SKILL 子域可脱离 Agent 单独使用（CLI 直跑）。
+
+## 安装方式
+
+三种助手的技能目录与发现机制如下（按各助手官方技能约定）：
+
+### opencode
+
+- 项目级：将本套件目录放置为 `<项目>/.opencode/skills/tool-ops-tune/`。
+- 全局：放置到 `~/.config/opencode/skills/tool-ops-tune/`。
+- opencode 通过 skill 工具自动发现 SKILL.md，按 frontmatter 的 name 与 description 判定触发；目录放入后即可用，无需额外注册。
+
+### Claude Code
+
+- 项目级：`<项目>/.claude/skills/tool-ops-tune/`（SKILL.md 与子域目录一并放入）。
+- 个人级：`~/.claude/skills/tool-ops-tune/`。
+- Claude Code 依据 SKILL.md 的 description 命中触发条件时自动调用本套件，无需手动启用。
+- 多 agent 编排：将 `agent/AGENTS.md` 作为项目编排规范并入 CLAUDE.md，`agent/agents/` 下两个 subagent 注册到 agents 目录即可启用五阶段自动调优。
+
+### Codex
+
+- 仓库级：`<仓库>/.agents/skills/tool-ops-tune/SKILL.md`（Codex 从当前目录向上扫描 `.agents/skills`，放在仓库根目录可让所有子目录使用）。
+- 用户级：`~/.agents/skills/tool-ops-tune/`。
+- Codex 启动时扫描技能目录，先只注入 name 与 description 进入上下文，命中后加载完整 SKILL.md；新增技能后需重启 Codex 生效。
+- 若所用 Codex 版本未启用 skills 特性，可将套件触发与路由说明写入仓库的 AGENTS.md（workspace 指令），使 Codex 将其作为仓库工作区指令加载——此为降级集成路径。
+
+## 加载验证
+
+- opencode：发起与 description 强信号吻合的提问（如「帮我判定这个算子的瓶颈」），或查看 skill 工具是否列出 `tool-ops-tune`。
+- Claude Code：输入含「算子调优 / 瓶颈判定 / Bound 判定 / 性能采集」等触发词的问题，观察是否按五阶段流程进入采集与判定。
+- Codex：启动后使用 `/skills` 浏览（或输入含触发词的问题），确认 `tool-ops-tune` 出现在可用技能列表。
+- CLI 直跑验证（不依赖助手）：`python3 ops-verdict/scripts/verdict.py --rules ops-verdict/rules/L1-single-core.yaml --csv ops-verdict/fixtures/mte2_bound_a2.csv --soc a2 -o /tmp/v.json`，产出合法判定书即安装完整。
+- DB 通道自验（Roadmap #4，可选）：拿一份 npu-compute `.npu-rep` 解包目录跑 `python3 ops-collect/scripts/facts_bridge.py --manifest <解包目录> --soc a5 --print-scalar`——目录特征自动识别 npu-compute 通道；含 `summary.db` 时输出应含 `top_stall_pct`（PcSampling）。
+- 回归自检（测试框架）：`python3 ops-verdict/evals/run_evals.py`（执行式判定回归，38 用例）+ `bash ops-verdict/evals/smoke/run_smoke.sh`（离线干跑冒烟，msprof shim 无 NPU 可跑）——退出码 0 才可用；变更规则/脚本后必须先过双绿再交付。
+
+## 使用示例
+
+向已加载套件的助手输入一个调优任务即可，例如：
+
+> 帮我调优这个 gelu 算子，工程在 ./gelu_project，cases.csv 里有 12 个 case，目标是耗时降到 100us 以内
+
+助手应按五阶段闭环执行：精度门禁预检 → 采集与基线固化（ops-collect 路由）→ 分层判定（verdict.py）→ 机制路由与候选方案 → 单变量迭代（每轮 diff_audit + 独立审查 + 同口径对比）→ REPORT 六要素归档，全程产物落 `tuning_artifacts/{operator}/`。
+
+已有 profiling 产物时也可直接问「这个算子为什么慢，给出瓶颈判定和证据」——仅走离线判定与报告解读，不修改源码。

package/skills/tool-ops-tune/README.md

@@ -0,0 +1,167 @@
+# OpsTune — 昇腾算子性能调优 AGENT/SKILL 套件
+
+![License](https://img.shields.io/badge/License-CANN--2.0-blue?style=flat-square)
+![Python](https://img.shields.io/badge/Python-3.8%2B-3776ab?style=flat-square&logo=python&logoColor=white)
+![Platform](https://img.shields.io/badge/Platform-Ascend%20NPU-orange?style=flat-square)
+![Evals](https://img.shields.io/badge/evals-38%2F38%20passing-brightgreen?style=flat-square)
+![Smoke](https://img.shields.io/badge/smoke-13%20checks%20all%20green-brightgreen?style=flat-square)
+![Agent Skills](https://img.shields.io/badge/Agent%20Skills-5%20%E5%AD%90%E5%9F%9F-blueviolet?style=flat-square)
+
+**判定进脚本 · 解释进 LLM · 经验可回流**
+
+📖 [架构设计](docs/ops-tune-design.md) ｜ [知识库规范](docs/知识库规范.md) ｜ [评测体系](docs/用例构建.md) ｜ [安装指导](INSTALL.md)
+
+给「已可运行、精度通过」的昇腾算子做性能调优的完整 Agent + SKILL 工具链：分层瓶颈判定引擎（规则-指标绑定契约）、机制卡与案例证据库、算子族模板代码货架、MC² 隔离测试与配平搜索、调优主循环（采集→问题判定→机制路由候选方案→单变量执行优化→对比确认）——让 Bound 判定可审计、阈值可回归、结论可复现。
+
+---
+
+## 📢 为什么需要 OpsTune
+
+算子性能调优长期是专家驱动的手工活：一次 MTE2 Bound / VF 级别的专家诊断常以人月计，判定质量随人波动，经验随人员流动流失。OpsTune 把这条链路工程化：
+
+| 业界现状痛点 | OpsTune 的答案 |
+|-------------|---------------|
+| Bound 判定靠 LLM/专家读文档，阈值变更不可回归 | **ops-verdict 判定引擎**：24 条专家规则 YAML 化 + 脚本求值 + 执行式回归（evals 38 用例） |
+| 指标没采也可能被「判」出瓶颈 | **规则-指标绑定契约**：REQUIRED 缺失 → SKIPPED，机制上杜绝无证据判定 |
+| MC² 场景 MTE2 被通信等待污染，单核优化做了白做 | **路由副作用**：污染判定命中自动禁用单核访存规则并改道通信掩盖策略 |
+| 跨口径比较、噪声带内宣称收益 | **口径指纹互锁**：12 字段 HARD 校验 + 精度门禁 + ±5% 噪声带三段结论 |
+| 融合算子隔离测试全靠手工 | **isolation_test.py**：T_comm/T_compute → R 值实验编排（跨 rank max 木桶口径内置） |
+| 经验不回流 | **案例卡 schema**（A-E 证据分级）+ E 级回灌 + 预估-实测校准数据随每轮产出 |
+
+**面向用户**：昇腾 NPU 算子开发者（Ascend C 为主）、性能工程师、算子仓 CI 维护者。
+
+---
+
+## 🏆 核心竞争力
+
+### ① 性能数据 AI 亲和性设计
+
+采集产物即 Agent 可直接消费的结构化数据——**AI 读得更快、更省 Token，判定更快更准**：
+
+- **950 平台采集对接 [npu-compute](../tool-npu-compute/)**（本仓 npu_tools/npu_compute）：相比传统 msprof 导出，npu-compute 产出结构化 `.npu-rep` 报告（7 Section CSV + `Summary.jsonl` + **`summary.db`** SQLite），Agent 侧零解析成本直接喂判定引擎；
+- **DB 格式消费链已打通**（Roadmap #4 交付）：`summary.db` 聚合查询下推（AVG+NULL-skip）使标量提取与分析查询**实测提速一个数量级**（`db_bench.py` 四负载等价性门禁 + 提速比，复跑命令见 [ops-collect/SKILL.md](ops-collect/SKILL.md)）；`PcSampling` 表（DB 独有）产出 `top_stall_pct`——L0_STALL_DOMINANT 规则的首个生产者；
+- **采集维度更全**：涵盖 **Block Profiling**（逐 Block 核间负载形态——L2 核间判定层的直接证据源）、**通信性能数据**（多卡/集合通信时延与带宽——MC² 卡间判定层输入）、**SIMT WARP 流水灯**（Warp 调度与发散形态——条件分支/离散索引类算子的指令级证据）——为多卡、多核、单核全场景性能调优提供更完整的证据链；
+- **指标词汇表与三代列名兼容**（aic_/aiv_/ai_）+ ratio_to_pct 双口径归一 + mean/max 双统计内建于引擎——性能数据从「人读的 CSV」升级为「机器判定的契约数据」。
+
+### ② TOP-DOWN 分层判定方法论，对标业界领导者
+
+对标业界领先 GPU Profiling 工具 Guided Analysis 的「规则引擎 + 绑定契约 + 预估加速比排序」形态，并向前一步——**判定进脚本，速度更快、结论更准、质量不随模型波动**：
+
+- **L3 卡间 → L2 核间 → L1 单核 → L0 指令** 四层瀑布，上层结论约束下层（TOP-DOWN 归因路径，杜绝单核视角误判融合算子）；
+- **内置 24 条专家经验规则**（MC² R 值五档 / 核间长尾离散度三档 / MTE2 真假 bound 二分 / 串行无重叠指纹 / 头开销 / host 下发阻塞…），每条带**阈值溯源 + 反证条目 + 置信度 + 预估收益区间 + 机制路由**；
+- **可扩展零代码**：新规则 = 一个 YAML 条目 + fixture + 断言用例（evals 全绿才可合入）——专家经验的积累不碰引擎；
+- **覆盖多卡、多核、单核全场景**：单算子 / 融合算子（FA·MC²）/ 批量回归 / 调优问答四类入口共用同一规则集与数据契约。
+
+### ③ 专业知识体系：分类化 · 结构化 · 可演进
+
+算子调优知识不是散落的文档，而是**分层分类、带路由入口、可检索可扩展**的知识资产：
+
+- **知识五层分类（K1-K5）**：判定规则（24 条 YAML）/ 优化机制卡（8 张，固定八要素：原理·前提·收益·架构限制·精度风险·验证命令·回滚条件·模板资产）/ 算子族实践（11 族 A/B 双型文档 + 32 个可拷贝代码模板 + 计时 harness ×2）/ 案例证据（A-E 分级，反例同等收录）/ 外部事实引用（CANN 真源动态引用不落副本）；
+- **多层次知识体系 + 生态对接**：经验性知识沉淀于本套件，事实性知识（芯片参数 / API 签名 / 官方示例 / 理论标尺）对接 [cann-knowledge](https://gitcode.com/cann/cannbot-knowledge) 知识库真源——单一事实源，不维护会腐烂的副本；
+- **知识自演进四回路**：案例回流（E 级实测入库）/ 校准闭环（预估 vs 实测偏差回写收益区间）/ 阈值进化（命中率统计 → 人审 + 回归全绿才生效）/ 缺口感知（「暂未收录」显式计数 → 排产信号）；
+- **知识轨迹能力**：每张判定书、每轮对比、每条回灌案例都带口径指纹与证据链可追溯——知识从哪来、被谁用过、验证过几轮，全程留痕。
+
+### ④ 算子性能 Benchmark 构建，评测与自进化双驱动
+
+调优能力本身也需要被评测——Benchmark 是 AGENT/SKILL 自进化的**量化反馈回路**：
+
+- **执行式回归体系**：evals 38 用例（判定回归 E1-E26 含 R 值临界值双侧守护 + 门禁脚本回归 S1-S12）+ 离线冒烟 smoke 13 项检查（msprof shim 无 NPU 可跑）+ 触发评测 7 用例——规则/阈值任何变更，判定质量劣化立即被抓住；
+- **真机标尺**：soc-spec 峰值表（带宽/算力/容量，来源可溯）提供「还差多远」的客观读数；CANNBench L1-L4 任务的 t_hw 理论下界可作外部标尺接入；
+- **自进化闭环**：Benchmark 评测数据（误报率 / 命中率 / 预估偏差）→ 阈值进化建议 → 人审 + 回归全绿 → 合入——AGENT/SKILL 的能力提升走机制不走自觉。
+
+---
+
+## 🏗️ 项目架构
+
+四层架构：**Agent 编排（只调度不判定）→ SKILL 能力（确定性沉淀）→ 规则引擎（判定进脚本）→ CANN 工具链（复用不重做）**。
+
+```
+skills/tool-ops-tune/
+├── SKILL.md                    # 套件入口：主循环总览 + 子域路由表
+├── INSTALL.md                  # 三助手（opencode/Claude Code/Codex）安装指导
+├── agent/                      # L3 Agent 编排层
+│   ├── AGENTS.md               #   OpsTuningAgent：调优主循环 + 三道精度门禁
+│   ├── agents/                 #   perf-implementer / perf-reviewer subagent
+│   └── workflows/              #   task-prompts（Step 执行手册）+ troubleshooting
+├── ops-collect/                # L2 采集编排（模式路由 + manifest 契约 + MC² 隔离测试）
+├── ops-verdict/                #   ★ 判定引擎（规则包 24 条 + snapshot/delta_compare
+│   │                           #     口径互锁 + soc-spec 标尺 + evals/smoke 回归）
+├── ops-mechanism/              #   机制卡 8 张 + 案例库（A-E 分级）+ mc2_search 配平搜索
+├── ops-family/                 #   算子族 11 族 + 32 个可拷贝模板 + tiling 候选生成器
+└── ops-report/                 #   结果可视化（render_html 单文件静态报告）
+```
+
+**调优主循环**：`（前置）意图与边界：精度门禁预检 + 场景分类 → 【采集 → 问题判定（verdict.json 分层瀑布）→ 机制路由（候选方案卡 ≤3）→ 单变量执行优化（diff_audit 机器闸门）→ 对比确认（KEEP/REVERT/复测三段结论）】循环至收敛 → （收尾）归档回灌（REPORT 六要素 + E 级案例）`
+
+## 🚀 快速开始
+
+### 前置条件
+
+- 任选一种 AI 编程工具：[Claude Code](https://code.claude.com/docs/en/setup) / OpenCode / Codex
+- Python ≥ 3.8 + PyYAML（判定引擎唯一硬依赖）
+- 上板采集需 CANN 工具链（msprof / npu-compute / npu-smi）；**纯判定 / 回归 / 问答无需 NPU**
+
+### 30 秒体验：不装 Agent，直接判定
+
+```bash
+# 拿一份 msprof 导出的 PipeUtilization.csv，一句话出判定书：
+python3 ops-verdict/scripts/verdict.py \
+    --rules ops-verdict/rules/L2-inter-core.yaml,ops-verdict/rules/L1-single-core.yaml \
+    --csv PipeUtilization.csv --soc a5 \
+    --scalar physical_cores=48,block_dim=24,task_duration_us=195 \
+    -o verdict.json
+```
+
+```
+verdict: NEEDS_OPTIMIZATION  |  MTE2 搬入瓶颈（moderate）；另有 2 项命中
+  HIT  [moderate/high  ] L1_MTE2_BOUND: MTE2 搬入瓶颈  (est [1.2, 2.0])  evidence: mte2_ratio=78.0
+  HIT  [critical/high  ] L2_IMBALANCE_SEVERE: 核间负载不均衡（离散度严重档）  (est [1.1, 1.5])
+  skipped=0  insufficient_data=0
+```
+
+每条命中都带**证据数值 + 阈值溯源 + 反证评估 + 置信度 + 预估收益 + 机制路由**——判定可审计，不是黑盒。
+
+### 用自然语言调优（装好 Agent 后）
+
+```text
+"帮我调优这个 gelu 算子，cases.csv 里有 12 个 case，目标是 100us 以内"
+"这个 MC² 算子为什么慢？给出瓶颈判定和证据"
+"把优化前后的 profiling 对比一下，生成报告"
+```
+
+Agent 按主循环执行：采集与基线固化 → 问题判定 → 机制路由候选方案 → 单变量执行优化 → 对比确认（KEEP/REVERT），循环至收敛后 REPORT 归档，全程产物落 `tuning_artifacts/{operator}/`。
+
+安装方式（opencode / Claude Code / Codex 三助手）与加载验证详见 **[INSTALL.md](INSTALL.md)**。
+
+## 📊 资产总览
+
+| 资产 | 规模 | 位置 |
+|------|------|------|
+| 判定规则（L0-L3 四包） | 24 条（阈值全溯源，BOUND 类必带反证） | ops-verdict/rules/ |
+| 优化机制卡 | 8 张（固定八要素，含 MC² 配平搜索） | ops-mechanism/references/optimize/ |
+| 案例证据卡 | 3 张（A-E 分级，含反例） | ops-mechanism/cases/ |
+| 算子族实践 + 模板 | 11 族 + 32 个可拷贝代码模板（族表断言零漂移）+ 计时 harness ×2 | ops-family/references/ |
+| 执行式回归 | evals 38 用例 + smoke 13 项检查（无 NPU 可跑） | ops-verdict/evals/ |
+| 数据契约 | 7 份 schema（collection/verdict/snapshot/scope/candidates/isolation/case） | 各子域 references/ |
+
+## 🗺️ Roadmap
+
+| # | 方向 | 说明 |
+|---|------|------|
+| 1 | **性能报告解读 SKILL（AscendC Toolkit 插件）** | 对接 AscendC Toolkit 插件形态：读取性能报告，输出「性能问题 + 证据 + 修复建议」三段式解读，可引用本套件（ops-tune）的判定引擎与机制卡作为依据——把专业判定能力带到开发者日常工作流 |
+| 2 | 补充最佳实践案例 | 案例证据库扩容（A/B 级官方 PR 案例 + E 级实测回流），覆盖更多算子族与融合形态 |
+| 3 | 优化 HTML 报告 | render_html 增强：交互式钻取、Bound 演化时间线、多轮迭代对比视图 |
+| 4 | ~~采集工具切换 DB 格式数据~~ **✅ 已交付** | npu-compute 采集产物 sqlite DB 格式消费（`--mode npu-compute` 采集编排 + facts_bridge DB 通道 + verdict `--db` + csv_to_db 升级器 + db_bench 性能验证）；PcSampling → top_stall_pct 打通 L0_STALL_DOMINANT |
+| 5 | 知识标准化 OKF 格式对接 CANN-KNOWLEDGE | 知识资产按 OKF（Open Knowledge Format）标准化，与 [cann-knowledge](https://gitcode.com/cann/cannbot-knowledge) 双向对接——本套件知识可被生态检索与复用 |
+| 6 | AGENT/SKILL 增加 trace 能力 | 判定与调优全程 trace 留痕（决策链可视化）：每步为什么这么做、证据是什么、替代方案为何未选 |
+| 7 | 新芯片 / API 适配 | 适配下一代芯片与新 AscendC API：soc-spec 峰值表 / 规则包 soc 域 / 列名兼容层随芯片演进扩展 |
+
+## 🤝 贡献
+
+- **新增判定规则**：YAML 条目（threshold_source 必填 + BOUND 类必带反证）+ fixture + evals 断言，回归全绿后提 PR——详见 `docs/知识库规范.md`；
+- **新增机制卡 / 案例卡 / 算子族模板**：按 `docs/知识库规范.md` 的八要素与 A-E 证据分级书写；
+- 提交流程遵循 [CONTRIBUTING.md](../../CONTRIBUTING.md)。
+
+## 📄 许可证
+
+[CANN Open Software License 2.0](../../LICENSE)

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

@@ -0,0 +1,93 @@
+---
+name: tool-ops-tune
+description: 昇腾算子性能调优 AGENT/SKILL 套件（OpsTune）。对「已可运行、精度通过」的算子工程做性能调优：分层瓶颈判定引擎（规则-指标绑定契约，判定只出自脚本）、性能采集编排（msprof 模式路由与 manifest 契约）、机制卡与案例证据库、算子族模板货架、调优主循环（采集→问题判定→机制路由候选方案→单变量执行优化→对比确认）。触发：算子调优、瓶颈判定、Bound 判定、性能采集、profiling 编排、调优前后对比、加速比结论时使用。
+---
+
+# 昇腾算子调优套件（OpsTune）
+
+> **判定进脚本 · 解释进 LLM · 经验可回流**
+> 给「已可运行、精度通过」的昇腾算子做性能调优的完整 Agent + SKILL 工具链：
+> Bound 判定可审计、阈值可回归、结论可复现。
+
+## 套件总览（调优主循环闭环）
+
+```
+工程 + cases（精度已通过）
+    │
+Phase 0 意图与边界 ─ 精度门禁预检（全集跑通）+ 场景分类（单算子/融合/回归/问答）→ scope.json
+    │
+Phase 1 采集与基线 ─ ops-collect 模式路由（MC² task-based 强制/单卡 standard/无卡 sim）
+    │                 + 不可变基线 snapshot（口径指纹 12 HARD 字段）
+    │
+Phase 2 分层判定 ── ops-verdict 规则引擎：L3 卡间→L2 核间→L1 单核→L0 指令瀑布
+    │                 + 路由副作用（MTE2 污染自动禁用单核访存判定）→ verdict.json
+    │
+Phase 3 机制路由 ── 按 findings[].mechanism_refs 加载机制卡（判定后才加载，证据先行）
+    │                 → 候选方案卡 ≤3（机制+证据+diff 草案+预估收益+回滚条件）
+    │
+Phase 4 单变量迭代 ─ perf-implementer 单机制实施 → diff_audit 范围机器校验
+    │                 → perf-reviewer 独立审查 → 同口径统一采集 → delta_compare
+    │                 三段结论（KEEP / REVERT / 噪声带复测）
+    │
+Phase 5 归档回灌 ── REPORT 六要素 + E 级案例候选 + 预估-实测校准数据
+```
+
+编排规范：`agent/AGENTS.md`（OpsTuningAgent 调优主循环 + 三道精度门禁 + 口径铁律）；
+Step 执行手册：`agent/workflows/task-prompts.md`；故障分流：`agent/workflows/troubleshooting.md`。
+
+## 子域路由表（按调优阶段加载）
+
+| 子域 | 回答的问题 | 关键资产 | 交付状态 |
+|------|-----------|---------|---------|
+| `ops-collect/` | 数据怎么采对采全 | 采集模式路由决策树 + collect_board/collect_cases/facts_bridge/jsonl_to_cases/collect_sim + isolation_test（MC² 隔离测试）+ manifest 契约（opstune.collection/1.0）+ npu-compute DB 格式通道（csv_to_db/db_bench，Roadmap #4） | ✅ 已交付 |
+| `ops-verdict/` ★ | 瓶颈是什么、为什么不是别的；改好了吗 | 判定引擎 6 脚本 + L0-L3 规则包 24 条 + 口径指纹互锁（snapshot/delta_compare） + soc-spec 峰值标尺 + 执行式回归（evals 38 用例 + 离线冒烟 smoke） | ✅ 已交付 |
+| `ops-mechanism/` | 怎么改、能涨多少、风险在哪 | 机制卡八要素 + 案例证据库（A-E 证据分级；含 MC² 机制卡与配平搜索） | ✅ 已交付 |
+| `ops-family/` | 代码怎么写（模板货架） | 算子族 A/B 双型文档 + 可拷贝代码模板 + tiling 候选生成器（含 mc2 族设计参考） | ✅ 已交付 |
+| `ops-report/` | 结果怎么呈现 | 调优结果可视化报告（render_html：单文件静态 HTML，零外部依赖） | ✅ 已交付 |
+
+> 子域间唯一耦合点是显式契约引用：verdict 的 `mechanism_refs` → 机制卡；方案卡的
+> `template` → 模板路径；manifest `blocks` → CSV 输入定位；snapshot HARD_KEYS →
+> delta_compare 校验域。契约字段不变则两侧互不影响。
+
+## 30 秒体验：不装 Agent，直接判定
+
+```bash
+# 拿一份 msprof 导出的 PipeUtilization.csv，一句话出判定书：
+python3 ops-verdict/scripts/verdict.py \
+    --rules ops-verdict/rules/L2-inter-core.yaml,ops-verdict/rules/L1-single-core.yaml \
+    --csv PipeUtilization.csv --soc a5 \
+    --scalar physical_cores=48,block_dim=24,task_duration_us=195 \
+    -o verdict.json
+```
+
+每条命中都带**证据数值 + 阈值溯源 + 反证评估 + 置信度 + 预估收益 + 机制路由**——判定可审计，不是黑盒。
+
+## 采集入口（上板 / 仿真）
+
+```bash
+# 上板标准采集（7 组 aic-metrics 顺序采集 + manifest 契约落盘）：
+bash ops-collect/scripts/collect_board.sh --mode standard --exe ./build/demo --args "8448 4096 4096" -o PROF_OUT
+
+# 950/A5 DB 格式采集（npu-compute → .npu-rep → 解包 → summary.db，Roadmap #4）：
+bash ops-collect/scripts/collect_board.sh --mode npu-compute --exe ./build/demo -o NPC_OUT
+
+# 逐 case 批量采集（cases.csv → perf_data.csv，batch_pipeline 直连）：
+python3 ops-collect/scripts/collect_cases.py --cases cases.csv --exe ./build/demo -o collect_out
+
+# 采集产物 → 判定标量桥接（L0 规则与 L1 反证的标量生产者；
+# --source auto 按目录特征判源，npu-compute 解包目录自动走 DB 通道）：
+python3 ops-collect/scripts/facts_bridge.py --prof PROF_OUT --soc a5
+```
+
+## 安装
+
+三种 AI 助手（opencode / Claude Code / Codex）的安装与加载验证见 [INSTALL.md](INSTALL.md)。
+
+## 职责边界
+
+| 做 | 不做 |
+|---|---|
+| 对「可运行且精度通过」的算子做性能调优闭环 | 不做算子开发（从零开发走算子开发域工作流） |
+| 判定进脚本（verdict.py 规则求值，LLM 只解释） | 不做精度调试（精度失败 → 停止调优转调试域） |
+| 同口径前后对比（口径指纹互锁 + 噪声带三段结论） | 不重做采集器（msprof/msopprof/cannsim 全部复用） |
+| 经验回流（E 级案例 + 校准数据 + 缺口计数） | 不在噪声带（±5%）内宣称收益 |

package/skills/tool-ops-tune/agent/AGENTS.md

@@ -0,0 +1,195 @@
+---
+description: 算子调优代理 OpsTuningAgent，接收可运行且精度通过的算子工程，调度 ops-collect / ops-verdict / ops-mechanism / ops-family SKILL 与 perf-implementer Subagent，管理「基线 → 分层判定 → 机制路由 → 单变量迭代 → 对比归档」的完整调优闭环。
+mode: primary
+skills:
+  - ops-collect
+  - ops-verdict
+  - ops-mechanism
+  - ops-family
+  - ops-report
+permission:
+  external_directory: allow
+---
+
+# OpsTuningAgent
+
+## 核心原则
+
+### 身份
+
+昇腾算子性能调优代理 OpsTuningAgent。接收**可运行且精度通过**的算子工程，按阶段调度
+Subagent，管理五阶段调优闭环。所有性能结论来自目标环境实测；判定只出自 ops-verdict
+规则引擎（本 agent 消费 verdict.json，不做判定）；代码修改只由 perf-implementer 执行。
+
+### 职责
+
+- **意图与边界**：理解调优目标（达标线 / 加速比 / 找瓶颈）；场景分类（单算子 / 融合算子 /
+  批量回归 / 问答）；精度未通过 → 拒绝进入调优（转调试域）
+- **工作流调度**：按阶段调用 subagent，读取 `tuning_artifacts/` 产物判定进度、驱动门禁
+- **进度监控与汇报**：每轮结束输出对比结论；多轮汇总
+
+### 能做什么
+
+- 接收算子工程 + 用例 + 目标，生成 scope.json 调优计划
+- 调用 Subagent 执行采集、判定、实施、对比
+- 读取 verdict.json / result.json / comparison.md 判断门禁
+- 仲裁机制选择争议（查官方文档与机制卡）
+- 汇报最终调优结果（含保留与回滚清单）
+
+### 不能做什么（纪律）
+
+- **禁止**：直接参与判定、策略制订或代码实施——判定只出自 ops-verdict 脚本
+- **禁止**：跳过基线采集直接分析；跳过判定直接选机制（证据先行）
+- **禁止**：凭经验给出优化建议、不按阶段顺序执行
+- **禁止**：自行编写、删减、改写 Subagent prompt 模板内容
+- **禁止**：一次迭代允许多个无关机制（单变量铁律）
+- **禁止**：把噪声带内（±5%）的变化当作收益宣称
+
+### 输入边界
+
+| 项 | 必需 | 说明 |
+|----|------|------|
+| 可运行算子工程 | **是** | 完整源码目录，能编译、运行、验证精度 |
+| 测试用例（cases.csv / jsonl） | **是** | shape/dtype/attrs；每个 case 都用户关注，**全量覆盖**（>20 取前 20 并告知用户截断） |
+| 输出目录 | **是** | `tuning_artifacts/{operator}/` 隔离产物目录 |
+| 性能目标 / max_rounds | 否 | 目标（如带宽 80%、耗时 <100us）或轮次；未指定默认 1 轮 |
+
+可选（触发对应扩展）：CANN-Bench 路径（评分接入，未接入占位）、仿真模式（无卡离线）、
+profiling 产物目录（问答模式直接判定）。
+
+### 输出边界
+
+- `scope.json`（调优计划与环境/口径指纹）→ `verdict.json`（分层判定书）→
+  候选方案卡（≤3）→ 逐轮 `result.json` + `comparison.md` → `REPORT.md`（终报，
+  报告六要素）→ 可选 `E 级案例回灌条目`
+
+### Subagent 职责划分
+
+| 角色 | 负责 |
+|------|------|
+| **perf-implementer** | 单候选机制实施：复制目录 → 模板拷贝优先 → 编译修复顺序 → 全量 case 精度验证。一次一个机制（单变量） |
+| **OpsTuningAgent（本 agent）** | 编排 + 门禁 + 统一采集调度 + 对比 + 报告。**垄断 delta_compare 的调用**（口径一致性由编排层保证） |
+
+---
+
+## 调优主循环（五阶段）
+
+```
+用户输入（工程 + cases + 目标）
+    │
+    ▼
+Phase 0 意图与边界（本 agent）
+    ├─ 精度门禁预检：工程正确性全集跑通？（失败 → 拒绝，转调试域）
+    ├─ 场景分类：单算子 / 融合算子（FA·MC²）/ 批量回归 / 问答
+    └─ 生成 tuning_artifacts/{op}/scope.json（opstune.scope/1.0：12 HARD + 2 机制变量 + 场景/目标）
+    │
+    ▼
+Phase 1 环境与基线固化
+    ├─ /ops-collect：环境指纹（env）+ 工具路由（MC² → task-based 强制）
+    ├─ 不可变基线：snapshot.py 落盘（timing-method 五选一 + 口径 12 字段）
+    └─ 理论标尺：soc-spec.yaml 峰值表（ops-verdict references/）→「还差多远」读数；
+       CANN-Bench t_hw 接入为规划项（未接入，占位——REVIEW2 G3 如实标注）
+    │
+    ▼
+Phase 2 采集与分层判定
+    ├─ /ops-collect：标准 7 组指标（或 MC² 隔离测试 → R 值）
+    ├─ /ops-verdict：verdict.py 分层瀑布 L3→L2→L1→L0
+    │    ├─ INSUFFICIENT_DATA → 按缺项补采（回到本 Phase 顶部，最多 2 轮）
+    │    └─ verdict.json（findings + 反证 + 置信度 + speedup_range）
+    └─ MC² 专项：L3_MTE2_POLLUTED 命中 → 单核访存机制自动禁用（路由副作用）
+    │
+    ▼
+Phase 3 机制路由与候选方案
+    ├─ /ops-mechanism：按 findings[].mechanism_refs 加载机制卡（渐进式披露）
+    ├─ /ops-family：模板路径进方案卡（✅可直接拷贝 / ⚠️部分实现 / ❌仅设计参考）
+    └─ 输出候选方案卡 ≤3（机制+证据+diff 草案+speedup_est+语义风险+回滚条件+模板路径）
+    │
+    ▼
+Phase 4 单变量迭代（每轮）
+    ├─ perf-implementer：实施单机制 → 编译 → 全量 case 精度（每轮门禁②）
+    ├─ 本 agent 统一采集：同口径性能（与基线同一 timing/warmup/repeat/device）
+    ├─ /ops-verdict：snapshot.py + delta_compare.py（口径校验+精度门禁③+噪声带三段）
+    │    ├─ KEEP → 保留，进入下一轮（上轮产物为新基线）
+    │    ├─ REVERT → 回滚并复跑确认回到基线水平；负优化记录进报告
+    │    └─ 噪声带内 → repeat 翻倍复测（同步重采基线与优化侧、重建快照后再比）；仍带内 → 按无稳定收益处置
+    └─ 停止条件：达标 / 候选尽 / 连续两轮无稳定收益 / 接近上限（NEAR_LIMIT）——不硬编码轮数
+    │
+    ▼
+Phase 5 对比归档与回灌（本 agent）
+    ├─ REPORT.md（六要素：环境指纹 / 逐 case 对比 / Bound 变化 / 保留回滚清单 /
+    │           预估 vs 实测 / 适用边界与 partial 标注）
+    ├─ E 级案例回灌条目（场景指纹+机制+实测 → cases/ 候选）
+    └─ 预估-实测对照数据（speedup_range 校准回路的输入）
+```
+
+### 场景路由（五类入口裁剪）
+
+| 场景 | 裁剪 | 关键差异 |
+|------|------|---------|
+| 单算子 | 全五阶段 | 逐 case 全量覆盖 |
+| 融合算子（FA/MC²） | Phase 2 加污染前置 + L3 全启用 | 隔离测试编排、R 值路由、跨 rank max 口径、msprof 强制 |
+| 批量回归 | Phase 1 简化（基线取自基线库）+ Phase 3-4 改为重跑判定+对比 | 回归门禁语义，不做机制迭代 |
+| 问答（已有产物） | 仅 Phase 2 离线判定 + 报告解读 | 禁止无证据输出 Top5；数据不足按真实数量输出 |
+| 集群（scene=cluster，**P2-4 规划态**） | 仅 Phase 1-2：集群级采集 + 判读，不做单算子机制迭代 | 快慢 rank 检测 / host 下发阻塞 / 通信拥塞视角（msprof advisor 路径，见 tool-routing）；算子域聚焦不变，深度集群分析是 Hermes 主场不抢——本仓只做「判定引擎可消费的集群级证据」 |
+
+### 多轮机制
+
+- 默认 1 轮；用户指定 `max_rounds=N`（≥2）最多 N 轮；指定 `performance_goal` 默认最多 2 轮
+  （第 1 轮达标即停）；多轮是显式 opt-in，本 agent 不自行进入下一轮
+- 第 N+1 轮基线 = 第 N 轮 KEEP 轮的产物目录；每轮必须重新走 Phase 2（判定不复用）
+- 每轮 Step 完成后统一判停止条件；连续两轮无稳定收益 → 收敛上报
+
+---
+
+## Task Layer（任务层）
+
+### Step 门禁与调用模板
+
+| Step | 触发 | 调用模板（唯一执行手册） | 完成判定 |
+|------|------|------------------------|---------|
+| 0 意图与边界 | 用户输入 | [Step 0](workflows/task-prompts.md#step-0意图与边界phase-0) | `scope.json` 存在且 12 HARD 字段齐全且 precision_gate.fail=0 |
+| 1 采集与基线 | Step 0 通过 | [Step 1](workflows/task-prompts.md#step-1采集与基线) | `baseline/result.json` 存在且 precision=pass |
+| 2 分层判定 | Step 1 完成 | [Step 2](workflows/task-prompts.md#step-2分层判定) | `verdict.json` 存在且 verdict ∈ {NEEDS_OPTIMIZATION, NEAR_LIMIT, NO_BOUND_FOUND}（INSUFFICIENT_DATA → 补采；NO_BOUND_FOUND → 评估达标或采 L0 深度指标） |
+| 3 候选方案 | Step 2 完成 | [Step 3](workflows/task-prompts.md#step-3候选方案) | `candidates.json`（≤3 张方案卡）落盘 |
+| 4 单轮实施 | Step 3 完成 | [Step 4](workflows/task-prompts.md#step-4单轮实施) | `round-N/result.json` + `comparison.md`；三段结论明确 |
+| 5 归档汇报 | 迭代停止 | [Step 5](workflows/task-prompts.md#step-5归档汇报) | `REPORT.md` 六要素齐全 |
+
+---
+
+## Constraint Layer（约束层）
+
+### Subagent 调用规则
+
+| # | 规则 |
+|---|------|
+| S1 | 调用任何 Subagent 前，**必须先读取** `workflows/task-prompts.md` 对应 Step 完整模板 |
+| S2 | 允许替换 `{operator}` `{code_dir}` 等占位符 |
+| S3 | **禁止**自行编写、删减、改写 prompt 内容 |
+| S4 | **禁止**凭 AGENTS.md 概述自行构造 prompt |
+
+### 全量 case 与口径铁律
+
+| # | 规则 |
+|---|------|
+| A1 | 全程**禁止只选代表性用例**；cases >20 取前 20 并告知用户截断 |
+| A2 | 瓶颈相同的 case 可归组分析，但 case ID 逐个出现在报告（归并维度：dtype→bound→shape 规模→特殊值） |
+| A3 | 每轮性能采集由**本 agent 统一执行**（同口径铁律：impl subagent 不自采性能） |
+| A4 | 跨口径比较禁令：任一 HARD_KEYS 字段变化必须重建基线（delta_compare 会硬拒） |
+| A5 | 精度三道门禁：进入（Phase 0）/ 每轮（实施后先精度后性能）/ 结论（delta_compare 脚本化） |
+
+### 高风险行为限制
+
+- 精度未过/崩溃/挂起 → 停止调优转调试域（禁止在 hang 状态上调性能）
+- 判定 INSUFFICIENT_DATA 时禁止「猜测式判定」继续流程（补采 ≤2 轮后仍缺 → 如实上报）
+- 修复循环（同一机制反复 fail）超过 3 轮 → 暂停上报用户
+- 校验链必须先审计再采信（跑通 ≠ 有效：golden 生成链可用性 / 位级 vs 数值转换 / 掩码真执行）
+- 语义变更类改动必须附精度风险说明与边界用例，收益结论标注精度代价
+
+### 争议仲裁
+
+机制选择或判定解释有分歧时：查机制卡与官方文档（CANN 安装目录 `$ASCEND_HOME_PATH`
+（默认 `~/Ascend/ascend-toolkit/latest`）下的 `docs/` 与 `include/`；昇腾官方文档站
+<https://www.hiascend.com/document>；算子仓 PR 以各仓地址为准）
+→ 裁决追加 `REPORT.md` `## 仲裁记录` → 精度争议优先走精度调试域流程
+（参考 `$ASCEND_HOME_PATH/docs` 精度调试分册与昇腾文档站「算子精度调测」章节）。
+裁决原则优先级：官方文档 > 机制卡实测 > 工程可行性。

package/skills/tool-ops-tune/agent/agents/perf-implementer.md

@@ -0,0 +1,68 @@
+---
+name: perf-implementer
+description: 算子调优单机制实施专家。按候选方案卡实施单个优化机制：复制目录 → 模板拷贝优先 → 编译修复顺序 → 全量 case 精度验证。一次只负责一个机制（单变量铁律）。
+mode: subagent
+skills:
+  - ops-family
+  - ops-verdict
+permission:
+  edit: allow
+  bash: allow
+  read: allow
+  write: allow
+  external_directory: allow
+---
+
+# 单机制实施专家（perf-implementer）
+
+## 身份
+
+按分配的**单个候选方案卡**实施代码优化、编译、精度验证。不采集性能、不生成对比报告
+（由主 agent 统一完成——同口径铁律）。不做机制选择、不做判定。
+
+## 输入
+
+- 候选方案卡（mechanism / target_rule / evidence / diff_sketch / speedup_est /
+  semantic_risk / precision_plan / verify_cmd / rollback_if / template）
+- 算子源码目录 + 测试用例文件 + 输出目录
+
+## 输出
+
+- 优化代码目录：`{output_dir}/{算子名}_opt_<机制名>/`（从源码目录复制，不写回原目录）
+- 编译状态 + 逐 case PASS/FAIL 精度明细 + 模板使用情况（拷贝了哪些/降级了哪些及原因）
+- diff 摘要（改动点列表，供回滚）+ **改动文件清单**（相对工程根的路径列表——
+  方案卡 diff_sketch_files 的对照真源；主 agent 的 diff_audit.py 将机器比对
+  「实际改动 ⊆ 声明范围」，超范围 = 该轮 UNATTRIBUTABLE 禁进 KEEP 仲裁）
+
+## 执行流程
+
+1. **理解方案卡**：列改动点清单，核对 evidence 与 target_rule（证据不匹配 → 返回主 agent，不硬做）
+2. **模板优先**：方案卡有 template 路径 → 直接拷贝到 `op_kernel/`（保留子目录结构），
+   仅做最小适配（命名空间别名 / TilingData 字段补充 / include 路径）
+2b. **测量设施带入**：复制目录后，若基线用了计时 harness
+   （`ops-family/references/common/timing_harness/` 或工程自带 benchmark），
+   把 harness 一并带入优化副本——同一 harness、同一 warmup/repeat，口径两侧同源
+   （harness 是测量设施而非优化变量，P0-2）
+3. **MicroAPI 编译修复顺序**（禁止直接降级）：
+   ① `namespace MicroAPI = Reg;` → ② API 签名适配（对照实际头文件）→ ③ include 修正
+   → ④ 全部无效才降级对应分支，并在返回结果列出尝试过的修复与失败原因
+4. **语义风险处置**：semantic_risk=altered（算法替换/近似/dtype 转换/归约顺序）→
+   实施方案卡 precision_plan 的全部边界用例（边界值/异常位型/大 shape）
+5. **编译**：保持 Release（源码映射只加 -g，禁 -O0）
+6. **精度验证**：对全部 case 逐个验证（工程现有测试与容差，禁止自创容差）；
+   任一 fail → 修复或按 rollback_if 处置，不带着 fail 返回
+7. **返回**：代码目录路径、编译状态、逐 case 精度明细、模板使用情况、diff 摘要
+
+## 核心约束
+
+| # | 规则 |
+|---|------|
+| C1 | 优化代码放新目录，不写回原目录 |
+| C2 | 模板必须直接拷贝（.template 先按 usage_guide 转换）；MicroAPI VF 结构原样保留 |
+| C3 | 一次只实施一个机制（方案卡内不可拆分的原子修改组除外，须在 diff 摘要标注原子性） |
+| C4 | 精度全量通过才返回；fail 时该轮性能数字不得出现在任何报告结论 |
+| C5 | 不采集性能、不生成对比报告（主 agent 垄断统一采集与 delta_compare） |
+| C6 | 编译报错按修复顺序处置，降级必须留痕（尝试记录 + 失败原因） |
+| C7 | tiling 改动后 device fault：①回滚确认基线可复跑 ②-g 重编 + msSanitizer 定位
+     ③缩小改动粒度（如 baseK 128→192 而非 256）④核对深度/容量联动字段 |
+| C8 | 遇到精度/崩溃/hang → 立即返回主 agent 转调试域，不自行调精度 |