zkr/shz-backend

Fork 0

Files

lapuda 6bc4d64c6b ✨ feat: 添加微信小程序调试工具和完整参数参考文档

2026-07-24 09:09:15 +08:00

26 KiB

Raw Blame History

name, description

name	description
wechat-devtools	Use the WeChat DevTools MCP and simulator to build, reproduce, inspect, verify, or capture screenshots from this uni-app Vue 3 mini-program. Trigger for WeChat mini-program UI, runtime, API, navigation, WXML, interaction, screenshot, automator, CDP, or connection debugging in /Users/lapuda/code/shz-employment-service, especially when verification must use the real simulator. Do not upload code or submit real business actions.

name

description

wechat-devtools

Use the WeChat DevTools MCP and simulator to build, reproduce, inspect, verify, or capture screenshots from this uni-app Vue 3 mini-program. Trigger for WeChat mini-program UI, runtime, API, navigation, WXML, interaction, screenshot, automator, CDP, or connection debugging in /Users/lapuda/code/shz-employment-service, especially when verification must use the real simulator. Do not upload code or submit real business actions.

微信小程序调试

使用微信开发者工具模拟器完成可复现、可观察、可回归的本地调试。优先使用 MCP 的运行态证据（页面路径、页面数据、元素信息和截图），再决定是否修改源码。

本项目必须遵守的约定

项目根目录：/Users/lapuda/code/shz-employment-service。
项目类型：HBuilderX 管理的 uni-app Vue 3 项目。
.vue、pages.json、manifest.json 等是 uni-app 源码，不能直接作为微信开发者工具小程序根目录；微信工具必须打开包含 app.json 和 project.config.json 的已构建目录。
当前机器最近一次验证的验收产物是 /Users/lapuda/code/shz-employment-service/dist/build/mp-weixin。不要固定假设产物永远在 unpackage/dist/build/mp-weixin；构建后应在候选目录中确认 app.json、project.config.json 和目标页面文件的更新时间。
unpackage/dist/build/mp-weixin 可能是旧产物。源码修改后必须先重新构建，再确认微信开发者工具打开的是新产物；不要因为旧产物中的页面没有变化就判断源码修改失败。
项目存在 .codegraph/ 时，理解或定位源码前先运行 codegraph explore "问题或符号"，再使用 rg 做精确搜索。
调用 MCP 时优先显式传入实际验收产物的 project_path，避免默认环境变量指向 uni-app 源码根目录或旧构建目录。

构建与模拟器启动顺序

源码修改后先使用 HBuilderX 内置的 uni CLI 生成验收产物。仓库可能没有 node_modules/.bin/uni；遇到 uni: command not found 后不要反复执行同一个 npm script：

PROJECT_ROOT=/Users/lapuda/code/shz-employment-service
HX_ROOT=/Applications/HBuilderX.app/Contents/HBuilderX
HX_UNI="$HX_ROOT/plugins/uniapp-cli-vite/node_modules/.bin/uni"

HX_APP_ROOT="$HX_ROOT" UNI_INPUT_DIR="$PROJECT_ROOT" \
  "$HX_UNI" build -p mp-weixin

构建成功后，选择实际存在且包含 app.json、project.config.json 的产物目录作为 MP_ROOT。当前机器通常使用：

MP_ROOT=/Users/lapuda/code/shz-employment-service/dist/build/mp-weixin
test -f "$MP_ROOT/app.json" && test -f "$MP_ROOT/project.config.json"

然后统一使用微信 CLI 打开 MP_ROOT，并使用固定端口：

/Applications/wechatwebdevtools.app/Contents/MacOS/cli open --project "$MP_ROOT" --port 60423 --debug
/Applications/wechatwebdevtools.app/Contents/MacOS/cli auto --project "$MP_ROOT" --port 60423 --auto-port 9420

端口含义：60423 是 IDE HTTP 服务，9420 是自动化 WebSocket，9222 是 cdp_enabled=true 时使用的 CDP 端口。三者不是同一个服务，不能互相替代。TCP ready 但 WS not ready 不代表模拟器可用；只有 wechat_automator(action="start") 返回 verified: true、tcp_ready: true、ws_ready: true，且 page_stack 或 page_data 能返回页面，才开始业务判断。

wechat_build(action="compile") 只编译微信开发者工具当前打开的微信小程序产物，不会把 uni-app 的 .vue 源码重新生成到 dist 或 unpackage。源码变更后的正确顺序是：HBuilderX CLI 构建 → 确认 MP_ROOT 和目标文件时间戳 → 微信工具打开/刷新该产物 → 必要时调用 compile → start → page_data。

wechat_ide(action="open", cdp_enabled=true) 适合需要 CDP 日志的场景；只做自动化交互时，标准 CLI 打开方式即可，CDP 不是 automator 的必要条件。若 App.getCurrentPage 无响应，先执行 preview 初始化运行时，再重新执行 auto 和 start。

截图快速通道与连接健康检查

截图依赖 9420 automator WebSocket，不依赖单独可用的 9222 CDP。截图任务遵循以下短路径，避免无故重编译或重复打开 IDE：

使用验收产物显式传参，例如 /Users/lapuda/code/shz-employment-service/dist/build/mp-weixin；先确认其中存在 app.json 和 project.config.json。
先调用 wechat_automator(action="start", project_path="...")。
只有返回 success: true、verified: true、tcp_ready: true、ws_ready: true 才能调用截图；再用 page_data(expected_path=...) 或 wechat_navigate 校验页面。
截图优先 full_page=false；页面路径明确时传 page_path，需要稳定取证时显式传 output_path。

如果 start 超时、返回 Connection closed 或截图报 daemon 超时，不要立刻重试截图。先用只读命令检查端口：

lsof -nP -iTCP:60423 -sTCP:LISTEN
lsof -nP -iTCP:9420 -sTCP:LISTEN
lsof -nP -iTCP:9222 -sTCP:LISTEN

按结果处理：

60423 和 9420 都存在：优先只重新调用一次 wechat_automator(start)；不要 open 或 compile。
缺少 9420：重新调用一次 wechat_automator(start)，确认 verified/ws_ready 后再截图。
缺少 60423：使用标准 CLI 恢复 IDE HTTP 服务，再启动 automator：
```
/Applications/wechatwebdevtools.app/Contents/MacOS/cli open --project "$MP_ROOT" --port 60423 --debug
```
然后重新调用 wechat_automator(start)。wechat_ide(open, cdp_enabled=true) 只保证尝试开启 9222，不能替代这一步。
只有 9222 存在、60423/9420 缺失：判定为 CDP-only 或半启动 IDE 状态。不要继续等截图 daemon；先关闭/退出该实例，再用上面的标准 CLI 方式启动。
CLI 报 IDE may already started ... wait IDE port timeout：判定为僵死或陈旧 IDE 状态。先调用 wechat_ide(action="quit")；若仍未退出，只能根据匹配当前项目的精确 PID 终止本地开发者工具进程，然后重新执行标准 CLI open。禁止使用无范围的 pkill 或重复尝试超过 3 次。
60423 和 9420 来自不同实例，或 MCP 默认项目路径与当前打开目录不一致：停止混用旧实例，正常退出本次验证启动的微信工具，使用同一个 MP_ROOT 重新执行 open 和 auto；不要用临时端口拼接多个自动化实例。

9222 仅在需要 wechat_inspector(action="cdp") 或 wechat_navigate 的 CDP 日志时检查。对截图来说，9420 ws_ready 是硬前提；不能用“9222 可访问”替代 automator 健康检查。MCP 截图失败时不得静默改用系统级截图，应先报告 MCP 连接状态或完成上述本地恢复。

调试与安全边界

只在本地微信开发者工具和模拟器中调试；不调用 wechat_build(action="upload")，不部署、不发布。
不填写或提交真实签到、报名、支付、登录授权等业务动作。可以点击打开表单或弹窗，但验证后使用取消按钮退出。
默认使用测试环境接口；不要修改数据库或调用真实提交接口。
页面验证优先按 page_data → element_info → 无写入交互 → 截图 → 日志的顺序取证。
使用 wechat_navigate 后必须校验返回的 path；使用 page_data 时传 expected_path。
截图仅在用户要求或需要视觉确认时调用，优先 full_page=false。
HBuilderX 发行可能临时修改 manifest.json 的 AppID；发行后检查 git diff -- manifest.json，若是工具引入的无关变化，恢复原值。

示例页面验证：

wechat_navigate(page_path="packageA/pages/outdoorFair/detail?jobFairId=10", wait_ms=3000)
wechat_automator(action="page_data", expected_path="packageA/pages/outdoorFair/detail")
wechat_automator(action="element_info", selector=".status-tag")
wechat_automator(action="element_info", selector=".checkin-btn")

可点击 .checkin-btn 验证弹窗出现，但不要点击 .submit-btn；验证后点击 .cancel-btn。完成后执行 git diff --check 和 git status --short，确认只留下预期源码改动。

前置条件

Step 0：安装与配置

pip install uv   # 如未安装 uv
uv tool install wechat-devtools-mcp --force  # 通过uv安装wechat-devtools-mcp

编辑器配置：

{
  "mcpServers": {
    "wechat-devtools": {
      "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"
      }
    }
  }
}

主流编辑器配置见 README.md

Important

必须手动开启开发者工具的服务端口：设置 → 安全设置 → 服务端口 → 开启。未开启将导致所有 CLI 操作报 CLI_TIMEOUT。

Step 1：运行时环境检查

首先调用 wechat_ide(action='status') 一次性确认所有前置条件。

检查项	偏好命令	失败时操作
CLI 已安装	`status` → `cli_exists: true`	安装工具并配置 `WECHAT_DEVTOOLS_CLI`
项目路径已配置	`status` → `project_exists: true`	配置 `WECHAT_PROJECT_PATH`
已登录	`is_login` → `logged_in: true`	`login(qr_format='terminal')` 扫码
Node.js 可用	`status` → `node_available: true`	安装 Node.js ≥ 8.0

Efficiency Principles

IDE 只在需要切换构建产物或恢复陈旧实例时 open；源码变更先构建 uni-app 产物，compile 只编译当前已打开的微信产物；页面跳转优先用 evaluate 而非重复 open。

场景	正确做法	错误做法
没改代码，换页面测试	`evaluate(expression="wx.reLaunch({url:'/pages/xxx/index'}); 'ok'")` → `page_data`	重新 open → compile
改了 uni-app 源码	HBuilderX CLI 构建 → 确认 `MP_ROOT`/时间戳 → `compile`（可选）→ `page_data`	只对旧产物执行 `compile`，然后误判源码未生效
连接断开	先快速恢复（仅 `start`）	直接走完整恢复

API 速查表

`wechat_ide` — IDE 生命周期

action	功能	关键参数
`open`	打开 IDE/项目（cdp_enabled 时自动做启动健康检查）	`cdp_enabled=true`（开启 CDP 9222 端口，自动采集 5s CDP 日志检测启动错误）
`login`	扫码登录	`qr_format="terminal"`
`is_login`	检查登录状态	—
`close` / `quit`	关闭项目 / 退出 IDE	—
`status`	环境诊断	—

`wechat_build` — 构建与发布

action	功能	关键参数
`compile`	编译检查（捕获错误/警告，成功后自动重连 automator）	—

注意：compile_condition 对 tabBar 页面可能无效（app 路由守卫覆盖），用 evaluate + wx.reLaunch 跳转更可靠

`wechat_automator` — 自动化交互

前提：先调用 start 开启并验证自动化端口；代码重新编译后按返回状态决定是否重新验证。

action	功能	必填参数
`start`	开启自动化端口	—
`tap`	点击元素	`selector`
`input`	输入文本	`selector`, `value`
`element_info`	获取元素详情（文本/尺寸/WXML）	`selector`
`set_data`	热更新页面 data（无需重编译）	`data_json`
`call_method`	调用页面方法	`method`, `args_json?`
`call_wx`	调用 wx API	`method`
`mock_wx`	Mock wx API 返回值	`method`, `result_json`
`evaluate`	执行 JS 表达式（逻辑层万能钥匙）	`expression`

注意：v0.7.0 起支持声明语句（const/let/var）
v0.9.2：compile 后自动 invalidate 旧缓存连接再重连，daemon 健康检查 3s 超时保护，navigate currentPage 轮询 2s 独立超时
v0.9.0：底层改为持久化 Node daemon（NDJSON 协议），WS 连接按端口缓存复用，工具调用延迟 ~3ms

`wechat_inspector` — 日志采集

action	功能	关键参数
`console`	采集 console 日志和 JS 异常	`duration=10`, `log_type="all"`
`cdp`	CDP 协议采集底层日志（WXML/渲染层）	`duration=10`, `detail_level="concise"`, `max_logs=50`

cdp 前提：以 cdp_enabled=true 打开项目，确保端口 9222 可用。

`wechat_screenshot` — 截图

output_path（可选）：截图保存路径。留空则自动保存到项目目录下 screenshots/ 文件夹
full_page（默认 true）：设为 false 只截当前视口
scroll_top（可选）：截图前滚动到的位置（逻辑像素），配合 full_page=false 使用
page_path（可选）：确保截图前在指定页面上，若当前页面不匹配则自动跳转
前提：先调用 wechat_automator(action='start')
注意：不要主动截图，仅在用户明确要求或排查异常需要视觉确认时才调用
限制：使用 scroll-view 组件滚动的页面无法长图拼接（automator SDK 限制），仅截取当前视口
限制：截图可能无法捕获 fixed/absolute overlay（弹窗、蒙层），以 page_data 为准
路径规约：推荐 <project>/screenshots/ 或显式绝对路径。避免写入 .claude/image-cache/ — 这是 Claude Code 的用户发图缓存目录，MCP 截图混入会互相污染

`wechat_navigate` — 跳转并采集日志

page_path（必填）：如 pages/index/index
wait_ms：等待毫秒，建议 3000
clear_logs：是否过滤历史 CDP 日志，默认 true
check_data：跳转后是否检查 page_data 空值，默认 true
detail_level：concise（仅 errors+warnings）或 full
v0.8.0 新增：自动检测 TabBar 页面并使用 switchTab 替代 reLaunch，返回 navigation_method 字段
前提：需 automator start；若要采集 CDP 日志，再以 cdp_enabled=true 打开项目并确保 9222 可用。

`wechat_file` — 文件读取

action	功能	必填参数
`project_info`	项目完整信息（app.json + 目录结构）	—
`list_pages`	所有页面列表（含文件完整性检查）	—
`read_page`	读取页面源码（wxml/wxss/js/json）	`page_path`
`read_file`	读取任意单文件（最多 800 行）	`file_path`

云函数与云数据库管理：本 MCP 自 v0.9.5 起不再提供 wechat_cloud 工具。请改用 CloudBase MCP（manageFunctions / readNoSqlDatabaseContent / writeNoSqlDatabaseContent 等），无 IDE 依赖且覆盖更完整。

CDP 日志策略

concise → 仅 errors + warnings（节省 Token，优先使用）
  ↓ summary.errors > 0 时
full    → 完整日志 + source 定位 → wechat_file(action='read_file', file_path=source)

场景	推荐参数
快速诊断	`duration=5, detail_level='concise', max_logs=20`
深度排查	`duration=10, detail_level='full', max_logs=100`
页面巡检	`duration=3, detail_level='concise', max_logs=30`

重要：CDP 错误计数可能包含跨页面累积的历史日志。v0.4.0 的 clear_logs=true（默认）会基于时间戳过滤历史日志，但仍建议以 page_data 作为最终验证标准。

CDP 日志噪音过滤

以下日志来源属于开发工具内部噪音，不代表应用错误，应在判断时排除：

source 前缀	说明	处理
`devtools://devtools/`	开发者工具自身的断言/警告	忽略
`ide:///extensions/`	IDE 扩展注入的提醒	区分对待

以下 message 模式属于框架级提醒，非应用错误：

message 模式	说明
`console.assert`	devtools 内部断言
`SharedArrayBufferIssue`	浏览器引擎警告
`getSystemInfo API 提示`	废弃 API 迁移提醒
`wx.saveFile 即将废弃` / `wx.removeSavedFile 即将废弃`	框架 API 废弃预警
`[Component] property "xxx" received type-uncompatible value`	组件属性类型不匹配警告

判断原则：CDP 的 errors/warnings 计数可能被上述噪音抬高，导致误判。始终以 page_data 返回的实际数据作为最终验证标准。

page_data 使用注意事项

必须校验 path 字段：返回的 data.path 表示当前实际页面，如果与导航目标不一致，说明页面跳转失败或被重定向。
常见不一致原因：
- 用户未登录，页面拦截跳转到登录/欢迎页
- 云函数调用失败（AppID undefined），页面 fallback 到首页
- page_path 拼写错误，navigate 静默失败（返回 success: true）
- 页面 onLoad 中有条件跳转逻辑

推荐模式：

wechat_navigate(page_path='pages/xxx/index', wait_ms=3000)
wechat_automator(action='page_data')
  ↳ data.path !== 'pages/xxx/index' → 页面未正确加载
  ↳ 用 page_stack 查看完整页面栈，定位重定向原因

返回值格式

{"success": true,  "data": {...}, "message": "操作描述"}
{"success": false, "error_code": "CLI_TIMEOUT", "message": "...", "hint": "修复提示"}
{"success": false, "error_code": "UNKNOWN_ERROR", "message": "小程序启动阶段检测到 N 个错误...", "hint": "...", "startup_errors": [...], "cdp_summary": {...}}

error_code	含义	处理
`PARAM_MISSING`	必填参数缺失	查看 hint 字段
`CLI_NOT_FOUND`	找不到 CLI	检查 `WECHAT_DEVTOOLS_CLI`
`PROJECT_PATH_MISSING`	项目路径未配置	检查 `WECHAT_PROJECT_PATH`
`NODE_NOT_FOUND`	Node.js 未安装	安装 Node.js ≥ 8.0
`CLI_TIMEOUT`	CLI 执行超时	开启服务端口；重启 IDE

Connection Recovery Tiers

Screenshot quick path (try first):

wechat_automator(action='start', project_path='...') # 必须看到 verified + ws_ready
wechat_automator(action='page_data', expected_path='...')
wechat_screenshot(full_page=false, page_path='...')

Automator recovery (when start fails):

MP_ROOT=/Users/lapuda/code/shz-employment-service/dist/build/mp-weixin
lsof -nP -iTCP:60423 -sTCP:LISTEN                  # 只读检查
lsof -nP -iTCP:9420 -sTCP:LISTEN
/Applications/wechatwebdevtools.app/Contents/MacOS/cli open \
  --project "$MP_ROOT" \
  --port 60423 --debug                                  # 仅在 60423 缺失时执行
wechat_automator(action='start', project_path='...')
wechat_automator(action='page_data', expected_path='...')

compile 只用于微信工具已打开的产物发生变更后的编译验证，不是 uni-app 源码构建命令，也不是截图连接恢复的默认步骤；cdp_enabled=true 只在需要 CDP 日志时启用，并且启用后仍要分别确认 60423 和 9420。

故障速查

症状	原因	解决
CDP 采集失败（9222 无响应）	IDE 未用 cdp_enabled 启动	`wechat_ide(action='open', cdp_enabled=True)` 重启
截图空白 / 尺寸 0	automator 未启动或页面未渲染	确认 `start` 已调用；增加 `wait_ms=3000`
`Page is not found`	page_path 拼写错 / 未注册	`wechat_file(action='list_pages')` 核查
`Element is obfuscated`	元素被遮挡或在 shadow-root 外	检查 WXML 结构，尝试父节点
`Cannot find context`	逻辑层崩溃 / 正在重载	等待 3s 后重试
`CLI_TIMEOUT`	服务端口未开启 / IDE 未运行	开启服务端口；`wechat_ide(action='open')`
元素未找到	不在当前页面或 selector 错	`page_stack` 确认页面；`element_info` 验证 selector
`Using AppID: undefined`	project_path 指向子目录而非项目根目录	改为包含 `project.config.json` 的目录
`appid missing` 云函数失败	AppID 未配置或未登录	检查 project_path + 登录状态
`Connection closed` 截图/操作失败	automator WS 连接断开（v0.9.0 daemon 架构下极少出现）	先快速恢复（仅 `start` → `page_data`）；失败再完整恢复（见 Recovery Tiers）
`Failed connecting to ws://localhost:9420`	automator 未启动或已断开	同上
截图 daemon 90 秒超时	`9420` 未建立；常见于只有 9222 的 CDP-only/半启动 IDE，或 60423 陈旧	检查 60423/9420；缺 60423 时标准 CLI `open --port 60423`，再 `start`，确认 `verified: true`、`ws_ready: true`
`start` 30 秒 CLI auto 超时	CLI 无法连接 60423，或 IDE 处于假在线状态	检查 60423；必要时 `quit` 并只终止匹配当前项目的僵死 PID，再标准 CLI `open`
navigate 返回 success 但页面未跳转	page_path 不存在或拼写错误	`list_pages` 确认路径；用 `page_stack` 验证
page_data.path 与 navigate 目标不一致	页面被重定向（未登录/参数错/云函数失败）	检查 AppID、登录状态、页面 onLoad 逻辑
CDP errors 计数含 console.assert	devtools 内部噪音	过滤 `devtools://` 来源，以 page_data 为准
子页面数据与主页面不一致	子页面使用独立数据获取链路	用 `evaluate` 直接调用 API 对比返回值
长图截图底部导航栏重复出现	固定区域检测失败（已在 v0.5.0 修复）	升级到最新版本；如仍复现请反馈
`open` 返回 startup_errors	小程序启动阶段有致命错误（页面无法显示）	根据 `startup_errors` 中的错误详情修复代码，修复后重新 `open`
`simulator not found` / `subPackages of undefined`	IDE 冷启动瞬态错误，运行时尚未就绪	忽略，继续执行 compile 刷新即可
compile 成功但 IDE 显示红色 WXML 错误	WXML 编译错误走 IDE 内部通道	检查中文引号 `""`、未关闭标签；查看 `wxml_errors` 字段
`currentPageTimeout is not defined`	wechat_navigate 内部变量作用域 bug（v0.7.0 已修复）	升级到 v0.7.0；或改用 evaluate + wx.reLaunch
compile_condition 入口页被覆盖	app 路由守卫覆盖编译入口	编译默认页，evaluate(wx.reLaunch) 跳转
switchTab ok 但未切换	switchTab 异步未完成	增加 wait_ms；v0.8.0 navigate 已自动处理 TabBar 页面
evaluate 报 `Unexpected token 'const'`	v0.6.0 仅支持表达式（v0.7.0 已修复）	升级到 v0.7.0；或用 IIFE 包裹
截图看不到弹窗/蒙层	fixed/absolute overlay 不在同一渲染层	以 page_data 为准
call_method 报 `page.xxx not exists` 且无页面信息	v0.6.0 未返回路径（v0.7.0 已修复）	升级到 v0.7.0；或先 page_data 确认 path
navigate TabBar 页面无效	TabBar 页面不支持 reLaunch/navigateTo	v0.8.0 自动检测并使用 switchTab；或手动 `evaluate(wx.switchTab)`
截图显示错误页面	screenshot connect 后页面被重置	使用 `page_path` 参数确保截图前在正确页面
scroll-view 页面长图只有一屏	automator SDK 无法捕获 scroll-view 内部滚动	已知限制，返回 `isScrollViewPage: true`；改用页面级滚动或 canvas 截图

连接断开恢复流程

当截图或自动化操作报 Connection closed、ws://localhost:9420 连接失败或 daemon 超时时，执行以下标准恢复流程。先做快速恢复；只有快速恢复失败，且端口检查确认 IDE 服务不完整时，才重开 IDE：

wechat_automator(action='start', project_path='...')               # ① 先尝试仅重连
wechat_automator(action='page_data', expected_path='...')          # ② 验证 automator

# 仅在 60423 缺失或 CLI auto 仍超时时：
/Applications/wechatwebdevtools.app/Contents/MacOS/cli open \
  --project "$MP_ROOT" \
  --port 60423 --debug
wechat_automator(action='start', project_path='...')               # ③ 重启 automator
wechat_automator(action='page_data', expected_path='...')          # ④ 再验证
# ⑤ 重试失败的截图/操作

绝对红线

❌ open 返回 startup_errors 后仍继续执行后续测试操作（必须先修复错误）
❌ 未确认 is_login: true 时调用 preview / upload
❌ 对生产项目调用 cache_clean(clean_type='all')
❌ 在 evaluate 中执行 eval() 或不安全代码
❌ 脑补运行状态——必须以 MCP 接口返回的实际数据为准
❌ 同一失败操作重试超过 3 次（应转为诊断根因）
❌ 自动化测试中使用 sleep 硬等待（用 wait_ms 或轮询 page_data）
❌ 在 SOP 流程中主动调用截图——仅在用户明确要求或异常排查需要视觉确认时才截图
❌ 连接断开时直接走完整恢复（应先快速恢复：仅 start → page_data）
❌ 没改代码就 compile（浪费时间，直接 evaluate 跳转）
❌ compile 后不验证 automator 连接（v0.8.0 自动重连，但需 page_data 确认）
❌ 使用 miniprogram/ 子目录作为云开发项目的 project_path
❌ navigate 后不校验 page_data.path 是否匹配预期页面
❌ 将 CDP 日志中 devtools:// 来源的 console.assert 视为应用错误
❌ 在多个并行 Agent 中同时使用 wechat_automator（9420 端口独占）
✅ wechat_screenshot 的 output_path 可选，留空自动保存到项目 screenshots/ 目录
✅ 使用任何自动化/截图功能前必须先调用 automator(action='start')
✅ 执行 tap/input 前先用 element_info 确认元素存在
✅ upload 前确认版本号已递增，build_npm 已执行
✅ 关注 CDP 日志中的 [Violation] 标记（渲染阻塞/性能问题）
✅ compile 后检查 AppID 是否为 undefined
❌ WXML 属性值中使用中文引号 "" 或未转义双引号（编译错误且工具无法检测）
✅ 截图/操作失败后先执行 start → page_data；仅在 60423 缺失时标准 CLI open → start
✅ 截图前确认 verified: true、tcp_ready: true、ws_ready: true
✅ navigate 后必须通过 page_data 或 page_stack 校验当前页面路径
✅ 在跨页面测试中比对同名字段的一致性

26 KiB Raw Blame History Unescape Escape