✨ feat: 完成aide flow设计

2025-12-14 21:55:56 +08:00
parent a48fbb5fae
commit a0c9173bc4
9 changed files with 821 additions and 15 deletions
--- a/aide-program/docs/commands/flow.md
+++ b/aide-program/docs/commands/flow.md
@@ -1,5 +1,17 @@
 # aide flow 子命令设计文档

+## 零、详细设计文档包
+
+本文档为概览设计；更细的实现交接规格见：
+
+- [aide-program/docs/commands/flow/README.md](flow/README.md)
+- [aide-program/docs/commands/flow/cli.md](flow/cli.md)
+- [aide-program/docs/commands/flow/state-and-storage.md](flow/state-and-storage.md)
+- [aide-program/docs/commands/flow/validation.md](flow/validation.md)
+- [aide-program/docs/commands/flow/git.md](flow/git.md)
+- [aide-program/docs/commands/flow/hooks.md](flow/hooks.md)
+- [aide-program/docs/commands/flow/verification.md](flow/verification.md)
+
 ## 一、背景

 ### 1.1 解决的问题
@@ -53,7 +65,7 @@ aide flow start <环节名> "<总结>"

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

 **输出**：
@@ -155,6 +167,9 @@ start

 :接收命令和参数;

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

@@ -165,17 +180,27 @@ else (否)
  stop
 endif

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

 :执行 git add .;

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

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

-if (环节特定行为?) then (是)
-  :执行特定行为;
+:更新并原子落盘状态文件;
+
+if (需要环节钩子?) then (是)
+  :执行 post-commit hooks;
 endif

 :输出结果;
@@ -244,7 +269,7 @@ HistoryEntry:
    phase: str                # 环节名
    step: int                 # 步骤序号
    summary: str              # 总结/原因
-    git_commit: str | None    # git commit hash
+    git_commit: str | None    # git commit hash（无变更可提交/未启用 git 时为空）
 ```

 ### 5.2 方法签名原型
@@ -311,8 +336,7 @@ class GitIntegration:

 ```
 class FlowValidator:
-    PHASE_ORDER: list[str]    # 环节顺序定义
-    VALID_TRANSITIONS: dict   # 有效跳转映射
+    phases: list[str]         # 从配置 flow.phases 读取

    validate_start(phase: str) -> bool
        # 校验 start 操作
@@ -334,6 +358,8 @@ class FlowValidator:
 | 进入 docs | 输出提示：请更新 CHANGELOG |
 | 离开 docs | 校验 CHANGELOG 是否已更新 |

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

 ## 七、依赖
@@ -360,9 +386,10 @@ class FlowValidator:

 ### 9.1 修改环节定义

-1. 更新本文档的流程校验规则图
-2. 修改 `FlowValidator.PHASE_ORDER` 和 `VALID_TRANSITIONS`
-3. 同步更新 [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)
+1. 修改 `flow.phases`（见 `aide-program/docs/formats/config.md`）
+2. 更新本文档的流程校验规则图（如需）
+3. 更新 `aide-program/docs/commands/flow/validation.md`（默认状态机示例）
+4. 同步更新 [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)

 ### 9.2 添加环节特定行为

@@ -381,6 +408,7 @@ class FlowValidator:
 ## 十、相关文档

 - [program 导览](../README.md)
+- [flow 详细设计（交接包）](flow/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)
--- a/aide-program/docs/commands/flow/README.md
+++ b/aide-program/docs/commands/flow/README.md
@@ -0,0 +1,68 @@
+# aide flow 详细设计（实现交接包）
+
+本目录为 `aide flow` 子命令的**详细设计**。目标是让接手开发者在不阅读额外上下文的情况下，能够依据本文档集完成实现、联调与验证。
+
+上游/关联文档：
+- 概览设计：[`aide-program/docs/commands/flow.md`](../flow.md)
+- 数据格式规范（状态文件、提交信息）：[`aide-program/docs/formats/data.md`](../../formats/data.md)
+- 配置格式规范（flow.phases）：[`aide-program/docs/formats/config.md`](../../formats/config.md)
+- 插件侧调用契约：[`/aide:prep`](../../../../aide-marketplace/aide-plugin/docs/commands/prep.md)、[`/aide:exec`](../../../../aide-marketplace/aide-plugin/docs/commands/exec.md)
+
+## 一、范围与目标
+
+### 1.1 目标
+
+- 以“静默即成功”为输出原则，提供统一的**进度追踪**与**Git 自动提交**能力
+- 将任务执行过程结构化为“环节（phase）+ 步骤（step）+ 历史（history）”
+- 对环节跳转进行校验，降低流程跳跃与遗漏
+- 在特定环节提供可插拔的行为（Hooks），例如 PlantUML 校验/生成与 CHANGELOG 校验
+
+### 1.2 非目标
+
+- 不做任务分析/方案选择（这是 plugin 的职责）
+- 不实现业务功能
+- 不接管项目的 Git 工作流策略（仅提供最小、可配置的自动化提交）
+
+## 二、关键约定（必须先统一）
+
+1. **环节来源**：以 `flow.phases` 为准（见 `aide-program/docs/formats/config.md`），默认值覆盖 prep+exec 全流程。
+2. **.aide 默认被 gitignore**：状态文件属于本地数据；Git 提交用于记录项目文件变化，状态历史中的 `git_commit` 仅做关联。
+3. **“无变更可提交”不是错误**：当工作区无可提交变更时，`aide flow` 仍应完成状态记录，但 `git_commit` 为空。
+4. **钩子顺序影响提交内容**：会产生/修改文件的钩子必须在 `git add/commit` 之前执行，才能进入同一次提交。
+5. **失败边界**：校验失败/关键钩子失败应阻止状态推进；Git 失败的处理需要在 `git.md` 中按“必须/可选”策略定义。
+
+## 三、文档索引（按实现模块拆分）
+
+- CLI 与输出：[`aide-program/docs/commands/flow/cli.md`](cli.md)
+- 状态与落盘：[`aide-program/docs/commands/flow/state-and-storage.md`](state-and-storage.md)
+- 流程校验：[`aide-program/docs/commands/flow/validation.md`](validation.md)
+- Git 集成：[`aide-program/docs/commands/flow/git.md`](git.md)
+- Hooks 机制：[`aide-program/docs/commands/flow/hooks.md`](hooks.md)
+- 验证清单：[`aide-program/docs/commands/flow/verification.md`](verification.md)
+
+## 四、推荐实现模块划分（仅文件/职责约定）
+
+建议在 `aide-program/aide/flow/` 下按职责拆分：
+
+- `tracker`：编排一次 flow 操作（校验 → hooks → git → 落盘 → 输出）
+- `validator`：环节/动作校验（基于 phases 列表）
+- `git`：Git 操作封装（add/commit/status/判定“无变更”）
+- `hooks`：内置 hook 与 hook 调度
+- `types`：状态结构（与 `aide-program/docs/formats/data.md` 一致）
+
+> 注：本文档只约定职责与接口，不提供实现代码。
+
+## 五、实现任务拆分（建议顺序）
+
+1. 完成状态结构与读写：按 `state-and-storage.md` 约定实现原子写入与锁
+2. 完成校验器：按 `validation.md` 对 start/next-part/back-part 等动作校验
+3. 完成 Git 封装：按 `git.md` 处理 repo 探测、提交信息、无变更/失败策略
+4. 完成 Hooks：按 `hooks.md` 实现 PlantUML/CHANGELOG 等内置钩子
+5. 完成 CLI 路由：在 `aide-program/aide/main.py` 增加 `aide flow ...` 子命令树
+6. 逐条对照 `verification.md` 做验证（至少覆盖“无变更”“非 git 仓库”“校验失败”）
+
+## 六、风险与待定项（需要开发前确认）
+
+- “每次 flow 操作都提交”会产生大量提交：是否需要通过配置提供降噪策略（如仅在 next-part 时提交）
+- PlantUML/PNG 是否应纳入提交：默认建议纳入，但需要与团队仓库习惯一致
+- CHANGELOG 校验规则的严格程度：硬失败还是警告（建议可配置）
--- a/aide-program/docs/commands/flow/cli.md
+++ b/aide-program/docs/commands/flow/cli.md
@@ -0,0 +1,82 @@
+# aide flow CLI 规格
+
+## 一、命令一览
+
+`aide flow` 由若干动作型子命令组成（每次调用记录一次历史，并尝试执行一次 Git 自动提交）：
+
+| 子命令 | 语法（API 约定） | 成功输出 | 主要用途 |
+|---|---|---|---|
+| start | `aide flow start <phase> "<summary>"` | 输出 `✓ 任务开始: <phase>` | 开始新任务（创建/重置状态） |
+| next-step | `aide flow next-step "<summary>"` | 静默 | 记录一个小步骤完成 |
+| back-step | `aide flow back-step "<reason>"` | 静默 | 记录一次小步骤回退 |
+| next-part | `aide flow next-part <phase> "<summary>"` | 输出 `✓ 进入环节: <phase>` | 前进进入下一环节 |
+| back-part | `aide flow back-part <phase> "<reason>"` | 输出 `⚠ 回退到环节: <phase>` | 回退到之前环节 |
+| issue | `aide flow issue "<description>"` | 静默 | 记录一般问题（不阻塞继续） |
+| error | `aide flow error "<description>"` | 输出 `✗ 错误已记录: <description>` | 记录严重错误（需要用户关注） |
+
+> 说明：`<summary>/<reason>/<description>` 建议由调用方负责加引号，避免空格导致参数截断。
+
+## 二、参数校验规则
+
+### 2.1 phase 校验
+
+- `<phase>` 必须是 `flow.phases` 列表中的一个元素
+- `next-part` 的 `<phase>` 必须是当前环节的**相邻下一环节**
+- `back-part` 的 `<phase>` 必须出现在当前环节之前（允许回退到任意之前环节）
+
+细则见：`aide-program/docs/commands/flow/validation.md`
+
+### 2.2 文本参数校验
+
+- `<summary>/<reason>/<description>` 不能为空字符串
+- 建议限制最大长度（例如 200~500 字符），超出时返回错误并提示调用方缩短（防止 commit message 过长）
+
+## 三、输出规范（与现有 core/output 保持一致）
+
+### 3.1 静默原则
+
+- **无输出 = 正常完成**
+- 仅在需要“阶段确认/回退提醒/错误可见化”时输出
+
+### 3.2 固定前缀
+
+沿用 `aide-program/docs/README.md` 的输出规范：
+
+- 成功：`✓`
+- 警告：`⚠`
+- 失败：`✗`
+- 信息：`→`（仅在需要解释下一步时使用）
+
+### 3.3 错误信息要求
+
+错误输出需要包含：
+
+1. 失败原因（尽量具体到参数/文件/外部命令）
+2. 建议下一步（如“请先运行 aide init”“请检查 flow.phases 配置”）
+
+## 四、退出码（与主程序一致）
+
+| 退出码 | 含义 |
+|---:|---|
+| 0 | 成功（含“无变更可提交”的情况） |
+| 1 | 失败（参数校验失败、流程校验失败、关键 Hook 失败、Git 必须但执行失败等） |
+
+> 说明：`aide flow error` 的 “✗” 属于**业务语义提示**；只要本次记录与（可选的）Git 操作完成，仍应返回 0。
+
+## 五、典型调用序列（契约）
+
+### 5.1 prep 阶段（/aide:prep）
+
+- `aide flow start task-optimize "开始任务准备: <任务简述>"`
+- 若干次 `aide flow next-step "<...>"`
+
+### 5.2 exec 阶段（/aide:exec）
+
+- `aide flow next-part flow-design "进入流程设计环节"`
+- 若干次 `aide flow next-step "<...>"`
+- `aide flow next-part impl "..."`
+- `aide flow next-part verify "..."`
+- `aide flow next-part docs "..."`
+- `aide flow next-part finish "..."`
+
+> 注意：exec 使用 `next-part` 进入 `flow-design`，意味着 prep 与 exec 共享同一个任务状态文件。
--- a/aide-program/docs/commands/flow/git.md
+++ b/aide-program/docs/commands/flow/git.md
@@ -0,0 +1,90 @@
+# Git 集成设计（GitIntegration）
+
+## 一、目标与原则
+
+### 1.1 目标
+
+- 让调用方无需手动执行 `git add/commit` 也能得到规范提交
+- 将“进度节点”与“提交记录”关联：在状态历史中记录 `git_commit`（可为空）
+
+### 1.2 原则
+
+- **静默即成功**：Git 正常执行时尽量不输出额外信息
+- **.aide 默认不进提交**：Git 记录的是代码/文档等实际产出，状态文件仅做本地追踪
+- **无变更可提交 ≠ 失败**：当工作区没有可提交变更时，本次记录仍然成功，`git_commit = null`
+
+## 二、提交信息生成规则（必须一致）
+
+提交信息格式以 `aide-program/docs/formats/data.md` 的“Git 提交信息格式”为准。
+
+核心模板：
+
+- 普通：`[aide] <phase>: <summary>`
+- issue：`[aide] <phase> issue: <description>`
+- error：`[aide] <phase> error: <description>`
+- back-step：`[aide] <phase> back-step: <reason>`
+- back-part：`[aide] <phase> back-part: <reason>`
+
+> 说明：`phase` 使用“动作完成后的 current_phase”，以保证 status 与 commit message 一致。
+
+## 三、暂存（add）策略
+
+默认策略（与现有文档保持一致）：
+
+- 执行 `git add .`（由 `.gitignore` 控制忽略项）
+
+可选增强（建议实现时评估，避免误提交）：
+
+- 仅暂存已跟踪文件：等价于“只更新 tracked 的变更”
+- 在提交前检查 `git status`，对明显异常（如大量生成文件）给出 `⚠` 提示
+
+## 四、事务边界（状态与 Git 的一致性）
+
+### 4.1 推荐边界
+
+一次 `aide flow` 调用视为一个“原子动作”：
+
+- 校验失败/关键 Hook 失败：不应推进状态，也不应提交
+- Git 必须但执行失败：不应推进状态（避免“状态已前进但提交缺失”）
+- 无变更可提交：允许推进状态，`git_commit = null`
+
+### 4.2 “无变更可提交”的判定
+
+当出现“nothing to commit / working tree clean”等语义时：
+
+- 视为成功，不返回错误
+- 仍写入状态历史，但 `git_commit` 为空
+
+## 五、失败与降级策略
+
+### 5.1 非 git 仓库
+
+若当前目录不在 git 仓库内：
+
+- **默认建议：失败**（提示用户初始化 git 或切换到正确目录）
+- 可配置降级：仅记录状态，不做 git（见 5.3）
+
+### 5.2 git 命令不可用/异常
+
+若 git 不存在或执行报错：
+
+- 默认失败，并输出具体错误与建议
+
+### 5.3 可配置项（建议加入 flow 配置）
+
+为满足不同团队习惯，建议在 `flow` 下增加可选配置（若不实现则使用默认行为）：
+
+| 配置键（建议） | 类型 | 默认值（建议） | 说明 |
+|---|---:|---:|---|
+| `flow.git.enabled` | bool | true | 是否启用 Git 集成 |
+| `flow.git.required` | bool | true | 启用后是否“必须成功”，否则降级为仅记录 |
+| `flow.git.allow_empty_commit` | bool | false | 是否允许创建空提交（用于记录纯流程节点） |
+| `flow.git.add_strategy` | string | `"dot"` | 暂存策略：`dot`（git add .）/ 其它策略（可扩展） |
+
+> 若 `allow_empty_commit = true`，则“无变更”场景也会产生 commit；需要评估对仓库历史的影响。
+
+## 六、与 Hooks 的顺序关系
+
+会产生/修改文件的钩子（如 PlantUML 生成 PNG）必须在 Git add/commit 之前执行，否则生成物不会进入本次提交。
+
+详细触发点见：`aide-program/docs/commands/flow/hooks.md`
--- a/aide-program/docs/commands/flow/hooks.md
+++ b/aide-program/docs/commands/flow/hooks.md
@@ -0,0 +1,127 @@
+# 环节钩子（Hooks）设计
+
+## 一、目标
+
+Hooks 用于在特定环节触发特定行为，常见用途：
+
+- 环节离开时做强校验（阻止流程跳转）
+- 自动生成/更新辅助产物（如 PlantUML PNG）
+- 给出必要提醒（如进入 docs 提示更新 CHANGELOG）
+
+## 二、触发点与顺序（必须统一）
+
+### 2.1 触发点
+
+Hooks 只在以下场景触发：
+
+- `start`：视为“进入某个 phase”
+- `next-part` / `back-part`：同时发生“离开旧 phase”与“进入新 phase”
+
+`next-step/back-step/issue/error` 默认不触发 phase hooks（除非后续明确新增需求）。
+
+### 2.2 顺序（影响提交内容）
+
+为保证“生成物进入同一次提交”，推荐顺序：
+
+1. **流程校验**（见 `validation.md`）
+2. **离开旧 phase 的 pre-commit hooks**（可能生成/修改文件，失败则阻止跳转）
+3. **Git add/commit**（见 `git.md`）
+4. **写入状态文件**（包含本次 `git_commit`）
+5. **进入新 phase 的 post-commit hooks**（提醒类/信息类为主）
+
+> 若团队选择“先落盘再提交”，必须重新评估：失败边界、生成物提交时机、以及 `git_commit` 的写入方式。
+
+## 三、Hook 接口约定（伪代码原型）
+
+```
+HookContext:
+    root: Path
+    phases: list[str]
+    from_phase: str | None
+    to_phase: str
+    action: str                  # start/next-part/back-part
+    summary: str
+
+HookResult:
+    ok: bool
+    level: "info" | "warn" | "error"
+    message: str
+```
+
+约定：
+
+- pre-commit hook 失败（ok=false 且 level=error）必须阻止流程跳转
+- warn/info 只允许在“需要用户可见”时输出，且保持简短
+
+## 四、内置 Hooks 规格
+
+### 4.1 离开 flow-design：PlantUML 校验与 PNG 生成（pre-commit）
+
+**触发**：
+
+- `next-part` 且 `from_phase == "flow-design"`
+
+**目标**：
+
+- 校验 PlantUML 语法
+- 生成 PNG（若配置启用）
+
+**输入约定（建议可配置）**：
+
+| 配置项（建议） | 默认值（建议） | 说明 |
+|---|---|---|
+| `flow.hooks.plantuml.enabled` | true | 是否启用该 hook |
+| `flow.hooks.plantuml.glob` | `docs/**/*.puml;docs/**/*.plantuml;discuss/**/*.puml;discuss/**/*.plantuml` | 待处理文件范围（分号分隔或列表） |
+| `flow.hooks.plantuml.on_missing_tool` | `"warn"` | 未安装 plantuml 的处理：warn/error |
+| `flow.hooks.plantuml.generate_png` | true | 是否生成 PNG |
+
+**行为约定**：
+
+- 若未匹配到任何 PlantUML 文件：静默通过
+- 若 plantuml 工具缺失：
+  - `on_missing_tool=warn`：输出一次 `⚠` 提示并通过
+  - `on_missing_tool=error`：失败并阻止跳转
+- 若语法校验失败：失败并阻止跳转（输出指出具体文件）
+
+### 4.2 进入 docs：提醒更新 CHANGELOG（post-commit）
+
+**触发**：
+
+- `next-part` 且 `to_phase == "docs"`
+
+**行为约定**：
+
+- 输出一次 `→ 请更新 CHANGELOG.md`（保持一句话）
+- 不影响状态推进与提交
+
+### 4.3 离开 docs：校验 CHANGELOG 已更新（pre-commit）
+
+**触发**：
+
+- `next-part` 且 `from_phase == "docs"`
+
+**校验目标**：
+
+- 确保在 docs 阶段，至少有一次提交包含 `CHANGELOG.md` 的改动
+
+**推荐实现判定（不引入额外状态字段）**：
+
+1. 从状态历史中找出 `phase == "docs"` 且 `git_commit` 非空的条目集合
+2. 遍历这些提交，判断是否有任意一次提交包含 `CHANGELOG.md`
+
+**降级处理**：
+
+- 若 Git 集成未启用/不可用：至少校验 `CHANGELOG.md` 文件存在，否则失败或警告（建议可配置）
+
+**配置项（建议）**：
+
+| 配置项（建议） | 默认值（建议） | 说明 |
+|---|---|---|
+| `flow.hooks.changelog.path` | `CHANGELOG.md` | changelog 路径 |
+| `flow.hooks.changelog.required` | true | 离开 docs 时是否硬失败 |
+
+## 五、Hook 失败的对外表现
+
+- 校验类 hook 失败：输出 `✗` + 简短原因 + 下一步建议（例如“请先修复 PlantUML 语法”）
+- 返回退出码 1
+- 不推进环节，不产生提交（保持原子性）
--- a/aide-program/docs/commands/flow/state-and-storage.md
+++ b/aide-program/docs/commands/flow/state-and-storage.md
@@ -0,0 +1,125 @@
+# 状态模型与存储设计
+
+## 一、状态文件（源规范）
+
+状态文件的数据结构以 `aide-program/docs/formats/data.md` 的“流程状态格式”为准：
+
+- 位置：`.aide/flow-status.json`
+- 顶层结构：`FlowStatus`
+- 历史条目：`HistoryEntry`
+
+本文档补充**字段语义**与**落盘/并发/容错**约定。
+
+## 二、字段语义（实现必须遵守）
+
+### 2.1 task_id
+
+- 生成时机：`aide flow start` 调用时生成
+- 语义：标识一次“任务”的全生命周期（覆盖 prep + exec）
+- 格式：与 `aide-program/docs/formats/data.md` 的时间戳约定一致
+
+### 2.2 current_phase
+
+- 语义：当前所处环节名称
+- 取值：必须在 `flow.phases` 中
+- 变更来源：`start`、`next-part`、`back-part`
+
+### 2.3 current_step
+
+为避免历史回溯混乱，建议将 `current_step` 定义为**单调递增的记录序号**：
+
+- `start` 产生第一条记录，`current_step = 1`
+- 每次成功记录一次动作（start/next-step/back-step/next-part/back-part/issue/error），`current_step += 1`
+- 不做递减（回退动作使用 action=back-step/back-part 表达）
+
+> 如果团队坚持“回退需要 step-1”，需先在全体文档中统一，并评估历史序号重复/倒序对调试的影响。
+
+### 2.4 history
+
+每次 flow 调用都会追加一个 HistoryEntry：
+
+- `timestamp`：本次记录时间（ISO 8601）
+- `action`：动作类型（与 data.md 枚举一致）
+- `phase`：本次动作完成后的 current_phase
+- `step`：本次动作完成后的 current_step
+- `summary`：摘要/原因/描述
+- `git_commit`：若本次产生了 commit，则为 commit hash，否则为空
+
+约束（建议实现中校验）：
+
+- `history[-1].phase == current_phase`
+- `history[-1].step == current_step`
+- `history` 按追加顺序即时间顺序
+
+## 三、存储生命周期
+
+### 3.1 start 行为（归档旧状态）
+
+当执行 `aide flow start` 时：
+
+- 若 `.aide/flow-status.json` 不存在：直接创建新状态
+- 若已存在：应先归档旧文件，避免无提示覆盖导致历史丢失
+
+推荐归档位置（本地数据，不纳入 git）：
+
+- `.aide/logs/flow-status.<old_task_id>.json`
+
+### 3.2 其它动作行为
+
+除 `start` 外的命令要求：
+
+- 状态文件必须存在，否则返回错误并建议先运行 `aide flow start ...` 或执行 `/aide:prep`
+
+## 四、并发与原子性（落盘必须可靠）
+
+### 4.1 互斥（锁）
+
+为避免并发调用导致状态文件损坏，`aide flow` 在读写前必须获得独占锁。
+
+推荐方案（跨平台、实现简单）：
+
+- 锁文件：`.aide/flow-status.lock`
+- 加锁：以“创建新文件（独占）”方式获取
+- 释放：删除锁文件
+
+约定：
+
+- 获取锁失败时：短暂重试（例如总计 2~3 秒），仍失败则返回错误 `✗ 状态文件被占用`
+- 异常退出时：应尽力清理锁（并允许人工删除）
+
+### 4.2 原子写入
+
+必须避免写一半导致 JSON 损坏：
+
+1. 写入临时文件：`.aide/flow-status.json.tmp`
+2. fsync（如实现选择支持）
+3. 原子替换为目标文件：`.aide/flow-status.json`
+
+### 4.3 编码与换行
+
+- UTF-8 编码
+- 换行统一 `\n`
+- JSON 建议使用稳定排序/缩进策略（便于人工阅读与 diff），但不要依赖其格式做解析
+
+## 五、容错与恢复策略
+
+### 5.1 JSON 解析失败
+
+当状态文件存在但无法解析：
+
+- 输出错误并提示用户手动处理（例如备份后删除该文件，再重新 start）
+- 不建议在未确认的情况下自动“修复”或丢弃字段
+
+### 5.2 目录缺失
+
+若 `.aide/` 不存在：
+
+- 返回错误并提示先执行 `aide init`
+
+## 六、与 Git 的关系（重要）
+
+`.aide/` 默认在仓库 `.gitignore` 内：
+
+- 状态文件用于本地追踪，不要求进入提交
+- Git 提交用于记录真实产出（代码/文档等）
+- 若团队希望将状态文件纳入版本库，应显式调整 `.gitignore`，并在 Git 策略上达成一致
--- a/aide-program/docs/commands/flow/validation.md
+++ b/aide-program/docs/commands/flow/validation.md
@@ -0,0 +1,120 @@
+# 流程校验规则（FlowValidator）
+
+## 一、设计目标
+
+流程校验的目标是：
+
+- 防止“跳过环节”造成关键步骤遗漏
+- 允许受控回退（返工有记录）
+- 支持通过配置 `flow.phases` 调整环节名称与顺序
+
+## 二、环节来源与基础约束
+
+### 2.1 phases 来源
+
+`phases` 必须来自配置 `flow.phases`（见 `aide-program/docs/formats/config.md`）。
+
+### 2.2 基础约束
+
+- phases 列表不能为空
+- phases 中的环节名必须唯一
+- 当前状态 `current_phase` 必须属于 phases
+
+当以上条件不满足时，返回错误并提示用户修正配置或重新 start。
+
+## 三、动作级校验
+
+### 3.1 start 校验
+
+允许：
+
+- `start <phase>`：`phase` ∈ phases
+
+建议额外约束（可选，但需在实现前确认）：
+
+- 若 phase 不是 phases[0]，输出 `⚠` 提醒“从中间环节开始”
+
+### 3.2 next-step / back-step / issue / error
+
+前置条件：
+
+- 状态文件存在（已 start）
+- `current_phase` 合法
+
+行为：
+
+- 不改变 phase（phase 保持 current_phase）
+- 仅记录一次历史
+
+### 3.3 next-part 校验
+
+前置条件：
+
+- 状态文件存在（已 start）
+- `to_phase` ∈ phases
+
+允许：
+
+- `to_phase` 必须等于 phases 中 `current_phase` 的**相邻下一项**
+
+禁止：
+
+- 跳跃（例如 `flow-design → verify`）
+- 原地（例如 `impl → impl`）
+
+### 3.4 back-part 校验
+
+前置条件：
+
+- 状态文件存在（已 start）
+- `to_phase` ∈ phases
+
+允许：
+
+- `to_phase` 必须位于 `current_phase` 之前（可回退到任意之前环节）
+
+禁止：
+
+- 前进（例如 `flow-design → impl` 使用 back-part）
+- 原地（例如 `verify → verify`）
+
+## 四、默认 phases 的状态机（示例）
+
+当 `flow.phases = ["task-optimize","flow-design","impl","verify","docs","finish"]` 时，推荐状态机如下：
+
+```plantuml
+@startuml
+skinparam defaultFontName "PingFang SC"
+
+[*] --> task_optimize : start(task-optimize)\n或 start(flow-design)
+
+task_optimize --> flow_design : next-part(flow-design)
+flow_design --> impl : next-part(impl)
+impl --> verify : next-part(verify)
+verify --> docs : next-part(docs)
+docs --> finish : next-part(finish)
+
+flow_design --> task_optimize : back-part(task-optimize)
+impl --> flow_design : back-part(flow-design)
+verify --> impl : back-part(impl)
+docs --> verify : back-part(verify)
+finish --> docs : back-part(docs)
+
+task_optimize --> task_optimize : next-step/back-step/issue/error
+flow_design --> flow_design : next-step/back-step/issue/error
+impl --> impl : next-step/back-step/issue/error
+verify --> verify : next-step/back-step/issue/error
+docs --> docs : next-step/back-step/issue/error
+finish --> finish : next-step/back-step/issue/error
+
+@enduml
+```
+
+> 注：示例图允许从 `flow-design` start，以兼容“跳过 prep 直接 exec”的场景；是否默认允许由实现选择，但必须在行为与提示上保持一致。
+
+## 五、与 Hooks 的关系
+
+部分校验属于“流程校验”，部分属于“环节特定校验”（Hooks）：
+
+- 流程校验：只关心 phases 顺序与动作合法性（本文件）
+- 环节特定校验：如离开 `flow-design` 时 PlantUML 校验、离开 `docs` 时 CHANGELOG 校验（见 `hooks.md`）
--- a/aide-program/docs/commands/flow/verification.md
+++ b/aide-program/docs/commands/flow/verification.md
@@ -0,0 +1,163 @@
+# 验证清单（实现完成后的自检）
+
+本清单用于在实现 `aide flow` 后进行验证，确保行为符合设计文档与 plugin 契约。
+
+## 一、准备条件
+
+- 当前目录为一个 git 仓库（用于验证 Git 集成相关条目）
+- 已执行 `aide init`，确保 `.aide/` 与 `config.toml` 存在
+- `flow.phases` 使用默认值或明确配置（见 `aide-program/docs/formats/config.md`）
+
+## 二、核心用例
+
+### 2.1 start 新任务（无历史）
+
+步骤：
+
+1. 运行 `aide flow start task-optimize "..."`
+
+期望：
+
+- `.aide/flow-status.json` 被创建且可解析
+- `current_phase == "task-optimize"`
+- `history` 至少 1 条记录，`action == "start"`
+- 若仓库无变更：不视为失败，`git_commit` 为空
+
+### 2.2 next-step 记录步骤（静默）
+
+步骤：
+
+1. 运行 `aide flow next-step "..."`
+
+期望：
+
+- 命令成功时无输出
+- `history` 追加一条 `action == "next-step"`
+
+### 2.3 next-part 正常前进
+
+步骤：
+
+1. 从 `task-optimize` 执行 `aide flow next-part flow-design "..."`
+
+期望：
+
+- 输出 `✓ 进入环节: flow-design`
+- 状态 phase 更新为 `flow-design`
+
+### 2.4 next-part 跳跃（应失败）
+
+步骤：
+
+1. 从 `flow-design` 执行 `aide flow next-part verify "..."`
+
+期望：
+
+- 输出 `✗` 错误，明确指出“不可跳过环节”
+- 状态不应推进（仍停留在 `flow-design`）
+- 不产生新提交（若 Git 为必须）
+
+### 2.5 back-part 回退（允许回到任意之前环节）
+
+步骤：
+
+1. 从 `impl` 执行 `aide flow back-part flow-design "..."`
+
+期望：
+
+- 输出 `⚠ 回退到环节: flow-design`
+- 状态 phase 更新为 `flow-design`
+
+### 2.6 非法 back-part（向前/原地）
+
+步骤：
+
+1. 从 `flow-design` 执行 `aide flow back-part impl "..."`
+2. 从 `verify` 执行 `aide flow back-part verify "..."`
+
+期望：
+
+- 均失败并输出 `✗`
+- 状态不推进
+
+## 三、Git 集成用例
+
+### 3.1 有变更时自动提交
+
+步骤：
+
+1. 修改任意可提交文件（例如 README）
+2. 执行 `aide flow next-step "..."` 或 `next-part ...`
+
+期望：
+
+- 产生一条新 commit，commit message 符合 `aide-program/docs/formats/data.md`
+- 状态历史条目中 `git_commit` 记录该 hash
+
+### 3.2 无变更时不报错
+
+步骤：
+
+1. 确保工作区干净
+2. 执行 `aide flow next-step "..."`
+
+期望：
+
+- 成功（静默）
+- `git_commit` 为空
+
+### 3.3 Git 必须但失败（应阻止状态推进）
+
+场景示例（任选其一）：
+
+- 在非 git 目录执行 flow 命令
+- 或刻意制造 git commit 失败（例如 hook 阻止/权限问题）
+
+期望：
+
+- 返回失败（退出码 1）
+- 状态不推进（避免“状态走了但提交没走”）
+
+## 四、Hook 用例
+
+### 4.1 离开 flow-design：PlantUML 校验/生成
+
+步骤（建议最小化）：
+
+1. 在 `docs/` 或 `discuss/` 放置一个可解析的 `.puml` 文件
+2. 确保当前 phase 为 `flow-design`
+3. 执行 `aide flow next-part impl "..."`
+
+期望：
+
+- hook 被触发
+- 若配置为生成 PNG：PNG 文件被生成，并进入同一次提交（有变更时）
+
+异常用例：
+
+- `.puml` 语法错误：应失败并阻止跳转
+
+### 4.2 进入 docs：提醒更新 CHANGELOG
+
+步骤：
+
+1. 从 `verify` 执行 `aide flow next-part docs "..."`
+
+期望：
+
+- 输出一次 `→` 提醒（一句话）
+
+### 4.3 离开 docs：校验 CHANGELOG 已更新
+
+步骤：
+
+1. 在 docs 阶段对 `CHANGELOG.md` 做一次修改并产生至少一次提交
+2. 执行 `aide flow next-part finish "..."`
+
+期望：
+
+- 校验通过并允许进入 finish
+
+异常用例：
+
+- docs 阶段未提交任何包含 `CHANGELOG.md` 的变更：按配置应失败或警告（见 `hooks.md`）