wechat-devtools

name wechat-devtools version 0.9.18 description 微信开发者工具 MCP —— 小程序构建、预览、调试与自动化测试 Wechat DevTools MCP Skill (v0.9.18) 前置条件 Step 0：安装与配置 pip install uv uv tool install wechat-devtools-mcp --force { "mcpServers" : { "wechat-devtools-mcp" : { "command" : "uvx" , "args" : [ "wechat-devtools-mcp" ] , "env" : { "WECHAT_DEVTOOLS_CLI" : "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat" , "WECHAT_PROJECT_PATH" : "D:\\Your\\Project\\Path" } } } } 注册名用 wechat-devtools-mcp （开发者工具 2.x 把自家 MCP bridge 注册成 wechat-devtools ，同名会被覆盖）。macOS CLI 路径 /Applications/wechatwebdevtools.app/Contents/MacOS/cli 。各编辑器配置见 README 。 必须开启服务端口 ： 设置 → 安全设置 → 服务端口 。未开启则所有 CLI 操作报 CLI_TIMEOUT 。 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 版本一致 mcp_version == 本文件 version 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 个原子工具）。 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 。 连接断开先 start → page_data ，不要直接走完整恢复。 API 速查表 完整参数与返回字段见 tool_reference.md 。 wechat_ide action 功能 关键参数 / 返回 open 启动 IDE 并打开项目。 cdp_enabled=true （默认）会 kill 已运行的 IDE、带 CDP 端口重启，等小程序 target 就绪后做启动健康检查 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 无 status 环境诊断 service_port_enabled 、 ide_port 、 official_mcp 、 mcp_version wechat_build action 功能 关键参数 / 返回 compile 编译并捕获 Error/Warning，成功后自动重连 automator（仅默认 9420） cdp_port ；返回 errors 、 warnings 、 wxml_errors 、 npm_warning 、 automator_verified 、 fatal_errors 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 轮） 返回 verified ； false 时按 retry_after_ms 重试 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 返回值（当前会话有效） 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 （疑似参数名错）。 前提： 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 。 SOP 标准操作流程 SOP A：初始化 wechat_ide(action='status') # 环境诊断 wechat_ide(action='is_login') # 未登录 → login(qr_format='terminal') wechat_ide(action='open', cdp_enabled=True) # 9222 被占用时加 cdp_port=9223 ↳ success=false + startup_errors → 先修复再继续 wechat_automator(action='start') # verified=false → 按 retry_after_ms 重试，期间可先 compile wechat_build(action='compile') # 建立干净基线，自动重连 automator wechat_automator(action='page_data') # 验证连接；AppID undefined → project_path 指到子目录了 project_path 必须是含 project.config.json 的根目录，云开发项目的 miniprogram/ 是子目录。 SOP A-2：改代码后 wechat_build(action='compile') → wechat_automator(action='page_data') 不需要重新 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 调试 wechat_file(action='list_pages') # 拿有效路径 wechat_navigate(page_path='pages/x/index', wait_ms=3000) # 跳转 + CDP 日志 wechat_automator(action='page_data') # path 必须等于目标页 ↳ 数据异常 → set_data 热更新验证；元素问题 → element_info；需要看图才 screenshot SOP C：异常排查（报错 / 白屏 / JS 异常） wechat_automator(action='page_data') # ① 关键字段 null → 数据没加载 wechat_automator(action='evaluate', fn_source='function(){ return wx.cloud.callFunction({name:"x",data:{}}) }') # ② 直接调 API 拿完整返回，[object Object] 时必用 wechat_inspector(action='cdp', duration=5) # ③ 能回放刚才的错误 wechat_build(action='compile') # ④ 看 errors / wxml_errors SOP D：全页面巡检 wechat_build(action='compile') wechat_file(action='list_pages') # 逐页顺序执行（禁止并行）： wechat_navigate(page_path=page, wait_ms=3000) wechat_automator(action='page_data', expected_path=page) # path 不匹配 → 标记重定向；字段空 → evaluate 诊断 # 汇总：按 page_data 结果输出报告；只在异常页补截图 SOP E：Mock 集成测试（支付 / 权限 / 网络 / 适配） mock_wx(method='requestPayment', result_json='{"errMsg":"requestPayment:ok"}') mock_wx(method='getLocation', result_json='{"latitude":23.1,"longitude":113.3}') mock_wx(method='request', result_json='{"errMsg":"request:fail timeout"}') # 模拟超时 mock_wx(method='getSystemInfo', result_json='{"theme":"dark","windowWidth":1024}') # 暗色 / 宽屏适配 tap(selector='.pay-btn') → page_data # 触发并验证