S18｜Worktree 隔离：多 Agent 平台 —— 独立目录，独立车道，让并行工作互不干扰

在前十七章我们的 Agent 已经拥有循环、工具、计划、子代理、技能、压缩、权限、Hook、记忆、提示词流水线、错误恢复、任务系统、后台任务、定时调度、多 Agent 团队、团队协议、自主代理十七大核心能力能拆任务、认领任务、让多个 Agent 并行推进不同工作。但如果所有人都在同一个工作目录里改文件很快就会出现问题两个任务同时改同一个文件、一个任务的修改污染另一个任务的目录、无法单独回看某个任务的改动范围。这一章 S18我们给并行任务加上Worktree 隔离系统为每个任务分配独立的执行车道让任务系统回答 “做什么”Worktree 系统回答 “在哪做而不互相踩到”让多 Agent 并行工作互不干扰。本章核心信息核心闭环任务创建 → 分配 Worktree → 绑定任务 ID → 进入隔离目录执行 → 收尾决定保留 / 回收工具数量18 个核心思想task 管目标worktree 管隔离执行车道和收尾状态两者不能混成一个概念先看懂本章所有名词Worktree同一个仓库的独立检出目录一条属于某个任务的独立工作车道和其他任务的修改默认隔离。隔离执行任务 A 在自己的目录里跑任务 B 在自己的目录里跑彼此不共享未提交改动修改互不影响。绑定把某个任务 ID 和某个 Worktree 记录明确关联起来让任务和执行车道一一对应。Closeout收尾任务完成后对 Worktree 的处理动作决定保留目录方便复查还是回收目录释放资源。Worktree 注册表记录所有 Worktree 的名称、路径、关联任务 ID、状态、最近活动等信息让系统知道每个车道的情况。Worktree 状态执行车道的生命周期状态包括 active活跃、kept保留、removed已删除、unbound未绑定。这一章到底要解决什么问题到 S17系统已经可以让多个 Agent 并行推进不同任务但存在一个关键问题所有任务都在同一个工作目录执行导致两个任务同时修改同一个文件互相覆盖、冲突未完成的修改污染目录影响后续任务的执行无法单独回看某个任务的改动范围排查问题困难无法安全清理已完成任务的执行环境本章要解决的核心问题为每个任务分配独立的执行车道让任务回答 “做什么”Worktree 回答 “在哪做而不互相踩到”实现并行工作的隔离执行。最小心智模型两张表看懂任务与 Worktree 的关系1. 任务板回答做什么、谁在做、状态如何 .tasks/task_12.json { id: 12, subject: Refactor auth flow, status: in_progress, owner: alice, worktree: auth-refactor, } 2. Worktree注册表回答在哪做、目录在哪、对应哪个任务 .worktrees/index.json { worktrees: [ { name: auth-refactor, path: .worktrees/auth-refactor, branch: wt/auth-refactor, task_id: 12, status: active } ] }一句话任务记录工作目标Worktree 记录执行车道两者通过 task_id 关联并行工作互不干扰。关键数据结构本章灵魂1. TaskRecord任务记录新增 Worktree 相关字段task { id: 12, subject: Refactor auth flow, status: in_progress, owner: alice, worktree: auth-refactor, worktree_state: active, last_worktree: auth-refactor, closeout: None, }新增关键字段worktree当前绑定的执行车道名称worktree_state车道状态active/kept/removed/unboundlast_worktree最近一次使用的车道closeout最后一次收尾动作2. WorktreeRecordWorktree 记录不只是路径映射worktree { name: auth-refactor, path: .worktrees/auth-refactor, branch: wt/auth-refactor, task_id: 12, status: active, last_entered_at: 1710000000.0, last_command_at: 1710000012.0, last_command_preview: pytest tests/auth -q, closeout: None, }它回答的不只是 “目录在哪”还包括最近什么时候进入过last_entered_at最近跑过什么命令last_command_preview最后是怎么收尾的closeout3. CloseoutRecord收尾记录closeout { action: keep, # keep/remove reason: Need follow-up review, at: 1710000100.0, }显式记录收尾动作和原因区分 “保留目录方便复查” 和 “回收目录释放资源”。4. EventRecordWorktree 事件日志event { event: worktree.closeout.keep, task_id: 12, worktree: auth-refactor, reason: Need follow-up review, ts: 1710000100.0, }记录 Worktree 的创建、进入、运行、保留、删除等全生命周期事件方便排查问题。最小实现代码极简可运行第一步先有任务再有 Worktree不要先开目录再回头补任务顺序必须是先创建任务再为任务分配 Worktree。# 1. 创建任务 task tasks.create(Refactor auth flow) # 2. 为任务分配Worktree worktrees.create(auth-refactor, task_idtask[id])第二步创建 Worktree 并写入注册表def create(self, name: str, task_id: int): # 生成隔离目录路径和分支名 path self.root / .worktrees / name branch fwt/{name} # 创建git worktree run_git([worktree, add, -b, branch, str(path), HEAD]) # 写入Worktree注册表 record { name: name, path: str(path), branch: branch, task_id: task_id, status: active, last_entered_at: time.time(), } self.index[worktrees].append(record) self._save_index()第三步同时更新任务记录绑定 Worktreedef bind_worktree(task_id: int, name: str): task tasks.load(task_id) # 更新任务与Worktree的绑定关系 task[worktree] name task[last_worktree] name task[worktree_state] active if task[status] pending: task[status] in_progress tasks.save(task)关键必须同时更新任务记录让任务板知道 “这个任务在哪个隔离目录里做”。第四步显式进入车道再在对应目录执行命令def enter(self, name: str): # 更新进入时间 self._update_entry(name, last_entered_attime.time()) # 记录进入事件 self.events.emit(worktree.enter, namename, tstime.time()) def run(self, name: str, command: str): worktree_path self._get_path(name) # 在隔离目录中执行命令 subprocess.run(command, cwdworktree_path, shellTrue) # 更新最后命令记录 self._update_command(name, command)cwdworktree_path是隔离的核心同一个命令在不同目录执行影响范围完全不同。第五步收尾时显式走 Worktree Closeoutdef closeout(self, name: str, action: str, reason: str, complete_task: bool False): record self._get_record(name) task_id record[task_id] # 1. 更新Worktree状态 record[status] kept if action keep else removed record[closeout] { action: action, reason: reason, at: time.time() } # 2. 处理目录保留或删除 if action remove: run_git([worktree, remove, name, --force]) shutil.rmtree(record[path], ignore_errorsTrue) # 3. 更新任务记录 task tasks.load(task_id) task[worktree_state] record[status] task[closeout] record[closeout] if complete_task: task[status] completed tasks.save(task) # 4. 记录收尾事件 self.events.emit(fworktree.closeout.{action}, task_idtask_id, worktreename, reasonreason)统一的 Closeout 接口明确处理保留 / 回收同时更新任务记录、Worktree 记录和事件日志。为什么关键设计必须这样做1. 任务状态和 Worktree 状态必须分开任务状态回答 “这件工作现在是 pending/in_progress/completed”Worktree 状态回答 “这条执行车道现在是 active/kept/removed”。例如任务已经 completed但 Worktree 可以保留给 Reviewer 查看两者不能混成一个字段。2. 必须同时更新任务记录和 Worktree 注册表如果只更新 Worktree 注册表不更新任务记录系统就无法从任务板一眼看出 “这个任务在哪个隔离目录里做”失去了绑定的意义。3. 必须显式进入车道再执行命令让读者清楚 “分配车道” 和 “真正进入并工作” 是两件事这样last_entered_at、last_command_at这些观察字段才有意义。4. Closeout 必须是显式动作统一的 Closeout 接口让收尾逻辑清晰区分保留和回收动作同时记录原因方便后续排查和复盘。如何接到前面章节的系统里S18 是前面多 Agent 系统的 “隔离层”和前面几章强耦合S12 提供任务 ID需要隔离执行的工作目标S15-S17 提供队友和认领机制并行推进任务的执行者S18 为这些任务提供独立执行车道让并行工作互不干扰完整链路任务被创建 - 队友认领任务 - 系统为任务分配Worktree并绑定 - 进入隔离目录执行命令 - 任务完成时决定保留/回收Worktree初学者最容易犯的 7 个坑有 Worktree 注册表但任务记录里没有 Worktree 字段任务板无法知道任务的执行目录绑定关系失效。有任务 ID但命令仍然在主目录执行不设置cwd参数Worktree 形同虚设修改还是会污染主目录。只会 Worktree 删除不解释 Closeout 的含义只记住 “删目录” 动作不知道系统真正想表达的是 “保留 / 回收” 两种收尾逻辑。删除 Worktree 前不检查未提交改动直接删除有脏改动的目录导致任务修改丢失无法恢复。没有 Worktree 状态 / Closeout 字段无法区分车道是活跃、保留还是已删除也不知道最后是怎么收尾的。把 Worktree 当成长期垃圾堆从不清理已完成任务的目录导致目录越来越多状态越来越乱。没有 Worktree 事件日志创建、删除失败或任务关系错乱时无法排查问题只能靠人猜。S17 → S18 升级了什么模块S17S18并行执行多个任务在同一个目录执行每个任务在独立 Worktree 目录执行修改隔离任务修改互相污染任务修改默认隔离互不干扰执行边界无明确执行目录无法区分任务改动任务与执行车道一一绑定可单独查看改动目录清理无统一收尾逻辑目录混乱显式 Closeout 动作统一处理保留 / 回收架构地位多 Agent 自治运转层多 Agent 并行隔离执行层本章教学边界本章先只把主干分工讲透task 记录 “做什么”worktree 记录 “在哪做”enter /execute/closeout 串起隔离执行车道崩溃恢复、删除安全检查、全局缓存区、非 git 回退这些运维细节都应该放在这条主干之后。一句话总结本章任务系统管 “做什么”Worktree 系统管 “在哪做而不互相踩到”。它给多 Agent 并行工作加上了隔离执行车道让每个任务都在独立目录中执行修改互不干扰让团队真正实现安全、有序的并行协作。