swarm-rd-orchestrator

这是一个基于 SQLite WAL 的仅追加事件日志，由 Ray actor 封装而成，因此并行 Agent 可以写入发现并拉取彼此的发现，无需共享可变存储；此外还提供命令行和 MCP 服务，方便人类和其他 Agent 直接使用。

这是 Milestone 1 原型（2026-08-03）：在继续开发前，先通过实际任务验证方案。请参阅下文的已锁定决策和 spike.py 中实际使用的验证框架。

安装

pip install swarm-rd-orchestrator-cli
# or
npm install -g swarm-rd-orchestrator-cli

两种方式都会在你的 PATH 中提供 swarm-rd-cli 命令。npm 包只是 Python 命令行的轻量封装：它会执行真正的二进制文件，而不会重新实现其功能。如果使用 npm 包，也请安装 Python 包。

**状态：**已在两个包注册表发布（PyPI 通过 GitHub Actions OIDC 发布，不存储令牌）。两者均已在干净环境中通过实际安装和实际命令运行进行验证，而不只是确认上传成功。

警告

这是一个尚未完成验证的 Milestone 1 原型（0.0.x），还不是稳定版本。仅在 macOS 上测试过；由于 Ray 上游对 Windows 的支持不如 Linux/macOS 完善，Windows 支持尚未验证。

快速开始

swarm-rd-cli append task-1 agent-a "found a race condition in the retry loop" --kind result
swarm-rd-cli append task-1 agent-b "confirmed: retry loop isn't holding the lock" --kind result
swarm-rd-cli pull task-1
# [1] (agent-a/result) found a race condition in the retry loop
# [2] (agent-b/result) confirmed: retry loop isn't holding the lock

swarm-rd-cli --json pull task-1     # structured output for scripts/agents
swarm-rd-cli list-tasks             # every task_id with a delta count
swarm-rd-cli mcp                    # run as an MCP server over stdio

所有返回数据的命令都支持 --json，便于 Agent 和脚本使用，无需抓取屏幕文本。mcp 子命令通过标准输入/输出将 append_delta、pull_deltas 和 list_tasks 暴露为带类型的 MCP 工具，因此 Agent 可以通过编程方式调用此程序，而不必通过 Shell 启动它。

功能

• 原子追加，经过验证，而非空口保证。 专门的测试会模拟写入过程中崩溃，并确认 SQLite WAL 层不会留下任何不完整的行，而不只是描述这一保证。
• 每个数据命令都支持结构化输出。 append、pull 和 list-tasks 支持 --json，这意味着通过命令行调用此工具的 Agent 无需抓取人类可读格式的文本。
• 不仅是命令行，还有 MCP 服务。 swarm-rd-cli mcp 通过标准输入/输出将相同的三项操作暴露为带类型的工具，因此 Agent 可以通过编程方式调用此程序，而不必启动子进程。
• 使用真实 Ray actor 测试并发，而非模拟。 关键测试会运行 3 个真实的 Ray actor 并发追加，并核对结果；这与实际工作负载使用的机制相同。
• 输入格式错误时会明确报错。 如果 delta 缺少 task_id、agent_id 或 content，就会在触及存储前引发 InvalidDeltaError。不会静默丢弃。

命令参考

根据命令行自身的 --help 输出生成：

usage: swarm-rd-cli [-h] [--db DB] [--json] {append,pull,list-tasks,mcp} ...

positional arguments:
  {append,pull,list-tasks,mcp}
    append              append a delta to the event log
    pull                pull deltas for a task
    list-tasks          list every task_id with a delta count
    mcp                 run as an MCP server over stdio

options:
  -h, --help            show this help message and exit
  --db DB               path to the event log (default: swarm-events.db)
  --json                structured JSON output (for agent/script use)

usage: swarm-rd-cli append [-h] [--kind {note,result,tool_output}]
                            task_id agent_id content

positional arguments:
  task_id
  agent_id
  content

options:
  -h, --help            show this help message and exit
  --kind {note,result,tool_output}

usage: swarm-rd-cli pull [-h] [--since SINCE] task_id

positional arguments:
  task_id

options:
  -h, --help     show this help message and exit
  --since SINCE  cursor to pull after

MCP 服务

swarm-rd-orchestrator-cli 提供了一个 Model Context Protocol（MCP）服务，因此 Agent 可以通过 stdio 将事件日志直接作为类型化工具调用，而不必通过 shell 调用 CLI 并解析文本。

pip install "swarm-rd-orchestrator-cli[mcp]"

运行方式：

swarm-rd-cli mcp

在配置中指定该命令，即可将其添加到 Claude Desktop（或任何其他 MCP 客户端）：

{
  "mcpServers": {
    "swarm-rd-orchestrator": {
      "command": "swarm-rd-cli",
      "args": ["mcp"]
    }
  }
}

提供了三个工具：

• append_delta(task_id, agent_id, content, kind="note") - 将发现、结果或工具输出追加到任务的事件日志。示例：append_delta(task_id="task-1", agent_id="agent-a", content="found a race condition in the retry loop", kind="result")。
• pull_deltas(task_id, since_cursor=0) - 按从旧到新的顺序，拉取某个任务中 ID 大于 since_cursor 的所有 delta。示例：pull_deltas(task_id="task-1") 会返回完整历史记录；pull_deltas(task_id="task-1", since_cursor=2) 只会返回游标 2 之后写入的 delta。
• list_tasks() - 列出事件日志中当前的所有 task_id 及其 delta 数量。示例：list_tasks() 会返回 [{"task_id": "task-1", "delta_count": 2}]。

对比

swarmmesh 是该作者作品集中的姊妹项目，也以 swarmmesh-cli 的名称发布在 PyPI 和 npm 上。就下方几乎所有方面而言，它目前都是更完整的选择。本项目的存在是为了提供一种有意采用 Ray 原生架构的替代方案，而不是因为 swarmmesh 有所不足。

	swarm-rd-orchestrator-cli	swarmmesh-cli
传输方式	Ray actor（进程内 / 分布式）	HTTP 服务
存储	SQLite，WAL 模式	默认使用内存，也可通过 --persist 使用 SQLite
跨语言	仅 Python	Python 和 Node
记忆搜索 / 排序	无（仅通过 task_id 拉取）	对记忆查询进行 BM25 关键词排序
MCP 服务	是	是
已发布到 PyPI/npm	是，已上线	是，已上线
CI	是	是

如果 Ray 原生分布式计算这一特点最终对你的用例并不重要，请改用 swarmmesh。它已上线、经过真实使用场景的测试，而且功能更多。

swarm-rd-orchestrator-cli 是什么，为什么要开发它

swarm-rd-orchestrator-cli 是一个基于 Ray actor 模型、供并行 AI 研究 Agent 共享的持久化事件日志。每个 Agent 都会以结构化 delta 的形式写入发现；任何其他 Agent 都可以拉取某个任务的完整历史记录，无需共享可变存储，也无需协调服务器进程。

开发它是为了验证一个具体且范围有限的假设：与基于 HTTP 的协调层相比，Ray 的 actor 和对象存储模型是否更适合协调真正大规模的并行研究 Agent。这个假设尚未得到验证。本项目以 Milestone 1 原型形式发布，目的就是先通过真实工作负载进行测试，再决定是否进一步投入；请参阅运行实际验证原型。

从源代码构建

git clone https://github.com/RudrenduPaul/swarm-rd-orchestrator.git
cd swarm-rd-orchestrator
python3 -m venv .venv
.venv/bin/pip install -e ".[dev,mcp]"

需要 Python 3.10 或更高版本（mcp SDK 依赖项所需）。

运行测试

.venv/bin/pytest test_event_log.py -v

9/9 项测试通过，其中包括关键测试：3 个并发 Ray actor 向同一个共享事件日志追加内容，核对结果后确认没有 delta 丢失或重复。

运行实际验证原型

在 spike.py 中编辑 REAL_TASK_ID、REAL_TASK_DESCRIPTION 和示例 Agent 发现，使其反映一个真实的研究任务，然后：

.venv/bin/python3 spike.py

阅读末尾打印的评估标准。决策规则：与原始 Ray 或 LangGraph 相比，如果符合条件的架构失败案例少于 3 个，就改用轻量 CLI 封装，而不是继续扩展该项目。

已确定的决策（2026-08-03）

• 基元：Ray（actor 模型和对象存储），LangGraph 作为备用方案
• 存储：SQLite，WAL 模式
• Delta 结构：{task_id, agent_id, timestamp, content, kind}
• 格式错误的 delta 会触发 InvalidDeltaError，绝不会被静默处理
• 许可证：Apache 2.0
• Python：3.10 或更高版本，mcp SDK 要求如此
• 发布：已发布到 PyPI（通过 GitHub Actions OIDC Trusted Publishing，不存储令牌）和 npm，并都已通过真实的干净环境安装验证

常见问题

这实际上有什么作用？ 它为作为 Ray actor 运行的并行 AI Agent 提供一个共享且持久的地方，用于写入发现结果并获取彼此的发现，同时避免相互覆盖对方的状态。它是传输和持久化层，而不是编排框架：它不会调度 Agent，也不会决定它们要做什么。

这与 swarmmesh 有什么不同？ 请参阅上文的比较。核心理念相同，但传输方式不同（使用 Ray actor 而不是 HTTP），而且目前 swarmmesh 功能更完整，也已经发布。

这能在 Windows、macOS 和 Linux 上运行吗？ 已在 macOS 上测试。Ray 本身原生支持 Linux 和 macOS；上游对 Ray 的 Windows 支持较为有限，因此在有人确认之前，请将 Windows 视为本项目尚未验证的平台。

我需要自己的 API 密钥吗？ 不需要。本项目不会自行调用大模型。它是一个协调层，供你自己的 Agent（无论使用什么模型或框架）写入和读取数据。

可以放心依赖它吗？ 还不行。这是尚未经过验证的里程碑 1 试验（版本为 0.0.x），并非稳定版本。事件日志的核心保证（原子追加、不会部分写入）已在 test_event_log.py 中测试，但除了试验脚本之外，本项目尚未在真实的多 Agent 工作负载上进行验证。

如何从 Agent 使用它，而不仅仅是由人使用？ 可以在每条命令中通过 --json 调用 CLI，也可以运行 swarm-rd-cli mcp 并将其作为 MCP 服务连接。两种方式都会提供结构化、可解析的输出。

这是一个库还是只有 CLI？ 两者兼有。如果你已在 Python 环境中，且不需要 CLI 或 MCP 层，可以直接导入 event_log.py 中的 EventLog 和 EventLogActor 类。

它采用什么许可证？我可以将其用于商业用途吗？ Apache 2.0。根据其条款，允许商业使用、修改和再分发；完整内容请参见 LICENSE。

贡献

由于这是一个尚未经过验证的试验项目，而非接受贡献的项目，目前还没有 CONTRIBUTING.md。如果你想在正式确定之前讨论某项更改，请提交一个 issue。

许可证

Apache 2.0。完整内容请参见 LICENSE。