[Docs][skills][part5] Add workflow/standards/perf skills, meta README and AGENTS routing, remove performance-evaluation-MindIE-SD-AtomGit

M.agents/README.md+89-89

	@@ -1,6 +1,6 @@
1	# Multimodal Skills	1	# Multimodal Skills
2		2
3	-面向 MindIE-SD 多模态扩散模型（Wan2.2 / FLUX / Qwen-Image）在昇腾 NPU 上的开发、验证、部署与性能优化技能集合。	3	+面向 MindIE-SD 多模态扩散模型（Wan2.2 / FLUX / Qwen-Image / MiniMax-H3）在昇腾 NPU 上的开发、验证、部署与性能优化技能集合。
4		4
5	## 技能总览	5	## 技能总览
6		6
	@@ -10,37 +10,35 @@
10	└──────┬──────────────┘	10	└──────┬──────────────┘
11	┌──────────────┬──────┼──────┬───────────┬──────────────┐	11	┌──────────────┬──────┼──────┬───────────┬──────────────┐
12	▼ ▼ ▼ ▼ ▼ ▼	12	▼ ▼ ▼ ▼ ▼ ▼
13	- ┌──────────┐ ┌──────────┐ ┌─────────────┐ ┌──────────┐ ┌────────────────┐	13	+ ┌──────────┐ ┌──────────┐ ┌─────────────┐ ┌──────────┐ ┌────────────────┐
14	- │ code- │ │ markdown │ │compilation- │ │model- │ │ ascend- │	14	+ │ code- │ │ markdown │ │compilation- │ │dummy-run │ │ ascend- │
15	- │ standards│ │ -lint │ │ support │ │verification│ │ deploy │	15	+ │ standards│ │ -lint │ │ dev │ │ -dev │ │ deploy │
16	- │ Python │ │ Markdown │ │ Pattern/ │ │ §A/B │ │ 本地/远端部署 │	16	+ │ Python │ │ Markdown │ │ Pattern + │ │ Dummy Run│ │ 本地/远端部署 │
17	- │ 格式规范 │ │ 格式检查 │ │ Backend/Copy│ │ 验证 │ │ + 编译安装 │	17	+ │ 格式规范 │ │ 格式检查 │ │ Inductor │ │ 架构验证 │ │ + 编译安装 │
18	- └──────────┘ └──────────┘ └─────────────┘ └──────┬────┘ └────────────────┘	18	+ └──────────┘ └──────────┘ └──┬──────┬───┘ └──────┬────┘ └───────┬────────┘
19	- │	19	+ │ │ │ │
20	- ┌────────┴────────┐	20	+ ┌────────┴──┐ ┌─┴──────────┐ │ ┌────────┴────────┐
21	- ▼ ▼	21	+ │ operator- │ │ aclgraph- │ │ │ framework- │
22	- ┌──────────────┐ ┌──────────────┐	22	+ │ dev │ │ dev │ │ │ integration │
23	- │performance │ │ profiling- │	23	+ │ 算子开发 │ │ 批量下发 │ │ │ vLLM-Omni/diffusers/
24	- │-evaluation │ │ collection │	24	+ │ (cannbot) │ │ (NPUGraph) │ │ │ 魔乐对接与验证 │
25	- │ msmodeling │ │ NPU profiling │	25	+ └───────────┘ └────────────┘ │ └─────────────────┘
26	- │ CPU模拟/实测 │ │ 数据采集+回传 │	26	+ │
27	- └──────┬───────┘ └──────┬───────┘	27	+ ┌─────────┴─────────┐
28	- │ │	28	+ ▼ ▼
29	- └────────┬────────┘	29	+ ┌──────────────┐ ┌──────────────┐
		30	+ │ profiling- │ │ performance │
		31	+ │ collection │ │ -analysis │
		32	+ │ NPU 采集+回传 │ │ 5层递进分析 │
		33	+ └──────┬───────┘ └──────┬───────┘
		34	+ │ │
		35	+ └────────┬─────────┘
30	▼	36	▼
31	- ┌─────────────────────┐	37	+ ┌─────────────────────┐
32	- │ performance- │	38	+ │ performance- │
33	- │ analysis │	39	+ │ optimization │
34	- │ 5层递进分析 │	40	+ │ 5步优化闭环 │
35	- │ 方向级建议 │	41	+ └──────────┬──────────┘
36	- └──────────┬──────────┘
37	- ▼
38	- ┌─────────────────────┐
39	- │ performance- │
40	- │ optimization │
41	- │ 5步优化闭环 │
42	- │ features.md 方案 │
43	- └──────────┬───────────┘
44	│	42	│
45	┌──────────▼───────────┐	43	┌──────────▼───────────┐
46	│ auto-optimization │ ← 端到端优化闭环	44	│ auto-optimization │ ← 端到端优化闭环
	@@ -63,26 +61,25 @@
63	\| 技能 \| 描述 \| 状态 \|	61	\| 技能 \| 描述 \| 状态 \|
64	\|------\|------\|:--:\|	62	\|------\|------\|:--:\|
65	\| [dev-workflow](skills/dev-workflow/SKILL.md) \| 开发总入口：Test-First 流程、并行开发策略、模型验证/部署/性能分析/复盘全流程路由 \| ✅ \|	63	\| [dev-workflow](skills/dev-workflow/SKILL.md) \| 开发总入口：Test-First 流程、并行开发策略、模型验证/部署/性能分析/复盘全流程路由 \| ✅ \|
66	-\| [code-standards](skills/code-standards/SKILL.md) \| Python 代码格式与 lint 规则（Ruff 配置 / pre-commit 钩子 / 门禁专项） \| ✅ \|	64	+\| [compilation-dev](skills/compilation-dev/SKILL.md) \| Pattern matcher 与 Inductor/default 后端：Pattern 创建/注册/调试、Copy 消减（default 路径） \| ✅ \|
67	-\| [markdown-lint](skills/markdown-lint/SKILL.md) \| Markdown 文件格式检查规范（MD040 / 验证命令 / 修复模板） \| ✅ \|	65	+\| [aclgraph-dev](skills/aclgraph-dev/SKILL.md) \| NPU 图批量下发（aclgraph / aclgraph_ex）：NPUGraph 静态 capture、graph pool、lazy capture、replay \| ✅ \|
68	-\| [compilation-dev](skills/compilation-dev/SKILL.md) \| 编译后端适配与分析：Pattern 创建/注册/调试、Copy 算子消减、四后端选择 \| ✅ \|	66	+\| [operator-dev](skills/operator-dev/SKILL.md) \| 算子级开发与优化：场景路由到外部 cannbot-skills（Triton / Ascend C / Catlass / PyPTO / TileLang）+ 本仓补充 \| ✅ \|
69		67
70	### 模型验证与部署	68	### 模型验证与部署
71		69
72	\| 技能 \| 描述 \| 状态 \|	70	\| 技能 \| 描述 \| 状态 \|
73	\|------\|------\|:--:\|	71	\|------\|------\|:--:\|
74	-\| [model-verification](skills/model-verification/SKILL.md) \| 模型验证：§A Dummy Run 无权重快速验证架构兼容性；§B 部署验证已部署模型的推理正确性（vLLM/diffusers/魔乐三种框架） \| ✅ \|	72	+\| [dummy-run-dev](skills/dummy-run-dev/SKILL.md) \| Dummy Run 构造验证：随机权重快速验证新模型架构兼容性，评估参数量/显存/耗时 \| ✅ \|
75	\| [ascend-deploy](skills/ascend-deploy/SKILL.md) \| 部署 MindIE-SD：本地昇腾直接编译安装，或 SSH 推送到远端容器编译。含环境兼容性前置检查、连接复用、NPU 管理 \| ✅ \|	73	\| [ascend-deploy](skills/ascend-deploy/SKILL.md) \| 部署 MindIE-SD：本地昇腾直接编译安装，或 SSH 推送到远端容器编译。含环境兼容性前置检查、连接复用、NPU 管理 \| ✅ \|
76	-\| [profiling-collection](skills/profiling-collection/SKILL.md) \| NPU profiling 数据采集：SSH → 开启 Profiler → 运行推理 → 压缩 → 回传本地。Warmup 自动剔除，数据对接 performance-analysis \| ✅ \|	74	+\| [framework-integration](skills/framework-integration/SKILL.md) \| 三方框架对接与验证：vLLM-Omni 全栈部署（950PR 源码构建）、Cache DiT + diffusers、魔乐社区、DiffSynth-Engine 等外部框架 compile 接入 \| ✅ \|
77		75
78	### 性能工程	76	### 性能工程
79		77
80	\| 技能 \| 描述 \| 状态 \|	78	\| 技能 \| 描述 \| 状态 \|
81	\|------\|------\|:--:\|	79	\|------\|------\|:--:\|
82	-\| [performance-evaluation](skills/performance-evaluation/SKILL.md) \| msmodeling 性能评估：无 NPU 时 CPU 模拟各硬件性能；有 NPU 时实测并路由到 profiling-collection 采集数据 \| ✅ \|	80	+\| [profiling-collection](skills/profiling-collection/SKILL.md) \| NPU profiling 数据采集：SSH → 开启 Profiler → 运行推理 → 压缩 → 回传本地。Warmup 自动剔除，数据对接 performance-analysis \| ✅ \|
83	\| [performance-analysis](skills/performance-analysis/SKILL.md) \| 5 层递进分析：Warmup 验证 → DiT/VAE 分离 → FA/MatMul/Vector/Comm 分类占比 → Host Bound/通信/融合检测 → 方向级优化建议 \| ✅ \|	81	\| [performance-analysis](skills/performance-analysis/SKILL.md) \| 5 层递进分析：Warmup 验证 → DiT/VAE 分离 → FA/MatMul/Vector/Comm 分类占比 → Host Bound/通信/融合检测 → 方向级优化建议 \| ✅ \|
84	\| [performance-optimization](skills/performance-optimization/SKILL.md) \| 5 步优化闭环：基线 → 分析 → 选方案（从 mindiesd-features.md 选取具体 API） → 实施 → 复验。唯一真相源驱动 \| ✅ \|	82	\| [performance-optimization](skills/performance-optimization/SKILL.md) \| 5 步优化闭环：基线 → 分析 → 选方案（从 mindiesd-features.md 选取具体 API） → 实施 → 复验。唯一真相源驱动 \| ✅ \|
85	-\| [parallelism-strategy](skills/parallelism-strategy/SKILL.md) \| 并行策略选型参考：TP/USP/RSP/CFG 概览。决策树和实测数据待后续补充 \| 📝 \|
86		83
87	### 端到端优化	84	### 端到端优化
88		85
	@@ -90,10 +87,13 @@
90	\|------\|------\|:--:\|	87	\|------\|------\|:--:\|
91	\| [auto-optimization](skills/auto-optimization/SKILL.md) \| 端到端优化闭环：组合 profiling-collection → performance-analysis → performance-optimization，从 profiling 采集到方案实施到复验的一键流程 \| ✅ \|	88	\| [auto-optimization](skills/auto-optimization/SKILL.md) \| 端到端优化闭环：组合 profiling-collection → performance-analysis → performance-optimization，从 profiling 采集到方案实施到复验的一键流程 \| ✅ \|
92		89
93	-### 治理与规范	90	+### 并行与治理
94		91
95	\| 技能 \| 描述 \| 状态 \|	92	\| 技能 \| 描述 \| 状态 \|
96	\|------\|------\|:--:\|	93	\|------\|------\|:--:\|
		94	+\| [parallelism-strategy](skills/parallelism-strategy/SKILL.md) \| 并行策略选型与实测：Ulysses USP、CP 通信掩盖（comm-stream masking）、CFG/TP/RSP，含 910B 实测数据与 AlltoAllV 绕过 \| ✅ \|
		95	+\| [code-standards](skills/code-standards/SKILL.md) \| Python 代码格式与 lint 规则（Ruff 配置 / pre-commit 钩子 / 门禁专项） \| ✅ \|
		96	+\| [markdown-lint](skills/markdown-lint/SKILL.md) \| Markdown 文件格式检查规范（MD040 / 验证命令 / 修复模板） \| ✅ \|
97	\| [mindie-sd-community-governance](skills/mindie-sd-community-governance/SKILL.md) \| 文档/治理/贡献者工作流/提交及 PR 规范/版本策略 \| ✅ \|	97	\| [mindie-sd-community-governance](skills/mindie-sd-community-governance/SKILL.md) \| 文档/治理/贡献者工作流/提交及 PR 规范/版本策略 \| ✅ \|
98		98
99	---	99	---
	@@ -107,26 +107,25 @@
107	```text	107	```text
108	1. 动手前检查清单（模型/精度/分辨率/NPU/CFG 配置确认）	108	1. 动手前检查清单（模型/精度/分辨率/NPU/CFG 配置确认）
109	2. 编码实现 → code-standards（Ruff lint）	109	2. 编码实现 → code-standards（Ruff lint）
110	-2.5 编译适配 → compilation-dev（Pattern 注册 / Copy 消减 / 后端选择）	110	+2.5 编译适配 → compilation-dev（Pattern 注册 / Copy 消减）；算子本体 → operator-dev；批量下发 → aclgraph-dev
111	-3. 模型验证 → model-verification §A（Dummy Run）	111	+3. 模型验证 → dummy-run-dev（Dummy Run）
112	4. 远端部署 → ascend-deploy（本地编译或 SSH 增量传输）	112	4. 远端部署 → ascend-deploy（本地编译或 SSH 增量传输）
113	-5. 部署验证 → model-verification §B（三种框架验证）	113	+5. 部署验证 → framework-integration §1（vLLM-Omni / diffusers / 魔乐）
114	-6. 性能评估 → performance-evaluation（msmodeling 或实测）	114	+6. NPU profiling → profiling-collection（数据采集）
115	-7. NPU profiling → profiling-collection（数据采集）	115	+7. 瓶颈分析 → performance-analysis（5 层递进）
116	-8. 瓶颈分析 → performance-analysis（5 层递进）	116	+8. 性能优化 → performance-optimization（选取方案 + 复验）
117	-9. 性能优化 → performance-optimization（选取方案 + 复验）	117	+9. 端到端闭环 → auto-optimization（一键采集→分析→方案→复验）
118	-10. 端到端闭环 → auto-optimization（一键采集→分析→方案→复验）	118	+10. 复盘归档 → dev-workflow §6
119	-11. 复盘归档 → dev-workflow §6
120	```	119	```
121		120
122	### 验证新模型架构	121	### 验证新模型架构
123		122
124	```text	123	```text
125	-# 无权重时：§A Dummy Run 构造验证	124	+# 无权重时：Dummy Run 构造验证
126	python examples/dummy_run/wan_infer.py --config_cache ./configs --device_id 0	125	python examples/dummy_run/wan_infer.py --config_cache ./configs --device_id 0
127		126
128	-# 有真实权重时：§B 部署验证（按框架选验证方法）	127	+# 有真实权重时：framework-integration §1 部署验证（按框架选验证方法）
129	-model-verification §B → B2 diffusers: from_pretrained → 1 step inference	128	+framework-integration §1 → 1.2 diffusers: from_pretrained → 1 step inference
130	```	129	```
131		130
132	### 部署到昇腾	131	### 部署到昇腾
	@@ -138,21 +137,18 @@ python setup.py build_py && pip install -e .
138		137
139	# 远端昇腾设备：SSH 增量部署	138	# 远端昇腾设备：SSH 增量部署
140	python skills/ascend-deploy/scripts/deploy_to_remote.py	139	python skills/ascend-deploy/scripts/deploy_to_remote.py
		140	+
		141	+# vLLM-Omni 全栈（950PR 源码构建）→ framework-integration §2
141	```	142	```
142		143
143	-### 评估 + 分析完整流程	144	+### Profiling + 分析完整流程
144		145
145	```bash	146	```bash
146	-# 1. msmodeling 评估（无 NPU 模拟或实测）	147	+# 1. 远端采集 profiling
147	-python -m cli.inference.video_generate \
148	- <model_path> --device ATLAS_800_A2_376T_64G \
149	- --height 480 --width 832 --frame-num 81 --dtype bfloat16
150	-
151	-# 2. 有 NPU 时：需采集 profiling → 采集 + 分析
152	python skills/profiling-collection/scripts/collect_profile.py \	148	python skills/profiling-collection/scripts/collect_profile.py \
153	--script wan_infer.py --device-id 0	149	--script wan_infer.py --device-id 0
154		150
155	-# 3. 分析 profiling 数据	151	+# 2. 分析 profiling 数据
156	python skills/performance-analysis/scripts/analyze_trace.py \	152	python skills/performance-analysis/scripts/analyze_trace.py \
157	--profile-dir ./profile_l1 --output-dir ./	153	--profile-dir ./profile_l1 --output-dir ./
158	```	154	```
	@@ -168,32 +164,32 @@ multimodal-skills/
168	├── dev-workflow/ # 开发总入口	164	├── dev-workflow/ # 开发总入口
169	│ ├── SKILL.md	165	│ ├── SKILL.md
170	│ └── references/ # pattern-dev / ascend-ops / cross-platform / rework-lessons	166	│ └── references/ # pattern-dev / ascend-ops / cross-platform / rework-lessons
171	- ├── code-standards/ # Python 格式规范	167	+ ├── compilation-dev/ # Pattern matcher + Inductor/default 后端
172	│ ├── SKILL.md	168	│ ├── SKILL.md
173	- │ └── references/ # gate-check-rules.md	169	+ │ ├── scripts/ # compare_profiles.py / cmp_kernels.py / analyze_copy_kernels.py
174	- ├── compilation-dev/ # 编译后端适配与分析	170	+ │ └── references/ # pattern-templates / registration-checklist / test-templates / mismatch-catalog / graph-comparison-guide / custom-graph-pass / copy-elimination-guide / benefit-rootcause / benchmark-guide / pattern-dev
175	- │ ├── SKILL.md	171	+ ├── aclgraph-dev/ # NPU 图批量下发（aclgraph/aclgraph_ex）
176	- │ └── references/ # backend-comparison / graph-comparison-guide / mismatch-catalog / pattern-templates / registration-checklist
177	- ├── markdown-lint/ # Markdown 格式检查
178	│ └── SKILL.md	172	│ └── SKILL.md
179	- ├── model-verification/ # 模型验证（Dummy Run + 部署验证）	173	+ ├── operator-dev/ # 算子开发（复用外部 cannbot-skills）
180	│ ├── SKILL.md	174	│ ├── SKILL.md
181	- │ └── references/ # construction-methods / phase-timer	175	+ │ └── references/ # operator-optimization-skill-map
		176	+ ├── dummy-run-dev/ # Dummy Run 构造验证
		177	+ │ ├── SKILL.md
		178	+ │ └── references/ # construction-methods / phase-timer / minimax-h3-notes
182	├── ascend-deploy/ # 部署（本地编译 + 远端 SSH）	179	├── ascend-deploy/ # 部署（本地编译 + 远端 SSH）
183	│ ├── SKILL.md	180	│ ├── SKILL.md
184	- │ ├── scripts/ # deploy_to_remote.py / pick_free_device.py	181	+ │ ├── scripts/ # deploy_to_remote.py / pick_free_device.py / ssh_helper.py
185	│ └── references/ # troubleshooting-tree.md	182	│ └── references/ # troubleshooting-tree.md
		183	+ ├── framework-integration/ # 三方框架对接与验证（vLLM-Omni 等）
		184	+ │ ├── SKILL.md
		185	+ │ └── references/ # troubleshooting-vllm-omni.md
186	├── profiling-collection/ # NPU profiling 采集	186	├── profiling-collection/ # NPU profiling 采集
187	│ ├── SKILL.md	187	│ ├── SKILL.md
188	│ └── scripts/ # collect_profile.py	188	│ └── scripts/ # collect_profile.py
189	- ├── performance-evaluation/ # 性能评估（msmodeling）
190	- │ ├── SKILL.md
191	- │ ├── scripts/ # validate_results.py
192	- │ └── references/ # setup-guide / evaluation-guide / hardware-specs / ...
193	├── performance-analysis/ # 瓶颈分析（5 层递进）	189	├── performance-analysis/ # 瓶颈分析（5 层递进）
194	│ ├── SKILL.md	190	│ ├── SKILL.md
195	│ ├── scripts/ # analyze_trace.py / compare_traces.py	191	│ ├── scripts/ # analyze_trace.py / compare_traces.py
196	- │ └── references/ # capability-matrix / operator-catalog / heuristics	192	+ │ └── references/ # capability-matrix / operator-catalog / heuristics / analysis_workflow
197	├── performance-optimization/ # 优化闭环	193	├── performance-optimization/ # 优化闭环
198	│ ├── SKILL.md	194	│ ├── SKILL.md
199	│ ├── scripts/ # refresh_features.py	195	│ ├── scripts/ # refresh_features.py
	@@ -203,6 +199,11 @@ multimodal-skills/
203	├── auto-optimization/ # 端到端优化闭环	199	├── auto-optimization/ # 端到端优化闭环
204	│ ├── SKILL.md	200	│ ├── SKILL.md
205	│ └── references/ # artifact-layout.md	201	│ └── references/ # artifact-layout.md
		202	+ ├── code-standards/ # Python 格式规范
		203	+ │ ├── SKILL.md
		204	+ │ └── references/ # gate-check-rules.md
		205	+ ├── markdown-lint/ # Markdown 格式检查
		206	+ │ └── SKILL.md
206	└── mindie-sd-community-governance/ # 文档/治理/提交规范	207	└── mindie-sd-community-governance/ # 文档/治理/提交规范
207	├── SKILL.md	208	├── SKILL.md
208	└── assets/ # mr_ruleset.xlsx	209	└── assets/ # mr_ruleset.xlsx
	@@ -211,32 +212,31 @@ multimodal-skills/
211	## 技能间数据流	212	## 技能间数据流
212		213
213	```text	214	```text
214	-model-verification (粗粒度时序) ──────────────────────┐	215	+dummy-run-dev (粗粒度时序) ─────────────────────┐
215	- │	216	+ │
216	-ascend-deploy (部署结果) ──→ model-verification §B ├─→ performance-analysis	217	+ascend-deploy (部署结果) ──→ framework-integration §1 ├─→ performance-analysis
217	- (验证已部署模型) │ (消费 profiling + 粗粒度数据)	218	+ (框架侧验证) │ (消费 profiling + 粗粒度数据)
218	- │	219	+ │
219	-performance-evaluation (msmodeling/实测) │	220	+profiling-collection (标准 CANN Profiler 数据) ──┘
220	- │ │	221	+ │
221	- └──→ profiling-collection ──┘	222	+ ▼
222	- (标准 CANN Profiler 数据)	223	+ performance-optimization
223	- │	224	+ (消费方向级建议 + 查 features.md 选方案)
224	- ▼
225	- performance-optimization
226	- (消费方向级建议 + 查 features.md 选方案)
227	```	225	```
228		226
229	## 贡献	227	## 贡献
230		228
231	新增 skill 请遵循 `dev-workflow` 中的「新增 Skill 规范」（引用 [Anthropic skill-creator](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md) 指南）。	229	新增 skill 请遵循 `dev-workflow` 中的「新增 Skill 规范」（引用 [Anthropic skill-creator](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md) 指南）。
232		230
		231	+> 每个 skill 均含 `evals/evals.json`（skill-creator 测试用例：≥2 条真实 prompt + expectations）。
		232	+> 新增或大改 skill 时必须同步增补 evals。
		233	+
233	### 当前开发状态	234	### 当前开发状态
234		235
235	-- ✅ 12 个 skill 已填充实际内容	236	+- ✅ 15 个 skill 已填充实际内容（含 evals/evals.json）
236	-- 📝 1 个 skill 待完善（parallelism-strategy）
237		237
238	## 参考链接	238	## 参考链接
239		239
240	- [Anthropic skill-creator 规范](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md)	240	- [Anthropic skill-creator 规范](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md)
241	-- [msmodeling 文档](https://gitcode.com/Ascend/msmodeling)	241	+- [cannbot-skills（算子开发外部技能库）](https://gitcode.com/cann/cannbot-skills)
242	- [MindIE-SD](https://gitcode.com/Ascend/MindIE-SD)	242	- [MindIE-SD](https://gitcode.com/Ascend/MindIE-SD)

M.agents/skills/auto-optimization/SKILL.md+5-8

	@@ -1,5 +1,6 @@
1	---	1	---
2	name: auto-optimization	2	name: auto-optimization
		3	+compatibility: 依赖 profiling-collection / performance-analysis / performance-optimization；NPU 设备
3	description: 端到端性能优化闭环，组合 profiling-collection、performance-analysis、performance-optimization	4	description: 端到端性能优化闭环，组合 profiling-collection、performance-analysis、performance-optimization
4	三个下层 skill 完成从 profiling 采集到方案实施的完整流程。	5	三个下层 skill 完成从 profiling 采集到方案实施的完整流程。
5	当用户需要完整优化模型推理性能、并确认优化效果时使用此 skill。	6	当用户需要完整优化模型推理性能、并确认优化效果时使用此 skill。
	@@ -32,7 +33,7 @@ profiling-collection + performance-analysis（复验）
32	## 前置条件	33	## 前置条件
33		34
34	- ascend-deploy 已完成：代码已编译安装、`import mindiesd` 成功	35	- ascend-deploy 已完成：代码已编译安装、`import mindiesd` 成功
35	-- 模型已部署并通过验证：用 model-verification §B 确认推理正确	36	+- 模型已部署并通过验证：用 framework-integration §1 确认推理正确
36	- NPU 设备可用且显存充足	37	- NPU 设备可用且显存充足
37		38
38	## 核心流程	39	## 核心流程
	@@ -101,16 +102,12 @@ python performance-analysis/scripts/compare_traces.py \
101	- Host Bound / 通信暴露率变化	102	- Host Bound / 通信暴露率变化
102	- 总推理耗时变化	103	- 总推理耗时变化
103		104
104	-差距 < 3% 视为噪声，不宣称有效。	105	+差距 < 3% 视为噪声，不宣称有效（阈值同 performance-optimization 单点维护）。
105		106
106	## 停止条件	107	## 停止条件
107		108
108	-满足任一条件即停止优化循环：	109	+同 `performance-optimization/SKILL.md` 的「停止条件」（目标达成 / 噪声范围 / 外部瓶颈 / 硬件瓶颈），
109	-	110	+本 skill 只编排不重复定义。
110	-1. 目标达成：推理速度或显存占用已满足性能预期
111	-2. 噪声范围：与基线差距 < 3%，继续优化无统计意义
112	-3. 外部瓶颈：根因在 CANN / TorchNPU / HCCL 而非 MindIE-SD 代码
113	-4. 硬件瓶颈：已改善但受限于 NPU 物理显存 / 带宽上限
114		111
115	## 产出规范	112	## 产出规范
116		113

A.agents/skills/auto-optimization/evals/evals.json+28-0

@@ -0,0 +1,28 @@
	1	+{
	2	+ "skill_name": "auto-optimization",
	3	+ "evals": [
	4	+ {
	5	+ "id": 1,
	6	+ "prompt": "我想完整优化一个扩散模型的推理性能，从采集 profiling 到出优化方案，怎么走？",
	7	+ "expected_output": "按 auto-optimization 闭环：profiling-collection 采集（warmup ≥10 步）→ performance-analysis 5 层分析（P0-P2 方向级建议）→ performance-optimization 查 mindiesd-features.md 选方案实施 → 复验对比",
	8	+ "files": [],
	9	+ "expectations": [
	10	+ "输出 4 步闭环（采集→分析→选方案→复验）",
	11	+ "提到 warmup ≥10 步、capture ≥5 步的采集要求",
	12	+ "提到复验用 compare_traces.py 对比前后指标",
	13	+ "引用停止条件（同 performance-optimization 单点）"
	14	+ ]
	15	+ },
	16	+ {
	17	+ "id": 2,
	18	+ "prompt": "优化做完后怎么判断是不是真的有效？",
	19	+ "expected_output": "复验：重新采集 + 分析，对比 DiT/VAE 阶段耗时、算子占比、Host Bound、总耗时；差距 <3% 视为噪声；满足停止条件（目标达成/噪声/外部瓶颈/硬件瓶颈）即停止",
	20	+ "files": [],
	21	+ "expectations": [
	22	+ "给出复验指标（阶段耗时/占比/Host Bound/总耗时）",
	23	+ "提到 3% 噪声阈值",
	24	+ "提到停止条件 4 项（引用 performance-optimization）"
	25	+ ]
	26	+ }
	27	+ ]
	28	+}

M.agents/skills/auto-optimization/references/artifact-layout.md+4-0

	@@ -64,3 +64,7 @@ precision: bfloat16
64	{通过/部分通过/未通过}	64	{通过/部分通过/未通过}
65	- 目标达成 / 噪声范围 / 外部瓶颈 / 硬件瓶颈	65	- 目标达成 / 噪声范围 / 外部瓶颈 / 硬件瓶颈
66	```	66	```
		67	+
		68	+## 维护与更新
		69	+
		70	+当优化闭环产出物结构变化时，按 dev-workflow 的复盘流程更新本文件。

M.agents/skills/code-standards/SKILL.md+1-0

	@@ -1,5 +1,6 @@
1	---	1	---
2	name: code-standards	2	name: code-standards
		3	+compatibility: ruff, pre-commit（含 codespell/typos 钩子）
3	description: MindIE-SD Python 代码格式与 lint 规则。当编写、格式化、lint 检查或审查 MindIE-SD 项目的 Python 代码时使用此 skill。	4	description: MindIE-SD Python 代码格式与 lint 规则。当编写、格式化、lint 检查或审查 MindIE-SD 项目的 Python 代码时使用此 skill。
4	即使用户只提到"提个MR"或"代码好像有 lint 问题"而未明确说格式化，也应触发。	5	即使用户只提到"提个MR"或"代码好像有 lint 问题"而未明确说格式化，也应触发。
5	通常由 dev-workflow 在编码阶段指引加载。	6	通常由 dev-workflow 在编码阶段指引加载。

A.agents/skills/code-standards/evals/evals.json+38-0

@@ -0,0 +1,38 @@
	1	+{
	2	+ "skill_name": "code-standards",
	3	+ "evals": [
	4	+ {
	5	+ "id": 1,
	6	+ "prompt": "我新写的 Python 文件 lint 报了一堆错，怎么修？",
	7	+ "expected_output": "按 code-standards：ruff check --fix 自动修复 + ruff format；文件头（shebang/coding/Mulan 版权）；导入排序（isort）；只修改动行，禁止批量格式化未修改代码",
	8	+ "files": [],
	9	+ "expectations": [
	10	+ "给出 ruff check --fix 与 ruff format 命令",
	11	+ "提到文件头模板（Mulan PSL v2 版权头）",
	12	+ "提到禁止对未修改行做格式化"
	13	+ ]
	14	+ },
	15	+ {
	16	+ "id": 2,
	17	+ "prompt": "提交前要跑哪些代码质量检查？",
	18	+ "expected_output": "pre-commit run --all-files（ruff-check/ruff-format/codespell/typos/trailing-whitespace 等钩子），Markdown 另跑 markdownlint",
	19	+ "files": [],
	20	+ "expectations": [
	21	+ "给出 pre-commit run --all-files",
	22	+ "列出主要钩子（ruff、codespell、typos）",
	23	+ "提到 markdownlint 走 manual stage 需显式触发"
	24	+ ]
	25	+ },
	26	+ {
	27	+ "id": 3,
	28	+ "prompt": "门禁报 avoid-import-method 违规，怎么改？",
	29	+ "expected_output": "把 __import__ 改为 importlib.import_module；同时注意 Ruff UP015 也会覆盖，两处检查都要过",
	30	+ "files": [],
	31	+ "expectations": [
	32	+ "给出 importlib.import_module 正例",
	33	+ "提到与 Ruff UP015 的关系",
	34	+ "提到 examples/ 目录同样适用"
	35	+ ]
	36	+ }
	37	+ ]
	38	+}

M.agents/skills/code-standards/references/gate-check-rules.md+4-0

	@@ -134,3 +134,7 @@ if npu_smi is None:
134	raise RuntimeError("npu-smi not found in PATH")	134	raise RuntimeError("npu-smi not found in PATH")
135	subprocess.run([npu_smi, "info", "-l"], ...)	135	subprocess.run([npu_smi, "info", "-l"], ...)
136	```	136	```
		137	+
		138	+## 维护与更新
		139	+
		140	+当门禁规则集更新或新增违规示例时，按 dev-workflow 的复盘流程更新本文件。

M.agents/skills/dev-workflow/SKILL.md+22-11

	@@ -1,5 +1,6 @@
1	---	1	---
2	name: dev-workflow	2	name: dev-workflow
		3	+compatibility: 无额外工具依赖（负责编排其余 skill）；需 git 与仓库工作区
3	description: MindIE-SD 开发总入口。当用户进行 MindIE-SD 的任何开发工作时使用此 skill——	4	description: MindIE-SD 开发总入口。当用户进行 MindIE-SD 的任何开发工作时使用此 skill——
4	包括但不限于写 pattern、改测试、部署到昇腾、跑 benchmark、性能分析、多卡并行、复盘归档。	5	包括但不限于写 pattern、改测试、部署到昇腾、跑 benchmark、性能分析、多卡并行、复盘归档。
5	即使用户未明确提到"开发流程"，只要涉及 MindIE-SD 代码改动都应触发。	6	即使用户未明确提到"开发流程"，只要涉及 MindIE-SD 代码改动都应触发。
	@@ -24,12 +25,13 @@ description: MindIE-SD 开发总入口。当用户进行 MindIE-SD 的任何开
24		25
25	若任务是新增或调试 MindIE-SD compilation pattern（RMSNorm / RoPE / AdaLayerNorm / GELU 融合），	26	若任务是新增或调试 MindIE-SD compilation pattern（RMSNorm / RoPE / AdaLayerNorm / GELU 融合），
26	路由到 `compilation-dev` skill 获取全生命周期指导：模型代码分析 → pattern 创建 → 注册 → 单元测试 → mismatch 调试 → 集成验证 → Copy 消减。	27	路由到 `compilation-dev` skill 获取全生命周期指导：模型代码分析 → pattern 创建 → 注册 → 单元测试 → mismatch 调试 → 集成验证 → Copy 消减。
		28	+算子本体（triton kernel 编写/调优）→ `operator-dev`；批量下发（aclgraph）→ `aclgraph-dev`。
27		29
28	## 2. 模型验证	30	## 2. 模型验证
29		31
30	-写实现前，在 NPU 上用 model-verification §A 的 Dummy Run 方法快速验证模型架构兼容性，	32	+写实现前，在 NPU 上用 dummy-run-dev 的 Dummy Run 方法快速验证模型架构兼容性，
31	不必下载完整权重。如果已通过验证则跳过。	33	不必下载完整权重。如果已通过验证则跳过。
32	-部署完成后，使用 model-verification §B 验证已部署模型的推理正确性。	34	+部署完成后，使用 framework-integration §1 验证已部署模型的推理正确性。
33		35
34	## 3. 并行开发策略	36	## 3. 并行开发策略
35		37
	@@ -48,10 +50,9 @@ description: MindIE-SD 开发总入口。当用户进行 MindIE-SD 的任何开
48		50
49	## 5. 性能评估与优化	51	## 5. 性能评估与优化
50		52
51	-功能验证通过后用 performance-evaluation 建立性能基线。	53	+功能验证通过后，用 profiling-collection 采集真实 NPU 数据、performance-analysis 分析并建立性能基线。
52	-Benchmark 规范见 performance-evaluation/references/benchmark-guide.md。	54	+Benchmark 计时方法论（L2-flush 放计时区外、warm/cold 双档）见 compilation-dev/references/benchmark-guide.md。
53		55
54	-需采集 NPU profiling 数据时使用 profiling-collection。
55	采集完成后用 performance-analysis 定位瓶颈，用 performance-optimization 选择优化方案。	56	采集完成后用 performance-analysis 定位瓶颈，用 performance-optimization 选择优化方案。
56	多卡场景参考 parallelism-strategy 选择并行策略。	57	多卡场景参考 parallelism-strategy 选择并行策略。
57		58
	@@ -62,7 +63,7 @@ Benchmark 规范见 performance-evaluation/references/benchmark-guide.md。
62	1. 回顾本阶段问题点和改进点	63	1. 回顾本阶段问题点和改进点
63	2. 检查是否需要补充 references/rework-lessons.md	64	2. 检查是否需要补充 references/rework-lessons.md
64	3. 交叉检查各模块 skill 需不需要更新	65	3. 交叉检查各模块 skill 需不需要更新
65	-4. 同步刷新项目 PLAN.md 任务状态	66	+4. 同步刷新 `.agents/README.md` 技能总览与各 skill 状态
66		67
67	### 识别更新信号	68	### 识别更新信号
68		69
	@@ -88,6 +89,9 @@ Benchmark 规范见 performance-evaluation/references/benchmark-guide.md。
88	## Reference Files	89	## Reference Files
89		90
90	- 📋 `../compilation-dev/SKILL.md` — 加载时机: 编写或修改 compilation pattern 时	91	- 📋 `../compilation-dev/SKILL.md` — 加载时机: 编写或修改 compilation pattern 时
		92	+- 🔧 `../aclgraph-dev/SKILL.md` — 加载时机: 静态 shape 大 batch 需要批量下发时
		93	+- 🔧 `../operator-dev/SKILL.md` — 加载时机: 算子本体开发/调优（复用 cannbot-skills）时
		94	+- 🔧 `../framework-integration/SKILL.md` — 加载时机: 三方框架对接/验证（vLLM-Omni 等）时
91	- ⚡ `references/ascend-ops.md` — 加载时机: 涉及 NPU 算子调用或环境诊断时	95	- ⚡ `references/ascend-ops.md` — 加载时机: 涉及 NPU 算子调用或环境诊断时
92	- 🔧 `references/cross-platform.md` — 加载时机: 跨平台部署或遇到 PowerShell/编码兼容问题时	96	- 🔧 `references/cross-platform.md` — 加载时机: 跨平台部署或遇到 PowerShell/编码兼容问题时
93	- 📝 `references/rework-lessons.md` — 加载时机: 每次复盘归档时，或遇到相似问题需查历史教训时	97	- 📝 `references/rework-lessons.md` — 加载时机: 每次复盘归档时，或遇到相似问题需查历史教训时
	@@ -100,11 +104,18 @@ Benchmark 规范见 performance-evaluation/references/benchmark-guide.md。
100		104
101	## 新增 Skill 规范	105	## 新增 Skill 规范
102		106
103	-当需要新建 skill 时，遵循 [Anthropic skill-creator](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md) 指南：	107	+当需要新建 skill 时，遵循 [Anthropic skill-creator](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md) 指南，以下为必检清单：
104		108
105	-- 目录结构: `<skill-name>/SKILL.md` + 可选 `scripts/` `references/` `assets/`	109	+- 目录结构: `<skill-name>/SKILL.md` + 可选 `scripts/` `references/` `assets/` `evals/`
106	- SKILL.md < 500 行，超限用 references/ 拆分（progressive disclosure）	110	- SKILL.md < 500 行，超限用 references/ 拆分（progressive disclosure）
107	-- description 要 pushy：明确写清触发条件，避免 undertrigger	111	+- frontmatter 必须含 `compatibility`：声明运行依赖（工具/环境/外部技能库）
		112	+- description 要 pushy：明确写清触发条件（what + when-to-trigger），覆盖 near-miss 边界
		113	+ （"看似相关但不应触发"的场景），避免 undertrigger 与误触发
		114	+- 必须建 `evals/evals.json`：≥2 条真实用户 prompt（`prompt` / `expected_output` / `expectations`，
		115	+ 格式遵循 skill-creator `references/schemas.md`）；新增或大改 skill 后必须同步增补
		116	+- references 必须全部接线：在 SKILL.md 列出 Reference Files + 加载时机；>300 行的 reference 必须带目录
		117	+- references 必须含"维护与更新"章节，写明更新触发条件
108	- 单 skill 单职责：不同模块/领域的内容拆分为独立 skill	118	- 单 skill 单职责：不同模块/领域的内容拆分为独立 skill
109	-- 命名：小写连字符，业界通用名（如 `ascend-deploy`、`model-verification`）	119	+- 模型/框架专属知识放 `references/<variant>/` 子目录（如 `references/models/minimax-h3.md`），避免平铺
110	-- 新 skill 必须包含"维护与更新"章节，写明更新触发条件	120	+- 命名：小写连字符，业界通用名（如 `ascend-deploy`、`dummy-run-dev`）
		121	+- 新 skill 必须包含"维护与更新"章节

A.agents/skills/dev-workflow/evals/evals.json+38-0

@@ -0,0 +1,38 @@
	1	+{
	2	+ "skill_name": "dev-workflow",
	3	+ "evals": [
	4	+ {
	5	+ "id": 1,
	6	+ "prompt": "帮我给 MiniMax-H3 新增一个 fusion pattern，走完整开发流程：先写测试再实现，最后推到远端昇腾环境验证",
	7	+ "expected_output": "遵循 Test-First 闭环（先写预期 FAIL 的测试 → 实现 → 远端部署 → pytest 验证），并正确路由：pattern 开发到 compilation-dev、部署到 ascend-deploy、验证到 dummy-run-dev/framework-integration",
	8	+ "files": [],
	9	+ "expectations": [
	10	+ "输出包含 Test-First 步骤（写测试预期 FAIL → 实现 → 部署 → 验证）",
	11	+ "路由到 compilation-dev（pattern 开发）与 ascend-deploy（远端部署）",
	12	+ "提到多卡验证时使用不同 NPU 卡隔离运行"
	13	+ ]
	14	+ },
	15	+ {
	16	+ "id": 2,
	17	+ "prompt": "多卡跑 MiniMax-H3 推理时 profiling 显示通信暴露 30%，怎么优化？",
	18	+ "expected_output": "路由到 parallelism-strategy（并行策略与通信掩盖）+ profiling-collection/performance-analysis（采集与分析），建议 comm-stream masking",
	19	+ "files": [],
	20	+ "expectations": [
	21	+ "引用 parallelism-strategy",
	22	+ "建议通信掩盖（comm-stream masking / mindiesd.parallel）",
	23	+ "指向 profiling-collection 采集 + performance-analysis 分析"
	24	+ ]
	25	+ },
	26	+ {
	27	+ "id": 3,
	28	+ "prompt": "完成一个功能阶段后要做复盘归档，流程是什么？",
	29	+ "expected_output": "按 dev-workflow §6 复盘流程：回顾问题点 → 补充 rework-lessons → 交叉检查各模块 skill → 刷新 .agents/README.md",
	30	+ "files": [],
	31	+ "expectations": [
	32	+ "输出 §6 复盘四步流程",
	33	+ "提到 rework-lessons.md 补充",
	34	+ "提到刷新 .agents/README.md 技能总览"
	35	+ ]
	36	+ }
	37	+ ]
	38	+}

M.agents/skills/dev-workflow/references/ascend-ops.md+4-0

	@@ -24,3 +24,7 @@
24	- Ascend 环境安装 triton 时必须用 `pip install triton-ascend`，不能安装标准 `triton`	24	- Ascend 环境安装 triton 时必须用 `pip install triton-ascend`，不能安装标准 `triton`
25	- 需同时安装 `pybind11` 作为隐式依赖	25	- 需同时安装 `pybind11` 作为隐式依赖
26	- 代码中通过 `_TRITON_ON_ASCEND` 标志区分 triton 是否真正可用（而非仅可 import）	26	- 代码中通过 `_TRITON_ON_ASCEND` 标志区分 triton 是否真正可用（而非仅可 import）
		27	+
		28	+## 维护与更新
		29	+
		30	+当NPU 算子 API 或环境诊断方法变化时，按 dev-workflow 的复盘流程更新本文件。

M.agents/skills/dev-workflow/references/cross-platform.md+4-0

	@@ -24,3 +24,7 @@ Windows 本地 GBK 编码可能与远端 UTF-8 输出冲突。处理方式：
24	`pip install -e .` 在首次安装时扫描包目录并建立索引，后续新增的 `.py` 文件不会自动加入。新增 Python 文件后必须重新执行 `pip install -e .`。	24	`pip install -e .` 在首次安装时扫描包目录并建立索引，后续新增的 `.py` 文件不会自动加入。新增 Python 文件后必须重新执行 `pip install -e .`。
25		25
26	此规则仅适用于 `mindiesd/` 包目录和 `csrc/` 编译源码目录下的文件变更。`examples/`、`tests/`、`docs/` 等非包/非编译目录下的文件变更不需要重新执行 `pip install -e .`。	26	此规则仅适用于 `mindiesd/` 包目录和 `csrc/` 编译源码目录下的文件变更。`examples/`、`tests/`、`docs/` 等非包/非编译目录下的文件变更不需要重新执行 `pip install -e .`。
		27	+
		28	+## 维护与更新
		29	+
		30	+当跨平台部署或编码兼容问题出现新模式时，按 dev-workflow 的复盘流程更新本文件。

D.agents/skills/dev-workflow/references/pattern-dev.md+0-114

	@@ -1,114 +0,0 @@
1	-# Pattern 编译开发规范
2	-
3	-> 已迁移至 `compilation-dev/SKILL.md`。
4	-> 本文档保留作为历史参考。Pattern 开发的全生命周期
5	-> 统一由 `compilation-dev` skill 覆盖。
6	->
7	-> 调试与验证: pattern 实现后若在模型 graph 上未命中，路由到 `compilation-dev` skill 进行定位和修复。
8	-
9	-## 1. Pattern 注册机制
10	-
11	-### ABCMeta isinstance 陷阱
12	-
13	-`PatternBase` 继承自 `ABC`（有 ABCMeta 元类），其 `isinstance` 会对实现抽象方法的子类返回 `True`。判断实例 vs 类时必须额外排除 `type`：
14	-
15	-```python
16	-# 错误：isinstance(SomePatternClass, PatternBase) → True（ABCMeta 行为）
17	-# 正确：
18	-if not isinstance(pat, type) and isinstance(pat, PatternBase):
19	- # 实例路径
20	-else:
21	- # 类路径
22	-```
23	-
24	-### 去重注册
25	-
26	-- 使用模块级 `_registered_pattern_names: set[str]` 记录已注册 pattern
27	-- 测试 setUp 须同时清理该集合和 `patterns.pattern_replacements`
28	-
29	-### 外接逻辑融合优先于接口照搬
30	-
31	-从外部项目（如 vllm-ascend）引入融合逻辑时：
32	-
33	-- 逻辑层：直接采用外部项目的 pattern 形状、replacement 目标、kernel 调用方式
34	-- 接口层：保持本地框架约定（如 `PatternBase` 的 `@staticmethod` 接口），不照搬外部项目的实例方法风格
35	-- 参数桥接：外部项目通过构造函数注入的参数（如 `scale`、`dtype`），用工厂函数 `create(dtype, scale)` 通过闭包注入，对齐本地既有模式
36	-
37	-```python
38	-# 正例：工厂函数 + 闭包桥接
39	-def create(dtype, scale=1.0):
40	- class MulAddPattern(PatternBase):
41	- @staticmethod
42	- def pattern(x, y):
43	- return x * scale + y # scale 来自闭包
44	- @staticmethod
45	- def replacement(x, y):
46	- return muls_add(x, y, scale) # kernel 融合
47	- return MulAddPattern
48	-
49	-# 反例：照搬外部项目的实例方法风格
50	-class MulAddPattern(PatternBase):
51	- def __init__(self, scale): ...
52	- def get_pattern(self): ... # 与本地 PatternBase 接口冲突
53	-```
54	-
55	-## 2. 测试文件组织
56	-
57	-```text
58	-tests/
59	-├── compilation/
60	-│ ├── test_bench_utils.py # benchmark 公共函数
61	-│ ├── test_backend.py # 后端集成测试（仅正确性）
62	-│ ├── test_pattern_registration.py # 注册机制测试
63	-│ ├── patterns/
64	-│ │ ├── test_gelu_pattern.py
65	-│ │ ├── test_rmsnorm_pattern.py
66	-│ │ ├── test_rope_pattern.py
67	-│ │ ├── test_adalayernorm_pattern.py
68	-│ │ └── test_xxx_pattern.py # 新增 pattern 测试
69	-│ └── regression/
70	-│ └── test_xxx_regression.py # 模型级回归测试
71	-├── layers/
72	-│ ├── test_muls_add.py # kernel 独立单元测试
73	-│ ├── test_rope.py
74	-│ └── test_rmsnorm.py
75	-```
76	-
77	-## 3. 双层测试原则
78	-
79	-每个融合 kernel 必须同时具备两层测试：
80	-
81	-\| 层级 \| 路径 \| 覆盖内容 \| 断言标准 \|
82	-\|---\|---\|---\|---\|
83	-\| kernel 层 \| `tests/layers/test_xxx.py` \| dtype/shape/scale 组合、边界值（scale=0/1/-1）、inplace 安全性、device/dtype 保真性、多次调用一致性 \| `torch.allclose(atol=...)` 按 dtype 分档：float32=1e-5, float16=1e-2, bfloat16=1e-1 \|
84	-\| pattern 层 \| `tests/compilation/patterns/test_xxx.py` \| `torch.compile` + `MindieSDBackend` 全链路：pattern 是否触发、replacement 是否生效、输出正确性 \| `cosine_similarity > 2^-7`，不强制耗时断言（除非张量足够大） \|
85	-
86	-### kernel 层测试模板
87	-
88	-```python
89	-class TestMulsAdd(unittest.TestCase):
90	- def test_basic_result_float32(self):
91	- x = torch.randn(4, 4096, dtype=torch.float32, device="npu")
92	- y = torch.randn(4, 4096, dtype=torch.float32, device="npu")
93	- result = muls_add(x, y, 1.5)
94	- expected = x * 1.5 + y
95	- self.assertTrue(torch.allclose(result, expected, atol=1e-5))
96	-
97	- def test_scale_variants(self):
98	- for scale in [0.0, 0.5, 1.0, 1.5, 2.0, -0.5, -1.0]:
99	- result = muls_add(x, y, scale)
100	- expected = x * scale + y
101	- self.assertTrue(torch.allclose(result, expected, atol=1e-5))
102	-
103	- def test_no_inplace_modification(self):
104	- x_orig = x.clone(); y_orig = y.clone()
105	- _ = muls_add(x, y, 1.5)
106	- self.assertTrue(torch.equal(x, x_orig))
107	- self.assertTrue(torch.equal(y, y_orig))
108	-
109	- def test_dtype_preservation_bfloat16(self):
110	- x = torch.randn(4, 4096, dtype=torch.bfloat16, device="npu")
111	- y = torch.randn(4, 4096, dtype=torch.bfloat16, device="npu")
112	- result = muls_add(x, y, 1.0)
113	- self.assertEqual(result.dtype, torch.bfloat16)
114	-```

M.agents/skills/dev-workflow/references/rework-lessons.md+105-1

	@@ -1,6 +1,6 @@
1	# 返工教训	1	# 返工教训
2		2
3	-> 目录 · 1. 拒绝未实现功能的前置配置 · 2. 最小必要改动原则 · 3. 独立任务必须实际并行执行 · 4. 非代码仓内容不入库 · 5. PLAN.md 未随任务变更同步更新 · 6. triton vs triton-ascend 包名混淆 · 7. pip install -e . 新增文件未被索引 · 8. SSH 连接重复创建 · 9. dummy_run 门禁违规综合教训 · 10. Markdown 代码块未指定语言触发 MD040 · 11. 嵌套 Shell 引号转义失败 · 12. Profiling 结果回传与 GBK 编码 · 13. 通用分析脚本纳入 Skills · 14. meta→to_empty 构造后未注册 buffer · 15. CRLF→LF 转换破坏二进制文件 · 16. 远端 model 模块名冲突 · 17. Gated Model 配置下载 · 18. expandable_segments 池锁定误判 OOM · 19. 多模型 CLI 参数不一致 · 20. 首次部署未检查远端文件完整性 · 21. 过度抽象 · 22. 未请求的额外功能 · 23. Pattern 单元测试通过但全模型不命中 · 24. register_replacement 无法处理 get_attr · 25. Inductor freeze 不识别自定义 NPU ops · 26. 编译开销定位方法	3	+> 目录 · 1. 拒绝未实现功能的前置配置 · 2. 最小必要改动原则 · 3. 独立任务必须实际并行执行 · 4. 非代码仓内容不入库 · 5. PLAN.md 未随任务变更同步更新 · 6. triton vs triton-ascend 包名混淆 · 7. pip install -e . 新增文件未被索引 · 8. SSH 连接重复创建 · 9. dummy_run 门禁违规综合教训 · 10. Markdown 代码块未指定语言触发 MD040 · 11. 嵌套 Shell 引号转义失败 · 12. Profiling 结果回传与 GBK 编码 · 13. 通用分析脚本纳入 Skills · 14. meta→to_empty 构造后未注册 buffer · 15. CRLF→LF 转换破坏二进制文件 · 16. 远端 model 模块名冲突 · 17. Gated Model 配置下载 · 18. expandable_segments 池锁定误判 OOM · 19. 多模型 CLI 参数不一致 · 20. 首次部署未检查远端文件完整性 · 21. 过度抽象 · 22. 未请求的额外功能 · 23. Pattern 单元测试通过但全模型不命中 · 24. register_replacement 无法处理 get_attr · 25. Inductor freeze 不识别自定义 NPU ops · 26. 编译开销定位方法 · 27. 打包排除 build 目录误删源码脚本 · 28. 权重分片缺失未对照 index.json 预检 · 29. vllm-omni 源码包缺 .git 导致版本非法 · 30. pip 依赖解析降级 torch 后未复原 · 31. 容器缺 HCCL ranktable 导致多卡失败 · 32. 第三方 wheel 文件名重命名破坏 pip 解析 · 33. 量化层 forward 内就地修改模块状态 → compile 每次重编译 · 34. 先诊断再下结论：性能劣化勿直接归因 kernel
4		4
5	以下问题均在 MindIE-SD 开发中实际发生并导致返工。	5	以下问题均在 MindIE-SD 开发中实际发生并导致返工。
6		6
	@@ -282,3 +282,107 @@ def graph_rewrite_after_freezing(fx_graph, inputs):
282	- RMSNorm 融合节省约 9ms（Pow+Mean → RmsNorm）	282	- RMSNorm 融合节省约 9ms（Pow+Mean → RmsNorm）
283		283
284	5. 确认 Custom Pattern 生效：搜索 compile 独有的 `RmsNorm` kernel（16ms）	284	5. 确认 Custom Pattern 生效：搜索 compile 独有的 `RmsNorm` kernel（16ms）
		285	+
		286	+## 27. 打包排除 build 目录误删源码脚本
		287	+
		288	+问题：用 tar 打包上传 vllm-ascend / MindIE-SD 源码时，EXCLUDE 列表包含 `build` 目录
		289	+（本意排除编译产物），但 vllm-ascend 的 patch 目录（`csrc/cmake/third_party/build/modules/patch/`）
		290	+和 MindIE-SD 的构建脚本目录（`build/*.sh`）都含 `build` 路径段，被一并排除。
		291	+后果：vllm-ascend 编译报 `protobuf_25.1_change_version.patch: No such file or directory`；
		292	+mindiesd 报 `No such file or directory: .../MindIE-SD/build`。
		293	+
		294	+规则：
		295	+
		296	+- 不要用 `in ('build', ...)` 匹配任意路径段，用精确路径或白名单
		297	+
		298	+## 28. 权重分片缺失未对照 index.json 预检
		299	+
		300	+问题：vllm serve 启动到权重加载时报
		301	+`ValueError: ... weights were not initialized from checkpoint`，列出几百个未加载权重。
		302	+根因是 `transformer/` 下缺少分片 00001（`diffusion_pytorch_model-00001-of-00009.safetensors`），
		303	+但 00002-00009 都在，目录看似"完整"。
		304	+
		305	+规则：
		306	+
		307	+- 不能只看目录里有多少个分片，必须对照 `*.safetensors.index.json` 的 `weight_map` 逐分片核对
		308	+- 缺失分片补下载：`https://hf-mirror.com/<org>/<model>/resolve/main/transformer/<缺失分片名>`
		309	+
		310	+## 29. vllm-omni 源码包缺 .git 导致版本非法
		311	+
		312	+问题：tar 打包排除 `.git` 后，vllm-omni `setup.py` 的 `get_version()`（setuptools_scm）
		313	+返回 `dev`，NPU 模式再拼 `+npu` 得到非法版本 `dev+npu`，
		314	+pip 报 `packaging.version.InvalidVersion`，metadata 生成失败。
		315	+
		316	+规则：
		317	+
		318	+- 源码安装时设 `export VLLM_OMNI_VERSION_OVERRIDE=0.26.0`（与目标 vllm 版本一致）
		319	+
		320	+## 30. pip 依赖解析降级 torch 后未复原
		321	+
		322	+问题：安装 vllm-omni 时 pip 按 vllm-ascend/vllm-omni 的 `requirements.txt`
		323	+（旧 pin `torch==2.10.0` / `torchaudio==2.10.0`）把 torch 从 2.11.0 降级到 2.10.0，
		324	+导致 torch_npu 2.11.0 报 `torch-npu requires torch==2.11.0+cpu`，NPU 后端加载失败。
		325	+
		326	+规则：
		327	+
		328	+- 后装组件用 `--no-deps` 或装完后立即复核版本（`python -c "import torch; print(torch.__version__)"`）
		329	+- 不以 vllm-ascend/omni 的 requirements.txt 旧 pin 为准
		330	+- 一次确认全栈版本（torch/torch_npu/vllm/vllm-ascend/vllm-omni）
		331	+
		332	+## 31. 容器缺 HCCL ranktable 导致多卡失败
		333	+
		334	+问题：vllm serve 多卡启动时，`--tensor-parallel-size 8` 的 worker 初始化报
		335	+`hcclCommInitRootInfoConfig error code is 4` / `Config_Error_Ranktable(EI0014)`。
		336	+根因：容器只挂载了 `/usr/local/Ascend/driver/lib64` 和 `version.info`，
		337	+未挂载 `/usr/local/Ascend/driver/topo`（HCCL ranktable JSON 所在目录）。
		338	+
		339	+规则：
		340	+
		341	+- 已运行容器可用 `docker cp /usr/local/Ascend/driver/topo <容器>:/usr/local/Ascend/driver/topo`
		342	+- 注意：docker cp 在容器重启后丢失，需重建或持久化挂载
		343	+
		344	+## 32. 第三方 wheel 文件名重命名破坏 pip 解析
		345	+
		346	+问题：为下载方便把 wheel 重命名为 `torch.whl` / `torch_npu.whl` 后
		347	+`pip install torch.whl` 报 `Invalid wheel filename (wrong number of parts)`。
		348	+pip 要求 wheel 文件名符合 `{name}-{version}-{build}-{py}-{abi}-{platform}.whl` 规范。
		349	+
		350	+规则：
		351	+
		352	+- 保留原始文件名，如 `torch-2.11.0+cpu-cp312-cp312-manylinux_2_28_x86_64.whl`
		353	+
		354	+## 33. 量化层 forward 内就地修改模块状态 → compile 每次重编译
		355	+
		356	+问题：w8a8/mxfp8 `--compile` 比 eager 慢 11~229×（transformer 1.8s vs 20ms）。
		357	+kernel profile 显示 wall 1873ms 中 kernel 仅 17ms（0.9%），Wait Time 1856ms，单个 1843ms
		358	+设备空闲间隙 —— 极端 host-bound。
		359	+
		360	+根因：`W8A8MXFP8OnlineQuantLinear.quant_matmul`（`mindiesd/quantization/layer.py`）forward 内
		361	+`self.bias = self.bias.to(torch.float32)` 就地修改模块状态。Dynamo guard 记录 trace 时的
		362	+bias dtype（bf16），执行后变成 fp32 → 每次调用 guard 失败 → 每次执行完整重编译
		363	+（Dynamo trace + Inductor + triton JIT ≈ 1.8s）。
		364	+
		365	+定位：`TORCH_LOGS=recompiles` 直接给出 guard failure 与具体 tensor
		366	+（`'..._buffers['bias']' dtype mismatch. expected BFloat16, actual Float`）。
		367	+
		368	+规则：
		369	+
		370	+- 算子层 forward 禁止就地修改模块属性（`self.xxx = ...`）；dtype 转换用局部变量
		371	+ （fp32 精度可通过局部变量传给算子保留）
		372	+- compile 性能异常先跑 `TORCH_LOGS=recompiles` 排除重编译，再进入 kernel 分析
		373	+- 修复后 w8a8 compile 从 1860ms 降至 16ms，全面优于 eager 与 bf16 compile
		374	+
		375	+## 34. 先诊断再下结论：性能劣化勿直接归因 kernel
		376	+
		377	+问题：曾将 mxfp8 compile 劣化初步归因于"量化算子无法融合/copy 开销"，但 profiling
		378	+证明 kernel 只占墙钟 0.9%，真正瓶颈是重编译（见上条）。若按错误归因去优化 kernel 会白费功夫。
		379	+
		380	+规则：
		381	+
		382	+- 用 kernel_details 区分 kernel-bound 与 host-bound：`wall_ms / kernel_sum_ms > 10` + Wait Time
		383	+ 高 → host-bound，先查 host 侧（重编译、launch、sync），再优化 kernel
		384	+- 结论必须基于 profiling 数据（kernel 时间占比、间隙位置、recompile 日志），不凭直觉
		385	+
		386	+## 维护与更新
		387	+
		388	+当出现新的返工教训时（复盘流程同步补充），按 dev-workflow 的复盘流程更新本文件。

M.agents/skills/markdown-lint/SKILL.md+2-1

	@@ -1,5 +1,6 @@
1	---	1	---
2	name: markdown-lint	2	name: markdown-lint
		3	+compatibility: markdownlint-cli v0.44.0, pre-commit
3	description: MindIE-SD 仓库 Markdown 格式 lint 规则。当编写、修改或审查 Markdown 文件（README、文档、	4	description: MindIE-SD 仓库 Markdown 格式 lint 规则。当编写、修改或审查 Markdown 文件（README、文档、
4	变更日志等）、或 CI 门禁报出 markdownlint 违规时使用此 skill。	5	变更日志等）、或 CI 门禁报出 markdownlint 违规时使用此 skill。
5	即使用户只提到"格式问题"或"MD040报错"而未说 markdownlint，也应触发。	6	即使用户只提到"格式问题"或"MD040报错"而未说 markdownlint，也应触发。
	@@ -13,7 +14,7 @@ description: MindIE-SD 仓库 Markdown 格式 lint 规则。当编写、修改
13	事实来源：	14	事实来源：
14		15
15	- `.pre-commit-config.yaml`（`markdownlint` 钩子配置）	16	- `.pre-commit-config.yaml`（`markdownlint` 钩子配置）
16	-- `markdownlint-cli` v0.46.0 规则集	17	+- `markdownlint-cli` v0.44.0 规则集
17		18
18	---	19	---
19		20

A.agents/skills/markdown-lint/evals/evals.json+38-0

@@ -0,0 +1,38 @@
	1	+{
	2	+ "skill_name": "markdown-lint",
	3	+ "evals": [
	4	+ {
	5	+ "id": 1,
	6	+ "prompt": "CI 报 MD040 违规，代码块没有语言标识，怎么批量修？",
	7	+ "expected_output": "按 markdown-lint：给围栏代码块补语言（python/shell/text/yaml 等），覆盖顶格与缩进两种变体，修复后重跑 markdownlint 验证",
	8	+ "files": [],
	9	+ "expectations": [
	10	+ "给出代码块语言选用指南（python/shell/text）",
	11	+ "提到覆盖顶格与缩进两种变体",
	12	+ "提到修复后重跑 markdownlint -c .markdownlint.json 验证 0 违规"
	13	+ ]
	14	+ },
	15	+ {
	16	+ "id": 2,
	17	+ "prompt": "批量修改含中文的 Markdown 文件，怎么保证编码不被破坏？",
	18	+ "expected_output": "按 §5.1：用 Python（open utf-8）或 Node.js 处理，避免 PowerShell Get-Content/Set-Content（引入 BOM 与乱码）",
	19	+ "files": [],
	20	+ "expectations": [
	21	+ "明确禁止 PowerShell 读写 UTF-8 中文文件",
	22	+ "给出 Python/Node.js 的安全处理方式",
	23	+ "提到修复后检查中文未损坏、无 BOM"
	24	+ ]
	25	+ },
	26	+ {
	27	+ "id": 3,
	28	+ "prompt": "提交前只想检查本次改动的 md 文件，怎么只跑这几个文件？",
	29	+ "expected_output": "pre-commit run markdownlint --files <file> 或 git diff --name-only HEAD~1..HEAD -- '*.md' \| xargs markdownlint -c .markdownlint.json",
	30	+ "files": [],
	31	+ "expectations": [
	32	+ "给出单文件检查命令",
	33	+ "给出提交范围检查命令（git diff --name-only + markdownlint）",
	34	+ "提到始终使用 -c .markdownlint.json 而非 --disable"
	35	+ ]
	36	+ }
	37	+ ]
	38	+}

M.agents/skills/mindie-sd-community-governance/SKILL.md+2-2

	@@ -1,5 +1,6 @@
1	---	1	---
2	name: mindie-sd-community-governance	2	name: mindie-sd-community-governance
		3	+compatibility: 无（assets/mr_ruleset_*.xlsx 随 skill 内置）
3	description: "Handle MindIE-SD documentation, governance, contributor workflow, commit or PR conventions, history cleanup, template changes, and version-policy updates with minimal context, fixed review steps, and deterministic output."	4	description: "Handle MindIE-SD documentation, governance, contributor workflow, commit or PR conventions, history cleanup, template changes, and version-policy updates with minimal context, fixed review steps, and deterministic output."
4	---	5	---
5		6
	@@ -78,7 +79,6 @@ description: "Handle MindIE-SD documentation, governance, contributor workflow,
78	- `.gitcode/PULL_REQUEST_TEMPLATE.md`	79	- `.gitcode/PULL_REQUEST_TEMPLATE.md`
79	- `README.md`	80	- `README.md`
80	- `docs/zh/developer_guide/test.md`	81	- `docs/zh/developer_guide/test.md`
81	-- `docs/zh/developer_guide/tooling.md`
82	- `assets/mr_ruleset_20260327101328.xlsx`，按需读取	82	- `assets/mr_ruleset_20260327101328.xlsx`，按需读取
83		83
84	### 3.3 文档内容或站点构建变更	84	### 3.3 文档内容或站点构建变更
	@@ -177,7 +177,7 @@ description: "Handle MindIE-SD documentation, governance, contributor workflow,
177	### 5.4 提交前检查	177	### 5.4 提交前检查
178		178
179	- 本地提交前检查入口统一使用 `pre-commit`	179	- 本地提交前检查入口统一使用 `pre-commit`
180	-- 事实依据来自 `README.md`、`docs/zh/developer_guide/test.md` 与 `docs/zh/developer_guide/tooling.md`	180	+- 事实依据来自 `README.md` 与 `docs/zh/developer_guide/test.md`
181	- 最小检查命令：	181	- 最小检查命令：
182	- `python -m pip install -r requirements-lint.txt`	182	- `python -m pip install -r requirements-lint.txt`
183	- `pre-commit install`	183	- `pre-commit install`

A.agents/skills/mindie-sd-community-governance/evals/evals.json+38-0

@@ -0,0 +1,38 @@
	1	+{
	2	+ "skill_name": "mindie-sd-community-governance",
	3	+ "evals": [
	4	+ {
	5	+ "id": 1,
	6	+ "prompt": "我要提交一个修复 pattern 的 commit，标题应该怎么写？",
	7	+ "expected_output": "按治理规范 5.1：commit 标题用 [Type][Scope]Summary 格式，Type 为 Feature/Bugfix/Docs/CI/Refactor/Test/Chore，如 [Bugfix][pattern] Fix RMSNorm matching for get_attr inputs",
	8	+ "files": [],
	9	+ "expectations": [
	10	+ "输出 [Type][Scope]Summary 格式",
	11	+ "Type 从固定集合中选择",
	12	+ "给出可直接使用的 commit 标题示例"
	13	+ ]
	14	+ },
	15	+ {
	16	+ "id": 2,
	17	+ "prompt": "准备提一个 PR，正文需要包含哪些内容？",
	18	+ "expected_output": "按 .gitcode/PULL_REQUEST_TEMPLATE.md：覆盖 Which issue(s)、Purpose、Test Plan、Test Report 四块；issue 关联用 Fixes # 或 Fix part of #",
	19	+ "files": [],
	20	+ "expectations": [
	21	+ "列出 4 个必需区块（Which issue(s)/Purpose/Test Plan/Test Report）",
	22	+ "提到 Fixes # 与 Fix part of # 写法",
	23	+ "提到缺少 issue/测试结果时保留占位标注"
	24	+ ]
	25	+ },
	26	+ {
	27	+ "id": 3,
	28	+ "prompt": "改了 docs/zh/ 下的用户文档，需要做什么配套检查？",
	29	+ "expected_output": "按治理规范：检查 docs/en/ 是否有对应配套页；若改首页/目录检查 docs/index.md 与中英文 menu_user_manual.md；给出文档站点编译验证命令（sphinx-build）",
	30	+ "files": [],
	31	+ "expectations": [
	32	+ "检查英文配套页是否存在",
	33	+ "检查首页/目录入口（index.md / menu_user_manual.md）",
	34	+ "给出 sphinx 编译验证路径"
	35	+ ]
	36	+ }
	37	+ ]
	38	+}

D.agents/skills/model-verification/SKILL.md+0-181

	@@ -1,181 +0,0 @@
1	----
2	-name: model-verification
3	-description: 在 NPU 上验证模型推理的正确性和兼容性。
4	- §A Dummy Run：使用随机权重快速验证新模型架构兼容性（无需真实权重）。
5	- §B 部署验证：验证已部署模型的推理正确性（依赖 ascend-deploy 完成部署）。
6	- 产出粗粒度时序数据可传递给 performance-analysis 或 profiling-collection。
7	- 当用户需要确认模型能否跑通、评估参数量和显存占用、
8	- 查验各组件构造耗时分布时使用此 skill。
9	- 即使用户只提到"帮我试试这个模型能不能跑"而未说 dummy run，也应触发。
10	- 由 dev-workflow 的验证阶段触发。
11	----
12	-
13	-# 模型验证
14	-
15	-验证模型在昇腾 NPU 上能否正确推理。
16	-
17	-## 前置确认
18	-
19	-验证前必须明确以下信息：
20	-
21	-\| 确认项 \| 说明 \| 示例 \|
22	-\|--------\|------\|------\|
23	-\| 模型名称 + 规格 \| 完整的模型标识 \| `FLUX.1-dev`, `Wan2.2-T2V-14B` \|
24	-\| 框架 \| 推理框架 \| `vLLM Omni` / `Cache DiT + diffusers` / `魔乐社区` \|
25	-\| 是否有真实权重 \| 权重状态 \| 仅配置文件 / 已下载完整权重 \|
26	-\| 依赖清单 \| 需要的 Python 包 \| `diffusers`, `transformers`, `sentencepiece` \|
27	-\| 部署状态 \| ascend-deploy 是否已完成 \| 已部署 / 未部署（需先执行 ascend-deploy） \|
28	-
29	-## 路径判断
30	-
31	-```text
32	-├─ 无真实权重 → §A Dummy Run 构造验证
33	-└─ 有真实权重 → §B 部署验证（需 ascend-deploy 完成）
34	-```
35	-
36	-> 环境部署问题见 ascend-deploy。NPU OOM 处理见 ascend-deploy §2 Step 7。
37	-
38	----
39	-
40	-## §A Dummy Run 构造验证
41	-
42	-使用随机权重构造模型，快速验证架构兼容性，无需下载几十 GB 的真实权重。
43	-
44	-### A1 适用场景
45	-
46	-- 在 NPU 上验证模型架构兼容性，无需下载真实权重
47	-- 评估模型参数量、显存占用、推理耗时
48	-- 先验证能跑通，再决定是否下载完整权重
49	-
50	-### A2 手动逐组件构造
51	-
52	-```python
53	-# Transformer / VAE / Scheduler：从 diffusers 加载 config → 随机权重
54	-transformer_cfg = FluxTransformer2DModel.load_config(config_dir, subfolder="transformer")
55	-transformer = FluxTransformer2DModel.from_config(transformer_cfg, torch_dtype=torch.bfloat16)
56	-
57	-# Text Encoder：从 transformers 加载 config → 随机权重
58	-clip_cfg = CLIPTextConfig.from_pretrained(clip_dir)
59	-text_encoder = CLIPTextModel(clip_cfg).to(torch.bfloat16)
60	-
61	-# Tokenizer：需要真实词表文件（KB 级），通过公开 repo 下载
62	-tokenizer = CLIPTokenizer.from_pretrained(clip_dir)
63	-
64	-# 组装 Pipeline
65	-pipe = FluxPipeline(
66	- scheduler=scheduler, vae=vae,
67	- text_encoder=text_encoder, tokenizer=tokenizer,
68	- transformer=transformer, ...
69	-)
70	-```
71	-
72	-配置文件可通过 modelscope 离线下载（KB 级），命令行 `--config_cache` 指定路径，无需 `HF_TOKEN`。
73	-两种构造方式的适用场景与已知陷阱详见 references/construction-methods.md。
74	-
75	-### A3 优化技巧
76	-
77	-\| 优化项 \| 方式 \| 效果 \|
78	-\|---\|---\|---\|
79	-\| 减少 Transformer block 数 \| `transformer_cfg["num_layers"] = 2` \| 参数量大幅降低 \|
80	-\| 关闭 CFG \| `guidance_scale=1.0` \| Transformer forward 减半 \|
81	-\| 跳过 VAE decode \| `output_type="latent"` \| 跳过 ~70% 推理耗时 \|
82	-\| 配置缓存 \| `snapshot_download(model_id, local_files_only=True)` \| 免联网，秒级启动 \|
83	-\| Warmup + Timed 分离 \| 先 warmup 不计时，再 timed 计时 \| 排除 JIT 冷启动 \|
84	-
85	-> `num_layers` 裁剪仅适用于支持动态层数的模型。
86	-
87	-### A4 验证结果示例
88	-
89	-```text
90	-transformer params: 14.29 B
91	-Total params: 34.38 B
92	-Estimated memory (bf16): 64.0 GB
93	-
94	-[CPU offload mode]
95	-Build time: 359.1 s
96	-Inference time: 122.1 s (2 steps, 5 frames)
97	-Peak NPU memory: 18.74 GB
98	-Verification: PASSED
99	-```
100	-
101	-### A5 常见问题（构造专属）
102	-
103	-\| 问题 \| 原因 \| 解决 \|
104	-\|---\|---\|---\|
105	-\| `AttributeError: 'list' object has no attribute '__module__'` \| Pipeline.from_config() tokenizer bug \| 手动逐组件构造 \|
106	-\| `TransformersModel has no attribute 'from_config'` \| transformers 版本不支持 \| `ModelClass(config)` \|
107	-\| `CLIPConfig has no attribute 'hidden_size'` \| AutoConfig 返回错误类型 \| `CLIPTextConfig.from_pretrained()` \|
108	-\| `NotImplementedError: Cannot copy out of meta tensor` \| meta→to_empty 后 buffer 残留 \| 降级为 CPU 直接构造 \|
109	-
110	-> 环境问题（`diffusers` 缺失、`sentencepiece` 缺失）见 ascend-deploy 故障排查表。
111	-
112	----
113	-
114	-## §B 部署验证
115	-
116	-> 前置条件：模型已通过 ascend-deploy 部署到 NPU 设备，`import mindiesd` 成功。
117	-
118	-验证已部署模型在真实权重下的推理正确性。按框架选择验证方法：
119	-
120	-### B1 vLLM Omni 部署
121	-
122	-```bash
123	-# 1. 检查服务状态
124	-curl http://localhost:8000/health
125	-
126	-# 2. 发送 1 次推理请求
127	-curl http://localhost:8000/generate -H "Content-Type: application/json" \
128	- -d '{"prompt": "test", "max_tokens": 1}'
129	-
130	-# 验证: HTTP 200 + 输出非空
131	-```
132	-
133	-### B2 Cache DiT + diffusers 部署
134	-
135	-```python
136	-# from_pretrained 加载已部署模型
137	-pipe = FluxPipeline.from_pretrained(
138	- model_path, torch_dtype=torch.bfloat16
139	-).to("npu")
140	-
141	-# 跑 1 步推理
142	-output = pipe("test prompt", num_inference_steps=1)
143	-
144	-# 验证: 无异常、无 OOM、output.images[0] shape 合法
145	-print(f"Output shape: {output.images[0].size}")
146	-```
147	-
148	-### B3 魔乐社区部署
149	-
150	-按社区指定入口执行，重点检查特性叠加是否生效：
151	-
152	-- 量化开关 → 权重精度是否符合预期
153	-- 稀疏开关 → sparsity 参数是否生效
154	-- Cache 开关 → 缓存命中日志有无
155	-
156	-### B4 验证通过标准
157	-
158	-\| 检查项 \| 标准 \|
159	-\|--------\|------\|
160	-\| 推理无异常 \| 无 `RuntimeError` / `OOM` / `CUDA error` \|
161	-\| 输出合法 \| shape > 0，非全零输出 \|
162	-\| 显存正常 \| 峰值 < 物理显存 90% \|
163	-\| 特性叠加 \| 量化/稀疏/Cache 开关生效 \|
164	-
165	----
166	-
167	-## 阶段耗时与显存追踪
168	-
169	-推理耗时与显存的精确追踪使用 _PhaseTimer 类，详见 references/phase-timer.md。
170	-
171	-> 需要更细粒度的 profiling 数据（kernel_details.csv, trace_view.json）时使用 profiling-collection。
172	-
173	-## Reference Files
174	-
175	-- 📦 `references/construction-methods.md` — 加载时机: 涉及模型构造方式选择或 gated model 配置文件获取时
176	-- ⏱️ `references/phase-timer.md` — 加载时机: 需要精确追踪推理各阶段耗时与显存时
177	-
178	-## 维护与更新
179	-
180	-当遇到新模型的兼容性问题、框架版本升级导致验证方式变化、
181	-或发现新的 NPU 算子兼容性问题时，按 dev-workflow 的复盘流程更新本 skill。

D.agents/skills/model-verification/references/construction-methods.md+0-69

	@@ -1,69 +0,0 @@
1	-# 模型构造方式与配置获取
2	-
3	-## 1. 模型构造方式
4	-
5	-有两种构造方式，各有适用场景和已知陷阱：
6	-
7	-### 方式 A：meta→to_empty（推荐用于已知兼容的模型）
8	-
9	-```python
10	-with torch.device("meta"):
11	- model = ModelClass.from_config(cfg, torch_dtype=torch.bfloat16)
12	-model.to_empty(device=torch.device("cpu")) # 或 npu_device
13	-```
14	-
15	-- 优点：构造时不分配 CPU/NPU 内存，极快
16	-- 适用范围：`WanTransformer3DModel`、`AutoencoderKLWan`、`AutoencoderKL` 等经过验证的模型
17	-
18	-### 方式 B：CPU 直接构造（兜底方案）
19	-
20	-```python
21	-model = ModelClass.from_config(cfg, torch_dtype=torch.bfloat16) # 分配 CPU 内存
22	-model.to(npu_device)
23	-```
24	-
25	-- 优点：100% 可靠，不依赖 meta 设备
26	-- 缺点：`from_config` 时占用 CPU RAM（大模型可能 OOM）
27	-
28	-### 已知陷阱
29	-
30	-\| 陷阱 \| 表现 \| 解决 \|
31	-\|---\|---\|---\|
32	-\| meta→to_empty 后未注册 buffer 残留 meta 设备 \| 运行时 `NotImplementedError: Cannot copy out of meta tensor; no data!` \| 降级为方式 B（CPU 直接构造）。常见于含位置编码预计算的模型（如 `QwenImageTransformer2DModel`） \|
33	-\| meta→to_empty→cpu 后与 accelerate hooks 不兼容 \| NPU 硬件错误 `SUSPECT REMOTE ERROR, error code 507057` \| 降级为方式 B。常见于 `CLIPTextModel` 等通过 accelerate 管理的轻量模型 \|
34	-\| VL 模型未裁剪 vision tower \| NPU OOM（vision tower 通常 32 层） \| 同步设置 `vision_config.depth`（见模型特定注意事项） \|
35	-
36	-### 模型特定注意事项
37	-
38	-Qwen2_5_VLForConditionalGeneration（Qwen-Image 的 text_encoder）：
39	-
40	-- 含独立 vision tower（`vision_config.depth = 32`），裁剪 `num_hidden_layers` 时必须同步裁剪 `vision_config.depth`
41	-- 推荐始终用方式 B（CPU 构造），避免 VL 模型复杂性
42	-
43	-FluxTransformer2DModel：
44	-
45	-- 层数参数可能有多个名称：`num_layers`、`num_single_transformer_blocks`、`num_joint_transformer_blocks`
46	-- 为兼容性，三者同时设置相同值
47	-
48	-## 2. Gated Model 配置获取
49	-
50	-对于 gated model（如 FLUX.1-dev）：
51	-
52	-\| 方案 \| 说明 \|
53	-\|---\|---\|
54	-\| `HF_TOKEN` 环境变量 \| 接受 license 后设置 token，`snapshot_download` 自动鉴权 \|
55	-\| modelscope 离线下载（推荐） \| 从 modelscope 下载 KB 级配置文件，`--config_cache` 指定路径，无需 HF_TOKEN \|
56	-\| 公开组件拆分 \| 仅适用于 text_encoder/tokenizer 来自公开 repo 的模型（如 FLUX 的 CLIP + T5） \|
57	-
58	-modelscope 离线流程：
59	-
60	-```python
61	-# 本地下载配置
62	-from modelscope import snapshot_download
63	-config_dir = snapshot_download(
64	- "black-forest-labs/FLUX.1-dev",
65	- allow_patterns=[".json", ".txt", ".model", "tokenizer", "merges", "vocab"],
66	- ignore_patterns=[".safetensors", ".bin", ".ckpt", ".pth"],
67	-)
68	-# 上传到远端后使用 --config_cache
69	-```

D.agents/skills/model-verification/references/phase-timer.md+0-43

	@@ -1,43 +0,0 @@
1	-# 阶段耗时与显存追踪
2	-
3	-## _PhaseTimer 类
4	-
5	-在每个 dummy run 脚本中内嵌统一的 `_PhaseTimer` 实例，追踪 BUILD 和 INFERENCE 两阶段的各模块耗时与显存：
6	-
7	-- BUILD 阶段：各组件构造时调用 `timer.record_build(name, elapsed)`，自动记录耗时 + 显存增量
8	-- INFERENCE 阶段：通过 `register_forward_pre_hook` / `register_forward_hook` 挂载到 pipe 的 `text_encoder`、`transformer`、`transformer_2`、`vae` 子模块，自动记录每次 forward 耗时和内存快照
9	-- Warmup/Timed 分离：先 `capture_warmup()` 消除 NPU 算子冷启动，再 `capture_timed()` 精确计时
10	-
11	-典型输出为 BUILD + INFERENCE 两段式汇总：
12	-
13	-```text
14	-======================================================================
15	- BUILD Time(s) Mem(GB)
16	- ----------------------------------------------------------
17	- Transformer 0.1 3.49
18	- Transformer_2 0.1 6.97
19	- VAE 0.1 7.44
20	- Text encoder + scheduler + tokenizer 1.4 18.03
21	- Move to device 0.0 18.03
22	- ----------------------------------------------------------
23	- BUILD TOTAL 1.7
24	-
25	- INFERENCE Time(s) Mem(GB) Peak(GB)
26	- --------------------------------------------------------------------
27	- -- Warmup --
28	- text_encoder 0.4 18.03 18.09
29	- transformer 7.2 18.09 18.09
30	-
31	- -- Timed --
32	- text_encoder 0.1 18.07 18.09
33	- transformer 7.1 18.09 18.09
34	- --------------------------------------------------------------------
35	- OVERALL TOTAL 8.8 18.09
36	-======================================================================
37	-```
38	-
39	-## 注意事项
40	-
41	-- forward hook 仅触发 `forward()` 调用，不触发 `decode()` / `encode()` 等子方法。VAE decode 耗时需通过总耗时减去 hook 记录耗时反推。
42	-- `torch_npu.npu.synchronize()` 在 hook 前后各调用一次，确保 NPU 异步操作已完成再计时。
43	-- 显存通过 `torch_npu.npu.memory_allocated(device_id)` 获取已分配量，峰值取各阶段最大值。

M.agents/skills/parallelism-strategy/SKILL.md+46-8

	@@ -1,32 +1,70 @@
1	---	1	---
2	name: parallelism-strategy	2	name: parallelism-strategy
3	-description: [WIP] 大模型分布式并行策略选型参考。当前提供策略分类概览（TP/USP/RSP/CFG），	3	+compatibility: 无额外工具（参考数据来自 dummy-run-dev/references/minimax-h3-notes.md §9）；多卡需 HCCL 环境
4	- 具体决策树和实测性能数据待后续补充。	4	+description: 大模型分布式并行策略选型与实测：Ulysses USP（all_to_all FA 切头）、
5	- 当用户需要在多个 GPU/昇腾设备上训练大模型、了解可选并行策略时使用此 skill。	5	+ Context Parallel 通信掩盖（comm-stream masking）、CFG 并行、TP/RSP 概览。
		6	+ 含 910B 实测数据与 HcclAlltoAllV 缺陷绕过方案（pad+等分）。
		7	+ 当用户需要多卡并行策略选择、上下文并行/通信掩盖调优、或排查多卡通信问题时使用此 skill。
		8	+ 即使用户只提到"多卡跑不动"或"通信暴露大"而未说并行，也应触发。
6	由 dev-workflow 在多卡场景中触发。	9	由 dev-workflow 在多卡场景中触发。
7	---	10	---
8		11
9	# 并行策略选择	12	# 并行策略选择
10		13
11	-> ⚠️ WIP — 此 skill 尚未完成。当前仅提供策略分类大纲，具体实施指南待后续补充。
12	-
13	## 策略一览	14	## 策略一览
14		15
15	\| 策略 \| 适用场景 \| 通信模式 \| 关键参数 \|	16	\| 策略 \| 适用场景 \| 通信模式 \| 关键参数 \|
16	\|------\|---------\|---------\|---------\|	17	\|------\|---------\|---------\|---------\|
17	-\| Ulysses 并行 \| 多模态扩散模型（序列维度切分） \| all-to-all \| ulysses_size \|	18	+\| Ulysses 并行 (USP) \| 多模态扩散模型（序列维度切分） \| all-to-all \| ulysses_size \|
18	\| CFG 并行 \| 开启 classifier-free guidance 的模型 \| 双分支独立推理 \| cfg_parallel \|	19	\| CFG 并行 \| 开启 classifier-free guidance 的模型 \| 双分支独立推理 \| cfg_parallel \|
19	\| 张量并行 (TP) \| 单层参数量超单卡显存 \| all-reduce / all-gather \| tp_size \|	20	\| 张量并行 (TP) \| 单层参数量超单卡显存 \| all-reduce / all-gather \| tp_size \|
20	\| 环状序列并行 (RSP) \| 长序列场景，通信可被计算掩盖 \| P2P 环形传递 \| world_size \|	21	\| 环状序列并行 (RSP) \| 长序列场景，通信可被计算掩盖 \| P2P 环形传递 \| world_size \|
21	\| 流水线并行 (PP) \| 层数多、单层显存可承受 \| send/recv \| pp_size \|	22	\| 流水线并行 (PP) \| 层数多、单层显存可承受 \| send/recv \| pp_size \|
22		23
		24	+## 已实测（910B NPU，2026-08，4 卡 CP + 通信掩盖）
		25	+
		26	+> 数据来源：`dummy-run-dev/references/minimax-h3-notes.md` §9（MiniMax-H3 256×384×124, 2 layers, bf16）。
		27	+
		28	+### Ulysses USP 触发条件
		29	+
		30	+Ulysses 的 all_to_all FA 切头路径不会自动生效：仅给 attention processor 设 seq 分片时
		31	+走的是非 CP 路径（profile 只有 allGather 无 allToAll）。必须给每个
		32	+`attn.processor._parallel_config` 设 `ParallelConfig(context_parallel_config=cp_cfg)`
		33	+（注意是 `ParallelConfig` 包装，不是 `ContextParallelConfig`），才会触发切头路径。
		34	+
		35	+### 通信掩盖（comm-stream masking）
		36	+
		37	+把 `torch.distributed._functional_collectives.all_to_all_single` /
		38	+`all_gather_tensor` monkey-patch 为 `mindiesd.parallel` 的专用流版本
		39	+（见 `examples/dummy_run/masking.py`）：HCCL 集合跑在独立 comm stream 上，
		40	+与 caller stream 的计算重叠（compute 记 ready 事件 → comm stream 等 → HCCL → 记 done → compute 等）。
		41	+
		42	+实测收益（mask on/off）：
		43	+
		44	+\| 指标 \| unmasked CP \| masked CP \| 改善 \|
		45	+\|---\|---\|---\|---\|
		46	+\| kernel 总耗时 \| 37.5ms \| 12.1ms \| -67.7% \|
		47	+\| Communication（未掩盖） \| 31.4ms \| 1.5ms \| -95.2% \|
		48	+\| Stage（设备时间线） \| 71.5ms \| 35.5ms \| -50.3% \|
		49	+
		50	+### HcclAlltoAllV 缺陷与绕过（重要）
		51	+
		52	+CANN 9.1.0 环境 `HcclAlltoAllV`（split 路径）SIGSEGV（等分 `HcclAlltoAll` 正常）。
		53	+绕过方案：pad + 等分——把 input 各块 pad 到 `S_PAD`（128 倍数，由全局 max(out_sizes)
		54	+推导，全 rank 一致），用等分 `HcclAlltoAll(count=S_PAD×row_elems)` 交换，再 slice 各块前
		55	+`out_sizes[j]` 行。实测 err=0.0，kernel 名从 `hcom_alltoallv` 变为 `hcom_alltoall`（等分）。
		56	+
23	## WIP 待定内容	57	## WIP 待定内容
24		58
25	-- [ ] 各策略在昇腾 910B 上的实测性能数据	59	+- [ ] 各策略在昇腾 910B 上的完整实测性能对比表
26	- [ ] HCCL 拓扑感知的策略选择决策树	60	- [ ] HCCL 拓扑感知的策略选择决策树
27	-- [ ] 混合并行策略的配置模板	61	+- [ ] 混合并行策略的配置模板（如 USP + CFG 组合）
28	- [ ] 策略切换的性能对比方法论	62	- [ ] 策略切换的性能对比方法论
29		63
		64	+## Reference Files
		65	+
		66	+- 📝 `../dummy-run-dev/references/minimax-h3-notes.md` §9 — 加载时机: 需要 CP/USP 实测细节、mask 注入代码或 AlltoAllV 绕过实现时
		67	+
30	## 维护与更新	68	## 维护与更新
31		69
32	当新的并行策略经验证有效、多卡互联拓扑发生变化或发现新的分布式训练模式时，	70	当新的并行策略经验证有效、多卡互联拓扑发生变化或发现新的分布式训练模式时，

A.agents/skills/parallelism-strategy/evals/evals.json+38-0

@@ -0,0 +1,38 @@
	1	+{
	2	+ "skill_name": "parallelism-strategy",
	3	+ "evals": [
	4	+ {
	5	+ "id": 1,
	6	+ "prompt": "多卡推理时 profiling 显示通信暴露 30%，怎么优化？",
	7	+ "expected_output": "路由到 parallelism-strategy：通信掩盖（comm-stream masking，mindiesd.parallel 专用流 + monkey-patch funcol.all_to_all_single/all_gather_tensor），参考实测收益（Communication -95%）",
	8	+ "files": [],
	9	+ "expectations": [
	10	+ "提到 comm-stream masking 方案（独立 HCCL 流与计算重叠）",
	11	+ "提到 monkey-patch 入口（funcol.all_to_all_single / all_gather_tensor）",
	12	+ "给出实测收益参考（通信未掩盖 31.4ms → 1.5ms）"
	13	+ ]
	14	+ },
	15	+ {
	16	+ "id": 2,
	17	+ "prompt": "配了 Ulysses 并行但 profiling 里只有 allGather 没有 allToAll，FA 切头没生效？",
	18	+ "expected_output": "按 USP 触发条件：必须给每个 attn.processor._parallel_config 设 ParallelConfig(context_parallel_config=cp_cfg)（ParallelConfig 包装而非 ContextParallelConfig），否则走非 CP 路径",
	19	+ "files": [],
	20	+ "expectations": [
	21	+ "定位为 _parallel_config 未正确设置",
	22	+ "提到 ParallelConfig 包装（不是 ContextParallelConfig）",
	23	+ "提到设置后才会触发 all_to_all FA 切头路径"
	24	+ ]
	25	+ },
	26	+ {
	27	+ "id": 3,
	28	+ "prompt": "多卡跑的时候 HcclAlltoAllV 直接 SIGSEGV 崩了，怎么办？",
	29	+ "expected_output": "按 AlltoAllV 缺陷绕过：等分 HcclAlltoAll 正常、split 路径 SIGSEGV → 用 pad + 等分方案（pad 到 S_PAD 128 倍数，等分交换后 slice），实测 err=0.0",
	30	+ "files": [],
	31	+ "expectations": [
	32	+ "说明 HcclAlltoAllV split 路径缺陷（CANN 9.1.0）",
	33	+ "给出 pad + 等分绕过方案",
	34	+ "提到 kernel 名从 hcom_alltoallv 变为 hcom_alltoall"
	35	+ ]
	36	+ }
	37	+ ]
	38	+}

M.agents/skills/performance-analysis/SKILL.md+22-4

	@@ -1,5 +1,6 @@
1	---	1	---
2	name: performance-analysis	2	name: performance-analysis
		3	+compatibility: Python 3.10+（脚本仅用标准库）；输入为 profiling 数据（kernel_details.csv / trace_view.json）
3	description: 针对真实 NPU 设备的 profiling 数据（trace.json / kernel_details.csv），	4	description: 针对真实 NPU 设备的 profiling 数据（trace.json / kernel_details.csv），
4	分析模型性能分布，定位算子级耗时与显存热点，输出瓶颈诊断和改进建议。	5	分析模型性能分布，定位算子级耗时与显存热点，输出瓶颈诊断和改进建议。
5	当用户有实际 profiling 产出、需要理解"模型为什么慢"或查找具体瓶颈时使用此 skill。	6	当用户有实际 profiling 产出、需要理解"模型为什么慢"或查找具体瓶颈时使用此 skill。
	@@ -14,7 +15,7 @@ description: 针对真实 NPU 设备的 profiling 数据（trace.json / kernel_d
14	## 数据源	15	## 数据源
15		16
16	Profiling 数据由 profiling-collection skill 在远端 NPU 设备上采集产出（已剔除 warmup）。	17	Profiling 数据由 profiling-collection skill 在远端 NPU 设备上采集产出（已剔除 warmup）。
17	-也可来自 model-verification 的粗粒度时序或 performance-evaluation 的 msmodeling 分析。	18	+也可来自 dummy-run-dev 的粗粒度时序。
18		19
19	\| 数据文件 \| 格式 \| 说明 \|	20	\| 数据文件 \| 格式 \| 说明 \|
20	\|---------\|------\|------\|	21	\|---------\|------\|------\|
	@@ -83,7 +84,7 @@ DiT: xx ms (xx%) \| VAE: xx ms (xx%)
83		84
84	对每个阶段独立做三层分析：	85	对每个阶段独立做三层分析：
85		86
86	-Layer 3a: Host Bound 分析	87	+#### Layer 3a: Host Bound 分析
87		88
88	多指标核算体系：同时维护以下指标（参照 ascend-profiling-anomaly）：	89	多指标核算体系：同时维护以下指标（参照 ascend-profiling-anomaly）：
89		90
	@@ -111,7 +112,24 @@ Anomaly 标签（参照 ascend-profiling-anomaly）：
111	\| `INTERNAL_BUBBLE_HEAVY` \| largest_internal_bubble >= max(1ms, 10% step) \|	112	\| `INTERNAL_BUBBLE_HEAVY` \| largest_internal_bubble >= max(1ms, 10% step) \|
112	\| `HOST_ORIGINATED_RISK` \| 高 underfeed + 周期性 bubble + host event 证据 \|	113	\| `HOST_ORIGINATED_RISK` \| 高 underfeed + 周期性 bubble + host event 证据 \|
113		114
114	-Layer 3b: 通信掩盖分析（多卡）	115	+快捷判别：先排除 torch.compile 重编译，再归因 kernel
		116	+
		117	+当 `wall_ms / kernel_sum_ms >> 10`（kernel 总耗时只占墙钟个位数百分比）、`Wait Time` 合计接近
		118	+wall、且出现单个超大设备空闲间隙（如 1.8s 里 99% 空闲）时，优先怀疑 **Dynamo guard 失败导致
		119	+每次调用重编译**，而不是 kernel 慢。典型根因：算子层 forward 内就地修改模块状态（如把 bias 从
		120	+bf16 改 fp32）使 guard 不稳定。
		121	+
		122	+```shell
		123	+# 确认重编译与 guard 失败原因（比 trace 分析更直接）
		124	+TORCH_LOGS=recompiles python <infer>.py --compile ... 2>&1 \| grep -E "Recompiling\|guard failure"
		125	+# 输出形如: tensor '..._buffers['bias']' dtype mismatch. expected BFloat16, actual Float
		126	+```
		127	+
		128	+重编译一次 ≈ Dynamo trace + Inductor codegen + triton JIT（~1.8s），会让 compile 比 eager 慢
		129	+10~200×。修复（forward 用局部变量、不 mutate 模块状态）后 compile 恢复应有的收益。
		130	+详见 compilation-dev/references/pattern-dev.md §4 与 dev-workflow/references/rework-lessons.md。
		131	+
		132	+#### Layer 3b: 通信掩盖分析（多卡）
115		133
116	```text	134	```text
117	Exposed Ratio = 未与计算重叠的通信耗时 / 通信总耗时	135	Exposed Ratio = 未与计算重叠的通信耗时 / 通信总耗时
	@@ -131,7 +149,7 @@ Exposed Ratio = 未与计算重叠的通信耗时 / 通信总耗时
131		149
132	> 完整 HCCL 测试和带宽数据见 hccl-test（Ascend agent-skills）。	150	> 完整 HCCL 测试和带宽数据见 hccl-test（Ascend agent-skills）。
133		151
134	-Layer 3c: 融合机会分析	152	+#### Layer 3c: 融合机会分析
135		153
136	优先检查 MindIE-SD 编译 Pattern（有开关可直接启用）：	154	优先检查 MindIE-SD 编译 Pattern（有开关可直接启用）：
137		155

A.agents/skills/performance-analysis/evals/evals.json+38-0

@@ -0,0 +1,38 @@
	1	+{
	2	+ "skill_name": "performance-analysis",
	3	+ "evals": [
	4	+ {
	5	+ "id": 1,
	6	+ "prompt": "帮我看看这份 kernel_details.csv 和 trace_view.json，模型为什么这么慢？",
	7	+ "expected_output": "跑 5 层递进分析（analyze_trace.py --profile-dir/--output-dir）：Layer 1 DiT/VAE 分离 → Layer 2 分类占比 → Layer 3 Host Bound/通信/融合 → Layer 4 算子明细 → Layer 5 P0-P2 建议",
	8	+ "files": [],
	9	+ "expectations": [
	10	+ "输出 Layer 1（DiT vs VAE 阶段占比）",
	11	+ "输出 Layer 2（FA/MatMul/Vector/Comm 分类占比）",
	12	+ "输出 Layer 5 方向级建议（P0-P2 优先级）"
	13	+ ]
	14	+ },
	15	+ {
	16	+ "id": 2,
	17	+ "prompt": "优化前后各采了一次 profiling，帮我对比看有没有效果",
	18	+ "expected_output": "用 compare_traces.py --baseline/--target/--baseline-label/--target-label 做算子级对比，标注 REGRESSION/improvement",
	19	+ "files": [],
	20	+ "expectations": [
	21	+ "使用 compare_traces.py",
	22	+ "对比按 kernel 名称聚合",
	23	+ "标注 REGRESSION/improvement 并给出结论"
	24	+ ]
	25	+ },
	26	+ {
	27	+ "id": 3,
	28	+ "prompt": "profile 数据里第一步耗时异常高，怀疑 warmup 没剔除",
	29	+ "expected_output": "Layer 0 warmup 校验：检测首步耗时异常/编译 kernel 集中出现 → 标注 WARMUP_NOT_STRIPPED，建议重新采集（warmup ≥5 步）",
	30	+ "files": [],
	31	+ "expectations": [
	32	+ "提到 WARMUP_NOT_STRIPPED 标注",
	33	+ "给出重新采集建议（warmup 步数）",
	34	+ "说明 warmup 未剔除会影响分析结论"
	35	+ ]
	36	+ }
	37	+ ]
	38	+}

M.agents/skills/performance-analysis/references/analysis_workflow.md+5-1

	@@ -33,7 +33,7 @@ python profiling-collection/scripts/collect_profile.py \
33		33
34	### Step 3: 本地分析	34	### Step 3: 本地分析
35		35
36	-使用 `analyze_trace.py` 对 Profiling 数据做三层递进分析：	36	+使用 `analyze_trace.py` 对 Profiling 数据做 5 层递进分析（Layer 3 内含三层子分析）：
37		37
38	```bash	38	```bash
39	tar xzf profile_l1.tar.gz	39	tar xzf profile_l1.tar.gz
	@@ -70,3 +70,7 @@ python analyze_trace.py --profile-dir ./profile_l1 --output-dir ./
70	- [ascend-profiling-anomaly](https://github.com/Ascend/agent-skills/tree/master/skills/ascend-profiling-anomaly): Bubble 检测、Anomaly 标签、Wait-Anchor 扫描、AICPU 分类	70	- [ascend-profiling-anomaly](https://github.com/Ascend/agent-skills/tree/master/skills/ascend-profiling-anomaly): Bubble 检测、Anomaly 标签、Wait-Anchor 扫描、AICPU 分类
71	- [ascend-deploy](../../ascend-deploy/SKILL.md): 远端部署	71	- [ascend-deploy](../../ascend-deploy/SKILL.md): 远端部署
72	- [profiling-collection](../../profiling-collection/SKILL.md): Profiling 数据采集	72	- [profiling-collection](../../profiling-collection/SKILL.md): Profiling 数据采集
		73	+
		74	+## 维护与更新
		75	+
		76	+当分析流程或脚本调用方式变化时，按 dev-workflow 的复盘流程更新本文件。

M.agents/skills/performance-analysis/references/capability-matrix.md+6-2

	@@ -21,11 +21,15 @@
21		21
22	\| 模型 \| 硬件 \| 日期 \| 结果 \|	22	\| 模型 \| 硬件 \| 日期 \| 结果 \|
23	\|------\|------\|------\|------\|	23	\|------\|------\|------\|------\|
24	-\| Wan2.2-T2V-14B \| 910B × 1 \| 2026-05-09 \| 已验证 (NC/C/torchair_ge/npugraph_ex 四模式, torchair_ge 消除 Copy) \|	24	+\| Wan2.2-T2V-14B \| 910B × 1 \| 2026-05-09 \| 已验证 (NC/C 两模式, C=default/Inductor) \|
25	-\| FLUX.1-dev \| 910B × 1 \| 2026-05-09 \| 已验证 (NC/C/torchair_ge/npugraph_ex 四模式, default(C) 最优) \|	25	+\| FLUX.1-dev \| 910B × 1 \| 2026-05-09 \| 已验证 (NC/C 两模式, default(C) 最优) \|
26	\| FLUX.1-dev \| L20 × 1 \| 2024-03-08 \| 已验证（见 evaluation_report.md） \|	26	\| FLUX.1-dev \| L20 × 1 \| 2024-03-08 \| 已验证（见 evaluation_report.md） \|
27		27
28	## 不可支持场景	28	## 不可支持场景
29		29
30	- 未触发 MindieSDBackend 编译的 trace：门控中止，先修复编译配置	30	- 未触发 MindieSDBackend 编译的 trace：门控中止，先修复编译配置
31	- diffusers 原生 fallback 的 trace：标注为 baseline，不用于优化分析	31	- diffusers 原生 fallback 的 trace：标注为 baseline，不用于优化分析
		32	+
		33	+## 维护与更新
		34	+
		35	+当验证证据或支持矩阵变化时，按 dev-workflow 的复盘流程更新本文件。

M.agents/skills/performance-analysis/references/heuristics.md+8-4

	@@ -6,14 +6,14 @@
6		6
7	\| 条件 \| 选择 \|	7	\| 条件 \| 选择 \|
8	\|------\|------\|	8	\|------\|------\|
9	-\| Copy 膨胀 >50% 且模型含 3D attention \| torchair_ge (绕过 aot_autograd functionalization) \|	9	+\| 静态 shape / 大 batch，需减少 host launch 开销 \| aclgraph 批量下发（见 `aclgraph-dev`） \|
10	\| 模型使用标准 Norm 层 (如 FLUX) \| default (MindieSDBackend, pattern 全部命中) \|	10	\| 模型使用标准 Norm 层 (如 FLUX) \| default (MindieSDBackend, pattern 全部命中) \|
11	-\| 模型使用 FP32LayerNorm (如 Wan2.2) \| torchair_ge (pattern 不匹配, Copy 膨胀) \|	11	+\| Pattern 命中但 Copy 膨胀 \| 修复 pattern / 混合模式（见 compilation-dev Phase 7） \|
12	\| 模型未支持 MindieSDBackend \| eager baseline → 标记为"待编译器适配" \|	12	\| 模型未支持 MindieSDBackend \| eager baseline → 标记为"待编译器适配" \|
13	\| VAE 部分不稳定 \| compiled transformer + eager VAE (混合模式) \|	13	\| VAE 部分不稳定 \| compiled transformer + eager VAE (混合模式) \|
14	-\| 实验/对比原生 npugraph_ex \| npugraph_ex — torch 2.9 上与 default 等价 (仍走 aot_autograd) \|
15		14
16	-> 完整 4-backend 对比见 `compilation-dev/references/backend-comparison.md`	15	+> 后端事实：本仓只有 default（Inductor）与 aclgraph（批量下发）两条路径；
		16	+> torchair_ge / npugraph_ex 在本仓未实现，不采用。
17		17
18	## 融合机会判断	18	## 融合机会判断
19		19
	@@ -74,3 +74,7 @@ Attention 自身不可融合——优化手段为 FA 量化和稀疏注意力。
74	\| MindIE-SD Pattern 命中 \| — \| 开启 CompilationConfig 开关 \| 标注开关名 \|	74	\| MindIE-SD Pattern 命中 \| — \| 开启 CompilationConfig 开关 \| 标注开关名 \|
75		75
76	优先级规则：P0 = MindIE-SD Pattern 命中 → P1 = 算子分类触发 → P2 = 通用融合/数据质量	76	优先级规则：P0 = MindIE-SD Pattern 命中 → P1 = 算子分类触发 → P2 = 通用融合/数据质量
		77	+
		78	+## 维护与更新
		79	+
		80	+当优化启发式或决策表变化时，按 dev-workflow 的复盘流程更新本文件。

M.agents/skills/performance-analysis/references/operator-catalog.md+4-0

	@@ -34,3 +34,7 @@ DiT（Transformer）和 VAE 通过 kernel 名称/类别分离：
34	\| GE error 4294967295 \| Conv2D (ResBlock) \| 910B \| VAE 部分不可用 \|	34	\| GE error 4294967295 \| Conv2D (ResBlock) \| 910B \| VAE 部分不可用 \|
35	\| `expandable_segments:True` 误判 OOM \| allocator \| 910B \| 移除此配置后恢复 \|	35	\| `expandable_segments:True` 误判 OOM \| allocator \| 910B \| 移除此配置后恢复 \|
36	\| triton vs triton-ascend 包名混淆 \| triton \| 全部 \| `import triton` 成功但 0 active drivers \|	36	\| triton vs triton-ascend 包名混淆 \| triton \| 全部 \| `import triton` 成功但 0 active drivers \|
		37	+
		38	+## 维护与更新
		39	+
		40	+当算子目录或已知问题变化时，按 dev-workflow 的复盘流程更新本文件。

D.agents/skills/performance-evaluation/SKILL.md+0-172

	@@ -1,172 +0,0 @@
1	----
2	-name: performance-evaluation
3	-description: 使用 msmodeling 评估模型推理性能，支持多硬件平台和多模态模型。
4	- 无 NPU 时在 CPU 上模拟各类 NPU/GPU 性能，完成初步评估；
5	- 有 NPU 时可通过 profiling-collection 采集真实数据，对接 performance-analysis 做深度分析。
6	- 当用户需要模拟或实测模型推理性能、对比不同硬件平台、建立性能基线时使用此 skill。
7	- 即使用户只提到"测一下这个模型的速度"而未说 msmodeling，也应触发。
8	- 用户必须明确指定模型规格、分辨率、设备类型和量化方式。评估过程中必须记录完整日志，评估结果按规范路径保存。
9	----
10	-
11	-# 性能评估
12	-
13	-使用msmodeling工具进行深度学习模型性能评估，提供算子级性能分析和跨平台对比能力。
14	-
15	-⚠️ 重要：每次评估都必须重新执行msmodeling工具，获取实时数据。禁止使用任何缓存或历史数据。
16	-
17	-## ⚠️ 执行前确认清单
18	-
19	-必须向用户确认的必需参数（无默认值）：
20	-
21	-\| 参数 \| 说明 \| 示例 \|
22	-\|------\|------\|------\|
23	-\| 模型规格 \| 模型具体规格版本 \| `T2V-14B`, `7B` \|
24	-\| 设备类型 \| 目标硬件设备名称 \| `ATLAS_800_A2_376T_64G` \|
25	-\| 分辨率 \| 输入图像/视频分辨率 \| `480x832`, `512x512` \|
26	-\| 量化方式 \| 模型量化策略 \| `DISABLED`, `W8A8_DYNAMIC` \|
27	-\| 视频帧数 \| 视频模型必须指定 \| `81`, `121` \|
28	-
29	-可选参数（有默认值）：
30	-
31	-- `--seq-len`: 64（文本长度）
32	-- `--dtype`: bfloat16
33	-- `--batch-size`: 1
34	-- `--world-size`: 1（卡数）
35	-- `--sample-step`: 28
36	-
37	-### 重要规则
38	-
39	-1. 禁止自动推断：不得猜测用户未明确指定的参数
40	-2. 必须确认：缺少必需参数时必须暂停询问用户
41	-3. 多卡需明确策略：world-size>1时必须明确并行策略
42	-4. 记录所有选择：用户指定的参数必须记录在日志中
43	-5. ⚠️ 每次评估必须重新执行msmodeling：禁止使用缓存数据或历史结果，每次都必须重新运行工具进行实时评估
44	-
45	-## 核心流程
46	-
47	-### Step 1: 环境准备
48	-
49	-msmodeling 下载、安装及硬件支持列表检测详见 references/setup-guide.md。
50	-简要流程：`git clone` → `pip install -e .` → 检查 `DeviceProfile.all_device_profiles.keys()` → 确定目标设备。
51	-
52	-⚠️ 每次评估前必须重新执行硬件检测，获取最新信息。
53	-
54	-### Step 2: 确认模型规格
55	-
56	-如果用户未明确模型规格，列出可用选项供选择。若模型未在 msmodeling 中支持，按照 msmodeling 使用方法进行适配。
57	-
58	-### Step 3: 确认硬件和参数
59	-
60	-获取用户明确指定的设备类型、分辨率、量化方式、视频帧数（视频模型）。
61	-
62	-未知硬件处理：详见 references/hardware-specs.md —— 常见硬件从公开资料预填充参考值，
63	-明确必需参数（矩阵BF16算力、显存容量、显存带宽、多卡互联带宽）。
64	-
65	-### Step 4: 确认并行策略（多卡时）
66	-
67	-如果 world-size > 1：
68	-
69	-```text
70	-检测到使用多卡配置（world-size=4）
71	-推荐并行策略：
72	-- Ulysses并行: 4 (ulysses-size=4)
73	-- 适用于: Wan2.2-T2V-14B
74	-- 通信模式: all-gather + all-reduce
75	-是否接受此配置？[Y/N]
76	-```
77	-
78	-推荐策略：
79	-
80	-- 多模态生成：ulysses-size = world-size
81	-- 支持CFG模型：cfg-parallel + ulysses-size = world-size/2
82	-
83	-### Step 5: 执行评估并记录
84	-
85	-⚠️ 关键：必须实际执行msmodeling工具进行实时评估，禁止使用任何缓存数据或历史结果。
86	-
87	-执行要求：
88	-
89	-1. 使用`python -m cli.inference.video_generate`或`python -m cli.inference.text_generate`实际执行
90	-2. 等待工具完成推理并输出性能数据
91	-3. 捕获实时输出并保存到日志文件
92	-4. 禁止使用之前的评估结果或缓存数据
93	-
94	-> 有 NPU 环境且需要深度分析时：评估后通过 profiling-collection skill 在真实设备上采集 profiling 数据，
95	-> 交给 performance-analysis 做三层递进分析。
96	-
97	-路径命名规范：
98	-
99	-```text
100	-results/<model>_<spec>_<device>_w<N>_u<N>_cfg<N>/
101	-```
102	-
103	-示例：
104	-
105	-- `wan2.2_t2v-14b_a2-376t-64g_d1/`（单卡）
106	-- `wan2.2_t2v-14b_a2-376t-64g_d4_u4/`（4卡Ulysses）
107	-- `wan2.2_t2v-14b_a2-376t-64g_d4_u2_cfg2/`（4卡+CFG）
108	-
109	-必须记录到日志（从实时执行输出捕获）：
110	-
111	-- 执行配置（模型、设备、分辨率、量化、并行策略等）
112	-- 算子分析（FlashAttention, MatMul, Vector, Comm）
113	-- 通信算子详情（all_gather, all_reduce, reduce_scatter）
114	-- 内存使用
115	-- 执行时间
116	-
117	-### Step 6: 生成报告
118	-
119	-生成 `evaluation_report.md`，包含：
120	-
121	-- 测试配置汇总
122	-- 性能指标表格
123	-- 算子分析
124	-- 通信分析（多卡）
125	-- 关键发现和优化建议
126	-- 附录：msmodeling的执行命令
127	-
128	-## 结果目录结构
129	-
130	-```text
131	-results/
132	-├── wan2.2_t2v-14b_a2-376t-64g_w1_u1_cfg0/
133	-│ ├── config.json # 配置信息
134	-│ ├── iteration_1.log # 执行日志
135	-│ ├── iteration_2.log
136	-│ └── summary.json # 汇总数据
137	-├── evaluation_report.md # 评估报告
138	-└── compare/ # 比较报告（多硬件时）
139	- └── comparison_*.md
140	-```
141	-
142	-## 算子分析说明
143	-
144	-评估输出包含以下算子类别：
145	-
146	-\| 算子 \| 说明 \|
147	-\|------\|------\|
148	-\| FlashAttention \| 注意力机制运算 \|
149	-\| MatMul \| 矩阵乘法（主要计算瓶颈） \|
150	-\| Vector \| 元素级运算（激活函数等） \|
151	-\| Comm \| 通信/内存操作开销 \|
152	-
153	-多卡场景：Comm包含通信算子（all_gather, all_reduce, reduce_scatter）
154	-
155	-## Reference Files
156	-
157	-- 📦 `references/setup-guide.md` — 加载时机: 首次使用 msmodeling，下载安装工具并分析硬件支持列表时
158	-- 📋 `references/evaluation-guide.md` — 加载时机: 需要完整评估流程细节、参数详解时
159	-- 🔧 `references/parameters.md` — 加载时机: 需要所有参数详细说明和约束条件时
160	-- 💻 `references/hardware-specs.md` — 加载时机: 遇到未知硬件需收集规格，或查询算力/带宽/互联参数时
161	-- ⏱️ `references/benchmark-guide.md` — 加载时机: 设置计时方法、判断 Triton launch 开销时
162	-- 📝 `references/examples.md` — 加载时机: 需要参考典型评估场景的完整命令行和配置示例时
163	-- ✅ `references/best-practices.md` — 加载时机: 评估操作规范、多卡配置、结果记录规范参考时
164	-
165	-## Bundled Scripts
166	-
167	-- `scripts/validate_results.py` — 验证评估结果是否符合 skill 规范（检查 config.json 字段完整性和路径命名）
168	-
169	-## 维护与更新
170	-
171	-当 msmodeling 版本更新、新硬件加入支持列表、评估参数规范变更或 Benchmark 方法改进时，
172	-按 dev-workflow 的复盘流程更新本 skill。

D.agents/skills/performance-evaluation/references/benchmark-guide.md+0-68

	@@ -1,68 +0,0 @@
1	-# Benchmark 规范
2	-
3	-## 计时方法
4	-
5	-测试耗时对比必须使用正确的 benchmark 方法：
6	-
7	-- 必须 warmup（至少 5 次），首次调用包含 JIT 编译
8	-- 必须 `torch.npu.synchronize()` 确保 NPU 操作完成
9	-- 多次迭代（≥10 次），取后 5 次平均
10	-- 断言 `compiled_time < original_time`（融合后应更快）
11	-
12	-```python
13	-def benchmark(func, args, warmup=5, repeat=10):
14	- for _ in range(warmup):
15	- func(*args)
16	- torch.npu.synchronize()
17	- times = []
18	- for _ in range(repeat):
19	- torch.npu.synchronize()
20	- start = time.perf_counter()
21	- func(*args)
22	- torch.npu.synchronize()
23	- end = time.perf_counter()
24	- times.append(end - start)
25	- return sum(times[-5:]) / 5
26	-```
27	-
28	-## MindIE-SD 编译预热
29	-
30	-`MindieSDBackend()` 编译时首次推理包含 JIT 编译耗时（默认最多 8 次尝试），
31	-后续 replay 跳过编译。Benchmark 时必须排除编译开销：
32	-
33	-- 执行 ≥ 5 步 warmup，确认不再触发 recompile
34	-- 前 N 步不计入计时，从第 N+1 步开始统计
35	-- 多卡场景各 rank 独立 warmup
36	-- 编译预热也触发 CANN Profiler JIT，warmup 步数需同时满足 Profiler 预热要求
37	-
38	-```python
39	-# 正确: warmup 不计时，timed 从稳定步开始
40	-for step in range(total_steps):
41	- output = model(...)
42	- torch.npu.synchronize()
43	- if step >= warmup_steps:
44	- timed_outputs.append(output)
45	-
46	-# 错误: warmup 未同步或计入计时
47	-for step in range(total_steps):
48	- start = time.perf_counter()
49	- output = model(...)
50	- end = time.perf_counter()
51	- times.append(end - start) # 包含编译耗时
52	-```
53	-
54	-## Triton kernel launch 开销
55	-
56	-Triton kernel 对逐元素小张量（如 32×8192）存在显著的 launch 开销（~0.2ms），而 torch 原生操作（如 `x * scale + y`）由 NPU 编译器直接融合（~0.03ms）。此场景下 Triton 路径可能慢 5-6 倍：
57	-
58	-- 规则：kernel 层测试仅验证正确性（`atol`），不要求耗时验证
59	-- 规则：pattern 集成测试的 `assertLess(compiled_time, original_time)` 对 sub-ms 级操作不适用，应移除或用更大张量（如 128×8192）重测
60	-- 判断标准：当原始操作耗时 < 1ms 时，一律不要求耗时断言
61	-
62	-## 多场景对照原则
63	-
64	-每次优化后必须与 baseline 对照，不得改变测试负载后宣称优化有效：
65	-
66	-- 同模型、同分辨率、同帧数、同精度、同 NPU 数
67	-- 仅改变优化变量（如开启/关闭量化、开启/关闭稀疏）
68	-- 差异 < 3% 视为噪声，不宣称有效

D.agents/skills/performance-evaluation/references/best-practices.md+0-306

	@@ -1,306 +0,0 @@
1	-# 评估专用最佳实践
2	-
3	-> 目录 · 1. 评估准备 · 2. 多卡配置 · 3. 日志和记录 · 4. 结果比较 · 5. 可复现性 · 6. 常见问题处理 · 7. 性能分析要求 · 8. 测试报告
4	-
5	-## 1. 评估准备
6	-
7	-### 明确所有必需参数
8	-
9	-在开始前获得用户对以下参数的明确确认：
10	-
11	-- ✅ 模型规格（如T2V-14B）
12	-- ✅ 设备类型（如ATLAS_800_A2_376T_64G）
13	-- ✅ 分辨率（如480×832）
14	-- ✅ 量化方式（如DISABLED）
15	-- ✅ 视频帧数（视频模型，如81）
16	-
17	-禁止：自动推断或猜测用户未明确指定的参数
18	-
19	-### 检查模型规格
20	-
21	-如果模型有多个规格，必须列出供用户选择：
22	-
23	-```text
24	-模型 Wan2.2 有多个规格可用：
25	-1. Wan2.2-T2V-14B (14B参数，文本到视频)
26	-2. Wan2.2-I2V-14B (14B参数，图像到视频)
27	-3. Wan2.2-T2V-1.3B (1.3B参数，轻量版)
28	-
29	-请选择具体规格（输入编号或名称）：
30	-```
31	-
32	-### 验证硬件支持
33	-
34	-确认目标设备在支持列表中，或获得完整的设备规格：
35	-
36	-```bash
37	-python -c "from tensor_cast.device import DeviceProfile; print(list(DeviceProfile.all_device_profiles.keys()))"
38	-```
39	-
40	-未知硬件处理：如果设备不在支持列表中，必须暂停询问规格：
41	-
42	-- 设备厂商
43	-- FP32算力（TFLOPS）
44	-- FP16算力（TFLOPS）
45	-- 显存容量（GB）
46	-- 显存带宽（GB/s）
47	-
48	-## 2. 多卡评估
49	-
50	-### 必须明确并行策略
51	-
52	-不要假设默认策略，根据模型类型推荐并确认：
53	-
54	-多模态生成模型：
55	-
56	-- 推荐：`ulysses-size = world-size`
57	-- 示例：4卡 → `--world-size 4 --ulysses-size 4`
58	-
59	-支持CFG的模型：
60	-
61	-- 推荐：`cfg-parallel` + `ulysses-size = world-size / 2`
62	-- 示例：4卡 → `--world-size 4 --cfg-parallel --ulysses-size 2`
63	-
64	-### 记录通信开销
65	-
66	-多卡时必须记录通信算子详情：
67	-
68	-```text
69	-Communication Operators:
70	-+-------------------+----------+----------+
71	-\| Op Name \| Time(ms) \| Calls \|
72	-+-------------------+----------+----------+
73	-\| all_gather \| 523.4 \| 28 \|
74	-\| all_reduce \| 312.8 \| 28 \|
75	-\| reduce_scatter \| 177.0 \| 14 \|
76	-+-------------------+----------+----------+
77	-Total communication time: 1013.2ms (7.0%)
78	-```
79	-
80	-## 3. 日志和记录
81	-
82	-### 路径命名规范
83	-
84	-严格遵循以下格式：
85	-
86	-```text
87	-results/<model>_<spec>_<device>_w<N>_u<N>_cfg<N>/
88	-```
89	-
90	-示例：
91	-
92	-- `wan2.2_t2v-14b_a2-376t-64g_w1_u1_cfg0/`（单卡）
93	-- `wan2.2_t2v-14b_a2-376t-64g_w4_u4_cfg0/`（4卡Ulysses）
94	-- `wan2.2_t2v-14b_a2-376t-64g_w4_u2_cfg1/`（4卡+CFG）
95	-
96	-### 完整记录配置
97	-
98	-所有用户指定的参数和使用的默认值都必须记录在config.json：
99	-
100	-```json
101	-{
102	- "user_specified": {
103	- "model_spec": "t2v-14b",
104	- "resolution": "480x832",
105	- "frame_num": 81,
106	- "quantization": "DISABLED"
107	- },
108	- "default_used": {
109	- "seq_len": 64,
110	- "dtype": "bfloat16",
111	- "world_size": 1
112	- }
113	-}
114	-```
115	-
116	-### 保存原始日志
117	-
118	-每次迭代的完整输出都要保存，不要只保存汇总：
119	-
120	-- `iteration_1.log`
121	-- `iteration_2.log`
122	-- `iteration_3.log`
123	-
124	-## 4. 结果比较
125	-
126	-### 同一场景比较
127	-
128	-确保比较的硬件使用完全相同的模型配置：
129	-
130	-- 相同模型规格
131	-- 相同分辨率
132	-- 相同量化方式
133	-- 相同并行策略
134	-
135	-### 生成比较报告
136	-
137	-使用专门的比较脚本生成对比报告：
138	-
139	-```bash
140	-python scripts/generate_comparison.py \
141	- --scenario "wan2.2-480p" \
142	- --baseline results/wan2.2_t2v-14b_a2-376t-64g_w1_u1_cfg0/ \
143	- --target results/wan2.2_t2v-14b_a3-752t-128g_w1_u1_cfg0/ \
144	- --output compare/comparison_wan2.2_480p_20240307.md
145	-```
146	-
147	-### 比较报告内容
148	-
149	-- 各硬件性能指标对比表
150	-- 算子级差异分析
151	-- 通信开销对比（多卡场景）
152	-- 性价比分析
153	-
154	-保存位置：`compare/comparison_<scenario>_<timestamp>.md`
155	-
156	-## 5. 可复现性
157	-
158	-### 记录完整环境
159	-
160	-在报告中包含：
161	-
162	-- 工具版本（msmodeling版本）
163	-- 驱动版本（CANN版本）
164	-- 设备规格（算力、内存、带宽）
165	-- 模型版本
166	-
167	-### 固定随机种子
168	-
169	-如可能，设置随机种子确保结果可复现：
170	-
171	-```bash
172	-export PYTHONHASHSEED=0
173	-export CUBLAS_WORKSPACE_CONFIG=:4096:8
174	-```
175	-
176	-### 多次迭代
177	-
178	-至少运行3次取平均，记录方差：
179	-
180	-\| 配置 \| 平均时间 \| 标准差 \| 最小值 \| 最大值 \|
181	-\|------\|----------\|--------\|--------\|--------\|
182	-\| 标准配置 \| 145.4s \| ±3.3s \| 142.2s \| 148.8s \|
183	-
184	-## 6. 常见问题处理
185	-
186	-### 用户未指定模型规格
187	-
188	-必须暂停并显示规格列表：
189	-
190	-```text
191	-模型 Wan2.2 有多个规格可用：
192	-1. Wan2.2-T2V-14B (14B参数，文本到视频，480p-720p)
193	-2. Wan2.2-I2V-14B (14B参数，图像到视频，480p-720p)
194	-3. Wan2.2-T2V-1.3B (1.3B参数，轻量版，480p)
195	-
196	-请选择具体规格（输入编号或名称）：
197	-```
198	-
199	-### 使用多卡但未指定并行策略
200	-
201	-根据模型类型推荐并确认：
202	-
203	-```text
204	-检测到使用多卡配置（world-size=4）
205	-
206	-推荐并行策略：
207	-- Ulysses并行: 4 (ulysses-size=4)
208	-- 适用于: Wan2.2-T2V-14B
209	-- 通信模式: all-gather + all-reduce
210	-
211	-是否接受此配置？
212	-[Y] 接受推荐配置
213	-[N] 自定义配置
214	-```
215	-
216	-### 视频模型未指定frame-num
217	-
218	-必须暂停并要求明确：
219	-
220	-```text
221	-检测到视频模型：Wan2.2-T2V-14B
222	-
223	-视频模型必须明确frame-num（视频总帧数）：
224	-常见选择：
225	-- 81帧（约3秒@27fps）
226	-- 121帧（约4.5秒@27fps）
227	-
228	-请输入frame-num: [81]
229	-```
230	-
231	-## 7. 性能分析要点
232	-
233	-### 算子级分析
234	-
235	-重点关注以下算子：
236	-
237	-- MatMul：通常是主要瓶颈（占比40-50%）
238	-- FlashAttention：次瓶颈（占比30-40%）
239	-- Comm（多卡时）：通信开销（占比5-15%）
240	-
241	-### 内存分析
242	-
243	-- 峰值内存不应超过设备容量的80%
244	-- 内存带宽利用率60-70%为正常范围
245	-- INT8量化可减少40-50%内存占用
246	-
247	-### 通信分析（多卡）
248	-
249	-- all_reduce通常占通信时间的主要部分
250	-- 通信开销应控制在总时间的15%以内
251	-- 如果通信占比过高，考虑优化并行策略
252	-
253	-## 8. 报告生成
254	-
255	-### 评估报告结构
256	-
257	-```markdown
258	-# 性能评估报告
259	-
260	-## 测试配置
261	-- 模型配置
262	-- 硬件配置
263	-- 运行配置
264	-
265	-## 性能汇总
266	-- 总体性能表
267	-- 详细数据表
268	-
269	-## 算子分析
270	-- 算子耗时表
271	-- 占比分析
272	-
273	-## 通信分析（多卡）
274	-- 通信算子详情
275	-
276	-## 内存分析
277	-- 峰值内存
278	-- 带宽利用率
279	-
280	-## 关键发现
281	-- 性能瓶颈
282	-- 优化建议
283	-
284	-## 文件清单
285	-- 结果文件列表
286	-```
287	-
288	-### 比较报告结构
289	-
290	-```markdown
291	-# 硬件性能比较报告
292	-
293	-## 测试配置
294	-- 各硬件配置对比
295	-
296	-## 性能对比
297	-- 总体性能对比表
298	-- 算子级对比表
299	-
300	-## 通信开销对比（多卡）
301	-- 通信算子对比
302	-
303	-## 结论与分析
304	-- 加速比分析
305	-- 性价比分析
306	-```

D.agents/skills/performance-evaluation/references/evaluation-guide.md+0-383

	@@ -1,383 +0,0 @@
1	-# 详细评估指南
2	-
3	-> 目录 · 第一步: 下载msmodeling+分析硬件 · 第二步: 准备模型确认规格 · 第三步: 确认硬件和参数 · 第四步: 未知硬件处理 · 第五步: 执行评估 · 第六步: 日志记录和保存 · 第七步: 生成报告 · 第八步: 同一场景不同硬件比较
4	-
5	-完整的性能评估流程指南。
6	-
7	-## 使用流程
8	-
9	-### 第一步：下载 msmodeling 并分析硬件支持
10	-
11	-⚠️ 这是评估的第一步，必须在每次评估时执行。
12	-
13	-#### 1.1 下载和安装 msmodeling
14	-
15	-```bash
16	-# 下载 msmodeling 工具
17	-git clone https://gitcode.com/Ascend/msmodeling.git
18	-cd msmodeling
19	-
20	-# 安装依赖
21	-pip install -r requirements.txt
22	-
23	-# 安装工具
24	-pip install -e .
25	-```
26	-
27	-#### 1.2 验证安装
28	-
29	-```bash
30	-# 验证安装是否成功
31	-python -c "import tensor_cast; print('msmodeling 安装成功')"
32	-```
33	-
34	-#### 1.3 通过 msmodeling 获取支持的硬件列表
35	-
36	-执行命令：
37	-
38	-```bash
39	-python -c "from tensor_cast.device import DeviceProfile; print(list(DeviceProfile.all_device_profiles.keys()))"
40	-```
41	-
42	-预期输出示例：
43	-
44	-```text
45	-['TEST_DEVICE', 'ATLAS_800_A2_376T_64G', 'ATLAS_800_A2_313T_64G', 'ATLAS_800_A3_752T_128G_DIE']
46	-```
47	-
48	-重要：
49	-
50	-- 此列表是实时获取的，必须在每次评估前重新执行
51	-- 禁止使用缓存的硬件列表
52	-- 即使之前执行过，也必须重新执行此命令
53	-
54	-#### 1.4 确定目标设备
55	-
56	-询问用户要评估的硬件，并验证是否在 msmodeling 支持列表中：
57	-
58	-```text
59	-当前环境通过 msmodeling 检测到的可用硬件：
60	-1. ATLAS_800_A2_376T_64G (华为昇腾A2, 376 TFLOPS BF16, 64GB HBM)
61	-2. ATLAS_800_A3_752T_128G_DIE (华为昇腾A3, 752 TFLOPS BF16, 128GB HBM)
62	-3. TEST_DEVICE (测试设备)
63	-
64	-请选择要评估的硬件（输入编号或设备名）：
65	-```
66	-
67	-详细步骤参见[安装和初始分析](setup-guide.md)。
68	-
69	-### 第二步：准备模型并确认规格
70	-
71	-步骤1：获取模型列表
72	-
73	-如果用户只提供了模型名称，需要查询可用规格：
74	-
75	-```text
76	-模型 Wan2.2 有多个规格可用：
77	-1. Wan2.2-T2V-14B (14B参数，文本到视频，480p-720p)
78	-2. Wan2.2-I2V-14B (14B参数，图像到视频，480p-720p)
79	-3. Wan2.2-T2V-1.3B (1.3B参数，轻量版，480p)
80	-
81	-请选择具体规格（输入编号或名称）： 1
82	-已选择: Wan2.2-T2V-14B
83	-```
84	-
85	-步骤2：下载模型
86	-
87	-```bash
88	-# 使用Hugging Face模型ID
89	-python -m cli.inference.text_generate meta-llama/Llama-2-7b-hf --device TEST_DEVICE --num-queries 1 --query-length 64
90	-
91	-# 使用本地模型路径
92	-python -m cli.inference.video_generate /path/to/local/model --device TEST_DEVICE --batch-size 1 --seq-len 64 --height 480 --width 832
93	-```
94	-
95	-### 第三步：确认硬件和参数
96	-
97	-获取用户明确指定的评估参数：
98	-
99	-- 设备类型（如 ATLAS_800_A2_376T_64G）
100	-- 分辨率（如 480x832）
101	-- 量化方式（如 DISABLED）
102	-- 视频帧数（视频模型，如 81）
103	-
104	-设备验证流程：
105	-
106	-1. 询问用户目标硬件设备名称
107	-2. 验证该设备是否在 Step 1 中获取的 msmodeling 支持列表中
108	-3. 如果在列表中：直接使用该设备
109	-4. 如果不在列表中：进入未知硬件处理流程
110	-
111	-未知硬件处理：如果设备不在支持列表中，必须暂停收集硬件规格。详见[硬件规格说明](hardware-specs.md)。
112	-
113	-### 第四步：配置硬件
114	-
115	-如果硬件已在支持列表中：直接使用 `--device <设备名>`
116	-
117	-如果硬件不在支持列表中：
118	-
119	-⚠️ 必须按[硬件规格说明](hardware-specs.md)收集规格信息。
120	-
121	-收集流程：
122	-
123	-1. 尝试预填充参考值：对于常见硬件（NVIDIA A100/H100, AMD MI300等），从公开资料获取参考规格
124	-2. 用户确认或修改：显示参考值供用户核对
125	-3. 明确必需参数：
126	- - ✅ 矩阵运算BF16算力（必填）→ FP16默认相同，INT8/FP8自动×2
127	- - ⚪ 向量运算BF16算力（可选）→ 影响FA评估准确性
128	- - ✅ 显存容量（必填）
129	- - ✅ 显存带宽（必填）
130	- - ✅ 互联带宽（多卡时必填）
131	-
132	-示例交互：
133	-
134	-```text
135	-检测到未支持的硬件: NVIDIA_A100_40GB
136	-
137	-正在查询公开资料获取参考规格...
138	-✓ 找到参考信息（来源：NVIDIA官方规格表）
139	-
140	-参考规格（请核对并修改）：
141	-1. 矩阵运算BF16算力: 312 TFLOPS ← 必填
142	-2. 向量运算BF16算力: 19.5 TFLOPS ← 可选（影响FA评估）
143	-3. 显存容量: 40 GB ← 必填
144	-4. 显存带宽: 1555 GB/s ← 必填
145	-5. 内部互联带宽: 600 GB/s (NVLink) ← 多卡时必填
146	-
147	-请确认或修改以上数值：
148	-```
149	-
150	-创建自定义设备配置：
151	-
152	-```python
153	-from tensor_cast.device import DeviceProfile, CommGrid, InterconnectTopology, StaticCost
154	-import torch
155	-
156	-MY_DEVICE = DeviceProfile(
157	- name="用户指定的设备名",
158	- vendor="用户指定的厂商",
159	- mma_ops={
160	- torch.bfloat16: xx.x * 1e12, # BF16矩阵算力（用户提供，必填）
161	- torch.float16: xx.x * 1e12, # FP16: 同BF16（默认）
162	- torch.int8: xx.x * 2e12, # INT8: BF16×2（自动推断）
163	- },
164	- gp_ops={
165	- torch.bfloat16: xx.x * 1e12, # BF16向量算力（用户提供，可选）
166	- torch.float32: xx.x * 0.5e12, # FP32: BF16÷2（自动推断）
167	- },
168	- memory_size_bytes=xx * (1024**3), # 显存容量（GB，必填）
169	- memory_bandwidth_bytes_ps=xxx * (1024**3), # 显存带宽（GB/s，必填）
170	- internal_interconnect_bw=xxx * (1024**3), # 内部互联带宽（卡数<8时必填）
171	- cross_node_interconnect_bw=xxx * (1024**3), # 机间互联带宽（卡数≥8时必填）
172	- compute_efficiency=0.75,
173	- memory_efficiency=0.65,
174	- comm_grid=CommGrid(...),
175	- static_cost=StaticCost(),
176	-)
177	-```
178	-
179	-### 第五步：执行评估
180	-
181	-#### 评估前确认检查清单
182	-
183	-执行前必须确认：
184	-
185	-- [ ] Step 1 已完成：已下载并安装 msmodeling
186	-- [ ] Step 1 已完成：已执行查询获取支持的硬件列表（实时）
187	-- [ ] Step 1 已完成：已从 msmodeling 支持列表中确定目标设备
188	-- [ ] 模型规格已明确指定（无默认值）
189	-- [ ] 设备类型已明确指定（支持列表中或已收集规格）
190	-- [ ] 未知硬件已收集规格：矩阵BF16算力、显存、带宽
191	-- [ ] 多卡时已收集：互联带宽（内部/机间）
192	-- [ ] 分辨率已明确指定（多模态模型，无默认值）
193	-- [ ] 量化方式已明确指定（无默认值）
194	-- [ ] 视频模型frame-num已明确指定（无默认值）
195	-- [ ] 多卡时并行策略已明确（world-size > 1）
196	-- [ ] seq_len使用默认值64或用户明确指定
197	-- [ ] ⚠️ 已重新执行msmodeling获取实时数据（禁止使用缓存）
198	-- [ ] 最终配置参数已记录到日志
199	-
200	-#### 文本生成评估 (LLM)
201	-
202	-⚠️ 关键：必须实际执行以下命令，获取实时评估数据。禁止使用缓存。
203	-
204	-基础命令：
205	-
206	-```bash
207	-python -m cli.inference.text_generate \
208	- <model_id> \
209	- --device <device_name> \
210	- --num-queries 1 \
211	- --query-length 64 \
212	- [--context-length 0] \
213	- [--decode] \
214	- [--dtype bfloat16] \
215	- [--tp-size 1] \
216	- [--dp-size 1] \
217	- [--ep-size 1]
218	-```
219	-
220	-注意：执行后等待工具完成推理，捕获实时输出并保存到日志文件。
221	-
222	-#### 视频生成评估 (Diffusion)
223	-
224	-⚠️ 关键：必须实际执行以下命令，获取实时评估数据。禁止使用缓存。
225	-
226	-基础命令：
227	-
228	-```bash
229	-python -m cli.inference.video_generate \
230	- <model_path> \
231	- --device <device_name> \
232	- --batch-size 1 \
233	- --seq-len 64 \
234	- --height <必须指定> \
235	- --width <必须指定> \
236	- --frame-num <必须指定> \
237	- [--sample-step 28] \
238	- [--dtype bfloat16] \
239	- [--world-size 1] \
240	- [--ulysses-size 1] \
241	- [--cfg-parallel]
242	-```
243	-
244	-注意：执行后等待工具完成推理，捕获实时输出并保存到日志文件。
245	-
246	-### 第六步：日志记录与结果保存
247	-
248	-#### 路径命名规范（必须遵守）
249	-
250	-结果目录命名格式：
251	-
252	-```text
253	-results/<model_name>_<model_spec>_<device_spec>_w<world_size>_u<ulysses_size>_cfg<cfg_flag>/
254	-```
255	-
256	-各字段说明：
257	-
258	-- `model_name`: 模型名称（如wan2.2, llama）
259	-- `model_spec`: 模型规格（如14b, 7b, t2v-14b）
260	-- `device_spec`: 设备规格（从device名称提取，如a2-376t-64g）
261	-- `world_size`: 卡数
262	-- `ulysses_size`: Ulysses并行大小
263	-- `cfg_flag`: 是否启用CFG（0或1）
264	-
265	-命名示例：
266	-
267	-```text
268	-# 单卡示例
269	-wan2.2_t2v-14b_a2-376t-64g_w1_u1_cfg0/
270	-
271	-# 多卡示例（4卡，Ulysses并行）
272	-wan2.2_t2v-14b_a2-376t-64g_w4_u4_cfg0/
273	-
274	-# 多卡+CFG示例（4卡，CFG并行+Ulysses）
275	-wan2.2_t2v-14b_a2-376t-64g_w4_u2_cfg1/
276	-```
277	-
278	-#### 日志记录规范
279	-
280	-每次评估必须记录以下内容到日志文件：
281	-
282	-1. 执行配置信息（必须记录）
283	-
284	- ```text
285	- Evaluation Configuration: [配置名]
286	- Model: [模型名]-[规格]
287	- Device: [设备名]
288	- Device Spec: [设备规格]
289	- Resolution: [高度]x[宽度]
290	- Frames: [帧数] (视频模型)
291	- Sample Steps: [步数]
292	- Sequence Length: [seq_len]
293	- Dtype: [数据类型]
294	- Quantization: [量化方式]
295	- World Size: [卡数]
296	- Ulysses Size: [Ulysses并行大小]
297	- CFG Parallel: [是否CFG并行]
298	- Parallel Strategy: [并行策略描述]
299	- Iterations: [迭代次数]
300	- Timestamp: [ISO时间戳]
301	- ```
302	-
303	-2. 算子分析表（必须记录）
304	-
305	- ```text
306	- +---------------+----------+----------+
307	- \| Op Type \| Time(ms) \| Percent \|
308	- +---------------+----------+----------+
309	- \| FlashAttention\| 5234.5 \| 36.0% \|
310	- \| MatMul \| 6128.3 \| 42.2% \|
311	- \| Vector \| 2156.2 \| 14.8% \|
312	- \| Comm \| 1013.2 \| 7.0% \|
313	- +---------------+----------+----------+
314	- ```
315	-
316	-3. 通信算子详情（多卡时必须记录）
317	-
318	- ```text
319	- Communication Operators:
320	- +-------------------+----------+----------+
321	- \| Op Name \| Time(ms) \| Calls \|
322	- +-------------------+----------+----------+
323	- \| all_gather \| 523.4 \| 28 \|
324	- \| all_reduce \| 312.8 \| 28 \|
325	- \| reduce_scatter \| 177.0 \| 14 \|
326	- +-------------------+----------+----------+
327	- Total communication time: 1013.2ms (7.0%)
328	- ```
329	-
330	-4. 最终结果汇总（必须记录）
331	-
332	- ```text
333	- Summary:
334	- - Total execution time: [时间]s
335	- - Average per-step time: [时间]s
336	- - Peak memory: [内存]GB
337	- - Operator breakdown:
338	- * FlashAttention: [耗时]ms ([占比]%)
339	- * MatMul: [耗时]ms ([占比]%)
340	- * Vector: [耗时]ms ([占比]%)
341	- * Comm: [耗时]ms ([占比]%)
342	- - Communication breakdown:
343	- * all_gather: [耗时]ms ([占比]%)
344	- * all_reduce: [耗时]ms ([占比]%)
345	- * reduce_scatter: [耗时]ms ([占比]%)
346	- ```
347	-
348	-### 第七步：分析结果
349	-
350	-工具输出包含：
351	-
352	-1. 性能汇总：单次前向时间、总推理时间、吞吐量
353	-2. 算子分析：FA(Flash Attention)、MM(MatMul)、Vector、Comm各算子耗时和占比
354	-3. 通信分析（多卡时）：all_gather、all_reduce、reduce_scatter等通信算子详情
355	-4. 内存分析：显存使用情况、峰值内存
356	-5. 带宽分析：内存带宽利用率
357	-6. Chrome Trace：可视化时间线（当使用 `--chrome-trace` 时）
358	-
359	-### 第八步：同一场景不同硬件比较
360	-
361	-当需要在同一场景下比较不同硬件性能时：
362	-
363	-1. 在各自硬件上执行评估（按上述流程）
364	-2. 收集各硬件的性能数据
365	-3. 生成比较报告：
366	-
367	-```bash
368	-# 生成比较报告
369	-python scripts/generate_comparison.py \
370	- --results results/wan2.2_t2v-14b_a2-376t-64g_w1_u1_cfg0/ \
371	- --results results/wan2.2_t2v-14b_a3-752t-128g_w1_u1_cfg0/ \
372	- --output compare/comparison_wan2.2_480p_$(date +%Y%m%d_%H%M%S).md
373	-```
374	-
375	-比较报告内容：
376	-
377	-- 各硬件性能指标对比表
378	-- 加速比分析
379	-- 算子级差异分析
380	-- 通信开销对比（多卡场景）
381	-- 性价比分析
382	-
383	-比较报告保存位置：`compare/comparison_<scenario>_<timestamp>.md`

D.agents/skills/performance-evaluation/references/examples.md+0-438

	@@ -1,438 +0,0 @@
1	-# 示例场景
2	-
3	-> 目录 · 场景1: 单卡视频模型评估 · 场景2: 多卡视频模型评估 · 场景3: 多卡+CFG视频模型评估 · 场景4: 同一场景不同硬件比较 · 场景5: 不同量化方式对比 · 场景6: 不同序列长度性能测试 · 日志文件示例 · 性能对比 · 总结
4	-
5	-## 场景1：单卡视频模型评估（Wan2.2 on A2）
6	-
7	-步骤1：确认模型规格（T2V-14B）
8	-
9	-```text
10	-模型 Wan2.2 有多个规格可用：
11	-1. Wan2.2-T2V-14B (14B参数，文本到视频)
12	-2. Wan2.2-I2V-14B (14B参数，图像到视频)
13	-3. Wan2.2-T2V-1.3B (1.3B参数，轻量版)
14	-
15	-请选择具体规格（输入编号或名称）： 1
16	-已选择: Wan2.2-T2V-14B
17	-```
18	-
19	-步骤2：确认分辨率（480×832）和帧数（81）
20	-
21	-```text
22	-检测到视频模型：Wan2.2-T2V-14B
23	-
24	-视频模型必须明确frame-num（视频总帧数）：
25	-常见选择：
26	-- 81帧（约5秒@16fps）
27	-- 121帧（约5秒@24fps）
28	-
29	-请输入frame-num: [81]
30	-```
31	-
32	-步骤3：确认量化方式（DISABLED）
33	-
34	-```text
35	-请选择量化方式：
36	-1. DISABLED (无量化，BF16)
37	-2. W8A8_DYNAMIC (动态INT8)
38	-3. FP8
39	-
40	-请输入选项: 1
41	-```
42	-
43	-步骤4：执行评估
44	-
45	-```bash
46	-python -m cli.inference.video_generate \
47	- Wan-AI/Wan2.1-T2V-14B \
48	- --device ATLAS_800_A2_376T_64G \
49	- --batch-size 1 \
50	- --seq-len 64 \
51	- --height 480 \
52	- --width 832 \
53	- --frame-num 81 \
54	- --sample-step 28 \
55	- --dtype bfloat16 \
56	- --quantize-linear-action DISABLED \
57	- --world-size 1 \
58	- --ulysses-size 1
59	-```
60	-
61	-步骤5：确认结果路径
62	-
63	-结果保存路径：`results/wan2.2_t2v-14b_a2-376t-64g_d1/`
64	-
65	----
66	-
67	-## 场景2：多卡视频模型评估（Wan2.2 on A2，4卡）
68	-
69	-步骤1：确认并行策略（Ulysses=4）
70	-
71	-```text
72	-检测到使用多卡配置（world-size=4）
73	-
74	-推荐并行策略：
75	-- Ulysses并行: 4 (ulysses-size=4)
76	-- 适用于: Wan2.2-T2V-14B
77	-- 通信模式: all-gather + all-reduce
78	-
79	-是否接受此配置？
80	-[Y] 接受推荐配置
81	-[N] 自定义配置
82	-```
83	-
84	-步骤2：确认是否使用CFG（否）
85	-
86	-```text
87	-Wan2.2-T2V-14B 不支持CFG，使用标准Ulysses并行策略。
88	-```
89	-
90	-步骤3：执行评估
91	-
92	-```bash
93	-python -m cli.inference.video_generate \
94	- Wan-AI/Wan2.1-T2V-14B \
95	- --device ATLAS_800_A2_376T_64G \
96	- --batch-size 1 \
97	- --seq-len 64 \
98	- --height 480 \
99	- --width 832 \
100	- --frame-num 81 \
101	- --sample-step 28 \
102	- --dtype bfloat16 \
103	- --quantize-linear-action DISABLED \
104	- --world-size 4 \
105	- --ulysses-size 4
106	-```
107	-
108	-步骤4：确认结果路径
109	-
110	-结果保存路径：`results/wan2.2_t2v-14b_a2-376t-64g_w4_u4_cfg0/`
111	-
112	----
113	-
114	-## 场景3：多卡+CFG视频模型评估（4卡，支持CFG）
115	-
116	-步骤1：确认CFG并行策略（CFG=2, Ulysses=2）
117	-
118	-```text
119	-检测到使用多卡配置（world-size=4）
120	-模型支持CFG: 是
121	-
122	-推荐并行策略：
123	-- CFG并行: 启用
124	-- Ulysses并行: 2 (ulysses-size=2)
125	-- 通信模式: all-gather + all-reduce + broadcast
126	-
127	-是否接受此配置？
128	-[Y] 接受推荐配置
129	-[N] 自定义配置
130	-```
131	-
132	-步骤2：执行评估
133	-
134	-```bash
135	-python -m cli.inference.video_generate \
136	- Wan-AI/Wan2.1-T2V-14B \
137	- --device ATLAS_800_A2_376T_64G \
138	- --batch-size 1 \
139	- --seq-len 64 \
140	- --height 480 \
141	- --width 832 \
142	- --frame-num 81 \
143	- --sample-step 28 \
144	- --dtype bfloat16 \
145	- --quantize-linear-action DISABLED \
146	- --world-size 4 \
147	- --cfg-parallel \
148	- --ulysses-size 2
149	-```
150	-
151	-步骤3：确认结果路径
152	-
153	-结果保存路径：`results/wan2.2_t2v-14b_a2-376t-64g_w4_u2_cfg1/`
154	-
155	----
156	-
157	-## 场景4：同一场景不同硬件比较
158	-
159	-步骤1：在A2上执行
160	-
161	-```bash
162	-python -m cli.inference.video_generate \
163	- Wan-AI/Wan2.1-T2V-14B \
164	- --device ATLAS_800_A2_376T_64G \
165	- --batch-size 1 \
166	- --seq-len 64 \
167	- --height 480 \
168	- --width 832 \
169	- --frame-num 81 \
170	- --sample-step 28 \
171	- --dtype bfloat16 \
172	- --quantize-linear-action DISABLED \
173	- --world-size 1 \
174	- --ulysses-size 1
175	-```
176	-
177	-结果路径：`results/wan2.2_t2v-14b_a2-376t-64g_w1_u1_cfg0/`
178	-
179	-步骤2：在A3上执行（相同配置）
180	-
181	-```bash
182	-python -m cli.inference.video_generate \
183	- Wan-AI/Wan2.1-T2V-14B \
184	- --device ATLAS_800_A3_752T_128G_DIE \
185	- --batch-size 1 \
186	- --seq-len 64 \
187	- --height 480 \
188	- --width 832 \
189	- --frame-num 81 \
190	- --sample-step 28 \
191	- --dtype bfloat16 \
192	- --quantize-linear-action DISABLED \
193	- --world-size 1 \
194	- --ulysses-size 1
195	-```
196	-
197	-结果路径：`results/wan2.2_t2v-14b_a3-752t-128g_w1_u1_cfg0/`
198	-
199	-步骤3：生成比较报告
200	-
201	-```bash
202	-python scripts/generate_comparison.py \
203	- --scenario "wan2.2-480p-standard" \
204	- --baseline results/wan2.2_t2v-14b_a2-376t-64g_w1_u1_cfg0/ \
205	- --target results/wan2.2_t2v-14b_a3-752t-128g_w1_u1_cfg0/ \
206	- --output compare/comparison_wan2.2_480p_20240307.md
207	-```
208	-
209	-步骤4：查看比较报告
210	-
211	-比较报告包含：
212	-
213	-- 各硬件性能指标对比表
214	-- 加速比分析
215	-- 算子级差异分析
216	-- 通信开销对比（多卡场景）
217	-- 性价比分析
218	-
219	----
220	-
221	-## 场景5：量化方式对比
222	-
223	-步骤1：FP16基准
224	-
225	-```bash
226	-python -m cli.inference.video_generate \
227	- model \
228	- --device TEST_DEVICE \
229	- --batch-size 1 \
230	- --seq-len 64 \
231	- --height 480 \
232	- --width 832 \
233	- --frame-num 81 \
234	- --sample-step 28 \
235	- --dtype bfloat16 \
236	- --quantize-linear-action DISABLED
237	-```
238	-
239	-步骤2：W8A8动态量化
240	-
241	-```bash
242	-python -m cli.inference.video_generate \
243	- model \
244	- --device TEST_DEVICE \
245	- --batch-size 1 \
246	- --seq-len 64 \
247	- --height 480 \
248	- --width 832 \
249	- --frame-num 81 \
250	- --sample-step 28 \
251	- --dtype bfloat16 \
252	- --quantize-linear-action W8A8_DYNAMIC
253	-```
254	-
255	-步骤3：W8A8静态量化
256	-
257	-```bash
258	-python -m cli.inference.video_generate \
259	- model \
260	- --device TEST_DEVICE \
261	- --batch-size 1 \
262	- --seq-len 64 \
263	- --height 480 \
264	- --width 832 \
265	- --frame-num 81 \
266	- --sample-step 28 \
267	- --dtype bfloat16 \
268	- --quantize-linear-action W8A8_STATIC
269	-```
270	-
271	-步骤4：FP8量化
272	-
273	-```bash
274	-python -m cli.inference.video_generate \
275	- model \
276	- --device TEST_DEVICE \
277	- --batch-size 1 \
278	- --seq-len 64 \
279	- --height 480 \
280	- --width 832 \
281	- --frame-num 81 \
282	- --sample-step 28 \
283	- --dtype bfloat16 \
284	- --quantize-linear-action FP8
285	-```
286	-
287	----
288	-
289	-## 场景6：不同序列长度性能测试（LLM）
290	-
291	-```bash
292	-for len in 128 512 1024 2048; do
293	- python -m cli.inference.text_generate \
294	- meta-llama/Llama-2-7b-hf \
295	- --device TEST_DEVICE \
296	- --num-queries 1 \
297	- --query-length $len \
298	- --decode
299	-done
300	-```
301	-
302	----
303	-
304	-## 日志文件示例
305	-
306	-### config.json
307	-
308	-```json
309	-{
310	- "config_name": "wan2.2_t2v-14b_a2-376t-64g_w1_u1_cfg0",
311	- "model_name": "wan2.2",
312	- "model_spec": "t2v-14b",
313	- "model_params": "14B",
314	- "device": "ATLAS_800_A2_376T_64G",
315	- "device_spec": "a2-376t-64g",
316	- "model_path": "./models/Wan2.1-T2V-14B",
317	- "height": 480,
318	- "width": 832,
319	- "frame_num": 81,
320	- "sample_step": 28,
321	- "seq_len": 64,
322	- "dtype": "bfloat16",
323	- "quantization": "DISABLED",
324	- "world_size": 1,
325	- "ulysses_size": 1,
326	- "cfg_parallel": false,
327	- "parallel_strategy": "single-card",
328	- "iterations": 3,
329	- "timestamp": "2024-03-07T14:30:00",
330	- "user_specified": {
331	- "model_spec": "t2v-14b",
332	- "resolution": "480x832",
333	- "frame_num": 81,
334	- "device": "ATLAS_800_A2_376T_64G",
335	- "quantization": "DISABLED"
336	- },
337	- "default_used": {
338	- "seq_len": 64,
339	- "dtype": "bfloat16",
340	- "batch_size": 1,
341	- "world_size": 1,
342	- "ulysses_size": 1,
343	- "sample_step": 28
344	- }
345	-}
346	-```
347	-
348	-### iteration_1.log
349	-
350	-```text
351	-Evaluation Configuration: wan2.2_t2v-14b_a2-376t-64g_w1_u1_cfg0
352	-Model: wan2.2-t2v-14b
353	-Device: ATLAS_800_A2_376T_64G
354	-Device Spec: a2-376t-64g
355	-Resolution: 480x832
356	-Frames: 81
357	-Sample Steps: 28
358	-Sequence Length: 64
359	-Dtype: bfloat16
360	-Quantization: DISABLED
361	-World Size: 1
362	-Ulysses Size: 1
363	-CFG Parallel: false
364	-Parallel Strategy: single-card
365	-Iterations: 3
366	-Timestamp: 2024-03-07T14:30:00
367	-
368	-Model compilation and execution time: 145.32s
369	-
370	-+---------------+----------+----------+
371	-\| Op Type \| Time(ms) \| Percent \|
372	-+---------------+----------+----------+
373	-\| FlashAttention\| 5234.5 \| 36.0% \|
374	-\| MatMul \| 6128.3 \| 42.2% \|
375	-\| Vector \| 2156.2 \| 14.8% \|
376	-\| Comm \| 1013.2 \| 7.0% \|
377	-+---------------+----------+----------+
378	-
379	-Communication Operators:
380	-+-------------------+----------+----------+
381	-\| Op Name \| Time(ms) \| Calls \|
382	-+-------------------+----------+----------+
383	-\| all_gather \| N/A \| N/A \|
384	-\| all_reduce \| N/A \| N/A \|
385	-\| reduce_scatter \| N/A \| N/A \|
386	-+-------------------+----------+----------+
387	-Total communication time: 0ms (0.0%)
388	-Note: Single-card mode, no communication operators
389	-
390	-Peak memory: 38.5 GB
391	-Memory bandwidth utilization: 62.3%
392	-
393	-Per-step average time: 5.19s
394	-
395	-Summary:
396	-- Total execution time: 145.32s
397	-- Average per-step time: 5.19s
398	-- Peak memory: 38.5GB
399	-- Operator breakdown:
400	- * FlashAttention: 5234.5ms (36.0%)
401	- * MatMul: 6128.3ms (42.2%)
402	- * Vector: 2156.2ms (14.8%)
403	- * Comm: 1013.2ms (7.0%)
404	-- Communication breakdown:
405	- * all_gather: N/A (single-card)
406	- * all_reduce: N/A (single-card)
407	- * reduce_scatter: N/A (single-card)
408	-```
409	-
410	-### 比较报告示例
411	-
412	-```markdown
413	-# 硬件性能比较报告
414	-
415	-场景: wan2.2-480p-standard
416	-比较硬件: Atlas A2 vs Atlas A3
417	-时间: 2024-03-07
418	-
419	-## 性能对比
420	-
421	-\| 指标 \| Atlas A2 \| Atlas A3 \| 加速比 \|
422	-\|------\|----------\|----------\|--------\|
423	-\| 总推理时间 \| 145.4s \| 98.2s \| 1.48× \|
424	-\| 单步时间 \| 5.19s \| 3.51s \| 1.48× \|
425	-\| 峰值内存 \| 38.5GB \| 38.2GB \| 0.99× \|
426	-
427	-## 算子级对比
428	-
429	-\| 算子 \| A2耗时 \| A3耗时 \| 加速比 \|
430	-\|------\|--------\|--------\|--------\|
431	-\| FlashAttention \| 5249ms \| 3542ms \| 1.48× \|
432	-\| MatMul \| 6138ms \| 4123ms \| 1.49× \|
433	-\| Comm \| 1013ms \| 892ms \| 1.14× \|
434	-
435	-## 结论
436	-
437	-Atlas A3相比A2在Wan2.2视频生成场景下性能提升约48%...
438	-```

D.agents/skills/performance-evaluation/references/hardware-specs.md+0-314

	@@ -1,314 +0,0 @@
1	-# 硬件规格说明
2	-
3	-> 目录 · 硬件规格收集流程 · 矩阵算力(BF16 MMA) · 向量算力(BF16 GP) · 显存容量 · 多卡互联带宽 · 硬件规格详细说明 · 常见设备配置示例 · 快速参考表
4	-
5	-## 硬件规格收集流程
6	-
7	-### 1. 已知硬件（支持列表中）
8	-
9	-如果设备在支持列表中，直接使用：`--device <设备名>`
10	-
11	-当前支持的设备：
12	-
13	-- `ATLAS_800_A2_376T_64G` - 华为Atlas 800 A2 (376 TFLOPS BF16, 64GB HBM2e)
14	-- `ATLAS_800_A2_313T_64G` - 华为Atlas 800 A2 (313 TFLOPS BF16, 64GB)
15	-- `ATLAS_800_A2_280T_64G` - 华为Atlas 800 A2 (280 TFLOPS BF16, 64GB)
16	-- `ATLAS_800_A3_752T_128G_DIE` - 华为Atlas 800 A3 (752 TFLOPS BF16, 128GB)
17	-- `ATLAS_800_A3_560T_128G_DIE` - 华为Atlas 800 A3 (560 TFLOPS BF16, 128GB)
18	-
19	-### 2. 未知硬件（不在支持列表中）
20	-
21	-如果设备不在支持列表中，必须收集以下规格信息。
22	-
23	-#### 硬件规格查询和预填充
24	-
25	-步骤1：尝试从公开资料获取
26	-
27	-对于常见硬件（如NVIDIA A100/H100, AMD MI300等），可以从官方规格表或技术文档获取参数，作为参考预填充：
28	-
29	-```text
30	-检测到未支持的硬件: NVIDIA_A100_40GB
31	-
32	-正在查询公开资料获取参考规格...
33	-✓ 找到参考信息（来源：NVIDIA官方规格表）
34	-
35	-参考规格（请核对并修改）：
36	-1. 设备厂商: NVIDIA
37	-2. 矩阵运算BF16算力: 312 TFLOPS ← 参考值
38	-3. 向量运算BF16算力: 19.5 TFLOPS ← 参考值（可选）
39	-4. 显存容量: 40 GB ← 参考值
40	-5. 显存带宽: 1555 GB/s ← 参考值
41	-6. 内部互联带宽: 600 GB/s (NVLink) ← 参考值（卡数<8时需要）
42	-
43	-请确认或修改以上数值：
44	-```
45	-
46	-常见硬件参考值（来源：官方技术规格）：
47	-
48	-\| 硬件 \| 矩阵BF16 \| 向量BF16 \| 显存 \| 带宽 \| 互联带宽 \|
49	-\|------\|---------\|---------\|------\|------\|---------\|
50	-\| NVIDIA A100 40GB \| 312 TFLOPS \| 19.5 TFLOPS \| 40 GB \| 1555 GB/s \| 600 GB/s \|
51	-\| NVIDIA A100 80GB \| 312 TFLOPS \| 19.5 TFLOPS \| 80 GB \| 2039 GB/s \| 600 GB/s \|
52	-\| NVIDIA H100 80GB \| 989 TFLOPS \| 67 TFLOPS \| 80 GB \| 3350 GB/s \| 900 GB/s \|
53	-\| AMD MI300X \| 1300 TFLOPS \| - \| 192 GB \| 5300 GB/s \| 896 GB/s \|
54	-
55	-步骤2：用户确认或修改
56	-
57	-如果无法从公开资料获取，或用户需要修改参考值：
58	-
59	-```text
60	-检测到未支持的硬件: [设备名]
61	-
62	-请提供以下规格信息：
63	-
64	-## 必需参数（矩阵运算）
65	-1. 矩阵运算BF16算力（TFLOPS）: [必填]
66	- → 注：FP16算力默认与BF16相同
67	- → 注：INT8/FP8算力 = BF16算力 × 2（自动推断）
68	-
69	-## 可选参数（向量运算）
70	-2. 向量运算BF16算力（TFLOPS）: [可选，回车跳过]
71	- → 注：如不填写，FlashAttention性能评估可能不准确
72	- → 注：FP32算力 = BF16算力 ÷ 2（自动推断）
73	-
74	-## 必需参数（内存）
75	-3. 显存容量（GB）: [必填]
76	-4. 显存带宽（GB/s）: [必填]
77	-
78	-## 多卡必需参数（互联）
79	-5. 内部互联带宽（GB/s）: [卡数<8时必填]
80	- → 示例：NVLink 600GB/s, HCCS 392GB/s
81	-
82	- 机间互联带宽（GB/s）: [卡数≥8时必填]
83	- → 示例：InfiniBand 200Gbps (25GB/s)
84	-```
85	-
86	-## 硬件规格详细说明
87	-
88	-### 矩阵运算算力（MMA Ops）
89	-
90	-#### 必需参数
91	-
92	-BF16矩阵运算算力（`mma_ops[torch.bfloat16]`）
93	-
94	-- 必填，单位：TFLOPS
95	-- 表示硬件进行BF16矩阵乘法的峰值算力
96	-- 推断规则：
97	- - FP16算力默认与BF16相同（`mma_ops[torch.half] = mma_ops[torch.bfloat16]`）
98	- - INT8/FP8算力 = BF16算力 × 2（`mma_ops[torch.int8] = mma_ops[torch.bfloat16] * 2`）
99	-
100	-```python
101	-mma_ops = {
102	- torch.bfloat16: xxx * 1e12, # BF16算力（用户提供，必填）
103	- torch.float16: xxx * 1e12, # FP16算力（默认与BF16相同）
104	- torch.int8: xxx * 2e12, # INT8算力（BF16的2倍，自动推断）
105	-}
106	-```
107	-
108	-#### 可选参数
109	-
110	-FP32矩阵运算算力（`mma_ops[torch.float32]`）
111	-
112	-- 可选，如不填写使用默认值
113	-- 通常约为BF16算力的1/2到1/4
114	-
115	-### 向量运算算力（GP Ops）
116	-
117	-#### 可选参数
118	-
119	-BF16向量运算算力（`gp_ops[torch.bfloat16]`）
120	-
121	-- 可选，单位：TFLOPS
122	-- 表示硬件进行BF16元素级运算（如激活函数）的峰值算力
123	-- 影响：如不填写，FlashAttention性能评估可能不够准确
124	-- 推断规则：
125	- - FP32向量算力 = BF16向量算力 ÷ 2
126	-
127	-```python
128	-gp_ops = {
129	- torch.bfloat16: xxx * 1e12, # BF16向量算力（用户提供，可选）
130	- torch.float32: xxx * 0.5e12, # FP32向量算力（BF16的一半，自动推断）
131	-}
132	-```
133	-
134	-注意：向量运算算力通常远小于矩阵运算算力（例如A100：矩阵312 TFLOPS vs 向量19.5 TFLOPS）
135	-
136	-### 内存规格
137	-
138	-#### 必需参数
139	-
140	-显存容量（`memory_size_bytes`）
141	-
142	-- 必填，单位：GB
143	-- 表示单卡可用的显存/HBM容量
144	-
145	-显存带宽（`memory_bandwidth_bytes_ps`）
146	-
147	-- 必填，单位：GB/s
148	-- 表示显存/HBM的峰值带宽
149	-- 影响内存密集型算子（如FlashAttention）的性能
150	-
151	-```python
152	-memory_size_bytes = xxx * (1024**3) # 显存容量（GB）
153	-memory_bandwidth_bytes_ps = xxx * (1024**3) # 显存带宽（GB/s）
154	-```
155	-
156	-### 互联带宽（多卡场景）
157	-
158	-#### 多卡时必须提供
159	-
160	-内部互联带宽（卡数 < 8时）
161	-
162	-- 必填（当world-size > 1且卡数<8时）
163	-- 单位：GB/s
164	-- 表示单机内多卡之间的互联带宽
165	-- 常见技术：NVLink, HCCS, Infinity Fabric
166	-
167	-机间互联带宽（卡数 ≥ 8时）
168	-
169	-- 必填（当world-size ≥ 8时）
170	-- 单位：GB/s
171	-- 表示跨机多卡之间的网络带宽
172	-- 常见技术：InfiniBand, RoCE
173	-
174	-```python
175	-# 卡数<8时
176	-internal_interconnect_bw = xxx * (1024**3) # 内部互联带宽（GB/s）
177	-
178	-# 卡数≥8时
179	-cross_node_interconnect_bw = xxx * (1024**3) # 机间互联带宽（GB/s）
180	-```
181	-
182	-#### 常见互联带宽参考
183	-
184	-\| 互联技术 \| 带宽 \| 适用场景 \|
185	-\|---------\|------\|---------\|
186	-\| NVLink 3.0 \| 600 GB/s \| NVIDIA GPU单机多卡 \|
187	-\| NVLink 4.0 \| 900 GB/s \| NVIDIA H100单机多卡 \|
188	-\| HCCS (华为) \| 392 GB/s \| 华为昇腾单机多卡 \|
189	-\| InfiniBand HDR \| 200 Gbps (25 GB/s) \| 跨机互联 \|
190	-\| InfiniBand NDR \| 400 Gbps (50 GB/s) \| 跨机互联 \|
191	-\| RoCE v2 \| 100 Gbps (12.5 GB/s) \| 跨机互联 \|
192	-
193	-### 其他说明
194	-
195	-参考`msmodeling\tensor_cast\device_profiles`路径下的README.md了解更多的配置信息要求。
196	-
197	-## 完整设备配置示例
198	-
199	-### 示例1：单卡配置（NVIDIA L20）
200	-
201	-```python
202	-"""NVIDIA L20 Device Profile."""
203	-
204	-import torch
205	-
206	-from ..device import DeviceProfile, CommGrid, InterconnectTopology, InterconnectType, StaticCost
207	-from ..utils import DTYPE_FP8, DTYPE_FP4
208	-
209	-
210	-# NVIDIA L20 Device Profile
211	-# Specs: 48GB HBM3, ~60 TFLOPS FP32, ~239 TFLOPS FP16/BF16
212	-L20_DEVICE = DeviceProfile(
213	- name="NVIDIA_L20",
214	- vendor="NVIDIA",
215	- mma_ops={ # 此处代表矩阵计算的算力
216	- torch.float32: 59.8 * 1e12, # FP32: BF16/2（自动推断）
217	- torch.bfloat16: 119.5 * 1e12, # BF16: 312 TFLOPS（用户提供）
218	- torch.half: 119.5 * 1e12, # FP16: 同BF16（自动推断）
219	- torch.int8: 239 * 1e12, # INT8: BF16×2（自动推断）
220	- DTYPE_FP8: 239 * 1e12, # FP8: 同INT8（自动推断）
221	- },
222	- gp_ops={ # 此处代表向量计算的算力
223	- torch.float32: 29.9 * 1e12, # FP32: BF16/2（自动推断）
224	- torch.bfloat16: 59.8 * 1e12, # BF16: 59.8 TFLOPS（用户提供）
225	- torch.half: 59.8 * 1e12, # FP16: 同BF16（自动推断）
226	- },
227	- memory_size_bytes=48 * (1024**3), # 显存: 48GB（用户提供）
228	- memory_bandwidth_bytes_ps=0.864 * (1024**4), # 带宽: 864 GB/s（用户提供）
229	- compute_efficiency=0.75,
230	- memory_efficiency=0.7,
231	- static_cost=StaticCost(
232	- mma_op_cost_s=5 * 1e-6,
233	- gp_op_cost_s=2 * 1e-6,
234	- ),
235	-)
236	-```
237	-
238	-### 示例2：多卡配置（NVIDIA L20）
239	-
240	-```python
241	-"""NVIDIA L20 Device Profile."""
242	-
243	-import torch
244	-
245	-from ..device import DeviceProfile, CommGrid, InterconnectTopology, InterconnectType, StaticCost
246	-from ..utils import DTYPE_FP8, DTYPE_FP4
247	-
248	-
249	-# L20 uses PCIe interconnect for single node
250	-L20_INTERCONNECT = CommGrid(
251	- grid=torch.arange(8).reshape(8),
252	- topologies={
253	- 0: InterconnectTopology( # 此处代表机内互联带宽，多卡配置时使用
254	- bandwidth_bytes_ps=64 * 1e9, # PCIe Gen4 x16
255	- latency_s=0.2 * 1e-6,
256	- comm_efficiency=0.7,
257	- ),
258	- },
259	-)
260	-
261	-# NVIDIA L20 Device Profile
262	-# Specs: 48GB HBM3, ~60 TFLOPS FP32, ~239 TFLOPS FP16/BF16
263	-L20_DEVICE = DeviceProfile(
264	- name="NVIDIA_L20",
265	- vendor="NVIDIA",
266	- mma_ops={ # 此处代表矩阵计算的算力
267	- torch.float32: 59.8 * 1e12, # FP32: BF16/2（自动推断）
268	- torch.bfloat16: 119.5 * 1e12, # BF16: 312 TFLOPS（用户提供）
269	- torch.half: 119.5 * 1e12, # FP16: 同BF16（自动推断）
270	- torch.int8: 239 * 1e12, # INT8: BF16×2（自动推断）
271	- DTYPE_FP8: 239 * 1e12, # FP8: 同INT8（自动推断）
272	- },
273	- gp_ops={ # 此处代表向量计算的算力
274	- torch.float32: 29.9 * 1e12, # FP32: BF16/2（自动推断）
275	- torch.bfloat16: 59.8 * 1e12, # BF16: 59.8 TFLOPS（用户提供）
276	- torch.half: 59.8 * 1e12, # FP16: 同BF16（自动推断）
277	- },
278	- memory_size_bytes=48 * (1024**3), # 显存: 48GB（用户提供）
279	- memory_bandwidth_bytes_ps=0.864 * (1024**4), # 带宽: 864 GB/s（用户提供）
280	- compute_efficiency=0.75,
281	- memory_efficiency=0.7,
282	- comm_grid=L20_INTERCONNECT, # 配置内部互联关系
283	- static_cost=StaticCost(
284	- mma_op_cost_s=5 * 1e-6,
285	- gp_op_cost_s=2 * 1e-6,
286	- ),
287	-)
288	-```
289	-
290	-## 快速参考表
291	-
292	-### 矩阵运算算力推断
293	-
294	-\| 用户输入 \| 自动推断FP16 \| 自动推断INT8/FP8 \|
295	-\|---------\|-------------\|-----------------\|
296	-\| BF16: 312 TFLOPS \| FP16: 312 TFLOPS \| INT8: 624 TFLOPS \|
297	-\| BF16: 376 TFLOPS \| FP16: 376 TFLOPS \| INT8: 752 TFLOPS \|
298	-\| BF16: 989 TFLOPS \| FP16: 989 TFLOPS \| INT8: 1978 TFLOPS \|
299	-
300	-### 向量运算算力推断
301	-
302	-\| 用户输入BF16 \| 自动推断FP32 \|
303	-\|-------------\|-------------\|
304	-\| BF16: 19.5 TFLOPS \| FP32: 9.75 TFLOPS \|
305	-\| BF16: 23.5 TFLOPS \| FP32: 11.75 TFLOPS \|
306	-\| BF16: 67 TFLOPS \| FP32: 33.5 TFLOPS \|
307	-
308	-### 多卡互联带宽要求
309	-
310	-\| 卡数 \| 必需参数 \| 示例 \|
311	-\|------\|---------\|------\|
312	-\| 1 \| 无 \| - \|
313	-\| 2-7 \| 内部互联带宽 \| NVLink 600 GB/s \|
314	-\| ≥8 \| 内部互联带宽 + 机间互联带宽 \| NVLink 600 GB/s + IB 25 GB/s \|

D.agents/skills/performance-evaluation/references/parameters.md+0-182

	@@ -1,182 +0,0 @@
1	-# 参数说明
2	-
3	-> 目录 · 完整参数列表(必需/可选/LLM专用/Diffusion专用) · 量化方式说明 · 并行策略说明 · 日志文件命名规范 · config.json 字段说明
4	-
5	-## 完整参数列表
6	-
7	-### 必需参数（无默认值，必须明确指定）
8	-
9	-\| 参数类别 \| 参数名 \| 说明 \| 用户输入示例 \| 约束 \|
10	-\|---------\|--------\|------\|-------------\|------\|
11	-\| 模型规格 \| `model_spec` \| 模型的具体规格版本 \| `14B`, `7B`, `T2V-14B` \| 如果模型有多个规格，必须列出供用户选择 \|
12	-\| 设备类型 \| `--device` \| 目标硬件设备名称 \| `ATLAS_800_A2_376T_64G` \| 必须在支持列表中或用户提供完整规格 \|
13	-\| 分辨率 \| `--height`, `--width` \| 多模态输入分辨率（图像/视频） \| `480`, `832` \| 无默认值，必须明确 \|
14	-\| 量化方式 \| `--quantize-linear-action` \| 模型量化策略 \| `DISABLED`, `W8A8_DYNAMIC`, `INT8` \| 无默认值，必须明确 \|
15	-\| 视频帧数 \| `--frame-num` \| 视频模型必须明确（仅限视频模型） \| `81`, `121` \| 视频模型必须指定 \|
16	-
17	-### 可选参数（有默认值）
18	-
19	-#### 通用参数
20	-
21	-\| 参数 \| 默认值 \| 说明 \| 可选值 \|
22	-\|------\|--------\|------\|--------\|
23	-\| `--seq-len` \| 64 \| 文本输入序列长度（tokens） \| 32, 64, 128, 256, 512 \|
24	-\| `--dtype` \| `bfloat16` \| 数据类型（推荐BF16） \| float16, bfloat16, float32 \|
25	-\| `--batch-size` \| `1` \| 批次大小 \| 1, 2, 4, 8 \|
26	-\| `--sample-step` \| `28` \| 采样步数（Diffusion模型） \| 20, 28, 50 \|
27	-
28	-#### 多卡并行参数
29	-
30	-\| 参数 \| 默认值 \| 说明 \| 约束 \|
31	-\|------\|--------\|------\|------\|
32	-\| `--world-size` \| 1 \| 使用的卡数（默认1卡） \| 1, 2, 4, 8 \|
33	-\| `--ulysses-size` \| 1 \| Ulysses并行大小 \| 多卡时必须明确 \|
34	-\| `--cfg-parallel` \| false \| CFG并行 \| 支持CFG的模型可选 \|
35	-\| `--tp-size` \| 1 \| Tensor Parallelism大小 \| LLM多卡时使用 \|
36	-\| `--dp-size` \| auto \| Data Parallelism大小 \| 可选 \|
37	-\| `--ep-size` \| 1 \| Expert Parallelism大小(MoE) \| MoE模型使用 \|
38	-
39	-#### 其他参数
40	-
41	-\| 参数 \| 默认值 \| 说明 \|
42	-\|------\|--------\|------\|
43	-\| `--context-length` \| 0 \| 上下文长度(tokens) \|
44	-\| `--decode` \| False \| 启用解码模式 \|
45	-\| `--compile` \| False \| 启用torch.compile \|
46	-\| `--chrome-trace` \| - \| 生成Chrome trace文件 \|
47	-\| `--quantize-attention-action` \| `DISABLED` \| Attention量化 \|
48	-\| `--num-mtp-tokens` \| 0 \| MTP token数量(DeepSeek) \|
49	-\| `--use-cfg` \| False \| 启用CFG(Classifier-Free Guidance) \|
50	-\| `--dit-cache` \| False \| 启用DiT缓存 \|
51	-\| `--cache-step-range` \| - \| 缓存步数范围 \|
52	-
53	-### 文本生成评估参数 (LLM)
54	-
55	-\| 参数 \| 说明 \| 默认值 \| 用户必须指定 \|
56	-\|------\|------\|--------\|-------------\|
57	-\| `model_id` \| HuggingFace模型ID或本地路径 \| - \| ✅ 是 \|
58	-\| `model_spec` \| 模型规格 \| - \| ✅ 必须 \|
59	-\| `--device` \| 硬件设备名 \| - \| ✅ 必须 \|
60	-\| `--num-queries` \| 并行查询数量 \| 1 \| ❌ 否 \|
61	-\| `--query-length` \| 输入序列长度(tokens) \| 64 \| ❌ 否（有默认值） \|
62	-\| `--context-length` \| 上下文长度(tokens) \| 0 \| ❌ 否 \|
63	-\| `--decode` \| 启用解码模式 \| False \| ❌ 否 \|
64	-\| `--dtype` \| 数据类型 \| `bfloat16` \| ❌ 否 \|
65	-\| `--tp-size` \| Tensor Parallelism大小 \| 1 \| 多卡时✅必须 \|
66	-\| `--dp-size` \| Data Parallelism大小 \| auto \| ❌ 否 \|
67	-\| `--ep-size` \| Expert Parallelism大小(MoE) \| 1 \| ❌ 否 \|
68	-\| `--compile` \| 启用torch.compile \| False \| ❌ 否 \|
69	-\| `--chrome-trace` \| 生成Chrome trace文件 \| - \| ❌ 否 \|
70	-\| `--quantize-linear-action` \| 线性层量化 \| - \| ✅ 必须 \|
71	-\| `--quantize-attention-action` \| Attention量化 \| `DISABLED` \| ❌ 否 \|
72	-\| `--num-mtp-tokens` \| MTP token数量(DeepSeek) \| 0 \| ❌ 否 \|
73	-
74	-### 视频生成评估参数 (Diffusion)
75	-
76	-\| 参数 \| 说明 \| 默认值 \| 用户必须指定 \|
77	-\|------\|------\|--------\|-------------\|
78	-\| `model_path` \| 模型路径或HuggingFace ID \| - \| ✅ 是 \|
79	-\| `model_spec` \| 模型规格 \| - \| ✅ 必须 \|
80	-\| `--device` \| 硬件设备名 \| - \| ✅ 必须 \|
81	-\| `--batch-size` \| 批次大小 \| 1 \| ❌ 否 \|
82	-\| `--seq-len` \| 文本序列长度 \| 64 \| ❌ 否（有默认值） \|
83	-\| `--height` \| 图像高度 \| - \| ✅ 必须 \|
84	-\| `--width` \| 图像宽度 \| - \| ✅ 必须 \|
85	-\| `--frame-num` \| 视频帧数 \| - \| ✅ 必须 \|
86	-\| `--sample-step` \| 采样步数 \| 28 \| ❌ 否 \|
87	-\| `--dtype` \| 数据类型 \| `bfloat16` \| ❌ 否 \|
88	-\| `--use-cfg` \| 启用CFG(Classifier-Free Guidance) \| False \| ❌ 否 \|
89	-\| `--world-size` \| 设备总数 \| 1 \| ❌ 否 \|
90	-\| `--ulysses-size` \| Ulysses并行大小 \| 1 \| 多卡时✅必须 \|
91	-\| `--cfg-parallel` \| CFG并行 \| false \| 支持CFG时可选 \|
92	-\| `--dit-cache` \| 启用DiT缓存 \| False \| ❌ 否 \|
93	-\| `--cache-step-range` \| 缓存步数范围 \| - \| ❌ 否 \|
94	-\| `--quantize-linear-action` \| 线性层量化 \| - \| ✅ 必须 \|
95	-\| `--chrome-trace` \| 生成Chrome trace \| - \| ❌ 否 \|
96	-
97	-## 量化方式说明
98	-
99	-\| 量化方式 \| 说明 \| 适用场景 \|
100	-\|---------\|------\|---------\|
101	-\| `DISABLED` \| 无量化，使用原始精度 \| 质量敏感场景 \|
102	-\| `W8A8_DYNAMIC` \| 动态INT8量化 \| 推理加速，轻微质量损失 \|
103	-\| `W8A8_STATIC` \| 静态INT8量化 \| 推理加速，预校准 \|
104	-\| `FP8` \| FP8量化 \| 新一代GPU/NPU \|
105	-\| `MXFP4` \| 4-bit量化 \| 极端压缩场景 \|
106	-
107	-## 并行策略说明
108	-
109	-### 单卡（默认）
110	-
111	-```bash
112	---world-size 1 --ulysses-size 1
113	-```
114	-
115	-### 多卡（4卡，Ulysses并行）
116	-
117	-```bash
118	---world-size 4 --ulysses-size 4
119	-```
120	-
121	-### 多卡+CFG（4卡，CFG并行+Ulysses）
122	-
123	-```bash
124	---world-size 4 --cfg-parallel --ulysses-size 2
125	-```
126	-
127	-### 自动推荐策略
128	-
129	-如果没有明确指定并行策略，系统会：
130	-
131	-1. 多模态生成模型：推荐 `ulysses-size = world-size`
132	-2. 支持CFG的模型：推荐 `cfg-parallel` + `ulysses-size = world-size / 2`
133	-
134	-## 日志文件命名规范
135	-
136	-\| 文件类型 \| 命名格式 \| 示例 \|
137	-\|---------\|---------\|------\|
138	-\| 执行日志 \| `iteration_{N}.log` \| `iteration_1.log` \|
139	-\| 配置信息 \| `config.json` \| `config.json` \|
140	-\| Chrome Trace \| `trace_{N}.json` \| `trace_1.json` \|
141	-\| 通信日志 \| `communication_{N}.log` \| `communication_1.log` \|
142	-\| 汇总数据 \| `summary.json` \| `summary.json` \|
143	-\| 最终报告 \| `evaluation_report.md` \| `evaluation_report.md` \|
144	-
145	-## config.json 字段说明
146	-
147	-```json
148	-{
149	- "config_name": "配置名称",
150	- "model_name": "模型名称",
151	- "model_spec": "模型规格",
152	- "model_params": "参数量",
153	- "device": "设备名称",
154	- "device_spec": "设备规格",
155	- "model_path": "模型路径",
156	- "height": "图像高度",
157	- "width": "图像宽度",
158	- "frame_num": "视频帧数",
159	- "sample_step": "采样步数",
160	- "seq_len": "序列长度",
161	- "dtype": "数据类型",
162	- "quantization": "量化方式",
163	- "world_size": "卡数",
164	- "ulysses_size": "Ulysses并行大小",
165	- "cfg_parallel": "是否CFG并行",
166	- "parallel_strategy": "并行策略",
167	- "iterations": "迭代次数",
168	- "timestamp": "时间戳",
169	- "user_specified": {
170	- "model_spec": "用户指定的模型规格",
171	- "resolution": "用户指定的分辨率",
172	- "frame_num": "用户指定的帧数",
173	- "device": "用户指定的设备",
174	- "quantization": "用户指定的量化方式"
175	- },
176	- "default_used": {
177	- "seq_len": "使用的默认值",
178	- "dtype": "使用的默认值",
179	- "batch_size": "使用的默认值"
180	- }
181	-}
182	-```

D.agents/skills/performance-evaluation/references/setup-guide.md+0-130

D.agents/skills/performance-evaluation/scripts/validate_results.py+0-167

M.agents/skills/performance-optimization/SKILL.md+10-8

A.agents/skills/performance-optimization/evals/evals.json+38-0

M.agents/skills/performance-optimization/references/optimization-dimensions.md+4-0

M.agents/skills/profiling-collection/SKILL.md+8-7

A.agents/skills/profiling-collection/evals/evals.json+27-0

MAGENTS.md+1-1