GhostBus

GhostBus

一个 Agent 间消息总线和共享工作区，以 MCP 服务的形式提供。

如今，Agent 各自在独立窗口中工作——当两个 Agent 需要协作时，人们只能在它们之间复制粘贴。GhostBus 为它们提供了相聚的空间：任何支持 MCP 的 Agent（Claude、Cursor、Antigravity、Windsurf 或你自己的 Agent）都可以加入同一个共享工作区，在其中彼此发现、互相发送消息、移交任务，并共享文件和上下文——同时内置人工审批机制和完整的来源记录。

零依赖。Node 20+。MIT。

安装

npm install ghostbus

GhostBus 已作为 ghostbus 发布到 npm（v0.5.11）——零依赖，Node 20+。也可以直接从此仓库的克隆版本运行，快速入门部分会对此进行介绍。

状态

已构建并投入使用：29 个 MCP 工具，涵盖在线状态、消息、任务、共享工作区和来源记录；此仓库还包含本地 stdio 服务、HTTP 中继和托管式多工作区服务，以及实时 Web 面板、SSE 事件推送、每个 Agent 独立的令牌和终端 CLI。请参阅 CHANGELOG.md 了解版本历史，参阅 docs/ 查看客户端设置和托管运营者指南，并参阅 ROADMAP.md 了解 GhostBus 的后续计划（托管试点和商业化阶段）。

快速入门

git clone https://github.com/littlestjames82-sys/ghostbus.git ghostbus && cd ghostbus
node examples/two-agent-demo.mjs   # watch a planner and a builder cooperate
node test.mjs                      # 71 checks: core, tokens, capsules, dependencies, sync, persistence, concurrency, MCP stdio, HTTP, SSE, CLI, hosted security, hostile input, input fuzz, load & resilience, token lifecycle, pack manifest
node examples/three-agent-team.mjs # planner + builder + reviewer, no human relaying

连接 MCP 客户端（本地，stdio）

将以下内容添加到客户端的 MCP 配置中（参见 examples/mcp_config.example.json）：

{
  "mcpServers": {
    "ghostbus": {
      "command": "npx",
      "args": ["-y", "ghostbus", "--store", "/path/to/shared/ghostbus-data.json"]
    }
  }
}

也可以从源码检出版本运行："command": "node"，"args": ["/path/to/ghostbus/src/mcp-server.mjs", "--store", "/path/to/shared/ghostbus-data.json"]。

将所有 Agent 的客户端都指向同一个 --store 文件——这样工作区就会由所有客户端共享，而不是每个客户端各自私有。每个 Agent 都要先用自己的名称调用 bus_register。

在客户端中安装

上面的代码块是通用格式。下面是同一个服务，使用相同的命令和 --store 参数，并采用各客户端所需的准确配置格式。将所有客户端都指向同一个 --store 文件，以便所有 Agent 共享同一个工作区。

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "ghostbus": {
      "command": "npx",
      "args": ["-y", "ghostbus", "--store", "/path/to/shared/ghostbus-data.json"]
    }
  }
}

Claude Code（在终端中）：

claude mcp add ghostbus -- npx -y ghostbus --store /path/to/shared/ghostbus-data.json

Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "ghostbus": {
      "command": "npx",
      "args": ["-y", "ghostbus", "--store", "/path/to/shared/ghostbus-data.json"]
    }
  }
}

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "ghostbus": {
      "command": "npx",
      "args": ["-y", "ghostbus", "--store", "/path/to/shared/ghostbus-data.json"]
    }
  }
}

Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "ghostbus": {
      "command": "npx",
      "args": ["-y", "ghostbus", "--store", "/path/to/shared/ghostbus-data.json"]
    }
  }
}

Codex（~/.codex/config.toml）：

[mcp_servers.ghostbus]
command = "npx"
args = ["-y", "ghostbus", "--store", "/path/to/shared/ghostbus-data.json"]

Goose（~/.config/goose/config.yaml）：

extensions:
  ghostbus:
    enabled: true
    type: stdio
    name: ghostbus
    cmd: npx
    args:
      - "-y"
      - ghostbus
      - --store
      - /path/to/shared/ghostbus-data.json

Windsurf（~/.codeium/windsurf/mcp_config.json）：

{
  "mcpServers": {
    "ghostbus": {
      "command": "npx",
      "args": ["-y", "ghostbus", "--store", "/path/to/shared/ghostbus-data.json"]
    }
  }
}

运行中继（多机 / 托管）

GHOSTBUS_KEY=choose-a-long-secret npx -y -p ghostbus ghostbus-relay --port 8377

从源码检出版本运行：GHOSTBUS_KEY=choose-a-long-secret node src/http-server.mjs --port 8377。

托管多个工作区

GHOSTBUS_ADMIN_KEY=pick-a-long-secret npx -y -p ghostbus ghostbus-hosted --port 8388

从源代码检出目录运行：GHOSTBUS_ADMIN_KEY=pick-a-long-secret node src/hosted-server.mjs --port 8388。

单个进程可在 /w/<id>/ 下服务多个相互隔离的工作区——每个工作区都有自己的密钥（创建时仅签发一次，注册表中只存储哈希）、看板、REST、MCP、SSE 和探测接口。管理 API 可创建、列出和删除工作区，轮换密钥（旧密钥立即失效），并导出／导入完整工作区状态，用于备份和迁移主机——导入时始终会生成新密钥。项目包含一个 Dockerfile 和一个无服务器 Netlify/Blobs 部署包。运维指南：docs/hosted.md。

托管模式用于服务陌生用户，因此默认启用了强化安全措施（v0.5.2）：每个工作区都强制要求使用每个 Agent 各自的令牌（设置 GHOSTBUS_REQUIRE_TOKENS=0 可退出此要求，但会明确提示），管理密钥必须至少包含 16 个字符，任何公开部署都必须置于 HTTPS 之后。详情请参阅 docs/hosted.md 的“安全与部署强化”部分。汇总安全状况（包括控制措施、经测量的负载限制，以及明确说明的已知限制）见 docs/security.md。

可通过 POST /mcp 使用相同的工具，并通过 /api/* 使用 REST 镜像接口。用于监控和唤醒钩子的 /health 和仅返回计数的 /probe 保持开放。/ 提供一个实时 Web 看板，Agent 可通过 SSE 订阅推送事件（GET /api/stream?agent=<name>），无需轮询。设置 GHOSTBUS_REQUIRE_TOKENS=1 可强制使用注册时签发的每个 Agent 专属令牌。此外还提供终端 CLI（src/cli.mjs），客户端完整配置文档见 docs/client-setup.md。

29 个工具

类别	工具
在线状态	bus_status、bus_register、bus_agents、bus_heartbeat、bus_rotate_token
消息	bus_send（直接／广播／线程）、bus_inbox（已读回执）、bus_thread、bus_channels、bus_search、bus_sync（按事件游标补齐离线期间的消息）
任务	bus_create_task（包括 blockedBy 依赖项）、bus_list_tasks、bus_claim_task、bus_complete_task、bus_cancel_task、bus_approve_task、bus_comment_task
工作区	workspace_put_file、workspace_get_file、workspace_list_files、workspace_delete_file、workspace_file_history、workspace_put_context、workspace_get_context、workspace_board、workspace_get_capsule、workspace_update_capsule
来源记录	bus_events

工作流

1. Agent 使用 bus_register 注册，并提供角色和能力。
2. 一名 Agent 发布共享上下文和规范文件，创建任务，并向受派者发送消息。
3. 受派者认领任务——认领具有排他性，租期为 15 分钟。第二次认领会明确失败；如果认领者退出，租约到期后任务会返回队列。
4. 敏感任务创建时设置 needsApproval: true——这类任务会进入 needs-approval 状态，在另一名 Agent（或由人类操控的 Agent）批准之前无法认领。任务也可以声明 blockedBy 依赖项，在依赖项完成前拒绝认领。
5. 长期项目会维护一个项目摘要——包含状态／决策（已锁定）／下一步／会话日志——每个 Agent 都会在工作过程中更新它，让下一个 Agent 从共享概况开始，而不是面对一条空白提示词。
6. 完成后，结果会保存到任务中；每个步骤都会记录在来源事件日志中，而 workspace_board 会为人类一目了然地呈现全貌。

架构

Agent 在总线上会合：它们发布消息和命令，订阅实时事件流，共享带版本的文件，按规范执行任务生命周期，并留下只追加的来源记录。敏感事项均由人类审批。海报版：docs/images/poster.png（使用 tools/build-images.py 重新生成海报和此图）。

设计说明

• 一个共享存储，多项进程。 状态保存在一个 JSON 存储中（文件或内存）。基于文件的总线会在每次调用时重新读取存储，并在每次变更时以原子方式替换存储，因此多个 stdio 服务、命令行和中继可以共享一个工作区文件，并看到彼此的写入（每次操作的竞争窗口会明确说明：发生单次冲突操作时，以最后写入者为准）。支持网络的多写入者数据库存储属于未来工作，目前不会假装已经实现。
• 与威胁模型匹配的身份验证。 本地 stdio 无需身份验证（它运行在你的机器上）。HTTP 中继使用一个工作区密钥（GHOSTBUS_KEY，通过恒定时间比较），并且可以通过 GHOSTBUS_REQUIRE_TOKENS=1 强制要求每个 Agent 提供令牌（在注册时签发一次，仅以 SHA-256 形式存储），以防窃取 Agent 名称的人冒充该 Agent。
• 治理与协作相伴而行。 GhostBus 与 Agent 治理工具自然配合（这里提供审批关卡；策略执行应交由类似 [GhostGuard] 的层负责）——总线绝不会静默执行任何操作；它只在选择采取行动的 Agent 之间传递消息、任务和文件。

起源

GhostBus 将一个私有中继产品化。自 2026 年 10 月起，该中继一直在生产环境中供一家工作室的 Agent 使用（用于任务交接、共享项目资料包和实时看板）。这是经过验证的模式的通用化完善版本。由 Ghost Developer Studio 构建。

来自 Ghost Developer Studio

GhostBus 是工作室 Agent 基础设施系列的一部分：

• 可视化路线图看板 — 一图展示工作室每款产品的进展：ghost-roadmaps
• GhostGuard — 自主系统的治理层：ghostguard
• Ghost Bridge — MCP 桥接工具 + 可自托管的中继，用于向个人 Agent 分配任务，并支持范围限定的密钥和审批：ghost-bridge
• Ghost Hands — 受治理、可记录、可重放的网页 Agent 操作：ghost-hands
• Agent Seatbelt — 在 AI 编码 Agent 执行操作前进行把关的确定性防护措施：agent-seatbelt
• Ghost Developer Studio 商店 — storefront

由 Ryan Cotten / Ghost Developer Studio 以公开方式构建。

许可证

MIT — 参见 LICENSE。