wuliLiuyue wxpilot — AI Agent 使用指南
wxpilot 是面向 AI Agent 的微信小程序自动化 CLI 工具，通过 Unix Domain Socket 与后台 Daemon 通信，Daemon 控制微信开发者工具（需已安装并运行）。
前置步骤
微信开发者工具需已安装并启动。
项目路径检测（AI Agent 执行前先判断）：
- 用户明确提供了项目路径 → 直接使用
- 当前工作目录下存在
dist/project.config.json→ 省略路径参数，CLI 自动检测 - 存在多个候选
dist目录 → CLI 交互提示选择，无需在对话中询问用户 - 均无 → 询问用户提供路径
快速开始
# 第一步：启动自动化（daemon 运行 cli auto，等待就绪）
wxpilot start # 自动检测 dist/project.config.json
wxpilot start /path/to/miniprogram # 明确指定路径
wxpilot start /path/to/miniprogram --appid wx你的AppID # appid 为占位符时
wxpilot start /path/to/miniprogram --proxy # 抓包会话：先自动启动 127.0.0.1:8899 代理
# 第二步：连接（可单独重试，无需重新 start）
wxpilot connect
# 查看当前页面，获取 %N 引用
wxpilot view
# 低 token 查找元素，直接返回匹配到的 %N
wxpilot find 提交
# 交互
wxpilot tap %1
wxpilot type %2 "13800138000"
# 截图
wxpilot shot /tmp/screen.png
Ref 机制（核心概念）
每次执行 wxpilot view 或 wxpilot find 后，页面中所有可交互元素都会被分配一个临时编号 %N。
- 编号在
view/find时重新生成（从 %1 开始） goto/back/reload后编号失效- 使用失效的编号会报错：
ERR: %N expired, run 'wxpilot view' to refresh - 导航后需重新执行
wxpilot view或wxpilot find以获取新编号
交互节点识别：基于双重信号检测——data-* 属性（outerWxml 快照保留，作为 bindtap 的代理）+ 源文件 WXML 的 tag+class 指纹（补全仅有 bindtap 无 data-* 的节点）。
命令参考
连接管理
wxpilot start # 自动检测 dist/project.config.json
wxpilot start <projectPath> # 启动自动化（运行 cli auto，等待就绪）
wxpilot start <projectPath> --appid wx你的AppID # appid 为占位符时指定
wxpilot start <projectPath> --cli-path <path> # 指定开发者工具 CLI 路径
wxpilot start <projectPath> --auto-port 9421 # 指定自动化端口（默认 9420）
wxpilot start <projectPath> --proxy # 抓包会话：自动先启动 127.0.0.1:8899 代理
wxpilot start <projectPath> --proxy --https # HTTPS MITM 抓包（需先安装 CA）
wxpilot connect # 连接（使用 start 记录的端点）
wxpilot connect --ws ws://127.0.0.1:9420 # 直接指定 ws 端点（跳过 start）
wxpilot disconnect # 断开连接
wxpilot status # 查看连接状态及代理状态
导航
wxpilot goto <route> # 跳转页面，如 /pages/order/index
wxpilot back # 返回上一页
wxpilot reload # 重载当前页面
视图（必须先执行才能获取 %N）
wxpilot view # 默认：紧凑交互摘要（compact=true, depth=5, limit=50）
wxpilot view --full # 完整树，含非交互节点（depth=20）
wxpilot view --depth <n> # 覆盖展开深度
wxpilot view --limit <n> # 覆盖交互节点数量上限（默认 50）
wxpilot find <query> # 查找 text/class/placeholder/tag，默认只查交互节点
wxpilot find <query> --all # 包含非交互节点
wxpilot find <query> --limit <n> # 覆盖匹配返回上限（默认 10）
wxpilot wait %N [--timeout 5000] # 等待元素出现
交互
wxpilot tap %N # 点击
wxpilot type %N <text> # 输入文本
wxpilot scroll %N <up|down> # 滚动
读取
wxpilot read %N # 读取元素文本
wxpilot assert %N <expected> # 断言文本（不匹配则退出码 1）
wxpilot state # 默认：返回顶层 key 摘要（类型+大小）
wxpilot state [path] # 返回指定子路径数据，如 "cart.items"
wxpilot state --full # 返回完整页面 data（数据量大，按需使用）
wxpilot shot [path] # 截图，保存到文件并返回路径
wxpilot shot [path] --base64 # 截图并附带 base64（token 消耗大，按需使用）
网络代理
# 推荐：抓包时优先使用 wxpilot start <projectPath> --proxy [--https]
# 仅在需要单独管理代理生命周期时，再直接使用 net.start / net.stop
wxpilot net start [--port 8899] [--https] # 单独启动代理（HTTPS 模式可解密 HTTPS 流量）
wxpilot net stop # 停止代理
wxpilot net log [--filter <url>] [--limit 20] # 查看请求摘要（默认不含 body）
wxpilot net log [--filter <url>] --with-body # 含请求/响应体（截断至 2000 字符）
wxpilot net mock <url> <jsonFile> # 添加 mock（jsonFile 包含响应 JSON）
wxpilot net unmock <url> # 移除 mock
wxpilot net clear # 清空日志
wxpilot net install-ca # 安装 CA 证书到系统钥匙串（HTTPS 模式首次使用）
mock 文件格式（jsonFile）：
{
"status": 200,
"body": { "code": 0, "data": { "items": [] } }
}
执行
wxpilot run <js> # 在页面上下文执行 JS，返回结果
wxpilot wx <method> [args...] # 调用 wx API，args 为 JSON 字符串
Daemon 管理
wxpilot daemon stop # 停止 daemon
wxpilot daemon restart # 重启 daemon
全局选项
--timeout <ms> 默认 10000ms
--verbose 打印调试信息
--json 所有输出改为 JSON 格式（适合程序解析）
JSON 模式输出格式
成功：
{"ok": true, "action": "tap", "ref": 1}
失败：
{"ok": false, "error": "ref_expired", "ref": 3}
{"ok": false, "error": "not_connected"}
{"ok": false, "error": "timeout after 10000ms"}
典型 Agent 工作流
# 1. 启动并连接
wxpilot start /path/to/project
wxpilot connect
# 2. 检查当前状态（顶层 key 摘要，低 token）
wxpilot status
wxpilot state
# 3. 跳转到目标页面，优先用低 token 查找获取目标 %N
wxpilot goto /pages/order/index
wxpilot find 提交 # 优先按 text/class/placeholder/tag 查找
# 若需要完整上下文，再退回 wxpilot view
# 4. 执行操作
wxpilot type %2 "13800138000"
wxpilot tap %1
# 5. 等待页面变化后重新获取引用
wxpilot find 提交成功
# 6. 断言结果 / 读取特定字段
wxpilot assert %5 "提交成功"
wxpilot state cart.total # 只读取需要的子字段
# 7. 截图留档（默认返回文件路径，不输出 base64）
wxpilot shot /tmp/result.png
低 token 原则：
- 优先用
find <query>替代通读view - 优先用
state <path>替代state --full shot默认只返回路径；仅在需要视觉分析时加--base64net log默认只返回摘要；仅排障时加--with-bodyview默认已紧凑；仅结构排查时加--full
代理抓包工作流
HTTP 模式（仅抓 HTTP，HTTPS 透明放行不记录）
# → 开发者工具：设置 → 代理 → 手动设置代理 → 127.0.0.1:8899
wxpilot start <projectPath> --proxy # 推荐：由 start 统一确保代理已启动
wxpilot connect
wxpilot net clear
wxpilot goto /pages/xxx/index
sleep 3 # 等待页面接口请求完成
wxpilot net log --filter api.example.com
HTTPS MITM 模式（解密 HTTPS 流量，首次需安装证书）
# ── 首次配置（仅需一次）──
wxpilot net start --https # 生成 CA 证书并启动 MITM 代理
wxpilot net install-ca # 一键安装 CA 证书到系统钥匙串
# → 完全退出并重启微信开发者工具（必须重启，进程级证书缓存）
# → 开发者工具：设置 → 代理 → 手动设置代理 → 127.0.0.1:8899
# ── 每次抓包 ──
wxpilot start <projectPath> --proxy --https
wxpilot connect
wxpilot net clear
wxpilot goto /pages/xxx/index
sleep 3
wxpilot net log --filter api.example.com
关键注意事项
- 开发者工具设置代理后，工具自身的内部请求也走代理；若代理未运行，页面可能直接报
TypeError: Failed to fetch - 抓包场景优先使用
wxpilot start <projectPath> --proxy，不要把“自动兜底重试”当主流程 net install-ca安装后必须完全重启开发者工具才生效- HTTP 模式下 HTTPS 请求透明隧道放行（不记录）；要记录 HTTPS 流量必须用
--https模式
注意事项
- 微信开发者工具需已安装并启动，
wxpilot start [projectPath]会执行cli auto并等待就绪，之后再执行wxpilot connect；省略路径时自动扫描 CWD 下含project.config.json的dist目录 - Daemon 会在首次 CLI 调用时自动后台启动，30 分钟无操作自动退出
- HTTPS 代理首次使用需运行
wxpilot net install-ca安装 CA 证书并重启开发者工具 wxpilot run中的 JS 在小程序页面 VM 中执行，不能访问 Node.js API- 所有命令输出统一截断至 4000 字符，超限时附加
[truncated, originalLength=X]提示；需完整数据时使用对应的--full参数
默认端口回退策略：
- 默认先使用
9420 - 如果出现
connect成功但status为connected=false、projectPath=null、view超时、或run报Connection closed，不要继续重试当前会话 - 立即执行
wxpilot daemon stop清理当前 daemon，再用新的端口重启，例如--auto-port 9421 - 若
9421仍异常，按序尝试9422、9423 - 切换端口后必须显式执行
wxpilot connect --ws ws://127.0.0.1:<新端口>，再用status或run '1+1'做最小连通性确认 - 只有在最小连通性确认通过后，再继续
view、find、tap等操作
禁止行为（避免 token 浪费）：
- 明明能用
find定位时，先跑整页view - 不默认用
shot输出 base64 - 不默认用
state全量输出 - 不默认用
net log附带 body - 不连续多次执行
view --full