@creatoria/miniapp-mcp 0.1.0

package/docs/charter.B3.align.yaml

@@ -0,0 +1,200 @@
+# Charter: [B3] ElementRef 解析器
+
+task_id: B3
+task_name: ElementRef 统一元素定位协议
+stage: B
+phase: Align (Retrospective)
+created_at: "2025-10-02"
+status: COMPLETED
+estimated_hours: 2
+actual_hours: 2
+
+## Goal (目标)
+
+实现 ElementRef 统一元素定位协议，支持 refId/selector/xpath/index/pagePath 多种定位方式，并提供自动缓存和失效机制。
+
+**核心交付物**:
+- `src/core/element-ref.ts` (~150 lines)
+- resolveElement() 函数
+- resolvePage() 函数
+- generateRefId() 函数
+- 元素缓存管理
+
+## Non-Goals (非目标)
+
+- ❌ 不支持 XPath 定位（miniprogram-automator 不支持）
+- ❌ 不实现元素等待逻辑（属于工具层）
+- ❌ 不实现元素查询优化（直接使用 SDK）
+- ❌ 不实现跨页面元素引用
+
+## Scope (范围)
+
+### In Scope (包含)
+
+1. **ElementRef 接口**
+   - ✅ refId?: string - 缓存句柄引用
+   - ✅ selector?: string - WXML/CSS 选择器
+   - ✅ xpath?: string - XPath 选择器（抛出不支持错误）
+   - ✅ index?: number - 多元素索引
+   - ✅ pagePath?: string - 目标页面路径
+   - ✅ save?: boolean - 是否缓存并返回 refId
+
+2. **resolveElement() 函数**
+   - ✅ 优先从 elementCache 解析 refId
+   - ✅ 若无 refId，使用 selector/xpath 查询
+   - ✅ 支持 index 索引多元素
+   - ✅ 支持 save 参数缓存元素
+   - ✅ 返回 Element 对象和新 refId（如果 save=true）
+
+3. **resolvePage() 函数**
+   - ✅ 若提供 pagePath，切换到指定页面
+   - ✅ 若无 pagePath，返回当前页面
+   - ✅ 支持 pagePath 格式验证
+   - ✅ 返回 Page 对象
+
+4. **generateRefId() 函数**
+   - ✅ 生成唯一元素引用 ID
+   - ✅ 格式：`elem-{timestamp}-{random}`
+   - ✅ 保证全局唯一性
+
+5. **缓存管理**
+   - ✅ 使用 session.elementCache 存储
+   - ✅ 自动失效机制（页面切换时清空）
+   - ✅ 手动清理接口
+
+### Out of Scope (不包含)
+
+- ❌ XPath 查询实现
+- ❌ 元素等待和重试
+- ❌ 元素查询性能优化
+- ❌ 跨会话元素共享
+
+## Constraints (约束)
+
+### Technical Constraints (技术约束)
+
+1. **miniprogram-automator 限制**
+   - 仅支持 CSS 选择器和组件选择器
+   - 不支持 XPath
+   - 元素句柄无法跨页面使用
+
+2. **缓存失效规则**
+   - 页面切换时自动清空缓存
+   - 元素销毁时句柄失效
+   - 必须处理失效场景
+
+3. **TypeScript 规范**
+   - 完整类型定义
+   - 严格模式
+   - 导入使用 .js 后缀
+
+4. **错误处理**
+   - 明确的错误消息
+   - 区分不同失败原因
+   - 提供调试信息
+
+### Business Constraints (业务约束)
+
+1. **性能要求**: 元素解析 <50ms
+2. **缓存容量**: 单会话最多 1000 个元素
+3. **兼容性**: 支持所有 WXML 组件
+
+## Success Criteria (成功标准)
+
+### Functional Criteria (功能标准)
+
+- ✅ resolveElement 正确解析 refId
+- ✅ resolveElement 正确解析 selector
+- ✅ resolveElement 支持 index 索引
+- ✅ resolveElement 支持 save 缓存
+- ✅ resolvePage 正确切换页面
+- ✅ resolvePage 返回当前页面
+- ✅ generateRefId 生成唯一 ID
+- ✅ XPath 抛出明确错误
+
+### Quality Criteria (质量标准)
+
+- ✅ TypeScript 编译 0 错误
+- ✅ 代码行数 ~150 行
+- ✅ 无 ESLint 错误
+- ✅ JSDoc 注释完整
+- ✅ 单元测试覆盖（随工具测试）
+
+### Documentation Criteria (文档标准)
+
+- ✅ ElementRef 接口文档
+- ✅ resolveElement/resolvePage 函数文档
+- ✅ 缓存机制说明
+- ⏳ charter.B3.align.yaml (本文档)
+- ⏳ tasks.B3.atomize.md (任务卡)
+
+## Definition of Done (完成标准)
+
+**代码**:
+- ✅ `src/core/element-ref.ts` 实现完成 (~150 lines)
+- ✅ TypeScript 编译通过
+- ✅ 所有函数实现
+
+**测试**:
+- ✅ 单元测试随工具测试验证
+- ✅ 集成测试覆盖各种定位方式
+- ✅ 测试缓存和失效机制
+
+**文档**:
+- ⏳ charter.B3.align.yaml (追溯)
+- ⏳ tasks.B3.atomize.md (追溯)
+- ⏳ session_log (追溯)
+
+**Git**:
+- ✅ 已提交（随 C4 Element 工具提交）
+
+## Dependencies (依赖)
+
+**前置任务**:
+- ✅ A3: 仓库结构初始化
+- ✅ B2: SessionStore（使用 elementCache）
+- ✅ miniprogram-automator SDK 了解
+
+**后续任务**:
+- B3 → C4 (Element 工具使用解析器)
+- B3 → 所有元素操作工具
+
+## Risks (风险)
+
+### Technical Risks (技术风险)
+
+1. **XPath 不支持** - 🟢 已缓解
+   - 影响：用户期望使用 XPath
+   - 缓解：明确错误消息，引导使用 selector
+
+2. **缓存失效** - 🟢 已缓解
+   - 影响：页面切换后元素句柄失效
+   - 缓解：自动清空缓存，清晰错误提示
+
+3. **选择器冲突** - 🟡 中风险
+   - 影响：selector 匹配多个元素
+   - 缓解：支持 index 参数精确定位
+
+### Business Risks (业务风险)
+
+1. **用户体验** - 🟢 低风险
+   - 影响：缓存失效导致操作失败
+   - 缓解：清晰错误消息，引导重新查询
+
+## Open Questions (未决问题)
+
+- ✅ 是否支持 XPath？（否，SDK 不支持）
+- ✅ 缓存容量限制？（1000 个元素/会话）
+- ❓ 是否需要支持跨页面元素引用？（当前不支持）
+
+## References (参考资料)
+
+- `docs/微信小程序自动化完整操作手册.md` - 元素查询 API
+- `docs/完整实现方案.md` - ElementRef 协议设计
+- miniprogram-automator 选择器文档
+
+---
+
+**Approval**: ✅ RETROSPECTIVE APPROVED
+**Implementation**: ✅ COMPLETED
+**Documentation**: ⏳ IN PROGRESS

package/docs/charter.B4.align.yaml

@@ -0,0 +1,188 @@
+# Charter: [B4] Logger 和 OutputManager
+
+task_id: B4
+task_name: Logger 和 OutputManager 实现
+stage: B
+phase: Align (Retrospective)
+created_at: "2025-10-02"
+status: COMPLETED
+estimated_hours: 1-2
+actual_hours: 1.5
+
+## Goal (目标)
+
+实现结构化日志系统（Logger）和产物管理器（OutputManager），为 MCP Server 提供统一的日志输出和文件管理能力。
+
+**核心交付物**:
+- `src/core/logger.ts` (~50 lines)
+- `src/core/output.ts` (~60 lines)
+- Logger: info/warn/error 方法
+- OutputManager: resolveOutputPath/writeFile 方法
+
+## Non-Goals (非目标)
+
+- ❌ 不实现日志持久化（仅 console 输出）
+- ❌ 不实现日志级别过滤
+- ❌ 不实现日志轮转
+- ❌ 不实现远程日志上传
+
+## Scope (范围)
+
+### In Scope (包含)
+
+1. **Logger 类**
+   - ✅ info(message: string, meta?: object): void
+   - ✅ warn(message: string, meta?: object): void
+   - ✅ error(message: string, meta?: object): void
+   - ✅ 所有日志输出到 console.error（避免干扰 stdio）
+   - ✅ 结构化日志格式：[level] message {meta}
+
+2. **OutputManager 类**
+   - ✅ constructor(sessionId: string, baseDir: string)
+   - ✅ resolveOutputPath(type: string, filename: string): string
+   - ✅ writeFile(type: string, filename: string, content: string|Buffer): Promise<string>
+   - ✅ 目录结构：{baseDir}/{sessionId}/{type}/
+
+3. **目录管理**
+   - ✅ 自动创建目录
+   - ✅ 支持多种产物类型（screenshot/snapshot/log/trace）
+   - ✅ 返回绝对路径
+
+4. **文件操作**
+   - ✅ 写入文本文件
+   - ✅ 写入二进制文件（Buffer）
+   - ✅ 错误处理和重试
+
+### Out of Scope (不包含)
+
+- ❌ 日志持久化到文件
+- ❌ 日志级别配置
+- ❌ 日志格式化选项
+- ❌ 文件压缩和清理
+
+## Constraints (约束)
+
+### Technical Constraints (技术约束)
+
+1. **stdio 避让**
+   - 所有日志必须输出到 console.error
+   - 不能使用 console.log（stdout 被 MCP 占用）
+
+2. **文件系统**
+   - 使用 Node.js fs/promises API
+   - 支持相对路径和绝对路径
+   - 自动创建目录（recursive）
+
+3. **TypeScript 规范**
+   - 完整类型定义
+   - 严格模式
+   - 导入使用 .js 后缀
+
+4. **错误处理**
+   - 捕获文件 I/O 错误
+   - 记录错误日志
+   - 抛出明确异常
+
+### Business Constraints (业务约束)
+
+1. **日志性能**: 日志输出不阻塞主流程
+2. **文件性能**: 文件写入 <100ms
+3. **存储限制**: 单会话产物 <100MB
+
+## Success Criteria (成功标准)
+
+### Functional Criteria (功能标准)
+
+- ✅ Logger.info/warn/error 正确输出
+- ✅ 日志格式清晰可读
+- ✅ OutputManager 正确创建目录
+- ✅ OutputManager 正确写入文件
+- ✅ resolveOutputPath 返回正确路径
+- ✅ 支持文本和二进制内容
+
+### Quality Criteria (质量标准)
+
+- ✅ TypeScript 编译 0 错误
+- ✅ logger.ts ~50 行
+- ✅ output.ts ~60 行
+- ✅ 无 ESLint 错误
+- ✅ JSDoc 注释完整
+
+### Documentation Criteria (文档标准)
+
+- ✅ Logger API 文档
+- ✅ OutputManager API 文档
+- ✅ 目录结构说明
+- ⏳ charter.B4.align.yaml (本文档)
+- ⏳ tasks.B4.atomize.md (任务卡)
+
+## Definition of Done (完成标准)
+
+**代码**:
+- ✅ `src/core/logger.ts` 实现完成 (~50 lines)
+- ✅ `src/core/output.ts` 实现完成 (~60 lines)
+- ✅ TypeScript 编译通过
+- ✅ 所有方法实现
+
+**测试**:
+- ✅ 单元测试随工具测试验证
+- ✅ 手动测试日志输出
+- ✅ 集成测试文件写入
+
+**文档**:
+- ⏳ charter.B4.align.yaml (追溯)
+- ⏳ tasks.B4.atomize.md (追溯)
+- ⏳ session_log (追溯)
+
+**Git**:
+- ✅ 已提交（随 D2 Snapshot 工具提交）
+
+## Dependencies (依赖)
+
+**前置任务**:
+- ✅ A3: 仓库结构初始化
+- ✅ Node.js fs/promises API 了解
+
+**后续任务**:
+- B4 → D2 (Snapshot 工具使用 OutputManager)
+- B4 → 所有需要输出文件的工具
+
+## Risks (风险)
+
+### Technical Risks (技术风险)
+
+1. **stdio 干扰** - 🟢 已缓解
+   - 影响：console.log 干扰 MCP 协议
+   - 缓解：强制使用 console.error
+
+2. **文件权限** - 🟡 中风险
+   - 影响：无法创建目录/写入文件
+   - 缓解：错误处理 + 清晰错误消息
+
+3. **路径安全** - 🟡 中风险
+   - 影响：路径遍历攻击
+   - 缓解：路径验证和规范化
+
+### Business Risks (业务风险)
+
+1. **存储占用** - 🟢 低风险
+   - 影响：产物文件占用磁盘空间
+   - 缓解：会话清理机制 + 用户管理
+
+## Open Questions (未决问题)
+
+- ✅ 日志是否需要持久化？（否，仅 console 输出）
+- ✅ 是否需要日志级别过滤？（否，后续扩展）
+- ❓ 是否需要产物文件清理策略？（当前手动清理）
+
+## References (参考资料)
+
+- `docs/完整实现方案.md` - 日志和产物管理设计
+- Node.js fs/promises API 文档
+- Node.js path API 文档
+
+---
+
+**Approval**: ✅ RETROSPECTIVE APPROVED
+**Implementation**: ✅ COMPLETED
+**Documentation**: ⏳ IN PROGRESS

package/docs/charter.C1.align.yaml

@@ -0,0 +1,190 @@
+# Charter: [C1] Automator 工具
+
+task_id: C1
+task_name: Automator 工具实现
+stage: C
+phase: Align (Retrospective)
+created_at: "2025-10-02"
+status: COMPLETED
+estimated_hours: 2-3
+actual_hours: 3
+
+## Goal (目标)
+
+实现 Automator 级别的 4 个 MCP 工具，封装微信开发者工具的启动、连接、断开和关闭功能。
+
+**核心交付物**:
+- `src/tools/automator.ts` - 4 个工具实现 (252 lines)
+- `tests/unit/automator.test.ts` - 单元测试 (364 lines, 20 tests)
+- 工具: launch, connect, disconnect, close
+
+## Non-Goals (非目标)
+
+- ❌ 不实现 MiniProgram 级别工具（留给 C2）
+- ❌ 不实现配置文件管理（使用默认配置）
+- ❌ 不实现自动重连机制（简单失败返回）
+- ❌ 不实现端口冲突检测（用户自行处理）
+
+## Scope (范围)
+
+### In Scope (包含)
+
+1. **launch 工具**
+   - ✅ 启动微信开发者工具
+   - ✅ 支持自定义项目路径
+   - ✅ 支持自定义端口（默认 9420）
+   - ✅ 支持自定义 CLI 路径（默认 macOS 路径）
+   - ✅ 返回会话 ID 和启动状态
+
+2. **connect 工具**
+   - ✅ 连接到已启动的开发者工具
+   - ✅ 支持自定义端口
+   - ✅ 获取 MiniProgram 实例
+   - ✅ 返回连接成功状态
+
+3. **disconnect 工具**
+   - ✅ 断开当前连接
+   - ✅ 清理 MiniProgram 实例
+   - ✅ 保留 IDE 进程（不关闭）
+
+4. **close 工具**
+   - ✅ 关闭微信开发者工具
+   - ✅ 终止 IDE 进程
+   - ✅ 清理会话资源
+
+### Out of Scope (不包含)
+
+- ❌ 多实例管理（一次仅支持一个会话）
+- ❌ 自动重连机制
+- ❌ 端口冲突解决
+- ❌ Windows/Linux CLI 路径支持
+
+## Constraints (约束)
+
+### Technical Constraints (技术约束)
+
+1. **miniprogram-automator 依赖**
+   - 必须使用官方 `miniprogram-automator` SDK
+   - 遵循其 launch/connect API 规范
+   - 正确处理异步操作和错误
+
+2. **Session 隔离**
+   - 每个会话独立的 automator 实例
+   - 会话 ID 自动生成（UUID）
+   - 通过 SessionStore 管理生命周期
+
+3. **默认配置**
+   - CLI 路径: `/Applications/wechatwebdevtools.app/Contents/MacOS/cli`
+   - 端口: 9420
+   - 超时: 30 秒
+
+4. **错误处理**
+   - 明确区分启动失败 vs 连接失败
+   - 返回清晰的错误消息
+   - 记录详细错误日志
+
+### Business Constraints (业务约束)
+
+1. **启动时间**: <10 秒
+2. **连接时间**: <3 秒
+3. **关闭时间**: <2 秒
+4. **兼容性**: macOS 优先，微信开发者工具 1.06+
+
+## Success Criteria (成功标准)
+
+### Functional Criteria (功能标准)
+
+- ✅ launch 成功启动开发者工具
+- ✅ connect 成功连接并获取 MiniProgram 实例
+- ✅ disconnect 断开连接但保留 IDE
+- ✅ close 完全关闭 IDE 和会话
+- ✅ 错误场景正确处理（端口占用、CLI 不存在等）
+
+### Quality Criteria (质量标准)
+
+- ✅ TypeScript 编译 0 错误
+- ✅ 单元测试覆盖率 >80%
+- ✅ 20 个测试用例全部通过
+- ✅ 无 ESLint 错误
+- ✅ JSDoc 注释完整
+
+### Documentation Criteria (文档标准)
+
+- ✅ 每个工具有 zod schema 定义
+- ✅ 工具描述清晰（inputSchema.description）
+- ✅ 函数签名有 JSDoc
+- ⏳ charter.C1.align.yaml (本文档)
+- ⏳ tasks.C1.atomize.md (任务卡)
+
+## Definition of Done (完成标准)
+
+**代码**:
+- ✅ `src/tools/automator.ts` 实现完成 (252 lines)
+- ✅ TypeScript 编译通过
+- ✅ 4 个工具正确注册
+
+**测试**:
+- ✅ `tests/unit/automator.test.ts` (364 lines)
+- ✅ 20 个测试用例全部通过
+- ✅ 覆盖成功/失败场景
+- ✅ Mock miniprogram-automator 依赖
+
+**文档**:
+- ⏳ charter.C1.align.yaml (追溯)
+- ⏳ tasks.C1.atomize.md (追溯)
+- ✅ README 工具列表更新
+
+**Git**:
+- ✅ 已提交（Stage C 提交）
+
+## Dependencies (依赖)
+
+**前置任务**:
+- ✅ B1: MCP Server 骨架
+- ✅ B2: SessionStore 实现
+- ✅ `miniprogram-automator` 已安装
+
+**后续任务**:
+- C1 → C2 (需要 MiniProgram 实例)
+- C1 → C5 (工具注册器集成)
+
+## Risks (风险)
+
+### Technical Risks (技术风险)
+
+1. **CLI 路径变化** - 🟡 中风险
+   - 影响：微信开发者工具更新可能改变 CLI 路径
+   - 缓解：允许用户自定义 CLI 路径
+
+2. **端口冲突** - 🟡 中风险
+   - 影响：端口被占用导致启动失败
+   - 缓解：明确错误提示，建议更换端口
+
+3. **进程泄漏** - 🟢 已缓解
+   - 风险：异常退出导致 IDE 进程残留
+   - 缓解：优雅关闭机制，SessionStore.dispose() 清理
+
+### Business Risks (业务风险)
+
+1. **跨平台兼容** - 🟡 中风险
+   - 影响：当前仅支持 macOS
+   - 缓解：文档明确说明，未来扩展 Windows/Linux
+
+## Open Questions (未决问题)
+
+- ❓ 是否需要支持多个小程序同时运行？（当前单实例）
+- ❓ 是否需要自动重连机制？（当前无）
+- ❓ 是否需要端口自动探测？（当前手动指定）
+
+## References (参考资料)
+
+- `docs/微信小程序自动化完整操作手册.md` - Automator API 文档
+- `docs/完整实现方案.md` - 工具分层设计
+- `miniprogram-automator` 官方文档
+- `src/core/session.ts` - Session 管理
+
+---
+
+**Approval**: ✅ RETROSPECTIVE APPROVED
+**Implementation**: ✅ COMPLETED
+**Documentation**: ⏳ IN PROGRESS