# 微信小游戏「开发者工具里验收」完整流程（Windows VM 版）

> 适用：在 NAS 的常驻 Windows Server 2022 虚拟机里，用微信开发者工具打开小游戏工程、编译、截图取证。
> 实测时间：2026-10-18。工程：`wyszz-island 0.2.1`（appid `wx1c0ae0869ea1424f`）

---

## 0. 一句话结论（先看这个）

```
✅ 打通：把工程送进 VM → 打开 → 登录 → 编译 → 截图取证 → 打包出真机码
⚠️ 卡点：这台 VM 只有「Microsoft 基本显示适配器 / SeaBIOS VBE」，没有任何 3D/OpenGL 能力
         → 小游戏运行时报「无法启动：当前设备或微信版本不支持所需的图形能力」
         → 模拟器画面空白，日志里的表现是 routeTo appLaunch timeout
📌 因此：**纯逻辑/UI 结构层面可以在 VM 里验收；渲染相关的验收必须在真机**
```

---

## 1. 环境事实（写死，别猜）

| 项 | 值 |
|---|---|
| VM 服务 | `systemctl {start,stop,restart} winvm-mcp`（单元 `/etc/systemd/system/winvm-mcp.service`） |
| VM 规格 | Windows Server 2022 中文桌面 / 6GB 内存 / 3 vCPU / 1920x1080（**DPI 缩放 150%**） |
| 显卡 | Microsoft 基本显示适配器（SeaBIOS VBE）—— **无 3D** |
| 被控通道 | Windows-MCP 端点 `http://127.0.0.1:18000/mcp/`（**带尾斜杠**；Bearer 密钥 `/vol1/ai/windows-mcp/.mcp-key`） |
| 调用器 | `/vol1/ai/windows-mcp/.venv/bin/python /vol1/ai/_scripts/vmctl.py {tools\|schema <片段>\|<ToolName> '<json>'\|@脚本文件} [--timeout N]` |
| VM 内 CLI | `C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat` |
| 工程目录（VM 内） | `C:\wyszz\wechat` |
| 源码（NAS） | `/vol1/ai/projects/wyszz-new/frontend-rebuild-hm02/dist/wechat` |
| appid | `wx1c0ae0869ea1424f`（**不能用默认 touristappid**，工具不认） |

---

## 2. 标准流程（7 步）

### ① 打包工程 → 送进 VM

```bash
# NAS 侧：把工程目录打成 zip
cd /vol1/ai/projects/wyszz-new/frontend-rebuild-hm02/dist/wechat
zip -qr /tmp/wyszz-serve/wechat-0.2.1.zip .
# 起个临时 HTTP 服务（端口任选空闲的）
cd /tmp/wyszz-serve && nohup python3 -m http.server 8093 >/dev/null 2>&1 &
```

VM 侧（经 vmctl.py 执行 PowerShell）：

```powershell
Invoke-WebRequest http://192.168.1.38:8093/wechat-0.2.1.zip -OutFile C:\wyszz\wechat.zip
Expand-Archive C:\wyszz\wechat.zip -DestinationPath C:\wyszz\wechat -Force
```

> ⚠️ **坑 C1**：`project.config.json` 若带 **BOM**，工具会报「配置无效」→ 必须写成 **UTF-8 无 BOM**
> ⚠️ **坑 C2**：`appid` 必须是真实 appid，`touristappid` 会导致上传/预览失败

### ② 登录（要主人配合扫码）

```powershell
& cmd /c '"C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat" islogin'
# 未登录时出码（约 2 分钟有效）：
Start-Process cmd.exe -ArgumentList '/c', '"<cli>" login --qr-format image --qr-size 480 --qr-output C:\wyszz\qr.png' -WindowStyle Hidden
Start-Sleep 26
# 把 C:\wyszz\qr.png POST 回 NAS（VM 连不进 NAS，用反向上传服务）
Invoke-WebRequest http://192.168.1.38:8094/ -Method POST -InFile C:\wyszz\qr.png -ContentType image/png -Headers @{ "X-Filename" = "qr.png" }
```

> NAS 侧先起：`python3 /vol1/ai/_scripts/vm-upload-server.py 8094`（文件落 `/tmp/vm-upload/`）
> 把图拷到 `/vol1/ai/agents/hermes/images/` 才能发微信（**媒体目录白名单**）

### ③ 打开工程

```powershell
& cmd /c '"<cli>" open --project C:\wyszz\wechat'
Start-Sleep 40
# 把窗口调到前台（否则截图截到别的窗口！）
(New-Object -ComObject WScript.Shell).AppActivate("wyszz-island-0.2.1")
```

> ⚠️ **坑 C3（最坑的一个）**：不调前台就截图，会连截 10 次都是**别的窗口**（我曾一直截到「服务器管理器」）

### ④ 编译

点工具栏的「编译」按钮（坐标见下），或直接 `Ctrl+B`。

### ⑤ 截图 + 读屏取证

```bash
cd /vol1/ai/windows-mcp
./.venv/bin/python /vol1/ai/_scripts/vmctl.py Screenshot      # 落 evidence/screenshot_1.png
cp evidence/screenshot_1.png /vol1/ai/agents/hermes/images/   # 发微信用
```

**读屏（关键能力）**——用 rapidocr 把屏幕文字读出来，连坐标一起给你：

```bash
/vol1/ai/typesafe-cu/typesafe-computer-use/.venv/bin/python \
   /vol1/ai/_scripts/ocr-image.py <图片> [最小置信度]
# 输出：[y= 425 x=1491 p=1.00] 无法启动
```

### ⑥ 打包出真机预览码

```powershell
& cmd /c '"<cli>" preview --project C:\wyszz\wechat --qr-format image --qr-output C:\wyszz\qr-preview.png'
# 需要足够内存（4GB 会 OOM ✗，6GB 实测通过 ✓），打包体积约 740KB
```

### ⑦ 拿证据、写结论

截图 → 拷到 `/vol1/ai/agents/hermes/images/` → 交付时必须给**绝对路径**。

---

## 3. 实测坐标表（1920x1080，从 OCR 读出来的真值）

```
普通编译（工具栏）   (1716,  56)
小游戏模式           ( 955,  13)
预览                 (1080,  13)
真机调试 / 上传      (1169,  12)
弹窗「确定」         (1505, 539)
```

> ⚠️ **坑 C4**：开发者工具是 Electron，**不暴露控件树** → 读不到按钮元素，只能按坐标点。
> 用 OCR 拿到文字坐标，是最可靠的定位方式。

---

## 4. 坑清单（血泪，按踩到时序）

| # | 坑 | 现象 | 解法 |
|---|---|---|---|
| C1 | project.config.json 带 BOM | 工具报「配置无效」 | 写成 UTF-8 **无 BOM**（`[IO.File]::WriteAllText` + `UTF8Encoding($false)`） |
| C2 | appid 是 touristappid | 上传/预览失败 | 换真实 appid |
| C3 | 截图不调前台 | 反复截到别的窗口 | 截前 `AppActivate("窗口标题")` |
| C4 | Electron 无控件树 | `Snapshot`/`App` 读不到按钮 | 按坐标点 + OCR 定位 |
| C5 | 4GB 内存 | `cli preview` 报 `System.OutOfMemoryException` | 给 VM 加到 6GB（页面文件曾 100% 用满） |
| C6 | 机型配置 | 改 localstorage JSON 会被工具写回 | 机型要在 UI 里选（配置文件不是实时存储） |
| C7 | 图形能力 | 模拟器空白 + `routeTo appLaunch timeout` | 见第 5 节 |
| C8 | 命令行长度 | PowerShell 工具超 ~18K 字符报 `WinError 206` | 长脚本先落盘再 `-File` 跑 |
| C9 | DPI 虚拟化 | 探针报 1280x720，截图却是 1875x1020 | 脚本声明 DPI 感知（`SetProcessDpiAwarenessContext(-4)`） |
| C10 | VM→NAS 单向 | NAS 连不进 VM（user-mode NAT） | 反向传文件用 `vm-upload-server.py` |

---

## 5. 图形能力这条卡点（当前未解决）

```
现象：模拟器弹「无法启动：当前设备或微信版本不支持所需的图形能力，请升级微信后重试。」
日志：routeTo appLaunch timeout
根因：VM 显卡 = Microsoft 基本显示适配器 / SeaBIOS VBE，无 3D/OpenGL
已试：GDI 基本显示、软件渲染（--disable-gpu）—— 结果见交付时附的最新结论
可选解法（按代价排序）：
  ① 真机验收（手机扫码）—— 最省事，但需要渲染在手机上没问题
  ② 给 VM 装 Mesa llvmpipe（软件 OpenGL 4.5）
     - 下载 pal1000/mesa-dist-win 的 release-msvc 包（约 67MB，需 7-Zip 解，py7zr 不支持 BCJ2）
     - 把 x64/opengl32.dll 等放进开发者工具安装目录
     - ⚠️ **需要管理员权限**：VM 用户 mc 虽在 Administrators 组，但 MCP 进程未提权，写不进 Program Files
  ③ 换真机调试（cli 的 auto 之外的「真机调试」模式）
```

---

## 6. 边界（不许动）

- 不许停/重启：`minecraft-fc6`、`cloudflared*`、`hermes-gateway`、`agents-anywhere-connector`、`codex-web`、`dsh`、`fc6-wiki`、`ledger-web`、`deliverd`
- 不许改 `/vol1/ai/账本`、`/vol1/ai/日记本`、`/vol1/ai/agents/hermes/memories/`
- VM 端口不许暴露公网

---

## 7. 相关资产

| 用途 | 路径 |
|---|---|
| VM 调用器 | `/vol1/ai/_scripts/vmctl.py` |
| 读屏工具（OCR） | `/vol1/ai/_scripts/ocr-image.py` |
| 反向上传服务 | `/vol1/ai/_scripts/vm-upload-server.py` |
| 截图出处 | `/vol1/ai/windows-mcp/evidence/screenshot_1.png` |
| 发微信用图目录 | `/vol1/ai/agents/hermes/images/` |
| 电脑操作 agent（备选） | `devops/typesafe-cu-windows-vm` 技能 |
| VM 搭建/保活 | `devops/windows-mcp-nas-vm` 技能 |
