sayurinana/agent-aide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ca1a5836e1ef910ee3a7b7f198889029de08a6c6
agent-aide/aide-program/docs/commands/env.md

8.0 KiB
Raw Blame History

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 配置结构

[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 配置兼容性

支持旧格式配置：

[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 模块基类

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() 中注册

八、相关文档