章節：使用 Hermes · 網址：https://hermesbible.com/docs/user-guide/tui
TUI 是 Hermes 的現代化前端——一個終端機介面，與 Classic CLI 共用相同的 Python 運行時。相同的 agent、相同的 session、相同的斜線命令；介面更乾淨、回應更即時。
這是建議的互動式執行 Hermes 方式。
啟動
# 啟動 TUI
hermes --tui
# 繼續最近的 TUI session（若無則回到最近的 classic session）
hermes --tui -c
hermes --tui --continue
# 透過 ID 或標題恢復特定 session
hermes --tui -r 20260409_000000_aa11bb
hermes --tui --resume "my t0p session"
# 直接執行原始碼——跳過預建構步驟（供 TUI 貢獻者使用）
hermes --tui --dev
也可以透過環境變數啟用：
export HERMES_TUI=1
hermes # 現在會使用 TUI
hermes chat # 同上
或在 ~/.hermes/config.yaml 中設定為持久預設值：
display:
interface: tui # "cli"（預設）或 "tui"
設定 display.interface: tui 後，直接執行 hermes（和 hermes chat）就會啟動 TUI。明確的參數永遠優先——執行 hermes --cli 可以在單次呼叫中回到經典 REPL，或用 hermes --tui / HERMES_TUI=1 在 config 預設為 cli 時強制使用 TUI。
經典 CLI 仍然是出廠預設。所有在 CLI 介面 中記載的功能——斜線命令、快捷命令、skill 預載入、personality、多行輸入、中斷——在 TUI 中完全相同地運作。
為什麼選用 TUI
- 首幀即時顯示 — 應用程式還在載入時，橫幅就已經繪製完成，所以 Hermes 啟動時終端機永遠不會感覺卡住。
- 非阻斷式輸入 — 在 session 尚未就緒前就可以打字佇列訊息。你的第一個提示詞會在 agent 上線後立即送出。
- 豐富的浮動面板 — 模型選擇器、session 選擇器、批准與澄清提示都以模態面板呈現，而非行內流程。
- 即時 session 面板 — 工具和 skill 會在初始化過程中逐步填入。
- 滑鼠友善選取 — 拖曳時以統一的背景色高亮顯示，而非 SGR 反白。使用你終端機的正常複製手勢即可複製。
- 替換畫面渲染 — 差異更新代表串流時不會閃爍，退出後也不會留下捲動歷史雜亂。
- 編輯器輔助功能 — 長片段的行內貼上自動折疊、
Cmd+V/Ctrl+V文字貼上搭配剪貼簿圖片備援、括號貼上安全機制，以及圖片/檔案路徑附件的標準化處理。
相同的 主題外觀 和 personality 適用。在 session 期間使用 /skin ares、/personality pirate 即時切換，UI 會立即重繪。參閱 主題外觀與佈景主題 取得完整可自訂項目清單，以及哪些適用於經典 CLI 與 TUI——TUI 支援橫幅色盤、UI 顏色、提示字元/顏色、session 顯示、選單、選取背景、tool_prefix 和 help_header。
可折疊的橫幅區段
TUI 啟動橫幅將執行時資訊分為四個可折疊區段，每個區段標題旁都有一個 ▸ / ▾ 箭頭符號：
| 區段 | 預設狀態 |
|---|---|
| 工具 | 展開 |
| Skills | 折疊 |
| 系統提示 | 折疊 |
| MCP 伺服器 | 折疊 |
點擊區段標題（或其箭頭）即可切換。工具列表預設展開，因為它是啟動時最常查看的區段；Skills、系統提示和 MCP 伺服器預設折疊，即使你已安裝數十個 skill 或接上許多 MCP 伺服器，橫幅仍能保持精簡。狀態為橫幅實例的區域性設定，下次啟動會重設為預設值。
系統需求
- Node.js ≥ 20 — TUI 以 Python CLI 啟動的子程序運行。
hermes doctor會驗證此需求。 - TTY — 與經典 CLI 相同，管線 stdin 或在非互動環境中執行時，會退回為單次查詢模式。
首次啟動時，Hermes 會將 TUI 的 Node 依賴項安裝到 ui-tui/node_modules（一次性，約幾秒）。後續啟動速度很快。如果你拉取新的 Hermes 版本，當原始碼比 dist 更新時，TUI bundle 會自動重新建構。
外部預建構
發行預建構 bundle 的發行版（Nix、系統套件）可以指引 Hermes 使用它：
export HERMES_TUI_DIR=/path/to/prebuilt/ui-tui
hermes --tui
該目錄必須包含 dist/entry.js。
快速鍵
快速鍵與 經典 CLI 完全相同。行為差異僅有：
- 滑鼠拖曳 會以統一的選取背景色高亮文字。
Cmd+V/Ctrl+V先嘗試一般文字貼上，再退回 OSC52/原生剪貼簿讀取，最後當剪貼簿或貼上內容解析為圖片時會附加圖片。/terminal-setup安裝本地 VS Code / Cursor / Windsurf 終端機快速鍵綁定，以改善 macOS 上Cmd+Enter以及復原/重做的操作體驗。- 斜線自動完成 會以浮動面板顯示並附帶說明，而非行內下拉選單。
Ctrl+X開啟即時 session 切換器。當佇列訊息被高亮時（在 agent 仍在運行時送出的），它仍然會刪除該佇列訊息。Esc會取消編輯並取消高亮，但不刪除。Ctrl+G/Ctrl+X Ctrl+E— 在$EDITOR中開啟目前輸入緩衝區，用於多行/長提示詞編輯；儲存並離開後，內容會作為提示詞送回。
斜線命令
所有斜線命令功能不變。部分命令為 TUI 專屬——它們會產生更豐富的輸出或以浮動面板而非行內面板渲染：
| 命令 | TUI 行為 |
|---|---|
/help | 以分類方式顯示命令的浮動面板，支援方向鍵導覽 |
/sessions（別名 /switch） | 即時 session 切換器——列出開啟中的 TUI session、切換、關閉，或啟動另一個 |
/model | 以供應商分組的模態模型選擇器，附帶成本提示 |
/skin | 即時預覽——瀏覽時即時套用佈景主題變更 |
/details | 切換詳細的工具呼叫資訊（全域或按區段） |
/usage | 豐富的 token / 成本 / 情境面板 |
/agents（別名 /tasks） | 可觀測性浮動面板——即時子 agent 樹狀結構，附帶終止/暫停控制、各分支成本/token/檔案彙總，以及逐輪歷史 |
/reload | 將 ~/.hermes/.env 重新讀入運行中的 TUI 程序，讓新加入的 API 金鑰無需重啟即可生效 |
/mouse [on|off|toggle|wheel|buttons|all] | 在運行時選擇滑鼠追蹤預設（同時持久化到 config.yaml 的 display.mouse_tracking）。wheel（1000+1006）保留捲軸滾動但不含讓 tmux 在提示列上不斷刷出「No image in clipboard」的游標懸停事件；buttons 增加拖曳選取功能；all 為預設值，包含游標懸停驅動的 UI。 |
其他所有斜線命令（包括已安裝的 skill、快捷命令和 personality 切換）與經典 CLI 完全相同。參閱 斜線命令參考。
即時 session 切換器
當你希望用一個終端機作為多個 TUI session 的調度器時，可以使用即時 session 切換器。它僅列出目前在此 TUI 程序中處於活躍狀態的 session；已關閉的 session 仍保存為記錄檔，可透過 /resume 或 hermes --tui --resume <id-or-title> 重新開啟。
以下任一方式可開啟：
- 在 TUI 中按
Ctrl+X。 - 使用
/sessions或/switch。 - 使用
/sessions new立即建立新的活躍 session。 - 點擊狀態列中的
N live sessions計數。
在切換器中：
↑/↓移動選取；滑鼠點擊也可選取列。Enter切換到選取的活躍 session。Ctrl+D關閉選取的活躍 session。Ctrl+N啟動空白的活躍 session。Ctrl+R重新整理活躍 session 列表。Esc關閉切換器。- 選取
+new，輸入提示詞，然後按Enter來派送新的活躍 session。若要為該新 session 選擇模型，先按Tab。
LaTeX 數學運算式渲染
TUI 的 Markdown 處理器會將 LaTeX 數學運算式行內渲染：$E = mc^2$ 和 $$\frac{a}{b}$$ 會渲染為 Unicode 格式的數學運算式，而非原始 TeX 原始碼。支援行內和區塊數學運算式；不支援的語法會退回為顯示包裹在程式碼跨度中的原始 TeX，以便複製。
此功能始終啟用——無需設定。經典 CLI 保留原始 TeX。
淺色終端機偵測
TUI 會自動偵測淺色終端機並相應切換為淺色主題。偵測分為三個層級：
HERMES_TUI_THEME環境變數——最高優先權。可選值：light、dark，或原始的 6 碼十六進位背景色（例如ffffff、1a1a2e）。COLORFGBG環境變數——經典的「我的背景色是什麼？」提示，由 xterm 衍生終端機使用。- 透過 OSC 11 偵測終端機背景色——適用於不設定
COLORFGBG的現代終端機（Ghostty、Warp、iTerm2、WezTerm、Kitty）。
若要永久使用淺色主題（不受終端機影響）：
export HERMES_TUI_THEME=light
忙碌指示器樣式
狀態列的忙碌指示器是可插拔的——預設會在 agent 工作時每 2.5 秒輪播 Hermes 的顏文字表情。可透過設定或 /indicator 斜線命令選擇其他樣式：
display:
tui_status_indicator: kaomoji # kaomoji | emoji | unicode | ascii
或在 session 中使用：/indicator emoji（等）。各樣式配有匹配的字元寬度，因此狀態列的其餘部分在輪播時不會抖動。
自動恢復
預設情況下，hermes --tui 每次啟動都會開始全新 session。若要自動重新連接最近的 TUI session（當你的終端機或 SSH 連線意外中斷時很有用），請啟用：
export HERMES_TUI_RESUME=1 # 最近的 TUI session
# 或：
export HERMES_TUI_RESUME=<session-id> # 指定的 session
取消設定該變數或明確傳入 --resume <id> 即可在每次啟動時覆蓋。
狀態列
TUI 的狀態列即時追蹤 agent 狀態：
| 狀態 | 意義 |
|---|---|
starting agent… | Session ID 已啟用；工具和 skill 尚在載入中。你可以打字——訊息會排隊，就緒後送出。 |
ready | Agent 閒置中，可接受輸入。 |
thinking… / running… | Agent 正在推理或執行工具。 |
interrupted | 目前回合已取消；按 Enter 重新送出。 |
forging session… / resuming… | 初始連線或 --resume 握手。 |
各主題外觀的狀態列顏色和閾值與經典 CLI 共用——參閱 主題外觀 進行自訂。
狀態列還會顯示：
- 工作目錄與 git 分支 —
~/projects/hermes-agent (docs/two-week-gap-sweep)。當你在側邊終端機執行git checkout時，分支後綴會更新（基於 mtime 快取），讓 TUI 反映你實際的活動分支，而非啟動時的分支。 - 每次提示詞的經過時間 — 回合運行中時顯示
⏱ 12s/3m 45s（即時），回合完成後凍結為⏲ 32s / 3m 45s。第一個數字是自上一條使用者訊息以來的時間；第二個是整個 session 的總時間。每次新提示詞時重設。 🗜️ N— 運行中的 session 已自動壓縮的次數。第一次壓縮觸發後出現。▶ N— 此 session 中目前正在執行的/background任務數量。至少有一個任務進行中時出現。⚠ YOLO— 當 YOLO 模式開啟時（hermes --yolo、/yolo或HERMES_YOLO_MODE=1）顯示的警告。相同標記也會出現在啟動橫幅中，確保你不會在不知情的情況下啟動自動批准的 session。
設定
TUI 遵守所有標準 Hermes 設定：~/.hermes/config.yaml、設定檔、personality、主題外觀、快捷命令、憑證池、記憶體供應商、工具/skill 啟用。沒有 TUI 專用的設定檔。
有幾個設定項目專門調整 TUI 介面：
display:
skin: default # 任何內建或自訂主題外觀
personality: helpful
details_mode: collapsed # hidden | collapsed | expanded — 全域手風琴預設值
sections: # 選填：按區段覆蓋（任何子集）
thinking: expanded # 始終展開
tools: expanded # 始終展開
activity: collapsed # 重新啟用活動面板（預設隱藏）
mouse_tracking: all # off | wheel | buttons | all（或 true/false 兼容舊版）。
# wheel — 1000+1006（捲動 + 點擊；無拖曳、無懸停——
# 推薦在 tmux 內使用，以消除游標懸停事件導致的
# 提示列「No image in clipboard」刷頻）
# buttons — 增加 1002 支援終端機端拖曳選取
# all — 增加 1003 支援支援懸停（捲軸懸停翻頁、
# 連結滑鼠移入等）
運行時切換：
/details [hidden|collapsed|expanded|cycle]— 設定全域模式/details <section> [hidden|collapsed|expanded|reset]— 覆蓋特定區段 （區段：thinking、tools、subagents、activity）
預設可見性
TUI 出廠時對各區段設有經過調整的預設值，將回合渲染為即時逐字稿，而非一整排箭頭：
thinking— 展開。推理過程會隨模型產生即時串流顯示。tools— 展開。工具呼叫及其結果預設展開顯示。subagents— 採用全域details_mode（預設折疊在箭頭下——直到真正發生委派才顯示）。activity— 隱藏。環境元資訊（閘道提示、終端機相容性提示、背景通知）在日常使用中大多是雜訊。工具失敗仍會在該工具列上行內顯示；當所有面板都隱藏時，環境錯誤/警告會透過浮動警告提示呈現。
各區段的覆蓋設定優先於區段預設值和全域 details_mode。若要調整佈局：
display.sections.thinking: collapsed— 將推理過程放回箭頭下display.sections.tools: collapsed— 將工具呼叫放回箭頭下display.sections.activity: collapsed— 重新啟用活動面板- 在運行時使用
/details <section> <mode>
在 display.sections 中明確設定的任何內容都會優先於預設值，因此現有設定不受影響。
Sessions
Sessions 在 TUI 和經典 CLI 之間共用——兩者都寫入相同的 ~/.hermes/state.db。你可以在其中一個中啟動 session，然後在另一個中恢復。Session 選擇器會顯示來自兩者的 session，並附帶來源標記。
參閱 Sessions 了解生命週期、搜尋、壓縮和匯出。
TUI 如何與閘道通訊
預設情況下，TUI 會啟動自己的行程內閘道，因此每個 TUI 實例都是自包含的——無需設定。
你可能會在原始碼或日誌中看到 HERMES_TUI_GATEWAY_URL 環境變數的引用。這是 Web 儀表板的內部接線細節，並非供使用者設定的遠端連接參數。當你開啟儀表板的「Chat」分頁（hermes dashboard → /chat）時，儀表板的 Web 伺服器會啟動一個內建的 TUI 子程序，並注入 HERMES_TUI_GATEWAY_URL，讓該子程序透過回環 WebSocket（/api/ws）連接到儀表板自身的行程內 tui_gateway。/api/ws 端點僅存在於儀表板伺服器（hermes_cli/web_server.py）內部，且與該程序的生命週期和授權綁定。
不存在通用的「將任何 TUI 指向任何獨立閘道端口」模式。特別是，OpenAI 相容的 API 伺服器（hermes gateway / api_server 平台）不提供 /api/ws 服務——它是模型後端介面（/v1/chat/completions、/v1/models、…），刻意不暴露 TUI 的 JSON-RPC 控制通道。將 HERMES_TUI_GATEWAY_URL 設定為該端口會導致 404。
若要讓多個介面共用同一組 sessions，請使用共用的 ~/.hermes/state.db（參閱 Sessions）或 Web 儀表板的內建聊天功能（參閱 Web 儀表板）——而非手動設定閘道 URL。
回到經典 CLI
啟動 hermes（不帶 --tui）預設會使用經典 CLI。若要讓機器偏好使用 TUI，請在 ~/.hermes/config.yaml 中設定 display.interface: tui（持久），或在你的 shell 設定檔中設定 HERMES_TUI=1（per-shell）。若要回退，設定 interface: cli / 取消環境變數，或使用 hermes --cli 進行一次性呼叫。
如果 TUI 啟動失敗（無 Node、缺少 bundle、TTY 問題），Hermes 會輸出診斷訊息並自動退回——不會讓你卡住。
參見
- CLI 介面 — 完整的斜線命令和快速鍵參考（共用）
- Sessions — 恢復、分支和歷史
- 主題外觀與佈景主題 — 設定橫幅、狀態列和浮動面板的主題
- 語音模式 — 兩個介面都可使用
- 設定 — 所有設定項目