LoopX

项目定位

LoopX 是一个开源、运行时中立、有状态的控制平面，专为长周期运行的 Agent 工作设计。它并不替代执行任务的 Agent 运行时（如 Codex、Claude Code、Cursor 或自建运行器），而是在它们之上维护一层紧凑、可复盘、可交接的控制状态。

核心理念是「Loop Engineering」：在多日工程、Issue 修复、Auto ML 实验、Auto Research、周期性心跳等长任务中，让目标、门控、待办、证据、配额和交接稳定地跨轮次、跨工具、跨 Agent 延续下去。

为什么需要 LoopX

单个会话内完成任务相对简单，但长任务会面临：目标变动、Owner 决策介入、证据过期、Agent 之间的交接、以及「无有效进展却仍在消耗调度资源」等情形。聊天记忆加定时器远远不足以治理这些问题。

LoopX 将控制状态收拢到一层精简内核中：

objective / issue / project
   │
   ▼
LoopX state: objective + gates + todos + scope + evidence + quota
   │
   ├─ human judgment needed? ── yes ─▶ 抛出具体问题并等待
   │
   ├─ safe fallback available? ──────▶ 执行一段受控的 Agent 切片
   │
   ▼
Codex / Claude Code / Cursor / shell agent 执行一轮
   │
   ▼
写入证据 + 交接 + 下一条 todo ─▶ 配额决定下一拍

一个有效的心理模型是「面向长任务的 Agent-Native 看板」：卡片承载身份、权限、证据与延续；移动操作是经过校验的算子（claim、gate、monitor、writeback）；看板只是投影，LoopX 状态才是事实源。注册 Agent 之间是平级关系，通过 claim、lease、能力、类型化延续来决定谁行动，不需要持久化的 leader 身份。

典型适用场景

• 多日工程、研究、基准、实验类目标；
• 需要保留范围、证据、审查状态的 Issue / PR 循环；
• 周期性心跳或监控任务；
• 存在 Owner、安全、发布、隐私数据门控的项目；
• 关注所有权、租约、交接的多 Agent 团队；
• 需要让非工程运营方也能看清进度的内容、研究、运营工作流。

LoopX 不是自主的生产控制器。危险权限、发布、生产写入、最终所有权保留给人。

安装与启动

环境要求：Python 3.11+、curl、tar、macOS 或 Linux Shell。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

若项目未初始化，可走引导式流程：

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

应保留既有状态，忽略 .loopx/、.codex/goals/、.local/。

宿主运行器接入

宿主	推荐方式	循环驱动
Codex App	让 Agent 连接项目、执行 loopx doctor、保留状态、上报当前 gate 与下一条 todo，再用 $loopx <task>	由 quota should-run.scheduler_hint 驱动的心跳自动化
Codex CLI	在项目中启动 codex，让其连接并诊断，再使用 $loopx <task> 或 /skills	可见的 /goal 指令，默认无隐藏 headless 执行
Claude Code	安装可选适配器，使用 /loopx <task> 后接 /loop	由 LoopX 守门的原生 /loop
OpenCode	安装静态命令外观，可选 --with-goal-bridge 接入周期目标	命令外观 + 显式 goal bridge
Pi	安装 goal 扩展后使用 /loopx <task>	由 LoopX 配额守门的 Pi goal 扩展

核心 CLI 循环

自定义运行器只需五步即可接入：

loopx quota should-run      # 当前已注册 Agent 是否应行动？
loopx todo claim            # 谁拥有这段切片？
loopx todo update           # 发生了什么变化？
loopx refresh-state         # 下一轮应看到什么？
loopx quota spend-slot      # 为已完成且校验通过的切片记账

控制平面能力面

能力面	作用	入门命令
目标状态	跟踪活跃状态、todo、claim、gate、证据、运行历史	loopx status、loopx diagnose、loopx review-packet
配额与交互契约	决定本轮是交付、提问、等待、自愈还是静默	loopx quota should-run
运行器桥接	让 Codex App / CLI、Claude Code 与通用 worker 共享同一守门	loopx heartbeat-prompt、loopx worker-bridge
运营面	渲染紧凑状态，浏览器不成为状态权威	loopx serve-status
外部投影	把 todo 和 gate 投到协作面板	loopx lark-kanban
领域能力	Issue-Fix、Content-Ops、Value-Connectors、ML-Experiment、Benchmark、Explore	loopx issue-fix 等
实验性上下文学习	默认关闭的 provider 中立 Reward Memory	loopx reward-memory experiment-status

角色职责

角色	职责
Agent	规划、分析、调用工具、执行一段受控动作
Provider	调用外部系统、返回观测与读回
Capability	描述调用方期望、规范化 Provider 输出、校验并提出类型化跃迁
Kernel	持有持久 todo、gate、monitor、accepted writeback、配额、恢复、调度

执行路径是 Agent → Capability → Provider；控制路径是 Provider readback → Capability transition → Kernel。可选 Provider 是被打包和管理的扩展，不是另一个控制平面。

高级路径

启用前可只读检查当前目标的能力目录：

loopx configure-goal --goal-id <goal-id>    # 不加 --execute 时为只读

常用能力包括：每日 triage、changelog 草稿、PR 跟踪等安全预设；Auto Research（proposer、executor、evaluator/promoter 协同）；Explore 图表与 Harness（默认关闭，需有可量化的离线评估）；loopx review-packet 生成面向 Owner 的复盘包。

运维与恢复

日常巡检：

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

自动轮次必须先查配额，仅在校验通过的 writeback 之后才追加 spend；静默跳过、preflight 失败、dry-run 预览不消耗配额。当用户 gate 阻塞某条通道时，单独审计过的安全 fallback 可继续，但不得绕过 gate。

发布公共文档或示例前可执行 loopx check 对 README、docs、examples 做边界扫描。

当前状态

v0.4.x 已可用，作为长任务 Agent 的本地控制平面，并正在扩大采用面。它不是完整 Agent 平台、Agent 运行时或自主生产控制器。状态与 CLI 契约是稳定核心；多项宿主集成与高级路径仍为可选、默认关闭或实验性。LoopX 不授予凭证、不批准破坏性或生产动作、不在未授权时代表用户发布、也不会把未经核实的运行当作成功证据。