cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/operators/normalization.md

@@ -0,0 +1,145 @@
+---
+type: OperatorRisk
+title: Norm 算子族
+description: 沿 Norm 统计与分母链核对方差、Welford 状态更新、epsilon 和近似迭代，用小输入区分合并与精度问题。
+tags: [RMSNorm, LayerNorm, 分块统计, Welford, epsilon, 迭代]
+---
+
+# Norm 算子族
+
+## 数学与 reference
+
+RMSNorm/LayerNorm 的 reference 包含统计量归约、epsilon、倒数或开方、缩放与可选偏置；误差可在归约后逐层放大。
+
+冻结归一化轴、每组有效元素、mean/variance 或 square-mean 公式、epsilon 的位置/dtype、gamma/beta 广播和输出 dtype。GroupNorm 还要冻结 group 合法性和每组元素数；物理 padding 不得进入统计。
+
+## I/O 与实际链路
+
+- 冻结输入/输出 shape、dtype、layout、有效区、padding 和 alias。
+- 从 host tiling、GM 搬入、局部计算、同步到 GM 搬出逐节点记录实际计算链，不以 API 名替代。
+- tiling 分支、多核分区、尾块与特殊值必须进入风险清单。
+
+## 敏感 checkpoint
+
+按当前疑点，从输入解码、首次布局/搬运后、核心计算前后、跨核合并前后和最终有效区输出中选择少量相关点，说明 reference、CPU 或 NPU 观察面及所用参考或检查性质。没有可靠局部 oracle 时先保留原值或检查适用的不变量；无法判断的观察记为 `AMBIGUOUS`，不据此宣称该段数值正确。选点与局部对照见[观察点设计](../../diagnosis/checkpoint-design.md)；需要解释可比误差的累积、放大或抵消时，使用逐层误差分析。
+
+沿相关数据流检查有效输入、统计量 partial、合并后统计量、epsilon 后分母、归一化值或仿射输出，按疑点从全零、全同、均值大而方差小、group 尾块和 padding 哨兵中选择输入。若统计集合错误，先修复 mask/count；集合正确但误差随长度或公式变化，再比较累加和消减机制。
+
+padding 哨兵只写入已经分配且约定允许写入/观察的物理 lane，不能越过 allocation capacity。先使用有限哨兵；NaN/Inf 仅在目标 API 和路径允许时加入，并保留有限值 control。poison-only 失败只能说明实验触及 padding 路径，不能单独确认统计集、搬运或越界中的某一个根因。
+
+## 大均值、小方差的公式对照
+
+对 LayerNorm/GroupNorm 等需要方差的路径，将实际 Kernel 的方差链明确写成下列哪一类：
+
+```text
+矩公式:      var = mean(x * x) - mean(x) * mean(x)
+两遍中心化: var = mean((x - mean(x)) * (x - mean(x)))
+```
+
+当 `x = C + delta` 且 `|C|` 远大于 `|delta|` 时，矩公式需要相减两个接近的大量，是消减候选的敏感输入。两遍中心化在数值上通常更稳定，但不能因此自动替换：总体/样本方差、归约顺序、中间 dtype 和目标算子的公式语义仍必须一致。RMSNorm 使用 square-mean 路径时也不应套用去均值的方差诊断。
+
+对两条公式使用同一有效集、同一输入位模式和同一逐步 dtype 建立独立 CPU 算术链。如果只有矩公式在“大均值、小方差”输入上出现零、微小负值或显著放大的误差，只能提高“矩公式消减” 候选；还要证明实际 Kernel 使用同一公式和中间 dtype。
+
+### 微小负方差的候选分流
+
+`var < 0` 不等于已确认需要 clamp。在加 epsilon 前保存方差位模式，并按首个分叉分流：
+
+- 矩公式的 `mean(x*x)` 与 `mean(x)^2` 各自接近 oracle，相减后首次得到微小负值：消减/舍入是候选，继续用偏置扫描和公式对照验证。
+- partial sum、count、mask 或合并结果已经分叉：先查统计参与集、尾块和跨核归约，不把负值归因于公式。
+- 两遍中心化中的平方项或平方和已为负：该现象不由正常的“非负项求和”解释，优先查数据解码、错 offset、未初始化、同步、越界或证据采集。
+- 只在特定 tiling/长度分支为负：保持数值分布不变，用分支边界两侧的 shape 对照归约顺序、count/mask 和尾块候选。
+
+只有当前算子语义允许、已排除错误统计集或搬运问题，并有单变量实验与边界回归支持时，才把 `max(var, 0)` 作为修复候选。否则 clamp 会遮蔽上游错误，也可能改变当前算子的特殊值语义。
+
+## 分块 Welford：合并统计状态而非局部方差
+
+只有切成多块、出现短尾块或跨核合并后均值/方差才错时，先对每个逻辑统计组保存 `(mean, M2, count)`：`M2` 是相对于**该块均值**的偏差平方和，`count` 是有效元素数，不是对齐长度、块数或核数。将两份非空状态合并的实数恒等式为：
+
+```text
+n = n_a + n_b
+delta = mean_b - mean_a
+mean = mean_a + delta * n_b / n
+M2 = M2_a + M2_b + delta * delta * n_a * n_b / n
+variance = M2 / (n - correction)   # 最终统计组，且分母在约定允许范围内
+```
+
+例如 `[0,0]` 与 `[10]` 两块的局部 `M2` 都为零，但整体 `mean=10/3`、`M2=200/3`，总体方差为 `200/9`。平均局部均值会得到 `5`；平均局部方差或漏掉跨组偏差项会得到 `0`。这个反例检查统计状态和权重，不能用扩大容差修复。tail 必须携带自己的实际 count；某个输出只有一项，也不代表只需保存一份累加状态。
+
+需要把不等长、空状态和局部修复分别做成对照时，按需查看 [Partial 统计合并：局部正确不等于全局正确](../cases/partial-statistics-merge.md)；实际统计状态仍按当前算子约定解释。
+
+空 partial 不提供均值：先按有效集判断，只有一侧非空时沿用该侧状态，两侧都空时按当前算子的空集语义处理。不要读取空槽的残留 mean/M2 后指望乘零消除它。correction 的应用位置与总体/样本语义一起冻结；`n-correction<=0` 时不能从上式猜测输出，仍查询当前算子约定。
+
+用同一有效输入分别做等长块、不等长尾块、含空任务和反向合并的对照，在局部状态、第一次 merge、最终除法三个边界比较独立 oracle。先核对 count 与状态含义，再检查每一步的实际 dtype、count 换算和合并树；实数公式等价不保证浮点逐位相同。固定每 8 块一组不是误差保证，Welford 也不能擅自替换任务规定的公式。累加顺序的后续分叉见 [累加、归约顺序与消减](../mechanisms/accumulation-order.md)。
+
+### 统计状态的原地更新时序
+
+公式正确但原地更新后出错时，把一次 merge 的旧状态与目标状态分开。沿用 `[0,0]`、`[10]`：旧状态为 `(n_a=2, mean_a=0, M2_a=0)`，另一块为 `(1,10,0)`；先由旧值算 `delta=10`、`n=3` 和 cross term，再提交目标 `(3,10/3,200/3)`。
+
+若先写回 `mean_a=10/3`，后面的代码才算 `delta=mean_b-mean_a`，得到的已是 `20/3`；即使权重仍是正确的 `2/3`，M2 也会错成 `800/27`。这是精确有理数反例，区分状态混用与普通 FP32 舍入。实现可以原地更新，只需保留后续计算仍要用的旧字段；不要求采用特定临时变量或存储布局。
+
+先观察一次 merge 的旧 `count/mean/M2`、delta、权重、目标状态和写回后状态；若这一处已分叉，无需先重建全量归约模型。再用单块、同均值、不等长尾块对照，检查 state 是否由本轮完整写入。更多空状态和漏项对照见[Partial 统计合并](../cases/partial-statistics-merge.md)。
+
+## 分块 Softmax：先统一最大值基准，再合并
+
+单块正确、分块后 softmax 权重或加权归一化输出才错时，检查每个 partial 是否携带了同一逻辑行的最大值 `m`、缩放后的指数和 `l`、未归一化加权和 `u`。对有限 score `s_i`、有限载荷 `v_i` 和非空有效集合，数值模型为 `m=max(s)`、`l=sum(exp(s_i-m))`、`u=sum(exp(s_i-m)*v_i)`；`u` 也可以是向量。两份非空状态合并时，分母与分子都要换到共同基准：
+
+```text
+m = max(m_a, m_b)
+alpha = exp(m_a - m); beta = exp(m_b - m)
+l = alpha * l_a + beta * l_b
+u = alpha * u_a + beta * u_b
+output = u / l
+```
+
+若实际实现存储的是已归一化输出或 log-sum-exp，先按其表示推导合并关系，不能把它当作上述 `u/l` 载体直接相加。让后一块的最大值分别低于、等于、高于前一块，并在两块放置不同载荷，可区分漏更新最大值、只重缩放分母、只重缩放分子以及直接平均局部输出。比较的是同一有效输入上的每级状态，不能用单块通过证明跨块状态已接通；真实 dtype、Exp 路径和 merge 顺序仍须分别核对。
+
+首个非空块可以直接建立状态；空块不应产生新的数学贡献。是否清零、覆盖或保留具体 buffer 按实际读写路径判断，不能读取未定义旧状态后靠 `0 * old` 消除它。整行被 mask 屏蔽时，应先按约定判定空有效集；将屏蔽值换成同一个有限负数并不能自动产生零贡献，因为减去该行最大值后每项仍是 `exp(0)=1`。空行、NaN/Inf 和最终分母异常的行为由当前输出语义决定，不默认添加 epsilon 或 clamp。
+
+这一方法由 FlashAttention 的在线状态引出，只用于当前确实存在分块指数归一化的路径，不要求采用特定 FA 流水、任务切分、API 或性能模板，也不把上述有限数模型当作 NPU 验证。
+
+## Epsilon 位置是算子语义
+
+下列表达式不可互换，需要由当前 oracle/独立规范决定哪一个才是验收目标：
+
+```text
+inv_std = 1 / sqrt(var + epsilon)
+inv_std = 1 / (sqrt(var) + epsilon)
+inv_std = rsqrt(max(var, 0) + epsilon)
+```
+
+同时冻结 epsilon 的来源、值、存储 dtype、运算 dtype、量化时点、加入位置与平方根/倒数顺序。两个实现即使在普通方差上误差很小，在全同、零方差或 epsilon 主导区也可能明显分叉。把 epsilon 从 `sqrt` 内移到 `sqrt` 外即使让当前样例通过，也只是改变了公式的候选实验；在 oracle/规范没有要求该位置时不能称为修复。
+
+实验时不为了让当前样例通过而搜索 epsilon。先从约定获取它，然后在下列 checkpoint 定位首次分叉：`mean/square-mean`、epsilon 加入前统计量、加入后值、`sqrt/rsqrt`、归一化值和仿射输出。
+
+## 倒数与开方的迭代预算
+
+统计量和 epsilon 后输入正确、近似分母仍错时，才检查实际使用的初值、迭代公式、逐步 dtype 与迭代次数。次数可能由 Host tiling 传入；代码中存在一个“稳定路径”名字，不能证明初值范围和迭代预算足够。
+
+例如对正有限 `d`，倒平方根 Newton 模型为 `r_next=r*(1.5-0.5*d*r*r)`。在精确算术中，`d=4、r0=1/4` 一步仅到 `r1=11/32`，离参考 `1/2` 仍有明显差距；“已经迭代一次”不构成误差保证。这是数学模型，不声明某个 Rsqrt API 使用该算法。
+
+在当前合法范围内选普通 `d`、epsilon 主导的小 `d` 和较大 `d`，保存初值与各步的 `1-d*r²`、最终分母及输出误差。残差本身也有舍入，结合独立参考解释；若上游 `d` 已错，增加次数不能修复统计问题。只有相邻迭代预算能按预测改变误差，才支持预算不足候选；是否采用范围约简、更好初值或更多迭代，还需当前语义、资源和原输入回归支持，不给通用固定次数。
+
+## 最小输入矩阵
+
+| 输入族 | 构造方式 | 主要区分的候选 | 必须的相邻对照 |
+|---|---|---|---|
+| 全零 | 有效集全为 `+0`；约定关心符号时另测 `-0` | 零方差、epsilon 位置、特殊值语义 | 单个非零元素 |
+| 非零常量 | 每个归一化组内全相同 | 去均值、count/mask、零方差 | 只改一个 lane |
+| 大偏置+小扰动 | 先将 `C+delta_i` 转为实际输入 dtype，确认存储后的 `x_i` 仍保留所需差异 | 矩公式消减、中间 dtype | 与实际存储值的方差匹配的零中心组 |
+| 零中心小扰动 | 根据大偏置组的实际存储值构造中心化输入，再核对量化后的方差是否匹配 | 分离偏置消减与普通累加误差 | 大偏置组 |
+| epsilon 主导 | 构造方差分别低于、接近和高于约定 epsilon 的组 | epsilon 位置/量化、`sqrt` 与 `rsqrt` 顺序 | 三个点保持 shape/tiling 一致 |
+| 统计边界 | 归一化长度 `B-1/B/B+1`、group 尾块、允许观测的 padding | count、mask、尾块、分支和跨核合并 | 保持数值分布只改 shape |
+
+例如 FP16 最近舍入下，`C=4096`、`delta=[0,1]` 都可精确表示，但 `C+delta` 存储后为 `[4096,4096]`，差异在入口已丢失。它不能用于区分后续方差计算的消减误差；应换用量化后仍有区分力的输入。
+
+每组同时记录实际输入值、逻辑轴/分组、有效 count、实际 tiling 分支、partial 归约顺序和中间 dtype。若改 dtype 同时改变 tiling，按 [dtype 变化的分层对照](../../diagnosis/numerical-modeling.md#改变-dtype-时核对哪些变化)区分相关候选，不用该结果单独证明累加精度。
+
+## 版本路由与边界
+
+相关说明：[累加、归约顺序与消减](../mechanisms/accumulation-order.md)、[NaN、Inf、溢出与次正规数](../mechanisms/special-values.md)、[Cast、舍入与中间精度](../mechanisms/cast-rounding.md)。epsilon 数值、API 实现和支持范围属于具体算子/版本约定；本页不代表任一 NPU case 已验证。
+
+提高中间精度、clamp 或添加 epsilon 只在算子约定允许且当前单变量实验支持时作为修复候选。
+
+本页公式是带条件的数学模型；具体 CANN 调用及其状态表示仍需查询当前版本 API 文档。
+
+max/sum 的重缩放与 SoftmaxFlashV2 的分块状态相关，具体接口见当前版本的 Softmax API 文档。加权和 `u` 的同系数合并由本页的数学定义推导；使用时须确认当前状态定义和归一化公式一致。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/operators/reduction.md

@@ -0,0 +1,167 @@
+---
+type: OperatorRisk
+title: 归约算子族
+description: 核对归约参与集、跨核合并与索引，并用自适应池化小窗口区分坐标、count 和累加精度。
+tags: [Reduce, 归约, Atomic, Partial, AdaptiveAvgPool2D]
+---
+
+# 归约算子族
+
+## 目录
+
+- [数学与 reference](reduction.md#数学与-reference)
+- [I/O 与实际链路](reduction.md#io-与实际链路)
+- [敏感 checkpoint](reduction.md#敏感-checkpoint)
+- [融合算子的归约支路](reduction.md#融合算子的归约支路)
+- [自适应平均池化](reduction.md#自适应平均池化的小窗口对照)
+- [Production 模式](reduction.md#production-模式多核局部量共享区与二次归约)
+- [Atomic 模式生命周期](reduction.md#atomic-模式生命周期)
+- [Partial 参与集合](reduction.md#partial-参与集合账本)
+- [带索引 partial 合并](reduction.md#带索引归约局部位置与逻辑全局位置)
+- [结果指纹候选矩阵](reduction.md#偏大偏小与波动的候选矩阵)
+- [严格 bitwise](reduction.md#严格-bitwise-与-atomic-合并)
+- [版本路由与边界](reduction.md#版本路由与边界)
+
+## 数学与 reference
+
+y = reduce(x, axis)；sum 的结合顺序、累加 dtype、尾部有效元素和多核合并顺序都是敏感点。
+
+冻结 reduction 类型、axis 规范化、keepdims、每个输出对应的有效输入集合、初值、空集合语义和输出 dtype。Mean 还要冻结除数；Max/Min 要冻结特殊值与 tie 规则。不要把累加误差与 axis、窗口、mask 或输出 shape 错误混为一个候选。
+
+同时把“数学上对同一集合求和”“项目要求的求值顺序”“项目 evaluator 的通过规则”分开。顺序 FP32 oracle、分组/树形 FP32 结果、逐位一致和 MERE/MARE 等容差通过不是同一约定；后两者即使都通过，也不能反推前两者的顺序相同。
+
+## I/O 与实际链路
+
+- 冻结输入/输出 shape、dtype、layout、有效区、padding 和 alias。
+- 从 host tiling、GM 搬入、局部计算、同步到 GM 搬出逐节点记录实际计算链，不以 API 名替代。
+- tiling 分支、多核分区、尾块与特殊值必须进入风险清单。
+- 为每级 partial reduction 记录输入有效数、mask、累加 dtype、输出布局和下一阶段消费者。
+- 记录 API 的精确函数名与重载：Tensor 前 count 个元素的 `ReduceSum(dst, src, workspace, count)`、带 mask/repeat 的高维切分 `ReduceSum` 和每 repeat 输出的 `WholeReduceSum` 必须分别查询官方 API 文档。
+
+## 敏感 checkpoint
+
+按疑点从输入解码、布局/搬运、局部归约、跨核合并和最终输出中选择少量相关观察，说明观察面、参考依据与有效区。缺局部 oracle 时先保留数值或检查适用的不变量，不据此排除整段计算。具体见[观察点设计](../../diagnosis/checkpoint-design.md)；已有可比误差且需要解释传播、放大或抵消时，再使用[逐层分析](../../diagnosis/progressive-error-analysis.md)。
+
+使用 axis 首尾、长度 1、整块、尾块、强消减和 padding 哨兵构造配对实验。若元素集合或 count 已错，先修复算子语义；集合正确但误差随长度/合并顺序增长，再路由 [累加、归约顺序与消减](../mechanisms/accumulation-order.md)。
+
+固定 shape 的验收不能证明相邻长度或非法 shape 行为；若诊断实验临时改变 count、分块或核数，必须明确它只是区分机制的局部 oracle，不得计入原接口回归。Golden-only 自检也不能替代 actual 与 golden 的独立比较。
+
+## 融合算子的归约支路
+
+逐元素输出通过、只有 bias 或统计输出失败时，先画出分叉点：`中间 FP32 值 → 输出 Cast` 与 `同一中间值 → 归约 → 输出 Cast`。已收窄输出即使逐位一致，也不能证明上游 FP32 值一致；更不能把这些输出重新升 FP32 后求和当作未收窄归约的 oracle。
+
+按疑点检查归约前 FP32 值、chunk partial、跨块合并、最终 Cast 和写回；某一路输出正常也不证明另一路的地址与最后一次写入正确。无 bias 对照可隔离是否进入归约，但改变 has_bias 可能同时改变 tiling，需要核对实际路径。
+
+集合与归约输入一致后，有限值偏差查[分层归约与主尾列](../mechanisms/accumulation-order.md#框架参考的分层归约与主尾列分派)，类别失配查[顺序与溢出](../mechanisms/special-values.md#有限输入的归约顺序也会改变非有限类别)。修复后出现新的整段尾区异常则查[可变计数](../mechanisms/tiling-tail-state.md#可变计数被消费后续输出漏写与清零不完整)。[GRU p2/p3 案例](../cases/thnn-fused-gru-bias-reduction.md)串起了这些分叉。
+
+## 自适应平均池化的小窗口对照
+
+当前约定若按下式定义自适应窗口，对输出坐标 `(oh,ow)` 分别列出 H/W 的半开区间：
+
+```text
+h0 = floor(oh * Hin / Hout)
+h1 = ceil((oh + 1) * Hin / Hout)
+w0 = floor(ow * Win / Wout)
+w1 = ceil((ow + 1) * Win / Wout)
+count = (h1-h0) * (w1-w0)
+```
+
+窗口可能重叠；不能由“平均池化”推断每个输入只属于一个窗口。先核对当前参考确实使用这一定义，再区分边界取整、H/W 角色、输入 stride、除数与累加 dtype，避免一次重写全量模拟器。
+
+一个单通道小例为 `Hin=3、Win=5、Hout=2、Wout=3`，输入 `x[h,w]=10*h+w`。H 窗口依次为 `[0,2)`、`[1,3)`；W 窗口为 `[0,2)`、`[1,4)`、`[3,5)`。实数平均输出为：
+
+```text
+[[ 5.5,  7.0,  8.5],
+ [15.5, 17.0, 18.5]]
+```
+
+对一个失配输出，保存窗口起止、实际读取坐标、count、逐步累加值和除法结果。这个输入能区分窗口与坐标错误，不能证明低精度累加正确。后者可另用单窗口 `[2^12,1,-2^12,1]`：在逐步最近偶数舍入的顺序模型中，FP16 累加再除以 4 得 `1/4`，FP32 累加得 `1/2`。实际参考的求和树不同则重新计算预测，不把顺序模型当 API 规则。
+
+补一个 `H=1` 或 `W=1` 的合法输入与可整除矩形对照。先用一两个窗口验证候选，局部结论成立后回到原 Kernel 和原比较器；只拟合整套 PASS/FAIL 标签，不能区分坐标错误与数值误差。
+
+## 归约接口组合中的常见误用
+
+| 现象 | 先核对什么 |
+| --- | --- |
+| 非对齐行结果偏大或尾部候选丢失 | 物理行距与有效列数分开；展开 mask/count、Compare 和搬运实际覆盖的元素。需要读取补齐区时，填充值应对当前归约或比较无影响 |
+| 最值正确，索引被读成微小浮点数 | 按当前重载解释索引的位编码，不能把编码字段直接当浮点数值；再做局部到全局的位置映射 |
+| 带索引的分组结果残留或相邻结果被覆盖 | 目的区是否为完整记录预留了空间与对齐；修正跨度时同步修改写入和消费偏移 |
+| pattern 输出数量或方向错误 | 用小二维矩阵对照归约轴，分别核对逻辑 shape、物理补齐、临时空间和当前重载 |
+| 复算时输入已改变 | 是否启用了源空间复用，或临时区覆盖了输入；用合法的独立缓冲路径对照 |
+| ReduceAll 或特殊值结果不符 | 原输入是否满足该接口的布尔编码或特殊值要求；只有算子定义要求时才做输入转换 |
+
+使用 `ascendc-api-knowledge-query` 分别查基础归约和按轴归约的原型、类型、对齐与临时空间；更名调用同时查接口变更与参数顺序。repeat 截断、分批漏项和零工作量见[调用计数与分批状态](../mechanisms/tiling-tail-state.md#调用计数与分批状态)。
+
+一个历史对照记录了 CANN 9.0.0 / Ascend910B1 上的 `whole_reduce_sum_unalign`：half 输入 shape 为 `[13,123]`，容差 0.001 的验收通过，但有 3 行与参考值相差 1 ULP。它说明容差通过不代表逐位相等；当前差异是否来自归约顺序，仍要检查参与元素、具体求值路径和中间 dtype。
+
+按轴归约中启用 isReuseSource 时，查询该重载是否允许改写源，再检查后续消费者是否仍需要原输入。高阶 ReduceMean/ReduceProd 也需检查长轴中的中间范围和溢出；“用了高阶接口”不排除数值边界，按轴分段观察应保留逻辑 shape、padding 和有效输出。
+
+## Production 模式：多核局部量、共享区与二次归约
+
+对于分阶段归约，可以分别检查以下关系：各核计算局部统计量，受控地合并或写入独立 workspace，所有参与核到达完成边界后，再由下一阶段做最终归约。审计时分别验证任务分配与 tail、局部结果就绪、共享区初值/ownership、核间完成条件、最终参与集合和累加 dtype。原子开关、核内依赖与全核同步是不同责任。先从当前 Kernel 确认实际阶段与参与集合，具体 API 支持须按当前版本核对。
+
+若最终结果偶尔偏大，先用每核唯一哨兵判断是局部结果重复写、原子模式未恢复、workspace 未清零，还是最终归约集合重复；若偶尔偏小，检查局部搬出发生在 producer 完成前或某些尾任务未参与。将 “原子合并”和“每核独立槽位后二次有序归约”作为单变量对照时，必须同时记录合并顺序改变带来的数值差异，不能把更稳定自动写成更符合原 oracle。
+
+## Atomic 模式生命周期
+
+把 Atomic 当作影响后续搬出的显式状态，而不是某一行调用的局部注释。沿所有分支和 early return 画出状态机：普通写状态 → 仅在目标合并搬出前开启 → 执行目标写入 → 立即恢复普通写状态。再核对目标 GM/workspace 初值、受 Atomic 影响的精确写集合，以及恢复后第一条普通写。若某条路径漏恢复，后续本应覆盖的搬出可能变成累加候选；若过早恢复，目标 partial 可能退化为互相覆盖候选。
+
+历史样例中出现过 `SetAtomicAdd` 与 `SetAtomicNone` 成对包住一次搬出，也记录过“未恢复后结果偏大”的排查线索。这只是一种历史观察。当前 profile 下具体 Atomic API 名、支持 dtype、作用于哪类搬运、恢复接口、所需核内流水依赖、跨核可见性与同步参与规则均为 UNKNOWN，必须使用 `ascendc-api-knowledge-query` 读取对应版本的 DMA 原子及相关搬运文档后才能下结论。
+
+模板声明的原子类型还要与真实输出 dtype 对齐。初始化覆盖与浮点合并乱序可能同时造成运行间波动，先分别对照 GM 初值、贡献集合和普通写/原子写的生效区间；DMA 原子的具体同步插入点及特殊值模式使用 `ascendc-api-knowledge-query` 核对，不跨版本照搬。
+
+### 跨卡归约对照
+
+AllReduce 与单卡参考有微小位差时，先核对每个 rank 的贡献及通信前后 dtype，再固定通信域、进程级确定性配置和执行形态做对照。配置相同不独立保证两个实现采用相同求和顺序，逐位要求也不能自行放宽成容差。若结果是旧值或缺少某个分段，先查[通信缓冲与完成范围](../mechanisms/multicore-ownership.md#跨卡通信的缓冲所有权)。Host 通信的配置入口使用 `knowledge-query` 确认。
+
+## Partial 参与集合账本
+
+对每个最终输出 `y[j]` 同时建立元素级数学集合和实现级 partial 多重集：
+
+```text
+ExpectedElements(j)
+  -> Tasks(core, round)
+  -> Partial(core, slot, valid_count, dtype, producer_epoch)
+  -> FinalContributors(j)
+```
+
+分别验证每个 required 元素进入且只进入要求的 partial、每个 partial 的有效长度和 tail 正确、空核/空任务没有伪造贡献、最终阶段没有漏槽或重复读取同一槽。这里必须保留 contributor 的重数；简单集合并集会把“同一 partial 被加了两次”错误地去重。先比较每个 partial 的独立 oracle：局部值已错时查上游计算与有效区；所有局部值都对而最终错时，再查参与集合、初始化、可见性和合并顺序。
+
+对 chunked reduction，参与多重集正确只证明 partial 没有漏项或重复。若问题转为相同参与集合下的舍入、分块或合并次序，则路由到 [累加、归约顺序与消减](../mechanisms/accumulation-order.md) 冻结对应 oracle 的顺序约定；本页继续负责参与集合、实际计算链和算子验收面的核对。
+
+若每个 partial 已与局部 oracle 一致而统计 merge 仍错，按需查看 [Partial 统计合并：局部正确不等于全局正确](../cases/partial-statistics-merge.md) 的不等长/空状态对照；它不替代本页的参与多重集审计。
+
+## 带索引归约：局部位置与逻辑全局位置
+
+最大/最小值正确而索引错误，或只在非首块、多核、并列极值时失败，先把每个 partial 写成 `(value, logical_index)`，同时记录 `local_ordinal -> logical_index` 的映射。输出索引可能是归约轴坐标或某个声明顺序下的展平坐标，不能直接换成 GM 字节 offset；只有连续且无跳跃的同一坐标系，才能简化为“块起点 + 局部索引”。多轴、stride、repeat 和 tail 路径按各自有效集合展开。
+
+合并时 value 与 index 必须来自同一候选，不能只合并 value 再保留任意局部 index。若要求返回第一个极值，有限普通输入下的 tie 应选择该逻辑遍历顺序中更早的 index，而不是先到达的 partial。例如 `[1,7]` 与 `[2,7]` 两块映射到全局位置后，最大值都为 `7`，索引分别为 `1`、`3`；反转合并到达顺序仍应选 `1`。只用严格 `>` 并保留先到达者，会在后一块先到时误选 `3`。
+
+区分实验分别改变非零块起点、极值所在尾块，以及两个含相同极值的 partial 到达顺序；另用不同极值作为非 tie 对照。在局部结果解码、全局映射、成对合并和最终索引转换后比较首个分叉。若索引暂存于浮点中，再转查 [Cast、舍入与中间精度](../mechanisms/cast-rounding.md) 的整数碰撞边界；不同 API 返回的索引可能是数值或编码字段，应先查当前重载再决定 Cast 还是位解释。
+
+first/last、NaN、符号零及索引遍历顺序都按任务约定确定，不能无条件采用 LE/GE 或强制 float 索引。mask 外和 padding lane 不应伪造候选；实际 API 的 calIndex、索引格式和临时空间需查询当前版本来源。
+
+## 偏大、偏小与波动的候选矩阵
+
+| 结果指纹 | 优先核对的可证伪候选 |
+|---|---|
+| 稳定偏大 | 输出/workspace 未按约定初始化；partial 重复参与；同一 task 被两核处理；Atomic 状态泄漏使后续普通写继续累加 |
+| 稳定偏小 | tail task 或某些参与核遗漏；空核/参与核判断错误；partial 在 producer 完成前搬出；最终阶段漏读有效槽 |
+| 同输入运行间波动 | 初始化不完整；共享写或完成边界不明确；未固定的合并次序；读到了不同 epoch 的 partial |
+| 数值接近但逐位不同 | 参与集合相同但合并树、partial 存储 dtype 或舍入点不同；先不要归因于漏项/重复项 |
+
+这些只是候选排序，不是由误差正负直接推出根因。用每核唯一哨兵、slot 有效标记、两项可手算输入和强消减输入分别区分“谁参与了”与“以什么顺序累加”。增加同步后现象变化也只证明实验触及执行路径，必须同时证明同步覆盖了正确 producer、consumer 和参与核集合。
+
+若局部量逐项正确但最终结果偶尔多一份或少一个 partial，优先比较 `FinalContributors` 的带重数清单和共享区有效标记；不要重新调整局部 Reduce 公式来掩盖合并阶段的漏项或重复项。
+
+## 严格 bitwise 与 Atomic 合并
+
+先冻结验收要求到底是顺序 oracle 的逐位一致，还是允许明确容差的数学归约。若当前 Atomic 合并约定没有权威证据保证固定顺序，就不能仅凭它与某个串行求和结果的 bitwise 差异证明 Atomic 参与集合或具体实现机制错误；若项目约定要求严格 bitwise，该差异本身仍是验收失败。反过来，容差通过也不能证明参与集合、特殊值类别或重复运行稳定性正确。对 NaN、Inf、符号零等仍按算子约定单独比较类别和符号。怀疑归约顺序导致位差时，查[累加、归约顺序与消减](../mechanisms/accumulation-order.md)。
+
+要求 bitwise 时按项目规则比较最终输出；只有另有求值顺序要求，或正在调查合并顺序差异时，才展开 partial 的生成、存储 dtype 和合并过程。“每核独立槽位 + 确定顺序二次归约”可作为区分实验。只要求容差时，在参与集合正确的前提下评估误差，不自行升级为逐位验收。
+
+## 版本路由与边界
+
+基础归约与 DMA 原子的接口资料使用 `ascendc-api-knowledge-query` 获取。API 的 mask、repeat、临时空间、Atomic 与同步支持范围应根据所查官方页面并结合当前产品核对；本页不代表任一具体实现或 NPU case 已验证。
+
+带索引 partial 的局部索引必须转换为最终输出的位置；具体 ReduceMax 索引示例使用 `ascendc-api-knowledge-query` 读取。其它 API 的索引坐标系与 tie 语义须单独确认。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/operators/softplus-v2-grad.md

@@ -0,0 +1,58 @@
+---
+type: OperatorRisk
+title: SoftplusV2Grad / SoftplusBackward 算法约定
+description: 围绕 Softplus 梯度角色与求值顺序定位，并按 repeat、极负区归零和属性残差直达案例支路。
+tags: [SoftplusV2Grad, SoftplusBackward, 分支, repeat, subnormal]
+---
+
+# SoftplusV2Grad / SoftplusBackward 算法约定
+
+当计算链包含 SoftplusV2Grad / SoftplusBackward 时，用本页补充梯度角色、分支和浮点求值顺序的敏感点。输出像某个中间量、阈值或极负区失配，以及大梯度下 Inf/有限类别不同，都属于相关线索。本页不声明任何产品上的 ACLNN API 可用，也不迁移 RegBase 历史案例的实现或修复。
+
+## 按残余症状进入案例
+
+已有部分修复时，直接按残差进入历史案例的对应支路；无需重新遍历全部候选。
+
+| 残余症状 | 案例入口与首个检查 |
+| --- | --- |
+| actual 像 `self`、sigmoid 或其他中间量 | [支路 A：角色与槽位](../cases/softplus-v2-grad-family.md#支路-a数据流角色与槽位)，核对实参和 CopyOut 的最后写者 |
+| 首 repeat 正常，后段重复或仅 tail 失败 | [支路 B：repeat、mask 与 tail](../cases/softplus-v2-grad-family.md#支路-brepeatmask-与-tail)，给真假支路设置可区分的合法值，比较跨 repeat 的具体 lane |
+| 阈值两侧选支错误，或大梯度下 Inf/有限不同 | [支路 C：浮点语义](../cases/softplus-v2-grad-family.md#支路-c浮点语义而不是实数恒等式)，分开核对原始谓词、clamp 与参考乘除顺序 |
+| 极负区为零，参考仍是小量；大梯度放大残差 | [支路 D：subnormal](../cases/softplus-v2-grad-family.md#支路-d设备精度与-subnormal)，在同一元素的产生、搬运、消费处定位首次归零 |
+| 改属性后输出不变，或只在后续调用失配 | [支路 E：Host 属性与产物](../cases/softplus-v2-grad-family.md#支路-ehost-属性复用与产物采用)，核对真实属性、缓存与执行产物 |
+
+案例中的 API、常量和环境仅覆盖正文范围；这里复用调查方法，不把历史实现当当前产品约定。
+
+## 公式与角色
+
+令 `bx = beta * self`。官方 SoftplusBackward 文档给出的反向公式是：
+
+```text
+gradInput = gradOutput * (1 / (1 + exp(-bx)))  if bx <= threshold
+            gradOutput                         if bx > threshold
+```
+
+`gradOutput` 是上游梯度输入，`self` 是 Softplus 正向输入，`beta` 与 `threshold` 是定义公式的标量，`gradInput` 是输出。逐调用点把它们同实际形参、实参、dtype、地址/槽位及最后写者对应起来；同类型指针或寄存器位置相邻不代表角色可互换。
+
+分支判据读取的是原始 `beta * self`：`bx > threshold` 直通 `gradOutput`，否则乘 sigmoid 因子。若为了计算 `exp` 使用稳定变换，仍保留 `bx_raw` 供谓词使用。把下界 clamp 后的量同时用于 false branch 和谓词，会改变分段语义；只有当前实现与独立 oracle 的 trigger/control 都支持时，它才是可证伪候选，不自动成为根因。
+
+## 数学公式与参考实现的求值顺序
+
+上面的 sigmoid 形式描述数学关系，不规定当前 reference 的浮点执行顺序。若 golden 调用某个框架 API，核对任务实际使用的版本、dtype 和分支；不能由 API 名称或这个数学公式推断它一定先计算 sigmoid 再乘梯度。
+
+令 `z = exp(bx)`，分别展开 `(gradOutput * z) / (z + 1)` 和 `gradOutput * (z / (z + 1))`。标记中间 Mul/Div 的范围：大梯度可能让第一条链先溢出，而第二条链仍为有限数。reference 出 Inf、Kernel 出有限数时，先查实际求值顺序；“避免了溢出”本身不能证明符合当前验收要求。只有输入、分支和参考语义已确认，才能判断某种稳定改写是否允许。
+
+用一组能让两条链分叉的合法输入和普通量级对照核对参考行为，保留中间乘积、比例及输出类别；已有可信观察可复用。通用区分方法见[乘除重结合](../mechanisms/algorithm-parameter-contract.md#乘除重结合的有限精度分叉)，历史诊断见[浮点语义支路](../cases/softplus-v2-grad-family.md#支路-c浮点语义而不是实数恒等式)。
+
+## 最小定位检查
+
+- 核对当前 golden 的实际执行链，把中间乘除、特殊值传播和后续放大标到计算链上；未确认顺序时先保留疑点，不用数学等价式替代。
+
+- 选择 `bx` 位于阈值两侧、且两支预测输出不同的 control/trigger；先验证实际谓词使用的槽位和值，再比较 `gradInput`。两支恰好舍入为同一值时记录 `NO_DISCRIMINATION`，不能排除谓词错误。
+- 对极负 `bx`，用当前任务冻结的 dtype 和逐步顺序计算 sigmoid 因子。若 actual 像 `gradOutput`、`sigmoid` 或另一个操作数，分别核对 `gradOutput/self/beta/threshold` 的实参槽位，而不是直接改公式或常量。
+- 为每个候选值保留 `bx_raw`、稳定计算量、谓词输入、false-branch 结果和 `gradInput` 的最后 writer。CopyOut 必须从最后写入 `gradInput` 的槽位搬出；“VF 已写结果”不能证明搬出源正确。
+- 比较 lower-clamp 开/关时，只改变 clamp，并保持槽位、谓词来源、dtype、CopyOut 和输入不变。只有输出按事前预测在 false branch 改变，才支持该候选；仍需证明 clamp 在当前约定中不应存在，才可归因。
+
+## 使用范围
+
+CANN 9.0.0 与 9.1.0 的 SoftplusBackward 产品约定均把 Ascend 950PR/950DT 标为该 ACLNN API 的“不支持”。本页可用于确认算法公式和参数角色；950PR 上的 API 支持、实现路径与数值模式必须另查当前版本的产品约定。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/patterns/operators/sort-merge.md

@@ -0,0 +1,65 @@
+---
+type: OperatorRisk
+title: 排序与归并算子族
+description: 核对排序与多路归并的 value/index、记录布局、有效长度、消耗计数和偏移单位，检查并列与截断边界。
+tags: [Sort, MrgSort, 索引, 有效长度]
+---
+
+# 排序与归并算子族
+
+## 数学与 reference
+
+Sort 生成有序 score/index 记录，MrgSort 合并最多若干有序队列；稳定性、有效长度和记录布局决定 oracle。
+
+## I/O 与实际链路
+
+- 冻结输入/输出 shape、dtype、layout、有效区、padding 和 alias。
+- 从 host tiling、GM 搬入、局部计算、同步到 GM 搬出逐节点记录实际计算链，不以 API 名替代。
+- tiling 分支、多核分区、尾块与特殊值必须进入风险清单。
+
+## 敏感 checkpoint
+
+按疑点从输入解码、局部排序、归并、记录搬运和最终有效输出中选择少量相关观察，说明观察面与参考依据。没有完整局部 oracle 时，可先检查排序、配对或数量守恒等适用性质，结论限于所检查的性质。选点和缺口处理见[观察点设计](../../diagnosis/checkpoint-design.md)；已有可比数值误差需要解释传播时，再用[逐层分析](../../diagnosis/progressive-error-analysis.md)。
+
+## value-index 指纹与并列约定
+
+排序记录不能只验 score。给每个输入位置配置唯一、可逆的 index 指纹，逐条核对输出 `(value,index)` 仍来自同一输入记录；“value 已有序”不证明 index 配对正确。重复 value、`+0/-0`、NaN、相同 score 的稳定性以及 TopK 截断边界必须由当前任务约定明确；未规定稳定顺序时，不能把任意一种 tie 顺序写进 golden，也不能用集合相等掩盖明确要求的稳定性。
+
+至少加入三组 control：全部 score 唯一，验证纯排序与配对；部分 score 相同，验证 tie/stability；截断点两侧相同或相邻，验证 TopK 边界。padding 或无效 proposal 使用与有效记录可区分的 poison，但只有物理缓冲区已分配、约定允许读写且 poison 本身是接口语义允许的值时才设置；否则保持 UNKNOWN，并通过有效长度成对输入观察。
+
+### Record/Proposal 有效区账本
+
+- **何时查**：排序值正确但 index 丢失、尾部出现旧记录、日志把 `record` 与 `proposal` 混称，或 CopyOut 长度和 TopK 长度不一致时查询。
+- **查什么**：对每个阶段分开记录 `capacity`、`produced`、`logical_valid`、`consumed`、`emitted`、`compared`，并记录物理记录跨度和字段解码依据。`capacity` 不能替代有效记录数；旧材料叫 proposal 只作为检索标签，当前记录是否为 score/index、Region Proposal 或其它布局必须由真实重载与版本 API 裁决。
+- **怎么证伪**：保持容量不变，只改变有效长度，并让有效记录带唯一指纹；仅当无效区已分配且允许诊断写入时才改变其内容，否则只做有效长度对照。若最终输出严格跟随有效长度、允许的无效区变化不影响有效结果，且每阶段计数守恒，就降低有效区泄漏候选。
+- **避免混淆**：无效区出现任意值不等于越界，只有它进入 `consumed/emitted/compared` 才形成证据；记录字节数、字段偏移、Extract/ProposalExtract 含义和产品支持均使用 `ascendc-api-knowledge-query` 核对当前原文，未知即 `UNKNOWN`。
+
+## 多路归并守恒账本
+
+每轮归并为每一路记录 `offset_before`、`remaining_before`、`consumed`、`remaining_after`，并记录本轮 `emitted` 和输出有效区。必须满足：每路 `remaining_after = remaining_before - consumed`，所有路的消耗总数与本轮真实输出数按接口语义对账，offset 只前进已消费记录的物理距离。一路耗尽后仍出现重复记录，先查有效路集合、紧凑返回计数与 offset 更新；总条数减少则查漏消费、过早退出或 TopK 截断约定，不先归因数值排序。
+
+守恒通过仍不证明顺序正确；顺序通过也不证明 value-index 配对和截断正确。分别使用每路不同量级的 value/index 指纹、单路耗尽、两路同时耗尽、只剩一路和恰好跨 TopK 边界的输入。`validBit`、返回数组含义、proposal 布局、偏移单位及产品支持使用 `ascendc-api-knowledge-query` 从当前版本的排序与归并原文确认。
+
+### 归并进度量与截断边界
+
+- **何时查**：归并卡住、重复上一批、一路耗尽后越界、输出超过/少于 TopK，或下一 group 才异常时查询。
+- **查什么**：把一轮拆成“确定有效路与输入有效长度 → 搬入 → 合并 → 读取逐路消费量 → 更新剩余量与 offset → 搬出 → 必要时清理 group 状态”。选择一个严格进度量，例如所有有效路 `remaining` 之和；每轮还记录停止谓词的轮前值和轮后值。
+- **怎么证伪**：覆盖首轮、一路提前耗尽、只剩一路、尾 group 和恰好到截断点；若每个非终止轮次进度量严格下降、输出 offset 只按真实 emitted 前进、重新初始化后不受上一 group 影响，就降低状态机候选。
+- **避免混淆**：循环终止只证明有进度，不证明队列输入已排序、tie 约定正确或截断记录正确；反之，最终 score 有序也不能证明没有重复/漏项。逐路返回计数是否紧凑、有效路编码与 offset 单位属于 exact overload 事实，只从版本页取值。
+
+## 接口组合中的排序异常
+
+- 输出每小块有序而整体无序时，核对是否只做了局部排序、是否启用所需的全排序模式，以及后续归并是否真的消费了全部有效路。
+- sortedNum/GetMrgSortResult 用于推进循环前，先确认当前模式下计数有效。有效路描述、实际队列长度和返回计数布局一起核对，不能假设无效槽位自动清零或把路数直接当 validBit。
+- proposal 地址差一个固定倍数时，检查字节、元素、记录跨度是否重复换算。GetSortLen/GetSortOffset 的文档与实现存在单位分歧时，按[排序单位说明](sort-merge.md#排序偏移的单位分歧)做小规模地址对照，不统一套倍数。
+- half/BF16 score 已经相等时，扩大为 float 不能恢复窄化前的区别。需要更高分辨率，应在首次窄化前保留；输入只剩低精度值时按其真实值和任务的并列规则排序。
+
+不同重载的 repeat、零次数、有效路编码与补齐要求使用 `ascendc-api-knowledge-query` 逐项核对，本页继续检查有序范围、进度和数量是否正确。
+
+## 排序偏移的单位分歧
+
+CANN 9.1 的 [GetSortOffset 文档](https://gitcode.com/cann/asc-devkit/blob/e5451c7feba11f9e259f4fbc19c4bf82f8c0496c/docs/api/SIMD-API/高阶API/排序操作/GetSortOffset.md)与[配套实现](https://gitcode.com/cann/asc-devkit/blob/e5451c7feba11f9e259f4fbc19c4bf82f8c0496c/impl/basic_api/kernel_operator_proposal_intf_impl.h)对单位的表述不一致。两边同时保留，结合当前版本与重载做最小布局对照：使用唯一 value/index 指纹，检查相邻记录真实地址差、有效记录数与分配跨度，区分字节、元素和记录单位。尚未确认时不套用任何一方的倍数，也不把小样本通过推广到其他重载。
+
+## 版本路由与边界
+
+排序与归并的接口资料使用 `ascendc-api-knowledge-query` 获取。本页为诊断模型，不代表任一具体实现或 NPU case 已验证。

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

@@ -0,0 +1,18 @@
+# 工具选用
+
+本页列出精度调试中可直接使用的 CANN 工具和调试 API，按需要选择对应入口。工具能力随 CANN 版本变化，使用 CANN 版本实际安装的工具。
+
+## 工具与调试 API
+
+| 工具或 API | 用途 | 使用入口 |
+| --- | --- | --- |
+| `DumpTensor` | 在 Kernel 内主动调用，输出指定 Tensor 的值 | [dumptensor.md](../diagnosis/dumptensor.md) |
+| `show_kernel_debug_data` | 解析已采集的 Kernel Tensor、printf 等调测数据 | [kernel-debug-data.md](kernel-debug-data.md) |
+| `msSanitizer` | 检查设备执行中的访存、竞争或同步问题 | [官方仓库](https://gitcode.com/Ascend/mssanitizer) |
+| `msobjdump` | 查看 Kernel 元数据、提取设备 ELF，工具支持时反汇编设备指令 | [msobjdump.md](msobjdump.md) |
+
+## 调用准备
+
+使用工程已有的 Python 环境及实际采用的 CANN 安装，先核对相关工具帮助和输入格式。已有可用路径时直接调用；安装不明或调用失败时，查当前安装的工具目录和配套说明。环境身份在实际运行端确认，缺失字段保留未知。
+
+工具产生的日志、比较结果、dump 和新配置放在[任务产物目录](../diagnosis/reporting.md#任务产物目录)中，每轮使用独立文件或子目录，保留原始输入。

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/tools/kernel-debug-data.md

@@ -0,0 +1,133 @@
+# show_kernel_debug_data：解析 Kernel 调测数据
+
+`show_kernel_debug_data` 将 Kernel 内 `AscendC::DumpTensor`、`AscendC::printf` 等接口生成的调测二进制解析为 Tensor 文件、日志和时间戳。
+
+## 使用场景
+
+- 已采集计算前后或搬运前后的 Tensor，需要读取中间值并与局部参考比较。
+- 同一处 Tensor 被多个核或多次循环输出，需要按核、标签和记录序号找到对应片段。
+- Kernel 的 printf、assert 或时间戳已落盘，需要还原日志，确认执行分支或辅助对齐 Tensor 记录。
+
+输入必须是 Kernel 调测数据；普通输入输出数组即使也以 `.bin` 保存，也不能按这种格式解析。工具只解析已采集的内容，不会自动执行 Kernel、增加观察点或判断算子精度是否达标。
+
+## 采集与解析
+
+使用工程实际采用的 CANN 环境，先运行 `show_kernel_debug_data -h` 确认命令及参数可用。以下示例中的 `<artifact-dir>` 表示本次任务产物目录，执行前替换为实际路径。已有原始调测文件时，直接进入“解析与输出”。
+
+### 配置与采集
+
+Kernel 已包含需要的调试接口调用时，通过工程的 ACL 初始化或框架入口加载以下配置，将调测数据落盘：
+
+```json
+{
+  "dump": {
+    "dump_kernel_data": "tensor,printf",
+    "dump_path": "<artifact-dir>/raw"
+  }
+}
+```
+
+`tensor` 导出 DumpTensor 数据，`printf` 导出格式化日志；还可选 `assert`、`timestamp`，或用 `all` 导出全部类型。ACL 直调工程由 `aclInit` 接收配置文件路径；已有框架初始化时使用其配置入口。仅创建 JSON 文件不会启用采集。
+
+需要断言文本时优先选 `all`，并保留程序的运行日志。部分 `ascendc_assert` 消息按 `printf` 类型采集，单选 `assert` 可能漏掉。
+
+采集 `PrintTimeStamp` 时，还需在实际编译 Kernel 的目标上启用 `ASCENDC_TIME_STAMP_ON`。将 `<kernel-target>` 替换为目标名：
+
+```cmake
+target_compile_definitions(<kernel-target> PRIVATE ASCENDC_TIME_STAMP_ON)
+```
+
+仅将采集类型设为 `timestamp` 或 `all`，不会开启编译时关闭的时间戳打点。
+
+`dump_path` 为必填项，可使用相对路径；核对程序运行目录。路径覆盖优先级为 `ASCEND_DUMP_PATH` > `ASCEND_WORK_PATH` > `dump_path`，找不到文件时先确认实际生效的目录。采集端还会在输出目录下创建 `printf/`、时间戳等子目录；运行带调试调用的 Kernel 后，按实际落盘位置选择本次原始文件。
+
+### 解析与输出
+
+命令接收两个位置参数：
+
+```text
+show_kernel_debug_data <bin_file_path> [output_path]
+```
+
+| 参数 | 含义 |
+| --- | --- |
+| `bin_file_path` | 必填。一个原始调测文件，或包含原始调测文件的目录；目录模式递归收集 `.bin`。 |
+| `output_path` | 可选。解析结果目录，不存在时自动创建；省略时使用当前工作目录。建议显式指定。 |
+
+解析单个文件：
+
+```bash
+show_kernel_debug_data "<raw-bin-file>" "<artifact-dir>/parsed-one"
+```
+
+解析同一次 Kernel 调用的调测目录：
+
+```bash
+show_kernel_debug_data "<artifact-dir>/raw/<本次调测目录>" "<artifact-dir>/parsed"
+```
+
+目录模式只传入本次调用的数据，避免混入其他运行或 Kernel 的文件；相同核、标签和记录序号可能生成同名输出。解析目录放在原始输入目录之外，防止下次递归解析时把已提取的 Tensor `.bin` 再当作原始调测文件。
+
+## 读取解析结果
+
+工具在输出目录下创建 `PARSER_<时间戳>/`，并打印实际位置。常见产物如下；只有输入包含相应记录时才会生成对应文件。
+
+| 产物 | 怎样使用 |
+| --- | --- |
+| `parser.log` | 查看解析日志；结合终端标准输出和错误输出检查异常。 |
+| `dump_data/<核标识>/` 下的 Tensor `.txt` | 快速观察数值和形态；有 shape 信息时按 shape 排列，没有时为顺序数值。 |
+| 同名 Tensor `.bin` | 提取出的 Tensor 原始数据字节。按实际 dtype 读取，用于数值或逐位比较；它不再是带调测记录头的输入文件。 |
+| `dump_data/index_dtype.json` | 查看 `desc` 标签对应的 dtype；它不提供完整的逻辑 shape、layout 或全局坐标映射。 |
+| `time_stamp_core_<核标识>.csv` | 查看采集到的时间戳记录。 |
+| 终端中的 `block.<核标识> begin/end` 段 | 查看对应记录的 printf、assert 等文本。 |
+
+具体目录层级和文件前缀随调测格式而异，定位时关注以下字段：
+
+- **核标识**：用于关联原始文件、解析目录与日志，不保证等同于 `AscendC::GetBlockIdx()`。文件名中的 `aic`、`aiv` 也不宜单独作为核运行类型的依据。需要对应逻辑 block 时，在同次采集的 printf 中输出 `GetBlockIdx()`，再与解析日志配对。
+- **index**：对应 `DumpTensor` 的第二个参数 `desc`，不是 Tensor 元素下标。不同 Tensor 使用不同标签，避免记录混在一起。
+- **loop**：同一核、同一标签在所解析记录中的出现序号，从 0 开始。条件打印、重复标签或多次 Kernel 调用都会影响对应关系，不能直接当作源码循环变量。
+
+比较时保留 `.bin` 并确认 dtype、实际采集元素数和布局；`.txt` 用于阅读，不用于恢复原始位模式。全局坐标需要结合 Kernel 的核分片、循环偏移及 DumpTensor 的起始偏移计算。
+
+## 使用实例：读取 Add 的输入与输出片段
+
+下面以官方 Add 样例的调测数据说明读取方法。样例将 `xLocal[64]`、`yLocal[64]`、`zLocal[64]` 起始的各 16 个 float32 元素分别标记为 `desc=0`、`1`、`2`。已有该样例一次运行的原始调测文件时：
+
+```bash
+show_kernel_debug_data "<本次样例调测目录>" "<artifact-dir>/add-parsed"
+```
+
+先找到各核标签 2 的第一条记录：
+
+```bash
+find "<artifact-dir>/add-parsed" -type f -name '*_index_2_loop_0.bin'
+```
+
+选择其中一份，在同目录下按共同前缀和相同 `loop` 找到输入与输出。下面的 `<共同前缀>` 取自实际文件，不固定核标识或 `aic`、`aiv` 前缀：
+
+```text
+<共同前缀>_index_0_loop_0.bin  # x 的片段
+<共同前缀>_index_1_loop_0.bin  # y 的片段
+<共同前缀>_index_2_loop_0.bin  # z 的片段
+```
+
+先读同名 `.txt` 查看值，再按 float32 读取三份 `.bin` 做局部比较。每份应有 16 个元素，即 64 字节；比较同一核、同一组记录中 `z[i]` 与 `x[i] + y[i]`，按项目判据判断差异。这里的元素 `i=0` 对应当前 tile 的偏移 64，不能直接对照完整输入数组的第 0 项。其他循环组也按相同的核、标签和记录顺序配对。
+
+这组数据只能检查已采集的 16 个元素；样例程序的精度验收与解析命令是否成功需分别判断。
+
+## 判断解析是否成功
+
+同时检查命令退出状态、异常输出和实际产物，再核对目标核、标签、记录数及每条 Tensor 的数据量。只采集 printf 时没有 Tensor 文件是正常情况；需要 Tensor 却只有日志时，检查采集类型和实际执行的调试调用。
+
+| 现象 | 处理方法 |
+| --- | --- |
+| 找不到输入或目录中没有 `.bin` | 核对配置是否加载、路径覆盖和本次运行的实际落盘目录。 |
+| `unknown block magic`、`file too small` 或 TLV 长度异常 | 确认输入为完整的原始调测文件，未混入普通数组或已解析产物；再核对采集端与解析器是否配套。保留原文件，不靠改扩展名或裁剪文件头修复。 |
+| 文本出现占位 `-`，或日志提示元素不足/多余 | 检查采集元素数与记录的 shape 是否匹配；不要把占位当作零。shape 小于实际数据量时，文本可能只显示一部分，二进制仍保留实际采集的字节。 |
+| 报输出路径含非 ASCII 字符 | 改用 ASCII 字符组成的输出路径后重试。 |
+| 路径含空格时被拆成多个参数 | 在能导入配套工具包的 Python 环境中，改用 `python3 -m show_kernel_debug_data "<raw-bin-file>" "<artifact-dir>/parsed-one"`，绕过 shell 包装脚本的参数转发。 |
+| 已生成部分结果，但命令报错或缺少预期记录 | 按异常定位对应输入文件；目录解析可能在中途失败，已有文件不能证明整个目录已解析完整。 |
+
+## 官方说明
+
+asc-tools 工具相关详细说明见 [asc-tools 官方仓库](https://gitcode.com/cann/asc-tools)，按 `show_kernel_debug_data` 查找使用说明与样例。安装版本与当前文档不一致时，以配套工具帮助和对应版本说明为准。