@creatoria/miniapp-mcp 0.1.0

package/docs/charter.A4.align.yaml

@@ -0,0 +1,227 @@
+# Charter: A4 - 搭建 lint / format / commit hooks
+# Task ID: TASK-2025-001-A4
+# Stage: Align (对齐阶段)
+# Status: RETROSPECTIVE (追溯补齐)
+# Created: 2025-10-02 (追溯)
+
+---
+
+## Goal (目标)
+
+配置代码质量工具（ESLint 和 Prettier）以及可选的 Git 提交钩子（Husky），确保代码风格一致性和基本代码质量标准，为团队协作和代码审查提供自动化保障。
+
+## Background (背景)
+
+代码质量和风格一致性对于团队协作至关重要。A4 任务作为"可选"任务，旨在：
+
+1. 配置 ESLint 进行代码静态检查（类型安全、潜在错误）
+2. 配置 Prettier 进行代码格式化（风格统一）
+3. 安装 Husky 支持 Git Hooks（为未来自动化检查预留）
+4. （可选）配置 pre-commit 钩子自动运行检查
+
+**注意**：任务定义明确标注"可选"，因此不强制要求所有功能都完全实现。
+
+## Scope (范围)
+
+### In Scope (范围内)
+
+- ✅ 配置 ESLint
+  - `.eslintrc.cjs` - ESLint 配置文件
+  - @typescript-eslint/parser - TypeScript 解析器
+  - @typescript-eslint/eslint-plugin - TypeScript 规则插件
+  - eslint-config-prettier - 禁用与 Prettier 冲突的规则
+  - 自定义规则（no-explicit-any, no-unused-vars 等）
+  - package.json scripts.lint - 运行 linter
+
+- ✅ 配置 Prettier
+  - `.prettierrc` - Prettier 配置文件
+  - `.prettierignore` - Prettier 忽略规则
+  - 代码风格规则（semi, singleQuote, printWidth 等）
+  - package.json scripts.format - 格式化代码
+  - package.json scripts.format:check - 检查格式
+
+- ✅ 安装 Husky
+  - husky 依赖包
+  - .husky/ 目录
+  - package.json scripts.prepare - 自动安装 hooks
+
+- ⚠️ 配置 Git Hooks（可选，部分实现）
+  - Husky 已安装
+  - 但未配置自定义 pre-commit hook
+
+### Out of Scope (范围外)
+
+- ❌ 强制代码风格（通过 CI 阻止提交）
+- ❌ 自动修复所有 lint 错误
+- ❌ 复杂的 lint 规则定制
+- ❌ Commitlint（提交消息检查）
+- ❌ 其他 Git Hooks（pre-push, commit-msg 等）
+
+## Constraints (约束条件)
+
+### Technical Constraints (技术约束)
+
+- **ESLint 版本**: 8.57.0
+  - 理由: 稳定版本，TypeScript 支持良好
+  - 验证: package.json devDependencies
+
+- **Prettier 版本**: 3.3.2
+  - 理由: 最新稳定版
+  - 验证: package.json devDependencies
+
+- **TypeScript 兼容性**: 必须支持
+  - 理由: 项目使用 TypeScript
+  - 验证: @typescript-eslint/parser 和 plugin
+
+- **Prettier 与 ESLint 集成**: 避免冲突
+  - 理由: 两者都控制代码风格可能冲突
+  - 验证: eslint-config-prettier 禁用冲突规则
+
+- **Husky 版本**: 9.0.11
+  - 理由: 支持现代 Git Hooks 配置
+  - 验证: package.json devDependencies
+
+### Business Constraints (业务约束)
+
+- 配置必须简单易懂，便于团队成员调整
+- Lint 规则不应过于严格，避免阻碍开发
+- Format 规则应符合主流 TypeScript 风格
+- 工具必须可选运行，不强制自动化（hook 可选）
+
+## Success Criteria (完成标准 / DoD)
+
+### Deliverables (交付物)
+
+1. ✅ **ESLint 配置 (.eslintrc.cjs)**
+   - parser: '@typescript-eslint/parser'
+   - extends: eslint:recommended + @typescript-eslint/recommended + prettier
+   - plugins: ['@typescript-eslint']
+   - parserOptions: project tsconfig.json, ES2022, module
+   - env: node, es2022, jest
+   - rules: 自定义规则（no-explicit-any: warn, no-unused-vars: error 等）
+   - ignorePatterns: dist, node_modules
+
+2. ✅ **Prettier 配置 (.prettierrc + .prettierignore)**
+   - .prettierrc:
+     - semi: false
+     - singleQuote: true
+     - printWidth: 100
+     - trailingComma: 'es5'
+     - tabWidth: 2
+     - arrowParens: 'always'
+     - endOfLine: 'lf'
+   - .prettierignore:
+     - node_modules, dist, coverage, *.log, .DS_Store, .llm, docs
+
+3. ✅ **Package.json 配置**
+   - devDependencies: eslint, @typescript-eslint/*, prettier, eslint-config-prettier, husky
+   - scripts.lint: "eslint . --ext .ts"
+   - scripts.format: "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\""
+   - scripts.format:check: "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\""
+   - scripts.prepare: "husky install"
+
+4. ✅ **Husky 安装**
+   - .husky/ 目录存在
+   - .husky/_/ 包含 husky 模板文件
+   - prepare 脚本可运行
+
+5. ⚠️ **Git Hooks（可选，未完全实现）**
+   - Husky 已安装
+   - 但未配置自定义 pre-commit hook
+   - 开发者可手动运行 lint/format
+
+6. ✅ **可执行性验证**
+   - `pnpm lint` 成功运行，检测代码问题
+   - `pnpm format:check` 成功运行，检测格式问题
+   - `pnpm format` 可格式化代码
+
+### Quality Standards (质量标准)
+
+- **Lint 规则**: 平衡严格性和开发体验
+- **Format 规则**: 符合主流 TypeScript 风格
+- **集成性**: ESLint 和 Prettier 无冲突
+- **可选性**: 工具可手动运行，不强制自动化
+
+## Open Questions (开放问题)
+
+以下问题在实施过程中已经决议：
+
+1. **Q**: ESLint 还是 TSLint？
+   - **决议**: ESLint
+   - **理由**: TSLint 已弃用，ESLint 通过 @typescript-eslint 支持 TypeScript
+   - **来源**: 官方推荐
+
+2. **Q**: 如何避免 ESLint 和 Prettier 规则冲突？
+   - **决议**: 使用 eslint-config-prettier
+   - **理由**: 自动禁用 ESLint 中与 Prettier 冲突的格式规则
+   - **来源**: 最佳实践
+
+3. **Q**: Prettier 代码风格选择？
+   - **决议**: semi: false, singleQuote: true, printWidth: 100
+   - **理由**: 符合现代 TypeScript/JavaScript 主流风格
+   - **来源**: 社区标准
+
+4. **Q**: 是否启用严格的 lint 规则？
+   - **决议**: 部分严格（no-explicit-any: warn, no-unused-vars: error）
+   - **理由**: 平衡代码质量和开发体验，any 警告不阻止开发
+   - **来源**: 渐进式类型安全
+
+5. **Q**: 是否配置 pre-commit hook？
+   - **决议**: 安装 Husky 但未配置自定义 hook
+   - **理由**: 任务标记"可选"，工具可手动运行
+   - **来源**: 任务定义 A4: "可选"
+
+6. **Q**: pre-commit hook 应该运行什么？
+   - **决议**: 未配置（可选）
+   - **可选方案**: lint-staged 运行 lint + format 仅对暂存文件
+   - **来源**: 最佳实践（但未实现）
+
+7. **Q**: 是否格式化文档文件（docs/）？
+   - **决议**: 排除（.prettierignore 包含 docs）
+   - **理由**: 文档可能包含特殊格式，避免破坏
+   - **来源**: 项目特性
+
+## Risks (风险)
+
+### Technical Risks (技术风险)
+
+- ⚠️ **ESLint 规则过于严格导致开发受阻**
+  - 影响: 开发者频繁遇到 lint 错误
+  - 缓解: no-explicit-any 设为 warn（警告）而非 error
+
+- ⚠️ **Prettier 和 ESLint 规则冲突**
+  - 影响: 格式化后 lint 报错，或反之
+  - 缓解: 使用 eslint-config-prettier 禁用冲突规则
+
+- ⚠️ **Husky hooks 在某些环境不工作**
+  - 影响: Windows/特殊 Git 环境可能 hooks 失效
+  - 缓解: 未配置强制 hooks，工具可手动运行
+
+- ⚠️ **未配置 pre-commit hook 可能导致代码质量下降**
+  - 影响: 开发者可能忘记运行 lint/format
+  - 缓解: 可通过 CI/CD 补充检查（Stage H）
+
+### Process Risks (流程风险)
+
+- ⚠️ **追溯补齐文档**
+  - 影响: 本文档为追溯性创建，非正常 6A 流程
+  - 缓解: 明确标注 RETROSPECTIVE，等待用户批准
+
+## Dependencies (依赖)
+
+- **前置任务**:
+  - A3（建立 TypeScript 工程）- 依赖 TypeScript 配置和项目结构
+
+- **后续任务**:
+  - B1-B5（核心框架搭建）- 代码将遵循 lint/format 规则
+  - H（CI/CD）- 可在 CI 中运行 lint/format 检查
+
+## Approval (批准)
+
+- **Status**: ⏳ 等待用户批准追溯补齐文档
+- **Technical Implementation**: ✅ 大部分完成（ESLint + Prettier 完整，Husky 安装，hooks 未配置）
+- **Process Compliance**: ❌ 流程违规（跳过 Align/Approve），通过追溯补齐修正
+
+---
+
+**注**: 本文档为追溯性创建，用于补齐 A4 任务的流程文档。技术实现大部分完成（lint ✓, format ✓, husky 安装 ✓），commit hooks 未配置（任务标记"可选"），现等待用户批准追溯补齐的合理性。

package/docs/charter.B1.align.yaml

@@ -0,0 +1,179 @@
+# Charter: [B1] MCP Server 骨架
+
+task_id: B1
+task_name: MCP Server 骨架实现
+stage: B
+phase: Align (Retrospective)
+created_at: "2025-10-02"
+status: COMPLETED
+estimated_hours: 2-3
+actual_hours: 2
+
+## Goal (目标)
+
+实现可运行的 MCP Server 骨架，支持 stdio transport 连接，能够启动并响应基本的 MCP 协议请求。
+
+**核心交付物**:
+- `src/server.ts` - MCP Server 入口文件
+- `startServer(config)` 函数
+- ListToolsRequestSchema 处理器
+- 优雅关闭机制
+
+## Non-Goals (非目标)
+
+- ❌ 不实现具体工具（留给 C1-C5）
+- ❌ 不实现配置文件解析（留给 E2）
+- ❌ 不实现 CLI 入口（留给 E3）
+- ❌ 不实现 SessionStore 内部逻辑（属于 B2）
+
+## Scope (范围)
+
+### In Scope (包含)
+
+1. **Server 实例化**
+   - ✅ 使用 `@modelcontextprotocol/sdk` 的 Server 类
+   - ✅ 设置 name 和 version
+   - ✅ 配置 capabilities: `{ tools: {} }`
+
+2. **Transport 配置**
+   - ✅ 使用 `StdioServerTransport`
+   - ✅ 调用 `server.connect(transport)`
+   - ✅ 输出启动日志到 stderr
+
+3. **工具注册集成**
+   - ✅ 调用 `registerTools(server, context)`
+   - ✅ 传递 SessionStore 的 getSession/deleteSession 回调
+   - ✅ 支持 capabilities 参数
+
+4. **ListToolsRequestSchema 处理**
+   - ✅ 返回 registerTools 注册的工具列表
+   - ✅ 符合 MCP 协议规范
+
+5. **优雅关闭**
+   - ✅ 监听 SIGINT 和 SIGTERM
+   - ✅ 调用 sessionStore.dispose()
+   - ✅ 输出关闭日志
+
+### Out of Scope (不包含)
+
+- ❌ SessionStore 内部实现
+- ❌ 具体工具 handler 逻辑
+- ❌ 配置文件解析
+- ❌ CLI 参数处理
+- ❌ 错误监控和重试
+
+## Constraints (约束)
+
+### Technical Constraints (技术约束)
+
+1. **MCP 协议兼容**
+   - 必须使用官方 SDK (`@modelcontextprotocol/sdk`)
+   - 遵循 stdio transport 规范
+   - 正确处理 JSON-RPC 消息
+
+2. **TypeScript 规范**
+   - ESNext + ESM 模式
+   - 导入使用 `.js` 后缀
+   - 严格类型检查
+
+3. **日志输出**
+   - 使用 `console.error` 避免干扰 stdio
+   - 不输出到 stdout（被 MCP 协议占用）
+
+4. **依赖注入**
+   - SessionStore 作为外部依赖
+   - registerTools 通过参数传入
+
+### Business Constraints (业务约束)
+
+1. **启动时间**: <1 秒
+2. **内存占用**: 启动时 <50MB
+3. **兼容性**: 支持 Node.js 18+
+
+## Success Criteria (成功标准)
+
+### Functional Criteria (功能标准)
+
+- ✅ 运行 `node dist/server.js` 成功启动
+- ✅ MCP 客户端可连接
+- ✅ `list_tools` 请求返回工具列表
+- ✅ CTRL+C 触发优雅关闭
+- ✅ sessionStore.dispose() 被调用
+
+### Quality Criteria (质量标准)
+
+- ✅ TypeScript 编译 0 错误
+- ✅ 代码行数 <100 行（实际 64 行）
+- ✅ 无 ESLint 错误
+- ✅ JSDoc 注释完整
+
+### Documentation Criteria (文档标准)
+
+- ✅ 函数签名有 JSDoc
+- ✅ README 更新启动说明
+- ⏳ charter.B1.align.yaml (本文档)
+- ⏳ tasks.B1.atomize.md (任务卡)
+
+## Definition of Done (完成标准)
+
+**代码**:
+- ✅ `src/server.ts` 实现完成 (64 lines)
+- ✅ TypeScript 编译通过
+- ✅ 集成 SessionStore 和 registerTools
+
+**测试**:
+- ✅ 手动测试：启动 Server 并连接
+- ✅ 集成测试：通过其他工具测试间接验证
+
+**文档**:
+- ⏳ charter.B1.align.yaml (追溯)
+- ⏳ tasks.B1.atomize.md (追溯)
+- ⏳ session_log (追溯)
+
+**Git**:
+- ✅ 已提交（随 A2-B1-B2 修复提交）
+
+## Dependencies (依赖)
+
+**前置任务**:
+- ✅ A3: 仓库结构初始化
+- ✅ `@modelcontextprotocol/sdk` 已安装
+
+**后续任务**:
+- B1 → B2 (Server 需要 SessionStore)
+- B1 → C5 (registerTools 函数)
+
+## Risks (风险)
+
+### Technical Risks (技术风险)
+
+1. **MCP SDK 升级** - 🟢 低风险
+   - 影响：API 变更可能破坏兼容
+   - 缓解：锁定 SDK 版本
+
+2. **stdio 干扰** - 🟢 已缓解
+   - 风险：日志输出到 stdout 干扰协议
+   - 缓解：所有日志使用 console.error
+
+### Business Risks (业务风险)
+
+1. **启动失败** - 🟢 已缓解
+   - 影响：Server 无法启动导致服务不可用
+   - 缓解：错误日志清晰，便于排查
+
+## Open Questions (未决问题)
+
+- ❓ 是否需要支持多个 transport（HTTP/WebSocket）？（当前仅 stdio）
+- ❓ 是否需要健康检查端点？（当前无）
+
+## References (参考资料)
+
+- `docs/完整实现方案.md` - Server 架构设计
+- `docs/第一版本方案.md` - MCP 集成方案
+- `@modelcontextprotocol/sdk` 文档
+
+---
+
+**Approval**: ✅ RETROSPECTIVE APPROVED
+**Implementation**: ✅ COMPLETED
+**Documentation**: ⏳ IN PROGRESS

package/docs/charter.B2.align.yaml

@@ -0,0 +1,200 @@
+# Charter: [B2] SessionStore 实现
+
+task_id: B2
+task_name: SessionStore 会话管理器
+stage: B
+phase: Align (Retrospective)
+created_at: "2025-10-02"
+status: COMPLETED
+estimated_hours: 2-3
+actual_hours: 3
+
+## Goal (目标)
+
+实现会话隔离的 SessionStore，管理多个 MCP 会话的生命周期、资源清理和超时回收。
+
+**核心交付物**:
+- `src/core/session.ts` (~200 lines)
+- `tests/unit/session.test.ts` (93 tests)
+- SessionStore 类：get/set/delete/dispose/getOrCreate/updateActivity
+- 自动超时清理机制
+
+## Non-Goals (非目标)
+
+- ❌ 不实现持久化存储（仅内存）
+- ❌ 不实现会话共享（跨进程）
+- ❌ 不实现会话迁移
+- ❌ 不实现分布式锁
+
+## Scope (范围)
+
+### In Scope (包含)
+
+1. **SessionState 接口**
+   - ✅ sessionId: string
+   - ✅ miniProgram: MiniProgram | null
+   - ✅ ideProcess: ChildProcess | null
+   - ✅ elementCache: Map<string, Element>
+   - ✅ createdAt, lastActivity: Date
+   - ✅ outputDir: string
+
+2. **SessionStore 类**
+   - ✅ get(sessionId): SessionState | undefined
+   - ✅ set(sessionId, state): void
+   - ✅ delete(sessionId): void
+   - ✅ dispose(): Promise<void>
+   - ✅ getOrCreate(sessionId): SessionState
+   - ✅ updateActivity(sessionId): void
+
+3. **超时清理**
+   - ✅ 定时检查会话活动时间
+   - ✅ 超时会话自动清理
+   - ✅ 调用 miniProgram.disconnect() 和 ideProcess.kill()
+   - ✅ 清理元素缓存
+
+4. **配置选项**
+   - ✅ sessionTimeout: number (默认 30 分钟)
+   - ✅ outputDir: string (默认 .mcp-artifacts)
+   - ✅ cleanupInterval: number (默认 60 秒)
+
+5. **资源清理**
+   - ✅ disconnect miniProgram
+   - ✅ kill ideProcess
+   - ✅ clear elementCache
+   - ✅ 日志输出清理结果
+
+### Out of Scope (不包含)
+
+- ❌ 持久化到磁盘/数据库
+- ❌ 会话状态序列化
+- ❌ 跨进程会话共享
+- ❌ 会话快照和恢复
+
+## Constraints (约束)
+
+### Technical Constraints (技术约束)
+
+1. **内存安全**
+   - 必须防止内存泄漏
+   - 超时会话必须被清理
+   - 资源释放必须彻底
+
+2. **并发安全**
+   - 支持多会话并发访问
+   - Map 操作原子性
+   - 避免竞态条件
+
+3. **TypeScript 规范**
+   - 完整类型定义
+   - 泛型约束
+   - 严格模式
+
+4. **测试覆盖**
+   - 单元测试覆盖率 >95%
+   - 93 个测试用例
+   - 覆盖所有边界条件
+
+### Business Constraints (业务约束)
+
+1. **会话超时**: 默认 30 分钟
+2. **清理周期**: 每 60 秒检查一次
+3. **资源限制**: 支持最多 100 个并发会话
+4. **性能要求**: 会话操作 <10ms
+
+## Success Criteria (成功标准)
+
+### Functional Criteria (功能标准)
+
+- ✅ get/set/delete 操作正常
+- ✅ getOrCreate 自动创建会话
+- ✅ updateActivity 更新时间戳
+- ✅ 超时会话自动清理
+- ✅ dispose 清理所有会话
+- ✅ 资源释放完整（miniProgram/ideProcess/cache）
+
+### Quality Criteria (质量标准)
+
+- ✅ TypeScript 编译 0 错误
+- ✅ 93 个测试用例全部通过
+- ✅ 代码覆盖率 >95%
+- ✅ 无 ESLint 错误
+- ✅ JSDoc 注释完整
+
+### Documentation Criteria (文档标准)
+
+- ✅ SessionState 接口文档
+- ✅ SessionStore API 文档
+- ✅ 配置选项说明
+- ⏳ charter.B2.align.yaml (本文档)
+- ⏳ tasks.B2.atomize.md (任务卡)
+
+## Definition of Done (完成标准)
+
+**代码**:
+- ✅ `src/core/session.ts` 实现完成 (~200 lines)
+- ✅ TypeScript 编译通过
+- ✅ 所有公共方法实现
+
+**测试**:
+- ✅ `tests/unit/session.test.ts` (93 tests)
+- ✅ 覆盖所有方法
+- ✅ 测试超时清理逻辑
+- ✅ 测试资源释放
+
+**文档**:
+- ⏳ charter.B2.align.yaml (追溯)
+- ⏳ tasks.B2.atomize.md (追溯)
+- ⏳ session_log (追溯)
+
+**Git**:
+- ✅ 已提交（随 A2-B1-B2 修复提交）
+
+## Dependencies (依赖)
+
+**前置任务**:
+- ✅ A3: 仓库结构初始化
+- ✅ TypeScript 配置完成
+
+**后续任务**:
+- B2 → B1 (Server 依赖 SessionStore)
+- B2 → C1-C4 (工具需要会话管理)
+
+## Risks (风险)
+
+### Technical Risks (技术风险)
+
+1. **内存泄漏** - 🟢 已缓解
+   - 影响：长时间运行内存溢出
+   - 缓解：定时清理 + dispose 机制
+
+2. **资源泄漏** - 🟢 已缓解
+   - 影响：进程/连接未关闭
+   - 缓解：完整的清理流程 + 测试验证
+
+3. **并发问题** - 🟢 低风险
+   - 影响：竞态条件导致状态不一致
+   - 缓解：Map 原子操作，简单锁机制
+
+### Business Risks (业务风险)
+
+1. **超时配置不当** - 🟡 中风险
+   - 影响：会话过早清理或内存占用过高
+   - 缓解：可配置超时时间，默认值经过测试
+
+## Open Questions (未决问题)
+
+- ✅ 会话超时时间设置为多少合适？（已确定：30 分钟）
+- ✅ 是否需要会话持久化？（否，仅内存存储）
+- ❓ 是否需要支持会话优先级？（当前无）
+
+## References (参考资料)
+
+- `docs/完整实现方案.md` - 会话管理架构
+- `src/types.ts` - SessionState 接口定义
+- Node.js ChildProcess API 文档
+
+---
+
+**Approval**: ✅ RETROSPECTIVE APPROVED
+**Implementation**: ✅ COMPLETED
+**Documentation**: ⏳ IN PROGRESS