OpenCode Worktree 指南：用 Git 隔离并行编码任务

Git worktree 是连接到同一仓库的另一个工作目录。主目录可以留在 main，旁边的新目录则检出 work/auth。两个目录中的文件和当前分支各自独立；底层 Git 对象仍由仓库共享，因此通常不必为每个任务完整克隆一次仓库。

这个流程不需要 OpenCode 专用的 worktree 模式。进入新目录后启动 CLI，它就会把该目录作为项目上下文。全局 OpenCode 设置仍可能生效，但项目文件、未跟踪文件和本地环境不会自动复制到所有工作树。

先检查当前目录的分支和改动。干净的起点能让你分清后续差异来自主任务还是新分支。从仓库根目录创建一个新分支，并把它检出到旁边的目录。不要把新工作树放进原仓库内部，以免目录关系变复杂。

下面的命令会在当前提交上创建 work/auth，并将工作目录放到 ../app-auth。如果分支已经存在，先确认它没有被其他工作树检出，再决定是否沿用。Git 通常不允许一个分支同时在多个链接工作树中处于检出状态。

从主仓库根目录运行。新分支从当前提交开始。

git status --short --branch
git worktree add -b work/auth ../app-auth
cd ../app-auth
opencode
git worktree list
git -C ../app-auth status --short --branch

执行 cd ../app-auth 后，在这个终端中运行 opencode。当前目录就是重要边界：每个工作树使用独立终端或会话，并先确认项目根目录再让代理改文件。可以先发只读任务，例如请 OpenCode 概括当前分支并列出准备检查的文件。

给每个会话分配明确任务，并在任务记录里写清分支名。例如一个工作树处理身份验证测试，另一个只更新文档。避免让两个会话同时改同一文件、运行重叠的数据迁移，或写入同一个生成目录。分开目录能减少文件冲突，但不会自动协调多个代理。

工作树会分开受 Git 管理的文件和索引，但它不是容器或安全边界。本地数据库、测试服务器、缓存、Docker 项目和外部账号仍可能被多个会话共享。任务需要服务时，先给它独立数据库或 schema、端口、项目名，或使用一次性环境。

Git 只会从所选提交检出受跟踪文件。.env、本地证书、缓存和构建输出等未跟踪或忽略文件，不保证会出现在新工作树里。按需重建环境，通过批准的方式加载密钥，不要把密钥提交到 Git。代理工作前后都检查 git status --short --branch。

把新分支作为独立改动审查。检查 git diff，在该目录运行项目检查，并确认分支只包含预期文件。测试通过后按团队流程合并或变基。链接工作树不能替代代码审查；提交尚未共享前，一个目录的改动也不会自动出现在另一个目录。

删除前检查有没有未提交改动，再决定提交、暂存还是保留。git worktree remove ../app-auth 会移除干净的链接检出；存在改动时 Git 会拒绝，除非使用强制选项。不要把强制删除当作日常清理。若你从 Git 外部删了目录，可运行 git worktree prune 清理陈旧登记；它不会删除仍有效的工作目录。

任务需要不同分支、独立文件快照，或需要保留数小时甚至数天的审查边界时，使用工作树。只读调查或必须查看当前未提交文件的任务，适合在同一检出目录中新开会话。若任务严格串行且只有一个目录要工作，普通分支切换通常更简单。

工作树也增加了分支命名、依赖安装、服务隔离、测试、合并和清理等步骤。如果两个代理必须修改同一批文件，拆成工作树可能让最终合并更难。应先把任务分成互不覆盖的改动，或改为顺序执行。

如果 git worktree add 提示分支已经被检出，先查看 git worktree list，然后创建新分支或回到已有工作树。如果 OpenCode 显示的文件不符合预期，先确认终端路径和项目根目录。如果命令找不到本地文件，记住忽略和未跟踪文件不属于 Git 检出内容。

如果多个会话的测试互相干扰，要检查 Git 以外的资源：数据库、端口、临时目录、代码生成器和共享缓存都可能冲突。若移除失败，在对应工作树运行 git status，先保存有价值的改动。保留主目录用于集成，并用工作树列表查看所有登记目录。