@creatoria/miniapp-mcp 0.1.2 → 0.2.0

package/docs/tasks.C2.atomize.md

@@ -1,665 +0,0 @@
-# Task Card: [C2] MiniProgram 工具
-
-**Task ID**: C2
-**Task Name**: MiniProgram 工具实现
-**Charter**: `docs/charter.C2.align.yaml`
-**Stage**: C (Tool Implementation)
-**Status**: ✅ COMPLETED (Retrospective)
-**Estimated**: 3-4 hours
-**Actual**: ~4 hours
-**Completed**: 2025-10-02
-
----
-
-## 目标 (Goal)
-
-实现 MiniProgram 级别的 6 个 MCP 工具，封装小程序导航、WX API 调用、代码执行、截图和系统信息获取功能。
-
-**交付物**:
-- ✅ `src/tools/miniprogram.ts` (330 lines)
-- ✅ `tests/unit/miniprogram.test.ts` (403 lines, 25 tests)
-- ✅ 6 个工具: navigate, callWx, evaluate, screenshot, getPageStack, getSystemInfo
-
----
-
-## 前置条件 (Prerequisites)
-
-- ✅ C1: Automator 工具已完成（获取 MiniProgram 实例）
-- ✅ B2: SessionStore 已实现
-- ✅ 了解微信小程序导航机制
-- ✅ 了解微信小程序 API (wx.*)
-
----
-
-## 实现步骤 (Steps)
-
-### 1. 定义工具 Schema ✅
-
-**文件**: `src/tools/miniprogram.ts`
-
-**步骤**:
-```typescript
-import { z } from 'zod'
-
-// 导航方法枚举
-const NavigateMethod = z.enum([
-  'navigateTo',
-  'redirectTo',
-  'navigateBack',
-  'switchTab',
-  'reLaunch',
-])
-
-// navigate 工具 Schema
-const navigateSchema = z.object({
-  sessionId: z.string(),
-  method: NavigateMethod,
-  url: z.string().optional(),
-  delta: z.number().optional(),
-})
-
-// callWx 工具 Schema
-const callWxSchema = z.object({
-  sessionId: z.string(),
-  method: z.string().describe('wx API 方法名，如 showToast'),
-  args: z.record(z.any()).optional(),
-})
-
-// evaluate 工具 Schema
-const evaluateSchema = z.object({
-  sessionId: z.string(),
-  code: z.string().describe('要执行的 JavaScript 代码'),
-})
-
-// screenshot 工具 Schema
-const screenshotSchema = z.object({
-  sessionId: z.string(),
-  path: z.string().optional().describe('截图保存路径'),
-})
-
-// 会话 Schema（用于 getPageStack, getSystemInfo）
-const sessionSchema = z.object({
-  sessionId: z.string(),
-})
-```
-
-**验证**: TypeScript 编译通过，Schema 类型正确
-
----
-
-### 2. 实现 navigate 工具 ✅
-
-**功能**: 支持 5 种小程序导航方法
-
-**代码**:
-```typescript
-async function handleNavigate(args: NavigateArgs, context: ToolContext) {
-  const { sessionId, method, url, delta } = args
-  const session = context.getSession(sessionId)
-
-  if (!session.miniProgram) {
-    throw new Error('MiniProgram not connected')
-  }
-
-  let result
-  switch (method) {
-    case 'navigateTo':
-      result = await session.miniProgram.navigateTo(url!)
-      break
-    case 'redirectTo':
-      result = await session.miniProgram.redirectTo(url!)
-      break
-    case 'navigateBack':
-      result = await session.miniProgram.navigateBack({ delta })
-      break
-    case 'switchTab':
-      result = await session.miniProgram.switchTab(url!)
-      break
-    case 'reLaunch':
-      result = await session.miniProgram.reLaunch(url!)
-      break
-  }
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify({
-          method,
-          url,
-          delta,
-          status: 'success',
-        }, null, 2),
-      },
-    ],
-  }
-}
-```
-
-**验证**:
-- ✅ 支持 5 种导航方法
-- ✅ navigateBack 使用 delta 参数
-- ✅ 其他方法使用 url 参数
-
----
-
-### 3. 实现 callWx 工具 ✅
-
-**功能**: 调用微信小程序 API
-
-**代码**:
-```typescript
-async function handleCallWx(args: CallWxArgs, context: ToolContext) {
-  const { sessionId, method, args: wxArgs = {} } = args
-  const session = context.getSession(sessionId)
-
-  if (!session.miniProgram) {
-    throw new Error('MiniProgram not connected')
-  }
-
-  const result = await session.miniProgram.callWxMethod(method, wxArgs)
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify({
-          method,
-          result,
-        }, null, 2),
-      },
-    ],
-  }
-}
-```
-
-**验证**:
-- ✅ 调用 wx.* API
-- ✅ 传递参数
-- ✅ 返回结果
-
-**示例**:
-```javascript
-// 调用 wx.showToast
-{
-  "method": "showToast",
-  "args": {
-    "title": "操作成功",
-    "icon": "success"
-  }
-}
-```
-
----
-
-### 4. 实现 evaluate 工具 ✅
-
-**功能**: 在小程序环境中执行 JavaScript 代码
-
-**代码**:
-```typescript
-async function handleEvaluate(args: EvaluateArgs, context: ToolContext) {
-  const { sessionId, code } = args
-  const session = context.getSession(sessionId)
-
-  if (!session.miniProgram) {
-    throw new Error('MiniProgram not connected')
-  }
-
-  const result = await session.miniProgram.evaluate(() => {
-    return eval(code)
-  })
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify({
-          code,
-          result,
-        }, null, 2),
-      },
-    ],
-  }
-}
-```
-
-**验证**:
-- ✅ 执行 JS 代码
-- ✅ 返回执行结果
-- ✅ 错误捕获
-
----
-
-### 5. 实现 screenshot 工具 ✅
-
-**功能**: 截取当前页面截图
-
-**代码**:
-```typescript
-async function handleScreenshot(args: ScreenshotArgs, context: ToolContext) {
-  const { sessionId, path } = args
-  const session = context.getSession(sessionId)
-
-  if (!session.miniProgram) {
-    throw new Error('MiniProgram not connected')
-  }
-
-  const timestamp = Date.now()
-  const filename = path || `screenshot-${timestamp}.png`
-  const fullPath = join(session.outputDir, 'screenshots', filename)
-
-  // 确保目录存在
-  await fs.mkdir(dirname(fullPath), { recursive: true })
-
-  await session.miniProgram.screenshot({
-    path: fullPath,
-  })
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify({
-          path: fullPath,
-          timestamp,
-        }, null, 2),
-      },
-    ],
-  }
-}
-```
-
-**验证**:
-- ✅ 生成截图文件
-- ✅ 自动创建目录
-- ✅ 返回文件路径
-
----
-
-### 6. 实现 getPageStack 工具 ✅
-
-**功能**: 获取当前页面栈信息
-
-**代码**:
-```typescript
-async function handleGetPageStack(args: SessionArgs, context: ToolContext) {
-  const { sessionId } = args
-  const session = context.getSession(sessionId)
-
-  if (!session.miniProgram) {
-    throw new Error('MiniProgram not connected')
-  }
-
-  const pages = await session.miniProgram.pageStack()
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify({
-          pages,
-          count: pages.length,
-        }, null, 2),
-      },
-    ],
-  }
-}
-```
-
-**验证**:
-- ✅ 返回所有页面路径
-- ✅ 包含页面数量
-
----
-
-### 7. 实现 getSystemInfo 工具 ✅
-
-**功能**: 获取设备系统信息
-
-**代码**:
-```typescript
-async function handleGetSystemInfo(args: SessionArgs, context: ToolContext) {
-  const { sessionId } = args
-  const session = context.getSession(sessionId)
-
-  if (!session.miniProgram) {
-    throw new Error('MiniProgram not connected')
-  }
-
-  const systemInfo = await session.miniProgram.systemInfo()
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify(systemInfo, null, 2),
-      },
-    ],
-  }
-}
-```
-
-**验证**:
-- ✅ 返回系统信息对象
-- ✅ 包含平台、版本、屏幕等信息
-
----
-
-### 8. 编写单元测试 ✅
-
-**文件**: `tests/unit/miniprogram.test.ts`
-
-**测试用例** (25 个):
-```typescript
-describe('MiniProgram Tools', () => {
-  describe('navigate', () => {
-    it('should navigateTo with url', async () => {})
-    it('should redirectTo with url', async () => {})
-    it('should navigateBack with delta', async () => {})
-    it('should switchTab to tabBar page', async () => {})
-    it('should reLaunch with url', async () => {})
-    it('should throw error if MiniProgram not connected', async () => {})
-    it('should handle navigation failure', async () => {})
-  })
-
-  describe('callWx', () => {
-    it('should call wx method with args', async () => {})
-    it('should call wx method without args', async () => {})
-    it('should return wx method result', async () => {})
-    it('should handle wx method error', async () => {})
-  })
-
-  describe('evaluate', () => {
-    it('should evaluate simple code', async () => {})
-    it('should evaluate with return value', async () => {})
-    it('should handle evaluate error', async () => {})
-    it('should support async code', async () => {})
-  })
-
-  describe('screenshot', () => {
-    it('should take screenshot with custom path', async () => {})
-    it('should take screenshot with auto-generated name', async () => {})
-    it('should create screenshot directory', async () => {})
-    it('should handle screenshot failure', async () => {})
-  })
-
-  describe('getPageStack', () => {
-    it('should return page stack', async () => {})
-    it('should return page count', async () => {})
-    it('should handle empty stack', async () => {})
-  })
-
-  describe('getSystemInfo', () => {
-    it('should return system info', async () => {})
-    it('should include platform', async () => {})
-    it('should include screen size', async () => {})
-  })
-})
-```
-
-**验证**:
-- ✅ 25 个测试全部通过
-- ✅ Mock MiniProgram 实例
-- ✅ 覆盖成功和失败场景
-
----
-
-## 完成标准 (Definition of Done)
-
-### 功能完成 ✅
-
-- [x] navigate 支持 5 种导航方法
-- [x] callWx 调用微信 API 成功
-- [x] evaluate 执行 JS 代码
-- [x] screenshot 生成截图文件
-- [x] getPageStack 返回页面栈
-- [x] getSystemInfo 返回系统信息
-
-### 代码质量 ✅
-
-- [x] TypeScript 编译 0 错误
-- [x] 无 ESLint 错误
-- [x] 代码行数 330 行（合理范围）
-- [x] JSDoc 注释完整
-- [x] 符合 ESM 规范（.js 后缀）
-
-### 测试 ✅
-
-- [x] 单元测试 403 行
-- [x] 25 个测试用例全部通过
-- [x] 覆盖所有导航方法
-- [x] Mock 外部依赖
-
-### 文档 ⏳
-
-- [x] 代码注释完整
-- [x] Schema 描述清晰
-- ⏳ charter.C2.align.yaml (追溯)
-- ⏳ tasks.C2.atomize.md (本文档)
-
----
-
-## 实现结果 (Implementation)
-
-### 文件清单
-
-| 文件 | 行数 | 说明 |
-|------|------|------|
-| `src/tools/miniprogram.ts` | 330 | 6 个 MiniProgram 工具实现 |
-| `tests/unit/miniprogram.test.ts` | 403 | 25 个单元测试 |
-
-### 工具列表
-
-| 工具名 | 功能 | 输入 | 输出 |
-|--------|------|------|------|
-| `miniapp_miniprogram_navigate` | 页面导航 | sessionId, method, url?, delta? | status |
-| `miniapp_miniprogram_callWx` | 调用 wx API | sessionId, method, args? | result |
-| `miniapp_miniprogram_evaluate` | 执行 JS 代码 | sessionId, code | result |
-| `miniapp_miniprogram_screenshot` | 截取页面截图 | sessionId, path? | path, timestamp |
-| `miniapp_miniprogram_getPageStack` | 获取页面栈 | sessionId | pages, count |
-| `miniapp_miniprogram_getSystemInfo` | 获取系统信息 | sessionId | systemInfo |
-
-### 导航方法
-
-| 方法 | 说明 | 参数 | 限制 |
-|------|------|------|------|
-| `navigateTo` | 跳转到新页面 | url | 最多 10 层 |
-| `redirectTo` | 重定向页面 | url | 关闭当前页面 |
-| `navigateBack` | 返回上一页 | delta | 不能超过当前层级 |
-| `switchTab` | 切换 tabBar | url | 仅限 tabBar 页面 |
-| `reLaunch` | 重启到页面 | url | 关闭所有页面 |
-
-### 设计决策
-
-1. **导航方法枚举**
-   - 使用 zod.enum 定义 5 种方法
-   - 理由：类型安全，自动校验
-
-2. **截图路径管理**
-   - 默认路径: `{outputDir}/screenshots/`
-   - 文件名: `screenshot-{timestamp}.png`
-   - 理由：避免文件冲突，便于管理
-
-3. **evaluate 安全性**
-   - 在小程序环境中执行
-   - 理由：隔离安全风险
-
-4. **错误处理**
-   - 明确检查 MiniProgram 实例
-   - 理由：防止空指针错误
-
----
-
-## 测试证据 (Test Evidence)
-
-### 单元测试结果
-
-```bash
-$ pnpm test miniprogram.test.ts
-
-PASS tests/unit/miniprogram.test.ts
-  MiniProgram Tools
-    navigate
-      ✓ should navigateTo with url (12ms)
-      ✓ should redirectTo with url (8ms)
-      ✓ should navigateBack with delta (9ms)
-      ✓ should switchTab to tabBar page (7ms)
-      ✓ should reLaunch with url (8ms)
-      ✓ should throw error if MiniProgram not connected (5ms)
-      ✓ should handle navigation failure (6ms)
-    callWx
-      ✓ should call wx method with args (10ms)
-      ✓ should call wx method without args (7ms)
-      ✓ should return wx method result (8ms)
-      ✓ should handle wx method error (6ms)
-    evaluate
-      ✓ should evaluate simple code (11ms)
-      ✓ should evaluate with return value (9ms)
-      ✓ should handle evaluate error (7ms)
-      ✓ should support async code (10ms)
-    screenshot
-      ✓ should take screenshot with custom path (13ms)
-      ✓ should take screenshot with auto-generated name (12ms)
-      ✓ should create screenshot directory (9ms)
-      ✓ should handle screenshot failure (7ms)
-    getPageStack
-      ✓ should return page stack (8ms)
-      ✓ should return page count (7ms)
-      ✓ should handle empty stack (6ms)
-    getSystemInfo
-      ✓ should return system info (9ms)
-      ✓ should include platform (7ms)
-      ✓ should include screen size (8ms)
-
-Test Suites: 1 passed, 1 total
-Tests:       25 passed, 25 total
-Time:        3.125s
-```
-
-### 手动测试
-
-**导航到新页面**:
-```bash
-# 通过 MCP 调用 navigate
-{
-  "sessionId": "xxx",
-  "method": "navigateTo",
-  "url": "/pages/detail/detail"
-}
-
-# 返回
-{
-  "method": "navigateTo",
-  "url": "/pages/detail/detail",
-  "status": "success"
-}
-```
-
-**调用微信 API**:
-```bash
-# 通过 MCP 调用 callWx
-{
-  "sessionId": "xxx",
-  "method": "showToast",
-  "args": {
-    "title": "操作成功",
-    "icon": "success"
-  }
-}
-
-# 返回
-{
-  "method": "showToast",
-  "result": { "errMsg": "showToast:ok" }
-}
-```
-
-**截取页面截图**:
-```bash
-# 通过 MCP 调用 screenshot
-{
-  "sessionId": "xxx"
-}
-
-# 返回
-{
-  "path": "/path/to/output/screenshots/screenshot-1696234567890.png",
-  "timestamp": 1696234567890
-}
-```
-
----
-
-## 已知问题 (Known Issues)
-
-### 技术债务
-
-1. **截图文件管理** - 🟢 低优先级
-   - 原因：未实现自动清理机制
-   - 影响：长期运行可能占用大量磁盘
-   - 计划：用户自行管理或添加清理工具
-
-2. **evaluate 安全性** - 🟡 中优先级
-   - 原因：可执行任意代码
-   - 影响：潜在安全风险
-   - 计划：添加代码沙箱或白名单
-
-### 风险
-
-1. **导航时序** - 🟡 中风险
-   - 缓解：使用 await 等待导航完成
-   - 监控：测试中验证页面加载状态
-
----
-
-## 参考资料 (References)
-
-### 文档
-
-- `docs/charter.C2.align.yaml` - 任务对齐文档
-- `docs/微信小程序自动化完整操作手册.md` - MiniProgram API 参考
-- 微信小程序官方文档 - 导航 API
-
-### 代码
-
-- `src/tools/automator.ts` - Automator 工具（C1）
-- `src/core/session.ts` - Session 管理
-- `src/tools/index.ts` - 工具注册器（C5）
-
-### 外部资源
-
-- [miniprogram-automator MiniProgram API](https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/miniprogram.html)
-- [微信小程序导航 API](https://developers.weixin.qq.com/miniprogram/dev/api/route/wx.navigateTo.html)
-
----
-
-## 后续任务 (Next Steps)
-
-### 依赖此任务的后续任务
-
-- ✅ C3: Page 工具（需要先导航到页面）
-- ✅ C4: Element 工具（需要 Page 实例）
-- ✅ C5: 工具注册器（集成 MiniProgram 工具）
-
-### 改进建议
-
-1. **导航历史管理**
-   - 记录导航历史
-   - 支持前进/后退
-
-2. **截图增强**
-   - 支持元素截图
-   - 支持多种格式（JPEG, WebP）
-   - 支持压缩和质量调节
-
-3. **evaluate 增强**
-   - 添加代码沙箱
-   - 支持 TypeScript
-   - 提供代码提示
-
----
-
-**任务状态**: ✅ COMPLETED
-**代码提交**: ✅ 已提交（Stage C 提交）
-**文档状态**: ⏳ RETROSPECTIVE (追溯补齐中)