@creatoria/miniapp-mcp 0.1.3 → 0.2.2

package/docs/tasks.A3.atomize.md

@@ -1,564 +0,0 @@
-# Task Cards: A3 - 建立基础目录结构与 TypeScript 工程
-# Parent Task: TASK-2025-001-A3
-# Stage: Atomize (原子化阶段)
-# Status: RETROSPECTIVE (追溯补齐)
-# Created: 2025-10-02 (追溯)
-
----
-
-## Overview (概览)
-
-本文档包含 A3 任务的原子化拆解，将"建立基础目录结构与 TypeScript 工程"拆分为 4 个可独立执行的子任务。每个任务估算时间为 10-20 分钟，总计约 60 分钟，符合 Atomize 原则（1-3 小时颗粒度）。
-
-**注**: 本文档为追溯性创建，基于已完成的实际产物（目录结构 + 配置文件）进行反推。
-
----
-
-## Task Card 1: 创建目录结构
-
-### Metadata (元数据)
-
-```yaml
-TaskID: TASK-2025-001-A3-1
-Title: 创建 src/, docs/, tests/, examples/ 目录结构
-Priority: HIGH
-Status: ✅ COMPLETED (Retrospective)
-Owner: ClaudeCode
-Estimate: 15 分钟
-Actual: ~15 分钟
-```
-
-### Context (上下文)
-
-**Why (为什么)**:
-- 清晰的目录结构是项目组织的基础
-- 分离源代码、测试、文档、示例便于维护和协作
-- 符合 TypeScript 项目最佳实践
-
-**Input (输入)**:
-- 项目根目录
-- TypeScript 项目标准结构规范
-- MCP Server 项目特定需求（工具、核心模块等）
-
-**Output (输出)**:
-- `src/` 目录及子目录（tools/, core/, config/）
-- `docs/` 目录
-- `tests/` 目录及子目录（unit/, integration/）
-- `examples/` 目录及子目录（scripts/, config/）
-
-### Implementation (实施)
-
-**Steps (步骤)**:
-1. 创建 `src/` 源代码目录
-   - 创建 `src/tools/` - MCP 工具实现
-   - 创建 `src/core/` - 核心功能模块
-   - 创建 `src/config/` - 配置管理
-2. 创建 `docs/` 文档目录
-   - 用于存放任务卡、指南、API 文档等
-3. 创建 `tests/` 测试目录
-   - 创建 `tests/unit/` - 单元测试
-   - 创建 `tests/integration/` - 集成测试
-4. 创建 `examples/` 示例目录
-   - 创建 `examples/scripts/` - 示例脚本
-   - 创建 `examples/config/` - 示例配置
-
-**Actual Implementation (实际实现)**:
-```bash
-mkdir -p src/{tools,core,config}
-mkdir -p docs
-mkdir -p tests/{unit,integration}
-mkdir -p examples/{scripts,config}
-```
-
-**Directory Structure**:
-```
-.
-├── src/
-│   ├── tools/         # MCP 工具实现
-│   ├── core/          # 核心模块（logger, session, etc.）
-│   └── config/        # 配置管理
-├── docs/              # 文档（任务卡、指南等）
-├── tests/
-│   ├── unit/          # 单元测试
-│   └── integration/   # 集成测试
-└── examples/
-    ├── scripts/       # 示例脚本
-    └── config/        # 示例配置
-```
-
-### Acceptance Criteria (验收标准 / DoD)
-
-- [x] `src/` 目录存在
-- [x] `src/tools/` 子目录存在
-- [x] `src/core/` 子目录存在
-- [x] `src/config/` 子目录存在
-- [x] `docs/` 目录存在
-- [x] `tests/` 目录存在
-- [x] `tests/unit/` 子目录存在
-- [x] `tests/integration/` 子目录存在
-- [x] `examples/` 目录存在
-- [x] `examples/scripts/` 子目录存在
-- [x] `examples/config/` 子目录存在
-
-### Risks (风险)
-
-- ⚠️ **目录结构调整成本**
-  - 缓解: 遵循标准 TypeScript 项目结构，减少后期调整
-
----
-
-## Task Card 2: 配置 TypeScript 工程
-
-### Metadata (元数据)
-
-```yaml
-TaskID: TASK-2025-001-A3-2
-Title: 配置 tsconfig.json 和 package.json TypeScript 依赖
-Priority: HIGH
-Status: ✅ COMPLETED (Retrospective)
-Owner: ClaudeCode
-Estimate: 20 分钟
-Actual: ~20 分钟
-```
-
-### Context (上下文)
-
-**Why (为什么)**:
-- TypeScript 提供类型安全，减少运行时错误
-- 声明文件生成支持其他项目引用
-- 严格模式和 ESNext 特性提高代码质量
-
-**Input (输入)**:
-- TypeScript 编译器版本要求（5.5.2）
-- Node.js 版本要求（18.0.0+，支持 ESNext）
-- MCP SDK 模块系统要求（ESM）
-- 类型定义需求（@types/node, @types/jest）
-
-**Output (输出)**:
-- `tsconfig.json` (27 行)
-- `package.json` 更新（TypeScript 依赖和脚本）
-
-### Implementation (实施)
-
-**Steps (步骤)**:
-
-1. 创建 `tsconfig.json` 配置文件
-   - 设置 target: "ESNext"（Node.js 18+ 支持）
-   - 设置 module: "ESNext"（ES Modules）
-   - 启用严格模式（strict: true）
-   - 配置输入输出目录（rootDir: "./src", outDir: "./dist"）
-   - 启用声明文件生成（declaration: true, declarationMap: true）
-   - 启用 Source Map（sourceMap: true）
-   - 配置 Path 别名（@/* → src/*）
-   - 排除测试目录（exclude: ["tests"]）
-
-2. 更新 `package.json`
-   - 添加 TypeScript 依赖（devDependencies）
-   - 添加类型定义依赖（@types/node, @types/jest）
-   - 添加构建脚本（build, dev, typecheck）
-   - 设置模块类型（type: "module"）
-   - 设置入口文件（main: "dist/index.js"）
-
-**Actual Implementation (实际实现)**:
-
-**tsconfig.json**:
-```json
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    "module": "ESNext",
-    "lib": ["ESNext"],
-    "moduleResolution": "node",
-    "rootDir": "./src",
-    "outDir": "./dist",
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "allowSyntheticDefaultImports": true,
-    "types": ["node", "jest"],
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["src/*"]
-    }
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "tests"]
-}
-```
-
-**package.json** (relevant sections):
-```json
-{
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "miniprogram-mcp": "dist/cli.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit"
-  },
-  "devDependencies": {
-    "@types/node": "^20.14.9",
-    "@types/jest": "^30.0.0",
-    "typescript": "^5.5.2",
-    "ts-jest": "^29.1.5",
-    "ts-node": "^10.9.2"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
-```
-
-### Acceptance Criteria (验收标准 / DoD)
-
-- [x] `tsconfig.json` 文件存在
-- [x] compilerOptions.target 设置为 "ESNext"
-- [x] compilerOptions.module 设置为 "ESNext"
-- [x] compilerOptions.strict 设置为 true
-- [x] compilerOptions.declaration 设置为 true
-- [x] compilerOptions.sourceMap 设置为 true
-- [x] compilerOptions.rootDir 设置为 "./src"
-- [x] compilerOptions.outDir 设置为 "./dist"
-- [x] paths 配置 "@/*": ["src/*"]
-- [x] exclude 包含 "tests"
-- [x] package.json 包含 TypeScript 依赖
-- [x] package.json 包含 @types/node 和 @types/jest
-- [x] package.json.scripts 包含 build, dev, typecheck
-- [x] package.json.type 设置为 "module"
-- [x] `pnpm build` 成功编译
-- [x] `pnpm typecheck` 通过类型检查
-
-### Risks (风险)
-
-- ⚠️ **ESM 模块兼容性**
-  - 缓解: 优先选择支持 ESM 的依赖
-
-- ⚠️ **Path 别名在不同工具中的支持**
-  - 缓解: 配置 jest.config.js 的 moduleNameMapper
-
----
-
-## Task Card 3: 配置 Jest 测试框架
-
-### Metadata (元数据)
-
-```yaml
-TaskID: TASK-2025-001-A3-3
-Title: 配置 jest.config.js 和测试环境
-Priority: HIGH
-Status: ✅ COMPLETED (Retrospective)
-Owner: ClaudeCode
-Estimate: 15 分钟
-Actual: ~15 分钟
-```
-
-### Context (上下文)
-
-**Why (为什么)**:
-- Jest 是 TypeScript 项目的标准测试框架
-- ts-jest 提供 TypeScript 支持
-- 需要配置 ESM 和 Path 别名支持
-
-**Input (输入)**:
-- TypeScript 配置（tsconfig.json）
-- ESM 模块系统要求
-- Path 别名配置（@/*）
-- 测试目录结构（tests/unit/, tests/integration/）
-
-**Output (输出)**:
-- `jest.config.js` (25 行)
-- package.json 测试脚本
-
-### Implementation (实施)
-
-**Steps (步骤)**:
-
-1. 创建 `jest.config.js` 配置文件
-   - 设置 preset: 'ts-jest/presets/default-esm'（ESM 支持）
-   - 设置 testEnvironment: 'node'
-   - 配置 extensionsToTreatAsEsm: ['.ts']
-   - 配置 moduleNameMapper（支持 .js 扩展名和 @/* 别名）
-   - 配置 transform（ts-jest + useESM）
-   - 设置 testMatch: ['**/tests/**/*.test.ts']
-   - 配置 coverage（collectCoverageFrom, coverageDirectory）
-
-2. 更新 `package.json`
-   - 添加 Jest 依赖（jest, ts-jest, @types/jest）
-   - 添加测试脚本（test, test:watch）
-
-**Actual Implementation (实际实现)**:
-
-**jest.config.js**:
-```javascript
-export default {
-  preset: 'ts-jest/presets/default-esm',
-  testEnvironment: 'node',
-  extensionsToTreatAsEsm: ['.ts'],
-  moduleNameMapper: {
-    '^(\\.{1,2}/.*)\\.js$': '$1',
-    '^@/(.*)$': '<rootDir>/src/$1',
-  },
-  transform: {
-    '^.+\\.tsx?$': [
-      'ts-jest',
-      {
-        useESM: true,
-        tsconfig: {
-          types: ['node', 'jest'],
-        },
-      },
-    ],
-  },
-  testMatch: ['**/tests/**/*.test.ts'],
-  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts'],
-  coverageDirectory: 'coverage',
-  coverageReporters: ['text', 'lcov', 'html'],
-}
-```
-
-**package.json** (relevant sections):
-```json
-{
-  "scripts": {
-    "test": "jest",
-    "test:watch": "jest --watch"
-  },
-  "devDependencies": {
-    "jest": "^29.7.0",
-    "ts-jest": "^29.1.5",
-    "@types/jest": "^30.0.0"
-  }
-}
-```
-
-### Acceptance Criteria (验收标准 / DoD)
-
-- [x] `jest.config.js` 文件存在
-- [x] preset 设置为 'ts-jest/presets/default-esm'
-- [x] testEnvironment 设置为 'node'
-- [x] extensionsToTreatAsEsm 包含 '.ts'
-- [x] moduleNameMapper 支持 .js 扩展名转换
-- [x] moduleNameMapper 支持 @/* 别名
-- [x] transform 配置 ts-jest + useESM
-- [x] testMatch 设置为 ['**/tests/**/*.test.ts']
-- [x] collectCoverageFrom 包含 src/**/*.ts
-- [x] package.json 包含 Jest 依赖
-- [x] package.json.scripts 包含 test, test:watch
-- [x] `pnpm test` 可以运行测试（即使没有测试文件）
-
-### Risks (风险)
-
-- ⚠️ **ESM + TypeScript + Jest 配置复杂**
-  - 缓解: 使用 ts-jest/presets/default-esm 预设
-
-- ⚠️ **Path 别名在 Jest 中不生效**
-  - 缓解: moduleNameMapper 映射 @/* 到 <rootDir>/src/$1
-
----
-
-## Task Card 4: 配置 Git 版本控制
-
-### Metadata (元数据)
-
-```yaml
-TaskID: TASK-2025-001-A3-4
-Title: 配置 .gitignore 排除规则
-Priority: MEDIUM
-Status: ✅ COMPLETED (Retrospective)
-Owner: ClaudeCode
-Estimate: 10 分钟
-Actual: ~10 分钟
-```
-
-### Context (上下文)
-
-**Why (为什么)**:
-- Git 版本控制是项目协作的基础
-- .gitignore 排除不应提交的文件（编译产物、依赖、日志等）
-- 保持仓库干净，减小仓库体积
-
-**Input (输入)**:
-- TypeScript 项目编译产物（dist/）
-- Node.js 依赖（node_modules/）
-- 测试覆盖率报告（coverage/）
-- 日志文件（*.log）
-- 环境变量文件（.env）
-- IDE 配置文件（.vscode/, .idea/）
-- MCP 特定文件（memory.json, .mcp.json）
-
-**Output (输出)**:
-- `.gitignore` (58 行)
-
-### Implementation (实施)
-
-**Steps (步骤)**:
-
-1. 创建 `.gitignore` 文件
-2. 添加 Node.js 标准排除规则
-   - node_modules/, package-lock.json, yarn.lock
-3. 添加 TypeScript 编译产物排除
-   - dist/, build/, *.tsbuildinfo
-4. 添加日志文件排除
-   - logs/, *.log, npm-debug.log*
-5. 添加测试覆盖率排除
-   - coverage/, .nyc_output/
-6. 添加 IDE 配置文件排除
-   - .vscode/, .idea/, *.swp, .DS_Store
-7. 添加环境变量文件排除
-   - .env, .env.local, .env.*.local
-8. 添加 MCP 特定文件排除
-   - .mcp-artifacts/, memory.json, .mcp.json
-9. 添加临时文件排除
-   - tmp/, temp/, .cache/
-
-**Actual Implementation (实际实现)**:
-
-**.gitignore** (58 lines):
-```gitignore
-# Dependencies
-node_modules/
-package-lock.json
-yarn.lock
-
-# Build output
-dist/
-build/
-*.tsbuildinfo
-
-# Logs
-logs/
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-
-# Testing
-coverage/
-.nyc_output/
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-*~
-.DS_Store
-
-# Environment
-.env
-.env.local
-.env.*.local
-
-# Artifacts
-artifacts/
-.mcp-artifacts/
-.test-output/
-*.screenshot.png
-*.snapshot.json
-
-# Temporary
-tmp/
-temp/
-.cache/
-
-# MCP
-memory.json
-.mcp.json
-.claude/
-
-# Session logs
-.llm/session_log/
-.llm/handoff/
-
-# OS
-Thumbs.db
-```
-
-### Acceptance Criteria (验收标准 / DoD)
-
-- [x] `.gitignore` 文件存在
-- [x] 排除 node_modules/
-- [x] 排除 dist/ 和 build/
-- [x] 排除 *.log
-- [x] 排除 coverage/
-- [x] 排除 .vscode/ 和 .idea/
-- [x] 排除 .env 文件
-- [x] 排除 .DS_Store
-- [x] 排除 MCP 特定文件（memory.json, .mcp.json）
-- [x] 排除临时文件（tmp/, temp/）
-
-### Risks (风险)
-
-- ⚠️ **过度排除可能导致必需文件未提交**
-  - 缓解: 遵循标准规则，仅排除编译产物和临时文件
-
----
-
-## Summary (总结)
-
-### Completed Tasks (已完成任务)
-
-| TaskID | Title | Estimate | Actual | Status |
-|--------|-------|----------|--------|--------|
-| A3-1 | 创建目录结构 | 15 min | ~15 min | ✅ COMPLETED |
-| A3-2 | 配置 TypeScript | 20 min | ~20 min | ✅ COMPLETED |
-| A3-3 | 配置 Jest 测试 | 15 min | ~15 min | ✅ COMPLETED |
-| A3-4 | 配置 Git | 10 min | ~10 min | ✅ COMPLETED |
-| **Total** | | **60 min** | **~60 min** | **✅ COMPLETED** |
-
-### Deliverables (交付物)
-
-1. ✅ **目录结构**
-   - src/ (tools/, core/, config/ 子目录)
-   - docs/
-   - tests/ (unit/, integration/ 子目录)
-   - examples/ (scripts/, config/ 子目录)
-
-2. ✅ **TypeScript 配置**
-   - tsconfig.json (27 行)
-   - package.json (TypeScript 依赖和脚本)
-
-3. ✅ **Jest 测试配置**
-   - jest.config.js (25 行)
-   - package.json (Jest 依赖和脚本)
-
-4. ✅ **Git 配置**
-   - .gitignore (58 行)
-
-### Quality Metrics (质量指标)
-
-- **估算准确性**: 60 分钟估算 vs ~60 分钟实际（100% 准确）
-- **配置完整性**: TypeScript, Jest, Git 配置全覆盖
-- **构建验证**: `pnpm build` ✓, `pnpm typecheck` ✓
-- **可维护性**: 配置清晰，注释完善
-
----
-
-## Retrospective Notes (追溯说明)
-
-**Process Violation (流程违规)**:
-- ❌ 实际开发中跳过了 Align/Atomize/Approve 阶段
-- ❌ 直接进入 Automate 阶段开始创建目录和配置文件
-- ✅ 通过追溯补齐任务卡进行补救
-
-**Lessons Learned (经验教训)**:
-1. 项目初始化也应遵循 6A 工作法
-2. TypeScript + ESM + Jest 配置复杂度较高，应在 Atomize 阶段预估充足时间
-3. Path 别名配置需要在多个地方同步（tsconfig, jest.config）
-4. 追溯补齐虽然能补救，但不如正常流程高效
-
-**Approval Required (需要批准)**:
-- ⏳ 等待用户批准本追溯性任务卡
-- ⏳ 用户批准后才能继续 A4 任务的 Review
-
----
-
-**注**: 本文档为追溯性创建，基于已完成的技术实现（目录结构 + 配置文件）反推任务拆解。所有任务已实际完成，现等待用户批准追溯补齐的合理性。