@creatoria/miniapp-mcp 0.1.0

package/docs//345/256/214/346/225/264/345/256/236/347/216/260/346/226/271/346/241/210.md

@@ -0,0 +1,155 @@
+# 微信小程序 MCP 自动化服务完整实现方案
+
+## 1. 背景与目标
+- 将微信官方自动化 SDK（`miniprogram-automator`）包装为符合 Model Context Protocol (MCP) 的服务，供各类 LLM / Agent 以自然语言编排端到端测试与运维流程。
+- 参考 `playwright-mcp` 的成熟实践，形成工具粒度清晰、配置灵活、可观测性良好的工程体系。
+- 保持与需求文档、《微信小程序自动化 API 完整文档》一致的能力覆盖，同时吸收 Playwright MCP 的上下文管理、能力开关、自动文档等工程手段。
+
+## 2. 总体架构
+```
+[LLM Host / IDE / Agent] ⇄ MCP Transport (stdio / SSE / HTTP)
+        │
+        ▼
+[MCP Server: miniprogram-mcp]
+        │  ├─ 工具 (Tools) Registry & Schema
+        │  ├─ Session / Context Store
+        │  └─ Output 管理 (日志 / 截图 / 数据快照)
+        ▼
+[微信开发者工具 CLI] ⇄ [miniprogram-automator]
+        │
+        ▼
+[本地小程序项目]
+```
+- MCP Server 负责解析工具调用、维护会话状态、调度 `miniprogram-automator` 与 IDE 自动化端口。
+- 会话上下文仿照 Playwright MCP：懒加载启动 IDE、持有 MiniProgram/Page/Element 句柄、统一回收资源。
+- 支持多 Host 并发接入，通过 MCP sessionId 隔离状态。
+
+## 3. MCP 服务设计
+### 3.1 运行流程
+1. Host 建立 MCP 连接（默认 stdio，可选 HTTP 端口模式）。
+2. `launch`/`connect` 工具唤起开发者工具 CLI，创建 `MiniProgram` 句柄并缓存至 `SessionStore`。
+3. 之后的工具调用显式传参（pagePath、selector、refId 等），服务端根据 ElementRef 解析具体对象并执行 automator API。
+4. 每次调用输出结构化结果（状态、数据、产物路径），可选附带审计信息（日志、截图、页面数据）。
+
+### 3.2 Session / Context 管理
+- `SessionState` (per MCP session)：
+  - `miniProgram`: automator 返回的实例。
+  - `ideProcess`: CLI 进程/端口信息。
+  - `pages`: 已打开页面堆栈。
+  - `elements`: refId → Element 缓存（页面切换后自动失效）。
+  - `outputs`: 当次会话的截图/数据快照目录。
+- 生命周期：首次请求创建，`miniProgram.close` 或会话断开时释放；异常时触发兜底清理。
+- 参考 Playwright 的 Context：加入 `outputFile()`、`log()`、`lookupSecret()` 等辅助方法以统一产物写入和敏感信息保护。
+
+### 3.3 工具体系
+- **Automator 级**：`launch`、`connect`、`disconnect`、`close`。
+- **MiniProgram 级**：导航（`navigate_to`/`redirect_to`/`switch_tab`/...）、系统信息、`call_wx_method`、`mock_wx_method`、`evaluate`、`screenshot`、`page_scroll_to`、`test_accounts` 等。
+- **Page 级**：`wait_for`、`query`/`query_all`、`xpath` 系列、`data`/`set_data`、`call_method`、`size`、`scroll_top`。
+- **Element 级**：`text`、`attribute`、`value`、`property`、`style`、`tap`、`longpress`、`trigger`、`touch*`、子类专属（`input`、`scroll_to`、`swipe_to`、`move_to`、`slider_slide_to`、`context_call`、`custom_set_data` 等）。
+- **扩展工具**（对标 Playwright capabilities）：
+  - `snapshot_page`（结构化 DOM 报文）；
+  0  `assert` 系列（exists/text/data 等）；
+  - `record_actions` / `replay_actions`；
+  - `storage_get/set/clear`；
+  - `network_mock`（基于 `mockWxMethod` 或注入脚本）；
+  - `capture_artifacts`（一次性导出截图 + 页面数据）。
+- 工具定义：使用 `zod` 构建 schema，统一注册到 `McpServer`，同时驱动 README/文档自动生成（借鉴 `update-readme.js` 的生成逻辑）。
+
+### 3.4 ElementRef 协议
+```ts
+type ElementRef = {
+  refId?: string;          // 已知句柄
+  selector?: string;       // WXML/CSS 选择器
+  xpath?: string;          // XPath 选择器
+  index?: number;          // 多元素选择时的下标
+  pagePath?: string;       // 指定页面
+  save?: boolean;          // 是否缓存句柄并返回新 refId
+};
+```
+- 优先级：`refId` > `xpath` > `selector`；若页面刷新导致失效，自动抛错并提示重新查询。
+- 解析成功后按需缓存，类似 Playwright 的 `Tab` 对象管理。
+
+## 4. API 映射策略
+- 对照《微信小程序自动化 API 完整文档》，确保 MiniProgram/Page/Element 方法全部可通过工具触达。
+- 未覆盖场景（如自定义函数调用、复杂数据注入）通过 `evaluate`、`expose_function`、`call_wx_method` 提供兜底能力。
+- 断言与快照基于页面数据 (`page.data`) 与元素属性构建，兼容 wx 数据绑定场景。
+
+## 5. 配置体系
+### 5.1 配置来源
+1. **CLI 参数**（与 Playwright 对齐）：项目路径、CLI 路径、自动化端口、headless、输出目录、超时、能力开关等。
+2. **配置文件**：JSON/TS（通过 `--config` 指定），可嵌套定义项目列表、默认页面、Mock 脚本、Secrets。
+3. **环境变量**：用于注入敏感信息（token、账号），配合 `lookupSecret` 管理。
+
+### 5.2 优先级与解析
+- 实现 `resolveConfig`: 默认配置 ← 配置文件 ← 环境变量 ← CLI Overrides。
+- 默认配置示例：
+  - `project.projectPath`: 当前工作目录。
+  - `timeouts`: action=5s / navigation=30s。
+  - `outputDir`: `.mcp-artifacts/{session}`。
+  - `capabilities`: `['core']`。
+- 支持多项目：`projects[].name + projectPath + custom launch options`，LLM 可通过 `launch` 的 `project` 字段选择。
+
+### 5.3 能力开关 (Capabilities)
+| Capability | 说明 | 依赖 |
+|------------|------|------|
+| `core` | 基础导航、查询、交互工具 | 必选 |
+| `assert` | 启用断言工具 | 数据比对模块 |
+| `snapshot` | 页面结构化快照 + 截图 | `snapshot_page`、`capture_artifacts` |
+| `record` | 录制/回放工具 | Action Recorder 存储 |
+| `network` | `mock_wx`、`mock_plugin_wx` 扩展 | 注入脚本/Mock 配置 |
+| `tracing` | 每会话生成行为日志（对应 Playwright trace 思路） | 输出目录 |
+| `vision` | 未来支持坐标/截图分析（可选） | 视觉模型/IDE 截图 |
+
+## 6. 输出与观测
+- **日志**：
+  - 控制台输出结构化 JSON（tool、duration、result），便于 Host 呈现。
+  - 可选写入 `session.log`，仿照 Playwright 的 `SessionLog`。
+- **产物**：
+  - 截图：`miniProgram.screenshot`；失败时自动抓取。
+  - 页面数据快照：`page.data()` + 元素树；断言失败时附带 diff。
+  - 动作录制：按工具调用序列生成 JSON。
+- **统计**：收集工具耗时、失败率，通过 CLI 参数启用。
+
+## 7. 开发与测试流程
+1. **环境准备**：安装微信开发者工具、开启 CLI/HTTP 调用；安装 Node 18+；`npm i` 安装依赖。
+2. **本地开发**：
+   - `npm run dev` 使用 ts-node 运行；
+   - 可通过 MCP Inspector / Claude Desktop 连接测试。
+3. **自动化测试**：
+   - 单元：针对 ElementRef 解析、配置解析编写 Jest/TS 测试。
+   - 集成：使用示例小程序项目 + CI Runner（macOS/Windows）跑回归脚本。
+   - 参考 Playwright 的 `playwright test` 实践，构建 `tests/` 用例驱动 CLI。
+4. **CI/CD**：
+   - 采用 GitHub Actions/Moore pipeline：
+     1. 安装依赖与微信 IDE（或缓存）；
+     2. 启动虚拟 display（macOS Runner 不需要 xvfb）；
+     3. 执行自动化脚本；
+     4. 上传日志/截图/快照为工件。
+   - 发布：`npm publish` 前运行 `npm run roll` 同步类型与文档。
+
+## 8. 安全与稳定
+- 限制工具对文件系统操作：`outputDir` 白名单。
+- 针对 `evaluate/inject` 建立白名单或沙箱，避免越权访问宿主机。
+- 会话超时与 watchdog：长期未活动自动关闭 IDE。
+- 断言/操作前增加 `page.waitFor`/`wait_for_selector`，减少竞态失败。
+
+## 9. 与 Playwright MCP 的对齐点
+- **工具 Schema 自动生成文档**：实现 `docs/update-readme.ts`，遍历工具注册，输出参数说明。
+- **能力分层**：使用 `capabilities` 控制高级功能开启，与 CLI `--caps` 对齐。
+- **上下文复用**：提供 `sharedMiniProgram` 模式，支持多个会话共享 IDE（类似 `SharedContextFactory`）。
+- **产物输出**：仿照 trace/video，提供统一的 `artifacts/` 目录结构：`screenshots/`、`snapshots/`、`actions.json`。
+
+## 10. 交付物与后续路线
+- **最小可用版本 (MVP)**：
+  - 实现 `core` 能力工具集；
+  - 支持 CLI 启动 + 配置文件；
+  - 提供示例脚本与使用文档。
+- **增强路线**：
+  1. 断言 DSL / 测试报告可视化；
+  2. 多端兼容（真机云测、远程调试接入）；
+  3. 与团队测试平台集成（结果上报、用例管理）；
+  4. 选择器智能推荐（结合页面结构快照与静态标记 `data-testid`）；
+  5. 结合 Playwright Vision 能力扩展到混合 H5 场景。
+
+---
+该方案汇总了需求文档的能力诉求、API 覆盖范围，以及 Playwright MCP 的工程实现方式，可作为后续开发与评审的基准文档。

package/docs//345/274/200/345/217/221/344/273/273/345/212/241/350/256/241/345/210/222.md

@@ -0,0 +1,110 @@
+# 微信小程序 MCP 实现任务拆解与计划
+
+## 阶段划分总览
+1. **环境与基础设施准备**（Stage A）
+2. **核心框架搭建**（Stage B）
+3. **核心工具实现**（Stage C）
+4. **高级能力与能力开关**（Stage D）
+5. **配置体系与 CLI 集成**（Stage E）
+6. **可观测性与产物输出**（Stage F）
+7. **测试验证与示例沉淀**（Stage G）
+8. **发布与维护流程**（Stage H）
+
+每个阶段的任务相互依赖：Stage A → B → C → D/E → F → G → H。可在资源许可时并行推进部分子任务（例如 Stage D 与 E）。
+
+---
+
+## Stage A：环境与基础设施准备
+| 编号 | 子任务 | 产出 | 依赖 |
+|------|--------|------|------|
+| A1 | 安装 Node 18+、微信开发者工具 CLI、miniprogram-automator 示例项目 | 已配置的开发环境说明 | - |
+| A2 | 配置 IDE 自动化端口（CLI/HTTP）并编写启动脚本 | `scripts/launch-wx-devtool.sh` / 指南文档 | A1 |
+| A3 | 建立基础目录结构（`src/`, `docs/`, `tests/`, `examples/`）与 TypeScript 工程 | 初始仓库结构、`tsconfig.json`, `package.json` | A1 |
+| A4 | 搭建 lint / format / commit hooks（可选） | ESLint/Prettier 配置 | A3 |
+
+## Stage B：核心框架搭建
+| 编号 | 子任务 | 产出 | 依赖 |
+|------|--------|------|------|
+| B1 | 实现 MCP Server 启动骨架：`McpServer` + `StdioServerTransport` | `src/server.ts` 可运行 | A3 |
+| B2 | Session 管理：`SessionStore`、上下文生命周期、资源清理 | `src/session.ts` | B1 |
+| B3 | ElementRef 解析器定义与缓存机制 | `src/elementResolver.ts` | B2 |
+| B4 | 输出/日志接口定义（供后续阶段使用） | `src/logger.ts`, `src/output.ts` | B2 |
+
+## Stage C：核心工具实现
+| 编号 | 子任务 | 产出 | 依赖 |
+|------|--------|------|------|
+| C1 | Automator 级工具：`launch`、`connect`、`disconnect`、`close` | `src/tools/automator.ts` | B1 |
+| C2 | MiniProgram 级工具（导航、callWx、evaluate、screenshot 等） | `src/tools/miniProgram.ts` | C1 |
+| C3 | Page 级工具（wait/query/xpath/data 等） | `src/tools/page.ts` | C2 |
+| C4 | Element 级工具（属性/交互/子类方法） | `src/tools/element.ts` | C3 |
+| C5 | 工具注册器：统一加载 Zod schema、生成工具列表 | `src/tools/index.ts` | C1–C4 |
+
+## Stage D：高级能力与能力开关
+| 编号 | 子任务 | 产出 | 依赖 |
+|------|--------|------|------|
+| D1 | 断言工具集（`assert.exists/text/data`） | `src/tools/assert.ts` | C2–C4 |
+| D2 | 快照能力：页面结构化数据 + 截图封装 | `src/tools/snapshot.ts`, 产物目录结构 | B4,C2 |
+| D3 | 录制/回放与动作序列管理 | `src/tools/record.ts` | B4,C2 |
+| D4 | 网络 Mock / wx.request 注入工具 | `src/tools/network.ts` | C2 |
+| D5 | Capabilities 机制：解析 `--caps`、按能力注册工具 | `src/capabilities.ts` | B1, C5 |
+
+## Stage E：配置体系与 CLI 集成
+| 编号 | 子任务 | 产出 | 依赖 |
+|------|--------|------|------|
+| E1 | 默认配置定义 + config schema | `src/config/defaults.ts` | B2 |
+| E2 | `resolveConfig`：合并配置文件、环境变量、CLI 参数 | `src/config/loader.ts` | E1 |
+| E3 | CLI 接入（命令行选项解析、帮助信息） | `src/cli.ts` | E2 |
+| E4 | 配置文件模板与示例（JSON / YAML / TOML 自选） | `/examples/config/` | E2 |
+
+## Stage F：可观测性与产物输出
+| 编号 | 子任务 | 产出 | 依赖 |
+|------|--------|------|------|
+| F1 | 结构化日志（tool、耗时、状态） + 控制台输出格式化 | `src/logger.ts` 实现 | B4 |
+| F2 | 失败时自动收集的截图/数据快照 | 与 D2 协作，产物写入 `artifacts/` | D2 |
+| F3 | 会话报告（可选）：生成 JSON/Markdown 汇总 | `artifacts/report.json` | F1,F2 |
+
+## Stage G：测试验证与示例沉淀
+| 编号 | 子任务 | 产出 | 依赖 |
+|------|--------|------|------|
+| G1 | 单元测试：配置解析、ElementRef、工具入参校验 | `tests/unit/**` | B3,E2 |
+| G2 | 集成测试：针对示例小程序跑端到端流程（登录/下单等） | `tests/integration/**` | C1–C4 |
+| G3 | 示例脚本与文档：`examples/`、MCP 客户端使用手册 | `docs/使用指南.md`、脚本 | C1–C5 |
+| G4 | 自动生成工具清单（仿 `update-readme.js`）并更新 README | `scripts/update-readme.ts` | C5,D5 |
+
+## Stage H：发布与维护流程
+| 编号 | 子任务 | 产出 | 依赖 |
+|------|--------|------|------|
+| H1 | CI/CD 流程：GitHub Actions 配置、IDE 安装、测试流水线 | `.github/workflows/*.yml` | A4,G1,G2 |
+| H2 | 版本管理与发布脚本（`npm version`、`npm publish`） | `scripts/release.ts` 或文档 | H1 |
+| H3 | 维护计划：issue 模板、版本路线图、风险登记 | `docs/roadmap.md`, `.github/ISSUE_TEMPLATE` | G4,H1 |
+
+---
+
+## 关键里程碑
+| 里程碑 | 完成标准 | 涉及任务 |
+|---------|-----------|-----------|
+| M1：基础可运行 | Stage B + C1 完成；可 launch/connect 小程序并执行简单操作 | B1–B4, C1 |
+| M2：核心工具完善 | MiniProgram/Page/Element 工具可用，支持基础断言 | C1–C4, D1 |
+| M3：高级能力上线 | Capabilities、快照、录制、配置文件、日志体系完备 | D1–D5, E1–E4, F1–F2 |
+| M4：质量验收 | 测试通过、示例脚本覆盖主流程、文档齐备 | G1–G4 |
+| M5：发布就绪 | CI/CD、发布脚本上线，生成首次版本 | H1–H3 |
+
+---
+
+## 风险与缓解措施
+- **IDE 兼容性/稳定性**：及时跟踪微信开发者工具版本更新；准备至少一个稳定版本镜像。
+- **自动化端口失效**：实现重试与连通性检查；提供诊断工具（CLI 命令）。
+- **元素句柄失效**：ElementRef 解析加入报错提示与重查策略。
+- **CI 环境支持度**：优先在 macOS Runner 验证，如需 Windows/Linux，提供文档说明及备用脚本。
+- **安全问题**：限制 `evaluate/inject` 的可用范围；将敏感凭证放入 secrets 管理。
+
+---
+
+## 建议的推进节奏（示例）
+- 周 1–2：完成 Stage A/B；输出 MVP 骨架。
+- 周 3–4：实现 Stage C 主体；交付 M1/M2。
+- 周 5–6：并行推进 Stage D/E + F；完成高级能力与配置体系。
+- 周 7：集中测试与文档（Stage G），达成 M4。
+- 周 8：建立 CI/CD 并正式发布（Stage H），进入维护阶段。
+
+以上计划可根据团队人力与优先级动态调整。EOF