5,085 stars 87 天从零跑出来的新品类：AI Agent 的 ” 长程状态内核 ”，不是另一个 agent framework，是架在 Codex / Claude Code / Cursor 之上的本地控制面。
写在前面
Agent 单轮干一件事不难，难的是把一件跨天、跨人、跨工具的事跑完。
跑过 agent 长任务的人都懂：第 40 轮的时候 agent 已经忘了最初的目标；” 等待 owner 确认 ” 埋在聊天记录里谁也没看见；两个 agent 同时碰一个仓库谁也不清楚谁拥有当前任务；上一轮声称成功了但没有可验证证据；一个心跳调度器在没事可做时仍然在燃烧 token。
问题的本质不是 agent 不够聪明——聊天记忆 + 定时器不是控制系统。它缺 ” 等待批准 ”、” 谁拥有下一步 ”、” 停止花费，因为没有有效状态转移 ” 这些概念。
huangruiteng/loopx（5,085 ⭐ / Apache-2.0 / Python / 2026-05-31 启动 / 8 月平均 1.4 天一个版本 的激进迭代）就是为这件事造的。它不替代 Codex / Claude Code / Cursor，它接管的是 两轮之间那段。
官方一句话定位：Keep the loop moving. Keep the judgment human.
一、它解决什么问题
LoopX = 一个本地控制面 + 一个状态内核。
跑在已有 agent 运行时之上，不替换它们。Codex、Claude Code、Cursor、shell agent 原先怎么跑还怎么跑；LoopX 管的是 agent 之间、轮次之间、跨天跨工具之间的状态。
一个紧凑的状态层保管：
- objective — 当前要完成的目标 + 作用域
- gates — 必须由人来定的关键决策点
- todos — 用户侧的待办 + agent 侧的待办，typed + 可执行
- claims / leases — 谁能认领、占用多长时间
- evidence — 这一轮做了什么、产出物在哪
- quota — 这一轮该不该跑、还剩多少额度
任何 agent 跑完一轮后，LoopX 把这一轮的 ” 证据 + 交接说明 + 下一步 todo” 写回，决定下一轮该醒还是该睡。
基本信息
| 字段 | 值 |
|---|---|
| 项目名 | LoopX |
| 仓库 | huangruiteng/loopx |
| 作者 | Huang Ruiteng（北京，独立开发者） |
| 创建 | 2026-05-31 |
| 最新版 | v0.5.2（2026-08-22） |
| Stars | 5,085 |
| Forks | 442 |
| Open issues | 49 |
| License | Apache-2.0 ✅ |
| 主语言 | Python |
| 运行时 | Python 3.11+ / 标准库外零依赖 |
| 平台 | macOS + Linux + PowerShell 7（无 Windows GUI 路径） |
| 状态 | v0.5.x — 作者自称 ”early but usable” |
| 30 天新增 | +4,919 stars（reporank 2026-08-24 数据） |
| 官网 | huangruiteng.github.io/loopx |
| 用户手册 | 飞书 wiki |
| Discord | discord.gg/XmGgQyCFZd |
二、五大核心状态：一张图讲清整本 README
README 里那段控制面图直接抄过来：
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 跑一个有边界的切片，跑完写回三样东西：证据、交接说明、下一条 todo。
“提出一个具体问题 “ 这条被单独强调过：它要的不是挂一句含糊的 ” 等待负责人 ”，而是问题本身要具体到对方能够直接回答。这个设计看着小，但决定了停下来的那一刻究竟是 有效的求助 ，还是 一次没人知道该怎么处理的阻塞。
心智模型：Agent-Native Kanban
卡片 = 一条工作（identity + authority + evidence + continuation）移动卡片 = 一组经过校验的操作（claim / gate / monitor / writeback）板子本身只是投影，LoopX 状态始终是真相源。这一点官方用 ” 看板投影到飞书 ” 做了明示：loopx lark-kanban 可以把 todo 和 gate 投到飞书上看，但视图永远不是权威。
三、五条 CLI 主循环：这就是 loop engineering 的全部
Loop engineering 整本手册压成 5 行命令：
loopx quota should-run # 这一轮该不该跑？loopx todo claim # 谁认领了这一片？loopx todo update # 这一轮改了什么？loopx refresh-state # 下一轮应该看到什么？loopx quota spend-slot # 一片被验证完成的工作入账
跟普通定时器最大的区别是 quota should-run 这一步：
- 多数 ” 让 agent 自己接着干 ” 的方案靠定时器唤醒，时间一到就跑一轮，至于账上有没有额度、眼下有没有值得推进的事并不关心
- LoopX 把配额纳入控制面，由 quota 决定这一轮应该交付、提问、等待、自我修复、还是干脆 保持沉默
- 额度耗尽时它安静下来，恢复之后自行继续
- 对按量付费或受速率限制的使用者，省下的是那些本来就不会产生任何有效状态转移的空转轮次——这笔开销长周期任务里累积起来并不小
四、Agent-Agnostic 集成矩阵：8 个 host 都支持
LoopX 显式声明 ”agent-agnostic”。不是绑定一个 agent runtime，是架在它们之上。
| Host | 推荐启动 | Loop 驱动方式 |
|---|---|---|
| Codex App | 让 agent 连接项目 → loopx doctor → 报当前 gate 和下一条 todo → $loopx <task> 或 /skills 选 loopx |
Codex App heartbeat automation（quota scheduler_hint 触发） |
| Codex CLI | codex 进项目 → 连接诊断 → $loopx <task> |
可见的 /goal <task_body>，默认无隐藏 headless |
| Claude Code | 安装 opt-in adapter → /loopx <task> + /loop |
原生 /loop 被 LoopX gate |
| OpenCode | 装 static command facade，可选 --with-goal-bridge |
命令 facade + 可选 goal bridge |
| Pi | loopx slash-commands --install --surface pi → /loopx <task> |
Pi goal extension（被 LoopX quota gate） |
| DeepSeek Harness (dsh) | pip install loopx[deepseek-harness] → dsh cordis.yml → loopx turn run-once |
headless dsh segments，每 tick 被 quota should-run gate |
| KunlunCode | loopx-kunluncode connect → 加 bounded todo → loopx-kunluncode run |
原生 Goal Pro 通过 app-server；LoopX 只在严格验证后 写完成和配额 |
| Cursor / shell / 自定义 runner | installer + loopx doctor，shell 或 scheduler 触发 |
你的 shell / scheduler / runner |
注意：KunlunCode 是字节内部代号 / dsh 是国内 DeepSeek Harness，这两个都进了 LoopX 的 first-class 支持列表，说明作者对国内 agent 生态有真实触达。
角色分层：4 个层级互不越界
| 角色 | 职责 |
|---|---|
| Agent | 规划 + 分析 + 调工具 + 跑一个有边界的动作 |
| Provider | 调外部系统 / 本地实现，返回有边界的观察、效果结果、读回 |
| Capability | 定义 caller 期望产出，归一化 provider 输出，验证，提出 typed transition |
| Kernel | 拥有持久 todo / gate / monitor / accepted writeback / quota / recovery / scheduling 全部真相 |
执行流：Agent → Capability → Provider
控制流（回写）：
Provider readback → Capability transition → Kernel
关键点：agent 从不直接写入控制自己的状态——这是整套设计的核心安全护栏。
五、对比：跟 LangChain Agents / AutoGPT / AgentOps 差在哪
| 维度 | LoopX | LangChain Agents | AutoGPT | AgentOps |
|---|---|---|---|---|
| 目标场景 | 长运行 coding agent 团队 | 通用 agent 编排 | 单 agent 自主流程 | 企业 agent 可观测性 |
| 内置 quota 调度 | ✅ | ❌ | ❌ | ✅（付费层） |
| 可验证交接 | ✅ | ❌ | ❌ | ✅（付费层） |
| Coding-agent 无关性 | ✅ Codex/Claude Code/Cursor/OpenCode/DSH/Pi/KunlunCode | ✅ | ❌ | ✅ |
| 开源 | ✅ Apache-2.0 | ✅ MIT | ✅ MIT | ❌ 付费 |
| 本地优先 | ✅（状态在 .loopx/） |
⚠️ | ❌ | ❌ 云依赖 |
| 据称运行时开销 | <1.2% CPU / <40MB RAM / 单实例 128 loop | 取决于 chain | 单 agent | SaaS |
核心判断 ：LoopX 不是 LangChain 的竞品——LangChain 处理 ” 模型怎么调工具、怎么规划、怎么跑 ”，LoopX 处理 ” 跑了几十个小时之后状态还能不能被可靠地延续“。
六、实战：35 分钟把 LoopX 跑起来
6.1 一行安装
PyPI 安装（不需要克隆）：
python3 -m pip install --upgrade loopx
loopx workflow-skills --install
loopx doctor
或一行 curl（早期 0.x 安装方式，新版建议走 pip）：
curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"
loopx doctor
要求：Python 3.11+，运行时 零外部依赖（标准库外不依赖任何包）。
6.2 接到一个项目
cd /path/to/your-project
loopx connect
loopx status
如果项目还没初始化：
loopx start-goal --guided --project . --goal-text " 把 OpenViking 的 issue #156 修完并通过 CI"
状态落在项目里的 .loopx/ 目录。保持 .loopx/ 在 .gitignore，公开 / 私有边界由 LoopX 自己维护。
6.3 跟 Codex App 接通
打开 Codex App 在项目目录，让它执行：
“ 把这个项目接上 LoopX，跑 loopx doctor 确认健康，保留已有状态，告诉我当前 gate 和下一条 agent todo”
Codex App 会自动按 heartbeat automation 节奏（被 quota scheduler_hint 驱动）唤醒下一轮。
6.4 跑一条已就绪的 loop
loopx preset list
loopx preset show daily-triage
loopx ready-score --goal-id <goal-id> --agent-id <agent-id>
预设覆盖了 daily triage / changelog drafts / PR watching 几条高频路径。Auto Research 一键开启 proposer + executor + evaluator/promoter 三角色并行，证据 / 配额 / todo 都在一张图上。
6.5 看一个公开证据：Auto ML Experiment 200+ 小时轨迹
README 里放的不是一轮演示，是 两条跨越 200+ 小时的真实轨迹：
- OpenViking Issue-Fix：作者本人作为 OpenViking 贡献者跑完一段 200+ 小时的公开贡献弧，PR 交付与可复用修复知识同步演进
- Auto ML Experiment：200+ 小时实验弧，假设、匹配的证据、被作废的谱系、正在跑的重复实验、晋级与停止的 gate 全在同一张图上
值得专门说的是 LoopX 对这些数字的处理方式——每次提到 ”200 多小时 ” 后面都跟着一句限定：
这是墙钟意义上的项目时长，不是 200 小时连续的模型执行，也不是在宣称无人值守的生产级自治。
在不少项目倾向于把数字往大了讲的当下，这种主动收窄声称范围的写法并不多见。
6.6 三个独立用户报告
README 还收了三份来自独立用户的实证（不是作者 dogfooding）：
| 用户 | 跑法 | 报告 |
|---|---|---|
| 独立用户 #1 | >13h C++ accuracy run |
跨阶段任务保持对齐 → 触发公开研究 → 接了 codebase-memory-mcp → 提升最终精度 |
| 独立用户 #2 | 4d unattended run |
四天无人值守 + 有用进展 + 周期报告界面 |
| 独立用户 #3 | 7 merged PRs |
在 zilliztech/mfs#166 公开可见，归属与 1B+ token 量级都是用户自报 |
七、风险与坑：8 条提前知道
- v0.5.x 还很早期 — 作者自称 “early but usable”，state + CLI contract 是稳定核心， 但若干 host 集成和高级路径要么可选、要么默认关闭、要么标着实验性。生产锁定建议 v0.5.2+，并锁定 minor 版本。
- 迭代极快，11 天发了 8 个版本 — 从 8/12 的 v0.4.5 到 8/22 的 v0.5.2， 平均 1.4 天一个版本。意味着 changelog 必须看，否则下个版本命令可能改名。
- 证据全部来自作者 + 三份独立用户报告 — 三条作者跑出的轨迹 + 三份独立用户报告；” 独立采纳和结果证据 ” 被列入 下一步里程碑——第三方验证目前还很少。
- 概念数量不少 — objective / gate / todo / claim / lease / capability / evidence / writeback / quota / projection， 装起来容易，要真正用起来得先花时间理解这套模型。轻的是安装，不是心智负担。
- 只支持 macOS / Linux（PowerShell 7） — Windows 原生 GUI 路径不支持。
- 概念开销 vs 收益不总是划算 — 单 session 短任务用 LoopX 是杀鸡用牛刀；只在跨天跨人跨工具时才明显受益。
- 看板 ≠ 真相源 —
loopx lark-kanban投到飞书可以看， 但视图永远不是权威，别用它做最终决策。 - Apache-2.0 ✅ 但要标版权 + 变更说明 — 商用 OK，但改了源码要声明、保留 NOTICE、不能加额外限制。
八、总结
三个 ” 最值得装的理由 ”
- 本地控制面思路对：把 agent 的 ” 长程状态 ” 从聊天记忆里剥出来，做成一个可治理、可交接、可审计的内核——这是 agent 团队从 ” 会用 ” 走到 ” 能用 ” 必须补的一层
- 与已有 agent 兼容：不替换 Codex / Claude Code / Cursor / dsh / Pi / KunlunCode，而是架在它们之上，迁移成本几乎为零
- Apache-2.0 + 5K stars + 8 个版本在 11 天：社区信号明确，反向证明开发者对 ” 持久 agent 状态层 ” 的真实需求
一句 ” 先试一周 ”
挑一个你已经在跑、跨多轮需要 agent 帮忙但总掉链子的真实任务，装上 loopx，跑一遍 loopx status，看 5 字段（objective / gate / todo / evidence / quota）有没有把 ” 现在卡在哪 ” 说清楚——说清楚了，这套东西对你就有用。
数据小观察
- 8 月 5 日 stars 还是 1,979，8 月 24 日已经 5,069，30 天 +4,919 stars，这种增速在没有大 V 推的情况下不常见
- 作者是北京独立开发者，飞书用户手册挂在自家 wiki，Discord + 飞书 + 微信三群运营——典型的国内单人项目全球化打法
- License 是 Apache-2.0 ✅ 不是 MIT，但商用风险基本一致