cann-workbench 0.0.0-stage → 0.0.2-alpha

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "CANN Workbench",
+    "description": "Operator development and performance tuning in DSH, with session-linked tasks, live visual results, skills, knowledge bases, and execution environments."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "CANN Workbench",
+    "description": "在 DSH 中开发算子、调优性能，结合会话任务面板、实时可视化结果、技能、知识库与运行环境。"
+  }
+}

package/package.json

@@ -1,6 +1,173 @@
 {
   "name": "cann-workbench",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2-alpha",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Operator development, performance tuning and fault diagnosis in DSH, with session-linked tasks, live reports, skills, knowledge bases, and execution environments.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "lib",
+    "skills",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md",
+    "doctor/LICENSE",
+    "doctor/NOTICE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-api-gateway",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-chat",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-tool",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-api-workspace-files",
+        "@deepseek-ai/dsh-api-workspace-controller",
+        "@deepseek-ai/dsh-api-session-controller"
+      ]
+    },
+    "manifestVersion": 1
+  },
+  "scripts": {
+    "build": "tsdown && node scripts/check-client-bundle.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run && node --test doctor/tests/*.test.js",
+    "check": "pnpm typecheck && pnpm test && pnpm build",
+    "typecheck:performance": "tsc --noEmit -p tsconfig.performance-check.json",
+    "test:diagnosis:native": "node scripts/doctor-native-harness.mjs",
+    "test:diagnosis:upstream": "node scripts/doctor-native-harness.mjs --upstream",
+    "test:diagnosis:package": "node scripts/verify-doctor-package.mjs",
+    "test:e2e": "pnpm build && playwright test"
+  },
+  "engines": {
+    "node": ">=22.19",
+    "dsh": ">=0.2.1-rc.5 <0.2.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.5-alpha.1 <5",
+    "@deepseek-ai/dsh-api-session-controller": ">=0.2.1-rc.5 <0.2.2",
+    "@deepseek-ai/dsh-api-workspace-controller": ">=0.2.1-rc.5 <0.2.2",
+    "@deepseek-ai/dsh-api-workspace-files": ">=0.2.1-rc.5 <0.2.2",
+    "@deepseek-ai/dsh-client-locale": ">=0.2.1-rc.5 <0.2.2",
+    "@deepseek-ai/dsh-client-ui-chat": ">=0.2.1-rc.5 <0.2.2",
+    "@deepseek-ai/dsh-client-ui-conversation": ">=0.2.1-rc.5 <0.2.2",
+    "@deepseek-ai/dsh-client-ui-layout": ">=0.2.1-rc.5 <0.2.2",
+    "@deepseek-ai/dsh-client-ui-primitives": ">=0.2.1-rc.5 <0.2.2",
+    "@deepseek-ai/dsh-client-ui-renderer": ">=0.2.1-rc.5 <0.2.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": ">=0.2.1-rc.5 <0.2.2",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": ">=0.2.1-rc.5 <0.2.2",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.2.1-rc.5 <0.2.2",
+    "@deepseek-ai/dsh-client-ui-tool": ">=0.2.1-rc.5 <0.2.2",
+    "@deepseek-ai/dsh-commands": ">=0.2.1-rc.5 <0.2.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/dsh-api-gateway": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-api-session-controller": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-api-workspace-controller": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-api-workspace-files": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-brand": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-locale": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-product-analytics": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-shortcuts": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-store": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-ui-chat": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-ui-layout": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-ui-sidebar": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-ui-theme": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-client-ui-tool": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-commands": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-fs": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-package-manifest": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-skill": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-typert-registry": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-util-code-language": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-util-workspace-path": "0.2.1-rc.5",
+    "@playwright/test": "1.58.2",
+    "@shikijs/langs": "4.4.3",
+    "@testing-library/react": "16.3.3",
+    "@types/js-yaml": "4.0.9",
+    "@types/node": "22.20.0",
+    "@types/react": "18.3.28",
+    "@types/react-dom": "18.3.7",
+    "anser": "2.3.5",
+    "clsx": "2.1.1",
+    "immer": "10.1.3",
+    "jsdom": "29.1.1",
+    "katex": "0.18.7",
+    "mdast-util-from-markdown": "2.0.3",
+    "mdast-util-gfm": "3.1.0",
+    "mdast-util-math": "3.0.0",
+    "micromark-core-commonmark": "2.0.3",
+    "micromark-extension-gfm": "3.0.0",
+    "micromark-extension-math": "3.1.0",
+    "micromark-factory-space": "2.0.1",
+    "micromark-util-character": "2.1.1",
+    "micromark-util-classify-character": "2.0.1",
+    "micromark-util-decode-string": "2.0.1",
+    "micromark-util-sanitize-uri": "2.0.1",
+    "micromark-util-symbol": "2.0.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "react-test-renderer": "18.3.1",
+    "shiki": "4.4.3",
+    "simple-icons": "16.31.0",
+    "tsdown": "0.22.14",
+    "typescript": "6.0.3",
+    "unrun": "^0.3.1",
+    "vite": "8.3.5",
+    "vitest": "4.1.8",
+    "zustand": "5.0.8"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-session": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-session-projection": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-util-values": "0.2.1-rc.5",
+    "@deepseek-ai/dsh-workspace": "0.2.1-rc.5",
+    "@deepseek-ai/schemastery": "3.18.5-alpha.1",
+    "ajv": "8.17.1",
+    "ajv-formats": "3.0.1",
+    "d3-flame-graph": "5.0.0",
+    "d3-selection": "3.0.0",
+    "diff": "8.0.2",
+    "echarts": "6.1.0",
+    "js-yaml": "4.1.1",
+    "zod": "4.4.3"
+  }
+}

package/skills/asc-tools/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/asc-tools/tool-ops-tune/LICENSE

@@ -0,0 +1,38 @@
+CANN Open Software License Agreement Version 2.0
+
+This CANN Open Software License Agreement Version 2.0 (hereinafter referred to as this "Agreement") is a legal agreement between you and Huawei, and it governs your use, modification, or distribution of CANN Open Software (hereinafter referred to as "Software"). Please read this Agreement carefully.
+
+If you are entering into this Agreement on behalf of a company or other legal entity, you represent that you have the legal authority to bind that entity to this Agreement, in which case "you" will mean the entity you represent.
+
+BY DOWNLOADING, INSTALLING, OR USING THE SOFTWARE, YOU AGREE YOU HAVE FULLY UNDERSTOOD AND ACCEPTED THE TERMS CONTAINED HEREIN. IF YOU DO NOT AGREE TO ANY OF THE TERMS OF THIS AGREEMENT, OR IF YOU DO NOT QUALIFY FOR AGREEING TO THIS AGREEMENT, YOU ARE NOT AUTHORIZED TO AND SHALL NOT DOWNLOAD, INSTALL, OR MAKE ANY USE OF THE SOFTWARE.
+
+1. Definition
+
+1.1   Software means the APIs, source code files, binaries, and related documents of Compute Architecture for Neural Networks("CANN") that are licensable by Huawei, and provided and licensed under this Agreement.
+
+1.2   Huawei AI Processors mean AI chipsets (i) branded with "Ascend", "Kirin"," Yueying" or other brands owned or controlled by Huawei; or (ii) manufactured (including have manufactured), supplied (including have supplied) or designed (including have designed) by Huawei.
+
+2.  Grant of Intellectual Property Rights
+2.1 Subject to the terms and conditions of this Agreement, including your full compliance thereof, Huawei hereby grants you a limited, worldwide, royalty-free, non-transferable, non-sublicensable, and revocable license for you to (i) download, use, modify, integrate, and distribute the Software or its derivative works for the purpose of developing software solely for use in systems with Huawei AI Processors and/or Software, and (ii) distribute any software developed based upon Software and/or its derivative works solely for use in systems with Huawei AI Processors and/or Software.
+
+3.  Restrictions
+3.1 You are not authorized to, and shall not use, modify, or distribute this Software or its derivative works for any other purposes than those expressly permitted by this Agreement. You shall not make any use of the Software or its derivative works to develop or distribute any software for use in systems with processors other than Huawei AI Processors. All rights not expressly granted herein are expressly reserved by Huawei.
+
+3.2 You are not authorized to, and shall not remove, obscure, or alter any copyright or other notices in this Software or any part of it.
+
+3.3 Distribution Restrictions
+You may distribute the Software or its derivative works in any medium, whether in source or executable forms, for the purpose stipulated in Section 2; provided that you provide recipients with a copy of this Agreement, and retain all notices in the Software.
+
+4. Disclaimer of Warranty and Limitation of Liability
+THE SOFTWARE IS PROVIDED WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL HUAWEI OR ANY OTHER COPYRIGHT HOLDER BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO ANY DIRECT, OR INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM YOUR USE OR INABILITY TO USE THE SOFTWARE, IN WHOLE OR IN PART, NO MATTER HOW IT IS CAUSED OR THE LEGAL THEORY IT IS BASED ON, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+5. Termination
+5.1 This Agreement will continue to apply until terminated by either you or Huawei as described below:
+a．You may terminate this Agreement by ceasing your use of the Software;
+b.  Huawei may at any time, terminate this Agreement if: (i) you fail to comply with any term of this Agreement; or (ii) you directly or indirectly initiate any legal proceeding against any individual or entity by alleging that the Software or any part of it infringes your intellectual property rights.
+5.2 By termination, all the rights granted to you under this Agreement are terminated, and you shall cease to use and delete this Software or any derivative works immediately. All rights granted to you under this Agreement shall hereby be void ab initio in the event of termination in accordance with Section 5.1. b above. Huawei reserves the right to pursue any and all legal remedies available to enforce the terms and conditions of this Agreement or to protect Huawei’s intellectual property rights for such breach or violation. All provisions shall survive the termination of this Agreement except for Section 2 and Section 3.3.
+
+6. MISCELLANEOUS
+If the application of any provision of this Agreement to any particular facts or circumstances is held to be invalid or unenforceable by a court of competent jurisdiction, then (a) the validity and enforceability of such provision as applied to any other particular facts or circumstances and the validity of other provisions of this Agreement shall not in any way be affected or impaired thereby and (b) such provision shall be enforced to the maximum extent possible so as to affect the intent of the you and Huawei and reformed without further action by you and Huawei to the extent necessary to make such provision valid and enforceable.
+
+END OF THE TERMS AND CONDITIONS

package/skills/asc-tools/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 a2 \
+    --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/asc-tools/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 a2 \
+    --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%）内宣称收益 |