gfx-triage git:20261108.3925321A

Immutable. This exact content never changes and is served at /api/v1/blob/2d348948ac79e63a.

---
name: gfx-triage
description: S2Arm 画面问题分诊与根修：拿到「花屏 / 贴图错 / 闪烁」「不满屏 / 宽屏两侧异常 / 拉伸」「没走直连 / 直连异常」任一类问题时先读本 skill。按症状分到三份排查手册，读 host.log 指定行定位，再按先红后绿写单测、根修。
---

# 画面问题分诊（gfx-triage）

你在帮 S2Arm 定位并根修一个画面问题。原则：**先看读数再猜原因，先写会红的单测再改代码，修机制不修症状**。三份手册是知识库，本文件只管分诊顺序。

## 0. 先确认三件事（每一件都看 host.log，不靠印象）
1. **图形模式**：grep `图形模式：`。是「没有直连库」→ 直接去 [直连异常与退回通用](../../docs/排查/直连异常与退回通用.md)。
2. **屏幕比例与宽屏开关**：grep `宽屏：` 和 `出图层已挂到根视图`。问题只在两侧条带，或者整幅比例不对 → 去 [不满屏与宽屏异常](../../docs/排查/不满屏与宽屏异常.md)。
3. **新红行**：grep `【红】`。任何新出现的红行先读完再往下走。

都不是 → 去 [花屏与贴图错](../../docs/排查/花屏与贴图错.md)。

## 1. 症状 → 手册 → 先看哪几行

| 症状 | 手册 | 先看 |
|---|---|---|
| 切场景后整屏发白 / 背景成片噪点 | 花屏 | 开 `DM_NVN_NONFINITE_FILL=1` 做反证，能复现就是旧字节 Inf/NaN |
| 高光 / 反射逐帧闪 | 花屏 | `same-pass feedback sampling up to frame …`；用 `DM_NVN_SHOT` 连拍，按块量或直接看连续帧 |
| 远景糊 / 锐不对，日志里大量重新登记 | 花屏 | `sampler pool up to frame … registered again` |
| isnan 挡不住的黑块 / 白块 | 花屏 | `graphics/metal/tests/t_mathmode.m`，编译数学模式 |
| 整局 16:9 加黑边 | 宽屏 | 总开关：环境变量 > 用户设置 > 包内能力清单 > widen_verified.tsv |
| 某页两侧残留旧帧 | 宽屏 | 截图帧号在不在「出图原比例居中 / 离开原比例页」区间里；「其中纯色 / 小图层按原样铺满」计数 |
| 暗化 / 模糊底只盖中间 | 宽屏 | 被采样的贴图有没有登记成整屏副本（定因中，见手册） |
| 整幅横拉 | 宽屏 | 是不是 Vulkan / GL 直连（第三层做不到） |
| 图形模式：没有直连库 / 起局报「游戏文件缺失」 | 直连 | `图形模式：没有直连库（依据 …）` 行与上面的【红】（链号不符、缺 shader_map.tsv / lib.idx）；`entry*.direct_missing`。11-07 起没有通用模式可退，导出诊断包反馈 |
| 首遇卡顿 | 直连 | `直连着色器现编汇总`、`shader loads:` 行 |
| GPU 线程异常 / 着色器取码报红 | 直连 | `S2AShaderFault` 红行的地址链 ①②③ |

## 2. 复现
- 优先在 Mac 局上复现：同一套通用自动玩家（AI 看屏驾驶，学过的路线自动回放）、同一个屏幕尺寸（`S2A_SCREEN_W` / `S2A_SCREEN_H`）、同一个开关。
- 修前在同配置下必须能复现。复现不了就写明「本机型复现不了」，交给能复现的设备复验，不要宣称修好。
- Mac 局截图拿到的是出图窗口，宽屏两侧可能截不到，这时以诊断行读数或真机截图为准。

## 3. 定因
- 把出错的那一笔 / 那一张贴图定位到具体对象：序号、池、偏移、格式、它是谁写的（拷贝 / 渲染 / 计算 / CPU）。
- 临时诊断行放在临时分支上，带环境变量开关，不合入。
- 一个假设一局：一次只差一个变量。

## 4. 根修（先红后绿）
1. 写单测，期望值不跑被测实现就能算出来。修前红，红的原因必须是被测缺陷本身。
2. 改代码，只改根因那一层。同类问题出现第二次，就改机制，不逐个补洞。
3. 单测转绿，再加一个负对照（关掉修复必红）。
4. 回到复现局验：期望 → 实测表，写局数、帧数、设备。

单测样板：
- 采样器 ABI：`graphics/nvn/tests/t_nvn_samp.c`
- 偏置 / 归约模拟：`graphics/nvn/tests/t_nvn_red.m`
- 编译数学模式：`graphics/metal/tests/t_mathmode.m`
- 着色器并发加载：`graphics/nvn/tests/t_nvn_shader_flight.m`
- 宽屏核心：`tests/visual/widen_unit/`
- 着色器取码防线：`tests/shader_garbage_guard_test.sh`

## 5. 判据会绿着失效，报绿时一并报射程
- 满屏验收只认纯黑边：两侧残留会被判「过」。满屏以看图为准。
- 整幅亮度均值量不到局部闪烁。
- 金样漂移要二分到提交、写明原因再重登记，不准放宽界限。
- 失败记录被缓存时，一次基础设施失败可能被冻结成「判据不过」。

## 6. 交付
PR 写清问题、根因、改动、实测（期望 → 实测表）、限制，并贴 `bash tools/contrib_check.sh` 摘要。新踩的坑按 AGENTS.md 追加到 `docs/坑记录.md`。

NVN 接线（给一款新游戏做直连接线）另见 [nvn-wire](../nvn-wire/SKILL.md)。