# 交接说明：微信小游戏《叫我大岛主》真机验收（交给另一个智能体继续）

## 一、要做什么

在 NAS 的常驻 Windows 虚拟机上，用**微信开发者工具**对《叫我大岛主》小游戏做验收；
当前卡点是**真机上小游戏卡在启动页进不去**，需要定位原因。

## 二、必须先读的流程文档（里面是实测过的步骤和坑，别自己重新发明）

1. 《小游戏在VM里出码-流程与坑-v2》—— 8 步标准流程 + 16 条坑清单
   - 文件：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm02/小游戏在VM里出码-流程与坑-v2.md`
   - 在线：https://files.hynixing.cn/dl/vm--v2-5d56f
2. 《验收流程-开发者工具》（v1，更偏验收步骤与实测坐标）
   - 文件：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm02/验收流程-开发者工具.md`
   - 在线：https://files.hynixing.cn/dl/item-21bc4
3. 《调试报错采集-20261019》—— 开发者工具侧的报错原文（可直接引用）
   - 文件：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm02/调试报错采集-20261019.md`
   - 在线：https://files.hynixing.cn/dl/20261019-c0fa4

## 三、当前状态（已完成的部分）

| 项 | 状态 |
|---|---|
| 被验收包 | G-09 产出的 `0.2.3-pre 微信正式包`，原 sha256 `601a6bbc…be1b` 已核验一致 |
| 部署位置（VM 内） | `C:\wyszz\wechat023`，projectname `wyszz-island-0.2.3-pre` |
| appid | 已从包内的 `touristappid` 替换为真实 `wx1c0ae0869ea1424f` |
| 开发者工具 | 已登录（`cli islogin` → `{"login":true}`），工程已打开，窗口标题 `wyszz-island-0.2.3-pre` |
| 真机预览码 | `cli preview` 成功，包体 TOTAL `770.2 KB` / 788,679 字节，二维码 47,260 字节已生成 |
| 手机侧 | **能打开了**（不再报错），但卡在启动页 |

## 四、当前的问题（核心）

### 4.1 真机侧（手机微信里）

- 现象：小游戏打开后**卡在启动页**，进不去游戏。
- 截图证据：手机截图 1260×2720，OCR 原文：
  ```
  叫我大岛主
  小游戏
  该小游戏已接入健康系统，家长可通过成长守护功能进行监督。
  抵制不良游戏，拒绝盗版游戏。注意自我保护，谨防受骗上当。
  适度游戏益脑，沉迷游戏伤身。合理安排时间，享受健康生活。
  开发团队承诺积极履行《网络游戏防沉迷自律公约》
  ```
- 视觉描述：微信小游戏启动页正常显示（标题 + “小游戏”标识 + 底部健康系统说明），
  但**上方本该渲染游戏画面的区域一片空白**，没有进度条、没有开始按钮、没有报错文字。
- **未拿到真机 console**：手机侧的控制台报错还没取到，需要走「真机调试」或让机主截图。

### 4.2 开发者工具侧（Linux/VM 上）

- 小游戏**模拟器起不来**，日志报错：
  ```
  [2026-10-19 00:21:01.222][ERROR][2.02.2608080][...app.asar\js\0bef819d396f49a48c3e44596e3b3e51.js] routeTo appLaunch timeout
  [2026-10-19 00:20:55.653][ERROR][2.02.2608080][PROJECT][C:\Program Files] [Devtools] devtools is not loaded properly
  [2026-10-19 00:20:55.657][ERROR][2.02.2608080][PROJECT][C:\Program Files] [Devtools] custom devtools frontend param is missing
  ```
  并弹窗：「无法启动 / 当前设备或微信版本不支持所需的图形能力，请升级微信后重试。」
- 根因（已实测确认）：开发者工具的 GPU 进程命令行带 **`--use-gl=disabled`**（工具自己加的），
  外部传入 `--use-angle=swiftshader --enable-unsafe-swiftshader` 会被它压掉；
  改工具配置里的 `enableGPU` 也无效。
- **反对照（重要）**：同一台 VM 里用无头 Edge 实测 `WEBGL_OK: WebGL 1.0 (OpenGL ES 2.0 Chromium)`，
  说明这台 VM **能**出软件 WebGL，问题出在开发者工具主动关闭 GL，不是 VM 没能力。

## 五、已验可行的替代路径

- 工程的 Web 版可直接渲染：`dist/web/index.html`（three.js 前端，与微信版同源）。
  用本机 `/usr/bin/chromium` 无头 + `--enable-unsafe-swiftshader` 已成功出图：
  - 竖屏 390×844 与桌面 1920×1080 两种尺寸截图均正常
  - OCR 读出真实游戏内容：「声望 / Lv 1 / 每分钟+10.0 / 可用0·寻访0 / 升级市政厅→ Lv.2 / 花费20金币 / 已保存」
  - 产物：`/vol1/ai/agents/hermes/images/游戏Web版渲染-竖屏手机-20261019-001747.png` 等

## 六、操作通道（现成的，别另找）

```
VM 调用器：/vol1/ai/windows-mcp/.venv/bin/python /vol1/ai/_scripts/vmctl.py
           用法：vmctl.py <工具名> '@脚本文件.ps1' --timeout N
           （工具名不能省；可用工具：PowerShell / Snapshot / Click / Type / App / WaitFor …）
读屏 OCR ：/vol1/ai/typesafe-cu/typesafe-computer-use/.venv/bin/python /vol1/ai/_scripts/ocr-image.py <图> [置信度]
          输出形如 [y=1392 x=488 p=0.98] 叫我大岛主
回传文件 ：NAS 先起 python3 /vol1/ai/_scripts/vm-upload-server.py 8094
          VM 里 Invoke-WebRequest -Uri http://192.168.1.38:8094/ -Method POST -Body $bytes -Headers @{"X-Filename"="x.png"}
开发者工具 CLI：C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat
          （islogin / open --project / preview --qr-format image --qr-output / upload / auto）
```

## 七、明确的约束与未做项

- 不要修改 `game.js` / `game.json`；`project.config.json` 目前只动过 appid 一个字段（出码必需）。
- 本次**没有**做：重新上传、发布、改任何游戏代码、装/降级开发者工具。
- 先前误改过的 `enableGPU` 已还原为 `true`。
- 真机 console 未获取；所有真机运行结论一律以实测为准，不得凭推测填写。
