Skip to main content
项目是你在 Vibex 里注册的一个文件夹；工作区是”以某种方式使用这个项目”。一个项目下可以同时存在多个工作区。 工作区是 Vibex 读写文件、运行终端和执行 Git 操作的边界。权威运行时保存工作区元数据和当前选择；Agent 能看到的文件范围也由工作区决定。

​
层级关系

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

​
两种工作区模式

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

​
打开项目

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

​
在项目下新建工作区

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

​
切换工作区

侧栏的 工作台 → 侧栏层级 设为 工作区视图 时，项目下会列出各个工作区及其分支。 切换工作区不会把未提交改动复制到另一处。当前会话仍属于它创建时所在的工作区；切换前请保存文件并检查 Git 状态。 如果编辑器里还有未保存的缓冲区，Vibex 会先阻止切换并提示你保存或放弃。每次打开或切换工作区都会更新 generation，过期的文件、终端和 Git 请求会被拒绝，避免结果写入错误目录。

​
Worktree 生命周期

  1. 创建时选择基础分支和名称。
  2. 在隔离目录中启动会话或手动编辑。
  3. 用 Git 面板检查改动，并按需提交。
  4. 选择 合并 或 Rebase。出现冲突时逐文件处理（可对每个文件选择保留目标端或来源端），处理完点击 标记已解决。中途可以用 中止合并 放弃合并。
  5. 确认结果后再丢弃 worktree。丢弃会删除隔离目录和未提交改动。
也可以对 worktree 执行 重命名 Worktree 和 删除 Worktree。
Worktree 的路径、分支和状态由权威运行时保存。移动端可以通过 Remote v2 请求这些操作，但实际执行始终发生在权威端。

​
文件访问边界

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

​
常见问题

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

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

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

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