@creatoria/miniapp-mcp 0.1.3 → 0.2.2

package/docs/tasks.D3.atomize.md

@@ -1,790 +0,0 @@
-# Task Card: [D3] Recording and Replay System
-
-**Task ID**: D3
-**Task Name**: 录制与回放系统实现
-**Charter**: `docs/charter.D3.align.yaml`
-**Stage**: D (Advanced Capabilities)
-**Status**: ✅ COMPLETED (Retrospective)
-**Estimated**: 3-4 hours
-**Actual**: ~3.5 hours
-**Completed**: 2025-10-02
-
----
-
-## 目标 (Goal)
-
-实现完整的工具调用序列录制与回放系统，支持保存测试场景、复现操作流程。
-
-**交付物**:
-- ✅ `src/tools/record.ts` (428 lines)
-- ✅ `tests/unit/record.test.ts` (422 lines)
-- ✅ 6 个 MCP 工具（record_start/stop/list/get/delete/replay）
-- ✅ ActionSequence 和 RecordedAction 数据结构
-
----
-
-## 前置条件 (Prerequisites)
-
-- ✅ B2: SessionStore 和 SessionState 已实现
-- ✅ C1-C4: 核心工具已实现（需要被录制）
-- ✅ C5: registerTools 机制已完成
-- ✅ types.ts 中定义了基础类型
-
----
-
-## 实现步骤 (Steps)
-
-### 1. 扩展数据结构 ✅
-
-**文件**: `src/types.ts`
-
-**新增类型**:
-```typescript
-// 录制的动作
-export interface RecordedAction {
-  timestamp: Date
-  toolName: string
-  args: Record<string, any>
-  duration?: number
-  success: boolean
-  error?: string
-}
-
-// 动作序列
-export interface ActionSequence {
-  id: string
-  name: string
-  description?: string
-  createdAt: Date
-  actions: RecordedAction[]
-}
-
-// 录制状态
-export interface RecordingState {
-  isRecording: boolean
-  startedAt: Date
-  currentSequence: ActionSequence
-}
-
-// 扩展 SessionState
-export interface SessionState {
-  // ... existing fields
-  recording?: RecordingState
-}
-```
-
-**验证**: TypeScript 编译通过
-
----
-
-### 2. 实现辅助函数 ✅
-
-**文件**: `src/tools/record.ts`
-
-**函数**:
-```typescript
-// 生成唯一 sequence ID
-function generateSequenceId(): string {
-  return `seq_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`
-}
-
-// 获取序列存储目录
-function getSequencesDir(session: SessionState): string {
-  return path.join(session.outputDir, 'sequences')
-}
-
-// 确保目录存在
-async function ensureSequencesDir(session: SessionState): Promise<void> {
-  const dir = getSequencesDir(session)
-  await fs.mkdir(dir, { recursive: true })
-}
-```
-
-**验证**: 函数逻辑正确，类型安全
-
----
-
-### 3. 实现录制启动 ✅
-
-**函数**: `startRecording(session, args)`
-
-**逻辑**:
-1. 检查是否已在录制（报错）
-2. 生成 sequenceId
-3. 初始化 session.recording 状态
-4. 返回 sequenceId
-
-**代码**:
-```typescript
-export async function startRecording(
-  session: SessionState,
-  args: { name?: string; description?: string } = {}
-): Promise<{ success: boolean; message: string; sequenceId?: string }> {
-  const { name = `Recording ${new Date().toISOString()}`, description } = args
-
-  if (session.recording?.isRecording) {
-    throw new Error('Already recording. Stop current recording first.')
-  }
-
-  const sequenceId = generateSequenceId()
-  session.recording = {
-    isRecording: true,
-    startedAt: new Date(),
-    currentSequence: {
-      id: sequenceId,
-      name,
-      description,
-      createdAt: new Date(),
-      actions: [],
-    },
-  }
-
-  return { success: true, message: `Recording started: ${name}`, sequenceId }
-}
-```
-
-**验证**: 单元测试覆盖成功/失败路径
-
----
-
-### 4. 实现录制停止 ✅
-
-**函数**: `stopRecording(session, args)`
-
-**逻辑**:
-1. 检查是否在录制（报错）
-2. 获取当前序列
-3. 可选：保存到文件（ensureSequencesDir + writeFile）
-4. 清空 session.recording
-5. 返回统计信息
-
-**代码**:
-```typescript
-export async function stopRecording(
-  session: SessionState,
-  args: { save?: boolean } = {}
-): Promise<{
-  success: boolean
-  message: string
-  sequenceId?: string
-  actionCount?: number
-  filePath?: string
-}> {
-  const { save = true } = args
-
-  if (!session.recording?.isRecording || !session.recording.currentSequence) {
-    throw new Error('Not currently recording')
-  }
-
-  const sequence = session.recording.currentSequence
-  const actionCount = sequence.actions.length
-  session.recording.isRecording = false
-
-  let filePath: string | undefined
-  if (save) {
-    await ensureSequencesDir(session)
-    const filename = `${sequence.id}.json`
-    filePath = path.join(getSequencesDir(session), filename)
-    await fs.writeFile(filePath, JSON.stringify(sequence, null, 2), 'utf-8')
-  }
-
-  session.recording = undefined
-
-  return {
-    success: true,
-    message: `Recording stopped: ${sequence.name} (${actionCount} actions)`,
-    sequenceId: sequence.id,
-    actionCount,
-    filePath,
-  }
-}
-```
-
-**验证**: 测试保存/不保存两种模式
-
----
-
-### 5. 实现动作捕获 ✅
-
-**函数**: `recordAction(session, toolName, args, success, duration?, error?)`
-
-**逻辑**:
-1. 检查是否在录制（否则直接返回）
-2. 构造 RecordedAction 对象
-3. 追加到 currentSequence.actions
-
-**代码**:
-```typescript
-export function recordAction(
-  session: SessionState,
-  toolName: string,
-  args: Record<string, any>,
-  success: boolean,
-  duration?: number,
-  error?: string
-): void {
-  if (!session.recording?.isRecording || !session.recording.currentSequence) {
-    return
-  }
-
-  const action: RecordedAction = {
-    timestamp: new Date(),
-    toolName,
-    args,
-    duration,
-    success,
-    error,
-  }
-
-  session.recording.currentSequence.actions.push(action)
-}
-```
-
-**验证**: 测试录制/非录制状态
-
----
-
-### 6. 实现序列列表 ✅
-
-**函数**: `listSequences(session)`
-
-**逻辑**:
-1. ensureSequencesDir
-2. 读取目录中所有 .json 文件
-3. 解析每个文件获取摘要信息
-4. 返回 sequences 数组
-
-**代码**:
-```typescript
-export async function listSequences(
-  session: SessionState
-): Promise<{
-  success: boolean
-  message: string
-  sequences: Array<{
-    id: string
-    name: string
-    description?: string
-    createdAt: string
-    actionCount: number
-  }>
-}> {
-  await ensureSequencesDir(session)
-  const dir = getSequencesDir(session)
-  const files = await fs.readdir(dir)
-
-  const sequences = []
-  for (const file of files) {
-    if (!file.endsWith('.json')) continue
-
-    const filePath = path.join(dir, file)
-    const content = await fs.readFile(filePath, 'utf-8')
-    const sequence: ActionSequence = JSON.parse(content)
-
-    sequences.push({
-      id: sequence.id,
-      name: sequence.name,
-      description: sequence.description,
-      createdAt: sequence.createdAt.toString(),
-      actionCount: sequence.actions.length,
-    })
-  }
-
-  return {
-    success: true,
-    message: `Found ${sequences.length} sequences`,
-    sequences,
-  }
-}
-```
-
-**验证**: 测试空目录/多个序列
-
----
-
-### 7. 实现序列获取 ✅
-
-**函数**: `getSequence(session, { sequenceId })`
-
-**逻辑**:
-1. 构造文件路径
-2. 读取并解析 JSON
-3. 返回完整序列
-
-**代码**:
-```typescript
-export async function getSequence(
-  session: SessionState,
-  args: { sequenceId: string }
-): Promise<{ success: boolean; message: string; sequence: ActionSequence }> {
-  const { sequenceId } = args
-
-  await ensureSequencesDir(session)
-  const filePath = path.join(getSequencesDir(session), `${sequenceId}.json`)
-
-  const content = await fs.readFile(filePath, 'utf-8')
-  const sequence: ActionSequence = JSON.parse(content)
-
-  return {
-    success: true,
-    message: `Sequence retrieved: ${sequence.name}`,
-    sequence,
-  }
-}
-```
-
-**验证**: 测试文件存在/不存在
-
----
-
-### 8. 实现序列删除 ✅
-
-**函数**: `deleteSequence(session, { sequenceId })`
-
-**逻辑**:
-1. 构造文件路径
-2. 使用 fs.unlink 删除文件
-3. 返回成功消息
-
-**代码**:
-```typescript
-export async function deleteSequence(
-  session: SessionState,
-  args: { sequenceId: string }
-): Promise<{ success: boolean; message: string }> {
-  const { sequenceId } = args
-
-  const filePath = path.join(getSequencesDir(session), `${sequenceId}.json`)
-  await fs.unlink(filePath)
-
-  return { success: true, message: `Sequence deleted: ${sequenceId}` }
-}
-```
-
-**验证**: 测试文件存在/不存在
-
----
-
-### 9. 实现序列回放 ✅
-
-**函数**: `replaySequence(session, { sequenceId, continueOnError? })`
-
-**逻辑**:
-1. 获取序列（调用 getSequence）
-2. 动态导入 tools 模块（避免循环依赖）
-3. 遍历 actions：
-   - 查找对应 toolFn
-   - 执行 toolFn(session, action.args)
-   - 记录成功/失败
-   - 如果失败且 continueOnError=false，抛出错误
-4. 返回统计信息和详细结果
-
-**代码**:
-```typescript
-export async function replaySequence(
-  session: SessionState,
-  args: { sequenceId: string; continueOnError?: boolean }
-): Promise<{
-  success: boolean
-  message: string
-  totalActions: number
-  successCount: number
-  failureCount: number
-  results: Array<{ toolName: string; success: boolean; error?: string }>
-}> {
-  const { sequenceId, continueOnError = false } = args
-
-  // Get sequence
-  const { sequence } = await getSequence(session, { sequenceId })
-
-  // Import tools dynamically
-  const tools = await import('./index.js')
-
-  const results = []
-  let successCount = 0
-  let failureCount = 0
-
-  // Replay each action
-  for (const action of sequence.actions) {
-    const startTime = Date.now()
-
-    try {
-      const toolFn = (tools as any)[action.toolName]
-      if (!toolFn || typeof toolFn !== 'function') {
-        throw new Error(`Tool not found: ${action.toolName}`)
-      }
-
-      await toolFn(session, action.args)
-
-      results.push({ toolName: action.toolName, success: true })
-      successCount++
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error)
-
-      results.push({
-        toolName: action.toolName,
-        success: false,
-        error: errorMessage,
-      })
-      failureCount++
-
-      if (!continueOnError) {
-        throw new Error(`Replay stopped at action ${action.toolName}: ${errorMessage}`)
-      }
-    }
-  }
-
-  return {
-    success: failureCount === 0,
-    message: `Replay completed: ${successCount} success, ${failureCount} failures`,
-    totalActions: sequence.actions.length,
-    successCount,
-    failureCount,
-    results,
-  }
-}
-```
-
-**验证**: 测试成功回放/部分失败/完全失败
-
----
-
-### 10. 注册 MCP 工具 ✅
-
-**文件**: `src/tools/index.ts`
-
-**工具定义**:
-```typescript
-// In registerTools function
-if (capabilities.includes('record')) {
-  // record_start
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    if (request.params.name === 'record_start') {
-      const session = getSession(request.params.sessionId)
-      return await recordTools.startRecording(session, request.params.arguments)
-    }
-    // ... other record tools
-  })
-
-  tools.push(
-    {
-      name: 'record_start',
-      description: 'Start recording tool call sequence',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          name: { type: 'string', description: 'Sequence name' },
-          description: { type: 'string', description: 'Sequence description' },
-        },
-      },
-    },
-    // ... other 5 tools
-  )
-}
-```
-
-**验证**: list_tools 返回所有 6 个工具
-
----
-
-### 11. 编写单元测试 ✅
-
-**文件**: `tests/unit/record.test.ts`
-
-**测试覆盖**:
-```typescript
-describe('Record Tools', () => {
-  describe('startRecording', () => {
-    // ✅ should start recording with default name
-    // ✅ should start recording with custom name and description
-    // ✅ should fail if already recording
-  })
-
-  describe('stopRecording', () => {
-    // ✅ should stop recording and save sequence
-    // ✅ should stop recording without saving
-    // ✅ should fail if not recording
-  })
-
-  describe('recordAction', () => {
-    // ✅ should record an action when recording is active
-    // ✅ should record failed action with error
-    // ✅ should not record action when not recording
-    // ✅ should record multiple actions in sequence
-  })
-
-  describe('listSequences', () => {
-    // ✅ should list all saved sequences
-    // ✅ should return empty list when no sequences exist
-  })
-
-  describe('getSequence', () => {
-    // ✅ should retrieve a specific sequence
-    // ✅ should fail when sequence not found
-  })
-
-  describe('deleteSequence', () => {
-    // ✅ should delete a sequence
-    // ✅ should fail when sequence not found
-  })
-
-  describe('replaySequence', () => {
-    // ✅ should replay a sequence successfully
-    // ✅ should stop on first error when continueOnError is false
-  })
-})
-```
-
-**验证**: 所有测试通过，覆盖率 >90%
-
----
-
-## 完成标准 (Definition of Done)
-
-### 功能完成 ✅
-
-- [x] 启动录制返回 sequenceId
-- [x] 执行工具时自动调用 recordAction
-- [x] 停止录制生成 JSON 文件
-- [x] list/get/delete 正常工作
-- [x] 回放成功重现操作序列
-- [x] continueOnError 模式正确处理错误
-
-### 代码质量 ✅
-
-- [x] TypeScript 编译 0 错误
-- [x] 无 ESLint 错误
-- [x] JSDoc 注释完整
-- [x] 符合 ESM 规范
-- [x] 代码行数：record.ts 428 行
-
-### 测试 ✅
-
-- [x] 单元测试完整（422 lines）
-- [x] 覆盖所有核心函数
-- [x] 边界情况测试
-- [x] 所有测试通过
-
-### 文档 ⏳
-
-- [x] 代码注释完整
-- [x] types.ts 定义清晰
-- ⏳ charter.D3.align.yaml (追溯)
-- ⏳ tasks.D3.atomize.md (本文档)
-
----
-
-## 实现结果 (Implementation)
-
-### 文件清单
-
-| 文件 | 行数 | 说明 |
-|------|------|------|
-| `src/tools/record.ts` | 428 | 录制/回放核心实现 |
-| `tests/unit/record.test.ts` | 422 | 完整单元测试 |
-| `src/types.ts` | +30 | 数据结构定义 |
-| `src/tools/index.ts` | +60 | 工具注册 |
-
-### 工具清单
-
-1. **record_start**: 启动录制
-   - 参数: name?, description?
-   - 返回: sequenceId
-
-2. **record_stop**: 停止录制
-   - 参数: save? (default: true)
-   - 返回: actionCount, filePath
-
-3. **record_list**: 列出所有序列
-   - 参数: 无
-   - 返回: sequences[]
-
-4. **record_get**: 获取序列详情
-   - 参数: sequenceId
-   - 返回: sequence (含完整 actions)
-
-5. **record_delete**: 删除序列
-   - 参数: sequenceId
-   - 返回: success
-
-6. **record_replay**: 回放序列
-   - 参数: sequenceId, continueOnError?
-   - 返回: totalActions, successCount, failureCount, results[]
-
-### 数据结构
-
-**ActionSequence**:
-```typescript
-{
-  id: "seq_1696234567890_abc123",
-  name: "Login flow test",
-  description: "Test user login and profile navigation",
-  createdAt: "2025-10-02T10:30:00.000Z",
-  actions: [
-    {
-      timestamp: "2025-10-02T10:30:01.234Z",
-      toolName: "element_tap",
-      args: { refId: "elem_login_button" },
-      duration: 150,
-      success: true
-    },
-    // ... more actions
-  ]
-}
-```
-
-### 设计决策
-
-1. **文件存储**
-   - 使用 JSON 格式（人类可读）
-   - 存储在 `{outputDir}/sequences/` 目录
-   - 理由：简单、可移植、易调试
-
-2. **动态导入**
-   - 回放时使用 `await import('./index.js')`
-   - 理由：避免循环依赖（record.ts ← index.ts）
-
-3. **状态管理**
-   - 录制状态存储在 SessionState.recording
-   - 理由：每个 Session 独立录制，天然隔离
-
-4. **错误处理**
-   - 录制失败的操作也记录
-   - 回放支持 continueOnError 模式
-   - 理由：完整记录实际执行情况
-
----
-
-## 测试证据 (Test Evidence)
-
-### 单元测试结果
-
-```bash
-$ pnpm test tests/unit/record.test.ts
-
- PASS  tests/unit/record.test.ts
-  Record Tools
-    startRecording
-      ✓ should start recording with default name (3 ms)
-      ✓ should start recording with custom name and description (1 ms)
-      ✓ should fail if already recording (2 ms)
-    stopRecording
-      ✓ should stop recording and save sequence (2 ms)
-      ✓ should stop recording without saving (1 ms)
-      ✓ should fail if not recording (1 ms)
-    recordAction
-      ✓ should record an action when recording is active (1 ms)
-      ✓ should record failed action with error (1 ms)
-      ✓ should not record action when not recording (1 ms)
-      ✓ should record multiple actions in sequence (1 ms)
-    listSequences
-      ✓ should list all saved sequences (2 ms)
-      ✓ should return empty list when no sequences exist (1 ms)
-    getSequence
-      ✓ should retrieve a specific sequence (1 ms)
-      ✓ should fail when sequence not found (1 ms)
-    deleteSequence
-      ✓ should delete a sequence (1 ms)
-      ✓ should fail when sequence not found (1 ms)
-    replaySequence
-      ✓ should replay a sequence successfully (2 ms)
-      ✓ should stop on first error when continueOnError is false (2 ms)
-
-Test Suites: 1 passed, 1 total
-Tests:       18 passed, 18 total
-```
-
-### 集成测试
-
-通过手动测试验证完整流程：
-1. ✅ 启动录制
-2. ✅ 执行多个工具调用（element_tap, page_query 等）
-3. ✅ 停止录制并保存
-4. ✅ 列出序列，获取详情
-5. ✅ 回放序列成功重现操作
-6. ✅ 删除序列
-
----
-
-## 已知问题 (Known Issues)
-
-### 技术债务
-
-1. **无序列编辑能力** - 🟡 中优先级
-   - 影响：无法修改已保存序列
-   - 计划：未来可添加 record_edit 工具
-
-2. **无变量参数化** - 🟡 中优先级
-   - 影响：回放硬编码参数
-   - 计划：未来支持 `{{variable}}` 语法
-
-3. **回放无速度控制** - 🟢 低优先级
-   - 影响：回放以最快速度执行
-   - 计划：未来添加 delay 参数
-
-### 风险
-
-1. **序列依赖状态** - 🟡 中风险
-   - 风险：回放依赖特定页面/元素状态
-   - 缓解：记录完整上下文（pagePath 等）
-   - 建议：用户确保回放环境一致
-
-2. **工具 API 变更** - 🟡 中风险
-   - 风险：工具签名变更导致旧序列失效
-   - 缓解：保留原始 args 结构
-   - 监控：语义化版本控制
-
----
-
-## 参考资料 (References)
-
-### 文档
-
-- `docs/完整实现方案.md` - 录制/回放架构
-- `docs/charter.D3.align.yaml` - 任务对齐文档
-- Playwright Inspector - 设计灵感来源
-
-### 代码
-
-- `src/core/session.ts` - SessionState 定义
-- `src/tools/index.ts` - 工具注册机制
-- `tests/unit/record.test.ts` - 测试参考
-
-### 外部资源
-
-- [Playwright Codegen](https://playwright.dev/docs/codegen) - 录制功能参考
-- [MCP Protocol](https://spec.modelcontextprotocol.io) - 工具定义规范
-
----
-
-## 后续任务 (Next Steps)
-
-### 依赖此任务的后续任务
-
-- ⏳ E4: 示例项目（使用录制序列演示）
-- ⏳ G1: 集成测试（使用回放验证功能）
-- ⏳ H1: 发布准备（录制序列作为示例）
-
-### 改进建议
-
-1. **序列编辑**
-   - 添加 record_edit 工具
-   - 支持插入/删除/修改单个 action
-
-2. **参数化**
-   - 支持 `{{variable}}` 语法
-   - 回放时传入变量映射
-
-3. **可视化**
-   - 生成序列流程图
-   - 导出为 Markdown/HTML 报告
-
-4. **远程存储**
-   - 支持上传序列到云端
-   - 团队共享测试场景
-
----
-
-**任务状态**: ✅ COMPLETED
-**代码提交**: ✅ 已提交（feat: [D3] 录制回放能力实现）
-**文档状态**: ⏳ RETROSPECTIVE (追溯补齐中)