# 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 文件描述：

```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 命令

```bash
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              # 工作区消息通信
```

### 生产模式（终端用户）

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

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

### 开发模式（贡献者）

```bash
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 暴露，方便集成到你自己的工具链：

```bash
# 创建任务
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 模式过滤：

```javascript
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 处理器 |
| 技能提取 | 从完成的会话中自动提取可复用的操作模式 |

```bash
# 通过 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 等待人类审批，不会擅自行动。

配置：
```bash
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
```

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

```bash
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 等） |

```bash
# 配置 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

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