loopx-project/loopx

LoopX – 长周期 AI 代理人的状态化控制平面

是什么 – LoopX 是一个开源、与提供方无关的“控制平面”，位于现有 LLM 代理运行时（Codex、Claude Code、Cursor 等）之上。它存储多轮、多日工作流的持久状态——目标、关卡、待办事项、证据、配额和交接，并决定下一个应由哪个代理执行。简而言之，它将一系列孤立的代理调用转变为可审查、可重启、有人类参与的循环。

为何重要 – 现代 LLM 代理在完成单个任务方面表现出色，但长期项目（研究实验、多日工程、持续监控）需要：

• 可在重启后保持的持久上下文
• 明确的人类审批点
• 安全的回退机制和配额限制
• 清晰的审计轨迹（做了什么、为什么、依据什么证据） LoopX 在不替换底层代理框架的前提下提供了这些能力。

核心概念

概念	作用
目标 / 目的	循环的高层次目标（例如：“训练一个模型两周”）
关卡	必须经由人类或策略驱动的检查点审批后才能进入下一阶段
待办事项	代理可领取并执行的有界工作项
证据	每轮生成的文件、日志或工件，以不可变方式存储，供后续审查
配额	限制可运行的轮次数量，防止失控执行
交接	责任结构化地转移给另一个代理或人类

如何工作 – 循环流程如下：

目标 → LoopX 状态（目标、关卡、待办事项、证据、配额）
   ├─ 若需人类判断 → 提出具体问题，等待
   ├─ 否则若存在安全回退 → 执行有界代理片段
   ▼
代理运行时（Codex、Claude Code 等）执行一轮
   ▼
LoopX 记录证据，更新状态，决定下一轮

状态存储在本地（“本地优先”工作区），是唯一真相源；代理运行时仅作为工作者存在。

主要功能

• 个人工作区 – 本地优先的 UI（浏览器/PWA 或原生桌面），可在重启后持续显示目标、待办任务、日程和证据。
• 提供方无关适配器 – 支持 Codex App、Claude Code、Cursor、KunlunCode、DeepSeek Harness 和通用 shell 运行器的插件。
• 人机协同审批 – 明确的审批步骤、类型化预览和状态变更前的收据。
• 跨运行时连续性 – 项目中途可从 Codex 切换到 Claude Code 而不丢失状态。
• 审计就绪的证据图 – 每轮输出版本化并可视化为任务图。
• 可扩展的技能/命令面 – 可在各种 IDE 和聊天平台中通过 /loopx 命令暴露 LoopX。
• 基准测试与案例研究 – SWE-Marathon、LHTB、自动机器学习、开源问题修复演示，展示超过 200 小时的循环。

技术栈

• 核心 – 控制平面服务器使用 TypeScript（Effect 运行时）；Python 3.11+ 客户端库和 CLI。
• 存储 – 基于本地文件系统的“本地优先”存储（.loopx/ 目录）。
• UI – 浏览器端仪表板（PWA）及可选的 macOS/Windows 原生桌面构建。
• 打包 – 通过 PyPI（pip install loopx）和 npm（TypeScript 核心）分发。

典型用例

• 需要定期人类审查的多日研究或工程实验。
• 必须保留上下文、证据和决策链的缺陷修复或 PR 工作流。
• 持续运行数周的监控或心跳任务。
• 所有权、租约和交接明确的代理团队。
• 任何长期自动化任务，其中人类操作员必须对关键操作保持控制。

快速上手

# 安装 Python 包（包含 CLI 和 TypeScript 运行时）
python3 -m pip install --upgrade loopx
# 安装内置工作流技能（代理、适配器等）
loopx workflow-skills --install
# 验证安装
loopx doctor

# 将项目连接到 LoopX
cd /path/to/your/project
loopx connect   # 若缺失则创建 .loopx/ 状态
loopx status    # 显示当前目标、关卡、待办事项

# 启动新长期目标（引导式向导）
loopx start-goal --guided --project . --goal-text "训练一个情感模型 10 天"

之后可通过 loopx dashboard 启动仪表板，或通过提供的适配器（如 codex、claude、cursor）运行代理。

成熟度 – 仓库已发布 1.0 版本，提供桌面预览和不断增长的集成。文档包括双语开发者手册、详细指南和展示目录。项目积极维护（Discord 社区、定期发布），并标记为“loop agents active”。

了解更多

• 网站 / 文档 – https://loopx-project.github.io/loopx/
• 开发者手册 – https://loopx-project.github.io/loopx/docs/book/en/
• Discord – https://discord.gg/XmGgQyCFZd
• 基准测试与案例研究 – 请参阅 README 的“Evidence”部分。

---

以上所有信息均直接取自仓库的 README，未添加任何外部推测。