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

package/assets/ops-direct-invoke/skills/ascendc-precision-debug/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: ascendc-precision-debug
+description: Ascend C 算子精度调试技能，提供精度问题诊断和解决方法。触发：输出异常（全为0、随机值、未初始化）、精度验证失败（rtol/atol 不达标）、FP16 精度差于预期、Cast 后数据错误、需要排查流水线同步（EnQue/DeQue）或 DataCopy 对齐问题。
+---
+
+# Ascend C 算子精度调试
+
+## 核心理念
+
+> **精度调试 = 理解 + 分析 + 定位 + 修复**
+
+1. **理解数据类型限制**：FP16 约 3-4 位有效数字，FP32 约 6-7 位。
+2. **识别数值稳定性问题**：大数吃小数、灾难性抵消。
+3. **掌握科学调试方法**：从最小复现到根因分析。
+
+## 使用时机
+
+**适用**：精度验证失败（rtol/atol 不达标）、输出全为0或随机值、FP16差于FP32、特定数值范围误差大、流水线同步问题、DataCopy对齐问题。
+
+---
+
+## 调试前置要求 ⭐⭐⭐
+
+> 进入调试前**必须**完成以下三步
+
+### 1. 固定最小可复现用例
+
+| 项目 | 说明 | 示例 |
+|------|------|------|
+| Shape | tensor 形状 | `{8, 16}` |
+| Dtype | 数据类型 | `float16` |
+| 固定值 | 具体数值 | `[1.0, 2.0, -0.5, ...]` |
+
+**选择原则**：优先简单 → 优先32字节对齐 → 优先FP32 → 覆盖边界值
+
+**💡 推荐实践**：调试时建议在至少两个 dtype（如 FP16 和 FP32）上用**同一 shape + 同一数据**验证。如果一种 dtype 通过另一种失败，可按下方对应的诊断模式快速缩小范围。
+
+### 2. 检索官方文档 ⭐
+
+> **禁止凭直觉修改代码**
+
+**检索顺序**：
+1. 使用 `/ascendc-docs-search` skill 搜索示例代码，查找类似算子。
+2. 使用 `/ascendc-docs-search` skill 查阅 API 文档。
+3. 对比官方实现与当前实现。
+
+### 3. 清理缓存和临时文件
+
+```bash
+rm -rf build input output
+mkdir -p build/input build/output
+```
+
+---
+
+## 快速决策树
+
+```
+[前置检查] 已固定用例？已检索API？已清理缓存？
+    │
+    └─ 否 → 先完成前置步骤
+    └─ 是 → 继续
+        │
+        ├─ [第0步] ⭐ 代码修改后输出完全不变？
+        │   ├─ 是 → 清理 build/ 和 kernel_cache 后重试
+        │   └─ 否 → 继续
+        │
+        ├─ [第0.5步] ⭐ 多 dtype 交叉验证
+        │   ├─ FP32通过但FP16/BF16失败 → 精度不足，见下方诊断模式
+        │   ├─ BF16通过但FP16/FP32失败 → API fallback 路径差异 或 精度阈值差异，见下方诊断模式
+        │   └─ 全部通过/全部失败 → 继续
+        │
+        ├─ [第一步] 排查数据搬运 ⭐⭐⭐
+        │   ├─ 输出是否全为 0 或随机错误？
+        │   │   ├─ 是 → 检查流水线同步（EnQue / DeQue）⭐⭐⭐
+        │   │   │       └─ DataCopy 后直接计算？→ 添加 EnQue/DeQue
+        │   │   │       └─ 临时验证：加 PipeBarrier，若正确则确认同步问题
+        │   │   ├─ 检查 DataCopy 是否 32 字节对齐
+        │   │   │       └─ 非对齐 → 改用 DataCopyPad
+        │   │   └─ 检查是否使用 GlobalTensor.SetValue
+        │   │           └─ 是 → 改用 LocalTensor.SetValue + DataCopyPad 搬出到 GM
+        │   └─ 验证：用 "CopyIn → CopyOut" 测试搬运
+        │
+        ├─ [第二步] 对比分析
+        │   └─ 对比官方示例与当前实现 → 发现差异
+        │
+        └─ [第三步] 诊断问题类型
+            ├─ 所有结果都差 → 公式/常量/API选择
+            ├─ 个别值错误 → 边界条件/除零/溢出
+            └─ 误差整体偏大 → FP16精度不足 → 尝试FP32中间计算
+```
+
+---
+
+## 症状-原因速查表
+
+| 症状 | 可能原因 | 诊断方向 |
+|------|----------|----------|
+| **输出全为 0 或随机错误** | 流水线同步缺失 / DataCopy 非对齐 / GlobalTensor.SetValue | 检查 EnQue / DeQue、数据对齐、改用 LocalTensor.SetValue + DataCopyPad ⭐⭐⭐ |
+| `sum=0, max_err=输入级别` | 输出没写出 | 检查输出队列类型（VECIN vs VECOUT） |
+| `sum=0, max_err≈0` | 输出全0/未初始化 | 检查 UB 溢出、buffer 分配 |
+| `特定参数范围失败` | 阈值/边界错误 | 验证阈值计算、检查分支条件 |
+| `非对齐数据失败` | DataCopy 对齐问题 | 改用 DataCopyPad |
+| `FP16 差但 FP32 好` | 精度不足 | 中间计算用 FP32 |
+| `Cast 后数据错误` | RoundMode 错误 | half → float用CAST_NONE，float → half用CAST_ROUND |
+| **BF16 通过但 FP16/FP32 失败** | (1) 部分 API 不支持 BF16，BF16 走了更简单的 fallback 路径反而正确；(2) BF16 与 FP16/FP32 精度特性不同（BF16 mantissa 7bit vs FP16 10bit），精度阈值或溢出行为差异 | 先排查 API fallback 分支差异，再检查精度阈值（rtol/atol）是否适配各 dtype |
+| **FP32 通过但 FP16/BF16 失败** | 半精度中间计算精度不足 | 升精度：Cast → FP32 计算 → Cast 回半精度 |
+| **修改代码后输出完全不变** | 二进制未更新 / 编译器缓存 | 清理 build/ 和 $HOME/atc_data/kernel_cache/ 后重试 |
+
+### 诊断模式："FP32 通过但 FP16/BF16 失败"
+
+这是最常见的精度诊断信号：FP16/BF16 在 Ascend C 中通常共享相同的 Cast-to-FP32 计算路径（`if constexpr (std::is_same_v<T, bfloat16_t> || std::is_same_v<T, half>)`），FP32 通过说明核心算法正确，问题在半精度转换环节。
+
+```
+确认: FP32通过，FP16/BF16失败
+    │
+    ├─ 检查中间计算精度
+    │   ├─ FP16/BF16 Cast→FP32 计算路径是否正确？
+    │   ├─ 是否有未升精度的中间运算（如直接 Add<half>）？
+    │   └─ 验证：将 FP16 路径的中间计算全部用 FP32，观察结果
+    │
+    ├─ 检查 Cast RoundMode
+    │   ├─ half→float 应使用 CAST_NONE
+    │   ├─ float→half 应使用 CAST_ROUND
+    │   └─ 验证：对比 Cast 前后的数值
+    │
+    ├─ 检查 Pipeline 同步
+    │   ├─ FP16/BF16 路径有额外的 Cast 操作，Cast 后是否 EnQue/DeQue？
+    │   ├─ FP32 路径无 Cast，天然无此同步问题
+    │   └─ 验证：在 Cast 后加 PipeBarrier，若正确则确认同步问题
+    │
+    └─ 检查 Buffer 大小
+        ├─ FP16/BF16 路径需额外 Cast buffer（2× innerDim × sizeof(float)）
+        ├─ FP32 路径不需要 Cast buffer
+        └─ 验证：检查 Tiling 中 castBuf 大小计算
+```
+
+### 诊断模式："BF16 通过，但 FP16/FP32 失败"
+
+这是一个有价值的诊断信号，可能由两类原因导致：
+
+**原因1：API 不支持导致 fallback 路径差异**。部分 Ascend C 算术/归约 API 不支持 BF16，开发者为 BF16 实现更简单的 fallback 路径。BF16 fallback 通过说明逻辑正确，问题出在 FP16/FP32 路径中调用的复杂 API 上。
+
+**原因2：精度阈值 / 数值范围差异**。BF16 (mantissa 7bit, 指数范围同 FP32) 与 FP16 (mantissa 10bit, 指数范围更小) 精度特性不同：BF16 不易溢出但尾数精度低，FP16 易溢出但尾数精度高。如果验证阈值（rtol / atol）未区分适配，或 FP16 发生溢出而 BF16 没有，就会出现 BF16 通过但 FP16 失败。
+
+```
+确认: BF16通过，FP16/FP32失败
+    │
+    ├─ [原因1] API fallback 路径差异
+    │   ├─ 搜索代码中 if constexpr (std::is_same_v<T, bfloat16_t>) 分支
+    │   ├─ BF16 走的 fallback 路径 vs FP16/FP32 走的主路径，差异在哪里？
+    │   ├─ 列出 FP16 / FP32 路径中使用但 BF16 路径未使用的 API
+    │   ├─ 逐个验证差异 API 的参数（mask、repeatTime、stride）
+    │   └─ 临时将 FP16 路径改为与 BF16 相同的 fallback 实现，观察是否通过
+    │
+    ├─ [原因2] 精度阈值 / 数值范围差异
+    │   ├─ FP16 是否溢出？（FP16 max ≈ 65504，BF16 指数范围同 FP32）
+    │   ├─ 验证阈值（rtol/atol）是否按 dtype 区分？
+    │   │   ├─ BF16: rtol=1e-2 级别（mantissa 仅 7bit）
+    │   │   └─ FP16: rtol=1e-3 级别（mantissa 10bit）
+    │   └─ 检查中间计算是否因 FP16 的更高精度要求暴露了算法缺陷
+    │
+    └─ 交叉验证
+        ├─ 使用 `/ascendc-docs-search` skill 查阅文档确认相关 API 是否支持 BF16
+        ├─ 如果 API 不支持 BF16 → 优先按原因1排查
+        └─ 如果 API 支持 BF16（BF16/FP16 走相同路径）→ 优先按原因2排查
+```
+
+---
+
+## 常见陷阱速查
+
+| 陷阱 | 症状 | 解决方案 |
+|-----|------|----------|
+| **流水线同步缺失** | 输出全0或随机错误 | DataCopy 后必须 EnQue/DeQue 同步 ⭐⭐⭐ |
+| **DataCopy 非对齐** | 小规模数据全0/异常 | 使用 DataCopyPad ⭐⭐⭐ |
+| **GlobalTensor.SetValue** | 输出全为0 | 改用 LocalTensor.SetValue + DataCopyPad 搬出到 GM ⭐⭐⭐ |
+| **Cast RoundMode** | Cast后数据混乱 | half→float用CAST_NONE，float→half用CAST_ROUND ⭐ |
+| FP16 精度不足 | 简单计算也有误差 | 关键中间值用 FP32 |
+| exp/log 溢出 | 出现 Inf 或 NaN | 先减最大值再计算 |
+| 减法抵消 | a≈b 时 a-b 误差大 | 使用数值稳定等价公式 |
+| Reduce 误差 | Reduce 结果比逐元素误差大 | 使用 FP32 累加器 |
+| 除零风险 | NaN 或异常大值 | 添加 epsilon 保护 |
+
+### 流水线同步调试
+
+**核心问题**：DataCopy / DataCopyPad 是异步 DMA 操作，直接在搬运后的数据上做 Vector 计算可能读到未完成的数据！
+
+```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);
+```
+
+**临时调试方法**：
+```cpp
+DataCopy(x, gm, size);
+PipeBarrier<PIPE_ALL>();  // 临时加，如果结果正确说明是同步问题
+Compute(x);
+```
+
+**如果 PipeBarrier 能解决问题，说明是同步问题** → 修复方案：改为 EnQue/DeQue 机制
+
+| 误区 | 正确理解 |
+|-----|---------|
+| AllocTensor 后数据就可用 | AllocTensor 只分配内存，不等待搬运 |
+| DataCopy 是同步的 | DataCopy 是异步 DMA，立即返回 |
+| 不用 EnQue/DeQue 也能正常工作 | 必须用 EnQue/DeQue 或 PipeBarrier 同步 |
+| PipeBarrier 性能好 | PipeBarrier 是全流水线停顿，性能差 |
+
+详细说明见 [references/common-traps.md](references/common-traps.md)
+
+---
+
+## SIMT 精度调试
+
+SIMT 算子有独特的精度调试问题：DCache 一致性、核内共享内存同步等。
+
+详细说明见 [references/simt-precision-debug.md](references/simt-precision-debug.md)
+
+### SIMT 特有精度陷阱
+
+| 陷阱 | 症状 | 解决方案 |
+|-----|------|----------|
+| **DCache 一致性** | VF 外通过 Scalar 单点写 GM 后其他核读不到 | 使用 DataCacheCleanAndInvalid 刷新 |
+| **SIMT printf 调试** | 需要在 VF 内打印变量 | VF 内用 AscendC::Simt::printf，VF 外用 PRINTF |
+| **workspace 数据同步** | 多核通过 workspace 交换数据后读取不一致 | 在同步位置加 SyncAll() + SetScheduleMode(1) |
+
+---
+
+## 调试策略层级
+
+```
+调试方法
+    │
+    ├─ 快速方法（优先尝试，≤7次）
+    │   ├─ 误差分布分析 → 识别误差模式
+    │   ├─ Printf 特定位置 → 缩小范围
+    │   ├─ DumpTensor 7步法 → kernel 内插桩 + CPU golden 逐段对比 ⭐
+    │   └─ 常见陷阱排查 → 对症下药
+    │
+    └─ 二分调试（保底手段）
+        └─ 快速方法尝试≥7次或方法穷尽时立即切换
+```
+
+> **重要原则**：不要盲目试错超过 7 次
+
+### DumpTensor 7步法
+
+kernel 内插桩调试的标准工具：在 CopyIn / Compute / CopyOut 关键点插入 `DumpTensor`，配合 CPU golden 同 desc 编号 (100/200/300) 逐段对比，快速定位异常出现在数据流哪一阶段。适用：输出错误、NaN/Inf、需要追踪 CopyIn → Compute → CopyOut 各阶段数据。
+
+详细说明见 [references/ascendc-dumptensor.md](references/ascendc-dumptensor.md)
+
+---
+
+## 问题定位方法
+
+### 1. 对比法（与工作的代码对比）
+
+找到正常工作的代码，逐行对比差异
+
+### 2. 边界二分法
+
+记录通过/失败的临界点，分析分支选择
+
+### 3. 数值验证法
+
+不要相信估算公式，用代码计算实际值
+
+### 4. Buffer 调试要点
+
+| 问题 | 表现 | 解决方案 |
+|------|------|----------|
+| VECIN 用于输出 | 输出等于输入 | 输出必须用 VECOUT 队列 |
+| Double Buffer 漏算 | 阈值错误 | 计算阈值时 ×2 |
+
+详细定位流程见 [references/diagnosis-workflow.md](references/diagnosis-workflow.md)
+
+---
+
+## 精度标准来源优先级
+
+1. **优先级1**：算子开发 Plan 中明确的精度要求
+2. **优先级2**：华为昇腾官方精度标准文档
+3. **优先级3**：本 Skill 默认值（仅作兜底）
+
+| 数据类型 | rtol | atol |
+|---------|------|------|
+| FP16 | 1e-3 | 1e-4 |
+| FP32 | 1e-5 | 1e-6 |
+| INT | - | 0 |
+
+---
+
+## Agent 使用指南
+
+### 调试计数规则
+
+```
+计数器 = 0
+每次尝试快速方法（误差分析/Printf/陷阱排查）→ 计数器+1
+当 计数器 >= 7 或 快速方法穷尽 → 立即切换二分调试
+```
+
+> **💡 经验建议**：如果多次尝试未取得进展（失败用例数量未减少），建议：
+> 1. 检查是否清理了编译缓存（`rm -rf build/ $HOME/atc_data/kernel_cache/`）
+> 2. 验证修改后二进制 sha256 是否确实改变
+> 3. 切换到完全不同的调试策略（如二分法降级到最小工作路径）
+
+### 调试总结要求
+
+每步调试成功后**必须**形成总结：
+
+- 文档描述不清晰的地方
+- 需要改进的地方及推荐方案
+- 给 Agent 造成困扰的点
+- 调试过程记录
+
+总结模板：[references/debug-summary-template.md](references/debug-summary-template.md)
+
+### 检查清单
+
+**调试阶段**：
+- [ ] 已固定最小可复现用例
+- [ ] 已通过 `/ascendc-docs-search` skill 确认 API 用法 ⭐
+- [ ] 已清理缓存和临时文件
+- [ ] **已排查流水线同步问题**（DataCopy 后是否 EnQue/DeQue）⭐⭐⭐
+- [ ] **已排查输出全为 0 问题**（DataCopy 对齐 / GlobalTensor.SetValue → LocalTensor.SetValue + DataCopyPad）⭐⭐⭐
+- [ ] 对比官方示例与当前实现
+- [ ] 尝试次数 < 7
+- [ ] 达到阈值立即切换二分调试
+
+---
+
+## 参考资料
+
+### 工作流程
+- [diagnosis-workflow.md](references/diagnosis-workflow.md) - 完整诊断工作流程
+- [binary-search-debug.md](references/binary-search-debug.md) - 二分调试详细指南
+
+### 问题诊断
+- [common-traps.md](references/common-traps.md) - 常见精度陷阱详解
+- [best-practices.md](references/best-practices.md) - 最佳实践
+
+### 调试工具
+- [printf-debug.md](references/printf-debug.md) - Printf 调试法
+- [data-comparison.md](references/data-comparison.md) - 数据对比法
+- [tools-reference.md](references/tools-reference.md) - 工具和命令参考
+- [ascendc-dumptensor.md](references/ascendc-dumptensor.md) - DumpTensor 7步法（含 API、错误模式）
+
+### 实战案例
+- [case-studies.md](references/case-studies.md) - 实战调试案例
+- [debug-summary-template.md](references/debug-summary-template.md) - 调试总结模板

package/assets/ops-direct-invoke/skills/ascendc-precision-debug/evals/evals.json

@@ -0,0 +1,161 @@
+{
+  "eval_mode": "text",
+  "evals": [
+    {
+      "id": 1,
+      "title": "精度调试的核心流程与哲学",
+      "config": {
+        "max_tokens": 160000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 120000,
+          "glm-5": 110000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "在 Ascend C 算子开发中，遇到精度问题时应该如何调试？精度调试的核心方法论是什么？请介绍精度调试的四个主要步骤，以及为什么 FP16 在累加时容易出现精度损失（Catastrophic Cancellation）。",
+      "expected_output": "1. 回复应说明 Ascend C 精度调试的核心理念是\"理解 + 分析 + 定位 + 修复\"四个环节，并指出调试不应凭直觉试错、应先定位误差来源。\n2. 回复应说明四个环节的内容：理解数据类型限制（FP16 约 3-4 位有效数字、FP32 约 6-7 位）与数值稳定性问题；分析时至少用两种 dtype（如 FP16 与 FP32）在同一 shape + 同一数据上交叉验证；定位时按\"排查数据搬运 → 对比官方实现 → 诊断问题类型\"逐层缩小；修复时给出对症手段（如 FP32 累加器、重排计算公式）。\n3. 回复应解释 FP16 累加精度损失的根因：FP16 尾数只有 10 bit（约 3-4 位有效数字），累加时大数吃小数、低位被舍入并逐次累积；以及两个接近的异号大数相减会发生灾难性抵消，使有效数字大量丢失（如 1.234 - 1.233 = 0.001），对应修复方向是提升中间计算精度或重排公式。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 2,
+      "title": "精度调试的前置条件",
+      "config": {
+        "max_tokens": 160000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 120000,
+          "glm-5": 110000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "在进行 Ascend C 算子精度调试之前，需要满足哪些前置条件？为什么必须准备可复现的最小用例和黄金数据？需要检查哪些步骤才能确保可以开始调试？",
+      "expected_output": "1. 回复应说明进入精度调试前必须完成的三项前置要求：固定最小可复现用例（固定 Shape / Dtype / 具体数值，选择原则为优先简单、优先 32 字节对齐、优先 FP32、覆盖边界值）、检索官方文档（用 /ascendc-docs-search 查 API 与示例，禁止凭直觉改代码）、清理缓存和临时文件（rm -rf build input output）。\n2. 回复应说明最小可复现用例与黄金数据的价值：固定 Shape / Dtype / 数值后问题才能稳定复现、排除干扰把问题缩小到最简单场景；黄金数据（CPU golden）作为对比基准，可在 CopyIn / Compute / CopyOut 关键点用 DumpTensor 配合同 desc 编号（100/200/300）逐段对比，定位异常出现在数据流哪一阶段。\n3. 回复应说明开始调试前的检查顺序：前置三项检查 → 确认代码修改是否真正生效（输出完全不变则清理 build/ 与 $HOME/atc_data/kernel_cache/）→ 多 dtype 交叉验证（FP32 通过但 FP16/BF16 失败指向半精度精度不足）。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 3,
+      "title": "算子精度比对调试请求（正向看护）",
+      "config": {
+        "max_tokens": 160000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 180000,
+          "glm-5": 170000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "distractor_skills": [
+          "ascendc-runtime-debug",
+          "ascendc-crash-debug"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我的 Ascend C FP16 算子的计算结果和 Golden 数据有偏差，误差约 5%。我已经用数据比对工具确认了异常输出的位置。我怀疑是 FP16 累加时的 Catastrophic Cancellation 导致的精度损失。请加载 ascendc-precision-debug 技能帮我确认并给出修复建议。",
+      "expected_output": "回复应针对 FP16 精度偏差问题进行分析，给出精度修复的一般建议。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 4,
+      "title": "算子性能调优咨询（负向看护）",
+      "config": {
+        "max_tokens": 160000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 120000,
+          "glm-5": 110000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我的 Ascend C 算子运行速度偏低，AIC 利用率只有 20%，如何分析流水瓶颈并进行优化？",
+      "expected_output": "回复应聚焦于性能分析和流水优化方法，不涉及精度调试相关内容。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 5,
+      "title": "输出全为0或随机错误的流水线同步排查（关键能力）",
+      "config": {
+        "max_tokens": 160000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我在写一个 Ascend C 算子，输入和输出都用 DataCopy 从 Global Memory 搬运到 LocalTensor，搬运完我直接在 LocalTensor 上做 Vector 计算，但计算结果要么全为 0，要么偶尔是随机错误值。我用数据比对工具确认了异常输出的位置。请阅读 ascendc-precision-debug 技能文档获取规范，帮我定位这类输出全 0 或随机错误问题的常见根因和排查方向，但不要实际执行 profiling 或修改我的代码。",
+      "expected_output": "回复应指出输出全为 0 或随机错误的常见根因是流水线同步缺失：DataCopy/DataCopyPad 是异步 DMA，直接在其后的数据上做 Vector 计算会读到未完成搬运的数据。关键要点：1. DataCopy 后应通过 EnQue/DeQue 同步，临时可用 PipeBarrier<PIPE_ALL> 验证是否为同步问题；2. 检查 DataCopy 是否 32 字节对齐，非对齐应改用 DataCopyPad；3. 检查是否误用 GlobalTensor.SetValue，应改用 LocalTensor.SetValue + DataCopyPad 搬出到 GM。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 6,
+      "title": "FP32 通过但 FP16/BF16 失败的升精度排查",
+      "config": {
+        "max_tokens": 160000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我的 Ascend C 算子做累加计算，用 FP32 输入验证完全通过，但换成同一 shape、同一数据的 FP16 后误差明显偏大，rtol/atol 不达标。我已经按调试前置要求固定了最小可复现用例并检索了 API 文档。请阅读 ascendc-precision-debug 技能文档获取规范，帮我分析 FP32 通过但 FP16/BF16 失败的诊断思路和排查方向，但不要实际执行 profiling 或修改我的代码。",
+      "expected_output": "回复应说明 FP32 通过但 FP16/BF16 失败说明核心算法正确、问题在半精度转换环节，属于半精度精度不足。关键要点：1. 检查 FP16/BF16 路径中间计算精度，是否有未升精度的中间运算，应将中间计算 Cast→FP32 计算后再 Cast 回半精度；2. 检查 Cast RoundMode，half→float 应使用 CAST_NONE，float→half 应使用 CAST_ROUND；3. 检查 Cast 后是否 EnQue/DeQue 同步以及 Cast buffer 大小（2×innerDim×sizeof(float)）。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 7,
+      "title": "Cast 后数据错误的 RoundMode 排查",
+      "config": {
+        "max_tokens": 160000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我的 Ascend C 算子需要在 FP16 和 FP32 之间做类型转换，我用 Cast 指令转换后输出数据是乱的，数值和预期完全对不上。代码里我没有显式指定 RoundMode。请阅读 ascendc-precision-debug 技能文档获取规范，帮我定位 Cast 后数据错误的最可能原因，说明正确的 RoundMode 用法，并告诉我如何通过对比 Cast 前后的数值来验证确认，以及除了 RoundMode 外还应该排查哪些方向，但不要实际执行 profiling 或修改我的代码。",
+      "expected_output": "1. 回复应指出 Cast 后数据混乱（数值和预期完全对不上）的最常见根因是 Cast RoundMode 与转换方向不匹配，并给出正确用法：half → float 使用 CAST_NONE，float → half 使用 CAST_ROUND。\n2. 回复应说明通过对比 Cast 前后的数值来验证：在 Cast 前 / Cast 后等关键点插桩 DumpTensor 或 printf，并用 CPU golden 逐段对比，据此判断异常出现在 Cast 环节还是上游搬运。\n3. 回复应指出除 RoundMode 外还应排查 Cast 后的流水线同步（DataCopy → EnQue → DeQue 后再 Cast，可临时用 PipeBarrier<PIPE_ALL> 验证），并给出其他排查方向（如 DataCopy 32 字节对齐、Cast buffer 大小、Cast 的 mask / repeat 参数）。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 8,
+      "title": "修改代码后输出完全不变的编译缓存排查",
+      "config": {
+        "max_tokens": 160000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我在修一个 Ascend C 算子的精度问题，改了公式和常量后重新编译运行，输出和之前一模一样，像是修改完全没有生效。我已经固定了最小可复现用例并检索了 API 文档。请阅读 ascendc-precision-debug 技能文档获取规范，帮我判断修改代码后输出完全不变的根因和处理方法，但不要实际执行 profiling 或修改我的代码。",
+      "expected_output": "回复应说明修改代码后输出完全不变的根因是二进制未更新或编译器缓存。关键要点：1. 清理 build/ 目录和 $HOME/atc_data/kernel_cache/ 编译缓存后重试；2. 可通过验证修改后二进制的 sha256 是否改变来确认修改是否生效；3. 若清理后仍不变，应检查修改是否真正落入编译路径。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 9,
+      "title": "DumpTensor 7步法定位 NaN/Inf 出现阶段",
+      "config": {
+        "max_tokens": 160000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我的 Ascend C 算子输出里有 NaN 和 Inf，不确定异常出现在 CopyIn、Compute 还是 CopyOut 阶段。我有 CPU 上的 golden 参考实现，也已经按前置要求固定了最小用例并检索了官方文档。请阅读 ascendc-precision-debug 技能文档获取规范，告诉我该用什么调试方法来追踪异常出现在数据流的哪一阶段，但不要实际执行 profiling 或修改我的代码。",
+      "expected_output": "回复应推荐 DumpTensor 7步法进行 kernel 内插桩调试。关键要点：1. 在 CopyIn / Compute / CopyOut 关键点插入 DumpTensor；2. 配合 CPU golden 使用同 desc 编号（如 100/200/300）逐段对比；3. 该方法适用于输出错误、NaN/Inf 以及需要追踪 CopyIn → Compute → CopyOut 各阶段数据的场景。",
+      "expectations": [],
+      "files": []
+    }
+  ],
+  "skill_name": "ascendc-precision-debug"
+}

package/assets/ops-direct-invoke/skills/ascendc-precision-debug/references/ascendc-dumptensor-refs/api-reference.md

@@ -0,0 +1,92 @@
+# DumpTensor API Reference
+
+## API Signature
+
+```cpp
+DumpTensor(const LocalTensor<T> &tensor, uint32_t desc, uint32_t dumpSize)
+```
+
+## Parameters
+
+| Parameter  | Type              | Description                                  |
+|------------|-------------------|----------------------------------------------|
+| `tensor`   | `LocalTensor<T>&` | The tensor to dump                           |
+| `desc`     | `uint32_t`        | Unique identifier (use systematic numbering) |
+| `dumpSize` | `uint32_t`        | Number of elements to dump                   |
+
+## Desc Numbering Convention
+
+| Range   | Stage                |
+|---------|----------------------|
+| 100-199 | Input tensors        |
+| 200-299 | Intermediate results |
+| 300-399 | Output tensors       |
+
+Increment by 10 within each range.
+
+## Best Practices
+
+```cpp
+// Control dump size - dump subset for large tensors
+uint32_t dumpSize = std::min(tileLength, 32u);
+DumpTensor(outputLocal, 300, dumpSize);
+
+// Avoid dumping entire large tensors
+DumpTensor(outputLocal, 300, 8192);  // ❌ Too much
+DumpTensor(outputLocal, 300, 32);    // ✅ Better
+```
+
+## Important Notes
+
+- DumpTensor outputs to system log
+- Remove dumps in production code (performance overhead)
+- Start with 32-64 elements, increase only if needed
+
+---
+
+## 调用约束
+
+| 约束             | 说明                                                                       |
+|------------------|----------------------------------------------------------------------------|
+| 调用上下文       | 仅在 kernel 函数内对 `LocalTensor` 调用；`GlobalTensor` 不能直接 dump      |
+| 同步要求         | 数据依赖搬运/计算完成后才能 dump，详见父文档「使用陷阱 §1」                |
+| dumpSize 上限    | 不能超过 tensor 实际元素数，超出会越界                                     |
+| dtype 支持       | 常用 `half / float / int32_t / bfloat16_t` 均支持，特殊 dtype 以 CANN 版本为准 |
+| 性能影响         | 显著时序开销，可能改变流水线行为，定位完成必须移除                         |
+
+## desc 编号扩展约定
+
+基础三段式（100/200/300）够覆盖单核简单算子。复杂算子建议扩展：
+
+```
+desc = base + blockOffset + stageOffset + iterOffset
+
+base       : 100=输入, 200=中间, 300=输出
+blockOffset: GetBlockIdx() * 1000     // 多核分离
+stageOffset: 0/10/20...               // 同段内多个插桩点
+iterOffset : tileIdx                   // 同一 tile 多次迭代区分
+```
+
+示例：core 1 上、第 2 个 tile、Compute 内第 2 个插桩点：
+```cpp
+uint32_t desc = 200 + GetBlockIdx() * 1000 + 20 + tileIdx;
+DumpTensor(midLocal, desc, 32);
+```
+
+## 与 PRINTF / printf 的关系
+
+| API           | 调用位置          | 用途                                    |
+|---------------|-------------------|----------------------------------------|
+| `DumpTensor`  | NPU kernel 内     | 批量看 LocalTensor 元素值              |
+| `PRINTF`      | NPU kernel 内     | 看 scalar、控制流、tile 形参           |
+| `printf`      | Host / CPU 仿真   | 看 host 侧 buffer、CPU golden 输出     |
+| `AscendC::Simt::printf` | SIMT VF 内 | SIMT 算子内单核打印（见父 SKILL SIMT 节）|
+
+调试 tensor 数据用 DumpTensor，调试控制流（tileNum、blockIdx、循环计数）配合 PRINTF。
+
+## 常见踩坑
+
+- **dumpSize 写死太大**：日志被淹没且 dump 自身耗时遮蔽 bug → 默认 32，定位收敛后再加
+- **多 tile 循环只看到最后一次**：每个 tile 单独编号，否则后面的 dump 覆盖前面观察
+- **修改后 dump 完全一致**：先怀疑 kernel cache，`rm -rf build/ $HOME/atc_data/kernel_cache/`
+- **NaN 出现位置不确定**：从输入往后逐段加 dump，找出 NaN 第一次出现的 desc

package/assets/ops-direct-invoke/skills/ascendc-precision-debug/references/ascendc-dumptensor-refs/error-patterns.md

@@ -0,0 +1,40 @@
+# DumpTensor 视角下的错误模式
+
+> 本文聚焦「在 dump 输出里看到什么样的异常 → 该往哪个方向查」。父 SKILL 的「症状-原因速查表」更全面，本文只列与 DumpTensor 插桩诊断强相关的模式。
+
+## DumpTensor 专属诊断模式
+
+| Dump 现象                                       | 最可能的根因                          | 下一步                                                         |
+|-------------------------------------------------|---------------------------------------|----------------------------------------------------------------|
+| desc=100（输入）就异常                          | DataCopy 未完成 / 未 DeQue 就 dump    | 把 DumpTensor 移到 DeQue 之后；或临时 PipeBarrier 验证        |
+| desc=100 正确，desc=200（中间）异常             | Compute 阶段问题                      | 在 Compute 内细分插桩，二分定位是哪个 API/参数                |
+| desc=200 正确，desc=300（输出）全 0 / 全旧值    | CopyOut 没生效 / 队列写错 (VECIN)     | 检查输出队列类型、EnQue/DeQue、DataCopyPad 对齐               |
+| 单核 dump 正确，多核合并后乱                    | desc 未含 blockIdx，多核日志交错      | `desc = base + GetBlockIdx() * 1000`                          |
+| Dump 显示输入与 CPU golden 不一致               | host 侧数据准备 / DataCopy stride 错  | 比对 host buffer，检查 DataCopy 参数                          |
+| 每隔 N 个值一处异常                             | stride / 对齐问题                     | 检查 DataCopy stride、是否需要 DataCopyPad                    |
+| dump 出现 NaN / Inf                             | 除零、exp 溢出、未初始化              | 在出现 NaN 的最早 desc 上游加 dump 缩小范围                   |
+| 改代码后 dump 完全没变                          | 二进制未更新 / kernel cache 命中      | `rm -rf build/ $HOME/atc_data/kernel_cache/` 重编             |
+
+## 通用错误模式速查
+
+仅当 dump 不足以定位、需要回到通用思路时使用：
+
+| Pattern                    | Root Cause                    | Fix                                            |
+|----------------------------|-------------------------------|------------------------------------------------|
+| All values off by constant | Missing bias/scale            | Check Adds/Muls operations                     |
+| Every Nth value wrong      | Stride/alignment issue        | Verify DataCopy stride, check vector alignment |
+| NaN or Inf values          | Division by zero/overflow     | Check denominators, verify input ranges        |
+| First/last values wrong    | Boundary/padding issue        | Check tile alignment, edge case handling       |
+| Errors accumulate          | Uninitialized vars/queue sync | Check init, verify EnQue/DeQue                 |
+| Random sporadic errors     | Race condition/queue depth    | Increase BUFFER_NUM, check sync                |
+| Output all zeros           | Missing compute/wrong queue   | Verify Compute called, check queue             |
+| Output matches input       | Computation not applied       | Verify operation executed                      |
+
+更完整的精度陷阱见父 SKILL 的 [common-traps.md](../common-traps.md)。
+
+## 诊断工作流
+
+1. 从 desc 最小值（输入侧）开始看，找到**第一个**与 CPU golden 不一致的阶段
+2. 对照上方「DumpTensor 专属诊断模式」表匹配根因
+3. 在该阶段上游再插一层 dump，验证假设
+4. 修复后必须清编译缓存重跑，确认 dump 数值变化