> ## 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.