102 lines
3.1 KiB
Markdown
102 lines
3.1 KiB
Markdown
# aide-program-flow
|
||
|
||
> 路径：aide-program/aide/flow/
|
||
> 最后更新：2025-12-15
|
||
|
||
## 概述
|
||
|
||
进度追踪模块，提供任务流程管理、Git 自动提交、环节校验和 Hooks 支持。
|
||
|
||
## 文件清单
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `__init__.py` | 模块初始化 |
|
||
| `tracker.py` | FlowTracker 主逻辑（~200 行） |
|
||
| `storage.py` | 状态文件读写（~147 行） |
|
||
| `types.py` | 数据结构定义（~103 行） |
|
||
| `validator.py` | 环节校验器（~50 行） |
|
||
| `git.py` | Git 集成（~75 行） |
|
||
| `hooks.py` | pre/post commit 钩子（~125 行） |
|
||
| `errors.py` | 自定义异常 |
|
||
| `utils.py` | 工具函数 |
|
||
|
||
## 核心组件
|
||
|
||
### FlowTracker
|
||
|
||
- **职责**：编排一次 flow 动作（校验 → hooks → git → 落盘 → 输出）
|
||
- **位置**：`tracker.py:20`
|
||
- **关键方法**：
|
||
- `start(phase, summary)` - 开始新任务
|
||
- `next_step(summary)` - 记录步骤前进
|
||
- `back_step(reason)` - 记录步骤回退
|
||
- `next_part(phase, summary)` - 进入下一环节
|
||
- `back_part(phase, reason)` - 回退到之前环节
|
||
- `issue(description)` - 记录一般问题
|
||
- `error(description)` - 记录严重错误
|
||
|
||
### FlowStorage
|
||
|
||
- **职责**：状态文件的读写、锁定和归档
|
||
- **位置**：`storage.py:16`
|
||
- **关键方法**：
|
||
- `lock()` - 上下文管理器，获取文件锁
|
||
- `load_status()` - 加载当前任务状态
|
||
- `save_status(status)` - 保存状态（原子写入）
|
||
- `archive_existing_status()` - 归档旧状态到 logs/
|
||
- `list_all_tasks()` - 列出所有任务
|
||
- `load_task_by_id(task_id)` - 按 ID 加载任务
|
||
|
||
### FlowValidator
|
||
|
||
- **职责**：校验环节跳转合法性
|
||
- **位置**：`validator.py`
|
||
- **校验规则**：
|
||
- `next_part`: 只能跳转到相邻的下一环节
|
||
- `back_part`: 可以回退到任意之前的环节
|
||
- `start`: 必须从有效环节开始
|
||
|
||
### 数据结构
|
||
|
||
- `FlowStatus` - 任务状态（task_id, current_phase, current_step, history）
|
||
- `HistoryEntry` - 历史条目（timestamp, action, phase, step, summary, git_commit）
|
||
|
||
## 接口说明
|
||
|
||
```python
|
||
# CLI 入口
|
||
aide flow start <phase> "<summary>" # 开始任务
|
||
aide flow next-step "<summary>" # 步骤前进
|
||
aide flow back-step "<reason>" # 步骤回退
|
||
aide flow next-part <phase> "<summary>" # 进入下一环节
|
||
aide flow back-part <phase> "<reason>" # 回退环节
|
||
aide flow issue "<description>" # 记录问题
|
||
aide flow error "<description>" # 记录错误
|
||
aide flow status # 查看当前状态
|
||
aide flow list # 列出所有任务
|
||
aide flow show <task_id> # 查看任务详情
|
||
```
|
||
|
||
## Git 集成
|
||
|
||
每次 flow 操作自动执行：
|
||
1. `git add .`
|
||
2. `git commit -m "[aide] <phase>: <summary>"`
|
||
|
||
提交信息格式：
|
||
- 正常操作：`[aide] impl: 完成数据库模型设计`
|
||
- 问题记录：`[aide] impl issue: 测试覆盖率低`
|
||
- 错误记录：`[aide] impl error: 数据库连接失败`
|
||
|
||
## 依赖关系
|
||
|
||
- 依赖：core（output, config）
|
||
- 被依赖：main.py
|
||
|
||
## 注意事项
|
||
|
||
- 状态文件使用文件锁防止并发写入
|
||
- 归档文件保存在 `.aide/logs/` 目录
|
||
- Hooks 支持 PlantUML 自动校验和构建
|