From 14d7c03b05b2b8ca94aaaa9863faab353a80e4c9 Mon Sep 17 00:00:00 2001
From: richarjiang <richarjiang@tencent.com>
Date: Sun, 19 Apr 2026 22:45:43 +0800
Subject: [PATCH] =?UTF-8?q?perf:=20=E6=9B=B4=E6=96=B0=E5=BE=AE=E4=BF=A1?=
 =?UTF-8?q?=E5=BC=80=E5=8F=91=E8=80=85=E5=B7=A5=E5=85=B7=E8=B0=83=E7=94=A8?=
 =?UTF-8?q?=20skill?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../wechat-devtools-http-preview/SKILL.md     | 252 ++++++++++++++++++
 1 file changed, 252 insertions(+)
 create mode 100644 .claude/skills/wechat-devtools-http-preview/SKILL.md

diff --git a/.claude/skills/wechat-devtools-http-preview/SKILL.md b/.claude/skills/wechat-devtools-http-preview/SKILL.md
new file mode 100644
index 0000000..8179eb3
--- /dev/null
+++ b/.claude/skills/wechat-devtools-http-preview/SKILL.md
@@ -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`
+