📦 LoopX 详细部署教程

LoopX 是一个开源的、面向长期任务 (Long-Horizon) 的 AI 代理控制平面。它不取代 Codex、Claude Code 等代理运行环境，而是在其之上提供一层有状态的治理层，用于管理目标、任务清单、决策门禁、证据和配额，使得跨天、跨会话的复杂工作能够被清晰地追踪、恢复和交接。它就像一个“代理原生看板”，让长期工作保持可控和可审查。

⚙️ 部署前准备

LoopX 是一个 Python 命令行工具，通过 PyPI 安装。根据你的操作系统，需要满足以下环境要求：

  • Python 版本：Python 3.11 或更高版本。确保 pip (或 pipx) 可用。
  • Node.js 版本：Node.js 22.6 或更高版本。LoopX 内部会调用一个轻量的 TypeScript 核心，它会自动启动。
  • 操作系统：macOS、Linux 或 Windows (推荐使用 PowerShell 7)。
  • （可选）Git：仅当你想从源码运行或参与开发时需要。

🚀 安装 LoopX

1. 通过 PyPI 安装 (推荐)

这是最标准、最推荐的安装方式，适合所有用户。

1
python3 -m pip install --upgrade loopx

提示：如果你希望隔离环境，也可以使用 pipx install loopx。

2. 安装核心工作流技能

安装完主程序后，需要安装其自带的技能集，这些技能定义了长期任务的工作流模式 (如 Issue 修复、内容运营等)。

1
loopx workflow-skills --install

3. 运行健康检查

验证所有组件是否正确安装并可用。

1
loopx doctor

这一步会检查 Python、Node.js 环境以及必要的依赖是否就绪。

Windows 用户 (PowerShell 7)：使用相同命令即可：

1
2
3
py -3.11 -m pip install --upgrade loopx
loopx workflow-skills --install
loopx doctor

4. 重启你的 AI 代理主机

安装完成后，请重启你正在使用的 AI 代理 (如 Codex App、Claude Code 等)，以便它们能加载新安装的 loopx 工作流技能。

🔗 连接到你的项目

LoopX 是项目级 (project-level) 的，你需要在你想要管理的项目根目录下进行操作。

1. 进入项目并连接

1
2
cd /path/to/your-project
loopx connect

connect 命令会初始化当前项目，创建必要的状态目录 (如 .loopx/)。

2. 启动一个长期目标 (Goal)

如果项目还没有活跃的目标，使用引导式命令创建一个：

1
loopx start-goal --guided --project . --goal-text "你的长期任务目标描述"

例如：

1
loopx start-goal --guided --project . --goal-text "为本项目实现用户认证功能，并修复已知的登录问题"

LoopX 会引导你设置目标、初始任务和必要的门禁。

3. 查看当前状态

随时查看项目的目标、任务进度、门禁和证据状态。

1
loopx status

🤖 从你的 AI 代理中调用 LoopX

LoopX 的设计是与你的 AI 代理协作，而不是取代它。你需要在代理的会话中，通过特定的命令或技能来调用 LoopX 的控制能力。

对于 Codex (CLI)

在你的 Codex 会话中，使用 $loopx 前缀来引用任务：

1
$loopx 请根据当前项目的目标和下一个待办任务，完成相应的代码修改

或使用 /skills 菜单选择 loopx 技能。

对于 Claude Code

  1. 安装可选的适配器。
  2. 在会话中运行 /loopx <任务描述>，然后运行 /loop 让 LoopX 驱动 Claude Code 执行一个被治理的轮次。

对于 DeepSeek Harness (dsh)

安装原生 DSH 插件，然后在会话中选择 loopx 技能即可。

通用方式：从任何 Shell 或自定义运行器

LoopX 的核心是一组显式的控制命令，你可以从任何脚本或运行器中调用：

1
2
3
4
5
loopx quota should-run      # 检查当前代理是否被允许执行
loopx todo claim            # 认领下一个待办任务
loopx todo update           # 更新任务状态和产出证据
loopx refresh-state         # 刷新代理需要看到的上下文
loopx quota spend-slot      # 在完成一个验证过的轮次后，消耗一个配额槽

🖥️ 使用仪表板 (Dashboard)

LoopX 提供了一个轻量级的本地 Web 界面，用于可视化地查看所有项目、目标和任务的状态。

1
loopx dashboard

它会启动一个浏览器窗口，显示一个只读的、自动刷新的看板。注意：LoopX 的本地状态文件始终是权威数据源，仪表板只是其投影。

📂 数据存储位置

所有 LoopX 的状态文件都存储在项目根目录下的 .loopx/ 文件夹中。请务必将此目录添加到你的 .gitignore 中，避免将本地状态文件提交到版本控制系统。

❓ 常见问题

  • Q: loopx doctor 检查失败，提示 Node.js 版本过低？
    • A: LoopX 需要 Node.js 22.6 或更高版本。请使用 nvm 或官方安装包升级。
  • Q: 如何更新 LoopX 到最新版本？
    • A: 运行 loopx update plan 查看更新计划，然后运行 loopx update apply 执行更新。你也可以直接使用 pip install --upgrade loopx。
  • Q: 如何在现有项目中恢复一个之前的目标？
    • A: 只要 .loopx/ 目录存在且包含目标状态，loopx connect 会自动识别并恢复。使用 loopx status 确认。
  • Q: LoopX 适合短期的、单次的任务吗？
    • A: 不完全是。LoopX 的设计初衷是管理跨越多轮、需要持续治理的长期任务。对于一次性任务，直接使用你的 AI 代理可能更轻量。
  • Q: 我在 Windows 上遇到了路径或执行问题？
    • A: 请确保使用 PowerShell 7 (pwsh)，而不是旧版 cmd。如果问题依旧，可以尝试在 WSL 2 (Linux 子系统) 中运行。

更详细的操作指南、高级工作流（如自动研究模式、基准测试）、完整命令参考和开发贡献指南，请查阅 LoopX 官方文档。