wuliLiuyue/wxpilot

wxpilot

面向 AI Agent 的微信小程序自动化 CLI
让 Agent 像操作浏览器一样操作微信开发者工具——页面导航、元素交互、状态读取、网络抓包与 mock。

目录

- 特性
- 工作原理
- 前置要求
- 安装
- 快速开始
- 核心概念
- 命令参考
- 网络代理与 mock
- 低 token 输出设计
- 架构
- 开发
- AI Agent 集成
- MCP 集成
- dsh 集成
- 贡献
- 许可证

特性

- 为 Agent 而生：所有命令输出默认紧凑化，统一截断至 4000 字符，最大程度降低上下文消耗
- Ref 机制：view 后页面可交互元素自动编号 %N，Agent 用编号即可点击/输入，无需维护选择器
- 低 token 查找：find  按 text/class/placeholder/tag 直接定位元素并返回 %N，无需通读整页
- 自动项目检测：省略路径时自动扫描当前目录下的 dist/project.config.json，多候选时交互选择
- 内置代理抓包：--proxy 一键启动 HTTP/HTTPS MITM 代理，支持请求 mock 与 body 查看
- JSON 模式：--json 输出结构化结果，便于程序/Agent 解析
- Daemon 托管：CLI 首次调用自动拉起后台 daemon，Unix Socket 通信，30 分钟空闲自动退出
- 推荐 Agent 接入方式：优先使用 Skill + CLI；对于已经采用 MCP 管理工具的宿主，提供可选的 MCP stdio 适配器

工作原理

┌─────────┐   JSON-RPC    ┌──────────┐   WebSocket   ┌─────────────────────┐
│ wxpilot │ ────────────► │  daemon  │ ────────────► │  微信开发者工具      │
│  (CLI)  │ ◄──────────── │ (后台)   │ ◄──────────── │  (automator + 页面) │
└─────────┘   Unix Socket └────┬─────┘               └─────────────────────┘
│
├── proxy      HTTP/HTTPS MITM 抓包 + mock
├── snapshot   WXML → 元素树 + 交互节点检测
└── ref-store  %N 临时引用与过期校验

CLI 与 daemon 分离：CLI 仅负责参数解析与输出格式化，daemon 负责实际的自动化控制、代理与状态管理。两者通过 ~/.wxpilot/rust-daemon.sock 通信。

前置要求

- macOS（当前仅提供 macOS 二进制；Linux/Windows 暂不支持）
- 微信开发者工具已安装并启动
- 源码构建需 Rust stable 工具链（rustup show 查看）

安装

一键安装（macOS）

curl -fsSL https://raw.githubusercontent.com/wuliLiuyue/wxpilot/main/install.sh | bash

指定版本：

curl -fsSL https://raw.githubusercontent.com/wuliLiuyue/wxpilot/main/install.sh | bash -s -- --version v0.1.0

自定义安装目录：

curl -fsSL https://raw.githubusercontent.com/wuliLiuyue/wxpilot/main/install.sh | bash -s -- \
--install-dir ~/.local/bin --daemon-dir ~/.wxpilot/bin

安装后：

- wxpilot → ~/.local/bin/wxpilot
- wxp-daemon → ~/.wxpilot/bin/wxp-daemon

若 ~/.local/bin 不在 PATH 中，按提示追加：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

源码构建

cd rust
cargo build -p wxp-cli --bin wxpilot
cargo build -p wxp-daemon --bin wxp-daemon
./target/debug/wxpilot --version

packages/web 为官网源码，与 CLI 无关，源码构建无需关注。

快速开始

1. 启动自动化（自动检测 dist/project.config.json，或明确指定路径）
wxpilot start
wxpilot start /path/to/miniprogram
wxpilot start /path/to/miniprogram --proxy          # 抓包：自动拉起 8899 代理
wxpilot start /path/to/miniprogram --appid wx你的AppID

2. 连接
wxpilot connect

3. 查看页面，获取可交互元素引用 %N
wxpilot view
wxpilot find 提交            # 低 token 查找，直接返回匹配到的 %N

4. 交互
wxpilot tap %1
wxpilot type %2 "13800138000"
wxpilot goto /pages/order/index

5. 导航后引用失效，重新获取
wxpilot view

6. 读取状态 / 断言 / 截图
wxpilot state cart.total     # 只读需要的子字段
wxpilot assert %3 "提交成功"
wxpilot shot /tmp/result.png

核心概念

Ref 机制

执行 wxpilot view 或 wxpilot find 后，页面可交互元素被分配临时编号 %N（从 %1 开始）。

- 编号在 view / find 时重新生成
- goto / back / reload 后编号失效，需重新执行 view
- 使用失效编号会报错：ref_expired: %N

交互节点识别（双重信号）：微信开发者工具的 outerWxml() 快照不保留 bindtap 等事件属性，因此采用：

1. data- 属性——快照中保留，作为 bindtap 的代理信号（约 80% 覆盖）
2. 源文件指纹——读取 .wxml 源文件，按 tag:sorted-classes 提取有 bindtap 节点的指纹，补全无 data- 的漏判节点

项目路径自动检测

wxpilot start 的 projectPath 参数可选：

- 省略时扫描 CWD 下最多 2 层子目录，收集含 project.config.json 的 dist 目录
- 唯一候选：自动使用
- 多个候选：交互选择
- 无候选：报错提示手动传入

命令参考

连接管理

wxpilot start                                      # 自动检测 dist/project.config.json
wxpilot start                         # 启动自动化（cli auto，等待就绪）
wxpilot start  --appid            # appid 为占位符时指定
wxpilot start  --cli-path       # 指定开发者工具 CLI 路径
wxpilot start  --auto-port 9421       # 自动化端口（默认 9420）
wxpilot start  --proxy                # 自动启动 127.0.0.1:8899 代理
wxpilot start  --proxy --https        # HTTPS MITM 抓包（需先安装 CA）
wxpilot connect                                    # 连接（使用 start 记录的端点）
wxpilot connect --ws                   # 直接指定 ws 端点
wxpilot disconnect
wxpilot status

导航

wxpilot goto           # 如 /pages/order/index
wxpilot back
wxpilot reload

视图

wxpilot view                  # 紧凑交互摘要（compact, depth=5, limit=50）
wxpilot view --full           # 完整树（含非交互节点，depth=20）
wxpilot view --depth
wxpilot view --limit
wxpilot find           # 查 text/class/placeholder/tag，默认只查交互节点
wxpilot find  --all    # 包含非交互节点
wxpilot find  --limit
wxpilot wait %N [--timeout 5000]

交互

wxpilot tap %N
wxpilot type %N
wxpilot scroll %N

读取

wxpilot read %N               # 读取元素文本
wxpilot assert %N   # 断言文本（不匹配则退出码 1）
wxpilot state                 # 顶层 key 摘要（类型+大小）
wxpilot state [path]          # 指定子路径，如 cart.items
wxpilot state --full          # 完整页面 data
wxpilot shot [path]           # 截图，保存文件并返回路径
wxpilot shot [path] --base64  # 截图并附带 base64

网络代理

wxpilot net start [--port 8899] [--https]     # 独立启动代理（--https 可解密 HTTPS）
wxpilot net stop
wxpilot net log [--filter ] [--limit 20] # 摘要，不含 body
wxpilot net log [--filter ] --with-body  # 含请求/响应体（截断 2000 字符）
wxpilot net mock
wxpilot net unmock
wxpilot net clear
wxpilot net install-ca                        # 安装 CA 到钥匙串（HTTPS 首次使用）

执行

wxpilot run               # 在页面 VM 中执行 JS（不能访问 Node.js API）
wxpilot wx  [args...] # 调用 wx API

Daemon

wxpilot daemon stop
wxpilot daemon restart

全局选项

--timeout     默认 10000ms
--verbose         详细日志
--json            JSON 格式输出

网络代理与 mock

抓包优先使用 wxpilot start  --proxy [--https]，由 start 在同一会话内确保代理已启动。

HTTP 模式

wxpilot start  --proxy
wxpilot connect
wxpilot net clear
wxpilot goto /pages/xxx/index
sleep 3
wxpilot net log --filter api.example.com

HTTPS MITM 模式（首次需安装证书）

首次配置（仅需一次）
wxpilot net start --https       # 生成 CA 证书
wxpilot net install-ca          # 安装到系统钥匙串
完全退出并重启微信开发者工具（必须重启）
开发者工具：设置 → 代理 → 手动 → 127.0.0.1:8899

每次抓包
wxpilot start  --proxy --https
wxpilot connect
wxpilot net log --filter api.example.com --with-body

mock

wxpilot net mock https://api.example.com/order ./mock-order.json

mock-order.json 格式：

{
"status": 200,
"body": { "code": 0, "data": { "items": [] } }
}

注意事项

- 开发者工具设代理后，工具自身的内部请求也走代理；代理未运行时页面可能报 TypeError: Failed to fetch
- net install-ca 安装后必须完全重启开发者工具才生效
- HTTP 模式下 HTTPS 请求透明隧道放行（不记录）；要记录 HTTPS 流量必须用 --https
- 端口回退：默认 9420，若 connect 成功但 status 异常，执行 wxpilot daemon stop 后用 --auto-port 9421 重启，依次尝试 9422/9423

低 token 输出设计

各命令默认输出均针对 AI 上下文消耗优化：

| 命令 | 默认行为 | 完整输出 |
|------|----------|----------|
| view | 紧凑交互摘要（compact, depth=5, limit=50） | --full |
| find | 匹配元素最小摘要（仅交互节点，limit=10） | --all |
| state | 顶层 key 摘要（类型+大小） | --full 或指定 path |
| shot | 保存文件，返回路径 | --base64 |
| net log | 摘要字段，limit=20，无 body | --with-body |

所有命令输出统一截断至 4000 字符，超限时附加 [truncated, originalLength=X]。

架构

| 模块 | 职责 |
|------|------|
| wxp-cli | 参数解析、daemon 探测/拉起、RPC 调用、输出格式化 |
| wxp-daemon | JSON-RPC server、运行时状态、automator、代理与存储 |
| wxp-rpc + wxp-common | RPC 协议与共享常量 |
| wxp-snapshot + wxp-ref-store | WXML → 元素树、交互节点检测、%N 引用存储 |
| wxp-proxy + wxp-store | HTTP/HTTPS 代理、网络日志存储 |

默认 runtime 文件：

- ~/.wxpilot/rust-daemon.sock — daemon 通信 socket
- ~/.wxpilot/rust-daemon.pid — daemon PID 锁（保证单实例）

开发

构建
cd rust && cargo build --workspace

测试
make rust-test                     # 等价于 cd rust && cargo test --workspace

本地打包安装闭环（macOS arm64 / x86_64）
make local-build                   # 产物在 dist/local//
make local-install                 # 安装到 ~/.local/bin 与 ~/.wxpilot/bin
make local-install-all             # 构建 + 安装一条龙

发布打包（生成 GitHub Releases 归档）
make public-release-package VERSION=v0.1.0
→ dist/public-release/v0.1.0/wxpilot-darwin-{arm64,x64}.tar.gz + checksums

将 dist/public-release// 下的三个文件（两个 tar.gz + wxpilot-checksums.txt）上传到 GitHub Releases，用户即可通过一键安装脚本获取。

AI Agent 集成

仓库内置 skills/wxpilot/SKILL.md，是一份面向 AI Agent 的完整使用指南，包含：

- 项目路径检测的 Agent 决策逻辑
- 典型 Agent 工作流（启动 → 查找 → 交互 → 断言 → 截图）
- JSON 模式输出格式
- 端口回退排障策略
- 低 token 使用准则

接入 Agent 时可直接引用该文件作为技能说明。

新的 Agent 集成建议优先采用 Skill + CLI：Skill 提供完整工作流说明，CLI 作为稳定的执行接口。该方式集成面最小，并且可以直接使用 CLI 的全部能力。

MCP 集成

对于已经通过 MCP 管理工具的宿主，wxpilot 同时提供可选的 MCP 集成层。

在仓库根目录构建 MCP 适配器：

pnpm install
pnpm --filter @wxpilot/mcp build

MCP 客户端配置示例：

{
"mcpServers": {
"wxpilot": {
"command": "node",
"args": [
"/absolute/path/to/wxpilot/packages/mcp/dist/index.js"
],
"env": {
"WXPILOT_BIN": "/absolute/path/to/wxpilot/rust/target/debug/wxpilot",
"WXPILOT_CWD": "/absolute/path/to/miniprogram"
}
}
}
}

适配器只暴露一个工具 wxpilot_execute，支持现有的连接、导航、交互、状态、截图、JavaScript、wx API 和网络操作。start 必须显式传入 projectPath；daemon stop 和 daemon restart 不通过 MCP 暴露。完整配置与开发说明见 packages/mcp/README.md 和 packages/mcp/README.zh-CN.md。

dsh 集成

面向 DeepSeek Harness（dsh）提供原生组合包（bundle）插件，把 wxpilot 暴露为一个面向模型的 wxpilot 工具：经 ctx.subprocess seam 直接调用 Rust CLI，带强类型 schema、规范 JSON 结果与 terminal 卡片。

pnpm dsh:build
dsh plugin --profile demo add ./packages/dsh

插件与 MCP 适配器通过 @wxpilot/shared 共享 argv 白名单；run/wx 等执行 JS 的操作默认不暴露，需配置 enableJsEval: true 开启。加载方式、配置项与开发说明见 packages/dsh/README.md 和 packages/dsh/README.zh-CN.md。

贡献

欢迎提交 Issue 和 Pull Request。

- 主实现语言为 Rust，默认修改 rust/crates/wxp-cli 与 rust/crates/wxp-daemon
- 提交前请确保 make rust-test 通过
- 仓库未配置 CI，请本地运行测试后再提交

许可证

本项目基于 GNU Affero General Public License v3.0 或更高版本（AGPL-3.0-or-later）© wuliLiuyue 开源。

- ✅ 个人学习、研究、内部使用、修改、再分发均可（须保留版权声明并同样以 AGPL-3.0-or-later 开源）。
- ✅ 商业使用亦被允许，但衍生作品与通过网络提供的服务必须以 AGPL-3.0-or-later 公开源码（即「传染式开源」）。
- ❌ 不得将本项目或其衍生作品以闭源/专有形式分发或作为闭源服务对外提供。
- 💼 如需将本项目嵌入闭源/专有商业产品或服务，请另行联系作者获取商业授权。

相关第三方依赖（如 tokio、clap 等）仍遵循其各自的 MIT/Apache-2.0 等许可证。