✨ feat: 完成aide flow设计

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
+- 不推进环节，不产生提交（保持原子性）