cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: tool-precision-debug
+description: 提供 Ascend C 算子精度异常定位、修复、回归与报告的全流程引导。触发：与项目预期不符的精度验证失败、输出全零或随机、NaN/Inf、低精度误差超预期，以及 Cast、DataCopy、归约或同步相关的数值异常。预期内的结果、正常测试设计和纯知识问答不因出现这些词触发。非目标：纯性能调优、崩溃与编译异常、环境安装、API 查询。
+---
+
+# Ascend C Precision Debug
+
+先按用户目标确定任务范围：
+
+| 任务类型 | 走法 |
+| --- | --- |
+| 只定位 | 阶段 1—3 定位根因，然后直接进入阶段 6 交付，不做修复与回归 |
+| 定位并修复 | 完整六阶段 |
+| 问答（询问诊断方法、出处或资料） | 按问题查阅对应参考页，不启动完整流程 |
+
+全程规则：
+
+- 已有可信结果直接复用，不重做；已有理解直接复用，不为形式重画。
+- 需要交付报告的任务，关键结果随阶段写入同一报告；报告位置、模板和章节对应见[报告指引](references/diagnosis/reporting.md)，格式以用户要求为准。仅在对话中交付时不建报告文件，但需保存的运行产物仍按其目录约定放置。
+- 仅用于取证的临时改动（插桩、临时串行化、探针），交付或转修复前恢复；进入修复时在阶段 4 一并处理。
+- 精度通过标准采用用户需求或项目已有比较器，不自行制定阈值。
+
+## 六阶段调试流程
+
+### 阶段 1：复现问题、确认基线
+
+目标是得到一个可信的失败现场：预期是什么、实际差在哪、什么条件下触发。
+
+- 先读公开需求、构建与测试入口和已有失败信息，明确预期结果与判定规则。在不修改代码的情况下按现有入口尝试复现；执行留证、长任务后台运行和停滞处理见[复现性方法](references/diagnosis/reproducibility.md#执行停滞与证据保存)。
+- 固定并记录复现要素：
+  - 输入（或可复验的生成方式）、shape/axis/dtype；
+  - 源码与实际产物的对应关系、构建运行命令；
+  - 参考结果与比较器的来源、参与比较的元素范围。
+  - 输出和失败日志能留则留；缺失信息注明，不猜测补齐。
+- 记录复现状态（稳定 / 偶发 / 当前未复现 / 无法运行）、已确认的失败用例、误差指标和异常元素的索引或分布。本阶段不要求找到首个异常点或根因。
+- 多输出时核对各输出的判定结果与整体判定规则，区分不出失败项时注明。
+
+本阶段核对：比较口径有效、失败现象已固定。比较对象、有效区或比较器的判据不明确时读[比较与验收](references/diagnosis/baseline.md)；重编无变化、结果漂移、未复现或现场不完整时读[复现性方法](references/diagnosis/reproducibility.md)。比较无效先修正口径；不稳定时收敛触发条件，优先检查并发/同步、初始化、生命周期、越界和随机源。无法运行或未复现时，如实说明限制并保留运行证据缺口，继续能开展的源码和已有数据分析。
+
+### 阶段 2：理解算子、画出计算链并标记敏感点
+
+目标是解释这个算子在算什么、本次实际执行走了哪条路径、哪里容易出错。
+
+- 先写清算子的数学语义：公式或坐标映射，各输入、输出和属性的作用；有 reference 时了解它按什么方式求值——数学等价的公式浮点行为可能不同。
+- 画出本次实际执行的计算链：沿实际分派和 tiling，从搬入、计算到写回，标出关键中间量。无法解释算子含义、相关路径、索引或数据交接时，按缺口读[算子建模方法](references/diagnosis/operator-modeling.md)。
+- 在运算顺序、中间精度、舍入点、特殊值等实现与数学语义可能分叉的位置做标记；再沿链核对输入域、数值转换、分支、地址和依赖等敏感点，需要补充检查方向时读[计算链敏感点](references/diagnosis/sensitive-points.md)的相关条目。
+
+reference 求值方式未确认且可能影响判断时，记入待确认项。
+
+**工具**：需要确认产物实际包含的 Kernel、核类型或 TilingKey 时，用 [msobjdump](references/tools/msobjdump.md) 查看元数据、提取设备 ELF。
+
+### 阶段 3：定位问题与验证根因
+
+**定位目标**：把已确认的输出异常追溯到实际执行路径上的具体代码问题——位置、触发条件、造成异常的机制。代码位置可以是一段实现或缺失操作的所在环节，不要求缩成单行；只有可疑范围时，保留“根因未确认”状态。
+
+先做低成本初筛（3.1），无进展再转入系统定位（3.2），取得新证据后验证根因（3.3）。按实际构建、测试耗时安排实验，给后续验证和交付留出时间；可能超预算时先保存当前补丁、结果和未决项。
+
+实验前简记候选及判别预期（这个候选成立时，预期会看到什么变化）；执行后补充实际结果和下一步判断。仅在对话中交付时随阶段进展说明这些关键结果。判断实验结果前先确认：跑的是刚构建的产物、输出是本轮的、比较有效；干预实验还要确认改动生效。具体纪律见[假设与实验方法](references/diagnosis/hypothesis-experiment.md)。
+
+两条底线：
+
+- 按阈值通过仍可能存在会被后续放大的差异；模型吻合、升精度改善或加同步后稳定，都只是支持相应候选，不确认根因。
+- 排除候选要核对其必要条件或预测与已确认事实是否冲突；不把“缺少某种常见误差形态”当作排除依据。
+
+#### 3.1 经验驱动的低成本验证
+
+- 结合阶段 2 的计算链、敏感点和失败现象，以及[patterns 的症状入口](references/patterns/index.md#按症状选择检查)，形成少量候选。候选要落到具体计算、搬运或依赖关系，按区分力和成本排序。
+- 为首批候选各选一项最有区分力的检查或可撤销实验，方法见[低成本验证](references/diagnosis/hypothesis-experiment.md#低成本验证)。首轮默认最多 3 个候选，不凑数量，也不在排除后滚动补充猜测。
+
+| 当前结果 | 下一步 |
+| --- | --- |
+| 具体实现错误与原始异常对应，已有证据支持 | 进入 3.3 确认根因，不必继续初筛 |
+| 已排除当前候选，首批仍有可低成本验证的候选 | 继续验证首批剩余候选，不增加新猜测 |
+| 仅有误差改善、无法区分原因，或首轮后没有明确方向 | 进入 3.2 系统定位 |
+| 缺少有依据的候选，或需要大范围插桩、重写参考、反复扫参 | 直接或提前进入 3.2 |
+
+#### 3.2 系统定位
+
+保留初筛已排除的候选和未解释的现象，按当前缺口选择方法：
+
+- **错误尚未对应到计算环节** → [错误分布与定位](references/diagnosis/localization.md)：把错值、索引和触发条件映射到实际计算与数据流。
+- **缺少能区分原因的中间观察** → [观察点设计](references/diagnosis/checkpoint-design.md)：选少量关键点，明确比较对象与采集方式。
+- **同一依赖链上已有稳定 PASS/FAIL 端点，仍需缩区** → [语义二分](references/diagnosis/semantic-bisection.md)：找一处当前判据的 PASS→FAIL 转变；据中点 PASS 排除更早 FAIL 还需局部单调等排除依据。
+- **需要区分本段新增差异与上游差异的传播** → [逐层误差分析](references/diagnosis/progressive-error-analysis.md)：比较实际输入和可信输入经过同一局部参考后的结果。它可以与二分配合，不必先观察到多次 PASS/FAIL 转变。
+- **需要区分数值路径候选，或衔接局部模型与设备观察** → [数值对照与设备探针](references/diagnosis/numerical-modeling.md)。
+
+#### 3.3 验证具体根因
+
+围绕初筛支持的机制或系统定位取得的新观察，核对具体实现及数据依赖。架构能力疑点用 `knowledge-query`，具体 Ascend C API 语义用 `ascendc-api-knowledge-query` 核对；针对性验证按[假设与实验方法](references/diagnosis/hypothesis-experiment.md)做，不重新扩展成全算子范围的猜测，已有充分证据时不另做实验。仍无法区分原因时回到 3.2 补充观察，不重复同类改动。
+
+根因确认后：修复任务进入阶段 4，只定位任务进入阶段 6。阻塞或预算结束时，交付已有证据、未决项和最有用的下一步——不把结束定位写成根因已确认。
+
+**工具**：
+
+- [DumpTensor](references/diagnosis/dumptensor.md)：在 Kernel 内主动调用，输出指定 Tensor 的值。
+- [show_kernel_debug_data](references/tools/kernel-debug-data.md)：解析 Kernel 的 Tensor、printf 等调测输出。
+- [msSanitizer](https://gitcode.com/Ascend/mssanitizer)：检查设备执行中的访存、竞争或同步问题。
+
+### 阶段 4：实施最小修复（仅修复任务）
+
+- 根据根因实施针对性修改，明确预期变化；一并清理本次仅用于取证的临时改动。
+- 修改公式、dtype、归约顺序或替换实现时，核对相关数值语义；临时串行化、清零或升精度若要作为正式修复保留，须确认符合项目的功能、数值和运行要求。
+
+新发现动摇根因时返回阶段 3。
+
+### 阶段 5：原失败回放与必要回归（仅修复任务）
+
+- 用原输入和验收口径回放失败，确认本次产物被采用（跑的是新构建的产物），再执行项目要求的相关测试。验收判据有疑点时先回查阶段 1。
+- 回归优先验证影响本次修复成立的已知风险，已有适用结果可复用；后续修改只补验受影响的部分。共享函数或分派有改动时，把当前风险对应到受影响的实际实现，用少量代表输入确认；输入变换、掩码或条件分支可能屏蔽风险时，核对样本实际触发的计算。细则见[报告指引](references/diagnosis/reporting.md)与[复现性方法](references/diagnosis/reproducibility.md#判断稳定性)。
+- 可见回归通过后，回看需求明确、当前实现可达且尚无验证依据的数值或离散语义边界，按影响和区分成本决定是否补充定向检查；不因随机样本通过就排除已知候选，也不为追求穷尽而扩展无依据的测试。偶发或漂移按[复现性方法](references/diagnosis/reproducibility.md)在同条件下重复比较。
+
+原失败或相关回归仍失败时，返回阶段 3 定位或阶段 4 调整修复；无法继续时进入阶段 6，说明未完成项。
+
+### 阶段 6：报告与交付
+
+需要报告的任务，汇总报告各阶段已填内容，给出结论、未完成项与风险。不逐阶段复述操作过程；同一证据只展开一次，清理已被后续结果替代的旧状态，保留影响判断的反证与转向。只定位的任务说明结论边界；修复任务分别说明根因、修改与验证情况，关键验证有缺口时注明未完成范围。交付时给出产物目录及报告链接。仅在对话中交付时，随阶段进展说明的关键结果即为交付内容，不另建报告文件。
+
+交付前核对：
+
+- [ ] **观察可信**：比较口径、产物采用与输出新鲜度已确认，未复现与无法运行如实保留。
+- [ ] **证据支持因果**：实验有区分力；异常位置、相似症状或局部模型吻合没有被直接当作根因。
+- [ ] **修复与验证对应**：支持修复结论的验证已覆盖最后一次相关修改，对应实际源码、运行产物与验收口径；诊断绕过与正式修复分别说明。
+- [ ] **结论与交付一致**：任务要求的报告、补丁和关键结果实际存在，结论与 diff、执行结果一致，具体缺口如实保留。
+
+## 参考资料
+
+| 当前问题 | 阅读入口 |
+| --- | --- |
+| 无法定位根因 | [诊断方法](references/diagnosis/index.md) |
+| 根据异常特征查候选机制、算子经验和历史案例 | [故障模式与案例](references/patterns/index.md) |
+| 核对项目已有比较器、golden 和有效区 | [比较与验收](references/diagnosis/baseline.md) |
+| 不确定芯片映射、架构差异、存储与执行模型，需要类似算子或实现示例 | 使用 `knowledge-query` |
+| 不确定 Ascend C API 参数、重载、使用限制或头文件语义 | 使用 `ascendc-api-knowledge-query` |
+| 选择 CANN 工具或调试 API | [工具选用](references/tools/index.md) |
+
+调用查询 Skill 时，把当前缺口限定为具体问题，并给出目标平台和相关版本。单 API 或窄概念核对按配套 Skill 的轻量流程查阅；阅读适用正文后回到当前计算链与实验，出现新知识缺口再补查。配套 Skill 不可用时，复用已有可信资料，继续不依赖该缺口的分析，并说明尚未核实的内容；不猜测验收阈值或硬件能力。采用 API 结论或对比官方实现时，核对目标 CANN、产品、具体重载和输入条件——相似代码或单次通过不能代替本次验证。