ARTICLE · 1047162
LoopX 源码解析(一):LoopX 是什么,它是如何支撑长任务
先给一个具体场景。你想让 agent 干一件大活：给一个开源仓库做一系列贡献——读代码、改代码、跑测试、提 PR，这个任务不是一次对话能做完的，预计要跨好几天、几十次会话。
不用任何框架直接做，会遇到四件事：
会话一断，全忘。 Claude Code 或 Codex 的会话结束后重开，agent 不知道昨天改到哪了、哪些方案试过失败了、下一步该干什么 跑偏没人管。 agent 干着干着忘记原始目标，开始重复劳动或者自己发明新需求，token 消耗没有人拦截 花钱没数。 一晚上烧了多少调用、值不值，没有记录 交接说不清。 你换了个模型或换个工具接着干，上一步的进度和教训传不过去
LoopX 就是解决这四件事的工具。本篇讲它的设计理念，以及这些理念怎么支撑长任务执行；
代码：github.com/huangruiteng/loopx
LoopX 是什么
一句话：LoopX 把任务状态持久化在项目目录的文件里（目标、待办清单、证据、预算记录），agent 每个工作回合开始前先调 LoopX 命令检查"现在允许跑吗、跑哪个待办"，结束时必须写回执行结果和证据、扣除预算；涉及高风险操作时，LoopX 生成一个具体问题暂停等人回答。
装完 LoopX 后，项目里多出一个 .loopx/ 目录存这些状态文件。agent 的每个工作回合（LoopX 叫一个 turn）变成固定流程：
loopx quota should-run → 现在能跑吗？预算还够吗？（不能跑就停，返回原因）loopx todo claim → 从待办清单认领一项（加锁，其他 agent 不会重复领）... agent 执行这一小段工作，产出证据（diff、测试结果）...loopx todo update → 写回结果和证据，更新待办状态loopx quota spend-slot → 记录：这一回合消耗了预算
注意执行工作的仍然是 Codex、Claude Code 这些你本来用的 agent 工具——LoopX 不包含任何模型，不执行任何业务工作。它只做管理：持久化状态、限制消耗、拦截高风险操作、结构化交接。这就是"控制平面"的含义：agent 负责执行，控制平面决定能不能执行、记录结果、拦截危险操作。
四条设计理念
LoopX 的所有机制都从下面四条理念推出来。
理念一：治理决策不依赖模型
整个 control_plane/ 目录里没有一次模型调用。"能不能跑"（配额决策）、"谁来做"（待办分配）、"做完没有"（验证）——全部是确定性代码。LLM 只出现在被驱动的 agent 工具里面。
这条理念来自对长任务失败的判断：会话丢失、目标漂移、超额消耗这些问题的根源，是把这些治理决策交给了概率性的模型输出。LoopX 的选择是把治理全部收进确定性代码，模型只负责执行。前面系列文章讲过的原则——"凡是能用确定性代码判定的，都不要让模型自己判定"——LoopX 把它做成了整个系统的架构。
理念二：状态在文件里，上下文每轮重建
任务的目标、待办、证据、决策记录都存在磁盘文件里，不依赖任何会话。agent 每个回合的上下文从这些文件重新组装，而不是延续聊天历史。
会话在 LoopX 里是可以随时丢弃的：进程崩溃、换模型、换工具，都不影响任务——下一个回合读文件恢复认知。这是"跨几天、几十次会话"能成立的前提。
理念三：长任务切成有界小段，每段必须留下证据
一个 turn 只做一小段有边界的工作，做完必须写回可验证的证据（代码 diff、测试结果、命令输出），然后记账。没有证据的执行不算进展。
这对应软件工程里已经被验证的实践：小步提交、每次提交可审查、可回退。区别在于 LoopX 用确定性代码强制它——agent 不写证据，这个回合就无法结算。
理念四：默认只读，风险操作交还给人
新任务的默认权限是只读。写文件、发布、删除这类高风险动作会触发门禁：LoopX 生成一个具体的问题（"是否同意先执行只读探查？"），暂停等待人回答，批准附带具体命令且不等于授予写权限。
人对任务的控制不靠盯着，靠在关键节点回答具体问题。
这套设计怎么支撑长任务
把开头的四个问题和 LoopX 的应对一一对应：
长任务执行的整体图景：心跳或定时触发 → 确定性决策（能不能跑、跑什么）→ 认领待办、加锁 → 从状态文件重建上下文 → agent 执行一小段 → 写证据、记账 → 调度下一轮。每一环都是确定性代码把关，模型只出现在"执行一小段"那里。
这个循环没有内存中的累积状态——每次心跳都完整重走决策链，所以任何时刻崩溃都不会污染决策。
设计亮点
把"不信任模型"做成架构而不是规范。多数系统的做法是在提示词里要求模型守规矩；LoopX 的做法是让模型在结构上没有越界的通道——治理决策它做不了（无 LLM）、状态它改不到（只有 Kernel 能写）、高风险操作它执行不了（门禁在前）。可迁移的判断：约束模型行为，机制比劝说可靠。
用"回合"作为长任务的基本单位。"把任务切成有界小段 + 每段留证据 + 每段记账"这个结构，同时解决了审查（每段可查）、恢复（每段是检查点）、预算（每段是计量单位）三个问题。一个原语解决三个问题，这是这个设计经济的地方。
人的角色被重新定义为"回答具体问题"。长任务里人的介入方式不是盯着看（不可持续），也不是放开不管（不可接受），而是在门禁处回答系统生成的具体问题。问题具体、附带命令、批准不扩权——这让人的监督成本降到了可承受的水平。
代价与局限
复杂度是真实成本。对跑几小时的任务，这套基础设施的复杂度远超收益；它的目标场景是周级、多 agent、多运行时的长任务。
每个回合都有固定开销。决策、加锁、重建上下文、结算，这些管理动作本身消耗时间和 token。任务切得越碎，管理开销占比越高——有界切片的粒度是使用时需要调的参数，不是免费选择。
确定性治理的灵活性有限。目标会随探索演化的一类任务（开放式研究），写在文件里的目标和待办需要频繁人工修订，门禁和配额的硬约束在这个场景下反而碍事。LoopX 适合边界清晰、可验证的任务（编码、修复、迁移）。
一个完整的例子：跨三天的编码任务
用一个具体任务把上面的理念和流程串起来。任务：给一个开源仓库添加深色模式支持——涉及前端组件、样式变量、测试，预计跨三天。agent 运行时用 Claude Code，你白天上班，只有晚上看一眼。
第 0 步，初始化。你运行 LoopX 的配置命令创建 goal，设定配额（比如每天最多 40% 的时间槽有活动）。.loopx/ 目录生成，初始待办清单是 agent 扩展出来的：调研现有样式结构、设计变量方案、改组件、补测试、提 PR。
第 1 天，正常回合。心跳触发，LoopX 跑 quota should-run：配额没超、没有挂起的门禁、有待办可领——允许跑。agent 领取"调研现有样式结构"（加锁），LoopX 从状态文件组装这个回合的上下文（目标 + 这条待办 + 之前的证据），Claude Code 执行：读组件代码、输出一份样式结构分析、写入 dark-mode-notes.md。回合结束，todo update 把分析文件记为证据、标记完成，spend-slot 记账。后面几个回合依次做完设计、改完组件。每天配额用完，should-run 返回 throttled，agent 停下——第二天窗口滑动自动恢复。
第 2 天，崩溃。你重启了电脑，Claude Code 的会话全没了。没有影响：心跳再次触发时，LoopX 从状态文件重建上下文——已完成三项、证据在哪、下一步是补测试。agent 直接从"补测试"继续，不重复已做的工作。这是理念二在起作用。
第 2 天晚上，门禁。测试补完，待办清单下一项是"提 PR"——推送到远端仓库属于高风险操作，触发门禁。LoopX 生成具体问题等你回答（"是否同意推送分支并创建 PR？"），agent 暂停。你晚上回来看一眼测试结果，批准，附带的是这一次的推送命令，不等于以后都能推。这是理念四。
第 3 天，交接。你想换 Codex 接手做最后的文档和 CI 收尾。LoopX 的交接是结构化数据：做了什么、关键决策（为什么选 CSS 变量而不是主题类）、试过什么失败了（直接覆盖样式不可行）、下一步。Codex 的第一个回合读这份交接继续，不需要读三天的对话历史。
完成。最后一条待办（CI 通过）由确定性检查判定——测试结果和 CI 状态是证据，不是 agent 自己说"我做完了"。goal 标记完成，全程的配额消耗、证据、每回合记录都在状态文件里，可回查。
这个例子里没有出现任何一次"模型自己决定接下来干什么"——每个回合的启动、停止、记账、拦截都是确定性代码做的，模型只在回合内部执行具体工作。这就是 LoopX 支撑长任务的方式。