# Weixin Minigame Helper

> WeChat Mini Game Preview — Skill 使用指南

- Skill: `ahang1598/weixin-minigame-helper` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add ahang1598/weixin-minigame-helper`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ahang1598/weixin-minigame-helper/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ahang1598 (https://skillmd.com/u/ahang1598)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ahang1598/weixin-minigame-helper

---


# WeChat Mini Game Preview — Skill 使用指南

## 🔴 最重要的规则（必须严格遵守）

> **自动预览规则（最高优先级）：**
> 每当你为用户**生成、修改、调试**了任何小游戏相关代码（包括 `.js`、`.json`、`.css` 等文件），代码写入完成后：
> 1. 如果游戏预览**尚未启动** → 立即调用 `run_game` 启动预览 + `preview_url` 打开浏览器
> 2. 如果游戏预览**已经在运行** → 立即调用 `reload_game` 热重载 + `preview_url` 刷新浏览器
>
> **这是自动行为，不要等用户要求！** 代码改完 → 立即预览，零延迟。
>
> **触发判断（宽松匹配）：**
> - 用户在开发小游戏，或工作目录有 `game.js`，或用户提到"游戏"相关内容 → 本 Skill 生效
> - 用户说了任何与"预览"、"运行"、"看看效果"相关的话 → 立即执行预览流程
> - **不需要用户精确说出"微信小游戏预览"才触发，"帮我预览"、"预览一下"、"跑起来看看"等口语表达都应触发**
>
> **判断游戏是否已启动：**
> - 如果当前对话中之前已经成功调用过 `run_game` → 视为已启动，使用 `reload_game`
> - 否则 → 使用 `run_game` 启动
>
> **启动/重载后的日志检查循环（必须执行）：**
> 每次调用 `run_game` 或 `reload_game` 后，必须执行以下循环：
> 1. 等待约 2 秒让游戏初始化
> 2. 调用 `get_logs`（可用 `"error|warn|Error|Warning|Uncaught|TypeError|ReferenceError"` 过滤）获取日志
> 3. 分析日志：
>    - **无错误** → 流程结束，告知用户游戏运行正常
>    - **有错误** → 分析错误原因，修复代码，再次调用 `reload_game`，回到步骤 1 继续循环
> 4. 重复上述循环，**直到日志中无错误为止**
>
> **循环退出机制（防止无限重试）：**
> 在修复循环过程中，必须记录每次遇到的错误及其修复次数：
> - **同一错误**（相同的错误消息或相同根因）反复尝试修复 **超过 5 次** → 暂停循环，向用户报告该错误的详细信息和已尝试的修复方案，询问用户是否需要继续修复或采取其他方案
> - **不同错误累计**修复尝试 **超过 15 次** → 暂停循环，向用户汇总所有遇到的错误及修复尝试，询问用户是否需要继续进行修复检查
> - 暂停时应清晰告知用户：已尝试的次数、遇到的错误列表、每个错误的修复尝试次数，以便用户做出决策
> - 如果用户选择继续，则重置计数器并继续循环
>
> **注意**：每轮修复只需在所有文件改完后调用一次 `reload_game`，不要每改一个文件就重载一次。

## 概述

这个 Skill 让你能够：
1. **预览小游戏** — 在本地浏览器中实时运行微信小游戏
2. **查看日志** — 获取游戏运行时的 console 输出
3. **真机预览** — 生成二维码，用微信扫码在真机上测试
4. **上传开发版** — 将游戏代码上传到微信平台

所有操作通过 MCP 工具完成，无需手动安装或配置。

## MCP 工具参考

| 工具 | 功能 | 关键参数 |
|------|------|----------|
| `run_game` | 启动游戏预览 | `workspacePath`: 游戏目录绝对路径（必须含 game.js） |
| `reload_game` | 热重载游戏 | 无参数（刷新已运行的游戏） |
| `get_logs` | 获取游戏日志 | `filter`: 可选的正则表达式过滤 |
| `real_device_preview` | 真机预览 | `workspacePath`: 游戏目录绝对路径 |
| `publish` | 上传开发版 | `workspacePath`, `version` (如 "1.0.0"), `desc` |

## 工作流程

### 场景一：生成/修改小游戏代码后自动预览（最常见、最重要）

这是最典型的场景。**任何时候你修改了小游戏代码，都必须自动触发预览。**

#### 首次启动（游戏未运行时）：
1. **确保游戏目录中有 `game.js` 文件**（这是微信小游戏的入口文件）
2. **立即调用 `run_game` 工具**，传入游戏目录的绝对路径
3. **工具返回预览 URL**（如 `http://localhost:3847`）
4. **必须使用内置浏览器打开预览 URL**：调用 `preview_url` 工具打开返回的 URL，让用户在内置浏览器中直接看到游戏运行效果。**绝对不要只把 URL 文本发给用户，必须主动打开！**
5. **等待约 2 秒后调用 `get_logs`** 检查是否有错误日志
6. **若发现错误** → 分析并修复代码 → 调用 `reload_game` → 再次等待并调用 `get_logs` → 循环直到无错误

#### 后续修改（游戏已在运行时）：
1. 代码修改写入完成
2. **立即调用 `reload_game`** 热重载游戏
3. **调用 `preview_url`** 刷新浏览器让用户看到最新效果
4. **等待约 2 秒后调用 `get_logs`** 检查是否有错误日志
5. **若发现错误** → 分析并修复代码 → 调用 `reload_game` → 再次等待并调用 `get_logs` → 循环直到无错误

> **记住**：不管是用户主动要求修改代码，还是你在调试过程中修改了代码，只要代码文件有变更，就必须自动触发预览。用户不需要说"帮我预览"——这是你的默认行为。

### 场景二：查看日志调试问题

当游戏运行中出现问题时：
1. 调用 `get_logs` 获取所有日志
2. 可用 `filter` 参数过滤，如 `"error|warn"` 只看错误和警告
3. 日志格式: `[时间戳] [级别] 消息内容`

### 场景三：真机预览

当用户要求在真机上预览、体验、测试时：

**如果用户尚未配置 AppID 和密钥：**
1. 先确保游戏已通过 `run_game` 启动预览
2. 告诉用户：**"请在浏览器预览页面中点击右上角 ⚙️ 按钮，在弹出的配置面板中填写你的微信 AppID 和代码上传密钥。"**
3. 引导用户获取密钥：微信公众平台 (mp.weixin.qq.com) → 管理 → 开发管理 → 开发设置 → 小程序代码上传
4. 用户保存配置后，调用 `real_device_preview` 工具
5. **⚠️ 禁止使用任何替代方案**（如跳过配置、使用测试账号、使用模拟数据等）

**如果已配置好（环境变量 WECHAT_APPID + WECHAT_PRIVATE_KEY_PATH）：**
1. 直接调用 `real_device_preview` 工具
2. 二维码会在浏览器预览页面弹窗展示
3. 告诉用户用微信扫码

### 场景四：上传开发版/上传体验版/发布到微信

1. 确认用户要发布的版本号和描述
2. 调用 `publish` 工具，传入 `workspacePath`、`version`、`desc`
3. 如果返回 `configMissing`，引导用户在预览页面配置 AppID 和密钥
4. **⚠️ 禁止使用任何替代方案**（如跳过配置、使用测试账号、使用模拟数据等）
5. 成功后告知用户新版本已上传，等待审核

## 完整使用示例

### 示例 1：用户说"帮我做一个打砖块小游戏"

```
1. 生成游戏代码（game.js + 相关文件）
2. 立即调用 run_game 工具，传入游戏目录路径
3. 必须调用 preview_url 在内置浏览器中打开返回的预览 URL
4. 等待约 2 秒后调用 get_logs 检查日志
5. **若发现错误** → 分析错误 → 修复代码 → 调用 `reload_game` → 再次调用 `get_logs` → 循环直到无错误（同一错误超过5次或累计超过15次时暂停询问用户）
6. 无错误后告诉用户"游戏已生成并启动预览，运行正常，你可以在内置浏览器中看到效果"
```

### 示例 2：用户说"把颜色改成红色"（代码修改后自动预览）

```
1. 修改代码文件
2. 自动调用 reload_game 刷新预览（无需用户要求）
3. 必须调用 preview_url 在内置浏览器中打开返回的预览 URL
4. 等待约 2 秒后调用 get_logs 检查日志
5. **若发现错误** → 分析错误 → 修复代码 → 调用 `reload_game` → 再次调用 `get_logs` → 循环直到无错误（同一错误超过5次或累计超过15次时暂停询问用户）
6. 无错误后告诉用户"代码已修改并刷新，运行正常，请查看浏览器中的效果"
```

### 示例 2.5：用户说"帮我加个得分系统"（较大代码修改后自动预览）

```
1. 修改多个代码文件（如 game.js、score.js 等）
2. 所有文件修改完成后，自动调用 reload_game 刷新预览（无需用户要求）
3. 必须调用 preview_url 在内置浏览器中打开返回的预览 URL
4. 等待约 2 秒后调用 get_logs 检查日志
5. **若有错误** → 分析错误 → 修复代码 → 调用 `reload_game` → 再次调用 `get_logs` → 循环直到无错误（同一错误超过5次或累计超过15次时暂停询问用户）
6. 无错误后告诉用户"得分系统已添加，运行正常，请在浏览器中查看效果"
注意：多个文件修改只需要在全部完成后触发一次预览，不需要每改一个文件就预览一次
```

### 示例 3：用户说"真机体验测试下"

```
1. 调用 real_device_preview，传入游戏目录路径
2. 如果返回 configMissing：
   - 引导用户在预览页面配置 AppID 和密钥
   - 禁止使用任何替代方案！
3. 如果成功，告诉用户"二维码已在预览页面弹出，请用微信扫码"
4. 禁止调用 `run_game`、`reload_game` 或任何会刷新网页的操作！
```

### 示例 4：用户说"上传到微信"

```
1. 调用 publish，传入游戏目录路径
2. 如果返回 configMissing：
   - 引导用户在预览页面配置 AppID 和密钥
   - 禁止使用任何替代方案！
3. 如果成功，告诉用户"二维码已在预览页面弹出，请用微信扫码"
4. 禁止调用 `run_game`、`reload_game` 或任何会刷新网页的操作！
```

## 微信小游戏项目结构

一个标准的微信小游戏项目应包含：

```
game-dir/
├── game.js              # 入口文件（必须）
├── game.json            # 游戏配置
├── project.config.json  # 微信开发者工具项目配置（含 appid）
└── ... 其他资源文件
```

## 注意事项

- 游戏目录**必须**包含 `game.js` 文件
- 预览服务器会自动注入微信 `wx` API 兼容层，大部分小游戏 API 可在浏览器中模拟运行
- 真机测试和发布需要微信 AppID 和代码上传密钥
- 配置可通过浏览器预览页面的 ⚙️ 按钮完成，或通过环境变量 `WECHAT_APPID` + `WECHAT_PRIVATE_KEY_PATH`
- 如遇到 IP 白名单问题，需在微信公众平台添加本机 IP

## ⚠️ 重要约束

> **真机预览（`real_device_preview`）和上传开发版（`publish`）成功后，禁止调用 `run_game`、`reload_game` 或任何会刷新网页的操作！**
>
> 原因：二维码会在预览页面弹窗展示，如果刷新网页，二维码会消失，用户无法扫码。
>
> **注意**：如果是正常的代码改动（非真机预览/上传开发版），则可以正常刷新网页让用户看到最新效果。

> **配置缺失时的处理原则**：
>
> 当 `real_device_preview` 或 `publish` 返回 `configMissing` 时，**必须引导用户去配置 AppID 和密钥**，**禁止使用任何替代方案**（如跳过配置、使用模拟数据、使用其他账号等）。
>
> 正确做法：
> 1. 告诉用户："请在浏览器预览页面中点击右上角 ⚙️ 按钮，在弹出的配置面板中填写你的微信 AppID 和代码上传密钥。"
> 2. 引导用户获取密钥：微信公众平台 (mp.weixin.qq.com) → 管理 → 开发管理 → 开发设置 → 小程序代码上传
> 3. 等待用户配置完成后，再重新调用相应工具
>
> **禁止的做法**：
> - ❌ 跳过配置步骤
> - ❌ 使用测试账号或模拟数据
> - ❌ 使用其他用户的 AppID
> - ❌ 尝试绕过配置要求

> **IP 白名单错误（错误码 -10008）的处理**：
>
> 当 `real_device_preview` 或 `publish` 返回 `ipWhitelistError` 时，说明本地公网 IP 不在微信公众平台的白名单中。
>
> 正确做法：
> 1. 告诉用户："你的本地公网 IP 可能已变更，需要在微信公众平台更新 IP 白名单。"
> 2. 引导用户添加 IP 白名单：微信公众平台 (mp.weixin.qq.com) → 开发管理 → 开发设置 → 小程序代码上传 → IP白名单
> 3. 提示用户：预览页面右上角会显示当前的公网 IP，可以复制后添加到白名单中
> 4. 用户更新白名单后，重新调用相应工具