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

2026-07-24 09:09:15 +08:00
parent 773679c292
commit 6bc4d64c6b
20 changed files with 1449 additions and 240 deletions
--- a/.codex/skills/wechat-devtools/SKILL.md
+++ b/.codex/skills/wechat-devtools/SKILL.md
@@ -0,0 +1,440 @@
+---
+name: wechat-devtools
+description: 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：
+
+```bash
+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`。当前机器通常使用：
+
+```bash
+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`，并使用固定端口：
+
+```bash
+/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：
+
+1. 使用验收产物显式传参，例如 `/Users/lapuda/code/shz-employment-service/dist/build/mp-weixin`；先确认其中存在 `app.json` 和 `project.config.json`。
+2. 先调用 `wechat_automator(action="start", project_path="...")`。
+3. 只有返回 `success: true`、`verified: true`、`tcp_ready: true`、`ws_ready: true` 才能调用截图；再用 `page_data(expected_path=...)` 或 `wechat_navigate` 校验页面。
+4. 截图优先 `full_page=false`；页面路径明确时传 `page_path`，需要稳定取证时显式传 `output_path`。
+
+如果 `start` 超时、返回 `Connection closed` 或截图报 daemon 超时，不要立刻重试截图。先用只读命令检查端口：
+
+```bash
+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：
+
+  ```bash
+  /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`，若是工具引入的无关变化，恢复原值。
+
+示例页面验证：
+
+```text
+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：安装与配置
+
+```bash
+pip install uv   # 如未安装 uv
+uv tool install wechat-devtools-mcp --force  # 通过uv安装wechat-devtools-mcp
+```
+
+编辑器配置：
+
+```json
+{
+  "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](https://github.com/WaterTian/wechat-devtools-mcp#%EF%B8%8F-%E7%BC%96%E8%BE%91%E5%99%A8%E9%85%8D%E7%BD%AE)
+
+> [!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 跳转更可靠
+
+| `preview` | 生成预览二维码 | `qr_format="terminal"` |
+| `upload` | 上传到微信后台 | **`version`（必填）**, `desc?` |
+| `build_npm` | 构建 NPM 依赖（upload 前必做） | — |
+| `cache_clean` | 清除缓存 | `clean_type="compile"` |
+
+### `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
+
+| `page_stack` | 获取页面栈 | — |
+| `page_data` | 获取当前页面 data | `expected_path?`（轮询验证页面路径） |
+| `system_info` | 获取运行时系统信息 | — |
+| `storage` | 读取本地缓存 | `key?`（空=列出全部） |
+
+### `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](https://github.com/TencentCloudBase/CloudBase-AI-ToolKit)（`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 使用注意事项
+
+1. **必须校验 path 字段**：返回的 `data.path` 表示当前实际页面，如果与导航目标不一致，说明页面跳转失败或被重定向。
+
+2. **常见不一致原因**：
+   - 用户未登录，页面拦截跳转到登录/欢迎页
+   - 云函数调用失败（AppID undefined），页面 fallback 到首页
+   - page_path 拼写错误，navigate 静默失败（返回 success: true）
+   - 页面 onLoad 中有条件跳转逻辑
+
+3. **推荐模式**：
+   ```
+   wechat_navigate(page_path='pages/xxx/index', wait_ms=3000)
+   wechat_automator(action='page_data')
+     ↳ data.path !== 'pages/xxx/index' → 页面未正确加载
+     ↳ 用 page_stack 查看完整页面栈，定位重定向原因
+   ```
+
+---
+
+## 返回值格式
+
+```json
+{"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` 校验当前页面路径
+- ✅ 在跨页面测试中比对同名字段的一致性
--- a/.codex/skills/wechat-devtools/agents/openai.yaml
+++ b/.codex/skills/wechat-devtools/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "微信小程序调试"
+  short_description: "用微信开发者工具模拟器调试、截图并验证小程序页面。"
+  default_prompt: "Use $wechat-devtools to health-check the WeChat DevTools connection, capture a screenshot, and verify this mini-program issue without uploading code or submitting real business data."
--- a/.codex/skills/wechat-devtools/references/tool_reference.md
+++ b/.codex/skills/wechat-devtools/references/tool_reference.md
@@ -0,0 +1,523 @@
+# wechat-devtools-mcp 工具参数完整参考 (v0.9.10)
+
+> 本文档是 `SKILL.md` 的扩展参考，提供 7 个聚合 API 的所有参数完整说明（v0.9.5 起 `wechat_cloud` 已禁用）。  
+> 基础 SOP 流程请参阅 `SKILL.md`。
+
+所有工具返回统一 JSON 信封：
+
+```json
+// 成功
+{"success": true, "data": {...}, "message": "操作描述"}
+// 失败
+{"success": false, "error_code": "PARAM_MISSING", "message": "...", "hint": "修复建议"}
+```
+
+> [!IMPORTANT]
+> **必须手动开启开发者工具的服务端口**：`设置` → `安全` → `服务端口` → `开启`。未开启将导致所有 CLI 操作报 `CLI_TIMEOUT`。
+
+
+---
+
+## 目录
+
+1. [wechat_ide — IDE 生命周期管理](#1-wechat_ide)
+2. [wechat_build — 构建与发布](#2-wechat_build)
+3. [wechat_automator — 自动化交互](#3-wechat_automator)
+4. [wechat_inspector — 运行时日志采集](#4-wechat_inspector)
+5. [wechat_screenshot — 界面截图](#5-wechat_screenshot)
+6. [wechat_navigate — 跳转并采集日志](#6-wechat_navigate)
+7. [wechat_file — 项目文件读取](#7-wechat_file)
+8. [错误码速查表](#8-错误码速查表)
+
+> 云函数/云数据库管理请改用 [CloudBase MCP](https://github.com/TencentCloudBase/CloudBase-AI-ToolKit)，无 IDE 依赖且能力更完整。
+
+---
+
+## 1. wechat_ide
+
+IDE 生命周期管理。覆盖原 `wechat_open`、`wechat_login`、`wechat_is_login`、`wechat_close_project`、`wechat_quit_ide`、`wechat_get_status`。
+
+### 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `action` | string | **必填** | `open` / `login` / `is_login` / `close` / `quit` / `status` |
+| `project_path` | string | 环境变量 | 小程序项目绝对路径，不填则使用 `WECHAT_PROJECT_PATH` |
+| `appid` | string | null | 小程序 AppID（`open` 时可选，覆盖 project.config.json 中的值） |
+| `port` | int | null | IDE HTTP 服务端口号（多 IDE 实例时使用） |
+| `lang` | string | null | 界面语言：`en` 或 `zh` |
+| `cdp_enabled` | bool | `true` | 是否开启 CDP 调试端口 9222，`open` 时使用 |
+| `qr_format` | string | `terminal` | 二维码格式：`terminal`（终端文字画）或 `base64`，`login` 时使用 |
+| `qr_output` | string | null | 二维码输出文件路径（PNG），`login` 时使用 |
+
+### action 说明
+
+| action | 功能描述 | 条件参数 | 注意事项 |
+|--------|----------|----------|----------|
+| `open` | 打开 IDE 并载入项目；需要时通过 `cdp_enabled` 做启动健康检查 | `cdp_enabled=true` | 若 IDE 已运行会 kill 并重启，确保 CDP 端口绑定；源码变更后仍需显式 compile/preview |
+| `login` | 生成登录二维码 | `qr_format`, `qr_output` | 需用户手机扫码，终端输出文字二维码 |
+| `is_login` | 检查当前登录状态 | 无 | 返回 `data.logged_in: bool` |
+| `close` | 关闭指定项目窗口 | `project_path` | 不退出 IDE 进程 |
+| `quit` | 完全退出 IDE 进程 | 无 | ⚠️ 会终止所有项目 |
+| `status` | 环境全面诊断 | 无 | 返回 `mcp_version`、CLI 路径、Node.js、项目路径等状态 |
+
+### 返回示例（status action）
+
+```json
+{
+  "success": true,
+  "data": {
+    "mcp_version": "0.9.3",
+    "cli_exists": true,
+    "cli_path": "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat",
+    "project_exists": true,
+    "project_path": "D:\\MyProject",
+    "node_available": true,
+    "node_path": "node (v22.19.0)"
+  },
+  "message": "状态正常"
+}
+```
+
+---
+
+## 2. wechat_build
+
+构建与发布。覆盖原 `wechat_compile_check`、`wechat_preview`、`wechat_upload`、`wechat_build_npm`、`wechat_cache_clean`。
+
+### 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `action` | string | **必填** | `compile` / `preview` / `upload` / `build_npm` / `cache_clean` |
+| `project_path` | string | 环境变量 | 小程序项目路径 |
+| `version` | string | null | 版本号，`upload` 时**必填**，例如 `1.0.0` |
+| `desc` | string | null | 版本描述，`upload` 时使用 |
+| `qr_format` | string | `base64` | 二维码格式：`terminal` 或 `base64` |
+| `qr_output` | string | null | 二维码保存路径 |
+| `info_output` | string | null | 编译/上传信息写入的 JSON 文件路径 |
+| `compile_condition` | string | null | 自定义编译条件（JSON 字符串）。注意：对 tabBar 页面可能无效（app 路由守卫覆盖），用 `evaluate` + `wx.reLaunch` 更可靠 |
+| `compile_type` | string | null | 编译类型：`miniprogram` 或 `plugin` |
+| `clean_type` | string | `compile` | `cache_clean` 时的缓存类型：`storage` / `file` / `compile` / `auth` / `network` / `session` / `all` |
+| `port` | int | null | IDE HTTP 服务端口号 |
+| `lang` | string | null | 界面语言 |
+
+### action 说明
+
+| action | 功能描述 | 条件必填 | 注意事项 |
+|--------|----------|----------|----------|
+| `compile` | 触发编译并捕获所有 Error/Warning | 无 | **最常用**；v0.9.0 daemon 自动重连 automator，无需重新 `start` |
+| `preview` | 生成预览二维码 | 无 | 需已登录；手机扫码可预览 |
+| `upload` | 上传代码到微信后台 | **`version`** | ⚠️ 生产操作，执行前确认代码无误 |
+| `build_npm` | 构建 NPM 依赖 | 无 | 新增/更新 npm 包后必须执行 |
+| `cache_clean` | 清除缓存 | 无 | 默认清编译缓存；`all` 会清除所有，**小心使用** |
+
+### 返回示例（compile action）
+
+```json
+{
+  "success": true,
+  "data": {
+    "errors": [],
+    "warnings": ["pages/index/index.wxml: 属性 wx:key 应使用唯一标识符"],
+    "compile_time_ms": 1234,
+    "automator_reconnected": true,
+    "automator_verified": true,
+    "port_changed": false,
+    "old_port": 9420,
+    "new_port": 9420
+  },
+  "message": "编译完成，0 个错误，1 个警告"
+}
+```
+
+---
+
+## 3. wechat_automator
+
+自动化交互与运行时查询。覆盖所有原自动化工具（13 个 action）。
+
+> **前提**：需先调用 `wechat_automator(action='start')` 开启并验证 9420 自动化端口；代码重新编译后按返回状态决定是否重新验证。
+
+### 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `action` | string | **必填** | 见下表 13 个 action |
+| `auto_port` | int | `9420` | 自动化监听端口 |
+| `project_path` | string | 环境变量 | 项目路径，`start` 时使用 |
+| `selector` | string | null | CSS 选择器，例如 `.submit-btn`、`#login`；`tap`/`input`/`element_info` 时**必填** |
+| `value` | string | null | 输入值，`input` 时**必填** |
+| `style_prop` | string | null | CSS 属性名，`element_info` 时可选 |
+| `data_json` | string | null | JSON 数据字符串，`set_data` 时**必填**，例如 `{"key": "val"}` |
+| `method` | string | null | 方法名，`call_method`/`call_wx`/`mock_wx` 时**必填** |
+| `args_json` | string | null | 方法参数（JSON 数组字符串），例如 `[1, "hello"]` |
+| `expression` | string | null | JS 代码（支持表达式和声明语句），`evaluate` 时**必填** |
+| `result_json` | string | null | Mock 返回值（JSON 字符串），`mock_wx` 时**必填** |
+| `key` | string | null | Storage key，`storage` 时可选（空=列出全部） |
+| `auto_account` | string | null | 指定 openid（测试账号），`start` 时可选 |
+
+### action 详细说明
+
+#### `start` — 开启自动化端口（含连接验证）
+
+```json
+{
+  "tool": "wechat_automator",
+  "arguments": {"action": "start", "project_path": "D:\\MyProject"}
+}
+```
+
+启动持久化 Node daemon 并开启自动化端口，自动轮询验证连接（最多 10 秒）。返回 `data.verified: true` 表示连接就绪；`verified: false` 表示已启动但未确认连接，此时额外返回 `hint`（操作建议）、`attempts_made`（已尝试次数）、`max_wait_seconds`（最大等待时间）。v0.9.0 起 compile 后 daemon 自动重连，无需再次调用 start。
+
+#### `tap` — 点击元素
+
+```json
+{"action": "tap", "selector": ".submit-btn"}
+```
+
+#### `input` — 输入文本
+
+```json
+{"action": "input", "selector": "input.search-box", "value": "搜索关键词"}
+```
+
+#### `element_info` — 获取元素详情
+
+```json
+{"action": "element_info", "selector": ".card-item", "style_prop": "color"}
+```
+
+返回：元素文本内容、包围盒（x/y/width/height）、WXML 结构、指定 CSS 值。
+
+#### `set_data` — 热更新页面 data
+
+```json
+{"action": "set_data", "data_json": "{\"list\": [], \"loading\": false, \"title\": \"测试\"}"}
+```
+
+修改立即生效，无需重编译。适合快速验证 UI 状态切换。
+
+#### `call_method` — 调用页面方法
+
+```json
+{"action": "call_method", "method": "onRefresh", "args_json": "[]"}
+```
+
+返回 `data.path` 标识当前页面路径；失败时错误消息中包含页面路径，便于定位问题。
+
+#### `call_wx` — 调用 wx API
+
+```json
+{"action": "call_wx", "method": "getSystemInfo", "args_json": "[]"}
+```
+
+#### `mock_wx` — Mock wx API
+
+```json
+{
+  "action": "mock_wx",
+  "method": "requestPayment",
+  "result_json": "{\"errMsg\": \"requestPayment:ok\"}"
+}
+```
+
+常用 Mock 模板：
+
+| 场景 | method | result_json 示例 |
+|------|--------|-----------------|
+| 支付成功 | `requestPayment` | `{"errMsg": "requestPayment:ok"}` |
+| 弹窗确认 | `showModal` | `{"confirm": true, "cancel": false, "errMsg": "showModal:ok"}` |
+| 定位授权 | `chooseLocation` | `{"name": "腾讯大厦", "latitude": 22.54, "longitude": 113.93, "errMsg": "chooseLocation:ok"}` |
+| 获取用户信息 | `getUserProfile` | `{"userInfo": {"nickName": "测试用户", "avatarUrl": "..."}, "errMsg": "getUserProfile:ok"}` |
+| 选择图片 | `chooseImage` | `{"tempFilePaths": ["wxfile://tmp.jpg"], "errMsg": "chooseImage:ok"}` |
+
+#### `evaluate` — 执行 JS 代码
+
+```json
+{"action": "evaluate", "expression": "getApp().globalData.userInfo"}
+```
+
+支持表达式和声明语句（`const`/`let`/`var`）。表达式模式优先，失败后自动 fallback 到语句模式。
+
+#### `page_stack` — 获取页面栈
+
+```json
+{"action": "page_stack"}
+```
+
+返回当前所有页面路径的有序列表，最后一个为当前活跃页。
+
+#### `page_data` — 获取当前页面 data
+
+```json
+{"action": "page_data"}
+{"action": "page_data", "expected_path": "pages/index/index"}
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `expected_path` | string | null | 期望的页面路径，传入后轮询验证当前页面是否匹配 |
+
+返回当前页面实例的完整 `data` 对象。当传入 `expected_path` 且当前页面不匹配时，返回 `data.path_mismatch: true` 和 `data.warning` 提示信息。
+
+#### `system_info` — 获取系统信息
+
+返回设备信息、操作系统版本、微信版本、屏幕尺寸等。
+
+#### `storage` — 读取本地缓存
+
+```json
+{"action": "storage"}           // 列出所有 key
+{"action": "storage", "key": "userToken"}  // 读取指定 key 的值
+```
+
+---
+
+## 4. wechat_inspector
+
+运行时日志采集。覆盖原 `wechat_get_console_logs`、`wechat_get_cdp_logs`。
+
+### 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `action` | string | **必填** | `console` 或 `cdp` |
+| `duration` | int | `10` | 采集持续时间（秒），范围 1~120 |
+| `detail_level` | string | `concise` | `cdp` 时：`concise`（仅 errors+warnings）或 `full`（全量） |
+| `max_logs` | int | `50` | `cdp` 时：最大返回条数，超出 `truncated=true` |
+| `cdp_port` | int | `9222` | CDP 调试端口 |
+| `auto_port` | int | `9420` | 自动化端口，`console` 时使用 |
+| `log_type` | string | `all` | `console` 时：`all` / `console` / `exception` |
+| `tap_selector` | string | null | 采集期间自动点击的元素（触发懒加载/交互日志） |
+| `tap_delay` | int | `500` | 点击延迟（毫秒） |
+
+### action 说明
+
+#### `console` — automator 端口日志
+
+- **采集来源**：9420 自动化端口
+- **捕获内容**：`console.log/warn/error` 输出 + JS 运行时异常（堆栈）
+- **前提**：先调用 `wechat_automator(action='start')`
+
+```json
+{
+  "action": "console",
+  "duration": 10,
+  "log_type": "exception"
+}
+```
+
+#### `cdp` — CDP 协议底层日志
+
+- **采集来源**：端口 9222（CDP 协议）
+- **捕获内容**：WXML 警告、废弃 API 提示、渲染层报错、Runtime 错误
+- **前提**：调用 `wechat_ide(action='open', cdp_enabled=True)` 确保端口 9222 已绑定
+
+```json
+{
+  "action": "cdp",
+  "duration": 10,
+  "detail_level": "concise",
+  "max_logs": 50
+}
+```
+
+### CDP 返回结构
+
+```json
+{
+  "success": true,
+  "data": {
+    "summary": {
+      "total": 15,
+      "errors": 2,
+      "warnings": 5,
+      "info": 8,
+      "truncated": false
+    },
+    "logs": [
+      {
+        "level": "error",
+        "message": "Component is not found in path \"components/foo/foo\"",
+        "source": "index.wxml",
+        "timestamp": "2026-03-19T10:00:01.234Z"
+      },
+      {
+        "level": "warning",
+        "message": "wx.getSystemInfoSync 已弃用，请使用 wx.getSystemInfo",
+        "source": "app.js",
+        "timestamp": "2026-03-19T10:00:01.567Z",
+        "column": 12,
+        "line": 45
+      }
+    ]
+  },
+  "message": "采集 10 秒，发现 2 个错误、5 个警告"
+}
+```
+
+
+**detail_level 对比：**
+
+| 模式 | 返回内容 | 适用场景 |
+|------|----------|----------|
+| `concise` | summary + errors + warnings | 快速诊断（节省 Token） |
+| `full` | summary + 所有级别日志 | 深度排查（需要完整上下文） |
+
+---
+
+## 5. wechat_screenshot
+
+捕获当前小程序模拟器界面截图，默认自动滚动拼接长图，保存为 PNG。
+
+### 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `output_path` | string | `null`（自动生成） | 截图保存路径。留空则自动保存到项目目录下 `screenshots/` 文件夹 |
+| `auto_port` | int | `9420` | 自动化监听端口 |
+| `overlap` | int | `50` | 分段重叠像素数，防止滚动拼接时内容截断 |
+| `full_page` | bool | `true` | 是否截取长图，设为 `false` 只截当前视口 |
+| `scroll_top` | int | null | 截图前滚动到的位置（逻辑像素） |
+| `page_path` | string | null | 确保截图前在指定页面上 |
+
+### 注意事项
+
+- `output_path` 可选：留空则自动保存到 `{WECHAT_PROJECT_PATH}/screenshots/screenshot_{timestamp}.png`
+- 如手动指定路径，父目录会自动创建，无需预先 mkdir
+- **前提**：已调用 `wechat_automator(action='start')`
+- **不要主动截图**：仅在用户明确要求或排查异常需要视觉确认时才调用
+- **限制**：截图可能无法捕获 fixed/absolute 定位的 overlay（弹窗、蒙层），以 `page_data` 为准
+- Windows 路径使用正斜杠 `/` 或双反斜杠 `\\` 均可
+
+### 返回示例
+
+```json
+{
+  "success": true,
+  "data": {
+    "path": "D:/YourProject/screenshots/screenshot_20260326_143000.png",
+    "width": 375,
+    "height": 1200,
+    "segments": 3,
+    "isScrollViewPage": false
+  },
+  "message": "截图已保存，共拼接 3 段"
+}
+```
+
+---
+
+## 6. wechat_navigate
+
+跳转到指定页面，等待渲染完成，同步采集 CDP 高清日志。适合检查页面 `onLoad`/`onShow` 阶段的初始化错误。
+
+### 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `page_path` | string | **必填** | 页面路径，例如 `pages/index/index`（无需前导 `/`） |
+| `wait_ms` | int | `2000` | 跳转后等待时间（毫秒），范围 100~30000 |
+| `auto_port` | int | `9420` | 自动化监听端口 |
+| `cdp_port` | int | `9222` | CDP 调试端口 |
+| `detail_level` | string | `concise` | `concise` 或 `full` |
+| `max_logs` | int | `50` | 最大返回 CDP 日志条数 |
+| `clear_logs` | `bool` | `true` | 否 | 是否过滤跳转前的 CDP 历史日志（基于时间戳）。设为 `false` 可获取完整累积日志。 |
+| `check_data` | `bool` | `true` | 否 | 跳转后检查 page_data，如超过 70% 字段为空且 URL 含 query 参数，追加参数名错误警告。 |
+| `project_path` | string | null | 项目路径（仅用于日志提示） |
+
+### 等待时间建议
+
+| 页面复杂度 | 推荐 wait_ms |
+|-----------|-------------|
+| 简单静态页面 | 1000~2000 |
+| 含网络请求的页面 | 3000~5000 |
+| 含动画/懒加载的页面 | 5000+ |
+
+### 返回示例
+
+```json
+{
+  "success": true,
+  "data": {
+    "current_page": "pages/index/index",
+    "navigation_method": "reLaunch",
+    "logs_since": "2026-03-25T10:30:00.000Z",
+    "filtered_before_navigation": 5,
+    "warning": "页面数据大部分为空，可能是 query 参数名错误。",
+    "cdp_logs": {
+      "summary": {"total": 3, "errors": 0, "warnings": 2, "info": 1, "truncated": false},
+      "logs": [...]
+    }
+  },
+  "message": "已跳转到 pages/index/index，采集到 3 条日志"
+}
+```
+
+---
+
+## 7. wechat_file
+
+项目文件读取。覆盖原 `wechat_project_info`、`wechat_list_pages`、`wechat_read_page`、`wechat_read_file`。
+
+### 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `action` | string | **必填** | `project_info` / `list_pages` / `read_page` / `read_file` |
+| `project_path` | string | 环境变量 | 小程序项目路径 |
+| `page_path` | string | null | 页面路径，`read_page` 时**必填**，例如 `pages/index/index` |
+| `file_path` | string | null | 相对文件路径，`read_file` 时**必填**，例如 `app.json` |
+
+### action 说明
+
+#### `project_info` — 项目完整信息
+
+返回：
+- `project.config.json` 解析结果（AppID、名称、编译条件等）
+- `app.json` 解析结果（页面列表、tabBar、全局配置）
+- 项目根目录结构（一层）
+
+#### `list_pages` — 页面列表
+
+返回 `app.json` 中注册的所有页面路径，并检查每个页面的 `.wxml`/`.js`/`.wxss`/`.json` 文件是否存在。
+
+#### `read_page` — 读取页面完整源码
+
+```json
+{"action": "read_page", "page_path": "pages/index/index"}
+```
+
+返回：
+- `index.wxml` — 模板结构
+- `index.wxss` — 样式
+- `index.js` — 逻辑（含 Page/Component 定义）
+- `index.json` — 页面配置
+
+#### `read_file` — 读取任意文件
+
+```json
+{"action": "read_file", "file_path": "components/header/header.js"}
+```
+
+最多返回 800 行，超出时附注截断说明。
+
+---
+
+## 8. 错误码速查表
+
+| error_code | 含义 | 常见原因 | 处理方式 |
+|------------|------|----------|----------|
+| `PARAM_MISSING` | 必填参数未提供 | 漏传 `selector`、`version` 等 | 查看 `hint` 字段，补充参数 |
+| `CLI_NOT_FOUND` | 微信开发者工具 CLI 不存在 | `WECHAT_DEVTOOLS_CLI` 路径错误 | 确认安装路径并更新环境变量 |
+| `PROJECT_PATH_MISSING` | 项目路径未配置 | `WECHAT_PROJECT_PATH` 未设置 | 配置环境变量或传入 `project_path` |
+| `NODE_NOT_FOUND` | Node.js 未安装或不在 PATH | Node 未安装/`NODE_PATH` 错误 | 安装 Node.js ≥ 8.0 |
+| `CLI_TIMEOUT` | CLI 命令执行超时 | IDE 未运行/端口未开启 | 调用 `wechat_ide(action='open')` 后重试 |
+| `CDP_CONNECTION_ERROR` | CDP 端口 9222 连接失败 | 未以 `cdp_enabled=True` 启动 | 调用 `wechat_ide(action='open', cdp_enabled=True)` |
+| `AUTOMATION_PORT_ERROR` | 自动化端口 9420 连接失败 | 未调用 `start` action | 先调用 `wechat_automator(action='start')` |
+| `FILE_NOT_FOUND` | 文件或页面路径不存在 | `page_path`/`file_path` 拼写错误 | 先调用 `list_pages` 确认路径 |
+
+---
+
+*返回 [SKILL.md](../SKILL.md)*