@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/compute-first-reduce-scatter/development.md

@@ -0,0 +1,272 @@
+# compute-first-reduce-scatter 开发指导
+
+> **场景 ID**：`compute-first-reduce-scatter`
+> **适用路线**：`implementation_route=apace_custom`，`selected_scenario=compute-first-reduce-scatter`（DESIGN 冻结后编译进 PLAN 的记录值）
+> **执行阶段**：Step 4（Implementation）只执行 PLAN，不改设计、不改接口/ABI；通用工程规范见 [`development-guide.md`](../../operator-design/development-guide.md)，架构原理见 [`fusion.md`](../../fundamentals/fusion.md) §6.2，通用方法论（D1-D6 决策点）见 [`dev-methodology.md`](../../operator-design/dev-methodology.md)。本文只写本场景差异化要点。
+
+---
+
+## 1. 有序开发动作（PLAN §4 编译模板）
+
+> **bring-up 两路径（按起点选）**：① 场景合同完备（design.md 已冻结）→ 直接按 A1-A7 FragmentTensor 一步到位；② 仅有语义无合同且存在可借用参考代码 → 先写 R 循环最简版跑通精度（临时裁剪项在 PLAN 登记"后续补齐"），再按 A1 优化为 FragmentTensor。
+
+| # | 动作 | 验收锚点 | 证据 |
+|:---|:---|:---|:---|
+| A1 | 实现 FragmentTensor mm kernel（消 R 循环，R16） | FragTensorA/FragScaleA/FragTensorC 打包 R 个 rank 段地址 + `QmmMxBlockMmadFragment` per-fragment L1 隔离，一次调用覆盖 `R × curTileM` 行 | 编译通过；grep 无 R×T 子调用循环 |
+| A2 | 实现 staging 即通信源 | mm 输出连续 `[M, N]` staging（GM workspace），rank 段 = chunk；PUT 钩子 src 偏移与 mm 写入偏移同源 | per-tile 契约不变量 3（[`development-guide.md`](../../operator-design/development-guide.md) §3.5） |
+| A3 | 实现 AIV 严格分离 | 后 R 核通信 / 前核归约；分核公式 `jobIndex = GetBlockNum()-1-GetBlockIdx()`；零 tile 核无条件 SetFlag | AIV 分支骨架与 [`fusion.md`](../../fundamentals/fusion.md) §6.2.1 一致 |
+| A4 | 实现增量归约 | 独立 `reduce_sum_ref.h`；手动 UB 批量形态：多 slot 布局 + src 双缓冲 + FP32 中间累加 + N 分段；禁止 TPipe/TQue 逐行模型 | R17/R18/R19（见 §5） |
+| A5 | 实现 `Wait<BARRIER_NONE>` + 手动 CrossDevice | 本场景（后 R 核映射）TeamBarrier 须 totalJobs=1 + 指定核显式 `CrossDevice()`；沿用 totalJobs=rankSize 会因 jobIndex 映射错位/守卫早退致跨卡同步失效（机制见 [`communication.md`](../../fundamentals/communication.md) §2.2） | grep `BARRIER_DEVICE` 为空 |
+| A6 | 完成 flag 编排 | T=1 单次 SetFlag / T>1 逐轮配对（Set/Wait 严格配对，flagId ∈ [0, FLAG_ID_MAX)）；SyncAll 在分核守卫外 | R5/R9 检查通过 |
+| A7 | 完成最终 drain | 循环结束消费残留事件（含次数守卫）；最后一轮归约与 drain 全量覆盖 | 挂死不出现 |
+
+> 执行纪律：每完成一个动作立即冒烟（改完即测）；bring-up 顺序 T=1/rank=2 → T>1 → 全量矩阵。
+
+---
+
+## 2. 文件级合同（[MODIFY] 清单）
+
+> 布局与命名规范以 [`development-guide.md`](../../operator-design/development-guide.md) §1.2 为唯一事实源；共享层零复制、CMake 直引 CANN 内置 apace。
+
+| 目录 | 文件 | 职责（本场景） |
+|:---|:---|:---|
+| kernel/ | `{op_name}_tiling_data.h` | 单份完整 mm tiling + `commTilingData` + 通信派生字段（每卡行数/chunk 字节/staging 大小/归约粒度）+ 就地 `CommContext`；**无 `localMatmul` 字段** |
+| kernel/ | `{op_name}_impl.h` | Impl：Init/Run 编排；AIC 统一 `for t` 循环（T=1 自然退化）+ SetFlag；AIV 逐轮 WaitFlag 门控 + Commit/Wait + SyncAll + 归约 |
+| kernel/ | `{op_name}_frag_kernel.h` | FragmentTensor mm 内核（A1），独立 namespace |
+| kernel/ | `reduce_sum_ref.h` | 归约文件（A4），独立 namespace |
+| src/ | `kernel_launcher.h` | 4 个 dtype 变体 `__global__` 入口（E4M3E4M3/E5M2E5M2/E4M3E5M2/E5M2E4M3），各含 `KERNEL_TYPE_MIX_AIC_1_1` |
+| src/ | `main.cpp` | 前置校验 → T 派生 → staging 分配（`M×N×sizeof(CType)`）→ dtype dispatch → fork 多 rank + TCP rootInfo + 建链 + launch（perf 模式内嵌 L2 flush） |
+| src/ | `root_info_exchanger.h`、`utils.h` | [REUSE] 从参考算子复制 |
+
+---
+
+## 3. Host 侧要求
+
+### 3.1 前置校验清单（fork/建链前执行，main.cpp 与 gen_data.py 双侧）
+
+**正确性类强制校验**：
+
+| # | 校验项 | 违反后果 |
+|:---|:---|:---|
+| 1 | `M % rankSize == 0` | M 轴切分错位 |
+| 2 | 对齐约束（`K%32`、`N%16`、单尾块 tailM 16 对齐且 ≤ headMSize 等，按 dtype/fixpipe 32B 行对齐推导） | 跨卡 Win 槽污染 |
+| 3 | `usedCoreNum ≥ rankSize` 且 `usedCoreNum - rankSize ≥ 1`（归约核至少 1 个） | 无核执行归约/rendezvous 挂死 |
+| 4 | Win 容量 `M×N×sizeof(CType)` ≤ `HcclGetHcclBuffer` 实测值 | 通信越界 |
+| 5 | `R ≤ 32`（MAX_FRAGMENT_COUNT 单次构建 fragment 数上限，与 T 无关） | FragmentTensor 越界 |
+| 6 | 新增输入 buffer 预算（bias 等 L1/BT 兜底核算） | L1/BT 溢出 |
+
+**风险提示类（不作 host 强制拒绝，按 case 复核）**：
+- flag 计数：计数器 0-15 衡量未消费积压（紧邻配对下 ≈1-2 不触顶，不构成 T 上限）；以 Set/Wait 严格配对为硬约束，T 上限按 case 实测确定（计数式配对已在多 tile 场景工程验证）。
+- 单轮 PUT 大小：无官方上限（bring-up 期过大单轮曾见间歇失败），大单轮须 case 复核（连续多轮精度 + 重复 launch 一致性）。
+
+### 3.2 T 派生
+
+- 优先 `T | mSeg` 无尾块（R10，实现最简）；**单尾块直传合法**（`tailMSize = mSeg % headMSize`，16 对齐且 ≤ headMSize）：如实填 `commTilingData` 尾块字段、tail tiling 入参 `m = rankSize × tailMSize`（注意 tail tiling 的 M 语义是 R 段拼接的逻辑总行数）
+- 多尾块或尾块 > headMSize 时走策略 A：`paddedCurTileM` 32 对齐 + `realFragmentSize` 限读 + 多套 tiling（全量 + head + tail）；三条路径均合法，见 [`fusion.md`](../../fundamentals/fusion.md) §6.2.7
+- tileM 选择按计算最优优先；T 上限按 case 实测确定
+
+> **约束联合推导原则**：单条约束各自满足 ≠ 联合可行。host 校验与 T 派生必须覆盖派生边界（尾块对齐、Win 容量、归约核数），cases.csv 必须包含约束边界用例（strided 场景、尾块边界、R 边界）——硬件隐式上限类缺陷（静默丢零、无报错）只在边界用例下暴露。
+
+### 3.3 dtype dispatch
+
+- host 按 `dtypeA`/`dtypeB` **运行期分派**到 4 变体入口，禁止硬编码单入口（硬编码 → 异 dtype 字节流被错误模板解释，精度系统性失败）
+- dispatch 宏模板见 [`development-guide.md`](../../operator-design/development-guide.md) §3.5
+- Win 数据区偏移按 host 建链布局确定，kernel/host 偏移同源（R14）
+
+---
+
+## 4. 验证矩阵（compute-first 特有项）
+
+| 类别 | 项 | 达标条件 |
+|:---|:---|:---|
+| 精度 | T=1 与 T>1 双路径 | 只测 T=1 会掩盖多 tile 布局 bug，双路径必须全 PASS |
+| 精度 | tail/非对齐 shape + 多 commTurn | tail 路径特征信号暴露 |
+| 精度 | per-tile 契约不变量 | 每轮 mm 只算本轮子区间（禁止"全量 mm × T 次"）；归约每轮只处理本轮行区间 |
+| 精度 | golden 语义 | 每卡"完整 K、切 M"，输出 `[M/R, N]`；golden FP32 累加路径 + 固定种子 |
+| 精度 | dtype 全覆盖 | 4 变体各自 PASS；E5M2 全错 → 查 dispatch |
+| 性能 | tileCnt 扫描 | 精度期 tileCnt=1 串行基线 → 性能期扫描（上限按 R9 口径），切 tileCnt 必须重调 `GetTilingData` |
+| 性能 | 投产门槛（R15） | 真实大 shape × R=2/4 双档 × 与同语义参考路径对标归档（融合算子或分步实现）；toy shape = FAIL；性能 shape 向业务方索取真实清单 |
+| 性能 | L2 flush 实接线（R20） | perf 每轮调 flush kernel，msprof 记录数 == 轮数 |
+
+### 4.1 对标基线工程已知坑（R15 落地，生产试错记录）
+
+> 环境口径：dav-3510 / CANN 9.2.0 / fork 直调多 rank。R15 要求与参考路径对标归档，但 aclnn 基准算子的**调用契约**（参数校验规则、group 机制、引擎模式）无现成文档——以下为实测踩坑记录，完整契约**未闭环**，设计期即应确定对标路径并预留试错时间。
+
+| 候选基线 | 已知坑（实测） | 结论 |
+|:---|:---|:---|
+| `aclnnMatmulReduceScatterV2`（融合） | CCU 引擎在 fork 直调场景报 "CCU tiling accelerator not support"（需框架侧机制注入，超出直调合理成本）；FP8 输入**必须带 scale**（per-tensor 量化语义，无 MX scale 输入，对标须声明差异）；scale dtype/形状校验严格（FP32/E8M0、[M/128,K/128] 或 [K/128,N/128] 类分块）；world group 不可手动创建（须用已初始化通信域）；streamMode/commMode 参数组合有硬约束；宿主链接 libhccl.so 可能误链系统 9.1.0 版本 | 融合路径在直调场景常判 N/A（须留证归档），转分步路径 |
+| `aclnnQuantMatmulV5` + `HcclReduceScatter`（分步） | 两段调用 + 中间同步，参数校验同样严格；须确认 aclnn 侧 scale 语义与被测算子对齐 | **推荐优先尝试**的分步对标路径 |
+| mc2 融合算子直调 | 候选检索方法见 R15（按 op 名模式搜 `$ASCEND_HOME_PATH/opp/built-in/op_impl/ai_core/tbe/kernel/`），勿只查单一算子名即下 N/A 结论 | 首选（同语义同框架） |
+
+> 工程纪律：对标试错属**设计期活动**——在 PLAN 中登记对标路径与预期成本；试错 ≥10 轮仍不可行时归档 N/A 证据（报错原文 + 参数组合）转下一候选，禁止无限试错。
+
+---
+
+## 5. 实现细节模板（本场景专属落地形态）
+
+> 通用方法论以 [`fusion.md`](../../fundamentals/fusion.md) §6.2 为唯一事实源；本节为落地骨架，新算子照搬结构、数值按自身 shape/dtype 重新推导。
+
+### 5.1 AIV 严格分离编排骨架
+
+```
+AIV (RunAllToAllAndReduceSum):
+  jobIndex = GetBlockNum() - 1 - GetBlockIdx()      ← 后 R 核通信
+  isCommBlock    = (jobIndex < rankSize)
+  isComputeBlock = (blockIdx < usedCoreNum - rankSize)  ← 归约核 = 前 (核数-R) 核
+
+  for t = 0..T-1（统一循环，T=1 自然退化）:
+     全 AIV: CrossCoreWaitFlag(flagId) → SyncAll   ← 无模板形态（Wait 后有标量流 Commit 下发，见 fusion.md §6.2.3）
+    通信核: Commit → Wait<BARRIER_NONE>（仅 Drain）
+    全 AIV: SyncAll
+    jobIndex=0: teamBarrier_.CrossDevice()          ← 显式跨卡 fence
+    全 AIV: SyncAll
+    归约核: t≥1 时 ReduceSum(t-1)（与下一轮通信重叠）
+  尾轮: 归约核 ReduceSum(T-1)；通信核 Finalize
+```
+
+> 同步机制选型依据（后 R 核映射下 TeamBarrier totalJobs=1 + 显式 CrossDevice，与官方前 R 核映射的 `Wait<BARRIER_DEVICE>` 模式互斥，机制分析见 [`communication.md`](../../fundamentals/communication.md) §2.2）；SyncAll 无跨设备能力，跨卡可见性只能走 CrossDevice。
+
+### 5.2 批量归约循环骨架
+
+> 归约实现必须同时提供两路径（[`fusion.md`](../../fundamentals/fusion.md) §6.2.6）：逐行版（T>1 多 tile 路径）与批量版（tileCnt=1 路径，一次处理多行摊薄 flag 次数）。
+
+**归约多核分治（必做）**：归约核集合（前 `rsCoreNum = usedCoreNum - rankSize` 核）内按行块均分本轮 `tileM` 行（连续行块、余数前摊），禁止单核归约（如 `GetBlockIdx()==0` 独担全量行）——归约耗时独占且多核误写同一输出区产生写竞争。
+
+```
+batchRows = UB预算 / (每行字节数 × 每元素 buffer 系数)   // host 按 UB 推导
+for batch in 按 batchRows 分批（覆盖本核行区间）:
+    for i = 0..R-1（R 个来源，pingpong 双缓冲）:
+        2D DataCopyPad(srcBuf[i%2], 来源 i 的本批行区间, blockCount=本批行数, 64B pitch)
+        Cast(srcFP32[i%2], srcBuf[i%2], CAST_NONE)      // 独立 srcFP32，禁止 in-place
+        PipeBarrier<PIPE_V>()
+        Add(accFP32, accFP32, srcFP32[i%2])
+    Cast(dstBF16, accFP32, CAST_RINT)
+    2D DataCopyPad(yGm 本批行区间, dstBF16, blockCount=本批行数)
+    // 一批数据一次 SetFlag/WaitFlag（FIFO 特性摊薄）
+```
+
+### 5.3 归约事件配对模板（R19 落地形态）
+
+4 类 HardEvent 的语义与 Set/Wait 时机以 [`fusion.md`](../../fundamentals/fusion.md) §6.2.6 为准；落地要点（pingpong slot = i%2）：
+
+- Init 时预初始化 `MTE3_V`（首次 Wait 前需有对应 Set）
+- slot 复用前 `WaitFlag<V_MTE2>(slot)`；搬入后 `SetFlag<MTE2_V>` → Wait → Cast/Add → `SetFlag<V_MTE2>` 释放
+- 循环结束**消费残留事件**（保持计数平衡，漏消费 → 后续挂死）；R=1 边界注意 slot 1 从未 Set 的未定义行为
+- 输出路径：等上批 MTE3 完成 → Cast → `V_MTE3` 配对 → 搬出 → 为下批预置 `MTE3_V`
+
+### 5.4 手动 UB 布局与预算
+
+> **UB 管理机制红线**：归约区 UB 管理必须与通信区使用同一机制——`TPipe::InitBuffer` 与 `Te::MakeMemPtr` 禁止混用（偏移空间不共享 → 地址重叠 → MTE2 越界）。推荐 `MakeMemPtr` 手动偏移（与官方算子一致，[`operator-anatomy.md`](../../operator-design/operator-anatomy.md) §4.3）。
+
+slot 结构（示例布局）：srcBuf[2]（pingpong 搬入）+ srcFP32[2]（pingpong Cast 目标，独立）+ accBuf（FP32 累加器，单份）+ dstBuf（输出）。
+
+host 侧 UB 预算推导（参数化公式，系数按 dtype 路径代入）：
+
+```
+perElemBytes = 2×sizeof(CType) + 2×sizeof(float) + sizeof(float) + sizeof(CType)
+availableUB = UB 总量 - guard 通信区
+maxElements = availableUB / perElemBytes
+redUbN      = min(N, 单次列宽上限) 且按对齐要求取整
+redUbM      = min(tileM, maxElements / redUbN)
+            // N > redUbN（strided 场景）时追加 redUbM ≤ 32（fusion.md §6.2.6 纪律 3 硬件限制）
+```
+
+> *工程提示：整片申请 UB 后 kernel 内运行期算偏移（按 [sum｜bf16×2｜f32×2｜out] 划分）与 host 传参布局同为合法形态，按 UB 预算与批量宽度选择。*
+
+### 5.5 多套 tiling 字段契约（tiling_data.h）
+
+```cpp
+struct {OpName}TilingData {
+    CommTilingData commTilingData;          // 通信切分（5 字段）
+    QuantMatmulTilingData mmTilingData;     // 全量 tiling（GetTilingData(m, n, k)），T=1 退化用
+    QuantMatmulTilingData subMmTilingData;  // head 子问题 tiling（GetTilingData(headMSize, n, k)），T>1 时强制存在
+    QuantMatmulTilingData tailMmTilingData; // tail tiling（GetTilingData(rankSize*tailMSize, n, k)），无尾块时字段仍须声明
+    // 通信派生字段：coreNum / rankSize / mSeg / chunkBytes / tileMaxBytes / stagingSize / redUbM / redUbN
+};
+// kernel 侧选择：(commTurn == 1) ? mmT : (isHeadTile ? subMmT : tailMmT)；blockDim 恒用 mmTilingData.usedCoreNum
+```
+
+> **T>1 时 subMmTilingData 强制存在**：全量 tiling 的 baseM 可能大于 headMSize 导致 tile 分布不合理，必须为 headMSize 独立调 `GetTilingData`。
+
+### 5.6 headMSize 标定原则
+
+决策原则（通用）："分片小 → 减小 tile 让通信尽早启动；分片大 → 增大 tile 减少同步次数"。分档实质由 `tileMaxBytes = tileM×N×sizeof(CType)` 主导（N 维度），非纯 R 档——同 R 下小 N 与大 N 的最优 tileM 方向相反。**数值为示例标定，新算子按 tile 粒度与流水深度目标自行标定**：异常特征 case（tileCnt 非最优、SyncAll 占比偏高）须按通信覆盖率与收益实测搜索，单点最优值不跨 case 复用。对齐：16 的倍数；单尾块 16 对齐且 ≤ headMSize（host 校验）。
+
+### 5.7 自研 FragmentTensor mm kernel 骨架
+
+参考 AllGather `qmm_mx_kernel_ag_udma.h`（`QmmMxKernelAgUdma`）改造，独立 namespace。改造时区分**必须保留**与**可省略**：
+
+| 必须保留（砍了即错） | 可省略（compute-first 特有） |
+|:---|:---|
+| per-fragment L1 隔离（`QmmMxBlockMmadFragment` 跨 rank 边界自动切 fragment） | dependId 预触发 / `WaitFlag`（计算不依赖通信） |
+| fragment 地址公式：A 段 `aGM + r×mPerRank×fullK`（**fullK = 完整 K 行 stride，A 不切分**），C 段 `stagingGm + r×mPerRank×cBytesPerM`；`cFragAddrs_` 保持原始 rank 顺序 | Win 区离散地址解析（A 为本卡 GM 连续 rank 段） |
+| localLast 编排（强制，见 §5.8）：fragment 重排 `[remote..., local]` + 边界提前 SetFlag | winDataBase（无 Win 区读 A） |
+| `SetL2Cache`（fullMBlock + 128B 对齐判定）+ tail tile `sch.UpdateTailTile` | — |
+
+> **TransA/TransB 参数化**：Impl 模板必须含转置参数（Layout 条件选择），禁止固定 Layout。
+>
+> **地址公式红线**：A 行 stride = 完整 K；行宽必须用**字节**（`r × mPerRank × K × sizeof(AType)`）——把元素数当字节偏移仅在 1 字节 dtype 巧合成立，FP16/BF16 扩展时静默错位。官方 kernel 用显式 `dataBytesPerMRow` 字节行宽，照搬时勿"简化"。
+>
+> **借鉴官方 AG kernel 必改项**：其 `cFragAddrs_[8]` 为硬编码 8 槽——R > 8 静默越界，必须扩为 `MAX_FRAGMENT_COUNT=32`；其三区 HEAD/MAIN/TAIL 懒构建结构在 per-tile 调用形态下可按统一 for-t 轮次重建形态省略。
+
+**Params 结构契约**（核心字段）：`mmTile`（当前轮 tiling 指针）/ `qbmmParams` / `rankSize, rankId` / `mPerRank` / `tileM`（problem M = R × tileM）/ `k, n, scaleKLen`（k = 完整 K）/ `aGM, aScaleGM, bGM, bScaleGM`（B 全 rank 共享）/ `stagingGm`（C 输出 = PUT 通信源）/ `cBytesPerM, tileMOffset`。
+
+核心方法：`BuildFragmentTensors`（cFragAddrs_ 按 staging 布局填、addrList localLast 重排、cFragAddrs_ 保持原始顺序）→ `Run`（构造 scheduler + FragL1Params + mmadFrag.Init）→ `Process`（调度循环：SetL2Cache → Slice → `mmadFrag(...)` 17 参调用散射到 staging）。
+
+### 5.8 localLast 双 flag 通信提前启动（compute-first 默认编排）
+
+机制原理见 [`fusion.md`](../../fundamentals/fusion.md) §6.2.2/§6.2.3。落地要点：
+
+1. **localLast 重排只作用于 FragmentTensor addrList**：构造时跳过本 rank 段、最后追加；**`cFragAddrs_` 必须保持原始 rank 顺序**（mmadFrag 内部 L1 cache 管理依赖原始顺序）——写错 = 阻塞级错误。
+2. **边界预计算**：`localFragBoundary = headMainRows - fragM`；调度循环内首次 `mPos >= localFragBoundary` 时 `SetFlag(flagA)`。
+3. **兜底补 Set**：未跨边界核（无本卡 tile）必须补 Set flagA——否则 AIV `WaitFlag(flagA)` 挂死。
+4. **AIV 两侧分等**：通信核 `WaitFlag(flagA)` 后启动 AllToAll；reduceSum 前 `WaitFlag(flagB)` 确认本卡段完成。
+
+### 5.9 per-tile 子区间契约代码模板（AIC RunMatmul，T>1 实现红线）
+
+```cpp
+for (uint32_t t = 0; t < commTurn; ++t) {
+    uint32_t curTileM    = GetTileM(t);        // t < headTileCnt ? headTileM : tailTileM
+    uint64_t tileMOffset = GetTileMOffset(t);  // t < headTileCnt ? t*headTileM : headTileCnt*headTileM
+    const auto& tileT = (commTurn == 1) ? mmTiling : (isHeadTile ? subMmTiling : tailMmTiling);
+    params.aGM      = aGm         + tileMOffset * axisK;                 // A 按行偏移
+    params.aScaleGM = scaleAGm    + tileMOffset * scaleARowBytes;
+    params.cGM      = workspaceGm + tileMOffset * axisN * sizeof(CType);
+    mmKernel_(params);                          // problem M = R × curTileM
+    CrossCoreSetFlag<0x2, PIPE_FIX>(flagId);
+}
+```
+
+不变量与违反后果见 [`development-guide.md`](../../operator-design/development-guide.md) §3.5 per-tile 契约表（唯一事实源）。
+
+---
+
+## 6. 合规映射（本场景重点项）
+
+> 全量红线见 [`review-checklist.md`](../../review-checklist.md)；违反任意红线 = FAIL。
+
+| # | 约束 | 本场景落点 |
+|:---|:---|:---|
+| R9 | flag Set/Wait 严格配对 + flagId ∈ [0, FLAG_ID_MAX) | A6；以"每轮 Set 双 flag"替代 localLast = 性能 FAIL |
+| R10 | 尾块策略 | §3.2 T 派生：默认 `T \| mSeg` 无尾块，否则策略 A padding + 多套 tiling |
+| R14 | Win 数据/元数据分离（硬红线）+ 单轮 PUT 大小（风险提示） | 偏移三处同源（PUT 写/归约读/host 建链）；单轮大小按 case 复核 |
+| R16 | mm 默认 FragmentTensor | A1；"vendor kernel + FragmentTensor C 输出"= 阻塞级错误 |
+| R21 | localLast 编排禁止移除 | A1/§5.8 |
+| R17 | 归约禁止逐行搬运 | A4：2D DataCopyPad blockCount=本批行数；strided redUbM ≤ 32 或 1D 退化 |
+| R18 | 归约独立 srcFP32 双缓冲 | A4：禁止 in-place 加宽 Cast |
+| R19 | 归约事件配对完整 | A4/A7：四类 HardEvent 同迭代配对 + 残留事件消费 |
+| R3 | 入口变体 + dtype dispatch | kernel_launcher.h 4 变体 + §3.3 |
+| R12 | UB 静态通信区隔离 | TPipe 与 MakeMemPtr 二选一 |
+| R20 | perf L2 flush 实接线 | §4 性能项 |
+
+---
+
+## 后续阅读
+
+| 文档 | 何时读 |
+|:---|:---|
+| [`fusion.md`](../../fundamentals/fusion.md) §6.2 | compute-first 架构原理与编排模式（通用方法论唯一事实源） |
+| [`dev-methodology.md`](../../operator-design/dev-methodology.md) | 五阶段流程 + D1-D6 决策点（本场景为 D1=计算在前的取值示例） |
+| [`operator-anatomy.md`](../../operator-design/operator-anatomy.md) §7 | 文件级契约与 MAX_FRAGMENT_COUNT |
+| [`development-guide.md`](../../operator-design/development-guide.md) §3.5 | per-tile 子区间契约、dispatch 宏模板 |
+| [`review-checklist.md`](../../review-checklist.md) | 全局红线 + 场景约束与 FAIL 诊断 |

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

@@ -0,0 +1,93 @@
+# get-all-gather-quant-matmul 场景设计
+
+> 场景 ID：`get-all-gather-quant-matmul`
+> 状态：`not_found`（AllGather GET 钩子未见源码记录；AllToAll GET 钩子已存在但官网无算子使用）
+> 支持范围：GET 模式，AllGather + QuantMatmul，N 轴切分，UDMA
+
+## 1. 准入条件
+
+| 条件 | 说明 |
+|------|------|
+| 通信方向 | GET（计算→通信） |
+| 编排形态 | AIC 先算，AIV 后拉 |
+| 切分轴 | N 轴按 rank 切分（⚠️ 无官方样例，为原理推导） |
+| 通信引擎 | UDMA |
+| 算子类型 | AllGather + QuantMatmul |
+| 官方参考 | 无（已验证事实：`block/aiv_comm/all_to_all/all_to_all_udma_get.h` 的 `AllToAllCommGetImpl` 已注册进 `CollectiveCommHelper<AllToAll, GET, ...>` 分发但无 kernel 使用方；**AllGather GET 钩子在源码中未见记录**——不得假定 `all_gather_udma_get.h` 存在，须在 Step 2 调查中以真实源码核对后记录 `not_found` 或补充证据） |
+
+## 2. 消费输入
+
+消费 matmul 链路事实（设计前核对结果），需求四要素中 `communication_direction=GET`、`split_axis=N`、`orchestration=AIC-first`。
+
+## 3. GET 设计边界
+
+### 3.1 通信方向与编排
+
+| 维度 | 合同 |
+|------|------|
+| 方向 | GET = 计算→通信：AIC 先算 C 写到 Win 区，AIV 从远端 Win 区拉回本 rank 的 C 段 |
+| 编排 | AIC 先 SetFlag → AIV WaitFlag |
+| 回压 | AIC `CrossCoreWaitFlag<0x2, PIPE_M>(tid-bufCnt)` 环形回压（原理推导：回压 gate AIC 计算主流水，pipe 选取见 `api-crosscore-sync.md` §4；与 [`fusion.md`](../../fundamentals/fusion.md) §3.4 契约一致；bufCnt 为深度参数） |
+
+### 3.2 数据分布
+
+| 维度 | 合同 |
+|------|------|
+| 切分轴 | N 轴按 rank 切分，每 rank 持有 N/rankSize 段（输出 C 按 N 分布） |
+| A 数据 | 各 rank 持有完整 A `[M, K]`（**A 不切分**：C 按 N 切分需全 M 的 A） |
+| B 数据 | 各 rank 持有 B 的 N/rankSize 段 `[K, N/rankSize]`（**B 按 N 切分**，与输出 C 的 N 切分一致；见 [`../../../fundamentals/architecture.md`](../../fundamentals/architecture.md) §4 GET 行"B N-split"） |
+| C 输出 | 每 rank 写出 N/rankSize 段到 Win 区，AIV 拉回完整 C |
+
+> ⚠️ 本场景标注 not_found（原理推导，未经官方源码验证）：上述分布为按 AllGather+Matmul（GET、N-split 输出）的语义推导，实现前必须对照源码逐条验证钩子行为。
+
+### 3.3 Win 区布局
+
+| 维度 | 合同 |
+|------|------|
+| 环形复用 | Win 槽位环形复用 + 回压（bufCnt 控制槽位数） |
+| 回压机制 | AIC `CrossCoreWaitFlag<0x2, PIPE_M>(tid-bufCnt)` 等待槽位可用（原理推导，非官方样例） |
+| 数据/元数据 | 分离，host/kernel 偏移同源 |
+
+### 3.4 通信轮次
+
+| 维度 | 合同 |
+|------|------|
+| T 推导 | 由 host 派生，默认 `T \| mSeg` 无尾块 |
+| flag 编排 | AIC SetFlag(tid) → AIV WaitFlag(tid)，T=1 单次 / T>1 逐轮配对 |
+
+### 3.5 flag 编排
+
+| 维度 | 合同 |
+|------|------|
+| 发起方 | AIC 先 SetFlag → AIV WaitFlag |
+| Wait 参数 | Wait(true) 按 waitLast 早退语义：DoWait 仅在 currentTileIdx_ == totalTiles - 1 时执行一次 |
+| SyncAll | 不需要（CrossCore flag 已保证时序） |
+| flagId | tid（tile 索引） |
+
+## 4. 联合合同
+
+```
+AIC: mm 计算 → 写 Win 区 → SetFlag(tid) → WaitFlag(tid-bufCnt) 回压
+AIV: WaitFlag(tid) → GET 从远端拉回 → 写输出 GM
+```
+
+## 5. Step 3 前提
+
+- 设计前核对已记录官方未覆盖项（GET 无官方参考）
+- 场景语义命中 `get-all-gather-quant-matmul` 判据
+- GET 钩子源码已只读验证：AllToAll GET 钩子（`block/aiv_comm/all_to_all/all_to_all_udma_get.h`）已确认存在；AllGather GET 钩子已确认**未见源码记录**（not_found），设计按钩子契约级原理推导进行，实现前须以真实源码补证
+
+## 6. 验证合同摘要
+
+| 维度 | 合同 |
+|------|------|
+| golden 语义 | 每 rank 输入（本地数据 + 远端数据来源）与输出语义明确，N 轴切分 |
+| 精度标准 | 以 ST verify_result.py 为准 |
+| 多卡矩阵 | R=2/4 双档 |
+| GET 稳定性 | 4+rank 不稳定已知风险（见 [`fusion.md`](../../fundamentals/fusion.md) §6.2.5 PUT 优先） |
+
+## 7. 已知限制
+
+- 官网无 GET 算子样例，GET 内容为钩子契约级描述
+- 地址公式与 self 跳过规则需从 `block/aiv_comm/` 头文件直接验证
+- GET 模式 4+rank 不稳定，PUT 优先

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

@@ -0,0 +1,70 @@
+# get-all-gather-quant-matmul 开发指导
+
+> **场景 ID**：`get-all-gather-quant-matmul`（GET 模式，AllGather + QuantMatmul 融合，N 轴切分，UDMA 直调）
+> **生效条件**：设计冻结后由 Step 3 编译进 PLAN（`implementation_route=apace_custom`，`selected_scenario=get-all-gather-quant-matmul`）；Step 4 **只执行 PLAN**，不得在实现期新增设计决策。
+> **前置阅读**：[`../../fundamentals/communication.md`](../../fundamentals/communication.md) §3（GET 钩子契约）、[`../../fundamentals/fusion.md`](../../fundamentals/fusion.md) §2/§3.4（GET 选型与环形回压）、[`../../fundamentals/compute.md`](../../fundamentals/compute.md) §3（QuantMatmulMxKernel）。
+
+---
+
+## 1. 状态说明：无官方参考，契约须源码验证
+
+| 事项 | 状态 |
+|:---|:---|
+| GET 钩子基础设施 | ✅ 已存在：`apace/block/aiv_comm/all_to_all/all_to_all_udma_get.h`（`AllToAllCommGetImpl`），已注册进 `CollectiveCommHelper<AllToAll, GET, ...>` 分发 |
+| AllGather GET 钩子 | ❌ 未实现（communication.md 钩子支持表：AllGather/GET = —） |
+| GET 使用方 kernel | ❌ 官网 kernel/ 下两个算子均为 PUT 模式，无 GET 使用方 |
+
+**开发纪律**：本文档为原理推导级指导。任何钩子行为假设（`PostInit`/`DoCommit`/`DoWait`/`DoFinalize` 职责、barrier 顺序、self 跳过、`Wait(true)` waitLast 早退语义）必须在实现前对照 `block/aiv_comm/` 源码逐条验证，并在 PLAN 第 11 章记录验证结论；与源码不符时以源码为准并回退设计阶段。
+
+## 2. 有序动作（Step 4 按序执行）
+
+| # | 动作 | 关键要点 |
+|:--|:---|:---|
+| 1 | 适配通信对象 | 优先**复用** `AllToAllCommGetImpl`（逐 targetRank 从远端 Win 拉回）。⚠️ **待验证假设**：其"按请求方 rankId 取槽位"语义是否天然覆盖 AllGather"收齐所有 rank 数据"语义，取决于 Win 布局合同，实现前必须对照源码逐条验证（本场景 not_found）；仅当分发层要求 `CollectiveCommHelper<AllGather, GET, ...>` 时才新写 `AllGatherCommGetImpl`，且须保持与 AllToAll GET 相同的钩子契约（barrier 先 Core 后 Device、self rank 跳过） |
+| 2 | 适配计算 | 复用 `QuantMatmulMxKernel`（`quant_matmul_mx_kernel.h`，CommPolicy 策略注入），AIC 按 N 轴切分算 C 并写入 Win 区（每 rank 持有 C 的 N/rankSize 列，B 可 N-split，见 architecture.md §4） |
+| 3 | 实现 Win 槽位环形复用 + 回压 | Win 区按 bufferCount 槽位环形复用；**AIC 侧 `CrossCoreWaitFlag` 等待槽位可用 flag**（AIV 拉走数据后置位），禁止无回压覆写（fusion.md §3.4） |
+| 4 | 完成 flag 编排闭环 | AIC 算完写 Win → `SetFlag`（C-ready）；AIV `WaitFlag` → `Commit(GET)` → 拉取完成 → `SetFlag`（V-done / 槽位释放）；尾部按 `Wait(true)` waitLast 语义处理——**最后一轮通信不被 Drain**，须由 `Finalize`/`DoFinalize` 的 CrossDevice barrier 完成 final drain，防止尾部越界覆盖 |
+
+> ⚠️ GET `DoCommit` 内 `CrossCore()+CrossDevice()` barrier 是对端 AIC 槽位就绪的回压保证，**不可省**；barrier 顺序为先 Core 后 Device（与 PUT 相反）。
+
+## 3. 文件级合同
+
+| 文件 | 状态 | 说明 |
+|:---|:---|:---|
+| `kernel/{op_name}_tiling_data.h` | MODIFY | tiling 结构体：N 轴切分字段、Win 偏移、bufferCount、flag id、tile 字节数 |
+| `kernel/{op_name}_impl.h` | MODIFY | Impl：Init/Run 编排，GET 模式 `AllToAllProcess` 中**不需要 SyncAll**（同步全由 CrossCore flag 负责，fusion.md §3.1） |
+| `kernel/quant_matmul_mx_kernel.h` | REUSE | 复用官方 `QuantMatmulMxKernel`，仅注入 GET CommPolicy |
+| `src/kernel_launcher.h` | MODIFY | `__global__` 入口含 `KERNEL_TYPE_MIX_AIC_1_1`；UDMA 模式带 `__gm__ CommContext*` |
+| `src/main.cpp` | MODIFY | Tiling + fork 多 rank + HCCL 建链 + launch；host 前置校验 + perf 模式 L2 flush |
+| `scripts/gen_data.py` / `verify_result.py` | MODIFY | golden 按 N 轴切分核对；多 rank 校验 |
+| `block/` `tiling/` | 禁止修改 | 与官网仓原始文件完全一致（R4） |
+
+## 4. 验证矩阵
+
+| 维度 | 要求 |
+|:---|:---|
+| 精度 | golden 比对覆盖 N 轴各 rank 列段；dtype 全变体；**重点回归 R=2 与 R=4+**（GET 多 rank 数据可见性风险，见 §6） |
+| 时序 | 大 shape / 多轮（bufferCount 环形翻转 ≥ 2 圈）下无脏读、无"假通过" |
+| 同步 | flag idx 配对（AIV WaitFlag idx == AIC SetFlag idx）；末轮 final drain 经 DoFinalize 验证 |
+| 性能 | 真实大 shape × R=2/4 双档，与 mc2 融合算子 / hccl 分步路径对标归档（R15）；perf 每轮实调 L2 flush kernel（R20） |
+| 可靠性 | 单轮 PUT 大小按 case 复核（bring-up 期 ≤512KB 起步，非硬上限）；所有 hcomm 调用返回值 assert |
+
+## 5. 合规映射（本场景重点 R 项）
+
+| R 项 | 本场景落点 |
+|:---|:---|
+| R1/R2 | 禁 `__schedmode__(1)`/`core_ratio`；入口含 `KERNEL_TYPE_MIX_AIC_1_1` |
+| R4 | `block/` `tiling/` 零修改（GET 钩子只用不改） |
+| R5 | C-ready / V-done / 槽位释放 flag idx 双侧配对 |
+| R6 | UDMA 模式 `__gm__ CommContext*` |
+| R12 | commBuf/barrierBuf 与 TPipe 管理 buffer 物理隔离 |
+| R13 | 通信对象 `totalJobs=rankSize`（后 rankSize 核各负责 1 个 targetRank 并行 GET） |
+| R14 | Win 数据/元数据区分离，host/kernel 偏移同源（硬红线）；单轮 PUT 大小按 case 复核（风险提示） |
+| R15/R20 | 投产级性能对标 + L2 flush 实接线 |
+| R7/R8 | 禁 `AscendC::Matmul` 高阶 API、禁 `Hccl::*` |
+
+## 6. 额外警示：GET 模式 4+ rank 不稳定性
+
+- **PUT 优先原则**（fusion.md §6.2.5）：GET 模式在 4+ rank 存在数据可见性问题，且官网无 GET 算子样例；设计期应已论证"必须 GET"的理由，否则回退 PUT。
+- 已知绕行方案（communication.md 陷阱 #11）：GET `Drain` 返回非 0 时，可用 `TeamBarrier.CrossDevice()`（跨 rank 就绪）+ `SyncAll<true>`（核间可见）后直接 `DataCopyPad` 读远端 Win 区。
+- R≥4 精度回归不通过时**禁止带病交付**：先在 PLAN 第 11 章记录 `design_issue`，回退设计阶段评估改 PUT 或绕行方案。

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/apace/scenarios/index.md

@@ -0,0 +1,47 @@
+# apace 定制扩展场景注册表
+
+> **定位**：本表是 apace 路线的**定制扩展场景唯一注册表**。Step 3（Design）在路线决策时，**仅当**设计前核对已记录官方 kernel 未覆盖的需求项后才查询本表；官方 `apace/kernel` 可直接调用或参考复用时（`apace_native` 路线）**不读取**本表。
+>
+> **查阅规则**：官方未覆盖项的**需求语义**命中某场景的语义判据时，**默认查阅**该场景的 design.md / development.md 作为设计基线，并将 `selected_scenario` 记录到 DESIGN.md。准入条件只含**需求侧语义判据**（数学语义、切分语义、通信方向），不含实现侧决策（通信实现方式、编排形态由场景文档指导决策，不作为准入前提）。语义零命中 → 判 `unsupported`；多命中 → 视为注册表缺陷或需求描述不清，停止并等待澄清，禁止自行择优。
+>
+> ⚠️ **已有生产实现的场景不受官方覆盖性判定反向阻断**：本仓/用户工程中已存在某场景的生产实现时，阅读该场景文档不需要"官方未覆盖"前提——场景文档同时是该类算子的改造/复用手册。
+
+## 场景注册表
+
+| 场景 ID | 支持范围 | 准入条件 | 设计指导 | 开发指导 | 状态 |
+|:---|:---|:---|:---|:---|:---|
+| `put-all-to-all-quant-matmul` | PUT 模式 AllToAll+QuantMatmul 的**变体扩展**（官方 kernel 未覆盖的需求：新 dtype 组合、bias/scale 融合、不同切分/编排），K 轴切分，UDMA 直调 | 通信原语为 AllToAll；localMatmul 为 QuantMatmul（含 scale）；PUT 方向；核间数据沿 K 轴切分；UDMA；**且存在官方 kernel 未覆盖的 native gap**（标准 PUT AllToAll+QuantMatmul 需求走 `apace_native`，不读本表） | [design.md](put-all-to-all-quant-matmul/design.md) | [development.md](put-all-to-all-quant-matmul/development.md) | 已实现 |
+| `put-all-gather-quant-matmul` | PUT 模式 AllGather+QuantMatmul 的**变体扩展**（新 dtype、bias 融合、rankSize>8、编排改造），M 轴输入切分，UDMA 直调 | 通信原语为 AllGather；localMatmul 为 QuantMatmul；PUT 方向；核间数据沿 **M 轴聚合**（每卡持本卡 M 行 × 全部 K 列，每卡输出全量 C）；UDMA；**且存在官方 kernel 未覆盖的 native gap**（标准需求走 `apace_native`） | [design.md](put-all-gather-quant-matmul/design.md) | [development.md](put-all-gather-quant-matmul/development.md) | 已实现 |
+| `get-all-gather-quant-matmul` | GET 模式，AllGather + QuantMatmul 融合，N 轴切分，UDMA 直调 | 通信原语为 AllGather；localMatmul 为 QuantMatmul；GET 方向；核间数据沿 N 轴切分；UDMA | [design.md](get-all-gather-quant-matmul/design.md) | [development.md](get-all-gather-quant-matmul/development.md) | not_found |
+| `compute-first-reduce-scatter` | compute-first 模式，ReduceScatter 语义 + QuantMatmul 融合，输出沿 M 轴切分，UDMA 直调 | **逻辑语义为 ReduceScatter**（每 rank 输出 M 轴分片、跨 rank 求和）；localMatmul 为 QuantMatmul；compute-first（先算后通信）；UDMA。（通信实现方式——AllToAll PUT + 本地增量归约——由场景文档指导决策，非准入前提） | [design.md](compute-first-reduce-scatter/design.md) | [development.md](compute-first-reduce-scatter/development.md) | 已实现 |
+
+### 状态说明
+
+| 状态 | 含义 |
+|:---|:---|
+| 已实现 | 有官方参考或生产实现，design.md / development.md 已就绪，可直接指导开发 |
+| planned | 场景已规划，指导文档编写中，暂不可用于路线决策 |
+| not_found | 代码仓中尚无使用该场景的 kernel；`get-all-gather-quant-matmul` 当前仅 AllToAll GET hook（`block/aiv_comm/all_to_all/all_to_all_udma_get.h`）有源码记录，**AllGather GET hook 未见源码记录**，设计指导为原理推导，须经源码验证后方可采用 |
+
+### 参考依据
+
+- `put-all-to-all-quant-matmul`：官方参考算子 `all_to_all_quant_matmul`（K 轴切分、UDMA 直调范式来源）；本场景定位为该范式的**变体扩展**指导，非标准 PUT 需求的重复
+- `put-all-gather-quant-matmul`：官方参考算子 `all_gather_quant_matmul`（AllGather+**PUT**、M 轴输入切分、FragmentTensor 三区范式来源）；本场景定位为该范式的**变体扩展**指导。注意与 `get-all-gather-quant-matmul` 的区别：官方 AG 是 PUT 模式（AIV 逐轮 PUT 到对端窗口），GET+AllGather 无任何官方实现
+- `get-all-gather-quant-matmul`：官方暂无 GET 算子样例；GET 切分策略为原理推导（见 [`../workflow_integration.md`](../workflow_integration.md) Step 2 §切分策略）
+- `compute-first-reduce-scatter`：已有生产实现（先本地计算、再 AllToAll PUT + 本地增量归约实现 ReduceScatter 语义），关键编排特征为 **compute-first + localLast 双 flag + 归约多核分治**（设计/开发合同见对应场景文档）。⚠️ 官方快照基准（`mc2/common/op_kernel/apace/`）中 ReduceScatter 仅为枚举占位（`collective_comm_api.h` 的 `CommCollectiveOp::ReduceScatter`，无 block 实现与 kernel 使用方）——本场景合同为自研编排，不与官方实现混淆
+
+## 唯一匹配约束
+
+1. 场景准入条件（语义判据）必须**互斥**：任意需求不得同时命中两个及以上场景的语义判据。
+2. **语义零命中**（官方未覆盖项无场景可覆盖）→ 路线判 `unsupported`，阻塞 DESIGN.md。
+3. **多命中** → 视为注册表缺陷或需求描述不清，判 `unsupported`，停止并等待澄清，禁止自行择优。
+4. 命中后默认查阅命中场景的指导文档作为设计基线；跨场景拼接设计元素时必须在 DESIGN.md 中显式论证。
+
+## 场景扩展
+
+新增定制扩展场景时：
+
+1. 在本目录下创建 `<scenario-id>/` 子目录（kebab-case，与表中场景 ID 一致）
+2. 子目录内提供 `design.md`（设计指导）与 `development.md`（开发指导）
+3. 在本表中登记一行，初始状态为 `planned`，文档就绪后改为 `已实现`
+4. 登记前必须核对与已有场景的准入条件互斥，不满足唯一匹配约束的注册不予合入

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

@@ -0,0 +1,83 @@
+# 场景：put-all-gather-quant-matmul（AllGather + QuantMatmul 变体扩展）
+
+> **状态**：已实现（官方参考算子 `apace/kernel/all_gather_quant_matmul/`）。
+> **定位**：官方 AllGather 范式的**变体扩展**指导——标准 AllGather+QuantMatmul 需求走 `apace_native`（直接调用/参考复用官方 kernel），**不读本表**；本场景服务于官方 kernel 未覆盖的变体（新 dtype、bias 融合、rankSize>8、编排改造）与 AG 专属事实汇总。
+
+## 1. 准入条件（语义判据）
+
+通信原语为 AllGather；localMatmul 为 QuantMatmul（含 MX scale）；PUT 方向；**核间数据沿 M 轴聚合**（每卡持本卡 A 分片 `[m, K]`，聚合后逻辑形状 `[R×m, K]`）；UDMA；**且存在官方 kernel 未覆盖的 native gap**。
+
+与 `put-all-to-all-quant-matmul` 的语义区分：A2A 是输入 K 轴切分（每卡持全部 M 行 × 本卡 K 段，输出 M 轴分布）；AG 是输入 M 轴切分（每卡持本卡 M 行 × 全部 K 列，每卡输出**全量 C** `[R×m, N]`，各卡 B 独立故 C 不同）。
+
+## 2. 数据分布与 golden 语义（区别于 A2A 的关键）
+
+| 项目 | 合同 |
+|:---|:---|
+| 输入分布 | 每 rank 独立 seed（`BASE_SEED + rankId`）生成本卡 A `[m, K]`（MX 量化：data fp8 + scale e8m0 per-64-group）；B 为本卡独立的 `[K, N]`（DN 列主：gen_data 写 `[N,K]` C-order 不转置，scaleB `[N, K/32]` C-order） |
+| 通信语义 | AllGather = `np.concatenate` 各 rank 反量化 A（M 轴聚合，`[R×m, K]`） |
+| 输出分布 | **每卡全量 C `[R×m, N]`**：`C_r = matmul(A_all_dequant, B_r_dequant) → bf16`——各卡 B 不同故输出不同（区别于 A2A 的 `[m, N]` 分片输出） |
+| 精度标准 | bit-exact 或 raw uint16 差 ≤ 1 ULP（`verify_result.py`：bf16 raw uint16 比较，`raw_max ≤ 1` 即 PASS；大 K 下 fp32 累加非结合性产生百个量级 1-ULP 元素属正常）——**严于 A2A 的 1e-2 allclose**，因无跨卡部分和累加序问题 |
+
+## 3. tiling 与切分（AG 专属公式）
+
+| 项目 | 公式/结论 | 锚点 |
+|:---|:---|:---|
+| 切分轴 | M（`tileM = min(m, 512)`，`TILE_M=512` 常量，m < tileM 时收缩）；K 不切 | `tests/st/all_gather_quant_matmul/src/main.cpp:47,111-114` |
+| tiling 入参形状 | **聚合后总 M**：`totalLogicalM = rankNum × (tileCnt × tileM + tailCnt × paddedTailM)` 后调 `GetTilingData(totalLogicalM, n, k)` | 同上 `main.cpp:119-127` |
+| 尾块对齐 | `paddedTailM = (tailM + 15) / 16 × 16`（kPaddingLength=16）；FragmentTensor 以 `paddedTailM` 为 fragmentSize、`tailM` 为 realFragmentSize 表达 padding | `all_gather_mx_matmul_udma_impl.h:78,189`；`qmm_mx_kernel_ag_udma.h:523-528` |
+| SWAT 开关 | AG 用 4 参重载 + **`SetOptimizeEnable(false)` + `SetMTailAlignEnable(true)`**（关闭边缘块合并、开启 M 尾 16 对齐——与 A2A 默认相反，移植时勿照抄 A2A） | `main.cpp:124-125` |
+| host 校验 | `K % 32 == 0`、`CeilDiv(K, 64) % 2 == 0`（gen_data 与 main.cpp 双侧） | `main.cpp:81-86` |
+| commTurn | `tileCnt + tailCnt`；AG 的 flagId 整体 **+1**（见 §4） | — |
+
+## 4. Flag 编排（AG 专属：预触发模式）
+
+与 A2A 的差异：AG 的 HEAD 区（本卡自身数据）**恒就绪**，AIV 在循环前**预触发 `CrossCoreSetFlag<0x2, PIPE_MTE3>(0)`**；循环内第 round 轮完成后 `SetFlag(round + 1)`。AIC 侧三区依赖映射：
+
+| 区域 | M 范围 | dependTileIdx | 数据源 |
+|:---|:---|:---|:---|
+| HEAD | `[0, headRows)` | 0（预触发，立即返回） | 本地 aGM |
+| MAIN | head + `[round × tileM × (R-1), ...)` | round + 1 | 各 rank 窗口（FragmentTensor，本 rank 除外） |
+| TAIL | head + mainSection 之后 | commTurn（最后一轮） | 全部 rank（含本地，paddedTailM 对齐） |
+
+AIC 统一经位掩码去重路径 wait（含 id 0，因已预触发不阻塞），收尾 drain 循环到 `commTurn` **含端点**。锚点：`qmm_mx_kernel_ag_udma.h:44（RegionTag）,557-592（ResolveTileCtx）,370-373（去重）,410-414（收尾）`；`all_gather_mx_matmul_udma_impl.h:246-263（AIV 循环）`。
+
+## 5. FragmentTensor 三区调度（AG 核心机制）
+
+- HEAD/MAIN/TAIL 三区各维护 FragmentTensor（`ResolveTileCtx` 按调度 tile 的 mPos 分区）
+- MAIN 区**延迟构建**：首次命中 `BuildMainFragment`，换轮 `UpdateMainRoundAddrs`（只换地址表不重建对象），构建开销被通信 wait 掩盖
+- matmul 走 blaze_ext `QmmMxBlockMmadFragment`（A/scaleA/C 三侧 FragmentTensor，B/scaleB/bias 普通 GM tensor；调用契约见 [`compute.md`](../../fundamentals/compute.md) §7）
+- AG 的 `SetL2Cache` 与 A2A 差异：无 isAtomicAdd 分支；scaleB 受 `fullMBlock && align` **双 gate**（`qmm_mx_kernel_ag_udma.h:246-273`）
+
+## 6. 硬约束（AG 专属）
+
+| 约束 | 说明 | 锚点 |
+|:---|:---|:---|
+| rankSize ≤ 8 | `cFragAddrs_[8]` / `winDataRankBase_[8]` / `winScaleRankBase_[8]` 为**定长 8 数组、循环无界检查**——R>8 静默越界；变体扩展到 R>8 必须先扩数组（建议按 `MAX_FRAGMENT_COUNT=32` 扩） | `qmm_mx_kernel_ag_udma.h:203-205,437-439` |
+| barrierBuf/scale 区布局 | 窗口 rank-major：`[rank r][m 行 data][m 行 scale]`（data 段在前，scale 段 offset = dataRegionBytes_）；UB 静态 512×2+32 | `all_gather_mx_matmul_udma_impl.h:135-142,166-171` |
+| BarrierMode | data `Init<BARRIER_NONE>` + scale `Init<BARRIER_DEVICE>`（与 A2A 的 data NONE + scale 默认不同——AG 的 scale Wait 承担跨卡 fence） | 同上 `:166-171` |
+| 单入口 | 官方仅 1 个 `__global__`（E4M3×E4M3→bf16，impl 头文件末尾）；变体加 dtype 按 A2A 的 4 变体 launcher 模式补 | `all_gather_mx_matmul_udma_impl.h:267-278` |
+| `localMatmul` 字段 | AG tiling **无** localMatmul（单 REMOTE 编排）；加该能力须重设计 | `all_gather_mx_matmul_udma_tiling_data.h:36-39` |
+
+## 7. ST 工程事实（AG 与 A2A 差异）
+
+| 项目 | AG | A2A |
+|:---|:---|:---|
+| perf 计时 | `aclrtEvent` × 20 次（`BENCHMARK_ITERATIONS=20`）取平均 | `steady_clock` × 10 次去首帧 |
+| `ASC_DEVKIT_MAJOR=9` | **无**（CMakeLists 无该宏） | 有 |
+| cases.csv 列 | `m,k,n,rank_num`（无 head_m_size） | `m,k,n,rank_num,head_m_size` |
+| devContext 处置 | `aclrtFree(devContext)`（与 A2A 不 free 的处置不同；新算子统一按 host-and-testing 口径处理） | 不 free |
+| run.sh | 同构四阶段；`--check` 静默模式（供 perf 分支捕获 PASS/FAIL） | 无 `--check` |
+| 用例特征 | 17 行含非对齐 M（2061/3085/4109/8205 触发尾块路径） | 8 行 |
+
+## 8. 变体扩展改造点速查
+
+| 变体 | 改动落点 |
+|:---|:---|
+| 新 dtype（E5M2/混合） | impl 模板参数 + 按 A2A launcher 模式加入口变体 + host dispatch（R3） |
+| 加 bias | `QBMMTiling.isBias` + bias GM 传参（mmad 通道现成，参照 hcomm impl 已设 biasGmAddr 的写法） |
+| rankSize > 8 | §6 硬约束：扩三数组 + 核数守卫重验（须 `usedCoreNum ≥ rankSize`） |
+| M 轴聚合 + 输出分片混合语义 | 越界本场景——重新走场景注册表判据 |
+
+## 9. 验证合同摘要
+
+golden = 每 rank 独立 seed 反量化 A/B → `np.concatenate` A → matmul → bf16（§2）。精度 bit-exact/1-ULP（§2）；先 tileCnt=1 串行基线（T=1 全 PASS 不能外推 T>1——三区布局与 flag 配对问题只在多 tile 暴露）。用例矩阵：rank 端点 × 对齐/非对齐 M（尾块路径）× 边界 shape（m<512 收缩、K=32 最小对齐）。