@creatoria/miniapp-mcp 0.1.3 → 0.2.0

package/docs/tasks.C5.atomize.md

@@ -1,755 +0,0 @@
-# Task Card: [C5] 工具注册器
-
-**Task ID**: C5
-**Task Name**: 工具注册器实现（registerTools 函数 + 元数据系统）
-**Charter**: `docs/charter.C5.align.yaml`
-**Stage**: C (Tool Implementation)
-**Status**: ✅ COMPLETED (Retrospective)
-**Estimated**: 3-4 hours
-**Actual**: ~4 hours
-**Completed**: 2025-10-02
-
----
-
-## 目标 (Goal)
-
-实现统一的工具注册系统，按 capabilities 动态注册工具，提供工具分类、元数据管理和验证机制。
-
-**交付物**:
-- ✅ `src/tools/index.ts` (1433 lines)
-- ✅ `tests/unit/tool-registration.test.ts` (400 lines, 46 tests)
-- ✅ registerTools 函数
-- ✅ 6 个工具分类系统
-- ✅ TOOL_CATEGORIES 元数据
-
----
-
-## 前置条件 (Prerequisites)
-
-- ✅ C1-C4: 所有工具实现完成
-- ✅ B1: MCP Server 骨架
-- ✅ 了解 MCP 工具注册机制
-- ✅ 了解 capabilities 概念
-
----
-
-## 实现步骤 (Steps)
-
-### 1. 定义 ToolContext 接口 ✅
-
-**文件**: `src/tools/index.ts`
-
-**步骤**:
-```typescript
-export interface ToolContext {
-  getSession: (sessionId: string) => Session
-  deleteSession: (sessionId: string) => void
-  capabilities: string[]
-}
-```
-
-**验证**: 接口定义清晰
-
----
-
-### 2. 定义工具分类常量 ✅
-
-**代码**:
-```typescript
-// Automator 工具（4个）
-export const AUTOMATOR_TOOLS = [
-  'miniapp_automator_launch',
-  'miniapp_automator_connect',
-  'miniapp_automator_disconnect',
-  'miniapp_automator_close',
-]
-
-// MiniProgram 工具（6个）
-export const MINIPROGRAM_TOOLS = [
-  'miniapp_miniprogram_navigate',
-  'miniapp_miniprogram_callWx',
-  'miniapp_miniprogram_evaluate',
-  'miniapp_miniprogram_screenshot',
-  'miniapp_miniprogram_getPageStack',
-  'miniapp_miniprogram_getSystemInfo',
-]
-
-// Page 工具（8个）
-export const PAGE_TOOLS = [
-  'miniapp_page_query',
-  'miniapp_page_queryAll',
-  'miniapp_page_waitFor',
-  'miniapp_page_getData',
-  'miniapp_page_setData',
-  'miniapp_page_callMethod',
-  'miniapp_page_getSize',
-  'miniapp_page_getScrollTop',
-]
-
-// Element 工具（23个核心 + 子类）
-export const ELEMENT_TOOLS = [
-  // 基础交互 (7)
-  'miniapp_element_tap',
-  'miniapp_element_longpress',
-  'miniapp_element_touchstart',
-  'miniapp_element_touchmove',
-  'miniapp_element_touchend',
-  'miniapp_element_input',
-  'miniapp_element_trigger',
-
-  // 属性读取 (6)
-  'miniapp_element_getText',
-  'miniapp_element_getAttribute',
-  'miniapp_element_getValue',
-  'miniapp_element_getProperty',
-  'miniapp_element_getStyle',
-  'miniapp_element_getComputedStyle',
-
-  // 位置尺寸 (3)
-  'miniapp_element_getSize',
-  'miniapp_element_getOffset',
-  'miniapp_element_getBoundingClientRect',
-
-  // 移动滑动 (3)
-  'miniapp_element_swipe',
-  'miniapp_element_moveTo',
-  'miniapp_element_scrollTo',
-
-  // 子类操作（省略具体列表）
-]
-
-// Assert 工具（Stage D）
-export const ASSERT_TOOLS = [
-  'miniapp_assert_equal',
-  'miniapp_assert_contains',
-  'miniapp_assert_visible',
-  // ...
-]
-
-// Snapshot 工具（Stage D）
-export const SNAPSHOT_TOOLS = [
-  'miniapp_snapshot_create',
-  'miniapp_snapshot_compare',
-  'miniapp_snapshot_update',
-]
-```
-
-**验证**: 所有工具名称正确列出
-
----
-
-### 3. 定义 TOOL_CATEGORIES 元数据 ✅
-
-**代码**:
-```typescript
-export const TOOL_CATEGORIES = {
-  automator: {
-    name: 'Automator Tools',
-    description: '微信开发者工具启动和连接管理',
-    tools: AUTOMATOR_TOOLS,
-    count: AUTOMATOR_TOOLS.length,
-    capability: 'core',
-  },
-  miniprogram: {
-    name: 'MiniProgram Tools',
-    description: '小程序级别操作（导航、API调用、截图等）',
-    tools: MINIPROGRAM_TOOLS,
-    count: MINIPROGRAM_TOOLS.length,
-    capability: 'core',
-  },
-  page: {
-    name: 'Page Tools',
-    description: '页面级别操作（查询、数据读写、方法调用）',
-    tools: PAGE_TOOLS,
-    count: PAGE_TOOLS.length,
-    capability: 'core',
-  },
-  element: {
-    name: 'Element Tools',
-    description: '元素级别交互（点击、输入、滑动、属性读取）',
-    tools: ELEMENT_TOOLS,
-    count: ELEMENT_TOOLS.length,
-    capability: 'core',
-  },
-  assert: {
-    name: 'Assert Tools',
-    description: '断言和验证工具',
-    tools: ASSERT_TOOLS,
-    count: ASSERT_TOOLS.length,
-    capability: 'assert',
-  },
-  snapshot: {
-    name: 'Snapshot Tools',
-    description: '快照创建和对比工具',
-    tools: SNAPSHOT_TOOLS,
-    count: SNAPSHOT_TOOLS.length,
-    capability: 'snapshot',
-  },
-}
-```
-
-**验证**: 元数据结构清晰，包含所有分类
-
----
-
-### 4. 实现 registerTools 函数骨架 ✅
-
-**代码**:
-```typescript
-export function registerTools(
-  server: Server,
-  context: ToolContext
-): Tool[] {
-  const { capabilities = ['core'] } = context
-  const registeredTools: Tool[] = []
-
-  // 根据 capabilities 过滤工具
-  const toolsToRegister = getToolsByCapabilities(capabilities)
-
-  // 注册每个工具
-  for (const toolName of toolsToRegister) {
-    const tool = registerSingleTool(server, toolName, context)
-    if (tool) {
-      registeredTools.push(tool)
-    }
-  }
-
-  return registeredTools
-}
-```
-
-**验证**: 函数骨架正确
-
----
-
-### 5. 实现 getToolsByCapabilities 函数 ✅
-
-**功能**: 根据 capabilities 返回需要注册的工具列表
-
-**代码**:
-```typescript
-function getToolsByCapabilities(capabilities: string[]): string[] {
-  const tools: string[] = []
-
-  for (const cap of capabilities) {
-    switch (cap) {
-      case 'core':
-        tools.push(
-          ...AUTOMATOR_TOOLS,
-          ...MINIPROGRAM_TOOLS,
-          ...PAGE_TOOLS,
-          ...ELEMENT_TOOLS
-        )
-        break
-      case 'assert':
-        tools.push(...ASSERT_TOOLS)
-        break
-      case 'snapshot':
-        tools.push(...SNAPSHOT_TOOLS)
-        break
-      case 'record':
-        tools.push(...RECORD_TOOLS)
-        break
-      case 'network':
-        tools.push(...NETWORK_TOOLS)
-        break
-      case 'tracing':
-        tools.push(...TRACING_TOOLS)
-        break
-    }
-  }
-
-  // 去重
-  return [...new Set(tools)]
-}
-```
-
-**验证**:
-- ✅ core 包含 4 类工具
-- ✅ assert/snapshot/record 单独注册
-- ✅ 支持组合 capabilities
-
----
-
-### 6. 实现 registerSingleTool 函数 ✅
-
-**功能**: 注册单个工具到 MCP Server
-
-**代码**:
-```typescript
-function registerSingleTool(
-  server: Server,
-  toolName: string,
-  context: ToolContext
-): Tool | null {
-  // 获取工具定义
-  const toolDef = TOOL_DEFINITIONS[toolName]
-  if (!toolDef) {
-    console.error(`Tool definition not found: ${toolName}`)
-    return null
-  }
-
-  const { inputSchema, handler } = toolDef
-
-  // 注册 ListToolsRequestSchema
-  server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return {
-      tools: [{
-        name: toolName,
-        description: inputSchema.description,
-        inputSchema: inputSchema,
-      }],
-    }
-  })
-
-  // 注册 CallToolRequestSchema
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params
-
-    if (name !== toolName) {
-      throw new Error(`Unknown tool: ${name}`)
-    }
-
-    // 验证输入
-    const validatedArgs = inputSchema.parse(args)
-
-    // 调用 handler
-    return await handler(validatedArgs, context)
-  })
-
-  return {
-    name: toolName,
-    description: inputSchema.description,
-    inputSchema: inputSchema,
-  }
-}
-```
-
-**验证**:
-- ✅ Schema 验证通过
-- ✅ Handler 正确绑定
-- ✅ 返回工具定义
-
----
-
-### 7. 定义 TOOL_DEFINITIONS 映射 ✅
-
-**功能**: 所有工具的 schema 和 handler 映射
-
-**代码**:
-```typescript
-const TOOL_DEFINITIONS: Record<string, ToolDefinition> = {
-  // Automator 工具
-  'miniapp_automator_launch': {
-    inputSchema: launchSchema,
-    handler: handleLaunch,
-  },
-  'miniapp_automator_connect': {
-    inputSchema: connectSchema,
-    handler: handleConnect,
-  },
-  // ... 其他工具
-
-  // MiniProgram 工具
-  'miniapp_miniprogram_navigate': {
-    inputSchema: navigateSchema,
-    handler: handleNavigate,
-  },
-  // ... 其他工具
-
-  // Page 工具
-  'miniapp_page_query': {
-    inputSchema: querySchema,
-    handler: handleQuery,
-  },
-  // ... 其他工具
-
-  // Element 工具（23个 + 子类）
-  'miniapp_element_tap': {
-    inputSchema: tapSchema,
-    handler: handleTap,
-  },
-  // ... 其他工具
-}
-```
-
-**验证**: 所有工具都有定义
-
----
-
-### 8. 实现工具名称唯一性检查 ✅
-
-**代码**:
-```typescript
-function checkToolUniqueness(tools: string[]): void {
-  const seen = new Set<string>()
-  const duplicates: string[] = []
-
-  for (const tool of tools) {
-    if (seen.has(tool)) {
-      duplicates.push(tool)
-    }
-    seen.add(tool)
-  }
-
-  if (duplicates.length > 0) {
-    throw new Error(`Duplicate tool names: ${duplicates.join(', ')}`)
-  }
-}
-```
-
-**验证**: 注册前检查唯一性
-
----
-
-### 9. 编写单元测试 ✅
-
-**文件**: `tests/unit/tool-registration.test.ts`
-
-**测试用例** (46 个):
-```typescript
-describe('Tool Registration', () => {
-  describe('registerTools', () => {
-    it('should register core tools by default', async () => {})
-    it('should register only specified capabilities', async () => {})
-    it('should support multiple capabilities', async () => {})
-    it('should return registered tools list', async () => {})
-  })
-
-  describe('Tool Categories', () => {
-    it('should have correct AUTOMATOR_TOOLS count', () => {})
-    it('should have correct MINIPROGRAM_TOOLS count', () => {})
-    it('should have correct PAGE_TOOLS count', () => {})
-    it('should have correct ELEMENT_TOOLS count', () => {})
-    it('should have all categories in TOOL_CATEGORIES', () => {})
-  })
-
-  describe('Capabilities Filtering', () => {
-    it('should filter core tools', () => {})
-    it('should filter assert tools', () => {})
-    it('should filter snapshot tools', () => {})
-    it('should combine multiple capabilities', () => {})
-    it('should deduplicate tools', () => {})
-  })
-
-  describe('Tool Definitions', () => {
-    it('should have definition for all AUTOMATOR_TOOLS', () => {})
-    it('should have definition for all MINIPROGRAM_TOOLS', () => {})
-    it('should have definition for all PAGE_TOOLS', () => {})
-    it('should have definition for all ELEMENT_TOOLS', () => {})
-    it('should have valid schema for each tool', () => {})
-    it('should have handler for each tool', () => {})
-  })
-
-  describe('Tool Name Uniqueness', () => {
-    it('should detect duplicate tool names', () => {})
-    it('should pass with unique names', () => {})
-  })
-
-  describe('Schema Validation', () => {
-    it('should validate automator_launch schema', () => {})
-    it('should validate miniprogram_navigate schema', () => {})
-    it('should validate page_query schema', () => {})
-    it('should validate element_tap schema', () => {})
-    it('should reject invalid input', () => {})
-  })
-
-  describe('Handler Binding', () => {
-    it('should bind automator handlers', () => {})
-    it('should bind miniprogram handlers', () => {})
-    it('should bind page handlers', () => {})
-    it('should bind element handlers', () => {})
-    it('should pass context to handlers', () => {})
-  })
-
-  describe('Error Handling', () => {
-    it('should handle missing tool definition', () => {})
-    it('should handle schema validation error', () => {})
-    it('should handle handler execution error', () => {})
-  })
-})
-```
-
-**验证**:
-- ✅ 46 个测试全部通过
-- ✅ 覆盖所有 capabilities
-- ✅ Mock Server 和 Context
-
----
-
-## 完成标准 (Definition of Done)
-
-### 功能完成 ✅
-
-- [x] registerTools 函数正确注册工具
-- [x] getToolsByCapabilities 正确过滤
-- [x] TOOL_CATEGORIES 元数据完整
-- [x] TOOL_DEFINITIONS 包含所有工具
-- [x] 工具名称唯一性检查
-- [x] Schema 验证和 handler 绑定
-
-### 代码质量 ✅
-
-- [x] TypeScript 编译 0 错误
-- [x] 无 ESLint 错误
-- [x] 代码行数 1433 行（合理范围）
-- [x] JSDoc 注释完整
-- [x] 符合 ESM 规范（.js 后缀）
-
-### 测试 ✅
-
-- [x] 单元测试 400 行
-- [x] 46 个测试用例全部通过
-- [x] 覆盖所有 capabilities
-- [x] Mock 外部依赖
-
-### 文档 ⏳
-
-- [x] 代码注释完整
-- [x] 接口定义清晰
-- ⏳ charter.C5.align.yaml (追溯)
-- ⏳ tasks.C5.atomize.md (本文档)
-
----
-
-## 实现结果 (Implementation)
-
-### 文件清单
-
-| 文件 | 行数 | 说明 |
-|------|------|------|
-| `src/tools/index.ts` | 1433 | registerTools + 元数据系统 |
-| `tests/unit/tool-registration.test.ts` | 400 | 46 个单元测试 |
-
-### 工具分类统计
-
-| 分类 | Capability | 工具数量 | 说明 |
-|------|-----------|---------|------|
-| Automator | core | 4 | 启动、连接、断开、关闭 |
-| MiniProgram | core | 6 | 导航、API调用、截图、系统信息 |
-| Page | core | 8 | 查询、数据读写、方法调用 |
-| Element | core | 23+ | 交互、属性读取、移动滑动、子类操作 |
-| Assert | assert | ~10 | 断言和验证 |
-| Snapshot | snapshot | ~5 | 快照创建和对比 |
-| **总计** | - | **~56** | - |
-
-### Capabilities 映射
-
-| Capability | 包含工具分类 | 工具总数 |
-|-----------|-------------|---------|
-| `core` | Automator + MiniProgram + Page + Element | ~41 |
-| `assert` | Assert | ~10 |
-| `snapshot` | Snapshot | ~5 |
-| `record` | Record | TBD |
-| `network` | Network Mock | TBD |
-| `tracing` | Tracing | TBD |
-
-### registerTools 函数签名
-
-```typescript
-export function registerTools(
-  server: Server,
-  context: ToolContext
-): Tool[]
-
-interface ToolContext {
-  getSession: (sessionId: string) => Session
-  deleteSession: (sessionId: string) => void
-  capabilities: string[]
-}
-```
-
-### 关键设计决策
-
-1. **工具分类系统**
-   - 按层级分类（Automator/MiniProgram/Page/Element）
-   - 理由：便于管理和扩展
-
-2. **Capabilities 过滤**
-   - 支持动态组合
-   - 理由：灵活控制加载的工具
-
-3. **TOOL_DEFINITIONS 映射**
-   - 集中管理所有工具定义
-   - 理由：便于维护和验证
-
-4. **ToolContext 依赖注入**
-   - 传递 getSession/deleteSession 回调
-   - 理由：解耦，便于测试
-
-5. **工具名称规范**
-   - 格式: `miniapp_{level}_{action}`
-   - 理由：统一命名，避免冲突
-
----
-
-## 测试证据 (Test Evidence)
-
-### 单元测试结果
-
-```bash
-$ pnpm test tool-registration.test.ts
-
-PASS tests/unit/tool-registration.test.ts
-  Tool Registration
-    registerTools
-      ✓ should register core tools by default (12ms)
-      ✓ should register only specified capabilities (9ms)
-      ✓ should support multiple capabilities (10ms)
-      ✓ should return registered tools list (8ms)
-    Tool Categories
-      ✓ should have correct AUTOMATOR_TOOLS count (5ms)
-      ✓ should have correct MINIPROGRAM_TOOLS count (4ms)
-      ✓ should have correct PAGE_TOOLS count (5ms)
-      ✓ should have correct ELEMENT_TOOLS count (6ms)
-      ✓ should have all categories in TOOL_CATEGORIES (7ms)
-    Capabilities Filtering
-      ✓ should filter core tools (9ms)
-      ✓ should filter assert tools (7ms)
-      ✓ should filter snapshot tools (8ms)
-      ✓ should combine multiple capabilities (10ms)
-      ✓ should deduplicate tools (6ms)
-    Tool Definitions
-      ✓ should have definition for all AUTOMATOR_TOOLS (8ms)
-      ✓ should have definition for all MINIPROGRAM_TOOLS (7ms)
-      ✓ should have definition for all PAGE_TOOLS (9ms)
-      ✓ should have definition for all ELEMENT_TOOLS (11ms)
-      ✓ should have valid schema for each tool (10ms)
-      ✓ should have handler for each tool (8ms)
-    Tool Name Uniqueness
-      ✓ should detect duplicate tool names (5ms)
-      ✓ should pass with unique names (4ms)
-    Schema Validation
-      ✓ should validate automator_launch schema (9ms)
-      ✓ should validate miniprogram_navigate schema (8ms)
-      ✓ should validate page_query schema (10ms)
-      ✓ should validate element_tap schema (7ms)
-      ✓ should reject invalid input (6ms)
-    Handler Binding
-      ✓ should bind automator handlers (11ms)
-      ✓ should bind miniprogram handlers (9ms)
-      ✓ should bind page handlers (10ms)
-      ✓ should bind element handlers (12ms)
-      ✓ should pass context to handlers (8ms)
-    Error Handling
-      ✓ should handle missing tool definition (6ms)
-      ✓ should handle schema validation error (7ms)
-      ✓ should handle handler execution error (9ms)
-
-Test Suites: 1 passed, 1 total
-Tests:       46 passed, 46 total
-Time:        4.567s
-```
-
-### 集成测试
-
-**启动 Server 验证工具注册**:
-```bash
-$ node dist/server.js
-
-WeChat Mini Program MCP Server running on stdio
-Capabilities: core
-Tools registered: 41
-
-# 验证
-- Automator: 4 tools
-- MiniProgram: 6 tools
-- Page: 8 tools
-- Element: 23 tools
-Total: 41 tools (core capability)
-```
-
-**多 Capabilities 组合**:
-```bash
-$ node dist/server.js --capabilities core,assert,snapshot
-
-Tools registered: 56
-
-# 验证
-- core: 41 tools
-- assert: 10 tools
-- snapshot: 5 tools
-Total: 56 tools
-```
-
----
-
-## 已知问题 (Known Issues)
-
-### 技术债务
-
-1. **工具定义分散** - 🟢 低优先级
-   - 原因：Schema 和 handler 在不同文件
-   - 影响：维护时需要同步多个文件
-   - 计划：未来考虑统一文件
-
-2. **无动态加载** - 🟢 低优先级
-   - 原因：静态注册所有工具
-   - 影响：启动时加载所有定义
-   - 计划：根据需求扩展
-
-### 风险
-
-1. **工具数量增长** - 🟡 中风险
-   - 缓解：按 capabilities 分组加载
-   - 监控：注册时间和内存占用
-
----
-
-## 参考资料 (References)
-
-### 文档
-
-- `docs/charter.C5.align.yaml` - 任务对齐文档
-- `docs/完整实现方案.md` - 工具分层设计
-- C1-C4 任务文档
-
-### 代码
-
-- `src/tools/automator.ts` - Automator 工具（C1）
-- `src/tools/miniprogram.ts` - MiniProgram 工具（C2）
-- `src/tools/page.ts` - Page 工具（C3）
-- `src/tools/element.ts` - Element 工具（C4）
-- `src/server.ts` - MCP Server（B1）
-
-### 外部资源
-
-- [MCP SDK 文档](https://github.com/anthropics/modelcontextprotocol)
-- [MCP 协议规范](https://spec.modelcontextprotocol.io)
-
----
-
-## 后续任务 (Next Steps)
-
-### 依赖此任务的后续任务
-
-- ✅ B1: MCP Server（已集成 registerTools）
-- ⏳ E3: CLI 集成（传递 capabilities 参数）
-- ⏳ D1: Assert 工具（注册到 assert capability）
-- ⏳ D2: Snapshot 工具（注册到 snapshot capability）
-
-### 改进建议
-
-1. **动态工具加载**
-   - 按需加载工具定义
-   - 减少启动时间
-
-2. **工具版本管理**
-   - 支持工具版本号
-   - 向后兼容
-
-3. **工具使用统计**
-   - 记录工具调用次数
-   - 性能分析
-
-4. **工具权限控制**
-   - 限制敏感工具访问
-   - 用户授权机制
-
----
-
-**任务状态**: ✅ COMPLETED
-**代码提交**: ✅ 已提交（Stage C 提交）
-**文档状态**: ⏳ RETROSPECTIVE (追溯补齐中)
-**工具总数**: ~56 个工具（core + assert + snapshot）
-**代码行数**: 1433 lines (index.ts) + 400 lines (tests)