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

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ascendc-tiling-design
+description: Ascend C 算子 Tiling 设计指南。提供算子分类体系和 Tiling 核心要素（多核切分、UB切分、Buffer规划、分支覆盖）的详细设计方法。触发：算子设计阶段、设计 Tiling 策略（多核切分/UB切分）、规划 Buffer 分配、查阅某类算子的 Tiling 方法论时。
+---
+
+# Ascend C 算子 Tiling 设计指南
+
+## 算子分类体系
+
+| 类别 | 特征 | 典型算子 | 设计指南 |
+|------|------|---------|---------|
+| **Reduction 归约类** | 沿轴归约（含索引跟踪变体） | ReduceSum, Softmax, LayerNorm, ArgMax | ✅ [场景路由](references/reduction/patterns.md)（⚠️ 必须先读） / [算法](references/reduction/algorithms.md) |
+| **Sort 排序类** | 排序、TopK、外部归并 | Sort, ArgSort, TopK | ✅ [场景路由](references/sort/patterns.md)（⚠️ 必须先读） / [多核两级归并方案](references/sort/alg-two-level-mrgsort.md) |
+| **Elementwise 逐元素类** | 输入输出Shape相同，逐元素独立计算 | Sin, Cos, Abs, Exp | ✅ [场景路由](references/elewise/patterns.md)（⚠️ 必须先读） |
+| Broadcast 广播类 | 输入Shape不同，需广播对齐 | Add, Mul, Sub | ✅ [场景路由](references/broadcast/patterns.md)（⚠️ 必须先读） |
+| Conversion 数据转换类 | 改变布局/形状，合并/拆分张量 | Transpose, Concat, Split | ⚠️ [场景路由](references/conversion/patterns.md)（当前仅 Transpose 部分支持） |
+| Random 随机类 | 生成随机数，需种子管理 | RandomUniform, Dropout | 📋 规划中 |
+| MatMul 矩阵乘类 | 矩阵乘法，高计算密度，用Cube单元 | MatMul, BatchMatMul, MatMulBias, GroupedMatmul | ✅ [场景路由](references/matmul/patterns.md)（⚠️ 必须先读平台路由） |
+| Convolution 卷积类 | 空间卷积，滑动窗口计算 | Conv2D, DepthwiseConv | 📋 规划中 |
+| FlashAttention 类 | 注意力计算 | FlashAttention, GQA, MHA, MLA（可叠加量化/稀疏 trait） | ✅ [场景路由](references/flashattention/patterns.md)（⚠️ 必须先读） |
+| Scatter 累加散射类 | 按 index 散射写入/累加，updates 按行组织 | MaskedScatter, ScatterNdAdd, ScatterElementsV2, ScatterAdd, InplaceIndexAdd, scatter_reduce | ✅ [场景路由](references/scatter/patterns.md)（⚠️ 必须先读） |
+| **Index 索引类**（A2/A3） | 以索引为核心访问数据，存在跨元素寻址 | Gather, GatherElements, IndexSelect, IndexAdd, RepeatInterleave, Take, Scatter, ScatterElements | ✅ [场景路由](references/index/patterns.md)（⚠️ 必须先读，按 P1~P7 分流到各 Pattern 文档） |
+| NN 神经网络类(其它)| 神经网络专用，多种操作组合 | GroupNorm 等非 attention | 📋 规划中 |
+
+> **芯片代际说明**：`references/index/` 下的文档面向 **A2/A3 代际**（910B / 910C，`arch22`，`dav_c220` / `DAV_2201`，单核 UB 192KB）；
+> 其中 `index/scatter.md` 为 A2/A3 的 UB 内标量散写方案，与面向 **A5 代际**（950，`arch35`，`DAV_3510`）的 `references/scatter/patterns.md` 分属两代，按目标芯片选用。
+> 两代在 UB 容量与可用指令上存在实质差异（A2/A3 无硬件 Scatter 指令、只能走标量方案），Tiling 结论不可跨代照搬。
+
+## 通用设计要素（所有类别必须）
+
+以下设计要素是所有算子类别都必须考虑和完成的：
+
+### 1. 多核切分策略
+
+**核心问题**：任务如何分配给多个 AI Core？
+
+**设计要点**：
+- 负载均衡：每个核处理的任务量尽量相等
+- 数据局部性：相邻数据尽量分配给同一核
+- 粒度适中：tile 不能太小（调度开销大），不能太大（并行度低）
+
+**输出**：
+- [ ] 总任务切分方式（按哪个维度切）
+- [ ] 每个 AI Core 处理的任务量
+- [ ] 使用的 AI Core 数量
+
+### 2. UB 切分策略
+
+**核心问题**：单次能处理多少数据？
+
+**设计要点**：
+- UB 容量限制（DAV_2201: 192KB, DAV_3510: 248KB）
+- 单次处理数据量
+- 是否需要分 chunk 处理
+
+**输出**：
+- [ ] 单次处理的数据量
+- [ ] 是否需要分 chunk
+- [ ] chunk 大小计算公式
+
+### 3. Buffer 规划
+
+**核心问题**：需要哪些 buffer？各多大？
+
+**设计要点**：
+- 输入 buffer（inQueue）
+- 输出 buffer（outQueue）
+- 中间计算 buffer（tmpBuf, workBuf 等）
+- Double Buffer 优化
+- **UB 复用与扩满**（必须遵守）：设计计算块时，尽可能实现 buffer 复用，减少临时 buffer 的申请；扩大 UB 使用量，实现尽可能用满所有可用 UB 空间。当多个计算步骤的 buffer 生命周期不重叠时，应复用同一 TBuf 而非申请新 buffer；在不超过 `GetCoreMemSize(UB)` 上限的前提下，增大 tile size 使 UB 利用率尽可能接近 100%
+
+**输出**：
+- [ ] Buffer 列表及用途
+- [ ] 各 Buffer 大小计算公式
+- [ ] Buffer 复用方案（哪些 buffer 可复用同一 TBuf）
+- [ ] 总 UB 使用量及 UB 利用率（总分配 / `GetCoreMemSize(UB)`）
+
+### 4. 分支场景覆盖
+
+**核心问题**：需要处理哪些不同场景？
+
+**常见分支维度**：
+- 数据类型：FP32 / FP16 / BF16 / INT8
+- Shape 大小：大 shape / 小 shape
+- 数据对齐：32字节对齐 / 非对齐
+- 边界情况：最小值 / 最大值 / 特殊值
+
+**输出**：
+- [ ] 分支决策条件
+- [ ] 各分支的处理策略
+- [ ] 边界测试用例

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/evals/evals.json

@@ -0,0 +1,72 @@
+{
+  "eval_mode": "text",
+  "evals": [
+    {
+      "id": 1,
+      "title": "Tiling 设计指南的功能与覆盖范围",
+      "config": {
+        "max_tokens": 100000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 120000,
+          "glm-5": 110000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请介绍 ascendc-tiling-design 技能的功能和使用场景，它覆盖哪些算子类别的 Tiling 设计？",
+      "expected_output": "回复应说明 ascendc-tiling-design 技能的功能、使用场景以及覆盖的算子分类体系。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 2,
+      "title": "通用 Tiling 设计要素",
+      "config": {
+        "max_tokens": 100000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 120000,
+          "glm-5": 110000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "所有算子类型的 Tiling 设计中必须考虑的通用要素有哪些？请分别说明每个要素的核心问题。不需要执行任何工具调用。",
+      "expected_output": "回复应说明 Tiling 设计的四个通用核心要素：\n- 多核切分策略：任务如何分配给多个 AI Core，关注负载均衡、数据局部性、粒度适中\n- UB 切分策略：单次能处理多少数据，受 UB 容量限制（DAV_2201: 192KB, DAV_3510: 248KB），决定是否需要分 chunk\n- Buffer 规划：需要哪些 buffer（inQueue/outQueue/tmpBuf/workBuf）及各多大，支持 Double Buffer 优化\n- 分支场景覆盖：需处理不同数据类型（FP32/FP16/BF16/INT8）、Shape 大小、数据对齐、边界情况等分支",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 3,
+      "title": "未确认 DAV_* 时先查架构",
+      "config": {
+        "max_tokens": 100000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 120000,
+          "glm-5": 110000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "distractor_skills": [
+          "npu-arch"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "现在要为一个 Broadcast 类算子选择实现路径。目标芯片是 Ascend910B3，但我还没有确认它对应的 DAV_* 架构号。请说明在进入 Broadcast 方案决策树之前应先做什么，以及确认架构后如何继续。只说明路由，不要生成代码。",
+      "expected_output": "回复应先使用 npu-arch 确认 Ascend910B3 对应的 SoC → DAV_* 映射，不能仅凭芯片名称猜测架构。确认架构号后，再按 ascendc-tiling-design/references/broadcast/patterns.md 的决策树继续选择广播路径；若映射结果为 DAV_2201，则进入 ub-broadcast.md 对应的 UB Broadcast 路径。",
+      "files": [],
+      "expectations": [
+        {
+          "type": "skill_activated",
+          "pattern": "npu-arch",
+          "description": "进入 Broadcast 决策树前先激活 npu-arch 完成架构确认"
+        }
+      ]
+    }
+  ],
+  "skill_name": "ascendc-tiling-design"
+}

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/broadcast/dynamic-ub-broadcast.md

@@ -0,0 +1,87 @@
+# Broadcast - 动态 UB Broadcast（DAV_3510）
+
+> **适用场景**: 合轴后多维，DAV_3510 芯片。使用动态 Broadcast API（rank 1~9）在 UB 内广播，无 32B 对齐限制。
+>
+> **DAV_2201** 请使用静态接口（rank=1/2），详见 [ub-broadcast.md](ub-broadcast.md)。
+
+---
+
+## 一、与静态接口的对比
+
+| 维度 | 静态接口 (DAV_2201/DAV_3510) | 动态接口 (DAV_3510) |
+|------|-------------------------------|---------------|
+| 芯片 | DAV_2201/DAV_3510 通用 | 仅 DAV_3510 |
+| rank | 仅 1D/2D | **1~9** |
+| axis | 仅 0/1（编译期） | **任意轴**（运行时） |
+| 对齐 | dim=2,axis=0 需 srcShape[1] 32B 对齐 | **无对齐限制** |
+| tmpBuffer | 需要手动管理或框架申请 | Tiling 内部管理 |
+| dtype | int8/uint8/half/float | int8/uint8/int16/uint16/half/bfloat16/int32/uint32/float/int64/uint64 |
+
+---
+
+## 二、API
+
+```cpp
+// 1. Kernel 侧计算 Tiling
+BroadcastTiling tiling;
+GetBroadcastTilingInfo<T>(rank, dstShape, srcShape, false, tiling);
+
+// 2. 执行广播
+Broadcast<T>(dstLocal, srcLocal, dstShape, srcShape, &tiling);
+```
+
+**参数说明**：
+
+| 参数 | 说明 |
+|------|------|
+| rank | 维度数，[1, 9] |
+| dstShape | 输出 shape，uint32_t 数组，长度 = rank |
+| srcShape | 输入 shape，uint32_t 数组，长度 = rank。srcShape[i]=1 且 dstShape[i]>1 时该轴广播 |
+| srcInnerPad | 最后一维是否 32B 对齐，当前仅支持 false |
+| tiling | `GetBroadcastTilingInfo` 的输出，传给 `Broadcast` |
+
+**示例**：
+
+```cpp
+// [2, 1, 4] → [2, 3, 4]（沿 axis=1 广播，rank=3）
+uint32_t dstShape[] = {2, 3, 4};
+uint32_t srcShape[] = {2, 1, 4};
+BroadcastTiling tiling;
+GetBroadcastTilingInfo<float>(3, dstShape, srcShape, false, tiling);
+Broadcast<float>(dstLocal, srcLocal, dstShape, srcShape, &tiling);
+
+// [1, 8] → [4, 8]（沿 axis=0 广播，rank=2，无 32B 对齐要求）
+uint32_t dstShape2[] = {4, 8};
+uint32_t srcShape2[] = {1, 8};
+BroadcastTiling tiling2;
+GetBroadcastTilingInfo<half>(2, dstShape2, srcShape2, false, tiling2);
+Broadcast<half>(dstLocal, srcLocal, dstShape2, srcShape2, &tiling2);
+```
+
+---
+
+## 三、约束
+
+| 约束 | 说明 |
+|------|------|
+| **芯片** | 仅 DAV_3510 |
+| **rank** | [1, 9] |
+| **广播条件** | srcShape[i]=1 且 dstShape[i]>1 |
+| **地址重叠** | src 和 dst 不能重叠 |
+| **srcInnerPad** | 当前仅支持 false |
+
+---
+
+## 四、数据流
+
+与静态 UB Broadcast 相同，区别仅在 Broadcast API 调用：
+
+```
+GM → DataCopyPad → UB [srcShape, 未广播]
+  ↓
+GetBroadcastTilingInfo + Broadcast → UB [dstShape, 已广播]
+  ↓
+Compute → UB → DataCopyPad → GM
+```
+
+Tiling 参数计算、多核切分、多维索引管理与 [ub-broadcast.md](ub-broadcast.md) 完全相同。

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/broadcast/nddma-broadcast.md

@@ -0,0 +1,199 @@
+# Broadcast - NDDMA Broadcast 分支（DAV_3510）
+
+> **适用场景**: 合轴后多维，DAV_3510 芯片。**仅用于 GM→UB 搬入阶段**，通过 NDDMA 硬件 stride=0 配置自动广播，数据到达 UB 时已是广播后的完整 tile。不适用于 UB 内部广播（UB 内部请使用 [动态 UB Broadcast](dynamic-ub-broadcast.md)）。
+>
+> **DAV_2201 不支持 NDDMA**，请使用 [UB Broadcast 静态接口](ub-broadcast.md)。
+
+---
+
+## 一、分支特征
+
+| 特征 | 说明 |
+|------|------|
+| **芯片要求** | DAV_3510（Ascend 950） |
+| **合轴后维度** | > 1 维 |
+| **广播方式** | GM→UB 搬运时，NDDMA 硬件根据 stride=0 自动复制数据 |
+| **与 UB BRC 的区别** | 不需要 UB 内 `Broadcast()` API 调用，搬入即完成广播 |
+| **NDDMA 最大维度** | 5 维。超过 5 维需要外层循环 + 多次 NDDMA 调用 |
+
+---
+
+## 二、核心 API：DataCopy + MultiCopyParams
+
+NDDMA 广播的本质：配置多维 strided copy，将广播轴的 srcStride 设为 0，硬件在该轴自动复制。
+
+### 2.1 MultiCopyParams 结构
+
+```cpp
+// NDDMA 最大支持 5 维
+constexpr int64_t NDDMA_MAX_DIMS = 5;
+
+AscendC::MultiCopyLoopInfo<NDDMA_MAX_DIMS> loopInfo;
+// loopInfo.loopSize[i]      — 第 i 维的循环次数
+// loopInfo.loopSrcStride[i] — 第 i 维的 GM 源跳跃（stride=0 → 该维自动复制）
+// loopInfo.loopDstStride[i] — 第 i 维的 UB 目标跳跃
+
+AscendC::MultiCopyParams<T, NDDMA_MAX_DIMS> params = {loopInfo, constValue};
+```
+
+### 2.2 调用方式
+
+```cpp
+static constexpr AscendC::MultiCopyConfig config = {false, 0, 0, false};
+AscendC::DataCopy<T, NDDMA_MAX_DIMS, config>(localTensor, globalTensor[gmOffset], params);
+```
+
+### 2.3 stride=0 的广播效果
+
+```
+示例: x=[1,3,8] 广播到 out=[4,3,8]
+  inputStrides  = [0, 8, 1]    ← 轴 0 stride=0，需要广播
+  outputStrides = [24, 8, 1]
+
+NDDMA 配置:
+  loopSize      = [4, 3, 8]
+  loopSrcStride = [0, 8, 1]    ← srcStride[0]=0，硬件在轴 0 重复读同一块数据
+  loopDstStride = [24, 8, 1]
+
+效果: 硬件自动将 [1,3,8] 的数据复制 4 次填满 [4,3,8]
+```
+
+---
+
+## 三、两种模式
+
+### 3.1 WithoutLoop（schMode=1）：UB 切分后剩余轴 ≤ 5
+
+剩余维度在 NDDMA 的 5 维限制内，一次 `DataCopy` 调用完成。
+
+```cpp
+// 配置 MultiCopyParams：将 ubSplitAxis 及之后的轴映射到 NDDMA 的 5 维
+MultiCopyParams<T, 5> params = BroadcastSetNddmaConfigWithoutLoop<T>(
+    outputDims, outputStrides, inputStrides, shapeLen, ubSplitSize, ubSplitAxis);
+
+// 一次搬入完成广播
+DataCopy<T, 5, config>(localTensor, globalTensor[gmOffset], params);
+```
+
+**优化**：如果某个广播输入的 `inputStrides[ubSplitAxis] == outputStrides[ubSplitAxis]`（即该输入在 UB 切分轴无需广播），退化为普通 `DataCopyPad`，避免 NDDMA 开销。
+
+### 3.2 WithLoop（schMode=2）：UB 切分后剩余轴 > 5
+
+剩余维度超过 NDDMA 的 5 维限制。将最内 5 维交给 NDDMA，外层轴通过 Kernel 循环遍历。
+
+```cpp
+// 配置 NDDMA 处理最内 5 维
+MultiCopyParams<T, 5> params = BroadcastSetNddmaConfigWithLoop<T>(
+    outputDims, outputStrides, inputStrides, shapeLen, ubSplitAxis);
+
+// 外层循环遍历剩余轴
+int64_t nddmaProduct = BroadcastFuseAxes(outputDims, ubSplitAxis + 1, shapeLen - 5) * ubSplitSize;
+int64_t nddmaIndices[3] = {0};
+
+for (int64_t i = 0; i < nddmaProduct; i++) {
+    if (i != 0) {
+        BroadcastUpdateNddmaAxesIndices(nddmaIndices, outputDims, ubSplitAxis, ...);
+    }
+    int64_t nddmaGmOffset = BroadcastGetNddmaOffset(nddmaIndices, inputStrides, ...);
+    int64_t nddmaUbOffset = BroadcastGetNddmaOffset(nddmaIndices, outputStrides, ...);
+
+    DataCopy<T, 5, config>(localTensor[nddmaUbOffset],
+                           globalTensor[gmOffset + nddmaGmOffset], params);
+}
+```
+
+### 3.3 FuseAxis 优化（WithLoop + CopyBrcSize ≤ 4）
+
+当 CopyBrc 节点数 ≤ 4 且 ≥ 3 时，尝试将广播模式相同的相邻轴合并，减少 NDDMA 调用次数：
+
+```cpp
+// 从最内轴向外扫描，相邻轴广播模式相同（都 stride=0 或都 stride>0）则合并
+while (count > ubSplitAxis) {
+    curFlag = inputStrides[count] == 0 ? 0 : 1;
+    if (curFlag != oriFlag) {
+        // 不同模式 → 新维度
+        outputDims2[newCount] = outputDims[count];
+    } else {
+        // 相同模式 → 合并
+        outputDims2[newCount] *= outputDims[count];
+    }
+}
+```
+
+---
+
+## 四、Tiling 参数计算
+
+与 UB Broadcast 分支完全相同（共用 `DoBrodcastTiling`），仅 schMode 不同：
+
+```cpp
+// 判定
+int64_t axisInsideUB = shapeLen - ubSplitAxis;
+if (axisInsideUB <= 5) {
+    schMode = 1;   // WithoutLoop
+} else {
+    schMode = 2;   // WithLoop
+}
+```
+
+---
+
+## 五、Kernel 执行流程
+
+```cpp
+__aicore__ inline void Process()
+{
+    int64_t ubLoopNum = (GetBlockIdx() == GetBlockNum() - 1)
+                        ? blockTail : blockFormer;
+
+    int64_t axesIndices[8] = {0};
+    BroadcastGetAxesIndices(axesIndices, blockFormer * GetBlockIdx(),
+        outputDims, ubSplitAxis, dimProductBeforeUbInner);
+
+    for (int64_t ubLoopIdx = 0; ubLoopIdx < ubLoopNum; ubLoopIdx++) {
+        if (ubLoopIdx != 0) {
+            BroadcastUpdateAxesIndices(axesIndices, outputDims, ubSplitAxis, ubOuter);
+        }
+
+        int64_t ubSplitSize = (axesIndices[ubSplitAxis] == ubOuter - 1)
+                              ? ubTail : ubFormer;
+
+        // 1. 广播输入：NDDMA 搬入（stride=0 轴硬件自动复制）
+        //    数据到达 UB 时已是广播后的完整 tile
+        BroadcastNddmaWithoutLoop/WithLoop(globalTensor, localTensor, ...);
+
+        // 2. 普通输入：DataCopyPad 线性搬入
+        DataCopyPad(inputLocal, inputGm[gmOffset], {1, inputLength * sizeof(T), 0, 0, 0});
+
+        // 3. 计算
+        Add(outputLocal, input0Local, input1Local, tileLength);
+
+        // 4. 搬出
+        DataCopyPad(outputGm[outOffset], outputLocal, {1, tileLength * sizeof(T), 0, 0, 0});
+    }
+}
+```
+
+---
+
+## 六、与 UB Broadcast 的对比
+
+| 维度 | UB Broadcast (DAV_2201) | NDDMA Broadcast (DAV_3510) |
+|------|---------------------|----------------------|
+| 广播时机 | 搬入后，UB 内调用 Broadcast API | 搬入时，硬件自动完成 |
+| UB 占用 | 需要 src + dst 两块空间 | 只需 dst 空间（搬入即是结果） |
+| API | `Broadcast<T, dim, axis>()` | `DataCopy<T, 5, config>()` |
+| 维度限制 | 静态接口 1D/2D；动态接口 rank 1~9 | NDDMA 最大 5 维，超过需外层循环 |
+| 性能 | 额外矢量指令开销 | 硬件完成，无额外指令 |
+| tmpBuffer | 需要（Broadcast API 内部使用） | 不需要 |
+
+---
+
+## 七、约束
+
+| 约束 | 说明 |
+|------|------|
+| **芯片** | 仅 DAV_3510（Ascend 950），DAV_2201 不支持 |
+| **NDDMA 最大维度** | 5。超过 5 维需外层循环 |
+| **stride=0 含义** | inputStrides 中 stride=0 的轴，硬件重复读取不推进地址 |
+| **无广播退化** | inputStrides == outputStrides 时退化为 DataCopyPad |

package/assets/ops-direct-invoke/skills/ascendc-tiling-design/references/broadcast/onedim.md

@@ -0,0 +1,152 @@
+# Broadcast - OneDim 分支
+
+> **适用场景**: 合轴后所有维度合为一维，本质是 Elementwise（部分输入可能是标量 dim=1）
+
+---
+
+## 一、分支特征
+
+| 特征 | 说明 |
+|------|------|
+| **合轴后维度** | 1 维 |
+| **广播方式** | 标量输入优先用 TensorScalar 接口（Adds/Muls 等），无对应接口时 Duplicate 展开 |
+| **数据连续性** | 所有数据连续，线性处理 |
+| **计算结果** | 与输出等长的 1D 向量 |
+
+---
+
+## 二、Buffer 规划
+
+```cpp
+// aliveNum = 所有存活节点数（输入 + 输出 + 中间 buffer）
+// maxDtypeBytes = 计算图中最大 dtype 字节数
+
+pipe->InitBuffer(buf, ubFormer * maxDtypeBytes * aliveNum);
+```
+
+---
+
+## 三、Tiling 参数计算
+
+### 3.1 UB 切分
+
+```cpp
+// 先分 UB，开 DB，128B 对齐
+int64_t ubFormerByte = (ubSize - extraSize) / aliveNum;
+int64_t ubFormer = (ubFormerByte / CACHE_LINE) * CACHE_LINE / maxDtypeBytes;
+// CACHE_LINE = 128
+```
+
+### 3.2 多核切分
+
+```cpp
+int64_t dimLength = outputDims[0];  // 合轴后只有 1 维
+
+int64_t ubOuter = ceil(dimLength / ubFormer);
+int64_t ubTail = dimLength % ubFormer;  // 0 → ubFormer
+int64_t blockFormer = ceil(ubOuter / coreNum);
+int64_t blockTail = ubOuter % blockFormer;  // 0 → blockFormer
+int64_t blockNum = ceil(ubOuter / blockFormer);
+```
+
+### 3.3 多核优化
+
+当 blockNum 不足 coreNum 一半时，缩小 ubFormer 使核数翻倍：
+
+```cpp
+if (blockNum < coreNum / 2 && ubFormer * maxDtypeBytes * aliveNum > 8 * 1024) {
+    // 尝试按 coreNum/2 重新分配
+    int64_t dimPerCore = dimLength * 2 / coreNum;
+    int64_t alignDimPerCore = ceil_align(dimPerCore * maxDtypeBytes, CACHE_LINE) / maxDtypeBytes;
+    ubFormer = min(ubFormer, alignDimPerCore);
+
+    // 下限：开 DB 后每核至少 8KB
+    int64_t lowestUbFormer = (8 * 1024 / aliveNum / CACHE_LINE) * CACHE_LINE / maxDtypeBytes;
+    ubFormer = max(ubFormer, lowestUbFormer);
+
+    // 重新计算分核参数
+    ubOuter = ceil(dimLength / ubFormer);
+    blockFormer = ceil(ubOuter / coreNum);
+    blockNum = ceil(ubOuter / blockFormer);
+}
+```
+
+---
+
+## 四、Kernel 实现要点
+
+### 4.1 数据流
+
+```
+GM → DataCopyPad → UB [ubFormer]
+  ↓
+  标量输入: 优先用 TensorScalar 接口（Adds/Subs/Muls 等），无需搬入
+           若无对应 TensorScalar 接口，才用 Duplicate 展开为向量 + TensorTensor 接口
+  非标量输入: DataCopyPad(inputGm, curLen)
+  ↓
+Compute (Add/Mul/Sub/... 逐元素)
+  ↓
+UB → DataCopyPad → GM
+```
+
+### 4.2 标量输入检测
+
+合轴后某个输入 dim=1 → 该输入是标量。用 scalarFlag 位图标记：
+
+```cpp
+// Host 侧
+int32_t scalarFlag = 0;
+for (int i = 0; i < inputNum; i++) {
+    if (dims[i][0] == 1) {
+        scalarFlag |= (1 << i);
+    }
+}
+```
+
+### 4.3 核心代码模板
+
+```cpp
+__aicore__ inline void Process()
+{
+    int64_t blockLoopNum = (GetBlockIdx() == blockNum - 1) ? blockTail : blockFormer;
+    int64_t offset = GetBlockIdx() * blockFormer * ubFormer;
+
+    for (int64_t i = 0; i < blockLoopNum; i++) {
+        int64_t curLen = (i == blockLoopNum - 1 && GetBlockIdx() == blockNum - 1)
+                         ? ubTail : ubFormer;
+
+        // CopyIn：非标量输入用 DataCopyPad
+        DataCopyPad(input0Local, input0Gm[offset], {1, curLen * sizeof(T), 0, 0, 0});
+
+        // Compute：标量输入优先用 TensorScalar 接口
+        if (scalarFlag & (1 << 1)) {
+            // 方式1（推荐）：有对应 TensorScalar 接口时直接用
+            Adds(outputLocal, input0Local, scalar1, curLen);
+            // 方式2（兜底）：无对应 TensorScalar 接口时 Duplicate + TensorTensor
+            // Duplicate<T>(input1Local, scalar1, curLen);
+            // CustomOp(outputLocal, input0Local, input1Local, curLen);
+        } else {
+            DataCopyPad(input1Local, input1Gm[offset], {1, curLen * sizeof(T), 0, 0, 0});
+            Add(outputLocal, input0Local, input1Local, curLen);
+        }
+
+        // CopyOut
+        DataCopyPad(outputGm[offset], outputLocal, {1, curLen * sizeof(T), 0, 0, 0});
+
+        offset += ubFormer;
+    }
+}
+```
+
+> **标量处理优先级**：Adds/Subs/Muls/Divs 等 TensorScalar 接口 > Duplicate + TensorTensor 接口。
+> TensorScalar 接口省掉 Duplicate 操作和一个 Buffer，性能更优。
+
+---
+
+## 五、常见问题
+
+| 问题 | 原因 | 解决方案 |
+|------|------|---------|
+| 标量输入结果错误 | scalarFlag 计算错误 | 检查合轴后 dims[i][0] 是否为 1 |
+| 核利用率低 | ubFormer 太大导致 blockNum 太少 | 启用多核优化（缩小 ubFormer） |
+| 非对齐数据错误 | DataCopy 不支持非对齐 | 使用 DataCopyPad |