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 工具参考

工作流程

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

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

首次启动（游戏未运行时）：

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. 用户更新白名单后，重新调用相应工具