docs: 更新小程序发布技能文档

- usage.md: 添加构建行为说明和 --build 参数说明
- faq.md: 添加开发版构建跳过说明和 ES5 转译问题解决方案
- config.md: 添加命令行参数说明和输出路径配置

Generated with [Claude Code](https://claude.com/claude-code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

.claude/skills/weapp-publish/references/config.md

@@ -56,6 +56,37 @@ pnpm install
 
 ---
 
+## 命令行参数
+
+### 发布类型 (action)
+
+| 参数 | 说明 | 构建行为 | 输出路径 |
+|------|------|----------|----------|
+| `experience` | 体验版（默认） | 默认执行构建 | `dist/weapp/production/` |
+| `dev` | 开发版 | 默认跳过构建 | `dist/weapp/development/` |
+
+### 构建控制参数
+
+| 参数 | 说明 |
+|------|------|
+| `--build` | 强制执行构建 |
+| `--no-build` | 跳过构建 |
+
+### 使用示例
+
+```bash
+# 开发版使用 watch 模式输出（快速）
+node scripts/publish-weapp.js enterprise dev
+
+# 开发版强制重新构建
+node scripts/publish-weapp.js enterprise dev --build
+
+# 体验版跳过构建（不推荐）
+node scripts/publish-weapp.js enterprise experience --no-build
+```
+
+---
+
 ## 环境变量配置
 
 发布时可通过环境变量自定义：
@@ -81,6 +112,19 @@ VERSION=1.2.0 DESC="新增功能" pnpm run publish:enterprise
 
 ---
 
+## 输出路径说明
+
+发布脚本根据类型自动选择输出路径：
+
+| 类型 | 环境变量 | 输出目录 | 用途 |
+|------|----------|----------|------|
+| **体验版** | `NODE_ENV=production` | `dist/weapp/production/` | 提交审核/体验版 |
+| **开发版** | `NODE_ENV=development` | `dist/weapp/development/` | 开发调试 |
+
+开发版使用 `.env.development` 中的 API 配置，体验版使用 `.env.production`。
+
+---
+
 ## 发布前准备
 
 ### 1. 安装技能依赖
@@ -102,3 +146,20 @@ pnpm install
 ### 3. 配置 IP 白名单
 
 在微信公众平台配置服务器的 IP 白名单。
+
+### 4. 确保 ES5 转译配置
+
+小程序的 `config/dev.ts` 中应包含以下配置，确保所有依赖被转译为 ES5：
+
+```ts
+mini: {
+  compile: {
+    include: [
+      // 确保产物为 es5，转译所有 node_modules（除了 Babel 核心）
+      filename => /node_modules\/(?!(@babel|core-js|style-loader|css-loader|react|react-dom))/.test(filename)
+    ]
+  }
+}
+```
+
+**原因**：微信小程序的预览编译器不完全支持 ES6+ 语法（如可选链 `?.`），需要确保所有代码被转译为 ES5。

.claude/skills/weapp-publish/references/faq.md

@@ -12,6 +12,38 @@
 
 **A**: 发布成功后，登录小程序后台"版本管理"，将指定版本设置为体验版。
 
+### Q: 开发版预览二维码生成失败，提示语法错误
+
+**A**: 这通常是因为代码中包含了微信小程序不支持的 ES6+ 语法（如可选链 `?.`）。
+
+**解决方案**：
+1. 确保小程序的 `config/dev.ts` 中配置了 ES5 转译：
+   ```ts
+   mini: {
+     compile: {
+       include: [
+         filename => /node_modules\/(?!(@babel|core-js|style-loader|css-loader|react|react-dom))/.test(filename)
+       ]
+     }
+   }
+   ```
+2. 使用 `--build` 参数强制重新构建
+
+### Q: 开发版为什么默认跳过构建？
+
+**A**: 开发版默认使用 `dev:weapp` (watch 模式) 的构建输出，因为：
+1. 开发时通常会运行 watch 模式，代码实时编译
+2. 跳过构建可以快速生成预览二维码，提高开发效率
+3. 如需重新构建，添加 `--build` 参数
+
+### Q: 体验版和开发版有什么区别？
+
+**A**:
+| 类型 | 用途 | 构建行为 | 输出路径 |
+|------|------|----------|----------|
+| **体验版** (experience) | 提交给测试人员体验 | 默认执行构建 | `dist/weapp/production/` |
+| **开发版** (dev) | 开发者自测 | 默认跳过构建 | `dist/weapp/development/` |
+
 ---
 
 ## 注意事项
@@ -21,3 +53,4 @@
 3. **版本管理**: 建议使用语义化版本号 (Semantic Versioning)
 4. **IP 白名单**: 确保服务器 IP 已在微信公众平台配置白名单
 5. **机器人编号**: 多个 CI 并发时使用不同的 robot 编号 (1-30)
+6. **开发模式**: 开发版预览前请确保 `dev:weapp` 正在运行

.claude/skills/weapp-publish/references/usage.md

@@ -3,31 +3,54 @@
 ## 发布企业小程序
 
 ```bash
-# 使用默认版本号和描述
+# 使用默认版本号和描述（体验版）
 pnpm run publish:enterprise
 
 # 自定义版本号和描述
 VERSION=1.2.0 DESC="新增订单管理功能" pnpm run publish:enterprise
 
-# 生成预览二维码
+# 生成预览二维码（默认跳过构建，使用 watch 模式输出）
 pnpm run publish:enterprise:dev
+
+# 强制重新构建后生成预览二维码
+pnpm run publish:enterprise:dev --build
 ```
 
 ## 发布人才小程序
 
 ```bash
-# 使用默认版本号和描述
+# 使用默认版本号和描述（体验版）
 pnpm run publish:talent
 
 # 自定义版本号和描述
 VERSION=2.0.0 DESC="全新改版，优化求职流程" pnpm run publish:talent
 
-# 生成预览二维码
+# 生成预览二维码（默认跳过构建，使用 watch 模式输出）
 pnpm run publish:talent:dev
+
+# 强制重新构建后生成预览二维码
+pnpm run publish:talent:dev --build
 ```
 
 ---
 
+## 构建行为说明
+
+### 开发版 (dev)
+- **默认跳过构建**：直接使用 `dev:weapp` (watch 模式) 的输出
+- 适用场景：本地开发时快速生成预览二维码
+- 强制构建：添加 `--build` 参数
+
+### 体验版 (experience)
+- **默认执行构建**：确保发布的是最新代码
+- 跳过构建：添加 `--no-build` 参数（不推荐）
+
+### 输出路径
+- 开发版：`dist/weapp/development/`
+- 体验版：`dist/weapp/production/`
+
+---
+
 ## 快捷命令参考
 
 | 用户指令 | Claude 行为 |