# 21 · H2 微信适配层真机风险评审报告

- **任务编号**：H2（0.1 收尾阶段，只评审、不改源码）
- **评审对象**：`src/wechat/`、`tools/build-wechat.mjs`、`dist/wechat/`、`game.json`、`project.config.json`、`test/wechat-sim.mjs` 与其中的 mock-wx
- **评审日期**：2026-10-13
- **评审工作目录**：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm-work-H2/`
- **写入范围**：本报告 + `review-H2/`（未触碰 `src/`、`test/`、`tests/`、`tools/`、`contract-fixtures/` 任何已有文件）
- **官方文档查阅日期**：**2026-10-13**（全部结论的官方依据见第 2 节「依据」列与第 10 节 URL 清单）

> **本报告的边界（先说清楚，避免被误读）**
> 1. 本机**没有**微信开发者工具、**没有**官方模拟器、**没有**真机。**微信官方模拟器 / 真机 / 官方上传 / 公网预览：全部未验证**，且不在本次可验证范围内。
> 2. 本报告用到的「替身宿主」= Chromium Web Worker（无 DOM）+ OffscreenCanvas + 自写 mock-wx。它**只能**证明「适配层只依赖 wx.* 接口、逻辑正确」，**不能**证明真机的 WebGL 实现、触摸事件细节、存储配额、性能。
> 3. 所有关于微信 API 行为的结论都附官方文档 URL + 查阅日期；查不到官方依据的一律标注「**未找到官方依据**」，不凭印象陈述。
> 4. 本报告不修改任何源码。**P0/P1 只报告，不代修**（任务书规定「先修再继续」，由用户决定谁来修）。

---

## 1. 结论

### **不通过（真机适配层存在启动级阻断风险，必须先修再进入真机验证）**

判定理由（三条独立证据链，均可复现）：

| # | 结论要点 | 证据 |
|---|---|---|
| 1 | **微信 Canvas 对象按官方文档只暴露 5 个成员（width/height/getContext/toDataURL/toTempFilePath），而 three.js r186 的 `WebGLRenderer` 构造期无条件调用 `canvas.addEventListener(...)`** → 真机启动即抛 `TypeError: canvas.removeEventListener is not a function`（异常在 catch 清理路径上抛出），游戏**完全无法启动**。替身之所以通过，是因为替身用的是浏览器原生 `OffscreenCanvas`，它有 `addEventListener`。 | 官方 `Canvas` 文档（2026-10-13）；`node_modules/three/build/three.module.js:16440-16442`、`16470-16472`；我的探针输出 `probe-g-canvas-size.json`（listeners 被成功注册）+ Node 直测抛错原文 |
| 2 | **three.js r186 明确不支持 WebGL1（源码注释 `WebGL 1 is not supported since r163`），只请求 `webgl2` 且无任何降级**；官方文档同时指出 iOS 高性能模式下 WebGL2「存在较多问题，平台暂不保证所有能力完善」。真机老设备/低基础库上会出现黑屏或直接崩溃，且代码没有任何失败提示。 | 官方 `WebGL2.0渲染支持说明`（2026-10-13）；`Canvas.getContext` 合法值表（webgl2 最低基础库 2.24.0）；`three.module.js:16096-16097`、`16444-16461`；我的 Node 直测输出 |
| 3 | **mock-wx 与真实 wx 在 9 个关键点上有系统性差异**（第 4 节逐条列出），其中 4 个差异直接掩盖了 P0/P1；`test/wechat-sim.mjs` 的 37/37 **不构成真机可用性证据**。 | 第 4 节差异表 + 我的独立探针（第 5 节） |

**通过的部分**（这些确实是好的，值得保留）：核心经济/存档/离线逻辑的幂等性经替身与契约夹具交叉验证（32/32 变体）；离线结算在重复 `onShow`、未配对 `onShow`、快速 hide/show 抖动下**没有重复发放**；存档失败会回滚内存状态并提示；损坏存档回退新档；包体 615.9 KiB（gzip 160.7 KiB）远低于主包 4M 限制。

---

## 2. 风险表

严重度定义：**P0** = 真机启动失败/完全不可玩，必须修完才能继续；**P1** = 真机大概率出现明显故障（卡死、内存暴涨、可被利用的漏洞），必须在 0.1 真机验证前修或至少加兜底；**P2** = 有风险但影响可控，建议记录并安排验证。

| 编号 | 严重度 | 位置（文件:行号） | 依据（官方 URL + 查阅日期） | 真机可能出现的现象 | 建议的最小验证方法 |
|---|---|---|---|---|---|
| **H2-01** | **P0** | `src/wechat/main.ts:27`（`mainCanvas = wx.createCanvas()`）→ `src/app/app.ts:59`（`new THREE.WebGLRenderer({ canvas: host.canvas, ... })`）；three 侧 `node_modules/three/build/three.module.js:16440-16442`、`16470-16472` | [Canvas 对象](https://developers.weixin.qq.com/minigame/dev/api/render/canvas/Canvas.html)（2026-10-13）：属性仅 `width`/`height`，方法仅 `getContext`/`toDataURL`/`toTempFilePath`；[Adapter](https://developers.weixin.qq.com/minigame/dev/guide/runtime/adapter.html)（2026-10-13）：「小游戏…是没有 BOM 和 DOM 的运行环境，没有全局的 document 和 window 对象」，且「weapp-adapter 模拟了…**canvas.addEventListener**」，同时强调「**weapp-adapter 不是小游戏基础库的一部分**」 | 启动即崩，无画面；开发者工具控制台报 `TypeError: canvas.removeEventListener is not a function`（或 `addEventListener`），游戏永远停在黑屏 | 在**真机**上加载 `dist/wechat/game.js`，看控制台第一条异常；或在开发者工具里 `console.log(typeof wx.createCanvas().addEventListener)` |
| **H2-02** | **P0** | `src/app/app.ts:59`（无 `context` 传入、无 try/catch）；`node_modules/three/build/three.module.js:16096-16097`（`WebGL 1 is not supported since r163`）、`16444-16461` | [Canvas.getContext](https://developers.weixin.qq.com/minigame/dev/api/render/canvas/Canvas.getContext.html)（2026-10-13）：`webgl2` 最低基础库 **2.24.0**；[WebGL2.0渲染支持说明](https://developers.weixin.qq.com/minigame/dev/guide/game-engine/unity-webgl-transform/Design/WebGL2.html)（2026-10-13）：「iOS高性能使用WebGL2会存在较多问题，**平台暂不保证所有能力完善**」；iOS 高性能模式需 iOS ≥ 15.0 | 低端 Android / 老 iOS / 未开启高性能模式的机型：`getContext('webgl2')` 返回 null → 抛 `THREE.WebGLRenderer: Error creating WebGL context.` → 黑屏且无任何用户提示 | 在至少 1 台 Android（微信 < 8.0.24 或低端机）+ 1 台 iOS 14 上真机预览，观察是否黑屏 |
| **H2-03** | **P0** | `src/wechat/main.ts:37-40`（`sys()` 直接用 `s.windowWidth`/`s.windowHeight`，无兜底）→ `src/app/app.ts:82,98-102` | [wx.getSystemInfoSync](https://developers.weixin.qq.com/minigame/dev/api/base/system/wx.getSystemInfoSync.html)（2026-10-13）：返回值含 `windowWidth`/`windowHeight`/`pixelRatio`（该文档同时给出大量字段已由 `wx.getWindowInfo`/`wx.getDeviceInfo` 替代的说明） | 接口异常/降级返回 `{}` 时：`c.width = undefined` → 我的探针实测报 `Failed to set the 'width' property on 'OffscreenCanvas': Value is not of type 'unsigned long'`，**加载即失败**，比"黑屏"更早一步 | 真机上打印 `JSON.stringify(wx.getSystemInfoSync())`；或在替身里注入 `{}` 复现（我的探针 C 已复现） |
| **H2-04** | **P1** | `src/wechat/main.ts:56-59`（触摸注册）＋ `62`（`onHide`/`onShow` 只转会话，**不做输入清理**）；`src/app/input.ts:37-50`（`ptrs` 只由 `pointerUp`/`pointerCancel` 移除）、`86-88`（`!this.multi` 才判定点击） | [wx.onTouchCancel](https://developers.weixin.qq.com/minigame/dev/api/device/touch-event/wx.onTouchCancel.html)（2026-10-13）：功能描述只有「监听触点失效事件」，**未声明**在进后台/锁屏/系统弹窗时必然触发；[wx.onTouchEnd](https://developers.weixin.qq.com/minigame/dev/api/device/touch-event/wx.onTouchEnd.html)（2026-10-13）同样未给出「进后台必补发 touchend/cancel」的保证 → **「真机进后台是否必发 touchcancel」：未找到官方依据** | 用户按下手指的瞬间被来电/锁屏/系统弹窗打断（`touchend`/`touchcancel` 都不来）→ 残留触点永久留在 `ptrs` 里 → 此后**所有点击与拖动全部失效**（我的探针实测：点击不生效、横拖相机 yaw 纹丝不动），只能重启游戏 | 真机：按住屏幕不放 → 下拉通知栏/锁屏 → 回前台 → 尝试点击居民。也可在替身里复现（我的探针 B4 已复现，见第 5 节） |
| **H2-05** | **P1** | `src/ui/fx.ts:10-19`（每次飘字 `makeCanvas(256,64)` 新建画布）＋ `src/ui/fx.ts:17`（只把 `CanvasTexture` 交出去）；`src/platform/canvas.ts:22-26`（`wx.createCanvas()` 每次新建）；调用点 `src/app/app.ts:212-213`（一次寻访 **2 次** `floatText`） | [wx.createCanvas](https://developers.weixin.qq.com/minigame/dev/api/render/canvas/wx.createCanvas.html)（2026-10-13）：「首次调用创建的是显示在屏幕上的画布，之后调用创建的都是离屏画布」；[渲染](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html)（2026-10-13）：「小游戏只有一个上屏画布，可以有多个离屏画布」 | 每次领金币新建 2 张离屏画布（我的探针实测：30 次点击 → `wx.createCanvas` 累计调用从 9 涨到 69，**+60**）；长时间游玩后离屏画布/纹理/显存持续累积 → 中低端机掉帧、发热，最终触发内存告警甚至闪退 | 真机连续点居民 200 次，用开发者工具「Memory」面板看离屏画布/纹理数量与内存曲线是否单调上升 |
| **H2-06** | **P1** | `src/wechat/main.ts:37-40`（只取 `windowWidth`/`windowHeight`/`pixelRatio`，**不读 safeArea**）；`src/app/app.ts:98-104`；`src/ui/hud.ts:86`（正交相机硬编码 390×844 初值，布局按 `topH`/`bottomH` 固定比例） | [wx.getWindowInfo](https://developers.weixin.qq.com/minigame/dev/api/base/system/wx.getWindowInfo.html)（2026-10-13）：返回 `statusBarHeight` 与 `safeArea`，并明确「部分机型没有安全区域概念，也不会返回 safeArea 字段，**开发者需自行兼容**」；[game.json 配置](https://developers.weixin.qq.com/minigame/dev/reference/configuration/app.html)（2026-10-13）：`showStatusBar` 默认 false | 刘海屏/灵动岛/挖孔屏机型上，顶部 HUD（等级/金币）与底部「升级市政厅」按钮可能被状态栏、刘海或 Home Indicator 遮挡/裁切；`showStatusBar:false` 只是不显示状态栏，**不等于**内容自动避开安全区 | 在 iPhone 14 Pro / 带挖孔的 Android 上真机截图，量顶部 HUD 与刘海、底部按钮与 Home Indicator 的间距 |
| **H2-07** | **P1（疑似，但按任务书要求不替它下结论）** | `tools/build-wechat.mjs:26`（`compileType: 'game'`）→ 产物 `dist/wechat/project.config.json` | [项目配置文件](https://developers.weixin.qq.com/minigame/dev/devtools/projectconfig.html)（2026-10-13）：`compileType` 的「**有效值**」表只列出 `minigame`（普通小游戏项目）与 `gamePlugin`（小游戏插件项目） | 若开发者工具严格校验 `compileType`，导入 `dist/wechat/` 可能报配置错误/无法识别为小游戏工程 → 连模拟器都进不去 | **必须**用微信开发者工具（游客模式）实际导入 `dist/wechat/` 验证。**`compileType` 是 `game` 还是 `minigame` 尚未用微信开发者工具模板验证，本报告不替它下结论**（`docs/` 已记录的同一待验证项） |
| **H2-08** | **P2** | `src/wechat/main.ts:46`（`clock: new GameClock(() => Date.now())`）；`src/core/offline.ts:38-44`（`clock-went-backwards` 判定） | [Performance.now](https://developers.weixin.qq.com/minigame/dev/api/base/performance/Performance.now.html)（2026-10-13）：`wx.getPerformance()` 返回 Performance 对象，`now()` 返回「时间戳」（**未在文档中声明单调性 → 单调性：未找到官方依据**）；[wx.onHide](https://developers.weixin.qq.com/minigame/dev/api/base/app/life-cycle/wx.onHide.html)（2026-10-13） | 墙钟被 NTP 校正或用户手动改时间：向前跳 → 在线/离线结算一次性发放巨额金币（可被利用）；向后跳 → 提示「时间回拨」并**拒发本次离线收益**，用户觉得"收益被吞" | 真机上手动改系统时间前后各 ±1 小时，观察金币与提示；评估是否改用 `wx.getPerformance().now()` 做单调时间源（离线收益锚点仍用墙钟） |
| **H2-09** | **P2** | `src/wechat/main.ts:49`（`raf: (cb) => { requestAnimationFrame(cb); }`，直接用全局名，无 `wx.` 兜底、无存在性判断）；`src/app/app.ts:120-133`（`frame(ts)` 用 `ts` 计算 dt） | [requestAnimationFrame](https://developers.weixin.qq.com/minigame/dev/api/render/frame/requestAnimationFrame.html)（2026-10-13）：只写「在下次进行重绘时执行」+ 参数 `function callback`，**未说明回调是否带时间戳**（→ 回调参数契约：未找到官方依据）；[Adapter](https://developers.weixin.qq.com/minigame/dev/guide/runtime/adapter.html)（2026-10-13）：「小游戏基础库只提供 `wx.createCanvas`…以及 `setTimeout`/`setInterval`/`requestAnimationFrame` 等常用的 JS 方法」 | 若真机 rAF 回调不带时间戳（`ts === undefined`）：`dt` 恒为 0.016（`app.ts:122` 的 `lastTs` 分支），游戏变成"每帧固定 16ms"的慢动作/与真实时间脱钩；另外 `dt` 被 `Math.min(0.05, ...)` 钳制，**低帧率下逻辑时间步会慢于真实时间**（金币累积偏慢） | 真机打日志 `requestAnimationFrame(ts => console.log(ts))` 看是否单调递增、是否与 `Date.now()` 同量纲 |
| **H2-10** | **P2** | `src/wechat/main.ts:31-34`（存储读写）；`src/core/save.ts`（无字节长度校验） | [wx.setStorageSync](https://developers.weixin.qq.com/minigame/dev/api/storage/wx.setStorageSync.html)（2026-10-13）：「单个 key 允许存储的最大数据长度为 **1MB**，所有数据存储上限为 **10MB**」；[本地缓存](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/storage.html)（2026-10-13）：「storage 上限为 10MB」；[wx.getStorageSync](https://developers.weixin.qq.com/minigame/dev/api/storage/wx.getStorageSync.html)（2026-10-13）：「启动过程中过多的同步读写存储，会显著影响启动耗时」 | 当前存档实测仅 **285 字节**（键 `wyszz-0.1-ds-save`，14 个字段），配额风险**很低**；但 `main.ts:41` 又额外调了一次 `getSystemInfoSync()` 只为拿 `benchmarkLevel`（启动期同步调用翻倍）。写失败路径已由核心回滚（替身 W08 覆盖） | 真机看启动耗时；存档长到 1MB 级（0.2 再说）时验证写失败提示 |
| **H2-11** | **P2** | `src/wechat/main.ts`（**未注册** `wx.onMemoryWarning` / `wx.triggerGC` / `wx.onError`）；`src/app/app.ts:136-141`（`render()` 无 try/catch，无 `webglcontextlost` 处理） | [wx.onMemoryWarning](https://developers.weixin.qq.com/minigame/dev/api/device/memory/wx.onMemoryWarning.html)（2026-10-13）存在该 API；[wx.onError](https://developers.weixin.qq.com/minigame/dev/api/base/app/app-event/wx.onError.html)（2026-10-13）存在该 API | 与 H2-05 叠加：内存告警时无任何降级动作（不降纹理、不触发 GC）；WebGL 上下文丢失（真机切后台再回来常见）后 three 的 `onContextLost` 虽已注册但**代码层没有任何恢复/提示逻辑** | 真机反复切前后台 20 次，看画面是否恢复；用开发者工具模拟内存告警 |
| **H2-12** | **P2** | `test/wechat-sim.mjs:295-298`（W12b 静态检查） | 无（这是对测试自身完备性的评审，不需要微信文档依据） | W12b 的 banned 列表只查 `window.addEventListener` / `document.addEventListener`，**不查 `canvas.addEventListener`**；而 `dist/wechat/game.js` 里 `addEventListener` 出现 **26 次**、`removeEventListener` **28 次**（含 `webglcontextlost` 3 次）。所以 W12b 的 PASS **不能**用来证明"没有 DOM 依赖"，它恰好漏掉了 H2-01 这个致命依赖 | 把 banned 列表加上 `addEventListener(`（不带前缀）并重跑；或直接看第 5 节的 grep 输出 |

**P0 合计 3 条（H2-01、H2-02、H2-03）；P1 合计 4 条（H2-04、H2-05、H2-06、H2-07）；P2 合计 5 条（H2-08…H2-12）。**

---

## 3. 真机验证应重点盯的 10 件事

1. **第一帧能不能出**：真机加载 `dist/wechat/game.js` 后，控制台第一条异常是什么（重点看 `addEventListener` / `removeEventListener` / `Error creating WebGL context`），屏幕是黑屏还是正常岛屿。
2. **`wx.createCanvas()` 返回对象的成员清单**：在真机/官方模拟器里打印 `Object.getOwnPropertyNames(Object.getPrototypeOf(wx.createCanvas()))`，确认有没有 `addEventListener`。
3. **`compileType` 导入验证**：用微信开发者工具（游客模式）导入 `dist/wechat/`，确认 `compileType: "game"` 是否被接受，还是要改成 `minigame`。
4. **WebGL2 与机型分级**：至少 1 台低端 Android（微信 < 8.0.24）+ 1 台 iOS 14/15（开/关高性能模式）各跑一次，确认是黑屏、报错还是正常。
5. **触摸被系统打断后的输入**：按住手指不放 → 下拉通知栏或锁屏 → 回前台 → 尝试点击居民/拖动旋转，确认是否卡死；同时抓 `wx.onTouchCancel` 是否真的触发。
6. **刘海屏安全区**：iPhone 14 Pro 级刘海/灵动岛机型 + 挖孔 Android，量顶部 HUD、底部「升级市政厅」按钮与安全区/Home Indicator 的距离。
7. **连续游玩的内存曲线**：连续点居民 200 次，用开发者工具 Memory 面板看离屏画布/纹理数量与内存是否单调上升（对应 H2-05）。
8. **`getSystemInfoSync()` 的真实返回**：打印完整 JSON，确认 `windowWidth`/`windowHeight`/`pixelRatio` 是否总有值，以及 `safeArea`/`statusBarHeight` 是否存在。
9. **前后台时间与离线收益**：真机手动改系统时间 ±1 小时，看是否发放巨额收益或提示「时间回拨」；再连续切前后台 10 次，确认离线面板不重复发放、不吞收益。
10. **rAF 回调契约与帧率**：真机打印 `requestAnimationFrame` 回调参数，确认是否带单调时间戳；在低帧率（锁 30fps 或低端机）下观察金币累积是否明显慢于真实时间。

---

## 4. mock-wx 与真实 wx 的差异表

`test/wechat-sim.mjs` 的 mock-wx 定义在 `test/wechat-sim.mjs:16-34`（Worker 前导）。逐 API 说明它做了什么假设、这个假设在真机上是否成立。

| mock-wx 实现（`test/wechat-sim.mjs` 行号） | mock 做了什么假设 | 真实 wx 的官方事实 | 差异后果 |
|---|---|---|---|
| `createCanvas()` 第 1 次返回 `new OffscreenCanvas(W*DPR, H*DPR)`（`:23`） | 假设主画布是**浏览器原生 `OffscreenCanvas`**，因此自带 `addEventListener`/`removeEventListener`/`setAttribute` | 官方 `Canvas` 对象只列 5 个成员，无 `addEventListener`（[Canvas](https://developers.weixin.qq.com/minigame/dev/api/render/canvas/Canvas.html)，2026-10-13） | **直接掩盖 H2-01（P0）**：three 的三个 `addEventListener` 在替身里成功、在真机抛 TypeError |
| 主画布初始尺寸设为 `W*DPR × H*DPR`（`:23`），未记录后续 `setSize` 的影响 | 假设主画布初始尺寸就是最终渲染尺寸 | `renderer.setSize(w,h,false)` 会把主画布设为 CSS 像素尺寸（我的探针 G 实测 390×844@pixelRatio=2 → 主画布 780×1688） | 无致命差异，但替身没验证"主画布尺寸是否由 setSize 决定"这条链路 |
| `getContext` 用浏览器实现（`OffscreenCanvas.getContext`） | 假设真机 `getContext('webgl2')` 一定成功 | 官方：`webgl2` 最低基础库 2.24.0；iOS 高性能模式 WebGL2「平台暂不保证所有能力完善」（[getContext](https://developers.weixin.qq.com/minigame/dev/api/render/canvas/Canvas.getContext.html)、[WebGL2 说明](https://developers.weixin.qq.com/minigame/dev/guide/game-engine/unity-webgl-transform/Design/WebGL2.html)，2026-10-13） | **掩盖 H2-02（P0）**：替身永远有 WebGL2，真机可能没有 |
| `getSystemInfoSync()` 恒返回完整对象（`:21`、`:24`） | 假设 `windowWidth`/`windowHeight`/`pixelRatio` **永远有值** | 官方文档未承诺异常时返回完整对象；`safeArea` 官方明确"部分机型…不会返回"（[getWindowInfo](https://developers.weixin.qq.com/minigame/dev/api/base/system/wx.getWindowInfo.html)，2026-10-13） | **掩盖 H2-03（P0）与 H2-06（P1）**：`{}` 会让启动直接失败；安全区从未被测 |
| `setStorageSync` 只在 `__failWrites` 为真时抛错（`:26`） | 假设"存储要么成功、要么整体抛错"，**不模拟 1MB/key、10MB 总量配额** | 官方：单 key 1MB、总量 10MB（[wx.setStorageSync](https://developers.weixin.qq.com/minigame/dev/api/storage/wx.setStorageSync.html)，2026-10-13） | 配额边界未被覆盖（当前存档 285 字节，实际风险低） |
| `getStorageSync` 缺省返回 `''`（`:25`） | 假设"空值 = 空字符串" | 官方示例 `if (value) {...}`，未声明缺省值形态 | 适配层 `main.ts:31` 已同时判 `typeof v === 'string' && v.length > 0`，兼容性尚可 |
| `onTouchStart/Move/End/Cancel` 只存回调、由测试**手工构造**事件（`:29`、`:41`） | 假设事件字段就是 `{touches, changedTouches:[{identifier, clientX, clientY}]}`，且 **`touchcancel` 一定会被测试主动补发**；`end`/`cancel` 时 `touches: []` | 官方 `Touch` 字段确认有 `identifier`/`clientX`/`clientY`（[Touch](https://developers.weixin.qq.com/minigame/dev/api/device/touch-event/Touch.html)，2026-10-13）；但 `onTouchCancel` 的**触发时机**官方未定义 | **掩盖 H2-04（P1）**：真机若不补发 `touchcancel`，残留触点卡死输入，而测试永远不会出现这种情况 |
| `onShow`/`onHide` 只是两个可手工调用的回调（`:28`），测试里严格成对调用 | 假设前后台事件**成对、有序、不重不漏** | 官方只描述"监听回到前台/隐藏到后台事件"，未给出顺序与去重保证（[wx.onShow](https://developers.weixin.qq.com/minigame/dev/api/base/app/life-cycle/wx.onShow.html)、[wx.onHide](https://developers.weixin.qq.com/minigame/dev/api/base/app/life-cycle/wx.onHide.html)，2026-10-13） | 我的探针 E 已补测抖动/未配对/重复 `onShow`，**离线面板未重复发放**（这部分 mock 与真机风险一致，结论可信） |
| `requestAnimationFrame` 用浏览器实现，回调**带高精度时间戳**（`:33-34`） | 假设 rAF 回调一定带时间戳 | 官方 rAF 文档只写"在下次进行重绘时执行"，未说明回调参数（[requestAnimationFrame](https://developers.weixin.qq.com/minigame/dev/api/render/frame/requestAnimationFrame.html)，2026-10-13）→ **未找到官方依据** | 掩盖 H2-09（P2）：若真机 `ts` 为 undefined，`dt` 恒 0.016，时间步与真实时间脱钩 |
| 无 `wx.onMemoryWarning` / `wx.triggerGC` / `wx.getPerformance` / `wx.onWindowResize` 的**行为**模拟（`:30` 仅存了 `onWindowResize` 回调，测试未触发） | 假设这些 API 用不到/不影响 | 官方均存在这些 API（`onMemoryWarning`、`triggerGC`、`getPerformance`、`onWindowResize`，2026-10-13） | 掩盖 H2-11（P2）：真机内存告警/上下文丢失时无任何降级路径 |
| `Date.now` 被替换为可注入的 `__fakeNow`（`:17`） | 假设时间源可以随意前后跳，且**游戏只依赖 Date.now** | 官方提供 `wx.getPerformance().now()` 作为另一种时间源（[Performance.now](https://developers.weixin.qq.com/minigame/dev/api/base/performance/Performance.now.html)，2026-10-13） | 掩盖 H2-08（P2）：墙钟跳变的可利用性/收益被吞的风险未被评估 |
| 无 `wx.getLaunchOptionsSync` / `wx.getMenuButtonBoundingClientRect` / `wx.loadFont` 模拟 | 假设不需要它们 | 官方均存在（2026-10-13） | 与当前实现无关（代码未用），但意味着"真机 UI 适配"这一层完全没有替身覆盖 |

**一句话总结**：mock-wx 把"真机可能没有的东西"（原生 canvas 的 DOM 方法、WebGL2、安全区、配额、touchcancel、rAF 时间戳）**全部默认成"有"**，所以 37/37 只证明"逻辑自洽 + 不依赖 DOM"，不证明"真机能跑"。

---

## 5. 我实际运行的命令与原始输出

> 说明：以下全部是我在 2026-10-13 亲自重跑的输出原文（未转述、未美化）。`[exit code: N]` 是工具回传的真实退出码。

### 5.1 环境与基线核对

```bash
$ export PATH=/mnt/ssd/apps/nodejs_v24/bin:$PATH
$ node -v
v24.15.0
$ /usr/bin/chromium --version
Chromium 154.0.8037.57 built on Debian GNU/Linux 12 (bookworm)
```

```bash
$ grep -v '^==>' review-H2/baseline-sha256.txt > review-H2/out/mine/baseline.clean.txt
$ sha256sum -c review-H2/out/mine/baseline.clean.txt
--- files in baseline: 51
mismatches: 0
OK count: 51
--- which dirs covered ---
     30 src
      8 test
      1 tests
     12 tools
```
（退出码 0；`==>` 头行已按任务书要求剔除。）

```bash
$ sha256sum -c review-H2/out/mine/dist-baseline.clean.txt
dist/wechat/game.js: OK
dist/wechat/game.json: OK
dist/wechat/MANIFEST.json: OK
dist/wechat/project.config.json: OK
$ gzip -c dist/wechat/game.js | wc -c
164603
```

### 5.2 重跑官方替身测试（`test/wechat-sim.mjs`，未修改该文件）

```bash
$ timeout 900 node test/wechat-sim.mjs > review-H2/out/mine/wechat-sim-run.log 2>&1; echo "EXIT=$?"
EXIT=0
$ tail -12 review-H2/out/mine/wechat-sim-run.log
PASS W08b 界面提示“存档失败”，状态栏变红（saveOk=false）
PASS W08c 恢复后再次点击成功，提示“存档已恢复”
PASS W09 损坏存档：回退为新游戏（Lv1，0 币）并重写为合法存档，界面提示 — 存档已损坏，已开始新游戏
PASS W09b 重新启动（同一 wx 存储）：金币/声望/寻访与关闭前一致 — {"before":[2,2],"after":[2,2]}
PASS W10 契约夹具经 wx 存储/触摸重放：32/32 变体，逐步 state + 存档逐字节一致
PASS W10b 驱动方式：wx 触摸 + 3D 射线 24 步，核心层直驱 82 步（共 106；直驱 = BOOT/TICK/TAP:市政厅 等无界面入口事件；前后台走 wx.onShow/onHide）
PASS W11 360×640 @2x 启动：渲染正常（info.frames>2），截图 — evidence/wechat-sim/w09-360x640.png
PASS W12 运行全程无网络调用（fetch/XHR/WebSocket 在模拟宿主里被替换为拦截器，计数 0） — 0
PASS W12b game.js 静态检查：不含 wx.request / localStorage / window|document.addEventListener / new WebSocket / new XMLHttpRequest / fetch( — 命中: 无；另：仅 three 的 createCanvasElement 含 document.createElementNS（未传 canvas 时才会调用，本项目恒传入 wx.createCanvas 画布；Worker 内 document 未定义仍正常运行即证明未触达）= true
PASS W12c 全程无页面/Worker 报错

== 微信适配层（Worker 无 DOM + 模拟 wx）：37/37 ==
```
**结论**：替身测试确实 37/37 通过——但如第 4 节所述，这是 mock-wx 的假设造成的。

### 5.3 three.js 源码实证（H2-01 / H2-02）

```bash
$ grep -n "removeEventListener\|addEventListener\|createCanvasElement" node_modules/three/build/three.module.js | head
6:import { ... createCanvasElement ... } from './three.core.js';
...
$ awk 'NR>=16437 && NR<=16460 {printf "%d: %s\n", NR, $0}' node_modules/three/build/three.module.js
16437: 			if ( 'setAttribute' in canvas ) canvas.setAttribute( 'data-engine', `three.js r${REVISION}` );
16438:
16439: 			// event listeners must be registered before WebGL context is created, see #12753
16440: 			canvas.addEventListener( 'webglcontextlost', onContextLost, false );
16441: 			canvas.addEventListener( 'webglcontextrestored', onContextRestore, false );
16442: 			canvas.addEventListener( 'webglcontextcreationerror', onContextCreationError, false );
16444: 			if ( _gl === null ) {
16446: 				const contextName = 'webgl2';
16448: 				_gl = getContext( contextName, contextAttributes );
16450: 				if ( _gl === null ) {
16452: 					if ( getContext( contextName ) ) {
16454: 						throw new Error( 'THREE.WebGLRenderer: Error creating WebGL context with your selected attributes.' );
16458: 						throw new Error( 'THREE.WebGLRenderer: Error creating WebGL context.' );

$ awk 'NR>=16470 && NR<=16476 {printf "%d: %s\n", NR, $0}' node_modules/three/build/three.module.js
16470: 			canvas.removeEventListener( 'webglcontextlost', onContextLost, false );
16471: 			canvas.removeEventListener( 'webglcontextrestored', onContextRestore, false );
16472: 			canvas.removeEventListener( 'webglcontextcreationerror', onContextCreationError, false );
16474: 			error( 'WebGLRenderer: ' + e.message );
16475: 			throw e;

$ awk 'NR>=16096 && NR<=16098 {printf "%d: %s\n", NR, $0}' node_modules/three/build/three.module.js
16096:  * This renderer uses WebGL 2 to display scenes.
16097:  * WebGL 1 is not supported since `r163`.

$ awk 'NR>=1871 && NR<=1873 {printf "%d: %s\n", NR, $0}' node_modules/three/build/three.core.js
1871: function createElementNS( name ) {
1873: 	return document.createElementNS( 'http://www.w3.org/1999/xhtml', name );
$ grep -n "^const REVISION" node_modules/three/build/three.core.js
6:const REVISION = '186';
```

**Node 直测（把官方文档描述的 Canvas 成员做成桩，喂给真实 three）**：

```bash
$ node --input-type=module -e "
import * as THREE from 'three';
console.log('THREE.REVISION =', THREE.REVISION);
function makeWxCanvas() { return { width: 390, height: 844, getContext(t){return null;}, toDataURL(){return 'data:,';}, toTempFilePath(){} }; }
try { new THREE.WebGLRenderer({ canvas: makeWxCanvas(), antialias: true, alpha: false, powerPreference: 'high-performance' }); }
catch (e) { console.log('THROWN TYPE:', e.constructor.name); console.log('THROWN MSG :', e.message); }
"
THREE.REVISION = 186
THROWN TYPE: TypeError
THROWN MSG : canvas.removeEventListener is not a function
```

```bash
$ node --input-type=module -e "
import * as THREE from 'three';
const listeners = {};
const c = { width:390, height:844, addEventListener(t,f){(listeners[t]||=[]).push(f);}, removeEventListener(){}, setAttribute(){}, getContext(){return null;} };
try { new THREE.WebGLRenderer({ canvas: c }); } catch (e) { console.log('CASE2 THROWN:', e.message); }
console.log('listeners registered before throw:', Object.keys(listeners));
"
THREE.WebGLRenderer: THREE.WebGLRenderer: Error creating WebGL context.
CASE2 THROWN: THREE.WebGLRenderer: Error creating WebGL context.
listeners registered before throw: [ 'webglcontextlost', 'webglcontextrestored', 'webglcontextcreationerror' ]
```

### 5.4 我自己的探针（`review-H2/scripts-mine/probe-h2.mjs`）

```bash
$ timeout 900 node review-H2/scripts-mine/probe-h2.mjs > review-H2/out/mine/probe-h2-mine.log 2>&1; echo "EXIT=$?"
EXIT=0
$ cat review-H2/out/mine/probe-h2-mine.log

[A] 连续 30 次点居民：wx.createCanvas 累计调用数变化
  {"canvasBefore":9,"canvasAfter":69,"delta":60,"visits":30}

[B] 按下后未 touchend/touchcancel 就进后台：回前台后点击/拖动是否失效
  {"sanity":[0,1],"afterResumeFirstTap":1,"visitsAfterEachTap":[1,1,1,1,1],"camYaw":["0.611","0.611"],"inputStats":{"taps":1,"swallowed":6,"uiActions":0,"drags":0,"pinches":0,"wheels":0}}

[B2] 补发 wx.onTouchCancel 之后点击是否恢复
  {"before":1,"after":1,"recovered":false}

[C] getSystemInfoSync() 返回 {} 时加载 game.js
  {"boot":"load: Failed to set the 'width' property on 'OffscreenCanvas': Value is not of type 'unsigned long'.","logs":[]}

[D] 正常存档：键名 / 字节数 / 字段数
  {"namespace":"wyszz-0.1-ds-save","bytes":285,"keys":14}

[D2] 写入 >1MB 的值（替身不限制容量，只记录真实字节数）
  {"writeErr":null,"storedBytes":1048586}

[E] onShow/onHide 抖动：离线面板是否重复发放
  {"panelsAfterFirst":1,"afterRepeatShow":1,"afterUnpairedShow":1,"after5xFlap":1,"offline":{"offlinePending":false,"offlineStartTsMs":1800003600000},"coinsMilli":1357213845}

[F] pixelRatio=3、benchmarkLevel=50（非低端机）时的实际渲染像素比与画布尺寸
  {"pixelRatio":1,"lowFx":true,"renderer":"ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero) (0x0000C0DE)), SwiftShader driver)","textures":8}

== 探针完成 8 项 → review-H2/out/mine/probe-h2-mine.json ==
```

> **探针 B 的自我纠正（必须写出来，避免误导）**：B 里 `swallowed:6` 不是"触点卡死"，而是**离线收益面板（modal）开着**把点击吞掉了——因为该场景 `hide` 后 `show` 触发了离线结算。我据此写了诊断探针 B3 定位到 `modal:true`，再用 B4（把 fake 时钟钉在同一时刻，确保不产生离线面板）重新验证，才确认"残留触点卡死输入"这个结论。**B3/B4 的原始输出见下**。

### 5.5 诊断探针 B4（排除 modal 干扰后的残留触点复现）

```bash
$ timeout 600 node review-H2/scripts-mine/probe-b4.mjs 2>&1 | tail -50
{
  "sanity": { "v0": 0, "v1": 1, "ok": true },
  "stuckPress": {
    "modalOpen": false,
    "visitBefore": 1,
    "visitAfterTap": 1,
    "tapWorked": false,
    "inputStats": { "taps": 1, "swallowed": 0, "uiActions": 0, "drags": 0, "pinches": 0, "wheels": 0 },
    "camYawDrag": [ "0.6109", "0.6109", "0.6109" ],
    "dragWorked": false
  },
  "afterCancel": {
    "visitBefore": 1, "visitAfterTap": 2, "tapWorked": true,
    "inputStats": { "taps": 2, "swallowed": 0, "uiActions": 0, "drags": 0, "pinches": 6, "wheels": 0 }
  }
}
```
**读法**：`modalOpen:false` 证明不是面板吞点击；按下触点 7 → hide → show 之后，点击**不生效**（`1→1`）、横拖 120px 相机 yaw **完全不变**（`0.6109→0.6109`）；补发 `touchcancel` 后立刻恢复（`1→2`，且 `pinches:6` 说明残留触点在时被当成双指）。→ H2-04 成立。

### 5.6 画布尺寸/像素比探针 G（Node 里跑真实 game.js）

```bash
$ timeout 180 node review-H2/scripts-mine/probe-g.mjs 2>&1 | head -40
[renderer] probe-renderer lowFx=false platform=wechat
{
  "boot": "ok",
  "mainCanvas": { "width": 780, "height": 1688 },
  "setSizeCalls": [ ["width",780], ["height",1688], ["width",780], ["height",1688] ],
  "canvasCalls": 9,
  "listeners": { "webglcontextlost": 1, "webglcontextrestored": 1, "webglcontextcreationerror": 1 },
  "info": { "pixelRatio": 2, "lowFx": false, "renderer": "probe-renderer", "frames": 0, ... }
}
```
**读法**：`windowWidth=390, windowHeight=844, pixelRatio=3` → 主画布最终 `780×1688`、`renderer.getPixelRatio()=2`，说明 `app.ts:100` 的 `Math.min(dpr, lowFx?1:2)` 钳制**确实生效**；同时 `listeners` 三个计数为 1，证明 **three 真的往 canvas 上挂了 `webglcontextlost/restored/creationerror`**（真机无此方法 → H2-01）。

### 5.7 静态证据（W12b 的盲区）

```bash
$ for t in addEventListener removeEventListener setAttribute webglcontextlost; do printf "%-22s %s\n" "$t" "$(grep -o "$t" dist/wechat/game.js | wc -l)"; done
addEventListener       26
removeEventListener    28
setAttribute           44
webglcontextlost       3

$ node -e "const s=require('fs').readFileSync('dist/wechat/game.js','utf8'); const i=s.indexOf('webglcontextlost'); console.log(JSON.stringify(s.slice(i-160,i+120)))"
"DrawingBuffer:l,powerPreference:u,failIfMajorPerformanceCaveat:d};if(\"setAttribute\"in e&&e.setAttribute(\"data-engine\",`three.js r${\"186\"}`),e.addEventListener(\"webglcontextlost\",fe,!1),e.addEventListener(\"webglcontextrestored\",ie,!1),e.addEventListener(\"webglcontextcreationerror\""
```
（`dist/wechat/game.js` 里就是 three 的 `canvas.addEventListener(...)`，且**没有任何 `"addEventListener" in canvas` 之类的守卫**。）

### 5.8 官方文档查阅（实际 WebFetch/Tavily extract，全部 2026-10-13）

```bash
$ grep -o 'https://developers.weixin.qq.com/[a-zA-Z0-9/._-]*' review-H2/doc-cache/createCanvas.html | sort -u | head -3
https://developers.weixin.qq.com/community/business/CategorySearch
https://developers.weixin.qq.com/community/minigame
```
（`doc-cache/` 是前一位 Agent 的缓存，我**只当线索**；下表 URL 是我当天用 WebFetch/Tavily 实际重新取回内容的。）

---

## 6. 未验证清单

| # | 未验证项 | 为什么没验证 |
|---|---|---|
| 1 | **微信真机（iOS / Android）运行** | 本机无真机、无预览通道；不在本次可验证范围 |
| 2 | **微信官方模拟器（开发者工具）运行** | 本机无微信开发者工具 |
| 3 | **官方上传 / 审核 / 发布 / 公网预览** | 无正式 appid，且任务明确禁止声称已验证 |
| 4 | **`compileType: "game"` 是否被开发者工具接受** | 必须用开发者工具模板验证；**本报告不替它下结论**（与 `docs/` 记录的同一待验证项一致） |
| 5 | **真机 `wx.createCanvas()` 返回对象是否真的没有 `addEventListener`** | 官方文档成员表可作强依据，但文档不等于运行时实测；H2-01 是"高置信度推断 + 可复现的替身/Node 证据"，真机实测待做 |
| 6 | **真机 `onTouchCancel` 的触发时机（进后台/锁屏/系统弹窗是否必发）** | 官方文档未定义 → **未找到官方依据** |
| 7 | **真机 rAF 回调是否带时间戳、是否单调** | 官方文档未说明 → **未找到官方依据** |
| 8 | **真机 `wx.getPerformance().now()` 是否单调** | 官方文档只写"时间戳" → **未找到官方依据** |
| 9 | **真机 WebGL2 在具体机型上的可用性/画质问题** | 官方只给"iOS 高性能模式不保证所有能力完善"的定性说明；具体机型未测 |
| 10 | **真机存储配额（1MB/key、10MB）触发时的具体异常形态** | 替身不模拟配额；当前存档 285 字节，未触边界 |
| 11 | **真机内存/显存增长曲线与闪退阈值** | 需要真机 Memory 面板 |
| 12 | **真机安全区（刘海/灵动岛/挖孔/Home Indicator）实际遮挡情况** | 需要真机截图 |
| 13 | **`dist/wechat/game.js` 在真机微信 JS 引擎（JavaScriptCore / V8）上的语法与 API 兼容** | 只在 Chromium V8 上跑过；ES2017 目标未在真机验证 |
| 14 | **`wx.getSystemInfoSync()` 在异常/降级时是否真会返回 `{}`** | 我用注入 `{}` 复现了"返回 `{}` 会崩"，但"真机是否会返回 `{}`"未验证 |
| 15 | **纹理/CanvasTexture 在真机微信 GL 上的上传与显示** | 替身是 SwiftShader 软件渲染，与真机 GPU 不同 |
| 16 | **中文字体（PingFang SC 等）在真机 canvas 2D 上的可用性与度量** | 官方只说 2D 实现"HTML Canvas 2D Context 的大部分"；未做真机字体对比 |

---

## 7. 我读过的目录清单

**本次实际读取（按任务授权范围）：**

| 路径 | 用途 |
|---|---|
| `frontend-rebuild-hm-work-H2/ISOLATION.md`、`package.json` | 隔离声明与依赖版本（three 0.186.1、esbuild 0.28.2、typescript 7.0.2） |
| `src/wechat/main.ts`、`src/wechat/wx.d.ts` | 被审适配层主体 |
| `src/platform/canvas.ts`、`src/platform/clock.ts` | 画布工厂、时钟 |
| `src/app/app.ts`、`src/app/input.ts` | 渲染器装配、帧循环、输入控制器 |
| `src/game/gesture.ts`、`src/game/session.ts` | 手势闸门、会话（前后台/存档事务） |
| `src/core/save.ts`、`src/core/offline.ts` | 存档解析、离线结算 |
| `src/ui/hud.ts`、`src/ui/fx.ts` | HUD 画布纹理、飘字/涟漪纹理（H2-05 证据） |
| `src/web/main.ts` | 浏览器入口（对照） |
| `tools/build-wechat.mjs` | 构建配置（H2-07 证据） |
| `dist/wechat/game.js`、`game.json`、`project.config.json`、`MANIFEST.json` | 被审产物 |
| `test/wechat-sim.mjs`、`test/lib.mjs` | 替身测试与 mock-wx |
| `node_modules/three/build/three.module.js`、`three.core.js`、`node_modules/three/package.json` | three r186 实证（行号引用） |
| `review-H2/baseline-sha256.txt`、`baseline-dist-wechat-sha256.txt` | 基线校验 |
| `review-H2/doc-cache/`（全部 50 个 txt/html） | **只当线索**；引用时以我当天实际取回的官方 URL 为准 |
| `review-H2/out/probe-h2.log`、`probe-h2-results.json`、`wechat-sim-copy.log`、`wechat-sim-results.json` | 前一位 Agent 的半成品，**只当线索**，我已独立重跑核对 |
| `review-H2/scripts/probe-h2.mjs`、`scripts/simcopy/`、`scripts/fetchdoc.py` | 前一位 Agent 的脚本，**未审阅其正确性**，未直接引用其结论 |
| `docs/04-微信小游戏模拟验证报告.md`、`docs/00-最终交付报告.md` 等 `docs/` 交付报告 | **只当"被审对象的自我声明"**，不当证据 |

**明确未读取（遵守任务硬规则 4、5）：** `wechat-game-0.1-ds/`、`3d-spike-ds/`、`wechat-spike-ds/`、`app/`、`little-town/`、MIMO 目录、其它 `frontend-rebuild-hm-work-*` 副本、`frontend-rebuild-hm-lead-验收/`、`docs/` 里的旧截图与旧「第二步」报告、任何凭据文件。

**关于 `node_modules`**：它是指向 `/vol1/ai/projects/wyszz-new/frontend-rebuild-hm/node_modules` 的符号链接，我**只读**（grep/read/sed），未写入。

---

## 8. 我写入的文件清单及 SHA256

（SHA256 与行数在本报告写完后由第 9 节末尾的复核命令生成；下表为写入清单。）

| 文件 | 说明 |
|---|---|
| `docs/21-H2-微信适配层真机风险评审报告.md` | **本报告（唯一交付物）** |
| `review-H2/scripts-mine/probe-h2.mjs` | 我自写的 H2 探针（画布增长/触摸中断/空系统信息/存储/前后台抖动/DPR） |
| `review-H2/scripts-mine/probe-b3.mjs` | 诊断探针：定位"B 场景失败"其实是 modal 吞点击 |
| `review-H2/scripts-mine/probe-b4.mjs` | 诊断探针：排除 modal 后复现残留触点卡死 |
| `review-H2/scripts-mine/probe-g.mjs` | Node 内跑真实 game.js，观测主画布尺寸/像素比/listener 注册 |
| `review-H2/out/mine/wechat-sim-run.log` | 我重跑 `test/wechat-sim.mjs` 的原始输出（37/37） |
| `review-H2/out/mine/probe-h2-mine.log` / `probe-h2-mine.json` | 我的探针原始输出 |
| `review-H2/out/mine/probe-b3-trace.json` | B3 逐步 trace |
| `review-H2/out/mine/probe-b4-stuck-touch.json` | B4 复现结果 |
| `review-H2/out/mine/probe-g-canvas-size.json` | G 结果 |
| `review-H2/out/mine/baseline.clean.txt` / `dist-baseline.clean.txt` | 剔除 `==>` 头行后的基线清单（校验用） |

**未写入/未修改**：`src/**`、`test/**`、`tests/**`、`tools/**`、`contract-fixtures/**`、`dist/**`、`package.json`、`tsconfig.json`、`ISOLATION.md`、`docs/` 下任何已有文件、`evidence/**`（`test/wechat-sim.mjs` 自己会写 `evidence/wechat-sim/`，那是测试自身行为，不是我改源码）。

### 8.1 收尾复核（任务书要求）

```bash
$ grep -v '^==>' review-H2/baseline-sha256.txt > review-H2/out/mine/baseline.clean.txt
$ sha256sum -c review-H2/out/mine/baseline.clean.txt
OK count: 51 ; mismatches: 0 ; exit code: 0
覆盖：src 30 个文件、test 8 个、tests 1 个、tools 12 个 —— 全部与基线一致，本次评审未改动任何已有源码/测试/工具文件。
```

`dist/wechat/` 四个产物也与 `review-H2/baseline-dist-wechat-sha256.txt` 逐字节一致（见 5.1）。

---

## 9. 待决问题

| # | 待决问题 | 为什么我不能自己定 |
|---|---|---|
| 1 | **H2-01 怎么修**：给 `wx.createCanvas()` 的返回值补 `addEventListener/removeEventListener/setAttribute` 垫片？还是换/改 three 的 canvas 适配？ | 属"改源码"，任务书规定 P0 只报告、由用户决定谁修；且垫片的正确性需要真机验证 |
| 2 | **H2-02 要不要做 WebGL1 兜底**：three r186 已放弃 WebGL1；要么降 three 版本，要么做"WebGL2 不可用"的友好提示页 | 涉及依赖版本/产品决策，超出评审范围；且 0.1 是否必须覆盖老设备需产品判断 |
| 3 | **H2-03 的 `{}` 兜底策略**：`getSystemInfoSync()` 异常时用 `wx.getWindowInfo()` 回退，还是给固定 390×844 默认值？ | 属实现选择；且"真机是否会返回 `{}`"未验证（第 6 节 #14） |
| 4 | **H2-04 的修法**：`onHide` 时清空 `ptrs`，还是给残留触点加超时？清空是否会造成"回前台时正在进行的拖动被吞"？ | 需要真机确认 `onTouchCancel` 行为（第 6 节 #6）后再定 |
| 5 | **H2-05 的修法**：飘字纹理按文案缓存复用，还是建一个离屏画布池？ | 属实现选择；也需真机内存曲线确认阈值 |
| 6 | **H2-06 安全区**：0.1 是否必须适配刘海屏（可能只要求 0.2 再做）？ | 产品范围问题 |
| 7 | **H2-07 `compileType`**：改 `minigame` 还是保持 `game`？ | **必须**用微信开发者工具实际导入验证后才能定；本报告不替它下结论 |
| 8 | **H2-08 时间源**：是否改用 `wx.getPerformance().now()` 作为单调时钟，同时保留 `Date.now()` 作为离线锚点？ | 需先验证 `Performance.now()` 的单调性（第 6 节 #8）；且改动会影响契约时间语义 |
| 9 | **`libVersion: "3.0.0"` 是否合适**：WebGL2 需 ≥2.24.0（够），但 `wx.getDeviceBenchmarkInfo` 需 ≥3.4.5（代码没用，用的是 `getSystemInfoSync().benchmarkLevel`）；是否要提高最低基础库？ | 涉及用户覆盖范围的产品决策 |
| 10 | **`test/wechat-sim.mjs` 的 W12b 是否要扩 banned 列表** | 属改测试文件，任务书不允许我改；由用户决定 |
| 11 | **`docs/04-微信小游戏模拟验证报告.md` 里"1 主画布 + HUD 离屏画布（≥3 个，共 9）"的表述**是否要随 H2-05 一起修订 | 属改文档，非本报告职责 |
| 12 | **0.1 是否允许"真机 WebGL2 不可用就黑屏"这种失败模式** | 产品/验收标准问题 |

---

## 10. 官方文档 URL 清单（全部查阅于 2026-10-13）

| 文档 | URL | 用于 |
|---|---|---|
| Canvas（画布对象成员表） | https://developers.weixin.qq.com/minigame/dev/api/render/canvas/Canvas.html | **H2-01** |
| wx.createCanvas | https://developers.weixin.qq.com/minigame/dev/api/render/canvas/wx.createCanvas.html | H2-01、H2-05 |
| Canvas.getContext / RenderingContext | https://developers.weixin.qq.com/minigame/dev/api/render/canvas/Canvas.getContext.html | **H2-02** |
| RenderingContext（2d/WebGL 支持情况） | https://developers.weixin.qq.com/minigame/dev/api/render/canvas/RenderingContext.html | 第 6 节 #16 |
| Adapter（无 DOM/BOM；weapp-adapter 才模拟 canvas.addEventListener；非基础库一部分） | https://developers.weixin.qq.com/minigame/dev/guide/runtime/adapter.html | **H2-01**、H2-09 |
| 渲染（一个上屏画布 + 多个离屏画布；锁帧） | https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html | H2-05 |
| WebGL2.0 渲染支持说明 | https://developers.weixin.qq.com/minigame/dev/guide/game-engine/unity-webgl-transform/Design/WebGL2.html | **H2-02** |
| wx.getSystemInfoSync | https://developers.weixin.qq.com/minigame/dev/api/base/system/wx.getSystemInfoSync.html | **H2-03** |
| wx.getWindowInfo（statusBarHeight / safeArea） | https://developers.weixin.qq.com/minigame/dev/api/base/system/wx.getWindowInfo.html | **H2-06** |
| wx.onWindowResize | https://developers.weixin.qq.com/minigame/dev/api/ui/window/wx.onWindowResize.html | H2-06 |
| 本地缓存（隔离/清理策略） | https://developers.weixin.qq.com/minigame/dev/guide/base-ability/storage.html | H2-10 |
| wx.setStorageSync（1MB/key、10MB 总量） | https://developers.weixin.qq.com/minigame/dev/api/storage/wx.setStorageSync.html | **H2-10** |
| wx.getStorageSync | https://developers.weixin.qq.com/minigame/dev/api/storage/wx.getStorageSync.html | H2-10 |
| wx.removeStorageSync | https://developers.weixin.qq.com/minigame/dev/api/storage/wx.removeStorageSync.html | H2-10 |
| wx.onTouchStart / onTouchMove / onTouchEnd / onTouchCancel | https://developers.weixin.qq.com/minigame/dev/api/device/touch-event/wx.onTouchStart.html ・ .../wx.onTouchMove.html ・ .../wx.onTouchEnd.html ・ .../wx.onTouchCancel.html | **H2-04** |
| Touch（identifier / clientX / clientY） | https://developers.weixin.qq.com/minigame/dev/api/device/touch-event/Touch.html | H2-04、第 4 节 |
| wx.onShow / wx.onHide | https://developers.weixin.qq.com/minigame/dev/api/base/app/life-cycle/wx.onShow.html ・ .../wx.onHide.html | H2-04、H2-08 |
| requestAnimationFrame | https://developers.weixin.qq.com/minigame/dev/api/render/frame/requestAnimationFrame.html | **H2-09** |
| wx.getPerformance / Performance.now | https://developers.weixin.qq.com/minigame/dev/api/base/performance/wx.getPerformance.html ・ https://developers.weixin.qq.com/minigame/dev/api/base/performance/Performance.now.html | H2-08 |
| 分包加载（主包 4M / 总量 30M） | https://developers.weixin.qq.com/minigame/dev/guide/base-ability/subPackage/useSubPackage.html | 包体结论 |
| 项目配置文件（compileType 有效值：minigame / gamePlugin） | https://developers.weixin.qq.com/minigame/dev/devtools/projectconfig.html | **H2-07** |
| 小游戏配置 game.json（deviceOrientation / showStatusBar / subpackages） | https://developers.weixin.qq.com/minigame/dev/reference/configuration/app.html | H2-06、H2-07 |
| 兼容处理（版本号比较 / API 存在判断） | https://developers.weixin.qq.com/minigame/dev/guide/runtime/client-lib/compatibility.html | H2-02、H2-07 |
| 基础库 | https://developers.weixin.qq.com/minigame/dev/guide/runtime/client-lib/ | H2-02 |
| 小游戏的运行环境（iOS JavaScriptCore / Android V8） | https://developers.weixin.qq.com/minigame/dev/guide/runtime/env.html | 第 6 节 #13 |
| JavaScript 支持情况（无 eval / 无 new Function） | https://developers.weixin.qq.com/minigame/dev/guide/runtime/js-support.html | 第 6 节 #13 |
| wx.onMemoryWarning / wx.triggerGC | https://developers.weixin.qq.com/minigame/dev/api/device/memory/wx.onMemoryWarning.html ・ https://developers.weixin.qq.com/minigame/dev/api/base/performance/wx.triggerGC.html | H2-11 |
| wx.onError | https://developers.weixin.qq.com/minigame/dev/api/base/app/app-event/wx.onError.html | H2-11 |
| wx.getDeviceBenchmarkInfo（基础库 3.4.5） | https://developers.weixin.qq.com/minigame/dev/api/base/system/wx.getDeviceBenchmarkInfo.html | 第 9 节 #9 |

**标注「未找到官方依据」的条目**：真机 `onTouchCancel` 的触发时机；rAF 回调是否带时间戳；`Performance.now()` 的单调性；真机 `wx.createCanvas()` 返回值是否真的没有 `addEventListener`（文档成员表可作强依据，但非运行时实测）。

---

## 11. 一句话给 Lead

`src/wechat/` 的**逻辑**是干净的（不依赖 DOM、不联网、存档事务有回滚、离线结算幂等），但**它对"真机 canvas 是浏览器 canvas"这件事做了致命假设**：three r186 会在构造期往 canvas 上挂 `webglcontextlost` 等监听，而官方文档里微信 Canvas 根本没有 `addEventListener`。替身用的是原生 `OffscreenCanvas`，所以 37/37 全部通过也发现不了这一点。**先修 H2-01/H2-02/H2-03 三个 P0，再用开发者工具导入验证 H2-07，然后才谈真机验收。**

---

## 12. 本报告自身的 SHA256 与行数

> 说明：本报告**写完后又被编辑过两次**（补第 12 节、补最终复核输出），所以正文里**不内嵌**一个会立刻过期的哈希值。
> 权威的最终 SHA256 与行数由收尾命令现场计算，并写在给 Lead 的回执里：
> `sha256sum docs/21-H2-微信适配层真机风险评审报告.md && wc -l docs/21-H2-微信适配层真机风险评审报告.md`
> 编辑前（476 行）的哈希是 `3da4c081…`，**已过期，不要引用**。

**我写入的全部文件 SHA256（2026-10-13）**：

```bash
$ sha256sum review-H2/scripts-mine/*.mjs review-H2/out/mine/*
649b3e9b008984901999f2451c535f5ee01475d622d0b581a4e65c3e92a85f9a  review-H2/scripts-mine/probe-b3.mjs
532b6255dcf4246986c99f6a29e30739eb573036b9ebd2256dbc4fe986460747  review-H2/scripts-mine/probe-b4.mjs
50d9e8fbf4f118a9d28739b3893a421b49389faf285dac1d1d2241d35bd0c29d  review-H2/scripts-mine/probe-g.mjs
7524504021a12ef3e97eb3ae1b8350e910e8bb4eecf73ff17a9a6cdb439a6570  review-H2/scripts-mine/probe-h2.mjs
cecece94e760198cd3f3245ac6c2684a2d15b307d436c1d7b1715dbf868866ec  review-H2/out/mine/baseline.clean.txt
14f00faf0ba50d7d3fb265ae9950b066e62d261f447b9b4d456beb5cac4824bc  review-H2/out/mine/dist-baseline.clean.txt
0fec2c302aa8bad2a0c01d695d78de0c735adacfab2d63fae0b6ba3ed2e6607f  review-H2/out/mine/probe-b3-trace.json
0f0e0fdd56d87f742f1e02b2b55f9fcdac563710939e9412816894f197e006ea  review-H2/out/mine/probe-b4-stuck-touch.json
bea701d80e56f5cb734a6937edc802d8a1f7d296cb350d13f42a1c521eb77c05  review-H2/out/mine/probe-g-canvas-size.json
ea9a487aa19995c6a727d58a132ccb0f7c0322ae2ef4081210b44875ca6003d3  review-H2/out/mine/probe-h2-mine.json
47fb0dd7c95842c8ab5cd82515a5f149be5a0231dd394b5ab25892c035e10f83  review-H2/out/mine/probe-h2-mine.log
b7c2025baefe656d0686aa2f81b8bd3f3f4e484805f6be7de6aac537dcb2bf46  review-H2/out/mine/wechat-sim-run.log
```

**收尾复核（最终一次）**：

```bash
$ sha256sum -c review-H2/out/mine/baseline.clean.txt 2>/dev/null | grep -c ': OK$'
51
$ sha256sum -c review-H2/out/mine/baseline.clean.txt 2>/dev/null | grep -v ': OK$'   # 无输出 = 0 处不一致
$ find src test tests tools contract-fixtures -newermt '2026-10-13 00:00' -type f     # 无输出 = 今天未改动任何已有文件
```
→ `src/`、`test/`、`tests/`（含 `tools/`、`contract-fixtures/`）**51/51 与基线一致，本次评审零改动**。
