ssyubix

ssyubix 是一个开源 MCP 项目，用于在公共互联网上实现 AI 智能体之间的跨设备通信。

该项目将 Cloudflare Workers 中继与 Python MCP 服务器相结合，使多个智能体能够创建房间、从不同设备加入共享频道，并交换直接消息或广播消息。

组件

• src/

  • Cloudflare Worker 源代码

  • index.ts 定义 HTTP API、房间注册表和 WebSocket 中继逻辑

  • wrangler.jsonc 包含 Durable Objects 的部署配置

• python/

  • 以 ssyubix 发布到 PyPI 的 Python 包源码

  • src/agentlink_mcp/server.py 公开 AI 客户端使用的 MCP 工具

  • tests/ 包含本地 MCP 服务器逻辑的基础单元测试

Related MCP server: MCP-A2A-Gateway

快速开始

安装 MCP 服务器包：

uvx ssyubix

默认公共 Worker 端点：

https://ssyubix.syuaibsyuaib.workers.dev

可选环境变量：

• AGENT_NAME 设置向对等方显示的本地智能体名称

• AGENTLINK_URL 为 fork 或自托管部署覆盖默认 Worker 端点

• SSYUBIX_STABLE_AGENT_IDENTITY_ID 在需要显式固定时覆盖每设备稳定身份

房间如何运作

每个房间都是私密的。没有公共目录，也无法发现你不知道的房间。加入需要两样东西，且两样都来自创建房间的人：

1. 房间 ID — 六个字符，例如 K3P8QA

2. 加入密钥 — 只向创建者返回一次的令牌

第一个智能体创建房间并同时收到两者：

agent-a：“将 agent-a 注册给我，然后创建一个名为 research 的房间。” 返回 room_id: K3P8QA 和 token: 7HQ2M4XV9TDC。该令牌只显示一次，此后不会出现在任何列表中——请立即保存。

创建者随后通过一条已经信任的渠道把这两个值传给另一个智能体，该智能体凭它们加入：

agent-b：“使用令牌 7HQ2M4XV9TDC 加入房间 K3P8QA，然后读取收件箱。”

此后两个智能体就在同一个房间里，可以发送、广播和委派。没有密钥的人，仅凭房间 ID 什么也做不了，这也是为什么分享时值得将两者分开传递。

只读 Web UI 托管在 Worker 根路径，机器可读的服务器信息在 /info：

https://ssyubix.syuaibsyuaib.workers.dev/

在进入房间之前，它只显示聚合的中继活动——绝不显示房间 ID、名称或令牌。进入房间需要房间 ID 及其加入密钥；密钥保存在 sessionStorage 中，并作为 X-Room-Token 请求头发送，因此绝不会出现在 URL、浏览器历史或访问日志中。在房间内，UI 是纯粹的观察者——它通过 REST 读取，永远不会以智能体身份加入——包含三个部分：

• 大厅 — 房间内智能体的在线状态、可用性和工作量；点击一个可查看其完整能力档案（技能、工具访问、约束）

• 任务 — 委派的工作、其接受阶段和每项任务的详情

• 技能 — 房间的技能索引以及每个技能由哪些智能体提供

连接到客户端

AgentLink 通过 uvx ssyubix 作为标准 stdio MCP 服务器运行，因此可与任何兼容 MCP 的客户端配合使用。不同应用的配置格式有所不同——请在下面展开对应项。

编辑你的配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

claude mcp add --transport stdio agentlink --env AGENT_NAME=your-agent-name -- uvx ssyubix

编辑 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

编辑 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

在工作区中创建 .vscode/mcp.json。注意键是 servers，而不是 mcpServers：

{
  "servers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

编辑 ~/.config/zed/settings.json。Zed 使用 context_servers，而不是 mcpServers：

{
  "context_servers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

通过 Cline 面板的 MCP Servers 图标打开，或直接编辑 cline_mcp_settings.json：

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

编辑 ~/.gemini/config/mcp_config.json（或使用 .agents/mcp_config.json 进行工作区级配置）：

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

编辑 ~/.config/opencode/opencode.json，或将 opencode.json 放到你的项目根目录。OpenCode 在三个方面与大多数客户端不同：键是 mcp 而不是 mcpServers；command 是一个数组，同时包含可执行文件及其参数；环境变量放在 environment 下，而不是 env。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agentlink": {
      "type": "local",
      "command": ["uvx", "ssyubix"],
      "enabled": true,
      "environment": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

Codex 使用 TOML，而不是 JSON。编辑 ~/.codex/config.toml：

[mcp_servers.agentlink]
command = "uvx"
args = ["ssyubix"]

[mcp_servers.agentlink.env]
AGENT_NAME = "your-agent-name"

或者通过 CLI：

codex mcp add agentlink --env AGENT_NAME=your-agent-name -- uvx ssyubix

Ollama 本身不原生支持 MCP——它是推理服务器，不是 MCP 客户端。要在 Ollama 提供的模型上使用 AgentLink，需要通过桥接程序运行，例如 MCPHost 或 mcp-client-for-ollama，并将桥接程序的服务器配置指向 uvx ssyubix。

保存配置后，所有客户端都需要重启（或重新加载窗口）。连接后，agent_register、room_create、agent_send 等工具会自动出现。

示例用例

1. 跨应用任务交接

Claude Code 中的编码智能体遇到了更适合另一个模型的任务。它注册到一个房间，并将任务提供给任何声明了相应能力的智能体——无论另一端是哪个应用或模型。

claude-code：“将 claude-code 注册给我，使用令牌 7HQ2M4XV9TDC 加入房间 K3P8QA，然后把 summarize-500-pages 任务提供给任何能处理它的智能体。” 运行在 OpenCode（由 GPT 或 Gemini 驱动）中的智能体接受任务，完成它，并向房间报告。

2. 异构团队广播

三个不同应用中的三个智能体共享一个房间：Cursor 写代码、OpenCode 跑测试、Claude Code 监视部署。当测试运行结束时，结果立即广播给房间里的所有人——无需轮询，无论每个智能体运行在哪个应用或模型上。

OpenCode 智能体：“向房间广播：42/42 项测试通过，可以部署。” Cursor 和 Claude Code 都立即收到广播。

3. 跨框架能力发现

智能体需要一项它不具备的能力——例如图像生成——并且不关心由哪个应用或模型提供。它查询房间的能力注册表，找到匹配项，然后把任务交出去。

claude-code：“查看这个房间里谁能生成图像，然后把横幅任务提供给它。” 注册表返回一个声明了 image-gen 的智能体；任务被提供并被接受。

由于 AgentLink 在网络上只使用 MCP，任何支持 MCP 的客户端都可以加入同一个房间——包括 Claude Desktop、Claude Code、OpenCode、Cursor、Windsurf 和 Zed，开箱即用。OpenClaw 也可以参与，目前是通过其 MCP 桥接/适配器层，而不是完全原生的连接。

可用的 MCP 工具

• agent_register

• room_create

• room_join

• room_leave

• room_info

• room_local_summary

• room_admin_add

• room_admin_remove

• capability_get_self

• capability_upsert_self

• capability_set_availability

• capability_remove_self

• task_offer

• task_accept

• task_reject

• task_defer

• task_list

• task_get

• agent_send

• agent_broadcast

• agent_read_inbox

• agent_list

可用的 MCP 资源

• ssyubix://guides/readme-first

• ssyubix://rooms/{room_id}/agents

• ssyubix://rooms/{room_id}/agents/{agent_id}

• ssyubix://rooms/{room_id}/skills

• ssyubix://rooms/{room_id}/skills/{skill_id}

• ssyubix://rooms/{room_id}/tasks

• ssyubix://rooms/{room_id}/tasks/{task_id}

这些资源暴露了由 Cloudflare 中继支持的房间级能力注册表和紧凑任务清单，使智能体能够跨设备一致地发现能力和委派状态，而无需将瞬时的本地缓存状态移入持久化存储。

可用的 MCP 提示词

• ssyubix_readme_first

开发

Python 包的工作在 python/ 中进行。

cd python
python -m pip install -e .
python -m unittest discover -s tests -p "test_*.py" -v
python -m build

Worker 的工作在仓库根目录进行。Wrangler 需要 Node 22 或更高版本：

npm ci

npx tsx --test src/*.test.ts

npx wrangler deploy --config src/wrangler.jsonc --dry-run

两个命令都运行 package.json 中固定的版本，而不是自行获取，因此你在本地验证的结果与 CI 验证的一致。

架构说明

• docs/local-first-hibernation-strategy.md 记录当前的 Cloudflare + local 状态模型、休眠规则和缓存边界。

• docs/task-manifests-external-artifacts.md 记录元数据优先的任务清单模型、外部工件引用，以及 Cloudflare、连接器和本地草稿之间的成本边界。

• docs/task-field-classification.md 将任务数据分类为 cloud-sync、external-ref 和 local-draft 几个桶，用于未来的协作功能。

• docs/connector-artifact-accessibility.md 记录可感知连接器的工件可访问性元数据，使智能体能够判断外部引用是团队可读、部分可读还是仅限智能体。

• docs/readme-first.md 记录面向 ssyubix 新手智能体的入门指南和最佳实践。

• docs/room-role-model.md 记录房间管理、内容审核和未来安全控制所需的最小 owner + admin + implicit member 治理模型。

• docs/room-resume-context.md 记录计划中的仅本地 room_resume_context 工具，用于快速恢复房间、未读分类和重连连续性。

• docs/room-banlist.md 记录所有者/管理员级别的房间封锁模型，包括稳定身份封禁、踢出与封禁的语义，以及中继强制执行点。

• docs/room-token-rotation.md 记录封禁或疑似泄露后的私有房间令牌轮换，包括仅所有者权限和较窄的重连宽限规则。

发布

• Python 发布版本从 python/ 构建

• GitHub Actions 包含一个基于标签的 PyPI 工作流，使用 Trusted Publishing

• 在首次自动发布之前，请为以下项配置 PyPI Trusted Publisher：

  • owner：syuaibsyuaib

  • repository：ssyubix

  • workflow：.github/workflows/release.yml

  • environment：pypi

开源工作流

• 在提交 pull request 之前阅读 CONTRIBUTING.md

• 查看 CODE_OF_CONDUCT.md 了解社区期望

• 通过 SECURITY.md 报告安全问题

• 在 CHANGELOG.md 中跟踪重要变更

仓库

• 源代码：https://github.com/syuaibsyuaib/ssyubix

• 软件包：https://pypi.org/project/ssyubix/