Maestro-Flow：多 Agent 工作流编排框架与实时仪表盘

Maestro-Flow 是一个面向 Claude Code、Codex、Gemini 等 AI Agent 的工作流编排框架，提供自然语言路由、并行执行、实时仪表盘、自愈问题管道和演进知识图谱。

随着 AI 编程助手生态的成熟，开发者开始同时使用多个 Agent 工具——Claude Code、Codex、Gemini、OpenCode 等。每个工具都有其优势和适用场景，但如何协调它们高效协作成为一个新问题。

传统的工作方式是手动决定："这个任务用 Claude，那个任务用 Codex"，然后分别执行、手动整合结果。这种方式效率低下，容易出错，且难以追踪整体进度。

更深层的问题是，AI 辅助开发往往缺乏系统性的项目管理。没有清晰的阶段划分、没有统一的工件存储、没有实时的进度可视化——开发者像是在黑暗中摸索。

Maestro-Flow 正是为了解决这些编排挑战而设计的。它不仅仅是一个工具，而是一个完整的工作流框架，将多 Agent 开发转变为可预测、可观测、可优化的工程流程。

Maestro-Flow 的核心价值主张是自动化最耗时的部分：决定使用哪些 Agent、按什么顺序、带什么上下文。开发者只需描述意图，系统就会路由到最优的命令链，驱动并行 Agent 执行，并通过实时仪表盘闭环反馈。

框架提供两种使用模式：

自然语言模式：一句话描述需求，让 Maestro-Flow 决定完整执行链

/maestro "implement OAuth2 authentication with refresh tokens"

分步模式：逐步执行各个阶段，保持人工控制

/maestro-init        # 设置项目工作空间
/maestro-roadmap     # 交互式创建分阶段路线图
/maestro-analyze     # 多维度分析
/maestro-plan        # 生成执行计划
/maestro-execute     # 波次并行 Agent 执行
/maestro-verify      # 目标反向验证

这种灵活性使得框架既适合快速原型开发，也适合需要严格控制的企业级项目。

Maestro-Flow 定义了完整的九阶段工作流：

初始化 → 头脑风暴 → 路线图 → 分析 → 计划 → 执行 → 验证 → 审查 → 里程碑审计 → 里程碑完成 → （下一里程碑回到分析）

每个阶段都有明确的输入输出和验收标准：

初始化（init）：设置项目工作空间，建立基础目录结构

头脑风暴（brainstorm）：探索多种实现方案，收集创意和约束

路线图（roadmap）：将项目分解为可管理的里程碑，建立时间线

分析（analyze）：深入分析当前里程碑的需求、技术方案和风险

计划（plan）：生成详细的执行计划，包括任务分解和依赖关系

执行（execute）：波次并行执行，协调多个 Agent 同时工作

验证（verify）：目标反向验证，确保实现符合预期

审查（review）：代码审查和质量检查

里程碑审计（milestone-audit）：里程碑完成前的全面检查

里程碑完成（milestone-complete）：归档工件，准备下一里程碑

所有工件存储在 .workflow/scratch/ 目录，由 state.json 工件注册表跟踪。阶段是路线图中的标签，而非物理目录，保持结构清晰。

Maestro-Flow 提供三种主要执行模式：

模式	流程	适用场景
/maestro-quick	分析 → 计划 → 执行	快速修复、小功能
Scratch 模式	分析 -q → 计划 --dir → 执行 --dir	无路线图，直接执行
/maestro "..."	AI 路由的命令链	描述意图，自动决策

框架提供 49 个斜杠命令，覆盖 6 个类别，支持从项目初始化到质量回顾的全流程。

Maestro-Flow 的核心编排机制是 Commander Agent——一个后台监督器，运行 tick 循环：

评估 → 决策 → 分派 → 等待 → 评估 → ...

它读取项目状态（阶段、任务、问题、Agent 槽位），决定需要关注什么，并自动分派 Agent。支持三种配置档案：

• 保守型：谨慎决策，充分验证后才推进
• 平衡型：在速度和质量之间取得平衡
• 激进型：快速迭代，接受更高的试错成本

这种监督机制确保项目始终在推进，不会因为单个 Agent 的阻塞而停滞。

Maestro-Flow 将问题管理视为核心工作流，而非事后补救。问题不是简单的工单，而是自愈管道：

发现 → 分析 → 计划 → 执行 → 关闭

发现阶段：/manage-issue-discover 从 8 个维度扫描：bug、UX、技术债务、安全、性能、测试缺口、代码质量、文档

分析阶段：/maestro-analyze --gaps 进行根因分析，写入 issue.analysis

计划阶段：/maestro-plan --gaps 生成与问题关联的 TASK 文件

执行阶段：/maestro-execute 波次并行执行，自动同步问题状态

关闭阶段：所有关联任务完成 → 已解决 → 已关闭

质量命令（审查、测试、验证）会自动为发现的问题创建工单。修复流程回到阶段管道。闭环自动完成。

Maestro-Flow 提供基于 Web 的实时项目仪表盘，地址为 http://127.0.0.1:3001。使用 React 19、Tailwind CSS 4 和 WebSocket 实时更新构建。

看板视图（K）：Kanban 列——待办、进行中、审查、已完成

时间线视图（T）：甘特图风格的时间线，带进度条

表格视图（L）：可排序的阶段和问题表格

中心视图（C）：指挥中心——活跃执行、问题队列、质量指标

用户可以在问题卡片上选择 Agent，点击播放。支持批量选择问题，并行分派。实时流面板显示 Agent 工作过程。