richard/mp-pilates
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
14d7c03b05b2b8ca94aaaa9863faab353a80e4c9
mp-pilates/.claude/skills/wechat-devtools-http-preview/SKILL.md
richarjiang 14d7c03b05 perf: 更新微信开发者工具调用 skill
2026-04-19 22:45:43 +08:00

8.3 KiB
Raw Blame History

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

调用：

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

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

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. 打开或刷新项目

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

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

4. 构建 npm

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

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

5. 上传体验版

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

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

推荐同时加 info-output：

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. 生成预览二维码

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

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 路径：

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

URL encode 项目路径

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

上传体验版完整示例

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 View Git Blame Copy Permalink