Agent Orchestration

🚀 代理编排

一个模型上下文协议（MCP）服务器，可让多个AI代理共享内存、协调任务，并在集成开发环境（IDE）和命令行工具（CLI）中有效协作。

项目徽章

🚀 快速开始

无需安装！直接使用 npx：

适用于任何IDE/CLI（AGENTS.md）

# 导航到你的项目目录
cd /path/to/your/project

# 使用AGENTS.md进行初始化
npx agent-orchestration init

这将创建包含完整编排说明的 AGENTS.md 文件，可与任何AI编码代理配合使用。

适用于Cursor IDE

# 导航到你的项目目录
cd /path/to/your/project

# 为Cursor进行初始化（复制 .cursor/rules/）
npx agent-orchestration init-cursor

这将复制包含Cursor特定规则的 .cursor/rules/ 目录。

✨ 主要特性

解决的问题

运行多个AI代理时，它们面临着关键的协调挑战：

1. 无轮次感知 - 代理不知道何时轮到自己行动，导致竞态条件。
2. 基于文件的预测 - 代理从文件而非共享内存中预测状态，导致读取过时数据。
3. 上下文漂移 - 并行代理对代码库的理解不一致。
4. 无代理发现 - 代理不知道其他代理正在处理同一项目。
5. 重复工作 - 多个代理可能同时尝试执行相同任务。
6. 冲突编辑 - 缺乏协调时，代理会相互覆盖彼此的更改。

解决方案

此MCP服务器提供以下功能：

• 共享内存 - 代理可以存储和检索上下文、决策和发现结果。
• 任务队列 - 基于轮次的任务执行，并支持依赖关系。
• 代理发现 - 代理可以查看其他正在处理该项目的代理。
• 资源锁定 - 防止对文件或资源的并发访问。
• 协调状态 - 实时了解编排状态。
• 自动上下文同步 - 自动更新 activeContext.md 以便于参考。

兼容性

可与任何支持MCP或 AGENTS.md 的AI编码代理配合使用：

• OpenAI Codex
• Google Jules
• Cursor
• Aider
• Windsurf
• VS Code Copilot
• GitHub Copilot Coding Agent
• Devin
• 以及更多！

📦 安装指南

无需安装，直接使用 npx 命令即可。

💻 使用示例

命令行工具使用示例

npx agent-orchestration init           # 创建AGENTS.md（适用于任何AI代理）
npx agent-orchestration init-cursor    # 为Cursor IDE进行设置（.cursor/rules/）
npx agent-orchestration serve          # 运行MCP服务器
npx agent-orchestration help           # 显示帮助信息

MCP服务器设置示例

将以下内容添加到你的MCP配置文件（例如，Cursor的 ~/.cursor/mcp.json）中：

{
  "mcpServers": {
    "agent-orchestration": {
      "command": "npx",
      "args": ["-y", "agent-orchestration", "serve"],
      "env": {
        "MCP_ORCH_SYNC_CONTEXT": "true"
      }
    }
  }
}

服务器会自动将当前工作目录作为项目根目录。

启动会话示例

使用 bootstrap 工具启动：

bootstrap

这将注册你，显示当前焦点、待处理任务和最近的决策。

📚 详细文档

可用工具

会话管理

代理管理

共享内存

任务管理

协调

推荐工作流程

主编排代理

1. bootstrap                          # 启动会话
2. memory_set current_focus "..."     # 设置项目焦点
3. task_create "Feature X"            # 创建任务
4. task_create "Feature Y"
5. coordination_status                # 监控进度

子代理（为特定工作生成）

1. claim_todo "Feature X"             # 在一次调用中注册并认领任务
2. lock_acquire "src/feature.ts"      # 在编辑前锁定文件
3. [进行工作]
4. task_complete <task_id> "Done"     # 完成任务
5. agent_unregister                   # 清理

内存命名空间

使用以下命名空间进行组织：

配置

环境变量

架构

┌─────────────────────────────────────────────────────────────┐
│                     IDE / CLI Tool                           │
├─────────────┬─────────────┬─────────────┬─────────────┬─────┤
│ Main Agent  │ Sub-Agent 1 │ Sub-Agent 2 │ Sub-Agent 3 │ ... │
└──────┬──────┴──────┬──────┴──────┬──────┴──────┬──────┴─────┘
       │             │             │             │
       └─────────────┴──────┬──────┴─────────────┘
                            │
                    ┌───────▼───────┐
                    │  MCP Server   │
                    │  (TypeScript) │
                    └───────┬───────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
      ┌───────▼───┐ ┌───────▼───┐ ┌───────▼───┐
      │  Agents   │ │   Tasks   │ │  Memory   │
      │  Registry │ │   Queue   │ │   Store   │
      └───────────┘ └───────────┘ └───────────┘
              │             │             │
              └─────────────┼─────────────┘
                            │
                    ┌───────▼───────┐
                    │    SQLite     │
                    │  (per-project)│
                    └───────────────┘

AGENTS.md

本项目遵循 AGENTS.md 格式，这是一种简单、开放的格式，被超过60,000个开源项目用于指导AI编码代理。

当你运行 npx agent-orchestration init 时，会创建一个 AGENTS.md 文件，该文件可与以下代理配合使用：

• OpenAI Codex
• Google Jules
• Cursor
• Aider
• Windsurf
• VS Code Copilot
• 以及更多！

🔧 技术细节

架构设计

项目采用分层架构，包括IDE/CLI工具层、MCP服务器层和数据存储层。MCP服务器使用TypeScript编写，负责协调多个AI代理的工作。数据存储层使用SQLite数据库，每个项目一个数据库实例。

工作流程

1. 初始化：通过 npx agent-orchestration init 或 npx agent-orchestration init-cursor 命令初始化项目。
2. 启动服务器：使用 npx agent-orchestration serve 命令启动MCP服务器。
3. 会话管理：使用 bootstrap 工具启动会话，注册代理并获取任务信息。
4. 任务处理：代理通过任务队列进行任务的创建、认领、更新和完成操作。
5. 共享内存管理：代理可以使用共享内存存储和检索上下文、决策和发现结果。
6. 协调机制：通过资源锁定和协调状态监控，确保代理之间的协作和同步。

📄 许可证

本项目采用MIT许可证。

🔧 故障排除

服务器无法启动

1. 确保已安装Node.js 18或更高版本：node --version。
2. 检查MCP配置文件中的路径是否正确。

数据库错误

SQLite数据库会自动在 .agent-orchestration/ 目录下创建。如果数据库损坏，可以执行以下命令：

rm -rf .agent-orchestration/

服务器下次启动时会重新创建数据库。

代理无法相互发现

• 确保所有代理在MCP配置中使用相同的当前工作目录（cwd）。
• 使用 agent_list 命令查看已注册的代理。
• 无心跳5分钟后，过时的代理会自动清理。

🔨 开发

前提条件

• Node.js 18或更高版本
• npm

环境搭建

# 克隆仓库
git clone https://github.com/madebyaris/agent-orchestration.git
cd agent-orchestration

# 安装依赖
npm install

# 构建项目
npm run build

# 监听模式（代码更改时重新构建）
npm run dev

# 清理构建
npm run clean && npm run build

🗺️ 路线图

我们正在积极开发新功能，以下是即将推出的内容：

• [ ] 外部内存集成 - 与外部内存提供商（如 Mem0、Byteover）以及我们自己的内存解决方案进行集成。
• [ ] 增强子代理知识 - 解决主代理和子代理之间知识共享的限制。
• [ ] 研究优先工作流程 - 在从头开始构建时，代理应先进行研究并准备好所有需求，再进行编码。
• [ ] 优雅的错误处理 - 在所有操作中实现更好的错误处理和恢复机制。
• [ ] 自动文档生成 - 自动为每个子代理和主代理的交互生成文档。

如果您有功能请求，请 提交一个问题！

👨‍💻 作者

Aris Setiawan - madebyaris.com

• GitHub: @madebyaris
• 仓库: agent-orchestration