sayurinana/agent-aide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

✨ feat: 完成文档拆分

Browse Source
This commit is contained in:
sayurinana(vm)
2025-12-13 22:22:01 +08:00
parent f535707657
commit 4cacd128ab
16 changed files with 3983 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

208
aide-program/docs/README.md Normal file
View File

@@ -0,0 +1,208 @@
# Aide Program 设计文档
## 一、概述
aide-program 是 Aide 工作流体系的命令行工具，为 aide-plugin 提供底层支持。
### 1.1 解决的问题
| 问题 | 解决方案 |
|------|----------|
| 操作不确定性 | 程序化封装，固定输入输出 |
| 输出信息冗余 | 精简输出，静默即成功 |
| git 操作分散 | 集成到 flow 命令，自动提交 |
| 状态难追踪 | 统一的状态文件和日志 |
### 1.2 与 aide-plugin 的关系
```
┌─────────────────────────────────────────────────┐
│ aide-plugin │
│ Commands: 定义流程（做什么、按什么顺序） │
│ Skill: 定义工具使用方法（怎么调用） │
└─────────────────────────────────────────────────┘
│
▼ 调用
┌─────────────────────────────────────────────────┐
│ aide-program │
│ 实际执行操作，返回精简结果 │
│ │
│ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ env │ │ flow │ │ decide │ │
│ └────────┘ └────────┘ └────────┘ │
│ ┌────────┐ ┌────────┐ │
│ │ config │ │ init │ │
│ └────────┘ └────────┘ │
└─────────────────────────────────────────────────┘
```
---
## 二、子命令索引
| 子命令 | 设计文档 | 实现状态 | 职责 |
|--------|----------|----------|------|
| `aide init` | [commands/init.md](commands/init.md) | ✅ 已实现 | 初始化 .aide 目录 |
| `aide env` | [commands/env.md](commands/env.md) | ✅ 已实现 | 环境检测与修复 |
| `aide config` | [formats/config.md](formats/config.md) | ✅ 已实现 | 配置读写 |
| `aide flow` | [commands/flow.md](commands/flow.md) | ⏳ 待实现 | 进度追踪与 git 集成 |
| `aide decide` | [commands/decide.md](commands/decide.md) | ⏳ 待实现 | 待定项 Web 确认 |
---
## 三、目录结构
```
aide-program/
├── aide.sh # Linux/Mac 入口脚本
├── aide.bat # Windows 入口脚本
├── docs/ # 设计文档（本目录）
│ ├── README.md # 导览（本文件）
│ ├── commands/ # 子命令设计文档
│ │ ├── env.md
│ │ ├── flow.md
│ │ ├── decide.md
│ │ └── init.md
│ └── formats/ # 数据格式文档
│ ├── config.md
│ └── data.md
└── aide/ # Python 代码
├── __init__.py
├── __main__.py # 支持 python -m aide
├── main.py # CLI 解析与命令分发
├── core/
│ ├── __init__.py
│ ├── config.py # 配置读写
│ └── output.py # 输出格式（✓/⚠/✗/→）
├── env/
│ ├── __init__.py
│ └── ensure.py # 环境检测与修复
├── flow/ # 待实现
│ ├── __init__.py
│ ├── tracker.py # 进度追踪
│ ├── git.py # git 自动提交
│ └── validator.py # 流程校验
└── decide/ # 待实现
├── __init__.py
├── server.py # HTTP 服务
└── web/ # 静态前端
```
---
## 四、输出规范
### 4.1 前缀符号
| 前缀 | 函数 | 用途 |
|------|------|------|
| `✓` | `output.ok()` | 成功 |
| `⚠` | `output.warn()` | 警告（可继续） |
| `✗` | `output.err()` | 失败 |
| `→` | `output.info()` | 进行中/信息 |
| `[n/m]` | `output.step()` | 步骤进度 |
### 4.2 静默原则
**无输出 = 正常完成**
只有在需要反馈信息时才输出。
### 4.3 输出示例
```bash
# 成功
✓ 环境就绪 (python:3.12, uv:0.4.0)
# 警告
⚠ 已修复: 创建虚拟环境 .venv
# 错误
✗ Python 版本不满足要求 (需要 >=3.10, 当前 3.8)
建议: 安装 Python 3.10+ 或使用 pyenv 管理版本
# 信息
→ 任务原文档: task-now.md
```
---
## 五、数据存储
### 5.1 存储位置
所有 aide 数据文件存放在项目根目录的 `.aide/` 下：
```
.aide/
├── config.toml # 项目配置
├── flow-status.json # 当前任务进度状态
├── decisions/ # 待定项决策记录
│ └── {timestamp}.json
└── logs/ # 操作日志
```
### 5.2 .gitignore 处理
- `aide init` 时自动检查 `.gitignore`
- 默认添加 `.aide/` 为忽略项
---
## 六、运行方式
### 6.1 通过入口脚本
```bash
# Linux/Mac
./aide-program/aide.sh <command> [args]
# Windows
aide-program\aide.bat <command> [args]
```
### 6.2 通过 Python 模块
```bash
# 需要先激活虚拟环境或设置 PYTHONPATH
python -m aide <command> [args]
```
### 6.3 依赖要求
- Python >= 3.11
- uv（用于虚拟环境和依赖管理）
- tomli-w（TOML 写入）
---
## 七、开发指南
### 7.1 添加新子命令
1. 在 `docs/commands/` 创建设计文档
2. 在 `aide/` 下创建对应模块目录
3. 在 `aide/main.py` 添加 CLI 路由
4. 更新本导览的子命令索引
5. 更新 [aide skill 设计文档](../../aide-marketplace/aide-plugin/docs/skill/aide.md)
### 7.2 修改现有子命令
1. 阅读对应的设计文档
2. 修改代码实现
3. 更新设计文档（如有接口变更）
4. 同步更新 aide skill 文档
### 7.3 代码规范
- 所有输出使用 `core/output.py` 中的函数
- 配置操作使用 `core/config.py` 中的 `ConfigManager`
- 遵循静默原则：成功时尽量少输出
---
## 八、相关文档
- [总导览](../../docs/aide-overview.md)
- [aide-plugin 导览](../../aide-marketplace/aide-plugin/docs/README.md)
- [aide skill 设计文档](../../aide-marketplace/aide-plugin/docs/skill/aide.md)

353
aide-program/docs/commands/decide.md Normal file
View File

@@ -0,0 +1,353 @@
# aide decide 子命令设计文档
## 一、背景
### 1.1 解决的问题
| 问题 | 影响 |
|------|------|
| 待定项呈现繁琐 | LLM 输出大量文本描述选项 |
| 用户确认不便 | 在终端中逐项确认效率低 |
| 决策记录分散 | 难以追溯历史决策 |
### 1.2 设计目标
提供**程序化的待定项确认机制**：
- LLM 传入精简 JSON 数据
- 程序启动 Web 服务，提供可视化界面
- 用户在 Web 界面操作
- LLM 读取精简决策结果
---
## 二、职责
### 2.1 做什么
1. 接收待定项 JSON 数据
2. 启动 HTTP 服务
3. 提供 Web 界面供用户操作
4. 存储用户决策
5. 返回决策结果
### 2.2 不做什么
- 不分析待定项内容
- 不做决策建议
- 不修改业务代码
---
## 三、接口规格
### 3.1 aide decide（提交数据）
**用途**：提交待定项数据并启动 Web 服务
**语法**：
```
aide decide '<json数据>'
```
**输入**：待定项 JSON 数据（见数据格式章节）
**输出**：
```
→ Web 服务已启动
→ 请访问: http://localhost:3721
→ 等待用户完成决策...
```
### 3.2 aide decide result
**用途**：获取用户决策结果
**语法**：
```
aide decide result
```
**输出**：
```json
{
"decisions": [
{"id": 1, "chosen": "option_a"},
{"id": 2, "chosen": "option_b", "note": "用户的补充说明"}
]
}
```
**错误情况**：
```
✗ 尚无决策结果，请等待用户完成操作
```
```
✗ 未找到待定项数据，请先执行 aide decide '<json>'
```
---
## 四、业务流程
### 4.1 整体流程
```
@startuml
skinparam defaultFontName "PingFang SC"
participant LLM
participant "aide decide" as Decide
participant "Web Server" as Web
participant User
LLM -> Decide : aide decide '<json>'
Decide -> Decide : 解析 JSON
Decide -> Decide : 保存待定项数据
Decide -> Web : 启动 HTTP 服务
Decide --> LLM : 输出访问链接
LLM -> User : 告知访问链接
User -> Web : 访问页面
Web -> User : 渲染待定项界面
User -> Web : 选择选项、添加备注
User -> Web : 提交决策
Web -> Web : 保存决策结果
LLM -> Decide : aide decide result
Decide -> Decide : 读取决策结果
Decide --> LLM : 返回 JSON 结果
@enduml
```
### 4.2 Web 服务流程
```
@startuml
skinparam defaultFontName "PingFang SC"
start
:接收 JSON 数据;
:解析并验证格式;
if (格式有效?) then (是)
else (否)
:输出错误信息;
stop
endif
:保存到 .aide/decisions/pending.json;
:启动 HTTP 服务;
note right: 默认端口 3721
:输出访问链接;
:等待用户操作;
:用户提交决策;
:保存决策结果;
note right: .aide/decisions/{timestamp}.json
:关闭 HTTP 服务;
stop
@enduml
```
---
## 五、数据结构
### 5.1 输入格式（LLM → 程序）
```
DecideInput:
task: str # 任务简述
source: str # 来源文档
items: list[DecideItem] # 待定项列表
DecideItem:
id: int # 待定项 ID
title: str # 问题标题
location: Location | None # 原文位置（可选）
context: str | None # 详细说明（可选）
options: list[Option] # 选项列表
recommend: str | None # 推荐选项的 value（可选）
Location:
file: str # 文件路径
start: int # 起始行
end: int # 结束行
Option:
value: str # 选项标识
label: str # 选项描述
score: int | None # 评分（可选）
pros: list[str] | None # 优点列表（可选）
cons: list[str] | None # 缺点列表（可选）
```
### 5.2 输出格式（程序 → LLM）
```
DecideOutput:
decisions: list[Decision] # 决策列表
Decision:
id: int # 待定项 ID
chosen: str # 选中的选项 value
note: str | None # 用户备注（可选）
```
### 5.3 方法签名原型
```
class DecideServer:
root: Path
port: int # 默认 3721
pending_path: Path # .aide/decisions/pending.json
decisions_dir: Path # .aide/decisions/
submit(json_data: str) -> bool
# 提交待定项数据，启动服务
get_result() -> DecideOutput | None
# 获取决策结果
_parse_input(json_data: str) -> DecideInput
# 解析输入 JSON
_validate_input(data: DecideInput) -> bool
# 验证输入格式
_start_server() -> None
# 启动 HTTP 服务
_stop_server() -> None
# 停止 HTTP 服务
_save_pending(data: DecideInput) -> None
# 保存待定项数据
_save_result(result: DecideOutput) -> None
# 保存决策结果
_load_result() -> DecideOutput | None
# 加载决策结果
```
### 5.4 Web 界面组件
```
DecideApp:
# React 前端应用
state:
items: list[DecideItem] # 待定项列表
decisions: dict[int, str] # 当前选择
notes: dict[int, str] # 用户备注
methods:
loadItems() -> None # 加载待定项
selectOption(id, value) -> None # 选择选项
addNote(id, note) -> None # 添加备注
submit() -> None # 提交决策
```
---
## 六、Web 界面设计
### 6.1 页面结构
```
┌─────────────────────────────────────────────────┐
│ Aide 待定项确认 │
│ 任务: <task> │
├─────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────┐ │
│ │ 1. <title> │ │
│ │ <context> │ │
│ │ │ │
│ │ ○ <option_a.label> [推荐] │ │
│ │ 优点: ... 缺点: ... │ │
│ │ │ │
│ │ ○ <option_b.label> │ │
│ │ 优点: ... 缺点: ... │ │
│ │ │ │
│ │ 备注: [________________] │ │
│ └─────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────┐ │
│ │ 2. <title> │ │
│ │ ... │ │
│ └─────────────────────────────────────────┘ │
│ │
│ [提交决策] │
└─────────────────────────────────────────────────┘
```
### 6.2 交互流程
1. 页面加载时从后端获取待定项数据
2. 用户点击选项进行选择
3. 用户可选择性添加备注
4. 点击"提交决策"按钮
5. 前端发送决策到后端
6. 后端保存结果并关闭服务
7. 页面显示"决策已提交"
---
## 七、依赖
| 依赖项 | 类型 | 说明 |
|--------|------|------|
| output | 内部模块 | 输出格式化 |
| http.server | 标准库 | HTTP 服务 |
| json | 标准库 | JSON 解析 |
---
## 八、被依赖
| 依赖方 | 说明 |
|--------|------|
| /aide:prep | 调用 decide 处理待定项 |
---
## 九、修改指南
### 9.1 修改输入/输出格式
1. 更新本文档的数据结构章节
2. 修改代码实现
3. 同步更新 [数据格式文档](../formats/data.md)
4. 同步更新 [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)
### 9.2 修改 Web 界面
1. 更新本文档的界面设计章节
2. 修改 `aide/decide/web/` 下的前端代码
### 9.3 修改端口配置
1. 在配置文件中添加端口配置项
2. 修改 `DecideServer` 读取配置
3. 更新 [配置格式文档](../formats/config.md)
---
## 十、相关文档
- [program 导览](../README.md)
- [数据格式文档](../formats/data.md)
- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)
- [/aide:prep 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/prep.md)

257
aide-program/docs/commands/env.md Normal file
View File

@@ -0,0 +1,257 @@
# aide env 子命令设计文档
## 一、背景
### 1.1 解决的问题
| 问题 | 影响 |
|------|------|
| 环境不一致 | 命令执行失败，打断业务流程 |
| 手动检查繁琐 | 每次都要检查 Python、虚拟环境、依赖 |
| 修复方式不统一 | 不同人有不同的修复习惯 |
### 1.2 设计目标
提供**统一的环境检测与修复**：
- 自动检测环境问题
- 能修复的自动修复
- 不能修复的给出明确建议
---
## 二、职责
### 2.1 做什么
1. 检测 Python 版本是否满足要求
2. 检测 uv 是否可用
3. 检测/创建虚拟环境
4. 安装依赖
5. 输出项目配置信息
### 2.2 不做什么
- 不修改业务代码
- 不执行业务逻辑
- 不进行流程追踪
---
## 三、接口规格
### 3.1 命令语法
```
aide env ensure [--runtime]
```
### 3.2 参数
| 参数 | 类型 | 说明 |
|------|------|------|
| `--runtime` | 可选 | 仅检查 aide 运行时环境，不依赖配置文件 |
### 3.3 输出
**成功（runtime 模式）**：
```
✓ 运行时环境就绪 (python:3.12, uv:0.4.0)
```
**成功（完整模式）**：
```
→ 任务原文档: task-now.md
→ 任务细则文档: task-spec.md
✓ 环境就绪 (python:3.12, uv:0.4.0, venv:.venv)
```
**自动修复**：
```
→ 创建虚拟环境: .venv
✓ 已创建虚拟环境
⚠ 未找到 requirements.txt，已创建空文件
→ 安装依赖（uv pip install -r requirements.txt）
✓ 环境就绪 (python:3.12, uv:0.4.0, venv:.venv)
```
**失败**：
```
✗ Python 版本不足，要求>=3.11，当前 3.9
```
```
✗ 未检测到 uv，请先安装（FileNotFoundError）
```
---
## 四、业务流程
```
@startuml
skinparam defaultFontName "PingFang SC"
start
if (--runtime 参数?) then (是)
:required_py = "3.11" (硬编码);
else (否)
:从配置文件读取 required_py;
endif
:检查 Python 版本;
if (版本满足?) then (是)
else (否)
:输出错误信息;
stop
endif
:检查 uv 可用性;
if (uv 可用?) then (是)
else (否)
:输出错误信息;
stop
endif
if (--runtime 参数?) then (是)
:输出运行时环境就绪;
stop
endif
:读取配置文件;
:确保 .gitignore 包含 .aide/;
:读取 venv 路径配置;
if (虚拟环境存在?) then (是)
else (否)
:使用 uv venv 创建;
if (创建成功?) then (是)
else (否)
:输出错误信息;
stop
endif
endif
:读取 requirements 路径配置;
if (requirements.txt 存在?) then (是)
else (否)
:创建空文件;
:输出警告;
endif
:使用 uv pip install 安装依赖;
if (安装成功?) then (是)
else (否)
:输出错误信息;
stop
endif
:输出任务文档路径配置;
:输出环境就绪;
stop
@enduml
```
---
## 五、数据结构
### 5.1 配置依赖
从 `.aide/config.toml` 读取：
```
[runtime]
python_min # Python 最低版本要求
[env]
venv # 虚拟环境路径
requirements # 依赖文件路径
[task]
source # 任务原文档路径
spec # 任务细则文档路径
```
### 5.2 方法签名原型
```
class EnvManager:
root: Path # 项目根目录
ensure(runtime_only: bool, cfg: ConfigManager) -> bool
# 主入口，返回是否成功
_get_required_python(cfg: ConfigManager, runtime_only: bool) -> str
# 获取 Python 版本要求
_parse_version(version: str) -> tuple[int, ...]
# 解析版本号字符串
_check_python_version(required: str) -> bool
# 检查 Python 版本
_check_uv() -> str | None
# 检查 uv，返回版本号或 None
_ensure_venv(venv_path: Path) -> bool
# 确保虚拟环境存在
_ensure_requirements_file(req_path: Path) -> None
# 确保 requirements.txt 存在
_install_requirements(venv_path: Path, req_path: Path) -> bool
# 安装依赖
```
---
## 六、依赖
| 依赖项 | 类型 | 说明 |
|--------|------|------|
| ConfigManager | 内部模块 | 配置读写 |
| output | 内部模块 | 输出格式化 |
| uv | 外部工具 | 虚拟环境和依赖管理 |
---
## 七、被依赖
| 依赖方 | 说明 |
|--------|------|
| /aide:init | 调用 env ensure --runtime 和 env ensure |
| aide init | 内部可能调用 env 检查 |
---
## 八、修改指南
### 8.1 修改检测逻辑
1. 更新本文档的业务流程图
2. 修改 `aide/env/ensure.py`
3. 如有新的输出，更新输出示例
### 8.2 添加新的检测项
1. 在本文档添加检测项说明
2. 在 `EnvManager` 添加对应方法
3. 在 `ensure()` 中调用
4. 更新 [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)
### 8.3 修改配置依赖
1. 更新本文档的"配置依赖"章节
2. 修改代码实现
3. 同步更新 [配置格式文档](../formats/config.md)
---
## 九、相关文档
- [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)

387
aide-program/docs/commands/flow.md Normal file
View File

@@ -0,0 +1,387 @@
# aide flow 子命令设计文档
## 一、背景
### 1.1 解决的问题
| 问题 | 影响 |
|------|------|
| 状态记录分散 | 难以追踪任务进度 |
| git 提交不规范 | 提交信息不一致，难以追溯 |
| 流程跳跃 | 遗漏重要环节 |
| 返工无记录 | 问题原因和解决方案丢失 |
### 1.2 设计目标
提供**统一的进度追踪与版本控制**：
- 自动记录状态变化
- 自动执行 git add + commit
- 校验流程跳转合理性
- 环节特定行为（如 PlantUML 校验）
---
## 二、职责
### 2.1 做什么
1. 记录任务执行状态（环节、步骤）
2. 自动执行 git add . && git commit
3. 校验环节跳转是否符合预期流程
4. 在特定环节执行特定行为（如校验 PlantUML）
### 2.2 不做什么
- 不执行业务逻辑
- 不进行任务分析
- 不修改业务代码
---
## 三、接口规格
### 3.1 aide flow start
**用途**：开始新任务
**语法**：
```
aide flow start <环节名> "<总结>"
```
**参数**：
| 参数 | 说明 |
|------|------|
| `<环节名>` | task-optimize / flow-design |
| `<总结>` | 本次操作的简要说明 |
**输出**：
```
✓ 任务开始: <环节名>
```
### 3.2 aide flow next-step
**用途**：记录小步骤前进
**语法**：
```
aide flow next-step "<总结>"
```
**输出**：静默（成功无输出）
### 3.3 aide flow back-step
**用途**：记录小步骤回退
**语法**：
```
aide flow back-step "<原因>"
```
**输出**：静默（成功无输出）
### 3.4 aide flow next-part
**用途**：进入下一个大环节
**语法**：
```
aide flow next-part <环节名> "<总结>"
```
**输出**：
```
✓ 进入环节: <环节名>
```
**特殊行为**：
- 离开 `flow-design` 时：校验 PlantUML 语法，生成 PNG
- 进入 `docs` 时：提示更新 CHANGELOG
- 离开 `docs` 时：校验 CHANGELOG 是否已更新
### 3.5 aide flow back-part
**用途**：回退到之前的大环节
**语法**：
```
aide flow back-part <环节名> "<原因>"
```
**输出**：
```
⚠ 回退到环节: <环节名>
```
### 3.6 aide flow issue
**用途**：记录一般问题（不阻塞继续）
**语法**：
```
aide flow issue "<描述>"
```
**输出**：静默（成功无输出）
### 3.7 aide flow error
**用途**：记录严重错误（需要解决）
**语法**：
```
aide flow error "<描述>"
```
**输出**：
```
✗ 错误已记录: <描述>
```
---
## 四、业务流程
### 4.1 状态记录流程
```
@startuml
skinparam defaultFontName "PingFang SC"
start
:接收命令和参数;
:读取当前状态;
note right: .aide/flow-status.json
:校验操作合法性;
if (合法?) then (是)
else (否)
:输出错误信息;
stop
endif
:更新状态文件;
:执行 git add .;
:生成提交信息;
note right: [aide] <环节>: <总结>
:执行 git commit;
if (环节特定行为?) then (是)
:执行特定行为;
endif
:输出结果;
stop
@enduml
```
### 4.2 流程校验规则
```
@startuml
skinparam defaultFontName "PingFang SC"
[*] --> task_optimize : start (prep阶段)
[*] --> flow_design : start (exec阶段)
task_optimize --> task_optimize : next-step
task_optimize --> [*] : 完成prep
flow_design --> flow_design : next-step
flow_design --> impl : next-part
impl --> impl : next-step
impl --> flow_design : back-part
impl --> verify : next-part
verify --> verify : next-step
verify --> impl : back-part
verify --> docs : next-part
docs --> docs : next-step
docs --> verify : back-part
docs --> finish : next-part
finish --> finish : next-step
finish --> [*] : 完成exec
@enduml
```
**校验规则**：
- `next-part` 只能前进到相邻环节或回退
- 不允许跳过环节（如 flow-design → finish）
- `back-part` 可以回退到任意之前的环节
---
## 五、数据结构
### 5.1 状态文件格式
位置：`.aide/flow-status.json`
```
FlowStatus:
task_id: str # 任务标识（时间戳）
current_phase: str # 当前环节名
current_step: int # 当前步骤序号
started_at: str # 开始时间（ISO格式）
history: list[HistoryEntry] # 历史记录
HistoryEntry:
timestamp: str # 时间戳
action: str # 操作类型（start/next-step/next-part/...）
phase: str # 环节名
step: int # 步骤序号
summary: str # 总结/原因
git_commit: str | None # git commit hash
```
### 5.2 方法签名原型
```
class FlowTracker:
root: Path
status_path: Path # .aide/flow-status.json
start(phase: str, summary: str) -> bool
# 开始新任务
next_step(summary: str) -> bool
# 记录步骤前进
back_step(reason: str) -> bool
# 记录步骤回退
next_part(phase: str, summary: str) -> bool
# 进入下一环节
back_part(phase: str, reason: str) -> bool
# 回退到之前环节
issue(description: str) -> bool
# 记录一般问题
error(description: str) -> bool
# 记录严重错误
_load_status() -> FlowStatus | None
# 加载状态文件
_save_status(status: FlowStatus) -> None
# 保存状态文件
_validate_transition(from_phase: str, to_phase: str) -> bool
# 校验环节跳转
_git_commit(message: str) -> str | None
# 执行 git add + commit，返回 commit hash
_run_phase_hooks(phase: str, entering: bool) -> None
# 执行环节特定行为
```
### 5.3 Git 集成
```
class GitIntegration:
root: Path
add_all() -> bool
# git add .
commit(message: str) -> str | None
# git commit -m "..."，返回 commit hash
get_status() -> str
# git status -sb
```
### 5.4 流程校验
```
class FlowValidator:
PHASE_ORDER: list[str] # 环节顺序定义
VALID_TRANSITIONS: dict # 有效跳转映射
validate_start(phase: str) -> bool
# 校验 start 操作
validate_next_part(from_phase: str, to_phase: str) -> bool
# 校验 next-part 操作
validate_back_part(from_phase: str, to_phase: str) -> bool
# 校验 back-part 操作
```
---
## 六、环节特定行为
| 触发时机 | 行为 |
|----------|------|
| 离开 flow-design | 校验 PlantUML 语法，生成 PNG |
| 进入 docs | 输出提示：请更新 CHANGELOG |
| 离开 docs | 校验 CHANGELOG 是否已更新 |
---
## 七、依赖
| 依赖项 | 类型 | 说明 |
|--------|------|------|
| ConfigManager | 内部模块 | 读取配置 |
| output | 内部模块 | 输出格式化 |
| git | 外部工具 | 版本控制 |
| plantuml | 外部工具 | 流程图生成（可选） |
---
## 八、被依赖
| 依赖方 | 说明 |
|--------|------|
| /aide:prep | 调用 flow start、next-step |
| /aide:exec | 调用 flow next-part、next-step、issue、error |
---
## 九、修改指南
### 9.1 修改环节定义
1. 更新本文档的流程校验规则图
2. 修改 `FlowValidator.PHASE_ORDER` 和 `VALID_TRANSITIONS`
3. 同步更新 [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)
### 9.2 添加环节特定行为
1. 在本文档添加行为说明
2. 在 `_run_phase_hooks()` 中实现
3. 更新相关 Command 设计文档
### 9.3 修改状态文件格式
1. 更新本文档的数据结构章节
2. 修改代码实现
3. 同步更新 [数据格式文档](../formats/data.md)
---
## 十、相关文档
- [program 导览](../README.md)
- [数据格式文档](../formats/data.md)
- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)
- [/aide:prep 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/prep.md)
- [/aide:exec 命令设计](../../../aide-marketplace/aide-plugin/docs/commands/exec.md)

221
aide-program/docs/commands/init.md Normal file
View File

@@ -0,0 +1,221 @@
# 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)

176
aide-program/docs/formats/config.md Normal file
View File

@@ -0,0 +1,176 @@
# 配置文件格式规范
## 一、概述
aide 使用 TOML 格式的配置文件，位于 `.aide/config.toml`。
配置文件采用**自文档化**设计，包含详细注释说明各字段用途。
---
## 二、文件位置
```
.aide/
└── config.toml
```
---
## 三、完整配置结构
```toml
# Aide 默认配置（由 aide init 生成）
# runtime: aide 自身运行要求
[runtime]
python_min = "3.11" # Python 最低版本要求
use_uv = true # 是否使用 uv 管理依赖
# task: 任务文档路径
[task]
source = "task-now.md" # 任务原文档默认路径
spec = "task-spec.md" # 任务细则文档默认路径
# env: 虚拟环境与依赖配置
[env]
venv = ".venv" # 虚拟环境路径
requirements = "requirements.txt" # 依赖文件路径
# flow: 流程配置
[flow]
phases = ["task-optimize", "flow-design", "impl", "verify", "docs", "finish"]
```
---
## 四、字段详解
### 4.1 [runtime] 运行时配置
| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `python_min` | string | `"3.11"` | Python 最低版本要求 |
| `use_uv` | bool | `true` | 是否使用 uv 管理虚拟环境和依赖 |
**使用场景**：
- `aide env ensure --runtime` 使用硬编码的 `"3.11"`
- `aide env ensure` 读取 `python_min` 进行检查
### 4.2 [task] 任务文档配置
| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `source` | string | `"task-now.md"` | 任务原文档默认路径 |
| `spec` | string | `"task-spec.md"` | 任务细则文档默认路径 |
**使用场景**：
- `/aide:prep` 未传参数时，使用 `source` 作为默认路径
- `/aide:exec` 未传参数时，使用 `spec` 作为默认路径
- `aide env ensure` 输出这两个路径供 LLM 记录
### 4.3 [env] 环境配置
| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `venv` | string | `".venv"` | 虚拟环境目录路径 |
| `requirements` | string | `"requirements.txt"` | 依赖文件路径 |
**使用场景**：
- `aide env ensure` 检查/创建虚拟环境
- `aide env ensure` 安装依赖
### 4.4 [flow] 流程配置
| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `phases` | array | `["task-optimize", "flow-design", "impl", "verify", "docs", "finish"]` | 环节名称列表 |
**使用场景**：
- `aide flow` 校验环节跳转合法性
- 定义有效的环节名称
---
## 五、配置读写接口
### 5.1 读取配置
```bash
aide config get <key>
```
**示例**：
```bash
aide config get task.source
# 输出: → task.source = 'task-now.md'
aide config get flow.phases
# 输出: → flow.phases = ['task-optimize', 'flow-design', 'impl', 'verify', 'docs', 'finish']
aide config get runtime.python_min
# 输出: → runtime.python_min = '3.11'
```
### 5.2 设置配置
```bash
aide config set <key> <value>
```
**示例**：
```bash
aide config set task.source "my-task.md"
# 输出: ✓ 已更新 task.source = 'my-task.md'
aide config set runtime.python_min "3.12"
# 输出: ✓ 已更新 runtime.python_min = '3.12'
```
**值类型自动解析**：
- `true` / `false` → bool
- 纯数字 → int
- 带小数点的数字 → float
- 其他 → string
---
## 六、配置访问规则
### 6.1 LLM 不直接读取配置文件
**原则**：LLM 不允许直接读取 `.aide/config.toml` 文件内容，避免污染上下文。
**正确做法**：通过 `aide config get <key>` 读取需要的配置值。
### 6.2 配置缺失处理
- 配置文件不存在时，`aide config get` 输出警告并返回空
- 配置项不存在时，`aide config get` 输出警告
- 建议先执行 `aide init` 确保配置文件存在
---
## 七、扩展配置
### 7.1 添加新配置项
1. 在本文档添加字段说明
2. 更新 `ConfigManager` 中的 `DEFAULT_CONFIG`
3. 在相关代码中读取新配置
4. 更新相关设计文档
### 7.2 配置项命名规范
- 使用小写字母和下划线
- 使用点号分隔层级：`section.key`
- 保持语义清晰
---
## 八、相关文档
- [program 导览](../README.md)
- [aide init 设计](../commands/init.md)
- [aide env 设计](../commands/env.md)
- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)

360
aide-program/docs/formats/data.md Normal file
View File

@@ -0,0 +1,360 @@
# 数据格式规范
## 一、概述
本文档定义 aide 系统中使用的各种数据格式，包括：
- 待定项数据格式（aide decide）
- 流程状态格式（aide flow）
- 决策记录格式
---
## 二、待定项数据格式
### 2.1 输入格式（LLM → aide decide）
LLM 调用 `aide decide '<json>'` 时传入的数据格式。
```
DecideInput:
task: string # 任务简述
source: string # 来源文档路径
items: DecideItem[] # 待定项列表
DecideItem:
id: number # 待定项 ID（唯一标识）
title: string # 问题标题
location?: Location # 原文位置（可选）
context?: string # 详细说明（可选）
options: Option[] # 选项列表（至少2个）
recommend?: string # 推荐选项的 value（可选）
Location:
file: string # 文件路径
start: number # 起始行号
end: number # 结束行号
Option:
value: string # 选项标识（用于返回结果）
label: string # 选项描述（显示给用户）
score?: number # 评分 0-100（可选）
pros?: string[] # 优点列表（可选）
cons?: string[] # 缺点列表（可选）
```
**示例**：
```json
{
"task": "实现用户认证模块",
"source": "task-now.md",
"items": [
{
"id": 1,
"title": "认证方式选择",
"location": {
"file": "task-now.md",
"start": 5,
"end": 7
},
"context": "任务描述中未明确指定认证方式，需要确认",
"options": [
{
"value": "jwt",
"label": "JWT Token 认证",
"score": 85,
"pros": ["无状态", "易于扩展", "跨域友好"],
"cons": ["Token 无法主动失效", "需要处理刷新"]
},
{
"value": "session",
"label": "Session 认证",
"score": 70,
"pros": ["实现简单", "可主动失效"],
"cons": ["需要存储", "扩展性差"]
}
],
"recommend": "jwt"
},
{
"id": 2,
"title": "密码加密算法",
"context": "选择密码存储的加密算法",
"options": [
{
"value": "bcrypt",
"label": "bcrypt",
"score": 90,
"pros": ["安全性高", "自带盐值"],
"cons": ["计算较慢"]
},
{
"value": "argon2",
"label": "Argon2",
"score": 95,
"pros": ["最新标准", "抗GPU攻击"],
"cons": ["库支持较少"]
}
],
"recommend": "bcrypt"
}
]
}
```
### 2.2 输出格式（aide decide result → LLM）
LLM 调用 `aide decide result` 时返回的数据格式。
```
DecideOutput:
decisions: Decision[] # 决策列表
Decision:
id: number # 待定项 ID
chosen: string # 选中的选项 value
note?: string # 用户备注（可选，仅在用户填写时出现）
```
**示例**：
```json
{
"decisions": [
{"id": 1, "chosen": "jwt"},
{"id": 2, "chosen": "bcrypt", "note": "团队更熟悉 bcrypt"}
]
}
```
---
## 三、流程状态格式
### 3.1 状态文件格式
位置：`.aide/flow-status.json`
```
FlowStatus:
task_id: string # 任务标识（时间戳格式）
current_phase: string # 当前环节名
current_step: number # 当前步骤序号
started_at: string # 开始时间（ISO 8601 格式）
history: HistoryEntry[] # 历史记录
HistoryEntry:
timestamp: string # 时间戳（ISO 8601 格式）
action: string # 操作类型
phase: string # 环节名
step: number # 步骤序号
summary: string # 总结/原因
git_commit?: string # git commit hash（可选）
```
**操作类型（action）**：
- `start` - 开始任务
- `next-step` - 步骤前进
- `back-step` - 步骤回退
- `next-part` - 环节前进
- `back-part` - 环节回退
- `issue` - 记录问题
- `error` - 记录错误
**示例**：
```json
{
"task_id": "2025-01-15T10-30-00",
"current_phase": "impl",
"current_step": 5,
"started_at": "2025-01-15T10:30:00+08:00",
"history": [
{
"timestamp": "2025-01-15T10:30:00+08:00",
"action": "start",
"phase": "flow-design",
"step": 1,
"summary": "开始任务: 实现用户认证模块",
"git_commit": "a1b2c3d"
},
{
"timestamp": "2025-01-15T10:45:00+08:00",
"action": "next-step",
"phase": "flow-design",
"step": 2,
"summary": "流程图设计完成",
"git_commit": "e4f5g6h"
},
{
"timestamp": "2025-01-15T11:00:00+08:00",
"action": "next-part",
"phase": "impl",
"step": 3,
"summary": "流程设计完成，开始实现",
"git_commit": "i7j8k9l"
},
{
"timestamp": "2025-01-15T11:30:00+08:00",
"action": "issue",
"phase": "impl",
"step": 4,
"summary": "测试覆盖率较低，后续需要补充",
"git_commit": "m0n1o2p"
},
{
"timestamp": "2025-01-15T12:00:00+08:00",
"action": "next-step",
"phase": "impl",
"step": 5,
"summary": "完成用户模型定义",
"git_commit": "q3r4s5t"
}
]
}
```
---
## 四、决策记录格式
### 4.1 存储位置
```
.aide/
└── decisions/
├── pending.json # 当前待处理的待定项
└── 2025-01-15T10-30-00.json # 历史决策记录
```
### 4.2 待处理文件格式
位置：`.aide/decisions/pending.json`
内容：与输入格式相同（DecideInput）
### 4.3 历史记录格式
位置：`.aide/decisions/{timestamp}.json`
```
DecisionRecord:
input: DecideInput # 原始输入
output: DecideOutput # 决策结果
completed_at: string # 完成时间（ISO 8601 格式）
```
**示例**：
```json
{
"input": {
"task": "实现用户认证模块",
"source": "task-now.md",
"items": [...]
},
"output": {
"decisions": [
{"id": 1, "chosen": "jwt"},
{"id": 2, "chosen": "bcrypt", "note": "团队更熟悉 bcrypt"}
]
},
"completed_at": "2025-01-15T10:35:00+08:00"
}
```
---
## 五、Git 提交信息格式
### 5.1 自动提交格式
aide flow 自动生成的提交信息格式：
```
[aide] <环节>: <总结>
```
**示例**：
```
[aide] flow-design: 开始任务: 实现用户认证模块
[aide] flow-design: 流程图设计完成
[aide] impl: 流程设计完成，开始实现
[aide] impl: 完成用户模型定义
[aide] verify: 验证通过
[aide] docs: 更新 CHANGELOG
[aide] finish: 任务完成
```
### 5.2 问题/错误记录
```
[aide] <环节> issue: <描述>
[aide] <环节> error: <描述>
```
### 5.3 回退记录
```
[aide] <环节> back-step: <原因>
[aide] <环节> back-part: <原因>
```
---
## 六、时间格式
所有时间字段使用 **ISO 8601** 格式：
```
YYYY-MM-DDTHH:mm:ss+HH:00
```
**示例**：
```
2025-01-15T10:30:00+08:00
```
文件名中的时间戳使用简化格式（避免特殊字符）：
```
YYYY-MM-DDTHH-mm-ss
```
**示例**：
```
2025-01-15T10-30-00
```
---
## 七、修改指南
### 7.1 修改待定项格式
1. 更新本文档的"待定项数据格式"章节
2. 修改 `aide/decide/` 相关代码
3. 同步更新 [aide decide 设计](../commands/decide.md)
4. 同步更新 [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)
### 7.2 修改流程状态格式
1. 更新本文档的"流程状态格式"章节
2. 修改 `aide/flow/` 相关代码
3. 同步更新 [aide flow 设计](../commands/flow.md)
### 7.3 添加新的数据格式
1. 在本文档添加新章节
2. 定义数据结构
3. 提供示例
4. 更新相关设计文档
---
## 八、相关文档
- [program 导览](../README.md)
- [aide flow 设计](../commands/flow.md)
- [aide decide 设计](../commands/decide.md)
- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)