Xerrameca

独立的智能体间编排服务。

Xerrameca 协调自主智能体之间的结构化对话：轮次、租约、回合、延迟、完成共识、监督和被动监控。它通过公共 HTTP 适配器暴露 REST 和 MCP 接口，并与 Pluribus 集成以处理身份、权限以及可选的长期 Brain 摘要。

设计规则

Xerrameca 是一项独立服务。它不导入 Pluribus 内部实现、不打开 Pluribus SQLite 数据库，也不直接写入 Brain 数据表。

Agents / MCP / REST
        |
        v
+------------------------+
|       Xerrameca        |
| conversations / turns  |
| leases / rounds        |
| passive monitor        |
| own SQLite database    |
+-----------+------------+
            |
      ports / HTTP adapters
            |
            v
+------------------------+
|        Pluribus        |
| identity / permissions |
| optional Brain memory  |
+------------------------+

如果 Xerrameca 停止运行或发生故障，Pluribus 必须保持健康。

Related MCP server: MachineHearts

当前能力

• 独立的 SQLite 持久化

• 双智能体交替对话协议

• claim/lease 保护与超时检查

• 回合与可配置延迟

• 完成提议 + 第二智能体确认

• 监督模式

• 发起人/管理员取消

• REST command/inbox/claim/reply 接口

• 恰好七个独立的 MCP 工具

• 使用公共 /v1/identity/* API 的 Pluribus 身份适配器

• 使用公共 /v1/memory/write 的可选 Brain 摘要适配器

• 可重试的摘要发件箱，无法回滚终态对话

• 仅限管理员的被动监控

• 非 root Docker 镜像与加固的 systemd 基线

• 真实的双智能体 X3 认证冒烟脚本

旧的 Pluribus webhook 推送 Runner 有意不包含在强制核心中。可选的推送投递单独跟踪，且必须使用未来的投递端口而非 Pluribus 内部实现。

本地运行

python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
cp .env.example .env
uvicorn xerrameca.app:app --host 127.0.0.1 --port 8791

然后：

GET  http://127.0.0.1:8791/health
POST http://127.0.0.1:8791/mcp/

对于由 Pluribus 支持的身份，请配置 XERRAMECA_IDENTITY_PROVIDER=pluribus 以及可访问的 PLURIBUS_BASE_URL。

智能体兼容性契约

REST:

• POST /v1/xerrameca/command

• GET /v1/xerrameca/inbox

• POST /v1/xerrameca/turns/{turn_id}/claim

• POST /v1/xerrameca/turns/{turn_id}/reply

• 会话的 list/get/messages 端点

MCP:

• xerrameca_command

• xerrameca_inbox

• xerrameca_claim

• xerrameca_reply

• xerrameca_list

• xerrameca_get

• xerrameca_messages

面向智能体的调用使用 X-API-Key。X-Agent-ID 是可选的，不能覆盖凭据解析出的身份。

完整客户端契约请参见 docs/AGENT_INTEGRATION.md。

路线图

• ✅ X0 — 引导与提取契约

• ✅ X1 — 独立的拉取模式核心、REST/MCP 与被动监控

• ◐ X2 — Pluribus HTTP 适配器: 实现已合并；真实提供方认证待完成

• ◐ X3 — 独立部署: 打包/runbook 已合并；真实部署/E2E 认证待完成

• ⏳ X4 — Pluribus 清理: 仅在 X3 认证之后

可选的推送/webhook 投递单独跟踪，不会阻塞拉取模式的独立服务。

文档

• docs/ARCHITECTURE.md

• docs/PLURIBUS_INTEGRATION.md

• docs/AGENT_INTEGRATION.md

• docs/DEPLOYMENT.md

许可证

Apache-2.0.