LoopX
**面向长程 Agent 的开放、有状态、Provider-neutral 控制面。**
LoopX 运行在任何 agent harness 之上，提供长程状态、语义决策、治理、恢复与人机协同；目标、gate、todo、证据、quota 和交接跨轮次保持稳定，有界执行仍由 harness 负责。
**面向长程 Agent 的开放、有状态、Provider-neutral 控制面。**
LoopX 运行在任何 agent harness 之上，提供长程状态、语义决策、治理、恢复与人机协同；目标、gate、todo、证据、quota 和交接跨轮次保持稳定，有界执行仍由 harness 负责。
你可以在一个页面中：
- 看清哪些事项正在等你、执行中、观察中、已安排或已停止；
- 在 Codex、Claude Code、direct-model 等已注册 Agent 会话之间延续工作，
不丢失 Goal 状态与证据；
- 通过 typed preview、显式确认与 receipt 审阅受保护变更；浏览器只负责投影，
LoopX state 始终是权威事实源。
```bash
loopx dashboard
```
`loopx dashboard` 是受支持的浏览器 / PWA 启动方式。若希望使用原生窗口，
可从源码运行实验性 Tauri shell；它复用同一组 loopback status 与 Chat 服务，
不会成为新的状态权威：
```bash
cd apps/desktop/loopx-control-plane
npm install
npm run dev
```
[阅读桌面 shell 指南](apps/desktop/loopx-control-plane/README.md)。关闭窗口时，
shell 只停止由自己启动的服务进程；已有 LoopX 服务与持久化 Goal 状态不会受影响。
[观看 32 秒完整演示](docs/assets/personal-workspace/loopx-dashboard-launch.mp4)
· [阅读工作区指南](docs/guides/personal-workspace-user-guide.md)
· [开始五分钟体验](docs/guides/personal-workspace-trial-guide.md)
## 为什么需要 LoopX
一个 agent 可以在单次会话里完成任务。长程工作更难：目标会变化，用户决策会出现，
证据会过期，平级 agent 会交接，scheduler 也可能在已经没有有效状态迁移时继续消耗。
聊天记忆和定时器不足以治理这些问题。
LoopX 把长期控制状态留在同一层紧凑状态里：
```text
目标 / issue / project
│
▼
LoopX state：objective + gate + todo + scope + evidence + quota
│
├─ 需要人类判断？ ── 是 ─▶ 提出具体问题并等待
│
├─ 有安全侧路？ ─────────▶ 执行一个有界 agent slice
│
▼
Codex / Claude Code / Cursor / shell agent 执行一轮
│
▼
写回证据 + handoff + next todo ─▶ quota 决定下一次 tick
```
Agent runtime 负责执行，LoopX 负责治理跨运行延续的控制状态，让工程、
研究、discovery 和运营 Loop 能持续推进。它不是又一个 agent framework，也不是
绑定某一 Provider 的编排 runtime。
一个形象化理解是：LoopX 是
**[面向长程 Agent 的可执行看板](docs/development/control-plane-course/00-concept-primer.md)**。
卡片带有稳定身份、权限、证据和 continuation；移动卡片要经过 claim、gate、
monitor、validate、writeback 等 typed operator。看板是 projection，LoopX state
才是事实源。
注册 agent 彼此平级。todo claim、lease、任务边界、能力门和 typed continuation
共同决定下一步谁执行，不需要一个长期拥有全局权限的 leader agent。
LoopX 适合：
- 多天或多周的工程、研究、benchmark、实验目标；
- 需要跨轮保留 scope、证据和 review 状态的 issue / PR Loop；
- recurring heartbeat 或 monitor-style agent 工作；
- 带 owner、安全、发布或私有数据 gate 的项目；
- 需要 ownership、lease 和 handoff 的平级 agent team；
- 需要把进展、阻塞和反馈入口清晰呈现给非技术用户的创作、研究或运营工作。
LoopX 不是生产自动化控制器。危险权限、生产写入、公开发布和最终 ownership
仍由人类负责。
## 证据
这些不是单轮 demo。OpenViking 的公开贡献序列与经过脱敏的 owner-run Auto ML
showcase 各自跨越 **200+ 小时自然时长**，持续保留多轮 todo、决策和证据更新。
这里的自然时长是项目从启动到最新证据的 wall-clock 时间。
不等于 200 小时连续模型执行，也不代表无人值守的生产自治。点击原图可以检查
public-safe graph、
证据分支和跨轮决策。
### 开源 Issue Fix
**超过 200 小时的公开贡献轨迹：Focused PR 交付与可复用修复知识互相反哺。**
LoopX 的创建者以
[OpenViking contributor](https://github.com/volcengine/OpenViking/pulls?q=is%3Apr+author%3Ahuangruiteng)
身份把这条路径用于持续的 issue-to-PR 修复。图中公开贡献序列从首个 PR 创建到
最后一次所示 review 或 update，跨越 200+ 小时。
[Issue-Fix 能力说明](loopx/capabilities/issue_fix/README.zh-CN.md)把 rolling
repository context、带 revision 的修复知识和 reviewer-facing preference
分开管理；所链接 PR 与当前 checkout 的源码、测试始终具有最高权威。
### Auto ML Experiment
**经过脱敏的 owner-run showcase：超过 200 小时的实验轨迹把假设、matched
evidence、无效谱系、运行中复现和 promote / stop gate 留在同一张图中。**
这张 public-safe graph 保留了该 200+ 小时自然时间窗口中的决策谱系。它是
owner-run showcase，不代表连续算力执行、独立复现、生产结果，也不代表公司或
雇主背书；脱敏后的图片本身不足以让第三方独立复现实验。
### Auto Research
**可复现的公开 KNN demo：Proposer、executor、evaluator/promoter 并行迭代，
todo、quota、证据与 targeted wake 同屏可见。**
这张截图来自 LoopX 内置的 exact-KNN demo。公开 task、可编辑与受保护文件、
deterministic CPU evaluator、dev / held-out 命令均在仓库内。可按
[showcase walkthrough](docs/product/use-cases/auto-research/decentralized-auto-research-showcase.md)
或 [demo 命令路径](demo/auto_research/README.md)复现工作流；它是 demo
结果，不是生产研究结论。
### 真实项目中的使用
- **外部独立用户 · `>13h` C++ 精度修复。** 用户报告多阶段任务持续对齐目标，
触发 public research 后采用[公开代码记忆工具](https://github.com/DeusData/codebase-memory-mcp)，
最终精度明显提升。[查看证据边界](docs/showcases/cases/independent-cpp-accuracy-long-run.md)。
- **外部独立用户 · `4d` 无人干预运行。** 用户报告 Agent 连续四天无需人工
干预，持续处理有价值的工作，并提供周期报告入口。
[查看脱敏案例](docs/showcases/cases/independent-four-day-unattended-agent.md)。
- **外部独立用户 · `7` 个合并 PR。** 一次归因于 LoopX 的 Engine 重构可由
[公开 Issue](https://github.com/zilliztech/mfs/issues/166)和七个合并 PR 检查；
LoopX 归因与用户报告的 `10 亿+` token 规模仍按用户自述标记。
[检查完整案例](docs/showcases/cases/independent-public-engine-refactor.md)。
这里长期只维护当前最强的三个案例，不复制全量清单。完整的 contributor case、
creator dogfooding、reproducible demo 和证据强度标签见
[Showcase 全量目录](docs/showcases/README.md)。
更多可检查入口：
- [产品首页](https://huangruiteng.github.io/loopx/)：查看产品叙事、快速开始和长程证据；
- [Showcase 全量目录](docs/showcases/README.md)和
[中英双语托管索引](docs/showcases/index.html)；
- [跨 runtime 实现审阅演示](docs/product/use-cases/cross-runtime/cross-runtime-impl-review-demo.md)；
- 公开[用户手册](https://my.feishu.cn/wiki/CaL5wMk9ui17ngkWzeUcMlAYnZg)。
## 试用 LoopX
要求：Python 3.11+。使用 console scripts 已加入 `PATH` 的 Python 环境；macOS
和 Linux 使用 POSIX shell，原生 Windows 使用 PowerShell 7。普通用户不需要
Git，package 除标准库外没有 runtime 依赖。
无需 clone，直接从 PyPI 安装：
```bash
python3 -m pip install --upgrade loopx
loopx workflow-skills --install
loopx doctor
```
已有安装可使用 `loopx update plan` 与 `loopx update apply`；LoopX 会保留检测到
的 pip、pipx 或 archive owner，不会在升级时暗中切换安装渠道。
原生 Windows PowerShell 7 可直接使用同一 PyPI release，不需要 POSIX 兼容层：
```powershell
py -3.11 -m pip install --upgrade loopx
loopx workflow-skills --install
loopx doctor
```
首次安装后重启 Agent host，使其重新加载 workflow skills。`pipx`、host command
surfaces、原生 Windows checkout 安装、升级、回滚、卸载与 archive fallback 见
[Installing LoopX](docs/guides/installing-loopx.md)。
然后在项目根目录连接：
```bash
cd /path/to/your-project
loopx connect
loopx status
```
如果项目尚未初始化，且 `connect` 明确提示缺少状态，可以走 guided path：
```bash
loopx start-goal --guided --project . --goal-text "你的长程目标"
```
已有 LoopX state 应复用，不要覆盖。确保 `.loopx/`、`.codex/goals/`、`.local/`
不会被提交。
### 从你已经在用的 Agent 启动
| Host | 推荐入口 | Loop driver |
| --- | --- | --- |
| Codex App | 让 agent 在当前项目里连接 LoopX、运行 `loopx doctor`、保留已有状态，并汇报当前 gate 和下一条 todo；然后用 `$loopx <复杂任务>` 或 `/skills` 里的 `loopx`。 | Codex App heartbeat；cadence 跟随 `quota should-run.scheduler_hint` |
| Codex App over SSH | `loopx agent-onboard --agent-type codex-app-ssh --project .` | 返回的可见 `/goal
飞书：扫码直接加入
微信：huangrt00 · 好友申请备注 LoopX
由仓库授权的 workflow 每 6 小时基于 GitHub 官方 stargazer 时间戳生成；仅当拉取条数与 GitHub 当前 Star 总数一致时发布。GitHub 图片缓存可能延迟刷新。