Worktree 协作:任务隔离、交接与安全清理
什么时候使用 worktree
跳转到“什么时候使用 worktree”多个 Agent 并行改同一仓库时,每条任务线使用一个独立 Git worktree:它有自己的工作目录和分支,但共享同一个仓库的 Git 历史。这样可以避免多个任务互相覆盖未提交文件、切换分支或污染构建产物。
只读评审或没有并行冲突的小改动不一定需要新目录。Worktree 也 不是操作系统沙箱:权限仍由运行时和账号约束,分工仍要约定不重叠的写集。
创建前确认资格与范围
跳转到“创建前确认资格与范围”Hive 托管工具要求:
- 任务由房主发起,本机 Server 托管的 Agent 已配置可写权限。
- 房间工作区是本地、非 bare 的 Git 仓库。
- 已明确开发目标、可写文件及是否允许提交、合入、推送。
访客任务、访客 Agent、未配置的 Agent、远程或被代理的请求不能借此创建或清理本机任务目录。普通接入凭证不是本机 worktree 管理授权。
以下示例仅说明工具参数,不会实际创建分支:
{ "slug": "login-form"}Agent 用 hive_worktree_create 创建或复用任务线;默认路径是 <仓库父目录>/<仓库目录名>-wt/<agent>-<slug>,默认分支 feat/<agent>-<slug>。
默认基于 本地默认分支的当前提交:优先使用本地 origin/HEAD 指向的分支,回退到 main 或 master。这不是远端最新提交;创建不会 fetch、pull、移动主工作区、安装依赖或执行 Git hooks。需要其他基线时明确传 base,并核对返回的提交。
一条任务线复用同一个 slug
跳转到“一条任务线复用同一个 slug”slug 标识开发任务线,不是一条聊天消息。补充需求、重试、review 返修都复用原 slug;再次调用 create 同时把当前调用登记到这条任务线。
已有托管目录会在身份核验后复用。不要改同 slug 的 branch 或 base,也不要把另一房间的同名任务线当成当前任务自动接管。创建失败或中断留下的登记仍会显示,不要为了重试就手工强删。
开始真正独立的新任务时使用新 slug。Hive 不会仅靠“继续那个登录任务”这类自然语言可靠推断你指的是哪一条线。
准备回合与新会话交接
跳转到“准备回合与新会话交接”图为原创流程示意图,不是实际 Worktree 面板截图。
支持交接的本机托管 Bridge 返回 runtimeHandoff 后,流程是:
- 准备回合只做准备:核对任务、创建 worktree、登记白板,简短说明路径和剩余工作,正常结束;不要在旧会话先改文件。
- Bridge 关闭旧运行时:不是把仍在执行的旧会话
cd到新目录,也不是直接移动原会话。 - 新运行时、新会话在精确 cwd 启动:沿用配置的权限档,刷新指令和附件边界,带上公共上下文与准备摘要。
- 新回合先核对目录、分支、基线与改动:依据交接摘要继续未完成工作,不重放已经完成的创建或对外动作。
只读准备、worktree 创建、白板更新,以及能明确识别 progress: true 的进度通知不阻断正常交接。但普通发消息、提问、委派、文件修改或未知工具调用会阻止自动续做,以免在另一个目录重复副作用。无法识别进度参数的运行时也会保守处理。
这里的正常交接 不会把准备回合从头重跑,与崩溃后的安全恢复不同。若交接未发生,先检查原工作区与详情,再由房主决定是否继续;不要自己把旧会话强行搬过去。
工作区档只对新 cwd 应用原有运行时权限,不授予整个 -wt 父目录或其他 Agent 的 checkout。旧 Bridge 可能不支持;升级并重启托管 Agent 后再用工作区档创建。非托管或旧版本返回的能力与指引须逐项核对,不自行扩大权限。
任务绑定决定在哪个目录继续
跳转到“任务绑定决定在哪个目录继续”显式绑定过 worktree 的调用会保留其任务线,即使房间或 Agent 当前焦点后来改变,重试旧调用也不会直接跑进新任务目录。
未绑定的后续消息使用当前焦点,所以有多个开发任务时应明确登记 slug。不同目录的消息不会被随意混成同一轮;绑定另一个目录的消息保持排队,不能用引导把它塞进当前 cwd。
切换 checkout 会丢弃不匹配的旧线程;只有记录的工作目录一致时才允许恢复保存的会话。目录不存在、登记身份不匹配或安全校验失败,应保留现场并核对,不把一个 403/404 当成“可以新建或强删”的证明。
交付不等于已合入
跳转到“交付不等于已合入”完成开发时交给 review 方:
- 路径、分支和基线提交;有提交时给出准确提交号。
- 完整补丁,包括新增文件;说明允许修改的写集是否守住。
- 已通过的验证、仅检查的部分,以及未运行的模型/上线验证。
- 未提交或未合入时明确说明,不用“已完成”暗示已经进入默认分支。
把白板事项转为已就绪供 review 依赖。合入、发布、清理各是独立动作,需在原授权范围内执行;托管清理工具不会帮你合并或推送分支。
安全清理:所有条件都过才移除
跳转到“安全清理:所有条件都过才移除”hive_worktree_list 或网页「任务目录」面板显示 Hive 已登记的任务线,不接管手工创建的目录。
清理会核对精确路径、Git 仓库身份、分支提交和任务占用,要求:
- 已被默认分支覆盖:普通合并检查祖先关系,cherry-pick/squash 使用受限的补丁等价检查;无法确定时保留,不猜测安全。
- 工作区干净:没有已跟踪文件改动、未跟踪文件,也没有挡住清理的忽略文件。任意层级的
node_modules(目录或软链)和dist/、coverage/、.astro/、*.tsbuildinfo这类构建产物能重新生成,不挡清理,会随目录一起删;软链只删链接本身,不会删到主目录的依赖。.env、本地配置、output/里的截图等其他忽略文件仍会阻止删除,列表的ignoredFiles和网页「任务目录」面板会列出是哪些文件。 - 没有占用且未锁定:运行、排队、停止中、等人回答、未处理的结果未知及相关子任务等都可能阻止清理。
- 清理已经获得房主授权,请求所依据的路径和分支提交没有变化。
只看 git status 的普通输出、看到已完成、或收到合入通知,都不足以证明可以删目录。
用受检查的入口,不强删
跳转到“用受检查的入口,不强删”- 房主可在网页「任务目录」面板选择可清理项,核对路径并确认;批量提醒也提供相同安全检查。面板从聊天顶栏房间名下的「⎇ 分支」下拉打开:点下拉底部的「管理任务目录」。和下拉一样,只有在 Server 这台电脑上打开页面的房主、并且房间工作区是 git 仓库时才有;它和「代码」「产物」同类,默认是可拖宽的侧边抽屉,可以铺满,Esc 关闭。
- Agent 获房主授权后用
hive_worktree_remove({ path, deleteBranch? })。默认尝试git branch -d,没有 force 参数。 - Squash 或 cherry-pick 等价合入后,目录可能允许移除,但 Git 仍拒绝安全删分支。工具会说明目录已移除、分支保留及原因;不要再用强删掩盖这个差异。
- 自动清理按房间设置,默认关闭,开关在「任务目录」面板顶部,开启须房主/设备确认;启用后也只处理通过同一组检查的目录,不是定期删除所有任务目录。


演示环境界面截图:人名、房间和仓库都是示例数据,会跟随文档的明暗主题切换。「任务目录」面板从顶栏「⎇ 分支」下拉底部打开,不在「管理房间」里;每条都写明分支、所属 Agent、路径和能不能清理的原因。
不要对自己或他人的托管目录使用裸 git worktree remove、文件系统递归删除或强删分支绕过检查。即使已合入,仍可能有排队消息绑定到该目录;看到占用拒绝就是稍后再试,不是换条命令删掉。
挡住清理的忽略文件应先由房主核对价值和来源,按明确授权另行处理。不要为了“让清理通过”去删凭证文件或本地配置。
安全清理后,服务端保留已退休任务线的清理回执,相关旧消息或委派回执不会被误派到另一个目录重新执行。手工删目录留下的异常登记仅在严格身份核验下可能恢复元数据,这不证明原分支已合入,更不是建议的清理方式。