@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.4

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/shared/profiling_mc2.md

@@ -0,0 +1,278 @@
+# 性能采集（msprof + L2 cache flush）参考
+
+本文档承载 MC2 skill 的"性能子能力"。MC2 算子性能采集的三个核心要点：
+
+1. **必须刷 L2 cache**：每轮主 kernel 前调 `heavy_add_kernel`，否则前一轮的 B 矩阵驻留 L2 让带宽指标虚高；
+2. **用 `msprof --ai-core=on --aic-mode=task-based` 采集**：以 task（kernel launch）为单位记录，**不用 `--warm-up`**；
+3. **多卡数据后处理规则**：每张卡取**最后 5 次** main kernel 的 Task Duration 求平均，4 张卡的平均值取**最大值**作为整体性能。
+
+> 父级性能采集流程见 `ops-profiling/SKILL.md`。本文件只补充 MC2 场景的差异化要点。
+
+---
+
+## 1. 为什么 MC2 性能采集需要刷 L2
+
+MC2 算子的 perf 模式跑多轮（默认 10 轮），每轮都会让主 kernel 把 B 矩阵从 GM 读到 L2。如果不在每轮之间清空 L2：
+
+- 下一轮的 B 直接从 L2 命中，**MTE2 带宽指标虚高**；
+- 通信开销（UDMA）相对计算的占比也会失真。
+
+参考工程的解法：每轮主 kernel 前调用 `heavy_add_kernel` 扫一遍大于目标芯片 L2 容量的 bf16 buffer（参考工程示例值 256 MB），把 B 挤出 L2。
+
+> **为什么不用 `--warm-up`？**  `msprof op --warm-up=N` 跳过前 N 次采集，依赖 NPU 自然运行把 L2 填满稳定状态——但 MC2 算子的 B 矩阵驻留 L2 恰恰是要消除的干扰。我们改用 `heavy_add_kernel` 主动挤出 L2，所以不需要 warm-up。
+
+---
+
+## 2. heavy_kernels.h 剖析
+
+参考工程在 `include/kernel/heavy_kernels.h` 提供两个"重负载"kernel：
+
+### 2.1 heavy_exp_kernel（boost 预热）
+
+```cpp
+__global__ __aicore__ __vector__ void heavy_exp_kernel(
+    GM_ADDR x, GM_ADDR y, int64_t totalLength, int64_t blockLength)
+```
+
+- 输入：bf16 buffer（参考工程示例值 10000×10000 = 200 MB）；
+- 操作：`y = exp(x)`，全部 AIV 核并行（block 数按目标芯片实际 AIV 核数确定，参考工程示例值 56）；
+- 用途：**去 host bound**——上板首次运行受 host 启动开销影响，先跑 100 次 exp 把 host 端的异步任务队列填满，让 NPU 进入稳定状态。
+
+参考工程 `src/all_to_all_matmul.cpp` 注释掉了 boost 阶段（`heavy_exp_kernel` 调用被注释）；新算子按需启用。
+
+### 2.2 heavy_add_kernel（L2 cache flush）
+
+```cpp
+__global__ __aicore__ __vector__ void heavy_add_kernel(
+    GM_ADDR x, int64_t totalLength, int64_t blockLength)
+```
+
+- 输入：bf16 flush buffer，大小按目标芯片实际 L2 容量动态确定、须大于 L2 容量（参考工程示例值 128×1024×1024 = 256 MB）；
+- 操作：`x += 1`，全部 AIV 核并行（block 数按目标芯片实际 AIV 核数确定，参考工程示例值 56）；
+- 用途：**刷 L2 cache**——flush buffer 大于目标芯片 L2 容量即可，扫描一遍把 B 矩阵挤出 L2（L2 容量等芯片规格以 npu-arch skill 为唯一知识源，本文档不复述数值）。
+
+参考工程 `src/all_to_all_matmul.cpp` 的 perf 主循环（`mode == "perf"` 分支）：
+
+```cpp
+constexpr int PERF_LOOP_COUNT = 10;
+for (int i = 0; i < PERF_LOOP_COUNT; ++i) {
+    // 1. 刷 L2
+    heavy_add_kernel<<<HEAVY_BLOCK_NUM, nullptr, stream>>>(
+        cacheFlush, CACHE_FLUSH_ELEM_COUNT, cacheFlushBlockLen);
+    // 2. 跑主 kernel
+    AllToAllQuantMatmulKernelE4M3E4M3<<<tilingData.tileQbmmTilingData.usedCoreNum, nullptr, stream>>>(
+        shmemSpace, deviceA, deviceScaleA, deviceB, deviceScaleB, deviceOutput, tilingData);
+    ACL_CHECK(aclrtSynchronizeStream(stream));
+}
+```
+
+每轮的 `heavy_add_kernel` + 主 kernel 都会被 msprof 单独采集，产生独立的 task 记录。分析时只取主 kernel 的记录。
+
+### 2.3 HEAVY_BLOCK_NUM 的选择
+
+```cpp
+constexpr int64_t HEAVY_BLOCK_NUM = 56;  // 示例值，按目标芯片实际 AIV 核数设置
+```
+
+HEAVY_BLOCK_NUM 取目标芯片的**实际 AIV 核数**（AIV 核数属芯片规格，以 npu-arch skill 为唯一知识源，本文档不复述典型值；运行时经 `npu-smi info` 或平台规格接口查询），让 heavy_add_kernel 占满所有 AIV 核，最大化 L2 flush 效果。
+
+---
+
+## 3. perf mode 调用约定
+
+参考工程的 host 程序通过第 5 个命令行参数区分 precision/perf 模式：
+
+```bash
+# precision 模式（默认）：单次 kernel + 精度比对
+./build/all_to_all_matmul 2048 8192 3584 4
+
+# perf 模式：10 轮 (cache_flush + main kernel)，供 msprof 采集
+./build/all_to_all_matmul 2048 8192 3584 4 perf
+```
+
+`run.sh` 透传这个参数（第 5 个位置参数）：
+
+```bash
+bash run.sh 2048 8192 3584 4 perf
+```
+
+### precision vs perf 流程对比
+
+| 步骤 | precision 模式 | perf 模式 |
+|------|---------------|-----------|
+| 数据准备 | gen_data.py 生成 input_*.bin | 同 precision |
+| kernel 调用 | 单次 `AllToAllQuantMatmulKernelE4M3E4M3` | 10 轮（cache_flush + main） |
+| 输出 | npu_out.bin + shmem_*.bin | 无（perf 模式不写文件） |
+| verify_result.py | 跑（比对精度） | 不跑（跳过） |
+| 用途 | 开发期精度验证 | msprof task 采集 |
+
+---
+
+## 4. msprof 采集命令与数据提取
+
+### 4.1 标准采集命令
+
+```bash
+PROJ="$(pwd)"  # 算子工程根目录
+
+msprof --ai-core=on --aic-mode=task-based \
+    --output="${PROJ}/docs/perf/round_001" \
+    --application="${PROJ}/build/all_to_all_matmul 2048 8192 3584 4 perf"
+```
+
+### 4.2 关键参数
+
+| 参数 | 说明 | MC2 场景 |
+|------|------|---------|
+| `--ai-core=on` | 开启 AI Core 数据采集 | 必设 |
+| `--aic-mode=task-based` | 以 task（kernel launch）为单位采集 | 必设——每个 kernel 一条记录 |
+| `--output=<dir>` | 输出目录 | 直接归档到 `docs/perf/round_NNN/` |
+| `--application="<cmd>"` | 被采集程序（含参数，整体用引号包起来） | 第 5 参必传 `perf` |
+| **不用** `--warm-up` | MC2 用 `heavy_add_kernel` 主动刷 L2 替代 | — |
+
+### 4.3 输出目录结构
+
+msprof 在 `--output` 指定目录下生成 `PROF_{timestamp}_{pid}/` 子目录：
+
+```
+{output}/
+└── PROF_{timestamp}_{pid}/
+    └── mindstudio_profiler_output/
+        ├── op_summary_{ts}_{pid}.csv   # 每个 kernel 的 task 记录（最关键）
+        ├── op_stat_{ts}_{pid}.csv      # 按 Op Name 聚合的统计
+        └── ...
+```
+
+**`op_summary_*.csv` 的关键字段**（实际 header 以本地 CANN 版本为准）：
+
+| 字段 | 含义 |
+|------|------|
+| `Op Name` | kernel 名（如 `AllToAllQuantMatmulKernelE4M3E4M3`、`heavy_add_kernel`） |
+| `Task Duration (us)` | 单次 task 的耗时（微秒） |
+| `aiv_time (us)` / `aic_time (us)` | AIV / AIC 流水耗时 |
+| `L2 Hit Rate` | L2 cache 命中率 |
+
+### 4.4 多卡数据后处理规则
+
+**核心规则**（多卡并行，整体性能由最慢的卡决定）：
+
+```
+1. 每张卡（rank）的 op_summary_*.csv 中：
+   - 过滤 Op Name == 主 kernel（如 AllToAllQuantMatmulKernelE4M3E4M3）的记录
+   - 共 10 条（对应 PERF_LOOP_COUNT=10）
+   - 取最后 5 条的 Task Duration (us) 求平均 → 该卡性能 P_i
+
+2. 整体性能 = max(P_0, P_1, P_2, P_3)
+```
+
+**为什么取最后 5 条？** 前 5 轮可能受冷启动 / device 频率未稳定影响，后 5 轮进入稳态，取均值降低随机波动。
+
+**为什么 4 卡取最大？** MC2 是多卡并行 + 跨卡同步（`aclshmem_barrier_all`），整体性能由最慢的卡（木桶效应）决定。取平均会高估性能。
+
+### 4.5 多卡后处理
+
+使用 `ops-profiling` skill 的 `perf_summary.py` 进行多卡数据后处理：
+
+```bash
+# 使用 ops-profiling skill 的统一解析工具（生成统计摘要并归档，用法见 ops-profiling/SKILL.md）
+python3 ${SKILL_PATH}/scripts/perf_summary.py "$ROUND_DIR" ops/{op_name}
+```
+
+> `perf_summary.py` 对 CSV 指标生成 min/avg/max 统计摘要（不做判定）。MC2 场景需特别关注的后处理规则（§4.4）：每卡取最后 5 次 main kernel 的 Task Duration 求平均，4 卡取最大值作为整体性能——该规则需基于其输出的 CSV/摘要手动计算。
+
+---
+
+## 5. MC2 性能指标判定
+
+### 5.1 主导流水判定
+
+MC2 算子是"通信+计算融合"，预期主导流水是 **AIC cube**：
+
+```
+cube_ratio 应 >40%（下限来自 MindStudio 官方文档；上限无官方阈值，内部经验约 70%）
+```
+
+若 `vec_ratio` 过高，说明：
+- AIV 在做大量非通信工作（可能 fixpipe 没下放到 AIC）；
+- 或通信 Put 太密集，AIV 占用过高（Put 数量 / 数据量失衡）。
+
+### 5.2 通信隐藏率
+
+理想情况下，AIV 的通信 Put 与 AIC 的 MMAD 完全并行：
+
+- AIV 的 `aiv_time(us)` 应该 ≈ AIC 的 `aic_time(us)`；
+- 若 AIV time >> AIC time：通信是瓶颈，需增大 `headMSize`（单次 Put 数据量更大）；
+- 若 AIC time >> AIV time：计算是瓶颈，需优化 Blaze Tiling（增大 baseK、scaleKL1）或减少 AIC 内部 rank 循环开销。
+
+### 5.3 核间负载均衡
+
+所有 AIC 核都按相同节奏遍历所有 rank 累加，理论上各核负载相同。但 Blaze 的尾块调度可能让部分核提前结束。判定：
+
+- `op_summary_*.csv` 各核 `aic_time(us)` 差异 <10%：达标；
+- 差异 10-30%：警告，检查 `BlockMmad` 的 dispatch 是否均匀；
+- 差异 >30%：严重，重审 Tiling 的 `mBaseTailSplitCnt` 等字段。
+
+### 5.4 卡间负载均衡（4 卡之间）
+
+每张卡都应给出近似的 `rank_avg`（§4.4 的 P_i）。若某张卡明显慢（如 P_2 >> 其他）：
+
+- 检查该卡的 NPU 健康（`npu-smi info` 看 Health 状态）；
+- 检查 SHMEM 端口冲突（`tcp://127.0.0.1:8998` 多卡共用时是否丢包）；
+- 检查该卡的 AIC 核数是否与其他卡一致（部分卡可能因故障降级）。
+
+### 5.5 理论耗时计算
+
+MC2 算子的理论耗时按"通信+计算取最大"估：
+
+```
+理论耗时 = max(通信耗时, 计算耗时)
+通信耗时 = rankSize * commMSize * kPerRank * sizeof(dtype) / UDMA 带宽
+计算耗时 = 2 * M * N * K / Cube 算力
+```
+
+若 §4.4 的整体性能（4 卡 max） ≈ 理论耗时 → 通算流水接近最优；
+若整体性能 >> 通信耗时 且 >> 计算耗时 → 同步开销过大，检查 CrossCore Flag 使用。
+
+---
+
+## 6. 优化方向速查
+
+| 瓶颈信号 | 优化方向 |
+|----------|---------|
+| 整体 Task Duration >> 理论耗时 | 检查 `CrossCoreWaitFlag` 的 idx 一致性，避免无谓 wait |
+| AIV ratio 高（vec_ratio > 30%） | 增大 `headMSize`，减少 Put 次数 |
+| AIC cube ratio 低（<40%） | 调整 Blaze Tiling（增大 baseK、scaleKL1） |
+| L2 命中率过高（>80%） | L2 flush 没起作用，检查 `heavy_add_kernel` 调用与 `CACHE_FLUSH_ELEM_COUNT` |
+| 单核不均衡（核间） | 调整 Blaze Tiling 的尾块分裂策略（mBaseTailSplitCnt / nBaseTailSplitCnt） |
+| 单卡不均衡（卡间） | §5.4——查 NPU 健康 / SHMEM 端口 / 核数一致性 |
+| AIC 内 rank 循环开销大 | 增大 `headMSize`，减少 tile 数；或合并多次 mmadOp_ 调用 |
+
+详细优化方法见 `ops-profiling/references/optimization_quickref.md`。
+
+---
+
+## 7. 排错速查
+
+| 现象 | 可能原因 | 排查方向 |
+|------|---------|---------|
+| `op_summary_*.csv` 无主 kernel 记录 | 跑的是 precision 模式 | 第 5 参传 `perf` |
+| `op_summary_*.csv` 只有 heavy_add_kernel | 主 kernel 在 precision 路径 | 同上 |
+| PROF_xxx 子目录数量 < rankNum | 部分 rank fork 失败 / 提前退出 | 查 host stderr，确认所有子进程都跑完 |
+| 主 kernel 记录 < 5 条 | `PERF_LOOP_COUNT < 5` | 调大 `src/*.cpp` 中的 PERF_LOOP_COUNT |
+| L2 命中率 >80% | L2 flush 失效 | 检查 `heavy_add_kernel` 的 totalLength 是否大于目标芯片 L2 容量 |
+| perf 模式跑得极慢 | `aclrtSynchronizeStream` 在每轮都同步 | 参考工程已正确实现，新算子不要每轮 sync |
+| 某张卡的 avg 明显高于其他卡 | NPU 健康 / SHMEM 端口 / 核数问题 | §5.4 |
+| Task Duration 在后 5 轮仍波动大 | device 频率未稳定 / 数据依赖 | 增大 PERF_LOOP_COUNT 到 20，取最后 5 |
+| 对照路径（torch/分步实现）trace 出现无关 kernel、计时失真 | 同步方式污染：用空转 kernel（如 `torch.exp` 循环）或全局 sync 做计时同步，会 flush 全局流水线 | 对照实验用 `torch.npu.current_stream().synchronize()` 仅同步当前流；验证 trace 中无对照组无关 kernel |
+
+---
+
+## 8. 后续阅读
+
+| 想了解 | 读 |
+|--------|---|
+| msprof CSV 字段详解 | `ops-profiling/references/csv_fields_reference.md` |
+| 单卡算子的性能优化方法 | `ops-profiling/references/optimization_quickref.md` |
+| 通算融合整体架构 | `mc2_architecture.md` |
+| `tileCnt` 调优（通算并行旋钮） | `pipeline_tuning.md` |
+| 参考工程改造食谱 | `codebase_map.md` |

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/scripts/fetch_apace.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+# fetch_apace.sh — 获取官网 ops-transformer 仓 apace 子树的最新代码
+#
+# 用途：ascendc-mc2-best-practice skill 不持有代码快照。文档引用的样例代码
+#       通过本脚本从官网仓（gitcode.com/cann/ops-transformer）现取现读。
+#
+# 用法：
+#   ./fetch_apace.sh                # 更新本地仓并输出 apace 子树路径
+#   ./fetch_apace.sh --ref <commit> # 锚定到指定 commit（复现用）
+#   APACE_REPO=/path/to/ops-transformer ./fetch_apace.sh  # 使用已有本地克隆
+#   APACE_PIN_REF=<commit> ./fetch_apace.sh               # 等价 --ref（环境变量形式）
+#
+# ⚠️ master 漂移警示：官网 master 的 apace 目录结构会演进（如 block/→core/ 迁移、
+#   kernel/fusions/ 层级、新增算子）。skill 文档以 pin 的已验证快照为结构基准；
+#   拉取 master 仅用于契约核对，使用前必须 diff 校验并在文档引用失效时更新文档。
+#
+# 行为：
+#   1. APACE_REPO 已设置且含 apace 子树 → git fetch 更新该仓（零重复克隆）
+#   2. 否则 sparse clone（--filter=blob:none --sparse，仅 apace 子树）到缓存目录
+#      默认缓存：~/.cache/apace-reference/ops-transformer
+#   3. 输出：APACE_ROOT=<本地 apace 子树绝对路径>
+#   4. 写入 manifest：<缓存或仓>/.apace_fetch_manifest.json
+
+set -euo pipefail
+
+REPO_URL="https://gitcode.com/cann/ops-transformer.git"
+APACE_SUBPATH="mc2/common/op_kernel/apace"
+CACHE_DIR="${APACE_CACHE_DIR:-$HOME/.cache/apace-reference/ops-transformer}"
+REF="${APACE_PIN_REF:-master}"
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --ref) REF="$2"; shift 2 ;;
+        *) echo "未知参数: $1" >&2; exit 1 ;;
+    esac
+done
+
+log() { echo "[fetch_apace] $*" >&2; }
+
+if [[ -n "${APACE_REPO:-}" ]]; then
+    if [[ ! -d "${APACE_REPO}/${APACE_SUBPATH}" ]]; then
+        log "错误：APACE_REPO=${APACE_REPO} 下不存在 ${APACE_SUBPATH}"
+        exit 1
+    fi
+    REPO_DIR="${APACE_REPO}"
+    log "使用已有本地克隆：${REPO_DIR}"
+    if [[ "${REF}" == "master" ]]; then
+        log "git fetch 更新中..."
+        git -C "${REPO_DIR}" fetch origin master --quiet || log "警告：fetch 失败（可能离线），使用本地现有状态"
+    fi
+else
+    REPO_DIR="${CACHE_DIR}"
+    if [[ -d "${REPO_DIR}/.git" ]]; then
+        log "缓存已存在：${REPO_DIR}，更新中..."
+        git -C "${REPO_DIR}" fetch origin master --quiet || log "警告：fetch 失败（可能离线），使用本地现有状态"
+    else
+        log "sparse clone 官网仓（仅 ${APACE_SUBPATH} 子树）到 ${REPO_DIR} ..."
+        mkdir -p "$(dirname "${REPO_DIR}")"
+        git clone --filter=blob:none --sparse --quiet "${REPO_URL}" "${REPO_DIR}"
+        git -C "${REPO_DIR}" sparse-checkout set "${APACE_SUBPATH}"
+    fi
+fi
+
+if [[ "${REF}" != "master" ]]; then
+    log "锚定到 ${REF}"
+    git -C "${REPO_DIR}" checkout --quiet "${REF}"
+else
+    git -C "${REPO_DIR}" checkout --quiet origin/master 2>/dev/null || git -C "${REPO_DIR}" checkout --quiet master
+fi
+
+APACE_ROOT="${REPO_DIR}/${APACE_SUBPATH}"
+COMMIT=$(git -C "${REPO_DIR}" rev-parse --short HEAD)
+DATE=$(date -Iseconds)
+
+cat > "${REPO_DIR}/.apace_fetch_manifest.json" <<EOF
+{
+  "source_repo": "${REPO_URL}",
+  "subpath": "${APACE_SUBPATH}",
+  "commit": "${COMMIT}",
+  "ref": "${REF}",
+  "fetched_at": "${DATE}",
+  "apace_root": "${APACE_ROOT}"
+}
+EOF
+
+log "完成：commit=${COMMIT}"
+echo "APACE_ROOT=${APACE_ROOT}"

package/assets/ops-direct-invoke/skills/ascendc-performance-best-practices/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: ascendc-performance-best-practices
+trigger: query
+description: Ascend C 算子性能优化最佳实践库。按算子族组织优化经验与参考代码总结，供性能优化实施阶段查询。触发：查询某类算子的性能优化参考实现、实施某项优化时需加载对应优化经验时。
+---
+
+# Ascend C 算子性能优化最佳实践
+
+## 算子分类体系
+
+按 **算子族（operator family）** 组织优化知识，同一族内所有变体共享同一份文档（如 `matmul`、`matmul_mxfp4`、`batch_matmul`、`matmul_a16w16` 等均归入 `matmul` 族；`matmul_all_reduce`、`allgather_matmul`、`matmul_reducescatter`、`alltoall_matmul` 等均归入 `mc2` 族）。
+
+| 类别 | 典型算子 | 适用架构 | 优化设计指南 |
+|------|---------|---------|------------|
+| MatMul 矩阵乘类 | MatMul, BatchMatMul, MatMul_MXFP4, MatMul_A16W16 | DAV_3510 | ✅ [性能优化指南](references/matmul/guide.md) |
+| MC² 通算融合类 | matmul_all_reduce, allgather_matmul, matmul_reducescatter, alltoall_matmul | DAV_3510 | ✅ [性能优化指南](references/mc2/guide.md) |
+| RadixSort 基数排序类 | TopK, KthValue, Sort, ArgSort, ArgMax/Min | DAV_2201 / DAV_3510 | ✅ [性能优化指南](references/sort/radix_sort.md) |
+| Scalar 编码与诊断 | 任意 ScalarBound 算子 | DAV_2201 / DAV_3510 | ✅ [性能优化指南](references/scalar/guide.md) |
+| Reduction 归约类 | ReduceSum, Softmax, LayerNorm, RMSNorm, ArgMax | DAV_3510 | ✅ [实现索引](references/reduce/guide.md) · [模板代码与使用指南](references/reduce/templates/usage_guide.md) · [公共基类](references/reduce/templates/dav310/softmax_v2_base.template) · [State Resident](references/reduce/templates/state_resident_design.md) |
+| Elementwise 逐元素类 | Sin, Cos, Abs, Exp | DAV_3510 | ✅ [双缓冲设计](references/elementwise/double_buffer_design.md) · [向量化效率优化](references/elementwise/vector_efficiency_design.md) |
+| Broadcast 广播类 | Add, Mul, Sub 等含广播轴算子 | DAV_3510 | ✅ [性能优化指南](references/broadcast/broadcast_design.md)（选型型，见结构 B） |
+| Conversion 数据转换类 | Transpose, Concat, Split | DAV_3510 | ✅ [Transpose融合设计](references/conversion/transpose_fusion_design.md) · ✅ [性能优化指南](references/conversion/guide.md) |
+| Convolution 卷积类 | Conv2D, DepthwiseConv | — | 📋 规划中 |
+| NN 神经网络类 | FlashAttention, GroupNorm | — | 📋 规划中 |
+| Random 随机类 | RandomUniform, Dropout | — | 📋 规划中 |
+| SIMT 线程级算子 | 条件分支、离散索引等不规则操作 | DAV_3510 | ✅ [性能优化指南](references/simt/optimization-guide.md) |
+
+> 未收录的算子族返回「该算子族优化知识暂未收录」。各族详细的优化类型、叠加关系、选型决策见该族 `references/<family>/` 目录。
+> 
+> **融合算子的优化**：对于融合算子（如 AddRelu、MulSub 等组合算子），可将其拆解为上述基础算子族，分别获取各基础算子的性能优化实践后，结合融合场景进行适配。例如 AddRelu 可拆解为 Broadcast（Add）+ Elementwise（Relu），分别参考对应族的优化指南。
+
+## 公共优化能力（跨算子族通用）
+
+| 优化类型 | 适用场景 | 文档 |
+|---------|---------|------|
+| **尾块处理（Tail Block）** | 数据量不能被 tile 大小整除的场景 | ✅ [尾块处理指南](references/common/tail_block_design.md) |
+| **数据搬运（DataCopy）** | 非对齐、小批量多次搬运等的场景 | ✅ [数据搬运](references/common/datacopy_optimization_design.md) |
+| **UB/TBuf常驻复用与Bank冲突规避** |  大量tile/loop都重复从GM搬运，会造成大量冗余MTE2开销的场景 | ✅ [UB/TBuf常驻复用与Bank冲突规避](references/common/ub_resident_design.md) |
+| **小 Shape 核数裁剪（Core Shrink）** | Vec/归约类小 Shape，`A1` 相对满核很小，全核启动/同步开销大于计算 | ✅ [核数裁剪设计](references/common/core_shrink_design.md) |
+
+## 查询方式
+
+| 输入 | 必需 | 说明 |
+|------|------|------|
+| 算子名 | 是 | 如 `matmul` / `matmul_mxfp4` / `batch_matmul` |
+| 优化类型 | 否 | 如 `pingpong` / `swat` / `streamk` / `fullload` / `scale_coalescing` / `mte2_preload` / `constant_folding`；不提供则加载全部 |
+
+查询流程：**算子名 → 映射到算子族 → 定位 `references/<family>/` → 按优化类型筛选文档**。算子族映射规则：精确匹配族名直接命中；以族名为前缀或核心词（如 `matmul_mxfp4`、`batch_matmul`）归入该族；其他形态由调用方按功能显式指定。
+
+### 模板代码查找链路
+
+当算子族提供可复用的模板代码时（如 Reduction 族的 5 个 Softmax 模板），按以下链路逐层查找：
+
+```
+SKILL.md（本文件）
+  → 算子分类表中定位算子族，点击 guide.md 链接
+    → references/<family>/guide.md
+      → 模板表中选择方案对应的模板，点击 .md 链接
+        → references/<family>/templates/<模板名>.md
+          → 说明文档中链接同名 .h / .cpp / .template 代码文件
+            → references/<family>/templates/<模板名>.{h,cpp,template}（以此为代码骨架实施）
+```
+
+> **模板代码文件类型**：`.h`、`.cpp`、`.template` 都是模板代码。`.template` 是参考模板源码（如 `references/reduce/templates/dav310/*.template`），使用前需按该目录 `usage_guide.md` 将 `.template` 转成同名 `.h`/`.cpp`（去掉 `.template` 后缀），转换后才可读、可编译。
+
+> ⚠️ 查到模板代码（`.h`/`.cpp`/`.template`）后，**必须直接拷贝模板文件到项目中使用**，而非"参考模板从头重写"。具体操作：
+> 1. 若为 `.template`，先按 `usage_guide.md` 转成 `.h`/`.cpp`；再将文件拷贝到项目的 `op_kernel/` 目录（保留 `dav310/` 等子目录结构）
+> 2. 仅做**最小适配**使其编译通过（如命名空间别名、TilingData 字段补充等）
+> 3. 在 kernel.cpp 中 `#include` 模板头文件，按分支条件 dispatch 到对应模板类
+> 4. 模板内的 MicroAPI VF 计算（RegTensor、MaskReg、LoadAsFp32、StoreFromFp32 等）**必须原样保留**
+>
+> **常见编译修复**（遇到 MicroAPI 报错时按此顺序尝试，禁止直接降级为高层 API）：
+> - **命名空间别名**：模板可能用 `AscendC::MicroAPI::`，而 CANN 安装中实际为 `AscendC::Reg::`。加一行 `namespace MicroAPI = Reg;` 即可解决
+> - **API 签名适配**：对照 CANN 实际头文件（`$ASCEND_HOME_PATH/x86_64-linux/asc/include/basic_api/reg_compute/`）调整参数数量/类型
+> - **头文件 include 路径**：确保 `kernel_reg.h` 或 `kernel_reg_compute_*.h` 被 `kernel_operator.h` 正确引入
+>
+> 禁止查到模板后仍从零编写 kernel。
+
+## 性能优化文档结构（两类，均为性能优化，按算子族性质选其一）
+
+> 两类都是"让算子更快"的最佳实践，区别只在优化的形态：A 是对单一实现调参，B 是在多种实现间选对路径。
+
+### A. 单实现调优型（对单一实现做某项性能优化，如 matmul pingpong/swat）
+
+每份 `<优化类型>_design.md` 的章节组织：
+
+**必选章节：**
+
+1. 优化目标 —— 效果与量化收益（kernel μs / MTE2 段 / CUBE busy 等）
+2. 架构概览 —— 存储层级、数据流、buffer 布局、事件同步模型
+3. 关键参数 —— 新增 / 调整字段与 Host 侧计算
+4. 核心计算循环 —— 改造前后对照（含事件同步）
+5. 优化的关键修改点 —— 表格形式
+
+**可选章节：**
+
+6. 注意事项 / 约束 —— 前置条件、L1/L0 预算、边界与兼容性
+7. 实施常见问题与解决方案 —— 高频踩坑与根因
+8. 实测性能、选型决策、与其他优化的叠加关系、自检清单
+
+### B. 多实现选型型（族内有多种实现路径，选对即性能最优，如 `broadcast`）
+
+这类族的性能优化**本质就是按场景选对实现**——`broadcast` 的 OneDim 前置快路径 + tile 内 NDDMA / DataCopyPad / UB 三类实现，选错直接慢甚至出错（nan）；选对才快。这同样是性能最佳实践，只是优化点在"选型"而非"调参"。结构：
+
+1. `<family>_design.md` 总览 —— 速查表、**选型决策树**（决定性能的核心）、tiling/切分逻辑、约束
+2. 每种实现一份分册（如 `nddma_design.md`）—— 适用条件、Kernel 写法、注意
+3. `code/` 子目录 —— 可直接参考/裁剪的 AscendC 范式源码（`.h/.cpp`）
+4. 进阶/边界单列（如 `advanced_tiling.md`）
+
+> 选 B 时"收益"体现为**选对实现避免劣化**，可不强制量化 μs，但必须给出**选型依据**（什么场景用哪种实现、为什么快/为什么错）。
+
+## 扩展新算子族
+
+1. 创建 `references/<family>/` 目录（以族名命名，非单个变体）
+2. 判断族性质：优化型 → 按 A 写 `<优化类型>_design.md`；实现指导型 → 按 B 写总览+分册(+code/)
+3. 更新本 SKILL.md 分类表格
+
+## 依赖
+
+无外部第三方依赖。知识主要以 Markdown 文档内置；实现指导型算子族（如 `broadcast`）另含
+`references/<family>/code/` 下的 AscendC 范式源码（`.h/.cpp`），随 skill 一并版本化、不依赖工作区外部目录。

package/assets/ops-direct-invoke/skills/ascendc-performance-best-practices/evals/evals.json

@@ -0,0 +1,138 @@
+{
+  "eval_mode": "text",
+  "evals": [
+    {
+      "id": 2,
+      "title": "MatMul 族在 DAV_3510 上的优化",
+      "config": {
+        "max_tokens": 200000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 240000,
+          "glm-5": 220000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "ascendc-performance-best-practices 中 MatMul 算子族有哪些优化知识？在 DAV_3510 架构上适用的优化指南是什么？可以加载技能，不需要执行其他外部工具调用。",
+      "expected_output": "回复应引用 MatMul 族的优化策略内容，说明 DAV_3510 架构上 MatMul 算子的优化策略和最佳实践。应列出 MatMul 族包含的变体和可用的优化策略类型。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 3,
+      "title": "Vector 算子性能优化咨询（正向看护）",
+      "config": {
+        "max_tokens": 160000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 180000,
+          "glm-5": 170000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "distractor_skills": [
+          "ascendc-perf-optimize",
+          "ascendc-tiling-design"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我想了解 ascendc-performance-best-practices 中 Vector 算子族在 DAV_3510 上的优化策略和最佳实践，请加载技能帮我查看具体内容。",
+      "expected_output": "回复应介绍 Vector 算子族在 DAV_3510 上的优化思路和主要方向。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 4,
+      "title": "MC² 通算融合算子 matmul_all_reduce 性能优化",
+      "config": {
+        "max_tokens": 160000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我在实现 matmul_all_reduce 通算融合算子，当前通信和计算是串行执行的，性能不达标。这个技能里 MC² 通算融合类在 DAV_3510 上有哪些性能优化策略？可阅读该技能文档获取规范，但不要实际执行 profiling 或修改代码。",
+      "expected_output": "回复应引用 MC² 通算融合类算子族（matmul_all_reduce、allgather_matmul、matmul_reducescatter、alltoall_matmul 等变体）的性能优化策略，说明 local_matmul（将本 rank 的 matmul 从通信块循环中分离以与通信重叠）与 pipeline_balancing（TilingData 驱动的系统搜索）等优化手段，并说明其在 DAV_3510 上的适用关系。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 5,
+      "title": "Reduction 归约类 Softmax 模板代码查找与集成",
+      "config": {
+        "max_tokens": 160000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我要在 DAV_3510 上实现一个输入为 3D [A1,R,A0]、且 R 超出 UB 容量的 Softmax 算子，想复用这个技能里的模板代码。应该如何查找并集成这些模板？可阅读该技能文档获取规范，但不要实际执行代码修改。",
+      "expected_output": "回复应说明 Reduction 归约类（Softmax/LayerNorm/RMSNorm）模板代码查找链路：从 SKILL.md 定位 reduce 族 → references/reduce/guide.md → templates/ 下按 R 与 UB 关系选择模板，R 超出 UB 时应选 ARA-Recompute（R 切 bin、3 阶段重读 + 二分累加树）；并强调使用前必须按 usage_guide.md 将 .template 转成同名 .h 后拷贝到项目 op_kernel 使用，禁止从零重写。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 6,
+      "title": "Broadcast 广播算子实现选型（多实现选型型）",
+      "config": {
+        "max_tokens": 160000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我在 DAV_3510 上实现 Add 广播算子，shape 为 [M,1]+[1,N] 部分轴广播，发现性能差而且有时出现 nan。这个技能里 Broadcast 族有哪些实现路径，该怎么选？可阅读该技能文档获取规范，但不要实际执行 profiling 或修改代码。",
+      "expected_output": "回复应说明 Broadcast 广播类族属于多实现选型型优化：OneDim 合轴塌一维快路径（标量广播前置优先）+ tile 内 NDDMA（搬入即广播）/ DataCopyPad（外层广播 offset 寻址）/ UB 内 Broadcast 三类实现；选型需按广播轴位置与 shape 判断，选错实现会变慢甚至产生 nan，应给出选型依据。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 7,
+      "title": "Elementwise 逐元素算子双缓冲流水线优化",
+      "config": {
+        "max_tokens": 160000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我写的 Exp 逐元素算子很慢，感觉数据搬运和计算是串行执行的，计算单元大量空闲。这个技能里 Elementwise 族在 DAV_3510 上有什么优化方案？可阅读该技能文档获取规范，但不要实际执行 profiling 或修改代码。",
+      "expected_output": "回复应引用 Elementwise 逐元素类的双缓冲设计（references/elementwise/double_buffer_design.md），说明通过多缓冲（如 InitBuffer 双缓冲）让 MTE2 搬入、Vector 计算、MTE3 搬出三个阶段流水线并行以隐藏内存访问延迟，并可就向量化效率优化方向给出提示。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 8,
+      "title": "公共优化能力：数据量不能被 tile 整除的尾块处理",
+      "config": {
+        "max_tokens": 160000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我在实现一个归约类算子，数据量不能被 tile 大小整除，尾块处理出现越界和负载不均衡的问题。这个技能里的公共优化能力有尾块处理的方案吗？可阅读该技能文档获取规范，但不要实际执行 profiling 或修改代码。",
+      "expected_output": "回复应引用公共优化能力中的尾块处理指南（references/common/tail_block_design.md），说明对不能被 tile 大小整除的数据量采用双轨制 norm/tail 核分离、GatherMask 向量化处理尾块以及 32B/64B 对齐与 DataCopyPad 等策略，避免越界访问与负载不均衡。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 9,
+      "title": "MatMul API 常量折叠实施",
+      "config": {
+        "max_tokens": 160000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我要把 Ascend C Matmul API 的运行时 TCubeTiling 改成编译期 MatmulApiStaticTiling 常量折叠，降低 aic_scalar_time。这个技能里 MatMul 族有对应的实施指南吗？改造时要注意哪些精度相关问题？可阅读该技能文档获取规范，但不要实际执行 profiling 或修改代码。",
+      "expected_output": "回复应引用 MatMul 族 constant_folding 策略（references/matmul/constant_folding_design.md），说明用 constexpr MatmulApiStaticTiling 作为第 5 个模板参数、Init/REGIST 传 nullptr 后再 SetOrgShape、调用点 shape 必须全程 constexpr；并强调 isTrans/BiasType/对象类型不可改、singleCore 填上界、SetOrgShape 不能放在 REGIST 之前，以及尾块维度不可常量化。",
+      "expectations": [],
+      "files": []
+    }
+  ],
+  "skill_name": "ascendc-performance-best-practices"
+}