Skip to content

kali20gakki/msAgent / skills/accuracy/loss-gnorm-diff-analyzer

loss-gnorm-diff-analyzer

Verified

端到端分析两侧 msprobe PyTorch statistics 原始 dump 数据(dump.json + stack.json + construct.json)与精度问题现象(loss / grad norm / 输出不一致等),按「确定性预处理 → 多视角候选发现 → 汇总排序 → 分级定向验证 → 报告校验」流程识别可疑候选节点并构建到目标异常现象的因果链,交付主分析报告与结构化证据记录。当用户提供两侧 dump 目录并需要定位训练精度问题根因时使用。侧别判定:用户指定 target(待分析侧)/ golden(参考侧)优先;未指定时按目录名与数据内容推断(npu/gpu 等仅为软线索,不作硬性假设);不可靠时询问用户。

references/dump-analysis-mechanism.md

View on GitHub
# dump 解析与差异计算机制

> 稳定领域知识:msprobe PyTorch statistics dump 的文件结构、字段语义、命名语法与 `dump_analyzer.py` 的计算机制。解析疑问、统计量解读疑问时查阅。本文件描述"数据是什么、脚本算了什么";对齐证据标准见 `alignment-playbook.md`;规则性义务的权威定义见 `hard-constraints.md`(HC 编号)——本文件内嵌的历史标注(vN/FM 编号)如与之出入,以 hard-constraints.md 为准。

## 1. 输入识别

### 1.1 dump.json 顶层结构

```json
{"task": "statistics", "level": "mix|L1|...", "framework": "pytorch",
 "dump_data_dir": null, "data": {"<节点名>": {"input_args": ..., "input_kwargs": ..., "output": ...}}}
```

- `task == "statistics"` 才支持。`data`/`md5` 模式:明确说明并停止。其他框架(如 MindSpore)的 dump 未适配——不承诺成功、不预设拒绝,按实际结构解析,失败时记录错误并停止。
- `data` 的键顺序 = **采集时的实际执行顺序**(时间序),解析时必须保留。
- `level` 为 `mix` 时同时含 API 级与 Module 级节点;`L1` 可能只有 API 级。

### 1.2 目录布局

不固定。递归发现 `dump.json`;`step<N>/rank<N>`、`step<N>/proc<PID>`、直接给定、深层嵌套都可能。proc 后缀可能是 PID(两侧不同、无 rank 语义)——此时按排序序号一一配对即可,但要在报告中说明。多 rank 时逐 rank 分析 + 跨 rank 共识。

### 1.3 stack.json / construct.json

- `stack.json`:`{序号: [[节点名, ...], [栈帧, ...]]}`,第一元素是**节点名列表**(共享同一栈的一组节点)。缺失时记录"堆栈不可用",不伪造堆栈证据。
- `construct.json`:`{节点名: 标签|null}`,格式不统一,常见三种形态:
  1. 值为 Module 节点名(API 节点 → 所属 Module 节点);
  2. 值为 `Apis_Between_Modules_RankN.M` 之类的分组标签;
  3. 大量为 null。解析时先识别形态再使用;只用于对齐佐证与定位,不作为唯一依据。

## 2. 节点与槽位

### 2.1 节点命名语法

```text
API 级:    <NS>.<算子名>.<调用号>.<forward|backward>     例 Tensor.permute.0.forward
Module 级: Module.<模块路径>.<forward|backward>.<调用号>  例 Module.encoder.0.Linear.forward.0
参数梯度:  Module.<模块路径>.parameters_grad.<调用号>     例 Module.proj_out.Linear.parameters_grad.0
```

- `NS ∈ {Tensor, Functional, Torch, Distributed, NPU, ...}`;算子名本身可含点。
- 调用号 = 该节点全名下的第几次调用。**同族调用号在两侧只在执行序列一致时等位**,族调用次数漂移后按调用号配对是系统性错配的主要来源。
- 变体命名:节点名可能出现 `_rank<N>` 后缀(如 `Tensor.__mul___rank14`,分片/多卡变体命名)。`dump_analyzer.py` 归一化族名时剥离该后缀;解读时它是"该调用是分片副本"的线索,不是新算子。

### 2.2 节点数据布局(四种)

```json
前向:        {"input_args": [...], "input_kwargs": {...}, "output": [...]}
前向(带参数): {"input_args": ..., "input_kwargs": ..., "output": [...], "parameters": {"weight": ..., "bias": ...}}
反向:        {"input": [...], "output": [...]}
参数梯度:    {"weight": [...], "bias": [...]}
```

- **反向槽位语义**:`input` = 上游传来的 grad_output(更靠近 loss 一侧),`output` = 向下游传出的 grad_input(更靠近参数/叶子一侧)。据此判断反向链路方向。
- **参数梯度**是"该模块参数收到的梯度"的直接观测,Norm 即该参数梯度的 L2 范数。

### 2.3 槽位元素

递归展开嵌套 list/dict 后,叶子有三类:

- **张量**:`{"type": "torch.Tensor|torch.distributed.tensor.DTensor|...FakeTensor", "dtype", "shape", "Max", "Min", "Mean", "Norm", "requires_grad", ...附加字段}`
  - DTensor 附加 `device_mesh`、`placements`(如 `Shard(dim 0)`)——**该张量是分布式分片**的标志,其统计量只描述本分片,与全量张量不可直接比较。
  - `Max/Min/Mean/Norm` 可能为 null(整型/uint8/bool 张量常见);可能为 NaN/Inf(记录原值)。
- **标量**:`{"type": "int|float|bool|str|None|slice|torch.Size|...", "value": ...}`。标量参数(切片、shape、device、antialias、scale 等配置)两侧不等 = 强结构证据。
- **None / 其他**:如实记录。

## 3. dump_analyzer.py 计算机制

### 3.1 对齐

1. **精确匹配**:节点全名相等(保持 target 侧 dump 顺序)。
2. **命名变体匹配**:两侧剩余节点按 `(归一化族, 调用号, 方向)` 匹配,要求双侧该键唯一(1:1)且至少一个张量槽位 shape 相同(挡掉分片副本)。质量低于精确匹配,报告中单独标注 `match: name_variant`。
3. 匹配质量评估:按归一化族的计数漂移表;family×方向 的跨侧 output 形状一致率(一致率 < 0.5 且对数 ≥3 → 标记"疑似编号错位/切分差异");名称序列公共前缀与分叉点上下文。

### 3.2 差异分级(每个张量槽位对)

| 级别 | 判定 | 含义 |
|---|---|---|
| structural | dtype/shape/槽位缺失/leaf 类型/DTensor 附加字段/requires_grad 不一致 | 结构分歧,统计量不可比或存在结构性差异 |
| significant | NRE ≥ 1e-3;或单侧 Norm 低于地板另一侧高于地板;或 NaN/Inf 参与;或(无 Norm 时)其他统计量相对差 ≥ 1e-3 | 显著数值分歧 |
| minor | 1e-6 ≤ NRE < 1e-3 | 轻微分歧(参考) |
| noise | 两侧 Norm 均低于 dtype 噪声地板 | 分母伪影,剔除 |
| none | 其余 | 一致 |

噪声地板(L2 量级):float64 `1e-15`、float32 `1.2e-7`、float16 `1e-3`、bfloat16 `1e-2`。阈值是**分析辅助**,不是根因规则:major 边界附近的分歧要结合 dtype 网格与算子语义判断。

逐槽位输出:四统计量的有符号差(target − golden)与相对差、NRE(`|‖t‖−‖g‖|/‖g‖`,statistics 模式下是**两侧统计量之比的相对差**,不是逐元素误差)、NaN/Inf 标记、噪声判定。

标量槽位:值或类型不等 → 计入标量参数差异(强证据,全文列出)。

### 3.3 首分歧锚点

按 dump 顺序(时间序)在匹配对中找第一个 significant 槽位,分三组:前向首分歧、反向首分歧、结构首分歧。**前向首分歧是误差最早可观测引入点的候选**;反向首分歧是最靠近 loss 的反向异常。注意:

- dump 顺序里前向/反向/优化器期算子(标为 forward,如 `_foreach_norm`)按真实时间交错,方向标签 ≠ 阶段标签;
- 首分歧之前所有匹配节点统计一致,只说明"dump 覆盖内更早处无显形",不排除差异在 dump 覆盖之外(输入/数据加载)已被引入。
- **归属语义**:首分歧所在的结构分歧簇是"最早显形归属候选";首分歧消费点之前的执行序被证实逐位一致时,该显形不能归因于任何更早环节——"窗口外更早已分歧"类归因必须给出窗口内可观测印记(哪个被捕获槽位承载它),无印记即无归因资格。
- **位序后果**:归属候选标注有位序后果——按现象类型选定的研判路径上(loss=前向、gnorm=反向),最早显形、未被有效域排除、非背景级的分歧簇必须排在所有显形更晚的候选之前(详见 hard-constraints.md HC-C3②)。**适用对象界定**:现象载体(现象的观测点,如裁剪输入悬殊、最终输出分歧)不是候选,不得占据位序锁定受益方;其机制层候选按机制环节自身位置(覆盖内/覆盖外)参与位序优先排序。位序锁定只在分歧本身在覆盖内显形的候选簇之间排序;机制环节在覆盖外的候选与覆盖内未排除簇的位序争议由位序优先裁决,研判路径选择不构成修正。**根因槽位承载**:排序第 1 位的覆盖内未排除结构簇同时承载报告的根因判断与"作为根因"置信度;其机制层(含覆盖外环节)以从属方式如实报告。"与现象载体连接未证实"不是让位条件——机制环节在覆盖外的候选与载体的连接默认不可证实,这正是排除迁移禁令存在的原因;窗口内产出与载体量级脱节类论证对它无否定资格(有效域)。**并入不转移根因主语**:指纹簇并入覆盖外候选的机制层时,合并后候选的根因表述仍以该指纹簇为主语,覆盖外环节降为其机制层/传播路径;"载体在覆盖外被生产"是载体定位事实,不构成根因身份——以"覆盖外生产路径不对称"为根因主语、指纹簇降为其机制层候选的反转,使根因表述退化为现象生产位置的复述(对任何覆盖外差异同样成立)。**载体分解非候选**:现象量在载体槽位上的分布分解(悬殊槽位清单、top-k 贡献、聚合值复现现象)是覆盖缺口锚点的内容、现象侧事实——它回答"异常在哪些槽位/有多大",不回答"为什么",无节点/算子/参数身份与机制语义者不具根因候选资格;机制归因下沉要求纳入覆盖外根因机制层的是覆盖内**结构/行为指纹**(dtype 簇、算子行为分歧、参数内容差、守恒违反等),而非载体分解;载体分解数值(量级差/有界性)不构成对机制候选连接的否定(有效域=被验证路径)。

### 3.4 参数梯度与 gnorm 估计

- 汇总所有 `parameters_grad` 节点的 weight/bias Norm:`gnorm_est = √Σᵢ Normᵢ²`。这是"dump 捕获到的参数"的梯度总范数估计;与框架自报 gnorm 交叉核对可评估捕获完整性(偏差大 → 有参数未捕获或存在累积反向未覆盖)。
- 每参数输出 `Norm²` 差(target − golden)排序表:gnorm² 差 ≈ Σᵢ (tᵢ² − gᵢ²),**按平方差贡献排序即"谁造成 gnorm 差异"的直接分解**,避免被绝对范数大但两侧相等的参数误导。
- 参数梯度是累积量(batch×sequence 上求和、可能多 micro-batch 累积);单次反向行只是其中一次贡献,量级论证要计入累积语义与捕获缺口。

### 3.5 dtype 分歧簇的消费点验证(研判方法)

脚本把 dtype/shape/槽位缺失等结构分歧聚成簇(dtype_clusters / shape_clusters)呈现,但**脚本不判定这些簇的语义影响**——豁免与定罪都必须由分析者在消费点完成:

1. **取值差异**:打开簇内代表槽位的原始统计,确认差异实质(bool↔float?值域?网格量化?),写明两侧各自的取值/统计。
2. **消费者识别**:找到接收该操作数的算子(同节点 output 消费者、或按执行序与 construct/栈定位下游节点)——控制类操作数(mask/索引/条件/scale)要看"谁在消费它来决定算不算、算多少"。
3. **消费处前向 + 反向行为对比**:在消费算子上分别核对①前向输出(两侧是否可比/等价);②反向输出或下游梯度(行为是否一致)。仅前向等价**不构成豁免**——控制操作数常改变反向分派路径(如 mask dtype 决定反向是 mask-then-grad 还是 grad-through)。任一环节无法在数据中验证时,该簇保持为候选并标注待验证,不得以"语义等价/适配实现"叙事合并豁免。**验证结论的有效域 = 被验证路径**:现象量被证实不经由被验证路径(被验证路径输出与现象量级脱节、现象来自窗口外/未捕获分支)时,对被验证路径的验证不可迁移到该簇在现象载体路径上的行为。**操作化后果(排除迁移禁令)**:该条件成立时,此前的"已排除/非因果"结论自动降级为"已核查(有效域=被验证路径);对现象载体路径未排除"——不得再标"非因果",该簇必须作为覆盖外候选的机制层候选保留在排序中,并明确回答"该簇能否解释覆盖外行为的单侧不对称"。触发条件由脚本机械判定(覆盖缺口锚点非空、聚合输入单侧悬殊且无窗口内生产者命中——见 3.8),摘要速览以 ⚠ 警告呈现。**对称义务**:有效域限制同样适用于**否定方向**——"该簇不可能解释现象/连接被否定"类降位论证若基于被验证路径上的行为(窗口内反向逐位一致等),其有效域同样是被验证路径;现象载体路径在覆盖外时,窗口内不可见不得外推为窗口外不可能,此类论证不得把覆盖内未排除簇降到覆盖外机制候选之后(hard-constraints.md HC-C5 排除迁移禁令与有效域)。**消费点集合的封闭性**:控制类操作数的"消费"同时发生在**前向分派**(算子按操作数决定怎么算)与**反向分派**(反向按同一操作数决定梯度怎么算/走哪条实现),因此"该簇全部消费点已验证/效应完全落在被验证路径内"类断言必须同时覆盖两个方向——只验证前向消费点时消费点集合不封闭,断言不成立。逐族可比性:反向数值对比的放弃必须逐族给出错配证据(形状不一致率、output 槽位语义差);其他族的错配不豁免本族——两侧形状一致的反向节点(statistics dump 中反向 input/output 四元组同形)是直接可比的,其跨侧比值沿反向执行序的放大本身就是"该簇反向行为单侧不对称"的窗口内指纹。**预测空间终端的枚举与排除完整性**:loss/输出类现象中,"现象载体"在 dump 内常表现为**多个**已捕获终端——最终输出算子(如 x₀ 重构 add)、预测头 Module 输出(unpatchify/重排前的 per-token 预测)、修正项操作数(进入输出组合的 x_t/噪声项)。各终端的分歧状态可以不同(最终输出差 2e-5 而预测头输出差 3.5%),因为组合/重排/CFG 类后处理会稀释或继承上游分歧。终端枚举程序:从现象类型出发列出全部已捕获的输出空间 Module 节点(`Module.*head*`、输出 Linear、最后一级 LayerNorm 链)与全形状 Tensor 终端,逐一给出两侧四元组与分歧状态;"某簇非因果"的排除必须在**全部**终端上成立。两侧同形状的全形状节点(含其在窗口内被捕获的生产者链,如"LN 输出→调制 mul→末残差 add→预测头"链)是可靠对比对象——"分片激活合并语义未证实"的例外只适用于两侧形状不同的分片统计,不适用于同形状全形状节点;调制 scale/门控位级一致而其作用对象分歧时,分歧来自上游传播(参数簇或更早),该链是排除论证必须覆盖的消费路径。**"窗口内无生产者"的反查程序**:该断言可被单次反查证伪,义务程序:①对目标操作数四元组 (Max, Min, Mean, Norm) 在同侧全 dump 的 output 槽位中反查(容差取统计网格,如 Norm 相对 1e-6、Max/Min 逐位;`_rankN` 副本一并索引);②两侧分别执行;③任一侧命中即断言推翻,命中生产者的输入操作数逐槽分解(分歧从哪个操作数进入),沿链继续反查至分歧进入点或覆盖边界。反查留痕(搜索范围与容差)写入报告 §2。**输出侧双假设闭合程序**:对"操作数语义存疑"类锚点(传错张量/错误求和项/错误缓冲),输入侧生产者未捕获时**闭合义务不消失,转到输出侧**:①列出两种假设——H1"操作数=语义应然者"(如插值位置嵌入表)、H2"操作数=实测捕获者"(如填充后图像张量);②按逐元素加法恒等式分别预测消费输出统计:mean(out)=mean(A)+mean(operand_X)、Max(out) ∈ [Max(A)+Min(X), Max(A)+Max(X)],X 分别取 H1/H2 的已知统计;③与实测输出比对:仅与一侧闭合(Δ 在捕获噪声内)即判别该侧真实参与运算,另一侧假设被否证;④双假设都无法闭合时才允许写"闭合不可判别",且必须列出尝试过的恒等式与两侧预测值。附加佐证:同一语义槽位两趟独立捕获逐位一致(伪影需多次协同错读)、语义应然者在全 dump 仅出现在生产链与写入值槽(死写、无下游消费)。**背景级入口差异的判定程序**:①找引入点——该分歧最早的合理产生环节是否在 dump 覆盖外(数据加载/样本选择/环境配置;覆盖内首观测节点只是影子,不是引入点);②问单侧语义——能否说出"哪一侧错、错在什么机制"?两侧各自合法地处理了不同数据 = 无单侧机制语义;③结论:①成立且②答"否" → 背景级入口差异,保持候选但按硬规则排位(不得高于覆盖内未排除指纹簇、不得承根因主语),其"独立充分性"(不同输入必然不同输出)记录为无判别力论证。反例边界:若两侧**本应同数据**且一侧加载了错误样本(有单侧语义),它不是"背景级"而是覆盖外缺陷候选——但此时必须回答机制归因下沉义务(覆盖内哪个指纹解释其单侧性)。

### 3.6 张量同一性反查(关系型证据的查询模式)

statistics 模式只有四统计量,但"统计四元组相等"这类**关系型证据**不受绝对值型失真影响,是定位"传错张量/缓冲区别名"的利器:

1. **操作数身份反查**:发现某操作数槽位统计可疑时,用其 (Max, Min, Mean, Norm) 四元组在同侧全 dump 中反查输出匹配的节点(注意浮点打印精度,逐位比较):
   ```python
   for name, node in data.items():          # 同侧 dump.data
       out = first_tensor_stat(node["output"])
       if out == suspicious_quad: print(name)
   ```
命中生产者后核对:消费操作数 ≣ 生产者输出?语义上应该是谁(与对侧同名节点的对应操作数比对)?
2. **同侧自比(强于跨侧对比)**:"本侧消费操作数 ≣ 本侧生产者输出"与"对侧同样一致"联合判断——一侧不一致、另一侧一致,即为单侧传错张量的直接证据,不受两侧输入不同、统计局部失真的影响。
3. **绝对值型 vs 关系型证据**:绝对值型断言("该统计是 NaN/65504/量级异常")依赖捕获保真度,可能被缓冲区别名等失真污染;关系型断言(两槽位统计逐位相等、排序一致、跨节点身份匹配)只依赖相对关系,失真怀疑不构成折扣理由。证据冲突时(区域失真已证实 vs 槽位关系指纹),关系指纹优先核查。
4. **锚点操作数溯源程序(批量,固定步骤)**:对进入因果链的每个锚点节点(前向/反向首分歧、首显形、污染点、现象终点),列出其全部操作数槽位并批量溯源,**不要等"看起来可疑"才查**:
   ```python
   quads = {}                                  # 同侧输出四元组索引(一次遍历建立)
   for name, node in data.items():
       q = first_tensor_stat(node["output"])
       if q is not None: quads.setdefault(q, []).append(name)
   # 对锚点节点每个操作数叶子 q:quads.get(q) 即同侧身份命中列表;
   # 命中 ≠ 该操作数的语义生产者(按执行序/栈定位)→ 传错张量/缓冲区别名。
   ```
输出溯源表(逐操作数一行):操作数槽位、四元组、同侧身份命中、语义生产者及其输出四元组、对侧同名节点同位操作数的分布性质(有界性/量级/dtype 来源)。**栈帧定案**:溯源表须含"栈帧文本"依据——更新类循环(`mul_(s).add_(x, alpha=t)` 同构公式:EMA 更新 x=参数本体 vs Adam exp_avg 更新 x=梯度,标量指纹 0.9996/0.0004 对二者无判别力)的语义角色以栈调用行文本定案(如 `ema_param.mul_(rate).add_(src_param, alpha=1-rate)` 的 `src_param` 即参数本体)。`anchor_stacks` 已覆盖速览高置信锚点、聚合悬殊、反向产生分歧、守恒违反节点,速览锚点行直接渲染栈帧(含调用文本)。**参数/权重派生张量**(位置嵌入、常量表、旋转编码等)与输入数据无关,跨侧分布性质可比,"两侧输入不同"不构成对它的豁免;其操作数身份或分布性质单侧异常,即为该侧"消费了错误张量"的直接证据。
5. **反查/对齐/普查/多 rank/参数普查/首分歧/链增益工具化**:上述模式的批量形态一律用 `scripts/query.py` 子命令完成,不再手写一次性脚本(用法详见脚本头注释);承报级普查的折叠执行口径(族级批量调用一次+代表实例抽样,禁逐实例枚举/自建普查脚本)以 SKILL.md §0 与 hard-constraints.md HC-C11⑥ 为权威:
   - `quad <dump> --from-node <节点> [--from-slot <槽> | 省略=批量] [--tolerance t] [--all]`:四元组身份反查。单槽=溯源某操作数;省略 `--from-slot`=批量模式(该节点全部张量统计槽逐槽一行,含 DTensor 等张量子类统计槽,末尾汇总"有命中槽位 N/M");`--tolerance` 相对容差(容差模式下双 NaN 视为匹配——逐位模式下 IEEE NaN!=NaN 恒无命中);`--all` 把索引域从 output 槽扩到全部槽位。输入侧逐位无命中+输出侧自命中=覆盖缺口形态(配合 §3.8 聚合输入悬殊解读)。
   - `align <dump_t> <dump_g> [--family 族名]`:跨侧对齐。省略 `--family`=汇总模式(逐族两侧计数漂移表,|Δ| 降序,--grep 过滤);`--family X`=实例配对模式(该族第 k 个 ↔ 第 k 个:T/G 名+order 并排,邻族 ±K 上下文;同位邻域不一致时打"⚠错位嫌疑"并给首个分歧行)。族计数漂移/调用号错位场景(TP 分片、增删调用、重计算)先跑 align 再谈数值对比——手工推断错位是实测过的最大单项返工成本。
   - `survey <dump_t> <dump_g> {backward|forward|only}`:批量分歧普查。backward/forward=同名节点对按公共 output 槽分桶(逐位一致/minor/≥1e-3/非有限/单侧空)+ Top-N NRE 行;only=单侧独有节点按族汇总(两侧计数+maxNorm,平台实现替换对直接可见)。供 HC-B6 全窗口普查表与发现视角 5(未匹配节点)直接取数。
   - `ranks <dir_t> <dir_g> [patterns...] [--slot 槽] [--top N]`(多 rank 布局专用):两侧 rank 目录逐 rank 分桶汇总(逐位一致/minor/≥1e-3/非有限/单侧空0/maxNRE/max 悬殊比)+ 跨 rank 显著明细(NRE 降序,含 rank/节点/槽位/NormT/NormG)。显著分歧仅在部分 rank 出现(rank 集中显形)或全部 rank 显著但跨 rank maxNRE 悬殊≥1e3×(量级集中)时显式告警。**两条已知限制**:(a) 逐 rank Top-N NRE 表有截断——量级更极端的邻簇行可把目标族挤出 Top-N,读 Top 表**不能替代**按族模式(patterns 传族名/节点名)的定向复核;(b) analysis_summary.md 的逐 rank 章节与「跨 rank 共识族表」(§3.7)必读(rank 专属族直接可见),但共识表只覆盖进入 Top 差异的族,同受 Top-N 截断约束。单 rank 布局不触发 HC-B8,无此义务。`--quads`:显著行之后**逐 rank 打印全量四元组明细**(T/G 四元组+槽位+kind,非仅显著行;每 rank 行数受 --top 约束)——HC-B8②「承重族逐 rank 数值分列呈报」的取数工具,把承重族的逐 rank 证据一次导出(此前需按 rank 手写脚本聚合)。
   - `params <dump_t> <dump_g> [--top N] [--grep 关键词] [--threshold t]`(参数槽全库普查):同名节点的 parameters 槽 + 顶层张量叶节点(param_grad 形态)逐槽分桶(逐位一致/聚合统计差/统计差/形状差/缺失)+ NRE ≥ 阈值槽位的方向统计(T>G/T<G 计数——§3.9 程序二 H-content/H-artifact 判别的输入:方向恒定只支持 H-artifact,不构成对 H-content 的排除)+ NRE 分位与 Top-N 明细(全精度四元组)。「N 槽位全部同向」「参数槽 X% 达显著」类断言(HC-B4 计数义务)直接从本工具取数,不再手写参数普查脚本。
   - `first <dump_t> <dump_g> [patterns...] [--threshold t] [--direction forward|backward|both]`(首分歧机械产出):按 T 执行序扫描同名节点对,逐方向找**首个显著数值分歧**(NRE≥阈值的槽位),打印该节点全槽位双侧对照 + **前置核查行**(更早匹配节点数与其最大 NRE——"无更早分歧"主张直接可引);另给结构首分歧(首个 dtype/shape 不一致,附 align 甄别提醒:先排错配再当真分歧)、首个非有限槽位(advisory)。前向=非 `.backward` 节点、反向=`.backward` 节点。**口径警告**:数值首分歧扫描**全部槽位**(含 input_args/parameters),比"仅输出槽"口径更严——非模型路径张量(如 bool/int 型比较算子的输入)可能在输入槽先达阈值;引用"首个/无更早"类断言时按实际扫描口径如实表述,限定槽位范围的断言注明范围。
   - `gain <dump_t> <dump_g> <patterns...> [--direction ...] [--threshold t] [--amp t] [--limit N]`(链增益剖面):模式定向逐节点行输出 r_in(input* 槽最大 NRE)/r_out(output* 槽最大 NRE)/增益=r_out/r_in,标记 **★分歧制造**(r_in<阈值而 r_out≥阈值——输入一致输出分歧,制造点直接指向)与★本地制造候选(输入输出均分歧、增益
     >1);汇总 r_out 分位(p10/p25/p50/p75/p90/max)、首个 r_out≥ --amp 节点(放大链入口)与分歧制造节点数。用于"继承型 vs 制造型"判别与反向放大链取数(此前需手写 profile 类脚本)。r_out 显示"—"=该侧该槽缺统计(槽位缺失簇形态,另见 §3.7)。

### 3.7 输出

- `analysis.json`:全量结果(对齐统计、首分歧、标量差异、dtype/shape 簇、Top 差异、参数梯度全表、未匹配分组、命名变体对、锚点堆栈、守恒检验、操作数身份对照等)。
- `analysis_summary.md`:人读摘要(供 LLM 第一轮阅读)。
- 多 rank:逐 rank 分析 + 跨 rank 共识族表;`--rank`/`--step` 可聚焦。

### 3.8 脚本关系型锚点:分侧守恒检验与操作数身份对照

**分侧守恒检验**(`conservation` 字段):对归约类反向节点(output 沿某维按整数倍 N 小于 input 的等分求和类,如 repeat_interleave/sum 类反向)计算逐侧 `N_eff = mean(out)/mean(in)`。等分求和的数学恒等式为 mean(out) = N·mean(in):

- **一侧守恒(N_eff≈N)、一侧违反 → 违反侧为缺陷侧第一指向**(该侧归约实现/精度不足,或该侧捕获不忠实——同位置)。这把"哪侧数值偏大"的方向性谜题转换为"哪侧违反数学恒等式"的侧别判别,是归约类分歧的首选判别证据。
- 两侧**同样违反且 N_eff 相近**多为 mean 类反向的语义性"违反"(mean 反向本就不是求和),脚本已过滤;两侧 N_eff 明显不同的仍会输出。
- 限制:mean(in)≈0(<1e-12)时检验无意义,自动跳过;组距不均的求和两侧都会"违反",此时两侧应同样违反(已被过滤逻辑覆盖);bf16 网格量化给 N_eff 带来 ~0.4% 级模糊,阈值 2%。

**操作数身份跨侧对照**(`operand_identity` 字段):对每个匹配节点对的每个操作数槽位,在同侧"全部节点输出四元组索引"中反查身份命中。正常情况操作数 ≡ 其生产者输出(同一张量两次捕获),**两侧都应有命中**;一侧有命中、另一侧无 → 命中存在性不对称:

- 提示"单侧消费了非其生产链上的张量"——传错张量、缓冲区别名,或(参数派生操作数)单侧把错误张量传进了算子。结合命中名单(命中在哪个语义区域)与对侧四元组判断。
- **参数/权重派生操作数**(位置嵌入、常量表等)与输入数据无关:其跨侧分布性质差异(如有界 [-1,1] vs ±20)即使两侧都"无命中"也有研判价值,按 mechanism 3.6 同侧自比展开。
- 假阳性来源:捕获时序/缓冲别名造成的单侧命中缺失(陈旧统计可能命中"旧"节点)、就地写算子的自命中(input ≡ 自身 output)、漂移区的错位配对。命中 ≠ 定罪,逐个按 3.6 的消费点程序复核后再作为证据。
- **语义结案义务**:身份命中 ≠ 语义正确——命中只证明"操作数确实是该张量"(捕获自洽),不证明"该张量应该出现在此槽位"。结案前必须与对侧同名节点同位操作数比对(锚点行已渲染两侧四元组):两侧不可公度(不同张量,非噪声级差异)且该槽位两侧语义应相同时,即为单侧语义缺陷候选,保持候选证据地位进入排序;可判别时用消费点输出对两种语义预期分别做算术闭合(例:embeddings 求和的输出 Mean 与"画布和"闭合、"位置嵌入和"否证,则实际参与运算者是画布——单侧语义缺陷坐实)。
- **消费节点输出四元组**(`quad_output`,v8):示例条目附该消费节点首个有限输出槽位的四元组——判别"真实消费错误张量 vs 捕获陈旧"的关键:捕获陈旧只解释**输入侧**槽位为何读到旧内容,解释不了**输出侧**为何呈现"旧操作数参与运算后的结果"。逐元素加法例:输出 Max ≈ 操作数A Max + 操作数B Max(组合界 ≥ A Max + B Min)与哪个四元组闭合,实际参与运算的就是谁。把某锚点判为"捕获陈旧"前,必须先用输出四元组完成该算术闭合(hard-constraints.md HC-D2 算术闭合)。

**锚点置信度与覆盖语义**:

- **操作数身份组置信度**:`high` = 组内全部来自精确名匹配对、且该族两侧计数无漂移(对齐可信区);`low` = 含命名变体匹配对或位于计数漂移族(分片/错位配对是主要假阳性来源,如 16-vs-8 卡合并 dump 中 block 区的同族错位)。低置信组只作线索、不得作为定罪证据;高置信组仍须消费点复核。摘要顶部的「决定性锚点速览」只收高置信组。
- **反向内产生分歧**(`backward_created` 字段):匹配反向节点对**输入槽位(grad_output 侧)全部可比四元组逐位一致、输出显著分歧** → 分歧在该反向内部产生而非继承,机制层搜索聚焦该反向实现路径(控制类操作数、dtype 分派)。注意反向还消费**不可见的前向保存张量**:对应前向输出两侧一致 → 分歧在该反向实现本身;前向输出已有分歧 → 可能继承自保存张量(用前向对比判别)。与守恒检验联合:守恒违反 + 输入逐位一致 = 该反向数值实现缺陷的强指纹。
- **梯度覆盖缺口**(`coverage_gap` 字段;API-only dump 无 paramgrad 节点时不产出):dNorm² 大的参数梯度其所属模块反向未捕获/未配对 → 梯度分歧产生于未捕获反向段,"差异来自窗口外"从推断升级为可核查的结构事实;此时机制层搜索必须回答"最后一个被捕获锚点与未捕获段之间,哪个覆盖内指纹(控制类操作数差异、结构分歧簇)能解释该模块族梯度的**单侧不对称**"。
- **聚合输入单侧悬殊**(`agg_single_sided` 字段,v7):norm 类聚合节点(`_foreach_norm`/`vector_norm`/`norm` 等,clip_grad_norm_ 的输入即 .grad 本体)的输入槽位跨侧 Norm 单侧悬殊(一侧 ≥100× 另一侧,≥2 个槽位)。API-only dump 无 paramgrad 节点时,这是覆盖缺口的**等价指纹**:脚本进一步对每个悬殊槽位做同侧输出四元组反查,无生产者命中的槽位占多数 → `window_out=true`(悬殊输入的生产/累积路径不在被捕获算子输出中),与覆盖缺口同样触发「⚠ 排除迁移禁令」。
  - 解读:`window_out=true` 的含义是"现象载体的生产路径未被捕获",**不是**直接断言根因在窗口外——窗口内反向的真实分歧同样会写入 .grad(此时差异根源仍在窗口内,注入只是路径形式);机制层候选必须回答"能否解释聚合输入的单侧不对称",覆盖内候选(控制类操作数簇等)与覆盖外候选同台排序(按位序优先硬规则)。
  - `bwd_max_norm_same_side`(窗口内反向输出 max Norm)仅作量级参照,不作为 window_out 判据(grad 种子/直通反向可能抬高该值)。

### 3.9 状态类主语归宿与参数槽位双假设研判

本节程序针对的失败形态:发现层正确(节点/簇/数值均被发现且引值属实)而裁定层把结论主语让渡给"状态类叙事"(缓冲载有陈旧内容)或过早排除结论承载通道(参数内容差)。规则权威定义在 hard-constraints.md(HC-C1③/HC-C5⑥/HC-C7/HC-C8①/HC-D2⑥),本节是操作程序。

**程序一:状态类断言的归宿判定**。对候选谓语执行 HC-C1③ 正典谓语改写测试——改写句式固定为「载体(或其输入缓冲)+候选谓语原文」,只把宾语替换为载体/其输入缓冲,谓语保持原文:

- **失格(载体状态复述)**:断言只刻画"载体/其输入缓冲载有什么内容"(陈旧、非本步产物、参数量级残留、悬殊、为零……)——它回答"现象是什么"而非"为什么不同"。改写后语义不变即失格;注意不得用偷换宾语/谓语的变体改写(如改写成"缓冲本身"后声称语义改变)来通过测试。归宿三选一,不得占排序第 1:①HC-C8③ 回退呈报的覆盖外定位/并列发现;②覆盖内指纹簇因果链的机制层环节(HC-C7);③若该内容差能在覆盖内找到生产者锚点(输入一致而输出分歧的算子),升格为行为分歧簇正常参与排序——此时主语是那个生产者节点,不是缓冲状态。
- **通过**:谓语承载机制语义(某算子/某实现的差异制造了该内容差)且主语是节点/算子/参数身份。
- **配套核验**(防"失格候选借道入位"):凭"载体值/聚合输入值/现象值复现"入优先组无效——那是 HC-C1① 载体证据,不是锚点节点级验证(HC-C8①);对覆盖内簇断言"与载体无连接/无机制通道"只能落"本步捕获路径内未观测到连接"(HC-C5⑥),覆盖外状态候选存在时一切连接否定按该条降级;指纹簇承主语 + 覆盖外定位两者并呈时,必须给出至少一个机制可达的通道假说 [待验证](跨步累积/早期步残留/未捕获写入路径;通道假说不要求量级闭合,HC-D7①/HC-E2 末款)——只断"无连接"即按主语让渡违规处理(HC-C7)。

**程序二:参数/常量槽位 Max/Min 恒等 + Mean/Norm 分歧的研判**(HC-D2⑥)。该形态与两类假说均相容:H-artifact(单侧捕获 Mean/Norm 归约失真——Max/Min 为精确统计不受归约影响,恰是恒等的原因)与 H-content(参数存在非极值元素级真实扰动——正是"参数携带误差"通道的数据形态):

1. **先判槽位身份**:该槽是否根因候选主张的差异制造节点(或其锚定链节点)的输入操作数/parameters 槽?是 → H-content 必须作为并列机制假说呈报 [未排除/待验证],两侧四统计量并列给出。
2. **排除门槛**:把 H-content 写成"已排除"需要不相容证据(证明该形态与内容扰动原理上不可共存);仅有形态学相容性证据(方向恒定/幅值反相关/网格量化)时,反证条目改写为"未排除(伪影假说与内容扰动假说并存,形态学支持前者但无判别力)"。
3. **判别手段(尽力而为,不强制)**:查同参数其余捕获点(parameters 槽、param_grad 槽、跨节点同四元组命中)是否复现同一形态——恒等复现指向系统性差异而非单点捕获失真;对消费节点做输出侧双假设闭合(HC-D2④),判别实际参与运算者。Max/Min 恒等只约束极值元素,**不构成内容一致的证明**(内容一致要求四元组全等)。判别结论的有效域=采证节点(跨节点适用见程序三)。

**程序三:闭合有效域与跨节点泛化禁令(HC-D2⑦ 操作程序)**——闭合有效域=采证节点:A 节点上闭合成立(输入/权重逐位一致+输出统计一致)不证明 B 节点闭合成立;B 节点上分歧操作数槽的内容差假说不得因 A 节点闭合被整簇排除。操作程序:

1. **跨节点同判前先核前提**:对每个拟推广的节点,引其自身输入/输出槽对照值核对该闭合的前提(尤其"输出统计一致")。输出分歧 → 前提不成立 → 禁止同判,该节点回到程序二第 1 条(H-content 并列呈报)。
2. **输出分歧节点上,分歧≥显著阈值的操作数槽=唯一在册差异源**:输入逐位一致而输出分歧时,该槽的 H-content 保持承报(候选身份或双假设),除非以该节点自身证据完成判别。
3. **算子实现差机制的兄弟实例核查**(机械判别测试):主张"算子实现差在相同输入上制造分歧"前,用 `query.py diff`/`gain`(同族 patterns)核查同族同精度、输入逐位一致的兄弟实例是否同型显形——存在输入一致而输出不显形的兄弟实例时,算子机制与显形分布矛盾,必须并列呈报参数内容差机制[未排除]并如实对照该不对称。
4. **候选池收缩约束**:把一条通道(如参数槽簇)整簇列为"已排除(伪影)"前,逐节点核对:存在输出分歧且唯一在册差异源属该通道的节点时,该通道必须保留至少一个候选身份或双假设承报——整簇消失即违规。

**程序四:内容正确性结案核查(HC-D2⑤ 公度性判据操作程序)**——单侧身份命中且极值形态结构性不同(一侧精确钳位/离散取值、对侧连续大值,Norm 接近不足为公度证明)、槽内容为参数/常量派生张量时,不得以"生产链闭合"(写入值→消费值一致)结案"非因果"、归因背景级输入差异。操作程序(把任一"操作数身份不对称"锚点结案为非因果前逐条执行):

1. **四统计量形态对照**:两侧同槽并列比对——极值形态(精确钳位/离散 vs 连续)、取值模式、符号模式任一结构性不同即属不可公度(HC-D2⑤ 判据);Norm/Mean 接近**不构成**公度证明。
2. **槽位内容来源定性**:该槽内容是输入数据的直接传播,还是参数/常量/缓冲派生?后者不适用"输入类差异"豁免(HC-D12②)——其跨侧形态差异是单侧异常的有效证据。
3. **生产链闭合的效力边界**:写→读一致/身份指纹命中只闭合"未传错张量";"被写/驻留内容是否=该槽语义应然内容"须独立核验(对侧同槽对照+该槽语义预期的量级/形态对照),未核验前不得结案非因果。
4. **背景级归因须量级核算**:把内容分歧归因于输入样本/配置差时,给出该背景源到该槽的演化路径与幅度上限,与实测分歧幅度对照;核算不闭合的归因无效,槽位保持单侧语义缺陷候选参与排序(锚定在消费该内容的节点,HC-C7)。

**程序五:源/放大器位序与同口径核验(HC-C3⑧⑨ 操作程序)**——"输入已含分歧、逐层放大"的传播机制不得居位序第 1 挤压全实例同型、有侧别对应的输入侧结构分歧簇(唯一在册差异源),候选间验证口径须一致。操作程序(排序落盘前执行):

1. **角色标注**:资格表每行标注机制角色——差异源(输入一致而输出分歧的制造节点;全实例同型+有侧别对应的覆盖内结构/内容分歧簇)或放大器(锚点输入已含 ≥1e-3 分歧、以增益/放大承报的传播机制)。差异源资格仅限覆盖内制造环节候选;差异产生点在覆盖外的候选(含锚定节点=现象载体/聚合输入的消费节点、谓语为机制假说形态者)角色=覆盖外归属/症状簇候选(HC-C3⑥),不得标注为差异源。
2. **源优先重排**:存在未排除差异源时,放大器候选位序不得高于任何未排除差异源;放大器并入差异源因果链的传播/放大环节(HC-C7)。全部在册差异源已以各自本节点证据排除/判别闭合时,放大器方可承主语。
3. **同口径核验**:逐一核对各候选的验证要求是否同一口径——对结构/内容分歧簇,"结构分歧实证"(双侧锚点槽位直接核验,HC-C8① 类型)即满足锚点节点级验证,其消费点行为验证(HC-D1)是维持未排除的持续义务,不是入优先组的额外门槛;不得一边允许他候选携带覆盖外缺口、一边以"机制后果未直接验证"压低本类候选(HC-C3⑨ 不对称标准)。
4. **形态对照效力域复核**:凡引用"某机制原理上无法产生某显形"(HC-C6④)参与排序者,核对该引用只用于通道判别、未用作跨簇位序依据(HC-D5 条)。
5. **迁移核对(HC-C5⑦)**:排序落盘前核对排除迁移禁令触发指纹(梯度覆盖缺口锚点非空/聚合输入单侧悬殊且无窗口内生产者命中/摘要「⚠ 排除迁移禁令」横幅在册)——成立时,资格表中覆盖内结构簇(dtype/控制类操作数/形状簇)及内容分歧簇的"已排除/非因果"状态逐簇改判为"未排除(HC-C5 迁移)",以机制层候选参与排序并明确回答"该簇能否解释聚合输入/参数梯度的单侧不对称"(机制层连接判据=作用域/指纹的定向一致;前向/loss 闭合不闭合反向域机制候选——HC-D2⑤ 前向闭合效力边界;量级比较不构成对连接的否定)。前向闭合+窗口内路径缺席+量级比较不得被用作对已验证覆盖内差异源的整簇排除。压缩恢复后以 investigation.json 的 anchor_checklist/覆盖缺口记录为准执行,不依赖重读摘要全文。

**执行成本边界**:程序五与候选资格表填写**同趟完成**——步骤①的产出即资格表"机制角色"列、步骤②即位序排列本身、步骤③仅对验证类型不同的候选对逐一核对(同类型候选默认同口径,在归一判定列留痕即视为已核对)、步骤④随资格表"反证"列填写核对、步骤⑤即资格表"未排除?"列的迁移改判重写(表格重写非重新验证)。不设独立复核阶段,不重复通排已排候选。

**程序六:输入槽状态差候选的来源定性与锚定(HC-B3③/HC-C8① 联动)**——first 锚点的分歧槽位为输入槽(如 RNG 序列差)时,该节点不得误读为"输入一致而输出分歧"的制造节点;输入槽状态差簇(消费节点其余输入一致+唯一分歧输入+输出显著分歧)不得因"制造环节未捕获"失去锚定。操作程序(候选登记与资格表填写同趟执行):

1. **槽位级转录(HC-B3③)**:first 首分歧锚点落账必须转录分歧**槽位名**与该槽双侧四统计量;候选资格表"输入一致性自证"必须附对应输入槽双侧值引用(证据 ID),无引用的自证无效。分歧槽为 input_args/parameters 类输入槽时,该节点**不得**登记为"输入一致而输出分歧"的制造节点。
2. **来源定性**:对输入槽状态差逐槽定性——(a) 窗口内生产者产出该差 →继承形态:候选主语上溯生产者,本节点并入传播链(HC-C3⑧);(b) 差异可由跨设备环境差完全解释(RNG 序列、输入数据、时钟等**无单侧缺陷语义**的覆盖外来源)→ 背景级关联显形:本节点输出分歧不承根因主语、不入优先组,作为环境差下游影子或独立环境差候选如实登记(HC-C4 关联;定性不写成"已排除"终态);(c) 差异直接以状态形态进入窗口且不可归入 (a)(b) → 继续步骤 3。
3. **分维闭合锚定**(锚定节点=该消费节点;验证对象=候选主张的差异制造环节——载体值/聚合输入值复现不算,HC-C8①):
   - 内容维闭合:该槽内容参与本节点算术且输出差可由该槽差解释——算术恒等式逐位成立,或该槽与本节点输出/下游的身份链闭合 → 锚点节点级验证=已验证,具优先组资格。
   - 类型/表达维闭合(dtype、表示形式、标量参数类槽差):本节点其余输入槽两侧一致(逐槽核验)且输出两侧分歧 ≥1e-3 → 差异经算子内部分派/路径选择影响行为;**类型维差不要求先行证明两侧内容语义等价** →锚点节点级验证=已验证,具优先组资格。
   - 均不成立 → 症状簇候选(HC-C3⑥ 位序),如实标注未闭合维度。
4. **成本边界**:本程序复用已有取数(first/单节点 diff/quad),不新增全库扫描;与候选资格表填写同趟完成,不设独立复核阶段。

## 4. 已知陷阱(解析侧)

1. **反向调用号语义**:反向节点的调用号是该族反向调用的计数,两侧只有在反向执行序列一致时才等位;重计算、梯度累积、分支差异都会使其错位。以形状一致率与 Module 锚点校验。
2. **proc/PID 目录名**:不是 rank,两侧必不同,按序号配对。
3. **construct.json 形态不一**:先识别再用;标签 ≠ 模块路径。
4. **大数据文件**:单文件可达数百 MB;不要直接读入对话,用脚本与 `analysis.json`,抽查原始节点用小的 `python3 -I` 片段。
5. **bf16/fp16 统计网格**:设备端归约产物可能按 dtype 网格量化,跨设备 ±1-2 ULP 的 mean/l2 差属伪影;max/min 为精确统计,是"已证实差异"的可靠判据。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall