# 实现计划: Mono-Kickstart

## 概述

本实现计划将 Mono-Kickstart CLI 工具分解为一系列增量开发任务。每个任务都建立在前面的任务之上，确保代码逐步集成，没有孤立或未使用的代码。实现将使用 Python 3.11+、argparse 标准库和 uv 包管理器。

**当前进度**：已完成平台检测器、配置管理器及其测试，CLI 基础框架已实现但需要从 Typer 迁移到 argparse。

## 任务

- [x] 1. 项目初始化和基础设施
  - 创建项目目录结构
  - 配置 `pyproject.toml`，定义项目元数据、依赖和命令入口点（`mk` 和 `mono-kickstart`）
  - 设置 uv 包管理器
  - 创建基础的 README.md 和 .gitignore
  - 初始化 Git 仓库
  - _需求: 10.1, 10.4, 10.8_

- [x] 2. 平台检测模块
  - [x] 2.1 实现平台检测器（`platform_detector.py`）
    - 实现 OS 检测（macOS、Linux、不支持）
    - 实现架构检测（ARM64、x86_64、不支持）
    - 实现 Shell 检测（Bash、Zsh、Fish）
    - 实现 Shell 配置文件路径获取
    - 实现平台支持性检查
    - _需求: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6_
  
  - [x] 2.2 编写平台检测器的属性测试
    - **属性 3: 平台特定安装包选择**
    - **验证需求: 1.5, 9.1, 9.2, 9.3**
  
  - [x] 2.3 编写平台检测器的单元测试
    - 测试各平台的正确检测
    - 测试不支持平台的错误处理
    - 测试 Shell 类型检测
    - _需求: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6_

- [x] 3. 配置管理模块
  - [x] 3.1 实现配置数据模型（`config.py`）
    - 定义 `ToolConfig`、`RegistryConfig`、`ProjectConfig`、`Config` 数据类
    - 实现配置的序列化和反序列化
    - _需求: 4.1_
  
  - [x] 3.2 实现配置管理器（`config.py`）
    - 实现从 YAML 文件加载配置
    - 实现配置合并逻辑（支持多源优先级）
    - 实现配置验证
    - 实现配置保存到文件
    - 实现默认配置生成
    - _需求: 4.1, 4.2, 4.3, 4.4, 4.5, 4.9_
  
  - [x] 3.3 编写配置管理器的属性测试
    - **属性 7: 配置优先级合并**
    - **验证需求: 4.1, 4.9**
    - **属性 8: 配置文件格式验证**
    - **验证需求: 4.4**
    - **属性 9: 配置往返一致性**
    - **验证需求: 4.5, 11.8**
  
  - [x] 3.4 编写配置管理器的单元测试
    - 测试配置文件加载（存在、不存在、格式错误）
    - 测试配置合并的各种场景
    - 测试配置验证（有效、无效）
    - 测试配置保存
    - _需求: 4.1, 4.2, 4.3, 4.4, 4.5, 4.9_

- [x] 4. 检查点 - 确保所有测试通过
  - 确保所有测试通过，如有问题请询问用户

- [x] 5. CLI 框架迁移（从 Typer 到 argparse）
  - [x] 5.1 重构 CLI 入口模块（`cli.py`）
    - 移除 Typer 依赖，使用 argparse 替代
    - 实现主解析器和子命令解析器
    - 实现 `init` 子命令（支持 --config、--save-config、--interactive、--force、--dry-run 参数）
    - 实现 `upgrade` 子命令（支持工具名称参数、--all、--dry-run 参数）
    - 实现 `install` 子命令（支持工具名称参数、--all、--dry-run 参数）
    - 实现 `--version` 和 `--help` 参数
    - 保留中文帮助信息
    - _需求: 8.1, 8.2, 8.3, 8.4, 10.1, 10.7_
  
  - [x] 5.2 实现 Shell 补全脚本生成
    - 实现 `setup-shell` 子命令（替代 Typer 的 --install-completion）
    - 生成 Bash 补全脚本
    - 生成 Zsh 补全脚本
    - 生成 Fish 补全脚本
    - 自动检测当前 Shell 并安装补全脚本
    - 配置 PATH 环境变量
    - _需求: 7.1, 7.2, 7.3, 7.8_
  
  - [x] 5.3 编写 CLI 框架的单元测试
    - 测试参数解析（init、upgrade、install 命令）
    - 测试帮助信息显示
    - 测试版本信息显示
    - 测试补全脚本生成
    - _需求: 8.1, 8.2, 8.3, 8.4, 7.1, 7.2, 7.3_

- [x] 6. 工具检测模块
  - [x] 6.1 实现工具检测器（`tool_detector.py`）
    - 实现命令可用性检查
    - 实现版本号获取
    - 实现各工具的检测方法（NVM、Node.js、Conda、Bun、uv、Claude Code、Codex、Spec Kit、BMad）
    - 实现批量检测方法
    - _需求: 1.2, 6.2_
  
  - [x] 6.2 编写工具检测器的单元测试
    - 测试命令可用性检查
    - 测试版本号解析
    - 测试各工具的检测逻辑
    - 使用 Mock 模拟命令执行
    - _需求: 1.2_

- [x] 7. 工具安装器基类和通用功能
  - [x] 7.1 实现工具安装器基类（`installer_base.py`）
    - 定义 `InstallResult` 枚举和 `InstallReport` 数据类
    - 实现 `ToolInstaller` 抽象基类
    - 实现通用的命令执行方法（支持重试）
    - 实现文件下载方法（支持重试）
    - _需求: 1.12, 6.3_
  
  - [x] 7.2 编写安装器基类的单元测试
    - 测试命令执行（成功、失败、重试）
    - 测试文件下载（成功、失败、重试）
    - 测试网络错误处理
    - _需求: 1.12_

- [x] 8. 具体工具安装器实现（第一批）
  - [x] 8.1 实现 NVM 安装器（`installers/nvm_installer.py`）
    - 实现安装逻辑（下载并执行安装脚本）
    - 实现环境变量写入 Shell 配置文件
    - 实现安装验证
    - 实现升级逻辑
    - _需求: 1.3, 5.5_
  
  - [x] 8.2 实现 Node.js 安装器（`installers/node_installer.py`）
    - 实现通过 NVM 安装 Node.js LTS
    - 实现设置默认版本
    - 实现安装验证
    - 实现升级逻辑
    - _需求: 1.4, 5.6_
  
  - [x] 8.3 实现 Conda 安装器（`installers/conda_installer.py`）
    - 实现根据平台选择安装包 URL
    - 实现下载和执行安装脚本
    - 实现安装验证
    - 实现升级逻辑（覆盖安装）
    - _需求: 1.5, 5.7_
  
  - [x] 8.4 编写第一批安装器的单元测试
    - 测试 NVM 安装器的各种场景
    - 测试 Node.js 安装器的各种场景
    - 测试 Conda 安装器的平台特定逻辑
    - 使用 Mock 模拟命令执行和文件操作
    - _需求: 1.3, 1.4, 1.5_

- [x] 9. 具体工具安装器实现（第二批）
  - [x] 9.1 实现 Bun 安装器（`installers/bun_installer.py`）
    - 实现安装逻辑（执行官方安装脚本）
    - 实现安装验证
    - 实现升级逻辑
    - _需求: 1.6, 5.8_
  
  - [x] 9.2 实现 uv 安装器（`installers/uv_installer.py`）
    - 实现安装逻辑（执行官方安装脚本）
    - 实现安装验证
    - 实现升级逻辑
    - _需求: 1.7, 5.9_
  
  - [x] 9.3 实现 Claude Code CLI 安装器（`installers/claude_installer.py`）
    - 实现原生二进制安装
    - 实现 `claude doctor` 验证
    - 实现升级逻辑
    - _需求: 1.8, 5.10_
  
  - [x] 9.4 实现 Codex CLI 安装器（`installers/codex_installer.py`）
    - 实现安装方式选择逻辑（Bun 优先，否则 npm）
    - 实现安装验证
    - 实现升级逻辑
    - _需求: 1.9, 5.11_
  
  - [x] 9.5 编写第二批安装器的属性测试
    - **属性 4: 条件安装方式选择**
    - **验证需求: 1.9**
  
  - [x] 9.6 编写第二批安装器的单元测试
    - 测试 Bun、uv、Claude Code、Codex 安装器
    - 测试 Codex 的安装方式选择逻辑
    - _需求: 1.6, 1.7, 1.8, 1.9_

- [x] 10. 具体工具安装器实现（第三批）
  - [x] 10.1 实现 Spec Kit 安装器（`installers/spec_kit_installer.py`）
    - 实现通过 uv tool install 从 GitHub 安装
    - 实现安装验证
    - 实现升级逻辑
    - _需求: 1.10, 5.12_
  
  - [x] 10.2 实现 BMad Method 安装器（`installers/bmad_installer.py`）
    - 实现通过 npx/bunx 交互式安装
    - 实现安装验证
    - 实现升级逻辑
    - _需求: 1.11_
  
  - [x] 10.3 编写第三批安装器的单元测试
    - 测试 Spec Kit 和 BMad Method 安装器
    - _需求: 1.10, 1.11_

- [x] 11. 检查点 - 确保所有测试通过
  - 确保所有测试通过，如有问题请询问用户

- [x] 12. 镜像源配置模块
  - [x] 12.1 实现镜像源配置器（`mirror_config.py`）
    - 实现 npm 镜像源配置
    - 实现 Bun 镜像源配置（创建 ~/.bunfig.toml）
    - 实现 uv 镜像源配置（创建 ~/.config/uv/uv.toml，包含 PyPI 镜像和 CPython 代理）
    - 实现镜像源验证方法
    - _需求: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7_
  
  - [x] 12.2 编写镜像源配置器的单元测试
    - 测试 npm 镜像配置和验证
    - 测试 Bun 镜像配置和验证
    - 测试 uv 镜像配置和验证
    - 测试配置文件格式（uv 的 python-install-mirror 在 [[index]] 之前）
    - _需求: 2.1, 2.2, 2.3, 2.4, 2.7_

- [x] 13. 项目创建模块
  - [x] 13.1 实现项目创建器（`project_creator.py`）
    - 实现目录结构创建（apps/、packages/、shared/）
    - 实现 workspace 配置文件生成（package.json、pnpm-workspace.yaml）
    - 实现 .gitignore 文件生成
    - 实现 README.md 文件生成
    - 实现 Git 仓库初始化
    - 实现已存在目录的处理逻辑
    - _需求: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6_
  
  - [x] 13.2 编写项目创建器的属性测试
    - **属性 14: 项目目录结构一致性**
    - **验证需求: 3.1**
  
  - [x] 13.3 编写项目创建器的单元测试
    - 测试目录和文件创建
    - 测试 Git 初始化
    - 测试已存在目录的处理
    - _需求: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6_

- [x] 14. 安装编排器
  - [x] 14.1 实现安装编排器（`orchestrator.py`）
    - 实现工具安装顺序确定（基于依赖关系）
    - 实现单个工具安装逻辑（检测、跳过或安装）
    - 实现批量工具安装逻辑（按顺序，容错）
    - 实现镜像源配置调用
    - 实现项目创建调用
    - 实现安装摘要生成和打印
    - 实现升级流程（全部或单个工具）
    - _需求: 1.1, 1.2, 1.12, 1.13, 5.1, 5.2, 5.4, 5.13, 5.14, 6.3, 6.7_
  
  - [x] 14.2 编写安装编排器的属性测试
    - **属性 1: 工具安装顺序一致性**
    - **验证需求: 1.1**
    - **属性 2: 幂等性**
    - **验证需求: 1.2, 6.1, 6.2**
    - **属性 5: 容错性**
    - **验证需求: 1.12, 5.13, 6.3**
    - **属性 6: 安装摘要完整性**
    - **验证需求: 1.13, 5.14**
    - **属性 10: 工具启用配置生效**
    - **验证需求: 4.6**
    - **属性 11: 单工具升级隔离性**
    - **验证需求: 5.4**
    - **属性 12: 错误信息完整性**
    - **验证需求: 6.5**
  
  - [x] 14.3 编写安装编排器的单元测试
    - 测试工具安装顺序
    - 测试幂等性（重复执行）
    - 测试容错性（部分失败）
    - 测试安装摘要生成
    - 测试升级流程
    - _需求: 1.1, 1.2, 1.12, 1.13, 5.4, 6.1, 6.2, 6.3_

- [x] 15. 检查点 - 确保所有测试通过
  - 确保所有测试通过，如有问题请询问用户

- [x] 16. CLI 集成和错误处理
  - [x] 16.1 集成所有模块到 CLI 入口
    - 在 init 命令中集成平台检测、配置管理、安装编排器
    - 在 upgrade 命令中集成工具检测和升级逻辑
    - 在 install 命令中集成工具检测和安装逻辑
    - 实现错误处理和日志记录
    - _需求: 8.1, 8.2, 8.3, 8.4, 10.1, 10.7_
  
  - [x] 16.2 配置 pyproject.toml 的命令入口点
    - 在 `[project.scripts]` 中注册 `mk` 和 `mono-kickstart` 两个入口
    - 移除 Typer 依赖
    - _需求: 10.1, 10.4, 10.8_
  
  - [x] 16.3 编写 CLI 集成的属性测试
    - **属性 13: 命令入口等价性**
    - **验证需求: 7.8, 10.8**
  
  - [x] 16.4 编写 CLI 集成的单元测试
    - 测试 init 命令的完整流程
    - 测试 upgrade 命令的完整流程
    - 测试 install 命令的完整流程
    - 测试错误处理（平台不支持、Python 版本不满足）
    - _需求: 8.1, 8.2, 8.3, 8.4, 9.4, 10.7_

- [~] 17. 交互式配置模块（可选功能）
  - [x] 17.1 实现交互式配置器（`interactive.py`）
    - 使用 questionary 库实现交互式问答
    - 实现项目名称询问
    - 实现工具选择询问（多选）
    - 实现 Node.js 版本询问
    - 实现 Python 版本询问
    - 实现镜像源询问
    - 实现配置摘要确认
    - _需求: 11.1, 11.2, 11.3, 11.4, 11.5, 11.6, 11.7, 11.9_
  
  - [x] 17.2 集成交互式配置到 init 命令
    - 在 init 命令中添加 --interactive 参数处理
    - 集成交互式配置器
    - 实现配置保存（--save-config）
    - _需求: 11.1, 11.8_
  
  - [x] 17.3 编写交互式配置器的单元测试
    - 测试各个问答步骤
    - 测试配置摘要生成
    - 测试默认值加载
    - 使用 Mock 模拟用户输入
    - _需求: 11.1, 11.2, 11.3, 11.4, 11.5, 11.6, 11.7, 11.9_

- [~] 18. 日志和错误处理完善
  - [x] 18.1 实现日志记录模块（`logger.py`）
    - 配置日志格式和级别
    - 实现控制台彩色输出
    - 实现日志文件写入（~/.mono-kickstart/logs/）
    - 实现敏感信息过滤
    - _需求: 6.5, 6.6, 6.7, 8.6, 8.7, 8.8, 8.9_
  
  - [x] 18.2 完善错误处理
    - 实现各类错误的统一处理
    - 实现错误恢复建议生成
    - 实现退出码管理
    - _需求: 6.5, 6.6, 9.4, 10.7_
  
  - [x] 18.3 编写日志和错误处理的单元测试
    - 测试日志记录
    - 测试错误处理
    - 测试退出码
    - _需求: 6.5, 6.6_

- [x] 19. 检查点 - 确保所有测试通过
  - 确保所有测试通过，如有问题请询问用户

- [~] 20. 集成测试
  - [x] 20.1 编写完整初始化流程的集成测试
    - 测试完整的 init 命令执行
    - 测试工具安装流程
    - 测试镜像源配置
    - 测试项目创建
    - 使用 Mock 模拟外部依赖
    - _需求: 1.1, 1.2, 1.13, 2.7, 3.1_
  
  - [x] 20.2 编写完整升级流程的集成测试
    - 测试完整的 upgrade 命令执行
    - 测试全部工具升级
    - 测试单个工具升级
    - _需求: 5.1, 5.2, 5.3, 5.4_
  
  - [x] 20.3 编写配置文件加载的集成测试
    - 测试多源配置加载和合并
    - 测试配置保存和重新加载
    - _需求: 4.1, 4.2, 4.5_

- [~] 21. 文档和打包
  - [x] 21.1 完善 README.md
    - 添加安装说明
    - 添加使用示例
    - 添加配置文件说明
    - 添加常见问题解答
  
  - [x] 21.2 创建 CHANGELOG.md
    - 记录版本历史和变更
  
  - [x] 21.3 配置 GitHub Actions CI/CD
    - 配置测试工作流（多 Python 版本、多平台）
    - 配置覆盖率报告
    - 配置 PyPI 发布工作流
  
  - [x] 21.4 验证打包和安装
    - 使用 uv 构建包
    - 测试 `uv tool install` 安装
    - 测试 `pip install` 安装
    - 测试 `uvx` 一次性执行
    - 验证 `mk` 和 `mono-kickstart` 命令可用
    - _需求: 10.1, 10.2, 10.3, 10.4, 10.5, 10.6_

- [x] 22. 最终检查点 - 完整验证
  - 确保所有测试通过，如有问题请询问用户
  - 验证代码覆盖率达到目标（>80%）
  - 验证所有需求都有对应的实现和测试

## 注意事项

- 标记 `*` 的任务为可选任务，可以跳过以加快 MVP 开发
- 每个任务都引用了具体的需求编号，确保可追溯性
- 检查点任务确保增量验证，及早发现问题
- 属性测试验证通用正确性属性
- 单元测试验证具体示例和边缘情况
- 集成测试验证端到端流程
- **CLI 框架已从 Typer 迁移到 argparse**，保留所有现有功能（init、upgrade、install 命令，Shell 补全等）

## 迁移说明

### Typer → argparse 迁移要点

1. **参数解析**：
   - Typer 的 `@app.command()` → argparse 的 `subparsers.add_parser()`
   - Typer 的 `typer.Option()` → argparse 的 `add_argument()`
   - Typer 的 `typer.Argument()` → argparse 的 `add_argument()` (positional)

2. **Shell 补全**：
   - Typer 的 `--install-completion` → 自定义 `setup-shell` 子命令
   - 手动生成 Bash/Zsh/Fish 补全脚本
   - 保留现有的补全脚本内容

3. **帮助信息**：
   - 保留中文帮助信息
   - 使用 argparse 的 `formatter_class` 自定义格式

4. **版本信息**：
   - Typer 的 `--version` callback → argparse 的 `action='version'`

5. **依赖移除**：
   - 从 `pyproject.toml` 移除 `typer` 依赖
   - 移除 `click` 依赖（Typer 的底层依赖）
   - 保留其他依赖（pyyaml、hypothesis 等）
