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

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/apace/scenarios/put-all-gather-quant-matmul/development.md

@@ -0,0 +1,62 @@
+# 场景开发指导：put-all-gather-quant-matmul
+
+> 前置阅读：[`design.md`](design.md)（设计合同）。本文给出实现模板锚点与验收清单。
+
+## 1. 文件清单与落点（改自官方 AG 算子）
+
+| 文件 | 动作 | 契约 |
+|:---|:---|:---|
+| `kernel/{op}_tiling_data.h` | 新建（改自 `all_gather_mx_matmul_udma_tiling_data.h`） | `AllGatherMxMatmulUdmaTilingData` = `QuantMatmulTilingData mmTile` + `CommTilingData commTile`（**单份**——AG 不像 A2A 有独立 scaleCommTilingData，scale 切分由 kernel 从 mmTile.k 重推导 `scaleKLen = CeilDiv(k,64)×2`）；`#pragma pack(push,8)`+`alignas(8)`；CommContext 包装在 `Apace::AivComm` 命名空间 + 全局 using 导出 |
+| `kernel/{op}_udma_impl.h` | 新建（改自 `all_gather_mx_matmul_udma_impl.h`） | Impl 类（Init 见 design.md §6 布局）+ `AllGatherProcess()`（AIV：预触发 SetFlag(0) + 逐轮 Commit/Wait/SyncAll/SetFlag(round+1) + Finalize）+ `MatmulProcess()`（AIC：组 KernelParams 委托 matmul kernel）+ `__global__` 入口（impl 头末尾，`KERNEL_TYPE_MIX_AIC_1_1`） |
+| `kernel/{op}_kernel.h` | 新建（改自 `qmm_mx_kernel_ag_udma.h`） | `QmmMxKernelAgUdma` 模板类：HEAD/MAIN/TAIL 三区 FragmentTensor + `ResolveTileCtx` + 延迟构建/`UpdateMainRoundAddrs` + `SetL2Cache`（design.md §5 双 gate） |
+| `src/main.cpp` | 新建（改自 AG ST） | host 推导（design.md §3 公式）；AG 无 head_m_size 参数；RunKernel 封装 launch |
+| `scripts/gen_data.py` / `verify_result.py` | 新建 | 纯 numpy 自实现 FP8 编解码（无 ml_dtypes 依赖）；每 rank 独立 seed；bit-exact/1-ULP 判定 |
+
+## 2. 关键实现锚点（官方源码，改造时逐一对照）
+
+| # | 事实 | 锚点 |
+|:---|:---|:---|
+| A1 | 入口 ABI：`__gm__ CommContext*` 首参 + aGM/aScaleGM/bGM/bScaleGM/cGM + tilingData 按值（7 参） | `all_gather_mx_matmul_udma_impl.h:267-271` |
+| A2 | Init 顺序（**与 A2A 不同**）：`InitBaseParams(tilingData)` **先于** ctx 提取；dataRegionBytes/scaleRegionBytes 在 ctx 提取后于 Init 内计算 | 同上 `:128-142` |
+| A3 | AIV 循环：守卫 `GetBlockIdx() < rankSize_` 内 `allGatherScale_.Commit(); allGatherData_.Commit(); allGatherData_.Wait<BARRIER_DEVICE>()`；守卫外 `SyncAll<true>()` + `SetFlag(round+1)`；循环外预触发 `SetFlag(0)` | 同上 `:246-263` |
+| A4 | BarrierMode：data `Init<BARRIER_NONE>` + scale `Init<BARRIER_DEVICE>`（scale 的 Wait 承担跨卡 fence；两对象共 channel） | 同上 `:166-171` |
+| A5 | 三区 FragmentTensor：`MakeFragParam(paddedTailM, tailM, ...)` padding 表达；MAIN 延迟构建 + `UpdateAddrList` 换轮 | `qmm_mx_kernel_ag_udma.h:389-398,523-528,532-555` |
+| A6 | matmul 调用：`mmadFrag(blockA, gmBlockB, blockScaleA, gmBlockScaleB, gmBlockBias, cFragAddrs_, mPerRank, tileM, tileCnt, tailM, rankCnt, Ni, singleShape, regionMPos, nPos, 0, blockC)`（17 参契约详见 [`compute.md`](../../fundamentals/compute.md) §7） | 同上 `:403-406` |
+| A7 | WINDOW_LEN 复定义技巧（调度器窗口=1 非侵入式修改）：`#define WINDOW_LEN 1L` → include `block_scheduler_qbmm.h` → `#undef` | 同上 `:24-26` |
+| A8 | 尾块拆分核数守卫：`(sch.GetEndBlockIdx()+1) * mTailTile * nTailTile <= GetBlockNum()` 才 `UpdateTailTile` | 同上 `:346-348` |
+| A9 | AIC 等待：waitedMask 位去重（含预触发 id 0）+ 收尾 drain `t <= commTurn` **含端点** | 同上 `:370-373,410-414` |
+
+## 3. 验证矩阵
+
+| 维度 | 覆盖 | 判据 |
+|:---|:---|:---|
+| 精度 | rank 2/4/8 × 对齐 M × 非对齐 M（2061/3085 类触发尾块 + paddedTailM padding 路径）× K=32 最小对齐 × m<512 收缩 | bit-exact 或 ≤1 ULP（raw uint16 比较） |
+| golden | 每 rank 独立 seed（`BASE_SEED+rank`）；B DN 落盘 `[N,K]` 不转置、scaleB `[N,K/32]`；AllGather=concatenate | gen_data 双侧校验（K%32、scale 偶数） |
+| T 维度 | tileCnt=1 串行基线 → 多 tile（三区布局/flag 配对仅在 T>1 暴露） | R9/R5 |
+| R>8 变体 | 扩数组后专测 R=16（越界回归） | design.md §6 硬约束 |
+| perf | msprof + L2 flush + parse_prof（官方口径 avg of card avgs + skill 投产另报跨 rank max） | R15/R20 |
+
+## 4. 常见 FAIL 信号与定位
+
+| 现象 | 根因 | 修复方向 |
+|:---|:---|:---|
+| R>8 时数据错乱/越界崩溃 | `cFragAddrs_[8]` 等定长数组静默越界 | 扩数组（design.md §6） |
+| 尾块行数错误/padding 区数据泄漏 | paddedTailM/realFragmentSize 表达错 | FragmentParam 成对设置（A5） |
+| HEAD 区等待挂死 | 预触发 SetFlag(0) 丢失或 AIC 特判跳过 id 0 | 保持统一位掩码路径（A9） |
+| 换轮后读到旧数据 | MAIN 换轮未先 wait 或 UpdateAddrList 顺序错 | 先 wait 再 update（A5） |
+| scale 精度错 | gen_data scaleB 布局/换算错（元素数 vs 字节数） | nonSplitAxisSize 换算 = ka/32；DN 落盘约定 |
+| 照抄 A2A 的 SWAT 开关 | AG 需 `SetOptimizeEnable(false)+SetMTailAlignEnable(true)`（A2A 默认相反） | design.md §3 |
+
+## 5. 合规映射（本场景重点红线）
+
+| 红线 | 本场景落点 |
+|:---|:---|
+| R1/R2 | 入口无 `__schedmode__`；含 `KERNEL_TYPE_MIX_AIC_1_1` |
+| R3 | 变体 dtype 加入口 + host dispatch（官方 AG 单入口仅 E4M3——照抄会被判 FAIL，须自行补） |
+| R4 | `block/`/`tiling/` 零修改（blaze_ext 属 block 层：新变体组件按 R4 纪律评估，优先参数化复用而非改共享层） |
+| R5 | SetFlag(round+1) ↔ WaitFlag 同 idx 配对（含预触发 0） |
+| R12 | UB 静态布局 512×2+32（MakeMemPtr，无 TPipe） |
+| R13 | 通信对象与 TeamBarrier 均 totalJobs=rankSize（官方前 R 核映射） |
+| R14 | 窗口 rank-major data 在前 scale 在后（winOffset=dataRegionBytes） |
+
+> 完整 R1-R21 见 [`review-checklist.md`](../../review-checklist.md)。

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/apace/scenarios/put-all-to-all-quant-matmul/design.md

@@ -0,0 +1,106 @@
+# put-all-to-all-quant-matmul 场景设计指导
+
+> **定位**：本文件是 `put-all-to-all-quant-matmul` 定制扩展场景的唯一设计指导。设计前核对记录的官方未覆盖项语义命中本场景判据时，默认查阅本文件（规则见 [`../index.md`](../index.md)），并据此完成 DESIGN.md 的定制设计；跨场景拼接设计元素须在 DESIGN.md 中显式论证。
+>
+> **场景边界（重要）**：标准 PUT AllToAll+QuantMatmul 需求由官方 kernel `all_to_all_quant_matmul` 直接覆盖，应判 `apace_native`，**不读取本场景**。本场景仅服务官方 kernel 未覆盖的**变体需求**（新 dtype 组合、bias/scale 融合、不同切分轴或编排形态等），准入前提是官方未覆盖项非空且语义命中本场景判据。
+
+## 1. 场景头
+
+| 项目 | 内容 |
+|:---|:---|
+| 场景 ID | `put-all-to-all-quant-matmul` |
+| 支持范围 | PUT 模式 AllToAll+QuantMatmul 的变体扩展，输入 A 按 K 轴按 rank 切分（每卡全 M 行 × 本卡 K 段）、输出按 M 轴分布，UDMA 直调 |
+| 官方参考算子 | `all_to_all_quant_matmul`（`apace/kernel/all_to_all_quant_matmul/`，K 轴切分、UDMA 直调范式来源） |
+| 授权修改范围 | 仅 `kernel/<op>/` 下新建文件；禁止修改 `block/`、`tiling/` |
+| 状态 | 已实现 |
+
+### 准入条件（须全部满足，且与其他场景互斥）
+
+| # | 条件 | 判据来源 |
+|:--|:---|:---|
+| 1 | 通信原语为 AllToAll | Step 2 `requirement_portrait` |
+| 2 | localMatmul 为 QuantMatmul（含 scale） | Step 2 候选组装事实 |
+| 3 | 通信方向为 PUT（通信→计算） | Step 2 需求四要素 |
+| 4 | 核间数据沿 K 轴切分 | Step 2 切分轴事实 |
+| 5 | 通信走 UDMA（非 HCCL windows 直调） | Step 2 ABI 事实（入口含 `CommContext`） |
+| 6 | 存在官方 kernel 未覆盖的 native gap（变体需求） | 设计前核对非空 |
+
+## 2. 消费输入
+
+| 输入 | 来源 | 用途 |
+|:---|:---|:---|
+| `matmul 链路事实` | 设计前核对（内联于 DESIGN.md §0.3） | 提供 M/N/K、dtype、scale 编码、Blaze matmul 链（`BlockMmad` + `BlockScheduler` + `MatmulWithScaleMx`）与 tiling 基线事实，是切分/Win 区/轮次推导的前提 |
+| 官方未覆盖项 | 设计前核对 | 授权本场景的唯一依据 |
+| 通信接口事实 / 入口 ABI 事实 | 设计前核对 | Win 区容量、入口签名、`CommContext` 传递方式 |
+
+## 3. 设计边界（PUT 模式专属合同）
+
+### 3.1 通信与切分合同
+
+| 项目 | 设计结论 | 事实源 |
+|:---|:---|:---|
+| 通信方向 | PUT：AIV 先推数据到远端 Win 区，AIC 从 Win 区读取计算（通信→计算） | `../../fundamentals/communication.md` §3.2 |
+| 编排形式 | 严格分离或时分复用（**前 R 核通信**为官方惯例：`GetBlockIdx() < rankSize` 守卫包裹 Commit/Wait，`SyncAll<true>()` 与 SetFlag 在守卫外全 AIV 执行） | `../../fundamentals/communication.md` §2 AIV 分核惯例 |
+| 切分轴 | 输入 A 按 K 轴按 rank 切分：每 rank 持有**全部 M 行 × 本卡 K/rankSize 列段**（`[M_total, Ka]`，M_total = m×rankSize）；**B 全量复制**（`[K, N]`，R 个 K 段拼接逻辑布局，PUT 模式 B 不切分，见 [`../../fundamentals/architecture.md`](../../fundamentals/architecture.md) §4 B 分布表） | Step 2 `matmul 链路事实` |
+| 通信原语实现 | `CollectiveComm<AllToAll, PUT, AType, TeamBarrier>` → `AllToAllCommPutImpl` | `apace/block/aiv_comm/all_to_all/all_to_all_udma_put.h` |
+
+### 3.2 Win 区布局（两段式）
+
+```text
+本 rank Win 区（commBufferAddrs[rankId]）
+├─ data 段：rankSize × rankDataBytes          ← winOffset = 0
+└─ scale 段：rankSize × scaleKaSize × axisM   ← winOffset = rankSize × rankDataBytes
+rankDataBytes = axisM × axisKa × sizeof(AType)
+```
+
+- data 与 scale 两个通信对象复用同一 Win 区，经 `winOffset` 分段；各对象独立 UB commBuf（512B × 2 + barrier 32B = 1056B）。
+- host 侧必须校验：Win 区需求（data 段 + scale 段）≤ HCCL 内置 buffer 实测容量。
+- 数据区/元数据区分离红线：官方布局 barrier flag 在独立 BARRIER_BUF，Win 数据区从偏移 0 可用；共享布局须按 host 约定偏移跳过头部，三处偏移同源（`../../fundamentals/communication.md` 陷阱 #12）。
+
+### 3.3 通信轮次 T 推导
+
+| 项目 | 公式/结论 |
+|:---|:---|
+| T（commTurn） | `T = splitAxisTileCnt + splitAxisTailCnt`（`GetCommTurn()` 返回值） |
+| 切分不变量 | `切分轴总元素数 = splitAxisTileSize × splitAxisTileCnt + splitAxisTailSize × splitAxisTailCnt` |
+| 两阶段策略 | 精度调试 `tileCnt=1` 串行基线；性能调优扫描 `{1,2,4,8,16}`（官方 cases.csv 实测档位 tileCnt∈[2,8]；上限受下方 commTurn 约束） |
+| 硬上限 | flagId 直接取轮次 tid 时轮次索引 < FLAG_ID_MAX(16) 且避开 SyncAll 保留区（`SyncAll<true>` 占 14，实际安全上界 13；本场景每轮 `SyncAll<true>`）；`waitedMask` 为 uint32 → 通信 tile 总数 ≤ 32 |
+| UDMA 可靠性 | 单轮 PUT 大小**无官方硬上限**（bring-up 期过大单轮曾见间歇失败，边界未定——512KB 量级系 bring-up 经验值；同平台更大单轮亦有稳定实例）。风险提示级：大单轮按 case 复核（连续多轮精度 + 重复 launch 一致性），不作 host 强制拒绝；间歇 FAIL 时优先增大 T（`../../fundamentals/communication.md` 陷阱 #13；R14 口径） |
+
+### 3.4 Flag 编排（PUT）
+
+| 项目 | AIV（通信侧） | AIC（计算侧） |
+|:---|:---|:---|
+| 逐轮动作 | `Commit(scale) → Commit(data) → Wait<BARRIER_DEVICE>() → SyncAll<true>() → SetFlag<0x2, PIPE_MTE3>(tid)` | `WaitFlag<0x2, PIPE_MTE2>(tid)`（经 `UdmaCommWaitPolicy::WaitTile`）后从 Win 读 A[tid] → Matmul |
+| 依赖计算 | — | `CalcDependTileIdx(mPos + blockM - 1, ...)` 推导依赖 tile，`waitedMask` 按位去重，循环末尾尾部兜底 |
+| self 跳过 | DoCommit 跳过 `targetRankId == rankId`；DoWait 仅非 self 执行 `Drain`，barrier 含 self | self 段经本地 GM/Win 直读 |
+| 回压 | 无（PUT 不需要环形回压） | — |
+
+## 4. 联合合同（通信 × 计算组装）
+
+| 项目 | 设计结论 |
+|:---|:---|
+| 组装形态 | AIV 驱动 UDMA PUT 与 AIC Blaze matmul 在同一 kernel 内逐 tile 流水；`Commit()` 非阻塞是重叠关键 |
+| localMatmul 模式 | 默认 `0`（REMOTE-only，官网 ST 基线）；通算并行选 `1`（LOCAL+REMOTE+AtomicAdd，须加 `PipeBarrier<PIPE_ALL>` 修复）；精度优先选 `2`（DEFERRED_SYNC，仅 UDMA impl 可达，L0C 须满足 `baseM × baseN × 4B ≤ 128/256KB`） |
+| 累加语义 | 各 rank 部分和在同一 L0C FP32 累加器累加，计满 `splitKNum` 触发单次 fixpipe → C；L0C 需求与 rankSize 无关 |
+| 核配比 | `KERNEL_TYPE_MIX_AIC_1_1`，禁止 `__schedmode__(1)`；通信核数 = rankSize。TeamBarrier `totalJobs = rankSize`（官方 A2A/AG 惯例：前 R 个通信核各以 `GetBlockIdx()` 作 jobIndex 参与，`teamBarrier_.Init(buf, ctx, rankSize, GetBlockIdx())`，CrossDevice 由 `Wait<BARRIER_DEVICE>` 内建触发，分布式轮询覆盖全部 rank） |
+| 同步面 | 单向通道 AIV→AIC（通信就绪 flag）；PUT 无 AIC→AIV 回压 |
+
+## 5. Step 3 输入/来源前提
+
+| # | 前提 | 不满足时 |
+|:--|:---|:---|
+| 1 | 设计前核对事实已**内联记录于 DESIGN.md §0.3**（含 `matmul 链路事实`、官方未覆盖项非空）；独立 `apace-investigation-report.md` 仅在委托方明确要求时才需（见 step2-investigation.md） | 返回 Step 2 补充调查（最多一次） |
+| 2 | 场景语义命中本场景判据 | 零命中/多命中 → `unsupported` |
+| 3 | 官方参考算子 `all_to_all_quant_matmul` 源码可读（UDMA impl、tiling_data、ST） | 停止并澄清 |
+| 4 | 已读 `../../fundamentals/communication.md`、`../../fundamentals/fusion.md` §2/§3/§4/§5、`../../operator-design/operator-anatomy.md` §3 | 补齐后再设计 |
+
+## 6. 验证合同摘要
+
+| 项目 | 合同要点 |
+|:---|:---|
+| golden 语义 | 设全局逻辑 M 总量 `M_total = m × rankSize`（m 为单卡输出行数）。**输入分布**：每卡持有 A 的本卡 K 段 `[M_total, K/rankSize]`（**全部 M 行 × 本卡 K 列段**，K 轴切分）+ B 全量复制 `[K, N]`（R 段 K 段拼接布局，各卡一致）。**通信语义**：本卡 A 的第 r 个 M 行块（m 行）PUT 给 rank r；收齐后本卡持有自己 m 行对应的全部 K 段。**输出分布**：每卡输出本卡 M 段 `[m, N]`（全局输出 `[M_total, N]` 按 M 轴分布，**不是每卡完整 C**）。golden 公式：`C_r = concat_K(各源 rank 发来的行块) × B`（K 段拼接后单次 matmul，非逐 rank 输出求和）。依据：官方 ST `gen_data.py` `a_local=(M_total, Ka)` + chunk 按 M 行块分发、`main.cpp` 输出 buffer 为 `m×n` |
+| 量化解码 | 设备输入为 MX/FP8 编码字节时，golden 须从最终写入设备的实际字节解码计算；ScaleB 为 DN 布局列主序（host 侧按 `[N, K/32]` C-order 写入，官方 gen_data 已修复此坑） |
+| 精度基线 | 先 `tileCnt=1` 串行基线 PASS，再扫描 tileCnt；nonfinite 门与 dtype 容差按 DESIGN §4.2 |
+| 多卡矩阵 | rankSize 端点 × shape（对齐/非对齐/tail）× tileCnt × dtype 组合 |
+| 性能基线 | 须含 L2 flush 证据；Step 3 不实现、不运行设备、不写设备 PASS |

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/apace/scenarios/put-all-to-all-quant-matmul/development.md

@@ -0,0 +1,74 @@
+# put-all-to-all-quant-matmul 开发指导
+
+> **场景 ID**：`put-all-to-all-quant-matmul`（PUT 模式，AllToAll + QuantMatmul 融合，K 轴切分，UDMA 直调）。
+> 本文档在 Step 3 设计冻结后编译进项目级 PLAN：`implementation_route=apace_custom`、`selected_scenario=put-all-to-all-quant-matmul`，生成 `operators/<operator_name>/docs/PLAN.md`（模板见 [`plan-template.md`](../../operator-design/plan-template.md)）。
+> 官方参考：`all_to_all_quant_matmul`（CANN 内置 apace `kernel/all_to_all_quant_matmul/`），经 CMake `-I` 直引，零复制。
+
+## 1. 有序开发动作（Step 4 只执行 PLAN）
+
+Step 4 不重新设计、不切换候选、不扩大支持域，仅按 PLAN §9.3 `ordered_actions` 顺序执行：
+
+| 顺序 | 动作 | 要点 | 验证 |
+|:---|:---|:---|:---|
+| A1 | 复用官方参考的 Scheduler/Kernel owner 基座 | 以 `all_to_all_quant_matmul` 的 `BlockScheduler`/`BlockMmad` 编排与 `{op}_udma_impl.h`（`Init`/`Run`/`RunAllToAll`/`RunMatmul`/`SetupParams`）为锚点起手，禁止从零写文件 | 静态走查，锚点逐一核对 |
+| A2 | 适配通信对象 `AllToAllCommPutImpl` | 通信对象数 = 2（A data + A scale）共享同一 channel；scale 对象 winOffset = `rankSize × rankDataBytes`；UB 双 commBuf（各 512B）+ barrierBuf；AIV 先 → AIC 后 | 对照 [`communication.md`](../../fundamentals/communication.md) 四段式契约 |
+| A3 | 适配计算内核（`QuantMatmulMxKernel` 或 FragmentTensor） | PUT 默认 vendor 复用 `QuantMatmulMxKernel`（Blaze `BlockMmad` + `BlockScheduler`）；改 FragmentTensor 为例外须 SCALAR 论证（[`fusion.md`](../../fundamentals/fusion.md) §6.2.2）；K 轴切分：`splitKNum`、`MakeLayoutB{}(rankSize*K, N)`、ProblemShape N = 完整 axisN | kernel 编译通过 |
+| A4 | 在具体 `__mix__` 入口补全 C-ready/V-done/slot/final drain | 入口含 `KERNEL_TYPE_MIX_AIC_1_1`（禁 `__schedmode__(1)`）；CrossCore flag idx 配对（C-ready Set ↔ V-done Wait）；slot 环形偏移与 `tileMaxByteSize_` 同源；`DoWait` 末轮 final drain（self rank 跳过 Drain 但仍执行 barrier） | 冒烟：单 rank 输出非全 0 |
+
+失败回退：实现层问题 Step 4 内修复；需改通信方向/Win/Flag 语义/支持域 → 记录 `design_issue` 回 Step 3。
+
+## 2. 文件级契约（[MODIFY]/[REUSE]）
+
+| 文件 | 动作 | 契约 |
+|:---|:---|:---|
+| `kernel/{op}_tiling_data.h` | 新建 | tiling 结构 + `CommContext`（`CommUdmaContext`+`CommUbmemContext`）；含 `localMatmul` 字段；`#pragma pack(push, 8)`+`alignas(8)`，字段顺序即 host-device 契约 |
+| `kernel/{op}_udma_impl.h` | 新建（改自参考 impl） | A1/A2 落地处；`localMatmul==1` 时 `RunLocalMatmul()` → `PipeBarrier<PIPE_ALL>()` → `RunMatmul()`（推荐修复，防 aclError:507015） |
+| `kernel/{op}_quant_matmul_mx_kernel.h` | 新建或直引 | A3 落地处；`LocalParams` 含 `localMatmul`/`matmulMode`/`splitKNum` |
+| `src/kernel_launcher.h` | 新建 | 4 个 dtype 变体入口（E4M3E4M3/E5M2E5M2/E4M3E5M2/E5M2E4M3），每个含 `KERNEL_TYPE_MIX_AIC_1_1` |
+| `src/main.cpp` | 新建（改自参考 ST） | 运行期 dtype dispatch（本 skill 新增红线/生产教训——⚠️ 官方参考 ST 本身**硬编码只 launch E4M3E4M3 入口**，4 变体定义未使用，照抄官方会被 R3 判 FAIL，须自行补 dispatch）；显式 `localMatmul` 赋值；`splitKNum` 规则：localMatmul=1 → `rankSize-1`，0/2 → `rankSize`；host 前置校验在 fork/建链前 |
+| `src/root_info_exchanger.h`、`src/utils.h` | copy_and_adapt | 从参考算子 ST 复制 |
+| `scripts/gen_data.py` / `verify_result.py` | 新建 | golden 语义先行（输入 K 轴切分：每卡全 M 行 × 本卡 K 段 `[M_total, Ka]`；输出 M 轴分布 `[m, N]`，见 design.md §6）；golden float32 高精度路径；固定种子；host 约束双侧校验 |
+| `CMakeLists.txt` / `cases.csv` / `run.sh` | 新建 | `APACE_ROOT` 指 CANN 内置 apace；`hccl_fwk` 用 `--no-as-needed` 包裹；cases.csv 覆盖 T=1/T>1、小 rank、tail 非整除、tile 粒度扫描 |
+| apace 共享层（`block/` `tiling/` `basic/` `utils/`） | [REUSE] 只读 | 禁止复制/篡改，CMake `-I` 直引；算子目录出现共享层副本即 FAIL |
+
+## 3. 验证矩阵（PUT AllToAll 专属）
+
+| 维度 | 要求 | 达标条件 |
+|:---|:---|:---|
+| 精度标准 | `verify_result.py` | `rtol=atol=1e-2`（all_to_all 系容差），多 rank × 多 shape 全 PASS |
+| localMatmul 三态 | 0 / 1 / 2 分支 | localMatmul=1 含 PipeBarrier；三态精度均过 |
+| dtype 覆盖 | 4 变体 | E4M3/E5M2 四组合各自 PASS（dispatch 错误特征：matched_ratio=0% + 误差 36-59%） |
+| 通信对象 | data + scale 双对象 | winOffset 同源；self rank 跳过 Drain 但 barrier 保留 |
+| 单轮 PUT 大小 | ⚠️ 风险提示（非硬上限） | bring-up 期先用小单轮跑通；放大后按 case 复核（无官方上限，边界未定） |
+| tileCnt 策略 | 精度调试期 tileCnt=1 串行基线 → 性能期扫 {1,2,4,8,16} | 切换 tileCnt 必须重调 `GetTilingData`；档位上限受 R9 口径约束（flagId=tid 时轮次索引 < 16 且避开 SyncAll 保留区 14 → 安全上界 13，见 design.md §3.3） |
+| 性能门槛（R15） | 真实大 shape × R=2/4 双档 × 三路径对标归档 | 仅 toy shape 基线 = FAIL |
+| 性能采集 | msprof + 每轮 L2 flush 实接线 | flush kernel 记录数 == 轮数 |
+
+## 4. 常见 FAIL 信号与定位
+
+| 现象 | 根因 | 修复方向 |
+|:---|:---|:---|
+| 死锁 aclError:507015 | localMatmul=1 缺 PipeBarrier，或误加 schedmode | 补 `PipeBarrier<PIPE_ALL>()`；删调度属性 |
+| E5M2 变体 matched_ratio=0% | dispatch 硬编码 E4M3 入口，字节流被错误模板解释 | 4 变体入口 + host 运行期 dispatch 宏 |
+| 精度不收敛、golden 全错 | golden 切分轴/每卡语义写错（输入 K 轴切分、输出 M 轴分布——勿把输出当完整 C） | 先修 gen_data 再怀疑 kernel |
+| 精度"假通过"、大 shape 紊乱 | PUT 数据覆盖 Win 区元数据/barrier 区 | 数据/元数据偏移同源（R14） |
+| 通信时间 ≈ R × 单 target | 通信被臆造约束退化为通信对象 totalJobs=1 串行 PUT | 通信对象改 totalJobs=rankSize（R13 前半） |
+| 运行期间歇 FAIL | 单轮 PUT 字节过大（经验阈值 ~512KB 量级，非硬上限） | 按 R14 风险提示复核单轮大小 + 调小 tile 粒度 |
+
+## 5. 合规映射（本场景重点红线）
+
+| 红线 | 本场景落点 |
+|:---|:---|
+| R1/R2 | 禁 `__schedmode__(1)`/`core_ratio`；每个入口含 `KERNEL_TYPE_MIX_AIC_1_1` |
+| R3 | PUT = 4 dtype 变体入口 + host 运行期 dispatch |
+| R4 | `block/`/`tiling/` 与 CANN 内置版本 diff 一致，零复制 |
+| R5 | C-ready/V-done flag idx 跨核配对（含计数式） |
+| R6 | UDMA 模式入口含 `__gm__ CommContext*` |
+| R7/R8 | 禁 `AscendC::Matmul`、禁 `Hccl::*` 高阶 API |
+| R11 | host 前置校验（整除/对齐/核数下限/Win 容量/flag 峰值），main.cpp 与 gen_data.py 双侧 |
+| R12 | commBuf/barrierBuf 与 TPipe buffer 物理隔离（静态偏移） |
+| R13 | 通信对象 `totalJobs=rankSize` 多核并行 PUT；TeamBarrier `totalJobs` 官方为 `rankSize`（`teamBarrier_.Init(buf, ctx, rankSize, GetBlockIdx())`，前 R 核映射下 CrossDevice 由 `Wait<BARRIER_DEVICE>` 内建触发）。compute-first 后 R 核映射的自研编排可采用 TeamBarrier totalJobs=1 + 显式 CrossDevice 替代，两种映射不得混用 |
+| R14 | Win 数据/元数据偏移 host/kernel 同源（硬红线）；单轮 PUT 大小按 case 复核（风险提示） |
+| R15/R20 | 投产级性能门槛 + L2 flush 实接线（见 §3 验证矩阵） |
+
+> 完整 R1-R20 与 FAIL 诊断见 [`review-checklist.md`](../../review-checklist.md)；改造食谱锚点见 [`development-guide.md`](../../operator-design/development-guide.md) §3.2/§3.3。

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/apace/troubleshooting/failure-navigation.md

@@ -0,0 +1,47 @@
+# apace 路线失败导航（Failure Navigation）
+
+> 按**现象**定位排查方向。每行给出首个失败层分类与应查阅的文档锚点。
+> 本表只做路由：根因细节、修复手法与红线定义以目标文档为准，不在此重复。
+
+## 首个失败层分类
+
+| 分类 | 含义 | 典型信号 |
+|:---|:---|:---|
+| 编译 | 编译/链接阶段失败，未进入设备执行 | 编译报错、API 符号缺失、模板实例化失败 |
+| ABI | host/kernel 接口与二进制契约不一致 | 入口变体错配、dtype 分发错误、参数布局漂移、host 前置校验缺失导致非法配置下发 |
+| 通信时序 | 通信与计算的先后/配对时序错误 | 读到未就绪数据、GET/PUT 可见性错乱、框架原语语义错配 |
+| 同步 | CrossCore flag / 事件 / barrier 配对或计数错误 | 死锁（507015/507014）、flagId 溢出、删同步后偶发错误 |
+| 设备精度 | 设备侧输出与 golden 不符 | matched_ratio 不达标、误差不收敛、部分输出为零 |
+| 性能 | 精度已 PASS，性能不达标或数据不可信 | cube_utilization 低、归约耗时高、perf 数据不可复现 |
+| 通信建链 | HCCL/URMA window 资源建链阶段失败 | Win 分配失败、rank 建链超时、CommContext 与引擎不匹配 |
+
+## 失败导航表
+
+| 现象 | 首个失败层 | 去哪里查 |
+|:---|:---|:---|
+| 死锁（aclError:507015） | 同步 | [`../review-checklist.md`](../review-checklist.md) R1/R5/R12；[`../fundamentals/architecture.md`](../fundamentals/architecture.md) §10 ①（禁 schedmode）；[`../fundamentals/communication.md`](../fundamentals/communication.md) 陷阱 #9（UB 静态区被 TPipe 覆盖）；[`../fundamentals/fusion.md`](../fundamentals/fusion.md) §5（MTE 未排空路径鉴别） |
+| localMatmul=1 MTE 异常 | 同步 | [`../fundamentals/fusion.md`](../fundamentals/fusion.md) §5.4（RunLocalMatmul 与 RunMatmul 之间补 `PipeBarrier<PIPE_ALL>()`） |
+| 精度不达标 | 设备精度 | [`../fundamentals/fusion.md`](../fundamentals/fusion.md) §5（AllToAll 语义）+ §6.2.6（归约 float32 累加）；[`../workflow_integration.md`](../workflow_integration.md) Step 6（精度验收流程）；[`../review-checklist.md`](../review-checklist.md) 常见 FAIL 原因 |
+| golden 全错、误差不收敛 | 设备精度 | [`../workflow_integration.md`](../workflow_integration.md) Step 2 §golden 语义（先核对每卡输入/输出与切分轴，再怀疑 kernel）；[`../operator-design/host-and-testing.md`](../operator-design/host-and-testing.md)（gen_data 工程侧）；先修 golden 再怀疑 kernel |
+| T=1 全 PASS、T>1 精度错 | 设备精度 | [`../fundamentals/fusion.md`](../fundamentals/fusion.md) §3.3/§6.2.3（多 tile 布局与 flag 逐轮计数配对）；按 tile/轮次定位超差分布 |
+| 编译失败 / API 符号缺失 | 编译 | [`../operator-design/development-guide.md`](../operator-design/development-guide.md)（工程搭建与依赖）；核对 CANN 内置 apace 事实源版本 |
+| Blaze matmul 排错 | 编译 | [`../fundamentals/compute.md`](../fundamentals/compute.md) §8 排错速查；[`../review-checklist.md`](../review-checklist.md) R7（禁 `AscendC::Matmul` 高阶 API） |
+| 通信时序错误 | 通信时序 | [`../fundamentals/communication.md`](../fundamentals/communication.md) 陷阱表；[`../fundamentals/fusion.md`](../fundamentals/fusion.md) §3（GET/PUT flag 编排不变量） |
+| flagId 计数器溢出（硬件异常中断） | 同步 | [`../fundamentals/fusion.md`](../fundamentals/fusion.md) §3.3/§6.2.3（flagId ∈ [0,15] 硬件数量上限 + Set/Wait 严格配对规避；计数深度按 R9 口径不设数值拒绝）；[`../review-checklist.md`](../review-checklist.md) R9 |
+| tail tile 非对齐精度问题 | 设备精度 | [`../fundamentals/fusion.md`](../fundamentals/fusion.md) §6.2.7（尾块策略 A：padding 对齐 + realFragmentSize 限读）；[`optimization-playbook.md`](optimization-playbook.md) §4 |
+| 归约性能差 | 性能 | [`../fundamentals/fusion.md`](../fundamentals/fusion.md) §6.2.6（多行批量归约 + 2D DataCopyPad）；[`optimization-playbook.md`](optimization-playbook.md) §2 |
+| 死锁（aclError:507014，归约路径） | 同步 | [`../fundamentals/fusion.md`](../fundamentals/fusion.md) §6.2.6 纪律 1 + [`../scenarios/compute-first-reduce-scatter/development.md`](../scenarios/compute-first-reduce-scatter/development.md) §5.3 事件模板（四类 HardEvent 同迭代配对 + 残留事件消费）；[`../review-checklist.md`](../review-checklist.md) R19 |
+| E5M2 变体精度全错 | ABI | [`../review-checklist.md`](../review-checklist.md) R3；[`../operator-design/development-guide.md`](../operator-design/development-guide.md) §3.5（4 变体入口 + host 运行期 dtype dispatch）；[`../operator-design/operator-anatomy.md`](../operator-design/operator-anatomy.md) |
+| N>redUbN 时部分输出为零 | 设备精度 | [`../fundamentals/fusion.md`](../fundamentals/fusion.md) §6.2.6 纪律 3（2D DataCopyPad strided 隐式上限，redUbM ≤ 32 或 1D 退化） |
+| 归约结果系统性错误 | 设备精度 | [`../fundamentals/fusion.md`](../fundamentals/fusion.md) §6.2.6 纪律 2（禁 in-place BF16→FP32 Cast，独立 srcFP32 双缓冲）；[`../review-checklist.md`](../review-checklist.md) R18 |
+| perf 数据不可复现 / MTE2 带宽虚高 | 性能 | [`../operator-design/host-and-testing.md`](../operator-design/host-and-testing.md) §4（L2 flush 实接线模板）；[`../review-checklist.md`](../review-checklist.md) R20 |
+| 大 shape 无法运行 / 间歇 FAIL | ABI | [`../operator-design/development-guide.md`](../operator-design/development-guide.md) §3.5（host 前置校验：正确性类整除/对齐/核数/Win 容量；单轮 PUT 大小按 R14 风险提示复核，非强制拒绝；R ≤ 32 为 fragment 数上限，R×T 无硬约束）；[`../fundamentals/communication.md`](../fundamentals/communication.md) 陷阱 #12/#13 |
+| cube_utilization 低 | 性能 | [`optimization-playbook.md`](optimization-playbook.md) §2（CUBE bound 判据与手法）；[`../fundamentals/fusion.md`](../fundamentals/fusion.md) §6.2.2（R×T 子调用 SCALAR 主 bound 特征） |
+| GET 模式 4+rank 不稳定 | 通信时序 | [`../fundamentals/fusion.md`](../fundamentals/fusion.md) §3.4/§6.2（GET 环形回压契约与 4+rank 数据可见性风险，计算在前场景优先 PUT）；[`../fundamentals/communication.md`](../fundamentals/communication.md) GET 契约 |
+| 仅非对齐 shape 精度 FAIL | 设备精度 | [`optimization-playbook.md`](optimization-playbook.md) §4（tail 路径排查模式）；[`../fundamentals/fusion.md`](../fundamentals/fusion.md) §6.2.7 |
+| 精度误差随 K 放大 | 设备精度 | [`optimization-playbook.md`](optimization-playbook.md) §4（累加位宽不足，先高精度中间累加保底） |
+| 重构后某维度性能退化 | 性能 | [`optimization-playbook.md`](optimization-playbook.md) §4/§2（数同步次数，批量摊薄） |
+| 复用框架通信原语大面积错数据 | 通信时序 | [`optimization-playbook.md`](optimization-playbook.md) §4/§3（work partition 地址偏移语义核对，targetRank vs sourceRank） |
+| 删减 SyncAll 后 NaN/偶发错误 | 同步 | [`optimization-playbook.md`](optimization-playbook.md) §4（同步是正确性保障不可裁剪）；[`../fundamentals/fusion.md`](../fundamentals/fusion.md) §3 |
+| 性能优化无从下手/无收益 | 性能 | [`optimization-playbook.md`](optimization-playbook.md) §1（阶段路径，勿跳级）/§2（现象→手法速查）/§5（实验纪律） |
+| 静态分析判定"不可行"但有争议 | 性能 | [`optimization-playbook.md`](optimization-playbook.md) §5（实证复核原则：最小实验复核，"原假设 vs 实测结果"对照归档） |

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/apace/troubleshooting/optimization-playbook.md

@@ -0,0 +1,143 @@
+# apace 算子优化手册（Optimization Playbook）
+
+> 本文档沉淀 apace 算子从"能跑"到"跑好"的通用方法论：开发/优化阶段路径、现象→手法速查、失败案例教训、排查模式与实验纪律。内容来自生产算子的多轮优化演进复盘，已全部泛化——不绑定任何单一算子的实现细节与调参数值。
+>
+> 性能采集方法（msprof/L2 flush/多卡后处理）见 [`../shared/profiling_mc2.md`](../../../shared/profiling_mc2.md)；tileCnt 两阶段策略见 [`../shared/pipeline_tuning.md`](../../../shared/pipeline_tuning.md)。本文档不重复，只讲"什么时候用什么手法、怎么验证、怎么避坑"。
+
+## 目录
+
+1. [开发/优化阶段路径](#1-开发优化阶段路径)
+2. [现象→手法→触发条件速查](#2-现象手法触发条件速查)
+3. [失败案例教训（已证伪的方向）](#3-失败案例教训已证伪的方向)
+4. [通用排查模式（现象→根因→修法）](#4-通用排查模式现象根因修法)
+5. [实验纪律](#5-实验纪律)
+6. [评审意见落地模式](#6-评审意见落地模式)
+
+---
+
+## 1. 开发/优化阶段路径
+
+apace 算子的成熟过程遵循固定顺序，**不要跳级**（如在精度未达标时做性能优化，或在串行基线未建立时做流水重叠）：
+
+```
+① 可运行基线（精度优先，tileCnt=1 串行）
+   → ② 精度修复（多 shape × 多 rank 全量 PASS）
+   → ③ 验收归档基线性能（msprof round_001，作为后续所有对比的锚点）
+   → ④ 架构级优化：通算流水重叠（收益最大，先做）
+   → ⑤ 参数级调优：tiling / tile 粒度 / 通信粒度
+   → ⑥ 热点子模块重写：op_summary 定位占比最高的子模块
+   → ⑦ 微优化：双缓冲、去冗余指令、自适应参数
+   → ⑧ 穷尽分析：确认无剩余空间，失败尝试同样归档
+```
+
+各阶段判据：
+
+| 阶段 | 进入条件 | 退出条件 |
+|:---|:---|:---|
+| ① 基线 | 工程搭建完成 | 单 rank 冒烟输出非全 0 |
+| ② 精度 | 基线可运行 | 全量用例 PASS（含 tail 非对齐、多 commTurn 场景） |
+| ③ 基线性能 | 精度全 PASS | msprof 数据归档到 `docs/perf/round_001/` |
+| ④ 流水重叠 | 基线性能已归档 | 通信耗时被计算掩盖（AIV time ≤ AIC time） |
+| ⑤ 参数调优 | 流水已建立 | tileCnt/tile 粒度扫描到 Task Duration 最小值 |
+| ⑥~⑦ 模块优化 | op_summary 有明确热点 | 单轮收益 ≥ 噪声水平（否则停止） |
+| ⑧ 穷尽分析 | 连续多轮无收益 | 输出优化空间分析报告，成功与失败尝试均归档 |
+
+**每轮优化必须绑定精度验证**：性能提交与"N/N case ALL PASS"证据同时落地，防止性能优化悄悄破坏精度。
+
+---
+
+## 2. 现象→手法→触发条件速查
+
+按 op_summary 流水指标定位瓶颈，再选手法。**先判主导流水（CUBE/MTE2/V/FIXPIPE 谁最高），再动手**。
+
+| 现象（判据） | 手法 | 触发条件与注意事项 |
+|:---|:---|:---|
+| AIC 计算与 AIV 通信串行，总时长 ≈ 两者之和 | per-tile 流水重叠：AIC 逐 tile `CrossCoreSetFlag` / AIV 逐 tile `CrossCoreWaitFlag` + 通信 | 计数式 flag 的 Set/Wait 必须严格配对；计数器 0-15 衡量未消费积压、不构成 T 上限（R9 口径——不设数值拒绝）；`tileCnt=1` 应自然退化为串行，便于回退对比 |
+| tiles/core ≈ 1，cube_utilization 低，CUBE bound | 减小 baseM（如对 SWAT tiling 结果做减半后处理 256→128），增加 tile 数提升核间负载均衡 | 触发条件：SWAT 在 `blockNum ≥ aicNum` 时不触发 `AdjustBasicBlock()`、输出 `baseM==256` 且减半后满足 M 轴整除；⚠️ 副作用：DMA 次数随之增多（MTE2 上升），**仅 CUBE bound 时值得**；baseM 必须保持 CUBE_BLOCK(16) 整数倍；减半后须重置 M 尾块参数（`mTailTile=1, mBaseTailSplitCnt=1, mTailMain=0`）并验证 L1 buffer 安全（`stepK`/`scaleKL1`/`nBufferNum` 不变仍有效） |
+| 仅个别核干活，其余核空转（如后处理只跑 block 0） | 多核并行：按 blockIdx 均分任务 + 余数前摊 | 后处理类 AIV 工作默认应全核参与；先确认任务可分行/分块且无跨核依赖 |
+| 自研基础模块（如归约/拷贝）性能差 | **优先找同生态已验证的参考实现整体替换**，只适配语义差异，而不是继续微调自研版 | 这是历史上单轮收益最大的手法（2 倍以上）；替换后用同一基线量化验证 |
+| 同步次数随某维度（rank 数/行数/tile 数）线性增长，该维度大时性能退化 | 批量摊薄：利用 MTE2/V/MTE3 流水 FIFO 性，一批数据只做 1 次 SetFlag/WaitFlag；批大小按 UB 容量自适应 | "重构后某维度退化"几乎必然指向同步开销；先数同步次数再改代码 |
+| MTE2 加载与 V 计算串行 | pingpong 双缓冲：输入 buffer 双份，按计数奇偶交替 | 累加器等有语义依赖的 buffer **保持单份**，不能盲目复制 |
+| V 指令链路过长（如 低精度→Cast→Add→Cast回） | 去冗余 Cast：用硬件原生低精度运算直接累加 | ⚠️ 触发条件苛刻：**仅当目标平台硬件级低精度累加的精度已实测达标**才能去掉高精度中间累加；必须先用高精度版本保底（见 §4 精度排查模式）。另需先确认该模块未被流水掩盖——被掩盖模块降精度实测收益趋近于零，而精度风险随 rank/配置漂移，生产上曾因此回退 |
+| 固定 tile 粒度在小分片场景（如多 rank）效率低 | 自适应 tile 粒度：host 按 rank 数/shape 分档选择首 tile 大小 | 本质是"同步次数 vs 流水粒度"的权衡：分片小→减小 tile 让通信尽早启动；分片大→增大 tile 减少同步。**分档值只是起点**——异常 case（tileCnt 非最优、SyncAll 占比偏高、GM 带宽争抢特征）需 per-case 搜索首 tile 大小，判据用通信覆盖率与收益实测；具体分档阈值需按平台实测标定，不跨平台/case 复用单点数值 |
+| 通信核与计算核互等 | 角色错峰：通信核发通信时，其余核算上一 tile 的残留工作 | 需要跨核同步点（SyncAll）配合；同步次数不可裁剪（见 §4）。compute-first 下进阶形态：fragment 重排 [remote..., local] + 双 flag（remote done 提前启动通信），见 [`fusion.md`](../fundamentals/fusion.md) §6.2.3 双 flag 计数式 |
+| 通信与归约串行排队（时分复用），AIV 侧成为关键路径 | **通信/归约核严格分离（专职化）**：后 rankSize 核专职通信（通信对象 totalJobs=rankSize，每核 1 个 target 并行 PUT）、前 (核数-R) 核专职归约，`AllToAll(t) ∥ Reduce(t-1)` 错位流水，无 Phase 2 | 收益稳定（R 越大越显著）：消除 Phase 2 串行的收益大于归约算力减少 R 核的代价。⚠️ 反面教训：通信对象退化为单核（臆造"多核写同一 UBMEM flag 竞态"约束）会让 R 个 target 串行 PUT，通信时间放大 R 倍——该竞态约束不存在；TeamBarrier totalJobs 按分核映射取值（官方前 R 核映射 = rankSize；compute-first 后 R 核映射 = 1 + 显式 CrossDevice，见 [`communication.md`](../fundamentals/communication.md) §2.2） |
+| 通信等待含框架内建跨设备 rendezvous，与分核守卫耦合 | **BARRIER_NONE + 手动 CrossDevice**：`Wait<BARRIER_NONE>` 仅 Drain 本 block channel，SyncAll 后由 block 0 显式 `teamBarrier_.CrossDevice()`，再一次 SyncAll 放行 | 多核并行通信 + 严格分离编排的配套手段；同步点显式可控（见 [`fusion.md`](../fundamentals/fusion.md) §6.2.3） |
+| 归约（reduceSum）模块本身耗时高，逐行处理 flag 次数多 | **手动 UB + 多行批量归约**：LocalTensor 手动偏移布局（FP32 累加器单份 + src 双缓冲 pingpong + 输出 buffer），一次处理多行摊薄 flag 次数 | 显著摊薄同步开销；per-tile 高频调用场景避免 TPipe 重复 InitBuffer 耗尽 UB（归约 buffer 循环外一次性分配） |
+| 归约 VEC 占比异常低但 flag/同步次数频繁 | **逐行归约（blockCount=1）**：flag/同步次数 = 行数 × N段数 × R | 改批量：2D DataCopyPad blockCount=本批行数（多行一次搬运），flag 次数除以 batchRows 摊薄——量化判据：逐行归约 = 性能 FAIL（见 [`fusion.md`](../fundamentals/fusion.md) §6.2.6） |
+| AIC SCALAR 占比异常高、CUBE 反而很低 | **R×T 子 mm 调用的 Params 重建开销**：检查是否每轮循环重建完整 Params | 改 FragmentTensor 一次调用消 R 循环，或减少 T（增大 tileM），或 Params 增量更新只改地址字段；小/中 shape 下 SCALAR 易成为主 bound（见 [`fusion.md`](../fundamentals/fusion.md) §6.2.2）。⚠️ 反向认知：小 R×T 时两者性能持平，FragmentTensor 的价值在代码统一与 per-fragment L1 隔离——SCALAR 红线针对大 R×T 才成立 |
+| 重复构建地址/描述符 | 增量复用：按轮次索引递推偏移，而非每轮重建 | 适用于 FragmentTensor 地址表、GM 指针族 |
+| mac_ratio 高但 cube_utilization 低 | 瓶颈在**数据供给（MTE2 带宽）而非计算**：MAC 在等数据。优化搬运链路（双缓冲、L2 footprint、布局），不要再压计算侧 | 经典误判点：mac_ratio 高 ≠ 计算 bound；结合 cube_util 与 mte2_ratio 构建 GM→L1→L0→L0C→GM 搬运链路图定位 |
+| L2 footprint 超容量、cache 命中低（大 shape 明显） | **problem 维度拆分子调用**：tile 大小不变、只缩 problem M（如 R×T 子调用），L2 footprint 缩小 → cube 利用率提升，大 shape 实测显著收益 | ⚠️ 与"拆小 tile"严格区分：后者 MTE2 次数翻倍，已证伪（§3）。拆分不得增加单位数据的搬运次数 |
+
+---
+
+## 3. 失败案例教训（已证伪的方向）
+
+以下方向在生产算子上实测**无收益或负收益**，遇到相同现象时不要再试：
+
+| 尝试 | 结果 | 通用教训 |
+|:---|:---|:---|
+| 增大 L0C 双缓冲深度（如 dbL0c=2） | fixpipe 时间反而上升 | L0 是稀缺资源，加深缓冲会与对侧 buffer 竞争空间 |
+| 增大 stepK（K 方向步进） | 无收益 | **当两条 pipe 已高度重叠（≥90%）时，减少任何一侧的次数都无收益**——先看重叠率再决定优化对象 |
+| 减小 baseN 提升 cube_util | 整体恶化 | fixpipe/DMA 的**固定开销随 tile 数线性放大**，cube_util 收益被抵消。减小 tile 前必须评估固定开销占比 |
+| 把框架通信原语的多核 work partition 直接套到语义不同的场景 | 大面积数据错误后回退 | 复用框架原语前必须核对**地址偏移语义**（work partition 按 targetRank 还是 sourceRank 切分）；语义不匹配就换优化维度，不要死磕框架 |
+| 通信退化为单核（仅 blockIdx==0 执行 Commit/Wait），理由"避免多核写同一 UBMEM flag 竞态" | R 个 target 串行 PUT，通信时间放大 R 倍；R≥4 且真同步时暴露死锁竞态 | **该竞态约束是臆造的**：TeamBarrier 按 job 分槽写入，无共享 flag 竞态；TeamBarrier totalJobs 按分核映射取值（见 [`communication.md`](../fundamentals/communication.md) §2.2）。设计阶段引入"约束"前必须在 skill/官网代码中找到实证来源 |
+| 用 `SyncAll` 替代跨设备 fence | 接收方在远端 PUT 到达前读未初始化数据（大面积元素错） | **SyncAll 是本地核间同步，无跨设备能力**——跨设备可见性只能走框架 CrossDevice（TeamBarrier），本地同步加多少次都无效 |
+| 手动轮询远端 GM flag 做跨设备同步 | 死循环超时 | **MTE 跨设备 GM 写可见性无框架 fence 保证**（本端 MTE2 读看不到远端 MTE3 写）——手动跨设备轮询不可行，须用框架 CrossDevice |
+| PUT/GET 数据覆盖 Win 区内元数据/barrier 区 | 精度"假通过"（碰巧正确），同步机制已被破坏，大 shape/多轮时紊乱 | 数据区与元数据区分离：官网布局 barrier flag 在独立 BARRIER_BUF（Win 数据区从 0 可用）；共享布局按约定偏移跳过头部，host 预留与 kernel 读写偏移同源——此类"假通过"最危险：精度验证无法发现，必须靠设计红线拦截 |
+| 单轮 PUT 数据量过大 | bring-up 期过大单轮曾见间歇失败（边界未定，非普适上限；同平台亦有更大单轮稳定运行的工程实例） | 无官方上限，勿以经验阈值做 host 强制拒绝；放大单轮后按 case 复核（连续多轮精度 + 重复 launch 一致性）；可靠性边界与带宽高效区间是两回事，不要混用 |
+| 为增加通算重叠把 tile/K-window 数翻倍（拆小 tile） | MTE2 次数翻倍至饱和，负收益回退 | 重叠收益要靠**拆 problem 维度**（tile 大小不变）获得，不能靠增加单位数据的搬运次数；改之前先看 MTE2 余量 |
+| local 段前置/后置重排以期通信提前启动 | 通信被计算完全掩盖的算子收益 ≈ 0 | **重排类优化先 profiling 确认瓶颈归属**（AIV WaitFlag 占比高 ⇒ 跳过重排）；仅通信暴露场景有收益。注意：compute-first 的 localLast 编排因 flag 配对契约依赖仍须保留，此处针对"额外重排"类提议 |
+
+---
+
+## 4. 通用排查模式（现象→根因→修法）
+
+| 现象特征 | 根因方向 | 修法 |
+|:---|:---|:---|
+| **仅非对齐 shape 失败**，其余全部 PASS | tail 路径：尾块不被 tile 粒度整除，matmul 产出垃圾数据 | tail 单独 tiling + padding 到对齐边界 + 用 real size 字段限制实际读取范围；**host 侧内存分配必须与 kernel 实际读取范围一致**（详见 [`fusion.md`](../fundamentals/fusion.md) §6.2.7） |
+| **精度误差随 K（或累加维度）放大**（小 K PASS、大 K FAIL） | 累加位宽不足，低精度累加误差随累加长度线性放大 | 先升高精度中间累加保底（如 BF16→F32→Add→Cast回）；降回低精度须同时满足：全量配置（含大 rank 数）实测达标 + 收益显著（未被流水掩盖），并保留回退开关 |
+| **重构后某维度性能退化**（其余维度正常） | 同步/flag 次数随该维度线性增长 | 数清每单位数据的同步次数，改批量处理摊薄（见 §2） |
+| **复用框架通信原语后大面积元素错误**（非边界、非尾块） | work partition 地址偏移语义与算子语义不匹配 | 读框架实现的偏移公式（按 targetRank 还是 sourceRank）；不匹配则回退单核通信基线，改从其他维度（后处理多核化等）要性能 |
+| **删减跨核同步后出现 NaN / 偶发错误** | SyncAll 保障跨核数据可见性，次数不可裁剪 | 恢复同步点。同步是正确性保障不是性能开销，优化同步前先证明数据依赖已消除 |
+| **少量元素错位/超差，分布无明显 tile 规律** | 参数误传：行步长/计数值等参数语义与签名不符（如行步长误传为段高、tile 计数误传 0） | **先逐参数核对调用点与签名的语义**（单位、轴、起算点），再怀疑算法；此类 bug 占比高且排查成本低 |
+| **越界/踩数据，地址看似正确** | 同一地址偏移在多处独立计算，两处公式漂移 | 地址偏移**单一来源**：派生量在一处计算后传递，不在多个文件各算一遍 |
+| **wall-clock 测得 kernel 极快（微秒级）但与 msprof 矛盾** | `<<<>>>` 是异步 launch，wall-clock 只测到下发开销 | 性能结论只以 msprof device 侧 Task Duration 为准（见 [`../shared/profiling_mc2.md`](../../../shared/profiling_mc2.md)） |
+| **统一分支路径后出现全零/未初始化数据** | 原 if/else 掩盖了退化路径的初始化遗漏 | 统一路径是好事——它会暴露退化路径的初始化 bug；补齐退化路径的 tiling/参数初始化 |
+
+---
+
+## 5. 实验纪律
+
+性能优化是实验科学，每条优化假设都按"可证伪的实验"执行：
+
+1. **单变量**：每轮只改一个变量（一个手法、一个参数），否则无法归因
+2. **同一锚点**：所有对比都相对同一个归档基线（`docs/perf/round_001/`），不相对"上一轮"链式对比（误差会累积）
+3. **稳态取值**：丢弃 warmup 轮次取稳态均值；多卡场景跨 rank 取 max（木桶效应）——采集细则见 [`../shared/profiling_mc2.md`](../../../shared/profiling_mc2.md)
+4. **量化回退**：不达标就回退，**回退提交同样记录量化数据**（R5/R6/R7 式编号留档），证明"试过、为什么不采用"
+5. **失败也归档**：负收益尝试与成功尝试同等篇幅写进优化报告，防止后人重复踩坑（§3 即来源于此）
+6. **精度绑定**：每轮 perf 提交附带全量精度 PASS 证据
+7. **穷尽收尾**：确认无剩余空间时输出分析报告（含理论耗时对比、各路流水占比、已证伪方向清单），作为算子的性能档案
+8. **实证复核**：静态分析得出的"不可行/无收益"结论，在有争议或收益量级不明时应设计最小实验复核（典型：拆 problem 维度的收益主因常是 L2 footprint 效应，静态分析易遗漏）。被推翻的假设是有价值的档案，不隐瞒
+9. **选择性路由**：一个手法只对部分 case 有效、对其他 case 退化时，不做统一开关，按 case 特征（rank 数/tile 粒度/shape 规模/bound 类型）路由到不同方案，保留各方案的局部收益
+
+---
+
+## 6. 评审意见落地模式
+
+评审意见（尤其是重构类）的落地方式是**"语义等价的高性能实现 + 量化回退机制"**，不是字面执行：
+
+1. 逐条实现评审意见，每条用同一基线量化对比
+2. 字面实现性能退化时，**诚实回退并记录数据**，然后寻找满足评审意图的替代实现（典型：为消除循环的"一次全覆盖"实现若实测回退，可改用 FragmentTensor 打包分段地址实现同等意图）
+3. 阻塞项（正确性/红线）修完即 PASS；建议项按收益排期
+4. 重构多发期主动做一次**设计文档 vs 代码的一致性核对**，防止文档腐化（文档与实现漂移会误导后续所有优化决策）
+
+---
+
+## 后续阅读
+
+- [`../shared/profiling_mc2.md`](../../../shared/profiling_mc2.md) — 性能采集与多卡后处理细则
+- [`../shared/pipeline_tuning.md`](../../../shared/pipeline_tuning.md) — tileCnt 两阶段策略
+- [`fusion.md`](../fundamentals/fusion.md) — 通算融合编排模式与硬限制
+- [`development-guide.md`](../operator-design/development-guide.md) — 工程改造食谱与验收清单

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/apace/workflow/step1-project-setup.md

@@ -0,0 +1,52 @@
+# Step 1: Project Setup
+
+> **定位**：建立算子工程骨架、校验 CANN 内置 apace 事实源与环境、登记只读参考点。Step 1 只做环境验证与目录创建；不核对接口事实、不判定路线、不创建算子实现文件。
+>
+> 父级流程定义以 `plugins-official/ops-direct-invoke/AGENTS.md` 为准；本文件只补充 apace 场景的差异化要点，不重写父级规则。plugin 场景下本步骤对应 plugin Step 1（环境检查），7 步门禁细则以 [`../workflow_integration.md`](../workflow_integration.md) 为准。
+
+## 1. 环境检查（门禁）
+
+### apace 场景额外校验
+
+校验项表与路径实测纪律以 [`../workflow_integration.md`](../workflow_integration.md) Step 1「apace 场景额外校验」为唯一事实源，本文件不重复（防止双写漂移）。其中"CANN 内置 apace"一项的物理路径形态以 `test -d` 实测登记为准（随 CANN 版本漂移）。
+
+### 门禁
+
+环境检查全部通过 → 进入 Step 2。任何一项失败禁止进入 Step 2。
+
+## 2. 项目目录创建
+
+创建算子根目录与最小空目录结构；kernel、host、脚本与测试文件均不在本步生成，留待 Step 3 的 PLAN 确定后再创建。
+
+```
+operators/{OpName}/            ← camelCase（对齐 CANN 算子注册名）
+├── docs/
+│   ├── DESIGN.md               # Step 3 输出
+│   └── PLAN.md                 # Step 3 输出
+├── kernel/                     ← [MODIFY] 本算子 kernel 头文件
+├── src/                        ← [MODIFY] host 侧
+├── scripts/                    ← [MODIFY] gen_data.py / verify_result.py / parse_perf.py
+├── data/
+│   ├── input/
+│   ├── golden/
+│   └── output/
+├── CMakeLists.txt
+└── cases.csv
+```
+
+> 共享层 `block/` `tiling/` `basic/` `utils/` **不复制、不出现在算子目录**——经 CMake `-I` 直引 CANN 内置路径。参考 kernel（`quant_matmul_mx_kernel.h`、`comm_channel_builder.h` 等）同样直引。
+
+## 3. 只读参考点
+
+| 参考点 | 路径 | 用途 |
+|--------|------|------|
+| CANN 内置 apace 框架 | 实测定位（`test -d`；两种已验证形态：`opp/built-in/op_impl/ai_core/tbe/impl/ops_transformer/ascendc/common/apace/`、`vendors/custom_transformer/op_impl/ai_core/tbe/custom_transformer_impl/ascendc/common/apace/`） | 编译事实源，CMake 直引 |
+| ops-transformer 仓（可选） | 经 `scripts/fetch_apace.sh` 获取 | 跟踪 master 新特性 / 核对最新契约，使用前必须与内置版本 diff 校验 |
+| 参考算子 | `kernel/all_to_all_quant_matmul/`、`kernel/all_gather_quant_matmul/` | 实现模式参考 |
+
+## 4. 不做的事
+
+- 不核对 apace 框架的接口组合候选（Step 2 职责）
+- 不选择实现路线（Step 3 职责）
+- 不创建场景实现文件（Step 4 职责）
+- 不提前编写公式、Tiling、golden 或任何固定工程模板

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/apace/workflow/step2-investigation.md

@@ -0,0 +1,89 @@
+# Step 2: 设计前核对（轻量检查清单）
+
+> **定位**：设计前的源码事实核对清单。**默认将核对事实内联记录于 DESIGN.md §0.3**，**不要求独立调查报告文件**；仅在设计委托方明确要求时才产出独立 `apace-investigation-report.md`。不做方案推荐、不匹配场景、不选择路线、不编译或运行设备。
+>
+> plugin 场景下本步骤在 plugin Step 2（设计）内由 Architect 完成，不产生独立交付物。
+
+## 1. 需求四要素（设计三拷问的事实化）
+
+动手核对源码前，先把需求落成可对照的四要素（对应方法论原则 2「设计三拷问」）：
+
+| 要素 | field id | 说明 | 示例 |
+|------|------|------|------|
+| golden 语义 | `golden_semantics` | 每卡输入/输出分布与切分轴（**输入分布轴与输出分布轴分别冻结**） | 输入：每卡完整 A（K 不切分）；输出：按 M 轴聚合 → [M/R, N] |
+| 通信方向 | `communication_direction` | GET / PUT / compute-first | PUT（通信→计算） |
+| 编排形态 | `orchestration` | 严格分离 / 时分复用 | 严格分离（后 R 核通信 / 前核归约） |
+| dtype/shape/rankSize | `dtype` / `shape` / `rank_size` | 输入/累加/输出 dtype、逻辑 shape、rank 数 | FP8_E4M3 × FP8_E4M3 → BF16，M=2048，R=4 |
+
+> **四要素提取不到时必须澄清**：golden 语义的"每卡输入分布"无法从用户需求唯一确定时（典型：用户说"每卡有 M/rankSize"但未说明是输入切分还是输出分布），**必须回 [`requirement-analysis/grill-protocol.md`](../../../requirement-analysis/grill-protocol.md) 维度 9 向用户追问**，禁止默认假设后直接进入源码核对。
+
+## 2. 源码核对范围（只读）
+
+只读核对 CANN 内置 apace 框架路径（Step 1 实测登记值；两种已验证形态：`opp/built-in/op_impl/ai_core/tbe/impl/ops_transformer/ascendc/common/apace/`、`vendors/custom_transformer/op_impl/ai_core/tbe/custom_transformer_impl/ascendc/common/apace/`），禁止 clone、更新、切换源码：
+
+```
+apace/
+├── basic/          # 基础数据结构与抽象（fragment_tensor/：FragmentTensor/MakeFragmentTensor/FragmentSliceCopy）
+├── block/          # 接口层
+│   ├── aiv_comm/
+│   │   ├── collective_comm_api.h    # 四段式通信 API 契约 + CommCollectiveOp/CommMode 分发
+│   │   ├── all_to_all/              # AllToAll GET/PUT 钩子
+│   │   ├── all_gather/              # AllGather PUT 钩子
+│   │   └── barrier/                 # TeamBarrier（barrier_ubmem.h）
+│   ├── blaze_ext/                   # Blaze 扩展（gemm/block/qmm_mx_block_mmad_fragment.h——FragmentTensor 路径的 MMAD 组件，AG 类算子必查）
+│   └── aiv_compute/                 # AIV 计算接口（⚠️ 空占位——量化/反量化/规约组件规划中，勿假定存在）
+├── kernel/         # 官方算子实现（可直接调用或参考）
+│   ├── all_to_all_quant_matmul/     # PUT AllToAll + QuantMatmul（UDMA 版 + hcomm/CCU 注册形态版）
+│   └── all_gather_quant_matmul/     # PUT AllGather + QuantMatmul（FragmentTensor 三区）
+├── tiling/         # tiling 算法（quant_matmul_tiling_{base,common,data,swat}.h + comm_tiling_data.h）
+└── utils/          # 通用工具与常量（constant.h + host 侧 comm_channel_builder.h）
+```
+
+可选：经 `scripts/fetch_apace.sh` 获取官网 master 最新代码核对契约，使用前必须与内置版本 diff 校验。
+
+## 3. 必须核对的事实（内联记录于 DESIGN.md §0.3）
+
+| 事实类别 | 内容 | 记录位置 |
+|---------|------|---------|
+| matmul 链路事实 | M/N/K、dtype 组合、scale 编码、Blaze 组件（`BlockMmad` + `BlockScheduler` + `MatmulWithScaleMx` 或 FragmentTensor 路径）、localMatmul 模式候选、tiling 基线 | DESIGN.md §0.3 |
+| 通信接口事实 | `CollectiveComm` 四段式契约、GET/PUT 钩子职责、CommContext 字段、Win 区布局 | 同上 |
+| 入口 ABI 事实 | 入口函数签名、CommContext 传递方式、dtype 变体入口数 | 同上 |
+| 官方覆盖性 | 官方 kernel 可直接调用/复用的部分、未覆盖的需求项 | DESIGN.md §2.2 |
+| 注册形态原型事实（需求存在既有实现时） | 原型语义/算法骨架/验证基准三要素 + 可借鉴/必须重写边界判定（按 [`paradigm-mapping.md`](../operator-design/paradigm-mapping.md) §3 清单） | DESIGN.md §0.3 |
+
+每条事实必须带 `文件:行号` 证据引用；声明读取边界内未找到 ≠ 不支持，不得据此虚构接口或文件名（教训：AllGather GET 钩子在源码中不存在，仅 `all_to_all_udma_get.h` 有记录）。
+
+## 4. 调用链核对要点
+
+从官方 kernel 入口追踪完整调用链，记录每个环节的逻辑对象、设备物理表示、资源生命周期、同步 owner：
+
+```
+__global__ 入口 → Impl::Init → Impl::Run
+  → AIV 侧：CollectiveComm::Init → Commit → Wait → Finalize
+  → AIC 侧：BlockMmad::Init → Run → Epilogue
+  → 同步：CrossCore SetFlag/WaitFlag / SyncAll
+```
+
+接口组合以官方 kernel 实例为参照（实例化的模板参数、钩子注册、调度器选择），不做组件名的笛卡尔积式拼接；不得把参考算子名称当作能力证据。
+
+## 5. 独立报告模式（可选）
+
+仅当设计委托方明确要求时，将 §1-§4 事实写入 `operators/{op}/docs/apace-investigation-report.md`：
+
+```text
+investigation_id
+source_root                     # CANN 内置 apace 路径
+requirement_facts               # §1 需求四要素
+matmul_chain_facts              # §3 matmul 链路事实
+comm_interface_facts: []        # 通信接口事实
+entry_abi_facts: []             # 入口 ABI 事实
+official_coverage: full | partial | none
+uncovered_requirements: []      # 官方未覆盖的需求项
+read_boundary: []               # 实际读取的文件清单
+```
+
+## 6. 边界声明
+
+- 不做方案推荐、不匹配场景、不选择路线
+- 不编译或运行设备
+- 事实不足时在 DESIGN.md 标记 `blocking` 并停止等待澄清，最多一次补充核对