catlog22/maestro-flow

Intent-driven workflow orchestration for multi-agent AI development — adaptive lifecycle engine, self-reinforcing knowledge graph, and visual dashboard for Claude Code, Gemini, Codex & more

Maestro‑Flow – 意图驱动的多智能体工作流编排

是什么 – 一个 TypeScript/Node.js 框架，允许您用自然语言描述“想要实现什么”，并自动构建、调度和运行一系列 AI 智能体来完成整个开发生命周期（头脑风暴 → 规划 → 编码 → 测试 → 审查 → 部署）。它支持多种 LLM 后端（Claude、Gemini、Codex、Qwen、Grok 等），并保持持久化知识图谱，使系统随时间不断变聪明。

核心功能（如 README 所述）

功能	作用
自我适应编排	Ralph 引擎将意图分类为 40 多种预定义命令链，并在每个决策节点上决定是继续、回滚还是插入修复循环——无需 YAML 文件。
跨后端调度	在单个工作流中可混合使用调用 Claude、Codex、Gemini、Qwen、OpenCode、Grok 等的智能体，支持四种协调模式：Delegate（异步委派）、Team（角色协作）、Wave（并行依赖）、Swarm（蚁群式探索）。
知识自我增强	运行中发现的模式、陷阱和决策会自动存储为 Spec 和 Knowhow 条目。钩子系统将这些知识注入后续提示，使未来运行更高效。
长期自我修正	Odyssey 命令运行小时级的自主循环，持续重新评估结果，直到满足验收标准，并在每个周期中持久化新知识。
精确搜索	内置字面量搜索（通过 ripgrep）和可选的语义重排序（BM25 → 嵌入向量），可快速定位代码片段；搜索尊重 `.gitignore`、`.maestroignore` 等安全限制。

安装（来自 README 的快速步骤）

# 全局安装 CLI（需要 Node ≥22.19）
npm install -g maestro-flow@0.5.82

# 交互式组件选择
maestro install

您还需要至少一个主机 CLI，例如 Claude Code（默认）或 Grok Build；可选的 Codex CLI 和 agy CLI 适配器也提供。

典型工作流

表达您的意图 – 例如：/maestro-ralph "实现 OAuth2 认证，支持 refresh token"
Ralph 构建链 – analyze → plan → execute → verify → review → test（失败时自动插入调试/修复循环）。
运行会话 – maestro session open，然后反复执行 maestro run next 直到会话完成。
知识积累 – 任何发现的模式都会被存储，并通过钩子在后续注入。
长运行模式 – 对于大型重构，请使用 /maestro-odyssey <意图> --mode <debug|planex|improve|…>，循环执行直到满足定义的验收标准。

关键概念与术语

Ralph – 将自然语言意图映射到命令链的决策引擎。
Odyssey – 用于重型调试、安全审计、UI 检查等的长时间自主循环。
决策节点 – 引擎评估结果并决定下一步动作的检查点。
Spec / Knowhow – 持久化知识资产，会自动添加到未来提示中。
钩子 – 17 个预定义扩展点，用于将存储的知识注入智能体提示。
MCP（模型上下文协议） – CLI 与 LLM 后端之间通信所用的协议。

示例命令

# 简单意图 → 完整流水线（默认质量模式）
/maestro "添加用户资料页"

# 直接运行单个任务而不走完整流水线
/maestro-companion "修正 README 拼写"

# 在仓库中搜索字面字符串
maestro search "Authorization: Bearer" --exact --json

# 运行长时间安全审计
/maestro-odyssey "安全审计整个项目" --mode security

文档与学习资源（列出）

快速入门指南 – 安装与首个工作流。
Ralph 引擎指南 – 决策逻辑、质量模式、会话处理。
命令参考 – 64 个斜杠命令和 35+ 个 CLI 命令。
知识管理指南 – Specs、Knowhow 与 SQLite 知识图谱的工作原理。
高级设计文档 – 多智能体协调、叠加扩展、工作树并行性、MCP 工具、搜索系统、MaestroGraph 架构等。

项目规模与技术栈

代码 – 333 个 TypeScript 文件（约 80,000 行）。
CLI – 使用 Commander.js、MCP SDK、better-sqlite3、web-tree-sitter 构建。
仪表板 – React 19 + Zustand + Tailwind CSS，通过 Hono/Vite 提供。
智能体 – 23 个定义，45 个技能包，64 个斜杠命令。
模板与工作流 – 92 个 JSON 模板，115 个工作流定义。

与类似工具的比较（来自 README 的摘要）

工具	重点	Maestro‑Flow 的优势
Superpowers	智能体技能框架（仅 Markdown）	全运行时编排、跨后端调度、持久知识图谱
OpenSpec	规范驱动开发	意图驱动自动链生成、动态决策节点
Trellis	多平台智能体固定装置	长时间自主循环（Odyssey）与自我修正流水线

由谁维护

由 @catlog22（GitHub 用户 catlog22）创建并维护。仓库包含微信群组用于社区讨论，采用 MIT 许可证发布。

总结

Maestro‑Flow 是一个生产级、意图驱动的编排层，让开发者能够利用多个 LLM 智能体自动化整个软件开发生命周期，同时从每次运行中持续学习。这是一个真正面向 AI 增强软件工程前沿的开源项目。