Dotfile 管理的判讀：配置格式是純文字（TOML/Lua/INI/JSON）的 terminal emulator，配置檔可以直接進 dotfile repo。iTerm2 這種以 GUI 面板為主的，要用它的匯出功能另外處理。

選型建議：如果跨 macOS + Linux 雙平台，Alacritty 或 WezTerm 的「一份配置兩邊通用」是明確優勢。如果只在 Linux 上用 Wayland，Foot 是輕量首選。

該放進配置的核心項目

• 字型：字型家族、大小、行高。建議使用 Nerd Font（含 icon glyph 的程式字型），很多 TUI 工具和 prompt 依賴這些 glyph
• 配色：前景/背景色、ANSI 16 色的定義。配色方案（Catppuccin、Tokyo Night、Gruvbox 等）通常有各 terminal 的預設配置檔可直接套用
• 快捷鍵：分頁/分割畫面的快捷鍵。注意跟 tmux/zellij 的快捷鍵衝突問題
• 渲染：GPU 加速、字型 hinting、抗鋸齒設定

配色系統的跨工具一致性

配色方案（color scheme）會同時影響 terminal emulator、editor、tmux status bar、shell prompt。用同一套配色方案（例如 Catppuccin Mocha）跨工具統一視覺是 rice 的基礎。

管理方式：

• 每個工具各自的配色設定檔都放進 dotfile repo
• 主題選擇集中記錄（例如 dotfile repo 的 README 寫「全域使用 Catppuccin Mocha」），換主題時有對照清單知道要改哪些檔案
• 部分配色方案提供「一鍵安裝腳本」涵蓋多個工具，也可以放在 bootstrap script 裡

字型管理

Nerd Font 是需要安裝在系統上的，不是單純的配置檔。處理方式：

• macOS：Brewfile 裡加 cask "font-hack-nerd-font"（透過 homebrew-cask-fonts tap）
• Linux：套件管理器安裝或手動下載到 ~/.local/share/fonts/
• 字型檔案本身不進 dotfile repo（太大、有版權），只記錄「安裝哪個字型」在套件清單或 bootstrap script 裡

安裝字型後如果畫面仍然顯示豆腐方塊，原因通常不是字型沒裝好，而是顯示它的程式在安裝之前就已啟動。每個 process 的可用字型集合在啟動時決定，之後新裝的字型對它不可見——需要重啟該程式才生效。詳見 字型的可用集合在 process 啟動時決定。fontconfig 的工具分工與 fallback 機制見 fontconfig。

SSH「連不上」本身（Permission denied、Host key verification failed、Connection refused）的判讀與修復，見 外部連入與無 key 的 bootstrap 路徑 的重連段落。這篇處理的是「連上了、但終端機或 session 的狀態不對」的那些情況。

SSH 斷線後本機終端機噴亂碼、狂跳字元

一個嚇人但無害的情況：SSH 連線被中斷後，你本機的終端機開始瘋狂輸出像 <35;80;24M 這樣的序列，尤其在你移動滑鼠時狂跳。這不是遠端機器在打字，是你本機的終端機被卡在滑鼠回報模式。

判讀關鍵在「什麼時候噴」：如果那串亂碼只在你移動滑鼠時出現、而且形如 數字;數字M，那就是滑鼠座標回報。成因是遠端跑的某個全螢幕程式（TUI、編輯器、終端機多工器）啟動時對終端機開了滑鼠追蹤模式，SSH 被硬斷時它來不及送出「關閉滑鼠模式」的序列就死了，於是你本機終端機還停在回報模式，滑鼠一動就把游標座標當輸入送進來。

修復是重置終端機的模式，跟遠端機器無關：

• 最快：開一個新的終端機分頁 / 視窗。模式是「那個終端機 session」的狀態，新視窗是乾淨的。
• 救現有視窗：先把滑鼠移開別動（洪流會停），盲打 reset 再 Enter，送出終端機重置。
• 若 reset 沒清掉，補送關閉滑鼠回報的序列：printf '\033[?1000l\033[?1002l\033[?1003l\033[?1006l'。

同一類的還有「alternate screen 沒還原」——遠端的全螢幕程式異常結束時，本機終端機可能卡在替代畫面緩衝區，看起來像畫面清空或凍結。reset 同樣能救。歸納起來：SSH 被硬斷後本機終端機行為異常，先懷疑「對端程式來不及還原終端機模式」，用 reset 或開新視窗處理本機終端機狀態，不必急著重連遠端。

遠端打字變亂碼、重複、位置錯亂

連上遠端後，如果互動式輸入變得不對——打一個字出現好幾個、游標位置錯亂、畫面重繪殘影——通常是兩層問題之一，判讀方式是分開排除。

第一層是字元編碼（locale）。從某些本機（例如 macOS）SSH 進 Linux 時，本機會把 LC_CTYPE 之類的變數帶過去；如果遠端沒有對應的 locale、就會退回 POSIX/C locale，讓終端機的行編輯（ZLE、readline）對多位元組字元的寬度判斷出錯，表現為輸入重複或錯位。判斷方式是在遠端 locale 看目前值、locale -a 看有沒有裝對應的 UTF-8 locale。修法是在遠端明確設好 LANG / LC_CTYPE 到一個實際存在的 UTF-8 locale，而不是讓它繼承一個遠端不認得的值。

第二層是終端機能力資料庫（terminfo）。你本機終端機的 TERM 值（例如某些新終端機用 xterm-ghostty 之類的自訂值）如果在遠端沒有對應的 terminfo 條目，遠端程式就不知道怎麼正確地清行、移動游標、重繪，畫面就會亂。判斷方式是在遠端 echo $TERM 看值、infocmp $TERM 看遠端認不認得。修法是把本機的 terminfo 條目送過去讓遠端安裝：infocmp -x $TERM | ssh <遠端> 'tic -x -'。

先分清是 locale 還是 terminfo，兩者症狀相似但修法不同：locale 是編碼寬度、terminfo 是繪製指令。查 locale 跟查 $TERM + infocmp 就能分開。

從 SSH 操控遠端的圖形桌面

想從一條純文字的 SSH 連線去操作遠端的 Wayland 圖形桌面（例如啟動應用、截圖、送 IPC 指令）時，會撞到兩類界線，判斷對是哪一類就知道怎麼繞。

第一類是圖形程式需要知道連到哪個顯示。SSH 進來的 shell 預設沒有圖形環境的環境變數，直接跑圖形程式會找不到 display。要對著遠端那個已經在跑的 Wayland session 操作，得補上它的環境變數：XDG_RUNTIME_DIR（通常 /run/user/<uid>）、WAYLAND_DISPLAY（socket 名，如 wayland-1）、必要時還有該 compositor 的 instance 變數與 DBUS_SESSION_BUS_ADDRESS。這些值怎麼撈：socket 名用 ls /run/user/$(id -u)/wayland-* 看；其餘變數直接從那個圖形 session 既有行程的環境複製最準——cat /proc/<compositor-pid>/environ | tr '\0' '\n' | grep -E 'WAYLAND_DISPLAY|XDG_RUNTIME_DIR|DBUS_SESSION|_INSTANCE_'（<compositor-pid> 用 pgrep -x Hyprland 之類找）。撈到後 export 進當前 SSH shell，這條連線就能對遠端的圖形 session 下指令、grim 截圖。

第二類是有些東西必須從實體圖形終端機（VT，即 Ctrl+Alt+F1~F6 切換的那些文字主控台）啟動，SSH 的 pty 起不來。Wayland 的合成器（compositor，畫桌面、把視窗合成到螢幕、管輸入輸出的核心程式，如 Hyprland）需要一個真正的圖形 VT 上的登入 session，拿到 DRM master（對顯示卡的獨佔繪圖控制權）與 logind seat（一組綁在一起的實體螢幕／鍵鼠裝置）才能啟動；從 SSH 的 pty 起它的預設 backend 會直接失敗（例如報 backend 建立失敗），因為預設 backend 要的 DRM master 與 seat 在 SSH 這條連線上不存在。判讀訊號：合成器一啟動就報 seat / DRM / backend 相關的錯，而你是從 SSH 起的——那就是這個界線。（例外：合成器多半有 headless backend，例如設 WLR_BACKENDS=headless 就不要 DRM master、不需 VT，專給 CI、雲端、自動化測試用；nested（跑在另一個 Wayland session 裡）也不需要。所以精確說是「預設 backend 需要圖形 VT」，不是「合成器一定起不來」。）

繞法是回到那台機器的實體圖形終端機去啟動 compositor，但「回到 VT」這件事也可以從 SSH 遠端做：

• sudo chvt <N> 從 SSH 切換那台機器目前顯示的虛擬終端機到第 N 個，比在虛擬機視窗裡跟宿主的 Ctrl+Alt+Fn 快捷鍵搏鬥穩定。
• 切過去卻是空白、沒有登入提示，通常是那個 VT 上沒有 getty 在跑：sudo systemctl start getty@tty<N>（開機時 enabled 但 inactive 是常見狀態，logind 的 autovt 沒觸發）。
• sudo fgconsole 確認目前是哪個 VT 在前景。

還有一個容易混淆的點：一台虛擬機可能同時有「序列主控台」跟「圖形顯示」兩個獨立輸出。在 guest 內 chvt 只切圖形那側，序列主控台看到的畫面不會變。如果你在虛擬機軟體裡看的是序列主控台，圖形桌面得切到顯示輸出那個 view 才看得到。判讀：切了 VT 但畫面沒反應，先確認你正在看的是哪個輸出。

判讀路由

遠端 / 終端機問題的分流：

• 本機終端機噴亂碼、只在動滑鼠時噴 → 滑鼠回報模式沒關（本機終端機狀態），reset 或開新視窗。
• 遠端打字重複 / 錯位 → 分 locale（查 locale）與 terminfo（查 $TERM + infocmp）。
• 圖形程式在 SSH 下找不到 display → 補 WAYLAND_DISPLAY / XDG_RUNTIME_DIR 等環境變數。
• compositor 從 SSH 起不來、報 seat/DRM 錯 → 它需要實體 VT，用 chvt + getty@tty<N> 回到圖形 VT 啟動。
• SSH 連不上（拒絕 / host key / refused）→ 見 外部連入與無 key 的 bootstrap 路徑。

這幾種分流的共同底線是先讀權威狀態（locale、$TERM、runtime 目錄、loginctl、fgconsole）再下判斷；背後的方法論見 診斷心法。

tmux

tmux 是最成熟、生態最廣的選擇。配置在 ~/.config/tmux/tmux.conf（新版）或 ~/.tmux.conf（傳統位置）。

核心配置項目

 1# prefix key（預設是 Ctrl-b，很多人改成 Ctrl-a）
 2unbind C-b
 3set -g prefix C-a
 4bind C-a send-prefix
 5
 6# 分割 pane 的快捷鍵（預設不直覺，改成 | 和 -）
 7bind | split-window -h -c "#{pane_current_path}"
 8bind - split-window -v -c "#{pane_current_path}"
 9
10# 用 vim 風格的 hjkl 切換 pane
11bind h select-pane -L
12bind j select-pane -D
13bind k select-pane -U
14bind l select-pane -R
15
16# 啟用滑鼠支援
17set -g mouse on
18
19# 256 色支援
20set -g default-terminal "tmux-256color"
21set -ag terminal-overrides ",xterm-256color:RGB"
22
23# status bar 位置
24set -g status-position top

tmux plugin

用 TPM（Tmux Plugin Manager）管理，常用：

• tmux-sensible：合理的預設值
• tmux-resurrect：重開機後還原 session 佈局
• tmux-continuum：自動儲存 session

zellij

zellij 是較新的替代品，Rust 寫的，內建佈局系統、tab 命名、浮動 pane。配置在 ~/.config/zellij/config.kdl（KDL 格式）。

跟 tmux 的主要差異：

• 開箱即用的 UI 提示（底部顯示可用快捷鍵），學習曲線較低
• 佈局用 KDL 宣告式描述，比 tmux 的 script 式設定更容易管理
• Plugin 系統用 WASM，跟 tmux 的 bash script 式 plugin 不同
• 生態較新、plugin 和整合沒有 tmux 多

選型判讀

已經熟 tmux 的人通常沒有強烈理由遷移；從零開始的人 zellij 的上手成本更低。

深入

這篇是多工器的概覽（在終端機生態裡的定位、tmux 與 zellij 的取捨）。把它們當「遠端工作工具」深入用——session 持久化的核心概念、遠端斷線接回、瀏覽器連遠端 session——見工具選單的深度頁：

• tmux 持久化與基礎——session 持久化怎麼保住遠端工作。
• zellij 分頁與 pane——內建佈局的操作深入。
• zellij 遠端 web 客戶端——從瀏覽器連遠端 session。
• 遠端連線與同步工具選型——多工器之外的連線（mosh/autossh）與同步（rsync/sshfs/mutagen）。

CLI 輸入的特殊性

桌面終端機的鍵盤直接傳送按鍵事件，沒有中間的輸入法處理層。使用者按 l 就是 l，按 Tab 就是 Tab，按 Ctrl+C 就是 interrupt signal。

手機鍵盤在使用者和 app 之間插入了 IME 層。使用者按 l 時，IME 可能等待後續按鍵組合成完整詞彙再傳送；使用者按的按鍵可能被自動校正替換；使用者的輸入被記錄到 IME 詞庫供跨 app 學習。

Terminal app 需要繞過或控制 IME 層的這些行為。app_tunnel 的 TextField 用 TextInputType.visiblePassword + autocorrect: false + enableSuggestions: false + enableIMEPersonalizedLearning: false 四個參數關閉 IME 的自動行為（U.C3）。

整行送出 vs 逐字元：protocol 層的影響

整行送出和逐字元送出在 UI 層看起來只是「按 Enter 送出整行」和「每個按鍵即時送出」的差別，但在 protocol 層是兩種不同的通訊模式。

整行送出

Client 端累積使用者輸入，使用者按 Enter 時傳送完整指令字串加換行符（ls -la\n）。Server 端收到完整行後處理。

Protocol 設計簡單：每個 WebSocket frame 是一個完整指令。Server 不需要管理部分輸入的狀態，也不需要即時回應 Tab 或方向鍵。

代價：使用者無法在手機上使用 Tab 補全（Tab 被 IME 攔截或不存在）、無法用方向鍵在指令中移動游標（移動的是 TextField 的游標，不是 server 端的 readline 游標）。

逐字元送出

Client 端每個按鍵即時傳送一個 WebSocket frame。Server 端的 shell 即時處理每個字元，包括 Tab 補全（server 回傳補全結果）、Ctrl+C（server 中斷當前程序）、方向鍵（server 端 readline 移動游標）。

Protocol 設計複雜：每個按鍵一個 frame，frame 內容是單一字元或控制序列。Server 端必須維護 readline 狀態。Client 端必須正確編碼控制字元（Ctrl+C = 0x03, Tab = 0x09）。

代價：protocol 複雜度高，每個按鍵都有網路延遲。在高延遲網路上輸入體驗差（打字後要等 round-trip 才看到回顯）。

決策在 protocol 層做

app_tunnel 選擇整行送出，犧牲 Tab 補全換取簡單的 protocol 設計。這個決策應該在 protocol spec 階段做 — 因為它影響 server 端（ttyd）的行為預期和 client 端的 frame 格式。在 UI 實作時才臨時決定，可能和 server 端的行為預期不一致。

特殊按鍵的 UI 方案

手機沒有 Esc、Tab、Ctrl、方向鍵。Terminal app 需要額外的 UI 元件提供這些按鍵。

底部工具列

固定在鍵盤上方的一排按鈕，提供常用特殊鍵。app_tunnel 的工具列包含 Esc、Tab、Ctrl、四個方向鍵。

工具列的設計考量：按鈕大小（手指能精確觸碰的最小尺寸約 44x44 pt）、排列順序（最常用的放中間）、長按行為（長按 Ctrl 是否支援 Ctrl 組合鍵）。

Ctrl 組合鍵

Ctrl+C（中斷）、Ctrl+D（EOF）、Ctrl+Z（暫停）在 CLI 操作中頻繁使用。手機上的實作方式通常是：按下 Ctrl 按鈕後進入「Ctrl 模式」，下一個按鍵自動加 Ctrl 前綴。

下一步路由

• 四維度決策表 → 輸入機制決策表
• 安全敏感輸入框的 IME 控制 → IME 安全 checklist
• 表單場景的輸入設計 → 表單 UX 模式

章節文章

跨分類引用

• → 模組二：Shell 配置：shell 是終端機工具的載體，配置拆分邏輯相通
• → 模組六：桌面 Rice 設計：配色系統的統一管理從 terminal 延伸到桌面

觀察

app_tunnel 的 AnsiParser 負責解析終端機輸出的 ANSI escape 序列，轉換為帶色彩的文字 token。unit test 用手寫字串驗證：

1// 測試資料範例 — 乾淨的 SGR 色彩碼
2test('紅色文字', () {
3  final tokens = parser.parse('\x1B[31mhello\x1B[0m');
4  expect(tokens.first, isA<TextToken>());
5});

真實 zsh prompt 啟動後送出的控制序列（擷取自實機 log）：

1\x1B]0;user@host: ~\x07          ← OSC：設定終端機視窗標題
2\x1B[?2004h                      ← CSI private mode：啟用括號貼上模式
3\x1B[?1h                         ← CSI private mode：啟用應用程式游標鍵
4\x1B(B                           ← 字元集指定：選擇 ASCII
5\x1B[?25l                        ← CSI private mode：隱藏游標

Parser 只認識 \x1B[{數字;數字}{字母} 格式的標準 CSI，其他全部殘留在輸出中。

判讀

1. 測試資料的代表性是隱性假設。18 個 test 的斷言都正確 — \x1B[31m 確實應該產生紅色 token。但「測試輸入能代表真實輸入」是一個未經驗證的假設。真實 zsh 的輸出包含 5+ 種 escape 序列類型，測試只覆蓋了 1 種。

2. Parser 的行為對未知序列是「透傳」而非「報錯」。這是合理的設計 — 不認識的序列不應該讓 parser 崩潰。但透傳的後果是亂碼靜默出現在畫面上，不觸發任何錯誤或 log，開發者在 unit test 環境完全不會察覺。

3. 手寫測試資料 vs 錄製真實資料。如果測試資料是從真實 shell session 錄製的（capture 一次真實 zsh 啟動輸出），OSC 和 CSI private mode 會自然出現在測試輸入中，parser 的透傳行為會在 test 階段就被看到。

策略

1. 從真實環境錄製測試資料：用 script 命令或 WebSocket log 錄一次真實 shell session 的完整輸出，作為 integration test 的輸入。即使不改 parser 邏輯，至少能看到「哪些序列被透傳了」。
2. Parser 對未知序列記 warning log：透傳是合理的 fallback，但加一行 developer.log('Unknown escape: ${escape.codeUnits}') 讓開發者知道有未處理的序列。
3. 測試分兩類：「功能正確性」用手寫乾淨字串；「環境相容性」用錄製的真實輸出。兩類測試回答不同問題。

下一步路由

• 想理解測試資料代表性 → Test data 代表性
• 想建 protocol integration test 用真實 ttyd 輸出 → 模組三：協議整合測試
• 類似案例（mock 遮蔽） → T.C1 WS frame type mock 遮蔽

觀察

app_tunnel 的 Terminal 畫面在 W2 修復前沒有任何文字輸入元件。使用者只能透過底部工具列的特殊鍵（Esc/Tab/Ctrl/方向鍵）操作終端機，無法打字。

W2-001 修復時加入的 TextField 及其參數：

1TextField(
2  keyboardType: TextInputType.visiblePassword,   // 避免自動校正
3  enableSuggestions: false,                       // 關閉建議列
4  autocorrect: false,                             // 關閉自動校正
5  enableIMEPersonalizedLearning: false,           // 關閉 IME 個人化學習
6  onSubmitted: _submitInput,                      // Enter 送出整行
7  textInputAction: TextInputAction.send,          // 鍵盤顯示「傳送」
8)

每個參數都是一個設計決策，但沒有一個是事前規劃的 — 全部是寫 code 時臨時判斷。

判讀

1. 輸入設計影響 UI layout 和 protocol。onSubmitted（整行送出）vs 逐字元即時送出不只是 UI 問題 — 整行送出代表 protocol 層送的是 command\n，逐字元送出代表每個按鍵都是一個 WS frame。這個決策應該在 protocol spec 階段就做，因為它影響 server 端的行為預期。

2. IME 控制有安全意涵。enableIMEPersonalizedLearning: false 不只是 UX 偏好 — CLI 輸入可能包含資料庫密碼、API key、伺服器路徑。IME 學習這些內容等於把 secret 存到了 IME 的詞庫裡，跨 app 可用。這是安全問題，不是 UX 問題。

3. 事後 hotfix 的六個參數每個都有 gotcha。如果這些決策在企劃階段做，可以寫成決策表並在 code review 時對照。事後 hotfix 時開發者可能漏掉其中一兩個（例如只加 autocorrect: false 但忘了 enableIMEPersonalizedLearning: false），漏掉的那個就成為安全漏洞。

策略

1. 功能規格新增「輸入機制決策表」：keyboard type / submit model / IME policy / special keys 四個維度，每個列出選項和取捨理由。
2. 輸入機制跟 protocol 一起設計：「整行送出」還是「逐字元」決定了 WS 訊框的設計，必須在 protocol spec 階段決定。
3. 安全敏感參數強制列入 review checklist：enableIMEPersonalizedLearning、autocorrect 在處理 secret 的輸入框中是安全要求，不是可選項。

下一步路由

• 想設計 mobile 輸入機制 → 輸入機制決策表
• 想看 protocol 跟輸入的關聯 → T.C1 WS frame type（sendData 的型別決策）
• 想做安全審查 → 待補：CLI 輸入安全 checklist

使用者連上遠端終端機後、無法返回首頁。

這是設計遺漏。Terminal 畫面的 connected 狀態沒有 disconnect 按鈕也沒有 back 按鈕。error 和 disconnected 狀態也沒有。使用者被困在畫面裡，唯一的出路是殺掉 app。

這不是「忘記加按鈕」的問題。回頭看企劃文件，操作盤點段確實列了「連線失敗顯示無法連線」這個失敗情境，但沒有系統性地問：這個畫面有幾個狀態？每個狀態能做什麼操作？怎麼離開？

本文整理畫面狀態機設計的方法、示範用狀態矩陣捕捉導航缺口、歸納 mobile app UX 的三個設計原則。

實際案例：Terminal 畫面的五個狀態

Terminal 畫面有一個 TerminalScreenUiState enum 定義了五個狀態：

1enum TerminalScreenUiState { idle, connecting, connected, error, disconnected }

實機測試前、這五個狀態各自的 UI 長這樣：

五個狀態、零個退出路徑。使用者一旦進入 Terminal 畫面就出不去。

問題不在按鈕、在設計方法

加 back 按鈕是 5 分鐘的事。真正的問題是：企劃階段沒有工具強制你為每個狀態想退出路徑。

操作盤點表長這樣：

「前端引導」只有一句話。它沒有被展開成畫面狀態。「連線失敗顯示無法連線」這句話覆蓋了 error 狀態的顯示，但沒有回答操作（重連？返回？）和退出（怎麼離開這個畫面？）。

畫面狀態矩陣

把狀態機設計變成一張表，強制回答每個狀態的四個面向：

表格的威力在「退出路徑」欄位：如果這格是空的，這就是一個 UX 死胡同。

三個 Mobile App UX 設計原則

從這個案例提煉出的三個原則，適用於所有 mobile app：

原則 1：每個畫面的每個狀態都需要退出路徑

沒有例外。即使是「connecting」這種過渡狀態，使用者也可能想取消。iOS 的 HIG 和 Material Design 都要求 modal 畫面提供 dismiss 機制 — 如果使用者進不了某個狀態的下一步（連線失敗、timeout、服務無回應），他至少得能退出。

反模式：假設使用者只走 happy path。「connected 之後使用者不會想回首頁」是開發者的假設，不是使用者的需求。

原則 2：Gate 必須有 fallback

Gate = 使用者必須通過的關卡（biometric、network、auth）。每個 gate 的設計不只是「成功時怎麼做」，還包含「失敗時的替代路徑」。

biometricOnly: true 就是缺少 fallback 的典型案例 — Face ID 不可用（戴口罩、光線差、指紋模糊）時使用者直接被擋住，沒有替代方案。改為 biometricOnly: false 讓系統提供密碼 fallback。

原則 3：輸入機制是設計產物，不是實作細節

「手機打字操作 CLI」的輸入設計決策比想像的多：

這些決策在企劃階段就應該做，因為它們影響 UI layout（是否需要輸入框？工具列放什麼鍵？）和 protocol 設計（逐字元還是整行？）。事後補的 TextField 參數列表（enableSuggestions: false, autocorrect: false, enableIMEPersonalizedLearning: false）全是散落的 hotfix，不是設計產物。

系統性方法：從操作盤點到畫面狀態矩陣

操作盤點是 BDD 的起點（使用者做什麼、成功時發生什麼、失敗時發生什麼）。但盤點到「前端引導」就停了 — 它回答了「顯示什麼」但沒回答「能做什麼」「怎麼離開」。

補上的步驟：

1. 從操作盤點列出所有畫面：每個操作涉及哪些畫面？（首頁 → 配對畫面 → QR 掃描 → 終端機畫面）
2. 每個畫面列出所有狀態：這個畫面有哪些 enum 值或邏輯分支？
3. 填畫面狀態矩陣：顯示 / 可用操作 / 進入條件 / 退出路徑。退出路徑欄位為空 = UX 死胡同
4. 每個 gate 標注 fallback：biometric / network / auth 各有什麼替代方案？
5. 輸入機制列決策表：keyboard type / submit model / IME policy / special keys

這是操作盤點本來就該產出的下一層。一張表能在 10 分鐘內暴露所有 UX 死胡同，省掉實機測試才發現的成本。

延伸閱讀

本文的觀察和判讀在 UX Design 畫面設計 教學系列中展開為系統性的教學模組：畫面狀態矩陣的定義與填寫方法、Gate 分類與三問設計法、輸入機制決策表。

遠端伺服器優先選 tmux 的理由是可用性。它幾乎是事實標準，多數 Linux 發行版的套件庫都有、很多伺服器甚至預裝。zellij 功能新、畫面提示友善，但通常要自行安裝；在不能隨意裝套件的機器上，tmux 處處可用就是決定性優勢。兩者的取捨在最後一節展開。

本文承接 終端機圖形化工具總覽 的多工器分類，聚焦 tmux 在遠端情境的實際操作。

持久化工作流：detach 與 reattach

tmux 對遠端最重要的能力是 session 持久化：session 跑在伺服器上，跟當前這條 SSH 連線無關，所以主動離開或被動斷線後它都還在。這條工作流由四個指令構成。

關鍵在於被動斷線與主動 detach 的結果相同：手機從 Wi-Fi 切到行動網路、SSH 連線逾時、筆電闔上，這些情況下 tmux session 都留在伺服器上，重連後 tmux a 就接回去。判讀訊號很單純：任何超過幾秒、不想因斷線重來的工作（build、資料遷移、tail -f 追 log、跑測試），開始前先進 tmux。

prefix key：tmux 操作的入口

tmux 的所有指令都以 prefix key 起手，預設是 Ctrl-b。操作方式是按下 Ctrl-b 放開、再按功能鍵，而不是同時按住。理解這個「兩段式」是上手 tmux 的第一道門檻；若按住不放或間隔太久而沒反應，多半是兩段式沒按對，重來一次即可。

window 與 pane 是兩個層級：window 是整頁工作區（類似分頁），pane 是一個 window 內切出的子區塊。遠端開發常見的佈局是一個 window 切成數個 pane，一個跑編輯器、一個跑 tail -f、一個留著敲指令。捲動歷史要先進 copy mode（prefix 後按 [），用方向鍵或 PageUp 往回看，按 q 離開 — 這是初學最容易卡住的點，因為進了 tmux 後終端機原本的捲動行為改由 tmux 接管。

遠端與手機的調校

tmux 預設設定對手機與慢速連線不夠順，幾項調整能明顯改善體感，全部寫在 ~/.tmux.conf。

prefix key Ctrl-b 在手機虛擬鍵盤上難按，常見的調整是改綁成 Ctrl-a（更靠近鍵盤左側）：

1# ~/.tmux.conf
2unbind C-b
3set -g prefix C-a
4bind C-a send-prefix

滑鼠支援讓觸控裝置能直接點選 pane 與捲動，在手機與平板特別有用：

1# ~/.tmux.conf
2set -g mouse on

頻寬層面，tmux 本身傳輸的是純文字、量很低，斷線重連的成本也小。真正吃頻寬的是跑在 tmux 裡的全螢幕 TUI（例如 btop）的高頻重畫 — 這要調的是那個工具自己的刷新率，而非 tmux。改完設定檔後，在既有 session 內用 prefix 後按 : 輸入 source-file ~/.tmux.conf 重新載入。

tmux 與 zellij 的選型對照

tmux 與 zellij 解決同一類問題，session 持久化是兩者共有的基本能力（zellij 甚至內建 resurrection），真正的選擇依據是可用性與上手成本。

選型分界很清楚：受限或陌生的伺服器、要求處處可用，選 tmux；自己掌控的機器、想要友善的上手體驗與內建 layout，選 zellij。對 prefix 快捷鍵還不熟的人，這條分界仍成立：在別人的伺服器上工作優先學 tmux，因為無法保證對方裝了 zellij，可用性約束高於上手體驗；zellij 的友善體驗留給自己能掌控安裝的機器。兩者的指令心智模型相近（都靠一個 prefix/modifier 起手），學會一個再換另一個成本不高。zellij 路線的實際操作在本資料夾另有兩篇：pane 的 CLI 操作見 Zellij 多終端機操作指南、瀏覽器遠端連線見 Zellij Web Client 外網連線教學。

下一步路由

• 在多工器的 pane 裡擺即時監控：見 TUI 監控工具。
• zellij 的進階用法：Zellij 多終端機操作指南 與 Zellij Web Client 外網連線教學。
• 多工器在三類遠端工具中的定位：終端機圖形化工具總覽。

安裝 Zellij

1# macOS
2brew install zellij
3
4# Linux（使用安裝腳本）
5bash <(curl -L zellij.dev/launch)
6
7# Windows（需要支援原生 Windows 的版本，詳見 GitHub Releases）
8# 從 https://github.com/zellij-org/zellij/releases 下載 Windows 版 .zip
9# 解壓後將 zellij.exe 加入 PATH

確認版本（需 v0.43.0 以上）：

1zellij --version

事前準備

• 一個網域名稱（或固定 IP）
• SSL 憑證（對外連線強制要求）
• SSH 連線能力（如需遠端操作主機）→ 參考 SSH Key 設定筆記

步驟一：取得 SSL 憑證

外網連線強制使用 HTTPS，必須提供 SSL 憑證。

取得 Let’s Encrypt 憑證的 certbot 指令需真實網域、本機未實機驗證；自簽憑證的 openssl 指令、以及 zellij web server 啟停與 token 管理已在 localhost 實機驗證。

使用 Let’s Encrypt（免費，推薦）

需要先安裝 certbot：

1# macOS
2brew install certbot
3
4# Ubuntu / Debian
5sudo apt install certbot
6
7# Windows（使用 Chocolatey）
8choco install certbot
9# 或使用 win-acme（Windows 原生替代方案）：https://www.win-acme.com/

申請憑證（將 your-domain.com 換成實際網域）：

1sudo certbot certonly --standalone -d your-domain.com

Windows 上若未使用 WSL，建議改用 win-acme，操作更直覺。

憑證預設存放在：

1# macOS / Linux
2/etc/letsencrypt/live/your-domain.com/fullchain.pem   # 憑證
3/etc/letsencrypt/live/your-domain.com/privkey.pem      # 私鑰
4
5# Windows（certbot）
6C:\Certbot\live\your-domain.com\fullchain.pem
7C:\Certbot\live\your-domain.com\privkey.pem

使用自簽憑證（測試用）

1openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

注意：自簽憑證會讓瀏覽器在連線時顯示安全警告，於測試環境手動選擇繼續即可；正式對外服務改用上面的 Let’s Encrypt 憑證。

步驟二：開放防火牆 Port

Zellij web server 預設只綁本機 127.0.0.1:8082，要讓外網連入必須顯式綁到對外位址（見步驟四的 --ip 0.0.0.0）並開放對應 port。本教學以 port 3000 為例（port 可自選），需對外開放這個 port：

以下防火牆指令（ufw / pf / Windows Defender）依各平台官方用法、環境特定、本機未實機驗證。

Linux（ufw）

1sudo ufw allow 3000/tcp
2
3# 或指定來源 IP（更安全）
4sudo ufw allow from 1.2.3.4 to any port 3000

macOS

macOS 內建的防火牆是應用程式層級的，無法直接開放特定 port。通常有兩種做法：

1. 系統偏好設定 → 網路 → 防火牆 → 確認沒有擋住 Zellij
2. 使用 pf（進階，通常不需要）：

1# 新增規則到 /etc/pf.conf
2echo "pass in proto tcp from any to any port 3000" | sudo tee -a /etc/pf.conf
3sudo pfctl -f /etc/pf.conf

macOS 預設防火牆通常不會擋住主動開啟的服務，多數情況下不需要額外設定。如果是在家用網路，記得在路由器設定 port forwarding。

Windows

1# 使用 Windows Defender Firewall（以系統管理員執行 PowerShell）
2New-NetFirewallRule -DisplayName "Zellij Web" -Direction Inbound -Protocol TCP -LocalPort 3000 -Action Allow
3
4# 或限制來源 IP（更安全）
5New-NetFirewallRule -DisplayName "Zellij Web" -Direction Inbound -Protocol TCP -LocalPort 3000 -RemoteAddress 1.2.3.4 -Action Allow

Zellij 已支援原生 Windows，直接在 PowerShell 或 Windows Terminal 中執行即可。

如果是雲端主機（AWS、GCP、Azure 等），記得同步在後台的安全群組開放 port 3000。

步驟三：啟動 Zellij

先啟動一個 Zellij session：

1zellij

步驟四：啟動 Web Server

在 Zellij 內，按 Ctrl+o 然後按 s 開啟 share plugin，從 UI 啟動 web server。

或直接用 CLI 啟動並指定憑證：

1zellij web \
2  --ip 0.0.0.0 --port 3000 \
3  --cert /etc/letsencrypt/live/your-domain.com/fullchain.pem \
4  --key /etc/letsencrypt/live/your-domain.com/privkey.pem

背景執行（daemon 模式）：

1zellij web -d \
2  --ip 0.0.0.0 --port 3000 \
3  --cert /path/to/cert.pem \
4  --key /path/to/key.pem

停止 web server：

1zellij web --stop

確認 web server 執行狀態：

1zellij web --status

Zellij web 預設綁 127.0.0.1:8082、只接受本機連線；對外服務必須用 --ip 0.0.0.0 顯式綁到對外位址、並用 --port 指定埠（本教學用 3000）。改用其他 port 時把 --port 一併調整（例如 --port 8443），防火牆規則也要同步改成該 port。

步驟五：產生登入 Token

為了安全，別人連線前需要用 token 登入，token 只會顯示一次，請立即複製。

1zellij web --create-token

或在 share plugin（Ctrl+o + s）裡產生。

將 token 分享給要連線的人。

步驟六：連線

對方在瀏覽器輸入：

1https://your-domain.com:3000/實際-session-名稱

首次連線會要求輸入 token，驗證後即可進入 session。若連線後畫面沒有回應，多半是 port 未對外開放，確認防火牆與雲端主機安全群組是否放行該 port。

連線後的行為

多人連線時，每個人都有自己的游標，可以同時操作。

安全建議

• Token 用完後記得撤銷：從 share plugin 或 CLI 管理
• 盡量限制開放的來源 IP，避免對全網開放
• 不建議長期開啟 web server，用完就關
• 撤銷 token 時，所有對應的 session token 也會一併失效

下一步路由

• zellij 的本機 pane 操作（查看佈局、讀取其他 pane、調整大小）：Zellij 多終端機操作指南。
• 不需要瀏覽器、純 SSH 的多工器持久化：tmux 基礎。
• 多工器在整個遠端工具選型中的定位：終端機圖形化工具總覽。

查看整體佈局

1zellij action dump-layout

會輸出完整的 KDL 格式佈局，包含所有 pane 的大小、位置、指令等資訊。

讀取其他終端機 pane 的內容

Claude 無法直接看到螢幕，但可以透過以下步驟讀取其他 pane 的輸出：

 1# 1. 切換 focus 到目標 pane（focus-next-pane 會依序切換）
 2# 2. dump 該 pane 的螢幕內容到檔案
 3# 3. 切回原本的 pane
 4# 4. 讀取 dump 的檔案
 5
 6zellij action focus-next-pane && \
 7zellij action focus-next-pane && \
 8zellij action dump-screen /tmp/zellij-pane-output.txt && \
 9zellij action focus-previous-pane && \
10zellij action focus-previous-pane

• dump-screen 只 dump 當前可見的內容
• dump-screen -f 會包含完整的 scrollback 歷史
• 切換次數取決於目標 pane 的位置，需根據 dump-layout 的結果判斷

調整 pane 大小

1# 縮小當前 pane（向左縮）
2zellij action resize decrease right
3
4# 放大當前 pane（向右擴）
5zellij action resize increase right
6
7# 每次約改變 ~4-5% 寬度，可用迴圈批次調整
8for i in $(seq 1 3); do zellij action resize decrease right; done

每次的步長是經驗值、不是固定比例 — zellij 的 resize 幅度依版本與 pane 當前尺寸而定，迴圈次數需視 dump-layout 的結果微調。

使用者的 Resize 快捷鍵

1. Ctrl + n 進入 Resize 模式
2. h/l 或方向鍵調整大小
3. Esc 退出

注意：在 Claude 互動式程式內，快捷鍵可能被吃掉，建議讓 Claude 用指令操作。

注意事項

• Ctrl + p 進入 Pane 模式，其中 r 用於在右邊新開 pane（調整大小是 Ctrl + n 的 Resize 模式）
• 使用者的典型佈局：左側 Claude（~35%），右側上下兩個終端機

下一步路由

• 把 session 分享給沒有 SSH 連線的協作者（瀏覽器連入）：Zellij Web Client 外網連線教學。
• 純 SSH 的多工器持久化與 tmux 對照：tmux 基礎。
• 多工器在遠端工具選型中的定位：終端機圖形化工具總覽。