agent-aide/.aide/project-docs/blocks/aide-program-env.md

aide-program-env

路径：aide-program/aide/env/ 最后更新：2025-12-17

概述

环境检测和管理模块，负责检测和修复开发环境。采用插件式架构，支持多种开发环境的检测。模块分为两类：类型A（全局工具，无需配置）和类型B（项目级，需要配置路径）。

目录结构

aide-program/aide/env/
├── __init__.py              模块初始化
├── manager.py               环境管理器
├── registry.py              模块注册表
└── modules/
    ├── __init__.py          模块集合初始化
    ├── base.py              模块基类定义
    ├── python.py            Python 解释器检测
    ├── uv.py                uv 包管理器检测
    ├── venv.py              虚拟环境管理
    ├── requirements.py      Python 依赖管理
    ├── rust.py              Rust 工具链检测
    ├── node.py              Node.js 运行时检测
    ├── node_deps.py         Node.js 项目依赖
    ├── flutter.py           Flutter SDK 检测
    └── android.py           Android SDK 检测

文件清单

文件	类型	说明
init.py	源码	模块初始化
manager.py	源码	EnvManager 类，环境检测核心逻辑
registry.py	源码	ModuleRegistry 注册表，管理所有检测模块
modules/base.py	源码	BaseModule 基类和数据类定义
modules/python.py	源码	Python 版本检测（类型A）
modules/uv.py	源码	uv 包管理器检测（类型A）
modules/venv.py	源码	虚拟环境检测/创建（类型B）
modules/requirements.py	源码	Python 依赖检测/安装（类型B）
modules/rust.py	源码	Rust 工具链检测（类型A）
modules/node.py	源码	Node.js 运行时检测（类型A）
modules/node_deps.py	源码	Node.js 依赖检测/安装（类型B）
modules/flutter.py	源码	Flutter SDK 检测（类型A）
modules/android.py	源码	Android SDK 检测（类型A）

核心组件

EnvManager 类

• 职责：环境管理器，协调各模块的检测和修复
• 位置：aide/env/manager.py:53
• 关键方法：
  • list_modules() - 列出所有可用模块（aide env list）
  • ensure() - 检测并修复环境（aide env ensure）
  • set_modules() - 设置启用的模块列表
  • set_module_config() - 设置模块配置
  • _process_module() - 处理单个模块的检测/修复

ModuleRegistry 类

• 职责：模块注册表，管理所有可用的环境检测模块
• 位置：aide/env/registry.py:8
• 关键方法：
  • register(module) - 注册模块
  • get(name) - 获取指定模块
  • names() - 获取所有模块名称
  • list_info() - 获取所有模块的元信息

BaseModule 抽象类

• 职责：模块基类，定义检测模块的接口
• 位置：aide/env/modules/base.py:37
• 抽象方法：
  • info - 返回模块元信息（ModuleInfo）
  • check(config, root) - 检测环境
  • ensure(config, root) - 修复环境（可选）
  • validate_config(config) - 验证模块配置

CheckResult 数据类

• 职责：检测结果封装
• 位置：aide/env/modules/base.py:12
• 字段：
  • success: bool - 是否成功
  • version: str | None - 版本信息
  • message: str | None - 消息
  • can_ensure: bool - 是否可修复

ModuleInfo 数据类

• 职责：模块元信息
• 位置：aide/env/modules/base.py:22
• 字段：
  • name: str - 模块名称
  • description: str - 描述
  • capabilities: list[str] - 能力（check, ensure）
  • requires_config: bool - 是否需要配置
  • config_keys: list[str] - 需要的配置键

模块列表

模块	类型	能力	说明
python	A	check	Python 解释器版本检测
uv	A	check	uv 包管理器检测
venv	B	check, ensure	虚拟环境检测/创建
requirements	B	check, ensure	Python 依赖检测/安装
rust	A	check	Rust 工具链（rustc + cargo）
node	A	check	Node.js 运行时
node_deps	B	check, ensure	Node.js 项目依赖
flutter	A	check	Flutter SDK
android	A	check	Android SDK

接口说明

环境检测 API

from aide.env.manager import EnvManager
from aide.core.config import ConfigManager

cfg = ConfigManager(Path.cwd())
manager = EnvManager(Path.cwd(), cfg)

# 检测运行时环境
manager.ensure(runtime_only=True)

# 检测所有启用模块
manager.ensure()

# 检测指定模块
manager.ensure(modules=["python", "node"])

# 列出可用模块
manager.list_modules()

模块实例化命名

支持多项目场景，如 node_deps:frontend、node_deps:backend：

# 配置格式
# [env."node_deps:frontend"]
# path = "frontend"
# manager = "pnpm"

依赖关系

• 依赖：aide/core（ConfigManager、output）
• 被依赖：aide/main.py

注意事项

• 类型A模块无需配置即可检测（全局工具）
• 类型B模块需要在配置中指定路径
• requirements 模块会自动注入 venv 路径
• node_deps 模块支持自动检测包管理器（npm/yarn/pnpm/bun）
• 模块名支持实例化命名（module_type:instance_name）