入門指南

本指南將引導您從安裝開始，到使用第一個終端機，再到進行第一次 AI 代理會話。這些內容已足以讓您開始工作；各項功能的詳細說明則位於手冊系列的其餘部分（請參見 手冊概覽）。

1. 什麼是 VelaTerm

用一句話來說：這是一個為 AI 代理時代所打造的終端機管理工具。它將分散的終端機會話整理成 專案 → 群組 → 會話的樹狀結構，並將 Claude Code 和 Codex 等編碼代理視為一等公民——您可以即時查看它們是否正在運作、是否正在請求輸入，或是已經完成，且重新開啟會話時會自動繼續之前的對話。再加上瀏覽器遠端存取與 SSH 遠端開發功能，您便能從任何地方掌控自己的會話。

2. 安裝

請從 下載頁面取得適用於您平台的套件：

此應用程式會自動檢查更新（也有「檢查更新…」的選單項目），因此能隨時保持在最新版本。

3. 第一次啟動：匯入專案

首次啟動時，視窗是空的，左側邊欄會提示您匯入一個資料夾。請點擊邊欄頂端的資料夾按鈕（或按 ⌘O），選擇您正在使用的資料夾——它將成為樹狀結構中的第一個「專案」。您也可以使用「從 Git 克隆」功能，直接從儲存庫 URL 建立專案。

一旦有專案進入，您就可以在該專案下建立 群組（可任意深入嵌套，例如前端 / 後端 / 測試），並在群組內建立 會話。樹狀結構如下所示：

4. 開啟您的第一個終端機

可透過以下三種方式之一：

1. 按下 ⌘T（在 Windows/Linux 上為 Ctrl+Alt+T）——您會立即得到一個臨時的終端機分頁。終端機一律是草稿：它只存在於中央面板，不會加入樹狀結構，關閉後即被丟棄，也正因如此才適合用於快速輸入指令。
2. 在側邊欄把滑鼠移到專案、群組或會話那一列，點 ＋ 按鈕 → 「新建終端機會話」。建立出來的仍是同一種草稿，差別只在於它從該節點的工作目錄啟動。群組的右鍵選單裡也有這一項。
3. 當中央面板是空的時，直接點擊「建立終端機」按鈕即可。

5. 開啟您的第一個 AI 代理會話

在專案或群組上按右鍵 → 選擇「New Claude Session」（該選單還提供 Codex，其餘選項則位於「More Agent Session」下）。VelaTerm會在該專案的目錄中啟動Claude Code，並自動注入其狀態報告掛鉤：

從那一刻起，您將獲得三項功能：

• 狀態點：側邊欄中會話旁的小點能即時反映代理的狀態——綠色表示正在運作，黃色表示需要您的操作（如提問或授權請求），洋紅色表示它已回覆且您已看到回覆。不必再一一點擊視窗來查看狀態。
• 系統通知：當代理停止運作並等待您的輸入或確認時，您會收到系統通知；若您已正在查看該會話，則不會有通知。
• 自動續行：關閉分頁——或退出整個應用程式——下次再次打開該會話節點時，對話將從中斷處繼續。若想要全新的對話？請建立新的會話節點。

此功能的前提是已安裝對應的 CLI。若未安裝，也不會造成困擾：會話中會出現安裝指南卡片，提供適用於您平台的推薦安裝指令、一鍵安裝功能以及重試按鈕。

6. UI 導覽

• 左側側邊欄：專案樹狀結構 + 搜尋框 + 四個頂部按鈕（匯入專案、從 Git 克隆、全局搜尋、已歸檔的會話）。
• 中央區域：分頁列 + 終端區域。分頁的運作方式類似瀏覽器：預設情況下，點擊樹狀結構中的某個會話會重新使用當前分頁；您切換離開的分頁仍會在背景中持續運作；真正結束該流程的方式是關閉分頁。分頁也可以分割成多個區域（右鍵按 ⌘D，下鍵按 ⌘⇧D）。
• 右側面板：隨著當前會話變化，包含三個分頁——檔案（檔案樹狀結構）、資訊（基本資料、模型、使用量、資源佔用情況），以及 Git（分支與變更記錄）。
• 狀態列：顯示會話數量、當前會話狀態、Git分支、通知開關，以及全局的「正在運作」/「待處理」/「已查看」計數器——點擊其中一項即可將側邊欄過濾為該狀態的會話。
• 標題列右側：亮色/暗色主題切換、遠端存取、連線到遠端伺服器、設定。

7. 下一步該去哪裡

• 關於樹狀結構與分頁的完整說明（分割、歸檔、全局搜尋、多選批量操作）：Interface & Session Management。
• 終端功能（搜尋、貼上圖片、Windows shell 選擇）：Terminal Usage。
• 代理功能差異、續行/分叉/授權模式：AI Agent Sessions。
• 讓代理將子任務分割成獨立的作業樹並同時運作：Session Spawning & Git Collaboration。
• 將這些功能帶到手機或其他電腦上使用：Remote Development & Management。