第 5 章：Workspace 与 Worktree 生命周期
1. 为什么 Worktree 是 Orca 的产品原语
并行 Agent 最大的冲突不是“同时思考”，而是同时修改同一份 working tree。Git worktree 为每个任务提供：
- 独立工作目录；
- 独立 index 与 checkout；
- 共用对象数据库，创建成本低；
- 可单独提交、测试和开 PR。
Orca 在其上叠加任务链接、状态、终端、浏览器、编辑器、session 与 lineage，形成 workspace card。
2. 三种工作入口
导入已有 Git repo
main 验证路径、读取 remote、识别 fork/upstream，并建立 Project/Repo/HostSetup。
Clone 项目
repos.ts 管理 clone generation、进度解析、abort cleanup 和路径去重。远程 host 上的 clone 委托给 provider/runtime。
Folder workspace
普通目录不执行 git worktree add，但仍创建 FolderWorkspace 元数据与 workspace session。后续代码必须通过 WorkspaceScope 分流。
3. 创建 worktree 的主时序
本地桌面入口在 src/main/ipc/worktrees.ts，公共 runtime 入口最终调用 OrcaRuntimeService 中的 managed worktree 方法。
4. Base ref 的选择
创建新任务前需要决定从哪里分支。来源可能是：
- 用户显式
baseBranch； - linked PR/MR 的 base；
- repo 的
worktreeBaseRef； - remote default branch；
- 当前 parent workspace，用于 stacked work。
Orca 会预取和解析 remote tracking ref，并记录 fallback。这里不能简单用 main：fork 可能以 upstream 为权威，远端默认分支可能不同，SSH host 的 ref 状态也可能滞后。
5. Git capability 与兼容基线
Orca 以 Git 2.25 作为核心流程基线。对于新能力，使用行为探测和窄 fallback：
| 能力 | 新路径 | 兼容路径 |
|---|---|---|
worktree list -z | NUL 分隔 | 旧 line-block parser |
| rev-parse path format | 直接绝对路径 | 相对 repo 解析 |
| for-each-ref exclude | Git 侧过滤 | 多取后客户端过滤 |
| merge-tree write-tree | 精确冲突 | 保守省略 |
能力 cache 按 native / WSL distro / SSH provider 隔离。只看 git --version 不够，因为 wrapper、vendor backport 和实际执行 host 可能不同。
详见上游 git-compatibility.md。
6. Worktree 扫描与 metadata fallback
worktrees:list 并不直接返回 Store 里的数组：
- 找到正确 Git provider；
- 运行
git worktree list； - 解析 path、HEAD、branch、locked、prunable；
- 合并
WorktreeMeta； - 计算 ownership、visibility、linked task、lineage；
- 对 disconnected SSH 使用 metadata fallback。
扫描具有：
- in-flight coalescing；
- generation invalidation；
- TTL cache；
- 并发上限；
- provider timeout；
- “authoritative / metadata-fallback” 标记。
离线返回旧卡片是合理的，但必须标明非权威，不能据此执行删除等破坏操作。
7. External worktree 的可见性
Git 仓库可能包含由命令行或其他工具创建的 worktree。Orca 区分：
orca-managed；external；unknown-legacy；agent-scratch。
Repo 设置控制是否显示外部 worktree，并用 inbox baseline、显式 import 与 suppression 避免每次扫描都重新打扰用户。
这是“发现”与“管理”分离的例子：能扫描到不代表 Orca 自动取得删除和生命周期所有权。
8. Setup 与默认终端
Repo 可配置 setup/archive/issue hooks。创建后根据 policy 决定：
- 询问、默认运行或跳过；
- Agent 立即启动，还是等待 setup；
- setup 在新 tab、水平 split 或垂直 split 中运行；
- shared/local hook 的优先级。
setup 是工作区事务的一部分，但它本身运行在 terminal 中。创建 Git worktree 成功不等于 setup 成功，因此 UI 需要分别表示 checkout 与 setup 状态。
9. --agent 为什么要占第一个终端
CLI 的 worktree create --agent codex --prompt ... 会让 Agent 占据第一 terminal，避免先创建一个无用 fallback shell，再开第二个 Agent tab。
启动结果可返回 startupTerminal.handle。这个 handle 是 runtime-scoped；重启后客户端必须重新 list，不能继续向旧 handle 双写。
10. Folder workspace 的不同之处
Folder workspace：
- 不创建 branch；
- 不参与 Git worktree list；
- 路径直接归属 folder scope；
- 可绑定 task、状态、Agent 和 terminal；
- 仍需记录 connection/execution host；
- 可以成为 child worktree 的 lineage parent。
任何工作区通用功能都应先接收 WorkspaceScope，只有真正需要 Git 的内部步骤再缩窄到 worktree。
11. 删除为何是最危险的流程
删除会同时影响：
- PTY/Agent 进程；
- archive hook；
- 共享 symlink/copy；
- Git registration 与目录；
- metadata、lineage、session tabs；
- 远端 lease 与 provider state。
非 force 删除先做 clean preflight。理由很现实：旧顺序是先杀 PTY，再执行 git worktree remove；若 Git 因 dirty/untracked 拒绝，目录留下了，但用户的 Agent 已死。
正确顺序：
SSH-backed repo 的删除仍由 SSH provider 拥有，本地 preflight 不能越权运行。
12. 并发与幂等
创建/删除需要处理：
- 同一路径的重复请求；
- clone/create 取消后迟到结果；
- scan 与 create 同时发生；
- worktree 在外部被移动或删除；
- 远端响应超时但操作可能已提交；
- metadata 写入与 UI reveal 的顺序。
常见工具是 in-flight map、operation key、generation、canonical path 与 host-qualified id。
13. 源码导航
- Worktree IPC：
src/main/ipc/worktrees.ts - Repo/Project IPC：
src/main/ipc/repos.ts - Git worktree：
src/main/git/worktree.ts - Git runner：
src/main/git/runner.ts - renderer slice：
src/renderer/src/store/slices/worktrees.ts - 删除设计：
docs/worktree-delete-preflight.md