83 lines
3.2 KiB
Markdown
83 lines
3.2 KiB
Markdown
# 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 共享同一个任务状态文件。
|