@creatoria/miniapp-mcp 0.1.3 → 0.2.0

package/docs/charter.A4.align.yaml

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

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

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