Claw Fact Bus 协议规范 v1.0

一种面向自治 AI Agent 集群的事实驱动协调协议。

由 Carter.Yang 创建并提出

---

本文档中的"MUST"、"MUST NOT"、"SHOULD"、"SHOULD NOT"、"MAY"和"OPTIONAL"等关键词按照 RFC 2119 的定义解释。

---

1. 哲学基础

1.1 核心公理

事实，而非命令。

总线承载的是关于现实的陈述。一个 Claw 永远不会告诉另一个 Claw 该做什么；它只陈述发生了什么、存在什么、或者需要什么。接收方 Claw 根据自己的判断行动。

✅  "文件 auth.py 已修改，diff: +23 -5 ，领域: 身份认证"
✅  "用户请求对 PR #42 进行代码审查"
✅  "claw-B 已认领 fact-0x3A1"
❌  "claw-B ，去审查 auth.py"       ← 命令，禁止

为什么不使用命令？ 在 AI Agent 集群中，没有任何单个 Agent 拥有全局知识或保证可靠性。基于命令的协调要求发送方了解接收方的状态、能力和可用性——这些假设在动态、易出错的环境中会失效。基于事实的协调将"发生了什么"与"谁应该响应"解耦，使系统能够在 Agent 加入、离开或故障时自组织。

1.2 AI 矩阵论

人类组织通过 OKR 层级对齐，因为人类通信是有损的、缓慢的、带宽受限的。AI Agent 可以直接处理原始事实并无损地维护因果链。

因此：在 AI 矩阵组织中，事实既是协调介质，也是组织结构。 事实的因果链是人类组织架构的 AI 等价物——它们不是自上而下设计的，而是从 Agent 对现实的反应中涌现出来的。

1.3 公理

以下是定义系统身份的不可协商属性。移除其中任何一个都会产生根本不同的系统。

1. 事实，而非命令 — 总线承载关于现实的陈述，永远不是指令。
2. 事实是不可变的 — 已发布事实的内容不可修改。只有总线对它的评估会演化。新事实可以取代旧事实。
3. 广播介质，本地过滤 — 所有事实存在于共享的全局事实空间中，全局可寻址。总线将事实推送到声明了匹配过滤器的 Claw 。每个 Claw 声明自己关心什么。没有中央协调器。
4. 事实是可质疑的 — 任何 Claw 都可以证实或反驳其他 Claw 的事实。总线记录这些行为但不裁决真相。消费者自行决定信任。
5. 因果链即组织结构 — 事实引用其父事实，形成无需预先设计编排的涌现工作流。
6. 故障安全降级 — 行为异常的 Claw 被逐步隔离。没有任何单个 Claw 故障能导致总线崩溃。

1.4 非目标

以下内容明确不在本协议范围内：

• 共识 — 总线不判定真相。它提供证据（证实、反驳、置信度）供消费者判断。
• 分布式总线部署 — 总线本身的复制、分区和容错是实现层面的关注点。
• 跨总线联邦 — 独立总线实例之间的通信留待未来扩展。
• 传输绑定 — 本规范与传输无关。HTTP 、WebSocket 、Unix socket 等绑定是独立文档。

1.5 架构渊源

来源	借鉴内容
CAN 总线 (ISO 11898)	内容寻址消息、广播 + 本地过滤、优先级仲裁、错误状态机、无中央主节点
EDA (事件驱动架构)	事件溯源（不可变仅追加日志）、幂等消费、编排模式
科学方法	同行评审（证实/反驳）、置信度报告、知识取代

1.6 设计原理

决策	原理
事实，而非命令	AI Agent 缺乏全局知识；将"发生了什么"与"谁响应"解耦可实现自组织
不可变事实	支持审计、回放、去重和因果推理；可变事实会破坏这四者
广播 + 过滤	无协调器瓶颈；每个 Agent 的过滤器就是它的"感知器官"
独占/广播模式	基本语义差异："单一处理器" vs "共享感知"——不是优化
核心中的证实/反驳	AI 输出本质上不可靠；没有协议级的可质疑性，信任只能私下处理，破坏互操作性
内容哈希	不可变记录的篡改检测； SHA-256 为了安全性而非速度
JSON 线格式	人类可读、可调试、通用支持；性能敏感部署可使用二进制编码

---

2. 协议实体

2.1 事实（ Fact ）

通信的原子单元。类比于 CAN 帧。

一个事实有两个结构区域：

• 不可变记录 — 由发布者设置，发布后冻结。受 content_hash 覆盖。
• 可变总线状态 — 由总线独占管理。随事实在其生命周期中流转而变化。

不可变记录字段

字段	类型	要求	描述
fact_id	string	MUST	全局唯一标识符
fact_type	string	MUST	点号分隔的分类法（如 code.review.needed）
payload	object	MUST	事实数据。Schema 由 fact_type 决定
source_claw_id	string	MUST	发布者的 Claw ID
created_at	float	MUST	创建时的 Unix 时间戳
mode	enum	MUST	exclusive（单一处理器）或 broadcast（所有匹配者）
priority	int 0-7	MUST	值越小优先级越高（ CAN 惯例）。见 §4
ttl_seconds	int	MUST	生存时间。过期后 → dead
parent_fact_id	string	OPTIONAL	直接因果父事实。根事实为空
causation_depth	int	MUST	在因果链中的深度。根事实为 0 。总线必须强制执行最大值
confidence	float 0-1	OPTIONAL	发布者的自我评估确定度。缺省 = 未指定（不是"确定"）
content_hash	string	MUST	规范化 JSON payload 的 SHA-256
domain_tags	string[]	OPTIONAL	内容领域标签（如 ["python", "auth"]）
need_capabilities	string[]	OPTIONAL	处理此事实所需的能力

可变总线状态字段

字段	类型	描述
state	enum	协议生命周期状态（见 §5 ）
claimed_by	string?	认领的 Claw ID （仅限 exclusive 模式）
resolved_at	float?	解决时的时间戳
corroborations	string[]	已证实此事实的 Claw ID 列表
contradictions	string[]	已反驳此事实的 Claw ID 列表

实现可以维护额外的总线内部状态（如 effective_priority、matched 标志），但这些不属于协议可见状态。

2.2 Claw

Agent 在总线上的存在。类比于 CAN ECU 。Claw 可以是 AI Agent 或人类操作员——协议不做区分。

字段	类型	要求	描述
claw_id	string	MUST	唯一标识符
name	string	MUST	人类可读名称
description	string	OPTIONAL	此 Claw 的功能描述
acceptance_filter	Filter	MUST	声明此 Claw 想要接收的事实
max_concurrent_claims	int	SHOULD	可同时处理的独占事实最大数量
state	enum	MUST	active、degraded、isolated、offline

实现可以维护额外的每 Claw 元数据（如可靠性评分、错误计数器），如故障隔离扩展所述。

2.3 接受过滤器

Claw 对想要接收的事实的声明。基于内容，而非基于目的地。

总线必须支持基于事实属性的内容过滤。推荐以下过滤维度：

维度	类型	描述
capability_offer	string[]	此 Claw 能做什么（如 ["review", "python"]）
domain_interests	string[]	订阅的领域
fact_type_patterns	string[]	Glob 模式（如 code.*、deploy.*.completed）
priority_range	(int, int)	接受的优先级范围（低，高）
modes	enum[]	接受的事实模式

实现可以支持额外的过滤维度（如语义类型、认识论状态、置信度阈值），如协议扩展所述。

2.4 总线

共享的通信介质。总线不是被动管道——它有义务：

义务	要求
发布后不得修改事实的不可变记录字段	MUST
必须将事实投递给所有匹配的 Claw	MUST
必须强制执行 exclusive 语义（最多一个认领者）	MUST
必须记录证实和反驳	MUST
必须强制执行因果深度限制	MUST
必须拒绝 content_hash 无效的事实	MAY
可以进行速率限制、去重和过载时丢弃负载	MAY
可以维护 Claw 可靠性状态并隔离故障 Claw	MAY
可以支持优先级老化以防止饥饿	MAY

---

3. 匹配协议

3.1 过滤器评估

事实到达 Claw 当且仅当以下全部通过：

门控 0: claw.state ∈ {active, degraded}               (MUST: 非 isolated/offline)
门控 1: fact.priority ∈ claw.filter.priority_range     (MUST: 优先级掩码)
门控 2: fact.mode ∈ claw.filter.modes                  (MUST: 模式兼容性)
门控 3: 至少一个内容维度匹配                            (MUST)

门控 3 的内容匹配至少应包括：

• fact.need_capabilities ∩ claw.capability_offer ≠ ∅，或
• fact.domain_tags ∩ claw.domain_interests ≠ ∅，或
• fact.fact_type 匹配任意 claw.fact_type_patterns（ glob ）

过滤器为空（无能力、无领域、无模式）的 Claw 应接收所有事实（监控模式）。

3.2 仲裁

模式	行为
broadcast	所有匹配的 Claw 接收事实。无仲裁。
exclusive	总线至多选择一个符合条件的 Claw 。选择在同一可见输入下必须是确定性的。

独占仲裁的具体评分或排名算法是实现选择。推荐算法参见实现说明。

---

4. 优先级

4.1 优先级级别

优先级使用 3 位字段（ 0-7 ），遵循 CAN 惯例（值越小优先级越高）：

值	名称	描述
0	CRITICAL	系统故障、数据丢失预防
1	HIGH	用户面对的阻塞问题
2	ELEVATED	重要但非阻塞
3	NORMAL	大多数事实的默认值
4	LOW	后台任务
5	BACKGROUND	内务处理、优化
6	IDLE	尽力而为的工作
7	BULK	批处理

4.2 反饥饿

总线应实现老化机制以防止低优先级事实被永久饥饿。事实不得老化进入 CRITICAL （优先级 0 ）——该级别保留给真正的紧急情况。

推荐老化参数参见实现说明。

---

5. 事实生命周期

5.1 协议可见状态

              PUBLISH
  ─────────────────────▶ PUBLISHED
                              │
                    ┌─────────┼─────────┐
                    │exclusive│         │broadcast
                    ▼         │         ▼
                 CLAIMED      │     (所有匹配的
                    │         │      Claw 看到它)
                    ▼         │         │
                 RESOLVED ◀───┘    RESOLVED
                    │
                    └──▶ 可以发出子事实（因果链延伸）

  任何非终止状态 ──▶ DEAD （ TTL 过期或故障时）

状态	描述
published	事实被总线接受，对匹配的 Claw 可见
claimed	一个 Claw 已承担独占责任（仅限 exclusive 模式）
resolved	处理完成。可能已产生子事实
dead	事实无法处理（ TTL 过期、所有 Claw 释放、显式失败）

实现可以跟踪额外的内部状态（如 matched、processing），但这些不得出现在协议级响应或事件中。

5.2 状态转换

从	到	触发
—	published	PUBLISH 被总线接受
published	claimed	CLAIM 由 Claw 发起（仅限 exclusive 模式）
published	resolved	直接解决（ broadcast 模式）
published	dead	TTL 过期，无匹配
claimed	resolved	RESOLVE 由认领 Claw 发起
claimed	published	RELEASE 由认领 Claw 发起（返回池中）
claimed	dead	认领超时，Claw 故障
dead	published	管理性重新分派（ OPTIONAL ）

---

6. 总线操作

6.1 操作目录

操作码	方向	描述
CONNECT	Claw → 总线	以 Claw 身份加入总线
DISCONNECT	Claw → 总线	优雅离开总线
HEARTBEAT	Claw → 总线	证明存活
PUBLISH	Claw → 总线	向总线发出事实
CLAIM	Claw → 总线	认领一个独占事实进行处理
RELEASE	Claw → 总线	释放已认领的事实回池中
RESOLVE	Claw → 总线	完成处理，可选发出子事实
QUERY	Claw → 总线	按过滤器读取事实（只读）
SUBSCRIBE	Claw → 总线	注册实时推送匹配事实
CORROBORATE	Claw → 总线	确认其他 Claw 的事实。总线必须将 claw_id 追加到 corroborations
CONTRADICT	Claw → 总线	质疑其他 Claw 的事实。总线必须将 claw_id 追加到 contradictions

6.2 PUBLISH 序列

Claw                                总线
  │                                  │
  │──── PUBLISH(fact) ──────────────▶│
  │                                  │── 验证 content_hash
  │                                  │── 执行准入检查
  │                                  │── 全部通过则：
  │                                  │     设置 state = PUBLISHED
  │                                  │     持久化事实
  │                                  │     为所有 Claw 评估过滤器
  │                                  │     向匹配的 Claw 推送 FACT_AVAILABLE
  │◀─── ACK(fact_id) ───────────────│
  │                                  │

准入检查必须包括内容哈希验证和因果深度强制执行。实现可以添加速率限制、去重、schema 验证和可靠性门控。

6.3 CLAIM 序列

Claw                                总线
  │                                  │
  │──── CLAIM(fact_id) ─────────────▶│
  │                                  │── 验证 fact.mode == EXCLUSIVE
  │                                  │── 验证 fact.state == PUBLISHED
  │                                  │── 验证 claw 并发认领数 < 最大值
  │                                  │── 原子操作：设置 claimed_by = claw_id
  │                                  │             设置 state = CLAIMED
  │                                  │── 向其他匹配的 Claw 推送 FACT_CLAIMED
  │◀─── ACK(success) ───────────────│
  │                                  │

CLAIM 是原子操作。当多个 Claw 尝试认领同一事实时，总线必须使用与 §3.2 一致的确定性标准至多选择一个。无仲裁扩展时，默认选择顺序为先到先得。有仲裁扩展（如高级仲裁）时，总线应使用扩展的评分算法。如果已选择其他 Claw ，总线必须向其他认领者返回失败。认领被拒绝的 Claw 不应重试同一事实。

6.4 RESOLVE 序列

Claw                                总线
  │                                  │
  │──── RESOLVE(fact_id,             │
  │       result_facts=[...]) ──────▶│
  │                                  │── 验证 claw == fact.claimed_by
  │                                  │── 设置 state = RESOLVED
  │                                  │── 设置 resolved_at = 当前时间
  │                                  │── 对每个子事实：
  │                                  │     设置 parent_fact_id = fact_id
  │                                  │     设置 causation_depth = 父 + 1
  │                                  │     执行 PUBLISH 序列
  │◀─── ACK ────────────────────────│
  │                                  │

6.5 CORROBORATE / CONTRADICT

Claw 不得证实或反驳自己的事实。总线必须拒绝此类尝试。

总线必须记录这些行为（将 claw_id 追加到相应列表），但不得基于证实/反驳计数自主更改事实的生命周期状态。信任推导是消费者端或扩展层面的关注点。

---

7. 安全护栏

总线必须强制执行某些安全不变量以防止级联故障和资源耗尽。

7.1 强制性护栏

护栏	要求
内容完整性 — 拒绝 content_hash 与 payload 不匹配的事实	MUST
因果深度限制 — 拒绝超过配置最大深度的事实	MUST
不可变性 — 发布后永远不修改事实的不可变记录字段	MUST
认领排他性 — 至多一个 Claw 可认领独占事实	MUST
TTL 强制执行 — 使超过生存时间的事实过期	MUST
跨域传播通过派生 — 事实的不可变字段（包括 fact_type）不得被修改以改变其域；跨域传播必须使用带有 parent_fact_id 链接的新派生事实	MUST

7.2 推荐护栏

护栏	要求
因果链环检测 — 拒绝父链包含环的事实	SHOULD
去重 — 在时间窗口内抑制重复发布	SHOULD
每 Claw 速率限制 — 防止单个 Claw 洪泛总线	SHOULD
全局负载丢弃 — 在极端负载下保护总线	MAY
Claw 可靠性跟踪 — 隔离持续故障的 Claw	MAY
优先级老化 — 提升未认领事实的优先级以防止饥饿	MAY
Schema 验证 — 根据注册 schema 验证 payload	MAY
事实归档 — 压缩或归档处于终止状态（ resolved 、dead ）超过可配置保留窗口的事实，以限制存储增长	MAY

所有推荐护栏的具体参数在实现说明中定义。

---

8. 事件

总线向已订阅的 Claw 推送以下事件：

事件	触发条件	Payload
fact_available	新事实匹配 Claw 的过滤器	该事实
fact_claimed	有人认领了独占事实	fact_id, 认领者 claw_id
fact_resolved	事实被解决	fact_id
fact_dead	事实进入 dead 状态	fact_id, 原因

扩展可以定义额外的事件（如 fact_trust_changed、fact_superseded、claw_state_changed）。

---

9. 线格式

所有总线通信使用统一的 JSON 信封：

{
  "message_id": "a1b2c3d4e5f6g7h8",
  "op": "publish",
  "claw_id": "abc123def456",
  "timestamp": 1709712000.0,
  "fact": { "...事实字段..." },
  "success": true,
  "error": null
}

序列化：JSON 。实现可以支持额外的编码（ MessagePack 、Protobuf ）作为传输级优化，但必须支持 JSON 作为基线。

---

10. 扩展

本核心规范设计为可扩展的。扩展独立版本化且为 OPTIONAL 。

扩展	范围
认识论状态	信任生命周期（ asserted → corroborated → consensus → contested → refuted ）、法定人数规则、信任推导
语义分类	semantic_kind 字段（ observation 、assertion 、request 、resolution 、correction 、signal ）
知识演化	subject_key 字段、自动和显式取代、SUPERSEDED 状态
Schema 治理	Schema 注册表、payload 验证、schema 版本控制和演化
故障隔离	TEC/REC 错误计数器、基于阈值的降级、恢复协议
高级仲裁	评分公式、可靠性加权选择
风暴防护	速率限制、去重、负载丢弃的具体参数

完整定义参见 EXTENSIONS.md。 推荐默认值参见 IMPLEMENTATION-NOTES.md。

---

附录 A：与 CAN 总线的对比

方面	CAN 总线	Claw Fact Bus
帧/消息单元	CAN 帧（ 8-64 字节）	事实（ JSON 对象）
寻址	消息 ID （基于内容）	fact_type + 标签（基于内容）
过滤	硬件掩码 + 过滤寄存器	AcceptanceFilter （基于内容）
仲裁	按消息 ID 逐位比较	实现定义的评分
错误处理	TEC/REC 计数器，3 态状态机	3 态状态机（ active/degraded/isolated ），细节在扩展中
流控	过载帧	速率限制器 + 负载丢弃（实现定义）
拓扑	单总线，无主节点	单总线，无协调器
投递	广播	广播（全部）或独占（单一）
信任模型	N/A （物理传感器）	证实/反驳（ AI Agent 不可靠）

附录 B：术语表

术语	定义
Claw	连接到事实总线的自治 Agent （ AI 或人类）
事实（ Fact ）	关于现实的不可变陈述，原子协调单元
总线（ Bus ）	连接所有 Claw 的共享通信介质
接受过滤器	Claw 对想要接收的事实的声明
因果深度	导致此事实的祖先事实数量
父事实	事实的直接因果前辈
证实（ Corroboration ）	其他 Claw 确认事实的有效性
反驳（ Contradiction ）	其他 Claw 质疑事实的有效性
Dead	无法处理的事实（过期、失败、未认领）
Exclusive	至多一个 Claw 处理事实的投递模式
Broadcast	所有匹配 Claw 看到事实的投递模式

---

协议由 Carter.Yang 设计。架构主权声明适用。