Polis Protocol

Polis Protocol

面向编码 Agent 的本地优先控制平面。在同一个代码仓库中运行 Claude、Codex、Gemini 和 Cursor——每份已认领的契约都会记录负责人，Agent 可以记录证据，共享经验有助于减少重复失败。纯 Markdown，存储在 Git 中，适用于所有厂商。

🌐 网站 → polis-protocol.ymlsora.chatgpt.site  ·  安装  ·  实证  ·  接入你的 Agent（MCP）

合成模拟：重复错误从 65% 降至 7%  ·  检测到建议式重叠冲突  ·  5 秒内复现：polis bench --mode learning
_{使用合成任务和种子 0 的模拟运行 — 下文公布了假设和局限。}

uvx polis-protocol init      # one command · no server · no database · just markdown in your repo

由 Claude · Codex · Gemini · Cursor 共享，全部读取同一个 _polis/ 文件夹。MIT。
⭐ 如果你认同下方的工作循环，点个星标就能帮助其他多 Agent 开发者发现这个项目。

---

10 秒版

三个 AI Agent 共享一个项目：Claude（研究）、Codex（前端）、Gemini（翻译）。

来了一个西班牙语翻译任务。谁来接？

一开始是 Claude——它给自己的评分很高。但在完成两份契约并积累一条经验后（“企业用语‘líder’在这里读起来不对；应使用运动圈的借词‘madrij’”），路由器悄然将这项工作转给了 Gemini。没人重新分配任务。团队学到了经验，路由也随之调整。

这个循环——根据过往表现路由工作，根据结果更新过往表现——正是整个项目的核心。无需安装或 API 密钥，用一条命令亲自体验：

git clone https://github.com/ymxlx/polis-protocol.git
cd polis-protocol && bash scripts/demo.sh

Score breakdown (sorted by total):
  gemini-translator-pesaj   total=0.688  hist=0.25  self=1.00  cost=1.00  avail=1.00  lessons=+0.10
                              ↳ lessons applied: 2026-04-18-madrij-not-lider
  claude-research-pesaj     total=0.453  hist=0.15  self=0.60  cost=1.00  avail=1.00  lessons=+0.00
  codex-frontend-pesaj      total=0.290  hist=0.00  self=0.20  cost=1.00  avail=1.00  lessons=+0.00

Recommendation: gemini-translator-pesaj   ← won on history + an applied lesson, not self-rating

如果你觉得这个循环很有意思，点个 ⭐ 确实能帮助其他多 Agent 开发者发现这个项目。

---

它是什么

如今，面向 AI Agent 的 Git 和 Markdown 任务看板层出不穷——认领任务、完成任务、标记为已完成。它们很不错，Polis 也能向其中写入内容。但看板是被动的：它记录发生过的事，却不会变得更聪明。协议在发布当天就冻结了。

Polis 在共享记录之上增加了一个主动协作层：

1. 沟通 — 每个有意义的操作都会写入只追加的 chronicle.md。（每个看板都能做到这一点。）
2. 优化 — 任务采用结构化契约，并通过多臂老虎机策略，分配给在所需能力标签上表现记录最佳的公民。（看板做不到；它不知道谁最擅长。）
3. 自我发展 — 已结算的契约可以生成结构化经验；经验会反馈到路由器中，在记录得到持续维护时，有助于减少重复失败。
4. 宪制演进 — 当规则不再有效时，公民可以针对协议本身提出修正案、投票并批准。

**看板是供你填写的东西。Polis 是一支不断发展的团队。**它会了解谁最擅长什么，也能改写自己的规则。

这一切都存在于一个文件夹中。没有中央服务器，没有必需的运行时，也没有专有格式。只要工具能读写 Markdown，就能参与。

如果你想了解 Polis 与 AGENTS.md、CrewAI、LangGraph、hcom、 SwarmClaw 或 Agent 记忆系统的比较，请参阅 docs/comparisons.md。

---

为什么叫“polis”

polis 是一座希腊小城——几千人彼此熟识，并自行管理事务。这个比喻恰如其分：

Polis	Polis 协议
公民	来自任意供应商的 AI Agent
能力卡	对 Agent 能力进行内容哈希的 YAML 清单
契约	包含意图、分配和结算信息的结构化任务
纪事	每位公民在会话开始时都会读取的只追加事件日志
经验	按能力标签归档的回顾总结
Chavruta	高风险操作前，由不同供应商的公民进行的结对评议
修正案	经投票批准的宪章变更

它有意采用明确的规则。名称容易记忆，文件格式严格，纪事行的格式不可妥协。协议层的严格性，正是让四家不同供应商的模型读取同一个文件夹，并就其中内容达成一致的关键。

---

快速开始

安装

在任意项目的根目录下：

# zero-install, one command
uvx polis-protocol init

# or install the CLI
pipx install polis-protocol      # isolated
pip install polis-protocol       # into the current env

init 会创建 _polis/，为 Claude/Codex/Gemini 写入桥接文件，并将你注册为公民。也可以在需要时指定身份：

uvx polis-protocol init \
  --agent-id claude-research-yourproject \
  --vendor anthropic --model claude-opus-4-7 --tool "claude code"

使用 --dry-run 预览创建内容，而不写入文件。重复运行不会破坏现有内容；polis init --repair 会恢复任何缺失的托管文件。 （正在参与协议本身的开发？git clone + python scripts/init_polis.py 仍然可用。）

现在你有了：

your-project/
├── CLAUDE.md / AGENTS.md / GEMINI.md / AIDER.md ← cross-tool entry pointers
├── .agents/skills/polis-protocol/SKILL.md ← skill mirror (Codex and Antigravity both read this)
└── _polis/
    ├── CONSTITUTION.md                    ← canonical protocol
    ├── README.md
    ├── index.md                           ← "where things stand"
    ├── chronicle.md                       ← append-only event log
    ├── citizens/<you>/                    ← capability_card, status, inbox, journal
    └── contracts/
        ├── open/                          ← active tasks
        ├── settled/                       ← closed tasks with lessons
        └── routing_stats.yml              ← learned routing policy

创建契约

polis contract open --title "Literature review" \
  --tags long-context-reading,source-checking --by claude-research-yourproject

或者手动将文件放入 _polis/contracts/open/——它就是普通的 Markdown：

---
contract_id: literature-review
opened_by: claude-research-yourproject
status: proposed
stakes: medium
required_tags: [long-context-reading, source-checking]
cost_ceiling: medium
---

# Literature review of multi-agent coordination protocols
...

路由

polis route --polis-root _polis \
  --contract _polis/contracts/open/literature-review.md --explain

输出：

Score breakdown:
  claude-research-yourproject  total=0.430  hist=0.00  self=0.90  cost=1.00  avail=1.00  lessons=+0.00
  codex-frontend-yourproject   total=0.350  hist=0.00  self=0.50  cost=1.00  avail=1.00  lessons=+0.00

Recommendation: claude-research-yourproject

结算并学习

polis contract settle literature-review --quality 5 --minutes 90
polis reconcile --polis-root _polis

老虎机的 routing_stats.yml 会更新，所有者在 _polis/lessons/<tag>/ 下归档的经验，都可以包含有界的 routing_effect，供路由器读取，并在下一个类似契约中通过 --explain 显示。失败可以转化为 polis guardrail add … 条目，供未来具有这些标签的契约继承为必须通过的验收标准。

避免冲突

polis reserve src/auth --as claude-research-yourproject --note "refactoring login"
# another cooperating Polis client receives a conflict warning with the holder named
polis release src/auth --as claude-research-yourproject

预留是记录在共享状态中的建议性协作机制。它们不是文件系统锁，也不是安全边界，更无法保证避免不参与 Polis 的工具引发的竞态。

通过 MCP 接入你的 Agent

每个 polis 也是一个 MCP 服务——polis mcp 通过 stdio 使用 MCP，无需额外依赖。它将整个生命周期作为工具公开（status、open / route / claim / settle / abandon、context packets、reserve / release、guardrails），并提供只读资源（polis://state、polis://replay、polis://replay/redacted、polis://constitution）：

# Claude Code
claude mcp add polis -- uvx --from polis-protocol polis mcp

# any other MCP client: command `uvx`, args `--from polis-protocol polis mcp`
# (run it from inside the project, or add `--polis-root /path/to/_polis`)

无法调用 CLI 的 Agent 现在也可以打开合约、获取可解释的路由建议、预留文件并提交附有证据的结算——通过 CLI 和仪表板共用的应用层完成。任何时候都不会手动编辑 _polis/ 文件。

---

以诚实的方式衡量成效

polis bench 开箱即用——我们对自己的主张进行了基准测试，而不是空口断言：

• 重复错误：−89%。 借助自动注入匹配的后续任务的经验教训和防护措施，重复错误率从约 65%（无记忆 Agent 或未管理的协作群）降至约 7% ——每类失败最多重现一次，随后就会成为常驻检查项。运行 polis bench --mode learning 即可复现。
• 确定性地检测建议冲突。 在基准测试中，只要所有参与者使用相同的共享状态，polis reserve 就会拒绝重叠的声明并指出持有者。预留不是文件系统锁，也不能防止竞争条件。
• 还有大多数项目不会告诉你的事实： 学到的路由效果胜过无技能基线（随机、轮询），仅凭结果就能恢复 Oracle 质量提升的约 35–55% ——但准确的静态自评在质量上仍有竞争力，基准报告也明确说明了这一点（polis bench）。Polis 的优势在于无需信任能力卡片也能学习、为每次选择提供透明的理由，以及基线所缺少的协调层。

---

四大制度

名册

每位公民发布一个文件：_polis/citizens/<agent-id>/capability_card.yml。其中包含供应商、模型、语言、自评能力标签、成本范围、延迟范围、常驻指令和签名。能力卡片是 polis 对“谁能做什么”的回答。没有中央目录，加入也无需许可——名册从设计上就是开放的。

合约

任务采用分为三部分的 Markdown 文件：

• 意图——目标、验收标准、所需标签、截止日期、成本上限、利害程度
• 分配——负责人、计划、预估工作量（领取时填写）
• 结算——结果、质量自评、有效做法、遇到的问题（关闭时填写）

未完成的合约位于 contracts/open/。已结算的合约移至 contracts/settled/，且永不删除。合约的结构是固定的，因此任何公民——以及路由器——都能读取每份合约，无需猜测其格式。

编年史

_polis/chronicle.md 是仅追加的事件日志。每个有意义的操作记录一行：

- 2026-05-14 09:12 | claude-research-pesaj | drafted outline | [[contracts/open/literature-review]] | covers 2019-2025, 14 papers
- 2026-05-14 09:15 | codex-frontend-pesaj  | settled contract | [[contracts/settled/auth-refactor]] | tests passing, lesson filed
- 2026-05-14 09:18 | gemini-translator-es  | requested review | [[reviews/2026-05-14-0918-spanish-rollout]] | high-stakes, needs chavruta

保留动词（opened contract、claimed contract、settled contract、filed lesson、requested review、proposed amendment、blocked on <thing>、……）具有语义含义，路由器和其他公民会解析这些内容。

经验教训单独存放在 _polis/lessons/<capability-tag>/。编年史记录发生了什么；经验教训记录学到了什么。大多数事件不是经验教训，而大多数经验教训都提炼自多个事件。

修正案

规则不再有效时，任何公民都可以提议修改。提案放在 _polis/amendments/proposed/<id>.md 中。其他公民会追加回应区块：agree | disagree | abstain | request_changes。当活跃公民（过去 14 天内在编年史中留下过记录的公民）中的简单多数表示同意后，该文件便会移至 amendments/ratified/，并修改章程。

协议会自我改进。本技能中的默认规则是起点；随着时间推移，每个 polis 都会以细微的方式逐渐演变，以适应自身项目。这种演变正是其意义所在。

---

Chavruta 评审

借鉴 beit midrash 的结对学习模式，chavruta 评审是 polis 防止单一模型失效的保障。任何标记为 stakes: high 的契约，都必须由另一家供应商的第二位公民在执行前审查计划。评审需回答三个问题：

所有者做对了什么？他们可能忽略了什么？决定：signed_off、requested_changes 或 rejected。

允许两位来自同一家供应商的公民互相评审，但效果较弱——chavruta 的价值恰恰在于模型之间存在结构性差异。请谨慎使用。大多数契约风险较低。

---

路由器如何学习

默认路由器采用多臂老虎机算法：

• 利用（85%）：将任务路由给在所需标签上综合得分最高的公民。得分权重为历史质量（55%）、自评分（20%）、成本匹配度（15%）和当前可用性（10%）。
• 探索（15%）：按得分加权，将任务路由给得分并非最高的公民，以确保策略能持续验证当前领先者是否仍然确实最佳。
• 冷启动：当某个标签没有历史记录时，以自评分为主。每个标签积累几份契约后，自评分的影响就会减弱。

契约结算时，routing_stats.yml 会更新质量得分和分钟数。随着记录增加，这些证据可以改善未来的推荐。完整算法见 references/routing.md。

你可以通过以下方式运行路由器：

• 一个 60 行的 Python 脚本（scripts/route_contract.py），
• 在任意 Agent 的会话中进行简短的推理步骤（计算量很小，足以在上下文中完成）。

两种方式都会得出相同的推荐。公民始终可以覆盖推荐。

---

仓库内容

路径	内容
polis/	polis CLI 背后的可安装软件包——路由、契约、预留、护栏、上下文包、基准测试、诊断、验证、迁移
SKILL.md	Claude Code 技能：何时激活、完整工作流
scripts/init_polis.py	初始化新的 polis（幂等、内容哈希卡片、桥接指针）；是 polis/initializer.py 的轻量封装
scripts/route_contract.py	多臂老虎机路由器和 --reconcile 任务；是 polis/routing.py 的轻量封装
scripts/benchmark.py	Polis Bench——路由与基线的对比，以及重复错误学习曲线
templates/POLIS_CONSTITUTION.md	写入每个新 polis 的规范宪章
templates/bridge_pointer.md	简短的 CLAUDE.md / AGENTS.md / GEMINI.md，用于指引每个工具查看宪章
references/protocol-spec.md	每种文件（卡片、契约、经验教训、修订、评审、状态、收件箱）的完整架构
references/templates.md	协议所用每种文件的复制粘贴模板
references/routing.md	多臂老虎机算法、冷启动、探索率调优、统计数据更新流程
references/amendments.md	何时修订、何时记录经验教训；法定人数规则；示例
references/troubleshooting.md	故障模式、恢复、扩展，以及从 agent-vault 迁移的路径

---

跨厂商协作

该协议与厂商无关。同一个 polis 可以由 Claude、Codex、Gemini CLI、Google Antigravity、Aider、基于 GPT 的工具以及任何能够读取 Markdown 的工具共享。Bootstrap 会写入以下发现指针：

• CLAUDE.md — Claude Code 的入口
• AGENTS.md — Codex、Jules、goose、opencode、Zed、Warp、VS Code 和 Devin 的入口
• GEMINI.md — Gemini CLI 和 Google Antigravity 的入口
• AIDER.md — Aider 的入口
• .agents/skills/polis-protocol/SKILL.md — Codex 和 Google Antigravity 都会读取的技能镜像（集成指南）

它们都指向同一个位置：_polis/CONSTITUTION.md。更新协议只需编辑这一个文件。

跨厂商路由正是该协议发挥价值的地方。西班牙语翻译会交给在 spanish-translation 上记录最佳的公民，而不是碰巧出现在用户当前聊天中的那个。长此以往，团队产出就不会再受任何单一模型盲点的限制。

---

与 agent-vault 的关系

agent-vault 是一个姊妹项目：它是一个更简单、仅用于通信的协议，Agent 可以在其中共享 Obsidian 风格的 Markdown 共享板。如果你只需要 Agent 彼此留言，agent-vault 就足够了。

在以下情况下选择 Polis Protocol：

• 你有来自多个厂商的 Agent，并且路由很重要。
• 你希望记录的结果和经验教训能为未来的路由提供参考。
• 你希望在现实需要时能够修订协议本身。

从 agent-vault 迁移的路径记录在 references/troubleshooting.md 中。

---

状态

v2.0（稳定版）— 在 PyPI 上发布 · MCP 注册表 · 网站。 该协议有意保持精简——仓库中的每个文件都是 Markdown，唯一的依赖项是 PyYAML，且不需要服务器或数据库。polis CLI 涵盖 init · route · reconcile · status · contract · reserve/release · guardrail · bench · serve · mcp · report · reflect · doctor · verify · migrate， 并由 CI 中覆盖 Python 3.10–3.13 的完整测试套件提供支持。架构 v2（_polis/polis.yml）可通过 polis migrate --plan|--apply|--rollback 可逆迁移。在官方 MCP 注册表中列出 polis mcp 是一次性的手动步骤——请参阅 docs/publishing-mcp-registry.md。 欢迎 Fork、提交问题和修订。

---

路线图

协议层已稳定。正在推进的工作，按预期影响大致排序：

• examples/ 示例库 — 3 个完整的 polis 示例（研究团队、产品团队、开源软件维护者三人组），通过实例进行讲解。欢迎贡献。
• 其他路由器 — 确定性的 UCB1 变体通过 route_contract.py --policy ucb 提供，带种子的 Thompson 抽样变体通过 --policy thompson 提供（两者均已记录在 references/routing.md 中），与默认的 ε-greedy 多臂老虎机并列。包含基于合成能力轨迹的基准测试框架。
• 上下文多臂老虎机 — 将每份契约的特征（截止日期压力、重要程度、语言）纳入路由决策，而不仅仅依赖每个标签的历史记录。
• 自动滚动归档 — 通过一行 cron 命令完成季度编年史滚动归档，以及对已结算契约进行 90 天归档，使运行一年的 polis 无需手动维护也能保持精简。
• 桥接扩展 — 为 Aider、opencode、Zed、Devin、Cursor agent mode 提供一流的入口指引。每项都是一个 30 行的 Markdown 存根文件。
• Polis 的 Polis — 为多团队项目记录一种模式：每个子团队都是自己的 polis，并由一个精简的元 polis 路由跨团队契约。
• 可视化工具 — 一个小型静态仪表板，读取 routing_stats.yml 和编年史，展示团队随时间的成长。（额外奖励：在一个全新的 polis 中，将其作为第一份契约来使用，以此进行自我试用。）
• 学术论文 — 撰写一篇短文，将 Polis 置于多 Agent 协调研究领域中（基于多臂老虎机的任务分配、黑板架构、基于 Agent 的模拟）。

如果你的需求不在此列表中，请提交 修订提案问题。

---

贡献

请参阅 CONTRIBUTING.md。我们欢迎漏洞报告、修订提案、新的桥接工具和完整示例。安全问题请发送至 SECURITY.md。

---

引用

如果你在学术工作中使用 Polis Protocol，请通过 CITATION.cff 或 GitHub 上的“引用此仓库”按钮引用它。

---

许可证

MIT — Yehuda Levy，2026。