multi-agent-hub

English · 简体中文

一个本地多 AI Agent 调度枢纽：把散落在各处的 AI 编码 CLI 统一成一个可派活、可协作的 Worker 池。

当前版本：v1.0.1 · 协议：Apache-2.0 · 更新日志：CHANGELOG.md

---

目录

• 它能做什么
• 快速开始
• 选择接入方式
• 原生宿主插件
• Worker 与默认模型
• 统一 MCP 工具与任务契约
• Web 控制台
• 实测状态
• 数据流向与安全
• 预打包文件
• 开发与测试
• 版本演进
• 文档导航
• 致谢

---

它能做什么

multi-agent-hub 基于标准 MCP 协议、原生插件与子代理体系，为 11 种 AI 编码 Worker 与 6 款原生宿主（及任意 MCP 客户端）提供统一的任务派发、结果回传、配额监控、账号管理和 WebUI 管理大盘。

接入 Hub 的任意 AI 客户端都能把任务派给其他 AI 执行：各自走自己的账号额度，同时共享任务队列、邮箱与协作笔记。

按接入方式分三类：

核心亮点

• 🤖 统一接入 11 种 Worker：一套契约覆盖 Antigravity、CodeBuddy（国际 / 国内）、GitHub Copilot、MiMo、MiniMax、TraeCode、ZCode、CodeArts、opencode 与 Cline。
• 🔌 深度适配 6 款原生宿主：原生子代理、斜杠命令与工作流，上下文自动隔离，免手动配参数。
• 🔐 WebUI 内完成 11 个 Worker 的登录：9 家 OAuth、cline 设备码授权、opencode API Key 三条路径并存；免 SSH 授权、登出、多账号保存与秒切，以真实凭据落盘判定登录状态，不报假成功。
• ⚡ 一键启停 Worker，全端同步：被禁用的 Worker 在派发前即被拦截（profile_disabled），不浪费额度。
• 🛡️ 严格执行终态判定：拒绝空回答、已知异常退出和超时后的半截回答；保留原任务 ref，禁止 Worker 给自己重复派发。
• 🔄 灵活部署：同机或分离部署；纯 Windows、纯 Linux、Windows ↔ Linux（局域网直连或 SSH 反向通道）均可。
• 🔍 自动发现：局域网 / 本机 Hub 广播扫描，配置恢复后 MCP 桥自动重连；配置与凭据独立于源码，升级不丢任务历史。
• 🖥️ 离线 Demo：demo.html 单文件、零依赖，无需后端即可体验完整控制台。

---

快速开始

环境要求

• Python 3.8+（安装 Codex 原生插件需 3.11+）
• Node.js 20+（MCP 桥接与 Web 控制台）
• 各 Worker 对应厂商的官方 CLI 及其登录态（如 agy、cb、trae、codearts）。安装器只负责环境探测和指令调用，不包含账号注册与自动登录。

三步跑起来

# 1. 获取代码
git clone https://github.com/Johhny-Xu/multi-agent-hub.git
cd multi-agent-hub

# 2. 安装并启动 Hub + Web 控制台 + 本机已有宿主的原生插件
sh install.sh --with-console          # Windows：.\install.cmd --with-console

# 3. 打开控制台
#    http://localhost:8890

• 也可以从 Releases 下载 agenthub-1.0.1-both.zip 解压后执行同样的命令。
• 在源码目录直接执行时，安装器会先在临时目录构建发行包再安装，无需手动打包。
• 日常启停：sh start.sh / sh stop.sh（Windows：start.bat / stop.bat）。
• 想先看看界面：直接用浏览器打开仓库里的 demo.html。

💡 用 sh install.sh 而不是 ./install.sh，可以避免某些解压工具丢失执行位导致的 Permission denied。详见 RUN_ON_LINUX.md。

两个默认端口，别搞混

---

选择接入方式

方案零：一句话交给你的 AI 自动安装（推荐）

把下面对应的一句话复制给你正在用的 AI 助手，它会自动克隆、安装并配置。

方案一：本机一键安装

适合在一台电脑上开发，希望一次配齐 Hub、控制台和已安装 IDE 的插件。按 快速开始 执行即可：安装器会自动检查环境，并探测注册本机上的 Codex、ZCode、DSH、CodeArts、Antigravity 原生插件与子代理。

方案二：任意 MCP 客户端免插件直连

适合 Cursor、Claude Desktop、Windsurf、Cline / Roo Code / Continue 等。先用 --with-console 启动控制台，然后二选一：

• 在控制台「子代理接入端点」卡片点 【复制本文（发给Agent配置）】，把提示词发给 AI，它会自己写好配置；
• 或手动写入：

{
  "mcpServers": {
    "multi-agent-hub": { "url": "http://127.0.0.1:8790/mcp" }
  }
}

可用工具：subagent_run（服务端等结果，大产物落盘只回摘要，不占会话上下文）、subagent_result、subagent_artifact、subagent_agents。

方案三：跨机部署（服务端 + 个人电脑）

适合在家庭服务器、NAS 或云主机上集中运行 Hub 和 Worker，在另一台电脑上写代码。

# 服务端：监听局域网并开启控制台（会在外部配置目录自动生成随机令牌 hub-token.txt）
sh install.sh --component hub --bind 0.0.0.0 --port 8765 --with-console

# 客户端：指定服务器与令牌完成配对
.\install.cmd --component plugins --url http://SERVER_IP:8765/mcp --token-file C:\private\hub-token.txt

• 自动发现：客户端不指定 --url 时会 UDP 广播扫描局域网内的 Hub，交互选择即可。
• 切换 Hub：之后随时运行 connect.cmd（Linux：sh connect.sh）。
• 不在同一局域网：用 SSH 反向通道，例如 ssh -N -R 127.0.0.1:18765:127.0.0.1:8765 user@SERVER。
• Linux 常驻：加 --systemd-user 注册为用户级 systemd 服务（该模式仅支持 Hub，不含控制台）。

方案四：只给某一个宿主装插件

见下一节 原生宿主插件。

---

原生宿主插件

Linux 下把 .\install.cmd 换成 sh install.sh 即可。

---

Worker 与默认模型

上表是新安装的默认值；已有服务器会保留原模型配置。

---

统一 MCP 工具与任务契约

宿主插件通过 MCP 桥暴露 8 个工具：

所有宿主遵循同一套任务契约：

• 附件：files 最多 8 个文件，总量不超过 1 MiB，在 Hub 端暂存。
• 工作目录：cwd 指 Hub 所在主机的目录，不会自动映射客户端路径。
• 结果跟踪：受理后返回持久化 ref，用 hub_fetch 轮询，不要重复派发。completed 只代表执行完成，答案是否正确仍需调用方验收。
• 完整参数见 任务选项说明。

---

Web 控制台

用 --with-console 启用，默认端口 8890。

---

实测状态

回归测试 ≠ 全量付费实测。 下表的回归通过证明框架逻辑正确，不代表每个服务商、模型或宿主都已跑通真实付费任务。

---

数据流向与安全

• 数据链路：宿主客户端 → 本地 MCP 桥 → Hub → 官方 CLI / 内核 → 模型服务商 API。
• 不是离线模型：Hub 只做路由与执行代理，提示词和附件会随官方 CLI 发往各服务商。
• 凭据隔离：Token、API Key 与会话数据都存放在源码目录之外，绝不入库。
• 传输安全：Bearer Token 只负责鉴权；跨公网请配合 HTTPS 反向代理、VPN 或 SSH 隧道。
• 漏洞报告请见 SECURITY.md。

---

预打包文件

自行构建：python packaging/build.py --output --component all。完整参数见 packaging/README.md。

---

开发与测试

# 全量隔离回归（不产生模型费用）
python tests/run_regressions.py --report docs/local-validation.json

# 控制台 DOM / 主题 / 收展断言
node --test tests/console_layout_theme_dom.mjs

# 扫描源码与 Git 历史中的凭据泄漏
python scripts/audit_secrets.py --history

# 改了 console/client/index.html 后重建离线 Demo
python scripts/build_demo.py

# 构建分发包（输出到仓库外）
python packaging/build.py --output ../agenthub-releases

可选：安装下面两个依赖后，原本跳过的真实 SDK / CLI 用例也会执行：

pip install google-antigravity==0.1.21
npm i -g @openai/codex && export CODEX_TEST_BINARY=$(command -v codex)

贡献约定（提交前检查、提交信息规范）见 CONTRIBUTING.md，行为准则见 CODE_OF_CONDUCT.md。

---

版本演进

完整记录见 CHANGELOG.md 与 版本历史。

---

文档导航

入门与部署

• Linux 运行说明
• 安装包构建与完整参数
• 统一任务选项

宿主集成

• Codex · ZCode / MiniMax Code · DSH · Antigravity
• CodeArts 原生插件 · CodeArts IDE & VS Code 扩展
• CodeArts 双向接入与认证边界 · CodeArts IDE 跟进 · CodeArts 接入已有模型路由

版本与验收

• 更新日志 · 版本历史
• 0.9.9 验收记录 · 网络自动发现验收（v0.8）
• 开发交接记录

---

致谢

• LobeHub / Lobe Icons：控制台与子代理头像使用的品牌 SVG 图标。
• TraeClaw：trae_delegate 通道所依赖的本地桥接与 CDP/DOM 自动化。
• Huawei CodeArts、Google Antigravity、Tencent CodeBuddy、GitHub Copilot、Xiaomi MiMo、MiniMax、ByteDance Trae、Z.ai 等官方 CLI 与开放生态。
• 所有提供反馈与建议的开发者。

开源协议

Apache License 2.0：允许使用、修改与分发；衍生作品须保留版权声明、许可证文本及修改说明。