3.2 KiB
3.2 KiB
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 错误信息要求
错误输出需要包含：
- 失败原因（尽量具体到参数/文件/外部命令）
- 建议下一步（如“请先运行 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 共享同一个任务状态文件。