1

_DEL/weixin-devtools/POWER.md

@@ -0,0 +1,116 @@
+---
+name: "weixin-devtools"
+displayName: "微信开发者工具自动化"
+description: "通过 weixin-devtools-mcp 控制微信开发者工具，支持页面导航、元素快照、截图、表单操作、JS 执行、网络监控、Console 日志等小程序自动化操作"
+keywords: ["微信开发者工具", "小程序调试", "devtools", "wechat", "miniprogram", "截图", "screenshot", "页面快照", "snapshot", "元素点击", "click", "表单", "form", "navigate", "console", "网络请求", "network", "evaluate", "自动化测试", "UI验证"]
+author: "NeoZQYY"
+---
+
+# 微信开发者工具自动化 Power
+
+通过 weixin-devtools-mcp 控制微信开发者工具，用于小程序 UI 调试、页面验证、自动化测试。
+
+## 可用 Server
+
+### weixin-devtools
+连接本地微信开发者工具实例，提供完整的小程序自动化能力。
+
+前置条件：
+- 微信开发者工具已打开并加载项目
+- 自动化端口 9420 已启用（设置 → 安全 → 服务端口）
+
+## 工具分类速查
+
+### 连接管理
+| 工具 | 说明 |
+|------|------|
+| `connect_devtools` | 连接开发者工具（支持 auto/launch/connect 策略） |
+| `disconnect_devtools` | 断开连接并清理状态 |
+| `reconnect_devtools` | 重连（可复用上次参数） |
+| `get_connection_status` | 查看连接状态 |
+| `check_environment` | 检查自动化环境配置 |
+| `diagnose_connection` | 诊断连接问题 |
+| `debug_connection_flow` | 调试连接流程 |
+
+### 页面导航
+| 工具 | 说明 |
+|------|------|
+| `navigate_to` | 跳转到指定页面（支持参数） |
+| `navigate_back` | 返回上一页 |
+| `switch_tab` | 切换 TabBar 页面 |
+| `relaunch` | 重启小程序并跳转 |
+| `get_current_page` | 获取当前页面信息 |
+
+### 元素操作
+| 工具 | 说明 |
+|------|------|
+| `get_page_snapshot` | 获取页面元素快照（含 uid） |
+| `$` | CSS 选择器查找元素 |
+| `click` | 点击元素（支持双击） |
+| `input_text` | 输入文本 |
+| `set_form_control` | 设置表单控件值（picker/switch/slider） |
+| `get_value` | 获取元素值或文本 |
+| `debug_page_elements` | 调试元素获取问题 |
+
+### 断言验证
+| 工具 | 说明 |
+|------|------|
+| `assert_text` | 断言元素文本（精确/包含/正则） |
+| `assert_state` | 断言元素状态（可见/启用/选中/聚焦） |
+| `assert_attribute` | 断言元素属性值 |
+
+### JS 执行
+| 工具 | 说明 |
+|------|------|
+| `evaluate_script` | 在 AppService 上下文执行 JS |
+
+### 监控与调试
+| 工具 | 说明 |
+|------|------|
+| `screenshot` | 页面截图（base64 或保存文件） |
+| `list_console_messages` | 列表查询 console 消息 |
+| `get_console_message` | 获取单条 console 详情 |
+| `get_network_requests` | 获取网络请求记录 |
+| `clear_network_requests` | 清空网络请求记录 |
+| `stop_network_monitoring` | 停止网络监听 |
+
+### 等待
+| 工具 | 说明 |
+|------|------|
+| `waitFor` | 等待条件满足（元素出现/消失/文本匹配/延时） |
+
+## 典型工作流
+
+### 1. 连接 → 导航 → 验证
+```
+connect_devtools → navigate_to → get_page_snapshot → assert_text
+```
+
+### 2. 表单填写 → 提交 → 检查结果
+```
+navigate_to → get_page_snapshot → input_text → click → waitFor → assert_text
+```
+
+### 3. 截图对比（配合 pixel-audit）
+```
+navigate_to → screenshot → 用 image-compare 对比 H5 截图
+```
+
+### 4. 数据验证
+```
+evaluate_script（读取页面 data）→ 对比预期值
+```
+
+## Steering
+
+| 文件 | 内容 |
+|------|------|
+| `workflow.md` | 连接策略、页面导航模式、元素操作最佳实践、常见问题排查 |
+
+加载：激活 Power → `readSteering("workflow.md")`
+
+## 注意事项
+- 操作元素前必须先 `get_page_snapshot` 获取 uid
+- `navigate_to` 不能跳转 TabBar 页面，用 `switch_tab`
+- `evaluate_script` 在 AppService 上下文执行，可访问 `wx`、`getApp()`、`getCurrentPages()`
+- 截图默认返回 base64，传 `path` 参数可保存到文件

_DEL/weixin-devtools/mcp.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "weixin-devtools": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "weixin-devtools-mcp",
+        "--tools-profile=full",
+        "--ws-endpoint=ws://127.0.0.1:9420"
+      ],
+      "env": {
+        "WECHAT_DEVTOOLS_CLI": "C:\\dev\\WechatDevtools\\cli.bat",
+        "WECHAT_DEVTOOLS_PROJECT": "C:\\NeoZQYY\\apps\\miniprogram"
+      },
+      "autoApprove": ["*"]
+    }
+  }
+}

_DEL/weixin-devtools/steering/workflow.md

@@ -0,0 +1,179 @@
+# 微信开发者工具自动化工作流
+
+## 连接策略
+
+### 首次连接
+```
+connect_devtools（strategy: "auto"）
+```
+auto 策略会依次尝试：发现已运行实例 → 通过 CLI 启动 → ws 直连。
+
+### 连接失败排查
+1. `check_environment` — 检查 CLI 路径、项目路径是否正确
+2. `diagnose_connection` — 检查端口、进程状态
+3. 确认开发者工具「设置 → 安全 → 服务端口」已开启
+
+### 重连
+```
+reconnect_devtools  // 复用上次参数
+```
+
+## 页面导航模式
+
+### 普通页面跳转
+```
+navigate_to(url: "/pages/task/task-list/index", params: { status: "pending" })
+```
+
+### TabBar 页面
+```
+switch_tab(url: "/pages/index/index")
+```
+注意：`navigate_to` 无法跳转 TabBar 页面，必须用 `switch_tab`。
+
+### 重启并跳转
+```
+relaunch(url: "/pages/index/index")
+```
+清空页面栈，适合需要干净状态的场景。
+
+### 返回
+```
+navigate_back(delta: 1)  // 返回上一页
+navigate_back(delta: 2)  // 返回两层
+```
+
+## 元素操作最佳实践
+
+### 操作流程（必须遵循）
+1. `get_page_snapshot` 获取当前页面所有元素的 uid
+2. 从快照中找到目标元素的 uid
+3. 用 uid 执行操作（click / input_text / get_value / assert_*）
+
+### 快照格式选择
+- `compact`（默认推荐）：含 uid、标签、文本、位置、尺寸，token 用量减少 60-70%
+- `minimal`：只含 uid、标签、文本，最省 token
+- `json`：完整 JSON，需要属性详情时用
+
+### CSS 选择器查找
+```
+$("view.container")     // 类名
+$("#myId")              // ID
+$("text=按钮")          // 文本匹配
+```
+返回匹配元素的详细信息，适合精确定位。
+
+### 输入文本
+```
+input_text(uid: "xxx", text: "测试内容")
+input_text(uid: "xxx", text: "追加内容", append: true)
+input_text(uid: "xxx", text: "新内容", clear: true)  // 先清空再输入
+```
+
+### 表单控件
+```
+set_form_control(uid: "xxx", value: 2)          // picker 选第3项
+set_form_control(uid: "xxx", value: true)        // switch 开启
+set_form_control(uid: "xxx", value: 50)          // slider 设为50
+```
+
+## 断言验证
+
+### 文本断言
+```
+assert_text(uid: "xxx", text: "精确匹配")
+assert_text(uid: "xxx", textContains: "包含")
+assert_text(uid: "xxx", textMatches: "\\d{4}-\\d{2}-\\d{2}")  // 正则
+```
+
+### 状态断言
+```
+assert_state(uid: "xxx", visible: true)
+assert_state(uid: "xxx", enabled: false)
+assert_state(uid: "xxx", checked: true)
+```
+
+### 属性断言
+```
+assert_attribute(uid: "xxx", attributeKey: "class", attributeValue: "active")
+```
+
+## JS 执行
+
+### 读取页面数据
+```javascript
+evaluate_script({
+  function: "() => { const pages = getCurrentPages(); return pages[pages.length-1].data; }"
+})
+```
+
+### 读取全局数据
+```javascript
+evaluate_script({
+  function: "() => { return getApp().globalData; }"
+})
+```
+
+### 调用 wx API
+```javascript
+evaluate_script({
+  function: "() => { return wx.getSystemInfoSync(); }"
+})
+```
+
+### 带参数执行
+```javascript
+evaluate_script({
+  function: "(key) => { return wx.getStorageSync(key); }",
+  args: ["userToken"]
+})
+```
+
+## 截图与视觉验证
+
+### 保存截图到文件
+```
+screenshot(path: "C:/NeoZQYY/export/screenshots/task-list.png")
+```
+
+### 配合 pixel-audit Power 做视觉对比
+1. H5 页面用 Playwright 截图
+2. MP 页面用 `screenshot` 截图
+3. 用 `image-compare`（已集成在 pixel-audit）对比差异
+
+## 网络请求监控
+
+### 查看请求
+```
+get_network_requests(urlPattern: "api/v1/tasks", limit: 10)
+get_network_requests(type: "request", successOnly: true)
+```
+
+### 清空并重新监控
+```
+clear_network_requests → 执行操作 → get_network_requests
+```
+
+## 等待策略
+
+### 等待元素出现
+```
+waitFor(selector: ".loading", disappear: true, timeout: 10000)  // 等 loading 消失
+waitFor(selector: ".task-card", timeout: 5000)                   // 等元素出现
+waitFor(text: "加载完成", timeout: 5000)                         // 等文本出现
+```
+
+### 固定延时
+```
+waitFor(delay: 2000)  // 等待 2 秒
+```
+
+## 常见问题
+
+| 问题 | 解决方案 |
+|------|----------|
+| 连接超时 | 检查 9420 端口是否开启，`diagnose_connection` |
+| 元素找不到 | 先 `get_page_snapshot` 确认页面已加载完成 |
+| navigate_to 失败 | TabBar 页面必须用 `switch_tab` |
+| evaluate_script 报错 | 函数不能引用外部闭包变量，必须自包含 |
+| 截图空白 | 页面可能还在加载，先 `waitFor` |