✨ feat: 完成文档拆分

2025-12-13 22:22:01 +08:00
parent f535707657
commit 4cacd128ab
16 changed files with 3983 additions and 0 deletions
--- a/aide-program/docs/commands/env.md
+++ b/aide-program/docs/commands/env.md
@@ -0,0 +1,257 @@
+# aide env 子命令设计文档
+
+## 一、背景
+
+### 1.1 解决的问题
+
+| 问题 | 影响 |
+|------|------|
+| 环境不一致 | 命令执行失败，打断业务流程 |
+| 手动检查繁琐 | 每次都要检查 Python、虚拟环境、依赖 |
+| 修复方式不统一 | 不同人有不同的修复习惯 |
+
+### 1.2 设计目标
+
+提供**统一的环境检测与修复**：
+- 自动检测环境问题
+- 能修复的自动修复
+- 不能修复的给出明确建议
+
+---
+
+## 二、职责
+
+### 2.1 做什么
+
+1. 检测 Python 版本是否满足要求
+2. 检测 uv 是否可用
+3. 检测/创建虚拟环境
+4. 安装依赖
+5. 输出项目配置信息
+
+### 2.2 不做什么
+
+- 不修改业务代码
+- 不执行业务逻辑
+- 不进行流程追踪
+
+---
+
+## 三、接口规格
+
+### 3.1 命令语法
+
+```
+aide env ensure [--runtime]
+```
+
+### 3.2 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `--runtime` | 可选 | 仅检查 aide 运行时环境，不依赖配置文件 |
+
+### 3.3 输出
+
+**成功（runtime 模式）**：
+```
+✓ 运行时环境就绪 (python:3.12, uv:0.4.0)
+```
+
+**成功（完整模式）**：
+```
+→ 任务原文档: task-now.md
+→ 任务细则文档: task-spec.md
+✓ 环境就绪 (python:3.12, uv:0.4.0, venv:.venv)
+```
+
+**自动修复**：
+```
+→ 创建虚拟环境: .venv
+✓ 已创建虚拟环境
+⚠ 未找到 requirements.txt，已创建空文件
+→ 安装依赖（uv pip install -r requirements.txt）
+✓ 环境就绪 (python:3.12, uv:0.4.0, venv:.venv)
+```
+
+**失败**：
+```
+✗ Python 版本不足，要求>=3.11，当前 3.9
+```
+
+```
+✗ 未检测到 uv，请先安装（FileNotFoundError）
+```
+
+---
+
+## 四、业务流程
+
+```
+@startuml
+skinparam defaultFontName "PingFang SC"
+
+start
+
+if (--runtime 参数?) then (是)
+  :required_py = "3.11" (硬编码);
+else (否)
+  :从配置文件读取 required_py;
+endif
+
+:检查 Python 版本;
+if (版本满足?) then (是)
+else (否)
+  :输出错误信息;
+  stop
+endif
+
+:检查 uv 可用性;
+if (uv 可用?) then (是)
+else (否)
+  :输出错误信息;
+  stop
+endif
+
+if (--runtime 参数?) then (是)
+  :输出运行时环境就绪;
+  stop
+endif
+
+:读取配置文件;
+:确保 .gitignore 包含 .aide/;
+
+:读取 venv 路径配置;
+if (虚拟环境存在?) then (是)
+else (否)
+  :使用 uv venv 创建;
+  if (创建成功?) then (是)
+  else (否)
+    :输出错误信息;
+    stop
+  endif
+endif
+
+:读取 requirements 路径配置;
+if (requirements.txt 存在?) then (是)
+else (否)
+  :创建空文件;
+  :输出警告;
+endif
+
+:使用 uv pip install 安装依赖;
+if (安装成功?) then (是)
+else (否)
+  :输出错误信息;
+  stop
+endif
+
+:输出任务文档路径配置;
+:输出环境就绪;
+
+stop
+@enduml
+```
+
+---
+
+## 五、数据结构
+
+### 5.1 配置依赖
+
+从 `.aide/config.toml` 读取：
+
+```
+[runtime]
+python_min     # Python 最低版本要求
+
+[env]
+venv           # 虚拟环境路径
+requirements   # 依赖文件路径
+
+[task]
+source         # 任务原文档路径
+spec           # 任务细则文档路径
+```
+
+### 5.2 方法签名原型
+
+```
+class EnvManager:
+    root: Path              # 项目根目录
+
+    ensure(runtime_only: bool, cfg: ConfigManager) -> bool
+        # 主入口，返回是否成功
+
+    _get_required_python(cfg: ConfigManager, runtime_only: bool) -> str
+        # 获取 Python 版本要求
+
+    _parse_version(version: str) -> tuple[int, ...]
+        # 解析版本号字符串
+
+    _check_python_version(required: str) -> bool
+        # 检查 Python 版本
+
+    _check_uv() -> str | None
+        # 检查 uv，返回版本号或 None
+
+    _ensure_venv(venv_path: Path) -> bool
+        # 确保虚拟环境存在
+
+    _ensure_requirements_file(req_path: Path) -> None
+        # 确保 requirements.txt 存在
+
+    _install_requirements(venv_path: Path, req_path: Path) -> bool
+        # 安装依赖
+```
+
+---
+
+## 六、依赖
+
+| 依赖项 | 类型 | 说明 |
+|--------|------|------|
+| ConfigManager | 内部模块 | 配置读写 |
+| output | 内部模块 | 输出格式化 |
+| uv | 外部工具 | 虚拟环境和依赖管理 |
+
+---
+
+## 七、被依赖
+
+| 依赖方 | 说明 |
+|--------|------|
+| /aide:init | 调用 env ensure --runtime 和 env ensure |
+| aide init | 内部可能调用 env 检查 |
+
+---
+
+## 八、修改指南
+
+### 8.1 修改检测逻辑
+
+1. 更新本文档的业务流程图
+2. 修改 `aide/env/ensure.py`
+3. 如有新的输出，更新输出示例
+
+### 8.2 添加新的检测项
+
+1. 在本文档添加检测项说明
+2. 在 `EnvManager` 添加对应方法
+3. 在 `ensure()` 中调用
+4. 更新 [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)
+
+### 8.3 修改配置依赖
+
+1. 更新本文档的"配置依赖"章节
+2. 修改代码实现
+3. 同步更新 [配置格式文档](../formats/config.md)
+
+---
+
+## 九、相关文档
+
+- [program 导览](../README.md)
+- [配置格式文档](../formats/config.md)
+- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)
+- [/aide:init 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/init.md)