问题新工作树是一份干净 checkout——
node_modules、.cache、.env 这些 gitignore 的东西都不在。装一遍依赖可能比 Agent 干活还慢。Orca 用三种互补机制解决。三种机制对比
| 机制 | 作用方式 | 适合 |
|---|---|---|
| Worktree Shared Paths | 从主 checkout 物化/符号链接到每个新工作树（macOS 上尽量 APFS clone-copy） | 每个仓库手动配置 |
orca.yaml 的 sharedDirectories |
仓库内检入的 gitignore 目录共享清单（符号链接/共享，不复制） | 大型可重建目录：node_modules、.cache |
.worktreeinclude |
gitignore 的文件或目录拷贝（每个工作树各持一份，非符号链接） | 需要独立副本的：.env、.vscode/ 本地配置 |
方式一：Settings → Repository 手动配置
在仓库设置里加 Worktree Shared Paths，输入需要从主 checkout 带入每个新工作树的路径。
方式二：orca.yaml（检入仓库，团队共享）
仓库根目录放一个 orca.yaml：
worktree:
sharedDirectories:
- node_modules
- .cache
- 条目必须在主 checkout 中真实存在且被 gitignore；被跟踪或缺失的路径会被跳过
- 与用户级 Worktree Shared Paths 叠加（追加，不替换）
方式三：.worktreeinclude（检入仓库，按文件拷贝）
仓库根目录放 .worktreeinclude，列出每个工作树各持一份的 gitignore 文件/目录：
.env
.env.local
.vscode/settings.json
- 支持空行和
#注释 - 目前只支持字面路径——glob 通配和取反会被跳过并给出警告
- 被跟踪、缺失或未被 gitignore 的路径不会拷贝
- 已被共享/链接的路径不会重复拷贝
选择建议「共享一份」用
sharedDirectories（省磁盘、改动即时可见）；「各持一份」用 .worktreeinclude（隔离更彻底，比如每个 Agent 各自登录的状态文件）。依赖目录改得频繁就用共享，避免每个工作树各装一份。实战配置范例
一个典型的前端仓库：
# orca.yaml —— 共享的大型可重建目录
worktree:
sharedDirectories:
- node_modules
- .cache
# .worktreeinclude —— 每个工作树独立的本地配置
.env
.env.local
.vscode/settings.json
Agent 启动后直接 pnpm dev 就能跑——依赖已经在，密钥也在（各自独立副本）。
落地练习：配一次共享
- 打开你仓库根目录，创建
orca.yaml，把node_modules（或语言对应的依赖目录）加进sharedDirectories - 创建
.worktreeinclude，加入.env等本地配置 - 新建一个工作树，看创建后的目录里依赖是否就绪
- 对比：不用共享机制再建一个，感受安装依赖的耗时差
怎么判断做对了？——新工作树里直接
npm run dev/pnpm dev能启动，且.env存在。
卡住了怎么办？ 路径没生效：确认目录真的被 gitignore（git check-ignore node_modules 验证）；确认写的是字面路径不是 glob。
小结
- 三种机制：Settings 共享路径、
orca.yamlsharedDirectories（共享）、.worktreeinclude（拷贝） sharedDirectories只接受被 gitignore 的真实目录，符号链接/共享而非复制.worktreeinclude只接受字面路径，每个工作树各持一份副本- 配置检入仓库后团队共享，新工作树开箱即用
下一节，工作树的管理操作。