LoopX：解决多日长时AI Agent上下文断点的控制平面

LoopX：解决多日长时AI Agent上下文断点的控制平面 | 前端进阶之旅

Full translation

完整中文译文

如果你曾经让一个编码 Agent 去完成一个持续数天的目标，你就会知道它的失败模式。问题不在于模型写了一个烂函数，而在于到了第 40 轮，Agent 已经不记得目标是什么、你做过了什么决定、什么已经不在范围内，或者上一次运行实际证明了什么。上下文窗口滚动了一轮，故事也随之跑偏了。

LoopX 就是为了解决这个特定问题而诞生的。它自称是"长期运行 AI Agent 的循环工程"，是一个本地控制平面，位于你的 Agent 运行时之上，而不是取代它。

一句话版本

你的 Agent（Codex、Claude Code、Cursor，随你选）执行有边界的循环。某个东西（心跳、cron 作业，或者你按了一下回车）触发下一轮循环。LoopX 持有在那些循环之间必须存活的状态。

该项目是这样划分边界的：

第三行就是整个产品。LoopX 不是执行器，也不是自主生产控制器。它是一个带有 CLI 的状态内核。

为什么"用个 TODO 文件就够了"并不够

TODO.md 加上一个长的 system prompt 能让你走得很远。一旦以下任意一条变为真，它就会垮掉：

目标中途变了，但没有任何记录说明为什么。
某个决定真的需要人来拍板，但那个请求淹没在聊天消息里没人看到。
两个 Agent 在碰同一个仓库，双方都不知道谁拥有什么。
上一次运行声称成功了，但没有artifact来证明它。
有些工作是安全且只读的，有些涉及到写入、生产环境或私密数据，而这种区分只存在于你脑子里。

LoopX 让这些事情变得明确且机器可读，这正是让循环能够运行更长时间而不会变得更不负责任的原因。

概念，平铺直叙地讲

生命周期目标（Lifetime goals）。一个持久的项目意图，超越单个聊天线程而存在。重要的是，生命周期目标并不会给 Agent 开放式的自主权：只有下一个有边界的转换才是可执行的。

用户关卡（User gates）。一个属于你的具体决定，被记录为一个一等公民对象，而不是记录集中的一句话。循环可以看到自己被一个人类阻塞了。

安全回退（Safe fallback）。当一条车道被关卡阻塞时，经过审计的侧路径可以继续移动，而不会绕过关卡。这一点我觉得最有意思：替代设计方案通常是"阻塞一切"或"让 Agent 决定"，两种都很糟糕。

TODO 所有权（Todo ownership）。TODO 被标记为 user 或 agent，带有一个 claimed_by 字段，这样多个 Agent 可以协调而不是冲突。

配额（Quota）。一个守卫，回答自动轮次是否应该现在就运行、等待、询问用户、自我修复或保持安静。实际上，这是你对心跳循环在无法产生已验证转换的轮次上燃烧 token 的防御。

运行历史和证据（Run history and evidence）。紧凑的仅追加事件，用于记录进度、验证、阻塞、奖励和配额消耗。

公共/私有边界检查（Public/private boundary checks）。一次本地扫描，尝试将凭证、原始日志、本地路径和私密状态排除在你发布的任何内容之外。

安装

需求相当轻量：Python 3.11+、curl、tar，以及 macOS 或 Linux shell。这个 Python 包在标准库之外没有运行时依赖。只有当你想要贡献代码时才需要 Git。

curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"
loopx doctor

安装程序会将发布快照放到 ~/.local/share/loopx/releases/、一个 CLI 包装器放到 ~/.local/bin、一个 man 页面，以及可复用的 Agent skills 放到 ~/.codex/skills。一如既往，如果你在乎的话，在运行管道安装脚本之前先读一读。

更新通过一个明确的接口进行，而不是盲目重新运行安装程序：

loopx update --check     # read-only
loopx update --dry-run   # read-only
loopx update --execute

2. 在不接触真实仓库的情况下先试试

loopx demo
cd /tmp/loopx-demo
loopx status
loopx quota should-run --goal-id demo-goal
loopx history --goal-id demo-goal

这会创建一个带有一个人类 TODO 和一个 Agent TODO 的可丢弃目标。你应该会看到 ok: True 和一个 should_run=True / state=eligible 的配额响应。先做这一步。只需要三十秒，就能告诉你心智模型是否对你奏效。

3. 连接真实项目

cd /path/to/your-project
loopx bootstrap \
  --goal-id your-project-goal \
  --objective "Improve this project through bounded, verified goal segments." \
  --goal-doc GOAL.md

loopx connect 是 bootstrap 的别名。这会创建：

your-project/
  .loopx/registry.json
  .codex/goals/your-project-goal/ACTIVE_GOAL_STATE.md

~/.codex/loopx/
  goals/<goal-id>/runs/

将这些添加到 .gitignore 再提交：

.loopx/
.codex/goals/
.opencode/goals/
goals/**/ACTIVE_GOAL_STATE.md

那些状态是实时的本地运行时数据。把控制器的活动目标状态提交正是私密路径和内部笔记最终出现在公开仓库的方式。

一个健康的连接意味着 loopx doctor 通过、上述两个文件都存在、loopx status 显示下一步谁行动，以及没有任何内容被 staged for commit。

4. Agent 优先路径

文档实际上推动你不要自己去运行这些命令。把类似这样的东西从你的项目根目录粘贴到 Codex、Claude Code 或 Cursor：

Connect the current project to LoopX. Do not clone the LoopX repository.
If `loopx` is not on PATH, install it with the official no-clone installer.

Then run `loopx doctor`. Working only from the current project root:
1. If LoopX state already exists, reuse it. Do not overwrite the goal or objective.
2. If the project is not connected, prefer `loopx connect`; use `loopx bootstrap`
   only when state clearly needs initialization.
3. Ensure `.loopx/`, `.codex/goals/`, and `.local/` are ignored.
4. Set up the thin LoopX heartbeat for this surface.
5. Stop after setup and report the active state id, current user gate, top agent
   todo, and next safe action.

Do not start longer delivery work in this setup turn.

在你尝试对非 Codex Agent 使用这个之前，有一个值得知道的注意事项：LoopX 只能驱动至少暴露一个控制钩子的 Agent，比如 shell 执行、goal/task 命令、自动化钩子或它自己的调度器。如果没有，LoopX 仍然会跟踪状态，但你需要手动运行命令。

5. 常用命令

状态检查：

loopx status
loopx history --goal-id your-project-goal
loopx quota should-run --goal-id your-project-goal

添加 TODO：

loopx todo add --goal-id your-project-goal --role agent \
  --text "Run the next bounded validation slice."

诊断也被设计为可以委托。loopx diagnose 故意发出一个面向 Agent 的证据包而不是判决，所以你可以让你的 Agent 运行它并从中推理：这个项目能否自动驾驶、什么阻塞了它、什么具体问题需要你的答案、下一步发生什么。

6. 心跳和配额（token 消耗部分）

一个自动轮次应该在工作前检查配额，并在验证回写后精确记录一次消耗：

loopx quota should-run --goal-id your-project-goal
loopx heartbeat-prompt --thin --goal-id your-project-goal
loopx quota spend-slot --goal-id your-project-goal --slots 1 --source heartbeat --execute

对于安静跳过、预检失败或 dry run 不会追加消耗。should-run 返回一个相当丰富的契约：投递是否可以运行、它在等待什么（用户、控制器、外部证据、健康、配额）、工作车道、TODO 摘要，以及消耗策略。

7. 在发布任何东西之前

loopx check --scan-path README.md --scan-path docs/ --scan-path examples/

8. 可选的本地仪表盘

有一个只读的 React 仪表盘用于检查跨全局注册表的项目、TODO、关卡和证据。它明确是实验性的：CLI 始终是事实来源，浏览器写入需要本地 opt-in。查看仓库文档以获取当前路径，因为它在 README 和入门指南之间移动过。

它刻意不做什么

维护者在这点上异常直接，这是一个好迹象。LoopX 不是完整的 Agent 平台、不是自主生产控制器、也不是你运行时的替代品。项目所有权和危险权限留在人类手中。它是一个本地协调底层。

适合的场景

是的，如果你：在一个跨越数天的目标上运行 Agent、有按计划触发的心跳或监控风格轮次、协调一个带有作用域侧 Agent 的控制器 Agent，或者已经被 Agent 自信地重做它上周二完成的工作咬过。演示只需要你一分钟，而且这些想法是可移植的，即使你从不采用这个工具。

可能还不行，如果你：把 Agent 用于单会话任务、你在没有 WSL 的 Windows 上、需要经过实战测试且有发布历史和大量用户群的东西、或者你不使用 Codex 系列或具有 shell 能力的 Agent。价值与你的循环运行时间成正比。短循环不会漂移，而那套仪式感会让人觉得是开销。

Repo: https://github.com/huangruiteng/loopx