开源项目第204期：LoopX — 长周期 Agent 控制平面，跑在 Codex/Claude Code 之上的状态管理层

引言

"Keep the loop moving. Keep the judgment human."

这是「每日一个开源项目」系列的第 204 篇 。今天的项目是 LoopX ------ 长周期 Agent 控制平面，5,288 颗 Star，Apache-2.0，作者 huangruiteng（黄睿腾）。

LoopX 解决一个单 session 解决不了的问题：Agent 能在一次对话里完成一个任务，但跨天、跨周的长期工作怎么办？ 目标变了，证据过时了，需要人工决策的节点出现了，Agent 和 Agent 之间要交接工作......聊天记忆和一个定时器根本不够管理这些。

LoopX 的定位不是 Agent 框架，而是运行在已有 Agent harness（Codex App / Claude Code / OpenCode 等）之上的控制平面：它持有持久化状态，决定"下一步做什么、是否该继续、需要人来判断什么"，而 Agent harness 负责在边界内执行具体的一跳工作。

你会学到什么

LoopX 的核心概念：Goal / Gate / Todo / Evidence / Quota 各自的职责
控制平面的五个核心问题（Five Questions 框架）
与九种 Agent harness 的集成方式
支持的能力路径（Issue Fix / Explore / Auto Research 等）
快速上手：安装、连接项目、启动 loop

前提知识

使用过 Claude Code、Codex 或类似 AI 编程 Agent
了解长周期工作管理的基本概念（目标、任务分解、Review 流程）
Python 基础使用经验

项目背景

概述

LoopX 的核心比喻是：Agent 原生的看板（Kanban）。

普通看板管的是人的任务。LoopX 的"卡片"携带的是：身份（谁拥有这个任务）、权限（谁能认领）、证据（完成了什么）、续接（下一步的上下文）。"移动卡片"不是点按钮，而是经过验证的算子操作（claim、gate、monitor、writeback）。看板是一个投影视图，LoopX 的状态才是真正的事实来源。

项目信息

作者: huangruiteng（黄睿腾）
主要语言: Python 3.11+
许可证: Apache-2.0（v0.4.8 起；更早版本为 MIT）
官网 : huangruiteng.github.io/loopx
用户手册 : 飞书 Wiki

项目数据

⭐ GitHub Stars: 5,288+
🍴 Forks: 476+
📄 许可证: Apache-2.0
📅 创建时间: 2026-05-31

核心概念

LoopX 把控制平面的职责压缩成五个问题：

问题	LoopX 维护的状态
目标是什么？	活跃 Goal、明确的 Scope、当前的权限
下一步做什么？	有序的用户和 Agent Todo、所有权、认领状态
什么需要人来判断？	具体的用户 Gate（不是模糊的"等待确认"）
证据发生了什么变化？	紧凑的运行历史、验证结果、阻塞项、已接受的 writeback
loop 可以继续吗？	配额（Quota）、能力状态、安全回退路径、调度提示

这五个问题对应五个产品承诺：长周期状态 / 语义决策 / 人机协作 / 可恢复性 / 治理。

控制平面的层次

sql 复制代码

objective / issue / project
   │
   ▼
LoopX state: objective + gates + todos + scope + evidence + quota
   │
   ├─ 需要人工判断？── 是 ──▶ 提出具体问题并等待
   │
   ├─ 有安全回退？──────────▶ 运行一个边界内的 Agent slice
   │
   ▼
Codex / Claude Code / Cursor / shell agent 执行一跳（one turn）
   │
   ▼
写入证据 + 交接状态 + 下一个 todo ──▶ Quota 决定下一次调度

Agent harness 执行具体工作；LoopX 管理让长期工作跨运行可续接的状态。

四个层次的职责分离

层次	职责
Kernel（内核）	持有持久化的 Goal、Todo、Gate、Evidence、Quota、Recovery、Scheduling
Capability（能力）	定义一个稳定、提供商中立的合约，产出一个有边界、可验证的调用结果
Provider（提供商）	调用外部系统或本地实现，返回有边界的观察结果和 readback
Extension（扩展）	打包和管理一个可选 Provider，有完整的安装/升级/回滚生命周期

执行路径是 Agent → Capability → Provider；控制路径返回 Provider readback → Capability transition → Kernel。

快速上手

安装

bash 复制代码

# 需要 Python 3.11+
python3 -m pip install --upgrade loopx
loopx workflow-skills --install
loopx doctor

macOS/Linux 用 POSIX shell，Windows 用 PowerShell 7（不需要兼容层）。

连接项目

bash 复制代码

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

首次使用，通过引导流程启动第一个 Goal：

bash 复制代码

loopx start-goal --guided --project . --goal-text "你的长期目标"

核心 loop 的五步调用

任意自定义 runner 都通过这五步调用：

bash 复制代码

loopx quota should-run    # 这个 Agent 现在该行动吗？
loopx todo claim          # 认领本次工作切片
loopx todo update         # 记录变更
loopx refresh-state       # 给下一跳准备上下文
loopx quota spend-slot    # 消耗一个经验证的配额 slot

与九种 Agent Harness 集成

Agent Harness	推荐接入方式
Codex App	让 Agent 执行 `loopx connect`，然后用 `$loopx <task>` 或 `/skills` 触发
Codex App（SSH）	`loopx agent-onboard --agent-type codex-app-ssh`
Codex CLI	`codex` 内联接入后用 `$loopx <task>` 或 `/skills`
Claude Code	安装适配器，然后 `/loopx <task>` + `/loop`
KunlunCode	`loopx-kunluncode connect` + 原生 Goal Pro
OpenCode	安装静态命令 facade，可选 `--with-goal-bridge`
Pi	`loopx slash-commands --install --surface pi`，然后 `/loopx <task>`
ZCode	`loopx slash-commands --install --surface zcode`
DeepSeek Harness (dsh)	`loopx[deepseek-harness]` + `loopx turn run-once`
Cursor / shell / 自定义	手动 `loopx connect` + 在 runner 里调用 LoopX

所有集成共享同一个控制平面状态，切换 harness 不丢失 Goal 状态。

能力路径（Capabilities）

LoopX 把通用控制平面原语包装成有具体产出的"能力路径"：

你需要...	能力	命令
把公开 issue 变成有证据支撑的可审 PR	Issue Fix	`loopx issue-fix`
在交付前验证最终 diff 的质量	Change Quality	`loopx capability show change-quality-qualification`
在不确定的研究中保持假设和发现可见	Explore	`loopx capability show explore`
基于当前证据重新校准决策	Decision Context	`loopx capability show decision-context`
定期生成带收据的进度报告	Periodic Report	`loopx capability show periodic-report`

查看所有已安装能力：

bash 复制代码

loopx capability list --format json

Auto Research：多 Agent 并行研究

LoopX 内置了一个 KNN 演示，展示 proposer / executor / evaluator 三角色多 Agent 并行工作：

bash 复制代码

# 查看预设
loopx preset list
loopx preset show daily-triage

# 查看 Auto Research 演示
# demo/auto_research/README.md

有据可查的长期运行案例

LoopX 强调：这不是一次性 demo。

OpenViking 开源贡献弧（200+ 小时）

作者本人用 LoopX 管理对 OpenViking 仓库的贡献序列，跨越 200+ 小时的经过时间（不是连续计算时长），Issue Fix 能力持续维护 rolling 的仓库上下文、修订标记的修复知识、面向 reviewer 的偏好。

Auto ML 实验（200+ 小时）

脱敏的所有者运行展示：在 200+ 小时跨度内保持假设、匹配证据、无效谱系、运行中副本和推进/停止关卡在一个图里可见。

社区独立用户案例：

一位用户：13h+ C++ 精度提升任务，保持多阶段对齐，触发公开研究，最终精度提升
一位用户：4 天无人值守运行，持续有效工作，带定期报告
一位用户：7 个已合并 PR，Engine 重构，1B+ token 规模（用户报告）

仪表板与可视化

bash 复制代码

# 启动本地 dashboard（PWA 模式）
loopx dashboard

也可以构建实验性的 Tauri 桌面窗口：

bash 复制代码

cd apps/desktop/loopx-control-plane
npm install
npm run dev

Session dash 追踪多 Goal 的进度：

bash 复制代码

loopx dash

状态检查：

bash 复制代码

loopx status
loopx history --goal-id your-project-goal
loopx quota should-run --goal-id your-project-goal
loopx diagnose
loopx review-packet      # 紧凑的 owner 视角：决策、证据、关卡

参考资源

🌟 GitHub : huangruiteng/loopx
📦 PyPI : loopx
🌐 官网 : huangruiteng.github.io/loopx
📖 用户手册（飞书） : CaL5wMk9ui17ngkWzeUcMlAYnZg
📚 Developer Book（双语） : 中文 · English
💬 Discord : discord.gg/XmGgQyCFZd

总结

LoopX 代表了一个关于 Agent 工程的清醒判断：Agent 的问题不只是"一跳里能不能做到"，而是"跨越多天、多次运行、多个 harness 之后，你还能知道工作进展到哪了、下一步该谁做什么"。

三点值得注意：

"控制平面"而非"Agent 框架"是一个刻意的定位。 LoopX 不执行工作，它管理状态------这和 Kubernetes 是"容器编排平面"而不是"容器运行时"是同样的设计思路。这意味着你可以换 Agent（今天用 Codex，明天用 Claude Code），Goal 状态不丢，历史证据不丢。

五个问题框架是可操作的设计。 很多系统说"支持长周期 Agent"，但"长周期"的意义很模糊。LoopX 把它拆成五个具体问题：目标/下一步/人工判断节点/证据变化/是否继续。每个问题对应一段代码，对应一个 CLI 命令，对应一个可验证的合约。

不做的事情也是设计选择。 LoopX 明确声明：不是自主生产控制器，不为用户授予凭据，不批准破坏性操作，不在未验证的情况下把一次运行标记为成功。在 Agent 能力边界不清晰的今天，这种明确的自我限定本身就是工程诚实的体现。

如果你有跨天运行的 AI Agent 工作------机器学习实验、大型代码重构、持续的开源贡献------LoopX 提供了目前最完整的开源控制平面方案。

探索 PrimeSkills ------ 精选 AI agent 和技能工具，每一个都经过真实工作流验证。没有炒作，只有真正好用的工具。

访问我的个人主页，获取更多见解和有趣的产品。