语言无关的实现指南，供 AI 工具用任意编程语言重新实现本系统。
一个两阶段自动化工作流编排系统，协调 AI 代码助手执行复杂任务：
- 规划阶段 - AI 分析任务，生成编号的计划文件
- 执行阶段 - 按顺序执行每个计划，支持验证和重试
任务输入 → 规划 → 验证 → 执行计划1 → 验证 → 执行计划2 → ... → 完成
↓ ↓ ↓
重试(3次) 重试(3次) 重试(3次)
↓ ↓ ↓
人工介入 人工介入 人工介入
| 组件 | 职责 |
|---|---|
| 编排器 (Orchestrator) | 主控制器，协调整个工作流 |
| AI 运行器 (Runner) | 启动 AI CLI 子进程，捕获输出 |
| 计划管理器 (Plan Manager) | 发现、追踪计划文件 |
| 验证器 (Verifier) | 用另一个 AI 实例验证输出 |
| 状态管理器 (State Manager) | 持久化工作流状态到文件 |
| 会话记录器 (Memory Manager) | 记录会话日志 |
| TCP 服务器 | 接收插件的停止通知 |
| 插件生成器 | 生成 AI 工具的钩子插件 |
- 工作目录、计划目录、会话目录、状态文件路径
- TCP 服务器地址和端口（默认 127.0.0.1:9527）
- 最大重试次数（默认 3）
- 各阶段超时时间
- AI CLI 命令
- 当前阶段：
idle | planning | executing | completed | failed | waiting_human - 当前计划名称、重试次数、任务描述、错误信息
- 文件路径、编号（0,1,2...）、名称、状态（pending/executing/completed/failed）
- 命名格式：
NNN-name.md（如000-setup.md）
AI 执行后必须输出的 JSON：
completed: 是否完成
summary: 简要描述
files_created: 新建的文件
files_modified: 修改的文件
issues: 遇到的问题
next_steps: 后续建议
验证 AI 输出的 JSON：
verified: 是否通过
checks: [{name, passed, message}, ...]
issues: 问题列表
suggestion: 修复建议
任务描述: {task}
[如果是重试: 上次失败原因: {error}，请换种方法]
要求:
1. 分析任务，分解为独立子任务
2. 在 docs/plans/ 创建编号的计划文件 (000-xxx.md, 001-xxx.md)
3. 每个计划包含：目标、步骤、预期输出、验收标准
完成后必须输出 JSON 状态报告到指定文件
计划内容: {plan_content}
[如果是重试: 上次失败原因: {error}，请换种方法]
要求:
1. 按计划执行任务
2. 遇到问题尝试自行解决
3. 确认验收标准达成
完成后必须输出 JSON 状态报告
原始任务: {task}
生成的计划: {all_plans}
验证标准:
- 计划是否覆盖任务所有方面
- 步骤是否清晰可执行
- 是否有遗漏或空白
- 分解是否合理有序
输出 JSON 验证报告
计划: {plan}
执行状态报告: {status}
验证标准:
- 是否标记完成
- 文件是否已创建/修改
- 是否有未解决问题
输出 JSON 验证报告
- 初始化：创建目录、加载状态、生成插件（如不存在）
- 启动 TCP 服务器监听停止通知
- 规划阶段：调用 AI 生成计划 → 验证 → 失败则重试
- 执行阶段：依次执行每个计划 → 验证 → 失败则重试
- 重试耗尽时请求人工介入
- 记录会话日志，保存最终状态
重试计数 = 0
循环（重试计数 < 最大重试）:
构建 prompt（含上次错误信息）
运行 AI
读取状态报告
若状态报告显示未完成 → 记录错误，重试
若未生成计划文件 → 记录错误，重试
若计划文件为空 → 记录错误，重试
调用验证 AI 检查计划质量
若验证失败 → 记录错误，重试
成功 → 返回
重试耗尽 → 请求人工介入
对每个待执行的计划:
重试计数 = 0
循环（重试计数 < 最大重试）:
构建 prompt（含计划内容和上次错误）
运行 AI
读取状态报告
若状态报告显示未完成 → 记录错误，重试
调用验证 AI 检查执行结果
若验证失败 → 记录错误，重试
成功 → 标记计划完成，继续下一个
重试耗尽 → 请求人工介入
- 用子进程启动 AI CLI：
ai_command -p "prompt" - 流式输出到控制台，同时捕获完整输出
- 处理超时、进程退出码
- 保存：将状态对象序列化为 JSON 写入文件
- 加载：读取文件反序列化，文件不存在则返回默认状态
- 支持中断恢复
当 AI 会话结束时，通知编排器。
{plugin_dir}/
├── manifest.json # 插件元数据
└── hooks/
├── config.json # 钩子配置，指定 Stop 事件触发脚本
└── stop_hook # 停止钩子脚本
- 检查状态文件是否存在（判断是否有活动工作流）
- 读取当前阶段
- 创建 TCP 连接，发送 JSON 通知：
{type: "stop", phase: "...", timestamp: "..."} - 允许 AI 正常退出
- 服务器监听 localhost:9527
- 接收 JSON 消息，触发回调
- 响应
{"status": "ok"}或{"status": "error", "message": "..."}
{工作目录}/
├── docs/
│ ├── plans/ # 计划文件
│ │ ├── 000-setup.md
│ │ ├── 001-implement.md
│ │ └── ...
│ └── memory/ # 会话日志
│ └── session-YYYY-MM-DD.md
│
├── .state/
│ ├── workflow.state.json # 工作流状态
│ └── status.json # AI 输出的状态报告（临时）
│
└── .plugins/
└── workflow/ # 插件
├── manifest.json
└── hooks/
├── config.json
└── stop_hook
| 命令 | 功能 |
|---|---|
run <task> |
运行工作流 |
run -f <file> |
从文件读取任务 |
status |
查看当前状态 |
plans |
列出计划文件 |
resume |
恢复中断的工作流 |
clean |
清理状态文件 |
clean --all |
同时清理计划文件 |
可选参数：-d 工作目录、--max-retries 重试次数、--port TCP 端口
- 每个阶段独立计数
- 重试时将上次错误传给 AI："上次失败原因: xxx，请换种方法"
- 默认最多 3 次
- 重试耗尽后暂停，等待用户输入
- 用户可选择继续（重置重试计数）或终止
- CLI 入口，支持各命令
- 两阶段工作流
- 计划文件发现和追踪（
NNN-name.md格式） - JSON 状态报告解析
- AI 验证机制
- 智能重试（携带错误上下文）
- 状态持久化和恢复
- 人工介入机制
- 跨平台（Windows/Linux/macOS）
- UTF-8 编码
- 超时处理
- 实时输出显示
- 仅使用标准库：JSON、文件系统、子进程、TCP 网络、正则、命令行解析
- 唯一外部依赖：目标 AI CLI 工具
- 两阶段分离 - 规划与执行分离，便于验证和重试
- 结构化输出 - JSON 格式确保可靠解析
- AI 验证 AI - 用另一个 AI 实例检查输出质量
- 智能重试 - 携带错误上下文让 AI 调整策略
- 状态持久化 - 支持中断恢复
- 最小依赖 - 便于跨平台移植
- 插件架构 - 与 AI CLI 工具集成