koatty 4.0.0 → 4.0.3

package/TASKS.md

@@ -0,0 +1,1227 @@
+# Koatty Monorepo 迁移任务清单
+
+> **目标**: 将 Koatty 框架迁移到 Monorepo 架构，并配置自动同步  
+> **执行方式**: 由工程 LLM 逐个执行，每个任务独立且可测试  
+> **预计时间**: 5-7 天  
+> **状态**: 📋 待开始
+
+---
+
+## 📊 任务概览
+
+| 阶段 | 任务数 | 预计时间 | 状态 |
+|-----|-------|---------|------|
+| **阶段 0**: 环境准备 | 3 | 0.5天 | ⏳ |
+| **阶段 1**: 创建 Monorepo | 5 | 1天 | ⏳ |
+| **阶段 2**: 迁移核心包 | 8 | 2天 | ⏳ |
+| **阶段 3**: 配置构建系统 | 6 | 1天 | ⏳ |
+| **阶段 4**: 配置自动同步 | 5 | 1天 | ⏳ |
+| **阶段 5**: 测试与验证 | 6 | 1天 | ⏳ |
+| **总计** | **33个任务** | **6.5天** | |
+
+---
+
+## 阶段 0: 环境准备
+
+### TASK-0.1: 验证 Node.js 版本
+
+**目标**: 确保 Node.js 版本 >= 18.0.0
+
+**前置条件**:
+- 无
+
+**执行步骤**:
+1. 运行 `node -v` 检查版本
+2. 如果版本 < 18.0.0，输出升级指南
+3. 创建验证报告
+
+**验收标准**:
+- [ ] Node.js 版本 >= 18.0.0
+- [ ] 输出版本信息到 `reports/node-version.txt`
+
+**测试命令**:
+```bash
+node -v
+cat reports/node-version.txt
+```
+
+**回滚方案**:
+- 无需回滚（只读操作）
+
+---
+
+### TASK-0.2: 安装 pnpm
+
+**目标**: 安装并验证 pnpm >= 8.0.0
+
+**前置条件**:
+- TASK-0.1 完成
+
+**执行步骤**:
+1. 检查 pnpm 是否已安装
+2. 如果未安装，运行 `npm install -g pnpm@8`
+3. 验证版本 `pnpm -v`
+4. 记录到报告
+
+**验收标准**:
+- [ ] pnpm 已安装
+- [ ] pnpm 版本 >= 8.0.0
+- [ ] 输出版本信息到 `reports/pnpm-version.txt`
+
+**测试命令**:
+```bash
+pnpm -v
+cat reports/pnpm-version.txt
+```
+
+**回滚方案**:
+- 无需回滚（全局安装）
+
+---
+
+### TASK-0.3: 创建备份分支
+
+**目标**: 为当前仓库创建备份分支
+
+**前置条件**:
+- TASK-0.2 完成
+- 当前在 koatty 仓库根目录
+
+**执行步骤**:
+1. 确保工作区干净: `git status`
+2. 创建备份分支: `git branch backup-before-monorepo-$(date +%Y%m%d)`
+3. 推送到远程: `git push origin backup-before-monorepo-$(date +%Y%m%d)`
+4. 记录分支名
+
+**验收标准**:
+- [ ] 创建了备份分支
+- [ ] 备份分支已推送到远程
+- [ ] 分支名记录在 `reports/backup-branch.txt`
+
+**测试命令**:
+```bash
+git branch --list 'backup-before-monorepo-*'
+cat reports/backup-branch.txt
+```
+
+**回滚方案**:
+```bash
+# 恢复到备份分支
+git checkout $(cat reports/backup-branch.txt)
+```
+
+---
+
+## 阶段 1: 创建 Monorepo 基础结构
+
+### TASK-1.1: 创建 Monorepo 目录
+
+**目标**: 在上层目录创建 koatty-monorepo
+
+**前置条件**:
+- TASK-0.3 完成
+
+**执行步骤**:
+1. 进入上层目录: `cd ..`
+2. 创建 monorepo 目录: `mkdir -p koatty-monorepo`
+3. 进入目录: `cd koatty-monorepo`
+4. 初始化 git: `git init`
+5. 创建 .gitignore
+
+**验收标准**:
+- [ ] koatty-monorepo 目录已创建
+- [ ] Git 仓库已初始化
+- [ ] .gitignore 文件已创建
+
+**测试命令**:
+```bash
+cd koatty-monorepo
+git status
+ls -la .gitignore
+```
+
+**回滚方案**:
+```bash
+cd ..
+rm -rf koatty-monorepo
+```
+
+**输出文件**:
+- `koatty-monorepo/.gitignore`
+
+---
+
+### TASK-1.2: 创建基础目录结构
+
+**目标**: 创建 packages、apps、tools 目录
+
+**前置条件**:
+- TASK-1.1 完成
+- 当前在 koatty-monorepo 目录
+
+**执行步骤**:
+1. 创建目录: `mkdir -p packages apps tools scripts .github/workflows`
+2. 创建 reports 目录: `mkdir reports`
+3. 列出目录结构
+
+**验收标准**:
+- [ ] packages/ 目录存在
+- [ ] apps/ 目录存在
+- [ ] tools/ 目录存在
+- [ ] scripts/ 目录存在
+- [ ] .github/workflows/ 目录存在
+- [ ] 目录结构输出到 `reports/directory-structure.txt`
+
+**测试命令**:
+```bash
+ls -la packages apps tools scripts .github/workflows
+tree -L 2 > reports/directory-structure.txt 2>/dev/null || find . -maxdepth 2 -type d > reports/directory-structure.txt
+```
+
+**回滚方案**:
+```bash
+rm -rf packages apps tools scripts .github
+```
+
+---
+
+### TASK-1.3: 初始化 package.json
+
+**目标**: 创建根 package.json
+
+**前置条件**:
+- TASK-1.2 完成
+
+**执行步骤**:
+1. 运行 `pnpm init`
+2. 更新 package.json 内容
+3. 添加必要的脚本
+
+**验收标准**:
+- [ ] package.json 存在
+- [ ] name 为 "koatty-monorepo"
+- [ ] private 为 true
+- [ ] packageManager 字段指定 pnpm@8
+- [ ] 包含基础 scripts
+
+**测试命令**:
+```bash
+cat package.json | jq '.name, .private, .packageManager'
+```
+
+**回滚方案**:
+```bash
+rm package.json
+```
+
+**输出文件**:
+- `package.json`
+
+---
+
+### TASK-1.4: 创建 pnpm-workspace.yaml
+
+**目标**: 配置 pnpm workspace
+
+**前置条件**:
+- TASK-1.3 完成
+
+**执行步骤**:
+1. 创建 pnpm-workspace.yaml
+2. 配置 packages、apps、tools 为 workspace
+
+**验收标准**:
+- [ ] pnpm-workspace.yaml 存在
+- [ ] 包含 'packages/*'
+- [ ] 包含 'apps/*'
+- [ ] 包含 'tools/*'
+
+**测试命令**:
+```bash
+cat pnpm-workspace.yaml
+```
+
+**回滚方案**:
+```bash
+rm pnpm-workspace.yaml
+```
+
+**输出文件**:
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - 'packages/*'
+  - 'apps/*'
+  - 'tools/*'
+```
+
+---
+
+### TASK-1.5: 创建 turbo.json
+
+**目标**: 配置 Turborepo
+
+**前置条件**:
+- TASK-1.4 完成
+
+**执行步骤**:
+1. 安装 turbo: `pnpm add -D turbo`
+2. 创建 turbo.json
+3. 配置 pipeline
+
+**验收标准**:
+- [ ] turbo 已安装
+- [ ] turbo.json 存在
+- [ ] 配置了 build、dev、test、lint pipeline
+- [ ] 启用了缓存
+
+**测试命令**:
+```bash
+cat turbo.json
+pnpm list turbo
+```
+
+**回滚方案**:
+```bash
+rm turbo.json
+pnpm remove turbo
+```
+
+**输出文件**:
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "globalDependencies": [
+    "tsconfig.base.json",
+    ".eslintrc.js"
+  ],
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", "*.tsbuildinfo"],
+      "cache": true
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "test": {
+      "dependsOn": ["build"],
+      "outputs": ["coverage/**"],
+      "cache": true
+    },
+    "lint": {
+      "outputs": [],
+      "cache": true
+    },
+    "clean": {
+      "cache": false
+    }
+  }
+}
+```
+
+---
+
+## 阶段 2: 迁移核心包
+
+### TASK-2.1: 配置 Git Remotes
+
+**目标**: 为每个核心包添加独立仓库的 remote
+
+**前置条件**:
+- TASK-1.5 完成
+- 当前在 koatty-monorepo 目录
+
+**执行步骤**:
+1. 添加 remote for koatty_core
+2. 添加 remote for koatty_router
+3. 添加 remote for koatty_serve
+4. 添加 remote for koatty_exception
+5. 添加 remote for koatty_trace
+6. 添加 remote for koatty_config
+7. 添加 remote for koatty
+8. 列出所有 remotes
+
+**验收标准**:
+- [ ] 7个 remote 已添加
+- [ ] remote 列表输出到 `reports/git-remotes.txt`
+
+**测试命令**:
+```bash
+git remote -v > reports/git-remotes.txt
+cat reports/git-remotes.txt
+```
+
+**回滚方案**:
+```bash
+git remote remove koatty-core
+git remote remove koatty-router
+git remote remove koatty-serve
+git remote remove koatty-exception
+git remote remove koatty-trace
+git remote remove koatty-config
+git remote remove koatty-main
+```
+
+---
+
+### TASK-2.2: 克隆 koatty_config
+
+**目标**: 将 koatty_config 克隆到 packages/
+
+**前置条件**:
+- TASK-2.1 完成
+
+**执行步骤**:
+1. 克隆仓库到临时目录
+2. 移动到 packages/koatty-config
+3. 删除 .git 目录（保留代码）
+4. 验证文件完整性
+
+**验收标准**:
+- [ ] packages/koatty-config/ 目录存在
+- [ ] package.json 存在且 name 为 "koatty_config"
+- [ ] src/ 目录存在
+- [ ] 无 .git 目录
+
+**测试命令**:
+```bash
+ls packages/koatty-config/
+cat packages/koatty-config/package.json | jq '.name, .version'
+test ! -d packages/koatty-config/.git && echo "No .git directory"
+```
+
+**回滚方案**:
+```bash
+rm -rf packages/koatty-config
+```
+
+---
+
+### TASK-2.3: 克隆 koatty_exception
+
+**目标**: 将 koatty_exception 克隆到 packages/
+
+**前置条件**:
+- TASK-2.2 完成
+
+**执行步骤**:
+1. 克隆仓库到临时目录
+2. 移动到 packages/koatty-exception
+3. 删除 .git 目录
+4. 验证文件完整性
+
+**验收标准**:
+- [ ] packages/koatty-exception/ 目录存在
+- [ ] package.json 存在且 name 为 "koatty_exception"
+- [ ] src/ 目录存在
+
+**测试命令**:
+```bash
+cat packages/koatty-exception/package.json | jq '.name, .version'
+```
+
+**回滚方案**:
+```bash
+rm -rf packages/koatty-exception
+```
+
+---
+
+### TASK-2.4: 克隆 koatty_trace
+
+**目标**: 将 koatty_trace 克隆到 packages/
+
+**前置条件**:
+- TASK-2.3 完成
+
+**执行步骤**:
+1. 克隆仓库
+2. 移动到 packages/koatty-trace
+3. 删除 .git 目录
+4. 验证
+
+**验收标准**:
+- [ ] packages/koatty-trace/ 目录存在
+- [ ] package.json 正确
+
+**测试命令**:
+```bash
+cat packages/koatty-trace/package.json | jq '.name'
+```
+
+**回滚方案**:
+```bash
+rm -rf packages/koatty-trace
+```
+
+---
+
+### TASK-2.5: 克隆 koatty_core
+
+**目标**: 将 koatty_core 克隆到 packages/
+
+**前置条件**:
+- TASK-2.4 完成
+
+**执行步骤**:
+1. 克隆 koatty_core
+2. 移动到 packages/koatty-core
+3. 删除 .git 目录
+4. 验证
+
+**验收标准**:
+- [ ] packages/koatty-core/ 目录存在
+- [ ] package.json 正确
+
+**测试命令**:
+```bash
+cat packages/koatty-core/package.json | jq '.name'
+```
+
+**回滚方案**:
+```bash
+rm -rf packages/koatty-core
+```
+
+---
+
+### TASK-2.6: 克隆 koatty_router
+
+**目标**: 将 koatty_router 克隆到 packages/
+
+**前置条件**:
+- TASK-2.5 完成
+
+**执行步骤**:
+1. 克隆仓库
+2. 移动到 packages/koatty-router
+3. 删除 .git 目录
+4. 验证
+
+**验收标准**:
+- [ ] packages/koatty-router/ 目录存在
+- [ ] package.json 正确
+
+**测试命令**:
+```bash
+cat packages/koatty-router/package.json | jq '.name'
+```
+
+**回滚方案**:
+```bash
+rm -rf packages/koatty-router
+```
+
+---
+
+### TASK-2.7: 克隆 koatty_serve
+
+**目标**: 将 koatty_serve 克隆到 packages/
+
+**前置条件**:
+- TASK-2.6 完成
+
+**执行步骤**:
+1. 克隆仓库
+2. 移动到 packages/koatty-serve
+3. 删除 .git 目录
+4. 验证
+
+**验收标准**:
+- [ ] packages/koatty-serve/ 目录存在
+- [ ] package.json 正确
+
+**测试命令**:
+```bash
+cat packages/koatty-serve/package.json | jq '.name'
+```
+
+**回滚方案**:
+```bash
+rm -rf packages/koatty-serve
+```
+
+---
+
+### TASK-2.8: 克隆 koatty 主包
+
+**目标**: 将 koatty 克隆到 packages/
+
+**前置条件**:
+- TASK-2.7 完成
+
+**执行步骤**:
+1. 克隆 koatty
+2. 移动到 packages/koatty
+3. 删除 .git 目录
+4. 验证
+5. 生成迁移报告
+
+**验收标准**:
+- [ ] packages/koatty/ 目录存在
+- [ ] 所有7个包都已迁移
+- [ ] 迁移报告生成: `reports/migration-summary.txt`
+
+**测试命令**:
+```bash
+ls packages/
+cat packages/koatty/package.json | jq '.name'
+echo "Migrated packages:" > reports/migration-summary.txt
+ls packages/ >> reports/migration-summary.txt
+cat reports/migration-summary.txt
+```
+
+**回滚方案**:
+```bash
+rm -rf packages/koatty
+```
+
+---
+
+## 阶段 3: 配置构建系统
+
+### TASK-3.1: 更新 workspace 依赖 - koatty_config
+
+**目标**: 将 koatty_config 的内部依赖改为 workspace:*
+
+**前置条件**:
+- TASK-2.8 完成
+
+**执行步骤**:
+1. 读取 packages/koatty-config/package.json
+2. 检查 dependencies 中的 koatty 相关包
+3. 如果是 monorepo 包，改为 "workspace:*"
+4. 保存文件
+
+**验收标准**:
+- [ ] monorepo 包使用 "workspace:*"
+- [ ] 独立包（koatty_container, koatty_lib, koatty_logger, koatty_loader）保持 npm 版本
+
+**测试命令**:
+```bash
+cat packages/koatty-config/package.json | jq '.dependencies'
+```
+
+**回滚方案**:
+```bash
+git checkout packages/koatty-config/package.json
+```
+
+---
+
+### TASK-3.2: 更新 workspace 依赖 - koatty_exception
+
+**目标**: 更新 koatty_exception 的依赖
+
+**前置条件**:
+- TASK-3.1 完成
+
+**执行步骤**:
+1. 更新 package.json 中的 monorepo 包依赖为 "workspace:*"
+2. 保留独立包的 npm 版本
+
+**验收标准**:
+- [ ] 依赖正确更新
+
+**测试命令**:
+```bash
+cat packages/koatty-exception/package.json | jq '.dependencies'
+```
+
+**回滚方案**:
+```bash
+git checkout packages/koatty-exception/package.json
+```
+
+---
+
+### TASK-3.3: 更新 workspace 依赖 - koatty_trace
+
+**目标**: 更新 koatty_trace 的依赖
+
+**前置条件**:
+- TASK-3.2 完成
+
+**执行步骤**:
+1. 更新依赖为 workspace:*
+
+**验收标准**:
+- [ ] 依赖正确更新
+
+**测试命令**:
+```bash
+cat packages/koatty-trace/package.json | jq '.dependencies'
+```
+
+**回滚方案**:
+```bash
+git checkout packages/koatty-trace/package.json
+```
+
+---
+
+### TASK-3.4: 更新 workspace 依赖 - koatty_core, koatty_router, koatty_serve
+
+**目标**: 批量更新剩余包的依赖
+
+**前置条件**:
+- TASK-3.3 完成
+
+**执行步骤**:
+1. 更新 koatty_core
+2. 更新 koatty_router
+3. 更新 koatty_serve
+4. 生成依赖关系报告
+
+**验收标准**:
+- [ ] 所有 monorepo 包使用 workspace:*
+- [ ] 依赖关系报告: `reports/dependencies.txt`
+
+**测试命令**:
+```bash
+for pkg in koatty-core koatty-router koatty-serve; do
+  echo "=== $pkg ===" >> reports/dependencies.txt
+  cat packages/$pkg/package.json | jq '.dependencies' >> reports/dependencies.txt
+done
+cat reports/dependencies.txt
+```
+
+**回滚方案**:
+```bash
+git checkout packages/koatty-core/package.json
+git checkout packages/koatty-router/package.json
+git checkout packages/koatty-serve/package.json
+```
+
+---
+
+### TASK-3.5: 更新 koatty 主包依赖
+
+**目标**: 更新 koatty 主包的所有依赖
+
+**前置条件**:
+- TASK-3.4 完成
+
+**执行步骤**:
+1. 更新所有核心包依赖为 workspace:*
+2. 保留独立包版本
+3. 验证依赖完整性
+
+**验收标准**:
+- [ ] koatty 正确依赖所有核心包
+- [ ] 使用 workspace 协议
+
+**测试命令**:
+```bash
+cat packages/koatty/package.json | jq '.dependencies'
+```
+
+**回滚方案**:
+```bash
+git checkout packages/koatty/package.json
+```
+
+---
+
+### TASK-3.6: 安装所有依赖并验证
+
+**目标**: 安装 workspace 依赖并验证
+
+**前置条件**:
+- TASK-3.5 完成
+
+**执行步骤**:
+1. 运行 `pnpm install`
+2. 检查是否有错误
+3. 验证 workspace 链接
+4. 生成依赖树
+
+**验收标准**:
+- [ ] pnpm install 成功
+- [ ] 没有依赖错误
+- [ ] workspace 包正确链接
+- [ ] 依赖树输出到 `reports/dependency-tree.txt`
+
+**测试命令**:
+```bash
+pnpm install
+pnpm list --depth=1 > reports/dependency-tree.txt
+cat reports/dependency-tree.txt
+```
+
+**回滚方案**:
+```bash
+rm -rf node_modules pnpm-lock.yaml
+```
+
+---
+
+## 阶段 4: 配置自动同步
+
+### TASK-4.1: 创建同步脚本
+
+**目标**: 创建 scripts/sync-to-repos.sh
+
+**前置条件**:
+- TASK-3.6 完成
+
+**执行步骤**:
+1. 创建 scripts/sync-to-repos.sh
+2. 添加执行权限
+3. 测试脚本语法
+
+**验收标准**:
+- [ ] 脚本文件存在
+- [ ] 有执行权限
+- [ ] bash 语法正确
+
+**测试命令**:
+```bash
+ls -la scripts/sync-to-repos.sh
+bash -n scripts/sync-to-repos.sh
+```
+
+**回滚方案**:
+```bash
+rm scripts/sync-to-repos.sh
+```
+
+**输出文件**:
+参考 MONOREPO_SYNC_STRATEGY.md 中的同步脚本
+
+---
+
+### TASK-4.2: 创建同步状态检查脚本
+
+**目标**: 创建 scripts/check-sync-status.sh
+
+**前置条件**:
+- TASK-4.1 完成
+
+**执行步骤**:
+1. 创建检查脚本
+2. 添加执行权限
+
+**验收标准**:
+- [ ] 脚本存在且可执行
+- [ ] 语法正确
+
+**测试命令**:
+```bash
+bash -n scripts/check-sync-status.sh
+```
+
+**回滚方案**:
+```bash
+rm scripts/check-sync-status.sh
+```
+
+---
+
+### TASK-4.3: 创建 GitHub Actions - 同步到独立仓库
+
+**目标**: 创建自动同步 workflow
+
+**前置条件**:
+- TASK-4.2 完成
+
+**执行步骤**:
+1. 创建 .github/workflows/sync-to-independent-repos.yml
+2. 配置矩阵构建
+3. 验证 YAML 语法
+
+**验收标准**:
+- [ ] workflow 文件存在
+- [ ] YAML 语法正确
+- [ ] 包含所有7个包的同步配置
+
+**测试命令**:
+```bash
+cat .github/workflows/sync-to-independent-repos.yml
+# 验证 YAML
+python3 -c "import yaml; yaml.safe_load(open('.github/workflows/sync-to-independent-repos.yml'))" 2>/dev/null || echo "YAML is valid"
+```
+
+**回滚方案**:
+```bash
+rm .github/workflows/sync-to-independent-repos.yml
+```
+
+**输出文件**:
+参考 MONOREPO_SYNC_STRATEGY.md 中的 GitHub Actions 配置
+
+---
+
+### TASK-4.4: 创建 GitHub Actions - 反向同步
+
+**目标**: 创建从独立仓库同步回 monorepo 的 workflow
+
+**前置条件**:
+- TASK-4.3 完成
+
+**执行步骤**:
+1. 创建 .github/workflows/sync-from-independent-repos.yml
+2. 验证配置
+
+**验收标准**:
+- [ ] workflow 文件存在
+- [ ] 配置正确
+
+**测试命令**:
+```bash
+ls -la .github/workflows/sync-from-independent-repos.yml
+```
+
+**回滚方案**:
+```bash
+rm .github/workflows/sync-from-independent-repos.yml
+```
+
+---
+
+### TASK-4.5: 配置 Changesets
+
+**目标**: 安装并配置 Changesets 用于版本管理
+
+**前置条件**:
+- TASK-4.4 完成
+
+**执行步骤**:
+1. 安装 @changesets/cli: `pnpm add -D @changesets/cli`
+2. 初始化: `pnpm changeset init`
+3. 配置 .changeset/config.json
+4. 更新根 package.json 添加 scripts
+
+**验收标准**:
+- [ ] @changesets/cli 已安装
+- [ ] .changeset/ 目录存在
+- [ ] config.json 已配置
+- [ ] package.json 包含 changeset 相关 scripts
+
+**测试命令**:
+```bash
+ls -la .changeset/
+cat .changeset/config.json
+cat package.json | jq '.scripts | with_entries(select(.key | contains("changeset")))'
+```
+
+**回滚方案**:
+```bash
+rm -rf .changeset/
+pnpm remove @changesets/cli
+```
+
+---
+
+## 阶段 5: 测试与验证
+
+### TASK-5.1: 构建所有包
+
+**目标**: 验证所有包可以成功构建
+
+**前置条件**:
+- TASK-4.5 完成
+- 所有依赖已安装
+
+**执行步骤**:
+1. 运行 `pnpm build`
+2. 检查构建输出
+3. 验证 dist 目录
+4. 记录构建时间
+
+**验收标准**:
+- [ ] 构建成功无错误
+- [ ] 所有包的 dist/ 目录存在
+- [ ] 构建报告输出到 `reports/build-result.txt`
+
+**测试命令**:
+```bash
+pnpm build 2>&1 | tee reports/build-result.txt
+for pkg in packages/*/; do
+  echo "Checking $pkg"
+  ls -la "$pkg/dist/" || echo "No dist in $pkg"
+done
+```
+
+**回滚方案**:
+```bash
+pnpm clean
+```
+
+---
+
+### TASK-5.2: 运行所有测试
+
+**目标**: 验证所有测试通过
+
+**前置条件**:
+- TASK-5.1 完成
+
+**执行步骤**:
+1. 运行 `pnpm test`
+2. 收集测试结果
+3. 生成覆盖率报告（如果有）
+
+**验收标准**:
+- [ ] 所有测试通过
+- [ ] 测试报告输出到 `reports/test-result.txt`
+
+**测试命令**:
+```bash
+pnpm test 2>&1 | tee reports/test-result.txt
+tail -20 reports/test-result.txt
+```
+
+**回滚方案**:
+- 无需回滚（只读操作）
+
+---
+
+### TASK-5.3: 验证 Turborepo 缓存
+
+**目标**: 验证增量构建和缓存功能
+
+**前置条件**:
+- TASK-5.2 完成
+
+**执行步骤**:
+1. 清理构建: `pnpm clean`
+2. 首次构建: `pnpm build`
+3. 再次构建: `pnpm build`
+4. 对比构建时间
+5. 验证 FULL TURBO 输出
+
+**验收标准**:
+- [ ] 第二次构建显示缓存命中
+- [ ] 看到 "FULL TURBO" 或 "cache hit"
+- [ ] 缓存报告输出到 `reports/cache-validation.txt`
+
+**测试命令**:
+```bash
+pnpm clean
+echo "=== First build ===" > reports/cache-validation.txt
+time pnpm build 2>&1 | tee -a reports/cache-validation.txt
+echo "=== Second build (should use cache) ===" >> reports/cache-validation.txt
+time pnpm build 2>&1 | tee -a reports/cache-validation.txt
+cat reports/cache-validation.txt
+```
+
+**回滚方案**:
+```bash
+rm -rf .turbo
+```
+
+---
+
+### TASK-5.4: 验证 workspace 协议
+
+**目标**: 确认 workspace:* 正确工作
+
+**前置条件**:
+- TASK-5.3 完成
+
+**执行步骤**:
+1. 检查 node_modules 中的软链接
+2. 修改一个包的代码
+3. 验证其他包能立即使用
+4. 生成 workspace 验证报告
+
+**验收标准**:
+- [ ] workspace 包是软链接
+- [ ] 修改即时生效
+- [ ] 验证报告: `reports/workspace-validation.txt`
+
+**测试命令**:
+```bash
+echo "Checking workspace links..." > reports/workspace-validation.txt
+ls -la node_modules/.pnpm/node_modules/koatty_* >> reports/workspace-validation.txt 2>&1 || \
+ls -la node_modules/koatty_* >> reports/workspace-validation.txt 2>&1
+cat reports/workspace-validation.txt
+```
+
+**回滚方案**:
+- 无需回滚
+
+---
+
+### TASK-5.5: 创建测试应用
+
+**目标**: 在 apps/demo 创建测试应用
+
+**前置条件**:
+- TASK-5.4 完成
+
+**执行步骤**:
+1. 创建 apps/demo 目录
+2. 创建 package.json
+3. 引用 monorepo 包
+4. 创建简单的测试代码
+5. 验证可以运行
+
+**验收标准**:
+- [ ] apps/demo 存在
+- [ ] 可以成功引用 koatty 包
+- [ ] 可以构建和运行
+
+**测试命令**:
+```bash
+cd apps/demo
+pnpm install
+pnpm build
+```
+
+**回滚方案**:
+```bash
+rm -rf apps/demo
+```
+
+---
+
+### TASK-5.6: 生成最终报告
+
+**目标**: 生成完整的迁移验证报告
+
+**前置条件**:
+- TASK-5.5 完成
+
+**执行步骤**:
+1. 汇总所有 reports/ 中的文件
+2. 生成迁移检查清单
+3. 生成下一步建议
+4. 创建 MIGRATION_COMPLETE.md
+
+**验收标准**:
+- [ ] reports/ 包含所有阶段的报告
+- [ ] MIGRATION_COMPLETE.md 存在
+- [ ] 包含成功/失败统计
+- [ ] 包含下一步行动建议
+
+**测试命令**:
+```bash
+ls -la reports/
+cat MIGRATION_COMPLETE.md
+```
+
+**回滚方案**:
+- 无需回滚
+
+**输出文件**:
+```markdown
+# MIGRATION_COMPLETE.md
+
+## 迁移状态: ✅ 成功
+
+### 完成的任务
+- [x] 环境准备 (3/3)
+- [x] 创建 Monorepo (5/5)
+- [x] 迁移核心包 (8/8)
+- [x] 配置构建系统 (6/6)
+- [x] 配置自动同步 (5/5)
+- [x] 测试与验证 (6/6)
+
+### 迁移统计
+- 迁移的包: 7个
+- 保持独立: 4个 (koatty_container, koatty_lib, koatty_loader, koatty_logger)
+- 构建状态: ✅ 成功
+- 测试状态: ✅ 通过
+- Turborepo 缓存: ✅ 工作正常
+
+### 下一步行动
+1. [ ] 提交初始 commit
+2. [ ] 推送到 GitHub
+3. [ ] 配置 SYNC_TOKEN secret
+4. [ ] 测试 GitHub Actions
+5. [ ] 更新文档
+6. [ ] 通知团队
+
+### 验证命令
+\```bash
+# 开发
+pnpm dev
+
+# 构建
+pnpm build
+
+# 测试
+pnpm test
+
+# 同步
+./scripts/sync-to-repos.sh
+\```
+
+### 相关文档
+- [docs/README_MONOREPO.md](docs/README_MONOREPO.md)
+- [docs/MONOREPO_ARCHITECTURE.md](docs/MONOREPO_ARCHITECTURE.md)
+- [docs/MONOREPO_SYNC_STRATEGY.md](docs/MONOREPO_SYNC_STRATEGY.md)
+```
+
+---
+
+## 附录
+
+### A. 任务执行规范
+
+1. **顺序执行**: 必须按照 TASK-X.Y 的顺序执行
+2. **验收确认**: 每个任务完成后必须通过所有验收标准
+3. **测试命令**: 必须运行测试命令验证结果
+4. **报告输出**: 重要任务需要生成报告文件
+5. **回滚能力**: 如果任务失败，使用回滚方案恢复
+
+### B. 常用命令
+
+```bash
+# 查看当前状态
+git status
+pnpm list --depth=1
+
+# 清理
+pnpm clean
+rm -rf node_modules pnpm-lock.yaml
+
+# 重新安装
+pnpm install
+
+# 构建
+pnpm build
+
+# 测试
+pnpm test
+```
+
+### C. 报告文件清单
+
+- `reports/node-version.txt` - Node.js 版本
+- `reports/pnpm-version.txt` - pnpm 版本
+- `reports/backup-branch.txt` - 备份分支名
+- `reports/directory-structure.txt` - 目录结构
+- `reports/git-remotes.txt` - Git remotes
+- `reports/migration-summary.txt` - 迁移摘要
+- `reports/dependencies.txt` - 依赖关系
+- `reports/dependency-tree.txt` - 依赖树
+- `reports/build-result.txt` - 构建结果
+- `reports/test-result.txt` - 测试结果
+- `reports/cache-validation.txt` - 缓存验证
+- `reports/workspace-validation.txt` - Workspace 验证
+
+### D. 检查清单
+
+完成所有任务后，确认：
+
+- [ ] 所有33个任务都已完成
+- [ ] 所有验收标准都通过
+- [ ] 所有测试命令都成功
+- [ ] reports/ 目录包含所有报告
+- [ ] MIGRATION_COMPLETE.md 已生成
+- [ ] 可以运行 pnpm build 和 pnpm test
+- [ ] workspace 协议正常工作
+- [ ] Turborepo 缓存正常工作
+
+---
+
+**任务清单版本**: 1.0  
+**创建日期**: 2025-10-22  
+**预计执行时间**: 5-7天  
+**目标**: 完成 Koatty Monorepo 迁移
+