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

package/assets/ops-direct-invoke/skills/ascendc-api-best-practices/references/api-pipeline.md

@@ -0,0 +1,206 @@
+# 流水线同步机制指南
+
+MTE 与 Vector 同步的核心机制。
+
+---
+
+## 目录
+
+1. [核心问题](#核心问题)
+2. [解决方案](#解决方案)
+3. [三种方案对比](#三种方案对比)
+4. [完整流水线模板](#完整流水线模板)
+5. [调试技巧](#调试技巧)
+
+---
+
+## 核心问题
+
+**DataCopy/DataCopyPad 是异步 DMA 操作，直接在搬运后的数据上做 Vector 计算可能读到未完成的数据！**
+
+### 硬件架构
+
+```
+GM → MTE2 (异步) → UB → Vector (同步) → MTE3 (异步) → GM
+```
+
+### 问题场景
+
+```cpp
+// ❌ 错误：DataCopyPad 后直接使用数据
+AscendC::LocalTensor<float> xLocal = inQueueX.AllocTensor<float>();
+AscendC::DataCopyPad(xLocal, xGm[offset], copyParams, padParams);
+AscendC::Adds<float>(yLocal, xLocal, 1.0f, count);  // 可能读到未完成搬运的数据！
+```
+
+**现象**：输出数据随机、错误
+
+---
+
+## 解决方案
+
+### 方案一：EnQue/DeQue 队列同步（推荐）
+
+**原理**：TQue 的 EnQue/DeQue 机制自动提供硬件同步点。
+
+```cpp
+// ✅ 正确：使用 EnQue/DeQue 同步
+// Step 1: CopyIn - MTE2 搬运
+AscendC::LocalTensor<float> xLocal = inQueueX.AllocTensor<float>();
+AscendC::DataCopyPad(xLocal, xGm[gmOffset], copyInParams, padParams);
+inQueueX.EnQue(xLocal);                    // 标记"就绪"
+
+// Step 2: Compute - Vector 计算
+AscendC::LocalTensor<float> xIn = inQueueX.DeQue<float>();  // 阻塞等待 MTE2 完成
+AscendC::LocalTensor<float> yLocal = outQueueY.AllocTensor<float>();
+AscendC::Adds<float>(yLocal, xIn, 1.0f, count);
+outQueueY.EnQue(yLocal);
+inQueueX.FreeTensor(xIn);
+
+// Step 3: CopyOut - MTE3 搬运
+AscendC::LocalTensor<float> yOut = outQueueY.DeQue<float>();  // 阻塞等待 Vector 完成
+AscendC::DataCopyPad(yGm[gmOffset], yOut, copyOutParams);
+outQueueY.FreeTensor(yOut);
+```
+
+**关键点**：
+- `EnQue(xLocal)` 标记 buffer 数据就绪
+- `DeQue<float>()` 阻塞等待数据就绪
+- DeQue 返回后，数据一定已经搬运完成
+
+### 方案二：PipeBarrier 手动同步
+
+```cpp
+// ✅ 可用：PipeBarrier 手动同步（替代队列同步）
+AscendC::LocalTensor<float> xLocal = inQueueX.AllocTensor<float>();
+AscendC::LocalTensor<float> yLocal = outQueueY.AllocTensor<float>();
+
+AscendC::DataCopyPad(xLocal, xGm[gmOffset], copyInParams, padParams);
+AscendC::PipeBarrier<PIPE_MTE2>();  // 等待 MTE2（GM→UB）完成
+
+AscendC::Adds<float>(yLocal, xLocal, 1.0f, count);
+AscendC::PipeBarrier<PIPE_V>();     // 等待 Vector 完成
+
+AscendC::DataCopyPad(yGm[gmOffset], yLocal, copyOutParams);
+AscendC::PipeBarrier<PIPE_MTE3>();  // 等待 MTE3（UB→GM）完成
+```
+
+---
+
+## 三种方案对比
+
+| 特性 | EnQue/DeQue | SetFlag/WaitFlag（HardEvent 事件式） | PipeBarrier |
+|-----|-------------|--------------------------------------|-------------|
+| 同步粒度 | buffer 级别 | pipe 对级别（如 MTE2→V、V→MTE3） | 单 pipe 或全 pipe 栅栏 |
+| 性能 | 高（支持并行） | 高（精细配对，开销最小） | `PipeBarrier<PIPE_V>` 等单 pipe 栅栏廉价；`PipeBarrier<PIPE_ALL>` 全流水线停顿，仅调试用 |
+| 代码复杂度 | 需要队列管理 | 需手动管理 eventID 配对/复用 | 简单直接 |
+| 适用 | TPipe/TQue 管理的标准搬运流水 | 手动 UB 管理、精细 pipe 间流水编排 | 防御性顺序依赖（如 V 内 Cast→Add）、调试定位 |
+
+> 三条路径不是二选一：TQue 场景用 EnQue/DeQue；手动 UB（无 TPipe）场景用 SetFlag/WaitFlag 事件流水；单 pipe 内的顺序依赖用细粒度 PipeBarrier 防御。
+
+### 事件式流水（SetFlag/WaitFlag HardEvent）要点
+
+```cpp
+// 核内 pipe 间事件同步：DataCopy(MTE2) 与 Cast/Add(V) 跨 pipe 重叠
+AscendC::SetFlag<AscendC::HardEvent::MTE2_V>(eventId);   // 标记 MTE2 搬运完成
+AscendC::WaitFlag<AscendC::HardEvent::MTE2_V>(eventId);  // V 侧等待后消费
+```
+
+使用纪律：
+
+1. **Set/Wait 必须同 eventID 配对**，且**在同一迭代内配对**——跨迭代 Set-Set 无中间 Wait 在 Ascend 950 实测挂死（`aclError:507014`）。**循环结束后必须消费残留事件**：最后一次/几次 Set 无对应 Wait 时需补 Wait；注意按实际 Set 次数守卫（如 pingpong 双 eventID 时，第二个 eventID 仅在迭代数 ≥ 2 时才被 Set 过，不可无条件 Wait——Wait 多于 Set 同样是未定义行为）
+2. **eventID 是有限共享资源**（TQue 与手动 SetFlag/WaitFlag 共用配额，典型 8 个/核）——手动事件与 TQue 混用时预算要合并计算
+3. V 内部的顺序依赖（Cast→Add）优先用 `PipeBarrier<PIPE_V>` 防御，省去 V→V 的 eventID 开销
+4. **跨 pipe 依赖必须用事件同步**：`PipeBarrier<PIPE_X>` 只保证同一 pipe 内的顺序，不保证跨 pipe 可见性——如 V 侧 Cast 写完的数据要经 MTE3 搬出时，必须 `SetFlag/WaitFlag<V_MTE3>`，仅 `PipeBarrier<PIPE_V>` 不足（生产踩坑：跨 pipe 缺事件同步导致搬出读到未写完的数据）
+
+### EnQue/DeQue 的双重作用
+
+1. **队列管理**：Double Buffer 场景下管理多 buffer 轮转
+2. **硬件同步**：提供 MTE ↔ Vector 之间的同步点
+
+```cpp
+// EnQue/DeQue 不仅仅是"队列"，更重要的是同步机制
+inQueueX.EnQue(xLocal);    // 1. 标记数据就绪  2. 通知硬件可以等待
+xLocal = inQueueX.DeQue(); // 1. 阻塞等待就绪  2. 获取可用 buffer
+```
+
+---
+
+## 完整流水线模板
+
+```cpp
+__aicore__ inline void ProcessTile(uint32_t tileIdx)
+{
+    // ========== CopyIn 阶段 ==========
+    // MTE2: GM → UB（异步）
+    AscendC::LocalTensor<float> xLocal = inQueueX.AllocTensor<float>();
+    AscendC::DataCopyPad(xLocal, xGm[tileIdx * tileSize], copyParams, padParams);
+    inQueueX.EnQue(xLocal);              // 同步点：标记就绪
+    
+    // ========== Compute 阶段 ==========
+    // Vector: UB 计算（同步，需等待 MTE2）
+    AscendC::LocalTensor<float> xIn = inQueueX.DeQue<float>();  // 同步点：等待 MTE2
+    AscendC::LocalTensor<float> yLocal = outQueueY.AllocTensor<float>();
+    AscendC::Adds<float>(yLocal, xIn, 1.0f, tileSize);
+    outQueueY.EnQue(yLocal);             // 同步点：标记就绪
+    inQueueX.FreeTensor(xIn);
+    
+    // ========== CopyOut 阶段 ==========
+    // MTE3: UB → GM（异步，需等待 Vector）
+    AscendC::LocalTensor<float> yOut = outQueueY.DeQue<float>();  // 同步点：等待 Vector
+    AscendC::DataCopyPad(yGm[tileIdx * tileSize], yOut, copyParams);
+    outQueueY.FreeTensor(yOut);
+}
+```
+
+### 流水线时序图
+
+```
+时间 →
+        
+Tile 0:  [MTE2]──EnQue──[Vector]──EnQue──[MTE3]
+                      ↑ DeQue等待    ↑ DeQue等待
+Tile 1:          [MTE2]──EnQue──[Vector]──EnQue──[MTE3]
+                  ↑ 并行！    ↑ DeQue等待    ↑ DeQue等待
+
+关键：DeQue 阻塞等待上一个阶段的异步操作完成
+```
+
+---
+
+## 调试技巧
+
+### 检查缺少 EnQue/DeQue
+
+```cpp
+// ❌ 错误：AllocTensor 后直接用
+LocalTensor<T> x = inQueue.AllocTensor<T>();
+DataCopy(x, gm, size);
+Compute(x);  // 错！可能读到未完成搬运的数据
+
+// ✅ 正确：DeQue 后再计算
+LocalTensor<T> x = inQueue.AllocTensor<T>();
+DataCopy(x, gm, size);
+inQueue.EnQue(x);
+LocalTensor<T> xIn = inQueue.DeQue<T>();  // 等待搬运完成
+Compute(xIn);
+```
+
+### 临时加 PipeBarrier 调试
+
+```cpp
+DataCopy(x, gm, size);
+PipeBarrier<PIPE_ALL>();  // 临时加，如果结果正确说明是同步问题
+Compute(x);
+```
+
+**如果 PipeBarrier 能解决问题，说明是同步问题** → 修复方案：改为 EnQue/DeQue 机制
+
+### 常见误区
+
+| 误区 | 正确理解 |
+|-----|---------|
+| AllocTensor 后数据就可用 | AllocTensor 只分配内存，不等待搬运 |
+| DataCopy 是同步的 | DataCopy 是异步 DMA，立即返回 |
+| 不用 EnQue/DeQue 也能正常工作 | 必须用 EnQue/DeQue、SetFlag/WaitFlag 或 PipeBarrier 之一同步 |
+| PipeBarrier 性能好 | **仅 `PipeBarrier<PIPE_ALL>` 是全流水线停顿**（性能差，仅临时调试用，定位后应移除）；`PipeBarrier<PIPE_V>` 等单 pipe 栅栏是廉价且必要的顺序依赖手段 |

package/assets/ops-direct-invoke/skills/ascendc-api-best-practices/references/api-precision.md

@@ -0,0 +1,146 @@
+# 精度转换与混合精度指南
+
+Cast API 使用规范和混合精度计算模式。
+
+---
+
+## 目录
+
+1. [Cast RoundMode 选择](#cast-roundmode-选择)
+2. [混合精度计算模式（FP16 输入）](#混合精度计算模式fp16-输入)
+3. [MX 块量化格式精度路径](#mx-块量化格式精度路径mxfp8--mxfp4-等)
+
+---
+
+## Cast RoundMode 选择
+
+### 选择规则
+
+| 转换方向 | RoundMode | 原因 |
+|---------|-----------|------|
+| **half → float** | `CAST_NONE` | 低精度→高精度，无精度损失 |
+| **float → half** | `CAST_ROUND` | 高精度→低精度，有精度损失 |
+| half → int32_t | `CAST_ROUND` / `CAST_CEIL` | 量化场景，根据需求选择 |
+| int32_t → float | `CAST_NONE` | 整数→浮点，无精度损失 |
+
+### 正确用法
+
+```cpp
+// ✅ half → float：低精度到高精度
+AscendC::LocalTensor<float> xFloat = workBuf.Get<float>();
+AscendC::Cast<float, half>(xFloat, xHalf, AscendC::RoundMode::CAST_NONE, count);
+
+// ✅ float → half：高精度到低精度
+AscendC::LocalTensor<half> yHalf = outQueue.AllocTensor<half>();
+AscendC::Cast<half, float>(yHalf, xFloat, AscendC::RoundMode::CAST_ROUND, count);
+```
+
+> ⚠️ **禁止向更宽类型做 in-place Cast**（如 BF16→FP32 in-place）：目标类型占 2× 空间，Cast 输出会覆盖同 buffer 内**尚未读取的源数据** → 系统性精度错误。向更宽类型 Cast 时必须使用独立目标 buffer（双缓冲场景配双份目标 buffer）。
+
+### Scatter/累加场景补充铁律（950PR 实测）
+
+- **Cast 的 dst/src 不可重叠/别名**：向量指令并行读写竞争 → NaN；`Compare` 的 dst
+  与 src1/src2 重叠同样会损坏输出（需独立零缓冲）
+- **升精度误用 `CAST_RINT` 的症状特征**：T→float 用了 `CAST_RINT` 会导致
+  "有贡献但值错"（matched_ratio≈0.005 级），而非"全零"——注意与越界/未同步类全零
+  症状区分
+- **SIMT 内 `static_cast<float>(bf16)` 不可靠**（可能被编译器折叠回 bf16 运算）；
+  fp16 的 static_cast 可靠。bf16 参与元素级运算前必须在向量阶段先 Cast 到 fp32
+  workspace，SIMT 内只碰 fp32
+- **fp16/bf16 累加的 acc_type 语义**：CPU golden 对重复 index 的 add 在 fp32 精确
+  累加后一次舍入；kernel 若逐次低精度舍入会差 1 ULP——整批向量 Cast 到 fp32 →
+  累加 → 向量 Cast 回（降精度用 CAST_RINT）
+
+---
+
+## 混合精度计算模式（FP16 输入）
+
+### 适用场景
+
+当输入输出为 FP16，但需要 FP32 精度进行中间计算时（如 Softmax、LayerNorm）。
+
+### 计算流程
+
+```
+half 输入 → Cast(FP32) → 中间计算(FP32) → Cast(half) → half 输出
+```
+
+### 为什么需要 FP32 中间计算？
+
+1. **ReduceMax/Exp/ReduceSum** 在 FP32 上精度更稳定
+2. **避免 FP16 数值溢出**：Exp 结果可能超出 FP16 表示范围
+3. **累积误差控制**：多次运算的累积误差在 FP32 下更小
+
+### 加减法场景示例
+
+半精度加减法默认升 FP32；仅当 spec 明确"输入同量级"（如 mask 叠加、已归一化概率相加）时才允许直接 `Add/Sub<half>`。BF16 与 FP16 适用同一规则，仅临界比值不同（BF16=128，FP16=1024）。
+
+> 完整示例、决策表与 Kernel 集成要点见 [api-arithmetic.md → 场景3](api-arithmetic.md#场景3半精度加减法精度优化)。
+
+---
+
+## MX 块量化格式精度路径（mxfp8 / mxfp4 等）
+
+### 适用场景
+
+输入或输出走 MX 类块量化格式（mxfp8 / mxfp4 / mxfp6 等）：每 32 元素一组共享一个 E8M0 scale，数据本体走低精度 dtype（如 fp8_e4m3 / fp8_e5m2 / fp4）。
+
+### 数据通路概览
+
+```
+高精度 fp32 张量 → 沿量化轴每 32 元素一组计算 amax
+                ↓
+            E8M0 scale 生成
+                ↓
+            Cast<量化 dtype, fp32>(x / scale) → 低精度数据 + 配套 scale
+```
+
+### E8M0 scale 编码规则
+
+E8M0 scale 编码 **必须使用 ceil 偏移**：
+
+```cpp
+e8m0_byte = (biased_exp_amax - emax_quant_dtype) + 1;  // ✅ ceil
+```
+
+参数：
+- `biased_exp_amax`：amax 的 fp32 biased exponent（0-255）
+- `emax_quant_dtype`：目标量化 dtype 的 max exponent（fp8_e4m3=8、fp8_e5m2=15、fp4_e2m1=2）
+- `+1`：ceil 偏移，确保 `amax / decoded_scale ≤ quant_dtype_max`
+
+### 反模式：floor 偏移导致 NaN
+
+```cpp
+❌ e8m0_byte = biased_exp_amax - emax_quant_dtype;  // 缺失 +1，落入 floor 区间
+```
+
+floor 偏移下 `amax / decoded_scale` 可能落在 `[quant_dtype_max, 2 × quant_dtype_max)` 区间（对 e4m3 即 `[448, 896)`）。Cast<量化 dtype, fp32, RINT> 对超过 dtype_max 的输入会产出 NaN（对 fp8_e4m3 为 `0x7F`）。
+
+### Cast<fp8_e8m0_t> 的 API 路径
+
+MX 类格式的 scale dtype 是 `fp8_e8m0_t`，需要把 fp32 的 biased exponent 部分编码为 e8m0：
+
+| 路径 | 说明 |
+|------|------|
+| **MemBase Cast API** | 不提供 `fp8_e8m0_t` 重载 |
+| **Reg-API Cast** | 提供 `bfloat16_t ↔ fp8_e8m0_t` 重载（查 `Cast-45.md` 等 Reg-API 变体），但需引入 Regbase 编程范式 |
+| **手写位运算** | 通过 `ReinterpretCast<uint32_t>(fp32_tensor)` 拿到位表示，`ShiftRight + And + Sub + Add` 提取 biased exp 并应用 ceil 偏移 |
+
+主路径选择按算子整体的编程范式决定：纯 MemBase 路径用手写位运算，Reg-API 路径可直接用 Cast。
+
+### 验证清单
+
+新增 MX 量化路径必须验证：
+- [ ] amax 沿正确的轴归约
+- [ ] E8M0 scale 公式用 ceil 偏移
+- [ ] Cast 之后输出无 NaN（有 NaN → 多半是 floor 偏移）
+- [ ] `amax / decoded_scale` 始终 ≤ 量化 dtype max
+
+### 编译错诊断速查
+
+| 编译错 | 真根因 | 修复 |
+|--------|-------|------|
+| `Mmad` does not accept fp8 ptr | Mmad fm/filter 模板参数同型约束未满足 | 显式指定 `Mmad<fp32, fp8_e4m3_t, fp8_e4m3_t>` 等同型组合 |
+| `Cast<fp8_e8m0_t, fp32>` unresolved | MemBase Cast 不支持 e8m0 直接 cast | 用手写位运算 或 切换 Reg-API 路径 |
+
+> MX 格式的 scale 轴选择（沿哪个张量维度量化）属于设计层决策，涉及与 matmul reduction 轴的对齐，见 [api-loaddata.md](api-loaddata.md) 与对应算子族 skill 的 dtype 路径契约。

package/assets/ops-direct-invoke/skills/ascendc-api-best-practices/references/api-quickref.md

@@ -0,0 +1,192 @@
+# API 快速参考
+
+Ascend C API 使用核心决策索引。遇到具体问题时，按需查阅详细文档。
+
+---
+
+## 目录
+
+1. [核心原则速查](#核心原则速查)
+2. [决策树：我应该用什么API？](#决策树我应该用什么api)
+3. [按场景查阅详细文档](#按场景查阅详细文档)
+
+---
+
+## 核心原则速查
+
+### 1. DataCopy vs DataCopyPad
+
+**原则：优先使用 DataCopyPad，参数统一用 Ext 版本**
+
+| 场景 | API | 参数 | 原因 |
+|-----|-----|------|------|
+| 所有 GM ↔ UB 搬运 | `DataCopyPad` | `DataCopyExtParams` + `DataCopyPadExtParams<T>` | 统一处理对齐/非对齐，参数范围更大 |
+| 确定数据严格 32 字节对齐 | `DataCopy` | `DataCopyParams` 或 `DataCopyExtParams` | 简单场景可用 |
+
+**详细用法**：[api-datacopy.md](api-datacopy.md)
+
+### 2. Cast RoundMode 选择
+
+| 转换方向 | RoundMode | 原因 |
+|---------|-----------|------|
+| half → float | `CAST_NONE` | 低→高精度，无损失 |
+| float → half | `CAST_ROUND` | 高→低精度，需舍入 |
+| half → int32_t | `CAST_ROUND` | 量化场景 |
+| int32_t → float | `CAST_NONE` | 整数→浮点 |
+
+**详细用法**：[api-precision.md](api-precision.md)
+
+### 3. TBuf vs TQue 选择
+
+| 场景 | 类型 | 说明 |
+|------|------|------|
+| MTE2/MTE3 搬运缓冲区 | `TQue<VECIN/VECOUT>` | `InitBuffer(que, num, size)` |
+| 纯 Vector 计算缓冲区 | `TBuf<VECCALC>` | `InitBuffer(buf, size)` |
+
+**详细用法**：[api-buffer.md](api-buffer.md)
+
+### 4. 流水线同步
+
+**原则**：必须用 EnQue/DeQue 同步 MTE 和 Vector
+
+**核心模式**：
+```
+CopyIn → EnQue → DeQue → Compute → EnQue → DeQue → CopyOut
+```
+
+**详细用法**：[api-pipeline.md](api-pipeline.md)
+
+### 5. Vector API repeatTime 限制
+
+**核心限制**：repeatTime 为 uint8_t 时，最大值 255
+
+**处理方法**：Host 侧限制 R_max 或 Kernel 侧分批处理
+
+**详细用法**：[api-repeat-limits.md](api-repeat-limits.md)
+
+### 6. Reduce API 选择
+
+| 场景 | 接口 | 说明 |
+|-----|------|------|
+| 逐行独立 Reduce | Level 2: `ReduceMax(dst, src, tmp, count)` | 无对齐要求，count 传 rLength |
+| 跨行批量 Reduce | Pattern: `ReduceMax<T, Pattern::AR>(...)` | 需 32 字节对齐 |
+
+**详细用法**：[api-reduce.md](api-reduce.md) | [Pattern 接口详解](api-reduce-pattern.md)
+
+### 7. GatherMask 解交织
+
+**三种用法**：
+
+| 场景 | 模式 | 关键参数 |
+|------|------|---------|
+| RoPE 奇偶拆分、按步长取元素 | 内置 pattern 1/2, Normal/Counter 均可 | `{1, 1, 8, 0}` |
+| (N,4)→4 列分量分离 | 内置 pattern 3/4/5/6 | `src0RepeatStride=8`, `repeatTimes=alignedLen/16` |
+| 非均匀间隔、复杂 mask | 用户自定义 `LocalTensor` mask | Counter/Normal 均可，mask 类型匹配 dst |
+
+⛔ **Critical**：`src0RepeatStride=8` 不可写成 1（repeat 重叠 224B → 精度全 fail）。**详细用法**：[api-gathermask.md](api-gathermask.md)
+
+---
+
+## 决策树：我应该用什么API？
+
+### Q1: 需要 GM ↔ UB 搬运数据？
+
+```
+是 → DataCopyPad（推荐）
+   → DataCopy（仅当确定32字节对齐时）
+
+否 → 继续
+```
+
+### Q2: 需要精度转换？
+
+```
+half → float → CAST_NONE
+float → half → CAST_ROUND
+其他 → 查阅 api-precision.md
+```
+
+### Q3: 需要分配 UB 缓冲区？
+
+```
+涉及 MTE 搬运 → TQue + InitBuffer(que, num, size)
+纯 Vector 计算 → TBuf + InitBuffer(buf, size)
+```
+
+### Q4: 遇到数据错误/随机值？
+
+```
+1. 检查是否缺少 EnQue/DeQue → api-pipeline.md
+2. 检查 DataCopyPad 参数 → api-datacopy.md
+3. 检查 Reduce API 的 tmpBuffer 类型 → api-reduce.md
+ 4. 检查多行处理时的 rowOffset 计算 → api-reduce.md
+ 5. 检查 repeatTime 是否溢出 → api-repeat-limits.md
+```
+
+### Q5: 需要混合精度计算（FP16 输入，FP32 中间计算）？
+
+```
+查阅 api-precision.md 的混合精度模式
+```
+
+### Q6: 需要跨卡数据搬运？
+
+```
+拉远端到本地 → Hcomm ReadNbi，详见 api-hcomm.md
+推本地到远端 → Hcomm WriteNbi，详见 api-hcomm.md
+需要远端通知 → WriteWithNotifyNbi
+```
+
+### Q7: AIC 和 AIV 需要跨核协同？
+
+```
+AIC 通知 AIV：AIC CrossCoreSetFlag<0x2, PIPE_FIX>(id) → AIV CrossCoreWaitFlag<0x2, PIPE_S>(id)
+AIV 回压 AIC：AIV CrossCoreSetFlag<0x2, PIPE_MTE3>(id) → AIC CrossCoreWaitFlag<0x2, PIPE_M>(id)
+注意：A3/910b（Atlas A2/A3 系列，DAV_2201）上 modeId/pipe 模板参数不生效；950（Ascend 950PR/950DT，DAV_3510）上模式 0/1/2 不支持 PIPE_S
+详见 api-crosscore-sync.md
+```
+
+### Q8: 依赖所有 block 都完成通信后才能继续？
+
+```
+Drain 只保证本 block 的 channel 任务完成
+需要"所有 block 完成"语义时加 SyncAll<true>() 块间同步
+详见 api-hcomm.md、api-crosscore-sync.md
+```
+
+### Q9: Host 侧如何建链并下发通信上下文？
+
+```
+HcclCommInitRootInfoConfig → HcclChannelDescInit + HcclChannelAcquire
+→ HcclEngineCtxCreate + HcclEngineCtxCopy → 跨 rank 带外 barrier → launch
+详见 api-hccl-host.md
+```
+
+### Q10: 多核/多 rank 写入同一 GM 地址？
+
+```
+是 → 需要原子操作
+  累加语义（ReduceScatter/AllReduce/split-K）→ SetAtomicAdd<T>()
+  取最大值（attention 归约）→ SetAtomicMax<T>()
+  取最小值 → SetAtomicMin<T>()
+  ⛔ FP8 不支持原子操作，需先转 BF16/FP32
+  ⛔ 用完必须 DisableDmaAtomic() 关闭
+否 → 不需要（默认状态）
+详见 api-atomic.md
+```
+
+---
+
+## 按场景查阅详细文档
+
+| 场景 | 文档 | 核心内容 |
+|-----|------|---------|
+| 数据搬运（GM↔UB） | [api-datacopy.md](api-datacopy.md) | DataCopyPad 参数、stride 计算、非对齐处理 |
+| 精度转换/混合精度 | [api-precision.md](api-precision.md) | Cast RoundMode、FP16 混合精度模式 |
+| UB 缓冲区管理 | [api-buffer.md](api-buffer.md) | TBuf/TQue 选择、Double Buffer、批量搬运 |
+| 流水线同步 | [api-pipeline.md](api-pipeline.md) | EnQue/DeQue 同步机制、时序图 |
+| repeatTime 限制 | [api-repeat-limits.md](api-repeat-limits.md) | 分批处理 |
+| 点对点通信 | [api-hcomm.md](api-hcomm.md) | ReadNbi/WriteNbi/Drain、URMA 队列语义 |
+| 跨核同步 | [api-crosscore-sync.md](api-crosscore-sync.md) | CrossCoreSetFlag/WaitFlag、SyncAll、flagId 硬件规则 |
+| HCCL Host | [api-hccl-host.md](api-hccl-host.md) | 建链、engine ctx、资源生命周期 |
+| DMA 原子操作 | [api-atomic.md](api-atomic.md) | SetAtomicAdd/DisableDmaAtomic、多 rank 累加前置条件 |

package/assets/ops-direct-invoke/skills/ascendc-api-best-practices/references/api-reduce-pattern.md

@@ -0,0 +1,132 @@
+# Reduce Pattern 接口详解
+
+跨行批量 Reduce 的 Pattern 接口高级用法。
+
+---
+
+## 两种重载形式
+
+### 形式1：显式传入 sharedTmpBuffer（推荐）
+
+```cpp
+template <class T, class pattern, bool isReuseSource = false>
+__aicore__ inline void ReduceMax(
+    const LocalTensor<T>& dstTensor, 
+    const LocalTensor<T>& srcTensor, 
+    const LocalTensor<uint8_t>& sharedTmpBuffer,  // 显式传入
+    const uint32_t srcShape[], 
+    bool srcInnerPad
+);
+```
+
+### 形式2：框架自动申请临时空间
+
+```cpp
+template <class T, class pattern, bool isReuseSource = false>
+__aicore__ inline void ReduceMax(
+    const LocalTensor<T>& dstTensor, 
+    const LocalTensor<T>& srcTensor, 
+    const uint32_t srcShape[], 
+    bool srcInnerPad
+);
+```
+
+> **⚠️ 形式2 必须预留临时空间**，否则运行时 UB 越界。详见 [临时空间预留](#临时空间预留)。
+
+---
+
+## Pattern 类型
+
+| Pattern | 方向 | 输入形状 | 输出形状 | 用途 |
+|---------|-----|---------|---------|------|
+| `Pattern::Reduce::AR` | 沿最后一维（列方向） | (R, C) | (R,) | 每行归约为1个值 |
+| `Pattern::Reduce::RA` | 沿第一维（行方向） | (R, C) | (C,) | 每列归约为1个值 |
+
+---
+
+## 参数说明
+
+| 参数 | 类型 | 说明 |
+|-----|------|------|
+| `T` | half/float | 数据类型 |
+| `pattern` | Pattern::Reduce::AR/RA | 归约模式 |
+| `isReuseSource` | bool | 是否复用源操作数（默认 false） |
+| `dstTensor` | LocalTensor\<T\> | 输出张量 |
+| `srcTensor` | LocalTensor\<T\> | 输入张量 |
+| `sharedTmpBuffer` | LocalTensor\<uint8_t\> | 临时缓存（形式1） |
+| `srcShape` | uint32_t[] | `{rows, alignedCols}`，**alignedCols 必须 32 字节对齐** |
+| `srcInnerPad` | bool | A2/A3 芯片只支持 `true` |
+
+---
+
+## 临时空间预留
+
+**两种形式都需要预留临时空间**：
+
+| 方式 | 预留方法 | 优点 | 推荐度 |
+|-----|---------|------|-------|
+| **形式1** | `InitBuffer(tmpBuf, tmpSize)` + 显式传入 | 内存可控、可复用 | ⭐⭐⭐⭐⭐ |
+| **形式2** | `InitBuffer(tmpBuf, tmpSize)`（框架自动使用） | 代码简洁 | ⭐⭐⭐ |
+
+**临时空间大小计算**：
+
+```cpp
+#include "kernel_operator.h"
+
+uint32_t maxSize, minSize;
+AscendC::GetReduceMaxMaxMinTmpSize(srcShape, sizeof(T), isReuse, maxSize, minSize);
+
+// 使用 maxSize（安全）或 minSize（节省内存）
+pipe->InitBuffer(tmpBuf, maxSize);
+```
+
+参考文档：`GetReduceMaxMaxMinTmpSize` API 文档
+
+---
+
+## 完整示例
+
+### 示例1：ReduceMax（AR/RA Pattern）
+
+```cpp
+AscendC::LocalTensor<float> dstLocal = outQueue.AllocTensor<float>();
+AscendC::LocalTensor<float> srcLocal = inQueue.DeQue<float>();
+AscendC::LocalTensor<uint8_t> tmpLocal = tmpBuf.Get<uint8_t>();
+
+uint32_t srcShape[] = {rows, alignedCols};  // alignedCols 必须 32 字节对齐
+constexpr bool isReuse = true;
+
+// AR Pattern：每行归约为1个值 → 输出 rows 个值
+AscendC::ReduceMax<float, AscendC::Pattern::Reduce::AR, isReuse>(
+    dstLocal, srcLocal, tmpLocal, srcShape, true);
+
+// RA Pattern：每列归约为1个值 → 输出 alignedCols 个值
+AscendC::ReduceMax<float, AscendC::Pattern::Reduce::RA, isReuse>(
+    dstLocal, srcLocal, tmpLocal, srcShape, true);
+```
+
+### 示例2：ReduceSum（框架自动申请）
+
+```cpp
+// ⚠️ 必须提前预留临时空间
+AscendC::LocalTensor<float> dstLocal = outQueue.AllocTensor<float>();
+AscendC::LocalTensor<float> srcLocal = inQueue.DeQue<float>();
+
+uint32_t srcShape[] = {rows, alignedCols};
+
+AscendC::ReduceSum<float, AscendC::Pattern::Reduce::AR, true>(
+    dstLocal, srcLocal, srcShape, true);
+```
+
+---
+
+## 对比总结
+
+| 对比项 | 形式1（显式传入） | 形式2（框架申请） |
+|-------|-----------------|------------------|
+| tmp 参数 | ✅ 显式传入 | ❌ 框架自动申请 |
+| 预留空间 | ✅ 调用时传入即可 | ⚠️ **必须在 InitBuffer 预留** |
+| 内存管理 | 手动管理，可复用 | 需提前预留，易遗漏 |
+| 推荐度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
+
+**推荐使用形式1**，避免遗漏预留空间导致运行时错误。