sayurinana/agent-aide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3e7781e1459f71502977030726b5192c6f73c051
agent-aide/.aide/project-docs/blocks/aide-program-flow.md

5.4 KiB
Raw Blame History

aide-program-flow

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

概述

进度追踪和流程控制模块，负责管理任务执行流程、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 源码 模块初始化
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 类

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

FlowStorage 类

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

GitIntegration 类

  • 职责：封装 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 类

  • 职责：流程校验，验证环节跳转合法性
  • 位置：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

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", "发现设计遗漏")

默认环节列表

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

依赖关系

  • 依赖：aide/core（ConfigManager、output）
  • 被依赖：aide/main.py

注意事项

  • 每次 flow 操作都会自动执行 git add + commit
  • 状态文件使用文件锁防止并发冲突
  • next-part 只能前进到相邻环节
  • back-part 可以回退到任意之前的环节
  • 离开 flow-design 时会自动校验和生成 PlantUML 图
  • 离开 docs 时会验证 CHANGELOG.md 已更新