[aide] task-optimize: 开始任务准备: 优化 docs.md 命令实现完整深度探索

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

@@ -1,67 +1,118 @@
 # aide-program-core
 
-> 路径：aide-program/aide/core/
-> 最后更新：2025-12-15
+> 路径：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            输出格式工具
+```
 
 ## 文件清单
 
-| 文件 | 说明 |
-|------|------|
-| `__init__.py` | 模块初始化，导出 output |
-| `config.py` | 配置管理器（~390 行） |
-| `output.py` | 统一输出格式（25 行） |
+| 文件 | 类型 | 说明 |
+|------|------|------|
+| aide/__init__.py | 源码 | 包初始化，定义包描述 |
+| aide/__main__.py | 源码 | 模块入口，支持 `python -m aide` |
+| aide/main.py | 源码 | 命令行主入口，解析参数并分发命令 |
+| core/__init__.py | 源码 | 核心模块初始化，定义模块描述 |
+| core/config.py | 源码 | 配置管理器，处理 TOML 配置 |
+| core/output.py | 源码 | 输出格式工具，统一输出前缀 |
 
 ## 核心组件
 
-### ConfigManager
+### ConfigManager 类
 
-- **职责**：管理 `.aide/config.toml` 配置文件
-- **位置**：`config.py:240`
+- **职责**：管理 .aide 目录和 config.toml 配置文件
+- **位置**：`aide/core/config.py:240`
 - **关键方法**：
-  - `ensure_config()` - 确保配置文件存在，不存在则创建默认配置
-  - `load_config()` - 加载配置（返回 dict）
-  - `get_value(key)` - 获取配置值（支持点号分隔的键）
-  - `set_value(key, value)` - 设置配置值（保留注释和格式）
-  - `ensure_gitignore()` - 根据配置决定是否忽略 .aide 目录
+  - `ensure_base_dirs()` - 创建 .aide 目录结构
+  - `ensure_gitignore()` - 根据配置更新 .gitignore
+  - `ensure_config()` - 确保配置文件存在
+  - `load_config()` - 加载 TOML 配置
+  - `get_value(key)` - 读取配置值（支持点号分隔键）
+  - `set_value(key, value)` - 设置配置值（保留注释）
+  - `_update_config_value()` - 保守更新配置，保留原文件注释
 
 ### DEFAULT_CONFIG
 
-- **职责**：默认配置模板（自文档化，含完整注释）
-- **位置**：`config.py:13`
-- **特点**：
-  - 包含所有配置节的详细说明
-  - 用户可仅通过此文件了解所有支持的功能
-  - 约 230 行注释文档
+- **职责**：默认配置模板，包含完整注释说明
+- **位置**：`aide/core/config.py:13-237`
+- **配置节**：
+  - `[general]` - 通用配置（gitignore_aide）
+  - `[runtime]` - 运行时要求（python_min, use_uv）
+  - `[task]` - 任务文档路径（source, spec）
+  - `[env]` - 环境检测模块配置
+  - `[docs]` - 项目文档配置
+  - `[flow]` - 流程追踪配置
+  - `[plantuml]` - PlantUML 工具配置
+  - `[decide]` - 待定项确认配置
 
 ### output 模块
 
 - **职责**：统一输出格式
-- **位置**：`output.py`
-- **输出函数**：
-  - `ok(msg)` → `✓ {msg}` 成功
-  - `warn(msg)` → `⚠ {msg}` 警告
-  - `err(msg)` → `✗ {msg}` 错误
-  - `info(msg)` → `→ {msg}` 信息
-  - `step(msg, current, total)` → `[n/m] {msg}` 步骤
+- **位置**：`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
-from aide.core.config import ConfigManager
+
+output.ok("操作成功")    # ✓ 操作成功
+output.warn("警告信息")  # ⚠ 警告信息
+output.err("错误信息")   # ✗ 错误信息
+output.info("提示信息")  # → 提示信息
 ```
 
 ## 依赖关系
 
-- 依赖：标准库 + tomllib + tomli_w
-- 被依赖：env, flow, decide, main
+- 依赖：tomllib（标准库）、tomli_w（第三方）
+- 被依赖：aide/env、aide/flow、aide/decide
 
 ## 注意事项
 
-- `set_value()` 使用正则表达式保守更新配置，保留注释
-- 配置键不存在时会回退到完全重写（丢失注释）
+- `set_value()` 使用正则替换保留原文件注释格式
+- 配置键支持点号分隔的嵌套访问（如 `env.venv.path`）
+- 新增配置键时会回退到完全重写模式（丢失注释）