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/loopxLoopX 是一个面向长时程 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你会看到整个目录分为三大区域各自承担不同职责区域定位面向谁contracts/人类可读的治理契约预算、权限边界产品/运营/贡献者protocols/版本化的机器契约v0/v1 状态协议实现者/集成方extensions.md能力Capability与扩展Extension的生命周期边界插件开发者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 标注的高流量读路径入手想了解直接读单 Agent 的证据时间线重规划/交接前agent_scoped_evidence_ledger_v0目标验收缺口与待决门禁goal-acceptance-observations状态数据与 Dashboard 载荷status-data-contract自动计算的配额语义quota-allocationAgent 执行一个受治理回合loopx_turn_v0小结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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考