@creatoria/miniapp-mcp 0.1.0

package/docs/charter.C2.align.yaml

@@ -0,0 +1,202 @@
+# Charter: [C2] MiniProgram 工具
+
+task_id: C2
+task_name: MiniProgram 工具实现
+stage: C
+phase: Align (Retrospective)
+created_at: "2025-10-02"
+status: COMPLETED
+estimated_hours: 3-4
+actual_hours: 4
+
+## Goal (目标)
+
+实现 MiniProgram 级别的 6 个 MCP 工具，封装小程序导航、WX API 调用、代码执行、截图和系统信息获取功能。
+
+**核心交付物**:
+- `src/tools/miniprogram.ts` - 6 个工具实现 (330 lines)
+- `tests/unit/miniprogram.test.ts` - 单元测试 (403 lines, 25 tests)
+- 工具: navigate, callWx, evaluate, screenshot, getPageStack, getSystemInfo
+
+## Non-Goals (非目标)
+
+- ❌ 不实现 Page 级别工具（留给 C3）
+- ❌ 不实现元素查询（属于 Page 工具）
+- ❌ 不实现页面数据操作（属于 Page 工具）
+- ❌ 不实现复杂的导航历史管理
+
+## Scope (范围)
+
+### In Scope (包含)
+
+1. **navigate 工具**
+   - ✅ 支持 5 种导航方法：navigateTo, redirectTo, navigateBack, switchTab, reLaunch
+   - ✅ 支持路径参数（url, query）
+   - ✅ 支持返回层级（delta）
+   - ✅ 等待页面加载完成
+
+2. **callWx 工具**
+   - ✅ 调用微信小程序 API (wx.*)
+   - ✅ 支持任意参数传递
+   - ✅ 返回 API 执行结果
+   - ✅ 错误处理和日志记录
+
+3. **evaluate 工具**
+   - ✅ 在小程序环境中执行 JavaScript 代码
+   - ✅ 支持异步代码执行
+   - ✅ 返回执行结果
+   - ✅ 错误捕获和堆栈跟踪
+
+4. **screenshot 工具**
+   - ✅ 截取当前页面截图
+   - ✅ 保存到指定路径
+   - ✅ 返回文件路径和元数据
+   - ✅ 支持自动生成文件名
+
+5. **getPageStack 工具**
+   - ✅ 获取当前页面栈信息
+   - ✅ 返回所有页面路径
+   - ✅ 标识当前活动页面
+
+6. **getSystemInfo 工具**
+   - ✅ 获取设备系统信息
+   - ✅ 返回平台、版本、屏幕等信息
+   - ✅ 兼容微信 API 格式
+
+### Out of Scope (不包含)
+
+- ❌ 元素查询和操作（C3/C4）
+- ❌ 页面数据读写（C3）
+- ❌ 断言和验证（Stage D）
+- ❌ 网络 Mock（Stage F）
+
+## Constraints (约束)
+
+### Technical Constraints (技术约束)
+
+1. **miniprogram-automator 依赖**
+   - 使用 MiniProgram 实例的官方 API
+   - 遵循异步操作规范
+   - 正确处理页面加载时序
+
+2. **导航约束**
+   - navigateTo: 最多 10 层
+   - switchTab: 仅限 tabBar 页面
+   - reLaunch: 关闭所有页面
+   - navigateBack: 不能超过当前层级
+
+3. **截图约束**
+   - 格式: PNG
+   - 默认保存路径: outputDir/screenshots/
+   - 文件名格式: screenshot-{timestamp}.png
+
+4. **evaluate 约束**
+   - 执行环境: 小程序渲染层
+   - 超时时间: 30 秒
+   - 不支持 Node.js API
+
+### Business Constraints (业务约束)
+
+1. **导航时间**: <2 秒
+2. **API 调用时间**: <5 秒
+3. **截图时间**: <3 秒
+4. **evaluate 超时**: 30 秒
+
+## Success Criteria (成功标准)
+
+### Functional Criteria (功能标准)
+
+- ✅ navigate 支持 5 种导航方法
+- ✅ callWx 成功调用微信 API
+- ✅ evaluate 执行 JS 代码并返回结果
+- ✅ screenshot 生成正确的截图文件
+- ✅ getPageStack 返回完整页面栈
+- ✅ getSystemInfo 返回系统信息
+
+### Quality Criteria (质量标准)
+
+- ✅ TypeScript 编译 0 错误
+- ✅ 单元测试覆盖率 >80%
+- ✅ 25 个测试用例全部通过
+- ✅ 无 ESLint 错误
+- ✅ JSDoc 注释完整
+
+### Documentation Criteria (文档标准)
+
+- ✅ 每个工具有 zod schema 定义
+- ✅ 导航方法枚举清晰
+- ✅ 工具描述包含示例
+- ⏳ charter.C2.align.yaml (本文档)
+- ⏳ tasks.C2.atomize.md (任务卡)
+
+## Definition of Done (完成标准)
+
+**代码**:
+- ✅ `src/tools/miniprogram.ts` 实现完成 (330 lines)
+- ✅ TypeScript 编译通过
+- ✅ 6 个工具正确注册
+
+**测试**:
+- ✅ `tests/unit/miniprogram.test.ts` (403 lines)
+- ✅ 25 个测试用例全部通过
+- ✅ 覆盖所有导航方法
+- ✅ Mock MiniProgram 实例
+
+**文档**:
+- ⏳ charter.C2.align.yaml (追溯)
+- ⏳ tasks.C2.atomize.md (追溯)
+- ✅ README 工具列表更新
+
+**Git**:
+- ✅ 已提交（Stage C 提交）
+
+## Dependencies (依赖)
+
+**前置任务**:
+- ✅ C1: Automator 工具（获取 MiniProgram 实例）
+- ✅ B2: SessionStore（管理 MiniProgram 实例）
+
+**后续任务**:
+- C2 → C3 (Page 工具需要导航到页面)
+- C2 → C5 (工具注册器集成)
+
+## Risks (风险)
+
+### Technical Risks (技术风险)
+
+1. **导航时序问题** - 🟡 中风险
+   - 影响：页面未加载完成就执行操作
+   - 缓解：使用 waitFor 等待页面稳定
+
+2. **callWx 参数序列化** - 🟢 已缓解
+   - 风险：复杂对象无法传递
+   - 缓解：使用 JSON 序列化
+
+3. **evaluate 安全性** - 🟡 中风险
+   - 影响：执行任意代码可能导致安全问题
+   - 缓解：仅在测试环境使用
+
+### Business Risks (业务风险)
+
+1. **截图文件管理** - 🟢 已缓解
+   - 影响：大量截图占用磁盘空间
+   - 缓解：用户自行清理 outputDir
+
+## Open Questions (未决问题)
+
+- ❓ 是否需要支持导航历史回退？（当前仅 navigateBack）
+- ❓ 是否需要限制 evaluate 可执行的代码？（当前无限制）
+- ❓ 截图是否需要支持压缩和格式转换？（当前仅 PNG）
+
+## References (参考资料)
+
+- `docs/微信小程序自动化完整操作手册.md` - MiniProgram API 文档
+- `docs/完整实现方案.md` - 工具分层设计
+- `miniprogram-automator` 官方文档
+- 微信小程序 API 文档
+
+---
+
+**Approval**: ✅ RETROSPECTIVE APPROVED
+**Implementation**: ✅ COMPLETED
+**Documentation**: ⏳ IN PROGRESS

package/docs/charter.C3.align.yaml

@@ -0,0 +1,211 @@
+# Charter: [C3] Page 工具
+
+task_id: C3
+task_name: Page 工具实现
+stage: C
+phase: Align (Retrospective)
+created_at: "2025-10-02"
+status: COMPLETED
+estimated_hours: 3-4
+actual_hours: 4
+
+## Goal (目标)
+
+实现 Page 级别的 8 个 MCP 工具，封装页面元素查询、等待、数据读写、方法调用和页面属性获取功能。
+
+**核心交付物**:
+- `src/tools/page.ts` - 8 个工具实现 (458 lines)
+- `tests/unit/page.test.ts` - 单元测试 (450 lines, 27 tests)
+- 工具: query, queryAll, waitFor, getData, setData, callMethod, getSize, getScrollTop
+
+## Non-Goals (非目标)
+
+- ❌ 不实现元素交互操作（留给 C4）
+- ❌ 不实现元素属性读取（留给 C4）
+- ❌ 不实现复杂的等待条件组合
+- ❌ 不实现数据变更监听
+
+## Scope (范围)
+
+### In Scope (包含)
+
+1. **query 工具**
+   - ✅ 单元素查询（selector/xpath）
+   - ✅ 支持 ElementRef 协议
+   - ✅ 支持页面路径指定
+   - ✅ 支持缓存和保存
+
+2. **queryAll 工具**
+   - ✅ 多元素查询
+   - ✅ 返回元素数组
+   - ✅ 支持索引访问
+
+3. **waitFor 工具**
+   - ✅ 等待元素出现
+   - ✅ 支持超时配置
+   - ✅ 支持自定义条件
+
+4. **getData 工具**
+   - ✅ 获取页面数据
+   - ✅ 支持路径查询（如 user.name）
+   - ✅ 返回完整数据或部分数据
+
+5. **setData 工具**
+   - ✅ 设置页面数据
+   - ✅ 支持批量更新
+   - ✅ 自动触发页面渲染
+
+6. **callMethod 工具**
+   - ✅ 调用页面方法
+   - ✅ 支持参数传递
+   - ✅ 返回方法结果
+
+7. **getSize 工具**
+   - ✅ 获取页面尺寸
+   - ✅ 返回宽度和高度
+
+8. **getScrollTop 工具**
+   - ✅ 获取页面滚动位置
+   - ✅ 返回垂直滚动距离
+
+### Out of Scope (不包含)
+
+- ❌ 元素点击、输入等交互（C4）
+- ❌ 元素属性、文本读取（C4）
+- ❌ 断言和验证（Stage D）
+- ❌ 页面性能监控
+
+## Constraints (约束)
+
+### Technical Constraints (技术约束)
+
+1. **miniprogram-automator 依赖**
+   - 使用 Page 实例的官方 API
+   - 遵循 WXML 选择器规范
+   - 支持 XPath 查询
+
+2. **ElementRef 协议**
+   - 支持 refId（缓存引用）
+   - 支持 selector（WXML 选择器）
+   - 支持 xpath（XPath 选择器）
+   - 支持 index（多元素索引）
+   - 支持 save（保存到缓存）
+
+3. **查询约束**
+   - selector: 支持 class, id, tag, attribute
+   - xpath: 完整 XPath 语法
+   - 超时默认: 5 秒
+
+4. **数据操作约束**
+   - setData: 自动触发页面渲染
+   - getData: 支持点记法路径（如 user.name）
+   - callMethod: 方法必须在 Page 定义中
+
+### Business Constraints (业务约束)
+
+1. **查询时间**: <2 秒
+2. **等待超时**: 默认 5 秒，可配置最大 30 秒
+3. **数据操作**: <1 秒
+4. **方法调用**: <5 秒
+
+## Success Criteria (成功标准)
+
+### Functional Criteria (功能标准)
+
+- ✅ query 支持 selector 和 xpath
+- ✅ queryAll 返回元素数组
+- ✅ waitFor 等待元素出现
+- ✅ getData 获取页面数据
+- ✅ setData 更新页面数据
+- ✅ callMethod 调用页面方法
+- ✅ getSize 返回页面尺寸
+- ✅ getScrollTop 返回滚动位置
+
+### Quality Criteria (质量标准)
+
+- ✅ TypeScript 编译 0 错误
+- ✅ 单元测试覆盖率 >80%
+- ✅ 27 个测试用例全部通过
+- ✅ 无 ESLint 错误
+- ✅ JSDoc 注释完整
+
+### Documentation Criteria (文档标准)
+
+- ✅ ElementRef 协议文档清晰
+- ✅ 选择器示例完整
+- ✅ 工具描述包含用法
+- ⏳ charter.C3.align.yaml (本文档)
+- ⏳ tasks.C3.atomize.md (任务卡)
+
+## Definition of Done (完成标准)
+
+**代码**:
+- ✅ `src/tools/page.ts` 实现完成 (458 lines)
+- ✅ TypeScript 编译通过
+- ✅ 8 个工具正确注册
+
+**测试**:
+- ✅ `tests/unit/page.test.ts` (450 lines)
+- ✅ 27 个测试用例全部通过
+- ✅ 覆盖 ElementRef 协议
+- ✅ Mock Page 实例
+
+**文档**:
+- ⏳ charter.C3.align.yaml (追溯)
+- ⏳ tasks.C3.atomize.md (追溯)
+- ✅ README 工具列表更新
+
+**Git**:
+- ✅ 已提交（Stage C 提交）
+
+## Dependencies (依赖)
+
+**前置任务**:
+- ✅ C2: MiniProgram 工具（导航到页面）
+- ✅ B2: SessionStore（管理 Page 实例）
+- ✅ ElementRef 协议设计
+
+**后续任务**:
+- C3 → C4 (Element 工具需要元素引用)
+- C3 → C5 (工具注册器集成)
+
+## Risks (风险)
+
+### Technical Risks (技术风险)
+
+1. **选择器复杂性** - 🟡 中风险
+   - 影响：复杂选择器可能查询失败
+   - 缓解：提供详细错误信息和示例
+
+2. **元素缓存失效** - 🟡 中风险
+   - 影响：页面更新后缓存的元素引用失效
+   - 缓解：页面变化时自动清理缓存
+
+3. **waitFor 超时** - 🟢 已缓解
+   - 风险：等待条件永不满足导致超时
+   - 缓解：可配置超时时间，明确错误提示
+
+### Business Risks (业务风险)
+
+1. **性能问题** - 🟢 已缓解
+   - 影响：频繁查询可能影响性能
+   - 缓解：支持元素缓存减少重复查询
+
+## Open Questions (未决问题)
+
+- ❓ 是否需要支持自定义等待条件函数？（当前仅等待元素）
+- ❓ 是否需要支持批量查询优化？（当前逐个查询）
+- ❓ 元素缓存策略是否需要优化？（当前页面变化时清理）
+
+## References (参考资料)
+
+- `docs/微信小程序自动化完整操作手册.md` - Page API 文档
+- `docs/完整实现方案.md` - ElementRef 协议设计
+- `miniprogram-automator` 官方文档
+- WXML 选择器文档
+
+---
+
+**Approval**: ✅ RETROSPECTIVE APPROVED
+**Implementation**: ✅ COMPLETED
+**Documentation**: ⏳ IN PROGRESS

package/docs/charter.C4.align.yaml

@@ -0,0 +1,263 @@
+# Charter: [C4] Element 工具完整实现
+
+task_id: C4
+task_name: Element 工具完整实现（23个工具 + 子类操作）
+stage: C
+phase: Align (Retrospective)
+created_at: "2025-10-02"
+status: COMPLETED
+estimated_hours: 6-8
+actual_hours: 8
+
+## Goal (目标)
+
+实现 Element 级别的完整工具集，包括 23 个核心交互工具和 6 类专用组件操作，覆盖点击、长按、触摸事件、属性读取、输入、滑动、移动等所有元素操作。
+
+**核心交付物**:
+- `src/tools/element.ts` - 23 个工具 + 子类操作 (956 lines)
+- `tests/unit/element.test.ts` - 单元测试 (1104 lines, 72 tests)
+- 工具分类:
+  - **交互操作** (7个): tap, longpress, touchstart, touchmove, touchend, input, trigger
+  - **属性读取** (6个): getText, getAttribute, getValue, getProperty, getStyle, getComputedStyle
+  - **位置尺寸** (3个): getSize, getOffset, getBoundingClientRect
+  - **移动滑动** (3个): swipe, moveTo, scrollTo
+  - **子类操作** (6类): Input, Textarea, Picker, ScrollView, Swiper, MovableView
+
+## Non-Goals (非目标)
+
+- ❌ 不实现断言工具（留给 Stage D）
+- ❌ 不实现录制功能（留给 Stage F）
+- ❌ 不实现元素截图（属于 Page 级别）
+- ❌ 不实现拖拽到其他元素（简化实现）
+
+## Scope (范围)
+
+### In Scope (包含)
+
+#### 1. 基础交互 (7个工具)
+
+- ✅ **tap**: 点击元素
+- ✅ **longpress**: 长按元素（350ms）
+- ✅ **touchstart**: 触摸开始事件
+- ✅ **touchmove**: 触摸移动事件
+- ✅ **touchend**: 触摸结束事件
+- ✅ **input**: 输入文本
+- ✅ **trigger**: 触发自定义事件
+
+#### 2. 属性读取 (6个工具)
+
+- ✅ **getText**: 获取元素文本内容
+- ✅ **getAttribute**: 获取元素属性（支持 data-* 属性）
+- ✅ **getValue**: 获取表单元素值
+- ✅ **getProperty**: 获取元素属性（JavaScript 属性）
+- ✅ **getStyle**: 获取元素样式
+- ✅ **getComputedStyle**: 获取计算后样式
+
+#### 3. 位置尺寸 (3个工具)
+
+- ✅ **getSize**: 获取元素尺寸（width, height）
+- ✅ **getOffset**: 获取元素偏移（left, top）
+- ✅ **getBoundingClientRect**: 获取完整边界信息
+
+#### 4. 移动滑动 (3个工具)
+
+- ✅ **swipe**: 滑动元素（支持方向和距离）
+- ✅ **moveTo**: 移动到指定位置
+- ✅ **scrollTo**: 滚动到指定位置
+
+#### 5. 专用组件操作 (6类子类工具)
+
+**Input / Textarea**:
+- ✅ input_input: 输入文本
+- ✅ input_clear: 清空内容
+- ✅ input_getValue: 获取值
+- ✅ input_focus: 聚焦
+- ✅ input_blur: 失焦
+
+**Picker**:
+- ✅ picker_select: 选择选项（支持索引/值）
+- ✅ picker_getValue: 获取当前值
+- ✅ picker_getRange: 获取选项列表
+
+**ScrollView**:
+- ✅ scrollview_scrollTo: 滚动到位置
+- ✅ scrollview_scrollIntoView: 滚动到子元素
+- ✅ scrollview_getScrollOffset: 获取滚动偏移
+
+**Swiper**:
+- ✅ swiper_swipeTo: 滑动到指定页
+- ✅ swiper_next: 下一页
+- ✅ swiper_prev: 上一页
+- ✅ swiper_getCurrent: 获取当前页索引
+
+**MovableView**:
+- ✅ movable_moveTo: 移动到位置
+- ✅ movable_getPosition: 获取当前位置
+
+#### 6. ElementRef 集成
+
+- ✅ 所有工具支持 ElementRef 协议
+- ✅ 支持 refId/selector/xpath 三种查询方式
+- ✅ 统一的元素解析逻辑
+
+### Out of Scope (不包含)
+
+- ❌ 元素截图（使用 Page screenshot）
+- ❌ 拖拽到其他元素（使用 touchstart + touchmove + touchend 组合）
+- ❌ 复杂手势识别（缩放、旋转等）
+- ❌ 动画状态检测
+
+## Constraints (约束)
+
+### Technical Constraints (技术约束)
+
+1. **miniprogram-automator 依赖**
+   - 使用 Element 实例的官方 API
+   - 遵循触摸事件坐标系统
+   - 正确处理异步操作
+
+2. **触摸事件坐标**
+   - pageX/pageY: 相对于页面的坐标
+   - clientX/clientY: 相对于视口的坐标
+   - 支持多点触摸（touches 数组）
+
+3. **长按时间**
+   - 默认: 350ms
+   - 符合微信小程序标准
+
+4. **子类组件约束**
+   - Picker: 仅支持 selector/multiSelector/time/date 模式
+   - ScrollView: 支持横向/纵向滚动
+   - Swiper: 支持循环/自动播放配置
+   - MovableView: 支持边界限制
+
+### Business Constraints (业务约束)
+
+1. **交互时间**: 单次操作 <1 秒
+2. **长按时间**: 350ms（固定）
+3. **滑动时间**: 可配置，默认 300ms
+4. **兼容性**: 支持所有微信小程序基础组件
+
+## Success Criteria (成功标准)
+
+### Functional Criteria (功能标准)
+
+**基础交互**:
+- ✅ tap 触发点击事件
+- ✅ longpress 触发长按事件
+- ✅ touchstart/move/end 支持触摸事件序列
+- ✅ input 输入文本到表单元素
+- ✅ trigger 触发自定义事件
+
+**属性读取**:
+- ✅ getText 获取文本内容
+- ✅ getAttribute 获取 HTML 属性
+- ✅ getValue 获取表单值
+- ✅ getProperty 获取 JavaScript 属性
+- ✅ getStyle/getComputedStyle 获取样式
+
+**位置尺寸**:
+- ✅ getSize 返回宽高
+- ✅ getOffset 返回偏移
+- ✅ getBoundingClientRect 返回完整边界
+
+**移动滑动**:
+- ✅ swipe 支持 4 个方向滑动
+- ✅ moveTo 移动到指定坐标
+- ✅ scrollTo 滚动到位置
+
+**子类操作**:
+- ✅ Input/Textarea 输入操作完整
+- ✅ Picker 选择操作完整
+- ✅ ScrollView 滚动操作完整
+- ✅ Swiper 翻页操作完整
+- ✅ MovableView 移动操作完整
+
+### Quality Criteria (质量标准)
+
+- ✅ TypeScript 编译 0 错误
+- ✅ 单元测试覆盖率 >85%
+- ✅ 72 个测试用例全部通过
+- ✅ 无 ESLint 错误
+- ✅ JSDoc 注释完整（956 行代码）
+
+### Documentation Criteria (文档标准)
+
+- ✅ 每个工具有详细 schema 定义
+- ✅ 子类操作分类清晰
+- ✅ 坐标系统文档完整
+- ⏳ charter.C4.align.yaml (本文档)
+- ⏳ tasks.C4.atomize.md (任务卡)
+
+## Definition of Done (完成标准)
+
+**代码**:
+- ✅ `src/tools/element.ts` 实现完成 (956 lines)
+- ✅ TypeScript 编译通过
+- ✅ 23 个核心工具 + 6 类子类操作正确注册
+
+**测试**:
+- ✅ `tests/unit/element.test.ts` (1104 lines)
+- ✅ 72 个测试用例全部通过
+- ✅ 覆盖所有工具和子类操作
+- ✅ Mock Element 实例
+
+**文档**:
+- ⏳ charter.C4.align.yaml (追溯)
+- ⏳ tasks.C4.atomize.md (追溯)
+- ✅ README 工具列表更新
+
+**Git**:
+- ✅ 已提交（Stage C 提交）
+
+## Dependencies (依赖)
+
+**前置任务**:
+- ✅ C3: Page 工具（query 获取元素）
+- ✅ ElementRef 协议实现
+- ✅ B2: SessionStore（管理元素缓存）
+
+**后续任务**:
+- C4 → C5 (工具注册器集成)
+- C4 → D1 (Assert 工具使用 Element 属性)
+
+## Risks (风险)
+
+### Technical Risks (技术风险)
+
+1. **触摸事件复杂性** - 🟡 中风险
+   - 影响：多点触摸和事件序列可能出错
+   - 缓解：完整的单元测试覆盖
+
+2. **子类组件兼容性** - 🟡 中风险
+   - 影响：不同组件可能有特殊行为
+   - 缓解：参考官方文档实现
+
+3. **坐标系统混淆** - 🟢 已缓解
+   - 风险：pageX 和 clientX 混用
+   - 缓解：统一使用 pageX/pageY
+
+### Business Risks (业务风险)
+
+1. **性能问题** - 🟢 已缓解
+   - 影响：大量元素操作可能影响性能
+   - 缓解：使用元素缓存优化
+
+## Open Questions (未决问题)
+
+- ❓ 是否需要支持拖拽到其他元素？（当前使用触摸事件组合）
+- ❓ 是否需要支持复杂手势（缩放、旋转）？（当前不支持）
+- ❓ 是否需要支持动画状态检测？（当前不支持）
+
+## References (参考资料)
+
+- `docs/微信小程序自动化完整操作手册.md` - Element API 文档
+- `docs/完整实现方案.md` - 工具分层设计
+- `miniprogram-automator` 官方文档
+- 微信小程序组件文档
+
+---
+
+**Approval**: ✅ RETROSPECTIVE APPROVED
+**Implementation**: ✅ COMPLETED (23个工具 + 6类子类操作)
+**Documentation**: ⏳ IN PROGRESS