# aide env 设计

## 一、命令概述

### 1.1 功能定位

`aide env` 命令用于检测和修复项目开发环境，确保所有必需的工具和依赖都已正确安装。

### 1.2 执行时机

- `/aide:init` 命令中调用（两次）
- 用户手动检查环境时
- 环境配置变更后

### 1.3 命令格式

```bash
aide env ensure [--runtime]
```

**选项**：
- `--runtime`：仅检查 aide 运行时环境（不依赖配置文件）

---

## 二、功能需求

### 2.1 aide env ensure --runtime

**用途**：检查 aide 程序自身运行所需的环境

**检查项**：
1. Python 版本（>= 3.10）
2. 必需的 Python 库（tomli/tomllib, tomli-w）

**特点**：
- 不读取项目配置文件
- 在 `aide init` 之前执行
- 失败时给出明确的安装建议

**输出示例**：

成功：
```
✓ 环境就绪 (python:3.12)
```

失败：
```
✗ Python 版本不满足要求 (需要 >=3.10, 当前 3.8)
  建议: 安装 Python 3.10+ 或使用 pyenv 管理版本
  文档: https://www.python.org/downloads/
```

### 2.2 aide env ensure

**用途**：检查项目开发环境

**检查项**：
1. Python 版本（根据配置文件）
2. 虚拟环境（根据配置文件）
3. 可选工具（git, uv 等，根据配置文件）

**特点**：
- 读取 `.aide/config.toml`
- 在 `aide init` 之后执行
- 可以自动修复部分问题

**输出示例**：

成功（无问题）：
```
✓ 环境就绪 (python:3.12, git:2.40.0)
```

成功（自动修复）：
```
⚠ 已修复: 创建虚拟环境 .venv
✓ 环境就绪 (python:3.12)
```

失败（无法修复）：
```
✗ Python 版本不满足要求 (需要 >=3.11, 当前 3.10)
  建议: 升级 Python 到 3.11+ 或修改配置文件
  配置: .aide/config.toml (env.python.version)
```

---

## 三、实现设计

### 3.1 函数接口

```python
def cmd_env(args: list[str]) -> int:
    """aide env 命令处理

    Args:
        args: 命令参数

    Returns:
        退出码（0 表示成功）
    """
    pass

def env_ensure(runtime_only: bool = False) -> int:
    """环境检测和修复

    Args:
        runtime_only: 是否仅检查运行时环境

    Returns:
        退出码（0 表示成功）
    """
    pass
```

### 3.2 实现流程

#### 3.2.1 aide env ensure --runtime

```python
import sys
import subprocess
from pathlib import Path
from core.output import ok, err

def env_ensure_runtime() -> int:
    """检查 aide 运行时环境"""

    # 1. 检查 Python 版本
    python_version = sys.version_info
    if python_version.major < 3 or (python_version.major == 3 and python_version.minor < 10):
        err(
            f"Python 版本不满足要求 (需要 >=3.10, 当前 {python_version.major}.{python_version.minor})",
            [
                "建议: 安装 Python 3.10+ 或使用 pyenv 管理版本",
                "文档: https://www.python.org/downloads/"
            ]
        )
        return 3

    # 2. 检查必需的库
    try:
        # Python 3.11+ 内置 tomllib
        if python_version.minor >= 11:
            import tomllib
        else:
            import tomli as tomllib

        import tomli_w
    except ImportError as e:
        err(
            f"缺少必需的 Python 库: {e.name}",
            [
                "建议: 运行 'pip install tomli tomli-w'",
                "或使用 uv: 'uv pip install tomli tomli-w'"
            ]
        )
        return 3

    # 3. 输出成功信息
    version_str = f"{python_version.major}.{python_version.minor}.{python_version.micro}"
    ok(f"环境就绪 (python:{version_str})")

    return 0
```

#### 3.2.2 aide env ensure

```python
from core.config import Config
from core.output import ok, warn, err

def env_ensure_project() -> int:
    """检查项目开发环境"""

    # 1. 加载配置
    try:
        config = Config(Path.cwd())
        config.load()
    except FileNotFoundError:
        err(
            "配置文件不存在",
            [
                "位置: .aide/config.toml",
                "建议: 运行 'aide init' 创建配置文件"
            ]
        )
        return 4
    except Exception as e:
        err(
            "配置文件读取失败",
            [
                f"原因: {str(e)}",
                "建议: 检查配置文件格式"
            ]
        )
        return 4

    # 2. 检查 Python 版本
    required_version = config.get("env.python.version", ">=3.10")
    if not check_python_version(required_version):
        err(
            f"Python 版本不满足要求 (需要 {required_version}, 当前 {get_python_version()})",
            [
                "建议: 升级 Python 或修改配置文件",
                "配置: .aide/config.toml (env.python.version)"
            ]
        )
        return 3

    # 3. 检查虚拟环境
    venv_path = config.get("env.python.venv", ".venv")
    venv_result = check_venv(venv_path)

    if venv_result == "missing":
        # 尝试创建虚拟环境
        if create_venv(venv_path):
            warn(f"已修复: 创建虚拟环境 {venv_path}")
        else:
            err(
                f"虚拟环境不存在且无法创建 ({venv_path})",
                [
                    "建议: 手动创建虚拟环境",
                    f"命令: python3 -m venv {venv_path}"
                ]
            )
            return 3

    # 4. 检查可选工具
    tools_info = []

    # 检查 git
    if config.get("env.tools.git", True):
        git_version = get_tool_version("git")
        if git_version:
            tools_info.append(f"git:{git_version}")
        else:
            warn("git 未安装（可选）")

    # 检查 uv
    if config.get("env.tools.uv", False):
        uv_version = get_tool_version("uv")
        if uv_version:
            tools_info.append(f"uv:{uv_version}")
        else:
            warn("uv 未安装（可选）")

    # 5. 输出成功信息
    python_version = get_python_version()
    info_parts = [f"python:{python_version}"] + tools_info
    ok(f"环境就绪 ({', '.join(info_parts)})")

    return 0
```

### 3.3 辅助函数

#### 3.3.1 版本检查

```python
import re
from packaging import version

def check_python_version(requirement: str) -> bool:
    """检查 Python 版本是否满足要求

    Args:
        requirement: 版本要求（如 ">=3.10"）

    Returns:
        是否满足要求
    """
    current = get_python_version()

    # 解析要求
    match = re.match(r'(>=|<=|>|<|==)?(\d+\.\d+(?:\.\d+)?)', requirement)
    if not match:
        return True  # 无法解析，假设满足

    operator, required = match.groups()
    operator = operator or "=="

    # 比较版本
    try:
        current_ver = version.parse(current)
        required_ver = version.parse(required)

        if operator == ">=":
            return current_ver >= required_ver
        elif operator == "<=":
            return current_ver <= required_ver
        elif operator == ">":
            return current_ver > required_ver
        elif operator == "<":
            return current_ver < required_ver
        elif operator == "==":
            return current_ver == required_ver
    except Exception:
        return True

    return True

def get_python_version() -> str:
    """获取当前 Python 版本

    Returns:
        版本字符串（如 "3.12.0"）
    """
    v = sys.version_info
    return f"{v.major}.{v.minor}.{v.micro}"
```

#### 3.3.2 虚拟环境检查

```python
import subprocess

def check_venv(venv_path: str) -> str:
    """检查虚拟环境状态

    Args:
        venv_path: 虚拟环境路径

    Returns:
        状态：'ok', 'missing', 'invalid'
    """
    venv_dir = Path(venv_path)

    if not venv_dir.exists():
        return "missing"

    # 检查是否是有效的虚拟环境
    if sys.platform == "win32":
        python_exe = venv_dir / "Scripts" / "python.exe"
    else:
        python_exe = venv_dir / "bin" / "python"

    if python_exe.exists():
        return "ok"
    else:
        return "invalid"

def create_venv(venv_path: str) -> bool:
    """创建虚拟环境

    Args:
        venv_path: 虚拟环境路径

    Returns:
        是否创建成功
    """
    try:
        subprocess.run(
            [sys.executable, "-m", "venv", venv_path],
            check=True,
            capture_output=True,
            text=True
        )
        return True
    except subprocess.CalledProcessError:
        return False
    except Exception:
        return False
```

#### 3.3.3 工具版本检查

```python
def get_tool_version(tool: str) -> str | None:
    """获取工具版本

    Args:
        tool: 工具名称（如 "git", "uv"）

    Returns:
        版本字符串，未安装则返回 None
    """
    try:
        result = subprocess.run(
            [tool, "--version"],
            capture_output=True,
            text=True,
            timeout=5
        )

        if result.returncode == 0:
            # 解析版本号
            output = result.stdout.strip()
            match = re.search(r'(\d+\.\d+\.\d+)', output)
            if match:
                return match.group(1)
            return "unknown"
    except (subprocess.TimeoutExpired, FileNotFoundError):
        pass

    return None
```

---

## 四、错误处理

### 4.1 错误分类

| 错误类型 | 退出码 | 处理方式 |
|---------|--------|---------|
| Python 版本不满足 | 3 | 显示当前版本和要求，给出升级建议 |
| 配置文件不存在 | 4 | 提示运行 aide init |
| 配置文件格式错误 | 4 | 显示错误位置和原因 |
| 虚拟环境无法创建 | 3 | 显示创建命令 |
| 必需工具未安装 | 3 | 显示安装建议 |

### 4.2 错误恢复

```python
def env_ensure_with_retry(runtime_only: bool = False, max_retries: int = 3) -> int:
    """带重试的环境检测

    Args:
        runtime_only: 是否仅检查运行时
        max_retries: 最大重试次数

    Returns:
        退出码
    """
    for attempt in range(max_retries):
        result = env_ensure(runtime_only)

        if result == 0:
            return 0

        if attempt < max_retries - 1:
            info(f"重试 ({attempt + 1}/{max_retries})...")

    return result
```

---

## 五、测试用例

### 5.1 runtime 模式测试

```python
def test_env_ensure_runtime_success():
    """测试运行时环境检测成功"""
    result = env_ensure_runtime()
    assert result == 0

def test_env_ensure_runtime_old_python(monkeypatch):
    """测试 Python 版本过低"""
    # 模拟 Python 3.8
    monkeypatch.setattr(sys, "version_info", (3, 8, 0, "final", 0))

    result = env_ensure_runtime()
    assert result == 3

def test_env_ensure_runtime_missing_lib(monkeypatch):
    """测试缺少必需库"""
    # 模拟 import 失败
    def mock_import(name, *args, **kwargs):
        if name in ["tomli", "tomllib"]:
            raise ImportError(f"No module named '{name}'")
        return __import__(name, *args, **kwargs)

    monkeypatch.setattr("builtins.__import__", mock_import)

    result = env_ensure_runtime()
    assert result == 3
```

### 5.2 项目环境测试

```python
def test_env_ensure_project_success(tmp_path, monkeypatch):
    """测试项目环境检测成功"""
    monkeypatch.chdir(tmp_path)

    # 创建配置文件
    cmd_init([])

    # 检测环境
    result = env_ensure_project()
    assert result == 0

def test_env_ensure_project_no_config(tmp_path, monkeypatch):
    """测试配置文件不存在"""
    monkeypatch.chdir(tmp_path)

    result = env_ensure_project()
    assert result == 4

def test_env_ensure_project_create_venv(tmp_path, monkeypatch):
    """测试自动创建虚拟环境"""
    monkeypatch.chdir(tmp_path)

    # 创建配置文件
    cmd_init([])

    # 确保虚拟环境不存在
    venv_path = tmp_path / ".venv"
    if venv_path.exists():
        shutil.rmtree(venv_path)

    # 检测环境（应该自动创建虚拟环境）
    result = env_ensure_project()
    assert result == 0
    assert venv_path.exists()
```

### 5.3 版本检查测试

```python
def test_check_python_version():
    """测试 Python 版本检查"""
    # 测试各种版本要求
    assert check_python_version(">=3.10") == True  # 假设当前是 3.12
    assert check_python_version(">=3.15") == False
    assert check_python_version("==3.12") == True
    assert check_python_version("<4.0") == True

def test_get_python_version():
    """测试获取 Python 版本"""
    version = get_python_version()
    assert re.match(r'\d+\.\d+\.\d+', version)
```

---

## 六、性能要求

### 6.1 执行时间

- `--runtime` 模式：< 100ms
- 项目环境检测（无修复）：< 500ms
- 项目环境检测（创建虚拟环境）：< 10s

### 6.2 资源占用

- 内存：< 50MB
- CPU：低（主要是 I/O 操作）

---

## 七、集成测试

### 7.1 完整工作流

```python
def test_env_workflow(tmp_path, monkeypatch):
    """测试完整的环境检测工作流"""
    monkeypatch.chdir(tmp_path)

    # 1. 检查运行时环境
    result = env_ensure_runtime()
    assert result == 0

    # 2. 初始化项目
    result = cmd_init([])
    assert result == 0

    # 3. 检查项目环境
    result = env_ensure_project()
    assert result == 0

    # 4. 验证虚拟环境已创建
    assert (tmp_path / ".venv").exists()
```

---

## 八、总结

### 8.1 核心要点

1. 两种模式：runtime 和 project
2. 自动修复部分问题（如创建虚拟环境）
3. 清晰的错误信息和建议
4. 完善的版本检查逻辑

### 8.2 实现检查清单

- [ ] 实现 cmd_env 函数
- [ ] 实现 env_ensure_runtime 函数
- [ ] 实现 env_ensure_project 函数
- [ ] 实现版本检查函数
- [ ] 实现虚拟环境检查和创建
- [ ] 实现工具版本检查
- [ ] 编写单元测试
- [ ] 编写集成测试
- [ ] 性能测试

---

**版本**：v1.0
**更新日期**：2025-12-13