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

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

@@ -0,0 +1,282 @@
+# Reduce API 使用指南
+
+逐行 Reduce 与跨行 Reduce 的 API 选择与使用规范。
+
+---
+
+## 目录
+
+1. [接口选择](#接口选择)
+2. [Level 2 接口（逐行处理）](#level-2-接口逐行处理)
+3. [Pattern 接口（跨行批量）](#pattern-接口跨行批量)
+4. [常见错误](#常见错误)
+5. [最佳实践](#最佳实践)
+
+---
+
+## 接口选择
+
+| 场景 | 接口 | 参数 | 对齐要求 | 典型用途 |
+|-----|------|------|----------|---------|
+| 逐行独立处理 | Level 2 | `(dst, src, tmp, count)` | **无** | Softmax, LayerNorm |
+| 跨行批量处理 | Pattern | **两种形式**（见下文） | 32 字节 | ReduceSum axis=-1 |
+
+**选择原则**：
+- 逐行独立计算 → **Level 2 接口**（更简单，无对齐要求）
+- 需要跨行 Reduce → **Pattern 接口**（性能更高，推荐形式1）
+
+---
+
+## Level 2 接口（逐行处理）
+
+### API 签名
+
+```cpp
+AscendC::ReduceMax<T>(dst, src, tmpBuffer, count, calIndex);
+AscendC::ReduceSum<T, isSetMask=true>(dst, src, tmpBuffer, count);
+AscendC::ReduceMin<T>(dst, src, tmpBuffer, count, calIndex);
+```
+
+**参数**：
+- `dst`：输出 LocalTensor（1 个元素）
+- `src`：输入 LocalTensor（count 个元素）
+- `tmpBuffer`：临时 buffer（**类型必须与 T 相同**）
+- `count`：元素个数（int32_t）
+- `calIndex`：是否计算索引（bool，默认 false）
+
+### tmpBuffer 类型要求
+
+**tmpBuffer 类型必须与 dst/src 相同**：
+
+```cpp
+// ❌ 错误：tmpBuffer 类型不匹配
+AscendC::LocalTensor<uint8_t> tmpBuffer = tmpBuf.Get<uint8_t>();
+AscendC::ReduceMax(rowTmp, src, tmpBuffer, count);  // 编译错误！
+
+// ✅ 正确：tmpBuffer 类型必须与 T 相同
+AscendC::LocalTensor<T> reduceTmp = reduceBuf.Get<T>();
+AscendC::ReduceMax(rowTmp, src, reduceTmp, count);
+```
+
+### 完整示例：Softmax 逐行处理
+
+```cpp
+__aicore__ inline void ProcessRow(
+    AscendC::LocalTensor<T>& xLocal, 
+    AscendC::LocalTensor<T>& yLocal, 
+    uint32_t rowIdx)
+{
+    uint32_t rowOffset = rowIdx * rLengthAlign;  // ⚠️ 用 rLengthAlign
+    
+    AscendC::LocalTensor<T> rowTmp = rowBuf.Get<T>();
+    AscendC::LocalTensor<T> reduceTmp = reduceBuf.Get<T>();
+    
+    // 1. ReduceMax（count = rLength，有效数据个数）
+    AscendC::ReduceMax<T>(rowTmp, xLocal[rowOffset], reduceTmp, 
+        static_cast<int32_t>(rLength), false);
+    
+    T maxVal = rowTmp.GetValue(0);
+    AscendC::Duplicate<T>(rowTmp, maxVal, rLength);
+    AscendC::Sub<T>(xLocal[rowOffset], xLocal[rowOffset], rowTmp, rLength);
+    
+    // 2. Exp
+    AscendC::Exp<T>(xLocal[rowOffset], xLocal[rowOffset], rLength);
+    
+    // 3. ReduceSum
+    AscendC::ReduceSum<T, true>(rowTmp, xLocal[rowOffset], reduceTmp, 
+        static_cast<int32_t>(rLength));
+    
+    T sumVal = rowTmp.GetValue(0);
+    AscendC::Duplicate<T>(rowTmp, sumVal, rLength);
+    AscendC::Div<T>(yLocal[rowOffset], xLocal[rowOffset], rowTmp, rLength);
+}
+```
+
+---
+
+## Pattern 接口（跨行批量）
+
+Pattern 接口有**两种重载形式**，详见 [api-reduce-pattern.md](api-reduce-pattern.md)。
+
+### 快速入门
+
+```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 字节对齐
+
+// 推荐使用形式1：显式传入 tmpLocal
+AscendC::ReduceMax<float, AscendC::Pattern::Reduce::AR, true>(
+    dstLocal, srcLocal, tmpLocal, srcShape, true);
+```
+
+### 关键要点
+
+| 要点 | 说明 |
+|-----|------|
+| **对齐要求** | `alignedCols` 必须 32 字节对齐 |
+| **Pattern 类型** | `Pattern::Reduce::AR`（沿列方向）、`Pattern::Reduce::RA`（沿行方向） |
+| **推荐形式** | 形式1（显式传入 sharedTmpBuffer） |
+| **临时空间** | 两种形式都需要预留，详见 [api-reduce-pattern.md](api-reduce-pattern.md) |
+
+### 非对齐数据处理
+
+```cpp
+// ✅ 方案1：改用 Level 2 接口（无对齐要求）
+AscendC::ReduceMax<T>(dst, src, tmp, rLength, false);
+
+// ✅ 方案2：用 DataCopyPad 填充到对齐
+uint32_t alignedCols = ((rLength * sizeof(T) + 31) / 32) * 32 / sizeof(T);
+AscendC::DataCopyExtParams copyParams{1, rLength * sizeof(T), 0, 0, 0};
+AscendC::DataCopyPadExtParams<T> padParams;
+padParams.isPad = true;
+padParams.rightPadding = alignedCols - rLength;
+DataCopyPad(dstLocal, srcGm, copyParams, padParams);
+
+uint32_t srcShape[] = {1, alignedCols};
+AscendC::ReduceMax<T, AscendC::Pattern::Reduce::AR, true>(dst, src, srcShape, true);
+```
+
+---
+
+## 常见错误
+
+### 错误1：tmpBuffer 类型不匹配
+
+```cpp
+// ❌ 错误
+AscendC::LocalTensor<uint8_t> tmpBuffer = tmpBuf.Get<uint8_t>();
+AscendC::ReduceMax(rowTmp, src, tmpBuffer, count);
+
+// ✅ 正确
+AscendC::LocalTensor<T> reduceTmp = reduceBuf.Get<T>();
+AscendC::ReduceMax(rowTmp, src, reduceTmp, count);
+```
+
+### 错误2：rowOffset 用 rLength 而非 rLengthAlign
+
+```cpp
+// ❌ 错误：单行通过，多行失败
+uint32_t rowOffset = rowIdx * rLength;
+
+// ✅ 正确
+uint32_t rowOffset = rowIdx * rLengthAlign;
+```
+
+### 错误3：非对齐数据用 Pattern 接口
+
+```cpp
+// ❌ 错误：rLength=13，非 32 字节对齐
+uint32_t srcShape[] = {1, rLength};
+AscendC::ReduceMax<T, AscendC::Pattern::Reduce::AR, true>(dst, src, srcShape, false);
+
+// ✅ 方案1：改用 Level 2 接口
+AscendC::ReduceMax<T>(dst, src, tmp, rLength, false);
+
+// ✅ 方案2：用 DataCopyPad 填充到对齐（见上文）
+```
+
+### 错误4：Reduce API count 传 rLengthAlign
+
+```cpp
+// ❌ 错误：count 应该是有效数据个数
+AscendC::ReduceMax(rowTmp, src, tmp, rLengthAlign, false);
+
+// ✅ 正确：count 只传有效数据个数
+AscendC::ReduceMax(rowTmp, src, tmp, rLength, false);
+```
+
+### 错误5：Pattern 接口形式2 忘记预留临时空间
+
+```cpp
+// ❌ 错误：运行时 UB 越界或结果错误
+AscendC::ReduceMax<float, AscendC::Pattern::Reduce::AR, true>(dst, src, srcShape, true);
+
+// ✅ 方案1：使用形式1（推荐）
+AscendC::LocalTensor<uint8_t> tmpLocal = tmpBuf.Get<uint8_t>();
+AscendC::ReduceMax<float, AscendC::Pattern::Reduce::AR, true>(dst, src, tmpLocal, srcShape, true);
+
+// ✅ 方案2：预留临时空间（详见 api-reduce-pattern.md）
+```
+
+### 错误6：Reduce dst 起始地址未 8 字节对齐
+
+`ReduceMax<float>` / `ReduceSum<float>` 等 Reduce API 要求 **dst 起始地址 8 字节对齐**（对 fp32 即 2 个元素对齐）。在"小组归约"场景下（每行多组、每组结果仅占 4 字节）容易出现奇数 offset 位置违反对齐。
+
+```cpp
+// ❌ dst 用 stride 1 fp32：每组结果占 4 字节，
+// 写到 dstBuf[r * groupsPerRow + g] 在 g 为奇数时只满足 4B 对齐
+const uint32_t groupsPerRow = 4;
+AscendC::ReduceMax<float>(dstBuf[r * groupsPerRow + g], src, tmp, 32, false);  // g=1,3 → 4B 对齐
+```
+
+修复：dst buffer 用 stride 2 fp32（每组结果占 8 字节槽位）：
+
+```cpp
+// ✅ stride 2 fp32 → 每个 dst 结果占 8 字节，任何 g 都满足 8B 对齐
+AscendC::ReduceMax<float>(dstBuf[r * groupsPerRow * 2 + g * 2], src, tmp, 32, false);
+```
+
+下游读取时索引同步乘 2。
+
+**症状**：Reduce API 返回静默错误（结果残留旧值或写到错位置），不一定立刻 trap。
+
+---
+
+## 最佳实践
+
+### 参数对照表
+
+| 参数位置 | 用 rLength | 用 rLengthAlign |
+|---------|-----------|-----------------|
+| DataCopyPad blockLen | ✓ | ✗ |
+| Reduce API count | ✓ | ✗ |
+| Sub/Exp/Div count | ✓ | ✗ |
+| UB rowOffset | ✗ | ✓ |
+| Buffer 大小计算 | ✗ | ✓ |
+
+### 决策流程
+
+```
+需要 Reduce 操作？
+    │
+    ├─ 逐行独立处理（Softmax/LayerNorm）
+    │     └─→ Level 2 接口
+    │           - 无对齐要求
+    │           - count = rLength
+    │
+    └─ 跨行批量 Reduce
+          └─→ Pattern 接口（形式1 推荐）
+                - 需要 32 字节对齐
+                - 显式管理 tmp buffer
+```
+
+### Buffer 分配
+
+```cpp
+uint32_t tileSize = rowsPerLoop * rLengthAlign * sizeof(T);
+uint32_t rowBufSize = rLengthAlign * sizeof(T);
+uint32_t reduceBufSize = 32 * 1024;
+
+pipe->InitBuffer(inQueueX, 1, tileSize);
+pipe->InitBuffer(outQueueY, 1, tileSize);
+pipe->InitBuffer(rowBuf, rowBufSize);
+pipe->InitBuffer(reduceBuf, reduceBufSize);
+```
+
+---
+
+## API 文档查阅优先级
+
+1. ⭐⭐⭐ **官方 API 文档**：通过 `/ascendc-docs-search` skill 查阅 `ReduceMax` API 文档
+2. ⭐⭐⭐ **官方示例代码**：通过 `/ascendc-docs-search` skill 搜索 `$ASC_DEVKIT_DIR/examples/01_simd_cpp_api/04_advanced_api/04_reduce/`
+3. Pattern 接口详解：[api-reduce-pattern.md](api-reduce-pattern.md)
+
+---
+
+## 参考示例
+
+- `$ASC_DEVKIT_DIR/examples/01_simd_cpp_api/04_advanced_api/04_reduce/reducemax/reducemax.asc` - Pattern 接口示例
+- ReduceMax API 文档（find 搜索）

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

@@ -0,0 +1,144 @@
+# Vector API repeatTime 参数限制
+
+> **核心问题**：repeatTime 为 uint8_t 时最大值 255，超过会溢出导致计算错误
+
+---
+
+## 目录
+
+1. [核心约束](#核心约束)
+2. [如何确认参数范围](#如何确认参数范围)
+3. [问题场景与解决方案](#问题场景与解决方案)
+4. [受影响的 API](#受影响的-api)
+
+---
+
+## 核心约束
+
+**使用 Vector API 前，必须确认 `repeatTime` 参数的范围限制！**
+
+当 `repeatTime` 为 `uint8_t` 类型时，最大值 **255**。
+
+---
+
+## 如何确认参数范围
+
+### 1. 查看函数原型中的参数类型
+
+```cpp
+// Sub API 函数原型（find "$ASC_DEVKIT_DIR/docs/zh/api/" -name "Sub*.md"）
+template <typename T, bool isSetMask = true>
+__aicore__ inline void Sub(
+    const LocalTensor<T>& dst,
+    const LocalTensor<T>& src0,
+    const LocalTensor<T>& src1,
+    uint64_t mask,
+    const uint8_t repeatTime,  // ← uint8_t 类型
+    const BinaryRepeatParams& repeatParams
+);
+```
+
+### 2. 根据数据类型确定范围
+
+| 数据类型 | 取值范围 | 含义 |
+|---------|---------|------|
+| `uint8_t` | 0 ~ 255 | 最多 255 次迭代 |
+| `uint16_t` | 0 ~ 65535 | 最多 65535 次迭代 |
+| `int32_t` | - | 无此限制 |
+
+---
+
+## 问题场景与解决方案
+
+### 问题场景
+
+```cpp
+// 问题：R=256，rowCount=256 > 255
+uint32_t rowCount = 256;
+AscendC::Sub<float>(
+    dst[col],
+    src0[col],
+    src1[col],
+    curMask,
+    rowCount,  // uint32_t 传入 uint8_t 参数，256 溢出为 0！
+    {1, 1, 1, repStride, repStride, 0}
+);
+```
+
+**结果**：`rowCount=256` 被截断为 `0`，Sub 不执行任何计算，输出数据错误。
+
+### 方案一：Host 侧限制 R_max（推荐）
+
+```cpp
+// Host 侧 R_max 计算
+constexpr uint32_t MAX_REPEAT_TIMES = 255;
+uint32_t R_max = (UB_SIZE - overheadBytes) / bytesPerRow;
+R_max = std::min(R_max, MAX_REPEAT_TIMES);  // 确保 R_max <= 255
+```
+
+### 方案二：Kernel 侧分批处理
+
+```cpp
+void SubWithBroadcast(
+    AscendC::LocalTensor<float>& dst,
+    AscendC::LocalTensor<float>& src0,
+    AscendC::LocalTensor<float>& src1,
+    uint32_t a0Count,
+    uint32_t alignedCols,
+    uint32_t rowCount)
+{
+    constexpr uint32_t MAX_REPEAT = 255;
+    uint32_t repStride = alignedCols / BLOCK_ELEMENTS;  // BLOCK_ELEMENTS = 8
+    
+    for (uint32_t col = 0; col < a0Count; col += MASK_FP32) {
+        uint32_t curMask = std::min(a0Count - col, MASK_FP32);
+        
+        // 分批处理
+        uint32_t processedRows = 0;
+        while (processedRows < rowCount) {
+            uint32_t batchRepeat = std::min(rowCount - processedRows, MAX_REPEAT);
+            uint32_t rowOffset = processedRows * alignedCols;
+            
+            AscendC::Sub<float>(
+                dst[rowOffset + col],
+                src0[rowOffset + col],
+                src1[col],
+                curMask,
+                batchRepeat,
+                {1, 1, 1, static_cast<uint8_t>(repStride), static_cast<uint8_t>(repStride), 0}
+            );
+            
+            processedRows += batchRepeat;
+        }
+    }
+}
+```
+
+---
+
+## 受影响的 API
+
+| API 类别 | API 名称 | 参数限制 |
+|---------|---------|---------|
+| 二元运算 | Sub, Add, Mul, Div, Max, Min | `repeatTime` ≤ 255 |
+| 一元运算 | Exp, Log, Sqrt, Abs, Neg | `repeatTime` ≤ 255 |
+| 标量运算 | Muls, Adds, Divs | `repeatTime` ≤ 255 |
+| 其他 | And, Or, Xor, Not | `repeatTime` ≤ 255 |
+
+---
+
+## 最佳实践
+
+| 阶段 | 检查项 |
+|-----|-------|
+| **API 使用前** | 查看文档确认 `repeatTime` 数据类型和范围 |
+| **Host Tiling** | 确保 `R_chunk_size` / `tileRows` 不超过限制 |
+| **Kernel 实现** | 如需超过限制，实现分批处理逻辑 |
+| **调试** | 若 R=256 时出错，优先检查 repeatTime 溢出 |
+
+---
+
+## 文档参考
+
+- Sub API 文档
+- 其他 Vector API 文档路径相同，搜索对应 API 名称

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

@@ -0,0 +1,200 @@
+# Ascend C API 使用限制与替代方案
+
+> **重要**：使用任何 API 前必读，避免编译错误和运行时问题
+
+---
+
+## 1. 编译期限制
+
+### 1.1 禁止使用 std:: 计算函数
+
+**原因**：Kernel 侧不支持 C++ 标准库，必须使用 Ascend C 提供的专用 API
+
+**触发场景**：所有数学计算、比较操作
+
+**禁止列表**：
+
+| std:: 函数 | ❌ 错误用法 | ✅ Ascend C 替代 | 说明 |
+|-----------|----------|----------------|------|
+| `std::abs` | `std::abs(x)` | `AscendC::Abs(dst, src, count)` | 绝对值 |
+| `std::min/max` | `std::min(a, b)` | `(a < b) ? a : b` 或 `AscendC::Min/Max` | 最小/最大值 |
+| `std::sqrt` | `std::sqrt(x)` | `AscendC::Sqrt(dst, src, count)` | 平方根 |
+| `std::pow` | `std::pow(x, y)` | `AscendC::Power(dst, src, count)` | 幂运算 |
+| `std::exp` | `std::exp(x)` | `AscendC::Exp(dst, src, count)` | 指数 |
+| `std::log/log2/log10` | `std::log(x)` | `AscendC::Log/Log2/Log10(dst, src, count)` | 对数 |
+| `std::sin/cos/tan` | `std::sin(x)` | `AscendC::Sin/Cos/Tan(dst, src, count)` | 三角函数 |
+| `std::floor/ceil/round` | `std::floor(x)` | `AscendC::Floor/Ceil/Round(dst, src, count)` | 取整 |
+| `std::isnan/isinf` | `std::isnan(x)` | 手动检查 | 特殊值判断 |
+
+**错误示例**：
+```cpp
+#include <algorithm>
+#include <cmath>
+
+uint32_t result = std::min(a, b);  // ❌ 编译错误
+float val = std::sqrt(x);          // ❌ 编译错误
+float val = std::exp(x);           // ❌ 编译错误
+```
+
+**正确替代**：
+```cpp
+// min/max：使用三元操作符
+uint32_t result = (a < b) ? a : b;  // ✅ min
+uint32_t result = (a > b) ? a : b;  // ✅ max
+
+// 或使用 Ascend C API（批量操作）
+AscendC::LocalTensor<T> minLocal = minBuf.Get<T>();
+AscendC::LocalTensor<T> srcLocal = srcBuf.Get<T>();
+AscendC::Min<T>(minLocal, srcLocal, src2Local, count);  // ✅ 批量最小值
+
+// sqrt/exp/log 等：使用 Ascend C API
+AscendC::LocalTensor<T> dstLocal = dstBuf.Get<T>();
+AscendC::LocalTensor<T> srcLocal = srcBuf.Get<T>();
+AscendC::Sqrt<T>(dstLocal, srcLocal, count);  // ✅ 平方根
+AscendC::Exp<T>(dstLocal, srcLocal, count);   // ✅ 指数
+AscendC::Log<T>(dstLocal, srcLocal, count);   // ✅ 对数
+```
+
+**⚠️ 重要**：所有数学计算都必须使用 Ascend C API，不能混用 std:: 函数！
+
+### 1.2 禁止动态内存分配
+
+**原因**：AI Core 无动态内存管理能力
+
+**触发场景**：创建数组、缓冲区等
+
+**错误示例**：
+```cpp
+std::vector<int> vec;       // ❌ 动态分配
+int* ptr = new int[10];     // ❌ 动态分配
+int* arr = malloc(100);     // ❌ 动态分配
+```
+
+**正确替代**：使用静态分配
+```cpp
+int arr[10];                          // ✅ 栈分配（Host 侧）
+constexpr uint32_t SIZE = 1024;       // ✅ 编译期常量
+pipe.InitBuffer(inQueue, 2, SIZE);    // ✅ UB 静态分配（Kernel 侧）
+```
+
+### 1.3 Host/Kernel 头文件隔离
+
+**规则**：
+- **Host 侧**（`.cpp`）：禁止包含 `kernel_operator.h`
+- **Kernel 侧**（`.asc/.h`）：可包含 `kernel_operator.h`
+
+**错误示例**：
+```cpp
+// host/tiling.cpp
+#include "kernel_operator.h"  // ❌ Host 侧禁止
+```
+
+**正确用法**：
+```cpp
+// host/tiling.cpp
+#include "tiling.h"  // ✅ 仅必要头文件
+#include <cstring>
+
+// kernel/operator.h
+#include "kernel_operator.h"  // ✅ Kernel 侧允许
+```
+
+---
+
+## 2. API 使用限制索引
+
+以下限制在各专题文档中详细说明：
+
+| 限制类型 | 详细文档 | 核心要点 |
+|---------|---------|---------|
+| **GM 数据搬运** | [api-datacopy.md](api-datacopy.md) | 禁用 SetValue/GetValue，强制 DataCopyPad |
+| **Reduce API** | [api-reduce.md](api-reduce.md) | dst ≠ tmpBuffer，禁用低阶 API |
+| **Compare 256字节对齐** | 见下文 2.1 | count 需 256B 对齐，padding 策略 |
+| **repeatTime 限制** | [api-repeat-limits.md](api-repeat-limits.md) | uint8_t 最大 255，需分批处理 |
+| **流水线同步** | [api-pipeline.md](api-pipeline.md) | MTE/Vector 必须用 EnQue/DeQue 同步 |
+
+### 2.1 Compare API 256字节对齐约束
+
+**约束**：`count` 个元素所占空间必须 **256 字节对齐**
+
+**处理方案**：Padding 策略
+
+```cpp
+// 1. 计算对齐大小（float 类型：64 的倍数）
+constexpr uint32_t A0 = 32;
+constexpr uint32_t A0_ALIGN = (A0 + 63) / 64 * 64;  // = 64
+
+// 2. UB Buffer 使用对齐大小
+pipe.InitBuffer(inQueue, 1, R * A0_ALIGN * sizeof(float));
+
+// 3. CopyIn 时填充极值
+Duplicate(xLocal, -FLT_MAX, R * A0_ALIGN);  // ArgMax 用极小值
+// 再拷贝实际数据到前 A0 个位置
+
+// 4. API 调用使用对齐大小
+Compare(cmpLocal, srcLocal, maxLocal, CMPMODE::GT, A0_ALIGN);
+
+// 5. CopyOut 只输出有效数据
+DataCopy(dstGm, yLocal, A0);  // 只输出 A0 个
+```
+
+**极值选择**：
+- ArgMax / 找最大值：`-FLT_MAX` 或 `-INFINITY`
+- ArgMin / 找最小值：`FLT_MAX` 或 `INFINITY`
+
+---
+
+## 3. 类型与常量规范
+
+### 3.1 编译期常量
+
+**规则**：Buffer 大小、循环次数等使用 `constexpr`
+
+```cpp
+// ✅ 正确：编译期常量
+constexpr uint32_t BUFFER_NUM = 2;
+constexpr uint32_t UB_SIZE = 192 * 1024;
+constexpr uint32_t BLOCK_SIZE = 32;
+
+// ❌ 不推荐：运行期常量
+const uint32_t buffer_num = 2;  // 可能影响性能
+```
+
+### 3.2 类型转换
+
+**规则**：显式类型转换，避免隐式精度损失
+
+```cpp
+// ✅ 正确：显式转换
+T sumVal = scalarLocal.GetValue(0);
+T invSumVal = (T)1.0 / sumVal;  // 显式转换为 T
+Muls<T>(dst, src, invSumVal, count);
+
+// ❌ 错误：隐式转换
+float val = 1.0 / sumVal;  // 若 T 是 half，精度损失
+```
+
+---
+
+## 4. 快速诊断清单
+
+遇到编译错误时，检查：
+
+- [ ] 是否使用了 **任何 std:: 计算函数**（min/max/abs/sqrt/exp/log等）→ 改用 Ascend C API 或基础操作
+- [ ] 是否使用了动态内存（`std::vector`, `new`）→ 改用静态分配
+- [ ] Host 侧是否包含了 `kernel_operator.h` → 移除该包含
+- [ ] Reduce API 的 dst 和 tmp 是否是同一 buffer → 使用不同 buffer
+- [ ] 是否使用了 WholeReduce 等低阶 API → 改用高阶 Reduce API
+- [ ] 是否使用了 `const` 而非 `constexpr` → 改用 `constexpr`
+- [ ] 是否使用了不存在的类型（如 `TensorShape`）→ 查阅正确 API
+- [ ] Compare API 的 count 是否满足 256 字节对齐 → 使用 padding 策略
+
+---
+
+## 5. 相关文档
+
+- [api-datacopy.md](api-datacopy.md)：DataCopyPad 使用规范
+- [api-reduce.md](api-reduce.md)：Reduce API 详细用法
+- [api-repeat-limits.md](api-repeat-limits.md)：repeatTime 限制与处理
+- [api-buffer.md](api-buffer.md)：Buffer 管理最佳实践
+- [api-precision.md](api-precision.md)：精度转换规范