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