cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/diagnosis/operator-modeling.md

@@ -0,0 +1,116 @@
+# 理解 Ascend C 算子与实际计算链
+
+本页用于阶段 2。读完相关代码后，应能说明：**这个算子要算什么，一个输出由哪些输入算出，代码怎样分块执行，结果最终写到哪里。** 从当前失败用例出发，先看相关路径；简单算子用几行说明即可，不必整理整个工程。
+
+按当前缺口选择本页相关部分，已有可信的公式、路径与索引说明直接复用。补充文档只在对应问题实际出现、已有信息不足时按需读取，不沿链接逐篇展开。
+
+## 1. 先弄清算子要算什么
+
+先读任务定义、输入输出和 reference（参考实现），明确三件事：
+
+- **计算含义**：写出公式或坐标映射，说明每个输入、输出和属性的作用。归约要明确轴，广播要明确维度，矩阵乘要明确各维和转置关系。
+- **数据约定**：确认实际 shape、dtype、布局和有效范围。多输出时，分清数值、索引、统计量等输出分别表示什么。
+- **参考行为**：确认项目用什么结果作为正确答案、怎样比较。数学上等价的公式，浮点运算顺序可能不同；涉及当前差异时，再核对 reference 的中间 dtype、求值顺序和特殊值处理。
+
+不要从 Kernel 的现有写法反推正确答案。先能用一个合法的小输入解释预期输出，再看 Kernel 是否实现了这层含义。比较规则沿用阶段 1 已确认的项目要求；尚不清楚的地方注明。
+
+reference 与候选已经分叉时，记录已确认的操作链与参考行为缺口。需要区分多种解释时，将不同预测、能区分它们的合法输入和正常对照交给阶段 3 验证；已有充分证据可直接复用，未执行的结果只记作预测。
+
+公式、分支谓词或参数含义尚未提供时，标为待核，不从相似历史案例补成当前事实。可以用明确标注的假设链解释方法，但它的数值预测只用于检验该假设；取得实际定义或源码后，再核对哪些环节确实对应本次计算。
+
+## 2. 找到本次执行的实现
+
+沿实际调用关系阅读：
+
+```text
+调用入口与实参 → Host 分派和 tiling → Kernel 入口 → 初始化与主循环 → 计算和写回
+```
+
+- **Host 侧**：看当前 shape、dtype、属性选择了哪个实现，分块参数如何计算、怎样传给 Kernel。
+- **Kernel 入口**：对上参数位置、模板或 TilingKey 分支，确认这次用的是哪段代码。源码里存在某个分支，不代表本次执行了它。
+- **初始化与循环**：看输入输出基地址、每块数据量、循环次数和临时缓冲如何设置。字段含义以赋值和使用处为准，例如 `tileLength` 是否包含补齐、`tileNum` 是否已经考虑双缓冲。
+
+工程没有独立 Host tiling、使用直调或其他组织方式时，沿实际参数来源读即可。优先复用阶段 1 的构建和运行信息；影响判断的分支仍未确认时，核对实际 tiling 值、构建选项和加载产物，暂时无法确认的路径注明。
+
+## 3. 看懂分块与索引
+
+把整体计算对应到当前实现的任务划分。只展开代码实际使用的层次：
+
+| 要弄清的问题 | 重点看什么 |
+| --- | --- |
+| 一个 block 负责什么 | 是一段元素、若干行、矩阵子块，还是某个输出的部分贡献；不同 block 的起点和长度怎样计算 |
+| 一轮 tile 处理什么 | 本轮起点、有效长度、循环步长；最后一轮是否走不同分支 |
+| 一个局部元素对应哪里 | 从逻辑坐标推导输入和输出偏移，区分元素数、字节数、stride 与实际 API 参数单位 |
+| 补齐部分怎样处理 | 分配容量、搬运长度、计算范围和写回范围分别是多少；padding 是否参与了计算 |
+
+选一个失败坐标，反推它属于哪个 block、哪轮 tile、哪个局部位置，再沿源码算回输入和输出地址。归约或矩阵乘还要追到全部贡献的合并位置；广播则分别推导各输入的坐标，不能把输出偏移直接套到所有输入。
+
+这里的 block 和 tile 是分块层次，不意味着算子使用 SIMT。只有当前执行段确实使用 SIMT 时，才继续根据线程索引和循环步长分析各线程读写的数据。
+
+## 4. 把计算链对应到执行与存储
+
+从输入沿数据流读到最终输出，写出真实操作，不能只列 `CopyIn → Compute → CopyOut` 三个函数名。
+
+- **搬入**：从哪个地址、搬多少数据、放入哪个缓冲；布局或有效范围有没有变化。
+- **计算**：按实际顺序写出运算、Cast、归约和分支，标明关键中间值及累加 dtype。循环中的状态要说明在哪里初始化、跨轮保留什么。
+- **交接与复用**：谁写、谁读、读取前怎样保证就绪、何时允许复用。代码用了队列、事件或其他同步，就把对应操作连到这条数据依赖上。
+- **写回**：最终取哪个缓冲、写到哪个输出坐标、写多少；存在 workspace 中转或后续 Kernel 时，继续追到最终结果。
+
+使用寄存器矢量计算时，展开相关的 Load、运算和 Store；调用高阶 API 时，先把它作为有明确输入输出的节点。只有内部行为影响当前判断时才继续展开。不同变量可能指向同一存储，源码先后顺序也不能单独证明异步操作已完成；先把实际地址、读写顺序和同步操作标在链上，未能解释的交接关系留作后续检查点。
+
+遇到不了解的 Ascend C 算子特性或接口语义时，带着具体问题使用 `ascendc-api-knowledge-query` 查询，例如当前 DataCopy 重载的 stride 单位，或归约接口的输出布局。采用最新资料，并核对它是否适用于当前 CANN 和产品；查到的结论落回对应代码，无法确认的地方注明。无需为了读懂普通算子，先泛读 SIMT 或架构指引。
+
+## 从输出类型建立局部比较链
+
+本节只在需要比较中间结果时使用。先明确这个量代表什么：搬运和重排看值与坐标映射；整数计算看精确语义；浮点计算要匹配该点的输入、dtype 和已确认的计算方式；量化要包含 scale、舍入和饱和，随机输出按项目的分布或序列要求比较。
+
+最终输出的 golden 或容差不能直接套到所有中间点，局部对照也不替换最终验收。只有准备构造浮点中间值参考、但不清楚怎样处理 dtype、累加或舍入时，再读[局部算术模型](numerical-modeling.md#局部算术模型)；进入定位阶段，需要采集中间数据、但无法确定采集位置或比较对象时，再读[观察点设计](checkpoint-design.md)。
+
+## 完成后的检查
+
+将与当前问题有关的公式、实际分支、分块索引和计算链写入报告第 3 节“相关计算链与数值约定”，标上对应的函数或关键表达式；已有说明可引用。用一个输出元素沿链走一遍，检查能否回答：
+
+1. 它依赖哪些输入，实际执行了哪些运算？
+2. 数据在哪轮产生，经过哪些缓冲，最终由谁写到哪里？
+3. 哪些信息已从代码或运行结果确认，哪些仍有疑问？
+
+能解释这条链后，继续按[计算链敏感点](sensitive-points.md)标记可能出错的位置，再进入阶段 3 验证。建模本身不代表已经确认根因。
+
+## 示例：读懂一个按行求和的算子
+
+下面用一个假设实现说明读法，不是可直接编译的 Kernel，也不是某个 API 的固定实现。
+
+**算子定义**：输入 `x[M,N]` 连续存储，输出 `y[M]`，每个输出是对应一行的和。输入输出为 FP16。假设当前代码每个 block 处理一行，每行按 `T` 个元素分块，先转 FP32，在块内和块间求和，最后转回 FP16。
+
+```text
+数学定义：y[r] = sum(x[r,c], c=0..N-1)
+本次参数：M=2，N=5，T=3，启动 2 个 block
+输入：x = [[1, 2, 3, 4, 5],
+           [6, 7, 8, 9, 10]]
+预期输出：y = [15, 40]
+```
+
+**先对上分块和地址**：block `r` 负责第 `r` 行；第 `t` 轮从列 `t*T` 开始，有效长度为 `min(T, N-t*T)`。输入元素偏移是 `r*N+t*T`，输出元素偏移是 `r`。
+
+| 执行位置 | 输入起始偏移 | 有效输入 | 本块和 |
+| --- | --- | --- | --- |
+| block 0，第 0 轮 | 0 | 1、2、3 | 6 |
+| block 0，第 1 轮 | 3 | 4、5 | 9 |
+| block 1，第 0 轮 | 5 | 6、7、8 | 21 |
+| block 1，第 1 轮 | 8 | 9、10 | 19 |
+
+**再画实际计算链**：
+
+```text
+每行开始：s = 0（FP32）
+    ↓
+本轮有效输入（GM，FP16）→ 搬入局部缓冲 → Cast 为 FP32
+    → 块内求和 partial → s = s + partial
+    → 还有下一块则继续，s 跨轮保留
+    ↓
+该行全部块完成 → s 转为 FP16 → 写入 y[r]
+```
+
+回到真实源码，在搬入到计算、计算到缓冲复用的连接处标出实际队列或同步操作。如果搬运包含补齐元素，确认它们不会改变本块的和。
+
+这时就能提出具体检查：`s` 是否错误地在每个 tile 开始时清零，第二轮是否仍按 3 个有效元素求和，block 1 是否从输入偏移 5 开始，输出是否写到 `y[1]`。这些是从定义和代码关系得到的候选，需要结合真实代码和结果验证，不能仅凭示例认定有错。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/diagnosis/progressive-error-analysis.md

@@ -0,0 +1,86 @@
+# 逐层误差传播分析
+
+需要判断当前差异是本阶段新增，还是上游差异传入、放大或抵消时使用。先选与失败有关的阶段，不要求采集全链，也不要求事先已经知道误差怎样传播。
+
+`PASS → PASS → FAIL → FAIL` 同样可能来自容差内微差被归约放大。二分帮助缩小超差区间，本页帮助解释区间内外的差异来源，可以配合使用；只有 PASS/FAIL 标签时，先补相关实际值与局部参考。
+
+## 目录
+
+- [选择相关阶段与参考](#选择相关阶段与参考)
+- [整理已有误差](#整理已有误差)
+- [区分传播与新增偏差](#区分传播与新增偏差)
+- [解释尺度与形态变化](#解释尺度与形态变化)
+- [根据结果继续定位](#根据结果继续定位)
+
+## 选择相关阶段与参考
+
+沿失败输出的实际数据依赖选择相关阶段，优先复用已有输出和比较报告。核对输入、执行路径、轮次与有效区；Reduce、broadcast 或布局变化前后，按输入输出映射关联数据及完整依赖范围，不套用相同数字索引。具体见[观察点设计](checkpoint-design.md#对应到本次执行的数据)。
+
+每个阶段使用匹配其公式、dtype、Cast、累加方式和必要求值顺序的局部参考与判据，见[局部对照](checkpoint-design.md#准备局部对照)。最终 golden 和容差不能直接套到所有中间量。缺最终 golden 时，可以依据已确认定义构造并核对独立局部参考；只有不变量时，结论限于该性质，不能据此排除整段计算。
+
+固定输入下出现漂移时，按[复现性方法](reproducibility.md#判断稳定性)核对执行实例与采集条件，避免把不同轮次的变化拼成传播趋势。参考不适用、数据不可比或采集不完整时保留 `AMBIGUOUS`，补相应缺口；已有有效观察继续保留。
+
+## 整理已有误差
+
+按相关依赖链整理已有比较结果，保留参考依据和有效范围。根据疑点记录绝对误差、适用的相对误差、超差比例、特殊值、错误坐标和符号，缺指标注明，不要求全链采集。分开观察：
+
+- 首个已观察到差异的点；
+- 首个按该点判据验收失败的点；
+- 幅度、符号、特殊值或错误位置发生变化的区间。
+
+首次观察到差异不等于首次产生差异，未测区间内部仍未知。首次超差也可能只是更早的误差被放大。相邻最大误差的差值或倍率不能代表本段新增偏差，误差可能换位置或相互抵消；不据此给各阶段排最终贡献大小。
+
+汇总已有报告中的误差变化、首次测得非零绝对误差及首次验收失败，位差可能没有非零绝对误差。没有指标或尚未测量的点保留缺口；表中相邻观测可能跨越未测阶段，不能据此认定它们在计算链中直接相邻，也不能仅凭趋势判定根因。
+
+## 区分传播与新增偏差
+
+需要判断偏差是否由本阶段引入时，准备可信的独立局部参考 `R`，按当前缺口取得以下对象。多输入、影响计算的属性和必要状态都应纳入参考，不能只重放其中一个输入。
+
+| 对象 | 如何取得 |
+| --- | --- |
+| `actual` | 本阶段真实观察到的输出 |
+| `R(x_obs)` | 将本阶段实际输入 `x_obs` 送入独立局部参考 |
+| `R(x_ref)` | 可信参考输入 `x_ref` 经同一局部参考的输出；已有等价的阶段参考可复用 |
+
+这两项比较回答不同问题，不能相互替代：
+
+1. **本段局部残差：比较 `actual` 与 `R(x_obs)`**。按该点适用的判据检查本段是否还有未解释的偏差，保留可获得的原值和差异。局部 PASS 只说明该判据通过，不代表差值为零，也不证明本段完全正确。
+2. **输入传播：比较 `R(x_obs)` 与 `R(x_ref)`**。需要判断上游输入差异时，取得这项比较的结果，将幅度、位置和类别与原输出差异核对；再检查第 1 项的局部残差是否仍影响这一解释。只在对照支持的范围内说明输入传播解释了什么，缺少该比较就保留来源未知。
+
+| 已取得的结果 | 可以怎样判断与继续 |
+| --- | --- |
+| `actual` 与 `R(x_obs)` 在局部判据下相符，但未比较 `R(x_obs)` 与 `R(x_ref)` | 本段在当前输入及判据下局部相符；不能写成“无新增偏差”或“全部来自上游”。下一项是补可信输入对照，不由第一项直接转成传播结论 |
+| 两项比较均已取得，输入变化经 `R` 后能对应原差异，局部残差也已核对 | 说明输入传播可以解释的具体部分与剩余缺口，再据已支持的输入差异回查上游；不把“已列三对象”代替这些条件 |
+| `actual` 仍偏离 `R(x_obs)` | 保留本段未解释的差异，核对计算、读取、状态及有效区；上游已有差异也不能排除本段同时有问题 |
+
+只有 `actual` 和 `R(x_obs)` 时，仍可检查本段局部差异，但不能由这两项得出输入偏差的传播量。近似比较也不能按相等关系传递：两个局部差异各自未超阈，叠加后仍可能导致原输出失败。缺实际阶段输入或适用参考时，说明尚不能区分的部分；保留已有数值或不变量观察，不把拟合 actual 的模型当作独立依据。
+
+尤其区分候选模型 `M` 与已确认语义的独立参考 `R`：`actual ≈ M(x_obs)` 只表示候选预测吻合，不能据此判为上游传播。一个反例是本段定义 `R(x)=x`，候选模型 `M(x)=2x`，实际输入与可信参考输入均为 `1`，实际输出为 `2`；候选完全吻合，但输入没有偏差，本段仍偏离独立参考。即使 `actual ≈ R(x_obs)`，也还需用 `R(x_ref)` 检查输入差异能否解释当前现象，再据此回查上游。
+
+例如本段定义为 `y = 16x`，可信输入为 `1`，实际输入为 `17/16`，则 `R(x_ref) = 16`、`R(x_obs) = 17`：
+
+| 实际输出 | 本例的局部差值 `actual - R(x_obs)` | 下一步 |
+| --- | --- | --- |
+| `17` | `0` | 输出差异可由输入传播解释，回查上游为何偏离 |
+| `21` | `4` | 输入传播只能解释差异 `1`，继续调查本段剩余差异 `4` |
+
+本例数值和运算在 float32 下可精确表示。一般浮点运算仍按已确认的舍入方式和局部判据比较，不套用精确相等要求。局部对照通过只覆盖当前输入和所选判据，不能证明上游或后续阶段正确。
+
+## 解释尺度与形态变化
+
+比较幅度时，保留原始误差，必要时再按有语义依据的阶段尺度归一，例如可信参考的范数或任务明确的动态范围。事先确定尺度的定义与计算范围；归一用于解释差异，不替换原验收阈值。不同语义阶段没有可比尺度时，不把归一数硬排成贡献大小。
+
+某个参考元素为零，不代表整个阶段没有可用尺度。例如参考为 `[0, 1]` 时，第一个元素不能用自身参考值作相对误差分母，但参考的无穷范数仍为 `1`。只有所选尺度为零、不可用或缺少语义依据时，才将该归一结果保留为未知；继续观察绝对误差和特殊值类别，不临时加 epsilon 改变排序。
+
+形态变化先按本段正常公式和坐标映射解释。正确的逐元素乘法，也能把全域微差变成仅在非零权重位置出现的差异；归约和布局变化同样会改变误差分布。因此尾部周期、符号或特殊值变化只是线索，形态不变也不能排除新增偏差。结合局部重放和源码，选择能区分当前解释的观察，不固定“形态变化优先、幅度其次”的顺序。
+
+## 根据结果继续定位
+
+| 有效观察或缺口 | 下一步 |
+| --- | --- |
+| 局部重放符合实际输出，输入差异可解释后续现象 | 回查上游差异来源；各段均符合局部语义而最终仍失败时，检查整个算法的累加精度、运算顺序和数值稳定性 |
+| 实际输出仍偏离基于实际输入的局部参考 | 确认比较与采集有效后，调查本段计算、实际读取、状态、有效区和数据依赖，形成具体候选 |
+| 误差在后段减小、消失或重新出现 | 检查抵消、截断、掩码或放大是否能解释变化，不能用后段通过回填前段正确 |
+| 缺适用参考、实际阶段输入或可比观察 | 补最能区分当前疑点的一项，或继续不依赖该缺口的分析；不把未知点作为正常边界 |
+
+有具体候选后，按[假设与实验](hypothesis-experiment.md#实验设计)检验预测并核对实际联动。需要继续缩区时，按[语义二分前提](semantic-bisection.md#前置条件)核对端点的可比性和稳定性；找一处判定转变不要求整段单调，但排除更早异常等更强结论需另有依据，一次误差跳变不足以证明未测区间单调。记录已解释的差异、尚未区分的部分和下一项检查，证据足够时收口，不为完成全链排名继续采样。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/diagnosis/reporting.md

@@ -0,0 +1,140 @@
+# 诊断与修复报告
+
+本文件将[六阶段调试流程](../../SKILL.md#六阶段调试流程)的产物整理成报告。阶段目标、推进与回退条件以 `SKILL.md` 为准。
+
+## 任务产物目录
+
+开始定位或修复时，在允许写入的范围内选定一个任务产物根目录 `<artifact-dir>`，并告知用户：
+
+1. 使用用户或任务环境指定的产物目录；只指定报告文件时，以其所在目录为根目录并保留文件名。
+2. 未指定时，复用本次任务已有的产物目录；只有报告或笔记文件时，使用其所在目录。
+3. 都没有时，使用 `<被调试工程>/.precision-debug/<任务标识>/`。
+
+默认路径以当前算子工程根目录为基准。任务标识优先沿用已有任务或 case ID，否则选择简短且不冲突的名称。同一任务续接沿用原目录，新任务避免覆盖旧产物。
+
+本次新建的报告、日志及元数据、探测和比较结果、观察点记录、输入输出样本、dump 与解析文件、实验脚本、临时配置、源码快照、补丁及可独立配置的构建输出，统一放在该目录或其子目录。按需创建子目录，每轮实验使用新文件名或子目录，保留已有证据。
+
+报告默认使用 `<artifact-dir>/report.md`，用户指定位置时按其要求。草稿与最终报告使用同一文件，阶段 6 整理后提供目录及报告链接；本地证据优先使用相对链接。知识问答或仅在对话中交付时不创建报告文件，需要保存的运行产物仍使用同一目录规则。
+
+已有源码、配置、输入和历史证据保持原位引用，正式源码仍在工程中修改。外部工具只能在固定位置输出时，将本轮需留存的结果收集到产物目录并注明原始位置；工具内部自动清理的临时文件无需归档。
+
+## 使用原则
+
+- **按任务裁剪。** 定位任务交付已有边界、依据和未决项，不为填模板实施修复。知识问答仅保留结论、依据和必要的命中摘要，不生成阶段报告或运行状态。用户指定格式时，按其格式保留关键事实。
+- **随阶段进展更新。** 关键结果在任务进行中随手写入报告对应部分（仅在对话交付时随阶段进展说明），结论以支撑当前判断和后续工作为限，不需要反复整理全文。允许复用、跳过和回退，不为填满报告补做步骤，不另建阶段台账；阶段 6 汇总时清理已被后续结果替代的旧状态。
+- **事实与版本对应。** 修改取自实际 diff，测试数量与结果取自执行记录。基线和定位证据对应当时版本；支持最终修复结论的验证证据，必须对应最后一次相关修改后的源码、实际运行的产物和验收口径，不能只凭时间先后判断有效。
+- **保留摘要与关键缺口。** 只记录影响判断、验证或复核的内容，关键失败与反证不能省略。删除无关字段、空表和填写提示；没有实际检查、修改或验证时说明原因，影响结论的未知项明确保留。详细内容引用源码位置、工程相对路径或执行记录，不粘贴完整日志、代码、Tensor 或敏感信息。
+- **核对实际交付。** 按选定位置保存报告并在回复中给出产物目录及报告链接。交付前核对结论、diff、实际结果和引用相符，未生成的报告、补丁或证据产物明确说明。
+
+## 阶段与报告对应
+
+以下七节承接各阶段产物，按下表随阶段进展填写，结论放在开头；按实际工作保留相关小节，无需提前展开尚未开展阶段的章节。章节号与调试阶段号分别标注。
+
+| 调试阶段 | 报告位置与产物 |
+| --- | --- |
+| 1. 复现问题、确认基线 | 第 2 节：原始问题与可信基线 |
+| 2. 理解算子与计算链 | 第 3 节：相关计算链与数值约定 |
+| 3. 定位问题与验证根因 | 第 4 节：候选依据与低成本验证、必要时转入系统定位的原因及观察、根因判断 |
+| 4. 实施最小修复 | 第 5.1 节：实际修改、语义与影响范围、诊断探针恢复情况 |
+| 5. 原失败回放与必要回归 | 第 5.2 节：最终执行对象、实际验证结果与覆盖范围 |
+| 6. 报告与交付 | 汇总第 1、6、7 节，核对第 2—5 节的适用内容与实际交付物，按任务约定交付 |
+
+只定位的任务从阶段 3 进入阶段 6，修复与回归小节按实际情况裁剪。阻塞或预算结束也可交付当前报告，保留原阶段的必要缺口；进入阶段 6 不表示定位或修复已经完成。
+
+## 可复制模板
+
+按实际任务填写。各节记录阶段产物，而非逐步操作经过；同一证据只展开一次，其他位置引用即可。
+
+```markdown
+# 精度诊断报告
+
+## 1. 任务与结论
+
+- 任务目标：涉及的算子、问题及本次定位或修复范围。
+- 根因或当前判断：已确认 / 待验证 / 未定位；概括原因与异常之间的联系。
+- 处置情况：实际修改及完成情况，区分正式修改、诊断性绕过和未修改。
+- 验证结论：实际通过、失败或未验证的范围，以及对任务完成情况的影响。
+- 流程说明（有则填写）：影响判断或覆盖的阶段复用、跳过、回退及其依据。
+- 交付物：任务产物目录、本次报告及要求的补丁、关键结果位置；要求但尚未生成的列入未完成项。
+
+分别说明根因、修改和验证结果。原失败未解决，或项目要求及支撑本次修复的关键验证未完成时，注明“修复未完成”；额外未验证范围作为限制说明。只定位任务按定位结论交付。
+
+## 2. 原始问题与可信基线（阶段 1）
+
+- 环境与执行对象：必要的 CANN、设备、执行方式及配置，基线源码与实际产物的关联标识。
+- 输入与触发条件：张量形状、计算轴、数据类型、相关数值范围或边界，以及固定输入或可复验的生成方式。
+- 原始异常：预期与实际差异、代表性误差指标或分布；多输出时明确失败项及组合判定。
+- 验收依据：所选标准与参考结果的来源、实际比较器及完整通过条件；有填充或无效位置时说明参与范围。区分正式验收与辅助逐点诊断，判定规则有修正时说明依据。
+- 复现入口与结果：关键命令或用例入口、复现状态及证据位置；状态按实际填写为稳定复现 / 偶发或漂移 / 当前未复现 / 无法运行。
+
+## 3. 相关计算链与数值约定（阶段 2）
+
+仅描述与本次异常、判断或修改有关的部分，不展开整个算子的设计说明。
+
+- 相关计算链：输入、关键计算或搬运阶段、输出，以及本次关注的敏感点。
+- 实际执行路径：本次采用的 dtype、宏、快慢路径或 tiling 分支；未确认采用的注明。
+- 必须保持的约定：需求来源及相关输出、舍入、特殊值等功能与数值语义。比较参数引用“原始问题与可信基线”，不重复抄写；必要但未核实的约定列入未完成项。
+
+## 4. 关键定位证据（阶段 3）
+
+记录初筛候选如何来自计算链、敏感点、自身知识或沉淀经验，以及关键验证结果。转入系统定位时，说明初筛未解决什么问题、为何选择后续方法、新观察怎样改变判断；直接确认根因时保留对应依据，不补写未执行的步骤。
+
+通过计算关系检验候选时，保留预测与实际差异的比较。同一证据只展开一次，短任务可用简短文字代替表格；没有实际检查或实验时说明原因，不保留空表。
+
+实验的判别预期按执行前记录填写，未留存时注明，不事后补造；源码检查等非干预性观察不强填预测。单次有效比较的 PASS/FAIL、重复观察的稳定性和插桩影响分别说明；一次对照通过不抹去已观察到的失败，受扰动结果注明适用范围。
+
+| 定位问题或候选及依据 | 所用方法、关键检查/实验与判别预期 | 实际结果与证据 | 判断、转向及适用边界 |
+| --- | --- | --- | --- |
+
+- 定位结论与范围：已确认根因时，说明具体代码位置、触发条件及其造成原始异常的机制，并引用实际路径与相应证据。代码位置可以是一段实现或缺失操作的所在环节；只支持可疑区间、时序相关或外部现象时，按该范围表述，保留根因未确认的状态。首次可见异常不自动等于根因。
+
+无效或无区分力的实验结果不能写成支持或排除某个原因的因果证据。仍能解释关键观察的竞争候选列入未完成项，不罗列从未影响判断的猜测。
+
+## 5. 正式修复与验证
+
+只定位的任务注明“未实施正式修复”，其余字段按实际裁剪；有临时诊断改动时仍说明恢复情况。
+
+### 5.1 正式修复（阶段 4）
+
+- 正式修改：文件或函数位置、实际改动要点及针对的错误机制；绕过与修复明确区分。
+- 语义与影响范围：相关约定是否保持，受影响的输出、共享实现和独立路径。
+- 临时诊断改动：未引入 / 已清理 / 有保留；有保留时说明内容与原因。
+
+### 5.2 回放与回归（阶段 5）
+
+- 最终执行对象：用于交付和验证的源码及产物标识。
+
+验证表仅列实际执行项，分别说明原失败回放和必要回归的范围；有用例统计时写明实际通过数/总数，必要时补充误差指标。偶发失败及重跑分别说明，不只报告最后一次通过；多处一起修改后只做组合回放，就写组合验证。
+
+结果沿用基线确认的标准与实际 evaluator 判据，辅助指标不覆盖验收结论，数值误差为零不自动等于位模式一致。原失败、相关回归或关键验证有缺口时，说明对本次修复结论的影响；后续修改影响的旧结果需补验对应部分。
+
+| 验证项与覆盖范围 | 实际结果 | 证据位置 |
+| --- | --- | --- |
+
+## 6. 未完成项与残余风险（有则填写）
+
+只记录影响本次结论或使用范围的具体事项，并区分：
+
+- 未完成项：本次待解决的异常、影响当前判断的竞争解释、项目要求或支撑本次修复的关键验证缺口。
+- 残余风险：已验证范围之外的具体风险或适用限制。额外范围未验证，不自动否定已验证的结果。
+
+每项说明事实、影响范围及必要时的最小确认动作。未解决的原始问题与必要验证缺口不能改写成残余风险。不罗列通用风险或无关优化建议；无相关事项时删除本节。
+
+## 7. 知识与工具命中
+
+仅列对判断、修改、验证有实际作用，或造成关键阻塞的项目。未采用的内容只在解释关键取舍或知识、工具缺口时保留；重复使用合并记录，不要求统计调用次数。未列出不代表未使用，无相关条目时写“无关键命中”；记录不足时说明具体缺失，不推测使用情况。
+
+### 知识
+
+内部知识用相对 Skill 根目录的路径和实际阅读的章节标识；外部资料注明来源，影响适用性时注明版本。仅见检索片段时注明；只在索引中见到文件名不算读过该文件，列出引用也不等于实际采用。实际作用关联本报告中的检查、实验或修改，不只写“参考了”“帮助定位”。
+
+| 知识来源与章节 | 对应阶段及实际作用或关键未采用原因 | 关联检查、实验或修改 |
+| --- | --- | --- |
+
+### 工具
+
+工程工具或本次分析脚本使用相对工程或产物目录的路径；官方工具与标准函数注明名称和来源，实际采用的标准及配置引用第 2 节。常规浏览、编辑、搜索及仅查看帮助不单独登记。区分工具运行状态、原验收结果与辅助诊断指标：有效发现失配不等于工具执行失败，正常退出也不等于精度通过。结果未采信、启动失败或超时仅在影响判断时记录，并说明实际影响。
+
+| 工具名称或路径 | 对应阶段、执行情况及实际作用或未采信原因 | 关键产物或证据 |
+| --- | --- | --- |
+```

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/diagnosis/reproducibility.md

@@ -0,0 +1,121 @@
+# 复现同一个失败
+
+需要复现原失败、确认新产物采用或解释结果漂移时使用。比较双方与判据先按[比较与验收](baseline.md)核对；本页帮助保存可回放现场、解释本轮结果并选择下一步。
+
+## 目录
+
+- [冻结失败现场](#冻结失败现场)
+- [核对环境与实际产物](#核对环境与实际产物)
+- [核对真实退出码](#核对真实退出码)
+- [记录复现结果](#记录复现结果)
+- [判断稳定性](#判断稳定性)
+- [探测失败不回退典型值](#探测失败不回退典型值)
+- [执行停滞与证据保存](#执行停滞与证据保存)
+
+## 冻结失败现场
+
+先保存能重放原失败的信息，已有可信记录直接引用；其余字段按当前疑点补充，缺项注明。
+
+| 对象 | 需要保留什么 |
+| --- | --- |
+| 输入与属性 | 实际输入文件，或已确认可复验的生成器、参数和种子；shape/axis/dtype/layout、有效范围及相关属性 |
+| 比较依据 | actual/golden、实际比较器和验收规则，逐输出及组合判定 |
+| 源码与构建 | 源码版本、相关改动、实际参与的 Host/Kernel/tiling 源码、构建目标和产物位置 |
+| 环境与路径 | 本次 CANN/编译器、设备、调用方式与实际分派；必要时补 driver/firmware、SoC/NPU Arch、tiling key、核数和关键宏 |
+| 执行与观察 | 命令、工作目录、完整日志、退出状态、可获得的错值/位置/误差，以及输入输出文件的位置 |
+
+调用方式与编程形态分别说明，例如 Kernel 直调不表示采用 RegBase 或 SIMT。仅连续调用才失败时，还要保留调用顺序和状态复用条件；同一随机种子不自动保证实际输入相同。
+
+关键事实写入[任务报告](reporting.md)，新建日志、输入快照与观察结果放在[任务产物目录](reporting.md#任务产物目录)。保留原输入和验收方式，诊断插桩、探索输入及修改后验证分别标识；输入、有效区或判据变化时说明差异。
+
+## 核对环境与实际产物
+
+重编后结果不变、切换构建配置或怀疑加载旧产物时，按缺口沿下列链路检查：
+
+| 环节 | 具体检查 |
+| --- | --- |
+| 源码 → 构建 | 核对本次构建目标、实际源码和编译选项，从构建日志找到生成的目标文件 |
+| 构建 → 加载 | 沿运行命令、工程加载配置和可获得的加载记录确认目标路径，结合实际分派或可区分行为核对本次执行的 Kernel/分支 |
+| 执行 → 输出 | 保存旧结果，使用新输出路径或确认工程已刷新输出，再核对比较器读取的是本轮对应文件 |
+
+版本从本次实际使用的 CANN/编译器根目录取得，构建目标与运行设备分别记录。编译成功、文件摘要改变或输出时间较新，都不能单独证明新 Kernel 被执行。执行记录中的命令或文件身份也不能单独证明框架动态加载了某个 NPU Kernel。
+
+### 排除旧构建、缓存与输出残留
+
+先保留原始输入、失败输出和日志，再按工程配置确认构建目录、相关缓存及加载路径。优先用独立构建/输出目录对照；确需清理时，仅处理已确认、可重建且属于本次任务的缓存，不套用固定机器路径。重建后仍需核对实际加载和输出刷新，结果不变也可能是输入对改动不敏感。
+
+怀疑进程持有旧模块或状态时，可用新进程对照；原问题依赖连续调用时，仍需保留原调用历史。清理或重启后通过不能代替原条件验证，相关线索见 [Host 属性与构建采用](../patterns/mechanisms/golden-host-contract.md)。设备 DCache 可见性另按[同步与可见性](../patterns/mechanisms/pipeline-sync-visibility.md)调查。
+
+## 核对真实退出码
+
+优先直接执行被测命令，每轮使用新日志路径，保留完整日志与真实退出状态。使用重定向保存日志时，在命令结束后立即保存退出码；返回 0 不等于精度通过，数值判定看本轮有效 evaluator。
+
+确需管道时，`pipefail` 可防止前端失败被末端成功掩盖，但它返回最右侧非零状态，不代替各环节退出码。例如前端返回 7、日志端返回 3 时，管道返回 3。以下为 **Bash 外部命令**示例，在子 shell 内先关闭遇错即退，保证失败后仍能保存状态：
+
+```bash
+(
+  set +e
+  set -o pipefail
+  <command> <arg> ... 2>&1 | tee "<artifact-dir>/pipeline.log"
+  run_codes=( "$?" "${PIPESTATUS[@]}" )
+  printf 'pipeline=%s command=%s tee=%s\n' "${run_codes[@]}"
+  exit "${run_codes[0]}"
+)
+```
+
+保存数组必须紧接管道，前面不要插入 `rc=$?`、日志展示或其他命令。Zsh 使用 `pipestatus`，保存语句为 `run_codes=( "$?" "${pipestatus[@]}" )`；默认数组从 1 开始，汇总状态取 `run_codes[1]`，不能照抄 Bash 下标。
+
+嵌套脚本仍需核对内部退出状态是否被覆盖；外层调用不能恢复脚本已经丢失的失败状态。只有历史日志而无可靠退出状态时，保留执行结果未知，条件允许再回放，不凭日志中是否出现 `FAIL` 推断。
+
+## 记录复现结果
+
+分别说明本轮执行结果、数值判定与原问题是否复现，用简短记录即可：
+
+| 当前观察 | 记录与下一步 |
+| --- | --- |
+| 在可比原条件下，有效比较再次观察到原精度失败 | 保留实际 FAIL，可记为 `REPRODUCED`，沿相关计算链继续定位 |
+| 针对原失败的回放有效比较通过，未观察到原异常 | 保留实际 PASS；未修改基线的回放可记为 `NOT_REPRODUCED`，核对历史与当前条件差异 |
+| 构建/执行失败、输出陈旧或没有有效比较 | 记录具体执行结果与缺口；未取得有效比较的部分保持未知，不记作数值 PASS 或已复现精度失败 |
+| 当前无法重放，只能使用历史证据 | 可记为 `EVIDENCE_ONLY`，说明缺失材料或条件，继续有边界的源码或历史数据分析 |
+
+例如：`本轮 evaluator 为 PASS；原问题本次未复现；缺少可比的修复前后证据，尚不能确认修复。` 有效的修改后 PASS 仍应如实报告；修复结论另按[原失败回放与必要回归](../../SKILL.md#阶段-5原失败回放与必要回归仅修复任务)核对，不能因一次通过就覆盖历史失败。
+
+当前未复现时，先比较历史与当前的输入、源码/产物、环境、命令、调用历史、tiling/核数和验收器。缺失材料注明其影响，后续观察追加保留；插桩或其他诊断改动的结果不替代原程序基线。
+
+## 判断稳定性
+
+在同一输入、产物和比较口径下重复观察，记录本批有效轮数、通过/失败数，按疑点保留错误位置、误差与输出摘要；少量展示点不能代表完整错误位置集合。无效轮次另记，不混入通过/失败计数。分类只覆盖本批样本及实际观察字段，不自动证明输出逐位稳定、内部边界稳定或根因。
+
+| 当前观察 | 下一步 |
+| --- | --- |
+| 相同位置持续失配 | 选已有代表性错值或坐标核对公式、索引和数据来源；阶段未知时按[观察点设计](checkpoint-design.md)补观察 |
+| 错误位置随轮次变化 | 对齐执行实例与调用历史，比较变化范围，再调查初始化、所有权、覆盖或同步；不要求先找到共同正常区 |
+| 位置相同而误差幅度变化 | 比较已记录数值、状态复用和运算顺序，不直接认定为低精度或随机噪声 |
+| 有时失败、有时通过 | 保留两类样本和出现条件，按疑点交错未修改对照；暂时找不到稳定触发条件也可继续调查 |
+| 全部失败但缺位置或误差信息 | 只说明本批全失败，按当前疑点补定位信息，不推定稳定失配 |
+| 本批有效比较均通过 | 保留 PASS 和未复现范围；有历史失败时继续核对条件差异 |
+| 存在执行、刷新或比较无效的轮次 | 先补具体缺口，保留其他有效观察，不用无效轮次推断稳定性 |
+
+诊断采样前明确下一轮能区分什么；重复运行不再推进判断时，换观察点或验证具体候选。项目要求的重复验收另按原方案完成，无法完成就报告缺口；不能因分类不再变化提前结束，也不反复运行直到得到一次通过。改变 shape、核数、分片或调用顺序属于新的诊断对照，按[实验设计](hypothesis-experiment.md#实验设计)核对实际联动。
+
+数值失败也可能按工程约定返回非零退出码，需要结合本轮有效验收报告与执行日志解释；不要把它与崩溃、超时或旧输出混为一类。随机语义输出按[随机输出验证](baseline.md#随机输出边际分布与序列要求分开验证)检查，不仅凭输出摘要变化判错。
+
+## 探测失败不回退典型值
+
+核数、容量、架构或执行形态不明时，保留查询入口、参数、退出码、原始返回值及本次 CANN 根目录，说明信息来自 Host、Kernel、构建配置还是设备运行端。产品/架构映射和资源含义使用 `knowledge-query` 查询，具体 API 及失败返回语义使用 `ascendc-api-knowledge-query` 核对。
+
+交叉验证按冲突或疑点选择，先确认两种入口是否观察同一对象。例如 Host 配置与 `GetBlockNum()` 可核对本次逻辑 block 数，不能由此推定设备物理核数；构建目标信息也不等于当前设备实测。已有适用的可靠来源时，不要求每个字段都做双入口核验。
+
+无法确认的字段保留 `UNKNOWN`，不拿典型配置、示例数字或另一设备/安装的结果兜底。`0` 按具体 API 的已确认语义解释；语义未知时，不擅自当作真实容量或“不支持”。缺值影响当前判断时，补来源或改做不依赖该值的检查，不把猜测写入 tiling。
+
+## 执行停滞与证据保存
+
+复现、定位实验与回归均保留完整日志和真实退出状态，保存方法见[核对真实退出码](#核对真实退出码)。长任务在启动前安排独立后台运行，并按工程已有方式设置合理的超时；结束后核对本次任务的进程是否已收尾。
+
+命令超出本环境已观察到的合理耗时而无新结果时：
+
+1. **确认卡在哪一段**：查看完整日志、最近进展和本次进程状态，区分未启动、构建、输入生成、设备执行与比较；无输出也可能只是日志缓冲。
+2. **保留现场并决定是否停止**：保存已有日志，结合当前进展与预算决定是否停止；需要手动停止时，只处理确认属于本次任务的进程。
+3. **确认上一轮状态再继续**：仍有本次任务的活动进程时先处理，避免与新一轮重叠。根据已知停滞环节调整下一次检查，不只是延长超时或重复整套运行；缩减样本时保留它与原触发条件的关系。
+
+超时不等于数值失败；未取得有效比较的部分保持未知。下一实验的安排与转向条件见[阶段 3](../../SKILL.md#阶段-3定位问题与验证根因)，本轮结果与未完成范围按[报告指引](reporting.md)交付。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/diagnosis/semantic-bisection.md

@@ -0,0 +1,72 @@
+# 语义二分定位
+
+同一依赖链上已有可比、稳定的 PASS/FAIL 端点时，可用二分减少中间观察，缩出一处当前判据的正常→异常转变。这个目标不要求整段单调，也不保证找到最早或唯一转变；缩区本身不证明其他代码正确。
+
+## 目录
+
+- [前置条件](#前置条件)
+- [执行](#执行)
+- [多轮记录](#多轮记录)
+- [退出和降级](#退出和降级)
+
+## 前置条件
+
+先确定本轮要搜索的判定边界，再核对：
+
+- **数据依赖对应**：按失败输出的真实生产者→消费者关系排列观察点，关联同一输入、相关逻辑数据、分片/轮次和观察面。多分支汇合时核对相关输入与共享状态，不能用一条支路 PASS 代表全部上游正常；具体见[观察点设计](checkpoint-design.md#选择位置)。
+- **判定可比**：参与缩区判断的点有适用的独立参考和判据。搜索累计差异时，各点使用同一原始输入推导的阶段参考；基于实际阶段输入的局部重放只检查本段，不能混成累计正常端点。不变量通过也只覆盖该性质，参考选择见[局部对照](checkpoint-design.md#准备局部对照)。
+- **观察有效且边界稳定**：已有可信 PASS 前端和 FAIL 后端，复用适用的重复观察。有漂移迹象时先按[复现性方法](reproducibility.md#判断稳定性)核对；单次有效 FAIL 仍保留，但不证明边界稳定。`AMBIGUOUS`、不可比或已知受扰动而不能代表当前目标的点不作端点。
+- **明确缩区能说明什么**：只找一处 PASS→FAIL 转变时，保留异类端点即可继续缩区。若要用中点 PASS 排除其前段的 FAIL，或认定最早、唯一转变，需结合计算和判据取得额外依据，例如有依据的局部单调假设或已验证的前段。重复稳定、已测点没有倒序，均不能证明未测点没有倒序。
+
+无需先测完整条链。每次按有效中点判定更新同类端点，都会保留左 PASS、右 FAIL，并缩小整数区间，最终取得一对相邻的候选观察点。即使中间曾有 FAIL→PASS，也只保证找到一处转变；已有抵消、覆盖恢复或路径切换线索时，按定位目标选择继续缩区或补逐层对照，不把未再观察的部分排除。
+
+## 执行
+
+1. **确定当前范围**：以已观察的 PASS 点 `L` 和后续 FAIL 点 `R` 为端点，保留两端结果、参考依据、源码位置和对应数据。
+2. **选择中间点 `M`**：在相关依赖链的当前区间内，选接近中部、语义清楚且容易取得参考的位置，同时考虑采集成本和扰动；不按源码行数划半。
+3. **取得有效比较**：优先复用已有实际结果和阶段参考，缺观察时按[检查点设计](checkpoint-design.md)补充，只采集当前判定所需的数据。
+4. **更新端点**：比较有效且两端仍代表本轮目标时，`M = PASS` 则更新 `L = M`，`M = FAIL` 则更新 `R = M`；无有效判定时先停下缩区。记录新范围，保留范围外已有异常与未测缺口；需要更强的排除结论时，另核相应依据，再决定下一观察。
+
+这里缩小的是所选判据的转变区间。较早的偏差可能尚在容差内，到后段才被放大至超差；中点 PASS 不能自动排除上游致错代码，FAIL 也不证明后段没有其他问题。需要解释传播与局部新增差异时，按[逐层分析](progressive-error-analysis.md#区分传播与新增偏差)继续。
+
+### 一个完整例子
+
+假设同一有效切片 `float32 [1,2,3,4]` 应原样经过以下搬运链，各点均按已确认的元素映射与原输入作精确比较。本例假设执行和观察稳定，只演示缩出一处判定转变。
+
+```text
+K0 入口 → K1 搬入后 → K2 临时缓冲 → K3 搬出前 → K4 输出
+```
+
+| 已有或新增观察 | 当前范围 | 下一步 |
+| --- | --- | --- |
+| K0 为 `[1,2,3,4]`，K4 为 `[1,2,30,4]` | K0 PASS → K4 FAIL | 选择中间点 K2 |
+| K2 为 `[1,2,30,4]`，判为 FAIL | K0 PASS → K2 FAIL | 再观察 K1 |
+| K1 为 `[1,2,3,4]`，判为 PASS | K1 PASS → K2 FAIL | 检查这段实际读取、偏移、长度和缓冲复用，形成具体候选 |
+
+此时已有明确的代码检查范围，可以进入候选验证；K3 仍未测，不把预测写成实际 PASS/FAIL。若补充观察发现差异曾消失再出现，保留有效端点，另查传播、恢复或其它转变，不把本次范围说成全链唯一异常。
+
+例如固定判定序列 `PASS, FAIL, PASS, PASS, FAIL`，从第 0、4 点二分可得到第 3→4 点的转变，却找不到最早的第 0→1 点。这个例子说明缩出一处边界与排除更早异常是两件事；也不能用判定边界代替具体根因。
+
+## 多轮记录
+
+复用已有比较报告，在同一记录中更新已测点、当前边界和下一观察点；已有结果少、下一步清楚时直接分析，不另建固定格式的计划。轮数和点数按实际区分需要安排。
+
+每轮取得比较后，重新核对可比性、稳定性、扰动和端点有效性，再更新端点；额外排除结论另核所需依据。比较报告和关键采集背景保留在[任务产物目录](reporting.md#任务产物目录)，未测点继续标为未测。
+
+当前记录的两个端点之间没有已列出的观察点，不代表源码只剩一步或一个 API。区间已足以检查具体实现时就转入[假设验证](hypothesis-experiment.md)；仍包含多段未知计算时，再补有区分力的语义点，不为凑“相邻”覆盖全部节点。
+
+**结束二分**：保留可信两端、区间涉及的代码和数据依赖、当前候选及下一项检查。已有证据足够时可直接确认相应机制，不强制再做实验。信息不足或观察冲突时，按原因补证或换观察；预算结束时交付已有缩区依据和未解决部分。
+
+## 退出和降级
+
+保留已有有效观察，按当前缺口选择下一步：
+
+| 情况 | 下一步 |
+| --- | --- |
+| 同一条件下判定交替或错误位置漂移 | 按[复现性方法](reproducibility.md#判断稳定性)核对触发与运行条件，暂停依赖稳定边界的缩区 |
+| 已发现多次转变，或需要解释累积、抵消、放大 | 保留已取得的有效边界，按[逐层分析](progressive-error-analysis.md)区分传播与本段差异，不以一处缩区代替其它异常的解释 |
+| 参考不独立、比较范围不对应或采集不完整 | 按[观察点设计](checkpoint-design.md)补具体缺口，或改观察其他可比位置，不把未知点当 PASS |
+| 插桩改变原现象，或其影响不足以支持当前边界 | 按[观察有效性](checkpoint-design.md#判断观察是否有效)核对；保留本轮有效结果及其限制，不替代原程序基线 |
+| 已有一个或多个有依据的候选 | 按[实验设计](hypothesis-experiment.md#实验设计)检查预测与实际联动，不为完成二分而增加无用观察 |
+
+例如单核对照同时改变 tiling、GM 所有权或调度时，按组合观察解释，不能直接确认某条同步关系。二分缩区结果与根因判断分开，具体机制由源码、预测和有效观察共同支持。