[aide] task-optimize: 开始任务准备: 优化 docs.md 命令实现完整深度探索

2025-12-17 02:28:46 +08:00
parent 3efff299d5
commit c805da7a90
14 changed files with 973 additions and 559 deletions
--- a/.aide/project-docs/blocks/aide-program-flow.md
+++ b/.aide/project-docs/blocks/aide-program-flow.md
@@ -1,32 +1,47 @@
 # aide-program-flow

 > 路径：aide-program/aide/flow/
-> 最后更新：2025-12-16
+> 最后更新：2025-12-17

 ## 概述

-进度追踪模块，提供任务流程管理、Git 自动提交、环节校验和 Hooks 支持。
+进度追踪和流程控制模块，负责管理任务执行流程、Git 集成和环节钩子。采用状态机模式，支持环节跳转校验、自动 Git 提交和 PlantUML 流程图验证。
+
+## 目录结构
+
+```
+aide-program/aide/flow/
+├── __init__.py              模块初始化
+├── types.py                 数据结构定义
+├── errors.py                错误类型
+├── tracker.py               流程追踪器
+├── storage.py               状态文件读写
+├── git.py                   Git 操作封装
+├── hooks.py                 环节钩子
+├── validator.py             流程校验
+└── utils.py                 工具函数
+```

 ## 文件清单

-| 文件 | 说明 |
-|------|------|
-| `__init__.py` | 模块初始化 |
-| `tracker.py` | FlowTracker 主逻辑（~220 行） |
-| `storage.py` | 状态文件读写（~147 行） |
-| `types.py` | 数据结构定义（~103 行） |
-| `validator.py` | 环节校验器（~50 行） |
-| `git.py` | Git 集成（~75 行） |
-| `hooks.py` | pre/post commit 钩子（~125 行） |
-| `errors.py` | 自定义异常 |
-| `utils.py` | 工具函数 |
+| 文件 | 类型 | 说明 |
+|------|------|------|
+| __init__.py | 源码 | 模块初始化 |
+| types.py | 源码 | FlowStatus、HistoryEntry 数据类 |
+| errors.py | 源码 | FlowError 异常类 |
+| tracker.py | 源码 | FlowTracker 核心类，编排流程动作 |
+| storage.py | 源码 | FlowStorage 类，状态文件读写和归档 |
+| git.py | 源码 | GitIntegration 类，Git 操作封装 |
+| hooks.py | 源码 | 环节钩子（PlantUML、CHANGELOG） |
+| validator.py | 源码 | FlowValidator 类，流程校验逻辑 |
+| utils.py | 源码 | 时间戳和文本处理工具 |

 ## 核心组件

-### FlowTracker
+### FlowTracker 类

 - **职责**：编排一次 flow 动作（校验 → hooks → 落盘 → git → 输出）
- **位置**：`tracker.py:20`
+- **位置**：`aide/flow/tracker.py:20`
 - **关键方法**：
  - `start(phase, summary)` - 开始新任务
  - `next_step(summary)` - 记录步骤前进
@@ -35,76 +50,126 @@
  - `back_part(phase, reason)` - 回退到之前环节
  - `issue(description)` - 记录一般问题
  - `error(description)` - 记录严重错误
-  - `_apply_action()` - 应用动作，生成新状态和 commit 消息
-  - `_do_git_commit()` - 执行 git 操作并更新 commit hash
+  - `_run()` - 核心执行逻辑
+  - `_apply_action()` - 应用动作，更新状态
+  - `_do_git_commit()` - 执行 Git 提交

-### FlowStorage
+### FlowStorage 类

- **职责**：状态文件的读写、锁定和归档
- **位置**：`storage.py:16`
+- **职责**：状态文件的读写、锁和归档
+- **位置**：`aide/flow/storage.py:16`
 - **关键方法**：
-  - `lock()` - 上下文管理器，获取文件锁
-  - `load_status()` - 加载当前任务状态
-  - `save_status(status)` - 保存状态（原子写入）
-  - `archive_existing_status()` - 归档旧状态到 logs/
+  - `ensure_ready()` - 确保 .aide 目录存在
+  - `lock()` - 文件锁上下文管理器
+  - `load_status()` - 加载当前状态
+  - `save_status()` - 保存状态（原子写入）
+  - `archive_existing_status()` - 归档旧状态
  - `list_all_tasks()` - 列出所有任务
-  - `load_task_by_id(task_id)` - 按 ID 加载任务
+  - `load_task_by_id()` - 根据 ID 加载任务

-### FlowValidator
+### GitIntegration 类

- **职责**：校验环节跳转合法性
- **位置**：`validator.py`
- **校验规则**：
-  - `next_part`: 只能跳转到相邻的下一环节
-  - `back_part`: 可以回退到任意之前的环节
-  - `start`: 必须从有效环节开始
+- **职责**：封装 Git 操作
+- **位置**：`aide/flow/git.py:12`
+- **关键方法**：
+  - `ensure_available()` - 检查 git 命令可用
+  - `ensure_repo()` - 检查是否在 git 仓库中
+  - `add_all()` - git add .
+  - `commit(message)` - git commit
+  - `rev_parse_head()` - 获取 HEAD commit hash
+  - `status_porcelain(path)` - 检查文件状态
+  - `commit_touches_path()` - 检查提交是否修改指定文件

-### 数据结构
+### FlowValidator 类

- `FlowStatus` - 任务状态（task_id, current_phase, current_step, history）
- `HistoryEntry` - 历史条目（timestamp, action, phase, step, summary, git_commit）
+- **职责**：流程校验，验证环节跳转合法性
+- **位置**：`aide/flow/validator.py:8`
+- **关键方法**：
+  - `validate_phase_exists(phase)` - 验证环节存在
+  - `validate_start(phase)` - 验证开始环节
+  - `validate_next_part(from, to)` - 验证前进跳转（只能相邻）
+  - `validate_back_part(from, to)` - 验证回退跳转（只能向前）
+
+### FlowStatus 数据类
+
+- **职责**：流程状态封装
+- **位置**：`aide/flow/types.py:50`
+- **字段**：
+  - `task_id: str` - 任务 ID（时间戳格式）
+  - `current_phase: str` - 当前环节
+  - `current_step: int` - 当前步骤号
+  - `started_at: str` - 开始时间（ISO 格式）
+  - `history: list[HistoryEntry]` - 历史记录
+
+### HistoryEntry 数据类
+
+- **职责**：历史条目封装
+- **位置**：`aide/flow/types.py:10`
+- **字段**：
+  - `timestamp: str` - 时间戳
+  - `action: str` - 动作类型
+  - `phase: str` - 环节名
+  - `step: int` - 步骤号
+  - `summary: str` - 摘要
+  - `git_commit: str | None` - Git 提交 hash
+
+## 环节钩子
+
+### PlantUML 钩子
+
+- **触发时机**：离开 flow-design 环节时（next-part/back-part）
+- **位置**：`aide/flow/hooks.py:61`
+- **功能**：
+  1. 校验 .puml/.plantuml 文件语法
+  2. 生成 PNG 图片
+  3. 检查目录：.aide/diagrams、docs、discuss
+
+### CHANGELOG 钩子
+
+- **触发时机**：离开 docs 环节时
+- **位置**：`aide/flow/hooks.py:126`
+- **功能**：验证 CHANGELOG.md 已更新

 ## 接口说明

+### 流程追踪 API
+
 ```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>                # 查看任务详情
+from aide.flow.tracker import FlowTracker
+from aide.core.config import ConfigManager
+
+cfg = ConfigManager(Path.cwd())
+tracker = FlowTracker(Path.cwd(), cfg)
+
+# 开始新任务
+tracker.start("task-optimize", "开始任务准备")
+
+# 步骤前进
+tracker.next_step("完成数据库设计")
+
+# 进入下一环节
+tracker.next_part("impl", "进入实现环节")
+
+# 回退环节
+tracker.back_part("flow-design", "发现设计遗漏")
 ```

-## Git 集成
+### 默认环节列表

-**执行顺序**（已优化）：
-1. 运行 pre_commit_hooks
-2. 更新 FlowStatus（内存）
-3. 保存状态到磁盘（flow-status.json）
-4. `git add .`
-5. `git commit -m "[aide] <phase>: <summary>"`
-6. 更新 commit hash 到状态文件
-
-> **关键改进**：状态文件先保存再执行 git 操作，确保 flow-status.json 的更新包含在 commit 中
-
-提交信息格式：
- 正常操作：`[aide] impl: 完成数据库模型设计`
- 问题记录：`[aide] impl issue: 测试覆盖率低`
- 错误记录：`[aide] impl error: 数据库连接失败`
+```python
+DEFAULT_PHASES = ["task-optimize", "flow-design", "impl", "verify", "docs", "finish"]
+```

 ## 依赖关系

- 依赖：core（output, config）
- 被依赖：main.py
+- 依赖：aide/core（ConfigManager、output）
+- 被依赖：aide/main.py

 ## 注意事项

- 状态文件使用文件锁防止并发写入
- 归档文件保存在 `.aide/logs/` 目录
- Hooks 支持 PlantUML 自动校验和构建
- Git 提交在状态保存之后执行，确保 .aide 目录变更被包含
+- 每次 flow 操作都会自动执行 git add + commit
+- 状态文件使用文件锁防止并发冲突
+- next-part 只能前进到相邻环节
+- back-part 可以回退到任意之前的环节
+- 离开 flow-design 时会自动校验和生成 PlantUML 图
+- 离开 docs 时会验证 CHANGELOG.md 已更新