weixin-minigame-helper
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 1
- Forks
- 0
03 SKILL.md 正文
WeChat Mini Game Preview — Skill 使用指南
🔴 最重要的规则(必须严格遵守)
自动预览规则(最高优先级): 每当你为用户生成、修改、调试了任何小游戏相关代码(包括
.js、.json、.css等文件),代码写入完成后:
- 如果游戏预览尚未启动 → 立即调用
run_game启动预览 +preview_url打开浏览器- 如果游戏预览已经在运行 → 立即调用
reload_game热重载 +preview_url刷新浏览器这是自动行为,不要等用户要求! 代码改完 → 立即预览,零延迟。
触发判断(宽松匹配):
- 用户在开发小游戏,或工作目录有
game.js,或用户提到"游戏"相关内容 → 本 Skill 生效- 用户说了任何与"预览"、"运行"、"看看效果"相关的话 → 立即执行预览流程
- 不需要用户精确说出"微信小游戏预览"才触发,"帮我预览"、"预览一下"、"跑起来看看"等口语表达都应触发
判断游戏是否已启动:
- 如果当前对话中之前已经成功调用过
run_game→ 视为已启动,使用reload_game- 否则 → 使用
run_game启动启动/重载后的日志检查循环(必须执行): 每次调用
run_game或reload_game后,必须执行以下循环:
- 等待约 2 秒让游戏初始化
- 调用
get_logs(可用"error|warn|Error|Warning|Uncaught|TypeError|ReferenceError"过滤)获取日志- 分析日志:
- 无错误 → 流程结束,告知用户游戏运行正常
- 有错误 → 分析错误原因,修复代码,再次调用
reload_game,回到步骤 1 继续循环- 重复上述循环,直到日志中无错误为止
循环退出机制(防止无限重试): 在修复循环过程中,必须记录每次遇到的错误及其修复次数:
- 同一错误(相同的错误消息或相同根因)反复尝试修复 超过 5 次 → 暂停循环,向用户报告该错误的详细信息和已尝试的修复方案,询问用户是否需要继续修复或采取其他方案
- 不同错误累计修复尝试 超过 15 次 → 暂停循环,向用户汇总所有遇到的错误及修复尝试,询问用户是否需要继续进行修复检查
- 暂停时应清晰告知用户:已尝试的次数、遇到的错误列表、每个错误的修复尝试次数,以便用户做出决策
- 如果用户选择继续,则重置计数器并继续循环
注意:每轮修复只需在所有文件改完后调用一次
reload_game,不要每改一个文件就重载一次。
概述
这个 Skill 让你能够:
- 预览小游戏 — 在本地浏览器中实时运行微信小游戏
- 查看日志 — 获取游戏运行时的 console 输出
- 真机预览 — 生成二维码,用微信扫码在真机上测试
- 上传开发版 — 将游戏代码上传到微信平台
所有操作通过 MCP 工具完成,无需手动安装或配置。
MCP 工具参考
| 工具 | 功能 | 关键参数 |
|---|---|---|
run_game |
启动游戏预览 | workspacePath: 游戏目录绝对路径(必须含 game.js) |
reload_game |
热重载游戏 | 无参数(刷新已运行的游戏) |
get_logs |
获取游戏日志 | filter: 可选的正则表达式过滤 |
real_device_preview |
真机预览 | workspacePath: 游戏目录绝对路径 |
publish |
上传开发版 | workspacePath, version (如 "1.0.0"), desc |
工作流程
场景一:生成/修改小游戏代码后自动预览(最常见、最重要)
这是最典型的场景。任何时候你修改了小游戏代码,都必须自动触发预览。
首次启动(游戏未运行时):
- 确保游戏目录中有
game.js文件(这是微信小游戏的入口文件) - 立即调用
run_game工具,传入游戏目录的绝对路径 - 工具返回预览 URL(如
http://localhost:3847) - 必须使用内置浏览器打开预览 URL:调用
preview_url工具打开返回的 URL,让用户在内置浏览器中直接看到游戏运行效果。绝对不要只把 URL 文本发给用户,必须主动打开! - 等待约 2 秒后调用
get_logs检查是否有错误日志 - 若发现错误 → 分析并修复代码 → 调用
reload_game→ 再次等待并调用get_logs→ 循环直到无错误
后续修改(游戏已在运行时):
- 代码修改写入完成
- 立即调用
reload_game热重载游戏 - 调用
preview_url刷新浏览器让用户看到最新效果 - 等待约 2 秒后调用
get_logs检查是否有错误日志 - 若发现错误 → 分析并修复代码 → 调用
reload_game→ 再次等待并调用get_logs→ 循环直到无错误
记住:不管是用户主动要求修改代码,还是你在调试过程中修改了代码,只要代码文件有变更,就必须自动触发预览。用户不需要说"帮我预览"——这是你的默认行为。
场景二:查看日志调试问题
当游戏运行中出现问题时:
- 调用
get_logs获取所有日志 - 可用
filter参数过滤,如"error|warn"只看错误和警告 - 日志格式:
[时间戳] [级别] 消息内容
场景三:真机预览
当用户要求在真机上预览、体验、测试时:
如果用户尚未配置 AppID 和密钥:
- 先确保游戏已通过
run_game启动预览 - 告诉用户:"请在浏览器预览页面中点击右上角 ⚙️ 按钮,在弹出的配置面板中填写你的微信 AppID 和代码上传密钥。"
- 引导用户获取密钥:微信公众平台 (mp.weixin.qq.com) → 管理 → 开发管理 → 开发设置 → 小程序代码上传
- 用户保存配置后,调用
real_device_preview工具 - ⚠️ 禁止使用任何替代方案(如跳过配置、使用测试账号、使用模拟数据等)
如果已配置好(环境变量 WECHAT_APPID + WECHAT_PRIVATE_KEY_PATH):
- 直接调用
real_device_preview工具 - 二维码会在浏览器预览页面弹窗展示
- 告诉用户用微信扫码
场景四:上传开发版/上传体验版/发布到微信
- 确认用户要发布的版本号和描述
- 调用
publish工具,传入workspacePath、version、desc - 如果返回
configMissing,引导用户在预览页面配置 AppID 和密钥 - ⚠️ 禁止使用任何替代方案(如跳过配置、使用测试账号、使用模拟数据等)
- 成功后告知用户新版本已上传,等待审核
完整使用示例
示例 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文件 - 预览服务器会自动注入微信
wxAPI 兼容层,大部分小游戏 API 可在浏览器中模拟运行 - 真机测试和发布需要微信 AppID 和代码上传密钥
- 配置可通过浏览器预览页面的 ⚙️ 按钮完成,或通过环境变量
WECHAT_APPID+WECHAT_PRIVATE_KEY_PATH - 如遇到 IP 白名单问题,需在微信公众平台添加本机 IP
⚠️ 重要约束
真机预览(
real_device_preview)和上传开发版(publish)成功后,禁止调用run_game、reload_game或任何会刷新网页的操作!原因:二维码会在预览页面弹窗展示,如果刷新网页,二维码会消失,用户无法扫码。
注意:如果是正常的代码改动(非真机预览/上传开发版),则可以正常刷新网页让用户看到最新效果。
配置缺失时的处理原则:
当
real_device_preview或publish返回configMissing时,必须引导用户去配置 AppID 和密钥,禁止使用任何替代方案(如跳过配置、使用模拟数据、使用其他账号等)。正确做法:
- 告诉用户:"请在浏览器预览页面中点击右上角 ⚙️ 按钮,在弹出的配置面板中填写你的微信 AppID 和代码上传密钥。"
- 引导用户获取密钥:微信公众平台 (mp.weixin.qq.com) → 管理 → 开发管理 → 开发设置 → 小程序代码上传
- 等待用户配置完成后,再重新调用相应工具
禁止的做法:
- ❌ 跳过配置步骤
- ❌ 使用测试账号或模拟数据
- ❌ 使用其他用户的 AppID
- ❌ 尝试绕过配置要求
IP 白名单错误(错误码 -10008)的处理:
当
real_device_preview或publish返回ipWhitelistError时,说明本地公网 IP 不在微信公众平台的白名单中。正确做法:
- 告诉用户:"你的本地公网 IP 可能已变更,需要在微信公众平台更新 IP 白名单。"
- 引导用户添加 IP 白名单:微信公众平台 (mp.weixin.qq.com) → 开发管理 → 开发设置 → 小程序代码上传 → IP白名单
- 提示用户:预览页面右上角会显示当前的公网 IP,可以复制后添加到白名单中
- 用户更新白名单后,重新调用相应工具
04 同仓库更多 Skills
vercel-sandbox
Run agent-browser + Chrome inside Vercel Sandbox microVMs for browser automation from any Vercel-deployed app. Use when the user needs browser automation in a Vercel app (Next.js, SvelteKit, Nuxt, Remix, Astro, etc.), wants to run headless Chrome without binary size limits, needs persistent browser sessions across commands, or wants ephemeral isolated browser environments. Triggers include "Vercel Sandbox browser", "microVM Chrome", "agent-browser in sandbox", "browser automation on Vercel", or any task requiring Chrome in a Vercel Sandbox.
slack
Interact with Slack workspaces using browser automation. Use when the user needs to check unread channels, navigate Slack, send messages, extract data, find information, search conversations, or automate any Slack task. Triggers include "check my Slack", "what channels have unreads", "send a message to", "search Slack for", "extract from Slack", "find who said", or any task requiring programmatic Slack interaction.
electron
Automate Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify, etc.) using agent-browser via Chrome DevTools Protocol. Use when the user needs to interact with an Electron app, automate a desktop app, connect to a running app, control a native app, or test an Electron application. Triggers include "automate Slack app", "control VS Code", "interact with Discord app", "test this Electron app", "connect to desktop app", or any task requiring automation of a native Electron application.
dogfood
Systematically explore and test a web application to find bugs, UX issues, and other problems. Use when asked to "dogfood", "QA", "exploratory test", "find issues", "bug hunt", "test this app/site/platform", or review the quality of a web application. Produces a structured report with full reproduction evidence -- step-by-step screenshots, repro videos, and detailed repro steps for every issue -- so findings can be handed directly to the responsible teams.
agent-browser
Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.
shadcn
Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", "switch to --preset", and for building a design system or applying a DESIGN.md or brand spec to shadcn/ui.