# 审查指南

> 这份文档面向**独立审查者**。目标不是"确认代码存在"，而是**尝试证伪它**。
> 如果你没有推翻任何一条，请说明你是怎么试的 —— "没找到问题"必须伴随"我试过什么"。

---

## 一、先复现，再读代码

**顺序很重要**：先把东西跑起来、亲手装一个 mod、亲眼看它渲染出来，**再**去读实现。
只读代码会被"看起来对"骗过去。

### 1.1 环境

- Windows + Node ≥ 22
- `playwright-core`（自检脚本要用）：`<node_workspace>/node_modules/playwright-core`
- 跑自检：
  ```bash
  cd dsh-motion-background        # clone 出来的目录名
  node verify.mjs
  ```
  期望：全部通过，退出码 0。

### 1.2 装进真实的 DSH（**这一步不能省**）

自检是离线的，**真机能暴露模拟环境覆盖不到的问题** —— 但别把这句话读成"离线自检只要绿就没问题"：
2026-09-25 的独立审核表明，最严重的几类问题（关键分支没覆盖仍全绿、源码字符串当行为证据、
报告器不是 fail-closed）**在离线就能发现**，前提是自检本身也要被审计（见 §C/§C2）。

```bash
# 1) 在 DSH profile 里挂上这个包（link 到仓库目录）
#    改 <DSH_HOME>/profiles/web/package.json：
#      dependencies: 加 "dsh-motion-background": "link:<仓库绝对路径>"
#      dsh.profile.bundles: 末尾加 "dsh-motion-background"
# 2) 在 profiles/web/node_modules/ 下建 junction 指向仓库目录
# 3) 重启宿主（改了 dsh.client.inject ⇒ 必须重启，刷新页面不够）
```

**拿到真实页面**：宿主启动时 stdout 会打印带令牌的 URL（`dsh web: http://127.0.0.1:3080/?token=...`），
用它可以在 headless 里打开真实页面；只刷新浏览器拿不到。

### 1.3 亲手装一个 mod

```bash
mkdir -p mods/my-test
cp mods/meteor/fragment.glsl mods/my-test/
# 写一个 mod.json，id 改成 my-test
```
刷新页面 ⇒ 设置里应多出「my-test」。**删掉文件夹** ⇒ 应消失。**这两个方向都要试。**

---

## 二、必查清单（逐项，附"怎么证伪"）

### A. 红线：内核里有没有第三方着色器代码

- 用**第三方着色器库的函数名清单**去全文搜索。⚠️ 本文档**故意不列出**这些串，也**不写出
  取自哪个库** —— 列了的话，你搜自己就会命中这份文档，反而制造噪声；写出名字则是在给这个
  仓库与那个库之间制造不必要的关联。
  做法：自己挑一个公开的着色器库，取其工具模块里导出的函数名，拿那批名字来 grep。
  内核里**一个都不该有**。
- **这条检查的效力边界**（独立审核要求写清）：它是对**某一批已知特征**的**高价值探测器**，
  **不是**"不存在任何第三方着色器代码"的证明 —— 换来源、把函数改名、或改写到无法按名字识别，
  都不在它的射程内。请**务必带阳性对照**（拿同一套探测器去搜一个已知含第三方着色器代码的样本，
  确认它能命中），否则"0 命中"既可能是干净、也可能是探测器失灵。
- 另外搜三个结构性特征：
  1. **复杂的顶点着色器** —— 带 sizing / 旋转 / offset / UV 分空间那一整套的，多见于成套着色器库；
    本内核的应当只是"位置 → UV"的极简全屏 quad。出现前者即可疑。
  2. **内联的 base64 图片**（成套着色器库常拿它当噪声贴图）—— 内核里不该有任何图片数据。
  3. **`mods/` 之外的文件里出现 GLSL** —— GLSL 只允许出现在 `mods/*/fragment.glsl`
     与 `mods/*/vertex.glsl`。

### B. mod 机制真的可插拔吗

| 试 | 期望 |
|---|---|
| 放一个合法 mod 进去 | 刷新后出现在效果下拉里 |
| 删掉它 | 刷新后消失 |
| 放一个**缺 `mod.json`** 的文件夹 | 进 `errors`，**其他 mod 照常可用** |
| 放一个 `fragment.glsl` 是**非法 GLSL** 的 mod | 同上；且**页面不崩、设置面板照常打开** |
| 两个文件夹声明**同一个 `id`** | 只有一个生效，另一个报重复 —— **不应出现两个同值选项** |
| `mod.json` 的 `id` 写成 `../evil` 或含空格/大写 | 被拒 |
| `colors` 写成一个非法值 | 被拒（**不应静默当成默认值**，否则作者拿到"颜色不对但看起来能跑"的效果） |
| 删掉整个 `mods/` 目录 | 不崩；面板提示"当前没有可用效果" |

**关键**：以上每条都要确认 **HTTP 200 且返回结构完整**（打开 `/motion-background/mods` 直接看 JSON）。

### C. 自检有没有"假绿"

这是本项目最怕的失败模式。**不要靠"读代码觉得对"**：本仓库把它做成可复跑的**反证驱动器**：

```bash
node mutations.mjs        # 基线必须绿，20 条变异必须让对应断言变红；写出 FALSIFICATION-<date>.md
```

> ⚠️ 跑之前先读 `README.md` 的「坑」一节：连跑整套会创建/清理大量夹具目录，
> 若**调用方 Agent 运行时**注入了带回合配额的删除垫片，整套可能被中途打断。

下表只列**最重要的一批**；权威清单是 `mutations.mjs` 里的 `CASES`（1 基线 + 20 变异），
每条都自带 `expect` 判据（变红的断言必须命中该模式）与可选的 `mustIntroduce`（见下）。

| 变异 | 期望变红的断言 |
|---|---|
| `--mutate=bg-only`（mod 只输出底色） | C 组「画面真的画出来了 / 不是一片纯底色」 |
| `--mutate=no-isolation`（宿主半见坏 mod 就中断整轮扫描） | B 组隔离性 |
| `--mutate=no-draw`（删掉 `gl.drawArrays`） | 像素断言 + E4「拖动真的触发重画」 |
| `--mutate=no-fallback`（候选循环只试第一个） | E5「首选失败 ⇒ 真的回落并出画」 |
| `--mutate=direct-register`（绕开 `slots.inject`） | 设置注册相关 |
| `--mutate=no-scan-sort`（删掉宿主半扫描前的排序） | 「源码级兜底」断言（行为层在按名枚举的文件系统上分不出来） |
| `--mutate=media-traversal` / `media-segments` | 媒体路由「22 种非法路径全部 404」 |
| `--mutate=media-keep-el` / `media-loud` / `media-noplay` | 「切走后不留 `<video>`」/「静音 + 循环」/「真的在播」 |
| `--mutate=pingpong-no-drive` / `seek-flood` | 「倒放段画面真的在变」/ seek「落位率 ≥ 0.9」 |
| `--mutate=pingpong-throttle`（闸门换成**纯时间限流** 400ms） | 「倒放**速度**在 0.8~1.2×」——**前车之鉴**：这一版**落位率反而是 1.0**（发得少、全落位），只靠速度与可见帧率才抓得住 |
| `--mutate=pingpong-reduce-ignored`（倒放路径不查 reduce-motion） | E19h「不进入倒放段」 |
| `--mutate=pingpong-loop-true` / `playmode-no-save` / `playmode-any-media` / `nomedia-label` | 往返 `loop` / 「选择已落盘」/「图片型不出现」/「带类型标注」 |
| `--mutate=crash`（C 组前抛错） | **报告器 fail-closed**：非零退出 + 打印「验证未完成」+ **不得**打印成功标志 |

**两条元纪律**（独立审核 2026-09-25 要求补的）：

1. **判据串不能误匹配**。判据必须在**施加变异的那一处**真的减少命中数；写窄了会误判「变异没生效」，
   写宽了会误匹配注释或别处的同名调用。例：`el.play(` 会匹配到 2 处说明注释 ⇒ 判据须写 `el.play();`。
   每条变异因此都带 `minRemoved`，命中不足即**抛错**（而不是记成 PASS）。
2. **`mustIntroduce` 必须变异前 0 次出现**，否则"变异真的施加了"这半个防护失效（恒真式）。
   例：`pingpong-throttle` 的 `if ((now - lastIssue) < 400)`、`playmode-any-media` 的
   `mod.media !== null && mod.media !== undefined ? mod : null`。

**任何一条破坏后仍然全绿 ⇒ 这就是一个必须报告的问题。** 另外三类"看起来在验证、其实没有"的写法，
审查时请专门去找：

1. **源码字符串存在性**（`src.includes('强度')`、`/KNOBS\.map\(/`）—— 把组件改成不渲染任何旋钮仍会绿；
2. **弱像素断言**（只要求"非底色像素 > 0"）—— 用 `gl.clear` 画个别的颜色、完全不跑 mod 着色器也能绿；
   只有当断言同时要求"与底色明显不同"且"确实是当前 mod 的画面"时才有分辨力；
3. **恒真断言**（断言用的字面量已经不存在、分支永远走不到、`≥0` 这类下界）—— 注入式反证是唯一的发现手段。

### C2. 报告器本身也要审

"脚本崩溃"与"断言失败"是两回事：一个 fail-open 的报告器会在崩溃后照样打印
「✅ 验证通过」。审查时请**故意让脚本中途抛错**（`--mutate=crash` 就是这条），
确认三件事同时成立：非零退出码、明确标注"未完成/哪个阶段"、**没有**成功标志。

### D. 设置面板（真机看，不要只读源码）

- 四个旋钮是否都出现：**强度 / 柔度 / 颗粒 / 形态**？（少一个就是契约违约）
- 把某个 mod 的 `panel.intensity` 指向一个**不存在的 uniform 名** ⇒ 该旋钮应**置灰**，
  不能"能拖但没反应"。
- 旋钮**初值**是否等于该 mod `spec` 里写的值？（内核用自己的默认值覆盖 mod 的设计 = bug）
- 拖动旋钮：画面是否**即时**变化？刷新后是否**保持**？
- 切换效果：是否重建渲染面？切换到一个坏 mod 时是否**回落**到可用的那个（而不是"面板在、画面空"）？

### E. 边界与降级

- 无 WebGL2（可用 `--disable-webgl` 或伪造 `getContext` 返回 null）⇒ 静默跳过，页面正常
- 宿主端点在但返回空 `mods` ⇒ 不报错、面板提示
- 宿主端点 404/500 ⇒ 记进 errors，内核不崩
- `prefers-reduced-motion: reduce` ⇒ 只画一帧（验证方式：看是否停止 rAF 续帧）
- 页面切到后台再回来 ⇒ 是否恢复（或有意的暂停策略）
- 卸载插件 ⇒ 画布、样式表、作用域属性、rAF、observer 是否都清干净
- **反复调用 `probeMods()` 20 次以上** ⇒ 是否会撞 WebGL context 上限（这是实测踩过的坑）

### F. R6 那条关键机制

把 `--dsw-alias-bg-base` 覆盖成半透明是"底纹能看见"的前提。请确认：

- 计算样式里确实是 `color-mix(...)` 而不是不透明的原色
- **并且**画面真的透出来了（不是"变量改了但视觉没变"）
- 关掉效果时，面板底色是否**回到不透明**（否则半透明就没意义，会露出垫层）

### G. 性能与安全

- 大分辨率（如 2560×1440）下是否流畅；连续开几分钟是否掉帧/内存增长
- mod 的 GLSL **能做什么、不能做什么**：确认内核没有 `eval` / `new Function` /
  动态 `import`；确认 mod 的源码只被当作着色器字符串交给 `gl.shaderSource`，
  没有任何地方把它当 JS 执行
- 确认内核**没有任何对外网络请求**（只有读本机 `/motion-background/mods`）

---

## 三、已知的局限（我们主动交代，不构成"你发现的缺陷"）

> 本节在 2026-09-25 按一次**独立离线审核**的结论重写：原来那版只列了"环境覆盖不足"，
> 而审核实测出的问题更靠前（断言本身在替 bug 背书）。修完之后的**当前**局限如下。

1. **全部验证跑在软件光栅（SwiftShader）上**，没有真实 GPU 的帧率/内存数据。
2. **没有在真实的 cordis / DSH 上做自动化断言** —— 真机只做过人工观察。
   `webServer.register` 与 `slots.inject` 的语义是按官方源码契约与同类插件实测推定的。
3. `colors: "array"`（多色团）**没有真实 mod 覆盖**（E 组只覆盖了它的契约分支：越界元素、`glError`）。
4. 可选 `vertex.glsl` 路径**没有真实 mod 覆盖**。
5. **设置卡片不是用真 React 渲染的**：E 组是"调用组件函数 + 遍历元素树"（能验初值/量程/置灰/回调），
   但不受控 input 的真实拖动、`useState` 触发的重渲染、`disabled` 的真实交互仍只有真机能看。
6. `docs/MOD-FORMAT.md` 与实现的逐条一致性由实现方维护（本轮已按审核结论逐条修正 6 处不一致），
   仍请独立复核。
7. **`probeMods()` 用游离画布**（不在 DOM ⇒ `clientWidth=0`），会走 `width/height` 兜底；
   它证明"能编译 + 能在给定尺寸下画一帧"，**不等于**主画布那条路径的等价证明（主路径由 C/E 组覆盖）。
8. **反证覆盖的是"我们想得到的坏法"**：`mutations.mjs` 的 20 条各自锚定一类断言，
   但"注入后仍全绿"的可能性不能靠它穷尽 —— 请把它当作**下限**，并继续自己设计破坏方式。
   本轮已实证过"能骗过某一条判据"的坏实现确实存在（纯时间限流的倒放闸门），
   补齐判据后归入 `pingpong-throttle`。⇒ **判据数不是覆盖度，判据之间是否互相独立才是。**

---

## 四、报告格式建议

1. **你怎么复现的**（跑了什么、装了什么、看到什么）
2. **逐项结论**：通过 / 不通过 / 未验证
3. **你尝试过的证伪动作**，以及结果
4. **发现的问题**：按严重度排序，每条附**最小复现步骤**
5. **你没验证的部分**（诚实列出）