agent-aide/aide-program/docs/commands/init.md

aide init 子命令设计文档

一、背景

1.1 解决的问题

问题	影响
配置文件缺失	其他 aide 命令无法正常工作
目录结构不存在	状态文件、决策记录无处存放
.gitignore 未配置	aide 数据文件被提交到仓库

1.2 设计目标

提供一键初始化：

• 创建 .aide/ 目录结构
• 生成默认配置文件
• 配置 .gitignore

---

二、职责

2.1 做什么

1. 创建 .aide/ 目录
2. 创建 .aide/decisions/ 子目录
3. 创建 .aide/logs/ 子目录
4. 生成默认 config.toml
5. 检查并更新 .gitignore

2.2 不做什么

• 不检测环境（那是 env 的职责）
• 不执行业务逻辑
• 不修改业务代码

---

三、接口规格

3.1 命令语法

aide init

3.2 参数

无参数。

3.3 输出

首次初始化：

✓ 已创建默认配置 .aide/config.toml
✓ 初始化完成，.aide/ 与默认配置已准备就绪

已存在时：

✓ 初始化完成，.aide/ 与默认配置已准备就绪

---

四、业务流程

@startuml
skinparam defaultFontName "PingFang SC"

start

:创建 .aide/ 目录;
note right: 如已存在则跳过

:创建 .aide/decisions/ 目录;

:创建 .aide/logs/ 目录;

if (config.toml 存在?) then (是)
  :加载现有配置;
else (否)
  :生成默认配置;
  :写入 config.toml;
  :输出创建提示;
endif

:检查 .gitignore;
if (.aide/ 已在忽略列表?) then (是)
else (否)
  :添加 .aide/ 到 .gitignore;
endif

:输出初始化完成;

stop
@enduml

---

五、数据结构

5.1 目录结构

.aide/
├── config.toml          # 项目配置
├── flow-status.json     # 当前任务进度（由 flow 创建）
├── decisions/           # 待定项决策记录
│   └── {timestamp}.json
└── logs/                # 操作日志

5.2 默认配置内容

# Aide 默认配置（由 aide init 生成）
# runtime: aide 自身运行要求
# task: 任务文档路径
# env: 虚拟环境与依赖配置
# flow: 环节名称列表，供流程校验使用

[runtime]
python_min = "3.11"
use_uv = true

[task]
source = "task-now.md"
spec = "task-spec.md"

[env]
venv = ".venv"
requirements = "requirements.txt"

[flow]
phases = ["task-optimize", "flow-design", "impl", "verify", "docs", "finish"]

5.3 方法签名原型

class ConfigManager:
    root: Path
    aide_dir: Path            # .aide/
    config_path: Path         # .aide/config.toml
    decisions_dir: Path       # .aide/decisions/
    logs_dir: Path            # .aide/logs/

    ensure_base_dirs() -> None
        # 创建基础目录结构

    ensure_gitignore() -> None
        # 确保 .gitignore 包含 .aide/

    ensure_config() -> dict
        # 确保配置文件存在，返回配置内容

    load_config() -> dict
        # 加载配置文件

    get_value(key: str) -> Any
        # 获取配置值（点号分隔的键）

    set_value(key: str, value: Any) -> None
        # 设置配置值

---

六、依赖

依赖项	类型	说明
output	内部模块	输出格式化
tomllib	标准库	TOML 读取
tomli_w	第三方库	TOML 写入

---

七、被依赖

依赖方	说明
/aide:init	调用 aide init 初始化配置
aide env ensure	依赖配置文件存在
aide flow	依赖目录结构存在
aide decide	依赖 decisions/ 目录存在

---

八、修改指南

8.1 修改默认配置

1. 更新本文档的"默认配置内容"章节
2. 修改 ConfigManager 中的 DEFAULT_CONFIG
3. 同步更新 配置格式文档

8.2 修改目录结构

1. 更新本文档的"目录结构"章节
2. 修改 ensure_base_dirs() 方法
3. 同步更新相关文档

8.3 添加新的初始化步骤

1. 在本文档添加步骤说明
2. 在 ensure_config() 或新方法中实现
3. 更新业务流程图

---

九、相关文档

• program 导览
• 配置格式文档
• aide skill 设计文档
• /aide:init 命令设计