LoopX版本化协议地图：如何快速读懂docs/reference中的契约文档

LoopX版本化协议地图：如何快速读懂docs/reference中的契约文档

【免费下载链接】loopxLong-horizon agent control plane for durable, governed work across Codex, Claude Code, and other harnesses.项目地址: https://gitcode.com/GitHub_Trending/lo/loopx

LoopX 是一个面向长时程 AI Agent 的控制平面（Control Plane），用于在 Codex、Claude Code 等运行时之上做持久的、受治理的工作管理。而 docs/reference/ 就是 LoopX 契约文档的"版本化协议地图"：它用一组稳定、可测试、可被代码引用的文档，规定了状态怎么存、权限怎么分、多 Agent 怎么协作。对新手来说，学会读懂这些契约文档，就等于拿到了 LoopX 的"内部规则手册"。

为什么需要契约文档：从一次性 Agent 到长程控制面

传统的 Agent 工具是"一次性"的：对话结束，状态就消失。而 LoopX 要管理的是跨小时甚至跨天的长时程任务——目标（Goal）、待办（Todo）、人工门禁（Gate）、配额（Quota）、证据（Evidence）都要持久存在、可恢复、可回滚。

要做到这一点，就必须把"系统该怎样运行"写成明确的契约（Contract）：哪些状态是权威数据、哪些只是只读投影、谁来写、谁不能写。这些规则不会散落在代码里，而是集中在 docs/reference/ 目录中，"稳定到足以被测试、被链接"。

协议地图的结构：docs/reference 三大区域

打开 docs/reference/README.md，你会看到整个目录分为三大区域，各自承担不同职责：

1️⃣ contracts/：人类可读的治理契约

这一层关注的是"治理规则"，例如 接口预算契约、Dashboard 奖励写边界，以及根目录的 状态数据契约、配额分配、项目 Agent Todo 契约。它们回答的是：谁能动数据、动到什么程度、边界在哪。

2️⃣ protocols/：版本化协议契约（地图主体）

这是"协议地图"的核心。protocols/README.md 把近百份契约按职责分成了 5 大分组：

• Control Plane And State（控制平面与状态）：如 loopx_turn_v0、事件溯源状态契约、回滚包
• Agent And Multi-Agent Coordination（多 Agent 协作）：如 长时程 Agent 状态协议、多 Agent 三层极简契约
• Runtime And Host Integration（运行时与宿主集成）：Codex CLI 命令注册表、计算机使用运行时等
• Domain Capabilities（领域能力）：自动研究、内容运营等场景协议
• Quality, Review, And Release（质量评审与发布）：模型行为资格验证等

命名规律很好记：文件名即协议名，后缀_v0/_v1是版本号。看到-v0表示该契约处于初始稳定期，未来可能不兼容地升级。部分文档还提供.zh-CN.md中文版（如 typed-date-resume-trigger-v0.zh-CN.md），中文用户可以直接对照阅读。

3️⃣ extensions.md：能力与扩展的边界

extensions.md 讲清了一个容易混淆的概念：能力（capability）是 LoopX 能做什么，扩展（extension）是可独立安装/升级的交付单元。内置能力与扩展能力共享同一个注册表，注册是显式的——这决定了你开发插件时的接入点。

四步读懂任意一份协议契约

拿到一份陌生的协议文档（比如 long-horizon-agent-state-protocol-v0），按下面四步读，几分钟就能建立完整心智模型：

第一步：看"Status"与开头定义

文档开头通常有一行状态声明（如 experimental、stable），随后用一两句话说明这份契约管辖什么、不管辖什么。例如 loopx_turn_v0 开宗明义：LoopX 持有目标状态的权威，宿主（Host）只负责执行模型调用，"不把宿主变成第二个控制平面"。

第二步：找"Mental Model"表格

LoopX 的协议文档偏爱用表格把角色、阶段、契约一一对齐。以 LoopX Turn 的四阶段控制环为例：

LoopX 决策 → Agent CLI 执行 → 独立验证器证明 → LoopX 提交

决定阶段归 LoopX，执行阶段归宿主，验证必须是独立程序（执行者不能自证完成），提交阶段只有验证通过才消耗配额。看懂这张表，你就理解了整个系统的权力分配。

第三步：分清"源状态"与"投影"

这是 LoopX 协议文档最重要的概念区分：

• 源状态（Source）：唯一事实来源，如注册表、活动目标状态、追加式事件流，只能通过生命周期命令写入
• 投影（Projection）：只读视图，如 Dashboard 卡片、状态摘要，可以压缩和重排，但绝不拥有真相、不授予权限

事件溯源状态契约 把这条规则推到了极致：每个目标拥有一条只增不改的事件流，ACTIVE_GOAL_STATE.md只是从事件渲染出来的工作台，事件按append_sequence顺序重放且幂等。

第四步：查"现有锚点"列

几乎每份协议都会列出一张"字段 ↔ 现有锚点"表，把契约字段映射到真实代码模块（如loopx/status.py、loopx/rollout_event_log.py）。读文档时顺藤摸瓜找到对应源码，抽象的契约就落到了具体实现上。部分协议还有配套的 JSON Schema（如 computer_use_runtime_v0 schema 目录），可以直接用于校验。

实战视角：契约在真实运行中长什么样

协议不是纸上谈兵。在 LoopX 的多 Agent 自动研究场景中，每个 Agent 在自己的 tmux 面板里循环领取 Todo、写证据、触发配额检查——这些行为正是上面契约文档的实时运行：心跳提示"LoopX 状态而非调度器决定工作"、阻塞的 P0 任务等待人工门禁、证据以 public-safe 事件写入追加日志。

高频入口速查表 📌

第一次进 docs/reference/ 的人，建议从 README 标注的"高流量读路径"入手：

小结

LoopX 的 docs/reference/ 目录本质上是一张版本化协议地图：contracts/管治理边界，protocols/管机器契约（按 v0/v1 版本演进、按五大职责分组），extensions.md管能力扩展生命周期。记住"命名即版本、表格即心智模型、源状态与投影分离"这三条阅读心法，你就能在几十份协议中快速定位到与自己任务相关的那一份，而不必逐篇通读。

【免费下载链接】loopxLong-horizon agent control plane for durable, governed work across Codex, Claude Code, and other harnesses.项目地址: https://gitcode.com/GitHub_Trending/lo/loopx