> ## Documentation Index
> Fetch the complete documentation index at: https://vibex.peatboy.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 專案與工作區

> 選擇、切換和隔離 Vibex 的檔案、Git 與 Agent 工作範圍。

**專案**是你在 Vibex 裡註冊的一個資料夾；**工作區**是“以某種方式使用這個專案”。一個專案下可以同時存在多個工作區。

工作區是 Vibex 讀寫檔案、執行終端機和執行 Git 操作的邊界。權威執行階段儲存工作區後設資料和當前選擇；Agent 能看到的檔案範圍也由工作區決定。

## 層級關係

```text theme={null}
專案（Project）
├── 工作區 Local（CurrentCheckout）    ← 直接在主檢出目錄工作
└── 工作區 Worktree（VibexWorktree）   ← 隔離目錄，可並存多個
        ├── 會話（Session）
        └── 會話組（Session group）     ← 同一 Worktree 下的多個會話
```

也就是說：**worktree 不是“另一種模式”，而是同一個專案下的第二個工作區。** 這正是可以一邊在主分支幹活、一邊讓 Agent 在隔離目錄裡試另一個方案的原因。

## 兩種工作區模式

| 模式 | UI 上的叫法 | 行為 |
| - | - | - |
| `CurrentCheckout` | **本地** / 當前檢出 | 檔案和 Git 操作直接作用於主檢出目錄；多個會話可能看到同一份改動。 |
| `VibexWorktree` | **Worktree** | Vibex 建立託管 Git worktree，並提供合併、rebase、衝突處理和丟棄流程。 |

> [!WARNING]
>
> 在 **本地** 工作區裡同時執行多個 Agent 時，它們可能修改同一個檔案。需要並行嘗試或評審時，改用 **Worktree**。

## 開啟專案

1. 在側欄點選 **新建專案**，或在 **新建會話** 頁面使用 **專案目錄**。
2. 在彈出的目錄瀏覽器中選擇倉庫根目錄（這是一個應用內瀏覽器，支援 `↑↓` 導航、`Enter` 開啟、`⌘Enter` 在此選擇、`⌘D` 收藏高亮行）。
3. 目錄瀏覽器左側的 **位置** 欄帶一個 **收藏** 分組：收藏的資料夾按最新在前排列、最多十二個，在行內或欄內再次點選即可取消收藏。
4. 確認後 Vibex 會以 **本地** 模式開啟該目錄。

專案會長期保留在側欄。右鍵專案可以定製圖示、新建資料夾、開啟 **自動繼續**、匯入會話或刪除專案。

## 臨時會話

新建會話時，位置選擇器提供 **臨時會話**。它不屬於任何專案：

* 適合一次性問題、試跑提示詞或不需要檔案訪問的任務。
* 仍然由同一個權威執行階段儲存，可以重新命名、分叉和歸檔。
* 需要讀寫工作區檔案或執行專案命令時，改為選擇專案或 Worktree。
* 臨時會話不能建立 Worktree。

## 在專案下新建工作區

新建會話時，輸入框上方的位置選擇器提供：

* **本地** —— 在主檢出目錄上工作。
* **新建 Worktree** —— 建立隔離工作區。選擇後會出現 **基準分支** 選擇器（可搜尋分支），以及 **Worktree 設定** 面板：
  * **Worktree 名稱** —— 會據此推匯出分支名 `vibex/<slug>`。
  * **路徑** —— 必須是絕對路徑。
  * **此專案預設新建 Worktree** —— 以後該專案預設新建 worktree。

建立後，Worktree 會出現在側欄的工作區視圖裡。可以從列表裡選擇已有 Worktree 繼續會話，也可以 **收尾** 一個不再需要的 Worktree。

## 切換工作區

側欄的 **工作台 → 側欄層級** 設為 **工作區檢視** 時，專案下會列出各個工作區及其分支。

切換工作區不會把未提交改動複製到另一處。當前會話仍屬於它建立時所在的工作區；切換前請儲存檔案並檢查 Git 狀態。

如果編輯器裡還有未儲存的緩衝區，Vibex 會先阻止切換並提示你儲存或放棄。每次開啟或切換工作區都會更新 generation，過期的檔案、終端機和 Git 請求會被拒絕，避免結果寫入錯誤目錄。

## Worktree 生命週期

| 狀態 | 主要操作 |
| - | - |
| **開發中** | **檢查改動** |
| **檢查中** | **標記可合併** |
| **可合併** | **合併** / **Rebase**（對應 `NoFfMerge` 與 `RebaseAndMerge`） |
| **排隊中** | **檢查合併** |
| **已歸檔** | 恢復 |

1. 建立時選擇基礎分支和名稱。
2. 在隔離目錄中啟動會話或手動編輯。
3. 用 Git 面板檢查改動，並按需提交。
4. 選擇 **合併** 或 **Rebase**。出現衝突時逐檔案處理（可對每個檔案選擇保留目標端或來源端），處理完點選 **標記已解決**。中途可以用 **中止合併** 放棄合併。
5. 確認結果後再丟棄 worktree。**丟棄會刪除隔離目錄和未提交改動。**

也可以對 worktree 執行 **重新命名 Worktree** 和 **刪除 Worktree**。行動端可以檢視每個受管 worktree 的狀態、選擇 worktree，並收尾一個 worktree；實際執行始終發生在權威端。

> [!NOTE]
>
> Worktree 的路徑、分支和狀態由權威執行階段儲存。行動端可以通過 Remote v2 請求這些操作，但實際執行始終發生在權威端。

## 會話組

會話組是同一 Worktree 下的會話集合，用來把多個 Agent 或分支放在一個任務下：

* 多選會話，右鍵 **新建會話組**。
* 組內可以 **分屏** 並排檢視，或 **合併窗格**。
* 組頭顯示團隊狀態和成員數量；摺疊的組會說明自己藏了多少會話。
* 組可以拖動到資料夾、與其他組換位，或拖回工作區根。
* 組內成員可以重排；拖到組外就移出組。
* **解散會話組** 不會刪除會話。

詳見[Agent 會話](https://vibex.peatboy.com/docs/zh-TW/sessions.md#會話組與分屏)。

## 歸檔

專案下的會話可以歸檔，歸檔後從側欄移出，但保留完整時間線：

* 會話行選單、多選選單和批次欄都可以歸檔。
* 資料夾行可以設定自動歸檔的空閒視窗（關閉，或 1–14 天）。
* **設定 → 已歸檔會話** 可以恢復或永久刪除。
* 歸檔是可逆的；刪除不是。

## 檔案訪問邊界

* 檔案樹、內容搜尋和編輯器只訪問當前工作區範圍。
* 檔案服務會規範化路徑並檢查符號連結、編碼、換行符和大小限制。
* Agent 的工具呼叫仍受權限和能力門控影響——開啟工作區不等於自動授權所有操作。
* 終端機預設綁定當前工作區，也可以在檔案樹裡對某個路徑選擇 **Open In → 終端機**。
* 遠端請求還會攜帶工作區作用域和 generation；重連後以權威執行階段重新讀取的狀態為準。

## 常見問題

### 為什麼 Agent 看不到我剛建立的檔案？

確認檔案儲存到了當前工作區，並重新整理檔案樹或重新開啟會話。如果檔案在工作區之外，需要先移動到工作區內，或作為附件提供。

### 為什麼 Git diff 沒有顯示改動？

檢查是否切換到了另一個工作區或 worktree——`Local` 和 `Worktree` 是完全不同的目錄。確認檔案已儲存，再在終端機裡執行 `git status --short` 對照。

### 為什麼會話組不能加入某個會話？

會話組只能包含同一個 Worktree 下的會話。先把會話移到目標 Worktree，或為它單獨建組。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.