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

测试命令:

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

测试命令:

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

测试命令:

git branch --list 'backup-before-monorepo-*'
cat reports/backup-branch.txt

回滚方案:

# 恢复到备份分支
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 文件已创建

测试命令:

cd koatty-monorepo
git status
ls -la .gitignore

回滚方案:

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

测试命令:

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

回滚方案:

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

测试命令:

cat package.json | jq '.name, .private, .packageManager'

回滚方案:

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/*'

测试命令:

cat pnpm-workspace.yaml

回滚方案:

rm pnpm-workspace.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
• 启用了缓存

测试命令:

cat turbo.json
pnpm list turbo

回滚方案:

rm turbo.json
pnpm remove turbo

输出文件:

{
  "$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

测试命令:

git remote -v > reports/git-remotes.txt
cat reports/git-remotes.txt

回滚方案:

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 目录

测试命令:

ls packages/koatty-config/
cat packages/koatty-config/package.json | jq '.name, .version'
test ! -d packages/koatty-config/.git && echo "No .git directory"

回滚方案:

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/ 目录存在

测试命令:

cat packages/koatty-exception/package.json | jq '.name, .version'

回滚方案:

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 正确

测试命令:

cat packages/koatty-trace/package.json | jq '.name'

回滚方案:

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 正确

测试命令:

cat packages/koatty-core/package.json | jq '.name'

回滚方案:

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 正确

测试命令:

cat packages/koatty-router/package.json | jq '.name'

回滚方案:

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 正确

测试命令:

cat packages/koatty-serve/package.json | jq '.name'

回滚方案:

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

测试命令:

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

回滚方案:

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 版本

测试命令:

cat packages/koatty-config/package.json | jq '.dependencies'

回滚方案:

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 版本

验收标准:

• 依赖正确更新

测试命令:

cat packages/koatty-exception/package.json | jq '.dependencies'

回滚方案:

git checkout packages/koatty-exception/package.json

---

TASK-3.3: 更新 workspace 依赖 - koatty_trace

目标: 更新 koatty_trace 的依赖

前置条件:

• TASK-3.2 完成

执行步骤:

1. 更新依赖为 workspace:*

验收标准:

• 依赖正确更新

测试命令:

cat packages/koatty-trace/package.json | jq '.dependencies'

回滚方案:

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

测试命令:

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

回滚方案:

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 协议

测试命令:

cat packages/koatty/package.json | jq '.dependencies'

回滚方案:

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

测试命令:

pnpm install
pnpm list --depth=1 > reports/dependency-tree.txt
cat reports/dependency-tree.txt

回滚方案:

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 语法正确

测试命令:

ls -la scripts/sync-to-repos.sh
bash -n scripts/sync-to-repos.sh

回滚方案:

rm scripts/sync-to-repos.sh

输出文件: 参考 MONOREPO_SYNC_STRATEGY.md 中的同步脚本

---

TASK-4.2: 创建同步状态检查脚本

目标: 创建 scripts/check-sync-status.sh

前置条件:

• TASK-4.1 完成

执行步骤:

1. 创建检查脚本
2. 添加执行权限

验收标准:

• 脚本存在且可执行
• 语法正确

测试命令:

bash -n scripts/check-sync-status.sh

回滚方案:

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个包的同步配置

测试命令:

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"

回滚方案:

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 文件存在
• 配置正确

测试命令:

ls -la .github/workflows/sync-from-independent-repos.yml

回滚方案:

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

测试命令:

ls -la .changeset/
cat .changeset/config.json
cat package.json | jq '.scripts | with_entries(select(.key | contains("changeset")))'

回滚方案:

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

测试命令:

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

回滚方案:

pnpm clean

---

TASK-5.2: 运行所有测试

目标: 验证所有测试通过

前置条件:

• TASK-5.1 完成

执行步骤:

1. 运行 pnpm test
2. 收集测试结果
3. 生成覆盖率报告（如果有）

验收标准:

• 所有测试通过
• 测试报告输出到 reports/test-result.txt

测试命令:

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

测试命令:

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

回滚方案:

rm -rf .turbo

---

TASK-5.4: 验证 workspace 协议

目标: 确认 workspace:* 正确工作

前置条件:

• TASK-5.3 完成

执行步骤:

1. 检查 node_modules 中的软链接
2. 修改一个包的代码
3. 验证其他包能立即使用
4. 生成 workspace 验证报告

验收标准:

• workspace 包是软链接
• 修改即时生效
• 验证报告: reports/workspace-validation.txt

测试命令:

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 包
• 可以构建和运行

测试命令:

cd apps/demo
pnpm install
pnpm build

回滚方案:

rm -rf apps/demo

---

TASK-5.6: 生成最终报告

目标: 生成完整的迁移验证报告

前置条件:

• TASK-5.5 完成

执行步骤:

1. 汇总所有 reports/ 中的文件
2. 生成迁移检查清单
3. 生成下一步建议
4. 创建 MIGRATION_COMPLETE.md

验收标准:

• reports/ 包含所有阶段的报告
• MIGRATION_COMPLETE.md 存在
• 包含成功/失败统计
• 包含下一步行动建议

测试命令:

ls -la reports/
cat MIGRATION_COMPLETE.md

回滚方案:

• 无需回滚

输出文件:

# 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. 常用命令

# 查看当前状态
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 迁移