> ## 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）
```

也就是说：**worktree 不是"另一种模式"，而是同一个项目下的第二个工作区。** 这正是可以一边在主分支干活、一边让 Agent 在隔离目录里试另一个方案的原因。

## 两种工作区模式

| 模式                | UI 上的叫法       | 行为                                              |
| ----------------- | ------------- | ----------------------------------------------- |
| `CurrentCheckout` | **本地** / 当前检出 | 文件和 Git 操作直接作用于主检出目录；多个会话可能看到同一份改动。             |
| `VibexWorktree`   | **Worktree**  | Vibex 创建托管 Git worktree，并提供合并、rebase、冲突处理和丢弃流程。 |

<Warning>
  在 **本地** 工作区里同时运行多个 Agent 时，它们可能修改同一个文件。需要并行尝试或评审时，改用 **Worktree**。
</Warning>

## 打开项目

1. 在侧栏点击 **新建项目**，或在 **新建会话** 页面使用 **项目目录**。
2. 在弹出的目录浏览器中选择仓库根目录（这是一个应用内浏览器，支持 `↑↓` 导航、`Enter` 打开、`⌘Enter` 在此选择、`⌘D` 收藏高亮行）。
3. 目录浏览器左侧的 **位置** 栏带一个 **收藏** 分组：收藏的文件夹按最新在前排列、最多十二个，在行内或栏内再次点击即可取消收藏。
4. 确认后 Vibex 会以 **本地** 模式打开该目录。

项目会长期保留在侧栏。右键项目可以定制图标、新建文件夹、开启 **自动继续**、导入会话或删除项目。

## 在项目下新建工作区

新建会话时，输入框上方的位置选择器提供两个选项：

* **本地** —— 在主检出目录上工作。
* **新建 Worktree** —— 创建隔离工作区。选择后会出现 **基准分支** 选择器（可搜索分支），以及 **Worktree 设置** 面板：
  * **Worktree 名称** —— 会据此推导出分支名 `vibex/<slug>`。
  * **路径** —— 必须是绝对路径。
  * **此项目默认新建 Worktree** —— 以后该项目默认新建 worktree。

## 切换工作区

侧栏的 **工作台 → 侧栏层级** 设为 **工作区视图** 时，项目下会列出各个工作区及其分支。

切换工作区不会把未提交改动复制到另一处。当前会话仍属于它创建时所在的工作区；切换前请保存文件并检查 Git 状态。

如果编辑器里还有未保存的缓冲区，Vibex 会先阻止切换并提示你保存或放弃。每次打开或切换工作区都会更新 generation，过期的文件、终端和 Git 请求会被拒绝，避免结果写入错误目录。

## Worktree 生命周期

| 状态      | 主要操作                                                   |
| ------- | ------------------------------------------------------ |
| **开发中** | **检查改动**                                               |
| **检查中** | **标记可合并**                                              |
| **可合并** | **合并** / **Rebase**（对应 `NoFfMerge` 与 `RebaseAndMerge`） |
| **排队中** | **检查合并**                                               |
| **已归档** | 恢复                                                     |

1. 创建时选择基础分支和名称。
2. 在隔离目录中启动会话或手动编辑。
3. 用 Git 面板检查改动，并按需提交。
4. 选择 **合并** 或 **Rebase**。出现冲突时逐文件处理（可对每个文件选择保留目标端或来源端），处理完点击 **标记已解决**。中途可以用 **中止合并** 放弃合并。
5. 确认结果后再丢弃 worktree。**丢弃会删除隔离目录和未提交改动。**

也可以对 worktree 执行 **重命名 Worktree** 和 **删除 Worktree**。

<Info>
  Worktree 的路径、分支和状态由权威运行时保存。移动端可以通过 Remote v2 请求这些操作，但实际执行始终发生在权威端。
</Info>

## 文件访问边界

* 文件树、内容搜索和编辑器只访问当前工作区范围。
* 文件服务会规范化路径并检查符号链接、编码、换行符和大小限制。
* Agent 的工具调用仍受权限和能力门控影响——打开工作区不等于自动授权所有操作。
* 终端默认绑定当前工作区，也可以在文件树里对某个路径选择 **Open In → 终端**。
* 远程请求还会携带工作区作用域和 generation；重连后以权威运行时重新读取的状态为准。

## 常见问题

### 为什么 Agent 看不到我刚创建的文件？

确认文件保存到了当前工作区，并刷新文件树或重新打开会话。如果文件在工作区之外，需要先移动到工作区内，或作为附件提供。

### 为什么 Git diff 没有显示改动？

检查是否切换到了另一个工作区或 worktree——`Local` 和 `Worktree` 是完全不同的目录。确认文件已保存，再在终端里运行 `git status --short` 对照。