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                    # 列出所有可用模块
aide env set <key> <value>       # 设置环境配置（带验证）
```

### 2.1 aide env ensure

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

**参数：**

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

### 2.2 aide env list

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

### 2.3 aide env set

设置环境配置，带模块名称验证。

**用法：**

```bash
aide env set modules <模块列表>      # 设置启用的模块（逗号分隔）
aide env set <模块名>.<配置项> <值>  # 设置模块配置
```

**示例：**

```bash
# 设置启用的模块
aide env set modules python,uv,rust,node

# 设置模块配置
aide env set venv.path .venv
aide env set requirements.path requirements.txt

# 设置实例化模块（多项目场景）
aide env set modules rust,node,flutter,android,node_deps:react
aide env set node_deps:react.path react-demo
```

**验证规则：**

- 设置 `modules` 时，验证每个模块类型是否存在
- 设置模块配置时，验证模块类型是否存在
- 无效模块名会报错并显示可用模块列表

**错误示例：**

```
✗ 未知模块: fortran, cobol
→ 可用模块: python, uv, venv, requirements, rust, node, flutter, node_deps, android
```

---

## 三、模块系统

### 3.1 模块分类

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

| 模块 | 描述 | 能力 |
|------|------|------|
| `python` | Python 解释器版本 | check |
| `uv` | uv 包管理器 | check |
| `rust` | Rust 工具链（rustc + cargo） | check |
| `node` | Node.js 运行时 | check |
| `flutter` | Flutter SDK | check |
| `android` | Android SDK | check |

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

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

### 3.2 模块能力

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

### 3.3 模块实例化命名

支持 `模块类型:实例名` 格式，用于同类型多实例场景：

```toml
# 多个 Node.js 项目
modules = ["node", "node_deps:react", "node_deps:vue"]

[env."node_deps:react"]
path = "react-demo"

[env."node_deps:vue"]
path = "vue-demo"
manager = "pnpm"
```

**输出示例：**
```
✓ node: 24.11.1 (npm 11.6.2)
✓ node_deps:react: react-demo (npm)
✓ node_deps:vue: vue-demo (pnpm)
```

---

## 四、配置

### 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]
modules = ["rust", "node", "flutter", "android", "node_deps:react"]

# Node.js 项目依赖（实例化命名）
[env."node_deps:react"]
path = "react-demo"
# manager = "npm"  # 可选，默认自动检测
```

### 4.3 node_deps 模块配置

| 配置项 | 必需 | 说明 |
|--------|------|------|
| `path` | 是 | package.json 所在目录 |
| `manager` | 否 | 包管理器：npm/pnpm/yarn/bun，默认自动检测 |

**自动检测逻辑**（按锁文件判断）：
- `pnpm-lock.yaml` → pnpm
- `yarn.lock` → yarn
- `bun.lockb` → bun
- `package-lock.json` 或无锁文件 → npm

### 4.4 配置兼容性

支持旧格式配置：

```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类模块无配置 = 错误(✗) = 配置错误

---

## 六、输出示例

### 6.1 aide env list

```
可用模块:
  模块           描述                   能力               需要配置
  ────────────────────────────────────────────────────────────
  python        Python 解释器版本       check            否
  uv            uv 包管理器            check            否
  venv          Python 虚拟环境        check, ensure    是 [path]
  requirements  Python 依赖管理        check, ensure    是 [path]
  rust          Rust 工具链           check            否
  node          Node.js 运行时        check            否
  flutter       Flutter SDK          check            否
  node_deps     Node.js 项目依赖      check, ensure    是 [path]
  android       Android SDK          check            否

当前启用: rust, node, flutter, android, node_deps:react
```

### 6.2 aide env ensure（多项目场景）

```
✓ rust: 1.94.0-nightly (cargo 1.94.0-nightly)
✓ node: 24.11.1 (npm 11.6.2)
✓ flutter: 3.38.4 (dart 3.10.3)
✓ android: /home/user/android-sdk (adb 1.0.41, build-tools 36.1.0, API 36)
→ node_deps:react: node_modules 不存在，尝试修复...
✓ node_deps:react: 已安装 (npm)
✓ 环境就绪 (rust:1.94.0-nightly, node:24.11.1, flutter:3.38.4, android:/home/user/android-sdk, node_deps:react:react-demo)
```

### 6.3 aide env set 示例

```bash
# 设置多种环境模块
$ aide env set modules rust,node,flutter,android,node_deps:react
✓ 已更新 env.modules = ['rust', 'node', 'flutter', 'android', 'node_deps:react']

# 设置实例化模块配置
$ aide env set node_deps:react.path react-demo
✓ 已更新 env."node_deps:react".path = 'react-demo'

# 验证失败示例
$ aide env set modules python,fortran
✗ 未知模块: fortran
→ 可用模块: python, uv, venv, requirements, rust, node, flutter, node_deps, android
```

---

## 七、代码结构

```
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 模块
    ├── rust.py             # Rust 模块
    ├── node.py             # Node.js 模块
    ├── flutter.py          # Flutter 模块
    ├── node_deps.py        # Node.js 项目依赖模块
    └── android.py          # Android SDK 模块
```

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