docs(miniprogram): 新增 MCP 联调章节 — 操作指南 + 已知限制 + 故障排查
- wiki/miniprogram.md §6: 完整 MCP 联调文档 - 前置条件与建立连接 - 16 个 MCP 工具使用说明 - 绕过微信登录的 storage 注入流程 - TabBar 页面列表与导航注意事项 - 已知限制：screenshot 超时、navigateTo 超时、auth 重定向 - e2e 验证脚本说明 - wiki/index.md: 新增 3 条 MCP 相关症状导航
This commit is contained in:
iven
@@ -38,6 +38,9 @@
|
||||
| 小程序登录失败 `btoa is not defined` | [[miniprogram]] secure-storage | Web API 不可用 | 使用 `Taro.arrayBufferToBase64` 替代 |
|
||||
| 微信登录 500 | [[database]] wechat_users 表结构 | Entity 字段与表不匹配 | 补 `created_by/updated_by/version` 列 |
|
||||
| 迁移文件缺失报错 | [[database]] 迁移注册 | migration/src/lib.rs | 已应用的迁移文件被删除，需创建 stub |
|
||||
| MCP 连接失败 `split` error | [[miniprogram]] MCP 联调 | project.config.json | 未开启 `automationAudits` |
|
||||
| MCP mp_screenshot 超时 | [[miniprogram]] MCP 联调 | automator 已知 bug | 用 `page_getElement` 替代截图 |
|
||||
| MCP 导航后跳回登录页 | [[miniprogram]] MCP 联调 §6.4 | storage 被清空 | 加密 token 写入后立即 reLaunch |
|
||||
|
||||
## 模块导航
|
||||
|
||||
|
||||
@@ -231,10 +231,107 @@ secret = "<通过环境变量 ERP__WECHAT__SECRET 设置>"
|
||||
- 微信开发者工具中 `getPhoneNumber` 需要真机调试或使用测试号
|
||||
- Redis 不可达时限流降级为 fail-open，不影响登录
|
||||
|
||||
## 6. 变更记录
|
||||
## 6. MCP 联调（微信开发者工具自动化）
|
||||
|
||||
> 通过 MCP (Model Context Protocol) 工具直接操控微信开发者工具中的小程序模拟器，实现页面导航、元素交互、数据读取等操作。
|
||||
|
||||
### 6.1 前置条件
|
||||
|
||||
1. **后端运行** — `cargo run` 启动 `http://localhost:3000`
|
||||
2. **小程序已构建** — `cd apps/miniprogram && pnpm build:weapp`
|
||||
3. **微信开发者工具已打开项目** — 加载 `apps/miniprogram/dist/`
|
||||
4. **自动化端口已开启** — `project.config.json` 中 `"automationAudits": true`，端口 9420
|
||||
|
||||
### 6.2 建立连接
|
||||
|
||||
```
|
||||
调用 mp_ensureConnection → 自动连接 ws://localhost:9420
|
||||
```
|
||||
|
||||
成功后返回系统信息（SDK 版本、设备型号、屏幕尺寸等）。
|
||||
|
||||
### 6.3 常用 MCP 操作
|
||||
|
||||
| 操作 | MCP 工具 | 说明 |
|
||||
|------|----------|------|
|
||||
| 查看当前页面 | `mp_currentPage` | 返回路径、尺寸、数据 |
|
||||
| 导航到页面 | `mp_navigate` | `navigateTo` / `switchTab` / `reLaunch` |
|
||||
| 返回上一页 | `mp_navigate` | `transition: "navigateBack"` |
|
||||
| 截图 | `mp_screenshot` | ⚠️ 当前版本超时，见下方限制 |
|
||||
| 读取 storage | `mp_callWx` | method: `getStorageSync` |
|
||||
| 写入 storage | `mp_callWx` | method: `setStorageSync` |
|
||||
| 查找元素 | `page_getElement` | CSS 选择器，返回标签/文本/尺寸 |
|
||||
| 查找多个元素 | `page_getElements` | CSS 选择器数组 |
|
||||
| 点击元素 | `element_tap` | CSS 选择器定位后点击 |
|
||||
| 输入文本 | `element_input` | CSS 选择器 + 值 |
|
||||
| 读取组件数据 | `element_getData` | 获取自定义组件的 data |
|
||||
| 设置组件数据 | `element_setData` | 修改自定义组件的 data |
|
||||
| 读取页面数据 | `page_getData` | 获取当前页面 data 对象 |
|
||||
| 设置页面数据 | `page_setData` | 修改当前页面 data |
|
||||
| 调用页面方法 | `page_callMethod` | 调用当前页面上暴露的方法 |
|
||||
| 等待元素出现 | `page_waitElement` | 轮询等待选择器匹配 |
|
||||
|
||||
### 6.4 绕过微信登录
|
||||
|
||||
MCP 无法模拟微信 OAuth，需要通过 `mp_callWx` 直接写入加密 auth 数据：
|
||||
|
||||
```
|
||||
1. 调用后端 API 获取 admin token:
|
||||
POST /api/v1/auth/login { username: "admin", password: "Admin@2026" }
|
||||
|
||||
2. 用 CryptoJS.AES.encrypt(token, ENC_KEY) 加密
|
||||
|
||||
3. 通过 mp_callWx 写入 storage:
|
||||
setStorageSync("access_token", encrypted_token)
|
||||
setStorageSync("refresh_token", encrypted_refresh)
|
||||
setStorageSync("user_data", encrypted_user_json)
|
||||
setStorageSync("user_roles", encrypted_roles_json)
|
||||
setStorageSync("tenant_id", encrypted_tenant_id)
|
||||
setStorageSync("current_patient", patient_object)
|
||||
setStorageSync("current_patient_id", patient_id)
|
||||
|
||||
4. reLaunch 到首页
|
||||
```
|
||||
|
||||
**ENC_KEY**: `0a17b71d46064b06f993c9c202b342425e311a79f5be026d830562e7ad51f522`
|
||||
|
||||
> ⚠️ 注意：写完 storage 后必须立即 reLaunch，否则 app 的 API 请求会因 token 无效触发 401 → logout 清空 storage。
|
||||
|
||||
### 6.5 TabBar 页面列表
|
||||
|
||||
以下页面是 TabBar 页面，必须用 `switchTab` 导航（不能用 `navigateTo`）：
|
||||
|
||||
- `pages/index/index` — 首页
|
||||
- `pages/health/index` — 健康数据
|
||||
- `pages/consultation/index` — 咨询
|
||||
- `pages/mall/index` — 积分商城
|
||||
- `pages/profile/index` — 个人中心
|
||||
|
||||
### 6.6 已知限制
|
||||
|
||||
| 问题 | 原因 | 替代方案 |
|
||||
|------|------|----------|
|
||||
| **mp_screenshot 超时** | `miniprogram-automator` 的 `screenshot()` 方法在当前 DevTools 版本卡死 | 用 `page_getElement` + `page_getData` 获取 UI 状态 |
|
||||
| **navigateTo 超时** | 某些页面的 API 调用阻塞了页面渲染回调 | 页面实际已加载，用 `mp_currentPage` 确认路径 |
|
||||
| **auth 重定向** | app 的 request interceptor 检测 401 后自动跳转 login 并清空 storage | 确保 token 有效，reLaunch 后等待足够时间 |
|
||||
| **getStorageSync 返回空** | reLaunch 触发 app 初始化，401 → logout 清空了 storage | 检查 token 是否过期，必要时重新注入 |
|
||||
|
||||
### 6.7 端到端验证脚本
|
||||
|
||||
`apps/miniprogram/e2e-final.cjs` 使用 `miniprogram-automator` Node.js 库执行完整链路验证：
|
||||
|
||||
- 11 条 UI 链路（页面导航 + 元素交互）
|
||||
- 10 个 API 数据闭环验证
|
||||
- 加密 storage 注入绕过微信登录
|
||||
- 超时保护避免卡死
|
||||
|
||||
运行：`cd apps/miniprogram && node e2e-final.cjs`
|
||||
|
||||
## 7. 变更记录
|
||||
|
||||
| 日期 | 变更 |
|
||||
|------|------|
|
||||
| 2026-04-27 | 新增 §6 MCP 联调章节：连接、操作列表、绕过登录、已知限制、e2e 脚本 |
|
||||
| 2026-04-26 | 全面更新：40 页面（含 9 个医护端页面）、15 目录、5 个 Tab 页、积分商城、线下活动 |
|
||||
| 2026-04-25 | 全面更新：20 页面、10 服务、9 组件、Zod 验证、加密密钥外部化说明 |
|
||||
| 2026-04-24 | 创建小程序 wiki 页面，记录登录流程、环境配置、历史陷阱 |
|
||||
|
||||
Reference in New Issue
Block a user