mp-pilates/.claude/skills/wechat-devtools-http-preview/SKILL.md

---
name: wechat-devtools-http-preview
description: '通过微信开发者工具 HTTP V2 接口完成小程序登录检查、自动预览、上传体验版等操作。适用于用户提到微信开发者工具 HTTP、自动预览、体验版上传、命令行发布体验版、流水线触发开发者工具发布时。'
license: MIT
allowed-tools: Bash
---

# 微信开发者工具 HTTP V2 体验版发布

## 适用场景

当用户出现以下意图时使用本 skill：

- 希望通过命令行或脚本调用微信开发者工具。
- 希望上传小程序体验版。
- 希望生成或刷新预览二维码。
- 希望把开发者工具 HTTP 能力接入本地自动化流程。
- 提到 `HTTP V2`、`/v2/upload`、`/v2/preview`、`/v2/autopreview`、`微信开发者工具端口` 等关键词。

## 核心结论

微信开发者工具在启动后会自动开启本地 HTTP 服务。对于“通过命令行发布体验版”这个目标，最直接的路径是：

1. 确认开发者工具已启动并拿到本地端口。
2. 确认工具已登录。
3. 如有需要先执行 `/v2/open` 打开项目。
4. 如项目依赖 npm，必要时先执行 `/v2/buildnpm`。
5. 调用 `/v2/upload` 上传体验版代码。
6. 如需同时给测试同学扫码，调用 `/v2/preview` 或 `/v2/autopreview`。

文档同时明确说明：如果场景是完全不依赖开发者工具的 CI/CD，官方更推荐 `miniprogram-ci`。因此本 skill 的定位是“基于本机已安装且已运行的微信开发者工具做自动化”，不是替代纯 CI 方案。

## 文档沉淀

根据微信开发者工具 HTTP 文档，需要记住这些约束：

- 接口路径统一使用 `/v2` 前缀。
- HTTP 服务会在开发者工具启动后自动开启。
- 端口号记录在用户目录下的 `.ide` 文件。
- `project` 参数一般都要求传项目绝对路径，且必须 URL encode。
- 项目目录必须存在合法的 `project.config.json`，并至少包含 `appid` 与 `projectname`。
- `upload` 用于上传代码，也就是生成体验版。
- `preview` 返回预览二维码。
- `autopreview` 会自动刷新并预览项目，适合频繁本地联调。
- `islogin` 可用于判断当前开发者工具是否已登录。
- `login` 可输出二维码，支持 `image`、`base64`、`terminal` 三种格式。
- `info-output` 可把预览或上传附加信息输出到 JSON 文件，适合自动化流程记录产物。

## 端口定位

开发者工具端口号文件：

- macOS: `~/Library/Application Support/微信开发者工具/<MD5>/Default/.ide`
- Windows: `~/AppData/Local/微信开发者工具/User Data/<MD5>/Default/.ide`

文档给出的 MD5 规则：`MD5(${installPath}${nwVersion})`

已知默认值：

- macOS: `installPath = /Applications/wechatwebdevtools.app/Contents/MacOS`
- macOS: `nwVersion = ''`
- Windows: `installPath = 微信开发者工具.exe 所在目录`
- Windows: `nwVersion = installPath/version` 文件中 `latestNw` 的值

## 标准工作流

### 1. 检查工具是否启动

先读取 `.ide` 文件中的端口号；如果没有端口文件，说明工具大概率未启动，先提示用户启动微信开发者工具。

### 2. 检查是否已登录

调用：

```bash
curl "http://127.0.0.1:${PORT}/v2/islogin"
```

如果未登录，调用 `/v2/login`，按需要输出二维码：

```bash
curl "http://127.0.0.1:${PORT}/v2/login?qr-format=terminal"
curl "http://127.0.0.1:${PORT}/v2/login?qr-format=base64&qr-output=%2Ftmp%2Fwechat-login.txt"
curl "http://127.0.0.1:${PORT}/v2/login?result-output=%2Ftmp%2Fwechat-login-result.json"
```

### 3. 打开或刷新项目

```bash
curl "http://127.0.0.1:${PORT}/v2/open?project=${ENCODED_PROJECT}"
```

当用户只要求上传或预览时，这一步不是必选，但执行后通常更稳定。

### 4. 构建 npm

当项目启用了小程序 npm 并且近期依赖有变更时执行：

```bash
curl "http://127.0.0.1:${PORT}/v2/buildnpm?project=${ENCODED_PROJECT}&compile-type=miniprogram"
```

### 5. 上传体验版

体验版发布的核心接口就是：

```bash
curl "http://127.0.0.1:${PORT}/v2/upload?project=${ENCODED_PROJECT}&version=${VERSION}&desc=${DESC}"
```

推荐同时加 `info-output`：

```bash
curl "http://127.0.0.1:${PORT}/v2/upload?project=${ENCODED_PROJECT}&version=${VERSION}&desc=${DESC}&info-output=${ENCODED_INFO_OUTPUT}"
```

参数要求：

- `project`：必填，项目绝对路径。
- `version`：必填，版本号。
- `desc`：可选，版本备注。
- `info-output`：可选，输出上传附加信息 JSON。

### 6. 生成预览二维码

如果用户还需要扫码体验，可继续调用：

```bash
curl "http://127.0.0.1:${PORT}/v2/preview?project=${ENCODED_PROJECT}&qr-format=terminal"
curl "http://127.0.0.1:${PORT}/v2/preview?project=${ENCODED_PROJECT}&qr-format=base64&qr-output=${ENCODED_QR_PATH}"
curl "http://127.0.0.1:${PORT}/v2/autopreview?project=${ENCODED_PROJECT}&info-output=${ENCODED_INFO_OUTPUT}"
```

区别：

- `/v2/preview`：单次预览，拿二维码最直接。
- `/v2/autopreview`：更适合联调时自动刷新预览。

## 推荐命令模板

### macOS 读取端口

如果已知是默认安装路径，可用下面的方式快速算出 `.ide` 路径：

```bash
MD5=$(printf '/Applications/wechatwebdevtools.app/Contents/MacOS' | md5)
PORT_FILE="$HOME/Library/Application Support/微信开发者工具/${MD5}/Default/.ide"
PORT=$(cat "$PORT_FILE")
```

### URL encode 项目路径

```bash
PROJECT="/absolute/path/to/miniprogram"
ENCODED_PROJECT=$(python3 - <<'PY'
import os, urllib.parse
print(urllib.parse.quote(os.environ['PROJECT'], safe=''))
PY
)
```

### 上传体验版完整示例

```bash
PROJECT="/absolute/path/to/miniprogram"
VERSION="1.2.3"
DESC="体验版发布：修复预约课表"
INFO_OUTPUT="/tmp/wechat-upload-info.json"

ENCODED_PROJECT=$(python3 - <<'PY'
import os, urllib.parse
print(urllib.parse.quote(os.environ['PROJECT'], safe=''))
PY
)

ENCODED_DESC=$(python3 - <<'PY'
import os, urllib.parse
print(urllib.parse.quote(os.environ['DESC'], safe=''))
PY
)

ENCODED_INFO_OUTPUT=$(python3 - <<'PY'
import os, urllib.parse
print(urllib.parse.quote(os.environ['INFO_OUTPUT'], safe=''))
PY
)

curl "http://127.0.0.1:${PORT}/v2/upload?project=${ENCODED_PROJECT}&version=${VERSION}&desc=${ENCODED_DESC}&info-output=${ENCODED_INFO_OUTPUT}"
```

## 执行规则

当你代表用户执行这个流程时，按下面顺序做：

1. 先确认当前系统是否安装并启动了微信开发者工具。
2. 优先读取 `.ide` 端口文件，而不是盲猜端口。
3. 上传前先验证 `project.config.json` 是否存在且含 `appid`、`projectname`。
4. 涉及路径、备注、输出文件参数时，一律 URL encode。
5. 如果 `islogin` 未登录，先引导用户扫码登录，不要直接继续上传。
6. 如果用户目标是“发布体验版”，优先使用 `/v2/upload`；不要误用 `/preview` 代替。
7. 如果用户目标是“出二维码给别人扫”，优先使用 `/v2/preview`。
8. 如果用户目标是“边改边自动刷新”，优先使用 `/v2/autopreview`。

## 故障排查

### 端口文件不存在

说明通常是开发者工具没启动，或者安装路径/MD5 推导错了。

排查顺序：

1. 让用户先手动打开微信开发者工具。
2. 检查是否使用了正确安装路径。
3. 重新计算 MD5。

### 调用 HTTP 接口失败

优先检查：

1. 是否能访问 `http://127.0.0.1:${PORT}/v2/islogin`
2. `PORT` 是否来自正确的 `.ide` 文件。
3. 开发者工具版本是否支持 `HTTP V2`。

### 上传失败

优先检查：

1. `project` 是否为绝对路径。
2. 是否已 URL encode。
3. `project.config.json` 是否存在。
4. `project.config.json` 里是否包含 `appid` 和 `projectname`。
5. 是否已登录工具。
6. npm 依赖是否需要先执行 `/v2/buildnpm`。

## 输出要求

当用户让你“帮我发布体验版”时，最终回复必须明确交代：

- 是否成功调用了 `/v2/upload`
- 使用的版本号与备注
- 是否生成了 `info-output` 文件
- 如果还做了预览，二维码输出到哪里或以什么格式返回

如果没有成功执行，必须明确停在哪一步，不要模糊地说“可能发布了”。

## 引用来源

本 skill 基于微信开放文档：

- 页面：微信开发者工具 HTTP V2
- 关键接口：`/v2/login`、`/v2/islogin`、`/v2/open`、`/v2/buildnpm`、`/v2/upload`、`/v2/preview`、`/v2/autopreview`