CodeNomad 项目与工作树
项目标签页将 CodeNomad 连接到后端计算机上的文件夹。打开标签页、浏览检出目录和移动对话族是不同的操作。
打开项目
- 点击新建实例（
+）打开主页。 - 选择浏览文件夹，选择后端文件夹并打开；或选择最近的文件夹下的条目。
- 若需仓库副本，选择克隆 Git 仓库，输入仓库 URL 和目标文件夹，然后选择克隆。
浏览远程服务器意味着浏览该服务器的文件系统，而非你的手机或笔记本电脑。打开项目不会为每个标签页创建独立的 OpenCode 守护进程。对话是原生 OpenCode 会话；其生命周期不等于标签页的生命周期。
克隆会将仓库写入目标位置。**如果目标文件夹已存在，先将其删除。**具有破坏性：仅在其中所有现有内容都可以删除时启用。不确定时请使用新目标位置。克隆失败不是删除现有项目的理由；重试之前先检查报告的目标位置和错误。
最近条目只是快捷方式。重命名工作区更改显示名称；从最近列表移除仅移除快捷方式，不会删除文件或对话。点击已打开的最近项目会打开新标签页；其已打开按钮（切换到已打开的项目）则会选择现有标签页。
使用新建实例启动器
- 长按或右键点击
+；键盘焦点位于此处时，使用 Alt+Down、Shift+F10 或 Menu 键。 - 搜索最近项目，或选择浏览…、临时或克隆…。
普通点击仍会打开完整主页。启动器是快捷入口，而非管理界面：请在主页重命名/移除最近项目和管理服务器书签。Escape 会关闭启动器并将焦点返回 +。
关闭标签页以关闭项目
- 使用标签页关闭按钮或命令面板中的关闭标签页（渲染器中为
Ctrl/Cmd+W）。 - 关闭标签页会在 CodeNomad 中关闭该项目：不再跟踪其事件和请求。会话继续在 OpenCode 中运行。
- 通过浏览或最近项目重新打开文件夹，即可再次找到这些会话。
| 操作 | 范围和影响 | 不会执行的操作 |
|---|---|---|
| 关闭标签页 | 移除该标签页的 CodeNomad 项目连接；在同一文件夹上单独打开的其他标签页不受影响 | 不会删除项目文件或原生历史记录，不会停止会话，也不会卸载 OpenCode 的 Location |
| 停止会话 | 所选对话的执行 | 不会关闭项目或删除历史记录 |
若另一窗口显示的是同一个项目连接，其标签页也会关闭，并且该窗口会显示通知；发起关闭的窗口不显示通知。关闭会立即生效；如果后端无法关闭该项目，会显示错误，主页上的切换到已打开的项目仍可访问它。不会自动重试。已关闭标签页中的未发送草稿不会保留在启动恢复中。
关闭整个窗口、退出或重新加载不会关闭其项目连接；正常的启动恢复仍然适用。如需确认执行已结束，请显式停止相关运行。CodeNomad 绝不会卸载原生 Location；共享服务维护请参阅 OpenCode 设置。
临时工作区
- 在启动器中选择临时，或在主页选择新建临时实例。
- 在 CodeNomad 管理的空文件夹中工作；不会自动初始化 Git。
- 关闭标签页时，选择保留、丢弃或取消。标签页菜单还提供保留为项目。
| 选择 | 影响 | 恢复方式 |
|---|---|---|
| 保留 | 在 CodeNomad 中关闭该项目，保留文件夹和对话，移除临时状态并添加到最近项目 | 从最近列表重新打开；文件夹不会移动 |
| 丢弃 | 删除临时工作区的对话和文件 | 无法撤销；请先将所需内容另存到其他位置 |
| 取消 | 保持临时工作区打开 | 继续工作或稍后决定 |
没有对话、文件或未发送草稿的未使用临时标签页会在关闭时静默丢弃。打开的临时标签页参与正常的启动恢复，但主页没有单独用于恢复已关闭临时文件夹的列表。
对话正在运行或文件夹在其他标签页/窗口打开时，会拒绝丢弃。请先停止运行并关闭其他视图。丢弃失败时仍保留临时状态：请解决报告的问题后重试，不要手动删除父目录。
选择或创建工作树
- 打开父对话并使用其输入框中的工作树选择器。窄布局下它仅显示箭头。
- 选择已发现的现有工作树，或选择 + 创建 worktree。
- 创建时输入名称并选择创建并使用 worktree。
CodeNomad 通过 OpenCode 发现工作树，并验证它们属于打开的仓库。新分支名从所选检出目录的 HEAD 开始。现有分支名使用该分支的当前修订；Git 可能拒绝已在其他位置检出的分支。工作树使用默认 .codenomad/worktrees 位置。未提交更改仍留在原检出目录；创建不会将它们复制到新工作树。
输入框选择器会将父对话及其递归后代作为经过验证的会话族移动。子会话无法独立更改此选择器。活动会话会阻止该操作：请先等待会话族完成或停止执行。等待移动完成后再请求下一次移动；出错时，请先检查刷新的对话/工作树状态再重试。
相比之下，文件中的浏览工作树只更改面板读取哪个检出目录。它不会移动对话、切换分支或更改下一条 Shell 命令的运行位置。
移除工作树
- 在输入框工作树列表中，对可移除的分支工作树使用删除 worktree。
- 检查目标文件夹。除非允许丢失本地更改，否则不要开启强制删除（丢弃本地更改）。
- 确认删除并检查结果列表。
删除会移除工作树的本地文件夹。Git 主检出目录不是可移除目标。CodeNomad 会将受影响的对话族移回根检出目录，验证位置后才移除工作树；活动会话可能阻止移除。删除不是未提交文件的归档或备份。
如果 Git 因已修改/未跟踪文件而拒绝，请先保留或清理这些文件再重试。强制删除会明确丢弃它们。目录被锁定时，请关闭使用它的终端、编辑器、监视器和后台进程。记录缺失时，请先刷新工作树并检查路径再重试。共享诊断信息时，错误对话框提供复制脱敏内容；即使已脱敏，也请先检查文本。
初始化 Git 或在没有 Git 时工作
- 对于 Git 可用的普通文件夹，打开文件 → 更改或提交。
- 选择初始化 Git。它会立即执行，不再额外确认。
- 等待项目元数据和对话刷新；若在 CodeNomad 外初始化 Git，请使用刷新。
初始化会在显式打开的文件夹中创建仓库，而非其父目录。它不会创建提交。失败时，请先查看消息并刷新再重试：不确定的回复不会自动重放。
如果后端无法运行 Git，显式打开的文件夹仍可在仅目录模式下使用对话和有界文件浏览。工作树操作和 Git 初始化要求该后端安装 Git。请参阅安装和文件。