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

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 设计文档

8.3 修改配置依赖

1. 更新本文档的"配置依赖"章节
2. 修改代码实现
3. 同步更新 配置格式文档

---

九、相关文档

• program 导览
• 配置格式文档
• aide skill 设计文档
• /aide:init 命令设计