Maestro

The Conductor for AI Agents — 多智能体编排与执行系统

Maestro 是一个本地优先的多 AI Agent 协作平台。它像一个乐团指挥，将多个 AI 编程助手（Claude Code、Codex、Gemini、Kiro、Aider 等）组织成一支协作团队，通过角色分工、任务调度和自动化流水线，让它们协同完成复杂的软件工程任务。

设计理念

角色优先，而非 Agent 优先

传统的多 Agent 系统直接管理 Agent 实例。Maestro 引入了 Role（角色） 作为中间抽象层：

Task → Role → Agent → Runtime

• Task 描述要做什么（需求、验收标准）
• Role 描述谁来做（能力、职责、提示词）
• Agent 是执行者（绑定到某个 Role 的运行实例）
• Runtime 是底层引擎（claude-code、codex、gemini 等 CLI 工具）

这意味着你可以定义一个 engineer 角色，背后可以是 Claude Code 也可以是 Codex —— 系统根据可用性和能力自动调度。角色"永远在线"，Agent 可以来去自如。

本地运行，零依赖外部服务

Maestro Hub 运行在你的开发机上，使用 SQLite 存储，不需要 Docker、Redis 或任何云服务。一个 maestro start 就能启动整个系统。

自动发现，即插即用

启动时 Maestro 会扫描 PATH，自动发现已安装的 AI CLI 工具并注册为可用 Runtime。无需手动配置每个 Agent 的连接方式。

渐进式自动化

从手动分配任务开始，逐步开启 Autopilot：

1. 手动创建任务、手动分配 → 熟悉系统
2. 开启自动调度 → 系统自动将任务分配给空闲 Agent
3. 开启 Chief → AI 项目经理自动拆解需求、创建任务、监控进度
4. 配置 Cron/Hook → 事件驱动的全自动流水线

核心概念

Workspace（工作区）

顶层组织单元，代表一个目标或项目群。包含多个 Project。

Project（项目）

属于某个 Workspace，有自己的工作目录和工作流定义。

Task（任务）

最小工作单元。具有：

• 状态流转：open → claimed → review → done
• 优先级（P0-P3）
• 依赖关系（DAG）
• 验收标准（done_when）
• 讨论线程

Role（角色）

逻辑上的职能定义，用 Markdown 文件描述：

---
name: engineer
extends: base/agent.md
capabilities: [code, test, debug, deploy]
headcount: 3
---

你是一名软件工程师，负责编写、测试和交付代码...

内置角色： | 角色 | 职责 | |------|------| | engineer | 编码、测试、部署 | | researcher | 调研、分析、方案设计 | | writer | 文档、内容创作 | | critic | Code Review、QA、测试 | | chief | 自主项目管理（AI PM） |

Agent（代理）

绑定到 Role 的执行实例。一个 Role 可以有多个 Agent（水平扩展）。

Runtime（运行时）

底层 AI CLI 工具。支持自动发现：

| Runtime | CLI | |---------|-----| | claude-code | claude | | codex | codex | | gemini | gemini | | opencode | opencode | | aider | aider | | kiro | kiro | | cursor | cursor | | 更多... | 持续扩展 |

架构概览

┌─────────────────────────────────────────────────────┐
│                   Web Dashboard                      │
│            (React + Tailwind + xterm.js)             │
└──────────────────────┬──────────────────────────────┘
                       │ HTTP / WebSocket
┌──────────────────────▼──────────────────────────────┐
│                    Hub Server                         │
│  ┌─────────┐ ┌──────────┐ ┌───────────┐ ┌───────┐  │
│  │ REST API│ │ EventBus │ │ Autopilot │ │ Chief │  │
│  └─────────┘ └──────────┘ └───────────┘ └───────┘  │
│  ┌──────────────┐ ┌────────────┐ ┌──────────────┐  │
│  │Role Dispatch │ │ Workflows  │ │   Skills     │  │
│  └──────────────┘ └────────────┘ └──────────────┘  │
│  ┌──────────────────────────────────────────────┐   │
│  │              SQLite (WAL mode)                │   │
│  └──────────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────────┘
                       │ Transport (PTY / SSH / HTTP)
┌──────────────────────▼──────────────────────────────┐
│              Agent Runtimes                           │
│  ┌─────────┐ ┌───────┐ ┌────────┐ ┌─────────────┐  │
│  │ Claude  │ │ Codex │ │ Gemini │ │ OpenCode... │  │
│  └─────────┘ └───────┘ └────────┘ └─────────────┘  │
└─────────────────────────────────────────────────────┘

使用方式

CLI 命令

maestro init              # 初始化 .hub/ 目录
maestro start             # 启动 Hub 服务
maestro start --daemon    # 后台守护进程模式
maestro start --port 8080 # 指定端口
maestro status            # 查看 Hub 运行状态
maestro logs              # 查看最近日志
maestro logs -f           # 实时跟踪日志
maestro stop              # 停止守护进程
maestro doctor            # 系统诊断（检查 DB、运行时、角色等）
maestro inbox             # Agent 收件箱操作
maestro chat              # 工作区消息通信

生产模式（终端用户）

maestro start              # 前台启动，单一端口 7423
maestro start --daemon     # 后台启动
maestro status             # 查看状态、PID、端口和日志位置
maestro logs -f            # 查看守护进程日志
maestro stop               # 停止服务

生产模式只需要访问 http://localhost:7423。Maestro 会在首次启动或前端产物过期时自动构建 Web UI，并由同一个 Hub 服务器同时提供静态页面和 API。

开发模式（贡献者）

bun install
bun run dev

开发模式会同时启动后端 http://localhost:7423 和 Vite 前端 http://localhost:5173。贡献者访问 http://localhost:5173 进行前端开发，HMR 会在保存后自动更新页面；后端由 bun --watch 在源码变更后自动重启。

Web 控制台

启动 Hub 后访问 http://localhost:7423，提供：

• 看板视图 — Kanban 风格的任务面板
• 甘特图 — 任务时间线与依赖关系可视化
• 实时终端 — 通过 xterm.js 查看 Agent 的实时输出
• 聊天面板 — 与 Agent 实时对话，支持 @mention
• 运行时管理 — 查看和管理已连接的 Agent Runtime
• 技能库 — 浏览和管理自动提取的可复用技能

API 驱动

所有功能都通过 REST API 暴露，方便集成到你自己的工具链：

# 创建任务
curl -X POST http://localhost:7423/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "实现用户认证模块",
    "role": "engineer",
    "priority": 1,
    "done_when": "JWT 认证中间件通过所有测试"
  }'

# 查看所有 Agent
curl http://localhost:7423/api/agents

# 查看任务状态
curl http://localhost:7423/api/tasks

# WebSocket 事件流
wscat -c ws://localhost:7423/space/events

实时事件

通过 WebSocket 订阅系统事件，支持 glob 模式过滤：

const ws = new WebSocket('ws://localhost:7423/space/events');
ws.send(JSON.stringify({ subscribe: 'task.*' }));
// 收到: task.created, task.claimed, task.completed ...

Autopilot（自动驾驶）

Autopilot 是 Maestro 的自动化引擎，统一管理：

| 功能 | 说明 | |------|------| | 自动调度 | 将 open 状态的任务自动分配给匹配角色的空闲 Agent | | Cron 任务 | 定时触发的自动化操作 | | 计划任务 | 按计划自动创建任务实例 | | Webhook 路由 | 将外部事件（GitHub、Linear 等）路由到 Hook 处理器 | | 技能提取 | 从完成的会话中自动提取可复用的操作模式 |

# 通过 API 启动 Autopilot
curl -X POST http://localhost:7423/api/autopilot/start

# 查看状态
curl http://localhost:7423/api/autopilot/status

# 手动触发一次调度
curl -X POST http://localhost:7423/api/autopilot/tick

Chief（AI 项目经理）

Chief 是一个可选的自主 Agent，充当 AI 项目经理的角色：

• 定期审视全局状态（工作区、项目、任务、Agent 负载）
• 自动拆解高层需求为具体任务
• 发现阻塞并尝试解决
• 调整 Agent 编制（扩缩容）
• 向人类升级无法自主决策的问题

Chief 的所有重大决策（创建项目、调整角色）都会发送到 Inbox 等待人类审批，不会擅自行动。

配置：

export ANTHROPIC_API_KEY=sk-ant-...
# 或通过 API 配置
curl -X PUT http://localhost:7423/api/config \
  -H "Content-Type: application/json" \
  -d '{"chief_model": "claude-sonnet-4-6", "chief_interval_min": 15}'

工作流引擎

任务状态流转通过可定制的状态机管理：

open → claimed → review → done
  ↓       ↓        ↓
  └───────┴────→ blocked
  └───────┴────→ abandoned

你可以为不同项目定义不同的工作流：

curl -X POST http://localhost:7423/api/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "strict-review",
    "scope": "project",
    "scope_id": "proj_xxx",
    "statuses": ["open", "claimed", "review", "approved", "done"],
    "actions": [
      {"name": "claim", "from": ["open"], "to": "claimed"},
      {"name": "submit", "from": ["claimed"], "to": "review"},
      {"name": "approve", "from": ["review"], "to": "approved", "requires": ["critic"]},
      {"name": "ship", "from": ["approved"], "to": "done"}
    ]
  }'

技能系统

Maestro 会从 Agent 的工作会话中自动提取可复用的技能模式，存储为 Markdown 文件：

.hub/skills/
├── deploy-to-production.md
├── setup-jest-config.md
└── database-migration.md

技能会在后续任务分配时注入到 Agent 的提示词中，让团队的经验得以积累和传承。

通信集成

| 渠道 | 说明 | |------|------| | Web Chat | 内置工作区聊天 | | Telegram | Bot 网关，支持斜杠命令 | | Lark/飞书 | Webhook 通知 | | Webhook | 通用入站 Webhook（GitHub、Linear 等） |

# 配置 Telegram Bot
export MAESTRO_TELEGRAM_BOT_TOKEN=your-bot-token

传输层

Agent 可以通过三种方式连接：

| 方式 | 场景 | |------|------| | local-pty | 本地进程（默认，自动发现的 CLI） | | ssh | 远程开发机上的 Agent | | http-api | 通过 HTTP API 代理的远程 Agent |

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | ANTHROPIC_API_KEY | Chief Agent 的 API Key | — | | MAESTRO_CHIEF_MODEL | Chief 使用的模型 | claude-sonnet-4-6 | | MAESTRO_CHIEF_BASE_URL | 自定义 API 端点 | Anthropic 官方 | | MAESTRO_TELEGRAM_BOT_TOKEN | Telegram Bot Token | — | | MAESTRO_HUB_URL | Hub 地址（Agent 侧） | http://localhost:7423 | | MAESTRO_<RUNTIME>_PATH | 指定 Runtime CLI 路径 | 自动发现 | | MAESTRO_<RUNTIME>_MODEL | 指定 Runtime 使用的模型 | Runtime 默认 |

License

本项目为私有软件，保留所有权利。未经授权不得复制、修改或分发。