397 lines
9.7 KiB
Markdown
397 lines
9.7 KiB
Markdown
# 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 新默认配置
|
||
|
||
```toml
|
||
# 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 配置兼容性
|
||
|
||
旧配置格式：
|
||
```toml
|
||
[env]
|
||
venv = ".venv"
|
||
requirements = "requirements.txt"
|
||
```
|
||
|
||
新配置格式：
|
||
```toml
|
||
[env]
|
||
modules = ["python", "uv", "venv", "requirements"]
|
||
|
||
[env.venv]
|
||
path = ".venv"
|
||
|
||
[env.requirements]
|
||
path = "requirements.txt"
|
||
```
|
||
|
||
**迁移策略**：读取时兼容旧格式，写入时使用新格式。
|
||
|
||
---
|
||
|
||
## 四、核心类设计
|
||
|
||
### 4.1 模块基类 (`env/modules/base.py`)
|
||
|
||
```python
|
||
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`)
|
||
|
||
```python
|
||
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`)
|
||
|
||
```python
|
||
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 配置兼容
|
||
|
||
读取配置时检测旧格式并转换：
|
||
|
||
```python
|
||
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 设计文档](./env.md) - 需更新
|
||
- [配置格式文档](../formats/config.md) - 需更新
|
||
- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md) - 需更新
|