---
name: wx-game-publish
display_name: 微信小游戏发布预检
display_name_en: WeChat Mini Game Publish Pre-check
description: |
  🎮 WeChat Mini Game 发布预检工具——检查项目结构、配置完整性、monetization 设置，
  生成 publish-checklist.md 确保游戏符合 WeChat 发布要求。
  触发词：发布小游戏 / 检查游戏配置 / 小游戏预检 / publish game / check game config。
  当用户说「帮我发布小游戏」或「检查这个游戏配置」时触发。
  语言跟随用户（中文/英文）。
  Do NOT use for：实际发布到 WeChat（需人工在 DevTools 操作）、生成游戏代码、
  替代 WeChat DevTools。
description_zh: |
  微信小游戏发布预检工具——检查项目结构、配置完整性、monetization 设置，
  生成 publish-checklist.md 确保游戏符合微信审核要求。
  一键验证 project.config.json、game.json、广告位配置、包大小，
  30秒完成全部检查，输出标准化报告。
description_en: |
  WeChat Mini Game publish pre-check tool — validates project structure, configuration completeness, and monetization settings.
  Generates publish-checklist.md to ensure compliance with WeChat review requirements.
  One-click validation of project.config.json, game.json, ad placements, and package size.
version: 0.0.8
author: 繁星粤动
metadata:
  slug: wx-game-publish
  packageName: '@oomoler_1-js/wx-game-publish'
  tags:
    - wechat
    - minigame
    - publish
    - preflight
    - monetization
  labels:
    requires_api_key: false
---

# wx-game-publish — 微信小游戏发布预检

> 30秒检查，告别反复调试发布失败

替你把「小游戏开发完成 → 能发布」之间的脏活跑完：检查项目结构、验证配置、
扫描 monetization 设置、计算包大小，输出 publish-checklist.md。

## 为什么需要这个工具？

微信小游戏发布有严格要求：
- ❌ appid 错误 → 审核被拒
- ❌ compileType 不对 → 无法上传
- ❌ 包大小超 2MB → 必须分包
- ❌ 广告位占位符未替换 → 上线后广告不显示

手动检查容易遗漏，这个 skill 帮你**一次性跑完所有检查**。

## Workflow

1. **接收项目**：接受游戏项目路径或 zip 文件（默认当前工作目录）
2. **解压/读取**：若为 zip，解压到临时目录；若为目录，直接读取
3. **检查必要文件**：project.config.json, game.json, src/ 目录
4. **验证 project.config.json**：
   - appid 存在且非空（`test` 为测试环境，⚠️ 警告）
   - compileType === 'game'（必须）
   - setting 包含 es6: true
5. **验证 game.json**：
   - deviceOrientation 存在（⚠️ 警告若缺失）
   - networkTimeout 合理（⚠️ 警告若缺失）
6. **检查 monetization 配置**：
   - src/config.js 中的 AD 对象（广告位 ID 是否为占位符）
   - src/ads.js 是否存在
7. **计算包大小**：
   - 统计 src/ 目录总大小
   - 检查是否超过 2MB（主包限制）
   - 检查 node_modules 是否存在（⚠️ 警告，应排除）
8. **检查 api.js**：
   - USE_MOCK 是否为 true（⚠️ 警告，上线前需改 false）
9. **生成 publish-checklist.md**：Markdown 报告，✅/⚠️/❌ 标记
10. **打印摘要到 stdout**：关键发现和建议

## Clarification Protocol

- **一次性追问**：确认项目路径 + monetization 配置位置（若用户不确定）
- **逐步澄清**：不适用（需求边界清晰）
- **选项式**：不适用（WeChat 配置要求是固定的）
- **关键假设确认**：WeChat 包大小限制（主包 2MB，分包 20MB），若用户项目特殊可覆盖

## Resource Routing

- 命中【项目结构/配置检查】→ 运行 `scripts/validate.js <project-path>` → 产出 `publish-checklist.md`
- 命中【WeChat 发布要求】→ 加载【references/wechat-requirements.md】→ 产出【配置检查清单】
- 命中【monetization 配置】→ 加载【references/monetization-guide.md】→ 产出【广告位配置建议】
- 命中【报告模板】→ 加载【assets/template-checklist.md】→ 产出【格式化报告】

### 三层路由表（A-401）

1. **正向决策表**：见上
2. **易混淆消歧表**：
   - 像「发布小游戏」但其实不是 → 别用「自动化发布」该用「预检检查」
   - 像「检查配置」但其实不是 → 别用「修改配置」该用「仅输出报告」
3. **跨模块顺序表**：组合任务按「结构检查 → 配置验证 → monetization 检查 → 报告生成」顺序读

## Failure Handling

### 四状态

| 状态 | 判定 | 处理 |
|------|------|------|
| Not started | 未开始 | 向用户说明障碍与替代路径 |
| In progress | 进行中 | 输出 partial checklist，标记已检查项 |
| Partial success | 部分成功 | 说清已完成哪几项、缺口在哪、从哪续 |
| Failed safely | 安全失败 | 保留中间产物 + 写 `publish-error.log` |

### 双层错误分类

| 级别 | 退出码 | 错误码 | 原因 | 建议处理 |
|------|--------|--------|------|----------|
| 进程级 | 1 | — | Node.js 脚本执行失败 | 检查 Node.js 环境、依赖安装 |
| 业务级 | — | E001 | 项目目录不存在 | 检查路径是否正确 |
| 业务级 | — | E002 | project.config.json 不存在 | 确认项目结构是否正确 |
| 业务级 | — | E003 | appid 为空 | 在微信开发者工具中查看 appid |
| 业务级 | — | E004 | compileType 不为 game | 修改 project.config.json |
| 业务级 | — | E005 | 主包大小超过 2MB | 分包处理或压缩资源 |

### 拒绝类失败（fail-with-direction）

- 用户说「帮我发布到 WeChat」→ 提醒：「本 skill 只检查配置，发布需手动在微信开发者工具操作。请运行 `wxgame publish` 或在 DevTools 中点击「上传」。」
- 用户说「帮我生成游戏代码」→ 拒绝：「本 skill 不生成游戏代码。请使用 `skill-creator` 或 `wechat-miniprogram` skill。」

## Validation

完成前必查：
1. `publish-checklist.md` 存在
2. 退出码 0（无 critical 错误）或用户已确认 ⚠️ 警告
3. 报告包含 ✅/⚠️/❌ 状态标记
4. 用户亲自跑一遍测试，AI 不能当唯一判官

## 约束（硬 → 检查项·机器判定）

1. **appid 必须非空且非 test** → `!appid || appid === 'test'` → ⚠️ 警告（测试环境可继续）
2. **compileType 必须为 game** → `config.compileType !== 'game'` → ❌ 阻塞
3. **主包大小 ≤2MB** → `totalSize > 2 * 1024 * 1024` → ❌ 阻塞
4. **不修改用户源文件** → 只读操作，写入仅限于生成报告文件

## 非目标清单

- ❌ 不自动发布到 WeChat（需人工在 DevTools 操作）
- ❌ 不处理 WeChat Developer Console 认证
- ❌ 不生成游戏代码或资产
- ❌ 不替代 WeChat DevTools 本身
- ❌ 不修改用户的 project.config.json 或 game.json