multi-agent-hub

English · 简体中文

multi-agent-hub 是一个本地多 AI Agent 调度 Hub，把电脑上散落的 14 种 AI 编码 CLI（被调度的执行端，统称 Worker）连通为一个共享任务池。当你同时使用 CodeBuddy、Copilot、Antigravity、TraeCode 等多家工具时，无需在单个账号额度见底后手动切工具或重述需求——当前客户端可直接把任务派给另一个 AI 接力完成。

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

核心亮点

• 🤖 一套契约调度 14 种 Worker：覆盖 Antigravity、CodeBuddy（国际版 / 国内版）、Qoder（国际版 / 国内版）、GitHub Copilot、MiMo、MiniMax、TraeCode、ZCode、CodeArts、opencode、Cline 与 Meoo（秒悟），任务各自消耗对应账号额度，共享同一任务队列、邮箱与协作笔记。
• 🔌 6 款原生宿主免手配参数：安装器自动写入原生子代理、斜杠命令与工作流，子代理上下文与主会话自动隔离。
• 🔐 WebUI 内完成全部 14 个 Worker 登录与切号：同时支持 9 家 OAuth、Cline 设备码授权、opencode API Key 三条路径；免 SSH 登录、登出、多账号保存与秒切，仅凭落盘真实凭据判定登录态，杜绝假成功。
• ⚡ 一键启停 Worker，全端立即生效：在控制台关闭某个 Worker 后，所有客户端的派发请求在执行前即被拦截（返回 profile_disabled），不白扣额度。
• 🛡️ 严格终态判定，拒绝半截结果：自动拦截空回答、已知异常退出和超时后的残缺回答；全程保留原任务 ref（任务追踪编号），且禁止 Worker 给自己递归派活。
• 💓 子代理存活深度感知（hub_task_status）：主代理异步派发后可随时探查子代理真实存活状态（PID、整棵进程树 CPU 消耗、输出增量与心跳），智能给出 working（真在计算）、alive_waiting（思考/排队中）与 worker_exited_result_missing（异常退出）等判定，杜绝长任务因 CLI 静默被主代理按墙钟误判卡死，且 CPU 增长自动续期防误杀。
• 🔄 支持单机与跨机混合部署：支持纯 Windows、纯 Linux、Windows ↔ Linux（局域网直连或 SSH 反向通道）；配置与凭据存放在源码目录外，升级版本不丢历史。
• 🔍 局域网自动发现与断线重连：客户端可通过 UDP 广播自动扫描局域网内的 Hub；配置恢复后 MCP 桥自动重连。
• 🖥️ 单文件离线预览：双击仓库根目录的 demo.html 即可在浏览器体验完整三栏控制台，无需启动后端。

---

目录

1. 30 秒上手
2. 三种接入方式怎么选
3. 原生宿主插件安装
4. 支持的 Worker 与默认模型
5. MCP 工具与任务契约
6. Web 控制台能看什么
7. 实测状态与边界
8. 数据流向与安全
9. 预打包文件与开发测试
10. 版本演进、文档导航与协议

---

30 秒上手

三步命令即可在本地同时拉起 Hub 调度服务、Web 控制台，并自动为本机已有的宿主装好插件。

环境要求

• Python 3.8+（若需安装 Codex 原生插件需 3.11+）
• Node.js 20+（用于运行本地 MCP 桥接与 Web 控制台）
• 各 Worker 对应的厂商官方 CLI 及其登录态（如 agy、cb、trae、codearts）。安装器负责探测环境与调用命令，不会替你注册账号。

启动命令

Linux / macOS

git clone https://github.com/Johhny-Xu/multi-agent-hub.git
cd multi-agent-hub
sh install.sh --with-console

Windows (PowerShell / CMD)

git clone https://github.com/Johhny-Xu/multi-agent-hub.git
cd multi-agent-hub
.\install.cmd --with-console

安装成功后你能看到什么

• 浏览器打开 http://localhost:8890，即可看到三栏式 Web 控制台（左侧活动栏与会话树、中间对话区、右侧工作台与 14 张 Worker 状态卡片）。
• 也可以从 Releases 下载 agenthub-1.0.19-both.zip 解压后执行同一条安装命令；在源码目录直接运行时，安装器会先在临时目录打包再安装，无需手动构建。
• 日常启停：sh start.sh / sh stop.sh（Windows：start.bat / stop.bat）。
• 只想先看界面：直接用浏览器打开仓库里的 demo.html。

💡 Linux 下请用 sh install.sh 而非 ./install.sh，可避免解压工具丢失可执行权限导致的 Permission denied。详见 RUN_ON_LINUX.md。

三个默认端口对照

---

三种接入方式怎么选

你可以把安装命令直接交给正在使用的 AI 助手自动执行，也可以按单机、免插件或跨机场景手动配置。

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

把下面对应场景的一段话发给你正在使用的 AI 客户端，它会自动完成克隆、安装与连通性验证。

方案一：本机一键全量安装

适合在一台电脑上写代码，希望一次配齐 Hub、控制台和本机所有已装 IDE 的原生插件。直接执行 30 秒上手 中的命令即可，安装器会自动探测并注册本机的 Codex、ZCode、DSH、CodeArts、Antigravity 插件与子代理。

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

适合 Cursor、Claude Desktop、Windsurf、Cline / Roo Code、Continue 等客户端。先用 --with-console 启动控制台，再任选一种方式配置：

1. 在 http://localhost:8890 控制台的「子代理接入端点」卡片点击 【复制本文（发给Agent配置）】，把提示词粘贴给你的 AI 自动写配置；
2. 或手动在客户端 MCP 配置文件中加入：

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

接入后可调用 4 个工具：subagent_run（服务端等待结果，大体积产物自动落盘并只回传摘要，不挤占主对话上下文）、subagent_result、subagent_artifact、subagent_agents。

方案三：跨机分离部署（服务器跑 Worker + 个人电脑写代码）

适合把 Hub 和各家 CLI 集中装在家庭服务器、NAS 或云主机上，在主力笔记本上写代码。需要将 替换为服务器 IP，将 替换为保存 hub-token.txt 的本地路径。

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

# 2. 客户端（Windows）：指定服务器地址与拷贝过来的令牌文件完成配对
.\install.cmd --component plugins --url http://:8765/mcp --token-file 

• 局域网自动发现：客户端不传 --url 时，会通过 UDP 广播扫描局域网内的 Hub 并提供列表供交互选择。
• 随时切换连接的 Hub：运行 connect.cmd（Linux：sh connect.sh）。
• 跨公网 / 异地连接：通过 SSH 反向通道转发，例如 ssh -N -R 127.0.0.1:18765:127.0.0.1:8765 @.
• Linux 后台常驻：安装服务端时追加 --systemd-user 可注册为用户级 systemd 服务（该模式仅托管 Hub 核心服务，不含 Web 控制台）。

---

原生宿主插件安装

如果你只想给某一款宿主单独安装插件，可按宿主的插件机制导入预打包扩展或执行定向命令（命令中的 `` 需替换为你的项目目录，Linux 下将 .\install.cmd 换为 sh install.sh）。

---

支持的 Worker 与默认模型

Hub 统一管理以下 14 种 Worker；表中所列为全新安装时的默认模型，升级已有服务器会保留你原有的模型配置。

---

MCP 工具与任务契约

所有原生宿主插件均通过本地 MCP 桥暴露相同的 9 个标准工具，并遵循统一的附件与目录契约。

任务契约三原则

1. 附件上限：files 单次最多附带 8 个文件，总大小不超过 1 MiB，发送后在 Hub 端暂存。
2. 工作目录归属：cwd 指 Hub 所在服务器上的目录路径，不会自动映射客户端本机路径。
3. 结果跟踪与存活验收：任务受理后返回持久化 ref。长任务建议通过 hub_task_status 查看子代理存活状态（读取 PID、整棵进程树 CPU 时间、输出增量与心跳，返回 working / alive_waiting / worker_exited_result_missing 等 verdict，首次调用建立基线，10 秒后再查可看 CPU/输出增量），确认还在计算时耐心等待，杜绝主代理误杀；完成后再用 hub_fetch 取回最终结果。状态为 completed 仅代表进程正常返回非空回答，代码与逻辑是否正确仍由调用方验收。完整参数见 任务选项说明。

---

Web 控制台能看什么

启动时加上 --with-console 即可通过 http://localhost:8890 访问内置控制台，在一个页面里完成对话派活、切号、查额度与看产物。

---

实测状态与边界

重要声明：回归测试通过 ≠ 所有商业模型均已完成付费实测。 下表中的自动化回归与压测证明调度框架、协议桥接与进程管理逻辑正确，不代表每个第三方厂商、模型或宿主都在你的账号环境下跑通了付费任务。

使用边界说明

1. Antigravity 原生插件 vs 可选 SDK：原生插件已跑通真实派发；可选 Python SDK 属于外部编排库，当前官方 wheel 不含 beta.run_workflow，且鉴权与宿主登录态隔离。
2. CodeArts 鉴权隔离：在 CodeArts IDE 内登录不等于独立 CLI 自动获得调用权限；其他厂商的登录态也不能替代华为账号的 AK/SK 或 OAuth 权限；当前仅开放默认思考档位与非流式文本。
3. 非跨 Hub 联邦：一个客户端同一时间指向一个选定的 Hub，并非多 Hub 联邦网络。

完整验收回执、源码哈希与失败日志见 0.9.9 验收记录 及 CodeArts IDE 跟进记录。

---

数据流向与安全

Hub 仅在本地或你的私有服务器内做协议转换与进程调度，所有凭据均与代码仓库物理隔离。

• 完整数据链路：宿主客户端 → 本地 MCP 桥 → Hub 服务 → 厂商官方 CLI / 内核 → 对应模型服务商 API。
• 不是离线大模型：Hub 本身不推理，你的提示词与附件最终会通过你所选 Worker 的官方 CLI 发往对应模型厂商。
• 凭据物理隔离：Hub 访问 Token、各厂商 API Key、OAuth 凭据与会话历史全部存放在源码目录外的系统配置目录中，绝不写入 Git 仓库。
• 公网传输建议：Bearer Token 仅用于接口鉴权，不加密报文；若跨公网部署，请务必配合 HTTPS 反向代理、VPN 或 SSH 隧道使用。
• 发现安全漏洞请按 SECURITY.md 中的流程私密报告。

---

预打包文件与开发测试

预打包发行文件

所有发行包均附带 SHA256SUMS 校验文件，可直接从 Releases 下载或自行构建：

常用开发与测试命令

在仓库根目录下可执行以下自检与打包命令（将 `` 替换为实际路径，如 ../agenthub-releases）：

# 1. 运行全量隔离回归测试（纯本地沙箱，不消耗任何模型额度）
python tests/run_regressions.py --report docs/local-validation.json

# 2. 运行 Web 控制台 DOM 结构、主题对比度与收展交互断言
node --test tests/console_layout_theme_dom.mjs

# 3. 扫描工作区源码与全部 Git 历史，确保无凭据泄漏
python scripts/audit_secrets.py --history

# 4. 修改 console/client/index.html 后重新生成单文件离线 Demo
python scripts/build_demo.py

# 5. 构建全套分发包（必须输出到仓库外目录）
python packaging/build.py --output  --component all

如需运行默认跳过的真实 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，打包参数详见 packaging/README.md。

---

版本演进、文档导航与协议

近期版本演进

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

文档导航

• 部署与参数：Linux 运行说明 · 安装包构建与完整参数 · 统一任务选项
• 宿主插件指南：Codex · ZCode / MiniMax Code · DSH · Antigravity · CodeArts 原生插件 · CodeArts IDE & VS Code 扩展
• CodeArts 专题：双向接入与认证边界 · CodeArts IDE 跟进记录 · 接入已有模型路由
• 验收与交接：0.9.9 验收记录 · 网络自动发现验收（v0.8） · 开发交接记录 · v1.0.18 交接记录 · 10-24 交接（WebUI 拆分 / 美化 / 贡献图）

致谢

• LobeHub / Lobe Icons：提供控制台与 Worker 头像使用的品牌 SVG 图标。
• TraeClaw：提供 trae_delegate 通道依赖的本地桥接与 CDP/DOM 自动化方案。
• L0NE-6/Qoder-Daily：Qoder / Qoder CN 每日签到的实现参考。forceRefresh 实时活动列表、CLAIM_BENEFIT 定向活动筛选与领取语义、token 续期链路，以及用本机 UMID 组件（runtime-info）生成 Cosy-MachineToken / Cosy-MachineCode / Cosy-MachineType 设备风控头的方案，均移植自该项目——国际版的每日积分活动只对带这些头的请求下发。感谢作者的无私分享。
• L0NE-6/Trae-AutoCheckin：Trae 每日签到的实现参考。req_source 请求体、必须使用客户端真实注册设备号（iCubeAuthInfo://icube-dc:）、状态 → 领取 → 同设备号回查确认的判定链、9095/9074/1001 的语义、以及用 refreshToken + 设备证明（ECDSA P-256）走新版 ExchangeToken 续期的方案，均移植自该项目。感谢作者的无私分享。
• @user_3a370331/totorosir-minimax-checkin（作者 龙猫科技说 longmaoit）：MiniMax Code（海螺 AI）每日签到的实现参考。signin/status → signin/claim 的两步链路、x-signature / yy 两套签名与固定参数键序、日状态与 claim_result 的语义、以及用 refresh_token 续期并把新凭证回写客户端登录态的做法，均移植自该技能。感谢作者的无私分享。
• Huawei CodeArts、Google Antigravity、Tencent CodeBuddy、GitHub Copilot、Xiaomi MiMo、MiniMax、ByteDance Trae、Z.ai、opencode、Cline 等官方 CLI 与开放生态，以及所有提交反馈的开发者。

开源协议

本项目基于 Apache License 2.0 开源：允许自由使用、修改与分发；衍生作品须保留原始版权声明、许可证文本及修改说明。