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

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/pitfalls/common_traps.md

@@ -0,0 +1,67 @@
+---
+title: 常见陷阱
+purpose: 汇总 RegBase 设计和实现中的高频错误，作为审查前快速检查表。
+read_when:
+  - 设计缺少分层或实现出现不稳定问题。
+  - 需要快速判断是否偏离 RegBase 主路径。
+keywords:
+  - traps
+  - review
+  - layer
+next_reads:
+  - api_misuse.md
+  - regbase_vs_membase_confusions.md
+  - precision_failures.md
+depth: foundation
+topic_type: pitfall
+---
+
+# 常见陷阱
+
+## 1. 分层陷阱
+
+- 把整个 kernel 写成一个大 VF 函数。
+- 把 GM/UB copy 和寄存器计算写在同一层，不说明 ownership。
+- 在 `Process` 里直接堆寄存器级数学，导致 `CopyIn -> Compute -> CopyOut` 不可读。
+- 只写 “RegBase path”，没有说明 Host / Kernel / UB / VF 边界。
+
+## 2. API 陷阱
+
+- 编造 `AscendC::Reg::*` 签名。
+- 把 MemBase / LocalTensor API 当成 RegBase VF API。
+- 没有检查 header 或 SDK 文档。
+- API 参数顺序和 mask 位置靠猜。
+
+## 3. tail / mask 陷阱
+
+- copy 层处理了 tail，但 VF store 没有 mask。
+- mask 使用对齐长度而不是有效长度。
+- compare mask 和 store mask 混用但语义不同。
+- padding 值进入数学结果。
+- `UpdateMask<T>(remaining)` 通过引用推进 `remaining`；随后手工递减同一变量会
+  double-decrement，导致跳过 slice 或 tail。
+- 使用 `UpdateMask<T>(active)` 时，`active` 也可能被更新；索引和
+  `remaining` 必须基于调用前保存的 `step` 或独立的循环索引，不能读取更新后的
+  局部值来推导下一次偏移。
+- 一个进度变量只能有一个推进者；先查当前 SDK 的 `UpdateMask` header，再确定
+  由 API 或外层循环负责推进。
+
+## 4. dtype / precision 陷阱
+
+- fp16/bf16 不说明是否升 fp32。
+- cast 回输出 dtype 的位置不清楚。
+- reduce accumulation dtype 不明确。
+- quant/dequant 缺少 scale、rounding、saturate 说明。
+
+## 5. 同步陷阱
+
+- 用 `SyncAll` 修本地 stage ordering。
+- 把 `MaskReg` 当同步。
+- 没有参考实现就加 `SetFlag` / `WaitFlag`。
+- cross-core flag 用来补本地 UB 交接。
+
+## 相关文档
+
+- [[api_misuse]]
+- [[regbase_vs_membase_confusions]]
+- [[precision_failures]]

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/pitfalls/index.md

@@ -0,0 +1,25 @@
+# 陷阱索引
+
+该目录用于定位 RegBase 设计、实现和审查中的常见错误。出现精度异常、构建失败、API 不确定、tail 错误或 MemBase / RegBase 混淆时，先读这里。
+
+## 选择表
+
+| 文档 | 用途 | 何时阅读 |
+|---|---|---|
+| [常见陷阱](./common_traps.md) | 快速扫查高频错误 | 设计或代码看起来不稳 |
+| [API 误用](./api_misuse.md) | 定位 API 家族、签名、层级误用 | 构建失败或审查 API |
+| [精度指南](./precision_guide.md) | 设计精度策略 | 需要 dtype/cast/mask 判断 |
+| [精度失败](./precision_failures.md) | 从结果异常定位原因 | 输出错误、NaN、tail 错 |
+| [RegBase vs MemBase 混淆](./regbase_vs_membase_confusions.md) | 区分两类数据流和 API | 代码混用 LocalTensor 与 RegTensor |
+| [症状到原因](./symptom_to_cause.md) | 快速从症状找检查路径 | 修复循环中使用 |
+
+## 使用原则
+
+- 先按症状定位，再回到对应 API、主开发指南或开发经验文档验证。
+- 不要只修表面错误；RegBase 问题通常来自分层或 mask 设计不清。
+- 审查中发现阻塞问题时，要指向具体层级和修复建议。
+
+## 相关文档
+
+- [[../api/index]]
+- [[../dev-experience/index]]

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/pitfalls/precision_failures.md

@@ -0,0 +1,51 @@
+---
+title: 精度失败
+purpose: 从输出异常、tail 错误、NaN/Inf 或 dtype 误差定位 RegBase 精度问题。
+read_when:
+  - 测试输出不匹配。
+  - 只有部分 shape 或 tail case 失败。
+keywords:
+  - precision
+  - failure
+  - tail
+next_reads:
+  - precision_guide.md
+  - symptom_to_cause.md
+  - ../api/regbase_api_reference.md
+depth: foundation
+topic_type: pitfall
+---
+
+# 精度失败
+
+## 1. 症状与可能原因
+
+| 症状 | 优先检查 |
+|---|---|
+| 只有 tail case 错 | `MaskReg`、store 长度、padding 值 |
+| 全量偏差 | dtype cast、近似公式、scale 或 epsilon |
+| 输出全 0 | store 路径、select mask、output UB 是否写入 |
+| 随机错误值 | UB ownership、未初始化 register、越界 load/store |
+| NaN/Inf 增多 | 除零保护、sqrt/rsqrt 输入、overflow |
+| fp16/bf16 误差大 | 是否需要 fp32 中间计算 |
+
+## 2. 定位顺序
+
+1. 先确认输入输出和参考 golden 一致。
+2. 查 Host tiling 的 count、offset、tail。
+3. 查 `CopyIn` / `CopyOut` 有效长度。
+4. 查 VF mask、cast 和 store。
+5. 查数学公式和近似实现。
+
+## 3. 修复原则
+
+- 先修数据边界，再修数学公式。
+- 先让 tail case 正确，再做性能优化。
+- 修改精度策略后同步更新 DESIGN.md。
+- 不要通过放宽 atol/rtol 掩盖明显实现错误。
+
+## 相关文档
+
+- [[precision_guide]]
+- [[symptom_to_cause]]
+- [[../api/regbase_api_reference]]

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/pitfalls/precision_guide.md

@@ -0,0 +1,85 @@
+---
+title: 精度指南
+purpose: 设计 RegBase 精度策略时使用，覆盖 dtype route、cast、mask、tail 和 accumulation。
+read_when:
+  - 设计涉及 fp16/bf16/fp32 转换。
+  - 需要判断 atol/rtol 或数值稳定策略。
+keywords:
+  - precision
+  - cast
+  - accumulation
+next_reads:
+  - precision_failures.md
+  - ../api/regbase_api_reference.md
+depth: foundation
+topic_type: pitfall
+---
+
+# 精度指南
+
+## 1. 设计必须显式说明
+
+- 输入 dtype、输出 dtype、VF 内部计算 dtype。
+- cast 发生在 load 后、计算中还是 store 前。
+- mask 是否覆盖所有可能越界或 padding 通道。
+- reduce / norm 的 accumulation dtype。
+- 比较、select 和近似公式的误差来源。
+
+## 2. 常见策略
+
+| 场景 | 策略 |
+|---|---|
+| activation | fp16/bf16 输入可升 fp32 做近似，再 cast 回输出 |
+| RMSNorm / LayerNorm | sum/mean/variance 使用更高精度 accumulation |
+| compare/select | mask 与两个分支 dtype 保持一致 |
+| quant | 记录 scale、rounding、saturate 和输出范围 |
+| tail | 无效通道不参与数学，也不写回有效输出 |
+
+## 3. Cast 放置
+
+数值敏感链路尽量在高精度中保持到最终 cast：
+
+- reduce、`exp`、`log`、reciprocal-style、normalization intermediates 优先使用 fp32。
+- 只有输出边界要求 fp16 或 bf16 时才 cast 回窄类型。
+- 避免多个 nonlinear operation 串在低精度中间结果上。
+- 安全规则是尽早升精度，尽晚降精度。
+
+常见 cast 方向：
+
+| 方向 | 常见 round mode | 说明 |
+|---|---|---|
+| `half -> float` | `CAST_NONE` | 升精度，不应引入舍入策略 |
+| `float -> half` | `CAST_ROUND` | 输出边界常见窄化路径 |
+| `int32_t -> float` | `CAST_NONE` | 语义通常是类型展开 |
+| `half -> int32_t` | 按 quantization rule 选择 | 必须记录 rounding、saturate 和输出范围 |
+
+VF 侧 `Cast` / `Truncate` 的代表签名在 [[../api/regbase_api_reference]] 中维护。写设计或代码前必须回查当前 SDK header 中的 `CastTrait`、`RegLayout`、`SatMode`、`MaskMergeMode`、`RoundMode`，不要只按 API 名称推断参数。
+
+## 4. Reduction 精度和 padding
+
+包含 sum、max、min、mean、norm 或类似聚合时，精度策略还必须说明：
+
+- partial result 的保存位置：`RegTensor`、UB 还是 GM。
+- accumulation dtype，以及最终 cast 的位置。
+- reduce 维度是否跨 tile，跨 tile 时 partial 如何合并。
+- tail lanes 是否参与 count、sum、max/min 或 variance。
+
+padding 不能改变归约语义：
+
+- max padding 不能大于有效数据。
+- min padding 不能小于有效数据。
+- sum / mean 的无效通道不能参与有效 count。
+- variance / norm 必须说明 epsilon、sum 和 count 的 dtype。
+
+## 5. 验收建议
+
+- 构造含 tail 的 shape。
+- 覆盖正负值、零、极值、NaN/Inf 相关输入（如算子语义需要）。
+- 对 fp16/bf16 明确 atol/rtol。
+- 对 fusion 链路比较拆分参考实现。
+
+## 相关文档
+
+- [[precision_failures]]
+- [[../api/regbase_api_reference]]
+- [[../api/arithmetic_and_reduce]]

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/pitfalls/regbase_vs_membase_confusions.md

@@ -0,0 +1,52 @@
+---
+title: RegBase 与 MemBase 混淆
+purpose: 区分 RegBase VF/寄存器数据流与 MemBase/LocalTensor 数据流，避免混用 API 和设计语言。
+read_when:
+  - 设计或代码同时出现 `LocalTensor` compute 和 `RegTensor` compute。
+  - 审查怀疑工作流走错分支。
+keywords:
+  - RegBase
+  - MemBase
+  - LocalTensor
+next_reads:
+  - ../api/regbase_api_reference.md
+  - ../dev-experience/regbase_programming_notes.md
+  - common_traps.md
+depth: foundation
+topic_type: pitfall
+---
+
+# RegBase 与 MemBase 混淆
+
+## 1. 核心区别
+
+| 维度 | RegBase | MemBase / LocalTensor 路径 |
+|---|---|---|
+| compute 核心 | `__VEC_SCOPE__` 内 `RegTensor` / `MaskReg` | `LocalTensor` 上调用 vector API |
+| 中间值 | 尽量留在寄存器 | 常物化到 UB tensor |
+| 有效通道控制 | `MaskReg` | API count / mask 语义依具体 API |
+| 数据流语言 | UB address -> 寄存器 -> UB address | LocalTensor -> LocalTensor |
+
+## 2. 可以共存的部分
+
+RegBase outer shell 可以使用 `TPipe`、`TQue`、`LocalTensor` 做 UB staging。这不等于 MemBase。关键在于 `Compute` 的数学核心是否进入寄存器级 VF body。
+
+## 3. 不应混用的部分
+
+- 在 VF body 内调用只适用于 `LocalTensor` 的 API。
+- 用 `LocalTensor` 中间值替代本应短生命周期的 `RegTensor`。
+- 设计文档一边说 `asc_vf_call`，一边给出 MemBase API 伪代码。
+- 审查时看到 `TQue` 就否定 RegBase。
+
+## 4. 修复方式
+
+- 重新画 Host / Kernel / UB / VF 分层。
+- 把 UB staging 和 VF compute 分开写。
+- API 映射表标注每个 API 所在层。
+- 对不确定 API 回到白名单和参考实现验证。
+
+## 相关文档
+
+- [[../api/regbase_api_reference]]
+- [[../dev-experience/regbase_programming_notes]]
+- [[common_traps]]

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/pitfalls/symptom_to_cause.md

@@ -0,0 +1,38 @@
+---
+title: 症状到原因
+purpose: 在修复循环中从可观察症状快速定位 RegBase 检查路径。
+read_when:
+  - 构建、运行或精度失败，但原因不清。
+keywords:
+  - symptom
+  - cause
+  - debug
+next_reads:
+  - api_misuse.md
+  - precision_failures.md
+  - ../dev-experience/regbase_build_notes.md
+depth: foundation
+topic_type: pitfall
+---
+
+# 症状到原因
+
+| 症状 | 优先原因 | 下一步 |
+|---|---|---|
+| 编译找不到 API | API 名或 header 不正确 | [[api_misuse]]、[[../api/regbase_api_whitelist]] |
+| 模板实例化失败 | dtype route 或 `RegTensor<T>` 不匹配 | 查 API 签名和 dtype 限制 |
+| 运行越界 | tiling count、UB offset 或 tail store 错 | 查 [[../dev-experience/tiling_review_notes]] |
+| 输出全 0 | store 未执行、mask 全 `false`、输出 UB 未入队 | 查数据流和 mask |
+| 只有 tail 错 | `MaskReg` 或有效长度错 | 查 [[precision_failures]] |
+| 性能异常差 | GM/UB 往返多、barrier 过重、fusion 未生效 | 查 [[../dev-experience/regbase_performance_practices]] |
+| 代码看似 RegBase 但审查不过 | MemBase / RegBase 混用 | 查 [[regbase_vs_membase_confusions]] |
+
+## 使用方式
+
+先用症状表确定第一条检查路径，再回到 API、模式或开发经验文档。不要在没有定位层级前盲目改代码。
+
+## 相关文档
+
+- [[api_misuse]]
+- [[precision_failures]]
+- [[../dev-experience/regbase_build_notes]]