@creatoria/miniapp-mcp 0.1.3 → 0.2.2

package/docs/charter.C5.align.yaml

@@ -1,220 +0,0 @@
-# Charter: [C5] 工具注册器
-
-task_id: C5
-task_name: 工具注册器实现（registerTools 函数 + 元数据系统）
-stage: C
-phase: Align (Retrospective)
-created_at: "2025-10-02"
-status: COMPLETED
-estimated_hours: 3-4
-actual_hours: 4
-
-## Goal (目标)
-
-实现统一的工具注册系统，按 capabilities 动态注册工具，提供工具分类、元数据管理和验证机制。
-
-**核心交付物**:
-- `src/tools/index.ts` - registerTools 函数 + 元数据系统 (1433 lines)
-- `tests/unit/tool-registration.test.ts` - 单元测试 (400 lines, 46 tests)
-- 功能:
-  - registerTools(server, context) 函数
-  - 6 个工具分类系统（AUTOMATOR, MINIPROGRAM, PAGE, ELEMENT, ASSERT, SNAPSHOT）
-  - TOOL_CATEGORIES 元数据（工具分类、描述、数量统计）
-  - Capabilities 过滤机制
-  - Schema 验证和 handler 绑定
-
-## Non-Goals (非目标)
-
-- ❌ 不实现工具的具体逻辑（由 C1-C4 完成）
-- ❌ 不实现动态工具加载（静态注册）
-- ❌ 不实现工具版本管理
-- ❌ 不实现工具权限控制
-
-## Scope (范围)
-
-### In Scope (包含)
-
-1. **registerTools 函数**
-   - ✅ 接收 MCP Server 实例
-   - ✅ 接收 ToolContext（getSession, deleteSession 回调）
-   - ✅ 根据 capabilities 过滤工具
-   - ✅ 批量注册工具到 Server
-   - ✅ 返回已注册工具列表
-
-2. **工具分类系统**
-   - ✅ AUTOMATOR_TOOLS: 4 个工具（launch, connect, disconnect, close）
-   - ✅ MINIPROGRAM_TOOLS: 6 个工具（navigate, callWx, evaluate, screenshot, getPageStack, getSystemInfo）
-   - ✅ PAGE_TOOLS: 8 个工具（query, queryAll, waitFor, getData, setData, callMethod, getSize, getScrollTop）
-   - ✅ ELEMENT_TOOLS: 23 个核心工具 + 子类操作
-   - ✅ ASSERT_TOOLS: 断言工具（Stage D）
-   - ✅ SNAPSHOT_TOOLS: 快照工具（Stage D）
-
-3. **TOOL_CATEGORIES 元数据**
-   - ✅ 工具分类名称和描述
-   - ✅ 每个分类包含的工具列表
-   - ✅ 工具数量统计
-   - ✅ Capability 映射关系
-
-4. **Capabilities 过滤**
-   - ✅ 支持 'core'（Automator + MiniProgram + Page + Element）
-   - ✅ 支持 'assert'（Assert 工具）
-   - ✅ 支持 'snapshot'（Snapshot 工具）
-   - ✅ 支持 'record'（Record 工具）
-   - ✅ 支持 'network'（Network Mock 工具）
-   - ✅ 支持 'tracing'（Tracing 工具）
-   - ✅ 支持组合 capabilities
-
-5. **工具验证**
-   - ✅ Schema 定义验证
-   - ✅ Handler 函数存在性检查
-   - ✅ 工具名称唯一性检查
-   - ✅ 错误日志和异常处理
-
-6. **ToolContext 接口**
-   - ✅ getSession(sessionId): Session
-   - ✅ deleteSession(sessionId): void
-   - ✅ 传递给所有工具 handler
-
-### Out of Scope (不包含)
-
-- ❌ 工具具体实现（C1-C4）
-- ❌ 动态工具加载
-- ❌ 工具版本管理
-- ❌ 工具权限控制
-- ❌ 工具使用统计
-
-## Constraints (约束)
-
-### Technical Constraints (技术约束)
-
-1. **MCP SDK 兼容**
-   - 使用 Server.setRequestHandler(CallToolRequestSchema, ...)
-   - 遵循 MCP 工具定义规范
-   - 正确返回工具列表和执行结果
-
-2. **工具命名规范**
-   - 格式: `miniapp_{level}_{action}`
-   - 示例: `miniapp_automator_launch`, `miniapp_element_tap`
-   - 全局唯一性
-
-3. **Capabilities 映射**
-   - core: Automator + MiniProgram + Page + Element
-   - assert: Assert 工具
-   - snapshot: Snapshot 工具
-   - record: Record 工具
-   - network: Network Mock 工具
-   - tracing: Tracing 工具
-
-4. **ToolContext 依赖注入**
-   - 通过参数传递 getSession/deleteSession
-   - 避免全局状态
-   - 便于测试和扩展
-
-### Business Constraints (业务约束)
-
-1. **注册时间**: <100ms
-2. **工具总数**: 当前 ~60 个工具（core + assert + snapshot）
-3. **内存占用**: 注册后 <10MB
-
-## Success Criteria (成功标准)
-
-### Functional Criteria (功能标准)
-
-- ✅ registerTools 正确注册工具
-- ✅ capabilities 过滤正确
-- ✅ 工具 handler 正确绑定
-- ✅ schema 验证通过
-- ✅ 返回正确的工具列表
-- ✅ TOOL_CATEGORIES 元数据完整
-
-### Quality Criteria (质量标准)
-
-- ✅ TypeScript 编译 0 错误
-- ✅ 单元测试覆盖率 >80%
-- ✅ 46 个测试用例全部通过
-- ✅ 无 ESLint 错误
-- ✅ JSDoc 注释完整
-
-### Documentation Criteria (文档标准)
-
-- ✅ registerTools 函数有详细注释
-- ✅ TOOL_CATEGORIES 有清晰说明
-- ✅ Capabilities 映射文档完整
-- ⏳ charter.C5.align.yaml (本文档)
-- ⏳ tasks.C5.atomize.md (任务卡)
-
-## Definition of Done (完成标准)
-
-**代码**:
-- ✅ `src/tools/index.ts` 实现完成 (1433 lines)
-- ✅ TypeScript 编译通过
-- ✅ registerTools 函数正确工作
-
-**测试**:
-- ✅ `tests/unit/tool-registration.test.ts` (400 lines)
-- ✅ 46 个测试用例全部通过
-- ✅ 覆盖所有 capabilities 组合
-- ✅ Mock Server 和 Context
-
-**文档**:
-- ⏳ charter.C5.align.yaml (追溯)
-- ⏳ tasks.C5.atomize.md (追溯)
-- ✅ README 工具列表更新
-
-**Git**:
-- ✅ 已提交（Stage C 提交）
-
-## Dependencies (依赖)
-
-**前置任务**:
-- ✅ C1: Automator 工具
-- ✅ C2: MiniProgram 工具
-- ✅ C3: Page 工具
-- ✅ C4: Element 工具
-- ✅ B1: MCP Server 骨架
-
-**后续任务**:
-- C5 → E3 (CLI 传递 capabilities 参数)
-- C5 → D1 (Assert 工具注册)
-- C5 → D2 (Snapshot 工具注册)
-
-## Risks (风险)
-
-### Technical Risks (技术风险)
-
-1. **工具数量增长** - 🟡 中风险
-   - 影响：工具过多可能影响性能
-   - 缓解：按 capabilities 分组加载
-
-2. **命名冲突** - 🟢 已缓解
-   - 风险：工具名称重复
-   - 缓解：注册时检查唯一性
-
-3. **Schema 验证失败** - 🟢 已缓解
-   - 风险：Schema 定义错误导致注册失败
-   - 缓解：单元测试覆盖所有工具
-
-### Business Risks (业务风险)
-
-1. **注册时间过长** - 🟢 已缓解
-   - 影响：启动慢
-   - 缓解：优化注册逻辑，<100ms
-
-## Open Questions (未决问题)
-
-- ❓ 是否需要支持动态工具加载？（当前静态注册）
-- ❓ 是否需要工具版本管理？（当前无版本）
-- ❓ 是否需要工具使用统计？（当前不收集）
-
-## References (参考资料)
-
-- `docs/完整实现方案.md` - 工具分层设计
-- `docs/微信小程序自动化完整操作手册.md` - 完整 API 参考
-- `@modelcontextprotocol/sdk` 文档
-- C1-C4 任务文档
-
----
-
-**Approval**: ✅ RETROSPECTIVE APPROVED
-**Implementation**: ✅ COMPLETED (1433 lines + 46 tests)
-**Documentation**: ⏳ IN PROGRESS

package/docs/charter.D1.align.yaml

@@ -1,190 +0,0 @@
-# Charter: [D1] 断言工具集
-
-task_id: D1
-task_name: 断言工具集实现
-stage: D
-phase: Align (Retrospective)
-created_at: "2025-10-02"
-status: COMPLETED
-estimated_hours: 2-3
-actual_hours: 2.5
-
-## Goal (目标)
-
-实现完整的断言工具集，为小程序自动化测试提供强大的验证能力。
-
-**核心交付物**:
-- `src/tools/assert.ts` - 9 个断言工具实现 (465 lines)
-- `tests/unit/assert.test.ts` - 单元测试 (394 lines, 27 tests)
-- 工具: assertExists, assertNotExists, assertText, assertTextContains, assertValue, assertAttribute, assertProperty, assertData, assertVisible
-
-## Non-Goals (非目标)
-
-- ❌ 不实现自定义断言逻辑（仅标准断言）
-- ❌ 不实现软断言（所有断言失败即抛错）
-- ❌ 不实现断言结果聚合报告（留给未来）
-- ❌ 不实现快照比对（属于 D2）
-
-## Scope (范围)
-
-### In Scope (包含)
-
-1. **元素存在性断言**
-   - ✅ assertExists - 断言元素存在
-   - ✅ assertNotExists - 断言元素不存在
-   - ✅ 支持 selector 和 pagePath 参数
-
-2. **文本内容断言**
-   - ✅ assertText - 精确文本匹配
-   - ✅ assertTextContains - 文本包含子串
-   - ✅ 返回期望值和实际值对比
-
-3. **表单值断言**
-   - ✅ assertValue - input/textarea 值断言
-   - ✅ 支持任意表单组件
-
-4. **属性和状态断言**
-   - ✅ assertAttribute - HTML 属性断言
-   - ✅ assertProperty - JavaScript 属性断言
-   - ✅ assertVisible - 可见性断言（基于尺寸）
-
-5. **页面数据断言**
-   - ✅ assertData - Page data 断言
-   - ✅ 支持嵌套路径访问
-
-### Out of Scope (不包含)
-
-- ❌ 正则表达式匹配（使用字符串精确/包含匹配）
-- ❌ 数值范围断言（使用精确匹配）
-- ❌ 数组长度/内容断言（使用 JSON 比较）
-- ❌ 自定义匹配器
-
-## Constraints (约束)
-
-### Technical Constraints (技术约束)
-
-1. **工具依赖**
-   - 复用 Page 工具（query, getData）
-   - 复用 Element 工具（getText, getValue, getAttribute, etc.）
-   - 通过函数调用而非直接 SessionState 访问
-
-2. **错误格式**
-   - 所有断言失败抛出 Error
-   - 错误消息格式: `Assertion failed: <详细说明>`
-   - 包含期望值 vs 实际值对比
-
-3. **返回值结构**
-   - 成功: `{ success: true, message: string, actual?: any }`
-   - 失败: 抛出 Error（不返回 success: false）
-
-4. **日志记录**
-   - 使用 session.logger 记录所有断言
-   - 包含 info（成功）和 error（失败）
-
-### Business Constraints (业务约束)
-
-1. **执行时间**: 单个断言 <500ms
-2. **错误信息**: 必须清晰指明失败原因
-3. **可组合性**: 可在测试流程中链式使用
-
-## Success Criteria (成功标准)
-
-### Functional Criteria (功能标准)
-
-- ✅ assertExists 正确检测元素存在性
-- ✅ assertNotExists 正确检测元素不存在
-- ✅ assertText 精确匹配文本内容
-- ✅ assertTextContains 检测子串包含
-- ✅ assertValue 验证表单值
-- ✅ assertAttribute 验证 HTML 属性
-- ✅ assertProperty 验证 JS 属性
-- ✅ assertData 验证页面数据（含嵌套）
-- ✅ assertVisible 验证元素可见性（非零尺寸）
-
-### Quality Criteria (质量标准)
-
-- ✅ TypeScript 编译 0 错误
-- ✅ 单元测试覆盖率 >90%
-- ✅ 27 个测试用例全部通过
-- ✅ 无 ESLint 错误
-- ✅ JSDoc 注释完整
-
-### Documentation Criteria (文档标准)
-
-- ✅ 每个工具有函数签名和 JSDoc
-- ✅ 错误消息格式统一
-- ⏳ charter.D1.align.yaml (本文档)
-- ⏳ tasks.D1.atomize.md (任务卡)
-
-## Definition of Done (完成标准)
-
-**代码**:
-- ✅ `src/tools/assert.ts` 实现完成 (465 lines)
-- ✅ 9 个断言工具全部实现
-- ✅ TypeScript 编译通过
-
-**测试**:
-- ✅ `tests/unit/assert.test.ts` (394 lines)
-- ✅ 27 个测试用例全部通过
-- ✅ 覆盖成功和失败场景
-- ✅ Mock page/element 工具依赖
-
-**文档**:
-- ⏳ charter.D1.align.yaml (追溯)
-- ⏳ tasks.D1.atomize.md (追溯)
-- ✅ 代码注释完整
-
-**Git**:
-- ✅ 已提交（commit: feat: [D1] 断言工具集实现）
-
-## Dependencies (依赖)
-
-**前置任务**:
-- ✅ C3: Page 工具（query, getData）
-- ✅ C4: Element 工具（getText, getValue, getAttribute, getProperty, getSize）
-- ✅ B2: SessionState 和日志系统
-
-**后续任务**:
-- D1 → Stage E (集成到工具注册器)
-- D1 → Stage F (端到端测试示例)
-
-## Risks (风险)
-
-### Technical Risks (技术风险)
-
-1. **断言性能** - 🟢 低风险
-   - 影响：大量断言可能拖慢测试
-   - 缓解：每个断言基于单次元素/数据查询
-
-2. **错误消息可读性** - 🟢 已缓解
-   - 风险：期望值 vs 实际值不清晰
-   - 缓解：统一格式 `Expected: "...", Actual: "..."`
-
-3. **深度嵌套数据比较** - 🟡 中风险
-   - 风险：JSON.stringify 可能无法正确比较复杂对象
-   - 缓解：当前使用 JSON 序列化比较，未来可引入深度比较库
-
-### Business Risks (业务风险)
-
-1. **断言失败定位** - 🟢 已缓解
-   - 影响：用户不知道哪个断言失败
-   - 缓解：错误消息包含 selector/refId/path 信息
-
-## Open Questions (未决问题)
-
-- ❓ 是否需要支持正则表达式匹配？（当前仅字符串）
-- ❓ 是否需要软断言（收集所有失败后统一报告）？（当前硬断言）
-- ❓ 是否需要自定义匹配器扩展机制？（当前固定 9 个工具）
-
-## References (参考资料)
-
-- `docs/完整实现方案.md` - 工具分层设计
-- `src/tools/page.ts` - Page 工具依赖
-- `src/tools/element.ts` - Element 工具依赖
-- Playwright Assertions - 断言设计参考
-
----
-
-**Approval**: ✅ RETROSPECTIVE APPROVED
-**Implementation**: ✅ COMPLETED
-**Documentation**: ⏳ IN PROGRESS

package/docs/charter.D2.align.yaml

@@ -1,234 +0,0 @@
-# Charter: [D2] 快照工具集
-
-task_id: D2
-task_name: 快照工具集实现
-stage: D
-phase: Align (Retrospective)
-created_at: "2025-10-02"
-status: COMPLETED
-estimated_hours: 2-3
-actual_hours: 2
-
-## Goal (目标)
-
-实现完整的快照工具集，为小程序自动化测试提供状态捕获和回溯能力。
-
-**核心交付物**:
-- `src/tools/snapshot.ts` - 3 个快照工具实现 (352 lines)
-- `tests/unit/snapshot.test.ts` - 单元测试 (251 lines, 10 tests)
-- 工具: snapshotPage, snapshotFull, snapshotElement
-
-## Non-Goals (非目标)
-
-- ❌ 不实现快照比对（diff）功能
-- ❌ 不实现快照回放（restore）功能
-- ❌ 不实现快照压缩/归档（仅原始 JSON + PNG）
-- ❌ 不实现多快照管理（仅单次捕获）
-
-## Scope (范围)
-
-### In Scope (包含)
-
-1. **snapshotPage - 页面快照**
-   - ✅ 捕获当前页面数据（data + query）
-   - ✅ 可选截图（PNG 格式）
-   - ✅ 保存为 JSON + 可选 PNG
-   - ✅ 返回文件路径
-
-2. **snapshotFull - 完整应用快照**
-   - ✅ 捕获系统信息（systemInfo）
-   - ✅ 捕获页面栈（pageStack）
-   - ✅ 捕获当前页面数据
-   - ✅ 可选截图（PNG 格式）
-   - ✅ 保存为 JSON + 可选 PNG
-
-3. **snapshotElement - 元素快照**
-   - ✅ 捕获元素文本（text）
-   - ✅ 捕获元素尺寸（size）
-   - ✅ 捕获元素位置（offset）
-   - ✅ 可选截图（PNG 格式）
-   - ✅ 保存为 JSON + 可选 PNG
-
-4. **通用功能**
-   - ✅ 自动生成文件名（带时间戳）
-   - ✅ 支持自定义文件名
-   - ✅ 使用 OutputManager 管理文件
-   - ✅ 时间戳记录（ISO8601 格式）
-
-### Out of Scope (不包含)
-
-- ❌ 快照比对（diff）
-- ❌ 快照恢复（restore）
-- ❌ 快照版本控制（git-like）
-- ❌ 快照压缩（zip/tar）
-
-## Constraints (约束)
-
-### Technical Constraints (技术约束)
-
-1. **工具依赖**
-   - 复用 MiniProgram 工具（getPageStack, getSystemInfo, screenshot）
-   - 复用 Page 工具（getData）
-   - 复用 Element 工具（getText, getSize, getOffset）
-   - 使用 OutputManager 管理文件输出
-
-2. **文件格式**
-   - JSON: 结构化数据，包含时间戳
-   - PNG: 截图文件（可选）
-   - 文件命名: `snapshot-{timestamp}.json` 或自定义
-
-3. **数据结构**
-   - **snapshotPage**:
-     ```typescript
-     {
-       timestamp: string          // ISO8601
-       pagePath: string           // 当前页面路径
-       pageData: any              // 页面 data
-       pageQuery: Record<string, any>  // 页面 query
-     }
-     ```
-   - **snapshotFull**:
-     ```typescript
-     {
-       timestamp: string
-       systemInfo: any            // 系统信息
-       pageStack: Array<{path, query}>  // 页面栈
-       currentPage: {
-         path: string
-         query: Record<string, any>
-         data: any
-       }
-     }
-     ```
-   - **snapshotElement**:
-     ```typescript
-     {
-       timestamp: string
-       refId: string
-       text?: string
-       attributes: Record<string, any>
-       size: {width, height} | null
-       offset: {left, top} | null
-     }
-     ```
-
-4. **返回值结构**
-   ```typescript
-   {
-     success: boolean
-     message: string
-     snapshotPath: string         // JSON 文件路径
-     screenshotPath?: string      // PNG 文件路径（可选）
-     data: {/* 快照数据 */}
-   }
-   ```
-
-### Business Constraints (业务约束)
-
-1. **执行时间**: 单次快照 <2s（含截图）
-2. **文件大小**: JSON <1MB, PNG <5MB
-3. **存储位置**: 默认 `outputDir`，可配置
-
-## Success Criteria (成功标准)
-
-### Functional Criteria (功能标准)
-
-- ✅ snapshotPage 正确捕获页面数据和截图
-- ✅ snapshotFull 正确捕获应用全局状态
-- ✅ snapshotElement 正确捕获元素状态
-- ✅ JSON 文件包含完整数据和时间戳
-- ✅ 截图可选（includeScreenshot 参数）
-- ✅ 支持自定义文件名
-- ✅ 文件保存到正确路径
-
-### Quality Criteria (质量标准)
-
-- ✅ TypeScript 编译 0 错误
-- ✅ 单元测试覆盖率 >80%
-- ✅ 10 个测试用例全部通过
-- ✅ 无 ESLint 错误
-- ✅ JSDoc 注释完整
-
-### Documentation Criteria (文档标准)
-
-- ✅ 每个工具有函数签名和 JSDoc
-- ✅ 数据结构定义清晰
-- ⏳ charter.D2.align.yaml (本文档)
-- ⏳ tasks.D2.atomize.md (任务卡)
-
-## Definition of Done (完成标准)
-
-**代码**:
-- ✅ `src/tools/snapshot.ts` 实现完成 (352 lines)
-- ✅ 3 个快照工具全部实现
-- ✅ TypeScript 编译通过
-
-**测试**:
-- ✅ `tests/unit/snapshot.test.ts` (251 lines)
-- ✅ 10 个测试用例全部通过
-- ✅ 覆盖成功和失败场景
-- ✅ Mock miniprogram/page/element 工具依赖
-
-**文档**:
-- ⏳ charter.D2.align.yaml (追溯)
-- ⏳ tasks.D2.atomize.md (追溯)
-- ✅ 代码注释完整
-
-**Git**:
-- ✅ 已提交（commit: feat: [D2] 快照能力实现）
-
-## Dependencies (依赖)
-
-**前置任务**:
-- ✅ C2: MiniProgram 工具（getPageStack, getSystemInfo, screenshot）
-- ✅ C3: Page 工具（getData）
-- ✅ C4: Element 工具（getText, getSize, getOffset）
-- ✅ B3: OutputManager 实现
-
-**后续任务**:
-- D2 → Stage E (集成到工具注册器)
-- D2 → Stage F (端到端测试示例)
-
-## Risks (风险)
-
-### Technical Risks (技术风险)
-
-1. **大数据量快照** - 🟡 中风险
-   - 影响：页面数据过大导致 JSON 文件巨大
-   - 缓解：当前无限制，未来可添加大小警告
-
-2. **截图失败** - 🟢 已缓解
-   - 风险：截图工具失败导致快照失败
-   - 缓解：截图为可选（includeScreenshot: false 可跳过）
-
-3. **文件名冲突** - 🟢 已缓解
-   - 风险：时间戳相同导致文件覆盖
-   - 缓解：OutputManager 使用 `Date.now()` 精确到毫秒
-
-### Business Risks (业务风险)
-
-1. **存储空间** - 🟡 中风险
-   - 影响：大量快照占用磁盘空间
-   - 缓解：用户自行管理 outputDir 清理
-
-## Open Questions (未决问题)
-
-- ❓ 是否需要快照压缩（zip）以节省空间？（当前原始文件）
-- ❓ 是否需要快照比对功能？（当前仅捕获）
-- ❓ 是否需要快照恢复功能？（当前仅只读）
-- ❓ 是否需要限制单个快照文件大小？（当前无限制）
-
-## References (参考资料)
-
-- `docs/完整实现方案.md` - 工具分层设计
-- `src/tools/miniprogram.ts` - MiniProgram 工具依赖
-- `src/tools/page.ts` - Page 工具依赖
-- `src/tools/element.ts` - Element 工具依赖
-- `src/core/output.ts` - OutputManager 实现
-- Playwright Screenshots - 截图功能参考
-
----
-
-**Approval**: ✅ RETROSPECTIVE APPROVED
-**Implementation**: ✅ COMPLETED
-**Documentation**: ⏳ IN PROGRESS