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

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/blaze-shmem/mc2_architecture.md

@@ -0,0 +1,199 @@
+# MC2 通算融合架构总览
+
+本文档面向第一次接触 MC2 的 Architect/Developer，建立 AIV/AIC 分工、UDMA 通信、4-buffer 流水、M 轴通算并行的整体心智模型。读完本文档应能回答：
+
+- 为什么 MC2 必须用 SHMEM/UDMA，不能用 HCCL？
+- AIV 和 AIC 各自做什么？怎么同步？
+- 4-buffer 流水怎么掩盖通信开销？
+- M 轴切分 vs N/K 轴切分的取舍？
+
+---
+
+## 1. MC2 是什么
+
+MC2 = Matrix Computation & Communication，多卡通算融合。典型场景：
+
+- **AllToAll + Matmul**：MoE 模型专家路由；每张卡把自己负责的 M 段通过 AllToAll 发给其他卡，接收方在收到的数据上做本地 Matmul。
+- **AllReduce + Matmul**：DDP 前向反向；Matmul 后的部分和通过 AllReduce 聚合。
+- **ReduceScatter + Matmul**：TP 反向梯度聚合。
+
+参考工程 `all_to_all_matmul/` 实现的是 **AllToAll + 量化 Matmul（MX FP8）** 的融合，可作为所有 MC2 算子的起手模板。
+
+## 2. 为什么不用 HCCL
+
+HCCL（Huawei Collective Communication Library）的高阶 API（`Hccl::AllReduce` 等）是 asc-devkit 官方通算融合路径的通信入口，但该路径**不支持 Kernel 直调，仅支持单算子 API 调用**（见 asc-devkit 官方文档《通算融合》算子实现章节）：
+
+```
+官方通算融合: aclnn 单算子 API → Kernel 内 Hccl 高阶 API（依赖框架注入的 GetHcclContext 上下文）
+                                     ↑
+                     直调（<<<>>>）拿不到框架注入的通信上下文，无法接入
+```
+
+而 MC2 直调的核心诉求是：**Kernel 内部下发通信 + 下发计算，让两者在硬件流水上重叠**。官方通算融合路径不向内核直调场景开放 Hccl 高阶 API；SHMEM/UDMA 直调路径把通信下发权交回 Kernel：
+
+```
+应用层: Kernel 内直接调 aclshmemx_udma_put_nbi(...)
+                ↓
+        UDMA 硬件引擎异步搬数
+                ↓ （同时）
+        AIC 管线继续下发 MMAD 指令
+                ↓
+        aclshmem_barrier_all() 等通信完成
+```
+
+UDMA（Unified DMA，对应 URMA 协议——Unreliable Remote Memory Access）是 Ascend 950 提供的 Kernel 级跨卡通信原语，所有通信下发在 Kernel 内完成，可与计算流水深度耦合。
+
+> **官方文档**：<https://shmem-doc.pages.dev/>。7 类 18 个 HCCL 高阶 API 在本路线全部禁用（清单及理由见 [`comm_shmem.md`](comm_shmem.md) §5）。
+
+## 3. AIV/AIC 分工
+
+Ascend 950 一个 Block 内有 AIC（Cube 核）和 AIV（Vector 核）两类算力。参考工程把通信和计算分给不同的核：
+
+| 核 | 职责 | 在参考工程的位置 |
+|----|------|----------------|
+| **AIV（Vector）** | 下发 UDMA Put 指令、维护通信流水 | `all_to_all_matmul_impl.h::AllToAllProcess()` |
+| **AIC（Cube）** | 在通信 buffer 上做 Blaze Matmul（遍历所有 rank 累加） | `all_to_all_matmul_impl.h::MatmulProcess()` |
+
+```cpp
+// all_to_all_matmul_impl.h Process()
+__aicore__ inline void Process() {
+  if ASCEND_IS_AIV {
+    AllToAllProcess();   // AIV 跑通信（UDMA Put + Barrier）
+  }
+  if ASCEND_IS_AIC {
+    MatmulProcess();     // AIC 在通信 buffer 上做完整 Blaze Matmul
+  }
+}
+```
+
+同一份 kernel 二进制同时跑在 AIV 和 AIC 上，靠 `ASCEND_IS_AIV` / `ASCEND_IS_AIC` 编译期分支隔离。
+
+### 跨核同步：CrossCore Flag
+
+AIV 写完 buffer 后必须通知 AIC 可读；AIC 读完必须通知 AIV 可覆盖。这对同步通过 `CrossCoreSetFlag` / `CrossCoreWaitFlag` 完成：
+
+```cpp
+// AIV 写完 bufferId 后置 flag
+CrossCoreSetFlag<0x2, PIPE_MTE3>(mLoopIdx);
+// AIC 读 bufferId 前等 flag
+CrossCoreWaitFlag<0x2, PIPE_MTE2>(mLoopIdx);
+```
+
+- `<0x2>` 是 `modeId`（同步模式参数），asc-devkit 中模式 2 表示"AI Core 内部 AIC 与所有 AIV 之间的同步控制"（AIV 发 `CrossCoreSetFlag` → AIC 侧 `CrossCoreWaitFlag` 解除阻塞，见 `CrossCoreSetFlag_ISASI.md`）。flag 的实际标识由函数参数 `flagId`（即 `mLoopIdx`）提供；
+- `PIPE_MTE3` 是 AIV 的输出管线（UB→GM/L1，在 3510 的 sync 层面 AIV 独有），`PIPE_MTE2` 是 AIV 和 AIC **共有**的输入管线（AIV: GM→UB, AIC: GM→L1）；
+- idx 用 `mLoopIdx`，AIV 写第 i 轮 buffer → AIC 读第 i 轮 buffer，idx 一一对应。
+
+### 流水深度控制
+
+AIV 不能无脑往前写——会覆盖 AIC 还没读的旧数据。参考工程用"等 AIC 释放信号"来限速：
+
+```cpp
+// AIV：写到第 bufferSize 轮后，必须等 AIC 释放第 (i - bufferSize) 轮的 buffer
+if (mLoopIdx >= bufferSize_) {
+  CrossCoreWaitFlag<0x2, PIPE_MTE3>(mLoopIdx - bufferSize_);
+  allToAllComm_.BarrierAll();  // 还要等所有其他卡也释放
+}
+```
+
+对应的 AIC 端在算完第 i 轮后置释放 flag（`all_to_all_matmul_impl.h::MatmulProcess` 内）。
+
+## 4. 4-Buffer 流水
+
+`bufferSize=4` 是参考工程的默认深度。把通信流水画出来：
+
+```
+时间轴 →
+AIV: |PutScale| Put(0) | Put(1) | Put(2) | Put(3) | Put(4) | Put(5) | ... | Put(N-1) |
+AIC:           |wait(0) | MMAD(0)| wait(1) | MMAD(1)|wait(2)| MMAD(2)| ... | MMAD(N-1)|
+               ↑ 4 个 buffer 轮转使用，bufferId = mLoopIdx & (bufferSize - 1)
+```
+
+- AIV 的 Put(i) 与 AIC 的 MMAD(i-1) 并行；
+- AIV 的 Put(i) 把数据写到 SHMEM 的 `bufferId = i & 3` 位置；
+- AIC 的 MMAD(i) 从同一 bufferId 位置读；
+- 通信延迟被 4 个 buffer 的流水深度掩盖。
+
+**bufferSize 取舍**：
+- 过浅（=1）：通信和计算串行，没有掩盖效果；
+- 过深：SHMEM 空间不够（默认 1 GB），或 AIC 等 AIV 凑够 4 轮才开始算，反而增加延迟；
+- 4 是经验最优值，参考工程固定为 4，新算子一般不动。
+
+## 5. SHMEM 空间布局
+
+每张卡的 SHMEM 空间（`aclshmem_align` 分配的 1 GB）被分成两段：
+
+```
+SHMEM base (rankId 视角)
+├── Data buffers[bufferSize]   ← 每个 bufferBlockSize 存所有 rank Put 过来的当前轮数据
+│   ├── buffer[0]: rankSize * commMSize * bytesPerMRow
+│   ├── buffer[1]: ...
+│   ├── buffer[2]: ...
+│   └── buffer[3]: ...
+└── Scale buffers              ← 所有 rank 的 Scale 一次性 Put（不参与流水）
+    └── rankSize * M * scaleBytesPerMRow
+```
+
+参考工程在 `all_to_all_comm_udma.h` 的 `AllToAllComm::GetDataAddrGm(bufferId)` 和 `GetScaleAddrGm()` 访问这两段。
+
+## 6. 切分策略：M 轴通算并行
+
+参考工程沿 M 轴切分，每块 `headMSize=512` 行。为什么选 M 轴？
+
+| 候选轴 | 通算并行性 | 实现难度 | 适用场景 |
+|--------|-----------|---------|---------|
+| **M 轴** | ✅ 高（不同 M 段可独立 Put，AIC 边收边算） | 中 | **通用首选**（参考工程采用） |
+| N 轴 | 低（N 轴切会让 B 矩阵跨卡，通信量翻倍） | 高 | 不推荐 |
+| K 轴 | 中（K 切分对应 ReduceScatter，每段需要 reduce） | 高 | AllReduce + Matmul 场景 |
+
+**M 轴切分的好处**：
+- A 矩阵按 M 段分布在不同卡，每卡独立 Put 自己的 M 段，无冲突；
+- B 矩阵全卡持有相同副本（或按 K 段分布），无需通信；
+- AIC 收到某段 M 后立即可算，无需等待所有段到齐。
+
+### headMSize 取值
+
+参考工程默认 `headMSize=512`（即 `tileCnt = M/512`），只是经验起点，**不是最优值**。约束：
+- 必须是 Blaze `BlockMmad` 的 `baseM`（典型 128 或 256）的整数倍；
+- 必须让单次 Put 的数据量 `headMSize * kPerRank * sizeof(dtype)` 落在 UDMA 高效区间（数百 KB ~ 数 MB）；
+- `headMSize = M / tileCnt`，调整 `tileCnt` 即调整 `headMSize`。
+
+**`tileCnt` 是通算流水的深度旋钮**——`tileCnt=1` 时无掩盖（串行基线），`tileCnt>1` 时 N-1 级流水掩盖通信延迟。分两阶段调优（详见 [`pipeline_tuning.md`](../../shared/pipeline_tuning.md)）：精度调试阶段用 `tileCnt=1` 做串行基线简化精度/审查，性能调优阶段扫描 `tileCnt` 找最优。
+
+## 7. UDMA 通信原语速览
+
+参考工程用到的三个核心 API（详见 `comm_shmem.md`）：
+
+```cpp
+// 1. 非阻塞 Put：本地 → 远程
+aclshmemx_udma_put_nbi(remoteWinAddr + dstOffset,
+                        localAddr + srcOffset,
+                        (__ubuf__ uint8_t*)nullptr,
+                        dataSize,
+                        remoteRank);
+
+// 2. Quiet：确保本次 Put 数据已到达对端 PE
+aclshmemx_udma_quiet(remoteRank);
+
+// 3. 全卡 Barrier：跨核同步点
+aclshmem_barrier_all();
+```
+
+- `Put_nbi` 是非阻塞的——下发完立即返回，AIV 继续下一条 Put；
+- `quiet` 确保本次 Put 数据已到达对端 PE（completed）；
+- `aclshmem_barrier_all()` 是全卡跨核同步点。
+
+参考工程在 `PutToAllRanks` 中"每个 Block 负责发往对应的 remoteRank"（`all_to_all_comm_udma.h::PutToAllRanks`），让多 Block 并发下发，避免单 Block 串行 Put 所有 rank。
+
+## 8. 性能采集要点
+
+MC2 算子的性能采集有一条核心特殊点：每轮主 kernel 前必须调用 `heavy_add_kernel` 刷 L2 cache，否则前一轮的 B 矩阵驻留 L2 会让本轮带宽指标虚高。详细流程（msprof task-based 采集、4 卡数据后处理、优化速查）见 [`profiling_mc2.md`](../../shared/profiling_mc2.md)。
+
+## 9. 后续阅读
+
+| 想了解 | 读 |
+|--------|---|
+| SHMEM API 细节、扩展其他通信原语 | `comm_shmem.md` |
+| Blaze 模板选型、BlockMmad 改造 | `matmul_blaze.md` |
+| msprof task-based 采集、4 卡后处理 | `profiling_mc2.md` |
+| 参考工程文件结构、改造食谱 | `codebase_map.md` |
+| 各 Step 的具体动作 | `workflow_integration.md` |

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/blaze-shmem/review-checklist.md

@@ -0,0 +1,29 @@
+# blaze-shmem 路线代码审查验收条件
+
+> Reviewer 在 Step 4 逐项检查。违反任意红线项 = FAIL。
+
+## 红线项
+
+| # | 检查项 | 验收条件 |
+|---|--------|---------|
+| R1 | 架构白名单 | CMakeLists.txt 中 `npu-arch` 落在 skill 声明的支持架构集合内（见 [`capability-declaration.md`](../../capability-declaration.md)） |
+| R2 | 无 HCCL 高阶 API | 代码中不含 `Hccl::`（完整禁止清单见 [`comm_shmem.md`](comm_shmem.md) §5） |
+| R3 | 无 asc-devkit matmul | 代码中不含 `AscendC::Matmul` |
+| R4 | 通信走 SHMEM | 头文件含 `shmem.h`，device 侧用 `aclshmemx_udma_*`/`aclshmem_barrier_all`（`aclshmemx_barrier_all_vec` 已废弃，见 [`comm_shmem.md`](comm_shmem.md) §4.4） |
+| R5 | Matmul 走 Blaze | 头文件含 `blaze/gemm/block/block_mmad*.h` |
+| R6 | L2 flush 证据 | 代码中含 L2 flush kernel 调用或等效实现（见 [`profiling_mc2.md`](../../shared/profiling_mc2.md)） |
+
+## 流程门禁
+
+| # | 检查项 | 验收条件 |
+|---|--------|---------|
+| R7 | 流程门禁完整 | `docs/` 下 DESIGN/PLAN/WALKTHROUGH/REVIEW.md 齐全；环境检查通过 |
+
+## 常见 FAIL 原因
+
+| 现象 | 根因 | 修复方向 |
+|------|------|---------|
+| 代码中含 `Hccl::AllReduce` | 开发者把 HCCL 当成"熟悉的 API"用了 | 要求 Developer 改写为 `aclshmemx_udma_put_nbi` + 自实现 Reduce 逻辑 |
+| 代码中含 `AscendC::Matmul` | 开发者误用 asc-devkit 接口 | 替换为 `Blaze::Gemm::Block::BlockMmad` |
+| SHMEM 空间不足崩溃 | DESIGN.md 的空间预算没算对 | 重算 `SHMEM_SPACE_SIZE` |
+| 精度对不上但无报错 | 多半是 ProcessSingleBatch 中 rank==rankId 分支错（未切换到本卡 GM）/ `remoteRankCnt` 没从 0 起算 | 对照 `qbmm_mx_kernel.h` 注释核对 |

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/blaze-shmem/workflow_integration.md

@@ -0,0 +1,215 @@
+# CANNBot Step 1→7 在 MC2 场景下的工作流映射
+
+本文档把父级 `plugins-official/ops-direct-invoke/AGENTS.md` 的 7 步流程具体化到 MC2 通算融合算子场景。CANNBot 主控和 Architect/Developer/Reviewer 三类 Subagent 在每个 Step 进入前都应先读对应小节，明确"本阶段在 MC2 场景下要做什么、门禁是什么、调用哪些 skill"。
+
+> 父级流程定义以 `plugins-official/ops-direct-invoke/AGENTS.md` 为准；本文件只补充 MC2 场景的差异化要点，不重写父级规则。
+
+---
+
+## Step 1：环境检查（门禁）
+
+### 标准动作（父级定义）
+
+按 `ascendc-env-check` skill 运行：
+1. `npu-smi info` 查设备列表与状态；
+2. 检查 `ASCEND_HOME_PATH` / `CANN_TOOLKIT_HOME` 等环境变量；
+3. 运行 `workflows/scripts/verify_environment.sh {operator_name}`，生成 `environment.json`。
+
+### MC2 场景额外校验
+
+| 校验项 | 命令 / 方法 | 失败处理 |
+|--------|------------|---------|
+| **NPU 架构必须为 dav-3510** | `npu-smi info` 读 `Chip Name` 应为 `Ascend 950` 系列；CMake 阶段再次校验 `NPU_ARCH=dav-3510` | 非 3510 直接终止，告知用户"仅支持 Ascend 950 (dav-3510)" |
+| **SHMEM 第三方库可解析** | 检查 `references/foundations/blaze-shmem/all_to_all_matmul/third_party/shmem/CMakeLists.txt` 是否存在；若不存在，`cmake/shmem.cmake` 会自动 `git clone --branch v1.5.0`（gitcode.com/cann/shmem） | 提示用户检查网络访问 gitcode.com |
+| **tensor_api（`AscendC::Te::*`）可解析** | 检查 `third_party/tensor_api/include/tensor_api/tensor.h` 是否存在；若不存在，`cmake/tensor_api.cmake` 会自动 `git clone` asc-devkit（与 ascendc-blaze-best-practice skill 共享来源） | 提示用户检查网络访问 gitcode.com |
+| **Blaze 头文件可解析** | blaze 头（`blaze/gemm/block/block_mmad*.h`）位于 CANN toolkit 的 `opp/built-in/op_impl/ai_core/tbe/impl/ops_nn/ascendc/common`，由 CMakeLists 的 `_BLAZE_COMMON_DIR` 指向；无需 clone | 提示用户检查 CANN 安装路径是否正确 |
+| **多卡环境可用** | `npu-smi info` 至少能看到 `rankNum` 张卡（默认 4 卡） | 提示用户准备多卡环境；单卡只能跑精度模式，性能模式需多卡 |
+
+### 门禁
+
+`environment.json` 的 `validation.all_passed=true` 且上述 MC2 校验全部通过 → 进入 Step 2。任何一项失败禁止进入 Step 2，告知用户原因。
+
+---
+
+## Step 2：设计（Architect）
+
+### 输出物
+
+父级要求双文件：`operators/{op}/docs/DESIGN.md` + `operators/{op}/docs/PLAN.md`。MC2 场景下 DESIGN.md **必须额外包含**以下小节（Reviewer 在 Step 4 会交叉检查）：
+
+#### §三大约束显式确认
+
+```markdown
+## 三大约束确认
+
+### 约束 1：通信走 SHMEM
+- 选用的 SHMEM 原语：<aclshmemx_udma_put_nbi / aclshmemx_barrier_all_vec / ...>
+- 确认无 Hccl:: 高阶 API：✅
+
+### 约束 2：Matmul 走 Blaze
+- 选用的 Blaze 模板：<Blaze::Gemm::Block::BlockMmad + Kernel::QuantMatmulMxKernelSwat 等>
+- DispatchPolicy：<MatmulWithScaleMx / ...>
+- 确认无 asc-devkit Matmul 高阶 API：✅
+
+### 约束 3：流程合规
+- 复用基底：references/foundations/blaze-shmem/all_to_all_matmul/
+- 计划修改的文件清单：<列出 [MODIFY] 文件>
+```
+
+#### §切分策略
+
+- **两阶段 `tileCnt` 策略**（详见 [`pipeline_tuning.md`](../../shared/pipeline_tuning.md)）：
+  - Step 2-4 设计/审查阶段：`tileCnt=1`（`headMSize=m`）做串行基线，简化精度/审查调试；
+  - Step 6 性能验收阶段：扫描 `tileCnt ∈ {1, 2, 4, 8, 16, 32}` 找最优，`headMSize=512` 只是起点不是最优值。
+- M 轴切分：`headMSize = m / tileCnt`，`bufferSize=4`
+- SHMEM 空间预算（默认 1 GB，需够装下 `rankSize * bufferSize * bufferBlockSize + scale`）
+
+#### §AIV/AIC 分工图
+
+明确哪些 work 在 AIV（通信），哪些在 AIC（计算），同步点在哪里（`CrossCoreSetFlag<0x2, PIPE_*>`，其中 `0x2` 是 modeId 即 AIV↔AIC 跨核同步模式）。
+
+### Architect 加载顺序
+
+1. 加载 ascendc-mc2-best-practice skill，读 `references/foundations/blaze-shmem/mc2_architecture.md` 建立整体心智模型；
+2. 若通信侧不确定用哪个 SHMEM 原语 → 读 `references/foundations/blaze-shmem/comm_shmem.md`；
+3. 若计算侧不确定用哪个 Blaze 模板 → 读 `references/foundations/blaze-shmem/matmul_blaze.md`；
+4. 输出 DESIGN.md + PLAN.md。
+
+### 门禁
+
+- 双文件齐全；
+- DESIGN.md 包含"三大约束确认"小节，且勾选 ✅；
+- 切分策略中 `headMSize` 等参数有可解释的依据（不能拍脑袋）。
+
+---
+
+## Step 2.5：设计串讲
+
+### Developer 串讲模式关注点
+
+- 复用的基底文件清单是否合理（不能把 `[REUSE]` 文件错标成 `[MODIFY]`）；
+- AIC 是否在通信 buffer 上遍历所有 rank，rank==rankId 是否切换到本卡 GM；
+- SHMEM 空间预算是否够（`rankSize * commMSize_ * kPerRank * bufferSize` + scale 段）。
+
+### Architect 串讲回应关注点
+
+- 若 Developer 提出"想用 HCCL 替代 SHMEM" → 直接拒绝（HCCL 高阶 API 禁止清单及理由见 [`comm_shmem.md`](comm_shmem.md) §5）；
+- 若 Developer 提出"想用 asc-devkit Matmul 高阶 API" → 直接拒绝（Matmul 必须走 Blaze 模板，见 [`matmul_blaze.md`](matmul_blaze.md)）。
+
+### 收敛
+
+严格 1 轮串讲；分歧写入 WALKTHROUGH.md `## 设计串讲仲裁`。
+
+---
+
+## Step 3：开发（Developer）
+
+### 起手流程
+
+```bash
+# 1. 从基底工程复制
+cp -r references/foundations/blaze-shmem/all_to_all_matmul operators/{op_name}
+
+# 2. 按 [MODIFY] 标记定点改造
+#    - src/{op_name}.cpp：函数名、kernel 调用、参数解析
+#    - include/kernel/all_to_all_comm_udma.h：通信原语（若非 AllToAll）
+#    - include/kernel/all_to_all_matmul_impl.h：通算融合主类
+#    - include/kernel/qbmm_mx_kernel.h：Blaze Kernel 包装（改 Scale/dtype/bias 时动）
+#    - include/tiling/*：TilingData 字段
+#    - scripts/gen_data.py + verify_result.py：dtype/容差
+
+# 3. 编译
+cd operators/{op_name}
+cmake -S . -B build -DNPU_ARCH=dav-3510
+cmake --build build -j
+
+# 4. 跑精度
+bash run.sh  # 默认 m=2048 k=8192 n=3584 rank=4 precision
+```
+
+### 开发阶段红线
+
+- **禁止**新增 `Hccl::` 调用（Reviewer 会在 Step 4 grep）；
+- **禁止**包含 asc-devkit 的 matmul 头；
+- **禁止**为了赶进度跳过 `run.sh` 的精度模式直接跑 perf；
+- 改完每个 `[MODIFY]` 文件后立即跑一次 `bash run.sh` 做冒烟，避免最后一次性 debug。
+
+### 门禁
+
+- 编译通过；
+- `bash run.sh`（precision 模式）输出 `verify_result.py: PASS`；
+- 代码已提交到 `operators/{op_name}/`。
+
+---
+
+## Step 4：审查（Reviewer）
+
+### 必查清单
+
+按 [`review-checklist.md`](review-checklist.md) R1~R7 逐项检查（含验收条件、常见 FAIL 原因与修复方向）。违反任意红线项 = FAIL。
+
+### 门禁
+
+- REVIEW.md 判定 `PASS` 或 `PASS WITH NOTES` → 进入 Step 6；
+- REVIEW.md 判定 `FAIL` → 进入 Step 5 修复循环。
+
+---
+
+## Step 5：修复循环
+
+最多 3 轮。每轮：Developer 修复 → Reviewer 复审。MC2 场景下常见的"修不动"问题：
+
+- **跨核同步 flag 错位**：`CrossCoreSetFlag<0x2, PIPE_MTE3>(mLoopIdx)` 与 `CrossCoreWaitFlag<0x2, PIPE_MTE2>(mLoopIdx)` 的 idx 必须一致；
+- **UDMA Put 顺序错**：`aclshmemx_udma_quiet(remoteRank)` 必须在每次 Put 后调用，否则数据未真正下发；
+- **remoteRankCnt 错位**： `splitKNum` 必须等于 `rankSize`，否则 fixpipe 时机不对（最后一次 mmadOp_ 才触发）；
+
+3 轮仍未通过 → 暂停上报用户。
+
+---
+
+## Step 6：性能验收（Developer）
+
+### MC2 专用流程（必须刷 L2 cache）
+
+> 详细步骤见 `profiling_mc2.md`。这里只给摘要。
+
+```bash
+PROJ="$(pwd)"
+
+# 1. 算子二进制已具备 perf 模式（run.sh 第 5 参传 perf）
+bash run.sh 2048 8192 3584 4 perf
+
+# 2. msprof task-based 采集（无 warm-up；L2 flush 由 perf 主循环内部保证）
+msprof --ai-core=on --aic-mode=task-based \
+    --output="${PROJ}/docs/perf/round_001" \
+    --application="${PROJ}/build/{op_name} 2048 8192 3584 4 perf"
+
+# 3. 多卡后处理：每卡取最后 5 次 main kernel 平均，4 卡取最大
+python3 scripts/extract_perf.py "${PROJ}/docs/perf/round_001" AllToAllQuantMatmulKernelE4M3E4M3 5
+```
+
+### 关键点
+
+- **两阶段 `tileCnt` 扫描**：进入 Step 6 时算子默认处于 `tileCnt=1` 串行基线（Step 2-4 期间配置）。Step 6 的工作是扫描 `tileCnt ∈ {1, 2, 4, 8, 16, 32}`，每个值跑一次 msprof 采集 + 后处理，对比整体 Task Duration 找最优。完整流程见 [`pipeline_tuning.md`](../../shared/pipeline_tuning.md) §3 阶段 B + §6 决策树；
+- **L2 cache flush 必须在主循环每轮触发**：参考工程在 perf 主循环（`src/all_to_all_matmul.cpp` 的 `mode == "perf"` 分支）中每轮先调用 `heavy_add_kernel`（256 MB bf16 全核扫一遍）刷 L2，再跑主 kernel，避免上一轮的热度污染本轮采集——所以 msprof 不需要 `--warm-up`；
+- **perf 模式默认跑 10 轮**：msprof task-based 为每轮 main kernel 生成一条 `op_summary_*.csv` 记录；
+- **多卡数据提取规则**：每卡取最后 5 次 main kernel 的 Task Duration 求平均 → 4 卡平均值取最大值作为整体性能（多卡并行由最慢卡决定）。
+
+### 门禁
+
+- `docs/perf/round_NNN/` 存在且包含 4 个 `PROF_*` 子目录（每卡一份）；
+- `extract_perf.py` 输出每卡 `rank_avg` 与整体 `max` Task Duration；
+- 最优 `tileCnt` 与对应整体 Task Duration 已写入 DESIGN.md "性能调优记录"；
+- 若整体 Task Duration 与理论耗时差距 >50% → 视为性能不达标，检查通算流水是否真的并行（AIV time vs AIC time）。
+
+---
+
+## Step 7：完成汇报
+
+CANNBot 主控汇总以下信息给用户：
+
+- **最终判定**：PASS / PASS WITH NOTES
+- **总分**：Reviewer 100 分制
+- **代码路径**：`operators/{op_name}/`
+- **性能概要**：Task Duration、主导流水（MC2 通常 AIC cube 主导）、通信隐藏率（AIV 与 AIC 重叠度）
+- **关键问题列表**：Step 4~5 期间遗留的 NOTE