Maestro：开源 AI 代理编排指挥中心，多任务并行与无人值守自动化工具

一、Maestro 是什么

Maestro 是一款开源、跨平台、桌面端 AI 代理编排工具，核心定位是把碎片化注意力转化为聚焦的工作意图，为同时管理多个 AI 代理、多个代码项目的高级开发者提供统一控制中心。它不是简单的 AI 对话客户端，而是面向“AI 驱动并行开发”的全流程调度平台，支持多代理并行、上下文隔离、任务队列、自动化执行、Git 深度集成、远程监控与数据可视化，让开发者以最低干扰、最高效率完成编码、重构、架构讨论、批量任务处理等工作。

Maestro 遵循键盘优先、极客体验、无扰工作流的设计理念，界面响应速度对标 Linear、Superhuman 等生产力工具，支持无限数量的代理与终端会话同时运行，每个代理拥有独立工作区、历史记录与隔离上下文，避免多任务之间的污染与干扰。

项目核心价值：

• 把多代理、多分支、多会话从“手动切换”变成“统一编排”

• 把重复、长时、多步骤任务从“人工盯守”变成“无人值守自动化”

• 把跨模型、跨项目的协同从“混乱沟通”变成“主持人 AI 有序调度”

• 把使用过程从“鼠标点选”变成“全键盘高效操作”

Maestro 采用 AGPL-3.0 开源协议，基于 TypeScript 开发，支持 Windows/macOS/Linux 三大系统，提供桌面客户端与 CLI 两种使用模式，既可本地运行，也可在服务器/CI/CD 环境中无头执行剧本任务。

二、Maestro 功能特色

Maestro 的功能围绕并行、隔离、自动化、协同、可视化五大核心设计，覆盖从单代理对话到多代理群组、从手动交互到无人值守、从本地开发到远程控制的全场景。

1. 多 AI 代理并行管理

• 支持同时运行无限数量的 AI 代理与终端会话

• 已兼容：Claude Code、OpenAI Codex、OpenCode

• 规划支持：Gemini CLI、Qwen3 Coder、Aider 等

• 每个代理独立上下文、独立历史、独立工作区

• 消息队列机制：AI 忙碌时自动排队，空闲自动补发，不丢失指令

2. Git Worktrees 并行开发（核心能力）

Maestro 深度集成 Git，实现真正无冲突并行开发：

• 从分支菜单一键创建工作树子代理，每个子代理独占独立目录

• 主仓库可正常交互式编码，子代理后台批量处理任务

• 任务完成后一键创建 PR，合并回主分支

• 彻底解决单分支、单目录下多任务阻塞问题

3. Auto Run & Playbooks 自动化剧本

这是 Maestro 最具生产力的功能：

• 基于文件系统的任务执行器，读取 Markdown 清单批量执行

• 每个任务使用全新干净上下文，避免历史干扰

• 支持循环执行、进度追踪、历史记录

• 支持长达近24小时无人值守运行

• 适合代码重构、批量修改、文档生成、审计报告、标准化操作等场景

4. Group Chat 多代理群组对话

• 在单个对话窗口中协调多个 AI 代理

• 内置主持人 AI，负责问题分发、结果汇总、逻辑调度

• 适合架构讨论、跨模块问题、多专业代理协同解答

• 自动路由问题到最合适的代理，减少冗余与错误

5. 键盘优先操作体系

• 全功能支持键盘操作，极少依赖鼠标

• 提供快捷键自定义与熟练度成就系统

• 核心快捷键：

• Cmd/Ctrl+K：快速操作面板

• Cmd/Ctrl+J：AI 终端 ↔ 命令终端切换

• Cmd/Ctrl+N：新建代理

• Opt/Alt+Cmd/Ctrl+U：打开使用仪表盘

6. 移动远程控制

• 内置 Web 服务器，生成二维码一键接入

• 支持局域网访问与 Cloudflare 隧道远程访问

• 手机可实时监控、控制所有代理状态、发送指令、查看进度

• 适合离开工位时继续调度与查看任务

7. CLI 无头运行模式

• 提供 maestro-cli 命令行工具

• 支持列出代理、运行剧本、定时任务

• 可集成到 cron、CI/CD 流水线

• 输出支持人类可读格式与 JSONL，便于脚本解析

8. 文件系统深度集成

• 内置文件浏览器，支持语法高亮、图片预览、Markdown 渲染

• 用 @ 符号快速引用文件，自动注入上下文

• 自动检测 Git 仓库、展示分支、查看 diff、提交日志

• 支持文件标签、搜索、快速跳转

9. 成本与进度追踪

• 实时 Token 用量与费用统计（按会话/全局）

• Auto Run 任务进度条与历史记录

• 11 个等级成就系统，从新手到指挥大师

10. 数据分析与可视化

• 使用仪表盘：多时间范围统计、代理对比、活动热力图、CSV 导出

• 文档图谱：自动解析 [[wiki链接]] 与普通链接，生成知识关系图，支持力导向/分层布局、键盘导航、小地图

11. 其他体验增强

• 草稿自动保存

• 语音播报通知

• 12 款内置主题（Dracula、Nord、Monokai、GitHub 等）

• 可扩展 Slash 命令

• 输出过滤、搜索、正则匹配

• 会话自动发现与导入

三、Maestro 技术细节

Maestro 采用现代化技术栈，以桌面端为核心、CLI 为补充、Web 远程为扩展，架构清晰、扩展性强。

1. 技术栈

• 主语言：TypeScript（99.6%）

• 桌面框架：Electron（跨平台 Windows/macOS/Linux）

• 构建工具：Vite、npm

• 测试：Vitest、Playwright（e2e）

• 样式：Tailwind CSS

• 协议：AGPL-3.0

2. 架构设计

项目采用分层隔离架构：

• UI 渲染层：响应式界面、键盘事件、主题系统

• 会话管理层：多代理隔离、上下文管理、消息队列

• 工作流引擎：Auto Run、Playbooks、循环调度、状态持久化

• Git 集成层：工作树管理、分支操作、PR 生成

• 远程服务层：内置 Web Server、QR 码、隧道穿透

• CLI 层：命令解析、无头执行、输出格式化

• 数据层：使用统计、费用计算、文档图谱解析

3. 核心技术特点

• 隔离性：每个代理会话独立沙箱，文件、上下文、历史互不干扰

• 透传模式：Maestro 本身不存储模型密钥，仅作为代理转发层

• 持久化：任务状态、会话历史、配置自动保存

• 热响应：界面采用高性能渲染，无卡顿、无延迟

• 可扩展性：支持主题、命令、代理类型扩展

4. 支持的 AI 代理

5. 平台支持

四、Maestro 应用场景

Maestro 面向重度 AI 辅助开发者，覆盖个人、团队、自动化三类场景。

1. 多项目并行开发

• 同时维护多个代码库，每个项目对应独立 AI 代理

• 不同分支、不同目录、不同模型同时工作

• 无需频繁切换窗口、重新登录、清理上下文

2. 大规模重构与批量修改

• 项目级代码规范统一

• 批量文件修改、注释生成、文档同步

• 用 Playbooks 按步骤执行，无人值守

• 适合微服务改造、依赖升级、样式统一、接口迁移

3. 架构设计与跨模块讨论

• 用 Group Chat 让多个代理协同分析架构

• 主持人 AI 汇总意见、梳理逻辑

• 生成设计文档、流程图、接口定义

4. 自动化文档与报告

• 自动生成 API 文档、使用手册、变更日志

• 批量审计代码质量、安全风险、规范合规

• 输出标准化报告，支持导出与版本管理

5. 远程/移动办公

• 出门时用手机监控 AI 任务进度

• 紧急指令通过远程控制发送

• 适合出差、通勤、非工位场景

6. CI/CD 与定时任务

• 用 CLI 模式在服务器定时执行剧本

• 每日构建检查、代码巡检、自动化测试辅助

• 输出结果日志可接入监控系统

7. 教学与研究

• 多模型对比实验：同一任务交给不同代理执行

• 记录执行步骤、耗时、结果质量

• 适合 LLM 研究、prompt 工程、代理能力评估

五、Maestro 使用方法

1. 安装方式

方式1：下载预编译包（推荐）

前往 GitHub Releases 下载对应系统安装包：
https://github.com/pedramamini/Maestro/releases

方式2：源码构建

git clone https://github.com/pedramamini/Maestro.git
cd Maestro
npm install
npm run dev

2. 前置依赖

• 已安装并登录至少一种支持的 AI 代理（Claude Code / OpenAI Codex / OpenCode）

• 可选：Git（启用 Worktrees 功能）

• 系统：Windows 10+ / macOS 11+ / Linux（现代发行版）

3. 快速上手步骤

1. 安装并启动 Maestro

2. 首次打开自动检测已安装的 AI 代理

3. 使用 Cmd/Ctrl+N 创建新代理

4. 使用 Cmd/Ctrl+J 在 AI 对话与命令终端之间切换

5. 打开项目目录，@引用文件直接发送给 AI

6. 用 Cmd/Ctrl+K 打开快速操作，执行“Run Auto”启动剧本

7. 用 Opt/Alt+Cmd/Ctrl+U 查看使用数据仪表盘

4. Git Worktrees 使用流程

1. 打开 Git 项目

2. 在分支菜单选择“Create Worktree Agent”

3. 子代理自动分配独立目录

4. 主代理正常开发，子代理执行任务

5. 完成后一键提交 PR

5. Playbooks 剧本编写

在项目中创建 .md 文件，使用清单格式：

# 重构任务
- [ ] 把所有 var 改为 let/const
- [ ] 为每个函数添加 JSDoc
- [ ] 统一错误处理格式
- [ ] 运行测试并修复失败

然后在 Maestro 中执行 Auto Run，自动逐任务处理。

6. 远程控制开启

1. 快捷键打开远程面板

2. 应用启动本地 Web 服务并显示二维码

3. 手机同网络扫码即可访问

4. 需要外网访问可配置 Cloudflare 隧道

7. CLI 模式使用

# 查看代理列表
maestro-cli list

# 运行剧本
maestro-cli run playbook.md

# 输出 JSONL 格式
maestro-cli run playbook.md --output jsonl

六、常见问题解答

Maestro 会存储我的 API Key 吗？

不会。Maestro 采用透传模式，仅作为本地代理调度工具，不会上传或存储你的模型密钥、对话内容、代码文件。

Maestro 支持国内模型吗？

目前官方支持 Claude Code、OpenAI Codex、OpenCode。国内模型如 Qwen3 Coder 已在规划中，未来可通过扩展支持更多国产代理。

运行 Auto Run 时电脑休眠会中断吗？

会。长时间无人值守建议关闭系统自动睡眠/休眠，或在服务器上使用 CLI 模式运行。

Git Worktrees 会影响我的原有代码吗？

不会。Worktrees 是 Git 官方功能，Maestro 只是封装使用，每个子代理使用独立目录，不影响主仓库。

可以同时运行多少个代理？

理论无上限，受内存与CPU限制。普通开发机器可稳定运行10–20个并行代理。

Maestro 收费吗？

完全开源免费，AGPL-3.0 协议，个人与商业均可使用（需遵守协议）。

数据保存在哪里？是否会丢失？

所有会话、配置、任务状态保存在本地，自动持久化。卸载软件不会主动删除数据，重装可恢复。

没有鼠标可以完全使用 Maestro 吗？

可以。Maestro 是键盘优先设计，几乎所有操作都有快捷键，支持纯键盘高效工作。

Playbooks 可以循环执行吗？

可以。Auto Run 支持循环模式，适合需要反复执行的监控、巡检、生成类任务。

远程控制是否安全？

默认仅局域网可用。开启外网访问需自行配置隧道，访问链路由用户自行负责安全。

Maestro 可以导入旧的 AI 对话历史吗？

可以。支持自动发现并导入已支持平台的历史会话，可搜索、收藏、继续对话。

如何更新 Maestro？

可下载最新 Releases 包覆盖安装，或从源码 git pull 重新构建。

七、相关官方链接

• GitHub 仓库：https://github.com/pedramamini/Maestro

• 官方文档：https://docs.runmaestro.ai

• 官方网站：https://runmaestro.ai

八、总结

Maestro 是一款面向专业开发者的开源 AI 代理编排桌面工具，以并行化、隔离化、自动化、键盘优先为核心设计，深度整合 Git 工作流与 AI 编码能力，提供多代理管理、剧本自动化、群组协同、远程控制、数据可视化等完整能力，解决了开发者在多项目、多代理、多分支场景下的上下文混乱、操作繁琐、效率低下、人工盯守等痛点，支持长时间无人值守执行复杂工作流，同时保持极客化的流畅体验与高度可控性，适合追求生产力、专注于工程化与自动化的开发者使用。