Luvus AI 智能体控制中心部署教程

Luvus 是一个为 AI 编程智能体设计的“任务控制中心”，提供了一个终端用户界面（TUI），用于管理多个 AI 编程助手（如 Claude Code、Codex、Grok 等）的工作空间、会话、文件和协作流程。

本教程将指导您完成 Luvus 的安装、配置和基本使用。

1. 项目概览与核心价值

Luvus 的核心价值在于为开发者提供一个统一的、持久化的终端界面来管理和编排各种 AI 编程智能体，解决在多工具、多项目间切换的碎片化问题。

核心功能

  • 持久化工作区 (Persistent Workspaces)：后台守护进程保持终端标签页、窗格、布局和会话状态，关闭后重新打开一切如故。
  • 全面的窗格与标签控制：支持鼠标、键盘快捷键或命令行进行分割、调整大小、移动、重命名、聚焦、运行和关闭操作。
  • 智能体感知 (Agent Awareness)：自动检测支持的智能体（如 Claude Code, GitHub Copilot CLI, Codex 等），并显示其运行状态（阻塞、工作中、完成、空闲）、会话标题、Token 和成本估算。
  • 智能体工作流 (Agent Workflows)：启动、命名、发送消息、检查状态、等待或恢复智能体任务。支持复刻（Fork）现有会话及其上下文。
  • 文件与代码管理：内置 Git 感知的文件树，可浏览、检查、打开和预览文件。
  • Git 与 GitHub 集成：查看仓库状态、分支、提交、PR、Issue 等，无需离开 Luvus。
  • 工作树与编排 (Worktrees & Orchestration)：创建 Git 工作树、协调依赖任务、预留文件路径、分配智能体、计划定时任务和运行质量门禁。
  • 远程与多客户端：可通过 SSH 连接，支持多个客户端独立视口。
  • 可扩展性：通过模块（Modules）安装扩展功能，支持自定义主题。

2. 环境准备

2.1 基础要求

  • 操作系统：macOS、Linux 或 Windows。
  • Git：Luvus 依赖 Git 进行仓库操作，请确保已安装并配置。
  • （可选）GitHub CLI：如需深度 GitHub 集成，建议安装 gh。

2.2 安装 Luvus

您可以根据操作系统选择以下任一方式安装。

方式一：官方安装脚本 (macOS 和 Linux)

1
curl -fsSL https://luvus.dev/install.sh | sh

方式二：Homebrew (macOS 和 Linux)

1
brew install RizRiyz/luvus/luvus

方式三：Windows PowerShell

1
irm https://luvus.dev/install.ps1 | iex

2.3 验证与诊断

安装完成后，运行以下命令检查环境是否就绪：

1
2
3
4
5
# 检查核心依赖 (git, gh, ssh 等) 和配置
luvus doctor

# 检查并安装可用更新
luvus update

3. 快速启动与基本使用

3.1 启动 Luvus

在终端中直接输入 luvus 并回车，即可启动或重新连接到您的 Luvus 会话。

1
luvus

首次启动时，Luvus 会引导您进行基本设置。

3.2 核心操作概念

  • 工作区 (Workspace)：一个项目目录。您可以在工作区内打开、重命名、固定和切换项目。
  • 窗格 (Pane) 和标签 (Tab)：Luvus 的界面布局。您可以在一个标签内分割多个窗格，每个窗格可以运行终端、智能体或查看文件。
  • 智能体 (Agent)：Luvus 会自动检测在 PATH 中或项目本地安装的支持的 AI 编程助手。您可以在窗格中启动一个智能体，并与它交互。

3.3 启动一个智能体

  1. 在 Luvus 界面中，使用快捷键（通常是 Ctrl+Space 或 Cmd+Space）打开命令面板。
  2. 输入或选择 “Start Agent”。
  3. 从列表中选择您想使用的智能体（如 claude, codex）。
  4. Luvus 会在当前或新窗格中启动该智能体，并自动检测其状态。

3.4 关键快捷键 (macOS 可能需要调整)

  • 命令面板：Ctrl+Space (macOS 用户需在系统设置中释放此快捷键)。
  • 切换工作区：Ctrl+w。
  • 聚焦下一个/上一个窗格：Ctrl+[ / Ctrl+]。
  • 垂直/水平分割窗格：Ctrl+Shift+v / Ctrl+Shift+h。
  • 关闭窗格：Ctrl+Shift+c。
  • 完整的快捷键列表可在 Luvus 内按 Ctrl+? 查看。

4. 配置与定制

4.1 配置文件

Luvus 的配置文件通常位于 ~/.config/luvus/config.toml (Linux/macOS) 或 %APPDATA%\luvus\config.toml (Windows)。您可以在其中自定义：

  • 键盘快捷键：重新映射快捷键或修改前缀键。
  • 主题：选择内置主题或安装社区主题。
  • 智能体设置：为特定智能体设置环境变量或默认参数。
  • 界面布局：调整侧边栏位置、大小等。

4.2 安装主题与模块

  • 主题：可在社区仓库找到，或自行创建。通常通过将主题文件放入 ~/.config/luvus/themes/ 目录并修改配置文件来启用。
  • 模块 (Modules)：用于扩展 Luvus 功能。可通过 luvus module install <module-name> 命令安装。

5. 高级功能：工作树与任务编排

Luvus 的一个强大特性是支持 Git 工作树，并能基于此进行复杂的任务编排。

  1. 创建工作树：在 Luvus 中，您可以为当前仓库创建一个新的工作树，用于并行开发不同功能或修复。
  2. 分配任务：您可以将一个工作树与一个智能体关联，并分配具体任务（如 “重构这个模块”）。
  3. 依赖与调度：您可以定义任务之间的依赖关系，或为任务设置时间表（如 “每天凌晨 2 点运行测试”）。
  4. 质量门禁：在任务完成后，Luvus 可以运行预定义的检查（如 linter、测试套件），只有通过门禁的任务才能被合并。

6. 常见问题与排查

问题 可能原因与解决方案
luvus 命令未找到 安装目录未加入 PATH。找到二进制文件位置（如 /usr/local/bin），并添加到您的 Shell 配置文件中。
快捷键 Ctrl+Space 无效 (macOS) macOS 系统默认占用该快捷键用于切换输入法。请前往 系统设置 → 键盘 → 键盘快捷键 → 输入源，禁用或更改”选择上一个输入源”的快捷键。
无法检测到智能体 确保智能体（如 Claude Code, Codex）已正确安装且其可执行文件在系统 PATH 中。您可以在 Luvus 启动后，在新的终端窗格中运行 which <agent> 来验证。
SSH 远程连接时界面显示异常 可能是终端类型或字符编码问题。尝试在远程机器上设置 export TERM=xterm-256color，或检查 Luvus 的 doctor 命令输出。
性能缓慢或卡顿 大型项目或长时间运行可能导致资源占用。尝试关闭不使用的窗格或工作区。检查 luvus doctor 是否有环境警告。

通过以上步骤，您已成功部署并可以使用 Luvus 来管理您的 AI 编程智能体。其强大的持久化会话和编排能力，将能显著提升您在多智能体、多项目管理场景下的工作效率。