agent-aide/aide-program/docs/commands/env.md

# aide env 子命令设计文档

## 一、背景

### 1.1 解决的问题

| 问题 | 影响 |
|------|------|
| 环境不一致 | 命令执行失败，打断业务流程 |
| 手动检查繁琐 | 每次都要检查 Python、虚拟环境、依赖 |
| 修复方式不统一 | 不同人有不同的修复习惯 |
| 检测项不可扩展 | 无法按需添加新的环境检测 |

### 1.2 设计目标

提供**模块化、可配置的环境检测与修复**：
- 模块化检测项，支持扩展
- 可配置启用哪些模块
- 能修复的自动修复
- 不能修复的给出明确建议
- 详细模式供人工确认

---

## 二、命令结构

```
aide env                         # 等同于 aide env ensure
aide env ensure [options]        # 检测并修复
aide env list                    # 列出所有可用模块
```

### 2.1 aide env ensure

检测环境并尝试修复问题。

**参数：**

| 参数 | 说明 |
|------|------|
| `--runtime` | 仅检测 aide 运行时环境（python + uv） |
| `--modules M1,M2` | 指定要检测的模块（逗号分隔） |
| `--all` | 检测所有已启用模块，仅检查不修复 |
| `-v, --verbose` | 显示详细配置信息 |

### 2.2 aide env list

列出所有可用的环境检测模块及其状态。

---

## 三、模块系统

### 3.1 模块分类

**类型A：自包含模块（无需配置即可检测）**

| 模块 | 描述 | 能力 |
|------|------|------|
| `python` | Python 解释器版本 | check |
| `uv` | uv 包管理器 | check |

**类型B：路径依赖模块（必须有配置才能检测）**

| 模块 | 描述 | 能力 | 必需配置 |
|------|------|------|----------|
| `venv` | Python 虚拟环境 | check, ensure | `path` |
| `requirements` | Python 依赖管理 | check, ensure | `path` |

### 3.2 模块能力

- `check`：检测环境是否可用
- `ensure`：检测失败时尝试自动修复

---

## 四、配置

### 4.1 配置结构

```toml
[env]
# 启用的模块列表
modules = ["python", "uv", "venv", "requirements"]

# 类型A模块配置（可选）
[env.python]
min_version = "3.11"

# 类型B模块配置（必需）
[env.venv]
path = ".venv"

[env.requirements]
path = "requirements.txt"
```

### 4.2 配置兼容性

支持旧格式配置：

```toml
[env]
venv = ".venv"
requirements = "requirements.txt"
```

读取时自动转换为新格式。

---

## 五、执行逻辑

### 5.1 输出级别规则

| 场景 | 在启用列表 | 有配置 | 结果 | 输出 | 行为 |
|------|-----------|--------|------|------|------|
| ensure | ✓ | ✓/NA | 成功 | ✓ | 继续 |
| ensure | ✓ | ✓/NA | 失败+可修复 | → | 修复 |
| ensure | ✓ | ✓/NA | 失败+不可修复 | ✗ | **停止** |
| ensure | ✓ | ✗(B类) | - | ✗ | **停止** |
| --modules | ✗ | ✓/NA | 成功 | ✓ | 继续 |
| --modules | ✗ | ✓/NA | 失败 | ⚠ | 继续 |
| --modules | ✗ | ✗(B类) | - | ⚠ | 跳过 |
| --all | any | any | any | ✓/⚠ | 仅检测 |

**核心原则：**
- 启用模块失败 = 错误(✗) = 必须解决
- 未启用模块失败 = 警告(⚠) = 可忽略
- 启用的B类模块无配置 = 错误(✗) = 配置错误

### 5.2 业务流程

```
@startuml
skinparam defaultFontName "PingFang SC"

start

:读取配置;
:获取启用模块列表;

if (--runtime?) then (是)
  :target = [python, uv];
else if (--modules?) then (是)
  :target = 指定模块;
else if (--all?) then (是)
  :target = 启用模块;
  :check_only = true;
else (否)
  :target = 启用模块;
endif

if (verbose?) then (是)
  :输出详细头部信息;
endif

:遍历 target 模块;

repeat
  :获取模块实例;
  :获取模块配置;

  if (verbose?) then (是)
    :输出模块配置详情;
  endif

  if (B类模块 && 无配置?) then (是)
    if (在启用列表?) then (是)
      :输出错误;
      stop
    else (否)
      :输出警告，跳过;
    endif
  endif

  :执行 check();

  if (成功?) then (是)
    :输出成功;
  else (否)
    if (check_only?) then (是)
      :输出警告;
    else if (可修复?) then (是)
      :执行 ensure();
      if (修复成功?) then (是)
        :输出成功;
      else (否)
        if (在启用列表?) then (是)
          :输出错误;
          stop
        else (否)
          :输出警告;
        endif
      endif
    else (否)
      if (在启用列表?) then (是)
        :输出错误;
        stop
      else (否)
        :输出警告;
      endif
    endif
  endif

repeat while (还有模块?)

:输出环境就绪;

stop
@enduml
```

---

## 六、输出示例

### 6.1 aide env list

```
可用模块:
  模块          描述                    能力               需要配置
  ────────────────────────────────────────────────────────────
  python       Python 解释器版本         check            否
  uv           uv 包管理器              check            否
  venv         Python 虚拟环境          check, ensure    是 [path]
  requirements Python 依赖管理          check, ensure    是 [path]

当前启用: python, uv, venv, requirements
```

### 6.2 aide env ensure

**成功：**
```
✓ python: 3.14.2 (>=3.11)
✓ uv: uv 0.9.16
✓ venv: .venv
✓ requirements: requirements.txt
✓ 环境就绪 (python:3.14.2, uv:uv 0.9.16, venv:.venv, requirements:requirements.txt)
```

**需修复：**
```
✓ python: 3.14.2 (>=3.11)
✓ uv: uv 0.9.16
→ venv: 虚拟环境不存在: .venv，尝试修复...
✓ venv: 已创建
✓ requirements: requirements.txt
✓ 环境就绪 (...)
```

**启用模块失败：**
```
✓ python: 3.14.2 (>=3.11)
✓ uv: uv 0.9.16
✗ venv: 已启用但缺少配置项: path
```

### 6.3 aide env ensure --verbose

```
============================================================
环境检测详细信息
============================================================

  工作目录: /home/user/myproject
  配置文件: /home/user/myproject/.aide/config.toml
  配置存在: 是

  启用模块: python, uv, venv, requirements

  目标模块: python, uv, venv, requirements

  [python] 配置:
    min_version: 3.11
✓ python: 3.14.2 (>=3.11)
  [uv] 配置:
    (无配置)
✓ uv: uv 0.9.16
  [venv] 配置:
    path: .venv
    path (绝对): /home/user/myproject/.venv
    path (存在): 是
✓ venv: .venv
  [requirements] 配置:
    path: requirements.txt
    path (绝对): /home/user/myproject/requirements.txt
    path (存在): 是
✓ requirements: requirements.txt
✓ 环境就绪 (...)
```

### 6.4 aide env ensure --runtime

```
✓ python: 3.14.2 (>=3.11)
✓ uv: uv 0.9.16
✓ 环境就绪 (python:3.14.2, uv:uv 0.9.16)
```

### 6.5 aide env ensure --all

```
✓ python: 3.14.2 (>=3.11)
✓ uv: uv 0.9.16
✓ venv: .venv
✓ requirements: requirements.txt
```

---

## 七、代码结构

```
aide/env/
├── __init__.py
├── manager.py              # 环境管理器主入口
├── registry.py             # 模块注册表
└── modules/
    ├── __init__.py
    ├── base.py             # 模块基类
    ├── python.py           # Python 模块
    ├── uv.py               # uv 模块
    ├── venv.py             # venv 模块
    └── requirements.py     # requirements 模块
```

### 7.1 模块基类

```python
class BaseModule(ABC):
    @property
    @abstractmethod
    def info(self) -> ModuleInfo: ...

    @abstractmethod
    def check(self, config: dict, root: Path) -> CheckResult: ...

    def ensure(self, config: dict, root: Path) -> CheckResult: ...

    def validate_config(self, config: dict) -> tuple[bool, str | None]: ...
```

### 7.2 添加新模块

1. 在 `aide/env/modules/` 创建模块文件
2. 继承 `BaseModule` 实现 `info` 和 `check` 方法
3. 如支持修复，实现 `ensure` 方法
4. 导出 `module` 实例
5. 在 `registry.py` 的 `register_builtin_modules()` 中注册

---

## 八、相关文档

- [program 导览](../README.md)
- [配置格式文档](../formats/config.md)
- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)