[aide] impl: 子计划1: 配置系统增强完成 - 自文档化配置模板、gitignore配置、plantuml.jar

.aide/flow-status.json

@@ -1,7 +1,7 @@
 {
   "task_id": "2025-12-15T17-28-53",
-  "current_phase": "flow-design",
-  "current_step": 9,
+  "current_phase": "impl",
+  "current_step": 10,
   "started_at": "2025-12-15T17:28:53+08:00",
   "history": [
     {
@@ -74,6 +74,14 @@
       "step": 9,
       "summary": "流程图设计完成: 1个总体流程图 + 6个子计划流程图",
       "git_commit": "46435c031cb933b04ddb4a01ee761b97f6016abf"
+    },
+    {
+      "timestamp": "2025-12-15T17:58:58+08:00",
+      "action": "next-part",
+      "phase": "impl",
+      "step": 10,
+      "summary": "流程设计完成，进入实现环节",
+      "git_commit": "5f27bb7424cc5ce2f18ab30a9f1a0ad9a626b604"
     }
   ]
 }

.aide/flow-status.lock

@@ -1 +1 @@
-113142
+119009

aide-program/aide/core/config.py

@@ -10,44 +10,230 @@ from tomli_w import dumps as toml_dumps
 
 from aide.core import output
 
-DEFAULT_CONFIG = """# Aide 默认配置（由 aide init 生成）
-# runtime: aide 自身运行要求
-# task: 任务文档路径
-# env: 环境模块配置
-# flow: 环节名称列表，供流程校验使用
+DEFAULT_CONFIG = """################################################################################
+#                           Aide 配置文件 (config.toml)
+################################################################################
+#
+# 本配置文件为 Aide 工作流体系的核心配置，由 `aide init` 命令生成。
+# 所有配置项都有详细说明，用户可仅通过本文件了解所有支持的功能。
+#
+# 配置操作说明：
+#   - 读取配置：aide config get <key>        例：aide config get flow.phases
+#   - 设置配置：aide config set <key> <value> 例：aide config set task.source "my-task.md"
+#   - 支持点号分隔的嵌套键，如：env.venv.path
+#
+# 注意：LLM 不应直接编辑此文件，必须通过 aide 命令操作。
+#
+################################################################################
+
+################################################################################
+# [general] - 通用配置
+################################################################################
+# 控制 Aide 的全局行为设置。
+
+[general]
+# 是否在 .gitignore 中忽略 .aide 目录
+# - true（默认）：自动添加 .aide/ 到 .gitignore，不跟踪 aide 状态
+# - false：不修改 .gitignore，允许 git 跟踪 .aide 目录
+#   适用于需要在多设备同步 aide 状态的场景
+gitignore_aide = true
+
+################################################################################
+# [runtime] - Aide 运行时要求
+################################################################################
+# 定义 aide 程序本身的运行环境要求。
+# 这些配置用于 `aide env ensure --runtime` 检测。
 
 [runtime]
+# Python 最低版本要求
+# 格式："主版本.次版本"，如 "3.11"、"3.12"
 python_min = "3.11"
+
+# 是否要求使用 uv 包管理器
+# - true：检测 uv 是否安装
+# - false：不检测 uv
 use_uv = true
 
+################################################################################
+# [task] - 任务文档配置
+################################################################################
+# 定义任务相关文档的默认路径。
+
 [task]
+# 任务原文档路径（用户提供的原始任务描述）
+# /aide:prep 命令在未指定参数时读取此文件
 source = "task-now.md"
+
+# 任务细则文档路径（aide 生成的可执行任务细则）
+# /aide:exec 命令在未指定参数时读取此文件
 spec = "task-spec.md"
 
+################################################################################
+# [env] - 环境检测配置
+################################################################################
+# 配置项目的开发环境检测模块。
+#
+# 模块分为两类：
+#   类型A - 无需配置即可检测（全局工具）：
+#     python  - Python 解释器版本检测
+#     uv      - uv 包管理器检测
+#     rust    - Rust 工具链（rustc + cargo）检测
+#     node    - Node.js 运行时检测
+#     flutter - Flutter SDK 检测
+#     android - Android SDK 检测
+#
+#   类型B - 需要配置路径才能检测（项目级）：
+#     venv         - Python 虚拟环境
+#     requirements - Python 依赖文件（requirements.txt）
+#     node_deps    - Node.js 项目依赖（package.json）
+#
+# 模块实例化（多项目场景）：
+#   格式：模块类型:实例名
+#   例如：node_deps:frontend、node_deps:backend
+#   各实例独立配置：[env."node_deps:frontend"]
+
 [env]
 # 启用的模块列表
+# 只有列在此处的模块才会被 `aide env ensure` 检测
+# 示例：
+#   - 纯 Python 项目：["python", "uv", "venv", "requirements"]
+#   - Rust 项目：["rust"]
+#   - Node.js 项目：["node", "node_deps"]
+#   - 多语言项目：["python", "uv", "venv", "node", "node_deps:frontend"]
 modules = ["python", "uv", "venv", "requirements"]
 
+# -------------------------------
+# 以下为各模块的详细配置示例
+# -------------------------------
+
 # Python 版本要求（可选，默认使用 runtime.python_min）
 # [env.python]
 # min_version = "3.11"
 
-# 虚拟环境配置（类型B模块，必须配置）
+# Rust 版本要求（可选）
+# [env.rust]
+# min_version = "1.70"
+
+# Node.js 版本要求（可选）
+# [env.node]
+# min_version = "18"
+
+# Flutter 版本要求（可选）
+# [env.flutter]
+# min_version = "3.0"
+
+# 虚拟环境配置（类型B模块，启用时必须配置）
+# path: 虚拟环境目录路径，相对于项目根目录
 [env.venv]
 path = ".venv"
 
-# 依赖文件配置（类型B模块，必须配置）
+# Python 依赖文件配置（类型B模块，启用时必须配置）
+# path: requirements.txt 文件路径，相对于项目根目录
 [env.requirements]
 path = "requirements.txt"
 
+# Node.js 依赖配置示例（类型B模块）
+# 注意：需先在 modules 中添加 "node_deps" 才会生效
+# [env.node_deps]
+# path = "."           # package.json 所在目录
+# manager = "npm"      # 包管理器：npm、yarn、pnpm
+
+# 多项目实例化示例（前端 + 后端分离项目）
+# modules = ["node_deps:frontend", "node_deps:backend"]
+#
+# [env."node_deps:frontend"]
+# path = "frontend"
+# manager = "pnpm"
+#
+# [env."node_deps:backend"]
+# path = "backend"
+# manager = "npm"
+
+################################################################################
+# [docs] - 项目文档配置（面向 LLM）
+################################################################################
+# 配置面向 LLM 的项目文档系统。
+# 这些文档用于帮助 LLM 理解项目结构，支持增量更新。
+
+[docs]
+# 项目文档目录路径
+# 存放总导览和各区块文档
+# 默认：.aide/project-docs
+path = ".aide/project-docs"
+
+# 区块计划文档路径
+# 记录文档区块划分和生成进度，用于多对话续接
+# 默认：.aide/project-docs/block-plan.md
+block_plan_path = ".aide/project-docs/block-plan.md"
+
+################################################################################
+# [flow] - 流程追踪配置
+################################################################################
+# 配置任务执行流程的追踪和校验。
+
 [flow]
+# 环节名称列表（有序）
+# 定义任务执行的标准流程，用于校验环节跳转合法性
+# 标准环节：
+#   task-optimize - 任务优化阶段（/aide:prep 使用）
+#   flow-design   - 流程设计（创建流程图）
+#   impl          - 迭代实现
+#   verify        - 验证交付
+#   docs          - 文档更新
+#   finish        - 收尾
 phases = ["task-optimize", "flow-design", "impl", "verify", "docs", "finish"]
 
+# 流程图目录路径
+# 存放 PlantUML 源文件（.puml）和生成的图片（.png）
+# flow-design 阶段会校验此目录下的 .puml 文件
+diagram_path = ".aide/diagrams"
+
+################################################################################
+# [plantuml] - PlantUML 配置
+################################################################################
+# 配置 PlantUML 流程图生成工具。
+
+[plantuml]
+# PlantUML jar 文件路径
+# 支持绝对路径或相对于 aide-program 目录的相对路径
+# 默认使用 aide-program/lib/plantuml.jar
+jar_path = "lib/plantuml.jar"
+
+# Java 命令路径（可选）
+# 默认使用系统 PATH 中的 java
+# java_path = "/usr/bin/java"
+
+################################################################################
+# [decide] - 待定项确认配置
+################################################################################
+# 配置待定项 Web 确认界面。
+
 [decide]
 # HTTP 服务起始端口
+# 如果端口被占用，会自动探测下一个可用端口
 port = 3721
-# 超时时间（秒），0 表示不超时
+
+# 监听地址
+# - "127.0.0.1"（默认）：仅本机访问
+# - "0.0.0.0"：允许外部访问（注意安全风险）
+bind = "127.0.0.1"
+
+# 自定义访问地址（可选）
+# 为空时自动生成为 http://{bind}:{port}
+# 适用于反向代理或自定义域名场景
+# 示例：url = "https://decide.example.com"
+url = ""
+
+# 超时时间（秒）
+# - 0（默认）：不超时，等待用户完成
+# - >0：超时后自动关闭服务
 timeout = 0
+
+################################################################################
+# 配置文件版本信息
+################################################################################
+# 本配置文件格式版本，用于未来兼容性检查
+# _version = "1.1.0"
 """
 
 
@@ -65,6 +251,17 @@ class ConfigManager:
         self.logs_dir.mkdir(parents=True, exist_ok=True)
 
     def ensure_gitignore(self) -> None:
+        """根据配置决定是否在 .gitignore 中添加 .aide/ 忽略项。"""
+        # 读取配置，默认为 True（忽略 .aide 目录）
+        config = self.load_config()
+        gitignore_aide = self._walk_get(config, "general.gitignore_aide")
+        if gitignore_aide is None:
+            gitignore_aide = True  # 默认值
+
+        if not gitignore_aide:
+            # 配置为 False，不添加忽略项
+            return
+
         gitignore_path = self.root / ".gitignore"
         marker = ".aide/"
         if gitignore_path.exists():