# 12 · 真机与官方模拟器验收手册（面向普通用户）

> **这份手册是给不写程序的人看的。** 你不需要看懂代码，只需要照着步骤点、照着表格看、把结果填进
> `docs/13-真机验收结果记录模板.md`。

**适用范围**：《我要当岛主》0.1 的微信小游戏产物 `dist/wechat/`，在**微信开发者工具自带的模拟器**和
**真手机**上做人工验收。本手册**不覆盖** 0.2（种子生成、有限扩岛），也**不覆盖**正式上传、提审、发布流程。

---

## 0. 先读这一段：现在的真实状态

这一点必须先说清楚，否则后面所有表格都会被误读。

| 事项 | 现在的状态 |
|---|---|
| 契约功能验收（32 个夹具变体） | 已做，32/32（依据 `docs/00-最终交付报告.md` §一） |
| 浏览器自动化测试 | 已做，59/59（Chromium + 软件渲染 SwiftShader，依据 `docs/03-浏览器测试报告.md`） |
| 微信**替身宿主**验证（Worker + 模拟 wx，37/37） | 已做，**但这不是官方模拟器，也不是真机**（依据 `docs/04-微信小游戏模拟验证报告.md` §重要边界） |
| **微信官方模拟器**（开发者工具里的模拟器） | **从未运行过**（本机没有微信开发者工具，依据 `docs/00` §一） |
| **微信真机** | **从未验证过**（依据 `docs/00` §一、`docs/04` §重要边界） |
| 微信官方上传 / 审核 / 发布 | **从未验证过**（依据 `docs/00` §一） |
| 帧率数字 19.9 fps | **是软件渲染（SwiftShader）的数字，不代表手机**（依据 `docs/00` §三、`docs/03` §已知局限） |

**因此：本手册第 3 节表格里每一行的"结果"列，现在**全部**预填为 `未验证`。**
这不是偷懒，而是事实——到目前为止，没有任何一项是在官方模拟器或真机上跑过的。
你在测试时把它改成 `通过` 或 `失败`；**没测的就保持 `未验证`，不许留白，也不许填 `通过`。**

本手册里凡是涉及微信平台行为的说法，都附了官方文档链接和查阅日期（**查阅日期：2026-10-12**）。
查不到官方依据的，会明确写"**未找到官方依据**"或"**未确认**"，绝不凭印象编。

---

## 1. 前置条件

### 1.1 电脑与微信开发者工具

| 项目 | 要求 | 依据 |
|---|---|---|
| 操作系统 | Windows / macOS 均可（官方下载页按操作系统提供安装包） | 官方《微信开发者工具》页（小游戏版）<br>https://developers.weixin.qq.com/minigame/dev/devtools/download.html<br>（该页指向下载页 https://developers.weixin.qq.com/miniprogram/dev/devtools/download ） |
| 工具版本 | **官方文档没有给出一个统一的"最低版本"。** 官方在多个功能页里给出的零散下限是：小游戏真机远程调试要求工具 **≥ 1.02.1809260**；真机调试 2.0 自 **1.05.2107221 RC** 起支持；`packOptions` 的 `regexp` / `glob` 规则要求工具 **≥ 1.02.1809260**。 | 官方《功能概述》（小游戏远程调试）https://developers.weixin.qq.com/minigame/dev/devtools/remote-debug.html ；官方《真机调试2.0》https://developers.weixin.qq.com/miniprogram/dev/devtools/remote-debug-2.html ；官方《项目配置文件》https://developers.weixin.qq.com/minigame/dev/devtools/projectconfig.html |
| 工具版本（实操建议） | **请安装官方下载页上的最新稳定版。** 上面那些下限都是"至少"，不是"够了"。 | 同上 |
| **具体版本号** | **未确认。** 官方下载页是动态渲染的页面，我在 2026-10-12 没有从该页读出确切版本号。**去哪里确认：**打开 https://developers.weixin.qq.com/miniprogram/dev/devtools/download ，页面上会写当前稳定版版本号。 | — |
| 登录 | 需要用微信**扫码登录**开发者工具；登录的微信号需要是该 AppID 的开发者/管理员。 | 官方《界面》https://developers.weixin.qq.com/miniprogram/dev/devtools/page.html |

> **关于"游客模式"（重要限制）**
> 官方原文："如果暂时没有微信，可以直接点击游客模式进入（**游客模式只能编辑本地项目**）"。
> —— 官方《界面》https://developers.weixin.qq.com/miniprogram/dev/devtools/page.html
> 也就是说：**用游客模式登录，无法做本手册要求的预览与真机调试。** 必须用微信扫码登录。

### 1.2 AppID：三种情况，限制不一样

微信小游戏**必须有 AppID 才能预览/真机调试/上传**（官方在导入小游戏的步骤里明确要求"填入游戏自己的小游戏 AppID"，
见官方《转换工具使用指南》https://developers.weixin.qq.com/minigame/dev/guide/game-engine/common-adaptation/Design/TransformTool.html ）。

| 情况 | 能不能做本手册的验收 | 依据 / 说明 |
|---|---|---|
| **A. 正式小游戏 AppID**（已注册小游戏账号，服务类目选"游戏"） | 能。这是唯一能走到"上传 → 体验版 → 提审"的路径。 | 官方《发布流程》https://developers.weixin.qq.com/minigame/introduction/gamemaker/minigame/release |
| **B. 小程序与小游戏"测试号"** | **能预览到真机。** 官方原文："即可获得为自己分配好的**小程序和小游戏测试账号**"；"点击工具栏上的预览按钮即可在**真机上预览体验**"。 | 官方《申请测试号》https://developers.weixin.qq.com/miniprogram/dev/devtools/sandbox.html |
| **C. 产物里现在写的 `touristappid`（游客工程值）** | **限制未确认。** 官方文档没有列出 `touristappid` 的完整限制清单。官方《开发者工具更新日志》里出现过一条"优化 **touristappid 禁用提示**"，说明它确实是一个被工具识别的特殊值，且会被"禁用"。 | 官方更新日志 https://developers.weixin.qq.com/miniprogram/dev/devtools/uplog |

**测试号能不能"上传"？** —— **官方文档未找到明确条文。**
我在微信开放社区里看到社区技术运营专员的回复是"测试版 appid 无法上传"（
https://developers.weixin.qq.com/community/minihome/doc/000020de490d78321c8c9ba3e56800 ）。
**这是社区回复，不是正式文档，请按"未确认"对待。**
另外官方《云测常见问题》里有一句"不支持使用测试 AppID 打开小程序"（
https://developers.weixin.qq.com/miniprogram/dev/devtools/minitest/cloud_problem.html ），但那是云测插件的限制，不能直接推广到上传。

**本项目产物的现状：** `dist/wechat/project.config.json` 里的 `appid` 是 `"touristappid"`，
描述字段写的是"游客模式工程，仅用于模拟器验证"。**要换 AppID，看第 2.9 步。**

### 1.3 基础库版本

| 项目 | 内容 | 依据 |
|---|---|---|
| 产物里写的版本 | `dist/wechat/project.config.json` → `"libVersion": "3.0.0"`（一个**具体版本号**） | 产物文件本身（SHA256 见第 2.0 步） |
| 官方允许的写法 | `libVersion` 可以写**具体版本号**，也可以写 `latest`（最新非灰度基础库）/ `trial`（最新基础库）/ `widelyUsed`（使用比例最高的基础库）。 | 官方《项目配置文件》https://developers.weixin.qq.com/minigame/dev/devtools/projectconfig.html |
| 一个重要细节 | 官方原文："手动在开发者工具-详情-本地设置中改变基础库的版本，会**覆盖掉** `project.private.config.json` 的 `libVersion` 字段"；而且 `latest` / `trial` / `widelyUsed` 这三个值**在 `project.private.config.json` 里无效**。 | 同上 |
| 基础库从哪来 | 官方原文："微信客户端都是携带 **上一个稳定版** 的基础库发布的"，新版本再灰度 12～24 小时。所以真机上实际用的基础库版本由**手机上的微信客户端**决定，不是你写了 `3.0.0` 就一定是 `3.0.0`。 | 官方《基础库》https://developers.weixin.qq.com/miniprogram/dev/framework/client-lib |
| 怎么在真机上查基础库版本 | 打开小游戏右上角菜单 → 打开调试 → 展开 vConsole → 切到 WeChat 页（这是官方在 AI 调试指南里给出的查看方式）。 | 官方《调试指南》https://developers.weixin.qq.com/miniprogram/dev/ai/debugging.html |
| 真机调试对基础库的要求 | 官方《真机调试2.0》（小程序页）写：Android 微信客户端 **8.0.6 及以上** + 基础库 **2.18.1 及以上**；iOS 微信客户端 **8.0.8 及以上** + 基础库 **2.18.1 及以上**。<br>而小游戏那页（《功能概述》）写的是另一套更老的要求：工具 ≥ 1.02.1809260，iOS 11.2~11.4.1 + 微信 6.7.2+，Android 微信 6.7.3+。<br>**两页不一致，官方没有统一口径** —— 以工具里的实际提示为准。 | https://developers.weixin.qq.com/miniprogram/dev/devtools/remote-debug-2.html<br>https://developers.weixin.qq.com/minigame/dev/devtools/remote-debug.html |
| 小游戏真机调试的"能力升级" | 官方《真机调试能力升级 Beta》里，v1.0 明确标注"**注意：iOS 暂不支持**"。 | https://developers.weixin.qq.com/minigame/dev/devtools/remote-debug-v2.html |
| **本项目要求的最低基础库** | **未确认。** 官方文档没有针对"用 `wx.createCanvas` + WebGL 的小游戏"给出统一最低基础库。**去哪里确认：**用工具编译一次，看 Console 是否报某个 API 不存在；或在工具"详情-本地设置-调试基础库"里试几个版本。 | — |

### 1.4 手机要求

| 项目 | 内容 | 依据 |
|---|---|---|
| 必须装微信 | 真机预览是"用手机微信扫描二维码"打开开发版小游戏。 | 官方《转换工具使用指南》https://developers.weixin.qq.com/minigame/dev/guide/game-engine/common-adaptation/Design/TransformTool.html |
| 官方给的**最低客户端版本** | 小游戏真机远程调试：iOS 11.2~11.4.1 系统 + 微信客户端 6.7.2 及以上；Android 微信客户端 6.7.3 及以上。<br>真机调试 2.0（小程序页）：Android 微信 8.0.6+ / iOS 微信 8.0.8+。<br>**两套数字不一致，且都很旧，未确认哪个对当前工具生效。** | https://developers.weixin.qq.com/minigame/dev/devtools/remote-debug.html<br>https://developers.weixin.qq.com/miniprogram/dev/devtools/remote-debug-2.html |
| **手机机型/配置的最低要求** | **未确认，未找到官方依据。** 官方没有给出小游戏的手机硬件门槛。**去哪里确认：**工具"详情"页或官方文档站搜索"小游戏 兼容性评估"。 | — |
| 一个可用的官方性能信号 | 官方 `wx.getSystemInfoSync` 的 `benchmarkLevel`（**仅 Android**）：`-2` 或 `0` = **该设备无法运行小游戏**；`-1` = 性能未知；`>=1` = 设备性能值。<br>本项目用它做性能分档：**0～19 视为低端机**（`src/wechat/main.ts` 第 41 行与 `lowFx` 判定）。 | 官方 `wx.getSystemInfoSync` https://developers.weixin.qq.com/minigame/dev/api/base/system/wx.getSystemInfoSync.html<br>本项目 `src/wechat/main.ts` |
| 刘海屏 / 安全区 | 官方 `wx.getSystemInfoSync` 返回 `safeArea`（**基础库 2.7.0 起**），并明确提示："部分机型没有安全区域概念，也不会返回 `safeArea` 字段，**开发者需自行兼容**"。 | 同上 |
| **建议准备**（这是建议，不是官方要求） | 至少两台机器：① 一台**带刘海/灵动岛的 iPhone**（测安全区遮挡）；② 一台**中低端 Android**（测帧率与发热）。 | 无官方依据，属于本手册的测试设计建议 |

### 1.5 动手前请准备好

1. 一台能装微信开发者工具的电脑（Windows / macOS）。
2. 一个能扫码登录开发者工具的**微信账号**。
3. 一个 **AppID**：正式小游戏 AppID，或**小游戏测试号**（见 1.2）。
4. 至少一台手机（装微信），能扫二维码。
5. 本项目的产物目录 `dist/wechat/`（含 `game.js`、`game.json`、`project.config.json`、`MANIFEST.json`）。
6. `docs/13-真机验收结果记录模板.md` 的一份副本（用来填结果）。
7. 大约 1～2 小时（真机调试连接与截图比较费时间）。

---

## 2. 导入与预览步骤

> 每一步都写了"**应看到什么**"。看不到就停下，先看第 5 节排查，不要跳步。

### 2.0 第 0 步：先确认产物没坏（1 分钟）

在电脑上打开命令行，进入产物目录，算一下每个文件的指纹（SHA256）。

```
cd <你的项目路径>/dist/wechat
sha256sum game.js game.json project.config.json MANIFEST.json
```

**应看到**（这四个值是本次交付的产物指纹，来自本目录 `MANIFEST.json` 与实际计算）：

| 文件 | 字节数 | SHA256 |
|---|---|---|
| `game.js` | 628731 | `7185453263687c277f293c2b01d7992c1e70450b2c33a3944a724974635d2517` |
| `game.json` | 64 | `82526622d158db584fe0783eb469d01eaaa33a85360c28d83bf2b01cb031b8ec` |
| `project.config.json` | 498 | `113e97a6b1b13773e91d5aec0aa9b9441a4c81667b1e5f074b0e2f088b770094` |
| `MANIFEST.json` | 524 | `e72bcdca5a8413df123cb71d1333bb413935adf370e45c73a39ae6ed11da6f65` |

（`game.js` 约 614 KiB，远低于官方"小游戏主包不超过 4M"的限制 ——
官方《代码包》https://developers.weixin.qq.com/minigame/dev/guide/base-ability/code-package.html ）

### 2.1 第 1 步：安装并打开微信开发者工具

1. 打开官方下载页 https://developers.weixin.qq.com/miniprogram/dev/devtools/download ，按你的操作系统下载并安装。
2. 启动工具，出现登录页。
3. 用**手机微信扫码登录**（不要用"游客模式"，见 1.1 的说明）。

**应看到**：扫码成功后进入"项目列表"页（左侧有项目列表，右上角有"+"号）。
—— 依据：官方《界面》https://developers.weixin.qq.com/miniprogram/dev/devtools/page.html

### 2.2 第 2 步：导入 `dist/wechat`

这一步照官方《转换工具使用指南》里"导入小游戏"的四步做：

1. 在工具左侧菜单里选择 **小游戏** 类别。
2. 点击右上角的 **导入** 按钮（或点 **+** 号新建项目）。
3. 在"创建小游戏"页面里：
   - **目录**：选到 `dist/wechat` 这一层（不要选它的上一级，也不要选 `dist`）。
   - **AppID**：填你自己的小游戏 AppID 或小游戏测试号（见 1.2）。
   - **模板**：选 **小游戏**。
4. 点击 **创建**。

—— 依据：官方《转换工具使用指南》"微信开发者工具调试 / 第一步、第二步"
https://developers.weixin.qq.com/minigame/dev/guide/game-engine/common-adaptation/Design/TransformTool.html

**应看到**：
- 项目窗口打开，出现**模拟器**区域（一块手机形状的画面）、目录树（能看到 `game.js`、`game.json`、`project.config.json`）、
  以及底部的**调试器**面板。
- 目录树里应该只有这 4 个文件，**没有** `src/`、`node_modules/`、`package.json` 之类的东西。

**如果工具提示 AppID 有问题**：先不要慌，跳到第 2.9 步改 AppID。

### 2.3 第 3 步：编译，看模拟器首屏

1. 点工具栏上的 **编译**（或按 `Ctrl/⌘ + R`）。
2. 等 3～10 秒。

**应看到**（这是本项目 0.1 的实际首屏内容，依据 `docs/01-视觉设计说明.md` 与 `src/ui/hud.ts`）：

- 画面**竖屏**，中央是一座**浮空小岛**：岛面有草地、米色石板路、一栋三层市政厅（青蓝屋顶 + 金色尖顶 + 旗帜）、
  4 栋彩色屋顶的房屋、一座风车、一口水井、一个池塘、若干树木；岛边有云，岛底是分层岩土截面和发光水晶。
- **顶部资源栏**（一条横向卡片）：
  - 左卡：`Lv` 徽标 + **等级 1**、**金币 0.0**、**`每分钟 +10.0`**；
  - 右卡：**`声望`**，下面一行 **`可用 0 · 寻访 0`**。
- **底部栏**：
  - 左：一个黄色按钮 **`升级市政厅 → Lv.2`**，下面小字 **`花费 20 金币`**；
  - 右：一张存档卡，绿点 + **`已保存`** / **`自动存档`**。
- **市政厅头顶**有一个小牌子，写着 **`Lv.1 市政厅`**。
- 画面下方会**短暂出现**一条提示：**`新的岛屿！点居民领金币，点市政厅升级`**（约 4 秒后消失）。

**如果模拟器是黑屏/白屏**：看第 5 节第 4 条。

### 2.4 第 4 步：看 Console 日志（确认跑的是同一套"冻结规则"）

1. 在底部**调试器**面板里，切到 **Console** 标签页。
2. 找到启动时打印的几行。

**应看到**（这是本项目 0.1 的指纹输出，来自 `src/core/fingerprints.ts`；浏览器端与微信替身宿主端都会打印同样的值，
依据 `docs/04-微信小游戏模拟验证报告.md` 的 W02）：

```
[fingerprint] economy OK wyszz-core-economy-v1:r1=10000:m1=10000
[fingerprint] visit OK wyszz-core-visit-v1:coin=3000:rep=1:tag=居民
[fingerprint] upgrade OK wyszz-core-upgrade-v1:c1=20000:c2=25000:r1=10000:r2=12000:growth=1.22
[fingerprint] save OK wyszz-core-save-v2:v=2:support=1,2:fields=13:carry=0..59999:ns=wyszz-0.1-ds-save
[fingerprint] offline OK wyszz-core-offline-v1:schema=2:base=60000:step=60000:cap=none
[fingerprint] all OK
```

还会有一行渲染器信息，末尾带 `platform=wechat`。

**应看到**：**没有红色的报错（pageerror）**。若有报错，把整段文字抄进结果记录模板的"问题描述"。

### 2.5 第 5 步：在官方模拟器里做功能检查

1. 模拟器里用鼠标**按住拖动** = 单指拖动；模拟器支持触摸模拟。
2. 用鼠标**单击**居民小人 = 单指点击。
3. 按第 3 节的表格逐项做，并把结果填进 `docs/13`。

**应看到**：每次点击居民，居民头顶冒出 `+3 金币` 和 `+1 声望` 的飘字，顶部金币与声望同步变化。

### 2.6 第 6 步：真机预览（把游戏装到手机上跑）

1. 点工具栏上的 **预览** 按钮。
2. 等工具打包上传完成（进度条走完）。

**应看到**：
- 弹出一个**二维码**窗口。
- 用**手机微信扫这个二维码**，手机上会打开"开发版"小游戏（开发版代码包只能通过扫码获得 ——
  官方《代码包》https://developers.weixin.qq.com/minigame/dev/guide/base-ability/code-package.html ）。
- 手机上**应看到**与模拟器一致的首屏（竖屏、浮岛、顶部资源栏、底部升级栏）。

**如果二维码出不来或手机打不开**：看第 5 节第 5 条。

### 2.7 第 7 步：真机调试（在电脑上看手机里的日志）

1. 点工具栏上的 **真机调试** 按钮。官方说明：工具会**先把本地代码打包上传**，就绪后手机扫码即可弹出调试窗口
   （官方《功能概述》https://developers.weixin.qq.com/minigame/dev/devtools/remote-debug.html ）。
2. 用手机微信扫码。

**应看到**：
- 电脑上弹出**远程调试窗口**：左侧是调试器（Console / Sources / …），右侧是"信息视图"，
  信息视图里会显示**手机型号、系统、名称、微信版本**以及**通信延时**。
- Console 里同样有第 2.4 步的那几行指纹日志。

**要注意的两条官方限制**：
- 小游戏远程调试"**目前尚不支持 Storage 面板**"（官方《功能概述》）。所以**看不到存档内容不是 bug**。
- 官方《真机调试能力升级 Beta》里 v1.0 标注"**注意：iOS 暂不支持**"（
  https://developers.weixin.qq.com/minigame/dev/devtools/remote-debug-v2.html ）。

### 2.8 第 8 步：在真机上看 vConsole 日志

1. 手机上打开小游戏后，点右上角 **…** 按钮 → 选 **开发调试** → 点 **打开调试**。
2. 重新进入小游戏。

**应看到**：屏幕右下角出现一个 **vConsole** 按钮，点开可以看到手机上的运行日志。
—— 依据：官方《转换工具使用指南》"第四步：查看调试日志 / 真机调试"
https://developers.weixin.qq.com/minigame/dev/guide/game-engine/common-adaptation/Design/TransformTool.html

### 2.9 第 9 步：换 AppID（需要时）

产物自带的 AppID 是 `touristappid`。要换成自己的：

**方法（推荐）**：在工具里点 **详情** → **基本信息** → 修改 AppID。
官方说明：在"详情-基本信息"里修改 AppID，会写到 `project.private.config.json`，
**不会覆盖** `project.config.json` 的 `appid` 字段。
另外官方明确：`appid` 字段"**只在新建项目时读取**"。
—— 依据：官方《项目配置文件》https://developers.weixin.qq.com/minigame/dev/devtools/projectconfig.html

**应看到**：改完后工具右上角/详情页显示的 AppID 变成你自己的；**预览**与**真机调试**按钮变为可用。

> **不要**手工去改 `dist/wechat/project.config.json` 里的 `appid` 然后期待生效——官方说它只在新建项目时读取。
> 如果你确实想改产物文件，请先记下改动，并在结果记录模板里注明"产物已被修改"。

### 2.10 第 10 步：前后台切换与重启（离线收益相关）

1. **模拟器**：用工具菜单里的 **前后台切换** 模拟"进后台 / 回前台"
   （官方《界面》里列出该菜单项："前后台切换：模拟客户端小程序进入后台运行和返回前台的操作"）。
2. **真机**：按 Home 键 / 切到别的 App 让微信进后台，再切回来。
3. **重启**：手机上把开发版小游戏完全退出（右上角 `…` → 开发调试 → 离开；或在历史列表里删掉），再重新扫码/重新打开。

**应看到**：
- 回前台时，如果离开时间 **大于 0 秒**，会弹出**离线收益面板**（见第 3 节第 10 项的具体文案与数字）。
- **第二次**连续回前台，**不会**再弹面板。
- 重启后，等级 / 金币 / 声望 / 寻访次数与关闭前一致。

### 2.11 第 11 步（可选）：上传体验版

这一步需要**正式小游戏 AppID**，且账号在微信公众平台上已注册、服务类目为"游戏"。
流程是"预览 → 上传代码 → 在管理后台设为体验版 → 提交审核 → 发布"。
—— 依据：官方《发布流程》https://developers.weixin.qq.com/minigame/introduction/gamemaker/minigame/release

**本手册不对这一步做验收**（它超出 0.1 的人工验收范围）。只在此处留一个入口说明。

---

## 3. 检查项表格

### 3.0 怎么用这张表

- **"结果"列现在全部是 `未验证`** —— 因为到写这份手册为止，没有任何一项在官方模拟器或真机上执行过。
- 你测完一项，就把结果改成 **`通过`** 或 **`失败`**。**没测的保持 `未验证`。**
- "备注"列写你实际看到的数字/文字，或失败时的现象。
- 正式填写请用 `docs/13-真机验收结果记录模板.md`。

### 3.1 主表

| # | 操作 | 预期（应看到什么） | 结果 | 备注 |
|---|---|---|---|---|
| 1 | 编译后在模拟器看首屏 | 竖屏浮空岛 + 城市（市政厅 / 4 房屋 / 风车 / 水井 / 池塘 / 道路 / 树 / 4 个居民）；顶部资源栏显示 `Lv1`、金币 `0.0`、`每分钟 +10.0`、`声望` 与 `可用 0 · 寻访 0` | 未验证 | |
| 2 | 单指在画面上拖动 | 岛屿跟着手指**旋转**；松手后有惯性；**不会**产生寻访奖励、**不会**升级 | 未验证 | |
| 3 | 双指捏合 / 张开 | 画面**平滑缩放**（设计范围 0.62× ～ 1.45×）；缩放过程中不会误触发点击 | 未验证 | |
| 4 | 单击一个**居民**小人 | 居民头顶冒 `+3 金币` 与 `+1 声望` 飘字；顶部金币 **+3.000**、`声望` 的 `可用` 与 `寻访` 各 **+1**；**没有冷却、没有次数上限**，连点 10 次就有 10 次奖励 | 未验证 | |
| 5 | 单击**市政厅** | 走的是**升级**入口（不是寻访）：金币够就扣费升级，不够就提示缺口 | 未验证 | |
| 6 | 单击道路 / 浮空岛边缘 / 树 / 云 / 天空 | **什么都不发生**（不发金币、不发声望、不改存档） | 未验证 | |
| 7 | 按住拖动一段距离后松手（不点中任何东西） | **不触发**寻访；判定为拖动 | 未验证 | 位移超过阈值（触摸 10px / 鼠标 8px）、或按住超过 600ms、或中途出现第二根手指，都判为拖动 |
| 8 | 连续快速点击升级入口（底栏按钮 或 市政厅） | **每一次点击都单独生效**，不会被"面板"阻断；金币足够时逐次扣费、逐次 +1 级 | 未验证 | **见 3.3 差异说明：0.1 没有"升级面板"** |
| 9 | 金币不足时点升级入口 | 出现 toast **`金币不足，还差 N 金币`**；底栏按钮变灰并显示 `需要 20 金币 · 还差 N 金币`；**金币一分不扣、等级不变** | 未验证 | |
| 10 | 把市政厅升到 Lv2，观察速率与下次费用 | 升级瞬间 toast 显示 `市政厅升至 Lv.2 · 每分钟 +12.0`；顶栏 `每分钟 +12.0`；底栏变成 `升级市政厅 → Lv.3` + `花费 25 金币` | 未验证 | Lv1=10/分钟、Lv2=12/分钟、C(2)=25（来源见 3.2） |
| 11 | 进后台待一会儿，再回前台 | 弹出**离线收益面板**：标题 `欢迎回来，岛主！`、`你离开了 <时长>`、大字 `+<收益>`、小字 `离线收益（已自动入账）`、`市政厅 Lv.1`、`每分钟 +10.0`、`结算后金币 <数>`，底部一个 `收下` 按钮 | 未验证 | 离开 **1 小时**（Lv1）应正好是 **+600 金币**（= 600000 毫币） |
| 12 | 再切一次后台，再回前台（第二次） | **不再弹面板**，也不再加金币（同一段离线时间**只结算一次**） | 未验证 | |
| 13 | 完全退出小游戏，重新打开 | **不再补发**离线金币；等级 / 金币 / 声望 / 寻访与关闭前一致 | 未验证 | |
| 14 | 关掉小游戏再打开（重启），看数据 | 存档**保留**：等级、金币、声望、寻访次数与关闭前一致 | 未验证 | |
| 15 | 观察帧率 | 主观是否流畅（无卡顿、无掉帧感）。Android 且微信 7.0.7 及以上、开发版/体验版，可用 **胶囊按钮 → 开发调试 → 打开性能监控面板** 看客观曲线 | 未验证 | **本项目已知的 19.9 fps 是软件渲染（SwiftShader）的数字，不能当手机结论** |
| 16 | 连续玩 10～15 分钟，摸手机背面 | 记录**主观发热感受**（凉 / 温 / 烫）与大概时间点 | 未验证 | **未找到官方依据**（官方没有给小游戏发热标准） |
| 17 | 检查所有文字是否被遮挡 / 重叠 | 顶部资源栏、底部升级栏与存档卡、市政厅头顶 `Lv.N 市政厅` 牌、飘字、toast、离线面板文字都完整可读，不互相压住，不被屏幕圆角/手势条切掉 | 未验证 | |
| 18 | **刘海屏 / 灵动岛机型**上看顶部资源栏 | 顶部资源栏**不应**被刘海、状态栏、圆角遮住 | 未验证 | **风险项**：本项目代码**没有**读取 `safeArea`，见 3.4 |
| 19 | 运行期看网络请求 | 官方模拟器 Network 面板 / 真机抓包：**不应有**任何第三方请求（本项目运行期不联网） | 未验证 | 替身宿主里实测网络调用为 0（`docs/04` W12），**真机未验证** |
| 20 | 真机上做"退出 → 重新进入"以外的多次前后台组合 | 反复进后台/回前台不会重复发钱，也不会漏发 | 未验证 | |
| 21 | 观察存档状态卡 | 正常时绿点 + `已保存` / `自动存档`；写档失败时变红 + `存档失败` / `请稍后重试`，并弹 toast `存档失败：本次操作未生效，请重试` | 未验证 | 触发写档失败在真机上不好造，做不到就填 `未验证` |

### 3.2 每个预期数值的来源（逐条核对，不自己编）

| 数值 / 规则 | 值 | 来源（文件 + 章节） |
|---|---|---|
| 初始等级 | `level = 1` | 契约 `frontend-rebuild-contract-v1/docs/02-状态与字段清单.md` §2.1 字段总表第 1 行（初始值 1）；契约 `docs/04-API契约.md` §4.1 不变量（`level=1`） |
| 初始金币 / 声望 / 寻访 | 全为 0 | 契约 `docs/02` §2.1（`coinsMilli`、`lifetimeReputation`、`spendableReputation`、`visitCount` 初始值均为 0）；契约 `docs/04` §4.2（`createVisitState` 四字段全 0） |
| 速率公式 | `R(L) = 10 × (1 + 0.20 × (L − 1))` 金币/分钟 | 契约 `docs/03-公式与规则清单.md` §3.3「等级速率」；契约 `docs/02` §2.1 派生量表「产出速率（金币/分钟）」 |
| Lv1 速率 | **10 金币/分钟**（= 10000 毫币/分钟） | 契约 `docs/03` §3.3（`Lv1 = 10`；毫币速率 `Lv1 = 10000`）；契约 `docs/04` §4.16 指纹 `r1=10000` |
| Lv2 速率 | **12 金币/分钟**（= 12000 毫币/分钟） | 契约 `docs/03` §3.3（`Lv2 = 12`；`Lv2 = 12000`）；契约 `docs/04` §4.16 指纹 `r2=12000` |
| Lv3 速率 | 14 金币/分钟 | 契约 `docs/03` §3.3（`Lv3 = 14`） |
| 费用公式 | `C(L) = ceil(20 × 1.22^(L − 1))` 金币，下界夹到 20 | 契约 `docs/03` §3.3「费用公式」；契约 `docs/02` §2.1 派生量表「升级费用（金币）」 |
| 首次升级费用 | `C(1) = 20` 金币 | 契约 `docs/03` §3.3（`C(1) = 20`） |
| **"下次费用 25"** | `C(2) = 25` 金币 —— 意思是**升到 Lv2 之后，再升到 Lv3 要花 25** | 契约 `docs/03` §3.3（`C(2) = 25`）；契约 `docs/04` §4.16 指纹 `c2=25000`（毫币） |
| 费用表 | C(1)=20, C(2)=25, C(3)=30, C(4)=37, C(5)=45 | 契约 `docs/03` §3.3 |
| 寻访奖励 | `coinsMilli +3000`、`lifetimeReputation +1`、`spendableReputation +1`、`visitCount +1`、`visitCoinsMilli +3000`、`totalGainMilli +3000` | 契约 `docs/03` §3.2「奖励（固定，无任何浮动）」 |
| **"金币 +3"** 的来源 | 3000 毫币 = 3.000 金币（1 金币 = 1000 毫币） | 契约 `docs/03` §3.2（+3000 毫币）；契约 `docs/02` §2.1 派生量表「金币数 = floor(coinsMilli / 1000)」 |
| **"声望 +1"** 的来源 | `lifetimeReputation`（累计）与 `spendableReputation`（可使用）**各 +1** | 契约 `docs/03` §3.2 |
| 寻访无冷却 / 无上限 | 明确"不设冷却、不设每日次数上限、不设递减收益、不设连击加成" | 契约 `docs/03` §3.2「明确不实现的限制」 |
| 只有"居民"才发奖 | 命中标签必须**恰好等于** `'居民'`；命中市政厅/道路/浮空岛/树/云或未命中 ⇒ 什么都不发生 | 契约 `docs/03` §3.2「触发条件」「不发奖的情形」；契约 `docs/04` §4.5 |
| 一次手势只发一次奖 | 同一次"按下→抬起"最多认领一次；连续 10 次独立手势 = 10 次奖励 | 契约 `docs/03` §3.2「手势门」 |
| 金币不足升级 | 不扣费、等级不变、**刚刚结算的时间收益原样保留** | 契约 `docs/03` §3.3 判定与效果 ③ |
| 升级前先按**旧**速率结算 | 强制步骤 | 契约 `docs/03` §3.3 判定与效果 ①；契约 `docs/04` §4.17 `UPGRADE` 段 |
| 离线收益无时长上限 | `OFFLINE_MAX_MS = Infinity`；1 小时 / 8 小时 / 24 小时 / 7 天**都不截断** | 契约 `docs/03` §3.4「无时长上限」 |
| 离线 1 小时 = 600 金币（Lv1） | `gainMilli = 600000`（600 金币），速率 10 金币/分钟 | 契约 `docs/03` §3.1 验证向量（Lv1，`delta_ms = 3600000` ⇒ `gainMilli = 600000`） |
| 离线区间**恰好结算一次** | 发放后 `offlinePending = false`；第二次回前台 `reason='not-pending'` 收益 0；刷新/重开同样不补发 | 契约 `docs/03` §3.4「一次性结算（强制）」 |
| 离线期间跳过在线结算（防重复） | `offlinePending === true` 期间，`TICK`/`TAP`/`UPGRADE` 触发的在线结算**必须被跳过** | 契约 `docs/03` §3.4「离线期间必须跳过在线自动结算（关键守卫）」 |
| 离线结算只改 6 个字段 | `coinsMilli`、`carryNumerator`、`lastSettleTsMs`、`settleCount`、`lastGainMilli`、`totalGainMilli` | 契约 `docs/03` §3.4.2 |
| 存档 schemaVersion | **2**（兼容 1） | 契约 `docs/02` §2.2 存档信封字段顺序（"schemaVersion（必须是 2）"）；契约 `docs/04` §4.16 指纹 `v=2:support=1,2` |
| 存档字段数 | **13 个**持久字段（信封共 14 个键 = schemaVersion + 13） | 契约 `docs/02` §2.1（13 个持久字段）与 §2.2（14 个键）；契约 `docs/04` §4.16 指纹 `fields=13` |
| 存档键名 | `wyszz-0.1-ds-save` | 契约 `docs/04` §4.16 指纹 `ns=wyszz-0.1-ds-save`；本项目 `docs/02-契约接入说明.md` §2；`src/core/constants.ts` |
| 首屏 HUD 文案 | `Lv` / `每分钟 +X.X` / `声望` / `可用 N · 寻访 N` / `升级市政厅 → Lv.N` / `花费 N 金币` / `已保存` / `自动存档` | 本项目 `src/ui/hud.ts` 第 229–294 行（实际绘制字符串） |
| 离线面板文案 | `欢迎回来，岛主！` / `你离开了 <时长>` / `离线收益（已自动入账）` / `市政厅 Lv.N` / `每分钟 +X.X` / `结算后金币` / `收下` | 本项目 `src/ui/hud.ts` `drawPanel()`（第 314–341 行） |
| 金币不足 toast | `金币不足，还差 N 金币` | 本项目 `src/app/app.ts` 第 229 行 |
| 存档失败 toast | `存档失败：本次操作未生效，请重试` / `存档已恢复正常` | 本项目 `src/app/app.ts` 第 238、241 行 |
| 存档损坏 toast | `存档已损坏，已开始新游戏` | 本项目 `src/core/save.ts` 第 157 行 |
| 拖动 / 点击阈值 | 触摸位移 ≤ **10px**、鼠标位移 ≤ **8px**、时长 < **600ms**、全程单指 ⇒ 才算点击 | 本项目 `src/app/input.ts` 第 25 行（`TAP_MOVE_TOUCH = 10, TAP_MOVE_MOUSE = 8, TAP_MAX_MS = 600`）；**契约未规定阈值**，这是接入层的选择（`docs/02-契约接入说明.md` §6.3） |
| 旋转 / 缩放范围 | 偏航无限、俯仰限 [16°, 62°]；缩放 0.62×～1.45× | 本项目 `docs/01-视觉设计说明.md` §1 |
| 预算上限 | draw calls ≤ 60、三角形 ≤ 40000、programs ≤ 16、世界材质 7 | 本项目 `docs/00-最终交付报告.md` §三；`docs/03-浏览器测试报告.md` T11 |
| 主包大小上限 | 小游戏主包 ≤ **4M**（代码包总大小 ≤ 30M） | 官方《代码包》https://developers.weixin.qq.com/minigame/dev/guide/base-ability/code-package.html |
| 存储配额 | 单个 key ≤ **1MB**，所有数据 ≤ **10MB** | 官方 `wx.setStorageSync` https://developers.weixin.qq.com/minigame/dev/api/storage/wx.setStorageSync.html |

### 3.3 与任务书描述**不一致**的地方（如实列出差异）

任务书（`docs/11-0.1收尾任务书-分级.md` §4）里对检查项的描述，有两条与**冻结契约**和**0.1 实际实现**不一致。
**以契约为准**，这里把差异写清楚：

| # | 任务书的说法 | 契约 / 实际实现 | 结论 |
|---|---|---|---|
| D1 | "点击**建筑和居民**会寻访" | 契约 §3.2 明确：**只有**射线命中标签**恰好等于 `'居民'`** 才发奖。点**市政厅**是**升级**入口；点道路 / 浮空岛 / 树 / 云 / 天空**什么都不发生**。 | **任务书这句与契约不符。** 检查项 5、6 已按契约改写。请**不要**把"点建筑没反应"记为失败。 |
| D2 | "升级入口**打开面板**，不阻断连续点击" | 0.1 **没有"升级面板"这个 UI**。升级有两条路径：① 点**市政厅模型**；② 点**底栏黄色按钮**。两条都**直接**扣费升级，不弹面板。整个 0.1 里**唯一的模态面板是"离线收益面板"**，它打开时会吞掉面板外的点击/拖拽/滚轮。 | **任务书这句与 0.1 实际实现不符。** 检查项 8 已改为"连续点击升级入口是否每次都单独生效"。 |

**其它需要提醒的"预期与直觉不同"的地方（这些都不是 bug）：**

- 刚进游戏时，金币是 **0.0** 而不是"3"；金币要等**点击居民**或**等时间**才会有。
- 金币显示有**一位小数**（例如 `3.0`、`12.5`）—— 这是设计，不是显示错误（`src/game/format.ts` `fmtCoinsMilli`）。
- 离线收益面板**离开 2 秒也会弹**（因为只要离线时长 > 0 就会发放），此时大字可能是 `+0.3` 这种小数。
- 小游戏真机调试**看不到 Storage 面板**（官方限制）。
- 默认视角下 4 个居民里有 2 个的"中心点"会被建筑/树冠挡住（但都有可点击区域）—— 这是遮挡的真实表现，
  依据 `docs/03-浏览器测试报告.md` §已知局限。**别把它记成"点不中居民"的失败**，请拖动旋转后再点。

### 3.4 刘海屏 / 安全区：这是一个**已知风险项**（请重点看）

- 官方 `wx.getSystemInfoSync` 会返回 `safeArea`（基础库 2.7.0 起），并明确提示："部分机型没有安全区域概念，
  也不会返回 `safeArea` 字段，**开发者需自行兼容**"。
  —— https://developers.weixin.qq.com/minigame/dev/api/base/system/wx.getSystemInfoSync.html
- **本项目 0.1 的微信适配层没有读取 `safeArea`，也没有读取 `statusBarHeight`。**
  它只读了 `windowWidth`、`windowHeight`、`pixelRatio` 和 `benchmarkLevel`。
  —— 依据：本项目 `src/wechat/main.ts` 第 38–41 行（原文：
  `const s = wx.getSystemInfoSync(); return { w: Math.max(1, s.windowWidth), h: Math.max(1, s.windowHeight), dpr: s.pixelRatio || 1 };`）。
- 另外，官方说 `wx.getSystemInfoSync` **从基础库 2.20.1 开始停止维护**，建议改用
  `wx.getSystemSetting` / `wx.getAppAuthorizeSetting` / `wx.getDeviceInfo` / `wx.getWindowInfo` / `wx.getAppBaseInfo`；
  并提示"当 `wx.getSystemInfoSync()` 接口发生错误时**可能会返回空对象**"。
  本项目仍在使用 `getSystemInfoSync`。**这是一个真机风险点，但 0.1 冻结期不改代码**，本次只做记录。

**所以第 18 项（刘海屏）请务必用一台带刘海的 iPhone 认真测，并把实际遮挡情况截图记录下来。**
这条属于"很可能失败"的项，不是走过场。

---

## 4. 结果记录模板

正式填写请用另一份文件：**`docs/13-真机验收结果记录模板.md`**。

它包含：机型、系统版本、微信版本、基础库版本、开发者工具版本、测试日期、测试人、AppID 类型、
截图文件名、每一项的结果、问题描述。

模板里已经写明这条硬规则，请照做：

> **没有测过的项必须填 `未验证`，不能留白，也不能填 `通过`。**

下面是一个最小的填写示例（**只是示例，不是真实结果**）：

```
机型：<你的手机型号>          系统版本：<例如 iOS 18.2>
微信版本：<例如 8.0.xx>       基础库版本：<vConsole 的 WeChat 页里看>
开发者工具版本：<工具"关于"里看>  测试日期：2026-__-__
AppID 类型：小游戏测试号 / 正式 AppID / touristappid（游客工程值）

第 1 项 首屏        → 通过   截图：shot-01-firstscreen.png   备注：顶部显示 Lv1 / 0.0 / 每分钟 +10.0
第 2 项 单指拖动    → 通过   截图：shot-02-rotate.png
第 3 项 双指缩放    → 失败   截图：shot-03-pinch.png        备注：缩放到最大后画面卡住约 1 秒
第 18 项 刘海屏     → 未验证                                备注：手上没有带刘海的机型
```

---

## 5. 常见失败的排查提示

> 这一节只写**有依据**的。依据来自：本项目文件、微信官方文档、或本项目已实际运行过的自动化测试结果。
> 没有依据的会明确写"**未确认**"。

**1）导入后提示 AppID 有问题 / 预览按钮是灰的**
- 依据：官方《界面》明确"新建项目需要 AppID；如没有 AppID，可以选择申请使用测试号"；
  官方《申请测试号》明确可申请**小游戏测试号**，且"点击工具栏上的预览按钮即可在真机上预览体验"。
- 处理：到 **详情 → 基本信息** 把 AppID 改成你的测试号或正式 AppID（官方说这会写到 `project.private.config.json`，
  不会覆盖 `project.config.json`）。
- 产物自带的 `touristappid` 的**完整限制清单**：**未确认**（官方文档没有列，只在更新日志里出现过
  "优化 touristappid 禁用提示"）。

**2）工具不把项目当成小游戏 / 报编译类型不合法**
- 依据：官方《项目配置文件》（小游戏版）列出的 `compileType` 有效值只有 **`minigame`（普通小游戏项目）**
  和 **`gamePlugin`（小游戏插件项目）**。
- 事实：本项目产物 `dist/wechat/project.config.json` 里写的是 **`"compileType": "game"`**。
- 结论：**这是一处差异，我无法确认当前工具是否仍接受 `game`。**
  如果工具报错，最小改动是把 `compileType` 改成 `minigame`（**这属于改产物配置，需要你或开发者决定；本次 L2 任务没有改**）。
  详见 `docs/L2-报告.md` 的"待决问题"。

**3）提示基础库下载失败**
- 依据：官方《项目配置文件》说 `libVersion` 可写具体版本号或 `latest` / `trial` / `widelyUsed`；
  且"手动在开发者工具-详情-本地设置中改变基础库的版本，会覆盖掉 `project.private.config.json` 的 `libVersion` 字段"。
- 处理：在 **详情 → 本地设置 → 调试基础库** 里换一个版本，或选 `latest`。
- 注意：`latest` / `trial` / `widelyUsed` 这三个值在 `project.private.config.json` 里**无效**（官方原文）。

**4）模拟器黑屏 / 白屏**
- **未找到官方依据**能直接对应本项目（官方《转换工具使用指南》的"故障排除"只列了 Emscripten 转换工具场景的
  `Error: File not found` 和"转换后游戏黑屏 → 检查 CDN 地址 / 尝试 WebGL 1.0"，本项目不是那个场景）。
- 有依据的两条：
  - 本项目产物是**自包含单文件**：`dist/wechat/` 里只有 `game.js`、`game.json`、`project.config.json`、`MANIFEST.json`，
    没有外部资源要加载，所以"资源路径错"的可能性低（依据：目录实际内容）。
  - 先看 Console 有没有报错（本项目在替身宿主里加载是**无报错**的，依据 `docs/04` 的 W01c / W12c；
    真机/官方模拟器未验证）。
- 处理：把 Console 全文抄进记录模板；换一个基础库版本再试。

**5）预览二维码出不来 / 手机扫码进不去**
- 依据：官方《功能概述》说明真机调试是"工具先将本地代码打包上传，就绪后手机扫码"；
  官方《代码包》说明开发版代码包**只能通过扫码获得**。
- 有依据的检查点：确认手机和电脑网络正常、确认已用微信扫码登录工具（**游客模式不行**）。
- 具体失败原因：**未确认**（官方没有给出针对性的排查条目）。

**6）真机调试窗口里找不到 Storage 面板**
- 依据：官方《功能概述》（小游戏远程调试）明确"**目前尚不支持 Storage 面板**"。
- 结论：**这是预期行为，不是 bug。** 想确认存档，请看游戏内的存档状态卡（`已保存` / `存档失败`）或重启后数据是否保留。

**7）iOS 真机调试的某些能力用不了**
- 依据：官方《真机调试能力升级 Beta》v1.0 明确"**注意：iOS 暂不支持**"。
- 结论：**预期行为。**

**8）帧率低 / 手机发热**
- 依据（官方）：微信 Android 7.0.7 及以上，为小游戏**开发版和体验版**提供**性能监控面板**，
  入口是"胶囊按钮 → 开发调试 → 打开性能监控面板"；官方还介绍了 Heap Snapshot 与 PerfDog。
  —— https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-action-memory-dev-profile.html
- 依据（本项目）：已知的 **19.9 fps 是 SwiftShader 软件渲染**下的数字，**不代表手机**
  （`docs/00` §三、`docs/03` §已知局限）。
- 结论：**不要在报告里把 19.9 fps 当作手机帧率。** 真机帧率必须用性能监控面板或 PerfDog 实测。
- 发热的"合格标准"：**未找到官方依据。**

**9）顶部文字被刘海 / 状态栏遮住**
- 依据：见 3.4。官方说 `safeArea` 需要开发者自行兼容；本项目代码**没有读 `safeArea`**。
- 结论：**很可能在刘海屏上被遮挡**，请截图记录，不要试图在 0.1 里修（冻结期）。

**10）回前台没有弹离线收益面板**
- 依据（契约 §3.4.2）：只有 `offlinePending === true` **且** `delta_ms > 0` 才会发放并弹面板；
  `reason` 为 `not-pending` / `no-elapsed` 时是**静默**的（本项目 `src/game/session.ts` `reportForeground()`）。
- 有依据的检查点：确认这次回前台之前**确实**进过后台（进后台会把 `offlinePending` 置为 `true`）；
  确认离开时间确实大于 0 秒。
- 如果**离开很久却没有面板**：把"进后台/回前台的时间点"记下来，这是真机上的可疑点，填进记录模板。

**11）离线收益被重复领取**
- 依据：契约 §3.4 的"一次性结算（强制）"与"离线期间必须跳过在线自动结算（关键守卫）"；
  夹具 `F17` 专门验证这条守卫；替身宿主 W07d 验证"重复 onShow 不重复发放"。
- 真机上如果**真的**重复发放：这是 **P0 级问题**，请立刻记录并停止测试，把时间点、截图、vConsole 日志一起交上来。

**12）重启后存档没了**
- 依据（官方）：`wx.setStorageSync` —— "除非用户主动删除或因存储空间原因被系统清理，否则数据都一直可用"；
  单个 key ≤ 1MB、所有数据 ≤ 10MB。本项目存档只有几百字节，**远不会超配额**。
- 依据（本项目）：存档键 `wyszz-0.1-ds-save`，schemaVersion=2，13 个状态字段（契约 `docs/04` §4.16、`docs/02` §2.2）。
- 有依据的检查点：
  - 是不是在**开发版**里"离开"了（右上角 `…` → 开发调试 → 离开 会清掉运行环境）；
  - 是不是在工具里执行过"**清除缓存**"（工具菜单里有"清除缓存：清除文件缓存、数据缓存"——官方《界面》）；
  - 有没有在 Console 看到 `存档已损坏，已开始新游戏`（说明读到的存档被判为损坏，回退新档）。
- 真机上的存储配额表现：**未验证**（`docs/04` §测试宿主的已知局限）。

**13）看到 `存档失败` / 红色状态点**
- 依据（本项目）：写档失败时内存回滚、底栏变红显示 `存档失败` / `请稍后重试`，
  toast `存档失败：本次操作未生效，请重试`；恢复后显示 `存档已恢复正常`
  （`src/app/app.ts` 第 238、241 行；`docs/02-契约接入说明.md` §4）。
- 这是**设计好的失败提示**，不是崩溃。真机上很难主动造出来；造不出来就填 `未验证`。

**14）Console 出现 `wx.getSystemInfoSync` 相关警告**
- 依据：官方该接口页明确"从基础库 2.20.1 开始，本接口停止维护"，建议改用
  `wx.getWindowInfo` 等；并提示出错时"可能会返回空对象"。
- 本项目仍在使用它（`src/wechat/main.ts` 第 38、41 行）。**这是已知风险，0.1 冻结期不改。**
- 请把警告原文与基础库版本抄进记录模板。

---

## 6. 本手册的"未确认 / 未验证"清单（汇总）

**未确认（查不到官方依据，或官方说法不统一）：**

| # | 未确认的事 | 去哪里确认 |
|---|---|---|
| U1 | 微信开发者工具当前**确切版本号** | 官方下载页 https://developers.weixin.qq.com/miniprogram/dev/devtools/download |
| U2 | `touristappid`（游客工程值）的**完整限制清单** | 官方文档站搜索"游客模式"；或直接在工具里试（预览/真机调试是否可用） |
| U3 | **测试号能否"上传"代码** | 官方文档**未找到明确条文**；社区运营专员回复称不能上传（社区内容）。请以你账号在工具里的实际上传按钮状态为准 |
| U4 | 小游戏真机调试的**统一**客户端/基础库最低要求 | 官方两页数字不一致（`minigame/dev/devtools/remote-debug` vs `miniprogram/dev/devtools/remote-debug-2`）；以工具实际提示为准 |
| U5 | 本项目所需**最低基础库版本** | 工具里逐版本试，看 Console 是否报 API 缺失 |
| U6 | 小游戏的**手机硬件最低要求** | **未找到官方依据**；官方文档站搜索"小游戏 兼容性评估" |
| U7 | `compileType: "game"` 是否仍被当前工具接受（官方只列 `minigame` / `gamePlugin`） | 导入时看工具是否报错；报错则改 `minigame` |
| U8 | 手机发热的"合格标准" | **未找到官方依据** |
| U9 | 小游戏**运行内存**的官方上限 | **未找到官方依据**（本次未查阅相关页面） |

**未验证（到目前为止从没在官方模拟器/真机上跑过）：**

- 第 3 节表格里的**全部 21 项**。
- 微信官方模拟器能否正常编译并运行本项目产物。
- 真机上 WebGL / WebGL2 上下文能否正常创建。
- 真机触摸事件（多点、取消、坐标）的实际行为。
- 真机存储配额与 `wx.setStorageSync` 的真实表现。
- 真机帧率、发热、内存。
- 刘海屏/安全区遮挡的真实情况（且代码未读 `safeArea`，风险偏高）。
- 上传 / 体验版 / 审核 / 发布全流程。

---

## 7. 官方文档引用清单（查阅日期：2026-10-12）

| 用在哪 | 官方文档 | URL |
|---|---|---|
| 工具下载 | 微信开发者工具（小游戏） | https://developers.weixin.qq.com/minigame/dev/devtools/download.html |
| 工具下载 | 微信开发者工具下载页 | https://developers.weixin.qq.com/miniprogram/dev/devtools/download |
| 登录 / 游客模式 / 新建项目条件 / 前后台切换菜单 | 界面 | https://developers.weixin.qq.com/miniprogram/dev/devtools/page.html |
| `project.config.json` 全部字段、`compileType` 有效值、`libVersion`、`appid` 只在新建时读取 | 项目配置文件（小游戏） | https://developers.weixin.qq.com/minigame/dev/devtools/projectconfig.html |
| `game.json` 配置项（`deviceOrientation`、`showStatusBar`） | 小游戏配置 | https://developers.weixin.qq.com/minigame/dev/reference/configuration/app.html |
| 测试号申请与"可真机预览" | 申请测试号 | https://developers.weixin.qq.com/miniprogram/dev/devtools/sandbox.html |
| 小游戏真机远程调试流程、Storage 面板不支持、老版本要求 | 功能概述（远程调试） | https://developers.weixin.qq.com/minigame/dev/devtools/remote-debug.html |
| 真机调试能力升级 Beta、v1.0 iOS 暂不支持 | 真机调试能力升级 | https://developers.weixin.qq.com/minigame/dev/devtools/remote-debug-v2.html |
| 真机调试 2.0 的机型/基础库要求 | 真机调试2.0 | https://developers.weixin.qq.com/miniprogram/dev/devtools/remote-debug-2.html |
| 导入 / 预览 / 真机调试四步、vConsole 入口 | 转换工具使用指南 | https://developers.weixin.qq.com/minigame/dev/guide/game-engine/common-adaptation/Design/TransformTool.html |
| 代码包版本类型、主包 ≤4M、总包 ≤30M | 代码包 | https://developers.weixin.qq.com/minigame/dev/guide/base-ability/code-package.html |
| 基础库版本号规则、版本比较 | 兼容 | https://developers.weixin.qq.com/minigame/dev/guide/runtime/client-lib/compatibility.html |
| 客户端携带上一稳定版基础库 | 基础库 | https://developers.weixin.qq.com/miniprogram/dev/framework/client-lib |
| `safeArea`、`benchmarkLevel`、`getSystemInfoSync` 停止维护 | `wx.getSystemInfoSync` | https://developers.weixin.qq.com/minigame/dev/api/base/system/wx.getSystemInfoSync.html |
| 存储配额（单 key 1MB / 总 10MB） | `wx.setStorageSync` | https://developers.weixin.qq.com/minigame/dev/api/storage/wx.setStorageSync.html |
| 存储读取 | `wx.getStorageSync` | https://developers.weixin.qq.com/minigame/dev/api/storage/wx.getStorageSync.html |
| 性能监控面板 / Heap Snapshot / PerfDog | 开发阶段内存调优 | https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-action-memory-dev-profile.html |
| 注册小游戏账号 / 上传 / 体验版 / 提审 | 发布流程 | https://developers.weixin.qq.com/minigame/introduction/gamemaker/minigame/release |
| 真机查基础库版本的入口 | 调试指南（AI） | https://developers.weixin.qq.com/miniprogram/dev/ai/debugging.html |
| `touristappid` 确实是被工具识别的特殊值 | 开发者工具更新日志 | https://developers.weixin.qq.com/miniprogram/dev/devtools/uplog |
| 测试号不能上传（**社区回复，非正式文档**） | 微信开放社区 | https://developers.weixin.qq.com/community/minihome/doc/000020de490d78321c8c9ba3e56800 |
| 云测不支持测试 AppID（**插件限制，不能推广到上传**） | 云测常见问题 | https://developers.weixin.qq.com/miniprogram/dev/devtools/minitest/cloud_problem.html |

---

## 8. 本项目的内部依据（本手册核对过的文件）

| 文件 | 用到的章节 |
|---|---|
| `frontend-rebuild-contract-v1/docs/02-状态与字段清单.md` | §2.1 字段总表与派生量、§2.2 存档信封、§2.5 校验顺序 |
| `frontend-rebuild-contract-v1/docs/03-公式与规则清单.md` | §3.1 时间收益（含验证向量）、§3.2 寻访规则、§3.3 升级规则、§3.4 离线规则、§3.5 边界行为总表 |
| `frontend-rebuild-contract-v1/docs/04-API契约.md` | §4.1–§4.2 初始状态、§4.5 寻访、§4.6 升级、§4.16 指纹、§4.17 调用顺序 |
| `frontend-rebuild-hm/docs/00-最终交付报告.md` | §一 结论表、§三 关键数据、§四 需要如实说明的事项 |
| `frontend-rebuild-hm/docs/01-视觉设计说明.md` | §1 构图与相机（旋转/缩放范围）、§7 UI 层级 |
| `frontend-rebuild-hm/docs/02-契约接入说明.md` | §4 事务与失败反馈、§5 UI 边界、§6 契约缺口（手势阈值） |
| `frontend-rebuild-hm/docs/03-浏览器测试报告.md` | §已知局限（SwiftShader 帧率、居民遮挡） |
| `frontend-rebuild-hm/docs/04-微信小游戏模拟验证报告.md` | §重要边界、§构建产物、§适配层、§结果 W01–W12 |
| `frontend-rebuild-hm/docs/11-0.1收尾任务书-分级.md` | §4 本任务书（用来对照差异 D1 / D2） |
| `frontend-rebuild-hm/dist/wechat/*` | `game.json`、`project.config.json`、`MANIFEST.json`、四个文件的 SHA256 |
| `frontend-rebuild-hm/src/ui/hud.ts` | 实际绘制的中文文案（顶栏 / 底栏 / 离线面板） |
| `frontend-rebuild-hm/src/app/app.ts` | toast 文案、点击 → 会话事件的转发 |
| `frontend-rebuild-hm/src/app/input.ts` | 手势阈值常量 |
| `frontend-rebuild-hm/src/game/session.ts` | 离线面板触发条件（`granted` 才弹） |
| `frontend-rebuild-hm/src/wechat/main.ts` | 微信适配层实际读取的系统字段（**未读 `safeArea`**） |
| `frontend-rebuild-hm/src/core/constants.ts` | 冻结常量（速率、费用、寻访奖励、存档键、离线无上限） |
| `frontend-rebuild-hm/evidence/wechat-sim-results.json` | 37 项替身宿主结果的原始记录 |
| `frontend-rebuild-hm/evidence/perf.json` | SwiftShader 下的 19.9 fps 与预算数字 |

---

**最后再强调一次**：这份手册里**没有任何一条真机结论**。
所有"预期"都来自冻结契约、本项目交付文档或微信官方文档；
所有"结果"都还是 `未验证`，等你测完再填。
