learn claude code S12 Worktree 任务隔离详解笔记

S12 Worktree 任务隔离详解笔记基于s12_worktree_task_isolation.py源码逐行分析配合s12-worktree-task-isolation.md设计思路。一、问题多个任务共享一个工作目录互相踩踏前面 11 章的 agent 都在同一个工作目录下操作。当只有一个 agent 时没问题。但当 s09-s11 引入了多 agent 团队后Alice 在改utils.pyBob 也在改utils.py→ 冲突Alice 跑了pip install flaskBob 跑了pip install django→ 全局环境污染Alice 的测试需要 Python 3.10Bob 需要 3.8 → 不可能同时满足共享文件系统是多 agent 并行的最大阻碍。每个 agent 需要一个独立的工作空间但又能共享代码基础。s12 的解决方案Git worktree。每个任务分配一个独立的 worktree 目录agent 在里面为所欲为——修改、装包、跑测试——不影响其他人。完成后worktree 可以被保留keep或删除remove。二、什么是 Git Worktree初学者git worktree允许你从同一个仓库创建多个工作目录每个目录有自己的分支。它们共享同一个.git目录节省磁盘空间但文件系统完全隔离。主仓库: /project (branch: main) worktree: /project/.worktrees/auth (branch: wt/auth) worktree: /project/.worktrees/api (branch: wt/api)每个 worktree 像一个独立的克隆但不需要重新 clone 整个仓库。创建 worktree 通常只需要几秒钟。三、和 s11 相比多了什么组件s11s12执行隔离无共享目录Git worktree目录级隔离任务绑定无task.worktree字段 bind_worktree()事件追踪无EventBus生命周期事件日志新工具idle,claim_taskworktree_create/list/status/run/keep/removeworktree_events工具数量1416四、EventBus可观测性的基础设施classEventBus:def__init__(self,event_log_path:Path):self.pathevent_log_path self.path.parent.mkdir(parentsTrue,exist_okTrue)defemit(self,event:str,taskNone,worktreeNone,errorNone):payload{event:event,ts:time.time(),task:taskor{},worktree:worktreeor{},}iferror:payload[error]errorwithself.path.open(a)asf:f.write(json.dumps(payload)\n)deflist_recent(self,limit:int20)-str:# 返回最近 N 条事件用于调试和监控EventBus 记录 worktree 和 task 的完整生命周期worktree.create.before → worktree.create.after (或 .failed) worktree.remove.before → worktree.remove.after (或 .failed) worktree.keep task.completed这不是给模型看的——是给开发者和运维工具看的。当系统出现异常worktree 创建失败、任务卡住事件日志是回溯问题的第一手资料。s12 是系列中第一个引入面向人类的可观测性的章节。五、WorktreeManagerGit Worktree 的生命周期5.1 初始化classWorktreeManager:def__init__(self,repo_root:Path,tasks:TaskManager,events:EventBus):self.git_availableself._is_git_repo()self.index_pathself.dir/index.jsonindex.json是 worktree 的注册表——记录所有 worktree 的名称、路径、分支、关联任务、状态。5.2create()— 创建 worktreedefcreate(self,name:str,task_id:intNone,base_ref:strHEAD)-str:self._validate_name(name)ifself._find(name):raiseValueError(fWorktree {name} already exists)pathself.dir/name branchfwt/{name}self.events.emit(worktree.create.before,...)# 核心执行 git worktree addself._run_git([worktree,add,-b,branch,str(path),base_ref])# 写入 indexentry{name:name,path:str(path),branch:branch,task_id:task_id,status:active,created_at:time.time()}idx[worktrees].append(entry)# 绑定到任务iftask_idisnotNone:self.tasks.bind_worktree(task_id,name)self.events.emit(worktree.create.after,...)base_ref默认为HEAD当前分支的最新提交。名字校验[A-Za-z0-9._-]{1,40}阻止特殊字符——因为 worktree 名会变成目录名和分支名。5.3run()— 在 worktree 中执行命令defrun(self,name:str,command:str)-str:wtself._find(name)pathPath(wt[path])rsubprocess.run(command,shellTrue,cwdpath,# ← 关键cwd 指向 worktree 目录capture_outputTrue,textTrue,timeout300,)return(r.stdoutr.stderr).strip()[:50000]和run_bash的唯一区别cwd指向 worktree 目录而非主工作目录。agent 可以在 worktree 中装包、改代码、跑测试——一切操作隔离在 worktree 内。5.4remove()— 删除 worktreedefremove(self,name:str,force:boolFalse,complete_task:boolFalse):self._run_git([worktree,remove,--forceifforceelse,wt[path]])ifcomplete_taskandwt.get(task_id)isnotNone:self.tasks.update(task_id,statuscompleted)self.tasks.unbind_worktree(task_id)idx[worktrees][...][status]removed如果complete_task: true自动把关联任务标记为完成并解绑——一条命令完成清理 workspace 完成任务。5.5keep()— 保留 worktreedefkeep(self,name:str)-str:idx[worktrees][...][status]keptidx[worktrees][...][kept_at]time.time()不删除 worktree只在 index 中标记为kept。适合代码还需要审查或先保留以备后续修改的场景。六、TaskManager 的扩展s12 的 TaskManager 在 s07 的基础上新增了worktree字段和bind_worktree/unbind_worktree方法defbind_worktree(self,task_id:int,worktree:str,owner:str)-str:taskself._load(task_id)task[worktree]worktreeifowner:task[owner]owneriftask[status]pending:task[status]in_progressself._save(task)defunbind_worktree(self,task_id:int)-str:taskself._load(task_id)task[worktree]self._save(task)任务和 worktree 之间是一对一的关系。task.worktree字段记录了这个任务在哪个隔离环境中执行。七、两个 Manager 的协作Task 创建 → task.status pending ↓ Worktree 创建 → task.bind_worktree(task_id, wt_name) ↓ task.status → in_progress Agent 在 worktree 中工作 → worktree_run(wt_name, pip install flask) ↓ 工作完成 → worktree_remove(name, complete_taskTrue) ↓ task.status → completed task.worktree → Tasks 是控制面管该做什么Worktrees 是执行面管在哪里做。两者的关联通过task.worktree字段 bind_worktree方法桥接。八、完整流程走读场景用户“重构认证模块在隔离环境中进行完成后清理。”第 1 轮Lead 创建任务task_create(重构认证模块)→ task 12。第 2 轮Lead 创建 worktreeworktree_create(auth-refactor, task_id12)→ 在.worktrees/auth-refactor/创建隔离目录分支wt/auth-refactor。Task 12 的status自动变为in_progressworktree设为auth-refactor。第 3-10 轮Lead 在 worktree 中工作worktree_run(auth-refactor, pip install bcrypt)、worktree_run(auth-refactor, python -m pytest tests/auth/)。所有修改在wt/auth-refactor分支上进行主工作区完全不受影响。第 11 轮Lead 完成工作worktree_remove(auth-refactor, complete_taskTrue)→ worktree 被删除Task 12 自动标记为completed。分支可以后续合并回 main。如果出错了worktree_events(limit10)显示最近 10 条事件{event:worktree.create.after,worktree:{name:auth-refactor,status:active}}{event:worktree.remove.failed,worktree:{name:auth-refactor},error:worktree contains uncommitted changes}Lead 看到错误改用worktree_remove(auth-refactor, forceTrue)强制删除或用worktree_keep(auth-refactor)保留下来手动处理。九、设计洞察9.1 控制面与执行面的分离Tasks控制面回答做什么Worktrees执行面回答在哪里做。两者通过task.worktree字段关联各自独立演化。这种分离让系统可以换一种执行隔离方式容器而非 worktree而不影响任务管理换一种任务管理方式Kanban 而非 JSON而不影响执行隔离9.2 Git 作为平台s12 大量依赖 Gitworktree add、worktree remove、rev-parse。在很多人眼中 Git 是版本控制工具但在这里 Git 是文件系统管理平台。git worktree解决了在同一仓库中创建多个独立工作目录的问题——这个问题自己实现可能需要上千行代码。站在巨人的肩膀上而不是自己造轮子。这是工程中最重要的判断力之一。9.3 可观测性不是后加的EventBus 从 worktree 创建的第一步就记录事件。事件覆盖了完整的生命周期before → after/failed每条事件带时间戳、关联的 task、关联的 worktree。当系统变得不可预测异步操作、多线程、外部依赖事件日志是你理解发生了什么的唯一窗口。9.4 s12 是整个系列的终章——也是新起点回头看整个系列s01: 循环 ← agent 能动了 s02: 工具 ← agent 能操作文件系统了 s03: 计划 ← agent 能追踪进度了 s04: 子 agent ← agent 能委托任务了 s05: 知识 ← agent 能按需学习领域专长了 s06: 压缩 ← agent 能无限工作了 s07: 任务图 ← 状态在对话之外存活了 s08: 后台 ← agent 不等命令了 s09: 团队 ← agent 能合作了 s10: 协议 ← agent 能握手了 s11: 自主 ← agent 自己找工作了 s12: 隔离 ← agent 能在独立空间中工作了s12 的 worktree 隔离让多 agent 并行成为可能——这是从单机单 agent到分布式 agent 网络的桥梁。虽然这个系列的代码在 s12 结束但它指向的方向远不止于此。