專案與工作階段

專案複製連結

一個專案就是一件正在做的事——實際用起來通常就是一個儲存庫——有自己的終端機、分頁和面板狀態。

Cmd+N 新建一個，裡面帶一個終端機。這個終端機從當前工作階段的目錄啟動；如果沒有當前工作階段，就從你的使用者家目錄啟動，所以接下來通常是 cd 到目標位置。剩下的 Zshell 會接手：檔案樹和 git 面板會錨定到包含那個目錄的儲存庫上。

想省掉這次 cd，在 Finder 裡右鍵一個資料夾，選 服務 → New Zshell Project Here——它會作為一個專案打開，終端機已經在裡面啟動好了。

專案是 Zshell 切換的基本單位：

專案的名字來自它當前選中的工作階段——也就是說，它跟著終端機走，和分頁標題一樣。右鍵側邊欄裡的專案，可以 Rename…（Use Automatic Title 撤銷）、Set Project Directory… 和 Close Project。關閉專案會結束它的工作階段，但不會動磁碟上的任何東西。

遠端共用工作階段採用不同的關閉方式：關閉窗格或專案只會分離此用戶端，主機的 shell 與工作繼續執行。

儲存 SSH 專案複製連結

打開指令面板（Cmd+P），選擇 新建 SSH 專案…。填寫主機、 可選的使用者名和連接埠，以及要打開的遠端目錄。認證方式可選 SSH 代理、密碼、 私鑰檔案或私鑰內容；儲存連線後，選中它並點擊 連線。

儲存的連線會在重新啟動後保留。可選的 分組 字段用於整理連線列表，每條連線旁邊的編輯、 刪除按鈕用於維護條目。密碼和貼上的私鑰儲存在 macOS 鑰匙串中；選擇私鑰檔案時，記錄的是 已有密鑰檔案的路徑。

經常執行的指令或需要附加 SSH 選項的啟動項，可以使用快速啟動。

側邊欄分組複製連結

點擊側邊欄底部的 新建分組，可以創建普通分組或資料夾分組。普通分組中新建的終端機從使用者家目錄啟動；資料夾分組提供選定的預設目錄。手動固定的專案目錄始終優先。移動專案到其他分組，不會改變正在執行的終端機，也不會覆蓋已固定的目錄。

把專案拖到分組標題或另一個專案上即可歸組，拖到側邊欄底部的 ＋（新建專案） 可以移出分組。分組標題之間也可以拖拽排序。單擊標題折疊或展開，雙擊重新命名，右鍵打開分組選單。通過 設定顏色標記… 自訂分組顏色，或用 移除顏色標記 清除。移除分組 會保留其中所有專案。數字快速鍵按當前可見專案的順序排列；上一項、下一項導航可以切到折疊組內的專案，並自動展開該組。

也可以從 Finder 把資料夾拖到側欄專案列表。已打開的資料夾會被選中，不會重復創建專案。

專案目錄複製連結

有兩個面板需要知道自己在顯示哪個資料夾：檔案樹和 git 面板。預設情況下 Zshell 自己判斷—— 它從終端機的當前目錄出發，往上找到最近的那個包含它的 git 儲存庫。

所以在儲存庫裡 cd 來 cd 去，檔案樹不會跟著跳：儲存庫根目錄始終是根目錄。不在儲存庫裡時，這兩個面板就單純跟著終端機走。

如果前台程式進入了另一個 checkout——比如 agent 切進自己的 Git worktree——檔案、Git 和資訊面板會跟著那個 checkout，前台任務回來時再恢復。手動固定的專案目錄始終優先，也會關閉這種自動換根。

想固定住，右鍵專案選 Set Project Directory…。固定的目錄會跨重新啟動記住，Use Automatic Directory 則交還自動判斷。

工作階段複製連結

每個專案可以有任意多個工作階段，顯示為頂部的分頁。一個工作階段就是一個真正的登錄 shell—— zsh、fish、bash，你帳戶設成什麼就是什麼——各有自己的工作目錄和捲動歷史。

本地新工作階段優先從固定的專案目錄啟動，其次使用側欄分組的預設目錄。沒有這兩項時，它繼承當前工作階段的目錄，再回退到使用者家目錄。

分頁分組複製連結

右鍵分頁選擇 移動到分組 → 新建分頁分組。該標籤會加入新組，分組在標籤欄中僅顯示彩色箭頭，不顯示名稱。選中組內標籤後新建的工作階段會留在該組；右鍵分組箭頭選擇 在分組中新建工作階段，也可以直接在組內創建工作階段。

把標籤拖到分組箭頭或另一個標籤上即可移動。快速選單也可以選擇目標分組，或 移出分組。單擊分組箭頭折疊、展開。折疊時當前終端機仍會執行並繼續顯示；切換到隱藏的標籤會自動展開其分組。移除分組會保留所有標籤與工作階段。固定組內標籤時，該標籤會移到分組之外的固定區。右鍵分組箭頭可以 設定顏色標記… 或 移除顏色標記。分頁分組的顏色、折疊狀態都會在重新啟動後恢復。

標籤還可以拖到側欄已有專案，或拖到側欄分組標題，在該分組內創建新專案。拖到側邊欄底部的 ＋（新建專案） 會創建不屬於任何側欄組的新專案。快速選單的 移動分頁到專案 也支持其他視窗。移動會保留執行中的終端機和窗格佈局。目標專案必須具有相同的本地或 SSH 位置；從標籤創建新專案時會繼承來源位置。包含 Diff 的標籤保留在原專案中。

分頁標題複製連結

分頁標題來自終端機自己報告的內容——你 shell 提示符裡的轉義序列，或者當前正在跑的程式。右鍵分頁可以 Rename… 手動改名，Use Automatic Title 則回到跟隨終端機。

分頁選單裡其餘的是常規那一套：Close、Close Others、Close Tabs to the Right、 Close All，外加針對工作階段目錄的 Reveal in Finder 和 Copy Absolute Path。Close Files 與 Close Diffs 會清掉專案裡的對應內容，但保留終端機和瀏覽器窗格。

視窗複製連結

Cmd+Shift+N 新開一個視窗。視窗之間互相獨立——各自的專案、各自的側邊欄狀態——恢復時也是分開恢復的。

重新啟動後還剩下什麼複製連結

Zshell 會隨著你的操作持續快照佈局，所以退出再打開會拿回：

• 每個專案，順序不變
• 每個分頁，包括自訂名稱、固定狀態和顏色標記
• 側邊欄分組的名稱、顏色標記、順序、成員和折疊狀態
• 分頁分組的顏色標記、順序、成員和折疊狀態
• 固定的專案目錄和空專案
• 每個分頁裡的窗格佈局
• 哪些側邊欄是打開的、右側選中的是哪個面板

原終端 PTY 不可用時，若啟用了 恢復 Agent 對話 和 AI 支援，Zshell 會繼續已驗證的 Claude Code、Codex、Pi 或 OpenCode 原對話。其他窗格在原目錄開啟新 shell。對話依原身分恢復；Zshell 不會重播命令來恢復執行中的建置。

開啟 terminal.restore-history 時會恢復之前的捲動歷史。 新配置預設開啟；恢復的捲動歷史會儲存在磁碟上。

終端機環境與初始化指令複製連結

選中專案後，通過 Terminal → Project Terminal Environment… 配置專案環境變數和初始化指令。 要只修改當前分頁，使用 Terminal → Tab Terminal Environment…。

儲存後只影響之後創建的終端機，已經執行的程序不變。初始化指令僅用於正常的登錄 shell；自訂啟動程式或顯式傳入 argv 時不執行。 ZSHELL_*、TERM、COLORTERM、TERM_PROGRAM 和 TERM_PROGRAM_VERSION 由 Zshell 管理，不能覆蓋。