LoopX 开发者手册导读：从控制平面基础到贡献路径，一条完整的中英文书目

LoopX 开发者手册导读：从控制平面基础到贡献路径，一条完整的中英文书目

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

LoopX 是一个面向长程 Agent 任务的**控制平面（Control Plane）**开源项目，它的开发者手册（Developer Book）以中英文语义镜像的方式，把"控制平面基础 → 项目接入 → 开发者贡献 → 工程边界"串成一条清晰的学习路径。这篇导读帮你 10 分钟看懂这本中英文书目的全部章节，找到适合自己的阅读起点 🎯

长程任务中的真实工作轨迹：决策、实验、验证与自我修复的闭环

一、这本开发者手册解决什么问题

普通 Agent 会话擅长在一次上下文内推理和执行，但真实开发工作会经历中断、交接、等待 CI、跨会话协作。LoopX 把目标（Goal）、工作队列（Todo）、权限（Gate/Evidence/Quota）和恢复条件放进项目拥有的控制平面，让长程任务可审计、可恢复、可交接。

docs/book/index.md 明确了这本书的定位：它不是 CLI 命令参考，也不要求你成为 Kernel 核心贡献者，而是给外部开发者一条稳定的路径，帮你判断：

• 当前任务只需一次普通会话，还是需要持久 Goal；
• 什么时候需要项目级 Todo、Gate、Evidence、Quota 与恢复合同；
• 如何从协议与不变量出发定位贡献 owner、修改实现并组织验证。

二、书目结构一览：4 部分 + 1 课程

按 mkdocs.zh.yaml 的导航，中文版书目组织如下：

LoopX 管家：跨 Goal 的个人控制平面工作区，集中展示需要你确认、执行中、观察中与已安排的 Agent 工作

三、第一部分：控制平面基础（第 1–6 章）

这是全书的地基，读完后你会建立完整的控制平面心智模型：

1. 从一次会话到长程任务——为什么一次 Session 不足以承载跨天任务，execution plane 与 control plane 如何分工；
2. 普通会话、Codex Goal 与 LoopX——三层状态与四类 Actor 的边界；
3. 持久状态与只读投影——canonical state、event 与 read-only projection；
4. 工作图、权限与 Peer 协作——Todo 工作图、Gate、claim、lease 与 authority；
5. 主要状态机与状态流转——把九组状态机连成一张图；
6. 一轮受治理的工作——Turn 如何决定、执行、验证和写回；
7. 恢复、自修复与运行边界——retry、replan、self-repair 与 terminal closure。

LoopX 1.0 Workspace：按 Goal 组织的工作面板，展示 Blocked、Queued、Running 与 Completed 的任务流转

四、第二部分：接入现有项目（第 7–9 章）

这条主线不需要修改 LoopX 源码，目标是在自己的仓库里跑通一个可恢复的 Goal：

• 连接你的 Git 项目：推荐把接入任务直接交给 Agent，你负责验收 Goal、identity 与 Git 边界（.loopx/、.codex/goals/不进入 Git）；
• 从 Codex App 启动与从 Codex CLI 启动：两条可选的 Host 启动路径。

五、第三部分：开发者贡献（第 10–16 章）

给 LoopX 做贡献不只等于修改 Kernel，也不只等于开发 Extension。贡献地图 给出协议优先的源码入口：

开发任务 → 贡献结果与 placement → 所属协议族 → 协议拥有的不变量 → bounded context → 当前实现与验证

后续章节依次覆盖：沿一条协议链定位实现、修改一条 Control-Plane 规则、从聚焦验证到 PR，以及 Extension 三件套——选择正确的放置位置、创建 standalone Extension、生命周期与 managed runtime。

六、Welcome Wagon：4 条路线，从读者到参与者 🚀

Welcome Wagon 提出"先完成一件真实的小事"，四条路线互不依赖：

开始前只需只读确认环境：loopx --version、node --version、loopx doctor、git status --short --branch。

七、中英文版本如何配合

• 中文入口：docs/book/index.md
• 英文入口：docs/book/en/index.md

两个版本是语义镜像：章节、行动、命令、链接目标或边界出现实质差异都属于文档缺陷——这本身就是一条低门槛的贡献方向（补术语一致性）。站点基于 MkDocs Material 生成，见 mkdocs.en.yaml。

八、版本基线速查

• 发布锚点：v1.0.4；运行时要求Python 3.11+ 与 Node.js 22.18.0+（TypeScript Effect runtime 由 LoopX 自动管理，无需手工维护 daemon）；
• 运行书中命令前先执行loopx --version与loopx doctor，版本不一致时以当前发布物的--help为准；
• 术语拿不准时，随时查阅附录：术语与命令入口。

结语

LoopX 开发者手册的价值不在于"读完"，而在于按图索骥：想理解为什么用控制平面，读第 1 章；想接入自己的项目，直接进第二部分；想提交第一份贡献，从 Welcome Wagon 路线 C 或贡献地图开始。选一条路线，留下一个可验证结果，再决定是否继续深入 📚

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