perf: 更新微信开发者工具调用 skill
This commit is contained in:
richarjiang
252
.claude/skills/wechat-devtools-http-preview/SKILL.md
Normal file
252
.claude/skills/wechat-devtools-http-preview/SKILL.md
Normal file
@@ -0,0 +1,252 @@
|
||||
---
|
||||
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`
|
||||
|
||||
Reference in New Issue
Block a user