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

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/apace/operator-design/paradigm-mapping.md

@@ -0,0 +1,93 @@
+# 语义范式映射与架构差异（apace 路线）
+
+> **定位**：目标需求存在**注册形态既有实现**（上游仓 ops-transformer `mc2/` 目录下的 HCCL/CCU 注册算子）时，在 apace 路线上实现同类语义的**选型与转换指南**。回答三个问题：选哪个原型参考、哪些可借鉴、哪些必须按 apace 架构重写。
+>
+> **参考实现定位**：优先在当前 CANN 环境内置 apace 路径下定位（Step 1 实测登记）；注册形态原型经 `scripts/fetch_apace.sh` 拉取上游仓后在 `mc2/<op>/` 目录查阅。已有实现仅作选型与借鉴边界的示例引用，不作为内容主体。
+>
+> **核心原则**：参考原型的**算法逻辑**（切分策略、通算重叠编排、量化语义、尾块处理），重写**架构机制**（通信引擎、同步原语、matmul 栈、tiling 生成、host 拉起）。禁止整段复制注册形态 kernel 代码——include 体系、同步原语、通信调用在 apace 下全部不兼容。
+>
+> **最优先参考永远是 apace 已有算子**（同为 apace 架构，骨架可直接复用）；注册形态原型只提供算法语义与验证基准。
+
+## 1. 选型总表
+
+按目标算子语义选取参考（apace 路线三态：`apace_native` 直接调官方 kernel / `apace_custom` 按场景组合 / `unsupported`）：
+
+| 目标算子语义 | apace 已有参考（首选） | 注册形态原型（算法借鉴，上游仓 `mc2/` 目录） | apace 路线 | 通信组件现状 |
+|:---|:---|:---|:---|:---|
+| AllGather + MX 量化 matmul（每卡独立 A/B，全量 C 输出） | `kernel/all_gather_quant_matmul/`（AllGather+PUT、M 轴输入切分、FragmentTensor 三区） | `all_gather_matmul`（fp16/bf16）、`all_gather_matmul_v2`（量化语义） | 标准 = native；变体见场景 [`put-all-gather-quant-matmul`](../scenarios/put-all-gather-quant-matmul/design.md) | AllGather+PUT 已注册 |
+| AllToAll + MX 量化 matmul（K 分段累加 `y = Σ_r A_r @ B_r`） | `kernel/all_to_all_quant_matmul/`（UDMA 版 + hcomm/CCU 版） | `allto_all_matmul`（先通后算+permute）、`matmul_allto_all`（先算后通） | 标准 = native；变体见场景 [`put-all-to-all-quant-matmul`](../scenarios/put-all-to-all-quant-matmul/design.md) | AllToAll+PUT/GET 已注册 |
+| ReduceScatter 语义 + 量化 matmul（先算后通，M 轴输出分片） | 无 | `matmul_reduce_scatter`（M 轴 RS 流水）、`quant_reduce_scatter`（纯量化 RS，one-shot 互读） | `apace_custom`，场景 [`compute-first-reduce-scatter`](../scenarios/compute-first-reduce-scatter/design.md) | ReduceScatter 仅枚举预留；用 AllToAll+PUT + 本地归约组合实现 |
+| AllReduce + 量化 matmul | 无 | `matmul_all_reduce`（量化通信三段式）、`quant_all_reduce`（纯量化 AR one-shot） | 无场景先例——设计前先读 §4 两条技术路线 | AllReduce**无枚举值**；须先扩展（见 [`communication.md`](../fundamentals/communication.md) §7） |
+| 纯量化规约（无 matmul） | 无 | `quant_all_reduce`、`quant_reduce_scatter`（AIV-only 窗口互读 + 边读边反量化累加） | 视同上，评估后登记场景 | 同上 |
+| 分组/变长 token 族（grouped alltoallv 类） | 无 | `grouped_mat_mul_allto_allv` 等 | 零场景命中 → 按注册表规则暂判 `unsupported`，需求澄清后评估登记新场景 | — |
+
+> 语义歧义警示：apace 的 `all_to_all_quant_matmul` 是 **K 分段累加**语义（B 为 `[rankSize*K, N]` 拼接权重、逐 rank L0C 累加），与注册形态 `allto_all_matmul` 的 **permute+单次 matmul** 语义不同。需求若为后者，AIC 数据流须重新设计，仅通信循环骨架可复用。
+
+## 2. 七维架构差异表（注册形态 → apace 直调形态）
+
+| 维度 | 注册形态原型（`mc2/<op>/`） | apace（`apace/`） | 转换动作 |
+|:---|:---|:---|:---|
+| **通信引擎** | AIC 发消息 → HCCL server（AICPU KFC / CCU）执行跨卡搬运 | AIV 直接 UDMA（Urma `WriteNbi/ReadNbi`）写/读对端通信窗口，`Drain` 等完成 | 通信调用全部重写为 `CollectiveComm` 四段式 |
+| **通信同步** | `hccl_.Wait(handleId)` 轮询 GM finishedTurnCnt | `Wait(Drain + TeamBarrier)` + `CrossCoreSetFlag<0x2,PIPE_MTE3>(round)` ↔ `CrossCoreWaitFlag<0x2,PIPE_MTE2>(round)`（flagId=轮次号） | 同步原语全部替换；EVENT_ID 4/5/6 自由约定作废 |
+| **核型分工** | `KERNEL_TYPE_MIX_AIC_1_2`（AIC 兼通信+计算，AIV 辅助 ND2NZ/bias cast） | `KERNEL_TYPE_MIX_AIC_1_1`（AIV 纯通信，AIC 纯 Blaze matmul） | AIV 职责重设计；ND2NZ 链路删除（Blaze 直读 DN） |
+| **matmul 栈** | AscendC `MatmulImpl` / Catlass / mat_mul_v3、qbmm_v3 | Blaze `BlockMmad<MatmulWithScaleMx,...>` + `BlockSchedulerQuantBatchMatmulV3`；多 rank 离散源用 FragmentTensor + blaze_ext | 计算调用全部重写；MX scale 融合语义相通 |
+| **tiling** | op_host 性能建模配平 + tiling key 二进制分发 | host 侧 `QuantMatmulTilingSwat::GetTilingData` + 手写 `CommTilingData`（5 字段）推导；kernel 消费扁平 POD 按值传参 | tiling 生成与下发结构重写 |
+| **workspace/窗口** | op_host 统一规划（gather 区+nd2nz 区+系统区）；输出可零拷贝 | host `CommChannelBuilder` 建链（HcclGetHcclBuffer 窗口 + 独立 barrier 区）；kernel 静态 UB 布局（每 comm 实例 512B + barrier 32B） | 窗口建立与内存规划重写 |
+| **host 拉起** | aclnn 两段式 API + op_graph KFC/CCU 任务生成 + tiling key 注册 | ST 直调：fork 多 rank（rankId=deviceId）→ `HcclCommInitRootInfoConfig` → `CreateDeviceContext` → `<<<usedCoreNum>>>` launch | 接入层整体不在 apace 范围（hcomm 变体是通往注册形态的桥梁，见 [`operator-anatomy.md`](operator-anatomy.md) §6.2 CCU 变体模板） |
+
+量化语义两者共通（MX：data fp8/fp4 + scale e8m0 每 64 元素组 2 字节 sub-scale），可直接借鉴。
+
+## 3. 可参考 vs 必须重写清单
+
+### 3.1 可参考（算法逻辑层）
+
+| 类别 | 内容 |
+|:---|:---|
+| 切分策略 | M 轴切 tile（tileCnt 主块 + tailCnt 尾块）驱动通算重叠；长/短块配平思想 |
+| 流水编排 | 本地数据先算掩盖通信首延迟；tile i+1 通信与 tile i 计算重叠；per-tile 依赖粒度同步（apace 的 dependTileIdx 机制即对应物） |
+| 量化通信三段式 | AllReduce = requant → A2A → 低比特域 reduceSum → AG → 反量化（通信量减半以上） |
+| one-shot 窗口互读 | 各 rank 数据入本卡窗口、读方错卡序轮询互读 + 状态区软同步 + 边读边反量化累加（与 UDMA 模型最同构的原型形态） |
+| 尾块/非对齐处理 | paddedTailM 对齐、尾块单独轮次 |
+| 输出布局 | C 按 rank 分段；AllToAll 结果按 rank 拼接 |
+| 验证基准 | golden = CPU 反量化 + matmul + 通信语义模拟；容差按量化类型分型 |
+
+### 3.2 必须重写（架构适配层）
+
+| 类别 | 注册形态写法 → apace 写法 |
+|:---|:---|
+| 通信调用 | `hccl_.AllGather/AlltoAll/ReduceScatter` → `CollectiveComm<Op, Mode, T, TeamBarrier>` 的 Init/Commit/Wait/Finalize |
+| 通信等待 | `hccl_.Wait(handleId)` → CommPolicy::WaitTile → `CrossCoreWaitFlag<0x2, PIPE_MTE2>(tileIdx)`（UDMA）或 `hccl_.Wait(handle)`（hcomm 变体） |
+| matmul 调用 | `MatmulCompute`/Catlass/qbmm → Blaze BlockMmad（+ blaze_ext Fragment 版） |
+| B 矩阵预处理 | ND→NZ 转换 → 直接 DN 布局进 Blaze（转换链路删除） |
+| tiling 生成 | op_host tilingFunc + tiling key → SWAT 引擎 + 手写 CommTilingData 推导 |
+| host 拉起 | aclnn/op_graph → ST main.cpp 直调（fork + HCCL + `<<<>>>`） |
+| 多 arch 分发 | arch 三套 + tiling key → 单一 dav-3510，dtype 用不同入口函数区分 |
+
+### 3.3 判断口诀
+
+写任何一段代码前自问：
+- 这段代码描述"**算什么、怎么切、何时重叠**"（算法逻辑）→ 参考原型；
+- 这段代码描述"**怎么通信、怎么同步、怎么算、怎么被拉起**"（架构机制）→ 用 apace 组件重写，骨架抄 apace 已有算子。
+
+典型错误：把 `hccl_.Wait()`、`CrossCoreSetFlag(EVENT_ID_6)`、ND2NZ 逻辑、tiling key 分发直接搬进 apace kernel——这些在 apace 中要么不存在、要么语义完全不同。
+
+## 4. AllReduce 类算子的两条技术路线（无 apace 先例，设计前必读）
+
+语义收敛建议（apace 适用范围 = MX 量化通算融合；非量化/伪量化变体不迁移）：
+
+**路线 A：直接规约（WriteReduceNbi）**——扩展 CollectiveComm 新增 AllReduce op，AIV 用 `Hcomm::WriteReduceNbi`（hcomm 原语，支持 int8/16/32、uint32、half、float、bfloat16 + `HcommUrmaReduceOp`）把部分和远程原位规约进对端输出窗口。组件改动最小（先补 `CommCollectiveOp::AllReduce` 枚举值——当前只有 AllToAll/AllGather/ReduceScatter，见 [`communication.md`](../fundamentals/communication.md) §7 扩展指南）；难点是远程规约完成语义（Drain 只保证本端发出，须 CrossDevice barrier 确保对端累加落窗）与首轮覆盖/清零语义（每 tile 独立 slot 天然免清零）。
+
+**路线 B：三段式分解（注册形态验证过的算法骨架）**——AllReduce = AllToAll → 低比特域 ReduceSum → AllGather。复用 apace 已有 AllToAll+PUT、AllGather+PUT 组件；中段 reduceSum 需要 AIV 向量计算（`block/aiv_compute/` 当前为空占位，须先建设）。流水掩蔽时序（第 1 块 ReduceSum 与 A2A 重叠、后续块与前一块 AG 重叠、段间 SyncAll 防精度）借鉴上游仓 `matmul_all_reduce` 的 `based_a2a_rs_ag` 实现。
+
+**建议**：先路线 A 打通功能闭环（顺带沉淀 AllReduce 通信原语），profiling 后若通信量成瓶颈再按路线 B 演进——两条路线 kernel 侧骨架一致（AIC 产 tile → AIV 逐 tile 通信），演进成本低。
+
+## 5. 原型研读操作指引
+
+1. **先读 README.md**（原型算子目录：语义公式、shape/dtype 约束、支持矩阵），再按需读 op_kernel 主实现与 op_host/op_tiling。
+2. 提炼**三要素**记录到 DESIGN.md：
+   - **语义**：公式、输入输出 shape、dtype、约束（整除/对齐/范围）
+   - **算法骨架**：切分轴、通算重叠时序、量化/反量化时机
+   - **验证基准**：golden 生成方式、容差（可直接继承到 ST gen_data/verify_result）
+3. 对照 §3 清单逐项判定借鉴/重写边界，并在 DESIGN.md §0.3 登记判定结果。
+4. 检查原型是否跨算子复用组件——同类思想在 apace 中应沉淀为 `block/` 共享组件而非算子内私货。
+5. 语义参考 ≠ 实现参考：注册形态算子均为 HCCL/CCU 注册实现、未用 apace——只借鉴算法与 golden，代码照 §2 差异表全部重写。

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/apace/operator-design/plan-template.md

@@ -0,0 +1,235 @@
+# {operator_name} MC2 通算融合算子开发计划
+
+> `{operator_name}` → 实际算子名称。本文档在开发流程中持续更新。
+
+本模板是 apace 路线算子的开发计划模板，在 DESIGN 定稿后由设计步骤填写，落地为项目内 `operators/<operator_name>/docs/PLAN.md`。PLAN 沿 MC2 开发主线组织：文件清单（REUSE/MODIFY）→ 通信设计基线（Win 区、Flag、通信轮次 T、localMatmul、tileCnt 扫描）→ 有序动作 → 接线 → 分层 checkpoint（编译 → Tiling 数值 → 多卡冒烟 → 精度 → 性能）→ 交付与回退。第 1、3、9、10 章在设计步骤定稿；第 2、4-8 章随开发更新；第 11 章只追加执行记录。
+
+> 仅 `implementation_route=apace_native | apace_custom` 可以生成 PLAN。`unsupported` 只生成阻塞 DESIGN；补充 Investigation 后仍缺关键事实（如 Win 区容量、Flag 编排、T 推导）时不生成 DESIGN/PLAN。
+
+---
+
+## 1. 需求概述
+
+| 项目 | 内容 |
+|-----|------|
+| 算子名称 | {operator_name} |
+| 通信方向 | PUT / GET / compute-first（来源 DESIGN） |
+| 编排形式 | 严格分离 / 时分复用（来源 DESIGN） |
+| 数学公式 | y = f(x) + 通信语义描述 |
+| 输入 | x1: shape=[...], dtype=...（含每 rank 输入 + **输入分布轴**：按哪轴切/不切） |
+| 输出 | y: shape=[...], dtype=...（含每 rank 输出 + **输出分布轴**：按哪轴分布/不切） |
+| Rank 规模 | rank_size=N，多卡启动方式（apace 直调 ST 为 fork 多进程 + TCP rootInfo 交换，见 host-and-testing.md §2） |
+| 需求类型 | 特定用例 / 通用 |
+
+本章内容与 DESIGN 保持一致，由设计步骤填写；开发中发现需求本身需要变化时，在第 5、11 章记录 `design_issue` 并回到设计步骤处理，不在 PLAN 中直接改写需求。
+
+---
+
+## 2. 文件清单
+
+| 文件 | 状态 |
+|------|------|
+| `kernel/{op_name}_tiling_data.h` — Tiling 结构体（host/device 契约，含 CommTilingData 与 Win/Flag/T 字段） | ⬜ |
+| `kernel/{op_name}_impl.h` — Impl：Init/Run/编排（AIC mm + AIV 通信/归约） | ⬜ |
+| `kernel/{op_name}_frag_kernel.h` — FragmentTensor mm 内核（命名遵循 apace 惯例：`qmm_mx_kernel_{rs/ag/a2a}_frag.h`；compute-first 默认；PUT vendor 复用可省） | ⬜ |
+| `kernel/reduce_sum_ref.h` — 增量归约（compute-first 专属；手动 UB 批量形态；其他路线可省） | ⬜ |
+| `src/kernel_launcher.h` — `__global__` 入口（`KERNEL_TYPE_MIX_AIC_1_1`，dtype 变体） | ⬜ |
+| `src/main.cpp` — Tiling + host 前置校验 + fork 多 rank + HCCL 建链 + launch（perf 模式内嵌 L2 flush） | ⬜ |
+| `src/root_info_exchanger.h` / `src/utils.h` — TCP rootInfo 交换与公共工具（从参考算子复制，REUSE） | ⬜ |
+| `scripts/gen_data.py` + `scripts/verify_result.py` — 数据生成与多 rank 校验 | ⬜ |
+| `cases.csv` — 用例矩阵（含 tile 粒度参数列） | ⬜ |
+| `run.sh` — 一键脚本（build/gen/run/verify/perf） | ⬜ |
+| `CMakeLists.txt` — 独立工程构建（APACE_ROOT 指向 CANN 内置 apace，禁止复制共享层） | ⬜ |
+
+每行标注 `REUSE`（复用已有文件）或 `MODIFY`（新建/修改）。实施阶段更新状态；新增项同时记录第 11 章。每行映射 §9 冻结合同的目标文件清单。`apace_native` 路线官方框架已覆盖全部需求时，kernel 侧可无新建文件（仅工程壳 + 接线），在清单首行显式注明"native 路线无 kernel 新建"。
+
+---
+
+## 3. 设计基线（冻结合同摘要）
+
+| 合同项 | 冻结值 | DESIGN 引用 |
+|--------|--------|------------|
+| 通信方向与编排形式 | PUT/GET/compute-first；AIC↔AIV 触发关系 | DESIGN §x |
+| Rank 规模与启动 | rank_size、rank_id 获取方式、启动命令 | DESIGN §x |
+| Win 区分配 | 每 buffer 容量、偏移表（send/recv/workspace/flag 区） | DESIGN §x |
+| Flag 编排 | flag 数量、含义、置位/等待时序（AIC→AIV / AIV→AIC） | DESIGN §x |
+| 通信轮次 T 推导 | kernel 侧 `commTurn = splitAxisTileCnt + splitAxisTailCnt`（operator-anatomy.md §3）；compute-first 路线 host 派生默认 `T \| mSeg` 无尾块、单尾块 ≤ 头块可直传（多尾块/尾>头走 padding 策略，其他路线按其语义推导），推导过程与取值依据 | DESIGN §x |
+| L2 flush 集成 | flush 时机（每轮 / 每 T 轮）、调用点 | DESIGN §x |
+| tileCnt 扫描策略 | 固定 / 二分扫描范围、选择判据 | DESIGN §x |
+| 精度标准 | 多 rank 精度矩阵对比阈值、非有限值门禁 | DESIGN §x |
+
+本章各项取自已定稿的 DESIGN，开发阶段只读；需要变更时记录 `design_issue` 并回到设计步骤。
+
+---
+
+## 4. 有序开发动作
+
+| 顺序 | 动作 | 前置 | 预期输出 | 验证 |
+|------|------|------|---------|------|
+| A1 | 工程框架 + CMake + 空 Kernel 编译 | 无 | 可执行文件编译通过 | build 成功 |
+| A2 | TilingData + Host Tiling（Win offset/T/flag 计算） | A1 | Tiling 单测/打印正确 | 数值核对 |
+| A3 | Kernel 实现（通信+计算协同、Flag 时序、L2 flush） | A2 | 编译通过 | 静态走查 |
+| A4 | 冒烟：最小 shape 单轮通信跑通 | A3 | 多卡运行不挂死 | 退出码=0 |
+| A5 | 精度：多 rank 精度矩阵全量用例 | A4 | §6 全部通过 | verify 通过 |
+| A6 | 性能：tileCnt 扫描 + msprof 采集 | A5 | §7 达标判定 | 性能基线对比 |
+
+顺序与前置关系必须确定；不能只写"参照文档实现"。失败回退见 §9。
+
+---
+
+## 5. 接线合同（Wiring）
+
+| 接线项 | 内容 |
+|--------|------|
+| CMake target | 可执行文件名、源文件列表、compile flags |
+| include 路径 | CANN 内置 apace 头文件路径（APACE_ROOT 直引，禁止复制共享层）、HCCL 头文件路径、kernel/host 共用 tiling 头路径 |
+| 链接库 | libhccl / ascendcl / runtime 库及链接顺序 |
+| Win 区接线 | 每逻辑 buffer → Win 区物理偏移映射表 |
+| Flag 接线 | 每 flag 索引 → 触发方/等待方/时序点映射 |
+| Launcher 接线 | rank_id/rank_size 传入路径、device 绑定、IPC/句柄初始化 |
+
+本章只把 DESIGN 已确定的 Win/Flag/通信合同落到具体工程接线，不引入 DESIGN 之外的新设计。
+
+---
+
+## 6. Checkpoints（分层验证）
+
+| checkpoint | 在动作后 | 范围 | 预期结果 | 完成条件 |
+|-----------|---------|------|---------|---------|
+| C1 编译 | A1 | 构建 | 编译链接通过 | 产物存在 |
+| C2 Tiling | A2 | host | offset/T/flag 数值正确 | 与 §3 冻结值一致 |
+| C3 冒烟 | A4 | 设备 | 最小用例多卡不挂死、退出码 0 | 日志无 timeout/hang |
+| C4 精度 | A5 | 设备 | 多 rank 精度矩阵全部通过 | Max Diff ≤ 阈值 |
+| C5 性能 | A6 | 设备 | msprof 数据归档、达标判定 | 满足 DESIGN 性能标准 |
+
+每个上设备的 checkpoint 必须记录执行上下文（rank_size、设备节点、实际命令、返回码），并区分实现失败、启动前风险与环境不可用；只有真实多卡执行证据才能判定该 checkpoint 通过。
+
+---
+
+## 7. 交付、清理与回滚
+
+| 交付件 | 来源动作 | 验收 checkpoint | 清理要求 |
+|--------|---------|----------------|---------|
+| 可执行文件 + 启动脚本 | A1-A3 | C1/C3 | 保留 |
+| 精度报告（多 rank 矩阵） | A5 | C4 | 归档 docs/ |
+| 性能数据（msprof + tileCnt 扫描表） | A6 | C5 | 归档 docs/perf/ |
+
+回滚规则：实现层失败（编译/精度/挂死）→ Step 4 内诊断修复并重跑受影响 checkpoint；需改变通信方向、Win/Flag 编排、T 语义、支持域或验收标准 → 回 Step 3；缺 MC2 源码事实 → 回 Step 2；环境/设备不可用 → 记录为环境阻塞，不当作设计问题回退。备选方案不会因失败自动启用。
+
+---
+
+## 8. 实施阶段持续更新区
+
+### 8.1 已知问题和决策记录
+
+| 日期 | 问题/决策 | 说明 |
+|------|----------|------|
+
+### 8.2 多 rank 精度矩阵结果
+
+**状态**: ⬜
+
+| 用例 | rank_size | shape | dtype | 各 rank Max Diff | 结果 |
+|------|----------|-------|-------|-----------------|------|
+| P1 随机数据 | | | | | ⬜ |
+| P2 零值 | | | | | ⬜ |
+| P3 边界/tail | | | | | ⬜ |
+
+### 8.3 性能结果
+
+**状态**: ⬜ | **数据**: docs/perf/round_NNN/
+
+| tileCnt | Task Duration | 通信占比 | 判定 |
+|---------|--------------|---------|------|
+
+实施阶段持续追加，不覆盖历史行；不改变冻结的精度与性能验收标准。
+
+---
+
+## 9. 冻结开发合同
+
+### 9.1 PLAN Metadata 与 DESIGN 绑定
+
+```text
+plan_template_provider: /ascendc-mc2-best-practice
+plan_template_path: references/foundations/apace/operator-design/plan-template.md
+project_root:
+operator_name:
+operator_root: <project-root>/operators/<operator_name>/
+design_path: operators/<operator_name>/docs/DESIGN.md
+implementation_route: apace_native | apace_custom
+selected_scenario: <仅 apace_custom 填写，场景注册表 scenarios/index.md 的语义命中场景 ID>
+communication_direction: PUT | GET | compute-first
+orchestration_form:
+rank_size:
+multi_rank_launch:
+cann_version: <Step 1 environment.md 实测登记的 CANN 版本>
+apace_source_ref: <APACE_ROOT 实测路径 或 fetch_apace.sh manifest 的 pin commit>
+win_area_layout_ref:
+flag_orchestration_ref:
+rounds_t_derivation_ref:
+l2_flush_integration_ref:
+tilecnt_scan_strategy_ref:
+precision_matrix_contract_ref:
+design_frozen_status: ready | blocking
+plan_owner: design_stage
+execution_owner: implementation_stage
+frozen_plan_status: ready | blocking
+```
+
+`frozen_plan_status=ready` 表示设计基线章节（1、3、9、10）已定稿，第 2、4-8、11 章仍随开发更新。
+
+### 9.2 目标文件与交付范围
+
+`target_file_manifest` 每项包含：`file_id / target_file / file_role / action_type: create | copy_and_adapt | modify | read_only / source_refs / design_contract_refs / expected_artifact`。所有 `target_file` 以 `operators/<operator_name>/` 开头；apace 官方源码（CANN 内置框架）与参考算子只登记为只读来源，禁止修改。
+
+### 9.3 有序开发动作
+
+`ordered_actions` 每项包含：`action_id / sequence / design_contract_refs / source_refs / target_files / action / prerequisites / expected_output / verification / failure_rollback`。涉及 Win 区 buffer、Flag、Tiling、Kernel entry 或 Launcher 的动作必须引用 §3 对应冻结合同项。
+
+### 9.4 分层验证 Checkpoint
+
+`validation_checkpoints` 每项包含：`checkpoint_id / after_action_ids / test_scope / inputs / expected_result / evidence_to_record / failure_rollback`。覆盖静态合同核对（Win offset/Flag/T 与 TilingData 一致）、构建、冒烟、多 rank 精度、边界/tail、重复运行与最终回归。第一个设备 checkpoint 前必须静态核对 Win 区偏移与 Flag 时序闭合，缺失不允许启动 Kernel。
+
+### 9.5 失败停止与回退
+
+- apace 源码事实被推翻：保留证据回 Step 2；
+- DESIGN/PLAN 缺启动实现必需事实（Win 容量、Flag 编排、T 推导、tileCnt 策略）：回 Step 3；
+- 多卡挂死/通信超时：先按 troubleshooting  playbook 诊断（Flag 时序、L2 flush、Win 溢出），确认为实现问题则 Step 4 内修复；
+- 修复显示必须改变通信方向、编排形式、Win/Flag 语义、支持范围或验收标准：回 Step 3；
+- 设备/NPU 资源不可用：经 `qrun` 排队执行，记录为环境阻塞，不当作设计问题回退。
+
+**章节维护分工**：第 1、3、9、10 章由设计步骤定稿，开发阶段不改动；第 2、4-8 章由开发阶段持续更新；第 11 章只追加。设计基线需要变化时，记录 `design_issue` 并回到设计步骤。
+
+---
+
+## 10. 冻结验收合同（Readiness 门禁）
+
+- `implementation_route` 只能为 `apace_native` 或 `apace_custom`；
+- 通信方向、编排形式、rank_size、Win 区布局、Flag 编排、T 推导、L2 flush、tileCnt 策略、多 rank 精度矩阵均有冻结值且无 TBD；
+- 所有 action 字段完整，依赖顺序无环（编译 → 冒烟 → 精度 → 性能）；
+- 每个验证合同有 checkpoint，多 rank 精度矩阵每个用例可追溯 DESIGN 需求；
+- 多卡启动命令、Win/Flag 接线、链接库均已在 §5 闭合；
+- 所有交付件均可追溯到动作与 checkpoint；无 TBD、无未决分支、无未解除的 blocking。
+
+---
+
+## 11. 执行记录（只追加）
+
+设计步骤只建立空表；开发阶段只追加：
+
+```text
+执行记录:
+  - 记录编号
+    动作或检查点编号
+    起止时间
+    实际变更文件
+    实际输出
+    结果: 完成 | 失败 | 环境阻塞
+    证据引用
+    与计划的偏差
+    已执行的回退
+    下一步动作或返回步骤
+```
+
+任何改变通信方向、编排形式、Win/Flag 语义、T 语义、验收标准或支持域的 deviation 都必须停止；项目根内新增文件、实现调整、tileCnt 实际值、同步实现或配置修复应更新第 2、4-8 章并追加执行记录，不修改第 9、10 章或 DESIGN。

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

@@ -0,0 +1,96 @@
+# apace 路线代码审查验收条件
+
+> Reviewer 在 Step 4 逐项检查。违反任意**硬红线**项 = FAIL。
+> 本文件是**全局红线**的唯一规范源（规则全文、理由与"详见"链接）；**场景约束**的完整定义以对应场景文档为规范源，本表只做索引与一句话判定。编号 R1-R21 保持稳定，跨文档引用不断链。
+>
+> **条目分级（Reviewer 必读）**：本表条目分两级——
+> - **硬红线**：违反 = FAIL（正确性/死锁/共享层完整性问题，如 R1-R8/R11-R13/R20 的主体）
+> - **风险提示**：原文含"生产实测经验值/官方无显式约束/边界未定"限定词的数值约束（如 512KB 单轮 PUT、flag 计数深度），违反**不直接 FAIL**——按 case 复核（连续多轮精度 + 重复 launch 一致性 + profiling 证据）；仅当复核证据缺失或实测失败才 FAIL。**镜像/转述这些条目时禁止删去限定词升格为硬门禁**（历史教训：经验阈值写成 host 强制拒绝曾误拒合法 shape）。
+>
+> **镜像同步纪律（修订者必读）**：R 条目镜像处——本表（唯一规范源）/ SKILL.md 红线索引 / fusion.md §6.2.10 / architecture.md §10 / operator-anatomy.md §5.8/§7.6 / 场景 design.md / 场景 development.md。修改任意一处 R 条目时，**其余镜像处必须同步检查**；本文件为唯一规范源，镜像处只做索引与一句话判定，禁止在镜像处展开规则细节（512KB 事故即镜像措辞漂移逐级扩散所致）。
+
+## 全局红线定义（所有 apace 算子必须满足）
+
+| # | 约束 | 说明 | 详见 |
+|---|------|------|------|
+| R1 | 禁止 `__schedmode__(1)` 和 `[[bisheng::core_ratio(1,1)]]` | 会导致 AIC/AIV 串行调度→死锁（`aclError:507015`）；核配比唯一由 `KERNEL_TYPE_MIX_AIC_1_1` 保证为 1:1 | [`architecture.md`](fundamentals/architecture.md) §10 ① |
+| R2 | 有 `KERNEL_TYPE_MIX_AIC_1_1` | 每个入口函数都含核配比声明 | [`architecture.md`](fundamentals/architecture.md) §10 ① |
+| R3 | 入口变体覆盖 dtype 合同全部组合 + host 运行期 dispatch | 变体数由 dtype 合同决定（FP8 E4M3/E5M2 双组合 = 4 变体；单一组合可单入口）；硬编码单入口 → 异 dtype 字节流被错误模板解释，精度系统性失败 | [`operator-anatomy.md`](operator-design/operator-anatomy.md) §5.3/§7.2 |
+| R4 | `block/` `tiling/` 未修改 | 与官网仓原始文件完全一致 | [`architecture.md`](fundamentals/architecture.md) §10 ③ |
+| R5 | CrossCore flag idx 配对 | AIV `WaitFlag` idx == AIC `SetFlag` idx（含计数式配对） | [`fusion.md`](fundamentals/fusion.md) §3 |
+| R6 | CommContext 与引擎匹配 | UDMA 模式有 `__gm__ CommContext*`；HCCL windows 无 | [`communication.md`](fundamentals/communication.md) |
+| R7 | 禁止 `AscendC::Matmul` 高阶 API | 高阶 API 不支持 AIV+URMA 直调场景（与 blaze-shmem 共享此约束） | [`compute.md`](fundamentals/compute.md) |
+| R8 | 禁止 HCCL 高阶 API（`Hccl::*`） | HCCL 集合通信库依赖框架注入上下文，AIV+URMA 直调场景拿不到（与 blaze-shmem 共享此约束） | [`comm_shmem.md`](../blaze-shmem/comm_shmem.md) §5 |
+| R11 | host 前置校验在 fork/建链前拒绝非法输入 | 整除/对齐/核数下限/Win 容量等**正确性类**校验，报错可操作，main.cpp 与 gen_data.py 双侧；compute-first 场景的完整清单（含归约核数/对齐/Win 容量）见场景文档。⚠️ 风险提示类数值（512KB 单轮 PUT、flag 计数深度）**不进强制拒绝清单**（见头部条目分级） | [`development-guide.md`](operator-design/development-guide.md) §3.5 |
+| R12 | UB 静态通信区隔离 | commBuf/barrierBuf 与 TPipe 管理 buffer 物理隔离（静态偏移或 guard TBuf），混用重叠 → 通信数据被踩踏 → 死锁 | [`communication.md`](fundamentals/communication.md) 陷阱 #9 |
+| R13 | 通信默认多核并行 | 通信对象 `totalJobs=rankSize`（每核负责 1 个 target 并行 PUT）；TeamBarrier `totalJobs` 官方为 `rankSize`（`teamBarrier_.Init(buf, ctx, rankSize, GetBlockIdx())`——前 R 核映射下 CrossDevice 由 `Wait<BARRIER_DEVICE>` 内建触发）。compute-first 后 R 核映射的自研编排可采用 TeamBarrier totalJobs=1 + 显式 CrossDevice 替代，两种映射不得混用。"多核写同一 UBMEM flag 竞态 → 退化为 totalJobs=1"是已证伪的臆造约束：退化为单核串行 PUT 通信时间放大 R 倍 | [`communication.md`](fundamentals/communication.md) §2.2；[`optimization-playbook.md`](troubleshooting/optimization-playbook.md) §3 |
+| R14 | Win 区数据/元数据分离（硬红线）；单轮 PUT 大小（风险提示） | ① **硬红线**：PUT/GET 数据不得覆盖 Win 区内元数据/barrier 区（偏移按 host 建链布局确定，host/kernel 同源）：官网布局 barrier flag 在独立 BARRIER_BUF、Win 数据区从 0 可用；共享布局须按约定偏移跳过头部（布局细则与已验证实现见 [`communication.md`](fundamentals/communication.md) 陷阱 #12；缺失 → 覆盖 flag → "假通过"）。② **风险提示**：单轮 PUT 大小无官方硬上限（bring-up 期过大单轮曾见间歇失败，边界未定）——大单轮 PUT 按 case 复核精度+重复 launch 一致性，不作 host 强制拒绝 | [`communication.md`](fundamentals/communication.md) 陷阱 #12/#13；[`fusion.md`](fundamentals/fusion.md) §6.2.4 |
+| R15 | 投产级性能验证门槛 | 精度 PASS 不算投产：性能验证必须覆盖真实大 shape 矩阵（非 toy shape）× R=2/4 双档，并与参考路径对标归档；仅基线采集、无对标 = 未达投产门槛。基线候选按算子族枚举：mc2 融合算子（RS 族含 `aclnnMatmulReduceScatterV2`，CANN 9.1.0/9.2.0 opp 内置 ascend950/ops_transformer 下已验证存在、fp8_e4m3fn 输入实跑可用；注意其无 MX scale 输入为 per-tensor 量化语义，对标须声明差异）/ hccl 分步（mm + HcclReduceScatter）。**aclnn 对标算子调用契约坑（CCU 引擎直调不可行、scale 形状校验、group 机制等生产试错记录）见 [`scenarios/compute-first-reduce-scatter/development.md`](scenarios/compute-first-reduce-scatter/development.md) §4.1**。候选检索方法：按 op 名模式搜 `$ASCEND_HOME_PATH/opp/built-in/op_impl/ai_core/tbe/kernel/`，勿只查单一算子名即下 N/A 结论 | [`host-and-testing.md`](operator-design/host-and-testing.md)；[`optimization-playbook.md`](troubleshooting/optimization-playbook.md) §1 |
+| R20 | perf 模式 L2 flush 实接线 | 性能采集每轮主 kernel 前必须实际调用 L2 flush kernel（msprof 记录数 == 轮数）；只分配 cacheFlush buffer 不调 kernel = 死代码 = MTE2 带宽虚高 | [`host-and-testing.md`](operator-design/host-and-testing.md) §4 |
+
+## 场景约束（按算子语义特征自动适用，完整定义以场景文档为规范源）
+
+> **适用判据（不依赖场景注册表命中）**：代码含 compute-first 编排（先算后通信、staging 即通信源）即适用 R9/R10/R16；含归约模块（reduceSum）即适用 R17-R19。Reviewer 只要看到对应代码形态就必须检查，不得以"场景未正式命中"为由跳过。
+
+| # | 适用场景 | 约束（一句话判定） | 规范源 |
+|---|---------|---------------------|--------|
+| R9 | compute-first | CrossCore flag **Set/Wait 严格配对**（硬红线：不配对 = 未定义行为/挂死）+ flagId 数量 16（0-15）为硬件事实；**每 flagId 计数器 0-15 衡量未消费积压**（官方有据；紧邻配对下 ≈1-2 不触顶，**不构成 T 上限**；计数式固定 flagId 配对工程验证 T=16）——T 上限按 case 实测确定，不设 host 强制数值拒绝 | [`fusion.md`](fundamentals/fusion.md) §6.2.3 |
+| R10 | compute-first | T 派生优先 `T \| mSeg` 无尾块（实现最简）；**单尾块且尾块 ≤ 头块（16 对齐）时 PUT 直传合法**（偏移精确，工程验证）；多尾块/尾块>头块走策略 A（tail padding 32 对齐 + realFragmentSize 限读 + 多套 tiling）——三条路径均合法，禁止为凑无尾块而牺牲流水粒度 | [`fusion.md`](fundamentals/fusion.md) §6.2.7 |
+| R16 | compute-first | A 各 rank 段 GM 连续时 mm 默认 FragmentTensor 消 R 循环（约束 `R ≤ 32` = 单次构建 fragment 数上限，与 T 无关）；vendor R×T 子调用路径须论证 SCALAR 占比可接受（R×T 小 + 大 shape） | [`fusion.md`](fundamentals/fusion.md) §6.2.2 |
+| R21 | compute-first | **localLast 编排禁止移除**：frag kernel 必须含 fragment 重排 `[remote..., local]` + 边界提前 SetFlag(flagA)；以"每轮 Set 双 flag"替代会导致 flagId 用量翻倍 + 丧失通信提前启动。`cFragAddrs_` 顺序写错才是 A/C 错位根因，非 localLast 本身 | [`fusion.md`](fundamentals/fusion.md) §6.2.2 |
+| R17 | compute-first（含归约模块） | 归约搬入/输出用 2D DataCopyPad 且 blockCount=本批行数（多行批量 + 手动 UB）为**性能推荐形态**；**例外**：MTE2-bound 算子中逐行 1D 路径可为参考形态（通信被 mm 掩盖时性能不劣化——须 profiling 证据支撑，性能不达标再改批量）；strided 场景隐式上限防御见下层 API 文档。**归约必须多核分治**：归约核集合内按连续行块均分本轮行（余数前摊，每核只处理自己的行区间），禁止单核归约（如 `GetBlockIdx()==0` 独立承担全量行 = 写竞争/归约独占 = FAIL） | [`fusion.md`](fundamentals/fusion.md) §6.2.6；`ascendc-api-best-practices` skill `references/api-pipeline.md` / `api-datacopy.md` |
+| R18 | compute-first（含 BF16→FP32 归约） | 禁止 in-place BF16→FP32 Cast（FP32 占 2× 空间覆盖未读 BF16 → 精度系统性错误），必须独立 srcFP32 双缓冲 | [`fusion.md`](fundamentals/fusion.md) §6.2.6 纪律 2；`ascendc-api-best-practices` skill `references/api-precision.md` |
+| R19 | compute-first（含归约模块） | MTE2_V/V_MTE2/V_MTE3/MTE3_V 四类 HardEvent 同迭代 Set/Wait 配对（含循环结束消费残留事件）；Set 无配对 Wait = 挂死（507014） | 事件模板：[`scenarios/compute-first-reduce-scatter/development.md`](scenarios/compute-first-reduce-scatter/development.md) §5.3；纪律：[`fusion.md`](fundamentals/fusion.md) §6.2.6 |
+
+## 红线项（操作化检查方法）
+
+> 场景约束（R9/R10/R16/R21/R17-R19）仅在对应场景命中时检查；其余为全局检查项。
+
+| # | 检查方法 |
+|---|---------|
+| R1 | `grep -rn "schedmode\|core_ratio"` 应为空 |
+| R2 | 每个 `__global__` 入口函数含 `KERNEL_TYPE_MIX_AIC_1_1` |
+| R3 | 入口变体数 == dtype 合同组合数（FP8 双组合 = 4 变体）；main.cpp 有运行期 dtype dispatch，无硬编码单一入口 |
+| R4 | `block/` `tiling/` 与官网仓原始文件 diff 一致；算子目录无共享层副本 |
+| R5 | AIV `WaitFlag` idx == AIC `SetFlag` idx（含计数式配对） |
+| R6 | UDMA 模式入口有 `__gm__ CommContext*`；HCCL windows 无 |
+| R7 | `grep -rn "AscendC::Matmul"` 应为空 |
+| R8 | `grep -rn "Hccl::"` 应为空 |
+| R9 | AIV `WaitFlag` idx == AIC `SetFlag` idx 且 Set/Wait 次数严格配对（含计数式固定 flagId）；flagId ∈ [0, FLAG_ID_MAX)；**无计数深度类数值断言要求**（计数器 0-15 衡量未消费积压、不构成 T 上限，T 上限按 case 实测）；**若以"每轮 Set 双 flag"替代 localLast 双 flag = 性能 FAIL**（[`fusion.md`](fundamentals/fusion.md) §6.2.2/§6.2.3） |
+| R10 | T 派生：`T \| mSeg` 无尾块 / 单尾块 ≤ 头块直传 / 策略 A padding 三形态任一合法；单尾块时 tailM 16 对齐且 `commTilingData` 如实填 tail 字段、tail tiling 入参 m=R×tailMSize；多尾块或尾块>头块必须走策略 A |
+| R11 | host 前置校验在 fork/建链前执行，main.cpp 与 gen_data.py 双侧；非法输入报错可操作；compute-first 场景 9 项齐全（场景 development.md §3.1） |
+| R12 | commBuf/barrierBuf 与 TPipe 管理 buffer 物理隔离（静态偏移或 guard TBuf）；**`TPipe` 与 `MakeMemPtr` 必须二选一，禁止混用**——`grep -n "TPipe\|InitBuffer" kernel/` 与 `grep -n "MakeMemPtr" kernel/` 若同时出现于同一 kernel 目录且未隔离 = FAIL（[`operator-anatomy.md`](operator-design/operator-anatomy.md) §4.3） |
+| R13 | 通信对象 `totalJobs=rankSize` 多核并行；TeamBarrier `totalJobs` 按分核映射取值（官方前 R 核映射 = rankSize；compute-first 后 R 核映射 = 1 + 显式 CrossDevice），两种映射不得混用；出现"totalJobs=1 避免 UBMEM flag 竞态"类设计（指**通信对象**退化单核）= FAIL |
+| R14 | Win 数据/元数据偏移 host/kernel 同源（硬红线）；单轮 PUT 大小无强制 512KB 校验要求（风险提示级：大单轮 PUT 须有 case 复核证据——连续多轮精度 + 重复 launch 一致性） |
+| R15 | profiling/ 含真实大 shape × R=2/4 双档 × 三路径对标归档；仅 toy shape 基线 = FAIL |
+| R16 | mm 内核为 FragmentTensor 自研；vendor 路径 DESIGN.md 有 SCALAR 占比论证；"vendor kernel + FragmentTensor C 输出"设计 = 阻塞级错误 |
+| R21 | frag kernel 含 localLast fragment 重排（`[remote..., local]` + 边界提前 SetFlag(flagA)）；`grep -n "localLast\|remote.*local\|flagA" kernel/` 无 localLast 相关代码 = FAIL；每轮 Set 双 flag（flagA+flagB）替代 localLast 双 flag = 性能 FAIL（峰值 2T） |
+| R17 | 归约搬入/输出 2D DataCopyPad 且 blockCount=本批行数；strided 场景（N>单次列宽）有 redUbM≤32 或 1D 退化（例外条件见场景约束 R17） |
+| R18 | 归约有独立 srcFP32 双缓冲；`grep -n "Cast<float" kernel/` 确认无 in-place 加宽 Cast |
+| R19 | MTE2_V/V_MTE2/V_MTE3/MTE3_V 同迭代 Set/Wait 配对；循环结束有残留事件消费（含次数守卫） |
+| R20 | perf 循环每轮调用 L2 flush kernel；msprof 结果中 flush kernel 记录数 == 轮数 |
+
+## 常见 FAIL 原因
+
+| 现象 | 根因 | 修复方向 |
+|:---|:---|:---|
+| 代码中含 `__schedmode__(1)` | 误加调度属性 | 删除，核配比由 `KERNEL_TYPE_MIX_AIC_1_1` 保证 |
+| 代码中含 `Hccl::AllReduce` | 误用 HCCL 高阶 API | 改用 `CollectiveComm` 四段式 API |
+| 代码中含 `AscendC::Matmul` | 误用 asc-devkit 接口 | 替换为 `Blaze::Gemm::Block::BlockMmad` |
+| `block/` 或 `tiling/` 有改动 | 误改共享层 | 恢复共享层文件，只在 `kernel/<op>/` 下改 |
+| 精度对不上但无报错 | flag idx 不配对 / splitKNum 配置错 | 核对 flag 编排和 splitKNum 规则 |
+| 死锁（aclError:507015） | schedmode 或 flag 不配对；**或通信 UB 静态区被 TPipe 分配覆盖** | 检查无 schedmode；检查 CrossCore flag idx 配对；检查 guard TBuf/静态偏移隔离（[`communication.md`](fundamentals/communication.md) 陷阱 #9） |
+| golden 全错且误差不收敛 | golden 切分轴/每卡语义写错 | 回设计阶段核对 golden 语义小节（[`workflow_integration.md`](workflow_integration.md) Step 2 §golden 语义），先修 gen_data 再怀疑 kernel |
+| T=1 全 PASS、T>1 精度错 | 多 tile 布局或流水路径 bug（T=1 退化路径会掩盖） | 按 tile/轮次定位超差分布，核对多 tile 下的输出布局与 flag 计数配对 |
+| 性能差：通信时间 ≈ R × 单 target 时间 | 通信对象被退化为单核 totalJobs=1 串行 PUT（臆造"UBMEM flag 竞态"约束） | 通信对象改 totalJobs=rankSize 多核并行（R13）；TeamBarrier 按分核映射取值（官方前 R 核映射 = rankSize；compute-first 后 R 核映射 = 1 + 显式 CrossDevice） |
+| 性能差：AIC CUBE/MTE2 流水占比接近饱和但 cube_utilization 极低 | R×T 子 mm 调用每轮重建 Params，SCALAR 主 bound（特征信号） | 改 FragmentTensor 一次调用消 R 循环（R16）/ 减少 T / Params 增量更新（[`fusion.md`](fundamentals/fusion.md) §6.2.2） |
+| 性能差：归约模块耗时高、归约 VEC 占比低但 flag/同步频繁 | 逐行归约（blockCount=1），flag 次数 = 行数×N段数×R | 手动 UB + 多行批量归约 + 2D DataCopyPad blockCount=多行（R17） |
+| 精度"假通过"但大 shape/多轮紊乱 | PUT/GET 数据覆盖了 Win 区内元数据/barrier 区 | 数据区与元数据区分离，host/kernel 偏移同源（R14）——精度验证发现不了，靠红线拦截 |
+| compute-first 归约读 staging 得 0/旧值 | 多核归约写竞争（多核写同一 yGm）、flag 配对缺失，或归约地址与 mm 写入不同源——**非 cache 问题** | 按序排查：flag idx 配对 → 归约多核分治（R17）→ staging 写/读地址同源；**禁止直接对 staging 加 dcci**（staging 可见性由 CrossCore flag 配对保证，参考实现不依赖 dcci，加 dcci 属误诊掩盖真根因，见 [`communication.md`](fundamentals/communication.md) 陷阱 #14） |
+| 死锁（aclError:507014，Ascend 950 归约路径） | 归约 SetFlag\<V_MTE2\> 无配对 WaitFlag（跨迭代 Set-Set 无中间 Wait） | 补齐 pingpong slot 事件配对 + 循环结束消费残留事件（R19，事件模板见 [`scenarios/compute-first-reduce-scatter/development.md`](scenarios/compute-first-reduce-scatter/development.md) §5.3） |
+| 精度 FAIL：E5M2 变体全元素不通过且误差量级稳定（不收敛） | main.cpp kernel dispatch 硬编码为 E4M3E4M3 入口，E5M2 字节流被 E4M3 模板错误解释 | 实现全部 dtype 变体入口 + host 运行期 dtype dispatch 宏（R3，[`development-guide.md`](operator-design/development-guide.md) §3.5） |
+| 精度 FAIL：N>redUbN 时部分输出为零，呈周期性分布（period=redUbM） | 2D DataCopyPad srcStride>0 时 blockCount 超 DAV_3510 隐式上限（约 29-32 行），超出行静默丢零 | host 限制 redUbM ≤ 32（方案 A）+ strided 场景 1D 逐行（方案 B），（R17 例外，[`fusion.md`](fundamentals/fusion.md) §6.2.6 纪律 3） |
+| 精度 FAIL：归约结果系统性错误（误差随来源序累积） | in-place BF16→FP32 Cast，FP32 输出覆盖同 buffer 未读 BF16 数据 | 独立 srcFP32 双缓冲（R18） |
+| perf 模式 MTE2 带宽虚高 / 性能数据不可复现 | L2 flush 未接线（cacheFlush buffer 分配但未调用 kernel，死代码） | 接入 heavy_add_kernel 每轮 flush + 同步（R20，[`host-and-testing.md`](operator-design/host-and-testing.md) §4 模板） |
+| 大 shape 无法运行 / 运行期间歇 FAIL | 正确性类校验缺失（m%R、scale 偶数、tailM 16 对齐、Win 容量、usedCoreNum≥R+1）；或单轮 PUT 超大**且无 case 复核证据**（风险提示级，非必然缺陷——更大单轮亦有稳定运行实例） | 补正确性类 host 校验（R11）；单轮 PUT 大时先跑通小单轮再放大并复核精度+重复 launch 一致性（R14 风险提示） |
+| DESIGN.md 与代码不一致 | localMatmul 等参数变更后未同步文档 | 同步 DESIGN.md |

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/apace/scenarios/compute-first-reduce-scatter/design.md

@@ -0,0 +1,107 @@
+# compute-first-reduce-scatter 场景设计指导
+
+> **定位**：apace 定制扩展场景设计合同。需求语义命中本场景判据时默认查阅（规则见 [`../index.md`](../index.md)）；设计细节（flag 硬件规则、分核惯例、Win 区布局）以 `../../fundamentals/fusion.md` §6.2 与 `../../fundamentals/communication.md` 为唯一事实源，本文不重复推导，只冻结场景级决策。
+
+## 1. 场景头
+
+| 项目 | 内容 |
+|:---|:---|
+| 场景 ID | `compute-first-reduce-scatter` |
+| 支持范围 | compute-first 模式，ReduceScatter 语义 + QuantMatmul 融合，输出沿 M 轴按 rank 切分，UDMA 直调 |
+| 准入条件（语义判据） | **逻辑语义为 ReduceScatter**（每 rank 输出 M 轴分片、跨 rank 求和）；localMatmul 为 QuantMatmul；compute-first（先算后通信）；通信走 UDMA |
+| 状态 | 已实现（有生产实现：先本地计算、再 AllToAll PUT + 本地增量归约实现 ReduceScatter 语义——通信实现方式为本场景设计决策，非准入前提）。⚠️ 官方 master 在 pin 快照之后已新增 **ReduceScatter UBMEM 路径模板**（`8fbd92b1d`，`kernel/fusions/quant_matmul_reduce_scatter/` 等 17 文件）——本场景仍定位 UDMA 直调路径的自研编排；设计前须按 [`communication.md`](../../fundamentals/communication.md) §8 漂移登记核对 master 是否已直接覆盖需求 |
+
+## 2. Consumes
+
+| 输入工件 | 来源 | 消费内容 |
+|:---|:---|:---|
+| `matmul 链路事实` | 设计前核对（内联于 DESIGN.md §0.3） | QuantMatmul 链路事实：Blaze 模板组件（`BlockMmad` + `BlockScheduler` + `MatmulWithScaleMx`）、dtype 组合、M/N/K 与对齐约束、localMatmul 模式候选 |
+
+缺少 matmul 链路事实 或其中任一事实为 `unknown`/`not_found` 时，停止并返回 Step 2 补充调查，禁止在本场景中推测补齐。
+
+## 3. 设计边界（compute-first 专属合同）
+
+### 3.1 通信方向与编排
+
+| 项目 | 合同 | 事实源 |
+|:---|:---|:---|
+| 通信方向 | compute-first（compute → communication）：先完成本地 mm，再以 AllToAll PUT + 本地增量归约实现 ReduceScatter 聚合语义 | fusion.md §6.2 |
+| 编排形式 | 严格分离（专职化）：**后 R 核通信 / 前 (核数-R) 核归约**，`AllToAll(t) ∥ Reduce(t-1)` 错位流水 | fusion.md §6.2.2 |
+| 分核映射 | 通信核：`jobIndex = GetBlockNum() - 1 - GetBlockIdx()`，最大 blockIdx → jobIndex 0；归约核：`blockIdx < rsCoreNum`。**禁止**套用通信在前算子的"前 R 核"惯例 | communication.md §2 |
+
+### 3.2 切分与数据分布
+
+| 项目 | 合同 |
+|:---|:---|
+| 切分轴 | 输出沿 **M 轴**按 rank 切分 |
+| 数据分布 | **输入不切分**：每 rank 完整持有 A `[M, K]`（各 rank 为各自独立数据，**非**全局 A 的 M 分片）与 B `[K, N]`（全 rank 共享）；每 rank 本地计算完整 `C = A @ B` `[M, N]`。**切分仅在输出分布**：C 按 M 轴切 R 段，向 targetRank 交付其 `M/rankSize` 输出行段（`chunkM = M / rankSize`），聚合后每 rank 输出本段归约结果 `[M/R, N]`。**golden 推导式**：`out_r = Σ_j C_j[r·chunkM : (r+1)·chunkM, :]`（`C_j` 为 rank j 的完整 mm 输出，求和跨全部 rank、仅取第 r 个 M 段；FP32 累加后转输出 dtype）——gen_data.py 依此逐 rank 生成，切勿把输入 A/B 误切分 |
+| staging 即通信源 | mm 输出写入 staging（workspaceGM）为连续 `[M, N]`；第 targetRank 段恰好等于发往该 rank 的 chunk，**零重排、零额外拷贝**（本场景关键红利） |
+| self rank 处理 | 本卡段 `stagingGm + rankId×chunkBytes` 本地合并，不经通信链路；Win self 槽闲置为已知取舍 |
+
+### 3.3 通信轮次 T 推导
+
+| 项目 | 合同 |
+|:---|:---|
+| T 公式 | 优先 `T = mSeg / headMSize` 整除（无尾块，实现最简）；**单尾块合法**：`tailMSize = mSeg % headMSize`（16 对齐且 ≤ headMSize）时 PUT 直传（偏移精确，生产实证 m4032：3×512+480 与 7×128+112 均通过），tail 轮用 tail tiling（入参 m=R×tailMSize）；多尾块或尾块>头块才必须走 padding 策略 |
+| 上限 | 计数式固定 flagId 下 T 上限按 case 实测确定（计数器 0-15 衡量未消费积压，紧邻配对下 ≈1-2 不触顶，不构成 T 上限）；轮次索引型 flagId 时轮次索引 < FLAG_ID_MAX(16) 且避开 SyncAll 保留区（`SyncAll<true>` 占 14）。**不设 host 强制数值拒绝** |
+| 调试策略 | 两阶段：精度调试 `T=1` 串行基线；性能调优再扫描合法 T 取值 |
+
+### 3.4 Flag 编排（compute-first）
+
+| 项目 | 合同 |
+|:---|:---|
+| 配对方向 | AIC `CrossCoreSetFlag<0x2, PIPE_FIX>(flagId)` ⇔ AIV **无模板** `CrossCoreWaitFlag(flagId)`（官方配对惯例"模板 Set + 无模板 Wait"，见 `ascendc-api-best-practices` skill `references/api-crosscore-sync.md` §4.1）；Set 用 `PIPE_FIX`（fixpipe 排空语义），AIV 侧 Wait 后紧随标量流通信下发——模板形态（如 `<0x2, PIPE_MTE2>`）不阻塞标量流，Commit 会在 flag 生效前执行 → PUT 读未写完的 staging（生产实测间歇精度失败），**禁止** |
+| T=1 | 循环外单次配对 |
+| T>1 | 逐轮计数式配对（T 次 Set ⇔ T 次 Wait，紧邻配对下积压 ≈ 1-2） |
+| 硬约束 | **Set/Wait 严格配对**（不配对 = 未定义行为/挂死）+ flagId 数量 16（0-15）；计数器 0-15 衡量未消费积压（官方有据，紧邻配对下不触顶），不作 host 强制校验 |
+| flagId 选取 | flagId ∈ [0, FLAG_ID_MAX)；工程验证使用计数式 flag，event ID 0（flagA）和 1（flagB） |
+| 双 flag 编排（**强制**） | **compute-first 场景必须遵循** [`fusion.md`](../../fundamentals/fusion.md) §6.2.2/§6.2.3 localLast 双 flag 编排：fragment 重排 `[remote..., local]` + 两个 flagId 分工（flagA=remote 段算完提前启动 PUT、flagB=本轮全部算完），未跨边界核兜底 Set flagA。**禁止以每轮 Set 两个 flag 替代 localLast 双 flag**——此替代使 flagId 用量翻倍且丧失通信提前启动能力。实现要点见 development.md §5.8 |
+
+### 3.5 增量归约
+
+| 项目 | 合同 |
+|:---|:---|
+| 归约形式 | 手工 UB 分批（batch）求和：每轮处理 R 个来源（R-1 个 Win 槽 + 本卡 staging 自 chunk） |
+| 中间精度 | **FP32 中间累加**，最终轮次转回输出 dtype 写 yGm |
+| 流水位置 | 归约核处理第 t-1 轮与通信核 PUT 第 t 轮并行（错位流水） |
+
+### 3.6 Win 区布局
+
+| 项目 | 合同 |
+|:---|:---|
+| 元数据分离 | Win 数据区与元数据/barrier 区分离：官网布局 barrier 在独立 BARRIER_BUF、数据区从 0 可用；共享布局须按约定偏移跳过头部（`localFlag(32B)+teamSyncCounter(32B)+crossCoreFlag(32B)=96B` → 对齐 128），偏移按 host 建链布局确定、host/kernel 同源（[`communication.md`](../../fundamentals/communication.md) 陷阱 #12） |
+| **winOffset 强制（共享布局）** | **共享布局（barrier 与数据同一 Win 区）时 winOffset 必须显式设置，禁止 0 偏移**（[`development-guide.md`](../../operator-design/development-guide.md) §3.5 已禁止）。官网布局（barrier 在独立 BARRIER_BUF）时数据区从 0 可用，winOffset=0 合法。AllToAll Init 的 winOffset 按 host 建链布局确定（共享布局一种已验证实现为 128B） |
+| 同源约束 | host 侧预留、PUT 写入偏移、归约读取偏移三处必须同源；0 偏移覆盖元数据会造成"假通过"，精度验证无法发现，属设计红线 |
+| 布局判定 | Win 区是否含头部元数据由 host 建链布局决定，以 communication.md 陷阱 #12 为唯一事实源 |
+
+## 4. 联合合同（计算 × 通信组合）
+
+三级流水：**mm → staging → PUT → 增量归约**。
+
+| 级 | 执行者 | 动作 | 交接机制 |
+|:---|:---|:---|:---|
+| 1 | AIC | RunMatmul 逐 tile 计算，结果写 staging（连续 [M, N]） | 每轮 CrossCoreSetFlag 通知 AIV |
+| 2 | AIV 通信核（后 R 核） | WaitFlag 门控后 Commit/Wait，将 staging 的 targetRank 段 PUT 至对端 Win 槽 | Win 区数据段（偏移 128 起） |
+| 3 | AIV 归约核（前核） | 对上一轮聚合 R 来源，UB 分批 FP32 求和 → yGm | 与第 2 级错位并行 |
+
+架构边界声明：compute-first 下通信依赖完整 mm 输出，**mm 段天然暴露**（无法被通信掩盖）；跨方案性能对比时须显式声明此为架构边界而非回归。
+
+## 5. Step 3 输入/源码前提
+
+| 前提 | 说明 |
+|:---|:---|
+| 场景命中 | 官方未覆盖项语义命中本场景判据，零命中/多命中判 `unsupported` |
+| Investigation 闭合 | matmul 链路事实全部 confirmed，无未闭合项 |
+| 修改范围 | 仅允许在 `kernel/<op>/` 下新建文件；禁止修改 `block/`、`tiling/` |
+| 直调约束 | 仅 UDMA 直调；HCCL windows 不支持直调 |
+| 核配比 | 由 `KERNEL_TYPE_MIX_AIC_1_1` 保证，禁止 `__schedmode__(1)` |
+
+## 6. 验证合同摘要
+
+| 项目 | 合同 |
+|:---|:---|
+| golden 语义 | 逐 rank：本地完整 [M, N] mm 输出，聚合全部 rank 的本 rank M 段，FP32 求和后转输出 dtype；gen_data.py 依据切分轴=M 生成 golden |
+| 精度基线 | 先 `T=1` 串行基线全绿，再扫描合法 T；阈值按输出 dtype 精度标准 |
+| 边界矩阵 | rankSize 端点 × shape 对齐/非对齐 × T 各合法取值（优先 `T \| mSeg` 无尾块；T 上限按 R9 口径 case 实测确定——计数式固定 flagId 0/1 生产验证 T=16，计数器 0-15 衡量未消费积压不触顶，不设 host 强制数值拒绝） |
+| 红线用例 | Win 区 0 偏移元数据覆盖检测（共享布局下偏移同源校验）；flagId ∈ [0,15] 硬件数量上限（`FLAG_ID_MAX=16`，计数式经 Set/Wait 严格配对规避溢出） |
+| 性能 | mm 段暴露为架构边界；性能采集须含 L2 flush 证据，与精度验证分离 |