quorum

Quorum

借助共享黑板实现经证明的多 Agent 共识——一个 MCP 服务。

编排器发起提案，参与的 Agent 将上下文写入共享黑板并说明理由、投票，Quorum 应用社会选择理论文献中严谨的聚合算法，并通过 Stamp 对每个步骤——提案、写入、投票、结果——进行证明，再追踪至 Telinea。记录不可变、防篡改，且可独立验证。

托管端点（无需登录，公开）： https://quorum-mcp.terradev.cloud/mcp

---

为什么需要 Quorum

LLM Agent 之间的多数投票在存在争议的问题上会失效，因为基于重叠数据训练的 Agent 有着系统性的共同盲点——它们并非康多塞陪审团定理所要求的独立投票者。而当 Agent 确实共同作出决策时，决策过程——谁投了票、说了什么、依据哪些上下文进行讨论——却不可见。

Quorum 提供了完整的基础机制：算法、状态和来源信息。

工具

• register — 一次性账号设置：将你的 api_key（由你选择的 Quorum 密钥）绑定到你的 telinea_key。Telinea 密钥会使用由你的 Quorum 密钥派生的密钥进行加密存储（AES-256-GCM、HKDF）——Quorum 密钥本身绝不会被存储。之后，你的提案产生的每个 span 都会使用你的 Telinea 密钥推送，并通过标准 OTLP bearer 身份验证。

• propose — 发起提案：name（将成为提案 ID）、question、voters（预期身份）、deadline_minutes。 可选参数：api_key（通过 register 获取——将提案绑定到你的 Telinea 账号以便流式传输 span；匿名使用时可省略）、namespace（租户前缀——ID 将变为 ns:name，不同团队可使用相同名称而不会冲突）、options（默认值为 ["yes","no"]）、algorithm（默认值为 approval）、quorum（投票者的最低百分比，默认值为 100）、threshold（绝对多数占比，默认值为 66.67）、description。返回提案 ID、创建证明 ID、截止时间和黑板 URI。

• write — 向提案的黑板追加 key/value，可选填写 author。写入内容只会追加，不会替换——完整的有序历史记录会被保留并进行证明。

• read — 读取黑板：按顺序返回每次写入及其时间戳、作者和证明 ID。可选使用 key 进行筛选。即投票前的讨论记录。

• vote — 以预期的 voter 身份提交选票，可选填写 reasoning（会存储在经证明的记录中，但绝不会影响结果）。选票格式取决于算法——见下文。重复投票和截止时间之后的投票都会被拒绝，并返回结构化错误。

• resolve — 应用算法并对结果进行证明。达到法定人数后（或截止时间之后）即可调用；达到法定人数时，截止时间一到也会自动触发。具备幂等性。遇到康多塞循环或未达到绝对多数门槛时，会返回状态为 unresolved 的 co_winners——如实呈现真正的模糊性，绝不隐瞒。

• history — 完整的经证明记录：创建、每次写入、每次带理由的投票，以及结果。可选使用 filter 筛选：all | writes | votes | outcome。合规审计材料。

算法

算法	选票	适用场景
plurality	选项字符串	仅限二元决策
approval	一个选项或多个选项的列表	默认值。 无策略性激励；适用于偏好较弱或存在多个偏好的情况
borda	所有选项的排序	3–5 个选项；找出普遍可接受的选项
condorcet	排序或单个选项	理性偏好聚合；出现循环时返回 co_winners
opinion_pool	总和为 1 的 {option: probability}	真实的概率信念；返回完整分布
supermajority	选项字符串	需要超过 50% 支持率的高风险决策（设置 threshold）

黑板

大模型共识失败通常是信息失败，而非算法失败——各 Agent 独自投票。黑板是限定在单个提案范围内的共享工作记忆：Agent 写入分析、阅读彼此的发现，然后在掌握信息的情况下投票。先写后读的顺序，以及截止时间前投票不可更改的设计，都是防止从众偏差的措施。

跟踪

每个提案都是一条 Telinea 跟踪记录。根跨度（proposal）在 propose 时开启，在 resolve 或截止时间到期时关闭——其持续时间就是审议时间。每次写入、投票和决议都会作为子跨度实时发出，并附带其 Stamp 证明 ID。根跨度状态：OK 表示已决议，UNRESOLVED 表示存在歧义，ERROR 表示过期且未达到法定人数。

跨度 ID 是确定性的（基于提案 ID 和事件序号生成 uuid5），因此重放和重启都具有幂等性。推送采用即发即弃并具备故障保护——遥测绝不会影响投票。

身份验证以账户为单位：跨度会使用通过 register 注册的 Telinea 密钥推送，因此摄取端会将其归属到正确的账户。密钥经过加密存储（使用 Quorum 密钥经 HKDF 派生的密钥执行 AES-256-GCM 加密——绝不存储 Quorum 密钥）；使用服务端持有的 QUORUM_DATA_KEY，可对提案范围内的数据重新加密，使跨度在重启后无需再次提供 Quorum 密钥也能通过身份验证。数据库转储中只会暴露密文。

配置：TELINEA_INGEST_URL（默认值为 https://ingest.terradev.cloud/v1/traces）、TELINEA_WORKSPACE_ID、 TELINEA_PROJECT_ID、TELINEA_DISABLED=1、QUORUM_DATA_KEY、 QUORUM_ACCOUNTS（账户存储路径，默认为 ~/.quorum/accounts.json）。

HTTP 传输

端点	方法	描述
/mcp	POST	JSON-RPC 2.0——单个或批量请求；通知 → 202
/mcp	GET	SSE 保持活动连接通道
/	GET/POST	服务身份信息 / MCP 别名
/health	GET	{"status":"ok"}
/v1/info	GET	自描述服务信息（工具、身份验证、跨度、文档）
/.well-known/agent.json	GET	Agent 卡片
/.well-known/oauth-protected-resource	GET	RFC 9728——公开访问，无需身份验证

通过 asyncio.Semaphore 将并发数限制为最多 100 个同时进行的 POST /mcp 请求。

速率限制以提案为单位：每个提案 ID 的 write 和 vote 事件速率上限为每分钟 QUORUM_PROPOSAL_RATE 个（默认值为 120），因此单个高频提案不会耗尽其他提案的资源。Caddy 中基于 IP 的边缘区域仅作为粗略的后备防护。

证明采用队列处理并合并：并发事件在每个排空批次中共用一次 NTP 采样，而不是每个事件查询一次——每个事件仍会获得独立的 Stamp 记录（唯一 ID、自有负载哈希），因此吞吐量不受 NTP 往返时间限制。

状态

事件溯源：每个提案在 ~/.quorum/proposals 下对应一个只追加的 JSONL 文件（可通过 QUORUM_DATA_DIR 覆盖）。命名空间提案存放在各自的命名空间子目录中（proposals/<ns>/<name>.jsonl）。日志本身就是历史记录——history 是对工具追加写入的同一文件进行筛选后读取的结果。任何内容都不会被改写或删除。

自托管

git clone https://github.com/theoddden/quorum-mcp.git
cd quorum-mcp
docker compose up -d --build

DNS 指向主机后，Caddy 会处理 TLS。参见 deploy/Caddyfile。

许可证

Copyright 2026 theoddden。根据 Apache License, Version 2.0 获得许可。