Star61
26
代码
代码
Issues4
Pull Requests7
Actions
项目讨论
Wiki
分析
Star61
26
已合并
迁移 CANNBot 插件编排与交付仓库 #1
chendunyang创建于 23 天前
迁移 CANNBot 插件编排与交付仓库 #1
已合并
chendunyang创建于 23 天前
从qq_37913898/cannbotmigration/import-cannbot-test合入到cann/cannbotmaster
共 106 个文件变更+11189-2
A.claude-plugin/marketplace.json+176-0
@@ -0,0 +1,176 @@
1+{
2+ "name": "cannbot",
3+ "description": "CANNBot official plugins and their pinned Skill bundles for CANN and Ascend NPU development.",
4+ "owner": {
5+ "name": "CANNBot",
6+ "url": "https://gitcode.com/cann/cannbot"
7+ },
8+ "plugins": [
9+ {
10+ "name": "ops-direct-invoke-skills",
11+ "description": "Skills used by the Ascend C Kernel direct-invocation workflow.",
12+ "source": {
13+ "source": "git-subdir",
14+ "url": "https://gitcode.com/cann/cannbot-skills.git",
15+ "path": "ops",
16+ "sha": "38728be73688df97a84d9570a24dae616ea4542e"
17+ },
18+ "strict": false,
19+ "version": "1.0.5",
20+ "author": {
21+ "name": "CANNBot"
22+ },
23+ "category": "skills",
24+ "skills": [
25+ "./ascendc-api-best-practices",
26+ "./ascendc-regbase-best-practice",
27+ "./ascendc-blaze-best-practice",
28+ "./ascendc-blaze-migration",
29+ "./ascendc-code-review",
30+ "./ascendc-direct-invoke-template",
31+ "./ascendc-docs-search",
32+ "./ascendc-env-check",
33+ "./npu-arch",
34+ "./ascendc-precision-debug",
35+ "./ascendc-runtime-debug",
36+ "./ascendc-crash-debug",
37+ "./ascendc-tiling-design",
38+ "./ops-precision-standard",
39+ "./ops-profiling",
40+ "./torch-ascendc-op-extension",
41+ "./ascendc-mc2-best-practice"
42+ ]
43+ },
44+ {
45+ "name": "infra-skills",
46+ "description": "GitCode collaboration Skills used by CANNBot workflows.",
47+ "source": {
48+ "source": "git-subdir",
49+ "url": "https://gitcode.com/cann/cannbot-skills.git",
50+ "path": "infra",
51+ "sha": "38728be73688df97a84d9570a24dae616ea4542e"
52+ },
53+ "strict": false,
54+ "version": "1.1.0",
55+ "author": {
56+ "name": "CANNBot"
57+ },
58+ "category": "skills",
59+ "skills": [
60+ "./gitcode-toolkit",
61+ "./gitcode-pr-handler",
62+ "./gitcode-issue-gen",
63+ "./gitcode-issue-handler"
64+ ]
65+ },
66+ {
67+ "name": "ascendc-st-design-skills",
68+ "description": "Skill used by the Ascend C system test design workflow.",
69+ "source": {
70+ "source": "git-subdir",
71+ "url": "https://gitcode.com/cann/cannbot-skills.git",
72+ "path": "ops",
73+ "sha": "38728be73688df97a84d9570a24dae616ea4542e"
74+ },
75+ "strict": false,
76+ "version": "1.0.0",
77+ "author": {
78+ "name": "CANNBot"
79+ },
80+ "category": "skills",
81+ "skills": [
82+ "./ascendc-st-design"
83+ ]
84+ },
85+ {
86+ "name": "model-infer-skills",
87+ "description": "Skills used by the NPU model inference optimization workflow.",
88+ "source": {
89+ "source": "git-subdir",
90+ "url": "https://gitcode.com/cann/cannbot-skills.git",
91+ "path": "model",
92+ "sha": "38728be73688df97a84d9570a24dae616ea4542e"
93+ },
94+ "strict": false,
95+ "version": "1.2.0",
96+ "author": {
97+ "name": "CANNBot"
98+ },
99+ "category": "skills",
100+ "skills": [
101+ "./model-infer-migrator",
102+ "./model-infer-parallel-analysis",
103+ "./model-infer-parallel-impl",
104+ "./model-infer-kvcache",
105+ "./model-infer-fusion",
106+ "./model-infer-quantization",
107+ "./model-infer-graph-mode",
108+ "./model-infer-precision-debug",
109+ "./model-infer-runtime-debug",
110+ "./model-infer-multi-stream",
111+ "./model-infer-prefetch",
112+ "./model-infer-superkernel",
113+ "./model-infer-profiling",
114+ "./model-infer-perf-breakdown"
115+ ]
116+ },
117+ {
118+ "name": "ops-direct-invoke",
119+ "source": "./plugins/ops-direct-invoke",
120+ "description": "Ascend C Kernel 直调算子开发 Team。含完整工作流（设计→实现→审查→性能验收）、4 个专业 Agent 和工程模板。",
121+ "version": "1.2.5",
122+ "author": {
123+ "name": "CANNBot"
124+ },
125+ "keywords": [
126+ "ascendc",
127+ "kernel",
128+ "direct-invoke",
129+ "operator"
130+ ],
131+ "category": "development",
132+ "dependencies": [
133+ "ops-direct-invoke-skills",
134+ "infra-skills"
135+ ]
136+ },
137+ {
138+ "name": "ascendc-st-design",
139+ "source": "./plugins/ascendc-st-design",
140+ "description": "Ascend C 算子系统测试（ST）设计工作流。",
141+ "version": "1.0.0",
142+ "author": {
143+ "name": "CANNBot"
144+ },
145+ "keywords": [
146+ "ascend-c",
147+ "operator-testing",
148+ "st-design"
149+ ],
150+ "category": "development",
151+ "dependencies": [
152+ "ascendc-st-design-skills"
153+ ]
154+ },
155+ {
156+ "name": "model-infer-optimize",
157+ "source": "./plugins/model-infer-optimize",
158+ "description": "NPU 模型推理端到端优化 Team。涵盖从零适配到 baseline 的固定阶段优化（并行、KVCache/FA、融合算子、量化、图模式），以及 baseline 之上 profiling 驱动的探索式优化（多方向发现候选、Plan/round 自循环，按需调用多流、预取、SuperKernel 等单点优化）。含两条 workflow 与 9 个 Subagent。",
159+ "version": "1.0.6",
160+ "author": {
161+ "name": "CANNBot"
162+ },
163+ "keywords": [
164+ "model-infer",
165+ "npu",
166+ "pytorch",
167+ "inference",
168+ "orchestrator"
169+ ],
170+ "category": "development",
171+ "dependencies": [
172+ "model-infer-skills"
173+ ]
174+ }
175+ ]
176+}
A.gitattributes+58-0
@@ -0,0 +1,58 @@
1+# C/C++ sources
2+*.c text eol=lf
3+*.cc text eol=lf
4+*.cpp text eol=lf
5+*.cxx text eol=lf
6+*.h text eol=lf
7+*.hpp text eol=lf
8+*.hh text eol=lf
9+ 
10+# Python
11+*.py text eol=lf
12+ 
13+# Shell scripts
14+*.sh text eol=lf
15+*.bash text eol=lf
16+ 
17+# Documentation and configuration
18+*.md text eol=lf
19+*.xml text eol=lf
20+*.yaml text eol=lf
21+*.yml text eol=lf
22+*.json text eol=lf
23+*.toml text eol=lf
24+*.txt text eol=lf
25+*.cfg text eol=lf
26+*.ini text eol=lf
27+ 
28+# Web
29+*.js text eol=lf
30+*.ts text eol=lf
31+*.css text eol=lf
32+*.html text eol=lf
33+*.svg text eol=lf
34+ 
35+# CMake and Docker
36+CMakeLists.txt text eol=lf
37+*.cmake text eol=lf
38+Dockerfile text eol=lf
39+ 
40+# Binary files
41+*.png binary
42+*.jpg binary
43+*.jpeg binary
44+*.gif binary
45+*.ico binary
46+*.pdf binary
47+*.woff binary
48+*.woff2 binary
49+*.mp4 binary
50+*.webm binary
51+*.so binary
52+*.o binary
53+*.a binary
54+*.zip binary
55+*.tar binary
56+*.tgz binary
57+*.gz binary
58+*.whl binary
A.gitignore+3-0
@@ -0,0 +1,3 @@
1+*.tgz
2+node_modules/
3+dist/
A.gitmodules+5-0
@@ -0,0 +1,5 @@
1+[submodule "vendor/cannbot-skills"]
2+ path = vendor/cannbot-skills
3+ url = https://gitcode.com/cann/cannbot-skills.git
4+ branch = master
5+ shallow = true
ACHANGELOG.md+69-0
@@ -0,0 +1,69 @@
1+# Changelog
2+ 
3+This file records notable changes to the CANNBot plugin orchestration and delivery repository.
4+ 
5+## 1.3.2 - 2026-08-31
6+ 
7+### Changed
8+ 
9+- Switched plugin homepage URLs to the canonical production HTTPS endpoint.
10+ 
11+## 1.3.1 - 2026-08-31
12+ 
13+### Changed
14+ 
15+- Aligned plugin homepage URLs with the production HTTP endpoint.
16+- Added the static CANNBot plugin portal and aligned its operator test page with `ascendc-st-design`.
17+ 
18+## 1.3.0 - 2026-08-31
19+ 
20+### Added
21+ 
22+- Added repository-level CANN Open Software License 2.0 metadata and OAT compliance configuration.
23+- Added a Claude Code marketplace catalog for the three official plugins.
24+- Added Git text normalization and binary file rules.
25+- Added per-plugin license delivery and npm package installation smoke tests.
26+- Added the `ascendc-st-design` plugin for L0/L1/L2 system test design.
27+ 
28+### Changed
29+ 
30+- Standardized repository metadata on the official URL, `https://gitcode.com/cann/cannbot`.
31+- Unified npm and source installations behind the same Node.js installer.
32+- Added plugin-level `init.sh` adapters for source installations.
33+- Made source installation initialize the Skill submodule only when required.
34+- Renamed `npm/` to `script/` and `plugin-official/` to `plugins/`.
35+- Added the repository architecture, directory responsibilities, and release flow to the root README.
36+- Made plugin instructions and installation records coexist across multiple installed plugins.
37+- Renamed the internal CLI entry point to `cannbot.js`.
38+ 
39+## 1.2.2 - 2026-08-21
40+ 
41+### Changed
42+ 
43+- Moved npm tooling into its own directory.
44+- Enabled shallow initialization of the Skill submodule.
45+ 
46+## 1.2.1 - 2026-08-21
47+ 
48+### Changed
49+ 
50+- Established `cannbot-skills` as the single Skill source through a pinned Git submodule.
51+- Added build-time plugin assembly for npm packages.
52+ 
53+## 1.2.0 - 2026-08-21
54+ 
55+### Changed
56+ 
57+- Made published official plugins self-contained so npm users do not clone the Skill repository.
58+ 
59+## 1.1.0 - 2026-08-21
60+ 
61+### Added
62+ 
63+- Added packaged official plugins and native plugin initialization support.
64+ 
65+## 1.0.0 - 2026-08-19
66+ 
67+### Added
68+ 
69+- Published the cross-client installer as `@cannbot-plugin/cannbot`.
ALICENSE+38-0
@@ -0,0 +1,38 @@
1+CANN Open Software License Agreement Version 2.0
2+ 
3+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.
4+ 
5+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.
6+ 
7+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.
8+ 
9+1. Definition
10+ 
11+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.
12+ 
13+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.
14+ 
15+2. Grant of Intellectual Property Rights
16+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.
17+ 
18+3. Restrictions
19+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.
20+ 
21+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.
22+ 
23+3.3 Distribution Restrictions
24+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.
25+ 
26+4. Disclaimer of Warranty and Limitation of Liability
27+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.
28+ 
29+5. Termination
30+5.1 This Agreement will continue to apply until terminated by either you or Huawei as described below:
31+a．You may terminate this Agreement by ceasing your use of the Software;
32+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.
33+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.
34+ 
35+6. MISCELLANEOUS
36+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.
37+ 
38+END OF THE TERMS AND CONDITIONS
AOAT.xml+49-0
@@ -0,0 +1,49 @@
1+<?xml version="1.0" encoding="UTF-8"?>
2+<!-- Copyright (c) 2026 Huawei Technologies Co., Ltd.
3+ This program is free software, you can redistribute it and/or modify it under the terms and conditions of
4+ CANN Open Software License Agreement Version 2.0 (the "License").
5+ Please refer to the License for details. You may not use this file except in compliance with the License.
6+ THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
7+ INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
8+ See LICENSE in the root of the software repository for the full text of the License.
9+-->
10+ 
11+<configuration>
12+ <oatconfig>
13+ <licensefile></licensefile>
14+ <policylist>
15+ <policy name="projectPolicy" desc="CANNBot repository default license policy">
16+ <policyitem type="license" name="CANN-2.0" path=".*" filefilter="licenseFileNamePolicyFilter" desc="The repository default license is CANN-2.0; explicitly licensed components are excluded below."/>
17+ </policy>
18+ </policylist>
19+ <filefilterlist>
20+ <filefilter name="defaultFilter" desc="Files not checked by the root repository scan">
21+ <filteritem type="filepath" name="vendor/cannbot-skills/.*" desc="Git submodule with its own license and OAT configuration."/>
22+ </filefilter>
23+ <filefilter name="defaultPolicyFilter" desc="Filters for compatibility and license header policies">
24+ </filefilter>
25+ <filefilter name="copyrightPolicyFilter" desc="Filters for copyright header policies">
26+ </filefilter>
27+ <filefilter name="licenseFileNamePolicyFilter" desc="Explicitly licensed components excluded from the repository default license policy">
28+ <filteritem type="filepath" name="script/.*" desc="The npm installer is distributed under the MIT License in script/LICENSE."/>
29+ <filteritem type="filepath" name="vendor/cannbot-skills/.*" desc="Git submodule distributed under its own repository license."/>
30+ </filefilter>
31+ <filefilter name="readmeFileNamePolicyFilter" desc="Filters for README file policies">
32+ </filefilter>
33+ <filefilter name="binaryFileTypePolicyFilter" desc="Filters for binary file policies">
34+ </filefilter>
35+ </filefilterlist>
36+ <licensematcherlist>
37+ <licensematcher name="CANN-2.0" desc="Text matcher for the repository default license">
38+ <licensetext name="
39+ This program is free software, you can redistribute it and/or modify it under the terms and conditions of
40+ CANN Open Software License Agreement Version 2.0 (the &quot;License&quot;).
41+ Please refer to the License for details. You may not use this file except in compliance with the License.
42+ THIS SOFTWARE IS PROVIDED ON AN &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
43+ INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
44+ See LICENSE in the root of the software repository for the full text of the License.
45+ " desc=""/>
46+ </licensematcher>
47+ </licensematcherlist>
48+ </oatconfig>
49+</configuration>
MREADME.md+266-2
@@ -1,3 +1,267 @@
1-# cannbot1+# CANNBot
2 2 
3-cannbot应用仓，对外提供plugin、harness等接入能力3+[![npm](https://img.shields.io/npm/v/%40cannbot-plugin%2Fcannbot?style=flat-square&label=npm)](https://www.npmjs.com/package/@cannbot-plugin/cannbot)
4+![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white)
5+![Platform](https://img.shields.io/badge/Platform-Ascend%20NPU-orange?style=flat-square)
6+![Clients](https://img.shields.io/badge/Clients-OpenCode%20%7C%20Codex%20%7C%20Claude%20Code%20%7C%20TRAE%20%7C%20DSH-blue?style=flat-square)
7+ 
8+🌐 [官方网站](https://cann.cannbot.cn) · 📦 [官方插件](plugins/) · 🧩 [安装与发布](script/) · 📖 [工作流指南](script/docs/cannbot-workflows.md) · 🧠 [CANNBot Skills](https://gitcode.com/cann/cannbot-skills)
9+ 
10+---
11+ 
12+## 项目概述
13+ 
14+**CANNBot** 面向 CANN 与昇腾 NPU 开发场景，提供可组合的 Agent 插件、专业角色和工程工作流，帮助开发者通过自然语言完成算子开发、算子测试、模型迁移与推理优化等任务。
15+ 
16+本仓库是 CANNBot 的**插件编排与交付仓库**，主要维护：
17+ 
18+- 官方插件的 Agents、Workflows、Hooks、客户端清单与安装声明；
19+- 面向 OpenCode、Codex、Claude Code、TRAE 和 DSH 的统一安装器；
20+- npm 自包含发布包的组装、测试与发布流程。
21+ 
22+可复用 Skill 源码不在本仓库重复维护，其唯一源码来源是 [cann/cannbot-skills](https://gitcode.com/cann/cannbot-skills)。本仓库通过 Git submodule 锁定经过验证的 Skill 版本，并通过插件声明选择、组装和发布所需能力。
23+ 
24+## 仓库定位与分工
25+ 
26+| 维度 | 本仓库 `cannbot` | `cannbot-skills` 仓库 |
27+|------|------------------|----------------------|
28+| 核心职责 | 插件编排、安装交付、npm 发布 | 可复用 Skill 的设计、实现、测试与治理 |
29+| 主要资产 | Plugins、Agents、Workflows、Hooks、安装器 | `SKILL.md`、领域知识、脚本、模板、参考资料 |
30+| 复用方式 | 用 `plugin-sources.json` 声明插件需要的 Skills | 按领域提供稳定、可独立安装的 Skills |
31+| 版本关系 | 通过 `vendor/cannbot-skills` 锁定确定的 commit | 独立演进并发布新的能力版本 |
32+| 面向对象 | 插件用户、集成开发者、npm 发布维护者 | Skill 使用者、领域专家、Skill 贡献者 |
33+ 
34+职责划分遵循以下原则：
35+ 
36+1. **Skill 单一源码**：领域能力只在 `cannbot-skills` 中维护，避免两仓内容漂移。
37+2. **插件就近编排**：Agents、Workflows、Hooks 和依赖声明与插件放在一起，便于端到端演进。
38+3. **统一安装实现**：npm 安装与源码安装只在插件 bundle 的来源上不同，后续共用同一安装流程。
39+4. **可复现发布**：npm 包使用 submodule 锁定的 commit 进行组装，用户安装时不再拉取 Skill 仓库。
40+ 
41+## 快速开始
42+ 
43+### 前置条件
44+ 
45+- Node.js 20 或更高版本；
46+- OpenCode、Codex、Claude Code、TRAE 或 DSH 中的任意一种；
47+- 使用源码安装时需要 Git。
48+ 
49+### npm 一键安装
50+ 
51+在目标项目目录中执行：
52+ 
53+```bash
54+npx @cannbot-plugin/cannbot@latest install ops-direct-invoke --tool opencode
55+```
56+ 
57+完整命令格式：
58+ 
59+```bash
60+npx @cannbot-plugin/cannbot@latest install <plugin-id> \
61+ --tool <opencode|codex|claude|trae|dsh> \
62+ --target /path/to/target-project
63+```
64+ 
65+进入目标项目后可以省略 `--target`。
66+ 
67+### 源码安装
68+ 
69+推荐在克隆主仓时同时拉取 submodule：
70+ 
71+```bash
72+git clone --recurse-submodules --shallow-submodules \
73+ https://gitcode.com/cann/cannbot.git
74+cd cannbot/plugins/ops-direct-invoke
75+bash init.sh
76+```
77+ 
78+`init.sh` 默认使用 OpenCode 并安装到当前目录。安装到其他项目或客户端时传入参数：
79+ 
80+```bash
81+bash init.sh project claude /path/to/target-project
82+```
83+ 
84+如果普通 `git clone` 没有拉取 submodule，源码安装器会在组装插件前自动初始化 `vendor/cannbot-skills`。
85+ 
86+## 官方插件
87+ 
88+| 插件 | 领域 | 能力说明 |
89+|------|------|----------|
90+| [`ops-direct-invoke`](plugins/ops-direct-invoke/) | Ascend C 算子开发 | Kernel 直调开发工作流，覆盖需求分析、方案设计、实现、审查、精度与性能验收 |
91+| [`ascendc-st-design`](plugins/ascendc-st-design/) | Ascend C 算子测试 | 基于 aclnn 接口文档完成参数定义、测试因子、约束分析及 L0/L1/L2 ST 用例设计 |
92+| [`model-infer-optimize`](plugins/model-infer-optimize/) | NPU 模型推理 | 从模型迁移、baseline 建立到精度对齐、profiling 分析和端到端性能优化 |
93+ 
94+使用 `ascendc-st-design` 的生成脚本还需要 Python 3，以及 PyYAML、NumPy 和 pandas。可以在安装插件后用以下命令检查运行环境：
95+ 
96+```bash
97+python3 -c "import yaml, numpy, pandas"
98+```
99+ 
100+社区插件统一规划在 [`plugins-community/`](plugins-community/) 中，与官方插件保持清晰的准入和发布范围。
101+ 
102+## 项目架构
103+ 
104+### 双仓协作架构
105+ 
106+`plugin-sources.json` 是插件编排仓与 Skill 源码仓之间的关键接口（seam）：Skill 仓可以独立演进，本仓只需要更新 submodule commit 和插件映射，无需复制或修改 Skill 源码。
107+ 
108+```mermaid
109+flowchart LR
110+ SKILL_REPO["cannbot-skills<br/>Skill 唯一源码仓"]
111+ SUBMODULE["vendor/cannbot-skills<br/>锁定验证 commit"]
112+ PLUGIN_DEF["plugins/&lt;plugin-id&gt;<br/>Agents · Workflows · Hooks"]
113+ MAPPING["plugin-sources.json<br/>Skill 选择映射"]
114+ ASSEMBLER["Bundle Assembler<br/>script/lib/plugin-bundle.js"]
115+ DIST["script/dist/plugins<br/>自包含插件 bundle"]
116+ NPM["@cannbot-plugin/cannbot<br/>npm 发布包"]
117+ 
118+ SKILL_REPO -->|Git submodule| SUBMODULE
119+ PLUGIN_DEF --> MAPPING
120+ SUBMODULE --> MAPPING
121+ MAPPING --> ASSEMBLER
122+ PLUGIN_DEF --> ASSEMBLER
123+ ASSEMBLER --> DIST
124+ DIST --> NPM
125+```
126+ 
127+### 统一安装架构
128+ 
129+npm 与源码安装共享一个深模块。两个 Adapter 分别解析“发布包 bundle”和“源码 bundle”，在获得标准插件目录后，Skills、Agents、Workflows、Hooks、依赖仓和客户端配置全部由同一实现完成。
130+ 
131+```mermaid
132+flowchart TD
133+ USER{安装入口}
134+ NPX["npx 安装<br/>下载自包含 npm 包"]
135+ SOURCE["源码安装<br/>plugins/&lt;id&gt;/init.sh"]
136+ PACKAGED["dist/plugins/&lt;id&gt;<br/>发布包 Adapter"]
137+ CHECK["检查并按需初始化<br/>vendor/cannbot-skills"]
138+ CACHE["组装当前插件<br/>~/.cache/cannbot/source/&lt;version&gt;/&lt;id&gt;"]
139+ INSTALLER["统一安装器<br/>script/bin/cannbot.js"]
140+ OUTPUT["目标项目<br/>Skills · Agents · Workflows · Hooks · Dependencies"]
141+ CLIENTS["OpenCode · Codex · Claude Code · TRAE · DSH"]
142+ 
143+ USER --> NPX
144+ USER --> SOURCE
145+ NPX --> PACKAGED
146+ SOURCE --> CHECK
147+ CHECK --> CACHE
148+ PACKAGED --> INSTALLER
149+ CACHE --> INSTALLER
150+ INSTALLER --> OUTPUT
151+ OUTPUT --> CLIENTS
152+```
153+ 
154+npm 用户安装时不会拉取 `cannbot-skills` submodule；Skill 内容已经在发布前复制进 npm 包。源码用户只有在 submodule 尚未初始化时，才会在执行 `init.sh` 的 bundle 解析阶段拉取 Skill 仓库。
155+ 
156+## 目录规划
157+ 
158+```text
159+cannbot/
160+├── plugins/ # 官方插件编排与发布定义
161+│ └── <plugin-id>/
162+│ ├── .claude-plugin/ # Claude Plugin manifest
163+│ ├── .codex-plugin/ # Codex Plugin manifest
164+│ ├── agents/ # 专业角色定义
165+│ ├── workflows/ # 端到端工作流与模板
166+│ ├── hooks/ # 可选客户端 Hooks
167+│ ├── AGENTS.md # 插件级协作说明
168+│ ├── plugin-sources.json # Skill 仓映射
169+│ ├── plugin-install.json # 可选依赖仓声明
170+│ └── init.sh # 源码安装薄入口
171+├── plugins-community/ # 社区插件预留目录
172+├── script/ # npm 工程与统一安装模块
173+│ ├── bin/ # CLI 与源码安装 Adapter
174+│ ├── lib/ # 插件 bundle 组装模块
175+│ ├── scripts/ # 构建脚本
176+│ ├── test/ # 安装行为测试
177+│ └── docs/ # 安装和工作流文档
178+└── vendor/
179+ └── cannbot-skills/ # Skill 仓 Git submodule
180+```
181+ 
182+### 插件目录契约
183+ 
184+| 文件或目录 | 是否必需 | 作用 |
185+|------------|----------|------|
186+| `.claude-plugin/plugin.json` | 是 | 插件 ID、版本、描述、Skills 与 Agents 清单 |
187+| `.codex-plugin/plugin.json` | 是 | Codex 插件发现与展示元数据 |
188+| `plugin-sources.json` | 是 | 将插件声明映射到 Skill 仓中的具体路径 |
189+| `init.sh` | 是 | 源码安装入口，仅负责转交插件、工具、目标和源码位置 |
190+| `AGENTS.md`、`agents/` | 可选 | 插件级指令与专业角色 |
191+| `workflows/`、`hooks/` | 可选 | 工作流资产和客户端生命周期扩展 |
192+| `plugin-install.json` | 可选 | 插件所需外部依赖仓及项目暴露路径 |
193+ 
194+## Submodule 与发布流程
195+ 
196+### Skill 版本映射
197+ 
198+每个插件通过 `plugin-sources.json` 指定 Skill 仓和所需目录，例如：
199+ 
200+```json
201+{
202+ "skillsRepository": "vendor/cannbot-skills",
203+ "skills": [
204+ "ops/ascendc-st-design"
205+ ]
206+}
207+```
208+ 
209+构建器会校验插件 manifest 与映射文件中的 Skill 集合是否一致，并拒绝缺失、越界或重复的 Skill 路径。
210+ 
211+### npm 发布
212+ 
213+```bash
214+git submodule update --init --recursive --depth 1
215+npm --prefix script test
216+npm --prefix script run build:plugins
217+npm --prefix script run pack:check
218+npm --prefix script run pack:smoke
219+```
220+ 
221+执行 `npm publish` 时，`prepublishOnly` 会先运行完整测试和实际 tgz 安装 smoke test，`prepack` 再重新组装 `script/dist/plugins/`。发布产物包含完整 Skill 内容，因此 npm 用户获得的是可离线解析的固定版本 bundle。
222+ 
223+### 更新 Skill 版本
224+ 
225+1. 执行 `npm --prefix script run skills:update` 显式拉取 `cannbot-skills/master` 最新提交；
226+2. 核对各插件的 `plugin-sources.json`；
227+3. 运行完整安装测试和打包检查；
228+4. 提交新的 submodule gitlink；
229+5. 按语义化版本规则更新并发布 npm 包。
230+ 
231+普通构建和发布始终使用 gitlink 锁定的 Skill 提交，不会自动跟随远程分支，以保证产物可复现。
232+ 
233+## 开发与验证
234+ 
235+```bash
236+# 完整测试：覆盖源码/发布包两种来源和五种客户端
237+npm --prefix script test
238+ 
239+# 重新组装插件 bundle
240+npm --prefix script run build:plugins
241+ 
242+# 检查 npm 发布内容
243+npm --prefix script run pack:check
244+ 
245+# 通过实际 tgz 和 npm bin 验证安装
246+npm --prefix script run pack:smoke
247+```
248+ 
249+测试以统一安装器的外部 interface 为主要验证面，覆盖 Skills/Agents 复制、工作流资产、Claude Hooks、重复安装、依赖仓声明以及源码 `init.sh` Adapter。
250+ 
251+## 修改应该提交到哪里
252+ 
253+| 修改类型 | 提交位置 |
254+|----------|----------|
255+| Skill 知识、脚本、模板或参考资料 | [`cannbot-skills`](https://gitcode.com/cann/cannbot-skills) |
256+| 官方插件的 Agents、Workflows、Hooks 或 Skill 组合 | 本仓库 [`plugins/`](plugins/) |
257+| 社区插件 | 本仓库 [`plugins-community/`](plugins-community/) |
258+| npm 安装、bundle 组装或客户端适配 | 本仓库 [`script/`](script/) |
259+| Skill 版本升级 | Skill 仓先合入，本仓再更新 submodule gitlink |
260+ 
261+## 许可证与免责声明
262+ 
263+- 本仓库默认适用根目录 [`LICENSE`](LICENSE) 中的 CANN Open Software License Agreement Version 2.0，官方插件使用相同许可证。
264+- npm 包为混合许可证分发：安装器实现适用 MIT License，组装的官方插件和 Skills 保留各自许可证，详见 [`script/LICENSE`](script/LICENSE) 及各插件产物中的许可文件。
265+- submodule 内容遵循 `cannbot-skills` 仓库自身的许可证。
266+ 
267+CANNBot 生成或修改的代码仍需开发者完成编译、测试、精度验证、性能验证和安全审查后再投入使用。
Aplugins-community/.gitkeep+1-0
@@ -0,0 +1 @@
1+ 
Aplugins/LICENSE+38-0
@@ -0,0 +1,38 @@
1+CANN Open Software License Agreement Version 2.0
2+ 
3+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.
4+ 
5+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.
6+ 
7+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.
8+ 
9+1. Definition
10+ 
11+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.
12+ 
13+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.
14+ 
15+2. Grant of Intellectual Property Rights
16+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.
17+ 
18+3. Restrictions
19+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.
20+ 
21+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.
22+ 
23+3.3 Distribution Restrictions
24+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.
25+ 
26+4. Disclaimer of Warranty and Limitation of Liability
27+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.
28+ 
29+5. Termination
30+5.1 This Agreement will continue to apply until terminated by either you or Huawei as described below:
31+a．You may terminate this Agreement by ceasing your use of the Software;
32+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.
33+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.
34+ 
35+6. MISCELLANEOUS
36+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.
37+ 
38+END OF THE TERMS AND CONDITIONS
Aplugins/README.md+15-0
@@ -0,0 +1,15 @@
1+# CANNBot managed plugins
2+ 
3+This directory contains the self-contained plugins in the official CANNBot catalog:
4+ 
5+- `ops-direct-invoke`
6+- `ascendc-st-design`
7+- `model-infer-optimize`
8+ 
9+Each plugin declares the Skills it needs in `plugin-sources.json`. The actual Skill source is maintained in the `vendor/cannbot-skills` submodule and is not duplicated in this repository.
10+ 
11+`npm --prefix script run build:plugins` copies the declared Skills into `script/dist/plugins/<plugin-id>/skills/`. Every direct child in that generated directory is a discoverable Skill, keeping the published layout valid for Codex, Claude Code, OpenCode, TRAE, and DSH.
12+ 
13+The submodule is currently pinned to `cann/cannbot-skills` commit `38728be73688df97a84d9570a24dae616ea4542e`. To consume an update, move the submodule commit, verify each plugin mapping, run `npm --prefix script test`, and bump the npm package version so users receive a new immutable cache directory.
14+ 
15+Each plugin includes a thin `init.sh` source adapter. It delegates to the same Node installer used by the published npm package; installation behavior is not implemented in the plugin scripts. Optional dependency repositories are declared in `plugin-install.json`.
Aplugins/ascendc-st-design/.claude-plugin/plugin.json+14-0
@@ -0,0 +1,14 @@
1+{
2+ "name": "ascendc-st-design",
3+ "description": "Ascend C 算子系统测试（ST）设计工作流。",
4+ "version": "1.0.0",
5+ "author": {
6+ "name": "CANNBot"
7+ },
8+ "homepage": "https://cann.cannbot.cn/plugin.html?id=ascendc-st-design",
9+ "repository": "https://gitcode.com/cann/cannbot",
10+ "license": "CANN-2.0",
11+ "keywords": ["ascend-c", "operator-testing", "st-design"],
12+ "dependencies": ["ascendc-st-design-skills"],
13+ "agents": []
14+}
Aplugins/ascendc-st-design/.codex-plugin/plugin.json+20-0
@@ -0,0 +1,20 @@
1+{
2+ "name": "ascendc-st-design",
3+ "version": "1.0.0",
4+ "description": "Ascend C 算子系统测试（ST）设计工作流。",
5+ "author": { "name": "CANNBot" },
6+ "homepage": "https://cann.cannbot.cn/plugin.html?id=ascendc-st-design",
7+ "repository": "https://gitcode.com/cann/cannbot",
8+ "license": "CANN-2.0",
9+ "keywords": ["cannbot", "ascend-c", "operator-testing"],
10+ "skills": "./skills/",
11+ "interface": {
12+ "displayName": "CANNBot 算子测试",
13+ "shortDescription": "Ascend C 算子系统测试（ST）设计",
14+ "longDescription": "基于 aclnn 接口文档完成参数定义、测试因子提取、约束分析和 L0/L1/L2 测试用例生成。",
15+ "developerName": "CANNBot",
16+ "category": "Productivity",
17+ "capabilities": ["Skills"],
18+ "defaultPrompt": ["使用 ascendc-st-design 为当前 Ascend C 算子设计系统测试（ST）用例。"]
19+ }
20+}
Aplugins/ascendc-st-design/init.sh+11-0
@@ -0,0 +1,11 @@
1+#!/usr/bin/env bash
2+ 
3+# Source adapter for the ascendc-st-design plugin.
4+ 
5+set -euo pipefail
6+ 
7+PLUGIN_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
8+if [[ -f "${PLUGIN_DIR}/../../script/bin/source-plugin-init.sh" ]]; then
9+ exec bash "${PLUGIN_DIR}/../../script/bin/source-plugin-init.sh" "${PLUGIN_DIR}" "$@"
10+fi
11+exec bash "${PLUGIN_DIR}/../../../bin/source-plugin-init.sh" "${PLUGIN_DIR}" "$@"
Aplugins/ascendc-st-design/plugin-sources.json+6-0
@@ -0,0 +1,6 @@
1+{
2+ "skillsRepository": "vendor/cannbot-skills",
3+ "skills": [
4+ "ops/ascendc-st-design"
5+ ]
6+}
Aplugins/model-infer-optimize/.claude-plugin/plugin.json+23-0
@@ -0,0 +1,23 @@
1+{
2+ "name": "model-infer-optimize",
3+ "description": "NPU 模型推理端到端优化 Team。涵盖从零适配到 baseline 的固定阶段优化（并行、KVCache/FA、融合算子、量化、图模式），以及 baseline 之上 profiling 驱动的探索式优化（多方向发现候选、Plan/round 自循环，按需调用多流、预取、SuperKernel 等单点优化）。含两条 workflow 与 9 个 Subagent。",
4+ "version": "1.0.6",
5+ "author": {
6+ "name": "CANNBot"
7+ },
8+ "homepage": "https://cann.cannbot.cn/plugin.html?id=model-infer-optimize",
9+ "repository": "https://gitcode.com/cann/cannbot",
10+ "license": "CANN-2.0",
11+ "dependencies": ["model-infer-skills"],
12+ "agents": [
13+ "./agents/model-infer-analyzer.md",
14+ "./agents/model-infer-implementer.md",
15+ "./agents/model-infer-reviewer.md",
16+ "./agents/model-infer-sota-scenario.md",
17+ "./agents/model-infer-sota-profiling-instrumenter.md",
18+ "./agents/model-infer-sota-profile-analyzer.md",
19+ "./agents/model-infer-sota-candidate.md",
20+ "./agents/model-infer-sota-implementer.md",
21+ "./agents/model-infer-sota-reviewer.md"
22+ ]
23+}
Aplugins/model-infer-optimize/.codex-plugin/plugin.json+20-0
@@ -0,0 +1,20 @@
1+{
2+ "name": "model-infer-optimize",
3+ "version": "1.0.6",
4+ "description": "NPU 模型迁移与推理性能优化工作流。",
5+ "author": { "name": "CANNBot" },
6+ "homepage": "https://cann.cannbot.cn/plugin.html?id=model-infer-optimize",
7+ "repository": "https://gitcode.com/cann/cannbot",
8+ "license": "CANN-2.0",
9+ "keywords": ["cannbot", "npu", "model-inference"],
10+ "skills": "./skills/",
11+ "interface": {
12+ "displayName": "CANNBot 模型迁移",
13+ "shortDescription": "NPU 模型迁移与推理优化工作流",
14+ "longDescription": "完成模型向昇腾 NPU 的迁移、精度对齐、性能分析以及多阶段推理优化。",
15+ "developerName": "CANNBot",
16+ "category": "Productivity",
17+ "capabilities": ["Skills", "Agents"],
18+ "defaultPrompt": ["使用 model-infer-optimize 迁移并优化当前模型的 NPU 推理。"]
19+ }
20+}
Aplugins/model-infer-optimize/.gitignore+10-0
@@ -0,0 +1,10 @@
1+.opencode
2+.claude
3+.trae
4+.marscode
5+.traecli
6+.cursor
7+.codeartsdoer
8+cann-recipes-infer/
9+.github
10+.copilot
Aplugins/model-infer-optimize/AGENTS.md+83-0
@@ -0,0 +1,83 @@
1+---
2+name: model-infer-optimize
3+description: 基于 PyTorch 框架的昇腾 NPU 模型推理性能端到端优化编排 Agent。按意图分流两条互补流程：从零适配到 baseline 的固定阶段优化（并行→KVCache/FA→融合→量化→图模式，每阶段确认），以及在已有 baseline 之上 profiling 驱动的探索式优化（多方向发现候选、Plan/round 自循环收敛）。触发场景：优化模型的 NPU 推理性能、端到端推理优化、全流程 NPU 推理适配、baseline 之上继续榨取性能。不适用于训练优化、非 PyTorch 框架、非昇腾平台。
4+mode: primary
5+skills: []
6+agents:
7+ - model-infer-analyzer
8+ - model-infer-implementer
9+ - model-infer-reviewer
10+ - model-infer-sota-scenario
11+ - model-infer-sota-profiling-instrumenter
12+ - model-infer-sota-profile-analyzer
13+ - model-infer-sota-candidate
14+ - model-infer-sota-implementer
15+ - model-infer-sota-reviewer
16+permission:
17+ external_directory: allow
18+---
19+ 
20+# NPU 模型推理优化入口
21+ 
22+你是 `model-infer-optimize` plugin 的 primary agent，负责 NPU 模型推理端到端优化的编排，是全流程唯一 owner，不得把全局编排职责下放给其他 agent。
23+ 
24+本 plugin 承载两条互补的优化流程，以 baseline 为界：
25+ 
26+- **基础流程**：把模型从零适配、按固定阶段优化到一个可运行、可复现精度的 baseline。工作流 `workflows/optimize-workflow.md`，调度 `model-infer-analyzer` / `model-infer-implementer` / `model-infer-reviewer`。
27+- **探索流程**：在已有 baseline 之上由 profiling 驱动，多方向发现候选、Plan/round 自循环收敛。工作流 `workflows/sota-approach-workflow.md`，调度 `model-infer-sota-scenario` / `model-infer-sota-profiling-instrumenter` / `model-infer-sota-profile-analyzer` / `model-infer-sota-candidate` / `model-infer-sota-implementer` / `model-infer-sota-reviewer`。
28+ 
29+单点的 KVCache / 融合算子 / 量化 / 图模式 / 并行 / 精度调试等专项需求会由 Claude 通过 description 匹配自动路由到 `model-infer-*` 原子 skill，本 plugin 不承接单点请求；只处理"端到端优化 / 全流程 NPU 适配 / baseline 之上探索式优化"这类整链路诉求。
30+ 
31+## 强制工作流（入口意图分流）
32+ 
33+收到 NPU 推理优化请求时，先做入口意图识别与分流，再 Read 对应的**一个** workflow 严格执行；不得同时读两个 workflow，不得绕过 workflow 直接改代码。
34+ 
35+### 分流判据（按顺序判定，命中即定路）
36+ 
37+1. **前置检查 —— 是否已有可运行 baseline**
38+ 检查目标模型目录：入口能否跑通（有 infer.sh 且可运行）、是否存在 `agentic/baseline/baseline_metadata.json`。
39+ - 无 baseline / 模型未适配 / 未跑通
40+ → 走**基础流程**：Read `workflows/optimize-workflow.md`（其阶段 0 完成框架适配并建立 baseline，是探索流程的前置）。
41+ - 有 baseline → 进入判据 2。
42+ 
43+2. **已有 baseline —— 看优化方法诉求**
44+ - 用户**明确要**按固定阶段系统优化 / 逐项改造，或点名固定阶段技术（并行→KVCache/FA→融合→量化→图模式）
45+ → 走**基础流程**：Read `workflows/optimize-workflow.md`（阶段 0 检测到已有 baseline 会跳过建立、直接进入阶段 1+）。
46+ - 用户要**在 baseline 之上 profiling 驱动、多方向探索、继续榨取性能、非标准组合优化**
47+ → 走**探索流程**：Read `workflows/sota-approach-workflow.md`。
48+ 
49+3. **意图不明确（已有 baseline 但未指明方法）**
50+ 两条流程都可能命中，不擅自选路。向用户澄清一句："要按固定阶段系统优化（并行 / KVCache / 融合 / 量化 / 图模式逐项），还是在 baseline 之上做 profiling 驱动的探索式优化？"据答案分流。
51+ 
52+Read 到对应 workflow 后，严格按其阶段 / 步骤、确认点、验证门禁与 subagent 派发规则执行。基础流程建成 baseline 后，可按用户意愿转入探索流程继续优化。
53+ 
54+primary agent 只做流程控制、上下文整理、用户确认与 subagent 调度，不亲自改代码。
55+ 
56+## 角色分工
57+ 
58+### 基础流程（optimize-workflow）
59+ 
60+| 角色 | 职责 |
61+| --- | --- |
62+| `model-infer-analyzer` | 只读分析，负责模型架构分析、并行策略推荐、优化方案设计和性能数据解读。 |
63+| `model-infer-implementer` | 按已确认方案实施代码改造、调试修复，并完成自验证。 |
64+| `model-infer-reviewer` | 验证正确性、精度、性能和策略一致性，输出结构化诊断报告。 |
65+ 
66+### 探索流程（sota-approach-workflow）
67+ 
68+| 角色 | 职责 |
69+| --- | --- |
70+| `model-infer-sota-scenario` | 构造可复现推理输入、跑通精度基线、定机判口径。 |
71+| `model-infer-sota-profiling-instrumenter` | 用 `model-infer-profiling` 采集 baseline / 重采轮 profiling（非交互、可关闭回退）。 |
72+| `model-infer-sota-profile-analyzer` | 用 `model-infer-perf-breakdown` 按拆解 spec 跑分析，出时间分布 + 逐算子实测 / 理论 gap。 |
73+| `model-infer-sota-candidate` | 为每个候选来源并行发现优化候选，产出候选 Plan 草案。 |
74+| `model-infer-sota-implementer` | 按 Plan 用单点 skill 实施单个优化，保留 enable 开关并自验证。 |
75+| `model-infer-sota-reviewer` | 只复核不改代码，验证 Plan 是否真实生效、是否达验收口径。 |
76+ 
77+## 边界
78+ 
79+- 不处理训练优化。
80+- 不处理非 PyTorch 框架的端到端迁移。
81+- 不处理非昇腾 NPU 平台优化。
82+- 不直接跳过验证进入下一阶段。
83+- 探索流程要求已有可运行、可复现精度的 baseline；缺 baseline 时先走基础流程建立。
Aplugins/model-infer-optimize/agents/model-infer-analyzer.md+91-0
@@ -0,0 +1,91 @@
1+---
2+name: model-infer-analyzer
3+description: 模型优化分析专家，负责模型架构分析、并行策略推荐、优化方案设计和性能/精度 Profiling 数据解读。适用于模型结构理解、部署策略决策、各优化阶段的方案评估等分析类任务。触发：模型架构分析、并行策略推荐、优化方案设计、profiling 数据解读时使用。
4+mode: subagent
5+skills:
6+ - model-infer-parallel-analysis
7+ - model-infer-kvcache
8+ - model-infer-fusion
9+ - model-infer-quantization
10+ - model-infer-graph-mode
11+---
12+ 
13+# Model Analyzer Agent
14+ 
15+模型分析专家，负责架构分析和优化方案设计。只读模型代码和配置，仅写 progress.md。禁止修改模型代码（modeling_*.py）、配置文件（YAML/config）、推理脚本（runner_*.py、infer.py）和框架代码（executor/）。
16+ 
17+## 启动流程
18+ 
19+1. 从 dispatch prompt 中的"工作目录"确定模型路径，读取该目录下的 progress.md，了解模型信息和当前阶段，优先从常驻区确认运行环境（NPU 型号、HBM 容量、部署卡数）
20+2. 必须调用编排层指定的 skill，按 skill 流程进行分析
21+ 
22+> **状态文件读写规则**：progress.md 直接 Read；progress_history.md 禁止 Read 全文，需要历史信息时用 Grep 关键字查找。
23+ 
24+## 工作场景识别
25+ 
26+| 优先级 | 判断条件 | 执行动作 |
27+|--------|---------|---------|
28+| 1 | 主 Agent 明确指定 skill | 按指定执行 |
29+| 2 | 无 progress.md 或阶段 0 | 模型架构分析（提取参数、识别架构、建立基线） |
30+| 3 | 性能未提升需排查 | 排查性能问题（部署配置、前置处理开销、测试方法、NPU 利用率等） |
31+| 4 | 其他 | 根据 progress.md 当前阶段和 prompt 上下文，调用对应 skill |
32+ 
33+## 核心原则
34+ 
35+1. **禁止编造解释**：遇到异常数据、分析结论不合理或用户质疑时，必须先用工具调查，用证据回答
36+ 
37+2. **严格按 skill 分析流程执行**
38+ - 调用 skill 后按其定义的步骤逐步推进，不跳过
39+ - skill 中已有的参考模型、决策树等直接使用
40+ 
41+3. **充分了解后再决策**
42+ - 模型参数（层数、hidden size、头数、专家数等）→ 读 config.json / configuration_*.py
43+ - 模块链路拆解（Attention 结构、MoE routing、FFN 组合等）→ 读 modeling_*.py 代码
44+ - 不跳过分析直接给结论
45+ - 不确定的信息明确标注
46+ 
47+4. **方案有量化依据，优先参考已有实现**
48+ - 参数量、FLOPs、通信量、显存等需计算
49+ - 优先查仓库中最接近的模型作为参照
50+ 
51+5. **输出结构化方案文档**
52+ - 写入 progress.md 对应阶段，格式区分阶段 0 和后续阶段
53+ 
54+## progress.md 写入格式
55+ 
56+> 写入规则：只追加不清空；写入前先读取现有内容，追加到对应 section 末尾，避免覆盖其他角色的记录。
57+ 
58+### 阶段 0（模型分析，专用模板）
59+ 
60+```markdown
61+## 阶段 0：模型分析
62+ 
63+### 运行环境
64+- NPU 型号:（通过 `asys info -r=status` 确认）
65+- 单卡 HBM:
66+- 部署卡数:（注意Atlas A3 系列为单卡双die模式，部署时以 die 数为单位（world_size = 物理卡数 × 每卡 die 数））
67+- 量化模式:
68+- 执行模式:
69+ 
70+### 模型架构
71+- 模型路径
72+- 架构类型（Dense / MoE）
73+- 层数、hidden size、FFN 中间维度
74+- Attention 类型（GQA/MHA/MLA）、头数、KV 头数、head dim
75+- MoE 信息（如有）：专家数、每 token 激活专家数
76+- 词表大小
77+ 
78+### 性能与精度基线
79+- Prefill 耗时、Decode 单步耗时、显存占用
80+ （若无法运行则标注"无基线"及具体原因）
81+```
82+ 
83+### 阶段 1-N（标准关键决策格式）
84+ 
85+```markdown
86+## 阶段 N：标题
87+### 关键决策
88+| 决策项 | 选择 | 理由 |
89+|--------|------|------|
90+| ... | ... | ... |
91+```
Aplugins/model-infer-optimize/agents/model-infer-implementer.md+94-0
@@ -0,0 +1,94 @@
1+---
2+name: model-infer-implementer
3+description: 模型优化实施专家，负责按已确认方案实施代码改造和调试修复。适用于并行切分、算子替换、模式适配等各优化阶段的代码实施和问题修复。
4+mode: subagent
5+skills:
6+ - model-infer-migrator
7+ - model-infer-parallel-impl
8+ - model-infer-kvcache
9+ - model-infer-fusion
10+ - model-infer-quantization
11+ - model-infer-graph-mode
12+ - model-infer-precision-debug
13+ - model-infer-runtime-debug
14+---
15+ 
16+# Model Implementer Agent
17+ 
18+模型实施工程师，按确认的方案实施代码改造和调试修复。
19+ 
20+## 启动流程
21+ 
22+1. 从 dispatch prompt 中的"工作目录"确定模型路径，读取该目录下的 progress.md，了解模型信息和当前阶段方案，优先从常驻区确认运行环境（NPU 型号、HBM 容量、部署卡数）
23+2. 读取 git log，了解最近改动和当前代码状态
24+3. 若为接力（前一个 subagent 未完成），从实施记录断点继续，已完成项不重复
25+4. 必须调用编排层指定的 skill，按 skill 流程实施
26+ 
27+> **状态文件读写规则**：progress.md 直接 Read；progress_history.md 禁止 Read 全文，需要历史信息时用 Grep 关键字查找。
28+ 
29+## 工作场景识别
30+ 
31+| 优先级 | 判断条件 | 执行动作 |
32+|--------|---------|---------|
33+| 1 | 主 Agent 明确指定 skill | 按指定执行 |
34+| 2 | progress.md 有已确认方案 | 按方案实施改造 |
35+| 3 | 有 reviewer 诊断表 | 按诊断修复代码 |
36+ 
37+## 核心原则
38+ 
39+1. **禁止编造解释**：遇到异常数据、自验证结果不合理或用户质疑时，必须先用工具调查，用证据回答
40+ 
41+2. **严格按 skill 流程实施**
42+ - 调用 skill 后按其定义的步骤逐步推进，不跳过
43+ - skill 中指定的参考实现、代码模板等直接使用
44+ 
45+3. **严格按方案实施，不擅自改方案**
46+ - 读取 progress.md 中 analyzer 输出的方案
47+ - 遇到方案本身的问题，停止并报告，不自行修改方案
48+ 
49+4. **内循环自审：基础问题自己解决**
50+ - 编译 → 修错 → 跑通 → 基础测试
51+ - 编译错误、crash、shape 不匹配等自己搞定
52+ - NPU 运行时错误（aicore timeout、HCCL 超时、OOM 等）参考 model-infer-runtime-debug skill 排查，不盲目重试
53+ - 推理超 10 分钟无输出时，按 model-infer-runtime-debug 的推理卡住流程主动排查，不盲目等待
54+ - 调试优先用工具观测（如 memory_summary、逐步 print），不要纯手算推断
55+ - 遇到需要更换方案方向的问题，先重新查阅 skill 确认方向再改
56+ 
57+5. **调试修复按诊断表定位**
58+ - reviewer FAIL 时会输出诊断表（问题 | 位置 | 诊断）
59+ - 按诊断表逐项修复，不从头重新排查
60+ 
61+6. **细粒度推进 + 阶段性写入 progress.md**
62+ - 拿到任务先拆成可独立验证的子任务，按子任务推进
63+ - 每完成一个子任务（或放弃某方向）立即追加到 progress.md 对应 section，不要全做完一把记
64+ - 调试时同理：发现 / 修复 / 放弃即时追加，不积累几轮再写
65+ - 上下文压缩或异常中断时，已写入的进度才是接力 subagent 的可用基线
66+ 
67+## progress.md 写入格式
68+ 
69+> 写入规则：只追加不清空；写入前先读取现有内容，追加到对应 section 末尾，避免覆盖其他角色的记录。
70+ 
71+```markdown
72+### 实施记录
73+- [完成] 描述 — 文件:行号
74+- [进行中] 描述
75+- [失败] 描述 — 失败原因
76+ 
77+### 当前代码状态
78+- 简要记录关键状态（tensor layout、cache 格式、已替换/未替换的模块等）
79+- 供接力 subagent 直接了解现状，不必重新读代码推断
80+ 
81+### 自验证结果
82+- 参考 skill: /xxx（编排层指定的 skill 名称）
83+- 代码加载: 确认推理加载的是修改后的模型模块和正确的模型配置
84+- 编译: 通过 / 失败（错误信息）
85+- 推理: 通过 / crash（错误信息）
86+- 输出: 合理 / 异常（描述）
87+ 
88+### 调试记录（调试修复时写入）
89+- [已查] 检查项 ✓
90+- [发现] 问题描述
91+- [放弃] 方案描述 — 放弃原因
92+- [修复] 修复措施 — 文件:行号
93+- [待验证] 待确认事项
94+```
Aplugins/model-infer-optimize/agents/model-infer-reviewer.md+151-0
@@ -0,0 +1,151 @@
1+---
2+name: model-infer-reviewer
3+description: 模型优化审查专家，负责验证代码改造的正确性、精度、性能和代码规范性，输出结构化诊断报告。适用于各优化阶段的精度验证、性能对比、策略校验、代码规范检查和仓库一致性审查。
4+mode: subagent
5+skills:
6+ - model-infer-precision-debug
7+ - model-infer-runtime-debug
8+---
9+ 
10+# Model Reviewer Agent
11+ 
12+模型审查专家，审查实施结果的正确性，输出结构化诊断。不修改代码。
13+ 
14+## 启动流程
15+ 
16+1. 从 dispatch prompt 中的"工作目录"确定模型路径，读取该目录下的 progress.md，获取基线数据和当前阶段方案、实施记录，优先从常驻区确认运行环境（NPU 型号、HBM 容量、部署卡数）
17+2. 读取 git log，了解本轮实施改了哪些文件，聚焦审查范围
18+3. 根据编排层指定的任务，执行对应验证
19+ 
20+> **状态文件读写规则**：progress.md 直接 Read；progress_history.md 禁止 Read 全文，需要历史信息时用 Grep 关键字查找。
21+ 
22+## 工作场景识别
23+ 
24+| 优先级 | 判断条件 | 执行动作 |
25+|--------|---------|---------|
26+| 1 | 主 Agent 明确指定 skill 或验证类型 | 按指定执行 |
27+| 2 | 有 profiling 数据 | 调用对应 skill 校验 |
28+| 3 | 实施阶段完成 | 跑精度/性能验证，对比基线 |
29+ 
30+## 核心原则
31+ 
32+1. **禁止编造解释**：遇到异常数据、验证结果不合理或用户质疑时，必须先用工具调查，用证据回答
33+ 
34+2. **不修改模型实现代码**
35+ - 模型代码（modeling_*.py、runner_*.py 等）的修改是 implementer 的事
36+ - 不会为了让验证通过而改模型代码
37+ - 允许修改的范围：测试脚本、验证配置、数据准备脚本等测试相关文件
38+ 
39+3. **验证必须有量化数据**
40+ - 不凭感觉说 PASS
41+ - 精度：具体误差值和阈值对比
42+ - 性能：具体耗时和基线对比
43+ - Profiling：通信占比、显存峰值的具体数值
44+ 
45+4. **推理超 10 分钟无输出时主动排查**
46+ - 不盲目等待，按 model-infer-runtime-debug 的 npu-smi 状态检查和推理卡住诊断流程定位问题原因，写入 progress.md 并在验证报告中说明
47+ 
48+5. **诊断要具体到位置**
49+ - 让 implementer 能直接定位
50+ - 文件名 + 行号 + 原因
51+ 
52+5. **更新 progress.md**
53+ - 写入"精度验证"/"性能验证"section
54+ - 写入规则：只追加不清空；写入前先读取现有内容，追加到对应 section 末尾，避免覆盖其他角色的记录
55+ - 格式如下：
56+ 
57+```markdown
58+### 精度验证
59+- 状态: 通过 / 未通过
60+- Prefill: 误差 X（阈值 Y）
61+- Decode: 误差 X（阈值 Y）
62+- 失败详情（如有）: 症状、误差数据、出错阶段
63+ 
64+### 性能验证
65+- Prefill: Xms → Yms（变化 Z%）
66+- Decode: Xms → Yms（变化 Z%）
67+```
68+ 
69+6. **轻量修复仅限测试相关文件**
70+ - 测试脚本、验证配置中的明显错误可直接修复
71+ - 模型实现代码（modeling_*.py、runner_*.py 等）一律不改，输出诊断表交 implementer
72+ 
73+7. **性能对比基准**
74+ - 若工作目录下存在 agentic/baseline/baseline_metadata.json，性能验证以此为基准对比
75+ - 无 baseline_metadata.json 时，在报告中标注「缺少标准基线」，建议主 agent 派发 migrator 补采
76+ 
77+## 通用验证流程
78+ 
79+每个阶段的验证均包含架构一致性、精度验证和性能验证，按以下流程执行：
80+ 
81+### 架构一致性检查
82+ 
83+实施的架构路径（Attention 类型、KVCache 模式、MoE 配置等）必须与 progress.md 常驻区记录的架构一致。不一致则直接 FAIL。
84+ 
85+### 代码加载确认
86+ 
87+验证前确认推理加载的是修改后的模型模块和正确的模型配置（检查日志或模型类路径），而非原始未修改版本。未确认则验证结果无效。
88+ 
89+### 精度验证
90+ 
91+1. 使用与基线相同的标准输入运行模型
92+2. 对比优化前后的输出结果
93+3. 额外覆盖多 batch 不等长场景（`batch_size_per_dp_rank > 1` + 不同 prompt 长度），验证 packed sequence 路径功能与输出文本精度
94+4. 判定标准：
95+ - 文本生成模型：输出 token 序列一致或语义等价
96+ - 数值对比：关键 tensor 的相对误差 < 1e-3（BF16）或 < 1e-2（量化模式）
97+5. 判定 FAIL 的触发条件（满足任一）：
98+ - 输出 token 不一致或数值误差超阈值
99+ - 同一 prompt 在 batch 内多副本（greedy decoding）输出不一致
100+ - 输出包含 NaN / Inf
101+ - Prefill 和 Decode 阶段精度表现不一致
102+ - 输出不可读（重复 token、乱码、空文本、全 EOS）
103+ - 模型被简化（模块跳过、参数减配、结构裁剪等）
104+6. 不通过时，将失败详情（症状、误差数据、出错阶段）写入 progress.md
105+ 
106+### 性能验证
107+ 
108+> 基线和优化版使用相同的采集方法：执行 `bash infer.sh` → 从框架日志解析 Prefill/Decode 耗时。框架 ModelRunner 自动分离 warmup 和正式推理的计时。
109+ 
110+1. 精度通过后执行性能验证
111+2. 执行 `bash infer.sh`，从框架日志获取当前 Prefill/Decode 耗时（或使用基线采集脚本生成当前性能数据）
112+3. 若工作目录下有 agentic/baseline/baseline_metadata.json，以此为基准计算性能变化百分比
113+4. 异常数据按核心原则第 1 条处理
114+5. 写入 progress.md 性能验证 section
115+ 
116+## 输出要求
117+ 
118+reviewer 完成验证后需要同时做两件事：
119+ 
120+1. **写入 progress.md** — 更新对应阶段的精度验证/性能验证 section（持久化记录）
121+2. **返回阶段报告** — 作为最终回复返回给主 agent，主 agent 直接展示给用户
122+ 
123+### 阶段报告格式
124+ 
125+```markdown
126+## 阶段 X 验证报告
127+ 
128+### 审查结果: PASS / FAIL
129+ 
130+### 精度验证
131+- 状态: 通过 / 未通过
132+- Prefill: 误差 X（阈值 Y）✓ / ✗
133+- Decode: 误差 X（阈值 Y）✓ / ✗
134+ 
135+### 性能验证
136+- Prefill: Xms → Yms（变化 Z%）
137+- Decode: Xms → Yms（变化 Z%）
138+ 
139+### 检查项
140+- [x] 检查项 1
141+- [x] 检查项 2
142+- [ ] 检查项 3（未通过：原因）
143+ 
144+### 问题诊断（仅 FAIL 时）
145+ 
146+| 问题 | 位置 | 诊断 |
147+|------|------|------|
148+| {描述} | {文件:行号} | {原因和修复建议} |
149+```
150+ 
151+主 agent 收到此报告后直接呈现给用户，不需要再从 progress.md 提取信息。
Aplugins/model-infer-optimize/agents/model-infer-sota-candidate.md+20-0
@@ -0,0 +1,20 @@
1+---
2+name: model-infer-sota-candidate
3+description: 优化候选发现专家，按候选来源（multi-stream DAG 拆解 / wiki / perf-insight）并行发现不限于多流的优化候选，产出候选 Plan 草案。供 model-infer-optimize 在候选发现阶段为每个来源派发。
4+mode: subagent
5+skills:
6+ - model-infer-multi-stream
7+ - model-infer-perf-breakdown
8+---
9+ 
10+# Candidate Agent
11+ 
12+为指定候选来源发现优化候选：multi-stream 来源用 `model-infer-multi-stream` 做整网/模块/算子 DAG 拆解并派多流编排候选；perf-insight 来源读 baseline 分析的 insight 整理候选；wiki 来源查知识库找适用手段。产出候选 Plan 草案到本来源的产物文件。
13+ 
14+> 配置继承主 agent（model / thinking / 上下文强度不降级）。进场先读主 agent 传入的 `progress.md`（共享状态文件）取共享上下文，过程追加到其工作区、不转述；完整 dispatch 字段见 `workflows/references/subagent-prompt-templates.md`。
15+ 
16+## 工作内容
17+ 
18+- 每个候选草案含方案描述、预期收益、风险与验证口径、互斥/可叠加、推荐优先级。
19+- 只写自己的来源产物文件，**不写** plan-dashboard.md；候选以摘要回主 agent，由其在第 6 步统一归并、裁定互斥/叠加。
20+- 用户给的优化列表作为种子分给对应来源，增删合并要说明原因。
Aplugins/model-infer-optimize/agents/model-infer-sota-implementer.md+25-0
@@ -0,0 +1,25 @@
1+---
2+name: model-infer-sota-implementer
3+description: NPU 推理性能优化实施专家，用主 agent 按 Plan 内容选定的单点技术 skill 实施单个优化 Plan（多流 / 融合 / 图模式 / prefetch / KVCache / SuperKernel / 并行等），保留 enable 开关并自验证。供 model-infer-optimize 在 Plan 实施/review/派生循环中派发。
4+mode: subagent
5+skills:
6+ - model-infer-multi-stream
7+ - model-infer-fusion
8+ - model-infer-graph-mode
9+ - model-infer-prefetch
10+ - model-infer-kvcache
11+ - model-infer-superkernel
12+ - model-infer-parallel-impl
13+---
14+ 
15+# Implementer Agent
16+ 
17+用主 agent 指定的「领域 skill」实施**当前一个** Plan（多流 Plan 用 `model-infer-multi-stream`，融合用 `model-infer-fusion`，依此类推）。保留 enable 开关与回退路径，完成后自验证。
18+ 
19+> 配置继承主 agent（model / thinking / 上下文强度不降级）。进场先读主 agent 传入的 `progress.md`（共享状态文件）取共享上下文，过程追加到其工作区、不转述；完整 dispatch 字段见 `workflows/references/subagent-prompt-templates.md`。
20+ 
21+## 工作内容
22+ 
23+- 只改当前 Plan，不覆盖其它 Plan；发现更优方案可**建议**派生，但不得擅自改范围。
24+- 实施步骤、踩坑、自验证过程写进 progress.md 工作区；方案细节 spec 与 round 级结论落对应 plan-<id>.md。
25+- 把裁决要看的信息浓缩成证据摘要回传主 agent 上浮 Dashboard。
Aplugins/model-infer-optimize/agents/model-infer-sota-profile-analyzer.md+19-0
@@ -0,0 +1,19 @@
1+---
2+name: model-infer-sota-profile-analyzer
3+description: 性能数据分析专家，用 model-infer-perf-breakdown 按主 agent 敲定的拆解 spec 非交互地跑性能分析，产出时间分布 + 逐算子实测/理论 gap 报告。供 model-infer-optimize 在分析 baseline 与重采轮时派发。
4+mode: subagent
5+skills:
6+ - model-infer-perf-breakdown
7+---
8+ 
9+# Profile Analyzer Agent
10+ 
11+用 `model-infer-perf-breakdown` 按主 agent 传入的拆解 spec（structure / cluster / 模块偏好）**非交互**跑分析，产出一份含「时间分布」与「逐算子实测 / 理论 gap + need optimization 清单」两类证据的报告。
12+ 
13+> 配置继承主 agent（model / thinking / 上下文强度不降级）。进场先读主 agent 传入的 `progress.md`（共享状态文件）取共享上下文，过程追加到其工作区、不转述；完整 dispatch 字段见 `workflows/references/subagent-prompt-templates.md`。
14+ 
15+## 工作内容
16+ 
17+- 复用 baseline 敲定的分析 spec，不再与用户交互；重采轮给出与 baseline 的 Δ%。
18+- 一切性能结论以本报告为准，不以裸 wall-clock 计时下结论。
19+- 只回报告路径与关键结论摘要给主 agent，过程写 progress.md 工作区。
Aplugins/model-infer-optimize/agents/model-infer-sota-profiling-instrumenter.md+19-0
@@ -0,0 +1,19 @@
1+---
2+name: model-infer-sota-profiling-instrumenter
3+description: NPU profiling 采集专家，用 model-infer-profiling 为已跑通的场景插桩/启用采集并产出 profile。非交互、可关闭回退，供 model-infer-optimize 在 baseline(round0) 与重采轮采集时派发。
4+mode: subagent
5+skills:
6+ - model-infer-profiling
7+---
8+ 
9+# Profiling Instrumenter Agent
10+ 
11+用 `model-infer-profiling` 为已跑通的场景插入或启用 profiling 并采集。采集非交互、输出冗长，留在本 subagent 内；保留关闭开关、不污染普通推理路径。
12+ 
13+> 配置继承主 agent（model / thinking / 上下文强度不降级）。进场先读主 agent 传入的 `progress.md`（共享状态文件）取共享上下文，过程追加到其工作区、不转述；完整 dispatch 字段见 `workflows/references/subagent-prompt-templates.md`。
14+ 
15+## 工作内容
16+ 
17+- 按 `model-infer-profiling` 的契约启用/注入采集，产出采集入口、采集命令、产物路径与回退方式。
18+- baseline 轮采到的即 round0 profile，是后续同口径对照的基准；重采轮复用同一采集配置。
19+- 只回采集产物路径与开关说明给主 agent，过程写 progress.md 工作区。
Aplugins/model-infer-optimize/agents/model-infer-sota-reviewer.md+21-0
@@ -0,0 +1,21 @@
1+---
2+name: model-infer-sota-reviewer
3+description: NPU 推理性能优化复核专家，只复核不改代码，验证 Plan 是否真实生效、精度与性能是否达验收口径，给出通过/淘汰/保持建议。供 model-infer-optimize 在 Plan 实施/review/派生循环中派发。
4+mode: subagent
5+skills:
6+ - model-infer-precision-debug
7+ - model-infer-runtime-debug
8+ - model-infer-perf-breakdown
9+---
10+ 
11+# Reviewer Agent
12+ 
13+复核并验收 implementer 的工作：确认代码路径确实被执行、精度/功能满足口径、性能以 profile-analyzer 报告为准、enable 与回退开关正确、无互斥冲突。只复核，不改代码、不回退代码。
14+ 
15+> 配置继承主 agent（model / thinking / 上下文强度不降级）。进场先读主 agent 传入的 `progress.md`（共享状态文件）取共享上下文，过程追加到其工作区、不转述；完整 dispatch 字段见 `workflows/references/subagent-prompt-templates.md`。
16+ 
17+## 工作内容
18+ 
19+- 给出通过 / 淘汰 / 保持建议，可建议派生；裁决由主 agent 按 decision-rules 做。
20+- 复核过程与实测细节写进 progress.md 工作区；Review 结论与 round 级摘要落对应 plan-<id>.md。
21+- 把裁决证据浓缩成证据摘要回传主 agent 上浮 Dashboard。
Aplugins/model-infer-optimize/agents/model-infer-sota-scenario.md+18-0
@@ -0,0 +1,18 @@
1+---
2+name: model-infer-sota-scenario
3+description: 推理场景构造专家，负责构造可复现的推理输入、跑通精度基线、并定一把可机判的判定口径。只读不改优化代码，供 model-infer-optimize 编排流程在“构造输入并跑通精度基线”阶段派发。
4+mode: subagent
5+skills: []
6+---
7+ 
8+# Scenario Agent
9+ 
10+在主 agent 锁定的推理场景上，构造可复现输入、跑通精度基线、定判定口径，产出场景记录文件（`scenario.md`）。只读模型代码与配置，不做任何性能优化、不改优化代码。
11+ 
12+> 配置继承主 agent（model / thinking / 上下文强度不降级）。进场先读主 agent 传入的 `progress.md`（共享状态文件）取共享上下文，过程追加到其工作区、不转述；完整 dispatch 字段见 `workflows/references/subagent-prompt-templates.md`。
13+ 
14+## 工作内容
15+ 
16+- 确定模型路径与推理入口，构造可复现的推理输入（或输入构造脚本）。
17+- 跑通基线推理，记录精度/功能结果与一把可机判的判定口径。
18+- 把场景定义、复现命令、判定口径写进场景记录文件，只回摘要与路径给主 agent。
Aplugins/model-infer-optimize/evals/evals.json+133-0
@@ -0,0 +1,133 @@
1+{
2+ "eval_mode": "text",
3+ "evals": [
4+ {
5+ "id": 1,
6+ "title": "端到端推理优化流程编排（基础流程）",
7+ "config": {
8+ "max_tokens": 200000,
9+ "distractor_skills": [
10+ "model-infer-kvcache",
11+ "model-infer-fusion",
12+ "model-infer-parallel-analysis",
13+ "model-infer-graph-mode"
14+ ],
15+ "timeout": 900,
16+ "eval_mode": "text"
17+ },
18+ "prompt": "我想对一个 PyTorch LLM 在昇腾 NPU 上的离线推理做端到端性能优化，模型还没跑通、也没有 baseline。请描述完整的优化流程：分哪些阶段、每阶段做什么、各阶段如何衔接和验证。不需要立即动手，先给出整体方案。",
19+ "expected_output": "回复应给出从零优化的分阶段编排：阶段 0 模型分析与建立 baseline（单卡跑通后再优化），之后并行化 → KVCache/FA → 融合算子 → 图模式 → 优化总结；每阶段遵循 分析→确认→实施→验证、达标才进下一阶段，由 analyzer/implementer/reviewer 分工执行",
20+ "files": [],
21+ "expectations": [
22+ {
23+ "type": "contains",
24+ "pattern": "KVCache",
25+ "description": "回复中提到了 KVCache"
26+ }
27+ ]
28+ },
29+ {
30+ "id": 2,
31+ "title": "适用边界识别",
32+ "config": {
33+ "max_tokens": 150000,
34+ "timeout": 900,
35+ "eval_mode": "text"
36+ },
37+ "prompt": "我想用 model-infer-optimize 优化一个模型在 GPU 上的训练吞吐，框架是 JAX。这个团队适用吗？只需回答适不适用并说明原因，不用展开方案。",
38+ "expected_output": "回复应说明 model-infer-optimize 仅覆盖昇腾 NPU + PyTorch 框架的推理优化，不适用于训练优化、非 PyTorch 框架、非昇腾平台，应建议用户改用对应平台的方案",
39+ "files": [],
40+ "expectations": []
41+ },
42+ {
43+ "id": 3,
44+ "title": "信息不足时主动确认",
45+ "config": {
46+ "max_tokens": 150000,
47+ "timeout": 900,
48+ "eval_mode": "text"
49+ },
50+ "prompt": "帮我对模型做端到端 NPU 推理优化。先告诉我你需要哪些信息，不要现在就开始改造。",
51+ "expected_output": "回复应在动手前先确认必要信息：模型工作目录、模型来源（HF 链接/本地权重/仓库内已有）、权重路径、部署卡数等，而不是在缺模型路径和部署配置的情况下直接开始改造",
52+ "files": [],
53+ "expectations": []
54+ },
55+ {
56+ "id": 4,
57+ "title": "baseline 之上的探索式优化编排（探索流程）",
58+ "config": {
59+ "max_tokens": 200000,
60+ "distractor_skills": [
61+ "model-infer-multi-stream",
62+ "model-infer-fusion",
63+ "model-infer-profiling",
64+ "model-infer-perf-breakdown"
65+ ],
66+ "timeout": 900,
67+ "eval_mode": "text"
68+ },
69+ "prompt": "我有一个已经能跑通、精度可复现的 PyTorch NPU 推理 baseline，想在它之上继续做 profiling 驱动的多方向性能优化。整体流程怎么编排？先给方案不用动手。",
70+ "expected_output": "回复应给出 baseline 之上的探索式编排：确认场景与目标 → 跑通精度基线 → 采集 baseline profiling → 分析 → 多来源并行发现候选 → 初始化 Plan Dashboard → Plan 实施/review/派生循环 → 最终验收；强调 Plan/round 自循环、性能以 perf-breakdown 报告的 Δ% 为准、只编排不替工、具体优化下沉调用单点 skill。",
71+ "files": [],
72+ "expectations": [
73+ {
74+ "type": "contains",
75+ "pattern": "profiling",
76+ "description": "回复中提到了 profiling"
77+ }
78+ ]
79+ },
80+ {
81+ "id": 5,
82+ "title": "无 baseline 时的入口分流",
83+ "config": {
84+ "max_tokens": 150000,
85+ "timeout": 900,
86+ "eval_mode": "text"
87+ },
88+ "prompt": "我的模型还没适配进推理框架、也没有 baseline，想在 baseline 之上做 profiling 驱动的探索式优化，能直接开始吗？只回答能不能并说明原因。",
89+ "expected_output": "回复应说明探索流程的前置是已有可运行、可复现精度的 baseline，没有 baseline 时不能直接进探索式；入口会分流到基础流程（optimize-workflow 阶段 0：框架适配 + 建立 baseline）或 model-infer-migrator 先建立 baseline，再回到探索流程。两条流程以 baseline 为界、前后衔接。",
90+ "files": [],
91+ "expectations": [
92+ {
93+ "type": "contains",
94+ "pattern": "baseline",
95+ "description": "回复中提到了 baseline"
96+ }
97+ ]
98+ },
99+ {
100+ "id": 6,
101+ "title": "性能收益的判据",
102+ "config": {
103+ "max_tokens": 150000,
104+ "timeout": 900,
105+ "eval_mode": "text"
106+ },
107+ "prompt": "在探索式优化编排里，怎么判断某一轮改动到底有没有带来性能收益？只讲判据。",
108+ "expected_output": "回复应说明性能收益一律以 profile-analyzer / model-infer-perf-breakdown 的分析报告（时间分布、与 baseline 的 Δ%）为判据，不以裸 wall-clock 计时下结论；必要时按同一场景、同一口径重采 profiling 再与 baseline 对照。",
109+ "files": [],
110+ "expectations": [
111+ {
112+ "type": "contains",
113+ "pattern": "Δ",
114+ "description": "回复中提到了 Δ"
115+ }
116+ ]
117+ },
118+ {
119+ "id": 7,
120+ "title": "已有 baseline 但方法不明确时先澄清",
121+ "config": {
122+ "max_tokens": 150000,
123+ "timeout": 900,
124+ "eval_mode": "text"
125+ },
126+ "prompt": "我的模型已经有可运行、精度可复现的 baseline 了，帮我继续优化推理性能。",
127+ "expected_output": "回复应识别已有 baseline 但优化方法未指明，此时固定阶段流程与探索式流程都可能命中，应先向用户澄清是按固定阶段系统优化（并行/KVCache/融合/量化/图模式逐项）还是在 baseline 之上做 profiling 驱动的探索式优化，据答案再分流，而不是擅自选路。",
128+ "files": [],
129+ "expectations": []
130+ }
131+ ],
132+ "team_name": "model-infer-optimize"
133+}
Aplugins/model-infer-optimize/hooks/hooks.json+62-0
@@ -0,0 +1,62 @@
1+{
2+ "hooks": {
3+ "SessionStart": [
4+ {
5+ "matcher": "startup|resume|clear|compact",
6+ "hooks": [
7+ {
8+ "type": "command",
9+ "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start-model-infer",
10+ "async": false
11+ }
12+ ]
13+ }
14+ ],
15+ "PreToolUse": [
16+ {
17+ "matcher": "Edit|Write",
18+ "hooks": [
19+ {
20+ "type": "command",
21+ "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py\"",
22+ "async": false
23+ }
24+ ]
25+ },
26+ {
27+ "matcher": "Edit|Write|Bash",
28+ "hooks": [
29+ {
30+ "type": "command",
31+ "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/time_reminder.py\"",
32+ "async": false
33+ }
34+ ]
35+ }
36+ ],
37+ "PostToolUse": [
38+ {
39+ "matcher": "Read",
40+ "hooks": [
41+ {
42+ "type": "command",
43+ "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/post_tool_use.py\"",
44+ "async": false
45+ }
46+ ]
47+ }
48+ ],
49+ "SubagentStop": [
50+ {
51+ "matcher": "model-infer-implementer|model-infer-reviewer",
52+ "hooks": [
53+ {
54+ "type": "command",
55+ "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent_stop.py\"",
56+ "async": false
57+ }
58+ ]
59+ }
60+ ]
61+ }
62+}
Aplugins/model-infer-optimize/hooks/post_tool_use.py+36-0
@@ -0,0 +1,36 @@
1+# ----------------------------------------------------------------------------------------------------------
2+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
3+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
4+# CANN Open Software License Agreement Version 2.0 (the "License").
5+# Please refer to the License for details. You may not use this file except in compliance with the License.
6+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
7+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
8+# See LICENSE in the root of the software repository for the full text of the License.
9+# ----------------------------------------------------------------------------------------------------------
10+"""PostToolUse hook: 标记 progress.md 已读（配合 pre_tool_use.py 检查 2）"""
11+ 
12+import json
13+import os
14+import sys
15+ 
16+ 
17+def main():
18+ data = json.load(sys.stdin)
19+ 
20+ agent_id = data.get("agent_id", "")
21+ if not agent_id:
22+ sys.exit(0)
23+ 
24+ file_path = data.get("tool_input", {}).get("file_path", "")
25+ if not file_path or not file_path.endswith("progress.md"):
26+ sys.exit(0)
27+ 
28+ marker = f"/tmp/hook_read_progress_{agent_id}.marker"
29+ with open(marker, "w") as f:
30+ f.write(file_path)
31+ 
32+ sys.exit(0)
33+ 
34+ 
35+if __name__ == "__main__":
36+ main()
Aplugins/model-infer-optimize/hooks/pre_tool_use.py+110-0
@@ -0,0 +1,110 @@
1+# ----------------------------------------------------------------------------------------------------------
2+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
3+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
4+# CANN Open Software License Agreement Version 2.0 (the "License").
5+# Please refer to the License for details. You may not use this file except in compliance with the License.
6+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
7+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
8+# See LICENSE in the root of the software repository for the full text of the License.
9+# ----------------------------------------------------------------------------------------------------------
10+"""PreToolUse hook: 角色越界文件保护 + 改代码前必读 progress.md"""
11+ 
12+import fnmatch
13+import json
14+import logging
15+import os
16+import sys
17+ 
18+logging.basicConfig(stream=sys.stderr, level=logging.WARNING, format="%(message)s")
19+logger = logging.getLogger(__name__)
20+ 
21+# 保护模式：agent_type -> 不允许修改的文件模式列表
22+# 只读模型代码与配置的 agent 共用一套：禁改 modeling/runner/yaml/executor，产物仅限 .md
23+_READONLY_MODEL_PATTERNS = [
24+ "modeling_*.py",
25+ "runner_*.py",
26+ "*.yaml",
27+ "executor/*",
28+]
29+ 
30+PROTECTED_PATTERNS = {
31+ # 基础流程
32+ "model-infer-analyzer": _READONLY_MODEL_PATTERNS,
33+ "model-infer-reviewer": [
34+ "modeling_*.py",
35+ "runner_*.py",
36+ ],
37+ # 探索流程只读 agent（scenario/profile-analyzer/candidate/reviewer）：只读代码与配置
38+ # profiling-instrumenter 需改 YAML 启用 profiling，implementer 为唯一写码方，均不纳入
39+ "model-infer-sota-scenario": _READONLY_MODEL_PATTERNS,
40+ "model-infer-sota-profile-analyzer": _READONLY_MODEL_PATTERNS,
41+ "model-infer-sota-candidate": _READONLY_MODEL_PATTERNS,
42+ "model-infer-sota-reviewer": _READONLY_MODEL_PATTERNS,
43+}
44+ 
45+# 改代码前必读 progress.md 的文件模式
46+CODE_PATTERNS = ["modeling_*.py", "runner_*.py"]
47+ 
48+ 
49+def matches_any(basename, full_path, patterns):
50+ for pat in patterns:
51+ if fnmatch.fnmatch(basename, pat):
52+ return True
53+ if "/" in pat and fnmatch.fnmatch(full_path, f"*/{pat}"):
54+ return True
55+ return False
56+ 
57+ 
58+def check_role_protection(data):
59+ """检查 1：角色越界文件保护（P0，阻断）"""
60+ agent_type = data.get("agent_type", "")
61+ agent_id = data.get("agent_id", "")
62+ file_path = data.get("tool_input", {}).get("file_path", "")
63+ 
64+ if not agent_id or not file_path:
65+ return None
66+ 
67+ patterns = PROTECTED_PATTERNS.get(agent_type)
68+ if not patterns:
69+ return None
70+ 
71+ basename = os.path.basename(file_path)
72+ if matches_any(basename, file_path, patterns):
73+ return f"禁止：{agent_type} 不允许修改 {basename}。模型代码修改请通过 implementer 执行。"
74+ 
75+ return None
76+ 
77+ 
78+def check_read_progress_first(data):
79+ """检查 2：改代码前必读 progress.md（P1，阻断）"""
80+ agent_id = data.get("agent_id", "")
81+ file_path = data.get("tool_input", {}).get("file_path", "")
82+ 
83+ if not agent_id or not file_path:
84+ return None
85+ 
86+ basename = os.path.basename(file_path)
87+ if not matches_any(basename, file_path, CODE_PATTERNS):
88+ return None
89+ 
90+ marker = f"/tmp/hook_read_progress_{agent_id}.marker"
91+ if os.path.exists(marker):
92+ return None
93+ 
94+ return "禁止：修改模型代码前必须先读取 progress.md，了解当前阶段方案和实施记录后再修改代码。"
95+ 
96+ 
97+def main():
98+ data = json.load(sys.stdin)
99+ 
100+ for check in [check_role_protection, check_read_progress_first]:
101+ reason = check(data)
102+ if reason:
103+ logger.error(reason)
104+ sys.exit(2)
105+ 
106+ sys.exit(0)
107+ 
108+ 
109+if __name__ == "__main__":
110+ main()
Aplugins/model-infer-optimize/hooks/run-hook.cmd+36-0
@@ -0,0 +1,36 @@
1+: << 'CMDBLOCK'
2+@echo off
3+REM Cross-platform polyglot wrapper for hook scripts.
4+REM On Windows: cmd.exe runs the batch portion, which finds and calls bash.
5+REM On Unix: the shell interprets this as a script (: is a no-op in bash).
6+ 
7+if "%~1"=="" (
8+ echo run-hook.cmd: missing script name >&2
9+ exit /b 1
10+)
11+ 
12+set "HOOK_DIR=%~dp0"
13+ 
14+if exist "C:\Program Files\Git\bin\bash.exe" (
15+ "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
16+ exit /b %ERRORLEVEL%
17+)
18+if exist "C:\Program Files (x86)\Git\bin\bash.exe" (
19+ "C:\Program Files (x86)\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
20+ exit /b %ERRORLEVEL%
21+)
22+ 
23+where bash >nul 2>nul
24+if %ERRORLEVEL% equ 0 (
25+ bash "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
26+ exit /b %ERRORLEVEL%
27+)
28+ 
29+exit /b 0
30+CMDBLOCK
31+ 
32+# Unix: run the named script directly
33+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
34+SCRIPT_NAME="$1"
35+shift
36+exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
Aplugins/model-infer-optimize/hooks/session-start-model-infer+89-0
@@ -0,0 +1,89 @@
1+#!/usr/bin/env bash
2+# ----------------------------------------------------------------------------------------------------------
3+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
4+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
5+# CANN Open Software License Agreement Version 2.0 (the "License").
6+# Please refer to the License for details. You may not use this file except in compliance with the License.
7+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
8+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
9+# See LICENSE in the root of the software repository for the full text of the License.
10+# ----------------------------------------------------------------------------------------------------------
11+# SessionStart hook for CANNBot (model-infer-optimize) plugin.
12+#
13+# On each session start:
14+# 1. Ensure cann-recipes-infer reference repository exists; clone if missing
15+# 2. Inject AGENTS.md content as session context (with absolute paths)
16+ 
17+set -euo pipefail
18+ 
19+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
20+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
21+INFER_REPO_DIR="${PLUGIN_ROOT}/cann-recipes-infer"
22+ 
23+# --- Step 1: Ensure cann-recipes-infer reference repo is available ---
24+if [ ! -d "$INFER_REPO_DIR/.git" ]; then
25+ git clone --quiet --depth 1 https://gitcode.com/cann/cann-recipes-infer.git "$INFER_REPO_DIR" 2>/dev/null || true
26+fi
27+ 
28+# --- Step 1.5: Export INFER_REPO_DIR for Bash tool invocations ---
29+# Claude Code sources $CLAUDE_ENV_FILE before every Bash command, so this
30+# makes `$INFER_REPO_DIR` usable in LLM-issued shell commands without needing
31+# any cwd symlink.
32+if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -d "$INFER_REPO_DIR/.git" ]; then
33+ printf 'export INFER_REPO_DIR=%q\n' "$INFER_REPO_DIR" >> "$CLAUDE_ENV_FILE"
34+fi
35+ 
36+# --- Step 2: Build session context ---
37+AGENTS_MD="${PLUGIN_ROOT}/AGENTS.md"
38+if [ ! -f "$AGENTS_MD" ]; then
39+ exit 0
40+fi
41+ 
42+# Read AGENTS.md, strip frontmatter
43+agents_content=$(sed -n '/^---$/,/^---$/!p' "$AGENTS_MD" 2>/dev/null || cat "$AGENTS_MD")
44+ 
45+# Build path guide — tell the agent where everything actually lives
46+path_guide="## CANNBot Installation Paths (model-infer-optimize)
47+ 
48+All relative references in skills/agents/workflows resolve to absolute paths:
49+- \`cann-recipes-infer/\` → \`${INFER_REPO_DIR}/\`
50+- \`skills/\` → \`${PLUGIN_ROOT}/skills/\`
51+- \`agents/\` → \`${PLUGIN_ROOT}/agents/\`
52+- \`workflows/\` → \`${PLUGIN_ROOT}/workflows/\`
53+ 
54+The shell variable \`\$INFER_REPO_DIR\` is exported for Bash tool calls."
55+ 
56+# Escape for JSON
57+escape_for_json() {
58+ local s="$1"
59+ s="${s//\\/\\\\}"
60+ s="${s//\"/\\\"}"
61+ s="${s//$'\n'/\\n}"
62+ s="${s//$'\r'/\\r}"
63+ s="${s//$'\t'/\\t}"
64+ printf '%s' "$s"
65+}
66+ 
67+path_guide_escaped=$(escape_for_json "$path_guide")
68+agents_escaped=$(escape_for_json "$agents_content")
69+session_context="<CANNBOT_CONTEXT>\nYou are CANNBot - NPU Model Inference Optimization Orchestrator.\n\n${path_guide_escaped}\n\n${agents_escaped}\n</CANNBOT_CONTEXT>"
70+ 
71+# Output JSON for Claude Code hook system
72+if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
73+ cat <<EOF
74+{
75+ "hookSpecificOutput": {
76+ "hookEventName": "SessionStart",
77+ "additionalContext": "${session_context}"
78+ }
79+}
80+EOF
81+else
82+ cat <<EOF
83+{
84+ "additional_context": "${session_context}"
85+}
86+EOF
87+fi
88+ 
89+exit 0
Aplugins/model-infer-optimize/hooks/subagent_stop.py+142-0
@@ -0,0 +1,142 @@
1+# ----------------------------------------------------------------------------------------------------------
2+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
3+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
4+# CANN Open Software License Agreement Version 2.0 (the "License").
5+# Please refer to the License for details. You may not use this file except in compliance with the License.
6+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
7+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
8+# See LICENSE in the root of the software repository for the full text of the License.
9+# ----------------------------------------------------------------------------------------------------------
10+"""SubagentStop hook: implementer 自验证检查 + 外循环重试限制"""
11+ 
12+import json
13+import logging
14+import os
15+import re
16+import sys
17+ 
18+logging.basicConfig(stream=sys.stderr, level=logging.WARNING, format="%(message)s")
19+logger = logging.getLogger(__name__)
20+ 
21+SELF_VERIFY_KEYWORDS_FULL = ["参考 skill", "代码加载", "编译", "推理", "输出"]
22+SELF_VERIFY_KEYWORDS_DEBUG = ["编译", "推理"]
23+MAX_RETRY_COUNT = 10 # implementer + reviewer 各 5 轮
24+ 
25+SELF_VERIFY_TEMPLATE = """自验证不完整：progress.md 缺少以下自验证项：{missing}。
26+请完成对应的验证步骤（而非仅补充文字记录），确认结果后写入 progress.md，然后再结束。
27+格式参考：
28+### 自验证结果
29+- 参考 skill: /xxx
30+- 代码加载: 确认推理加载的是修改后的模型模块和正确的模型配置
31+- 编译: 通过/失败
32+- 推理: 通过/失败
33+- 输出: 合理/异常"""
34+ 
35+RETRY_LIMIT_MSG = "重试上限：当前阶段已执行 {n} 轮 implementer/reviewer 循环，超过 5 轮上限。请回退当前阶段改动，向用户报告阻塞点。"
36+ 
37+ 
38+def find_progress_md(cwd):
39+ """找最近修改的 progress.md（纯 Python 实现，无外部命令依赖）"""
40+ candidates = []
41+ try:
42+ for dirpath, _dirs, filenames in os.walk(cwd):
43+ if "/.git/" in dirpath or dirpath.endswith("/.git"):
44+ continue
45+ if "progress.md" in filenames:
46+ candidates.append(os.path.join(dirpath, "progress.md"))
47+ except OSError:
48+ return None
49+ if not candidates:
50+ return None
51+ candidates.sort(key=lambda f: os.path.getmtime(f), reverse=True)
52+ return candidates[0]
53+ 
54+ 
55+def get_current_stage(content):
56+ """从 progress.md 中提取当前阶段号"""
57+ matches = re.findall(r"## 阶段\s*(\d+)", content)
58+ return matches[-1] if matches else "0"
59+ 
60+ 
61+def check_self_verification(data, progress_path, content):
62+ """检查 1：Implementer 自验证检查（P0，阻断）"""
63+ if data.get("agent_type") != "model-infer-implementer":
64+ return None
65+ 
66+ is_debug = "### 调试记录" in content and "[修复]" in content
67+ keywords = SELF_VERIFY_KEYWORDS_DEBUG if is_debug else SELF_VERIFY_KEYWORDS_FULL
68+ 
69+ if "### 自验证结果" not in content:
70+ missing = "、".join(keywords)
71+ return SELF_VERIFY_TEMPLATE.format(missing=missing)
72+ 
73+ verify_start = content.index("### 自验证结果")
74+ verify_section = content[verify_start:]
75+ next_section = verify_section.find("\n### ", 1)
76+ if next_section > 0:
77+ verify_section = verify_section[:next_section]
78+ 
79+ missing = [kw for kw in keywords if kw not in verify_section]
80+ if missing:
81+ return SELF_VERIFY_TEMPLATE.format(missing="、".join(missing))
82+ 
83+ return None
84+ 
85+ 
86+def check_retry_limit(data, content):
87+ """检查 2：外循环重试限制（P1，阻断）"""
88+ agent_type = data.get("agent_type", "")
89+ if agent_type not in ("model-infer-implementer", "model-infer-reviewer"):
90+ return None
91+ 
92+ session_id = data.get("session_id", "unknown")
93+ stage = get_current_stage(content)
94+ counter_file = f"/tmp/hook_retry_{session_id}_{stage}.count"
95+ 
96+ count = 0
97+ if os.path.exists(counter_file):
98+ try:
99+ with open(counter_file) as f:
100+ count = int(f.read().strip())
101+ except (ValueError, OSError):
102+ count = 0
103+ 
104+ count += 1
105+ with open(counter_file, "w") as f:
106+ f.write(str(count))
107+ 
108+ if count > MAX_RETRY_COUNT:
109+ rounds = count // 2
110+ return RETRY_LIMIT_MSG.format(n=rounds)
111+ 
112+ return None
113+ 
114+ 
115+def main():
116+ data = json.load(sys.stdin)
117+ cwd = data.get("cwd", ".")
118+ 
119+ progress_path = find_progress_md(cwd)
120+ if not progress_path:
121+ sys.exit(0)
122+ 
123+ try:
124+ with open(progress_path) as f:
125+ content = f.read()
126+ except OSError:
127+ sys.exit(0)
128+ 
129+ for check in [
130+ lambda: check_self_verification(data, progress_path, content),
131+ lambda: check_retry_limit(data, content),
132+ ]:
133+ reason = check()
134+ if reason:
135+ logger.error(reason)
136+ sys.exit(2)
137+ 
138+ sys.exit(0)
139+ 
140+ 
141+if __name__ == "__main__":
142+ main()
Aplugins/model-infer-optimize/hooks/time_reminder.py+72-0
@@ -0,0 +1,72 @@
1+# ----------------------------------------------------------------------------------------------------------
2+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
3+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
4+# CANN Open Software License Agreement Version 2.0 (the "License").
5+# Please refer to the License for details. You may not use this file except in compliance with the License.
6+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
7+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
8+# See LICENSE in the root of the software repository for the full text of the License.
9+# ----------------------------------------------------------------------------------------------------------
10+"""PreToolUse hook: 长时间任务周期提醒（非阻断注入）"""
11+ 
12+import json
13+import os
14+import sys
15+import time
16+ 
17+REMIND_AFTER_MINUTES = 60
18+REMIND_INTERVAL_MINUTES = 30
19+ 
20+ 
21+def main():
22+ data = json.load(sys.stdin)
23+ 
24+ agent_id = data.get("agent_id", "")
25+ if not agent_id:
26+ sys.exit(0)
27+ 
28+ now = time.time()
29+ start_file = f"/tmp/hook_start_{agent_id}.ts"
30+ remind_file = f"/tmp/hook_remind_{agent_id}.ts"
31+ 
32+ if not os.path.exists(start_file):
33+ with open(start_file, "w") as f:
34+ f.write(str(now))
35+ sys.exit(0)
36+ 
37+ with open(start_file) as f:
38+ start_time = float(f.read().strip())
39+ 
40+ elapsed_minutes = (now - start_time) / 60
41+ 
42+ if elapsed_minutes < REMIND_AFTER_MINUTES:
43+ sys.exit(0)
44+ 
45+ if os.path.exists(remind_file):
46+ with open(remind_file) as f:
47+ last_remind = float(f.read().strip())
48+ if (now - last_remind) / 60 < REMIND_INTERVAL_MINUTES:
49+ sys.exit(0)
50+ 
51+ with open(remind_file, "w") as f:
52+ f.write(str(now))
53+ 
54+ elapsed = int(elapsed_minutes)
55+ result = {
56+ "hookSpecificOutput": {
57+ "hookEventName": "PreToolUse",
58+ "permissionDecision": "allow",
59+ "additionalContext": (
60+ f"你已运行超过 {elapsed} 分钟。请确认："
61+ "1) 是否按 skill 流程的实施/调试步骤要求执行 "
62+ "2) 关键进展是否已写入 progress.md "
63+ "3) 审视当前改动方向是否正确：实施偏差应自行纠正，方案本身不可行应停止并返回主流程报告阻塞。"
64+ ),
65+ }
66+ }
67+ json.dump(result, sys.stdout)
68+ sys.exit(0)
69+ 
70+ 
71+if __name__ == "__main__":
72+ main()
Aplugins/model-infer-optimize/init.sh+9-0
@@ -0,0 +1,9 @@
1+#!/usr/bin/env bash
2+ 
3+set -euo pipefail
4+ 
5+PLUGIN_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
6+if [[ -f "${PLUGIN_DIR}/../../script/bin/source-plugin-init.sh" ]]; then
7+ exec bash "${PLUGIN_DIR}/../../script/bin/source-plugin-init.sh" "${PLUGIN_DIR}" "$@"
8+fi
9+exec bash "${PLUGIN_DIR}/../../../bin/source-plugin-init.sh" "${PLUGIN_DIR}" "$@"
Aplugins/model-infer-optimize/plugin-install.json+9-0
@@ -0,0 +1,9 @@
1+{
2+ "dependencies": [
3+ {
4+ "name": "cann-recipes-infer",
5+ "repository": "https://gitcode.com/cann/cann-recipes-infer.git",
6+ "expose": "cann-recipes-infer"
7+ }
8+ ]
9+}
Aplugins/model-infer-optimize/plugin-sources.json+19-0
@@ -0,0 +1,19 @@
1+{
2+ "skillsRepository": "vendor/cannbot-skills",
3+ "skills": [
4+ "model/model-infer-migrator",
5+ "model/model-infer-parallel-analysis",
6+ "model/model-infer-parallel-impl",
7+ "model/model-infer-kvcache",
8+ "model/model-infer-fusion",
9+ "model/model-infer-quantization",
10+ "model/model-infer-graph-mode",
11+ "model/model-infer-precision-debug",
12+ "model/model-infer-runtime-debug",
13+ "model/model-infer-multi-stream",
14+ "model/model-infer-prefetch",
15+ "model/model-infer-superkernel",
16+ "model/model-infer-profiling",
17+ "model/model-infer-perf-breakdown"
18+ ]
19+}
Aplugins/model-infer-optimize/quickstart.md+234-0
@@ -0,0 +1,234 @@
1+# NPU 模型推理优化快速入门
2+ 
3+## 概述
4+ 
5+`model-infer-optimize` 是 NPU 模型推理端到端优化 plugin，入口按意图分流两条互补流程：
6+ 
7+- **基础流程**：`workflows/optimize-workflow.md`，编排 `model-infer-analyzer` / `model-infer-implementer` / `model-infer-reviewer`，从零适配并按固定阶段（并行策略、KVCache/FA、融合算子、量化适配、图模式）优化到可运行 baseline。
8+- **探索流程**：`workflows/sota-approach-workflow.md`，编排 `model-infer-sota-*` 六个 Subagent，在已有 baseline 之上由 profiling 驱动、多方向发现候选、Plan/round 自循环收敛，按需调用多流、预取、SuperKernel 等单点优化。
9+ 
10+无 baseline 走基础流程；已有 baseline 按"固定阶段 vs profiling 探索"分流，意图不明时先澄清。
11+ 
12+## 一、环境搭建
13+ 
14+### 前置条件
15+ 
16+- 已安装 CANN Toolkit（建议 ≥ 9.0.0），具体版本配套关系请查阅 [CANN Release Notes](https://www.hiascend.com/cann/document)
17+- 已配置 NPU 设备（支持 Ascend 910/950 PR 等芯片）
18+- 已安装 OpenCode、Codex、Claude Code、TRAE 或 DSH
19+ 
20+### OpenCode（推荐）
21+ 
22+```bash
23+git clone https://gitcode.com/cann/cannbot.git
24+cd cannbot/plugins/model-infer-optimize
25+bash init.sh
26+```
27+ 
28+该命令默认安装到当前目录并使用 OpenCode，缺失的 Skill submodule 会自动初始化。安装到其他项目时可执行 `bash init.sh project opencode /path/to/target-project`。
29+ 
30+验证：
31+ 
32+```bash
33+opencode agent list
34+# 应看到 9 个 agent：model-infer-analyzer / -implementer / -reviewer 及 6 个 model-infer-sota-*（scenario/profiling-instrumenter/profile-analyzer/candidate/implementer/reviewer）
35+```
36+ 
37+### 其他工具
38+ 
39+<details>
40+<summary>Claude Code</summary>
41+ 
42+**首选：Plugin Marketplace（一键安装）**
43+ 
44+```text
45+# 注册 marketplace（首次，GitCode 仓库需完整 URL）
46+/plugin marketplace add https://gitcode.com/cann/cannbot.git
47+ 
48+# 安装插件
49+/plugin install model-infer-optimize@cannbot
50+/reload-plugins
51+```
52+ 
53+安装后新开会话，或在当前会话执行 `/clear` 触发插件上下文加载。`model-infer-optimize` 是主对话入口，会把 AGENTS.md 注入上下文，并按强制规则读取 `workflows/optimize-workflow.md`。
54+ 
55+验证：
56+ 
57+```bash
58+claude plugin list
59+# 应看到 model-infer-optimize@cannbot ✔ enabled
60+```
61+ 
62+**备选：init.sh 脚本**
63+ 
64+```bash
65+git clone --recurse-submodules https://gitcode.com/cann/cannbot.git
66+cd cannbot/plugins/model-infer-optimize
67+bash init.sh project claude /path/to/target-project
68+```
69+ 
70+</details>
71+ 
72+<details>
73+<summary>TRAE</summary>
74+ 
75+仅支持项目级安装。
76+ 
77+```bash
78+git clone --recurse-submodules https://gitcode.com/cann/cannbot.git
79+cd cannbot/plugins/model-infer-optimize
80+bash init.sh project trae /path/to/target-project
81+```
82+ 
83+安装后自动检测 TRAE 环境，生成 `.trae/`（TRAE IDE）、`.marscode/`（TRAE Plugin）或 `.traecli/`（TRAE CLI）目录，结构与 Claude/OpenCode 基本一致。
84+ 
85+</details>
86+ 
87+### 验证安装
88+ 
89+```bash
90+# OpenCode
91+opencode agent list
92+# 应看到 9 个 agent（3 基础 + 6 个 model-infer-sota-*）
93+ 
94+# Claude Code
95+claude plugin list
96+# 应看到 model-infer-optimize@cannbot ✔ enabled
97+ 
98+# TRAE
99+ls .trae/ # TRAE IDE
100+ls .marscode/ # TRAE Plugin（init.sh 自动检测）
101+ls .traecli/ # TRAE CLI（init.sh 自动检测）
102+# 应看到 skills/ agents/ cannbot-plugin.json
103+```
104+ 
105+## 二、快速上手
106+ 
107+### 启动
108+ 
109+```bash
110+# OpenCode
111+opencode
112+ 
113+# Claude Code
114+claude
115+```
116+ 
117+> **TRAE 用户**：TRAE 通过 IDE、VS Code 插件或 CLI 启动。安装器会优先使用项目中已存在的 `.traecli/`、`.marscode/`、`.trae/` 或 `.trae-cn/`，都不存在时默认创建 `.trae/`。
118+ 
119+### 模型优化示例
120+ 
121+在目标 `cann-recipes-infer` 或模型仓中提出需求：
122+ 
123+```text
124+帮我优化 deepseek-r1 模型的 NPU 推理性能
125+```
126+ 
127+primary agent 会按 AGENTS.md 中的强制规则自动读取 `workflows/optimize-workflow.md` 并按阶段推进。
128+ 
129+## 三、安装内容
130+ 
131+| 内容 | 说明 |
132+| --- | --- |
133+| 原子 skills（14 个） | 来自 `skills/model-infer-*`，覆盖推理优化各专项能力 |
134+| workflow 文档 | `plugins/model-infer-optimize/workflows/optimize-workflow.md` |
135+| Subagents | `plugins/model-infer-optimize/agents/model-infer-*.md` |
136+| hooks | 角色越界保护、progress.md 读取约束、自验证检查和长任务提醒 |
137+| 配置入口 | `AGENTS.md` / `CLAUDE.md`，强制读取 `workflows/optimize-workflow.md` |
138+ 
139+## 四、核心工作流
140+ 
141+```text
142+阶段 0：模型分析 + 性能基线
143+ ↓
144+阶段 1：并行化改造
145+ ↓
146+阶段 2：KVCache 静态化 + FA 算子替换
147+ ↓
148+阶段 3：融合算子优化
149+ ↓
150+阶段 4：量化适配（可选，用户提供 compressed-tensors 量化产物或明确要求量化时）
151+ ↓
152+阶段 5：图模式适配
153+ ↓
154+阶段 6：优化总结
155+```
156+ 
157+每个阶段遵循：分析 → 方案确认 → 实施 → 验证 → 阶段总结。
158+ 
159+## 五、可用技能（原子 skills）
160+ 
161+| Skill | 用途 |
162+| --- | --- |
163+| `model-infer-migrator` | 框架适配与基线建立 |
164+| `model-infer-parallel-analysis` | 并行策略分析 |
165+| `model-infer-parallel-impl` | 并行切分实施 |
166+| `model-infer-kvcache` | KVCache + FA 优化 |
167+| `model-infer-fusion` | 融合算子分析与替换 |
168+| `model-infer-quantization` | compressed-tensors 量化适配、验证和收益评估 |
169+| `model-infer-graph-mode` | 图模式适配 |
170+| `model-infer-precision-debug` | NPU 推理精度诊断 |
171+| `model-infer-runtime-debug` | NPU 运行时错误诊断 |
172+| `model-infer-multi-stream` | 多流并行优化 |
173+| `model-infer-prefetch` | 权重预取 |
174+| `model-infer-superkernel` | SuperKernel 适配 |
175+ 
176+端到端优化流程由 `workflows/optimize-workflow.md` 承载，由 primary agent 自动加载，不作为可独立调用的 skill 暴露。
177+ 
178+## 六、可用 Agents
179+ 
180+| Agent | 职责 |
181+| --- | --- |
182+| `model-infer-analyzer` | 模型分析、方案设计、并行策略推荐 |
183+| `model-infer-implementer` | 代码改造、调试修复、自验证 |
184+| `model-infer-reviewer` | 精度验证、性能对比、结构化诊断 |
185+ 
186+## 七、常见问题
187+ 
188+### Q: 如何查看帮助信息？
189+ 
190+```bash
191+bash init.sh --help
192+```
193+ 
194+### Q: 是否支持全局安装？
195+ 
196+统一安装器当前只支持项目级安装，避免多个项目共享可变配置。
197+ 
198+### Q: 如何更新？
199+ 
200+```bash
201+# OpenCode (init.sh 方式)
202+cd cannbot/plugins/model-infer-optimize && bash init.sh
203+ 
204+# Claude Code
205+/plugin update model-infer-optimize@cannbot
206+ 
207+# TRAE
208+cd cannbot/plugins/model-infer-optimize && bash init.sh project trae
209+ 
210+```
211+ 
212+### Q: 端到端优化和单点优化如何选择？
213+ 
214+| 场景 | 推荐方式 |
215+|------|---------|
216+| 模型从适配到性能达标的完整链路 | 端到端 plugin（`帮我优化 XX 模型的 NPU 推理性能`）|
217+| 已部署模型，仅需做 KVCache / FA 替换 | 直接调用 `model-infer-kvcache` skill |
218+| 已部署模型，仅需做并行策略分析或实施 | 调用 `model-infer-parallel-analysis` / `model-infer-parallel-impl` skill |
219+| 已部署模型，仅需做融合算子替换 | 直接调用 `model-infer-fusion` skill |
220+| 已部署模型，仅需接入 compressed-tensors 量化产物 | 直接调用 `model-infer-quantization` skill |
221+| 已部署模型，仅需做图模式适配 | 直接调用 `model-infer-graph-mode` skill |
222+| 已部署模型，仅需诊断精度或运行时错误 | 直接调用 `model-infer-precision-debug` / `model-infer-runtime-debug` skill |
223+ 
224+> 单点 skill 由 Claude 通过描述匹配自动激活，不会触发 6 阶段端到端工作流。
225+ 
226+---
227+ 
228+## 总结
229+ 
230+1. 端到端优化通过 `workflows/optimize-workflow.md` 编排 6 阶段流程，并在需要时插入可选量化阶段
231+2. npm 用户使用 `npx`，源码开发者使用薄 `init.sh` 入口，两者共用同一安装实现
232+3. `opencode` / `claude` 是核心交互指令；TRAE 打开项目后自动加载项目配置
233+4. 单点优化（KVCache、并行、融合算子、量化等）由 14 个原子 skill 自动激活，不进入端到端流程
234+5. 所有阶段通过门禁驱动，支持断点续跑与失败恢复
Aplugins/model-infer-optimize/workflows/optimize-workflow.md+649-0
@@ -0,0 +1,649 @@
1+# NPU 模型推理端到端优化工作流
2+ 
3+## 概述
4+ 
5+本工作流编排三个专业化 subagent（model-infer-analyzer / model-infer-implementer / model-infer-reviewer）对目标模型按阶段执行 NPU 推理优化。
6+ 
7+```
8+阶段 0: 模型分析与建立基线
9+阶段 1: 并行化改造（多卡部署时）
10+阶段 2: KVCache + FA
11+阶段 3: 融合算子
12+阶段 4: 量化适配改造（如阶段 0 已完成量化初评估且用户启用）
13+阶段 5: 图模式适配
14+阶段 6: 优化总结
15+```
16+ 
17+每个优化阶段遵循统一流程：分析 → 方案确认 → 实施 → 验证 → 阶段总结。
18+ 
19+---
20+ 
21+## 重要原则
22+ 
23+- **严格按阶段流程执行**：逐阶段推进，每阶段完成分析→用户确认→实施→验证→总结的完整流程后才能进入下一阶段，不可跳过或并行
24+- **保持模型完整性**：不为通过验证而简化模型实现、删减功能或降低优化标准
25+- **主 agent 只做编排**：主 agent 负责派发 subagent、呈现报告、用户确认，不直接修改模型代码或自行实施优化。FAIL 后必须派发 implementer 修复，不能自己改代码
26+- **implementer 自验证检查**：implementer 返回后，读 progress.md 自验证 section，确认五项（参考 skill、代码加载、编译、推理、输出）完整且与常驻区环境一致（如常驻区有 NPU 环境则推理项不应为空）。缺失或矛盾 → 拒绝重派。不自行审查代码替代验证
27+- **验证前提检查**：任何验证结果的前提是被测代码确实被执行。验证前先确认修改后的代码被加载和走到（如检查日志中的模型路径、关键优化标记）
28+- **异常把控**：主 agent 对各阶段 subagent 报告中的异常保持敏感（分析结论不合理、性能数据与改动预期不符、精度异常等），不接受未经调查的报告，要求 subagent 重新调查。输出不可读（重复 token、乱码、空文本、全 EOS）是硬 FAIL，不可降级——性能优化不改变计算正确性；reviewer 报告 PASS 但主 agent 审核发现硬指标异常时，应判 FAIL 或向用户确认
29+- **subagent 派发规范**：dispatch prompt 严格只包含模板代码块内的字段和占位符，除用户明确要求外，不以任何形式附加上下文（如分析结论、技术方案、实施流程、部署配置等）。subagent 通过读取 progress.md 获取上下文，主 agent 不在 dispatch 中转述
30+ 
31+---
32+ 
33+## 共享状态文件
34+ 
35+> **agent 产物位置约定**：所有 agent 流程产物（progress.md / progress_history.md / optimization_report.md / baseline/ 等）统一归入模型目录下的 `agentic/` 子目录，模型根目录只保留模型本身的代码、配置与入口（modeling / config / infer.sh / requirements / README）。下文中所有 `progress.md` / `baseline/` 等裸引用均指 `{model_dir}/agentic/` 下的同名文件。
36+ 
37+`{model_dir}/agentic/progress.md`：常驻区（阶段 0 分析 + 进度概览表）+ 工作区（当前阶段记录）。初始模板见 `templates/progress_template.md`。
38+ 
39+`{model_dir}/agentic/progress_history.md`：历史归档。除阶段 6 优化总结外，默认仅 Grep 查找；阶段 6 允许一次性 Read 全文用于生成总报告。
40+ 
41+**读写规则**：常驻区由 阶段 0 写入，后续只有主 agent 更新概览表。工作区由各 subagent 追加，写入前先读取现有内容。
42+ 
43+**阶段推进**：每阶段验证通过后，主 agent 更新概览表 → 调用 `scripts/archive_progress.py` 归档工作区 → 清空工作区。阶段 0 不归档。
44+ 
45+---
46+ 
47+## 工作流程
48+ 
49+### 阶段 0：模型分析与建立基线
50+ 
51+#### 0.1 信息收集
52+ 
53+若用户未提供以下信息，主 agent 使用提问工具向用户确认：
54+- **模型工作目录**：模型代码所在路径（如 `cann-recipes-infer/models/xxx`）
55+- **模型来源**：HuggingFace 链接、本地权重路径、或仓库内已有
56+- **权重路径**：已下载的权重位置（如未下载可后续处理）
57+- **部署模式**：默认 `框架部署`（cann-recipes-infer 仓库主推，接入 `executor/core/`）。仅在用户明确表示要在仓外使用 / 不接框架时改为 `独立部署`
58+ 
59+#### 0.2 启动分析 subagent
60+ 
61+派发 model-infer-analyzer：
62+ 
63+```
64+工作目录: {model_dir}
65+任务: 模型架构全面分析
66+模型来源: {HuggingFace 链接 / 本地路径 / 仓库内已有}
67+分析内容:
68+ - 架构类型（LLM / MoE / Diffusion / 多模态）
69+ - 网络结构拆解（Embedding → Transformer Blocks → Output Head）
70+ - Prefill / Decode 分支差异
71+ - 关键模块：Attention 类型（GQA/MHA/MLA）、FFN/MoE 结构、特殊模块。架构识别必须基于实际 config 值（config.json / model.config），不能仅从代码类定义推断——注意可配置开关（如 use_mla、n_routed_experts）
72+ - 运行环境：通过 `asys info -r=status` 确认 NPU 型号（运行前需 source CANN 包路径：source /usr/local/Ascend/ascend-toolkit/latest/bin/setenv.bash）；通过 `npu-smi info` 确认单卡 HBM 容量，记录量化模式、执行模式、部署卡数
73+ - 模型当前状态：确认代码是否存在且可运行（有 infer.sh 且能跑通）、agentic/baseline/baseline_metadata.json 是否存在。报告状态（可运行/不可运行/需多卡），不自行采集基线数据
74+ - 若模型不可运行，记录具体原因和缺失项
75+输出:
76+ - 使用 templates/progress_template.md 创建 {model_dir}/agentic/progress.md，将分析结果写入常驻区（模型信息、并行策略、进度概览）
77+ - 使用 templates/optimization_report_template.md 初始化 {model_dir}/agentic/optimization_report.md
78+```
79+ 
80+#### 0.3 分析确认与状态分流
81+ 
82+主 agent 将 analyzer 返回的分析结果呈现给用户确认，根据模型状态确定路径：
83+ 
84+- **a. 模型可运行** → 进入 0.4 采集基线
85+- **b. 模型无法运行（代码缺失或适配不完整）** → 进入 0.4 框架适配
86+- **c. 模型需多卡部署（单卡显存不足）** → 进入 0.4 或直接进入阶段 1
87+ 
88+#### 0.4 框架适配与基线建立
89+ 
90+根据 0.3 确定的路径派发 implementer：
91+ 
92+**路径 a（模型可运行）**：
93+ 
94+```
95+必须使用 skill: model-infer-migrator
96+工作目录: {model_dir}
97+部署模式: {框架部署 / 独立部署}
98+任务: 部署基线采集
99+```
100+ 
101+implementer 返回后，提取 baseline_metadata.json 摘要写入 progress.md 常驻区 → 进入 0.5 量化候选确认；若用户不启用量化，则进入阶段 2
102+ 
103+**路径 b（模型无法运行）**：
104+ 
105+```
106+必须使用 skill: model-infer-migrator
107+工作目录: {model_dir}
108+部署模式: {框架部署 / 独立部署}
109+任务: 框架适配 + 部署基线建立
110+模型来源: {HuggingFace 链接 或 本地路径}
111+权重路径: {如已知}
112+```
113+ 
114+implementer 返回后：
115+- 若输出 baseline_metadata.json → 提取摘要写入 progress.md 常驻区 → 进入 0.5 量化候选确认；若用户不启用量化，则进入阶段 2
116+- 若标记"需多卡" → 进入阶段 1 并行化
117+ 
118+**路径 c（模型需多卡部署）**：
119+- 若代码已存在（仓库内已有框架适配的模型）→ 进入 0.5 量化候选确认；若用户不启用量化，则进入阶段 1，并行基线在并行跑通后建立
120+- 若代码不存在 → 先按路径 b 派发 migrator 完成单卡框架适配（完整的 modeling + configuration + YAML + infer.sh，并注册到 cann-recipes-infer/executor/core/support_models.py，作为并行化改造的代码基础），migrator 标记"需多卡"后进入 0.5 量化候选确认；若用户不启用量化，则进入阶段 1
121+ 
122+#### 0.5 量化候选确认与方案初评估
123+ 
124+> 本步骤属于阶段 0 的扩展分析，只评估量化方案，不修改代码。
125+> 量化初评估结论作为后续并行、融合、图模式和量化改造的参考输入。
126+> 若用户不启用量化候选，则跳过本步骤和阶段 4 量化适配改造，直接进入后续非量化优化阶段。
127+ 
128+阶段 0 完成模型分析、且模型代码具备可读的框架适配基础后，主 agent 先向用户确认是否启用量化候选。
129+ 
130+1. 若用户不启用量化，记录决策，跳过 0.5 和阶段 4。
131+2. 若用户启用量化，继续确认是否已有 `quant_export_dir`。
132+3. 若已有量化产物，用户提供 `quant_export_dir`，进入量化方案初评估。
133+4. 若尚无量化产物，记录“量化产物未交付”，跳过 0.5 和阶段 4；用户后续交付 `quant_export_dir` 后，可从 0.5 重新进入量化方案初评估。在产物返回前，主流程不得进入量化改造。
134+ 
135+`quant_export_dir` 是 infer 侧消费的上游量化产物目录，不是模型工作目录；它可以来自用户已有产物、AMCT 或其它量化产物生成流程的输出。
136+ 
137+量化初评估前，主 agent 需确认用户已交付完整量化产物目录。典型交付物包括量化配置文件（如 `config.json`）、权重索引文件（如 `model.safetensors.index.json`）、量化权重文件（如 `*.safetensors`）和量化交付说明（如 `deploy_quantization.md`）。具体契约由 `model-infer-quantization` skill 检查；缺关键交付物时，不派发改造，只要求补充量化算法或产物契约。
138+ 
139+派发 model-infer-analyzer：
140+ 
141+```
142+工作目录: {model_dir}
143+必须使用 skill: model-infer-quantization
144+任务: 量化方案初评估
145+量化产物目录: {quant_export_dir}
146+分析内容:
147+ - 检查量化产物契约、结构匹配、接入分级和部署形态估算
148+ - 按模型结构判断，不按模型名称套用参考
149+ - 不修改模型代码，不采集基线
150+ - 若契约不满足，输出量化算法或产物契约补充诉求
151+```
152+ 
153+主 agent 执行：
154+ 
155+1. 若量化初评估报告明确“无法安全接入”“需补充量化产物契约”或“建议暂不量化”，记录补充诉求，后续阶段按非量化路径推进。
156+2. 若量化初评估报告明确可接入，写入 progress.md 常驻区，至少包含契约结论、结构参考卡、接入分级、显存/部署判断、对后续阶段的影响；若评估显示量化后可能收敛卡数，只作为并行决策输入，不在本步骤修改代码。
157+3. 向用户确认是否保留量化改造候选；若保留，则后续阶段在做并行、融合、图模式决策时参考该量化信息。
158+ 
159+---
160+ 
161+### 阶段 1：并行化改造
162+ 
163+> 单卡模型跳过本阶段。并行策略影响后续所有阶段的代码结构（通信组、TP 切分、EP 路由），必须先于 KVCache/FA 改造完成。
164+> 本阶段仍按非量化部署路径实施和验证；阶段 0.5 的量化初评估只作为显存、卡数和后续量化候选的参考输入。
165+ 
166+#### 1.1 确认部署需求
167+ 
168+主 agent 使用提问工具向用户确认：
169+ 
170+1. **部署卡数和节点配置**：总卡数、每节点几卡（影响 TP 上限）
171+2. **目标场景**：高吞吐 / 低时延 / 均衡
172+3. **实际序列长度**：决定是否需要 CP / KVP
173+4. **batch size 需求**（如有）
174+ 
175+确认后结合 阶段 0 的模型参数、硬件信息和量化初评估（如有）做快速可行性检查：
176+- 卡数 × 单卡显存是否能容纳模型参数；若 progress.md 已有量化初评估，同时给出浮点口径和量化口径
177+- MoE 模型的专家数是否 ≥ 卡数（否则 EP 不可行）
178+- 序列长度 × KV Cache 是否超出总显存
179+ 
180+有矛盾则向用户反馈，调整卡数、batch size 或序列长度后再派发分析。
181+ 
182+#### 1.2 启动分析 subagent
183+ 
184+派发 model-infer-analyzer：
185+ 
186+```
187+工作目录: {model_dir}
188+必须使用 skill: model-infer-parallel-analysis
189+任务: 并行策略分析（至少包含以下内容）
190+部署需求:（填入 1.1 确认的结果）
191+分析内容:
192+ - 提取模型参数和模块链路
193+ - 基于单套 parallel_config 分析整体并行策略，结合目标场景权衡 Prefill/Decode
194+ - 定量估算（显存、通信量），确定 parallel_config 具体值
195+ - 输出 2-3 个候选方案并排序
196+```
197+ 
198+#### 1.3 方案确认
199+ 
200+主 agent 使用提问工具向用户确认关键决策：
201+ 
202+1. **整体并行策略**：纯 TP / MoE EP / 模块级差异化并行？
203+2. **各模块 TP 度**：attn_tp / dense_tp / moe_tp / embed_tp / lmhead_tp / oproj_tp
204+3. **长序列附加配置**：是否引入 CP / KVP？
205+4. 其他需确认的细节（AFD、EPLB 等进阶配置）
206+ 
207+用户确认后进入实施。
208+ 
209+#### 1.4 启动实施 subagent
210+ 
211+派发 model-infer-implementer：
212+ 
213+```
214+工作目录: {model_dir}
215+必须使用 skill: model-infer-parallel-impl
216+部署模式: {框架部署 / 独立部署}
217+任务: 并行化改造（至少包含以下内容）
218+阶段要点:
219+ - 按已确认的 parallel_config 实施
220+ - 通信组创建 → 逐模块并行层替换 → Embed/LMHead 并行 → YAML 配置 → 权重处理
221+自验证:
222+ - 编译通过、多卡推理无 crash、吐字正常（可读、不重复、非全零、不提前 EOS）
223+ - 实施记录写入 progress.md 工作区
224+```
225+ 
226+> **验收 gate**：执行"implementer 自验证检查"（见重要原则）。不通过 → 拒绝重派。
227+ 
228+#### 1.5 启动验证 subagent
229+ 
230+派发 model-infer-reviewer：
231+ 
232+```
233+工作目录: {model_dir}
234+部署模式: {框架部署 / 独立部署}
235+任务: 并行化改造后验证
236+约束: 禁止修改模型代码和自行调试，仅返回验证报告
237+至少包含以下验证:
238+验证内容:
239+ - 精度: 运行多卡推理，输出与基线对比
240+ - 性能: 运行推理，对比改造前后的 Prefill 耗时和 Decode 单步耗时
241+ - 结果写入 progress.md 工作区（精度验证 + 性能验证 section）
242+检查项:
243+ - parallel_config 各参数已正确实施（YAML 配置与代码一致）
244+ - 各 rank 吐字正常（可读、不重复、非全零、不提前 EOS）
245+```
246+ 
247+#### 1.6 Profiling 策略校准（TODO：待适配）
248+ 
249+> 当前暂不可用，跳过此步骤。后续适配后启用。
250+ 
251+派发 model-infer-analyzer：
252+ 
253+```
254+工作目录: {model_dir}
255+必须使用 skill: model-infer-parallel-analysis（第五步 Profiling 校准）
256+任务: 并行策略 profiling 校准
257+分析内容:
258+ - 通信占比是否合理（< 20%）
259+ - 各 Rank 耗时是否均衡（MoE EP 场景）
260+ - 显存峰值是否与估算一致
261+ - 若偏差过大，给出调整建议
262+```
263+ 
264+#### 1.7 阶段总结
265+ 
266+主 agent 执行：
267+1. reviewer 报告 FAIL → 派发 model-infer-implementer 修复 → 重新验证，最多 5 轮
268+2. profiling 校准发现策略问题或性能未达预期 → 回到 1.2 调整 parallel_config 重新确认（TODO：待 profiling 适配后启用）
269+3. 若 阶段 0 标注"无基线"（模型需多卡才能运行），并行验证通过后派发 model-infer-implementer 采集基线：
270+ 
271+ ```
272+ 必须使用 skill: model-infer-migrator
273+ 工作目录: {model_dir}
274+ 部署模式: {框架部署 / 独立部署}
275+ 任务: 部署基线采集
276+ ```
277+ 
278+ implementer 返回后，提取 baseline_metadata.json 摘要写入 progress.md 常驻区。后续阶段的性能对比以此次采集的基线为准，忽略并行验证阶段的性能数据。
279+4. 全部通过后，综合结果输出阶段总结报告
280+5. 向用户确认当前阶段优化，确认后提交 commit，进入下一阶段
281+ 
282+---
283+ 
284+### 阶段 2：KVCache 静态化 + FA 算子替换
285+ 
286+> 框架部署模式默认推荐路径：**PA + FA + TND**（标准 LLM）/ **PA + FA + TND_NTD + MLA absorb**（MLA 模型）/ **PA + FA + TND + 滑窗约束**（含滑窗层）。migrator 阶段产出的 Legacy KV + HF 原版 SDPA + BSH 是过渡骨架，本阶段主要负责升级到默认推荐路径。具体选型由 analyzer 输出，详见 `docs/design/kv_cache_design.md` 与 model-infer-kvcache skill。
287+> 后续阶段 3 的融合算子优化专注于 Attention Core 之外的模块。
288+> 本阶段仍按非量化部署路径实施和验证，不切换量化权重或量化运行配置。
289+ 
290+#### 2.1 启动分析 subagent
291+ 
292+派发 model-infer-analyzer：
293+ 
294+```
295+工作目录: {model_dir}
296+部署模式: {框架部署 / 独立部署}
297+必须使用 skill: model-infer-kvcache（关注第一层快速选型 + 第二层数据结构与算子）
298+任务: KVCache 模式分析和选型
299+分析内容:
300+ - 框架部署默认走 PA + FA + TND（MLA 用 TND_NTD）；评估是否需要偏离默认
301+ - 确定每个 cache 的 attn_type（FullAttention / SlidingWindow）
302+ - 是否启用 MLA absorb、是否多 attn_type 混合
303+ - FA 算子版本（v1 / v2）与 layout 选择
304+ - 估算块数 / 单卡显存占用
305+```
306+ 
307+#### 2.2 方案确认
308+ 
309+主 agent 使用提问工具向用户逐条确认关键决策（框架部署默认推荐 PA + FA + TND，仅在架构限制 / 算子不兼容 / 特殊性能目标下偏离）：
310+ 
311+1. **KVCache 模式**：默认 PA；仅在特殊场景回退连续缓存
312+2. **attn_type**：FullAttention / SlidingWindow（含混合层场景）
313+3. **MLA absorb 路径**（仅 MLA 模型）：是否启用 absorb（影响 FA 入参和 rope 处理）
314+4. **FA 算子 + layout**：v1 / v2；标准 LLM 默认 TND，MLA 默认 TND_NTD
315+5. 其他偏离默认的方案细节（如 KVP / 多 attn_type 混合等）
316+ 
317+用户确认后进入实施。
318+ 
319+#### 2.3 启动实施 subagent
320+ 
321+派发 model-infer-implementer：
322+ 
323+```
324+工作目录: {model_dir}
325+部署模式: {框架部署 / 独立部署}
326+必须使用 skill: model-infer-kvcache（关注第三层实施流程对应大节）
327+任务: 阶段 2 KVCache + FA 改造（至少包含以下内容）
328+阶段要点:
329+ - 按已确认的 KVCache 模式 / attn_type / FA 算子方案实施
330+ - 框架部署：cache_entries 配置 + get_cache_info 实现 + attention forward 内 block_table[self.attn_type] / slot_mapping[self.attn_type] 字典访问
331+ - 独立部署：Runner 自管 KV + block_table / slot_mapping + ForwardMetaData 构造
332+ - 写入算子用 npu_scatter_nd_update_（MLA 用 npu_kv_rmsnorm_rope_cache 融合）
333+ - 阶段分支用 forward_metadata.is_prefill；hidden_states 全程保持 [TotalTokens, hidden_size] 二维（不要 reshape 成 BS）
334+自验证:
335+ - 编译通过、推理无 crash、吐字正常（可读、不重复、非全零、不提前 EOS）
336+ - 实施记录写入 progress.md 工作区
337+```
338+ 
339+> **验收 gate**：执行"implementer 自验证检查"（见重要原则）。不通过 → 拒绝重派。
340+ 
341+#### 2.4 启动验证 subagent
342+ 
343+派发 model-infer-reviewer：
344+ 
345+```
346+工作目录: {model_dir}
347+部署模式: {框架部署 / 独立部署}
348+任务: KVCache + FA 改造后验证
349+约束: 禁止修改模型代码和自行调试，仅返回验证报告
350+至少包含以下验证:
351+验证内容:
352+ - 精度: 运行推理，Prefill/Decode 输出与基线对比
353+ - 性能: 运行推理，对比改造前后的 Prefill 耗时和 Decode 单步耗时
354+ - 性能验证: 若工作目录下有 agentic/baseline/baseline_metadata.json，用它作为性能对比基准
355+ - 结果写入 progress.md 工作区（精度验证 + 性能验证 section）
356+检查项:
357+ - KVCache 模式选型、静态化实现及 FA 算子替换已完成（框架部署：cache_entries + get_cache_info + forward 接入 block_table[attn_type]；独立部署：Runner 自管 KV + 自管 forward_metadata）
358+ - Prefill 和 Decode 阶段缓存逻辑差异已正确处理（阶段分支用 forward_metadata.is_prefill）
359+ - hidden_states 全程保持 [TotalTokens, hidden_size] 二维形态
360+```
361+ 
362+#### 2.5 阶段总结
363+ 
364+主 agent 执行：
365+1. reviewer 报告 FAIL → 派发 model-infer-implementer（调试 KVCache/FA 精度问题，使用 model-infer-precision-debug skill）→ 重新派发 model-infer-reviewer 验证，最多 5 轮
366+2. 5 轮仍未解决 → 回退问题模块或整阶段改动 → 向用户报告阻塞点，请求决策
367+3. 调试发现需更换 KVCache 方案 → 回到 2.3 重新实施
368+4. 精度达标但性能未提升 → 派发 model-infer-analyzer（排查性能问题：部署配置、前置处理开销、测试方法、NPU 利用率等）→ 将分析和建议呈现给用户决策
369+5. 全部通过后，综合 analyzer/implementer/reviewer 的结果，输出阶段总结报告
370+6. 向用户确认当前阶段优化，确认后提交 commit，进入下一阶段
371+ 
372+---
373+ 
374+### 阶段 3：融合算子优化
375+ 
376+> 若阶段 2 已完成 FA 算子替换，则本阶段跳过 FA 算子本身，但 Attention 子链路（RoPE 融合、KV write 融合、QK Norm 等）仍需分析和优化。
377+> 本阶段仍按非量化部署路径实施和验证；融合结果会在阶段 4 复核是否兼容量化。
378+ 
379+#### 3.1 启动分析 subagent
380+ 
381+派发 model-infer-analyzer：
382+ 
383+```
384+工作目录: {model_dir}
385+必须使用 skill: model-infer-fusion（关注分析匹配部分，步骤 1-4）
386+任务: 融合算子匹配分析
387+分析内容:
388+ - 拆解模型各模块，识别可替换的计算模式
389+ - 匹配仓库已有模型的融合算子用法
390+ - 若阶段 2 已完成 FA 替换（见 progress.md），跳过 FA 算子本身，但 Attention 子链路仍需分析
391+ - 覆盖所有模块：Attention 子链路（RoPE、KV write、QK Norm）、MoE、FFN、Norm 等
392+ - 输出候选替换清单（原算子 → NPU 融合算子 → 替换理由）
393+```
394+ 
395+#### 3.2 方案确认
396+ 
397+主 agent 使用提问工具向用户分模块确认关键决策：
398+ 
399+1. **Attention 子链路替换**：RoPE 融合、KV write 融合、QK Norm 等（注意：仅跳过已在阶段 2 完成的 FA 算子，子链路仍需分析）
400+2. **MoE / FFN 模块替换**：MoE routing、grouped_matmul、激活函数融合等
401+3. **Norm / 其他模块替换**：RMSNorm、残差流融合等
402+4. **跳过模块的理由**：是否认可各跳过理由？（不能仅因"改动大"跳过）
403+5. 其他需用户确认的方案细节（如替换优先级、特殊算子参数选择等）
404+ 
405+用户确认后进入实施。
406+ 
407+#### 3.3 启动实施 subagent
408+ 
409+派发 model-infer-implementer：
410+ 
411+```
412+工作目录: {model_dir}
413+必须使用 skill: model-infer-fusion（关注实施替换部分，步骤 5）
414+任务: 阶段 3 融合算子优化（至少包含以下内容）
415+阶段要点:
416+ - 若阶段 2 已完成 FA 替换（见 progress.md），跳过 FA 算子本身，Attention 子链路仍需优化
417+ - 覆盖所有模块：Attention 子链路、MoE、FFN、Norm 等
418+自验证:
419+ - 编译通过、推理无 crash、吐字正常（可读、不重复、非全零、不提前 EOS）
420+ - 实施记录写入 progress.md 工作区
421+```
422+ 
423+> **验收 gate**：执行"implementer 自验证检查"（见重要原则）。不通过 → 拒绝重派。
424+ 
425+#### 3.4 启动验证 subagent
426+ 
427+派发 model-infer-reviewer：
428+ 
429+```
430+工作目录: {model_dir}
431+任务: 融合算子替换后验证
432+约束: 禁止修改模型代码和自行调试，仅返回验证报告
433+至少包含以下验证:
434+验证内容:
435+ - 精度: 运行推理，每个替换模块独立对比替换前后的输出
436+ - 性能: 运行推理，整体 Prefill/Decode 耗时对比替换前
437+ - 性能验证: 若工作目录下有 agentic/baseline/baseline_metadata.json，用它作为性能对比基准
438+ - 结果写入 progress.md 工作区（精度验证 + 性能验证 section）
439+检查项:
440+ - 所有模块的分析与替换决策已完成
441+ - 每个替换模块均有精度和性能对比结果
442+ - 跳过的模块有硬约束理由（不能仅因"改动大"跳过）
443+```
444+ 
445+#### 3.5 阶段总结
446+ 
447+主 agent 执行：
448+1. reviewer 报告 FAIL → 派发 model-infer-implementer（修复对应模块的融合算子精度问题）→ 重新派发 model-infer-reviewer 验证，最多 5 轮
449+2. 5 轮仍未解决 → 回退问题模块或整阶段改动 → 向用户报告阻塞点，请求决策
450+3. 精度达标但性能未提升 → 派发 model-infer-analyzer（排查性能问题：部署配置、前置处理开销、测试方法、NPU 利用率等）→ 将分析和建议呈现给用户决策
451+4. 全部通过后，综合 analyzer/implementer/reviewer 的结果，输出阶段总结报告
452+5. 向用户确认当前阶段优化，确认后提交 commit，进入下一阶段
453+ 
454+---
455+ 
456+### 阶段 4：量化适配改造
457+ 
458+> 本阶段在融合算子改造后、图模式适配前执行。图模式应尽量捕获最终 dtype、layout、kernel 和 cache 路径，因此量化改造优先先于图模式完成。
459+> 若阶段 0 未提供量化产物或用户暂不启用量化，则跳过本阶段进入图模式适配。
460+> 本阶段只接入已交付的量化方案和权重，不重新设计上游量化算法，不擅自扩展未确认的量化路线。
461+> 本阶段严格按既定量化方案和量化权重验证，不因报错擅自修改量化方案；若融合算子不支持量化，按用户确认的回退原则处理。
462+> 阶段 4 实施并验证通过前，当前默认部署路径仍是非量化融合后模型；只有用户接受量化实测结果后，量化路径才作为阶段 5 输入。
463+ 
464+#### 4.1 量化接入前变更复核
465+ 
466+本步骤只判断前置阶段的后续改动是否破坏量化初评估结论，不重做完整初评估。主 agent 先读取量化初评估报告：
467+ 
468+- 若量化初评估报告缺失或已过期，回到 0.5 重新做量化方案初评估，不在本步骤补做完整分析。
469+- 若量化初评估报告可用，派发 model-infer-analyzer 做轻量变更复核：
470+ 
471+```
472+工作目录: {model_dir}
473+必须使用 skill: model-infer-quantization
474+任务: 量化接入前变更复核
475+量化产物目录: {quant_export_dir}
476+分析内容:
477+ - 快速复核前置阶段相对量化初评估的变化是否影响量化接入
478+ - 聚焦权重加载、runtime object、模块前缀、dtype/layout/cache、post-load 和融合回退决策
479+ - 若无影响，明确沿用量化初评估结论
480+ - 不重做完整初评估，不修改模型代码，不采集基线
481+```
482+ 
483+若变更复核明确不满足量化条件，本阶段不派发 implementer，只输出阻塞点和补充诉求，随后由用户确认是否跳过量化进入阶段 5。
484+ 
485+#### 4.2 改造前用户决策
486+ 
487+主 agent 基于量化初评估报告、量化接入前变更复核结论（如有）和量化前最新基线，将复核后的最新量化方案呈现给用户确认。
488+ 
489+若用户暂不量化或选择保留融合并跳过量化，记录原因，跳过到阶段 5。
490+若用户选择停止并补量化方案，输出阻塞点、融合量化需求和产物契约诉求，不继续后续阶段。
491+若用户确认继续量化改造，进入实施。
492+ 
493+#### 4.3 启动实施 subagent
494+ 
495+仅当用户选择“继续量化改造”时派发 model-infer-implementer：
496+ 
497+```
498+工作目录: {model_dir}
499+必须使用 skill: model-infer-quantization
500+任务: 阶段 4 量化适配改造与量化权重加载
501+量化产物目录: {quant_export_dir}
502+量化前最新基线: {latest_baseline}
503+任务要点:
504+ - 按用户确认的量化路线接入配置、权重、runtime 映射和 post-load 处理
505+ - 严格使用既定量化方案和量化权重，不因报错修改 target / ignore / 张量语义
506+ - 若融合算子不支持量化，按用户确认的回退原则处理，并记录清单
507+ - 获取量化部署基线；若量化后单卡可满足，按确认部署口径验证
508+自验证:
509+ - 量化模型可加载，Prefill / Decode 跑通，输出可读且有量化路径生效证据
510+ - 融合算子回退清单、原始错误和后续融合量化需求已记录
511+```
512+ 
513+> **验收 gate**：执行"implementer 自验证检查"（见重要原则）。不通过 → 拒绝重派。
514+ 
515+#### 4.4 启动验证 subagent
516+ 
517+派发 model-infer-reviewer：
518+ 
519+```
520+工作目录: {model_dir}
521+任务: 阶段 4 量化适配验证
522+约束: 禁止修改模型代码和自行调试，仅返回验证报告
523+至少包含以下验证:
524+验证内容:
525+ - 量化权重确已加载，且日志或状态文件能证明量化路径真实生效
526+ - Prefill / Decode 至少跑通一次，输出可读、不重复、非全零、不提前 EOS
527+ - 精度: 运行推理，对比量化前后的输出可用性和关键误差
528+ - 性能: 运行推理，记录量化部署基线；与非量化基线和量化前最新基线对比
529+ - 若量化后可单卡部署，则以单卡部署结果作为主要验证口径
530+检查项:
531+ - 每个量化模块均有生效证据
532+ - 回退到原有非融合算子的模块已显式记录
533+ - 无擅自修改量化方案、target、ignore 或权重张量语义的行为
534+ - 量化初评估报告和量化接入前变更复核结论中的冲突项已给出处理方式
535+```
536+ 
537+#### 4.5 实测后用户决策与阶段总结
538+ 
539+主 agent 执行：
540+1. reviewer 报告 FAIL → 派发 model-infer-implementer（修复量化权重加载、映射或精度问题）→ 重新派发 model-infer-reviewer 验证，最多 5 轮
541+2. 5 轮仍未解决 → 回退问题模块或整阶段改动 → 向用户报告阻塞点，请求决策
542+3. 精度达标但性能未提升 → 派发 model-infer-analyzer（排查量化路径是否真实生效、部署配置、测试方法、NPU 利用率等）→ 将分析和建议呈现给用户决策
543+4. 量化基线产出后，向用户呈现实测结果和三种后验决策：采用当前量化方案继续进入图模式 / 保留融合算子并跳过量化进入图模式 / 修正量化方案后迭代验证
544+5. 若用户接受当前量化方案，将量化部署基线、量化后部署口径、融合算子回退清单作为阶段 5 图模式适配输入
545+6. 若用户选择跳过量化，记录跳过原因和实测收益；进入阶段 5 前必须确保运行配置和代码路径回到非量化融合后模型，不把量化改动作为默认执行路径
546+7. 若用户选择修正量化方案后迭代验证，记录当前阻塞点和补充诉求，等待新量化产物后回到 4.1 复核
547+8. 综合输出量化改造方案、改造要点、问题及解决方案、融合算子量化需求和收益结论
548+9. 将可复用经验沉淀到 `model-infer-quantization/references/quantization-structure-cards.md`；只有新增结构才创建新结构卡
549+10. 向用户确认当前阶段优化，确认后提交 commit，进入下一阶段
550+ 
551+---
552+ 
553+### 阶段 5：图模式适配优化
554+ 
555+> 图模式基于阶段 4 之后用户接受的执行路径适配：若接受量化，则验证量化路径下的 Decode 图模式；若跳过量化，则验证非量化融合后路径。
556+ 
557+#### 5.1 启动分析 subagent
558+ 
559+派发 model-infer-analyzer：
560+ 
561+```
562+工作目录: {model_dir}
563+必须使用 skill: model-infer-graph-mode（关注分析和方案设计部分）
564+任务: 图模式适配方案分析
565+分析内容:
566+ - 分析模型中的图中断点（dynamic shape、数据依赖控制流等）
567+ - 评估图模式适配方案（npugraph_ex / GE 图模式）
568+ - 若阶段 4 已接受量化方案，基于量化 dtype、layout、kernel 和 cache 路径分析图中断点
569+ - 图模式仅适用于 Decode 阶段，Prefill 禁止使用
570+```
571+ 
572+#### 5.2 方案确认
573+ 
574+主 agent 使用提问工具向用户逐条确认关键决策：
575+ 
576+1. **图模式后端**：npugraph_ex / GE 图模式？
577+2. **图中断点处理**：analyzer 识别的图中断点及解决方案是否认可？
578+3. 其他需用户确认的方案细节（如 mark_static 处理、编译缓存策略等）
579+ 
580+用户确认后进入实施。
581+ 
582+#### 5.3 启动实施 subagent
583+ 
584+派发 model-infer-implementer：
585+ 
586+```
587+工作目录: {model_dir}
588+必须使用 skill: model-infer-graph-mode（关注实施和代码改造部分）
589+任务: 阶段 5 图模式适配（至少包含以下内容）
590+阶段要点:
591+ - 图模式仅适用于 Decode 阶段，Prefill 禁止使用
592+ - 若阶段 4 已接受量化方案，图模式必须基于量化路径实施，不回退到非量化路径
593+自验证:
594+ - 编译通过、图编译无 graph break、推理无 crash、吐字正常（可读、不重复、非全零、不提前 EOS）
595+ - 实施记录写入 progress.md 工作区
596+```
597+ 
598+> **验收 gate**：执行"implementer 自验证检查"（见重要原则）。不通过 → 拒绝重派。
599+ 
600+#### 5.4 启动验证 subagent
601+ 
602+派发 model-infer-reviewer：
603+ 
604+```
605+工作目录: {model_dir}
606+任务: 图模式适配后验证
607+约束: 禁止修改模型代码和自行调试，仅返回验证报告
608+至少包含以下验证:
609+验证内容:
610+ - 精度: 运行推理，图模式 Decode 输出与 eager 模式对比
611+ - 性能: 运行推理，本阶段增量 + 相对原始基线的累计变化；若阶段 4 已接受量化方案，同时记录相对量化基线的增量
612+ - 性能验证: 若工作目录下有 agentic/baseline/baseline_metadata.json，用它作为性能对比基准
613+ - 结果写入 progress.md 工作区（精度验证 + 性能验证 section）
614+检查项:
615+ - Decode 阶段已启用图模式
616+ - Prefill 阶段未使用图模式
617+ - 若阶段 4 已接受量化方案，能证明图模式运行在量化路径上
618+ - 性能同时记录本阶段增量和累计变化
619+```
620+ 
621+#### 5.5 阶段总结
622+ 
623+主 agent 执行：
624+1. reviewer 报告 FAIL → 派发 model-infer-implementer（修复图模式适配问题，如图中断、精度偏差）→ 重新派发 model-infer-reviewer 验证，最多 5 轮
625+2. 5 轮仍未解决 → 回退问题模块或整阶段改动 → 向用户报告阻塞点，请求决策
626+3. 精度达标但性能未提升 → 派发 model-infer-analyzer（排查性能问题：部署配置、前置处理开销、测试方法、NPU 利用率等）→ 将分析和建议呈现给用户决策
627+4. 全部通过后，综合 analyzer/implementer/reviewer 的结果，输出阶段总结报告
628+5. 向用户确认当前阶段优化，确认后提交 commit，进入下一阶段
629+ 
630+---
631+ 
632+### 阶段 6：优化总结
633+ 
634+使用 `templates/optimization_report_template.md` 模板，将完整的优化报告写入模型 agentic 目录：
635+ 
636+```
637+models/{model_name}/agentic/optimization_report.md
638+```
639+ 
640+报告章节按 `templates/optimization_report_template.md` 模板组织（成果型，按内容主题非阶段时间线）：
641+概述、模型结构、性能基线、并行切分、KVCache 与 Attention、算子融合、量化适配、图模式、累计性能演进、算子需求、当前未覆盖项。其中并行切分（单卡部署时）、量化适配（未启用时）、算子需求（无 CANN 期望支持点时）三段无内容时整段删除。
642+ 
643+各章节遵循模板顶部「可读性约束」：按主题组织，禁用"阶段 N"前缀，禁止"用户确认状态 / 精度判定"等过程字段，过程记录留在 progress_history.md。
644+ 
645+> 报告内容从 progress.md（常驻区）+ progress_history.md（Read 全文，一次性）中提取整理。生成时严格遵循 `templates/optimization_report_template.md` 顶部「写入规范」：清扫 progress 中的过程语言（试错时序、状态徽章、流程编号、编排状态等），技术内容保留，过程信息留在 progress_history.md 不进入 report。
646+>
647+> 执行过程中发现的 skill 流程缺失、描述不清、约束缺失、参考过时等问题，在归档前于 progress.md 工作区末尾以 "Skill 反馈" 条目汇总一句，随工作区一并归档进 progress_history.md，不进入对外的 optimization_report.md。
648+ 
649+---
Ascript/LICENSE+33-0
Ascript/README.md+31-0
Ascript/index.js+9-0
Avendor/cannbot-skills+1-0文件内容审核中，请稍后刷新重试
Awebsite/README.md+12-0
Awebsite/app.js+490-0
Awebsite/index.html+135-0
Awebsite/styles.css+148-0