# TUI 指南

單一 bubbletea textarea（`internal/runtime/tui`）；斜線指令開啟短暫 popup，關閉後乾淨回到輸入提示。

自 v1.2.0 起 TUI 不再自行執行 agent：所有請求都由 daemon 執行，TUI 是經 Unix socket `~/.config/agenvoy/daemon.sock`（權限 `0600`、以換行分隔的 JSON frame）連線的 client。執行與發起它的連線綁定，關閉 TUI 會停止該次執行，但保留其 pending 快照。該次執行的確認與 `ask_user` 問題只送到發起它的 TUI 視窗；`$HOME` 外的路徑、`sudo` argv 或 `sandbox: false` 的確認會在 TUI 的密碼欄位要求系統密碼（`$HOME` 內的敏感路徑只需一般確認），由 daemon 驗證（`sudo -S -v`）。socket 斷線時狀態列顯示 `Connecting`，TUI 每 5 秒重試；一般輸入、skill、`/pending` 續跑與排程觸發會等到重新連線，本地 `/` 指令照常可用。工作目錄由 TUI 自行管理，以 `Shift+P` 設定。移除於 v1.3.0：daemon 不再推送 agent 以 `cd` 切換後的目錄，因為 agent 已無法變更工作目錄。

v1.3.8 起，session 有背景 leg 在跑時，輸入框上方顯示 `N background task(s) running`，沒有任務執行時後面再接 `(esc to cancel)`，每秒更新。v1.3.0 的 `Waiting for background tasks (the reply continues here)` 提示及其後續輸入模式移除於 v1.3.8，因為執行不再為背景工作維持 pending（見[待決任務與取消](/zh/execution-engine-pending)）。

## 快捷鍵

| 按鍵 | 動作 |
|---|---|
| `Enter` | 送出當前輸入。執行中只會送出一般文字，作為 **steer** 訊息遞送給執行中的迴圈；`/` 指令在執行結束前不列出也不送出 |
| `Alt+Enter` | 插入換行 |
| `!` 前綴 | v1.3.0 起，`!<command>` 會以 `$SHELL -c`（未設定時為 `/bin/sh`）在 TUI 的工作目錄執行該行其餘內容，由 TUI 行程直接執行、不經沙箱，最長 30 分鐘；輸入行以 `!` 開頭時輸入框轉為紅色並顯示 `$ ` 提示。exit code 與輸出（最多 32 KiB）印在對話紀錄中，接著以 `[Shell command]` 訊息交給 agent 回報結果；這則訊息不會出現在對話紀錄。與其他訊息相同，需要已註冊模型且 daemon 已連線，`Esc` / `Ctrl+C` 可中止指令。v1.3.2 起含 `sudo` 字詞的指令會先檢查是否有有效的 sudo ticket；沒有時先開啟 `System password:` popup，以 `sudo -S -v` 驗證密碼後才執行，指令中的 sudo 會沿用該 ticket。密碼錯誤時回報 `[Denied] password: incorrect password`；`Esc` 關閉 popup 且不執行指令 |
| `/` | 開始斜線指令過濾（popup 選單——Up / Down 移動、Tab / Enter 補進 textarea、Esc 關閉） |
| `Up` / `Down` | 游標位於第一行 / 最後一行時瀏覽輸入歷史（per-session `.cmd_history` 檔） |
| `Esc` | popup 以外依序（v1.2.0）：關閉指令選單，否則關閉通知框，否則在執行中開啟取消 popup —— **No**、**Yes（cancel）**、**Pause（keep pending）** 三選一。cancel 會丟棄 pending 任務（v1.3.9 起以 `[Canceled]` 回覆保留在對話歷史），pause 則停止該次執行但保留可由 `/pending` 續接；兩者都會一併停止該任務的背景工作。尚未輸出任何內容的執行會直接取消，不跳 popup。其餘情況清空非空的輸入；輸入為空且沒有執行時，開啟背景任務選單（v1.3.8）：**No**、各執行中的 leg 與 **All**（兩條以上才有），選定後再確認一次才取消 |
| `Ctrl+C` | 執行中時直接取消任務（走 user-cancel 路徑，pending 任務一併丟棄；v1.3.9 起以 `[Canceled]` 保留在對話歷史）；否則印出 `ctrl+c again to quit`。3 秒內再按一次 `Ctrl+C` 即離開 TUI |

單鍵切換僅在輸入為空、指令選單關閉且無執行中任務時生效（`Shift+Tab` 只檢查後兩項）：

| 按鍵 | 動作 |
|---|---|
| `Shift+Tab` | 切換 auto 模式（`safe` ↔ `auto`） |
| `Shift+F` | 切換 fast 模式——啟用時模式列顯示 `[fast]` |
| `Shift+G` | 切換 `CLAUDE.md` / `AGENTS.md` 注入（v1.2.0；啟動時為關閉）。開啟且工作目錄有其中一個檔案時，模式列顯示 `[CLAUDE.md]` 或 `[AGENTS.md]`，該檔加入每輪的 context |
| `Shift+U` | 所有會回報用量的已註冊供應商之即時用量 / 餘額：`codex`、`grok-oauth`、`copilot`、`deepseek`、`openrouter`、`claude-code`（Ollama Cloud 移除於 v1.2.0）；結果顯示於通知框。v1.1.3 起有多個額度視窗的供應商依 `5h/week/total` 各顯示一個百分比，各自依剩餘量上色 |
| `Shift+P` | 開啟 **Work directory** popup（v1.3.0）：可填絕對路徑、`~/...` 或相對於目前目錄的路徑；不存在的路徑會以 `[Not found] work directory` 拒絕，各層目錄的大小寫會修正為磁碟上的實際寫法 |
| `Shift+W` / `Shift+S` | 在 `auto` 與已註冊模型間向前 / 向後輪替 session 模型（與 `/model` 內調整 fallback 排序的 `w` / `s` 不同） |
| `Shift+A` / `Shift+D` | 在 `auto`、`none`、`low`、`medium`、`high`、`xhigh`、`max` 間調降 / 調升 session 的 reasoning 等級——v1.1.0 起包含 `auto` |

Shell 指令模式（`Shift+T`）已移除；v1.3.0 起改以 `!` 前綴直接執行指令。`Shift+M` 模型清單已移除；請用 `/model`，它會列出已註冊模型。

清單型 popup 中，`Enter` 確認選中項，`d` 刪除、`t` 設定 tier（僅在該 popup 提供這些動作時）。文字輸入型 popup 以 `Ctrl+S` 確認、`Enter` 換行、`Esc` 取消。

自 v1.3.3 起確認、密碼與 `ask_user` popup 不理會 `Esc`，須選擇選項。確認框提供 **Yes**、**Yes don't ask again**、**Yes allow this turn**、**No skip this**（可附理由給 agent）、**Abort keep for resume** 與 **Cancel delete task**；需要密碼的確認（`$HOME` 外的路徑、`sudo`、`sandbox: false`）不提供兩個免詢問選項，一般確認（含 `$HOME` 內的敏感路徑）則保留，系統密碼錯誤時 popup 保留，驗證成功才關閉。`run_command`／`background_command` 的確認會在分隔線與指令上方顯示 dispatcher model 的說明。開著的 popup 會隨終端機大小重新渲染，`ask_user` 依視窗高度截斷問題與描述，讓每個選項都完整顯示；popup 開著時任務結束，狀態不再卡在執行中。

TUI 自動 tail 當前 session 的 `action.log`（外部行程寫入的行以 warn-purple 的 `▌ ` 前綴標示）。僅單一 session 檢視。

自 v1.1.0 起，狀態訊息（指令結果、錯誤、`Shift+U` 輸出）集中在輸入框上方帶框的通知框，不再捲入對話紀錄。v1.1.3 起單純的成功確認（角色已儲存、key 已刪除、新 session 等）改寫入 debug 日誌，通知框只留需要注意的訊息；v1.3.0 起空狀態與進度訊息（`no active session`、`nothing scheduled`、`compacting history...` 等）也改寫入 debug 日誌，v1.3.2 起 `⚠ restricted path approved` 提示亦同。通知框保留最後 32 行、一次顯示 4 行；超過時按 `Tab` 往上翻頁，`Esc` 關閉。