# 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)