Agent Orchestrator

MCP 服务器和 localhost GUI，可将工作路由到 Cursor 智能体和外部 LLM 后端（兼容 OpenAI 的 API、Anthropic、本地 vLLM、Ollama 或自定义 HTTP 智能体）。

Chat (GUI or MCP)
  → Auto router (control tools | single agent | multi-agent debate)
      → Cursor (local or cloud) — can edit allowlisted directories
      → External models — text only
      → Local model server on 127.0.0.1 — never public

快速开始

需要 Node.js 22.13+。

npm install
cp .env.example .env

将 API 密钥放在 .env 或 GUI 的后端页面中——切勿放在 agents.config.yaml 中。apiKeyEnv 是变量名（GEMINI_API_KEY），不是密钥本身。

# GUI (loopback only)
npm run gui

打开打印到 stderr 的 URL（http://127.0.0.1:8787?token=…）。会话令牌存储在 .orchestrator/gui.secret（已被 git 忽略）。

如果端口 8787 已被占用，说明 GUI 已在运行——请使用 gui:stop 或打开现有的令牌 URL。停止本地模型容器不会停止 GUI。

Cursor：此仓库包含 .cursor/mcp.json。克隆后重新加载一次 MCP。list_agents 会重新读取环境变量和 GUI 密钥，无需完全重启 IDE。

Related MCP server: Cloud Agent MCP Server

聊天

主页是一个聊天会话。头部（新建聊天、会话切换器、设置）和输入框保持固定；只有消息滚动。

• 自动（默认）——硬件/下载/启动使用控制工具；当两个或更多后端就绪时，计划/修复/审查使用辩论模式；否则使用单个智能体。

• 辩论 ——圆桌会议：每个就绪的模型依次发言（每个发言者一个气泡），然后由收尾者进行综合。

• 单个 / 固定某个后端——仅使用该后端。

当某个发言者正在运行时，思考中标签会显示名称、已用时间和阶段，让界面看起来不会像是卡住了。

写入和安装操作会等待批准。 在待处理操作卡片上点击批准之前，实施/安装只会停留在计划阶段。之后，Cursor 只能在写入允许列表内进行写入。主机级安装（包管理器、游戏引擎、sudo）会被明确标出并仍需等待。外部模型从不编辑文件。

设置

密钥存放在 .env 和 .orchestrator/secrets.env 中（已被 git 忽略，权限模式 0600）。重新加载环境变量会读取启动后新增的密钥。

安全

不要对 GUI 或 vLLM 做隧道转发。云端 Cursor 智能体无法访问 localhost；orchestrator 在本地与云端之间传递文本。

写入允许列表

默认：当前工作区（WORKSPACE_CWD / workspace.cwd）。可通过设置 → 允许列表或 add_allowed_dir 添加更多。当你提到一个未在列表中的绝对路径时，聊天界面会提供一键添加。

本地模型（与厂商无关）

list_hardware 会探测当前存在的任何加速器（NVIDIA CUDA、AMD ROCm、Intel XPU，如果没有则为 CPU）。推荐使用实测 VRAM，而不是只看单一厂商。当存在其他 GPU 时，缺少 NVIDIA 不会被当作“仅 CPU”。

当估算权重加上约 20% 的 KV-cache 余量 ≤ 单卡 VRAM 时，目录模型适合。当一个模型单卡放不下、但两张卡能放下时，多 GPU 可以使用张量并行。

将快照下载到 .orchestrator/models（已被 git 忽略，必须保留在允许列表中）。受限的 Hugging Face 仓库需要 HF_TOKEN，可放在环境变量或 GUI 中——绝不能放入 git。

start_vllm 会根据检测到的后端选择服务栈：

• CUDA — 当安装了 CUDA wheel 时，使用宿主机 vllm serve

• ROCm — 如果存在 ROCm vLLM，则使用它

• XPU — 如果供应商 Docker 镜像已在本地，则使用它们；否则使用宿主机 XPU 构建

• CPU — 不用于服务路径

API 仅在 127.0.0.1 上发布（端口 8000–8099）。启动会立即返回（202）；请在本地模型页面上等待，直到 /v1/models 健康。运行中的服务器会自动注册为后端（如果客户端要求 Bearer，则使用虚拟回环令牌——你无需从容器中复制密钥）。

你可以同时运行多个模型。每个目录 ID 都有自己独立的容器、端口和后端（vllm-<catalog-slug>）。停止某个实例；从组合中移除还会从 YAML 中删除该后端；删除权重需要单独确认。

pip install -r scripts/requirements-hf.txt   # downloads
# Then install the vLLM build that matches your GPU (CUDA, ROCm, or vendor XPU/Docker).

MCP 工具

默认专家

只有 Cursor 后端会编辑文件。将 backend 指向 agents.config.yaml 中的任意 ID。

添加后端

backends:
  groq:
    type: openai
    baseUrl: https://api.groq.com/openai/v1
    model: llama-3.3-70b-versatile
    apiKeyEnv: GROQ_API_KEY

specialists:
  groq-reviewer:
    description: Fast external review
    backend: groq
    fallback: reviewer

Gemini 使用 Google 的 OpenAI 兼容端点。设置一个当前模型 ID（当密钥有效时，GUI 会列出 Google 提供的 ID）。不要在 model 中放注释或 pro / flash 列表。

YAML 中的 ${ENV_NAME} 会从进程环境变量展开。

从其他仓库使用

{
  "mcpServers": {
    "agent-orchestrator": {
      "type": "stdio",
      "command": "/absolute/path/to/this-repo/node_modules/.bin/tsx",
      "args": ["/absolute/path/to/this-repo/src/index.ts"],
      "env": {
        "AGENT_ORCHESTRATOR_CONFIG": "/absolute/path/to/this-repo/agents.config.yaml",
        "WORKSPACE_CWD": "${workspaceFolder}",
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

哪些内容不在 git 中

.env、.orchestrator/（GUI 令牌、密钥、聊天记录、允许列表、模型权重、vLLM 状态）、node_modules/ 和日志。参见 .gitignore。