@creatoria/miniapp-mcp 0.1.3 → 0.2.2

package/docs/tasks.D2.atomize.md

@@ -1,619 +0,0 @@
-# Task Card: [D2] 快照工具集
-
-**Task ID**: D2
-**Task Name**: 快照工具集实现
-**Charter**: `docs/charter.D2.align.yaml`
-**Stage**: D (Advanced Capabilities)
-**Status**: ✅ COMPLETED (Retrospective)
-**Estimated**: 2-3 hours
-**Actual**: ~2 hours
-**Completed**: 2025-10-02
-
----
-
-## 目标 (Goal)
-
-实现 3 个快照工具，为小程序自动化测试提供状态捕获能力，支持页面、应用、元素三个维度的快照。
-
-**交付物**:
-- ✅ `src/tools/snapshot.ts` (352 lines)
-- ✅ `tests/unit/snapshot.test.ts` (251 lines, 10 tests)
-- ✅ 3 个快照工具全部实现
-
----
-
-## 前置条件 (Prerequisites)
-
-- ✅ C2: MiniProgram 工具（getPageStack, getSystemInfo, screenshot）
-- ✅ C3: Page 工具（getData）
-- ✅ C4: Element 工具（getText, getSize, getOffset）
-- ✅ B3: OutputManager 实现
-- ✅ SessionState 定义完成
-
----
-
-## 实现步骤 (Steps)
-
-### 1. 创建快照工具文件 ✅
-
-**文件**: `src/tools/snapshot.ts`
-
-**步骤**:
-```typescript
-import type { SessionState } from '../types.js'
-import * as miniprogramTools from './miniprogram.js'
-import * as pageTools from './page.js'
-
-// 定义快照函数
-export async function snapshotPage(
-  session: SessionState,
-  args: {
-    pagePath?: string
-    filename?: string
-    includeScreenshot?: boolean
-    fullPage?: boolean
-  }
-): Promise<{
-  success: boolean
-  message: string
-  snapshotPath: string
-  screenshotPath?: string
-  data: any
-}> {
-  // 实现...
-}
-```
-
-**验证**: TypeScript 编译通过，正确导入依赖
-
----
-
-### 2. 实现页面快照 (snapshotPage) ✅
-
-**功能**: 捕获当前页面数据和可选截图
-
-**代码**:
-```typescript
-export async function snapshotPage(session, args) {
-  const { pagePath, filename, includeScreenshot = true, fullPage = false } = args
-  const logger = session.logger
-
-  if (!session.miniProgram) {
-    throw new Error('MiniProgram not connected')
-  }
-
-  if (!session.outputManager) {
-    throw new Error('OutputManager not available')
-  }
-
-  // 1. 获取页面栈，找到当前页面
-  const pageStackResult = await miniprogramTools.getPageStack(session)
-  const currentPageInfo = pageStackResult.pages[pageStackResult.pages.length - 1]
-
-  if (!currentPageInfo) {
-    throw new Error('No active page found')
-  }
-
-  // 2. 获取页面数据
-  const pageDataResult = await pageTools.getData(session, { pagePath })
-
-  // 3. 构建快照数据
-  const timestamp = new Date().toISOString()
-  const snapshotData = {
-    timestamp,
-    pagePath: currentPageInfo.path,
-    pageData: pageDataResult.data,
-    pageQuery: currentPageInfo.query,
-  }
-
-  // 4. 保存 JSON 文件
-  const outputManager = session.outputManager
-  await outputManager.ensureOutputDir()
-
-  const snapshotFilename = filename || outputManager.generateFilename('snapshot', 'json')
-  const snapshotPath = await outputManager.writeFile(
-    snapshotFilename,
-    Buffer.from(JSON.stringify(snapshotData, null, 2))
-  )
-
-  // 5. 可选截图
-  let screenshotPath: string | undefined
-  if (includeScreenshot) {
-    const screenshotFilename = snapshotFilename.replace('.json', '.png')
-    const screenshotResult = await miniprogramTools.screenshot(session, {
-      filename: screenshotFilename,
-      fullPage,
-    })
-    screenshotPath = screenshotResult.path
-  }
-
-  return {
-    success: true,
-    message: 'Page snapshot captured successfully',
-    snapshotPath,
-    screenshotPath,
-    data: snapshotData,
-  }
-}
-```
-
-**验证**:
-- ✅ 捕获页面路径、数据、query
-- ✅ 生成 JSON 文件
-- ✅ 可选截图
-- ✅ 返回文件路径
-
----
-
-### 3. 实现完整应用快照 (snapshotFull) ✅
-
-**功能**: 捕获系统信息、页面栈、当前页面数据
-
-**代码**:
-```typescript
-export async function snapshotFull(session, args) {
-  const { filename, includeScreenshot = true, fullPage = false } = args
-
-  // 1. 获取系统信息
-  const systemInfoResult = await miniprogramTools.getSystemInfo(session)
-
-  // 2. 获取页面栈
-  const pageStackResult = await miniprogramTools.getPageStack(session)
-  const currentPageInfo = pageStackResult.pages[pageStackResult.pages.length - 1]
-
-  if (!currentPageInfo) {
-    throw new Error('No active page found')
-  }
-
-  // 3. 获取当前页面数据
-  const pageDataResult = await pageTools.getData(session, {})
-
-  // 4. 构建快照数据
-  const timestamp = new Date().toISOString()
-  const snapshotData = {
-    timestamp,
-    systemInfo: systemInfoResult.systemInfo,
-    pageStack: pageStackResult.pages,
-    currentPage: {
-      path: currentPageInfo.path,
-      query: currentPageInfo.query,
-      data: pageDataResult.data,
-    },
-  }
-
-  // 5. 保存 JSON 和截图（逻辑同 snapshotPage）
-  // ...
-}
-```
-
-**数据结构**:
-```json
-{
-  "timestamp": "2025-10-02T10:30:45.123Z",
-  "systemInfo": {
-    "platform": "devtools",
-    "version": "8.0.0"
-  },
-  "pageStack": [
-    { "path": "pages/index/index", "query": {} },
-    { "path": "pages/detail/detail", "query": { "id": "123" } }
-  ],
-  "currentPage": {
-    "path": "pages/detail/detail",
-    "query": { "id": "123" },
-    "data": { "title": "Detail Page", "count": 5 }
-  }
-}
-```
-
-**验证**:
-- ✅ 捕获系统信息
-- ✅ 捕获完整页面栈
-- ✅ 捕获当前页面数据
-- ✅ 生成 JSON + 可选截图
-
----
-
-### 4. 实现元素快照 (snapshotElement) ✅
-
-**功能**: 捕获元素文本、尺寸、位置
-
-**代码**:
-```typescript
-export async function snapshotElement(session, args) {
-  const { refId, filename, includeScreenshot = false } = args
-
-  // 动态导入 elementTools 避免循环依赖
-  const elementTools = await import('./element.js')
-
-  // 1. 获取元素文本（可能不存在）
-  let text: string | undefined
-  try {
-    const textResult = await elementTools.getText(session, { refId })
-    text = textResult.text
-  } catch {
-    text = undefined
-  }
-
-  // 2. 获取元素尺寸
-  const sizeResult = await elementTools.getSize(session, { refId })
-
-  // 3. 获取元素位置
-  const offsetResult = await elementTools.getOffset(session, { refId })
-
-  // 4. 构建快照数据
-  const timestamp = new Date().toISOString()
-  const snapshotData = {
-    timestamp,
-    refId,
-    text,
-    attributes: {}, // 当前未实现属性捕获
-    size: sizeResult.size,
-    offset: offsetResult.offset,
-  }
-
-  // 5. 保存 JSON 和截图（逻辑同 snapshotPage）
-  // ...
-}
-```
-
-**数据结构**:
-```json
-{
-  "timestamp": "2025-10-02T10:31:20.456Z",
-  "refId": "elem-123",
-  "text": "Click Me",
-  "attributes": {},
-  "size": { "width": 100, "height": 40 },
-  "offset": { "left": 20, "top": 100 }
-}
-```
-
-**验证**:
-- ✅ 捕获元素文本（可选）
-- ✅ 捕获元素尺寸
-- ✅ 捕获元素位置
-- ✅ 生成 JSON + 可选截图
-
----
-
-### 5. 文件名生成逻辑 ✅
-
-**OutputManager 集成**:
-```typescript
-const outputManager = session.outputManager
-
-// 自动生成文件名（带时间戳）
-const snapshotFilename = filename || outputManager.generateFilename('snapshot', 'json')
-// 示例: snapshot-1696234567890.json
-
-// 截图文件名（替换扩展名）
-const screenshotFilename = snapshotFilename.replace('.json', '.png')
-// 示例: snapshot-1696234567890.png
-
-// 写入文件
-const snapshotPath = await outputManager.writeFile(
-  snapshotFilename,
-  Buffer.from(JSON.stringify(snapshotData, null, 2))
-)
-```
-
-**验证**:
-- ✅ 自动生成唯一文件名
-- ✅ 支持自定义文件名
-- ✅ 截图与 JSON 同名（仅扩展名不同）
-
----
-
-### 6. 编写单元测试 ✅
-
-**文件**: `tests/unit/snapshot.test.ts`
-
-**测试用例** (10 个):
-```typescript
-describe('Snapshot Tools', () => {
-  describe('snapshotPage', () => {
-    it('should capture page snapshot with screenshot', async () => {})
-    it('should capture page snapshot without screenshot', async () => {})
-    it('should support custom filename', async () => {})
-    it('should fail when no miniProgram connected', async () => {})
-    it('should fail when no active page', async () => {})
-  })
-
-  describe('snapshotFull', () => {
-    it('should capture full application snapshot', async () => {})
-    it('should capture full snapshot without screenshot', async () => {})
-    it('should fail when no miniProgram connected', async () => {})
-  })
-
-  describe('snapshotElement', () => {
-    it('should fail when no miniProgram connected', async () => {})
-    it('should fail when no outputManager available', async () => {})
-  })
-})
-```
-
-**验证**:
-- ✅ 10 个测试全部通过
-- ✅ Mock miniprogramTools, pageTools, elementTools
-- ✅ Mock OutputManager
-- ✅ 覆盖成功和失败场景
-
----
-
-## 完成标准 (Definition of Done)
-
-### 功能完成 ✅
-
-- [x] snapshotPage 捕获页面数据和截图
-- [x] snapshotFull 捕获应用全局状态
-- [x] snapshotElement 捕获元素状态
-- [x] JSON 文件包含时间戳
-- [x] 截图可选（includeScreenshot 参数）
-- [x] 支持自定义文件名
-- [x] 使用 OutputManager 管理文件
-
-### 代码质量 ✅
-
-- [x] TypeScript 编译 0 错误
-- [x] 无 ESLint 错误
-- [x] 代码行数 352 行（合理范围）
-- [x] JSDoc 注释完整
-- [x] 符合 ESM 规范（.js 后缀）
-
-### 测试 ✅
-
-- [x] 单元测试 251 行
-- [x] 10 个测试用例全部通过
-- [x] 覆盖所有成功/失败场景
-- [x] Mock 外部依赖
-
-### 文档 ⏳
-
-- [x] 代码注释完整
-- [x] 函数签名清晰
-- [x] 数据结构定义清晰
-- ⏳ charter.D2.align.yaml (追溯)
-- ⏳ tasks.D2.atomize.md (本文档)
-
----
-
-## 实现结果 (Implementation)
-
-### 文件清单
-
-| 文件 | 行数 | 说明 |
-|------|------|------|
-| `src/tools/snapshot.ts` | 352 | 3 个快照工具实现 |
-| `tests/unit/snapshot.test.ts` | 251 | 10 个单元测试 |
-
-### 工具列表
-
-| 工具名 | 功能 | 输入 | 输出 |
-|--------|------|------|------|
-| `snapshotPage` | 捕获页面快照 | pagePath?, filename?, includeScreenshot?, fullPage? | success, snapshotPath, screenshotPath?, data |
-| `snapshotFull` | 捕获完整应用快照 | filename?, includeScreenshot?, fullPage? | success, snapshotPath, screenshotPath?, data |
-| `snapshotElement` | 捕获元素快照 | refId, filename?, includeScreenshot? | success, snapshotPath, screenshotPath?, data |
-
-### 数据结构
-
-**snapshotPage 数据**:
-```json
-{
-  "timestamp": "2025-10-02T10:30:45.123Z",
-  "pagePath": "pages/detail/detail",
-  "pageData": { "count": 5, "items": [] },
-  "pageQuery": { "id": "123" }
-}
-```
-
-**snapshotFull 数据**:
-```json
-{
-  "timestamp": "2025-10-02T10:30:45.123Z",
-  "systemInfo": { "platform": "devtools", "version": "8.0.0" },
-  "pageStack": [
-    { "path": "pages/index/index", "query": {} },
-    { "path": "pages/detail/detail", "query": { "id": "123" } }
-  ],
-  "currentPage": {
-    "path": "pages/detail/detail",
-    "query": { "id": "123" },
-    "data": { "count": 5 }
-  }
-}
-```
-
-**snapshotElement 数据**:
-```json
-{
-  "timestamp": "2025-10-02T10:31:20.456Z",
-  "refId": "elem-123",
-  "text": "Click Me",
-  "attributes": {},
-  "size": { "width": 100, "height": 40 },
-  "offset": { "left": 20, "top": 100 }
-}
-```
-
-### 关键代码片段
-
-**时间戳生成**:
-```typescript
-const timestamp = new Date().toISOString()
-// 示例: "2025-10-02T10:30:45.123Z"
-```
-
-**文件名生成**:
-```typescript
-const snapshotFilename = filename || outputManager.generateFilename('snapshot', 'json')
-// 默认: snapshot-1696234567890.json
-// 自定义: custom-snapshot.json
-
-const screenshotFilename = snapshotFilename.replace('.json', '.png')
-// snapshot-1696234567890.png
-```
-
-**可选截图**:
-```typescript
-let screenshotPath: string | undefined
-if (includeScreenshot) {
-  const screenshotResult = await miniprogramTools.screenshot(session, {
-    filename: screenshotFilename,
-    fullPage,
-  })
-  screenshotPath = screenshotResult.path
-}
-```
-
-### 设计决策
-
-1. **JSON + PNG 分离**
-   - JSON 存储结构化数据
-   - PNG 存储可视化截图
-   - 理由：灵活性，便于独立处理
-
-2. **截图可选**
-   - 默认 includeScreenshot = true
-   - 理由：截图耗时，某些场景不需要
-
-3. **时间戳格式**
-   - 使用 ISO8601 (`new Date().toISOString()`)
-   - 理由：国际标准，可读性强
-
-4. **动态导入 elementTools**
-   - 使用 `await import('./element.js')`
-   - 理由：避免循环依赖
-
----
-
-## 测试证据 (Test Evidence)
-
-### 单元测试结果
-
-```bash
-$ pnpm test snapshot.test.ts
-
-PASS tests/unit/snapshot.test.ts
-  Snapshot Tools
-    snapshotPage
-      ✓ should capture page snapshot with screenshot (18ms)
-      ✓ should capture page snapshot without screenshot (12ms)
-      ✓ should support custom filename (10ms)
-      ✓ should fail when no miniProgram connected (6ms)
-      ✓ should fail when no active page (8ms)
-    snapshotFull
-      ✓ should capture full application snapshot (20ms)
-      ✓ should capture full snapshot without screenshot (14ms)
-      ✓ should fail when no miniProgram connected (7ms)
-    snapshotElement
-      ✓ should fail when no miniProgram connected (6ms)
-      ✓ should fail when no outputManager available (7ms)
-
-Test Suites: 1 passed, 1 total
-Tests:       10 passed, 10 total
-Time:        1.856s
-```
-
-### 快照文件示例
-
-**snapshot-1696234567890.json**:
-```json
-{
-  "timestamp": "2025-10-02T10:30:45.123Z",
-  "pagePath": "pages/detail/detail",
-  "pageData": {
-    "count": 5,
-    "items": [
-      { "id": 1, "name": "Item 1" },
-      { "id": 2, "name": "Item 2" }
-    ]
-  },
-  "pageQuery": {
-    "id": "123",
-    "from": "list"
-  }
-}
-```
-
-**snapshot-1696234567890.png**: (二进制截图文件)
-
----
-
-## 已知问题 (Known Issues)
-
-### 技术债务
-
-1. **元素属性未捕获** - 🟡 中优先级
-   - 原因：attributes 字段为空对象
-   - 影响：无法捕获元素 HTML 属性
-   - 计划：未来补充 getAttribute 批量调用
-
-2. **大数据量警告** - 🟢 低优先级
-   - 原因：pageData 可能非常大
-   - 影响：JSON 文件可能数 MB
-   - 计划：未来添加大小警告或截断
-
-### 风险
-
-1. **截图失败** - 🟢 低风险
-   - 缓解：截图为可选，失败不影响 JSON 保存
-   - 监控：单元测试覆盖截图失败场景
-
-2. **文件覆盖** - 🟢 低风险
-   - 缓解：generateFilename 使用毫秒级时间戳
-   - 监控：用户自行管理 outputDir
-
----
-
-## 参考资料 (References)
-
-### 文档
-
-- `docs/charter.D2.align.yaml` - 任务对齐文档
-- `docs/完整实现方案.md` - 工具分层设计
-
-### 代码
-
-- `src/tools/miniprogram.ts` - MiniProgram 工具依赖
-- `src/tools/page.ts` - Page 工具依赖
-- `src/tools/element.ts` - Element 工具依赖
-- `src/core/output.ts` - OutputManager 实现
-
-### 外部资源
-
-- [Playwright Screenshots](https://playwright.dev/docs/screenshots)
-- [JSON.stringify 文档](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)
-
----
-
-## 后续任务 (Next Steps)
-
-### 依赖此任务的后续任务
-
-- ⏳ E1: 工具注册器集成（添加 snapshot 工具到 capabilities）
-- ⏳ F1: 端到端测试示例（使用快照工具）
-
-### 改进建议
-
-1. **快照比对**
-   - 实现 diff 工具比较两个快照
-   - 输出差异报告
-
-2. **快照恢复**
-   - 实现 restore 工具从快照恢复状态
-   - 适合回归测试
-
-3. **属性批量捕获**
-   - snapshotElement 补充 attributes 字段
-   - 批量调用 getAttribute
-
-4. **快照压缩**
-   - 支持 zip 压缩节省空间
-   - 批量快照归档
-
----
-
-**任务状态**: ✅ COMPLETED
-**代码提交**: ✅ 已提交（commit: feat: [D2] 快照能力实现）
-**文档状态**: ⏳ RETROSPECTIVE (追溯补齐中)