Agent Orchestrator — 并行 AI 代理的编排层

Agent Orchestrator 负责管理在你的代码库上并行工作的 AI 编码代理集群。每个代理都有自己的 Git 工作树、分支和 PR。当 CI 测试失败时，代理会自动修复；当评审人员留下评论时，代理也会相应处理。只有在需要人工判断时，你才会被介入。

与代理无关（Claude Code、Codex、Aider）· 与运行时环境无关（tmux、Docker）· 与代码追踪工具无关（GitHub、Linear）

实际演示

快速入门

先决条件： Node.js 20+、Git 2.25+、tmux、gh CLI。可通过 brew install tmux（macOS）或 sudo apt install tmux（Linux）安装 tmux。

安装

npm install -g @aoagents/ao

git clone https://github.com/ComposioHQ/agent-orchestrator.git
cd agent-orchestrator && bash scripts/setup.sh

启动

只需指向任意仓库，它就会在一个命令中完成克隆、配置并启动仪表板：

ao start https://github.com/your-org/your-repo

或者在现有的本地仓库中直接运行：

cd ~/your-project && ao start

仅此而已。仪表板将在 http://localhost:3000 打开，编排器代理也将开始管理你的项目。

添加更多项目

ao start ~/path/to/another-repo

工作原理

1. 你启动——ao start 会启动仪表板和编排器代理。
2. 编排器生成工作代理——每个问题都会在隔离的 Git 工作树中分配一个独立的代理。
3. 代理自主工作——它们读取代码、编写测试并创建 PR。
4. 反应机制处理反馈——CI 失败和评审意见会自动重新路由回代理。
5. 你审查并合并——只有在需要人工判断时，你才会被介入。

编排器代理内部使用 AO CLI 来管理会话。你无需学习或使用 CLI——一切均由仪表板和编排器代理自动处理。

配置

ao start 会自动生成带有合理默认值的 agent-orchestrator.yaml 文件。你可以稍后编辑该文件以自定义行为：

# agent-orchestrator.yaml
# 运行时数据会自动存储在 ~/.agent-orchestrator/{hash}-{projectId}/ 目录下
port: 3000

defaults:
  runtime: tmux
  agent: claude-code
  workspace: worktree
  notifiers: [desktop]

projects:
  my-app:
    repo: owner/my-app
    path: ~/my-app
    defaultBranch: main
    sessionPrefix: app

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 2
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 30m
  approved-and-green:
    auto: false # 设置为 true 可实现自动合并
    action: notify

CI 失败时，代理会获取日志并修复问题。评审人员提出修改要求时，代理会予以回应。当 PR 通过评审且 CI 测试绿色时，你会收到合并通知。

完整的参考文档请参阅 agent-orchestrator.yaml.example，或运行 ao config-help 查看完整架构。

远程访问

AO 在运行期间会让你的 Mac 保持唤醒状态，因此你可以远程访问仪表板（例如通过 Tailscale 从手机访问），而不会让设备进入睡眠模式。

工作原理： 在 macOS 上，AO 会自动使用 caffeinate 保持空闲防止睡眠的状态。当 AO 退出时，该状态将被释放。

# agent-orchestrator.yaml
power:
  preventIdleSleep: true  # macOS 默认开启，Linux 无操作

如果你希望 AO 运行时允许设备进入空闲睡眠状态，可将其设置为 false。

合盖限制： macOS 在硬件层面强制执行合盖睡眠——任何用户空间的声明都无法覆盖这一行为。如果你在旅途中需要在合盖状态下进行远程访问，可以使用 clamshell 模式（外接电源、显示器和输入设备）。

插件架构

七个插件槽位。生命周期由核心管理。

所有接口均在 packages/core/src/types.ts 中定义。插件只需实现其中一个接口，并导出一个 PluginModule 即可。就这么简单。

为什么需要 Agent Orchestrator？

在终端中运行一个 AI 代理很简单。但如果要在不同的问题、分支和 PR 上同时运行 30 个代理，这就变成了一个协调难题。

如果没有编排工具，你需要手动完成以下工作：创建分支、启动代理、检查代理是否卡住、阅读 CI 失败信息、转发评审意见、跟踪哪些 PR 已经可以合并、并在完成后清理环境。

有了 Agent Orchestrator，你只需运行 ao start，然后就可以放手不管了。系统会自动处理隔离、反馈路由和状态跟踪等工作。你只需要评审 PR 并做出决策——其余的一切都由自动化完成。

文档

开发

pnpm install && pnpm build    # 安装并构建所有包
pnpm test                      # 运行测试（共 3,288 个测试用例）
pnpm dev                       # 启动 Web 控制台的开发服务器

代码规范和架构细节请参阅 docs/DEVELOPMENT.md。

贡献

欢迎贡献！通过插件系统，你可以轻松地为新的代理、运行时、追踪器和通知渠道添加支持。每个插件都是 TypeScript 接口的具体实现——有关模式详情，请参阅 CONTRIBUTING.md 和 开发指南。

许可证

MIT

Agent Orchestrator 快速上手指南

Agent Orchestrator 是一个用于并行管理多个 AI 编程代理的编排层工具。它能为每个任务自动创建独立的 Git 工作树和分支，自主修复 CI 失败、处理代码审查意见并发起 PR，开发者只需通过统一仪表盘进行监督。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：macOS 或 Linux
• Node.js：版本 20 或更高 (下载地址)
• Git：版本 2.25 或更高 (下载地址)
• tmux：终端复用器
  • macOS: brew install tmux
  • Linux: sudo apt install tmux
• GitHub CLI (gh)：用于与 GitHub 交互 (安装指南)

注意：请确保已配置好 gh 工具的认证（运行 gh auth login），以便工具能自动处理分支和 PR。

安装步骤

方式一：通过 npm 全局安装（推荐）

npm install -g @aoagents/ao

如果遇到 EACCES 权限错误，请在命令前添加 sudo，或参考 npm 官方文档修复全局安装权限。

方式二：从源码安装（适合贡献者）

git clone https://github.com/ComposioHQ/agent-orchestrator.git
cd agent-orchestrator && bash scripts/setup.sh

基本使用

安装完成后，您可以立即启动编排器。它会自动克隆仓库、配置环境并打开管理仪表盘。

1. 启动新项目

指向任意 GitHub 仓库 URL 启动：

ao start https://github.com/your-org/your-repo

或者在已有的本地项目目录中启动：

cd ~/your-project && ao start

2. 访问仪表盘

命令执行后，系统会自动在浏览器打开仪表盘，默认地址为： http://localhost:3000

此时，编排器代理（Orchestrator Agent）已开始运行：

• 它会自动监听仓库中的 Issue 或任务。
• 为每个任务生成独立的 AI 代理（默认使用 Claude Code）。
• 代理将在隔离的 Git worktree 中编写代码、运行测试并提交 PR。
• 若 CI 失败或收到审查评论，代理会自动尝试修复。

3. 添加更多项目

如需同时管理多个仓库，只需再次运行启动命令指向新路径：

ao start ~/path/to/another-repo

4. 自定义配置（可选）

首次运行后，根目录会生成 agent-orchestrator.yaml 配置文件。您可以编辑该文件以更改默认行为（如切换 AI 模型、运行时环境或通知渠道）：

# agent-orchestrator.yaml 示例片段
defaults:
  runtime: tmux       # 运行时环境：tmux 或 process
  agent: claude-code  # AI 代理：claude-code, codex, aider 等
  workspace: worktree # 工作区模式：worktree 或 clone
  
reactions:
  ci-failed:
    auto: true        # CI 失败时自动发送给代理修复
    retries: 2
  changes-requested:
    auto: true        # 审查要求变更时自动处理

修改配置后，重启 ao start 即可生效。