> ## Documentation Index
> Fetch the complete documentation index at: https://vibex.peatboy.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Vibex TUI

> 在终端里使用同一个 Vibex 运行时：会话、审批、队列、设置与配对。

Vibex TUI 是一个字符网格客户端，和桌面端、移动端属于同一类：它渲染权威运行时发来的投影，发送类型化操作，不直接打开数据库、浏览器或媒体栈。它适合 SSH、tmux、服务器和不想离开终端的场景。

TUI 随每个桌面安装包一起发布：

| 平台 | 入口 |
| - | - |
| Linux | `.deb` / AppImage 里的 `/usr/bin/vibex` |
| macOS | `.app` 旁边的 `vibex`，安装器会链接到 `PATH` |
| Windows | NSIS 安装的 `vibex.exe` |
| 容器 | `docker exec -it <container> vibex-server tui` |

## 启动

```bash theme={null}
cd /path/to/your/project
vibex
```

它会附着到该 home 对应的运行时；没有运行时在跑时，会自己启动一个。常用命令：

| 命令 | 作用 |
| - | - |
| `vibex` | 附着到（或启动）当前 home 的运行时。 |
| `vibex connect vibex://…` | 配对远程运行时并附着。 |
| `vibex status` | 只报告 home、模式、端点和原因，不附着。 |
| `vibex --home <dir>` | 使用另一个 home。 |
| `vibex-server tui` | 从服务端二进制启动客户端。 |

`vibex status` 在出问题时应该第一个运行：它会说明这个 home 会用哪种运行时、连哪个端点，以及为什么。

### 本机模式与远程模式

| 模式 | 何时出现 | 说明 |
| - | - | - |
| **本机模式** | 没有别的进程持有这个 home | 客户端启动并拥有运行时；支持原生引导（steering）。 |
| **远程模式** | 另一个运行时持有 home，或通过 `vibex connect` 连接 | 客户端是网络对端；引导退化为打断并重发。 |

如果 home 被锁住、桌面端又没允许 TUI 接入，客户端会打印它尝试过的端点和三种出路：在桌面端打开 **设置 → 常规 → Vibex TUI**、退出桌面端，或连接到另一个运行时。

## 界面

界面是一列全宽横带：状态、对话流、回合状态、输入框和快捷键栏。窗口变窄时，装饰、队列和状态带会先让位，对话流和输入框保留；没有最小尺寸，也不会弹“窗口太小”。

* 结束的回合折在 `▸ Worked for 12s` 分隔线后面，点它或按 `e` 展开。
* 滚走的用户消息会钉在视口上方，不会随着滚动消失。
* `/` 在对话流里搜索，支持智能大小写正则；`n` / `p` 跳转匹配。
* 拖选文本会通过 OSC 52 复制，SSH 和 tmux 里也能用。
* 长粘贴收成 `[Pasted: 42 lines]` 芯片，图片从剪贴板、粘贴或拖入文件变成芯片。
* 状态带显示工作区、连接状态和当前模式；回合状态行显示正在运行的工具、耗时和审批数。

## 输入框

| 前缀 / 按键 | 作用 |
| - | - |
| `/` | 打开 Agent 命令和可复用 Prompt。 |
| `@` | 打开工作区文件和 Agent 委派列表；`←` / `→` 切换两个面板。 |
| `$` | 插入已启用的 Skill。 |
| `Enter` | 发送。 |
| `Shift+Enter` / `Ctrl+J` | 换行；终端不支持扩展键时用 `Ctrl+J`。 |
| `↑` | 在空输入框里召回上一条消息。 |
| `Ctrl+O` | 把草稿交给 `$EDITOR`。 |
| `Ctrl+S` | 引导正在运行的回合。 |
| `Ctrl+C` | 第一次清空草稿，第二次打断回合，第三次询问是否退出。 |

运行中写下的消息会进入队列，回合结束后自动发出。队列属于它写入的会话：切走再回来，它还在原处。

## 会话

`vibex` 打开时默认落在当前目录的新会话页，目录和上次使用的运行时已经填好。直接输入第一条消息即可创建会话；标题来自这条消息。

* `n` 新建会话，`Ctrl+W` 改工作区，`Ctrl+G` 打开 Agent 设置。
* `Ctrl+L` 或 `1` 打开会话列表；`Esc` 在输入页和列表之间切换。
* 会话列表按桌面端的排布绘制，支持置顶、重命名、分叉、归档、分组和拖动排序。
* 委派的子会话以树形分支显示，行尾的开关展开分支。
* `e` 打开选中行的详情，`c` 关闭所有详情卡，`y` 复制会话信息。

## 审批、提问与队列

Agent 的请求就地出现：

* 审批是页面上的卡片：`a` 允许，`d` 拒绝，`Ctrl+A` 本会话始终允许。
* 提问占据输入框横带，用 `Tab` 在字段间移动，`Enter` 提交。
* 自动继续保留桌面端的五秒倒计时；`t` 停止本次自动继续。
* 队列用 `Alt+↑↓` 选行，`Alt+E` 拉回草稿，`Alt+X` 删除，`Alt+J/K` 调整顺序，`Alt+Enter` 打断当前回合并立即发送。
* `Alt+D` 打开 Dock，集中显示正在运行的子 Agent、计划和被持有的消息。

## 管理、配对与设置

管理页是桌面风格的配置中心，包含 **Agent**、**Providers**、**Model**、**MCP**、**Skill**、**Prompt** 和 **配对与远程访问**。只显示当前运行时真的能提供的操作；没有权限的操作会说明原因，而不是消失。

配对页把 **配对**、**已配对设备** 和 **远程访问** 放在同一个标签条里：

* 二维码、一次性配对码和链接都在面板里生成。
* 一次配对会携带运行时发布的所有路由，用 `[` / `]` 切换。
* 本机局域网配对窗口用 `a` 允许、`r` 拒绝。
* 已配对设备可以撤销，并查看远程协议审计。

设置页包含主题与明暗模式（20 套）、语言（`en` / `zh-CN` / `zh-TW`）、图标集、着陆 logo、动效、推理显示、默认工作区和键位绑定。所有选择写入 `~/.vibex/tui-interface.json`，键位写入 `~/.vibex/tui-keys.toml`。

## 快捷键速查

| 按键 | 作用 |
| - | - |
| `?` | 打开快捷键速查表，按分组显示。 |
| `Ctrl+P` | 命令面板，最近使用过的命令排在前面。 |
| `/` | 在对话流、列表或速查表中搜索；具体范围取决于焦点。 |
| `Tab` | 在对话流和输入框之间切换焦点。 |
| `F2` | 展开或折叠所有块。 |
| `F9` | 重新加载键位文件。 |
| `Esc` | 关闭弹层；在输入页和会话列表之间切换。 |

键位可以在设置里逐项修改；冲突的键位会被拒绝，并指出已经占用它的动作。TUI 也会读取 `~/.vibex/tui-keys.toml`。

## 通知与终端行为

通知通过终端转义序列送达。附着到桌面端时，通知通道会让给桌面端，同一个事件只从一个通道来。

TUI 会接管终端的键盘协议：支持扩展键的终端能区分 `Enter` 和 `Shift+Enter`；不支持的终端退回 `Ctrl+J` 换行。复制使用 OSC 52，所以在 SSH 和 tmux 里也能工作。

## 限制

TUI 专注于会话和运行时的可操作性，不是桌面工作台的完整替代：

* 不提供文件编辑器、Markdown/PDF/Office 预览、内嵌浏览器或电脑操作面板。
* 图片附件以终端能显示的方式呈现，复杂图片仍建议在桌面端查看。
* 远程模式下没有原生引导，`Ctrl+S` 会退化为打断并重发。
* 电脑操作和浏览器面板的实时画面不在 TUI 中提供。

## 遇到问题

| 现象 | 处理 |
| - | - |
| 启动后提示 home 被锁 | 在桌面端打开 **设置 → 常规 → Vibex TUI**，退出桌面端，或 `vibex connect` 到另一个运行时。 |
| 中文或图标显示为方块 | 换一个带 CJK 和 Nerd Font 的终端字体；TUI 会为部分图标提供 ASCII 回退。 |
| `Shift+Enter` 不换行 | 终端不支持扩展键盘协议；用 `Ctrl+J`。 |
| 复制不到系统剪贴板 | 终端需要支持 OSC 52；在 tmux 里确认 `set-clipboard` 已开启。 |
| 远程模式无法引导 | 这是协议限制；使用 `Ctrl+C` 打断后重新发送。 |
| 键位文件写错 | TUI 会报告无法使用的行并继续启动；按 `F9` 重新加载。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.