loopx

面向长时运行 AI agent 团队的轻量级循环状态内核，跨 Codex、Claude Code 等运行时统一管理目标、门禁、待办、证据和配额，让多轮 agent 工作可复盘、可交接、可续跑。亮点是 agent 无关且本地优先，提供持续目标、配额感知自动唤醒、可验证交接等机制，适合多日工程、研究和监控类任务。仍处于早期阶段，非自主生产控制器，危险权限和最终决策需由人掌控。

README

LoopX

面向长期运行 AI agent（智能体）工作的本地控制平面。

在 Codex、Claude Code、Cursor 或你自己的 runtime（运行时）执行有界回合（bounded turns）时，保持目标、门禁（gates）、待办、证据、配额和交接（handoffs）稳定不变。

Public website（公开网站） · Docs（文档） · Try LoopX（试用 LoopX） · See real loops（查看真实循环） · How it works（工作原理） · User manual（用户手册） · 简体中文

把会干活的 Agent，接成可管理、可复盘、可持续改进的数字员工。

一个轻量级状态内核与 agent 无关的本地控制平面，用于循环工程（loop engineering）。LoopX 让长期运行的工作可审查、可重启，并更容易在回合、工具和 agent 之间交接。它不会取代你的 agent runtime。

面向长期运行 AI agent 与对等 agent 团队的循环工程（Loop engineering）。

保持循环运转。保持判断由人掌握。

为什么选择 LoopX

一个 agent 可以在单次会话中完成一项任务。长期运行的工作则困难得多：目标会变化、需要所有者决策、证据会过期、agent 会把工作交接给同伴，而且调度器在没有有效转换可做时仍可能继续消耗资源。仅靠聊天记忆和定时器不足以治理这种情况。

LoopX 将持久化控制状态保存在一个紧凑的层中：

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

LoopX 控制平面看板

一个有用的心智模型是 面向长期运行工作的 agent 原生看板。卡片携带身份、权限、证据和续接信息。移动是经过验证的运算符（operator），例如 claim、gate、monitor 和 writeback。看板只是一个投影；LoopX 状态始终是事实来源。

已注册的 agent 是对等节点。claim、lease（租约）、任务边界、能力和类型化续接（typed continuation）决定下一步由谁行动；不需要持久的领导者身份。

LoopX 在以下场景中很有用：

多天的工程、研究、基准测试或实验目标；
必须保留范围、证据和审查状态的 issue 与 PR 循环；
周期性 heartbeat（心跳）或监控工作；
带有所有者、安全、发布或私有数据门禁的项目；
所有权、租约和交接很重要的对等 agent 团队；
进度必须对非工程运维人员保持可读的创作者、研究或运营工作流。

LoopX 不是自主生产控制器。危险权限、发布、生产写入和最终所有权始终由人类掌握。

实证

这些不是单回合演示。OpenViking Issue-Fix 和 Auto ML 轨迹各覆盖 200+ 小时的累计循环生命周期，横跨许多有界回合、决策和证据更新。累计生命周期是墙钟项目时间，不是 200 小时的连续模型执行，也不是无人值守生产自主性的声明。打开每个可视化以检查公开安全图、证据分支和跨回合保留的决策。

开源 Issue 修复

200+ 小时公开贡献弧线：PR 交付与可复用修复知识共同演进。

LoopX 的创建者以 OpenViking 贡献者的身份使用这条路径。所呈现的公开贡献序列从首个 PR 创建到最新呈现的审查或更新，跨越 200 多个累计小时。Issue-Fix 能力将持续滚动的仓库上下文、带修订标记的修复知识和面向评审者的偏好分开保存；关联的 PR 加上当前 checkout 源码和测试仍是权威来源。

Auto ML 实验

200+ 小时所有者运行实验弧线：假设、匹配证据、无效谱系、运行中的重复实验以及 promote/stop 门禁在同一张图中可见。

这份脱敏的公开安全图保留了跨越 200+ 累计小时的决策谱系。它是轨迹证据，不代表连续计算、独立复现或生产结果的声明。

Auto Research

提案者、执行者和评估/晋升 agent 并行迭代，同时待办、配额、证据和定向唤醒保持可见。

更多可检查的界面：

公开主页：产品叙事、快速上手和长期运行证据；
展示目录，包括阻塞 P0 安全轮换、 LoopX 自迭代和动态工作流编排；
跨 runtime 实现审查演示；
公开用户手册。

试用 LoopX

要求：Python 3.11+、curl、tar，以及 macOS 或 Linux shell。Git 仅用于贡献者克隆/canary 工作流。Python 包除标准库外没有 runtime 依赖。

无需克隆即可安装：

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

然后从你的项目根目录连接：

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

如果项目尚未初始化且 connect 提示状态缺失，请使用引导路径：

loopx start-goal --guided --project . --goal-text "Your long-running objective"

LoopX 应复用现有状态而非覆盖它。请将 .loopx/、.codex/goals/ 和 .local/ 保持为忽略状态。

从你的 Agent 开始

宿主	推荐启动方式	循环驱动
Codex App	让 agent 将此项目连接到 LoopX，运行 `loopx doctor`，保留现有状态，并报告当前门禁和下一个待办。然后使用 `$loopx <复杂任务>` 或从 `/skills` 选择 `loopx`。	Codex App heartbeat 自动化，从 `quota should-run.scheduler_hint` 刷新
Codex App over SSH	`loopx agent-onboard --agent-type codex-app-ssh --project .`	返回的可见 `/goal <task_body>`
Codex CLI	在项目中启动 `codex`，让它连接并诊断 LoopX，然后使用 `$loopx <复杂任务>` 或 `/skills`。	可见的 `/goal <task_body>`；默认无隐藏 headless 执行
Claude Code	安装 opt-in 适配器，然后运行 `/loopx <任务>`，再运行 `/loop`。	原生 Claude Code `/loop`，由 LoopX 门禁控制
OpenCode	安装静态命令门面；选择 `--with-goal-bridge` 以启用周期性目标。	OpenCode 命令门面和显式 goal bridge（目标桥）
Cursor、shell 或自定义 runner	使用安装器和 `loopx doctor`；手动连接或从你的 runner 调用 LoopX。	你的 shell、调度器或 runner

精确的、可复制粘贴的安装消息和宿主恢复路径见 Getting Started（入门指南）。宿主集成的细节可查看 Codex App 宿主命令注册表契约、 Codex CLI 打包安装路径或 Claude Code 适配器。

对于自定义 runner，请阅读 Embed LoopX in Your Agent Runner（将 LoopX 嵌入你的 Agent Runner）和 worker bridge 安装契约。核心 tick（心跳节拍）刻意保持小巧：

loopx quota should-run      # should this registered agent act now?
loopx todo claim            # who owns this slice?
loopx todo update           # what changed?
loopx refresh-state         # what should the next turn see?
loopx quota spend-slot      # account for a completed, validated slice

成功的连接应满足：

loopx doctor 通过；
存在 .loopx/registry.json 和投影出的活动目标状态；
loopx status 显示当前目标、具体用户门禁和下一个 agent 待办；
有可见的循环驱动或精确的激活指令；
本地 runtime 状态被忽略而非提交。

基于克隆的安装仅适用于想要实时 canary 包装器的贡献者：

git clone https://github.com/huangruiteng/loopx ~/loopx
~/loopx/scripts/install-local.sh
loopx doctor

能力

LoopX 将其控制平面机制归结为五个问题：

问题	LoopX 保持可见的内容
目标是什么？	活动目标、明确范围和当前权限。
接下来发生什么？	有序的用户和 agent 待办、所有权、claim 和 lease。
什么需要人类判断？	具体的用户门禁，而非模糊的"等待所有者"。
哪些证据发生了变化？	紧凑的运行历史、验证、阻塞项和已接受的 writeback（回写）。
循环可以继续吗？	配额、能力、安全回退（safe fallback）、调度器提示和停止条件。

控制平面表面

表面	功能	从何处开始
目标状态与状态查看	跟踪活动状态、待办、claim、门禁、证据、运行历史和首屏关注点。	`loopx status`、`loopx diagnose`、`loopx review-packet`
配额与交互契约	决定一个回合应该交付、询问、等待、自我修复还是保持安静。	`loopx quota should-run`、配额分配
Agent runtime 桥接	让 Codex App、Codex CLI、Claude Code 和通用 worker 与同一个守卫保持对齐。	`loopx heartbeat-prompt`、`loopx codex-cli-bootstrap-message`、`loopx worker-bridge`
运维表面	渲染紧凑状态，而无需让浏览器成为状态权威。	`loopx serve-status`、仪表盘
外部投影	将待办和门禁投影到协作表面，同时 LoopX 保持权威性。	`loopx lark-kanban`、Lark Kanban 适配器
领域能力	打包可重复的工作通道，如 issue 修复、内容运营、价值连接器规划、ML 实验建议、基准证据和 Explore。	`loopx issue-fix`、`loopx content-ops`、`loopx value-connectors`、`loopx ml-experiment`、`loopx benchmark`、Explore
实验性上下文学习	让命名注册 agent 通过忽略的、默认关闭的项目配置试用 provider 无关的 Reward Memory（奖励记忆）。OpenViking 只是一个 provider 选项，而非全局依赖。	`loopx reward-memory experiment-status`、Reward Memory 架构
治理模式	捕获可复用的路由、门禁、证据、投影和规划形状。	交互模式、状态模型

开箱即用的原语包括：生命周期目标、具体用户门禁、可审计的安全回退、对等 todo 所有权、配额与引导、紧凑运行历史、基于证据的交接、只读优先的管理表面、项目级价值信号，以及公共/私有边界检查。

Runtime 职责

角色	职责
Agent	规划、分析、使用工具，并通过宿主/runtime 执行一个有界动作。
Provider	调用外部系统并返回观察结果、效果结果和回读。
Capability	定义调用方结果、规范化 provider 输出、验证它，并提出类型化转换。
Kernel	拥有持久化待办、门禁、监控器、已接受 writeback、配额、恢复和调度。

执行路径是 Agent -> Capability -> Provider；控制路径返回 Provider readback -> Capability transition -> Kernel。扩展是可选的 provider 被打包和管理的方式，而不是另一个控制平面所有者。参见 Architecture（架构）和 Extensions and Capabilities（扩展与能力）。

高级路径

第一个有用的循环并不需要所有可选表面。仅在工作需要时才添加这些能力。

在启用高级路径之前，先检查当前目标只读能力目录：

loopx configure-goal --goal-id <goal-id>

不带 --execute 时，它只报告当前/默认状态、适配度、边界和可复制命令，不会更改项目状态。

预设与 Auto Research

安全预设涵盖日常分诊、changelog 草稿和 PR 监控。一条命令的研究路径协调提案者、执行者和评估/晋升者角色，同时保持配额和证据可见。参见初学者预设指南和 Auto Research 命令路径。

loopx preset list
loopx preset show daily-triage

预设检查是只读的。对于已连接的周期性目标， loopx ready-score --goal-id <goal-id> --agent-id <agent-id> 报告循环是否可重复运行。

受治理的回合

LoopX 可以从经过验证的回执、新的配额状态和 provider 无关的预算生成一个纯粹的、有界的回合决策。当前的 Codex CLI 快速入门和激活契约记录在 LoopX Turn for Codex CLI 中。

Explore 图与 Harnes

Explore 是受支持的、可选的、默认关闭的。当任务具有可测量的离线评估、基线、处理和护栏时，它效果最佳；它不能替代生产审批。从 Explore 能力及其 Lark 展示映射开始。

审查 Agent 工作

使用 loopx review-packet 获得面向所有者的紧凑视图，涵盖决策、证据、验证和未解决的门禁。智能管理表面描述了运维模型；项目级奖励模型描述了跨输出数量、质量、token 成本和用户注意力成本的保守价值信号。

关于一个具体的对等工作流，参见跨 runtime 实现审查演示： Claude 实现而 Codex 审查，同时 LoopX 保持所有权、证据、配额和交接的明确性。

应用与投影路径

本地只读优先 UI：仪表盘指南
公开产品概览：公开主页
文档门户：托管文档
飞书/Lark 投影：Lark Kanban 适配器
通用宿主集成：集成指南
自定义多 agent runner：自定义 runner 集成

可选的投影让状态更易检查；它们不会成为事实来源。

运维与恢复

日常检查从以下命令开始：

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

自动回合必须首先检查配额，并且只在验证 writeback 之后追加花费。静默跳过、预检失败和 dry-run 预览不花费配额。当用户门禁阻塞某一条通道时，单独审计过的安全回退可以继续，但不得绕过门禁。

对等 agent 在交付前使用 loopx todo claim，验证后使用 loopx todo update，以便所有权和证据保持可见。

调度器节奏遵循 quota should-run.scheduler_hint；已安装的 Codex App 自动化通过返回的 ack_hint.cli_args 确认当前提示。冲突恢复、监控语义、自我修复和确切的运维命令维护在 Getting Started、 Quota Allocation 和 Long-Task Cadence Policy 中。

在发布公开文档或示例之前：

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

高级文档

从与你角色匹配的路径开始。已发布的文档站点请使用托管的文档门户；文档索引始终是完整的源映射。

使用与运维

Getting Started（入门指南）：安装、连接、诊断、日常工作流、heartbeat、仪表盘、开发和命令。
User Manual（用户手册）：公开上手、概念、FAQ 和精选案例。
Showcase Catalog（展示目录）：公开安全案例与证据标签。
Update Notes（更新说明）：公开安全进度说明。
Release Readiness（发布就绪）：安装/更新路径、兼容性门禁、发布说明和可安全依赖的表面。
Dashboard（仪表盘）和 Status Data Contract（状态数据契约）。

理解控制平面

Architecture（架构）：生命周期目标不变量和内核。
State Interaction Model（状态交互模型）：actor、存储、交互契约和 writeback。
Interaction Pattern Catalog（交互模式目录）：可复用的路由、门禁、证据、投影和规划模式。
Loop Engineering Principles and Pitfalls（循环工程原则与陷阱）以及中文版。
Control-Plane Developer Course（控制平面开发者课程）：九节中文代码驱动的课程。
Product Vision（产品愿景）：更广泛的 Loop Agent 方向。

集成与扩展

验证与治理

社区与反馈

LoopX 仍在早期阶段。最有用的反馈来自真实的长期运行 agent 项目：控制平面在哪里帮到了你，在哪里显得笨重，以及哪些门禁或交接从视野中消失了。

使用 GitHub Issues 提交可复现的 bug、安装问题和功能请求。
为文档修复、展示案例和公开安全的小示例开启 PR。
中文用户和贡献者可以加入 Lark 开发者群。要加入微信群，请添加 huangrt00 并在好友请求中注明 LoopX。

Lark 开发者群

微信：huangrt00
提及 LoopX 以获取入群邀请

LoopX 标志
LoopX 项目标识

贡献

外部贡献者应从 Contributor Tasks（贡献者任务）开始，了解公开、可认领的工作；并从 Contributing（贡献指南）了解设置、验证和边界规则。项目角色和公开历史记录在 Governance（治理）、 Authors and Contributors（作者与贡献者）和 Project History（项目历史）中。

LoopX 将本地活动状态与公开仓库分开。请勿提交 .loopx/、.codex/goals/、实时的 ACTIVE_GOAL_STATE.md、原始基准追踪、凭据、私有日志或运维工件。

当前状态

v0.4.x 系列是一个早期但可用的本地控制平面，面向长期运行的 agent 工作。它不是完整的 agent 平台、agent runtime 或自主生产控制器。

今天 LoopX 提供：面向目标、类型化待办和决策范围的持久化状态内核、对等 claim 和 lease、证据与 writeback、配额感知调度，以及跨回合续接。引导启动、周期性 heartbeat、隔离的 Codex CLI 回合、基于证据的 Issue-Fix 准入、可选的 Explore 和 auto research 路径、公开验证 canary，以及只读优先的多项目仪表盘，都构建在这一共享控制状态之上。

支持级别保持明确。状态和 CLI 契约是稳定核心；多个宿主集成和高级路径是可选的、默认关闭的或实验性的。LoopX 不授予凭据、不批准破坏性或生产操作、不在未经授权的情况下代表用户发布内容，也不会将未经验证的运行变成成功证据。

接下来的里程碑是：更简单的安装和宿主打包、更广泛的类型化 runtime 适配器、跨重复公开循环更强的终端验收、独立采用与结果证据，以及更完善的管理表面。

许可证

MIT。参见 LICENSE。

开源项目huangruiteng2026-08-05原文

打开互动版