weixin-miniprogram-cli

专为 AI Coding Agent 设计的微信小程序自动化 CLI。配合 Skill 使用，打通开发、测试、部署的全流程。

For AI Agents

请安装对应Skill来使用，目录为：skills/weixin-miniprogram-cli。

安装

推荐通过 npm 全局安装：

npm install -g weixin-miniprogram-cli

或从源码手动安装：

git clone https://github.com/BigLiao/weixin-miniprogram-cli.git
cd weixin-miniprogram-cli
npm install && npm run build && npm link

前置条件： Node.js >= 16，已安装微信开发者工具并开启 设置 → 安全设置 → 服务端口。

测试

仓库已切换到正式单元测试框架 vitest。

npm test
npm run test:watch

当前首批用例覆盖命令解析、上下文状态管理和项目路径校验等稳定基础能力；后续命令级行为可以继续在此基础上补齐。

端到端测试单独执行：

WX_E2E=1 npm run test:e2e

默认会使用 examples/miniprogram-demo 作为示例项目，也支持环境变量覆盖：

WX_E2E=1 \
WX_E2E_PROJECT=./examples/miniprogram-demo \
WX_E2E_AUTO_PORT=9420 \
npm run test:e2e

E2E 依赖本机已安装并登录微信开发者工具，且已开启“服务端口”。运行产物会保存到 artifacts/e2e/。

安装 Skill

通过自带命令可以自动安装 Skill。

wx-mp-cli install-skill              # 安装到当前项目 .claude/skills/
wx-mp-cli install-skill --universal  # 安装到 .agent/skills/（跨 agent 通用）
wx-mp-cli install-skill --global     # 安装到 ~/.claude/skills/（用户全局）

或者手动下载 ./skills/weixin-miniprogram-cli 到skills目录下。

基本使用

安装完后可以通过命令操作微信开发者工具来实现自动化。

wx-mp-cli open ./my-miniprogram
wx-mp-cli launch --auto-port 9420
wx-mp-cli snapshot                        # 获取页面元素
wx-mp-cli click "button.submit"           # 通过 UID 交互
wx-mp-cli assert-text ".title" --text "成功"
wx-mp-cli screenshot --path ./result.png
wx-mp-cli close

命令一览

执行 wx-mp-cli help <command> 查看完整参数。

连接

wx-mp-cli open ./my-miniprogram                 # 打开 IDE 项目并创建 session
wx-mp-cli launch --auto-port 9420               # 启动 automator 并连接当前 session
wx-mp-cli status                                # 查看当前 session 状态
wx-mp-cli session list                          # 查看所有 session
wx-mp-cli close                                 # 关闭项目窗口并销毁当前 session

端口语义：

• open --port <port>：IDE HTTP 服务端口
• launch --auto-port <port>：automator WebSocket 端口

快照与查询

wx-mp-cli snapshot                         # 页面元素树 + UID
wx-mp-cli page                             # 当前页面信息
wx-mp-cli query ".search-input"            # 按选择器查找元素
wx-mp-cli wait --selector ".modal"         # 等待元素出现

snapshot 返回页面所有元素及自动生成的 UID，后续命令用 UID 操作元素。页面跳转后需重新执行。

交互

wx-mp-cli click "button.submit"                    # 点击
wx-mp-cli fill "input.username" --text "test"      # 输入文本
wx-mp-cli value "input.username"                   # 读取值
wx-mp-cli hover "view.card"                        # 长按

导航

wx-mp-cli goto "pages/detail/index"        # 跳转页面（自动识别 tabBar）
wx-mp-cli go-back                          # 返回
wx-mp-cli relaunch "pages/home/index"      # 重启到指定页面
wx-mp-cli scroll 500                       # 滚动到指定位置（px）

断言

wx-mp-cli assert-text ".title" --text "你好"               # 精确匹配
wx-mp-cli assert-text ".desc" --textContains "欢迎"        # 包含
wx-mp-cli assert-text ".code" --textMatches "v\\d+\\.\\d+"   # 正则
wx-mp-cli assert-attr ".btn" --key class --value active    # 属性断言
wx-mp-cli assert-state ".modal" --visible                  # 可见性

截图与脚本

wx-mp-cli screenshot --path ./shot.png     # 截图
wx-mp-cli eval "return wx.getSystemInfoSync()"  # 在页面执行 JS

控制台与网络

wx-mp-cli console                          # 控制台日志
wx-mp-cli console --types error            # 按类型过滤
wx-mp-cli console-detail 5                 # 日志详情
wx-mp-cli network                          # 网络请求列表
wx-mp-cli network --failedOnly             # 仅失败请求
wx-mp-cli network-detail "req_3"           # 请求详情
wx-mp-cli network-clear                    # 清空记录

存储

wx-mp-cli storage --action list
wx-mp-cli storage --action get --key userToken
wx-mp-cli storage --action set --key theme --value '"dark"'
wx-mp-cli storage --action remove --key tempData
wx-mp-cli storage --action clear

CI / IDE 控制

本地执行，无需 daemon——直接控制开发者工具 IDE：

wx-mp-cli ide-open --project ./my-app      # 打开项目
wx-mp-cli ide-open --appid wx1234567890    # 按 AppID 打开目标
wx-mp-cli login --qr-size default          # 登录（终端显示二维码）
wx-mp-cli login --result-output ./login.json
wx-mp-cli islogin                          # 检查登录状态
wx-mp-cli upload --version 1.0.0           # 上传代码
wx-mp-cli upload --appid wx1234567890 --version 1.0.0
wx-mp-cli preview --project ./my-app       # 预览（生成二维码）
wx-mp-cli preview --appid wx1234567890
wx-mp-cli build-npm --compile-type plugin  # 构建 NPM
wx-mp-cli auto --project ./my-app --auto-account <openid>
wx-mp-cli cache --clean compile            # 清理工具缓存
wx-mp-cli ide-close                        # 关闭项目窗口
wx-mp-cli quit                             # 退出开发者工具

相关 IDE 命令统一支持项目目标参数：

--project <path>           # 项目路径
--appid <appid>            # 小程序 AppID 或第三方平台 AppID
--ext-appid <ext-appid>    # 第三方平台开发时被开发 AppID

如果同时传了 --project 和 --appid / --ext-appid，会优先使用 --project。

诊断

wx-mp-cli doctor                           # 环境与连接一键诊断

工作原理

open 负责打开 IDE 项目并创建 session，launch 负责通过 cli auto --auto-port 启动 automator 并建立 miniprogram-automator 连接。后续每条命令通过 Unix Socket 与 daemon 通信，执行后即退出。daemon 在命令间持续维护 session、元素映射、控制台日志和网络记录；当最后一个 session 被 close 清理后，daemon 会自动退出。

配置

wx-mp-cli config                           # 查看配置
wx-mp-cli config --cliPath <path>          # 设置开发者工具 CLI 路径
wx-mp-cli config --defaultProject <path>   # 设置默认项目

开发者工具路径在 macOS/Windows 上自动检测，也可通过环境变量 WECHAT_DEVTOOLS_CLI 覆盖。

License

MIT