# 交接说明 · 《我要当市长》微信开发者工具安装与最小验证

> 交接时间：2026-10-09 01:4x (Asia/Shanghai)
> 交接方：上一会话（上下文已臃肿）；接任方：新对话
> 本文档自包含：读完即可接手，无需再向用户索要背景。

---

## 0. 任务与边界（不可越界）

**任务**：通过**已有的 Windows-MCP 通道**操作 Windows 虚拟机，安装已下载并核验的官方微信开发者工具，验证启动 + 最小原生小游戏；后续可推进真机测试与 Three.js 迁移。

**用户长期禁则（违反即事故）**
1. 不修改 MIMO / app / little-town / DSH 3D 原型；不影响 https://mayor3d.hynixing.cn/。
2. 不做网络 / 域名 / NAS 权限 / VM 硬件改动 —— **除非用户当轮明确授权**（例如本轮授权过"临时二维码域名"，用完已删）。
3. 报告 / 日志 / 截图 / 工具输出中**不得出现任何凭据**（尤其 auth_key、AppSecret）。
4. 不绕过 UAC、不改密码 / 组 / 安全策略 / 计划任务定义。
5. **真机没实际跑通，不许写"已验证"**。
6. 任何产出实体文件，交付前必须走 deliver-link 发下载链接。
7. 没有合法 AppID 时只能用官方"免 AppID / 游客模式"，并如实记录其限制。
8. 所有写入限制在本项目目录 `/vol1/ai/projects/wyszz-new/wechat-spike-ds/` 与 VM 内的 spike 项目 `C:\projects\wyszz-wx-spike\minigame-env-check\`。

---

## 1. 环境与访问（缺这段就得从零摸索）

### 1.1 虚拟机
- QEMU 进程 `qemu-system-x86_64 ... -name winvm-mcp`（上次 pid 997182），磁盘 `/mnt/ssd/winvm-mcp/win.qcow2`，Windows Server 2022 Standard Evaluation 10.0.20348，4096 MB / 3 vCPU。
- 网络：`-netdev user`（**SLIRP 隔离 NAT，无 tap / 无 bridge**）
  - `hostfwd=tcp:127.0.0.1:18000-:8000`（**仅宿主环回**）
  - `hostfwd=tcp:127.0.0.1:15985-:5985`（WinRM，同样仅环回）
- 客户机监听 `0.0.0.0:8000`，防火墙规则 `windows-mcp 8000 (QEMU NAT host only)`：Inbound/Allow，**remote=10.0.2.0/255.255.255.0**，TCP 8000；三档 profile 均 Enabled=True。
- 结论：**8000 不存在公网/局域网暴露**；三层隔离 = SLIRP NAT + hostfwd 仅环回 + 防火墙限源。

### 1.2 MCP 通道
- 端点：`http://127.0.0.1:18000/mcp/`（windows-mcp 4.0.11，protocol 2025-11-25，streamable-http，stateless）。
- **鉴权密钥：`/vol1/ai/windows-mcp/.mcp-key`（43 字节，mode 600）。绝不打印、不写入任何报告/截图。** 校验用 sha256 前缀 `62fa1c3d43536430`。
- 帮手：`PY=/vol1/ai/windows-mcp/.venv/bin/python`，
  `${PY} tools/wx.py list | ps '<cmd>' | psf <file.ps1> | shot <name> | snap | fslist | fsread | fswrite | raw <Tool> '<json>'`
  截图落在 `<proj>/evidence/screenshots/<name>_1.png`。
- 可用工具：`Click {"loc":[x,y],"clicks":1}`、`Shortcut {"shortcut":"..."}`、`Snapshot {}`、`Screenshot`、`PowerShell`、`FileSystem`。
- 冒烟测试：`curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:18000/mcp/` → **401 = 活着**（无密钥被拒是正常的）；**000 = 通道死了**（见 §4.1 恢复）。

### 1.3 两条完整性级别不同的通道（**务必区分，上一版报告这里出过错**）
| 通道 | 完整性 | 触发方式 | 用途 |
|---|---|---|---|
| **A · MCP HTTP** | **Medium（中，非管理员）** | `tools/wx.py ...` | 绝大多数取证、点击、截图 |
| **B · 计划任务轮询** | **High（高，管理员）** | 写 `/mnt/ssd/winvm-mcp/serve/run.ps1`，等轮询执行 | 需要管理员权限的写操作 |

- B 的证据：`wmcp-poll1`（`RunLevel=HighestAvailable`，每分钟）→ `C:\Users\mc\wmcp\poll.ps1`；早期 `elevprobe.txt` 实测 `High Mandatory Level (S-1-16-12288)`、`IsInRoleAdmin=True`、含 `BUILTIN\Administrators`。
- **用户要求**：高完整性写操作**先报备**再动；默认只用 A 做只读取证。

### 1.4 文件通道（局域网）
- 下载服务：`http://192.168.1.38:8088/<name>` → `/mnt/ssd/winvm-mcp/serve/`
- 上传接收：`POST http://192.168.1.38:8089/up/<name>` → `/mnt/ssd/winvm-mcp/inbox/`
- 轮询机制：`poll.ps1` 每 20s 拉 `serve/run.ps1`，MD5 去重（`C:\Users\mc\wmcp\last.txt`）→ 写 `cur.ps1` 执行 → 输出 `run.out`；心跳 `inbox/hb.log`。
- 这两个端口是**既有**服务（非本任务创建），局域网可达 —— 用户尚未决定是否收紧。

### 1.5 脚本硬规则（违反就白干）
- 经通道发送的脚本**必须是纯 ASCII**，发前自检：`LC_ALL=C grep -nP '[^\x00-\x7F]' file`。
- PowerShell **没有 `chr()`**：用 `[char]34`；构造中文用码点：
  `function CJK($cp){ return (-join ($cp | ForEach-Object { [char]$_ })) }`（微=0x5FAE 信=0x4FE1 开=0x5F00 发=0x53D1 者=0x8005 工=0x5DE5 具=0x5177 登=0x767B 录=0x5F55）
- 复杂单行 PowerShell **几乎必坏** → 一律写成 `.ps1` 文件用 `psf` 执行。
- 用 TypeScript 模板字符串生成脚本时：**别用反引号、别用 `${}`**，用数组 `join("\n")` 拼。

---

## 2. 当前状态（做到哪了，别重复做）

| 项 | 状态 | 证据 |
|---|---|---|
| 安装 | ✅ 完成 | `C:\Program Files (x86)\Tencent\微信开发者工具\`，EXE 202,930,736，PE 2.02.0（Stable **2.02.2608080**），签名 Valid（Tencent） |
| 窗口 | ✅ 正常 | 窗口 `minigame-env-check` 1024×728 |
| 小游戏显示 | ✅ | 模拟器渲染「环境验证」，窗口 390×844 dpr3，canvas 390×844，`boot 00:32:03` |
| 点按 | ✅ 完整序列 0→1→2→3→4→5（每次单点恰好 +1） | 逐次截图 + 游戏自身日志 `taps=1..5` |
| 控制台 | ⚠️ 按用户指定措辞 | 「游戏代码未捕获运行时错误；开发者工具自身存在两条环境/授权错误」（❌2 ⚠️1：jsbridge not ready / 游客模式 access_token expired） |
| 登录 | ✅ 已登录 | 工具「详情→AppId→修改」能列出账号 AppID 列表（须登录）；日志 `Login ×9`。**未跑 `cli islogin`**（IDE 服务端口未开） |
| **真机** | ❌ **未验证** | 唯一卡点：缺合法**小游戏** AppID |
| Three.js 迁移 | ⬜ 未开始 | —— |

**AppID 现状（关键）**
- 项目当前显示 `touristappid`（游客模式）；`project.config.json` 里写的是 `wx6ac3f5090a6b99c5`（工具向导的模板值，工具会覆盖 —— **不是配置错误**）。
- 账号下可用 AppID：`wxf3db135de6e01d28`「牧语算草」= **小程序**类型 → **不能**用于小游戏真机。
- 用户新注册的小游戏账号：控制台 `gh_18b6e396ee0d`，设置页有「**游戏设置**」tab（= 确为小游戏账号 ✅），但**基本信息未完善** → 尚未出现在工具可用列表。
- 社区偏方「公共体验 AppID `wx6ac3f5090a6b99c5`」= **非官方 hack，用户已同意不采用**。

---

## 3. 下一步该做什么

**若用户给出小游戏 AppID**
1. 备份并改写 `C:\projects\wyszz-wx-spike\minigame-env-check\project.config.json` 的 `appid`（只改这一个 spike 项目）。
2. 重启工具取干净态：kill → `win/launch_devtools_only.ps1` → 等 ~45s。
3. 点「预览」或「真机调试」→ 二维码。
4. **二维码交付用"实时页"方案**（用户可能在外地，消息往返曾报告约 7 分钟延迟，静态二维码必过期）：
   - 守护循环截取二维码 → `convert -crop 176x176+774+143 +repage -filter point -resize 300% -bordercolor white -border 50`
   - 过期判定：裁剪 `160x160+782+151` 取灰度均值，**live≈0.55 / expired≈0.83**，>0.78 点刷新按钮 **(856,226)**
   - 成果库用 `deliver-link --link`（软链，同一 URL 内容持续更新），页面每 5 秒带 `?t=` 取新图；**用完 `publish.py rm <id>` 删除**。
5. 手机扫码 → 手机上点 5 次验证 0→1→2→3→4→5，记录机型 + 微信版本 → 更新报告，把"真机未验证"改成实测结论。

**若用户暂不推进真机**：保持现状即可；手机侧可用已发布的「网页体验版」感受交互（**明确标注非真机、不计入验收**）。

---

## 4. 已知坑与恢复手册（避免重复犯错）

### 4.1 MCP 通道挂了怎么恢复（本任务实际发生过）
**症状**：`curl 127.0.0.1:18000/mcp/` 返回 000（而 8088 正常）。
**根因**：虚拟机被非正常重置后，`C:\Users\mc\.windows-mcp\config.toml` 会被**清零成 153 字节的 0x00**（`authkey.txt` 同样被清零）→ 服务启动即报 `Error: Invalid statement (at line 1, column 1)` 秒退。
**恢复步骤（全部经 B 通道 = 轮询）**
1. 写 `/mnt/ssd/winvm-mcp/serve/run.ps1`（ASCII），内容：用 `[System.Text.UTF8Encoding($false)`（**无 BOM**）重写 config.toml，值为
   `[server]` / `transport = "streamable-http"` / `host = "0.0.0.0"` / `port = 8000` / `stateless_http = true` / `auth_key = "<从 /vol1/ai/windows-mcp/.mcp-key 读，本地 shell 替换，绝不出现在输出里>"`。
2. 等轮询（≤20s）→ 检查 `inbox/run.out`；再 `schtasks /Run /TN windows-mcp-server`。
3. 验证：`curl 127.0.0.1:18000/mcp/` = **401**；`tools/wx.py list` 返回 13 个工具。
4. **用完把 `serve/run.ps1` 还原**为原始版本（md5 `24aa940e32be15ed30a5a189dcc8de29`）。
> 注意：B 通道的 `run.ps1` 是**一次性的**，别留在那里；也别把密钥写进它以外的任何宿主文件。

### 4.2 GUI 操作坑
- **模态对话框会吞掉后续所有点击**。误判案例：点「取消」时先关掉的是下拉框，对话框其实还在 → 后续 5 次点按全部无效、截图计数不变。判断"是否关闭"**必须看 UI 树里 取消/确定 按钮是否还在**，Snapshot 输出为空不能当"已关闭"。
- 「修改」精确坐标：AppId 行 = **(952,289)**；项目名称行 = (977,252)。我错了两次（966,281 / 965,291 都点空）。
- 详情面板开合 = 点 **(871,13)**；错误认知：`(985,43)` 不是编译按钮而是通知铃；`Ctrl+B` 在编辑器焦点下无效。
- **最可靠的"重编译/取干净初态" = 重启工具**：kill（`MainWindowTitle -like "*minigame*"`）→ `win/launch_devtools_only.ps1` → 等 ~45s。重启后**第一次点击会被窗口焦点吞掉**，点按测试记得先补一次"激活点击"。
- 控制台错误列表可能为空但徽标仍显示 ❌2 ⚠️1；**最大化调试器**（约 (513,617)）能看到游戏自身 `taps=N` 日志 —— 这是最硬的点按互证。

### 4.3 脚本/工具坑（我实际踩过）
1. `pkill -f qr_loop` 会**杀掉自己**（自己的命令行含同名字符串）→ 用括号技巧 `'qr_loo[p]'`，且命令行里别再出现字面文件名。曾因此两次"脚本瞬间自尽、无输出"。
2. `nohup ... &` 起的后台任务有时让 bash 工具返回空输出 → 关键结果写日志/文件再读。
3. 覆盖刚写过的文件可能被拒（`file changed since it was read`）→ 先 read 或换文件名。
4. PowerShell 里 `-replace "\"",""` 这类嵌套引号必炸 → 用 `[char]34` 或 `.Split("=").Trim().Trim($q)`。
5. 工具写文件失败/坐标点空时**不要连续重试同一坐标**，先用 Snapshot（UI 树）拿到精确坐标与元素名。

### 4.4 事实类（容易搞错）
- **微信"小程序" ≠ "微信小游戏"**：小游戏入口 `game.js`+`game.json`+`wx.createCanvas()`；小程序是 `app.json`+`app.js`+`pages/*.wxml/.wxss`。**两者 AppID 不通用**。
- 本任务做的是**小游戏**（不是小程序），项目文件已确认。
- 小游戏账号注册时**必须在服务类目勾「游戏」**（一级类目注册后不可改，选错只能重注册）；快速判断：后台设置页有「**游戏设置**」tab 即为小游戏账号。
- 小游戏真机前提：**合法小游戏 AppID** + 扫码的微信号是该小游戏的管理员/开发者。
- `touristappid` 与 `project.config.json` 的 appid 不一致 = **游客模式覆盖**的正常现象。

---

## 5. 已交付资源（别重复生成，链接可用）

| 内容 | 链接 |
|---|---|
| **验收报告 v2（当前有效）** | https://files.hynixing.cn/raw/v2-2e575 （下载 https://files.hynixing.cn/dl/v2-2e575 ） |
| 验收报告 v1（已被 v2 取代） | https://files.hynixing.cn/raw/item-164e8 |
| 手机网页体验版（非真机，仅体验交互） | https://files.hynixing.cn/raw/item-70457 |
| 临时二维码页 | **已按用户要求删除**（两条 404），守护循环已停 |

---

## 6. 文件与工具位置速查

**项目目录 `/vol1/ai/projects/wyszz-new/wechat-spike-ds/`**（本任务所有写入都在此）
- `tools/wx.py` — 通道帮手（list/ps/psf/shot/snap/fslist/fsread/fswrite/raw）
- `win/*.ps1` — 历次脚本：`launch_devtools_only.ps1`（重启工具）、`verify_installed.ps1`（安装核验）、`check_project.ps1`、`login_probe*.ps1`、`mcp_audit*.ps1` / `wmcp_audit3.ps1` / `wmcp_audit4.ps1` / `task_audit.ps1` / `fw8000.ps1`
- `evidence/screenshots/`、`evidence/logs/`
- `accept/验收报告v2-微信开发者工具最小验证.html`（成品）、`accept/acceptance-v2.html`（模板，占位符 `__SEQ__`/`__TAPSLOG__`/`__CONSOLE__`，用 python 把 PNG 转 base64 替换）
- `h5/环境验证-手机体验版.html`
- `handoff/` — 本文档

**成果库/交付**
- 发布：`/vol1/ai/_scripts/deliver-link <绝对路径> "<标题>" "<说明>" "<分类>" [--link] [--json]` → 输出 `DOWNLOAD/PREVIEW`；按 sha256 去重；大文件加 `--link`（软链，源文件不能删）
- 删除：`python3 /vol1/ai/deliverables/publish.py rm <id>`
- 本地自检：`deliverd` 监听 `127.0.0.1:8086`，`curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8086/raw/<id>`
- 对外：`https://files.hynixing.cn/raw/<id>`（浏览器内联）/ `.../dl/<id>`（强制下载）。**NAS 无法自验公网链接**（在 Cloudflare Access 后面）。

**VM 内关键路径**
- `C:\Users\mc\.windows-mcp\config.toml`（live 配置，含 auth_key → **勿打印**）
- `C:\Users\mc\wmcp\`（`poll.ps1`、`tick1.ps1`、`watchdog.ps1`、`boot.ps1`、`fw.ps1` + 日志/输出）
- `C:\projects\wyszz-wx-spike\minigame-env-check\`（spike 小游戏项目）
- `C:\Program Files (x86)\Tencent\微信开发者工具\`
- 计划任务：`windows-mcp-server`（Medium）、`wmcp-poll1`/`wmcp-watchdog`（每分钟，HighestAvailable）、`wmcp-boot`/`wmcp-fw`

---

## 7. 安全与合规现状（继承，不要放宽）
- 密钥仅存 `/vol1/ai/windows-mcp/.mcp-key`（600）。宿主 `/mnt/ssd/winvm-mcp/inbox` 已收紧为 **dir 700 / files 600**（其中 7 个历史文件含 auth_key）。本轮产生的含密钥临时文件（客户机 `config.fixed/nobom/rebuilt.toml`）**已删除**。
- 我的所有脚本经哈希比对**零密钥字面量**。
- `wmcp-*` 计划任务与防火墙规则文件时间均为 **2026-10-07 16:2x–16:5x**（早于本任务窗口，**非本任务创建**）。
- 回滚命令：`schtasks /End /TN windows-mcp-server` + `Stop-Process -Name pythonw -Force`；`schtasks /Change /TN windows-mcp-server /DISABLE`；`netsh advfirewall firewall delete rule name="windows-mcp 8000 (QEMU NAT host only)"`。
- 既有局域网服务 `0.0.0.0:8088/8089`（netsvc）**用户尚未决定是否收紧**。

---

## 8. 给接任方的操作建议（省上下文）
1. **先做冒烟测试**（§1.2），再读 §2 现状表 —— 已通过的项别再重测，除非用户要求。
2. 需要事实时优先读 `evidence/` 与本文档，**不要重新摸索**已经定性的东西（AppID 类型、完整性级别、暴露面、点按序列）。
3. 每轮只做一组相关动作；GUI 操作后立刻截图自证。
4. 产出文件 → deliver-link → 再回复用户。
5. 真机结论未拿到前，报告里始终保留"**真机未验证**"。

---
*本文档由上一会话生成，含其全部关键结论与踩坑记录；如有冲突，以 VM/工具的当场实测为准。*
