@creatoria/miniapp-mcp 0.1.3 → 0.2.0

package/docs/tasks.C3.atomize.md

@@ -1,745 +0,0 @@
-# Task Card: [C3] Page 工具
-
-**Task ID**: C3
-**Task Name**: Page 工具实现
-**Charter**: `docs/charter.C3.align.yaml`
-**Stage**: C (Tool Implementation)
-**Status**: ✅ COMPLETED (Retrospective)
-**Estimated**: 3-4 hours
-**Actual**: ~4 hours
-**Completed**: 2025-10-02
-
----
-
-## 目标 (Goal)
-
-实现 Page 级别的 8 个 MCP 工具，封装页面元素查询、等待、数据读写、方法调用和页面属性获取功能。
-
-**交付物**:
-- ✅ `src/tools/page.ts` (458 lines)
-- ✅ `tests/unit/page.test.ts` (450 lines, 27 tests)
-- ✅ 8 个工具: query, queryAll, waitFor, getData, setData, callMethod, getSize, getScrollTop
-
----
-
-## 前置条件 (Prerequisites)
-
-- ✅ C2: MiniProgram 工具已完成（导航功能）
-- ✅ B2: SessionStore 已实现
-- ✅ ElementRef 协议设计完成
-- ✅ 了解 WXML 选择器语法
-- ✅ 了解 XPath 查询语法
-
----
-
-## 实现步骤 (Steps)
-
-### 1. 定义 ElementRef Schema ✅
-
-**文件**: `src/tools/page.ts`
-
-**步骤**:
-```typescript
-import { z } from 'zod'
-
-// ElementRef 协议
-const elementRefSchema = z.object({
-  refId: z.string().optional().describe('缓存的元素引用 ID'),
-  selector: z.string().optional().describe('WXML 选择器'),
-  xpath: z.string().optional().describe('XPath 选择器'),
-  index: z.number().optional().describe('多元素索引'),
-  pagePath: z.string().optional().describe('目标页面路径'),
-  save: z.boolean().optional().describe('保存到缓存'),
-})
-
-// query 工具 Schema
-const querySchema = z.object({
-  sessionId: z.string(),
-  elementRef: elementRefSchema,
-})
-
-// queryAll 工具 Schema
-const queryAllSchema = z.object({
-  sessionId: z.string(),
-  selector: z.string().optional(),
-  xpath: z.string().optional(),
-})
-
-// waitFor 工具 Schema
-const waitForSchema = z.object({
-  sessionId: z.string(),
-  elementRef: elementRefSchema,
-  timeout: z.number().optional().default(5000),
-})
-```
-
-**验证**: ElementRef 协议定义清晰
-
----
-
-### 2. 实现元素解析辅助函数 ✅
-
-**功能**: 统一处理 refId/selector/xpath 三种查询方式
-
-**代码**:
-```typescript
-async function resolveElement(
-  session: Session,
-  elementRef: ElementRef
-): Promise<Element> {
-  const { refId, selector, xpath, index, pagePath } = elementRef
-
-  // 获取 Page 实例
-  const page = pagePath
-    ? await session.miniProgram.currentPage()
-    : await session.miniProgram.currentPage()
-
-  // 优先使用 refId
-  if (refId) {
-    const cachedElement = session.elementCache.get(refId)
-    if (cachedElement) {
-      return cachedElement
-    }
-    throw new Error(`Element refId ${refId} not found in cache`)
-  }
-
-  // 使用 selector
-  if (selector) {
-    const element = await page.$(selector)
-    return element
-  }
-
-  // 使用 xpath
-  if (xpath) {
-    const element = await page.$x(xpath)
-    return index !== undefined ? element[index] : element[0]
-  }
-
-  throw new Error('Must provide refId, selector, or xpath')
-}
-```
-
-**验证**:
-- ✅ 支持 refId 缓存查询
-- ✅ 支持 selector 查询
-- ✅ 支持 xpath 查询
-
----
-
-### 3. 实现 query 工具 ✅
-
-**功能**: 单元素查询并支持缓存
-
-**代码**:
-```typescript
-async function handleQuery(args: QueryArgs, context: ToolContext) {
-  const { sessionId, elementRef } = args
-  const session = context.getSession(sessionId)
-
-  const element = await resolveElement(session, elementRef)
-
-  let refId: string | undefined
-  if (elementRef.save) {
-    refId = uuidv4()
-    session.elementCache.set(refId, element)
-  }
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify({
-          refId,
-          selector: elementRef.selector,
-          xpath: elementRef.xpath,
-          found: !!element,
-        }, null, 2),
-      },
-    ],
-  }
-}
-```
-
-**验证**:
-- ✅ 返回元素引用
-- ✅ 可选保存到缓存
-- ✅ 返回 refId
-
----
-
-### 4. 实现 queryAll 工具 ✅
-
-**功能**: 多元素查询
-
-**代码**:
-```typescript
-async function handleQueryAll(args: QueryAllArgs, context: ToolContext) {
-  const { sessionId, selector, xpath } = args
-  const session = context.getSession(sessionId)
-
-  const page = await session.miniProgram.currentPage()
-
-  let elements
-  if (selector) {
-    elements = await page.$$(selector)
-  } else if (xpath) {
-    elements = await page.$x(xpath)
-  } else {
-    throw new Error('Must provide selector or xpath')
-  }
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify({
-          count: elements.length,
-          selector,
-          xpath,
-        }, null, 2),
-      },
-    ],
-  }
-}
-```
-
-**验证**:
-- ✅ 返回元素数量
-- ✅ 支持 selector 和 xpath
-
----
-
-### 5. 实现 waitFor 工具 ✅
-
-**功能**: 等待元素出现
-
-**代码**:
-```typescript
-async function handleWaitFor(args: WaitForArgs, context: ToolContext) {
-  const { sessionId, elementRef, timeout } = args
-  const session = context.getSession(sessionId)
-
-  const page = await session.miniProgram.currentPage()
-
-  const { selector, xpath } = elementRef
-  if (selector) {
-    await page.waitFor(selector, { timeout })
-  } else if (xpath) {
-    await page.waitFor(xpath, { timeout })
-  } else {
-    throw new Error('Must provide selector or xpath')
-  }
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify({
-          selector,
-          xpath,
-          timeout,
-          status: 'found',
-        }, null, 2),
-      },
-    ],
-  }
-}
-```
-
-**验证**:
-- ✅ 等待元素出现
-- ✅ 支持超时配置
-- ✅ 超时抛出错误
-
----
-
-### 6. 实现 getData 工具 ✅
-
-**功能**: 获取页面数据
-
-**代码**:
-```typescript
-async function handleGetData(args: GetDataArgs, context: ToolContext) {
-  const { sessionId, path } = args
-  const session = context.getSession(sessionId)
-
-  const page = await session.miniProgram.currentPage()
-  const data = await page.data()
-
-  let result = data
-  if (path) {
-    // 支持点记法路径，如 user.name
-    result = path.split('.').reduce((obj, key) => obj?.[key], data)
-  }
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify({
-          path,
-          data: result,
-        }, null, 2),
-      },
-    ],
-  }
-}
-```
-
-**验证**:
-- ✅ 获取完整数据
-- ✅ 支持路径查询
-
----
-
-### 7. 实现 setData 工具 ✅
-
-**功能**: 设置页面数据
-
-**代码**:
-```typescript
-async function handleSetData(args: SetDataArgs, context: ToolContext) {
-  const { sessionId, data } = args
-  const session = context.getSession(sessionId)
-
-  const page = await session.miniProgram.currentPage()
-  await page.setData(data)
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify({
-          data,
-          status: 'updated',
-        }, null, 2),
-      },
-    ],
-  }
-}
-```
-
-**验证**:
-- ✅ 更新页面数据
-- ✅ 自动触发渲染
-
----
-
-### 8. 实现 callMethod 工具 ✅
-
-**功能**: 调用页面方法
-
-**代码**:
-```typescript
-async function handleCallMethod(args: CallMethodArgs, context: ToolContext) {
-  const { sessionId, method, args: methodArgs = [] } = args
-  const session = context.getSession(sessionId)
-
-  const page = await session.miniProgram.currentPage()
-  const result = await page.callMethod(method, ...methodArgs)
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify({
-          method,
-          args: methodArgs,
-          result,
-        }, null, 2),
-      },
-    ],
-  }
-}
-```
-
-**验证**:
-- ✅ 调用页面方法
-- ✅ 传递参数
-- ✅ 返回结果
-
----
-
-### 9. 实现 getSize 和 getScrollTop 工具 ✅
-
-**功能**: 获取页面尺寸和滚动位置
-
-**代码**:
-```typescript
-async function handleGetSize(args: SessionArgs, context: ToolContext) {
-  const { sessionId } = args
-  const session = context.getSession(sessionId)
-
-  const page = await session.miniProgram.currentPage()
-  const size = await page.size()
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify(size, null, 2),
-      },
-    ],
-  }
-}
-
-async function handleGetScrollTop(args: SessionArgs, context: ToolContext) {
-  const { sessionId } = args
-  const session = context.getSession(sessionId)
-
-  const page = await session.miniProgram.currentPage()
-  const scrollTop = await page.scrollTop()
-
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify({ scrollTop }, null, 2),
-      },
-    ],
-  }
-}
-```
-
-**验证**:
-- ✅ getSize 返回宽高
-- ✅ getScrollTop 返回滚动位置
-
----
-
-### 10. 编写单元测试 ✅
-
-**文件**: `tests/unit/page.test.ts`
-
-**测试用例** (27 个):
-```typescript
-describe('Page Tools', () => {
-  describe('query', () => {
-    it('should query by selector', async () => {})
-    it('should query by xpath', async () => {})
-    it('should query by refId', async () => {})
-    it('should save to cache', async () => {})
-    it('should throw error if not found', async () => {})
-  })
-
-  describe('queryAll', () => {
-    it('should query all by selector', async () => {})
-    it('should query all by xpath', async () => {})
-    it('should return count', async () => {})
-  })
-
-  describe('waitFor', () => {
-    it('should wait for element', async () => {})
-    it('should timeout if not found', async () => {})
-    it('should use custom timeout', async () => {})
-  })
-
-  describe('getData', () => {
-    it('should get all data', async () => {})
-    it('should get data by path', async () => {})
-    it('should handle nested path', async () => {})
-  })
-
-  describe('setData', () => {
-    it('should set data', async () => {})
-    it('should update multiple fields', async () => {})
-  })
-
-  describe('callMethod', () => {
-    it('should call method without args', async () => {})
-    it('should call method with args', async () => {})
-    it('should return method result', async () => {})
-  })
-
-  describe('getSize', () => {
-    it('should return page size', async () => {})
-  })
-
-  describe('getScrollTop', () => {
-    it('should return scroll position', async () => {})
-  })
-
-  describe('ElementRef resolution', () => {
-    it('should resolve by refId', async () => {})
-    it('should resolve by selector', async () => {})
-    it('should resolve by xpath', async () => {})
-    it('should handle index for xpath', async () => {})
-    it('should throw if no ref provided', async () => {})
-  })
-})
-```
-
-**验证**:
-- ✅ 27 个测试全部通过
-- ✅ 覆盖 ElementRef 协议
-- ✅ Mock Page 实例
-
----
-
-## 完成标准 (Definition of Done)
-
-### 功能完成 ✅
-
-- [x] query 支持 selector/xpath/refId
-- [x] queryAll 返回元素数组
-- [x] waitFor 等待元素出现
-- [x] getData 支持路径查询
-- [x] setData 更新页面数据
-- [x] callMethod 调用页面方法
-- [x] getSize 返回页面尺寸
-- [x] getScrollTop 返回滚动位置
-
-### 代码质量 ✅
-
-- [x] TypeScript 编译 0 错误
-- [x] 无 ESLint 错误
-- [x] 代码行数 458 行（合理范围）
-- [x] JSDoc 注释完整
-- [x] 符合 ESM 规范（.js 后缀）
-
-### 测试 ✅
-
-- [x] 单元测试 450 行
-- [x] 27 个测试用例全部通过
-- [x] 覆盖 ElementRef 协议
-- [x] Mock 外部依赖
-
-### 文档 ⏳
-
-- [x] 代码注释完整
-- [x] Schema 描述清晰
-- ⏳ charter.C3.align.yaml (追溯)
-- ⏳ tasks.C3.atomize.md (本文档)
-
----
-
-## 实现结果 (Implementation)
-
-### 文件清单
-
-| 文件 | 行数 | 说明 |
-|------|------|------|
-| `src/tools/page.ts` | 458 | 8 个 Page 工具实现 |
-| `tests/unit/page.test.ts` | 450 | 27 个单元测试 |
-
-### 工具列表
-
-| 工具名 | 功能 | 输入 | 输出 |
-|--------|------|------|------|
-| `miniapp_page_query` | 单元素查询 | sessionId, elementRef | refId, found |
-| `miniapp_page_queryAll` | 多元素查询 | sessionId, selector/xpath | count |
-| `miniapp_page_waitFor` | 等待元素出现 | sessionId, elementRef, timeout? | status |
-| `miniapp_page_getData` | 获取页面数据 | sessionId, path? | data |
-| `miniapp_page_setData` | 设置页面数据 | sessionId, data | status |
-| `miniapp_page_callMethod` | 调用页面方法 | sessionId, method, args? | result |
-| `miniapp_page_getSize` | 获取页面尺寸 | sessionId | width, height |
-| `miniapp_page_getScrollTop` | 获取滚动位置 | sessionId | scrollTop |
-
-### ElementRef 协议
-
-| 字段 | 类型 | 说明 | 优先级 |
-|------|------|------|--------|
-| `refId` | string? | 缓存的元素引用 ID | 1 (最高) |
-| `selector` | string? | WXML 选择器 | 2 |
-| `xpath` | string? | XPath 选择器 | 3 |
-| `index` | number? | 多元素索引（用于 xpath） | - |
-| `pagePath` | string? | 目标页面路径 | - |
-| `save` | boolean? | 保存到缓存并返回 refId | - |
-
-### 选择器示例
-
-**WXML Selector**:
-```css
-.list-item                  /* class */
-#title                      /* id */
-view                        /* tag */
-[data-id="123"]            /* attribute */
-view.item > text           /* 组合 */
-```
-
-**XPath**:
-```xpath
-//view[@class="list-item"]
-//text[contains(text(), "搜索")]
-//view[1]/text[2]
-```
-
-### 设计决策
-
-1. **ElementRef 协议**
-   - 统一元素引用方式
-   - 理由：简化工具接口，支持缓存优化
-
-2. **元素缓存策略**
-   - 使用 Map 存储元素引用
-   - 页面变化时清理缓存
-   - 理由：减少重复查询，提高性能
-
-3. **getData 路径查询**
-   - 支持点记法（user.name）
-   - 理由：便于获取嵌套数据
-
-4. **waitFor 超时**
-   - 默认 5 秒，可配置
-   - 理由：平衡等待时间和用户体验
-
----
-
-## 测试证据 (Test Evidence)
-
-### 单元测试结果
-
-```bash
-$ pnpm test page.test.ts
-
-PASS tests/unit/page.test.ts
-  Page Tools
-    query
-      ✓ should query by selector (10ms)
-      ✓ should query by xpath (8ms)
-      ✓ should query by refId (7ms)
-      ✓ should save to cache (9ms)
-      ✓ should throw error if not found (6ms)
-    queryAll
-      ✓ should query all by selector (11ms)
-      ✓ should query all by xpath (9ms)
-      ✓ should return count (7ms)
-    waitFor
-      ✓ should wait for element (13ms)
-      ✓ should timeout if not found (5010ms)
-      ✓ should use custom timeout (3005ms)
-    getData
-      ✓ should get all data (8ms)
-      ✓ should get data by path (7ms)
-      ✓ should handle nested path (9ms)
-    setData
-      ✓ should set data (10ms)
-      ✓ should update multiple fields (8ms)
-    callMethod
-      ✓ should call method without args (9ms)
-      ✓ should call method with args (7ms)
-      ✓ should return method result (8ms)
-    getSize
-      ✓ should return page size (6ms)
-    getScrollTop
-      ✓ should return scroll position (7ms)
-    ElementRef resolution
-      ✓ should resolve by refId (8ms)
-      ✓ should resolve by selector (7ms)
-      ✓ should resolve by xpath (9ms)
-      ✓ should handle index for xpath (8ms)
-      ✓ should throw if no ref provided (5ms)
-
-Test Suites: 1 passed, 1 total
-Tests:       27 passed, 27 total
-Time:        8.456s
-```
-
-### 手动测试
-
-**查询元素**:
-```bash
-# 通过 selector 查询
-{
-  "sessionId": "xxx",
-  "elementRef": {
-    "selector": ".list-item",
-    "save": true
-  }
-}
-
-# 返回
-{
-  "refId": "elem-abc123",
-  "selector": ".list-item",
-  "found": true
-}
-```
-
-**获取页面数据**:
-```bash
-# 获取嵌套数据
-{
-  "sessionId": "xxx",
-  "path": "user.name"
-}
-
-# 返回
-{
-  "path": "user.name",
-  "data": "张三"
-}
-```
-
----
-
-## 已知问题 (Known Issues)
-
-### 技术债务
-
-1. **元素缓存失效** - 🟡 中优先级
-   - 原因：页面更新后缓存元素可能失效
-   - 影响：使用失效 refId 会报错
-   - 计划：页面导航时自动清理缓存
-
-2. **复杂选择器支持** - 🟢 低优先级
-   - 原因：部分复杂选择器可能不支持
-   - 影响：需要使用 xpath 替代
-   - 计划：完善选择器文档和示例
-
-### 风险
-
-1. **查询性能** - 🟢 低风险
-   - 缓解：支持元素缓存
-   - 监控：测试中验证查询时间
-
----
-
-## 参考资料 (References)
-
-### 文档
-
-- `docs/charter.C3.align.yaml` - 任务对齐文档
-- `docs/微信小程序自动化完整操作手册.md` - Page API 参考
-- `docs/完整实现方案.md` - ElementRef 协议设计
-
-### 代码
-
-- `src/tools/miniprogram.ts` - MiniProgram 工具（C2）
-- `src/core/session.ts` - Session 管理
-- `src/tools/index.ts` - 工具注册器（C5）
-
-### 外部资源
-
-- [miniprogram-automator Page API](https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/page.html)
-- [WXML 选择器文档](https://developers.weixin.qq.com/miniprogram/dev/reference/wxml/)
-
----
-
-## 后续任务 (Next Steps)
-
-### 依赖此任务的后续任务
-
-- ✅ C4: Element 工具（使用 query 获取元素）
-- ✅ C5: 工具注册器（集成 Page 工具）
-- ⏳ D1: Assert 工具（使用 getData 验证）
-
-### 改进建议
-
-1. **智能等待**
-   - 支持自定义等待条件函数
-   - 支持等待数据变化
-
-2. **批量查询优化**
-   - 一次查询多个元素
-   - 减少网络开销
-
-3. **缓存管理增强**
-   - 自动检测缓存失效
-   - 提供缓存清理工具
-
----
-
-**任务状态**: ✅ COMPLETED
-**代码提交**: ✅ 已提交（Stage C 提交）
-**文档状态**: ⏳ RETROSPECTIVE (追溯补齐中)