拓冰网站定制 
Cairn协议API深度指南Fact图、Intent认领与Reason Lease的并发一致性设计【免费下载链接】CairnA AI general-purpose state-space search engine, validated first on autonomous penetration testing.项目地址: https://gitcode.com/gh_mirrors/cairn2/CairnCairn衍迹是一个面向 AI 的通用状态空间搜索引擎已在自主渗透测试场景完成验证。这篇文章带你深入它的协作探索协议 APIFact 图如何做到只增不改的一致性、Intent 认领claim机制如何避免多个 Agent 重复劳动、Reason Lease 又如何保证项目级推理互斥——这正是 Cairn 多 Agent 并发协作不打架的三大核心设计。一、Cairn 协议是什么黑板架构的三个原语Cairn 把从起点到终点的探索建模为一张有向图。多个消费者人或 Agent并发读取完整图、各自声明探索方向、各自产出新事实最终由某个消费者判断终点已达成。这套协议是经典**黑板架构Blackboard Architecture**的现代化重构完整定义见官方协议文档 server-protocol.md。图中只有三个原语原语图中的角色一句话理解Fact节点已确认的客观事实只增不改Intent边已声明的探索方向带认领与心跳状态机Hint图外输入人工策略建议或 Agent 间传递的态势评估一个关键设定系统不做任何推理和决策只负责图的一致性维护。所有判断都交给读图的消费者Server 只做守门员。上图是 Cairn 的运行时界面左侧 Origin → Goal 之间不断长出新的 Fact 与 Intent右侧面板可以看到每个 Fact 是由哪条 Intent 产出、由哪个 Worker 执行的——图本身就是完整的审计日志。二、Fact 图只增不改节点与超边语义Fact 的设计只有两条铁律只增不改状态变化通过追加新 Fact 表达。例如shell 断了不是去修改旧 Fact而是新增一条f025: host-A shell 已断开。事实的时序本身就携带了状态演化信息描述是提炼而非原始数据扫描结果这类大体积输出Fact 只写关键洞见加文件引用保证图轻量、原始数据仍可追溯。Intent 的from字段是一个数组这是协议里很精巧的一个设计当多个已知事实共同支撑一次探索时全部列入from这条 Intent 在图上等价于一条超边完整保留多事实 → 一次探索的因果关系而不必被迫选一个主 Fact 丢失上下文。实现上from列表存放在独立的intent_sources表中见数据库 schema db.pyf002 ──┐ ├──(intent)──→ f006 f004 ──┘另外两条容易忽略的约束from不能包含goal项目创建时系统会自动写入origin与goal两个特殊 Fact见创建逻辑 projects.py。三、Intent 认领heartbeat 协议如何防止重复劳动这是并发协作的核心问题Agent A 正在探索SQL 注入Agent B 读到图后不能又去探索同一方向。Cairn 的解法是把每条未结论的 Intent 设计成一个带状态机的租约状态由worker和last_heartbeat_at两个字段共同表达Intent 状态worker 含义尚无结论worker null无人处理等待认领尚无结论worker 有值有消费者正在处理尚无结论worker 心跳超时worker 自动清空为 null可被重新认领已结论to ≠ nullworker 永久保留为产出者不再参与超时逻辑围绕这条状态机协议提供三个接口实现见 intents.pyheartbeat认领 续约未认领时任何消费者 heartbeat 即完成认领已认领则只有持有者可续约否则返回409 冲突。也就是说认领不是一个独立动作而是 heartbeat 的自然语义release主动释放探索失败或决定放弃时持有者立即释放其他消费者可以马上接手不必干等超时conclude结论落定原子操作一次性完成写入新 Fact Intent 打上结论 worker 永久保留三件事返回 Fact 和 Intent 的完整对象。超时由全局设置intent_timeout控制。它的实现方式很值得一提Server 采用惰性过期——每次读取或写入前顺手执行一条 UPDATE把心跳超时的 Intent 的 worker 批量清空见 services.py 中的expire_workers。不需要后台定时器任何一次 API 调用都顺带打扫过期的锁简单且无遗漏。四、Reason Lease项目级推理互斥Explore 解决的是一条边谁来探还有一个更高层次的问题谁来读整张图做全局判断是否已完成下一步该探索什么方向。这就是reason任务它的并发约束由项目级 Reason Lease表达单个项目同一时刻最多只有一个 reason 在运行跨项目则允许并行。Lease 生命周期只有三个接口实现见 projects.pyclaimproject.reason为空则认领成功写入 worker、trigger、started_at被他人占用且未超时返回 409同一 worker 重复 claim 幂等返回天然支持重试heartbeat仅持有者可续约更新last_heartbeat_atrelease持有者主动释放立即回到无人状态已为空时幂等。Lease 会直接出现在GET /projects和GET /projects/{id}的project.reason字段中前端和其他消费者一眼就能看出谁正在对整个项目做 reason 判断。它同样受reason_timeout超时保护走的是同一套惰性清理expire_reason_leases。一个微妙的设计区分Reason Lease不是图数据不产生 Intent/Fact不参与因果推理它只是项目级协调状态——正如协议文档强调的这类状态不是事实不属于图。五、并发一致性三道防线汇总把上面两条线索合起来Cairn 的并发一致性靠的是三道防线全部由 Server 单点裁决防线机制防住什么️ 原子写conclude / complete / claim 都在单个事务内完成校验 写入两个消费者同时结论落定、同时完成项目️ 租约 心跳worker 字段 409 冲突 超时自动清空死锁持有者崩溃与重复执行️ 硬停止项目切stopped时Server立即清空所有 open Intent 的 worker 和 reason lease并拒绝后续探索写操作403停止后旧 claim 还活着导致的僵尸任务第三道防线尤其重要stopped的语义是硬停止——claim 立即失效而非等超时消费者收到 403 或读到状态变化后应立刻取消本地任务。这样项目恢复active后能马上重新认领不必空等。在架构层面还有一层收口Dispatcher 是唯一的协议写入者。Agent Worker 只接收渲染好的 prompt、返回结构化输出不直接 claim、不直接 heartbeatDispatcher 代它完成认领、续约、结论落定与释放协议客户端见 client.pyreason 任务的 lease 封装见 reason.py。写入口单一一致性边界清晰。六、上手实践消费者的典型流程理解了机制实际使用时的节奏是这样的完整清单见 server-protocol.md 末尾的消费者典型使用流程读图GET /projects/{id}拿结构化数据用于调度判断GET /projects/{id}/export?formatyaml拿图快照渲染给 Agent初始态facts 只有 origin/goal 时可声明一条保留的bootstrapintentfrom[origin],descriptionbootstrap直接尝试解题走同样的 claim → heartbeat → conclude/release 生命周期有未认领 Intentheartbeat 认领 → 执行探索 → 成功则 conclude、失败则 release无未认领 Intentclaim reason lease → 读图推理 → 产出 complete 或新 intent →无论成败都 release判断有误completed 项目可调用reopen撤销完成态纠错信息落为新 Fact继续探索。超时参数intent_timeout/reason_timeout通过GET/PUT /settings调整心跳周期通常配置为略小于超时值给抖动留足余量。七、关键文件导航 内容路径协作协议完整定义含 YAML 导出示例docs/specs/server-protocol.mdDispatcher 调度与任务模型设计docs/specs/dispatcher-design.mdIntent 心跳/释放/结论 API 实现cairn/src/cairn/server/routers/intents.pyReason lease、complete、reopen 实现cairn/src/cairn/server/routers/projects.py惰性超时清理expire_workers / expire_reason_leasescairn/src/cairn/server/services.pySQLite schemafacts / intents / intent_sourcescairn/src/cairn/server/db.pyDispatcher 协议客户端cairn/src/cairn/dispatcher/protocol/client.py运行示例配置dispatch.example.yaml一句话总结Cairn 协议用Fact 只增不改 Intent 租约 Reason Lease三件套把多 Agent 并发探索收敛为一组短小原子接口——没有中央调度、没有 Agent 间直接通信一致性完全由 Server 单点兜底。这也是它能支撑多个 Agent 并行渗透、互不干扰的关键所在。【免费下载链接】CairnA AI general-purpose state-space search engine, validated first on autonomous penetration testing.项目地址: https://gitcode.com/gh_mirrors/cairn2/Cairn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cairn协议API深度指南：Fact图、Intent认领与Reason Lease的并发一致性设计
Cairn协议API深度指南Fact图、Intent认领与Reason Lease的并发一致性设计【免费下载链接】CairnA AI general-purpose state-space search engine, validated first on autonomous penetration testing.项目地址: https://gitcode.com/gh_mirrors/cairn2/CairnCairn衍迹是一个面向 AI 的通用状态空间搜索引擎已在自主渗透测试场景完成验证。这篇文章带你深入它的协作探索协议 APIFact 图如何做到只增不改的一致性、Intent 认领claim机制如何避免多个 Agent 重复劳动、Reason Lease 又如何保证项目级推理互斥——这正是 Cairn 多 Agent 并发协作不打架的三大核心设计。一、Cairn 协议是什么黑板架构的三个原语Cairn 把从起点到终点的探索建模为一张有向图。多个消费者人或 Agent并发读取完整图、各自声明探索方向、各自产出新事实最终由某个消费者判断终点已达成。这套协议是经典**黑板架构Blackboard Architecture**的现代化重构完整定义见官方协议文档 server-protocol.md。图中只有三个原语原语图中的角色一句话理解Fact节点已确认的客观事实只增不改Intent边已声明的探索方向带认领与心跳状态机Hint图外输入人工策略建议或 Agent 间传递的态势评估一个关键设定系统不做任何推理和决策只负责图的一致性维护。所有判断都交给读图的消费者Server 只做守门员。上图是 Cairn 的运行时界面左侧 Origin → Goal 之间不断长出新的 Fact 与 Intent右侧面板可以看到每个 Fact 是由哪条 Intent 产出、由哪个 Worker 执行的——图本身就是完整的审计日志。二、Fact 图只增不改节点与超边语义Fact 的设计只有两条铁律只增不改状态变化通过追加新 Fact 表达。例如shell 断了不是去修改旧 Fact而是新增一条f025: host-A shell 已断开。事实的时序本身就携带了状态演化信息描述是提炼而非原始数据扫描结果这类大体积输出Fact 只写关键洞见加文件引用保证图轻量、原始数据仍可追溯。Intent 的from字段是一个数组这是协议里很精巧的一个设计当多个已知事实共同支撑一次探索时全部列入from这条 Intent 在图上等价于一条超边完整保留多事实 → 一次探索的因果关系而不必被迫选一个主 Fact 丢失上下文。实现上from列表存放在独立的intent_sources表中见数据库 schema db.pyf002 ──┐ ├──(intent)──→ f006 f004 ──┘另外两条容易忽略的约束from不能包含goal项目创建时系统会自动写入origin与goal两个特殊 Fact见创建逻辑 projects.py。三、Intent 认领heartbeat 协议如何防止重复劳动这是并发协作的核心问题Agent A 正在探索SQL 注入Agent B 读到图后不能又去探索同一方向。Cairn 的解法是把每条未结论的 Intent 设计成一个带状态机的租约状态由worker和last_heartbeat_at两个字段共同表达Intent 状态worker 含义尚无结论worker null无人处理等待认领尚无结论worker 有值有消费者正在处理尚无结论worker 心跳超时worker 自动清空为 null可被重新认领已结论to ≠ nullworker 永久保留为产出者不再参与超时逻辑围绕这条状态机协议提供三个接口实现见 intents.pyheartbeat认领 续约未认领时任何消费者 heartbeat 即完成认领已认领则只有持有者可续约否则返回409 冲突。也就是说认领不是一个独立动作而是 heartbeat 的自然语义release主动释放探索失败或决定放弃时持有者立即释放其他消费者可以马上接手不必干等超时conclude结论落定原子操作一次性完成写入新 Fact Intent 打上结论 worker 永久保留三件事返回 Fact 和 Intent 的完整对象。超时由全局设置intent_timeout控制。它的实现方式很值得一提Server 采用惰性过期——每次读取或写入前顺手执行一条 UPDATE把心跳超时的 Intent 的 worker 批量清空见 services.py 中的expire_workers。不需要后台定时器任何一次 API 调用都顺带打扫过期的锁简单且无遗漏。四、Reason Lease项目级推理互斥Explore 解决的是一条边谁来探还有一个更高层次的问题谁来读整张图做全局判断是否已完成下一步该探索什么方向。这就是reason任务它的并发约束由项目级 Reason Lease表达单个项目同一时刻最多只有一个 reason 在运行跨项目则允许并行。Lease 生命周期只有三个接口实现见 projects.pyclaimproject.reason为空则认领成功写入 worker、trigger、started_at被他人占用且未超时返回 409同一 worker 重复 claim 幂等返回天然支持重试heartbeat仅持有者可续约更新last_heartbeat_atrelease持有者主动释放立即回到无人状态已为空时幂等。Lease 会直接出现在GET /projects和GET /projects/{id}的project.reason字段中前端和其他消费者一眼就能看出谁正在对整个项目做 reason 判断。它同样受reason_timeout超时保护走的是同一套惰性清理expire_reason_leases。一个微妙的设计区分Reason Lease不是图数据不产生 Intent/Fact不参与因果推理它只是项目级协调状态——正如协议文档强调的这类状态不是事实不属于图。五、并发一致性三道防线汇总把上面两条线索合起来Cairn 的并发一致性靠的是三道防线全部由 Server 单点裁决防线机制防住什么️ 原子写conclude / complete / claim 都在单个事务内完成校验 写入两个消费者同时结论落定、同时完成项目️ 租约 心跳worker 字段 409 冲突 超时自动清空死锁持有者崩溃与重复执行️ 硬停止项目切stopped时Server立即清空所有 open Intent 的 worker 和 reason lease并拒绝后续探索写操作403停止后旧 claim 还活着导致的僵尸任务第三道防线尤其重要stopped的语义是硬停止——claim 立即失效而非等超时消费者收到 403 或读到状态变化后应立刻取消本地任务。这样项目恢复active后能马上重新认领不必空等。在架构层面还有一层收口Dispatcher 是唯一的协议写入者。Agent Worker 只接收渲染好的 prompt、返回结构化输出不直接 claim、不直接 heartbeatDispatcher 代它完成认领、续约、结论落定与释放协议客户端见 client.pyreason 任务的 lease 封装见 reason.py。写入口单一一致性边界清晰。六、上手实践消费者的典型流程理解了机制实际使用时的节奏是这样的完整清单见 server-protocol.md 末尾的消费者典型使用流程读图GET /projects/{id}拿结构化数据用于调度判断GET /projects/{id}/export?formatyaml拿图快照渲染给 Agent初始态facts 只有 origin/goal 时可声明一条保留的bootstrapintentfrom[origin],descriptionbootstrap直接尝试解题走同样的 claim → heartbeat → conclude/release 生命周期有未认领 Intentheartbeat 认领 → 执行探索 → 成功则 conclude、失败则 release无未认领 Intentclaim reason lease → 读图推理 → 产出 complete 或新 intent →无论成败都 release判断有误completed 项目可调用reopen撤销完成态纠错信息落为新 Fact继续探索。超时参数intent_timeout/reason_timeout通过GET/PUT /settings调整心跳周期通常配置为略小于超时值给抖动留足余量。七、关键文件导航 内容路径协作协议完整定义含 YAML 导出示例docs/specs/server-protocol.mdDispatcher 调度与任务模型设计docs/specs/dispatcher-design.mdIntent 心跳/释放/结论 API 实现cairn/src/cairn/server/routers/intents.pyReason lease、complete、reopen 实现cairn/src/cairn/server/routers/projects.py惰性超时清理expire_workers / expire_reason_leasescairn/src/cairn/server/services.pySQLite schemafacts / intents / intent_sourcescairn/src/cairn/server/db.pyDispatcher 协议客户端cairn/src/cairn/dispatcher/protocol/client.py运行示例配置dispatch.example.yaml一句话总结Cairn 协议用Fact 只增不改 Intent 租约 Reason Lease三件套把多 Agent 并发探索收敛为一组短小原子接口——没有中央调度、没有 Agent 间直接通信一致性完全由 Server 单点兜底。这也是它能支撑多个 Agent 并行渗透、互不干扰的关键所在。【免费下载链接】CairnA AI general-purpose state-space search engine, validated first on autonomous penetration testing.项目地址: https://gitcode.com/gh_mirrors/cairn2/Cairn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考