sayurinana/agent-aide

Fork 0

Files

sayurinana(vm) 4838b91def [aide] impl: 子计划3 文档和Skill更新完成

2025-12-17 04:12:10 +08:00

11 KiB

Raw Blame History

aide flow 子命令设计文档

零、详细设计文档包

本文档为概览设计；更细的实现交接规格见：

一、背景

1.1 解决的问题

问题	影响
状态记录分散	难以追踪任务进度
git 提交不规范	提交信息不一致，难以追溯
流程跳跃	遗漏重要环节
返工无记录	问题原因和解决方案丢失

1.2 设计目标

提供统一的进度追踪与版本控制：

自动记录状态变化
自动执行 git add + commit
校验流程跳转合理性
环节特定行为（如 PlantUML 校验）

二、职责

2.1 做什么

记录任务执行状态（环节、步骤）
自动执行 git add . && git commit
校验环节跳转是否符合预期流程
在特定环节执行特定行为（如校验 PlantUML）

2.2 不做什么

不执行业务逻辑
不进行任务分析
不修改业务代码

三、接口规格

3.1 aide flow start

用途：开始新任务

语法：

aide flow start <环节名> "<总结>"

参数：

参数	说明
`<环节名>`	来自 `flow.phases`（默认：task-optimize / flow-design / impl / verify / docs / finish）
`<总结>`	本次操作的简要说明

输出：

✓ 任务开始: <环节名>

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 "<描述>"

输出：

✗ 错误已记录: <描述>

3.8 aide flow status

用途：查看当前任务状态

语法：

aide flow status

输出：

→ 当前任务: <task_id>
→ 环节: <current_phase>
→ 步骤: <current_step>
→ 开始时间: <started_at>

无活跃任务时：

→ 无活跃任务

3.9 aide flow list

用途：列出所有任务（当前 + 已归档）

语法：

aide flow list

输出：

→ 当前任务:
  <task_id> (<current_phase>, step <n>)

→ 已归档任务:
  <task_id_1> (finish)
  <task_id_2> (finish)

3.10 aide flow show

用途：查看指定任务的详细信息

语法：

aide flow show <task_id>

输出：

→ 任务: <task_id>
→ 环节: <current_phase>
→ 步骤: <current_step>
→ 开始时间: <started_at>

→ 历史记录:
  [1] <timestamp> <action> <phase> step=<n>: <summary>
  [2] ...

四、业务流程

4.1 状态记录流程

@startuml
skinparam defaultFontName "PingFang SC"

start

:接收命令和参数;

:读取配置;
note right: flow.phases

:读取当前状态;
note right: .aide/flow-status.json

:校验操作合法性;
if (合法?) then (是)
else (否)
  :输出错误信息;
  stop
endif

if (需要环节钩子?) then (是)
  :执行 pre-commit hooks;
  if (通过?) then (是)
  else (否)
    :输出错误信息;
    stop
  endif
endif

:执行 git add .;

:生成提交信息;
note right: [aide] <环节>: <总结>

:执行 git commit（若启用）;
note right: 无变更可提交时不视为失败\ngit_commit = null

:更新并原子落盘状态文件;

if (需要环节钩子?) then (是)
  :执行 post-commit hooks;
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]  # 历史记录
    source_branch: str | None # 源分支名（分支管理）
    start_commit: str | None  # 起始提交（分支管理）
    task_branch: str | None   # 任务分支名（分支管理）

HistoryEntry:
    timestamp: str            # 时间戳
    action: str               # 操作类型（start/next-step/next-part/...）
    phase: str                # 环节名
    step: int                 # 步骤序号
    summary: str              # 总结/原因
    git_commit: str | None    # git commit hash（无变更可提交/未启用 git 时为空）

5.2 分支概况文件格式

位置：.aide/branches.json 和 .aide/branches.md

BranchesData:
    next_number: int          # 下一个分支编号
    branches: list[BranchInfo]  # 分支记录列表

BranchInfo:
    number: int               # 分支编号
    branch_name: str          # 分支名（aide/NNN）
    source_branch: str        # 源分支名
    start_commit: str         # 起始提交
    end_commit: str | None    # 结束提交
    task_id: str              # 任务 ID
    task_summary: str         # 任务摘要
    started_at: str           # 开始时间
    finished_at: str | None   # 结束时间
    status: str               # 状态（active/finished/merged-to-temp）
    temp_branch: str | None   # 临时分支名（仅安全合并时）

5.3 方法签名原型

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:
    phases: list[str]         # 从配置 flow.phases 读取

    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 是否已更新

详细触发点与顺序见：aide-program/docs/commands/flow/hooks.md

七、依赖

依赖项	类型	说明
ConfigManager	内部模块	读取配置
output	内部模块	输出格式化
git	外部工具	版本控制
plantuml	外部工具	流程图生成（可选）

八、被依赖

依赖方	说明
/aide:run	调用 flow start、next-part、next-step、status、issue、error
/aide:load	调用 flow status 检查任务状态

九、修改指南

9.1 修改环节定义

修改 flow.phases（见 aide-program/docs/formats/config.md）
更新本文档的流程校验规则图（如需）
更新 aide-program/docs/commands/flow/validation.md（默认状态机示例）
同步更新 aide skill 设计文档

11 KiB

Raw Blame History

aide flow 子命令设计文档

零、详细设计文档包

一、背景

1.1 解决的问题

1.2 设计目标

二、职责

2.1 做什么

2.2 不做什么

三、接口规格

3.1 aide flow start

3.2 aide flow next-step

3.3 aide flow back-step

3.4 aide flow next-part

3.5 aide flow back-part

3.6 aide flow issue

3.7 aide flow error

3.8 aide flow status

3.9 aide flow list

3.10 aide flow show

四、业务流程

4.1 状态记录流程

4.2 流程校验规则

五、数据结构

5.1 状态文件格式

5.2 分支概况文件格式

5.3 方法签名原型

5.3 Git 集成

5.4 流程校验

六、环节特定行为

七、依赖

八、被依赖

九、修改指南

9.1 修改环节定义

9.2 添加环节特定行为

9.3 修改状态文件格式

十、相关文档

11 KiB Raw Blame History Unescape Escape

aide flow 子命令设计文档

零、详细设计文档包

一、背景

1.1 解决的问题

1.2 设计目标

二、职责

2.1 做什么

2.2 不做什么

三、接口规格

3.1 aide flow start

3.2 aide flow next-step

3.3 aide flow back-step

3.4 aide flow next-part

3.5 aide flow back-part

3.6 aide flow issue

3.7 aide flow error

3.8 aide flow status

3.9 aide flow list

3.10 aide flow show

四、业务流程

4.1 状态记录流程

4.2 流程校验规则

五、数据结构

5.1 状态文件格式

5.2 分支概况文件格式

5.3 方法签名原型

5.3 Git 集成

5.4 流程校验

六、环节特定行为

七、依赖

八、被依赖

九、修改指南

9.1 修改环节定义

9.2 添加环节特定行为

9.3 修改状态文件格式

十、相关文档

11 KiB

Raw Blame History