maestro-flow

v0.4.21

Published

12 minutes ago

Workflow orchestration CLI with MCP endpoint support and extensible architecture

0High
0Medium
0Low

dyw1234

Maestro-Flow

多智能体时代的编排层

不仅是执行，更是编排。

English | 简体中文

Maestro-Flow 是一个面向 Claude Code、Codex、Gemini 等多智能体的工作流编排框架。你只需描述意图，Maestro-Flow 自动路由到最优命令链，驱动多个 AI 智能体并行执行，通过自适应决策节点、实时仪表盘和知识图谱形成完整的项目交付闭环。

安装

npm install -g maestro-flow
maestro install

前置条件：Node.js >= 18，Claude Code CLI。可选：Codex CLI、Gemini CLI 用于多智能体工作流。

快速开始

/maestro-ralph 是主推入口 — 闭环生命周期引擎，自动读取项目状态、推断当前位置、构建自适应命令链并驱动执行：

/maestro-ralph "实现基于 OAuth2 的用户认证，带 refresh token"

Ralph 自动判断你在生命周期中的位置（brainstorm → blueprint → analyze → roadmap → plan → execute → verify → review → test → milestone-complete）并构建相应命令链。上游起源命令（brainstorm、blueprint）和 roadmap 均为可选 — Ralph 根据项目状态和范围自动跳过。关键检查点的 decision 节点根据实际执行结果，动态插入 debug → fix → retry 循环。

/maestro-ralph status              # 查看会话进度
/maestro-ralph continue            # decision 暂停后恢复
/maestro-ralph -y "搭建 REST API"   # 全自动模式，无人值守

其他入口

| 命令 | 适用场景 | |------|---------| | /maestro "..." | 描述意图，AI 自动路由最优命令链 | | /maestro-quick | 快速修复、小功能（analyze → plan → execute） | | /maestro-* | 逐步执行：init、brainstorm、blueprint、analyze、roadmap、plan、execute、verify |

核心特性

1. 自适应生命周期引擎（`maestro-ralph`）

读取项目状态 → 推断生命周期位置 → 构建含 decision 节点的命令链。每个检查点读取实际执行结果，决定继续还是插入 debug → fix → retry 循环。链在运行中动态增长/收缩。

brainstorm → blueprint(可选) → init → analyze(宏观) → roadmap(可选) → analyze(微观) → plan → execute → verify
                                                                                                       ◆ post-verify
                                              business-test
                                              ◆ post-business-test
                                              review
                                              ◆ post-review
                                              test
                                              ◆ post-test
                                              milestone-audit → milestone-complete
                                              ◆ post-milestone → 下一里程碑

三种质量模式：full（verify + business-test + review + test）、standard（verify + review + test）、quick（verify + CLI-review）。

2. 完整质量管线

每个 ◆ decision 节点是一个质量门禁，根据实际结果动态调整链路：

verify — 目标回溯验证：检查所有 plan 需求是否实现、架构约束校验、反模式扫描、Nyquist 测试覆盖率
business-test — PRD 前向业务测试：需求追溯、fixture 生成、验收标准多层执行
review — 多维度代码审查：正确性、可读性、性能、安全、测试、架构
test-gen — 覆盖率缺口分析 + 自动测试生成（TDD/E2E 分类，L0-L3 渐进层）
test — 交互式 UAT：探索性测试，会话持久化，缺口闭环

3. 分层命令拓扑

命令按四层组织：上游起源层（brainstorm 发散、blueprint 收敛）、理解层（analyze 双层模式：宏观探索影响面 + 微观 Phase 级深入）、编排层（roadmap — 可选，纯 Milestone > Phase 分解）、执行层（plan → execute → verify）。6 条规范路径（Path A–F）覆盖从全新项目到小修复的所有场景。50 个斜杠命令覆盖 7 大类别，所有产物存放于 .workflow/scratch/，由 state.json 追踪。

4. Issue 闭环

Issue 是自修复管线：discover → analyze → plan → execute → close。质量命令自动为发现的问题创建 Issue，修复代码回流到阶段管线。

5. 可视化仪表盘

实时看板 http://127.0.0.1:3001，React 19 + Tailwind CSS 4 + WebSocket 实时更新。Kanban 看板、甘特时间线、可排序表格、指挥中心。在 Issue 卡片上选择智能体，一键派发。

maestro serve                  # → http://127.0.0.1:3001
maestro view                   # 终端 TUI 替代方案
maestro command-help           # 在浏览器中打开交互式命令参考（别名: ch）

6. 多智能体引擎

并行协调 Claude Code、Codex、Gemini、Qwen、OpenCode。波次执行 — 独立任务并行，依赖任务等待前置完成。

7. 智能知识库

Wiki 知识图谱支持 BM25 搜索、反向链接遍历、健康评分。学习工具箱（retro、follow、decompose、investigate、second-opinion）汇入统一的 lessons.jsonl 知识库。

命令与 Agent

| 类别 | 数量 | 前缀 | 用途 | |------|------|------|------| | 核心工作流 | 19 | maestro-* | 全生命周期 — ralph、init、brainstorm、blueprint、analyze、roadmap、plan、execute、verify、milestones、overlays | | 管理 | 12 | manage-* | Issue 生命周期、代码库文档、知识捕获、记忆管理、状态 | | 质量 | 9 | quality-* | review、test、debug、test-gen、integration-test、business-test、refactor、sync | | 学习 | 5 | learn-* | 复盘、跟读、模式拆解、探究、多视角 | | 规范 | 3 | spec-* | setup、add、load | | 知识图谱 | 2 | wiki-* | 连接发现、知识摘要 |

.claude/agents/ 下 21 个专业化 Agent 定义，Claude Code 按需加载。

架构

maestro/
├── bin/                     # CLI 入口
├── src/                     # 核心 CLI (Commander.js + MCP SDK)
│   ├── commands/            # 11 个 CLI 命令 (serve, run, cli, ext, tool, ...)
│   ├── mcp/                 # MCP 服务器 (stdio 传输)
│   └── core/                # 工具注册、扩展加载器
├── dashboard/               # 实时 Web 仪表盘
│   └── src/
│       ├── client/          # React 19 + Zustand + Tailwind CSS 4
│       ├── server/          # Hono API + WebSocket + SSE
│       └── shared/          # 共享类型
├── .claude/
│   ├── commands/            # 50 个斜杠命令 (.md)
│   └── agents/              # 21 个 Agent 定义 (.md)
├── workflows/               # 45 个工作流实现 (.md)
├── templates/               # JSON 模板 (task, plan, issue, ...)
└── extensions/              # 插件系统

| 层级 | 技术 | |------|------| | CLI | Commander.js, TypeScript, ESM | | MCP | @modelcontextprotocol/sdk (stdio) | | 前端 | React 19, Zustand, Tailwind CSS 4, Framer Motion, Radix UI | | 后端 | Hono, WebSocket, SSE | | 智能体 | Claude Agent SDK, Codex CLI, Gemini CLI, OpenCode | | 构建 | Vite 6, TypeScript 5.7, Vitest |

文档

Maestro Ralph 指南 — 自适应生命周期引擎：位置推断、decision 节点、质量模式、重试升级
命令使用指南 — 全部 53 个命令，含工作流图表、管线衔接、Issue 闭环
命令参考 (HTML) — 交互式 HTML 版本，支持搜索、卡片网格、工作流示例（maestro command-help 打开）
CLI 命令参考 — 全部 21 个终端命令：install、delegate、coordinate、wiki、hooks、overlay、collab
Spec 系统指南 — <spec-entry> 格式、keyword 加载、验证 Hook、session dedup 注入
Delegate 异步执行指南 — 异步任务委派：CLI & MCP 用法、消息注入、链式调用
Overlay 系统指南 — 非侵入式命令扩展：格式、section 注入、bundle 打包/导入
Hook 系统指南 — Hook 系统架构、11 个 Hook、Spec 注入、上下文预算
Worktree 并行开发指南 — 里程碑级 worktree 并行：fork、sync、merge、dashboard 集成
Collab 协作 — 使用指南 — 2-8 人小团队协作
Collab 协作 — 设计文档 — 架构、数据模型、命名空间边界
MCP 工具参考 — 全部 9 个 MCP 端点工具

致谢

GET SHIT DONE by TACHES — 规格驱动开发模型和上下文工程理念。
Claude-Code-Workflow — 前身项目，开创了多 CLI 编排和 skill 路由工作流。

贡献者

@catlog22 — 创建者 & 维护者

交流群

欢迎加入微信群交流反馈：

打赏

如果这个项目对你有帮助，欢迎请作者喝杯咖啡：

友情链接

Linux DO：学AI，上L站！

许可证

MIT