@creatoria/miniapp-mcp 0.1.3 → 0.2.0

package/docs/charter.B3.align.yaml

@@ -1,200 +0,0 @@
-# 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

@@ -1,188 +0,0 @@
-# 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

@@ -1,190 +0,0 @@
-# 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