222 lines
4.2 KiB
Markdown
222 lines
4.2 KiB
Markdown
|
# 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 默认配置内容
|
|||
|
|
|
|||
|
|
```toml
|
|||
|
|
# 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. 同步更新 [配置格式文档](../formats/config.md)
|
|||
|
|
|
|||
|
|
### 8.2 修改目录结构
|
|||
|
|
|
|||
|
|
1. 更新本文档的"目录结构"章节
|
|||
|
|
2. 修改 `ensure_base_dirs()` 方法
|
|||
|
|
3. 同步更新相关文档
|
|||
|
|
|
|||
|
|
### 8.3 添加新的初始化步骤
|
|||
|
|
|
|||
|
|
1. 在本文档添加步骤说明
|
|||
|
|
2. 在 `ensure_config()` 或新方法中实现
|
|||
|
|
3. 更新业务流程图
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 九、相关文档
|
|||
|
|
|
|||
|
|
- [program 导览](../README.md)
|
|||
|
|
- [配置格式文档](../formats/config.md)
|
|||
|
|
- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)
|
|||
|
|
- [/aide:init 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/init.md)
|