用途
claw-consensus 解决的是在多台计算机上运行 AI 智能体（如 Claude Code）时常见的协调问题：机器之间状态漂移、人类被迫充当终端之间的复制粘贴信使、任务“已发送”被误读为“已完成”、同步链路静默失效等。它提供了一套多机协调层，让不同机器上的智能体能够协商决策、提交结果、相互验证，并仅在涉及资金或不可逆操作时唤醒人类。
主要能力
- 共识协议：propose → counter → accept → commit，附带仅追加事件日志、轮次上限、超时、固定领导者打破平局以及脑裂检测。
- 双轨消息总线：每条机器间消息同时通过两条轨道发送——同步文件夹上的文件邮箱，以及机器和人类都能读取的群聊。单一入口 bus_send.py 使单轨发送无法发生。
- 单写者文件：每个发送者只追加自己的文件，每个记录者只写自己的分片，避免整文件同步冲突。
- ACK 纪律：直接命令需要显式 ACK 和结果报告；超过 SLA 的沉默会触发追查和升级。
- 独立验证：应用变更的机器不能是唯一验证者，“全局完成”需要第二台机器的独立检查，并有防橡皮图章保护。
- 领导者/跟随者规范：恰好一台机器（常开中枢）提交共享规范，跟随者只读接收并通过总线提议变更。
- 三层自愈同步：看门狗在状态变化时告警、有界自动催促、对等节点失联时自动故障转移至聊天轨道。
- 纯标准库 Python：无包、无服务器、无数据库，可运行 python 即可运行整个系统。
使用方式
快速开始（约 15 分钟，2 台机器）：
- 选择一台机器间同步的文件夹（Syncthing、Dropbox 或 git 仓库），在两台机器上将 MACHINE_BUS_DIR 设为其中的子文件夹。
- 将 reference/ 复制到两台机器，根据 docs/BUS.md 中的示例创建 <bus>/machines.json。
- 发送第一条消息：python bus_send.py OTHER-MACHINE "hello from HUB-1"；在另一台机器上：python machine_bus.py read。
- 接入第二轨道：将 BUS_RAIL2_CMD 设为向群聊（Telegram 群、Slack 频道、Discord webhook）发布一条文本参数的命令。
- 创建 <bus>/_decisions/consensus.json 并填入领导者机器名。运行首次协商：python consensus.py propose "test: adopt rule X" --tier 0，另一台机器用 python consensus.py respond <id> accept 应答，然后提交并执行两次验证调用。
- 在常开机器上，每约 20 分钟调度一次 sync_monitor.py，并同时运行 consensus.py tick。
项目还提供演示/评估命令，可在本机模拟两台机器并驱动五个场景（正常路径、Tier-2 人类门禁、危险动作误标触发绊线、分区恢复时捕获脑裂、损坏账本行不吞后续事件），退出码为 0 表示所有终态正确。
适用场景
- 在多台机器（笔记本、台式机、常开中枢、家庭电脑）上运行 AI 智能体并需要协调决策。
- 希望减少人工在终端之间复制粘贴、避免状态漂移的团队或个人。
- 需要让智能体在常规决策上自主达成共识，仅在风险或不可逆操作时通知人类。
限制
- 所有测量数据来自作者自有的六台机器，属于参考实现而非独立结果。
- 有趣的失败场景需要多台机器才能复现，单机演示无法覆盖全部情况。
- 项目仍在演进中，部分失败模式尚未有对应防护。
- 论文 arXiv 提交（cs.MA）尚待背书，仓库副本为当前规范预印本。
- 具体收费、价格、平台支持等未在资料中提供。
