LoopX

面向长期运行代理的开放、提供商中立、有状态控制平面。

_{在 Codex、Claude Code、Cursor 或你自己的运行时执行有界回合时，保持目标、门控、待办事项、证据、配额和交接稳定。}

公共网站 · 文档 · 开发者手册 · 尝试 LoopX · 查看真实循环 · 工作原理 · 用户手册 · 简体中文

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

开放且提供商中立，LoopX 是一个轻量级状态内核和本地优先的控制平面，用于循环工程。它使长期运行的工作可审查、可重启，并更容易在回合、工具和代理之间交接，而无需替换执行工作的运行时。

面向长期运行 AI 代理和同级代理团队的循环工程。

保持循环运转。保持判断力在人手中。

了解 LoopX

开发者手册 - 从控制平面基础到项目入门和开发者贡献的精选双语路径。中文版 · English
快速入门 - 安装、连接项目，并运行你的第一个受治理循环。指南
文档 - 完整参考和操作站点。LoopX 文档

为什么选择 LoopX

一个代理可以在一次会话中完成任务。长期运行的工作更难：目标会变化、所有者决策出现、证据变得过时、代理将工作交给同级、调度器在没有有用过渡时继续消耗。聊天记忆和定时器不足以治理这些。

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

目标 / 问题 / 项目
   │
   ▼
LoopX 状态：目标 + 门控 + 待办事项 + 范围 + 证据 + 配额
   │
   ├─ 需要人工判断？── 是 ──▶ 提出具体问题并等待
   │
   ├─ 有安全回退？──────────▶ 运行一个有界代理切片
   │
   ▼
Codex / Claude Code / Cursor / shell 代理执行一个回合
   │
   ▼
写入证据 + 交接 + 下一个待办事项 ──▶ 配额决定下一个节拍

代理运行时执行工作。LoopX 治理状态，使工程、研究、发现和操作循环能够在多次运行中继续。它不是另一个代理框架，也不是特定于提供者的编排运行时。

LoopX 控制平面面板

一个有用的心智模型是用于长期运行的代理原生看板。卡片携带身份、权限、证据和延续。移动是经过验证的运算符，如 claim、gate、monitor 和 writeback。看板是一个投影；LoopX 状态仍然是事实来源。

注册代理是同级。Claims、leases、任务边界、能力和类型化延续决定谁下一步行动；不需要持久领导者身份。

当您运行时，LoopX 很有用：

多日工程、研究、基准或实验目标；
必须保留范围、证据和审查状态的 issue 和 PR 循环；
定期心跳或监控工作；
具有所有者、安全、发布或私有数据门控的项目；
同级代理团队，其中所有权、租约和交接很重要；
创建者、研究或操作工作流，其进展必须对非工程操作者保持可读。

LoopX 不是自主生产控制器。危险权限、发布、生产写入和最终所有权保留在人类手中。

证据

这些不是单回合演示。公共 OpenViking 贡献序列和经过编辑的、所有者运行的 Auto ML 展示均跨越超过 200 小时的循环生命周期，跨越许多有界回合、决策和证据更新。生命周期是墙钟项目时间。它不是 200 小时的连续模型执行，也不是无人值守生产自主性的声明。打开每个可视化以检查跨回合保留的公共安全图、证据分支和决策。

开源 Issue 修复

超过 200 小时的公共贡献弧：PR 交付和可重用修复知识共同演进。

LoopX 的创建者作为 OpenViking 贡献者使用此路径。所代表的公共贡献序列从其第一个 PR 创建到最新代表的审查或更新，跨越超过 200 个经过的时间。Issue-Fix 能力将滚动的仓库上下文、修订标记的修复知识和面向审查者的偏好分开；链接的 PR 加上当前 checkout 源和测试仍然是权威的。

Auto ML 实验

经过编辑的所有者运行展示：超过 200 小时的实验弧使假设、匹配证据、无效血统、运行中的重复和提升/停止门控在一个图中可见。

经过编辑的公共安全图保留了该 200+ 小时窗口内的决策血统。它是所有者运行的展示，不是连续计算、独立复现、生产结果或公司/雇主认可的声明。编辑图像不足以独立复现底层实验。

Auto Research

可复现的公共 KNN 演示：提议者、执行者和评估者/提升者代理并行迭代，同时待办事项、配额、证据和定向唤醒保持可见。

此截图来自 LoopX 的内置精确 KNN 演示。公共任务、可编辑和保护文件、确定性 CPU 评估器以及 dev/held-out 命令都位于此仓库中。按照展示演练或命令路径复现工作流；它是演示结果，不是生产研究声明。

用于真实项目

独立用户 · >13h C++ 精度运行。 用户报告多阶段任务保持对齐，触发公共研究，采用了公共代码记忆工具，并提高了最终精度。阅读证据边界。
独立用户 · 4d 无人值守运行。 用户报告四天无人干预、有用的持续工作和定期报告界面。阅读编辑后的案例。
独立用户 · 7 个合并 PR。 一个 LoopX 归因的 Engine 重构在公共 issue 和七个合并 PR 中可见；归因和报告的 1B+ token 规模仍然是用户报告。检查案例。

这些是当前最强的三个案例，不是完整清单。浏览完整 Showcase 目录了解贡献者案例、创建者自用、可复现演示和明确的证据强度标签。

更多可检查表面：

公共主页用于产品叙述、快速入门和长期运行证据；
完整 Showcase 目录及其双语托管索引；
跨运行时实现审查演示；
公共用户手册。

尝试 LoopX

要求：Python 3.11+、curl、tar 和 macOS 或 Linux shell。Git 仅用于贡献者克隆/canary 工作流。Python 包在标准库之外没有运行时依赖。

无需克隆安装：

curl -fsSL https://huangruiteng.github.io/loopx/install.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/ 被忽略。

从你的代理开始

宿主	推荐开始	循环驱动
Codex App	让代理将此项目连接到 LoopX，运行 `loopx doctor`，保留现有状态，并报告当前门控和下一个待办事项。然后使用 `$loopx <复杂任务>` 或从 `/skills` 选择 `loopx`。	Codex App 心跳自动化，从 `quota should-run.scheduler_hint` 刷新
Codex App over SSH	`loopx agent-onboard --agent-type codex-app-ssh --project .`	返回的可见 `/goal <任务体>`
Codex CLI	在项目中启动 `codex`，让它连接并诊断 LoopX，然后使用 `$loopx <复杂任务>` 或 `/skills`。	可见 `/goal <任务体>`；默认无隐藏无头执行
Claude Code	安装可选适配器，然后运行 `/loopx <任务>`，接着 `/loop`。	本机 Claude Code `/loop` 由 LoopX 门控
OpenCode	安装静态命令门面；为重复目标选择 `--with-goal-bridge`。	OpenCode 命令门面和显式目标桥
Pi	使用 `loopx slash-commands --install --surface pi` 安装可选目标扩展，然后从受信任的 Pi 会话中使用 `/loopx <任务>`。	可见 Pi 目标扩展由 LoopX 配额门控（`loopx_goal_activate` + `agent_settled` 延续）
Cursor、shell 或自定义运行器	使用安装程序和 `loopx doctor`；手动连接或从你的运行器调用 LoopX。	你的 shell、调度器或运行器

精确的、可复制的设置消息和宿主恢复路径位于快速入门。宿主集成可以检查 Codex App 宿主命令注册表契约、Codex CLI 打包安装路径或 Claude Code 适配器。

对于自定义运行器，从最小自定义运行时示例（python3 examples/custom-runtime-minimal-cli-turn-smoke.py）开始，然后完整的在您的代理运行器中嵌入 LoopX 指南和 worker 桥安装契约。核心 tick 特意很小：

loopx quota should-run      # 这个注册代理现在应该行动吗？
loopx todo claim            # 谁拥有这个切片？
loopx todo update           # 什么改变了？
loopx refresh-state         # 下一个回合应该看到什么？
loopx quota spend-slot      # 为完成、验证的切片记账

首次运行反馈

如果 LoopX 对您有效，一分钟的公共 issue 帮助我们了解真实首次运行的样子。它是可选的，不包含遥测，不应包含日志、路径、凭据、内部项目名称或目标内容：

loopx first-run-report 在本地打印相同的预填链接，不发送任何内容。

成功连接具有：

loopx doctor 通过；
.loopx/registry.json 和投影的活动目标状态；
loopx status 显示当前目标、具体用户门控和下一个代理待办事项；
可见的循环驱动器或精确的激活指令；
本地运行时状态被忽略而不是提交。

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

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

能力

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

问题	LoopX 保持可见的内容
目标是什么？	活动目标、显式范围和当前权限。
接下来发生什么？	有序的用户和代理待办事项、所有权、claims 和 leases。
什么需要人工判断？	具体的用户门控，而不是模糊的“等待所有者”。
什么证据改变了？	紧凑的运行历史、验证、阻塞器和接受的 writeback。
循环可以继续吗？	配额、能力、安全回退、调度器提示和停止条件。

控制平面表面

表面	它做什么	从何处开始
目标和状态	跟踪活动状态、待办事项、claims、门控、证据、运行历史和首屏关注。	`loopx status`、`loopx diagnose`、`loopx review-packet`
配额和交互契约	决定一个回合是否应交付、询问、等待、自我修复或保持安静。	`loopx quota should-run`、配额分配
代理运行时桥	保持 Codex App、Codex CLI、Claude Code 和通用 workers 与同一守卫对齐。	`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
实验性上下文学习	让命名注册代理通过忽略的、默认关闭的项目配置试用提供商中立的 Reward Memory。OpenViking 是一个提供商选项，不是全局依赖。	`loopx reward-memory experiment-status`、Reward Memory 架构
治理模式	捕获可重用的路由、门控、证据、投影和规划形状。	交互模式、状态模型

内置原语包括生命周期目标、具体用户门控、审计的安全回退、同级待办所有权、配额和转向、紧凑运行历史、证据支持的交接、读优先管理表面、项目级价值信号以及公共/私有边界检查。

运行时职责

角色	职责
代理	规划、分析、使用工具，并通过宿主/运行时执行一个有界动作。
提供商	调用外部系统并返回观察、效果结果和回读。
能力	定义调用者结果、规范化提供商输出、验证它并提出类型化过渡。
内核	拥有持久待办事项、门控、监视器、接受的 writeback、配额、恢复和调度。

执行路径是 代理 -> 能力 -> 提供商；控制路径返回 提供商回读 -> 能力过渡 -> 内核。扩展是可选提供商如何打包和管理，而不是另一个控制平面所有者。参见架构和扩展和能力。

高级路径

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

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

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

没有 --execute，这报告当前/默认状态、适合性、边界和可复制命令，而不改变项目状态。

预设和 Auto Research

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

loopx preset list
loopx preset show daily-triage

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

受治理回合

LoopX 可以从经验证的收据、新鲜配额状态和提供商中立预算生成一个纯有界回合决策。当前 Codex CLI 快速入门和激活契约记录在 LoopX Turn for Codex CLI 中。

Explore 图和 Harness

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

审查代理工作

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

对于一个具体的同级工作流，参见跨运行时实现审查演示：Claude 实现，Codex 审查，而 LoopX 保持所有权、证据、配额和交接显式。

应用和投影路径

本地读优先 UI：仪表板指南
公共产品概述：公共主页
文档门户：托管文档
飞书/Lark 投影：Lark Kanban 适配器
通用宿主集成：集成指南
自定义多代理运行器：最小自定义运行时示例，然后自定义运行器集成

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

操作和恢复

从每日检查开始：

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

自动回合必须首先检查配额，并且仅在验证 writeback 后追加花费。安静跳过、预检失败和干运行预览不花费。当用户门控阻止一个通道时，单独审计的安全回退可能继续，但不得绕过门控。

同级代理在交付前使用 loopx todo claim，在验证后使用 loopx todo update，以便所有权和证据保持可见。

调度器节奏遵循 quota should-run.scheduler_hint；安装的 Codex App 自动化通过返回的 ack_hint.cli_args 确认当前提示。冲突恢复、监视器语义、自我修复和精确操作者命令维护在快速入门、配额分配和长任务节奏策略中。

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

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

高级文档

从匹配您当前任务的路径开始。使用托管的文档门户获取已发布文档站点；文档索引保持为完整源映射。此列表保持选择性；每个类别索引拥有其更深的文档和版本化协议。

使用和操作

快速入门：安装、连接、诊断、日常工作流、心跳、仪表板、开发和命令。
用户手册：公共入门、概念、FAQ 和精选案例。
操作：目标延续、待办事项、节奏、注意力和权限工作流。
配额分配和心跳自动化提示：调度器资格、花费和计划延续。
仪表板和状态数据契约：面向操作者的状态和投影契约。
发布就绪性：安装/更新路径、兼容性门控、发布说明和可安全依赖的表面。

理解控制平面

架构：生命周期目标不变量和内核。
状态交互模型：参与者、存储、交互契约和 writeback。
概念：可重用的路由、门控、证据、投影和规划模式。
产品基础：循环工程原则、项目级奖励和奖励风格重新规划。
产品愿景：更广泛的循环代理方向。

集成和扩展

集成指南
最小自定义运行时示例
自定义代理运行器集成
集成：运行时、宿主、协作和外部系统适配器，包括 worker 桥和 Lark。
扩展和能力

构建和审查 LoopX

开发者指南：贡献者工作流、基准开发、文档布局和质量门控。
参考和协议：稳定契约和版本化实现协议，包括宿主命令和奖励记忆架构。
控制平面开发者课程：九场中文、代码主导的讲座。
测试和质量：验证层和基于风险的检查。
公共/私有边界：安全夹具、示例、证据和发布。

检查结果

Showcase 目录：公共安全案例和证据标签。
研究和证据：基准调查和源支持发现。
更新说明：公共安全进度说明。

项目和社区

合作伙伴项目

LoopX 欢迎与其他开源项目合作，构建长期运行的代理生态系统。我们的确认合作伙伴包括：

OpenViking - AI 代理的自进化上下文数据库
NoKV - AI 原生分布式文件系统

社区和反馈

LoopX 仍处于早期。最有用的反馈来自真实的长期运行代理项目：控制平面在哪里有帮助，哪里感觉沉重，以及哪些门控或交接从视野中消失。

使用 GitHub Issues 处理可复现的错误、安装问题和功能请求。
为文档修复、展示写作和小型公共安全示例打开 PR。
加入 Discord 社区，或使用下面的 Lark 或微信。

参见支持了解渠道路由和服务边界，以及通信了解官方发布来源。

_{Lark：扫码直接加入
微信：huangrt00 · 好友请求中提及 LoopX}

贡献

外部贡献者应从贡献者任务开始处理公共、可认领的工作，以及贡献了解设置、验证和边界规则。项目角色和公共历史记录在治理、作者和贡献者以及项目历史中。

LoopX 保持本地活动状态与公共仓库分离。不要提交 .loopx/、.codex/goals/、实时 ACTIVE_GOAL_STATE.md、原始基准跟踪、凭据、私有日志或操作者工件。

当前状态

v0.4.x 系列是用于长期运行代理工作的早期但可用的本地控制平面。它不是完整的代理平台、代理运行时或自主生产控制器。

今天 LoopX 提供持久状态内核，用于目标、类型化待办事项和决策范围、同级 claims 和 leases、证据和 writeback、配额感知调度以及跨回合延续。引导开始、循环心跳、隔离的 Codex CLI 回合、证据支持的 Issue-Fix 准入、可选的 Explore 和自动研究路径、公共验证 canaries 和读优先多项目仪表板构建在该共享控制状态之上。

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

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

Star 历史

_{每六小时使用仓库授权的工作流从 GitHub 官方 stargazer 时间戳生成。仅当获取的行匹配 GitHub 当前 star 计数时才发布快照；GitHub 的图像缓存可能延迟刷新。}

许可证

MIT。参见 LICENSE。