LoopX：给长程 AI Agent 一个持久化的本地控制面

LoopX

AI Agent 的能力在变强，但真正难的是让 Agent 跑完一个跨天、跨会话、跨多个 Agent 协作的长任务后，还能把进展、证据、待办决策完整交接回来。LoopX 就是冲着这个痛点设计的：一个 agent-agnostic 的本地控制面，把目标、门禁、待办、证据、配额和交接做成持久化状态层，让 Codex、Claude Code、Cursor 或者自定义 runner 都能在一个统一框架下执行有界轮次。

GitHub Trending 显示该项目目前 2693 star，语言是 Python，MIT 许可证，零运行时依赖（纯标准库实现）。它给自己的定位是 "the local control plane for long-running AI agent work"，核心做的是 Loop Engineering。

LoopX 解决什么问题

一个 Agent 在一次会话内可以完成不少事。但长程任务更难：目标会变，Owner 决策会随时插入，证据会过期，Agent 之间需要交接，调度器可能在已经没有有意义的进展时还在烧算力。聊天记忆加一个定时器不足以治理这种场景。

LoopX 把这些治理需求抽象成一个紧凑的状态层。核心心智模型是 Agent-Native Kanban：卡片承载身份、权限、证据和续接信息；移动操作是经过验证的算子（claim、gate、monitor、writeback）；看板只是一个投影，LoopX 状态才是唯一真相来源。

整体流程可以用一段伪代码描述：

text

objective / issue / project
   │
   ▼
LoopX state: objective + gates + todos + scope + evidence + quota
   │
   ├─ human judgment needed? ── yes ─▶ ask a concrete question and wait
   │
   ├─ safe fallback available? ──────▶ run one bounded agent slice
   │
   ▼
Codex / Claude Code / Cursor / shell agent executes one turn
   │
   ▼
write evidence + handoff + next todo ─▶ quota decides the next tick

每个 Agent turn 都要穿过 authority、boundary、quota、validation、writeback 五道关卡，才能被算作有效进展。这保证了一个目标可以活很久，但每一轮 Agent 行动仍然是受约束的。

六层持久化控制面

LoopX 的架构有六层持久化控制面，加上一个可选的只读探针层：

层	职责
Registry	记录已知目标、关联仓库、适配器、权限来源、状态和防护
Goal State	单个目标的活跃状态文件
Run Log	每个目标的 JSON 和 Markdown 报告
Run History	供 Agent、心跳和 UI 消费的紧凑索引
Status / Attention Queue	第一屏摘要：谁需要行动
Compute Quota	每个目标可消耗多少自动 Agent 算力的本地策略

可选的探针层是一个项目级只读观测命令，而非独立的第七层。注册时存储为自由文本，心跳和操作策略要求执行时必须是只读的。

四种运行时角色

角色	职责	不能做的事
Agent	规划、分析、工具调用，通过 host/runtime 执行一个有界动作	持有目标生命周期或无界效果权限
Provider	外部调用、观测、效果结果和回读	决定领域转换策略或写 LoopX todo 状态
Capability	调用方结果契约、领域策略、观测归一化、验证和类型化转换提案	持有调度、claim、gate 或直接写生命周期
LoopX Kernel	目标、todo、claim、gate、monitor、quota、已接受的 writeback、恢复和调度	领域推理或 provider 实现细节

请求路径和结果路径是反向的：Agent → Capability → Provider → 外部系统；外部观测/效果回读 → Provider → Capability → 类型化转换提案 → LoopX Kernel → 下一个 todo/gate/monitor/turn。一个观测不等于一次转换，一个 provider receipt 不等于已接受的进展——必须经过 Capability 验证和 Kernel 提交才算数。

配额系统：一个数字治理算力分配

LoopX v0.1 的 Compute Quota 设计刻意简单：每个目标一个配额数字，自动化或控制器 tick 用这个数字决定该目标多久消费一次 Agent 时间。

这个数字可以理解为占空比（duty cycle）或相对权重：

1.0：全占空比。如果控制器每小时检查一次，该目标在每个健康检查的 24 小时窗口内都有资格。默认分钟粒度下意味着每天 1440 个自动计算分钟槽位。
0.5：半占空比，约每天 12 小时。
0：计算暂停。这是目标级硬暂停：目标仍然可见，但不接收任何自动 Agent 轮次。

配额的应用顺序在硬门禁之后：健康/安全门禁 → 操作者门禁 → 证据等待 → 焦点等待 → 计算配额。这保证配额不会变成第二个权限系统。

配额 JSON 结构示例：

json

{
  "quota": {
    "compute": 0.5,
    "window_hours": 24,
    "slot_minutes": 1,
    "allowed_slots": 720,
    "spent_slots": 240,
    "state": "eligible",
    "next_eligible_at": "2026-06-02T12:00:00+08:00"
  }
}

核心命令面

LoopX 的核心 tick 故意做得很小：

bash

loopx quota should-run      # 这个注册的 Agent 现在应该行动吗？
loopx todo claim            # 谁拥有这个切片？
loopx todo update           # 发生了什么变化？
loopx refresh-state         # 下一轮应该看到什么？
loopx quota spend-slot      # 记录一个已完成且验证的切片

安装不需要 clone 仓库：

bash

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

连接项目后：

bash

cd /path/to/your-project
loopx connect
loopx status

LoopX 支持多种 Agent 宿主：Codex App（心跳自动化驱动）、Codex CLI（可见 /goal 命令）、Claude Code（opt-in adapter + 原生 /loop）、Cursor / shell / 自定义 runner。每种宿主的 loop driver 不同，但都经过同一个配额和门禁框架。

Turn 决策的类型化词汇

操作者文档常用 deliver / wait / ask / replan / repair / stay quiet 来描述一个 turn 的意图。但 LoopX 内部的 Turn 契约使用两个类型化枚举：

契约	时机	成员
`LoopXTurnRoute`	host 执行前	`ready_for_host`, `repair_required`, `replan_required`, `user_action_required`, `wait`, `blocked`, `contract_error`
`LoopXTurnResultKind`	host 执行后	`validated_progress`, `validated_completion`, `repair_required`, `replan_required`, `user_action_required`, `wait`, `host_failure`, `validation_failed`, `writeback_failed`, `quota_spend_failed`

这种类型化设计避免了自然语言缩写丢失的信息：prose "deliver" 被拆分为 validated_progress 和 validated_completion；失败种类（host_failure、validation_failed、writeback_failed、quota_spend_failed）是头等公民；"stay quiet" 是通知/监控行为，不属于两个枚举的成员。

实际验证：200+ 小时的长程轨迹

LoopX 的作者用这个框架驱动了两条 200+ 小时经过时间的长程轨迹作为验证证据。经过时间（elapsed lifetime）指墙钟项目时间，不是 200 小时连续模型执行。

第一条是开源 Issue-Fix 轨迹：作者以 OpenViking 贡献者身份使用 LoopX 驱动 PR 交付。Issue-Fix 能力保持滚动仓库上下文、修订戳标记的修复知识和面向 reviewer 的偏好分离；关联 PR 加上当前 checkout 源码和测试始终保持权威性。

第二条是 Auto ML 实验轨迹：假设、匹配证据、无效谱系、运行中的重复和 promote/stop 门禁在一个图中保持可见。

200小时长程轨迹

这些是轨迹证据，不是对连续计算、独立复现或生产结果的声明。LoopX 明确定位自己不是自主生产控制器：危险权限、发布、生产写入和最终所有权始终留在人类手中。

领域能力包

LoopX 把控制面机制折叠成五个问题：

问题	LoopX 保持可见的内容
目标是什么？	活跃目标、显式范围和当前权限
接下来发生什么？	有序的用户和 Agent todo、所有权、claim 和租约
什么需要人类判断？	具体的用户门禁，而非含糊的"等待 owner"
什么证据变了？	紧凑的运行历史、验证、阻塞和已接受的 writeback
循环可以继续吗？	配额、能力、安全回退、调度提示和停止条件

基于这五个问题，LoopX 封装了多个领域能力包：Issue-Fix（issue 修复）、Content-Ops（内容运营）、Value-Connectors（价值连接规划）、ML-Experiment（实验建议）、Benchmark（基准证据）和 Explore（探索图与测试台）。每个能力包定义调用方结果，归一化 provider 输出，验证后提出类型化转换。

安全边界与治理

LoopX 的设计哲学在安全边界上体现得最明显。几个关键原则：

公共/私有边界：.loopx/、.codex/goals/、活跃的 ACTIVE_GOAL_STATE.md、原始 benchmark 轨迹、凭据、私有日志和操作者工件都不提交到公共仓库。发布公共文档或示例前，可以用 loopx check 扫描。

自我修复是 opt-in 的：control_plane.self_repair.enabled 默认 false。即使开启，一个目标也只能花一个有界轮次修复阻止正常交付的 LoopX 健康或契约阻塞。

配额不授予权限：quota plan 报告的是建议性的下一个自动轮次，它不授权、不清除操作者门禁、不记录人类奖励、不授权项目 Agent 运行本来被阻塞的工作。

Lifetime Goal 不变体：目标可以活很多年，但每个 Agent 轮次仍然必须穿过当前权限、边界、配额、验证和 writeback 才能算作进展。这叫做"保持连续性而不声称无界自主性"。

适用场景与局限

LoopX 适合的场景包括：多天的工程/研究/基准测试/实验目标、需要保留范围和证据的 issue 和 PR 循环、定期心跳或监控工作、有 owner/安全/发布/私有数据门禁的项目、所有权/租约和交接重要的 peer-agent 团队、以及进展需要对非工程操作者可读的创作者/研究/运维工作流。

它不适合做自主生产控制器。LoopX 当前处于 v0.4.x，定位为早期但可用的本地控制面，不是完整的 Agent 平台、Agent runtime 或自主生产控制器。

下一步的发展方向包括更简单的安装和宿主打包、更广泛的类型化 runtime adapter、跨重复公共循环的更强终端验收、独立采用和结果证据，以及更打磨的管理界面。

来源：GitHub - huangruiteng/loopx