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

aide env 重新设计 - 实现计划

一、设计概要

1.1 命令结构

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

1.2 参数

参数	说明
--runtime	仅检测 aide 运行时环境（python + uv）
--modules M1,M2	指定要检测的模块（逗号分隔）
--all	检测所有已启用模块，仅检查不修复

1.3 模块分类

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

• python, uv, java, go, rust, gcc, cmake, node, flutter

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

• venv, requirements, npm

---

二、目录结构变更

aide-program/aide/
├── __init__.py
├── __main__.py
├── main.py                    # [修改] 更新 CLI 路由
├── core/
│   ├── __init__.py
│   ├── config.py              # [修改] 更新默认配置
│   └── output.py
└── env/
    ├── __init__.py
    ├── ensure.py              # [删除] 旧实现
    ├── manager.py             # [新建] 环境管理器主入口
    ├── registry.py            # [新建] 模块注册表
    └── modules/               # [新建] 模块目录
        ├── __init__.py
        ├── base.py            # [新建] 模块基类
        ├── python.py          # [新建] Python 模块
        ├── uv.py              # [新建] uv 模块
        ├── venv.py            # [新建] venv 模块
        ├── requirements.py    # [新建] requirements 模块
        ├── node.py            # [新建] Node.js 模块
        ├── npm.py             # [新建] npm 模块
        └── ...                # 其他模块按需添加

---

三、配置文件变更

3.1 新默认配置

# Aide 默认配置（由 aide init 生成）

[runtime]
python_min = "3.11"
use_uv = true

[task]
source = "task-now.md"
spec = "task-spec.md"

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

# 类型A模块配置（可选，指定版本要求）
[env.python]
min_version = "3.11"

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

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

[flow]
phases = ["task-optimize", "flow-design", "impl", "verify", "docs", "finish"]

3.2 配置兼容性

旧配置格式：

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

新配置格式：

[env]
modules = ["python", "uv", "venv", "requirements"]

[env.venv]
path = ".venv"

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

迁移策略：读取时兼容旧格式，写入时使用新格式。

---

四、核心类设计

4.1 模块基类 (env/modules/base.py)

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Any
from pathlib import Path

@dataclass
class CheckResult:
    """检测结果"""
    success: bool
    version: str | None = None
    message: str | None = None
    can_ensure: bool = False  # 失败时是否可修复

@dataclass
class ModuleInfo:
    """模块元信息"""
    name: str
    description: str
    capabilities: list[str]  # ["check"] 或 ["check", "ensure"]
    requires_config: bool    # 是否需要配置（类型B）
    config_keys: list[str]   # 需要的配置键，如 ["path"]

class BaseModule(ABC):
    """模块基类"""

    @property
    @abstractmethod
    def info(self) -> ModuleInfo:
        """返回模块元信息"""
        pass

    @abstractmethod
    def check(self, config: dict[str, Any], root: Path) -> CheckResult:
        """检测环境"""
        pass

    def ensure(self, config: dict[str, Any], root: Path) -> CheckResult:
        """修复环境（可选实现）"""
        return CheckResult(
            success=False,
            message="此模块不支持自动修复"
        )

4.2 模块注册表 (env/registry.py)

from aide.env.modules.base import BaseModule, ModuleInfo

class ModuleRegistry:
    """模块注册表"""

    _modules: dict[str, BaseModule] = {}

    @classmethod
    def register(cls, module: BaseModule) -> None:
        cls._modules[module.info.name] = module

    @classmethod
    def get(cls, name: str) -> BaseModule | None:
        return cls._modules.get(name)

    @classmethod
    def all(cls) -> dict[str, BaseModule]:
        return cls._modules.copy()

    @classmethod
    def list_info(cls) -> list[ModuleInfo]:
        return [m.info for m in cls._modules.values()]

# 自动注册所有模块
def _auto_register():
    from aide.env.modules import python, uv, venv, requirements, node, npm
    # 每个模块文件导出一个 module 实例
    for mod in [python, uv, venv, requirements, node, npm]:
        if hasattr(mod, 'module'):
            ModuleRegistry.register(mod.module)

_auto_register()

4.3 环境管理器 (env/manager.py)

from pathlib import Path
from typing import Any

from aide.core import output
from aide.core.config import ConfigManager
from aide.env.registry import ModuleRegistry
from aide.env.modules.base import CheckResult

class EnvManager:
    """环境管理器"""

    def __init__(self, root: Path, cfg: ConfigManager):
        self.root = root
        self.cfg = cfg

    def list_modules(self) -> None:
        """列出所有可用模块"""
        # 实现 aide env list
        pass

    def ensure(
        self,
        runtime_only: bool = False,
        modules: list[str] | None = None,
        check_only: bool = False,  # --all 时为 True
    ) -> bool:
        """检测并修复环境"""
        # 主逻辑实现
        pass

    def _get_enabled_modules(self) -> list[str]:
        """获取已启用的模块列表"""
        pass

    def _get_module_config(self, name: str) -> dict[str, Any]:
        """获取模块配置"""
        pass

    def _check_module(self, name: str, is_enabled: bool) -> tuple[bool, CheckResult]:
        """检测单个模块"""
        pass

    def _ensure_module(self, name: str, is_enabled: bool) -> tuple[bool, CheckResult]:
        """检测并修复单个模块"""
        pass

---

五、执行逻辑详解

5.1 aide env ensure 流程

1. 读取配置
2. 获取 modules 列表（已启用模块）
3. 对每个模块：
   a. 获取模块实例
   b. 获取模块配置
   c. 检查类型B模块是否有必需配置
      - 已启用 + 无配置 → ✗ 错误，停止
      - 未启用 + 无配置 → ⚠ 警告，跳过
   d. 执行 check()
   e. 如果失败且可修复：执行 ensure()
   f. 根据启用状态决定输出级别
4. 输出最终状态

5.2 aide env ensure --all 流程

1. 读取配置
2. 获取 modules 列表
   - 有列表 → 使用列表
   - 无列表 → ⚠ 警告 + 使用所有已注册模块
3. 对每个模块：
   a. 仅执行 check()（不修复）
   b. 输出检测结果
4. 输出汇总

5.3 aide env ensure --modules X,Y 流程

1. 解析指定的模块列表
2. 读取配置，获取已启用列表
3. 对每个指定模块：
   a. 判断是否在启用列表中
   b. 检查类型B模块配置
   c. 执行 check() + ensure()
   d. 根据启用状态决定输出级别
4. 输出最终状态

---

六、输出级别规则

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

---

七、实现步骤

阶段1：基础架构

1. 创建 env/modules/ 目录结构
2. 实现 base.py 模块基类
3. 实现 registry.py 模块注册表
4. 更新 core/config.py 默认配置

阶段2：核心模块实现

5. 实现 python.py 模块
6. 实现 uv.py 模块
7. 实现 venv.py 模块
8. 实现 requirements.py 模块

阶段3：管理器与 CLI

9. 实现 manager.py 环境管理器
10. 更新 main.py CLI 路由
11. 删除旧的 ensure.py

阶段4：扩展模块（可选）

12. 实现 node.py 模块
13. 实现 npm.py 模块
14. 其他模块按需添加

阶段5：文档与测试

15. 更新 docs/commands/env.md 设计文档
16. 更新 docs/formats/config.md 配置文档
17. 添加测试用例

---

八、向后兼容

8.1 命令兼容

旧命令	新行为
aide env ensure	保持不变
aide env ensure --runtime	保持不变

8.2 配置兼容

读取配置时检测旧格式并转换：

def _migrate_config(config: dict) -> dict:
    """兼容旧配置格式"""
    env = config.get("env", {})

    # 如果没有 modules 字段，使用默认值
    if "modules" not in env:
        env["modules"] = ["python", "uv", "venv", "requirements"]

    # 如果使用旧的 venv/requirements 字段
    if "venv" in env and not isinstance(env["venv"], dict):
        old_venv = env.pop("venv")
        env.setdefault("venv", {})["path"] = old_venv

    if "requirements" in env and not isinstance(env["requirements"], dict):
        old_req = env.pop("requirements")
        env.setdefault("requirements", {})["path"] = old_req

    return config

---

九、相关文档

• aide env 设计文档 - 需更新
• 配置格式文档 - 需更新
• aide skill 设计文档 - 需更新