wechat-devtools
微信开发者工具 MCP —— 小程序构建、预览、调试与自动化测试
By watertian · 408 installs
npx skills add watertian/wechat-devtools-mcp --skill wechat-devtools
Source repository · Upstream listing
Wechat DevTools MCP Skill (v0.9.20)
前置条件
Step 0：安装与配置
注册名用 wechat devtools mcp （开发者工具 2.x 把自家 MCP bridge 注册成 wechat devtools ，同名会被覆盖）。macOS CLI 路径 /Applications/wechatwebdevtools.app/Contents/MacOS/cli 。各编辑器配置见 [README](https://github.com/WaterTian/wechat devtools mcp step 4 编辑器配置)。
必须开启服务端口 ： 设置 → 安全设置 → 服务端口 。未开启则所有 CLI 操作报 CLI TIMEOUT 。
9222 常被 Chrome 占用的机器在 env 加 "WECHAT CDP PORT": "9333" ；Node.js 须 ≥ 18。
Step 1：运行时环境检查
先调 wechat ide(action='status') 一次确认全部前置条件：
检查项 字段 失败时
CLI 已安装 cli exists: true 配置 WECHAT DEVTOOLS CLI
服务端口已开启 service port enabled: true false 必然 CLI TIMEOUT ，去设置里打开； null 是读不到，不等于关闭
项目路径有效 project exists: true 配置 WECHAT PROJECT PATH ，须指向含 project.config.json 的根目录
Node.js 可用 node available: true 安装 Node.js ≥ 18
CDP 端口没被别人占 cdp port occupant.kind 为 none / ide foreign （常见是 Chrome）→ open(cdp port=9333) 或设 WECHAT CDP PORT
项目窗口活着 project window open: true （IDE 带 CDP 跑着时才有值，否则 null ） false → start 会顺手重开窗口
版本一致 skill version == mcp version （status 自动读项目内 skill 副本，不一致 message 会提示） uv tool upgrade wechat devtools mcp 或同步 skill 副本
已登录 is login → logged in: true login(qr format='terminal') 扫码
官方内建 MCP official mcp.available 见下方分流规则
环境分流规则（IDE 2.x 内建 MCP）
开发者工具 2.x（2026 08 18 起为官方 Stable）在 http://127.0.0.1:<ide port /mcp 内建 MCP Server（47 个原子工具，2 个已废弃）。 official mcp.available: true 且官方 MCP 已接入当前 agent 时：
操作 交给谁
开关项目、登录、编译、预览、上传、build npm、点击/输入/滚动、云开发 官方工具优先，同一操作不要两边各做一遍
长图拼接截图 本 skill。官方 simulator screenshot 只截视口且压到长边 1280 JPEG
CDP 结构化日志（ inspector cdp / navigate ） 本 skill。能回放采集前的历史消息并过滤噪音
SOP C / D / I / J 任务级流程 本 skill 编排，基础步骤可调官方工具
available: false （1.06、IDE 未启动、端口漂移）或官方 MCP 未接入时，本 skill 承接全部能力，不要让用户为基础操作去装官方 MCP。
效率原则
IDE 只在会话开始 open 一次；改了代码只需 compile → page data （自动重连 automator），不要重新 open。
没改代码换页面用 evaluate(fn source="function(){ wx.reLaunch({url:'/pages/x/index'}); return 'ok' }") → page data 。
连接断开时 automator 动作 / navigate / screenshot 会自动 start 一次并重试（返回 auto recovered ；有副作用的 tap / input / call method 只在连接阶段失败时重试）。仍失败再手动 start → page data ，不要直接走完整恢复。
API 速查表
完整参数与返回字段见 [tool reference.md](references/tool reference.md)。
wechat ide
action 功能 关键参数 / 返回
open 启动 IDE 并打开项目。 cdp enabled=true （默认）先检查 cdp port 上是谁：被别的浏览器占着直接报错不杀 IDE；否则 kill 已运行的 IDE、带 CDP 端口重启，等小程序 target 就绪后做启动健康检查 cdp port （默认 WECHAT CDP PORT 或 9222；成功后同会话 inspector/navigate/compile 不传即沿用）；返回 ide runtime 、 cdp ready 、 project opened ；有 error 时 success:false + startup errors
login / is login 扫码登录 / 查登录态 qr format ； logged in
close / quit 关项目窗口 / 退出 IDE（等进程真正消失，上限 10s） quit 返回 exited
status 环境诊断 service port enabled 、 ide port 、 official mcp 、 mcp version 、 skill version （项目内副本，不一致给 hint）、 cdp port / cdp port occupant （端口上是 IDE 还是别的浏览器）、 project window open
wechat build
action 功能 关键参数 / 返回
compile 编译并捕获 Error/Warning，成功后自动重连 automator（仅默认 9420） cdp port ；返回 errors 、 warnings 、 wxml errors 、 npm warning 、 automator verified 、 fatal errors 、 cdp skipped （CDP 端口被别的浏览器占着，未采 WXML 运行时错误）
preview 生成预览二维码 qr format 、 qr output （相对路径相对项目根）；返回 qr stale warning 表示 bundle 可能没刷新
upload 上传到微信后台，生产操作 version 必填， desc
build npm 构建 npm。新增/更新依赖后必做，否则运行时报 module ... is not defined 无
cache clean 清缓存 clean type （默认 compile ； all 慎用）
compile condition 对 tabBar 页可能被 app 路由守卫覆盖，跳转用 evaluate 更可靠。
wechat automator
先调 start 开启自动化端口，整个会话一次。
action 功能 必填 / 返回
start 开自动化端口，CLI + TCP + WS 三重验证；窗口未加载完时自动重跑 cli auto （最多 3 轮）；WS 级最多等 45s（ ready timeout 可调，真机约 7~11s 才首次应答） 返回 verified 、 ready after ms ； false 时先再 start 一次，不要先 open
tap / input 点击 / 输入 selector （ input 另需 value ）
element info 元素 tagName/text/wxml/size/offset ， style prop 时带 style selector
set data 热更新页面 data，无需重编译 data json ；返回 updated keys
call method 调页面方法 method 、 args json? ；返回 return value 、 path
call wx / mock wx 调 wx API / Mock 返回值（当前会话有效）。同步返回的 API（ Sync 、 getWindowInfo 等）自动经 evaluate 直调，返回 sync: true method （mock 另需 result json ）
evaluate 逻辑层执行 JS fn source （推荐）或 expression ；返回 result 、 mode
page stack 页面栈 返回 depth 、 pages
page data 当前页 data expected path? 会轮询等页面匹配；返回 path 、 data 、 path mismatch
system info / storage 系统信息 / 本地缓存 storage 传 key 取值，不传列 keys
evaluate 用法：
fn source 传完整函数源码（ function(){...} 或箭头函数），入参放 args json （JSON 数组）。多语句、声明、 return 都由函数体决定， mode: "function" 。
expression 只传单个表达式。多语句会退回语句模式（全部执行， mode: "statement" ），没有 return 时结果为 null 并附 hint 。
例： fn source="function(){ const p=getCurrentPages(); return p[p.length 1].route }" 。
wechat inspector
action 功能 关键参数
cdp CDP 采集 WXML 警告、渲染层报错、Runtime 错误。 能回放采集前的历史消息 duration=10 、 detail level 、 max logs 、 cdp port
console automator 事件采集 console 与 JS 异常。只收连接后的事件 duration （排查异常 ≥8s）、 log type 、 tap selector
排查「刚才报的错」用 cdp ；要与交互严格对齐时间线才用 console 。
wechat screenshot
full page （默认 true）长图拼接， false 只截视口，可配 scroll top ； page path 不匹配时自动跳转； output path 留空存到项目 screenshots/ 。
只在用户要求或需要视觉确认时截图；fixed/absolute 弹窗蒙层可能拍不到，以 page data 为准。
先看 message 有无 ⚠。以下情况图看着连续但不完整：
返回字段 含义 应对
is scroll view page: true 页面靠 scroll view 滚动，只截到视口 用 evaluate 读数据代替视觉确认
truncated: true 超分段上限，底部没拍到 full page=false + scroll top 分段截
content gaps: N 固定头尾吃光重叠，N 处内容丢失 调大 overlap （如 150）重试
detection confident: false 固定头尾识别不可靠 结果仅供参考
fixed header / fixed footer 是识别到的固定区高度（物理像素）。
wechat navigate
page path 必填，可带 query；tabBar 页自动走 switchTab ，其余 reLaunch （返回 navigation method ）。
wait ms 默认 2000，含网络请求的页面建议 3000。 clear logs=true 过滤跳转前的历史 CDP 日志。
返回 current page 、 cdp logs 、 navigation mismatch ；带 query 且 check data=true 时数据大面积为空会给 warning （疑似参数名错）；CDP 端口被别的浏览器占着时照常跳转但 cdp available: false 并附 cdp warning ；失联自动恢复后附 auto recovered 。
前提： start 已调用且项目以 cdp enabled=true 打开。reLaunch 进入的页面云函数调用可能丢上下文，非 tabBar 页优先 evaluate + wx.navigateTo 。
wechat file
action 功能 必填 / 返回
project info project config 、 app config 、 directory 、 app.js / app.wxss 节选 无
list pages app.json 全部页面，含文件完整性 返回 pages[{path, complete, missing}] 、 total
read page 页面四件套源码 page path ；返回 files{文件名: 内容} 、 resolved base
read file 任意单文件，最多 800 行 file path ；返回 content 、 resolved path 、 truncated
路径口径统一：先按 miniprogramRoot 解析再回退项目根， list pages 的输出可直接喂给 read page 。
云函数与云数据库请用 [CloudBase MCP](https://github.com/TencentCloudBase/CloudBase AI ToolKit)。
SOP 标准操作流程
SOP A：初始化
project path 必须是含 project.config.json 的根目录，云开发项目的 miniprogram/ 是子目录。
SOP A 2：改代码后
不需要重新 open，也不需要 cache clean。
页面跳转
场景 方式
普通页 evaluate(fn source="function(){ wx.navigateTo({url:'/pages/x/x?id=1'}); return 'ok' }")
tabBar 页 wechat navigate(page path='pages/x/index')
强制重置 同上用 wx.reLaunch
跳转后 page data(expected path='pages/x/x') ，校验 path
SOP B：UI 调试
SOP C：异常排查（报错 / 白屏 / JS 异常）
SOP D：全页面巡检
SOP E：Mock 集成测试（支付 / 权限 / 网络 / 适配）
Mock 仅当前会话有效。拦截请求可用 fn source="function(){ var o=wx.request; wx.request=function(p){ console.log(p.url); return o.apply(wx,arguments) }; return 'ok' }" 。
SOP G：带 query 参数的子页面
SOP I：跨页面数据一致性
SOP J：小程序 + 管理后台并行比对
管理后台走 Playwright MCP，小程序走本 MCP，两者端口不同可并行提取，比对在主进程串行做。automator 9420 独占，同一时刻只能有一个 agent 操作本 MCP。
CDP 日志策略
场景 参数
快速诊断 duration=5, detail level='concise', max logs=20
深度排查 duration=10, detail level='full', max logs=100
页面巡检 duration=3, detail level='concise', max logs=30
concise 只回 errors + warnings； summary.errors 0 再用 full 拿 source 定位，配合 read file 。
cdp 会回放采集前的缓冲区（12 秒前的错误也能拿到）， console 只收连接后的事件。
已自动过滤： [system] 、 WAService.js 、 WAWebview.js 、IDE 外壳页； open 的启动检查还过滤 devtools:// 与 ide:///extensions/ 。
需要自己排除： devtools:// 来源的 console.assert 、 SharedArrayBufferIssue 、 wx.saveFile 即将废弃 类框架预警。
ide:///extensions/inject/… 来源的 warning 不是噪音 ，是框架报的真实问题（无效 app.json 字段、API 废弃、WXSS 选择器不合法）。
计数可能被噪音抬高，最终以 page data 为准。
page data 必须校验 data.path 等于导航目标；不一致的常见原因：未登录被拦到登录页、云函数失败 fallback 首页、page path 拼错、onLoad 条件跳转。传 expected path 可轮询等待匹配， path mismatch: true 时用 page stack 看完整栈。
返回值与恢复
成功 {"success": true, "data": {...}, "message": "..."} ，失败 {"success": false, "error code": "...", "message": "...", "hint": "..."} 。
error code 只有 6 种： PARAM MISSING 、 CLI NOT FOUND 、 PROJECT PATH MISSING 、 NODE NOT FOUND 、 CLI TIMEOUT 、 UNKNOWN ERROR 。连接失败、跳转失败等都归 UNKNOWN ERROR ，看 message 与 hint 。
连接断开恢复分三级：
0. 自动：动作本身会 start 一次再重试，成功时 data.auto recovered 带 ready after ms 。
1. 快速： start → page data 。
2. 完整： open(cdp enabled=True) → start → compile → page data 。
故障速查
症状 原因 解决
CLI TIMEOUT 服务端口未开 / IDE 未运行 status 看 service port enabled ；开端口； open
open 返回 startup errors 小程序启动阶段有致命错误 先修代码再 open
start 返回 verified=false （端口在听、小程序未应答） IDE 仍在编译/加载项目；或项目窗口刚被其它会话的 cli close 关掉又重开（SessionEnd 钩子、常驻 bot 等） 直接再 start （可加大 ready timeout ）；连续 3 次失败才 open(cdp enabled=True) 。 open 会杀 IDE、冷启动更慢，别把它当第一反应
CLI auto 连续 3 次返回成功但端口未监听 项目窗口没加载完或已关闭（ cli auto 会假成功；纯 CLI open 后约需 15s） 稍等再 start ；仍失败 open(cdp enabled=True) 重启后再 start
动作仍返回 Failed connecting to ws://localhost:9420 / Connection closed 项目窗口被关（其它会话 cli close 、手动关窗）或 automator 闲置后不应答；动作已自动 start 一次仍没救回 看 status 的 project window open ；手动 start （ cli auto 会重开窗口）→ page data ；再失败才 open(cdp enabled=True)
CDP 采集失败 / 采到的全是别的东西 未以 cdp enabled 打开，或 9222 被 Chrome 占用（ status 的 cdp port occupant.kind 为 foreign 即是） open(cdp port=9333) ，之后 inspector / navigate / compile 不传 cdp port 自动沿用；长期设 WECHAT CDP PORT
Using AppID: undefined / appid missing project path 指向子目录 / 未登录 改为含 project.config.json 的根目录； is login
navigate 后 page data.path 与目标不一致 page path 拼错、被重定向（未登录 / 参数错 / 云函数失败）、switchTab 未完成 list pages 核对；查登录态与 onLoad 逻辑；增大 wait ms
evaluate 返回 null 且 mode: "statement" expression 走了语句模式没 return 改用 fn source 并显式 return
元素未找到 / Element is obfuscated 不在当前页、selector 错、被遮挡 page stack 确认页面； element info 验证；换父节点
scroll view 页长图只有一屏 automator 无法捕获 scroll view 内部滚动 返回 is scroll view page: true ，改用 evaluate 读数据
长图看着连续但少一截 固定头尾吃光重叠 看 content gaps ，增大 overlap
截图看不到弹窗 / 拍到错误页面 overlay 不在同一渲染层 / 截图前页面被重置 以 page data 为准；传 page path
compile 成功但 IDE 显示红色 WXML 错误 WXML 错误走 IDE 内部通道 看 wxml errors ；检查中文引号、未闭合标签
运行时报 @babel/runtime/helpers/xxx is not defined npm 依赖更新后未 build npm build npm → compile ， console(duration≥8, log type='exception') 验证
工具行为异常 / 参数对不上（IDE 2.x） 注册名撞车：官方 bridge 也叫 wechat devtools 注册名改 wechat devtools mcp ； status 的 mcp version 可确认调到谁
Windows 上 open 后项目没打开 / CDP 连不上（IDE 2.x） 旧版 Windows 分支没有 1.x/2.x 判定 升级到最新版；仍失败附 ide runtime 反馈
ide:///extensions/inject/… 的 warning 框架报的真实应用问题 当真实告警处理，不要过滤
绝对红线
❌ open 返回 startup errors 后继续测试
❌ 未确认 logged in: true 就 preview / upload
❌ 对生产项目 cache clean(clean type='all')
❌ 脑补运行状态；同一失败操作重试超过 3 次（应转为诊断根因）
❌ 硬 sleep 等待，用 wait ms 或 page data(expected path) 轮询
❌ start 返回 verified=false 就立刻 open 重启 IDE（先重试 start ）
❌ SOP 里主动截图，只在用户要求或需要视觉确认时截
❌ 没改代码就 compile
❌ navigate 后不校验 page data.path
❌ 多个 agent 并行使用 wechat automator （9420 独占）
❌ 用 miniprogram/ 子目录作 project path；WXML 属性值里用中文引号（工具无法检测）
✅ 自动化 / 截图前先 start ； tap / input 前先 element info 确认元素
✅ upload 前确认版本号递增、 build npm 已执行
✅ compile 后用 page data 确认 automator 连接