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

# aide-program-core

> 路径：aide-program/aide/core/ 及 aide-program/aide/
> 最后更新：2025-12-17

## 概述

Aide CLI 工具的核心模块，包含配置管理、输出格式化和命令行入口。本区块是整个 aide 程序的基础设施层，被所有其他模块依赖。

## 目录结构

```
aide-program/aide/
├── __init__.py              包初始化
├── __main__.py              模块入口
├── main.py                  命令行主入口
└── core/
    ├── __init__.py          核心模块初始化
    ├── config.py            配置管理
    └── output.py            输出格式工具
```

## 文件清单

| 文件 | 类型 | 说明 |
|------|------|------|
| aide/__init__.py | 源码 | 包初始化，定义包描述 |
| aide/__main__.py | 源码 | 模块入口，支持 `python -m aide` |
| aide/main.py | 源码 | 命令行主入口，解析参数并分发命令 |
| core/__init__.py | 源码 | 核心模块初始化，定义模块描述 |
| core/config.py | 源码 | 配置管理器，处理 TOML 配置 |
| core/output.py | 源码 | 输出格式工具，统一输出前缀 |

## 核心组件

### ConfigManager 类

- **职责**：管理 .aide 目录和 config.toml 配置文件
- **位置**：`aide/core/config.py:240`
- **关键方法**：
  - `ensure_base_dirs()` - 创建 .aide 目录结构
  - `ensure_gitignore()` - 根据配置更新 .gitignore
  - `ensure_config()` - 确保配置文件存在
  - `load_config()` - 加载 TOML 配置
  - `get_value(key)` - 读取配置值（支持点号分隔键）
  - `set_value(key, value)` - 设置配置值（保留注释）
  - `_update_config_value()` - 保守更新配置，保留原文件注释

### DEFAULT_CONFIG

- **职责**：默认配置模板，包含完整注释说明
- **位置**：`aide/core/config.py:13-237`
- **配置节**：
  - `[general]` - 通用配置（gitignore_aide）
  - `[runtime]` - 运行时要求（python_min, use_uv）
  - `[task]` - 任务文档路径（source, spec）
  - `[env]` - 环境检测模块配置
  - `[docs]` - 项目文档配置
  - `[flow]` - 流程追踪配置
  - `[plantuml]` - PlantUML 工具配置
  - `[decide]` - 待定项确认配置

### output 模块

- **职责**：统一输出格式
- **位置**：`aide/core/output.py`
- **函数**：
  - `ok(msg)` - 成功输出（✓ 前缀）
  - `warn(msg)` - 警告输出（⚠ 前缀）
  - `err(msg)` - 错误输出（✗ 前缀）
  - `info(msg)` - 信息输出（→ 前缀）
  - `step(msg, current, total)` - 步骤输出（[n/m] 前缀）

### main() 函数

- **职责**：命令行入口，构建解析器并分发命令
- **位置**：`aide/main.py:16`
- **支持的命令**：
  - `aide init` - 初始化 .aide 目录
  - `aide env {ensure|list|set}` - 环境管理
  - `aide config {get|set}` - 配置管理
  - `aide flow {start|next-step|back-step|next-part|back-part|issue|error|status|list|show}` - 进度追踪
  - `aide decide {submit|result}` - 待定项确认

## 接口说明

### 配置读写 API

```python
from aide.core.config import ConfigManager

cfg = ConfigManager(Path.cwd())
cfg.ensure_config()  # 确保配置存在
value = cfg.get_value("env.venv.path")  # 读取嵌套键
cfg.set_value("task.source", "my-task.md")  # 设置值
```

### 输出格式 API

```python
from aide.core import output

output.ok("操作成功")    # ✓ 操作成功
output.warn("警告信息")  # ⚠ 警告信息
output.err("错误信息")   # ✗ 错误信息
output.info("提示信息")  # → 提示信息
```

## 依赖关系

- 依赖：tomllib（标准库）、tomli_w（第三方）
- 被依赖：aide/env、aide/flow、aide/decide

## 注意事项

- `set_value()` 使用正则替换保留原文件注释格式
- 配置键支持点号分隔的嵌套访问（如 `env.venv.path`）
- 新增配置键时会回退到完全重写模式（丢失注释）