Maestro Flow
⌘ 终端工作流 · 知识驱动 · 多 CLI 协作

Maestro Flow
终端工作流手册

一套围绕 maestro 的开发工作流编排系统：把「想法 → 规格 → 计划 → 执行 → 验证」拆成明确步骤，知识驱动、多 CLI 协作、状态可追溯。

给「会用终端、第一次接触 Maestro」的你——读完能独立从 0 跑通一个开发任务。不用背命令，跟着工作流走即可。

40+
智能命令链类型
6
工作流路径 A–F
5
协作 CLI 工具
v0.5.36
当前版本

🧩 结构化工作流

把开发拆成想法、规格、计划、执行、验证等明确步骤，每步有产出。

🔍 知识驱动

每个任务前先检索已有知识（spec / knowhow / 代码图谱），避免重复踩坑。

🤝 多 CLI 协作

把活儿委派给最合适的工具：Claude / Gemini / Codex / Qwen。

📌 状态可追溯

每个里程碑、每次执行都有记录，断点可续。

⚠️ 先搞懂两类入口（最重要）：Maestro 有两种命令，别混用——
$ maestro 终端 CLI：检索 / 知识图谱 / 委派 / 安装 / 看板等基础设施，在普通终端里敲。
/ maestro- Claude Code Slash 命令：brainstorm、analyze、plan、execute、verify、ralph 等工作流编排，在 Claude Code 对话框里以 / 开头输入。
本手册凡是带 / 前缀的都在 Claude Code 里跑；不带前缀的 maestro … 在终端里跑。
安装与配置

1 · 安装

npm install -g maestro-flow maestro install # 交互式选择要装的资产

前置：Node ≥ 18、Claude Code CLI（可选 Codex / Gemini）。验证（当前最新 0.5.36）：

maestro --version maestro update --check # 查是否有新版

maestro install 会把 slash 命令 / 技能 / hooks 装进 .claude/，装完重启 Claude Code 才能用 /maestro-*。

2 · 配置 CLI 工具

通过 ~/.maestro/cli-tools.json 管理可用 CLI：

{ "tools": { "claude": { "enabled": true }, "codex": { "enabled": true } } }

也可用 maestro config 交互配置。

3 · 初始化项目

在 Claude Code 里、项目目录下运行：

/maestro-init

会创建 .workflow/ 目录，存放状态、知识库与会话记录。多项目共享知识用 maestro workspace link。

第一个任务 · 5 分钟跑通

不确定走哪条路？直接把意图丢给 Ralph 引擎，它会读状态、自动拼命令链。

最简单：交给 Ralph 自动编排

/maestro-ralph "给项目添加一个健康检查接口"

/maestro-ralph 是主入口：自动判断你在生命周期的哪一步（brainstorm→plan→execute→verify…）并逐步推进，关键节点会停下让你确认。想完全无人值守：

/maestro-ralph -y "添加健康检查接口" # 全自动，不暂停

推荐：分步可控

分析需求

/maestro-analyze "添加健康检查接口" → 产出分析 ANL-xxx

制定计划

/maestro-plan → 接上一步分析，产出 PLAN-xxx

执行

/maestro-execute → 产出代码变更

验证

/maestro-verify → 产出验证报告

工作流路径 · 按场景选

先定位场景，再照「怎么用」里的命令逐行照敲——每张卡片的命令块就是可直接复制的完整序列。

命令带 / 前缀的在 Claude Code 对话框里输入。(可选) 的步骤可跳过。带 ↻ 的是对每个阶段循环。拿不准时，直接 /maestro "意图" 让它自动选路。

Path A · 全新大项目

/maestro-brainstorm "项目想法" /maestro-blueprint # 可选：出规格 /maestro-init /maestro-analyze "主题" # 宏观摸底 /maestro-roadmap # 拆里程碑 # ↻ 对每个阶段 N 循环： /maestro-analyze 1 # 阶段1 细分 /maestro-plan 1 /maestro-execute /maestro-verify

何时：从零起步、需求大而模糊。
怎么用：brainstorm 发散 → 可选 blueprint 出规格 → init 建目录 → analyze 宏观摸底 → roadmap 拆阶段；之后对第 1、2…个阶段，重复 analyze N → plan N → execute → verify 直到收口。

Path B · 旧项目大功能

/maestro-analyze "功能X" /maestro-roadmap # ↻ 每个阶段 N： /maestro-analyze 1 /maestro-plan 1 /maestro-execute /maestro-verify

何时：已有项目里加一个大功能。
怎么用：跳过 init，先 analyze 摸清现有代码 → roadmap 拆阶段 → 每阶段 analyze N → plan N → execute → verify 循环。

Path C · 中等功能

/maestro-analyze "功能X" /maestro-plan /maestro-execute /maestro-verify

何时：单个功能、范围清晰、无需分阶段。
怎么用：analyze 得到分析后，plan 自动接上分析结果，再 execute → verify，一条直线走完。

Path D · 小改动

/maestro-plan "修复描述" /maestro-execute /maestro-verify

何时：bug 修复或小调整，逻辑清楚。
怎么用：略过 analyze，plan 直接写修复描述生成计划，execute 改完 verify 验证。

Path E · 纯规格文档

/maestro-blueprint "项目想法"

何时：只要规格/设计文档，暂不写代码。
怎么用：blueprint 输入项目想法，生成 Product Brief、PRD、架构、Epics 等文档供团队评审。

Path F · 纯探索

/maestro-brainstorm "idea"

何时：方向未定，先要点子。
怎么用：brainstorm 输入 idea，多角度发散产出供你决策，不直接落地。

⚡ 快速修复

/maestro-quick "修复描述"

何时：一行说得清的小修复，想跳过中间步骤。
怎么用：quick 加修复描述，内部自动串 analyze→plan→execute，跳过可选 agent，一步到位。

🤖 全自动 / 不确定走哪条

/maestro "任务描述" # 意图路由，自动选链 /maestro-ralph -y "任务" # 闭环全自动

何时：拿不准该走 A–F 哪条。
怎么用：/maestro 按项目状态自动匹配 40+ 种命令链；-y 跳过所有确认。

🔁 Issue 闭环

/manage-issue-discover /manage-issue create /maestro-analyze --gaps /maestro-plan --gaps /maestro-execute /manage-issue close

何时：从发现问题到修复关闭的完整闭环。
怎么用：discover 发现 → create 建 issue → 用 --gaps 聚焦缺口做分析/计划 → execute → close。

Odyssey · 长循环自纠错：需要「跑到验收为止」的反复迭代时，用 Odyssey 命令——它会自动循环考古→诊断→修复→验证→沉淀知识。
/odyssey-debug（调试）· /odyssey-planex（需求驱动）· /odyssey-improve（代码改进）· /odyssey-review-test-fix（深审+修）· /odyssey-ui（UI 优化）
核心命令详解

闭环五件套（Claude Code slash 命令）：analyze → plan → execute → verify，外加 roadmap 拆阶段。

/maestro-analyze · 分析

分析需求或代码，宏观摸底或缺口分析，产出 ANL-xxx。

/maestro-analyze "需求描述" /maestro-analyze --gaps # 分析缺口 /maestro-analyze 1 # 分析路线图第 1 阶段

/maestro-plan · 计划

基于分析或描述制定执行计划，产出 PLAN-xxx。

/maestro-plan "修复描述" /maestro-plan # 接最近一次分析 /maestro-plan 1 # 计划第 1 阶段 /maestro-plan --gaps # 计划缺口

/maestro-execute · 执行

执行计划，产出代码变更。

/maestro-execute /maestro-execute --gaps

/maestro-verify · 验证

验证执行结果是否符合预期，产出验证报告。

/maestro-verify

其它常用

/maestro-roadmap

从需求生成路线图，拆成带里程碑的阶段。

/maestro-roadmap

/maestro-brainstorm

多角度头脑风暴，产出想法供决策。

/maestro-brainstorm "idea"

/maestro-blueprint

生成规格文档（PRD / 架构）供阅读。

/maestro-blueprint "想法"
知识系统
Gate 规则：任何编码 / 修改 / 调试任务，先 search 再动手。用 1-3 个核心关键词，多次定向搜索胜过一次大查询。这些都是终端 CLI（不带 /）。

maestro search · 搜索

maestro search "topic" # 语义搜索 maestro search "Symbol" --code # 代码符号 maestro search "x" --type spec # 规格 maestro search "x" --type knowhow # 知识

0.5.36 提速：开常驻搜索守护进程，模型热缓存，搜索更快。

maestro search-daemon start # start | stop | status

maestro kg · 知识图谱

maestro kg sync # 先建/更新索引 maestro kg query <text> maestro kg context <node> maestro kg callers <fn> # 谁调用了它 maestro kg callees <fn> # 它调用了谁

maestro spec · 规格管理

记录决策、模式、规则到项目规格（注意是子命令 spec add，非 spec-add）。

maestro spec add <category> "标题" "内容" --keywords kw1,kw2 maestro spec load --category <cat>

类别：archcodingdebugtestreviewlearning

在 Claude Code 里也可用 slash：/spec-add / /spec-load。

knowhow · 知识捕获

把可复用的模板、配方、技巧固化下来。

maestro knowhow <...> # 终端 /manage-knowhow-capture # Claude Code

用 --spec-category 可桥接进 agent 自动注入。

多 CLI 委派与探索

把任务委派给最合适的 CLI 工具，并行分析、交叉验证、独立子任务。这些都是终端 CLI。

maestro delegate · 委派

maestro delegate "<PROMPT>" --to codex --mode analysis

默认后台运行，完成后回调通知：

maestro delegate "分析认证模块" --to codex --role analyze # 立即返回，后台执行 maestro delegate status <exec-id> # 查状态/结果

关键参数

参数说明默认
--togemini/qwen/codex/claude首个启用
--roleanalyze/explore/review/implement/plan—
--modeanalysis(只读) / write(修改)analysis
--model模型覆盖工具默认
--cd工作目录当前
--resume恢复会话—
角色与回退链：委派支持角色路由，每个角色有回退链，前一个不可用自动切下一个。例如 analyze → [codex, agy, claude]。

maestro explore · 轻量代码探索 0.5.36

它是什么 / 何时用

一个 grep-first 的快速代码搜索 agent：只用 Grep / Glob / Read，最多 3 轮，直连一个 OpenAI 兼容端点（不占用主力 CLI）。适合「X 在哪实现 / 某处怎么工作」这类代码定位，比开整个 CLI agent 更快更省。

maestro explore "JWT 校验在哪实现的" maestro explore -e deepseek "xxx 怎么工作" maestro explore --all "对比前后端鉴权逻辑" # 多端点并行

会话存到 .workflow/explore/。带具体关键词/符号名命中率更高，开放式架构分析仍交给 delegate。

配置端点

独立文件 ~/.maestro/api-explore.json（不会改 cli-tools.json，只读其 proxy 字段）：

{ "endpoints": { "deepseek": { "baseUrl": "https://api.deepseek.com/v1", "apiKey": "sk-...", "model": "deepseek-chat", "concurrency": 2, "maxTurns": 4 } } }

支持多个命名端点并行扇出；也可用环境变量 API_EXPLORE_API_KEY 等。纯 opt-in，不配就休眠。

状态与里程碑

查看状态

查看项目进度、下一步建议，或开看板。

/manage-status # 文字仪表盘 maestro view # 看板 dashboard

里程碑管理（slash）

/maestro-roadmap # 生成路线图 /maestro-milestone-audit # 审计 /maestro-milestone-complete # 完成归档 /maestro-milestone-release # 发布

Fork / Merge 并行

为里程碑创建独立工作树，并行开发后合并回主线。

/maestro-fork <milestone> /maestro-merge <milestone>
高级特性

⚡ Ralph 自适应引擎

11 态状态机：读状态、推断生命周期位置、拼带质量门的命令链，决策节点动态插入 debug→fix→retry。

/maestro-ralph "复杂任务" /maestro-ralph status # 进度 /maestro-ralph continue # 续跑

🔁 Odyssey 长循环

跑到验收为止的自纠错迭代。

/odyssey-debug /odyssey-planex /odyssey-improve /odyssey-review-test-fix /odyssey-ui

🔍 质量管线

/quality-review # 审查 /quality-auto-test # 自动测试 /quality-test # 验收 /quality-refactor # 重构 /quality-debug # 调试

👥 团队协作 Team

多角色协作的 agent 管线。

/team-planex # 计划+执行 /team-frontend # 前端团队 /team-roadmap-dev # 路线图驱动

🎨 UI 设计工作流

/team-uidesign /team-ui-polish /workflow:ui-design:codify-style

📋 更多

终端跑 maestro --help 看全部 CLI 子命令；在 Claude Code 里输入 / 浏览所有 slash 命令与技能。

配置文件参考

全局配置

文件作用
~/.maestro/cli-tools.jsonCLI 工具配置
~/.maestro/api-explore.jsonexplore 端点配置
~/.claude/CLAUDE.md全局指令 / 工作准则
~/.claude/settings.jsonClaude Code 设置（hooks/权限）

项目配置

文件 / 目录作用
.workflow/状态、知识库、会话
.workflow/specs/项目规格
.workflow/kg/知识图谱
.workflow/explore/explore 会话记录
常见问题

/maestro-* 命令找不到

先装资产再重启 Claude Code：

npm install -g maestro-flow maestro install maestro --version

搜索无结果

先建立索引：

maestro kg sync

委派失败

检查 CLI 工具是否启用：

cat ~/.maestro/cli-tools.json maestro config

下一步

• 通读 ~/.claude/CLAUDE.md 了解工作准则
• 终端 maestro --help / Claude Code 里 /maestro-ralph "..." 起步
• 从一个真实小任务开始实践