@creatoria/miniapp-mcp 0.2.0 → 0.2.3

package/docs/current/03-connect-screenshot-timeout-diagnosis.md

@@ -0,0 +1,168 @@
+# 连接 / 截图超时问题诊断与优化方案
+
+> 版本: 1.0.0
+> 日期: 2026-05-31
+> 状态: 🔍 诊断完成，待修复
+
+## 0. 调研结论速览（TL;DR）
+
+| 任务 | 结论 |
+|------|------|
+| **1. 代码是否需要更新以适配小程序 CLI** | ⚠️ 需要少量更新。SDK `miniprogram-automator@0.12.1` 是当前最新可用版本，CLI 路径/端口适配本身没问题，但 **launch 传入的 `timeout` 参数 SDK 内部根本没使用**，connect 的 `wsEndpoint` 在不传 port 时传了 `undefined` 会触发 SDK 异常路径。 |
+| **2. 修复现有超时问题** | 🔴 必须修复。**根因是 `connect`/`launch` 两个 handler 完全没有超时/重试保护**，连接超时卡死的概率最高；截图虽已有保护，但 `withTimeout` 实现有「超时后底层 promise 不取消」的泄漏缺陷。 |
+
+---
+
+## 1. 问题现象
+
+- 调用 `automator_connect` / `automator_launch` 经常卡住无响应，最终 MCP 调用超时
+- 调用 `miniprogram_screenshot`（尤其 `fullPage`）偶发卡顿
+- 卡死后后续工具调用全部被阻塞
+
+---
+
+## 2. 根因分析（基于 SDK 源码逐行确认）
+
+### 2.1 🔴 P0：connect / launch 无任何超时保护（连接卡死的主因）
+
+**位置**：
+- `src/capabilities/automator/handlers/connect.ts:47`
+- `src/capabilities/automator/handlers/launch.ts:58`
+
+两个 handler 都是直接 `await automator.connect()/launch()`，**没有 `withTimeout` 也没有 `withRetry`**，与 screenshot/evaluate 的保护策略不一致。
+
+#### SDK connect 内部行为（`node_modules/miniprogram-automator/out/Launcher.js` + `Connection.js`）
+
+```
+connect(opts) → connectTool(opts) → Connection.create(wsEndpoint) → new ws(endpoint)
+```
+
+`Connection.create` 仅 `new ws(e)` 并监听 `open`，**没有连接超时**。
+当出现以下情况时，`new ws()` 会永久挂起、既不 resolve 也不 reject：
+- 端口可达（TCP 层通），但 DevTools 未开启「CLI/HTTP 调用」
+- DevTools 进程假死 / 自动化端口被占用但无响应
+- 防火墙吞包（SYN 通、握手后无数据）
+
+→ **这是「连接经常超时」的根因**：超时不是发生在我们这层，而是 SDK 的 WebSocket 永远不返回，MCP 层只能等到上游（MCP client）整体超时。
+
+#### SDK launch 内部行为（已逐行核验 Launcher.js + licia/waitUntil.js）
+
+```
+launch() → spawn(cli) → waitUntil(condition, timeout=30s, interval=1s) → checkVersion() → sleep(5000) → 返回
+```
+
+condition 内部：`p(spawn error) || f(exit+15s 超时标志) || (d = await connectTool({wsEndpoint:'ws://127.0.0.1:'+port}))`
+
+**关键缺陷（决定性）**：`licia/waitUntil` 的超时判断 `elapsed >= timeout` **只在 condition() 这个 Promise resolve 之后**才执行：
+
+```js
+evalCondition().then(function(val){
+  var elapsed = now() - startTime
+  if (val) resolve(val)
+  else if (timeout && elapsed >= timeout) reject(...)  // ← 只有 condition 返回后才走到
+  else setTimeout(pollCondition, interval)
+}, reject)
+```
+
+而 condition 里 `await connectTool()` → `Connection.create()` → `new ws()`。**端口通但 DevTools 无响应时 `new ws()` 永不 resolve → condition() 永不返回 → 30s 超时判断永远执行不到 → launch 永久挂死。SDK 的 30s `timeout` 在最常见故障场景下完全失效。**
+
+- `ILaunchOptions.timeout`（默认 `3e4`）**确实被用作 waitUntil 的总超时**（我初版误判为"未引用"，此处已纠正）；但因上面缺陷，它只在「CLI 进程起不来 / 端口轮询返回 false」时生效，对「ws 挂起」无效
+- CLI 进程 `exit` 后再过 **15s** 才把 `f=!0` 置位（仅覆盖进程崩溃场景）
+- 因此 **launch 与 connect 共享同一根因**：都死在 `Connection.create` 那个无超时的 `new ws()`
+
+### 2.2 🟠 P1：`withTimeout` 超时后底层 promise 不取消（资源泄漏 + 误导性日志）
+
+**位置**：`src/runtime/timeout/timeout.ts:20-44`
+
+```typescript
+const result = await Promise.race([promise, timeoutPromise])
+```
+
+`Promise.race` 在超时时只是让外层 race 出结果，**底层 SDK 调用仍在继续运行**。后果：
+1. SDK `Connection` 内部用自增 `id` 累积 pending callback（`Connection.js:30,46`），超时后这些 callback 永不清理 → 内存泄漏
+2. 截图重试时，上一次「超时」的截图请求其实还在跑，与重试请求并发，**加重 DevTools 负载**，让超时更易复现
+3. `setTimeout` 定时器未 `unref()`，进程退出时可能被 timer 拖住
+
+### 2.3 🟡 P2：connect 的 wsEndpoint 默认值缺陷
+
+**位置**：`src/capabilities/automator/handlers/connect.ts:47-49`
+
+```typescript
+const miniProgram = await automator.connect({
+  wsEndpoint: port ? `ws://localhost:${port}` : undefined,  // ← undefined
+} as any)
+```
+
+`IConnectOptions.wsEndpoint` 是**必填 string**。传 `undefined` 时 SDK 走 `new ws(undefined)`，行为未定义（多数情况立刻抛错或挂起），错误信息也不友好。应在 handler 层兜底默认端口 9420。
+
+### 2.4 🟡 P2：launch 未利用 connectTimeout 配置 + 缺少 connectTimeout 配置项
+
+`SessionConfig` 有 `launchTimeout`/`screenshotTimeout`，但 **没有 `connectTimeout`**，且 launch handler 没有读取 `launchTimeout` 来做外层 race 兜底。
+
+---
+
+## 3. 修复方案
+
+### 3.1 P0：给 connect / launch 加超时 + 重试保护
+
+**connect.ts**：
+- `wsEndpoint` 不传 port 时兜底为 `ws://127.0.0.1:9420`（与 SDK 默认端口一致，用 127.0.0.1 避免 localhost 解析到 IPv6 ::1 导致连不上）
+- 用 `withTimeout` 包裹，默认 `connectTimeout = 30s`
+- 用 `withRetry` 包裹，`maxRetries: 1`，`shouldRetry: onConnectionError`
+
+**launch.ts**：
+- 用 `withTimeout` 包裹，默认 `launchTimeout = 60s`（SDK 内部轮询 + sleep(5s) 较慢，给足余量）
+- 不再依赖 SDK 失效的 `timeout` 参数，改由外层 race 兜底
+- 超时时给出明确指引："请检查 DevTools 是否已打开、自动化端口是否开启"
+
+### 3.2 P1：修复 withTimeout（unref + 可选 onTimeout 清理）
+
+```typescript
+export async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  operation: string
+): Promise<T> {
+  let timeoutId: NodeJS.Timeout
+  const timeoutPromise = new Promise<T>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new Error(`${operation} timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+    // 避免 timer 阻止进程退出
+    if (typeof timeoutId.unref === 'function') timeoutId.unref()
+  })
+  try {
+    return await Promise.race([promise, timeoutPromise])
+  } finally {
+    clearTimeout(timeoutId!)
+  }
+}
+```
+
+> 注：底层 SDK promise 无法真正 abort（SDK 未暴露 cancel），但 `unref` + `finally clearTimeout` 已能消除 timer 泄漏。SDK pending callback 泄漏需 SDK 层支持，列为已知限制。
+
+### 3.3 P2：新增 connectTimeout 配置项
+
+- `types.ts` `SessionConfig` 增加 `connectTimeout?: number`
+- `config/defaults.ts` 增加默认值 30000
+- `config/loader.ts` 支持 `MCP_CONNECT_TIMEOUT` 环境变量
+- `timeout.ts` `DEFAULT_TIMEOUTS.connect` 已存在（30000），复用
+
+---
+
+## 4. 任务 1（适配 CLI）结论详述
+
+`miniprogram-automator@0.12.1` 已是该包目前可用最新版本，对接的是微信开发者工具 CLI（`/Applications/wechatwebdevtools.app/Contents/MacOS/cli`），CLI 接口长期稳定，**不需要为「适配新版 CLI」做大改**。需要做的「代码更新」仅限：
+
+1. launch 应显式传 `timeout`（= launchTimeout），SDK 确实会用它做轮询总超时；但因 SDK ws 挂起缺陷，仍需外层 race 兜底
+2. connect `wsEndpoint` 兜底默认端口（见 3.3），并改用 `127.0.0.1` 与 SDK launch 内部一致（避免 localhost → IPv6 ::1）
+3. 在 handler 层补齐超时/重试（见 3.1），这才是 CLI 交互不稳定时的真正防护
+
+---
+
+## 5. 验证计划
+
+- 单元测试：connect/launch handler 在底层 promise 永不 resolve 时，能在 `connectTimeout/launchTimeout` 内抛出明确错误（用 fake miniProgram + 永挂 promise）
+- 单元测试：`withTimeout` 超时后 timer 被清理（无 open handle）
+- 回归：`pnpm test:unit` 全绿、`pnpm typecheck` 通过
+- 集成（需真机 DevTools）：故意不开自动化端口，确认 connect 在 30s 内失败而非永久挂起

package/docs/current/04-toolchain-version-baseline.md

@@ -0,0 +1,123 @@
+# 工具链版本基线与超时配置说明
+
+> 最后更新: 2026-05-31
+> 版本: 0.3.0 (规划中)
+
+---
+
+## 工具链版本基线
+
+| 组件 | 当前版本 | 状态 | 说明 |
+|------|---------|------|------|
+| miniprogram-automator | 0.12.1 (2023-11-07) | 已停更（约两年半，changelog 停在 0.12.0 / 2022-09） | 自动化能力仍可用，但不会有新特性 |
+| 微信开发者工具 | v2.01.2510260 (2025-10) | 活跃迭代 | 推荐使用最新稳定版 |
+| CLI auto 最低工具版本 | 1.05.2111232 | 最低要求 | 低于此版本不支持 auto 命令 |
+| Node.js | >= 18.0.0 | 必需 | 运行时环境 |
+
+---
+
+## CLI 命令与路径
+
+### 命令格式
+
+```bash
+cli auto --project <path> --auto-port <port> [--auto-account <openid>]
+```
+
+### CLI 路径
+
+**macOS:**
+
+```text
+/Applications/wechatwebdevtools.app/Contents/MacOS/cli
+```
+
+**Windows:**
+
+```text
+<安装路径>/cli.bat
+```
+
+### 启用自动化
+
+在开发者工具中：**设置 → 安全 → 开启 CLI/HTTP 调用**。
+
+默认自动化端口：`9420`。
+
+---
+
+## 超时配置说明
+
+### 配置项一览
+
+| 配置项 | SessionConfig 字段 | 默认值 | 作用范围 |
+|--------|-------------------|--------|---------|
+| 全局操作超时 | `timeout` | 30s | 导航、wait 等通用操作 |
+| JS 执行超时 | `evaluateTimeout` | 5s | evaluate / wx 调用 |
+| 启动超时 | `launchTimeout` | 60s | miniprogram_launch |
+| 连接超时 | `connectTimeout` | 30s | miniprogram_connect |
+| 截图超时 | `screenshotTimeout` | 10s | 普通截图；fullPage 截图基础超时也基于此值 |
+
+### 配置方式
+
+#### 方式一：.mcp.json 配置文件（推荐）
+
+在项目根目录创建 `.mcp.json`，写入超时字段（单位：毫秒）：
+
+```json
+{
+  "projectPath": "/path/to/miniprogram",
+  "cliPath": "/Applications/wechatwebdevtools.app/Contents/MacOS/cli",
+  "port": 9420,
+  "timeout": 30000,
+  "evaluateTimeout": 5000,
+  "launchTimeout": 60000,
+  "connectTimeout": 30000,
+  "screenshotTimeout": 10000,
+  "capabilities": ["core", "assert", "snapshot", "record", "network"]
+}
+```
+
+#### 方式二：CLI 参数
+
+通过命令行参数传递项目路径和端口：
+
+```bash
+npx -y @creatoria/miniapp-mcp --project-path /path/to/miniprogram --port 9420
+```
+
+超时参数可通过配置文件设置。
+
+#### 方式三：环境变量
+
+已确认支持的环境变量：
+
+```bash
+export MCP_PROJECT_PATH=/path/to/miniprogram
+export MCP_PORT=9420
+export MCP_CAPABILITIES=core,assert,snapshot
+```
+
+超时相关配置可通过 `.mcp.json` 配置文件设置。
+
+### 调优建议
+
+- **网络慢 / 真机调试**：适当调大 `connectTimeout` 和 `launchTimeout`，避免连接阶段超时。
+- **fullPage 截图慢**：fullPage 截图需要截取整个页面内容，耗时通常比普通截图更长，可调大 `screenshotTimeout`。
+- **evaluate 执行慢**：如果小程序逻辑复杂，evaluate 可能需要更多时间，可调大 `evaluateTimeout`。
+
+---
+
+## 兼容性与影响
+
+- `miniprogram-automator` SDK 已停更，但现有自动化功能仍然可用，不影响当前项目运行。
+- 微信开发者工具处于活跃迭代中，新版本可能带来协议变化，需关注更新日志。
+- CLI auto 命令要求开发者工具版本 >= 1.05.2111232，低于此版本需先升级。
+
+---
+
+## 相关文档
+
+- [故障排查指南](../troubleshooting.md)
+- [连接与截图超时诊断](./03-connect-screenshot-timeout-diagnosis.md)
+- [微信小程序工具链版本调研](../../调研中/微信小程序工具链最新版本调研/README.md)

package/docs/current/README.md

@@ -0,0 +1,229 @@
+# 当前待实施改动总览
+
+> 最后更新: 2025-12-27
+> 版本: 0.3.0 (规划中)
+
+## 概述
+
+本目录包含两个待实施的改动计划：
+
+1. **架构迁移**：完全使用新架构（capabilities + runtime）
+2. **截图修复**：解决截图超时卡住问题
+
+---
+
+## 改动一览
+
+| 改动 | 类型 | 优先级 | 预计工时 | 文档 |
+|------|------|--------|---------|------|
+| 架构迁移 | 重构 | 高 | 18-25h | [01-architecture-migration.md](./01-architecture-migration.md) |
+| 截图修复 | Bug Fix | 紧急 | 8-9h | [02-screenshot-timeout-fix.md](./02-screenshot-timeout-fix.md) |
+
+---
+
+## 改动一：架构迁移
+
+### 背景
+
+项目当前处于混合架构状态：
+- 运行时服务 (runtime/) 已完成迁移：100%
+- 工具实现 (tools/) 完全未迁移：0%
+- 能力框架 (capabilities/) 仅作为代理：50%
+
+### 目标
+
+将 5,244 行工具代码从 `src/tools/` 迁移到 `src/capabilities/`，实现：
+- 模块化工具组织
+- Schema 驱动的输入验证
+- 动态工具加载
+- 删除旧的 tools/ 和 core/ 目录
+
+### 核心改动
+
+```
+当前结构:                         目标结构:
+src/                              src/
+├── tools/          ❌ 5,244行     ├── capabilities/    🆕 模块化
+│   ├── index.ts    1,645行       │   ├── automator/
+│   ├── automator.ts              │   │   ├── schemas/
+│   ├── miniprogram.ts            │   │   └── handlers/
+│   └── ...                       │   ├── miniprogram/
+├── core/           ❌ 兼容层      │   │   ├── schemas/
+│   └── *.ts        → runtime     │   │   └── handlers/
+└── runtime/        ✅ 保持       │   ├── page/
+                                  │   ├── element/
+                                  │   ├── loader.ts     🆕
+                                  │   └── registry.ts   🆕
+                                  └── runtime/          ✅ 保持
+```
+
+### 工作量
+
+| 阶段 | 内容 | 预计时间 |
+|------|------|---------|
+| Phase 1 | 基础设施（loader/registry） | 3-4h |
+| Phase 2 | Automator 迁移（4工具） | 2-3h |
+| Phase 3 | MiniProgram 迁移（6工具） | 2-3h |
+| Phase 4 | Page 迁移（8工具） | 2-3h |
+| Phase 5 | Element 迁移（23工具） | 3-4h |
+| Phase 6 | Assert/Snapshot/Record/Network | 4-5h |
+| Phase 7 | 清理与测试 | 2-3h |
+| **总计** | - | **18-25h** |
+
+---
+
+## 改动二：截图超时修复
+
+### 问题
+
+`miniprogram_screenshot` 工具调用时经常卡住：
+- 无超时保护：Promise 永不 resolve/reject
+- base64 返回被删除：必须走文件保存路径
+- 级联影响：所有 snapshot 工具都会卡住
+
+### 根本原因
+
+```typescript
+// ❌ 当前代码 - 无超时保护
+const screenshotBuffer = await session.miniProgram.screenshot({
+  path: fullPath,
+  fullPage,
+})
+
+// ✅ 应该使用 withTimeout
+const screenshotBuffer = await withTimeout(
+  session.miniProgram.screenshot({ ... }),
+  timeoutMs,
+  'Screenshot capture'
+)
+```
+
+### 核心改动
+
+1. **P0**：为 screenshot 添加 withTimeout 保护
+2. **P0**：恢复 returnBase64 参数和 base64 返回
+3. **P1**：为其他 miniprogram 操作添加超时
+4. **P1**：添加重试机制
+5. **P2**：优化 fullPage 超时配置
+
+### 工作量
+
+| 任务 | 预计时间 | 优先级 |
+|------|---------|--------|
+| screenshot 超时保护 | 1h | P0 |
+| 恢复 base64 返回 | 1h | P0 |
+| 其他操作超时保护 | 2h | P1 |
+| 重试机制 | 1.5h | P1 |
+| 配置优化 | 1h | P2 |
+| 测试 | 2h | P1 |
+| **总计** | **8-9h** | - |
+
+---
+
+## 建议实施顺序
+
+### 方案 A：先修复后迁移（推荐）
+
+```
+Week 1: 截图修复 (8-9h)
+  ├─ Day 1-2: P0 任务（超时保护 + base64）
+  └─ Day 3-4: P1 任务（其他超时 + 重试）
+
+Week 2-3: 架构迁移 (18-25h)
+  ├─ Day 1: Phase 1（基础设施）
+  ├─ Day 2-3: Phase 2-4（核心工具）
+  ├─ Day 4-5: Phase 5-6（剩余工具）
+  └─ Day 6: Phase 7（清理测试）
+```
+
+**优势**：
+- 先解决紧急问题
+- 迁移时可以同时应用超时保护
+
+### 方案 B：迁移时同步修复
+
+```
+直接进行架构迁移，迁移 miniprogram 工具时顺带修复超时
+```
+
+**优势**：
+- 避免重复修改同一文件
+- 代码只需 review 一次
+
+**劣势**：
+- 紧急问题需要等待更长时间
+
+---
+
+## 文件变更汇总
+
+### 新建文件（约 40 个）
+
+| 目录 | 文件数 | 描述 |
+|------|--------|------|
+| capabilities/*/schemas/ | ~20 | Zod schema 定义 |
+| capabilities/*/handlers/ | ~12 | 工具处理器 |
+| capabilities/ | 3 | loader/registry/index |
+| runtime/retry/ | 2 | 重试机制 |
+| tests/ | 3 | 新增测试 |
+
+### 修改文件（约 10 个）
+
+| 文件 | 改动 |
+|------|------|
+| src/server.ts | 使用新的 capabilities 入口 |
+| src/tools/miniprogram.ts | 添加超时保护（临时，迁移后删除） |
+| src/config/defaults.ts | 新增超时配置 |
+| src/types.ts | 更新类型定义 |
+| tests/**/*.test.ts | 更新导入路径 |
+
+### 删除文件（约 17 个）
+
+| 目录 | 文件数 | 描述 |
+|------|--------|------|
+| src/tools/ | 9 | 全部工具文件 |
+| src/core/ | 8 | 全部兼容层文件 |
+
+---
+
+## 风险评估
+
+| 风险 | 概率 | 影响 | 缓解措施 |
+|------|------|------|---------|
+| 迁移过程中引入 bug | 中 | 高 | 逐阶段提交，完整测试 |
+| 超时时间设置不合理 | 低 | 中 | 配置化，允许用户调整 |
+| 测试覆盖不足 | 低 | 中 | 先补充测试再迁移 |
+| 文档不同步 | 低 | 低 | 同步更新 README |
+
+---
+
+## 验收标准
+
+### 架构迁移
+
+- [ ] 所有 65 个工具迁移到 capabilities/
+- [ ] tools/ 和 core/ 目录删除
+- [ ] 所有工具有 Zod schema
+- [ ] 单元测试 100% 通过
+- [ ] 集成测试通过
+- [ ] TypeScript 编译无错误
+
+### 截图修复
+
+- [ ] 截图 10s 内返回或超时
+- [ ] fullPage 截图 30s 内返回或超时
+- [ ] returnBase64=true 正确返回 base64
+- [ ] 所有 miniprogram 操作有超时保护
+- [ ] 超时测试覆盖
+
+---
+
+## 相关文档
+
+- [01-architecture-migration.md](./01-architecture-migration.md) - 架构迁移详细计划
+- [02-screenshot-timeout-fix.md](./02-screenshot-timeout-fix.md) - 截图修复详细方案
+- [03-connect-screenshot-timeout-diagnosis.md](./03-connect-screenshot-timeout-diagnosis.md) - 连接与截图超时问题诊断
+- [04-toolchain-version-baseline.md](./04-toolchain-version-baseline.md) - 工具链版本基线与超时配置说明
+- [../../调研中/微信小程序工具链最新版本调研/README.md](../../调研中/微信小程序工具链最新版本调研/README.md) - SDK/CLI/开发者工具版本调研
+- [../directory-structure-and-code-style-best-practices.md](../directory-structure-and-code-style-best-practices.md) - 代码规范
+- [../migration/](../migration/) - 历史迁移文档

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@creatoria/miniapp-mcp",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "MCP server for WeChat Mini Program automation using miniprogram-automator",
   "type": "module",
   "packageManager": "pnpm@9.0.0",
@@ -64,7 +64,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
     "commander": "^12.1.0",
-    "miniprogram-automator": "^0.12.1",
+    "miniprogram-automator": "0.12.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {