learn-claude-code s12 解析Worktree 任务隔离用 Git Worktree 构建永不碰撞的 Agent 并行执行通道【免费下载链接】learn-claude-codeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1项目地址: https://gitcode.com/GitHub_Trending/an/learn-claude-code本篇指南基于 learn-claude-codeBash is all you need 的 nano claude-code agent harness 教学仓库中第 s12 课的核心文档深入讲解如何用 git worktree 为每个任务分配独立的执行目录解决多 Agent 并行开发时的文件互相污染问题。读完后你将理解任务控制平面 目录执行平面的双状态机设计、任务与 worktree 的 ID 绑定机制、生命周期事件流的实现细节并能在真实仓库中运行这套隔离方案。1. 问题背景共享目录下的并行碰撞s12 处于仓库旧版 12 课渐进式课程线的终点附近到 s11 为止Agent 已经具备自主认领claim和完成任务的能力任务板task board负责做什么。但所有任务都运行在同一个共享目录里文档中给出了一个典型的失败场景两个 Agent 同时重构不同模块——Agent A 改config.pyAgent B 也改config.py未提交的改动互相混合unstaged changes mix谁也没法干净地回滚。任务板只追踪what to do对where to do it没有任何约束。s12 的解法一句话概括给每个任务一个独立的 git worktree 目录任务管目标worktree 管执行上下文用任务 ID 把两者绑定起来Isolate by directory, coordinate by task ID。对应实现位于 agents/s12_worktree_task_isolation.py英文文档见 docs/en/s12-worktree-task-isolation.md中文对照见 docs/zh/s12-worktree-task-isolation.md。2. 整体架构双平面 双状态机文档给出的架构全景图如下左半部分是控制平面.tasks/任务状态右半部分是执行平面.worktrees/真实的工作目录中间通过 task_id 双向关联Control plane (.tasks/) Execution plane (.worktrees/) ------------------ ------------------------ | task_1.json | | auth-refactor/ | | status: in_progress ------ branch: wt/auth-refactor | worktree: auth-refactor | task_id: 1 | ------------------ ------------------------ | task_2.json | | ui-login/ | | status: pending ------ branch: wt/ui-login | worktree: ui-login | task_id: 2 | ------------------ ------------------------ | index.json (worktree registry) events.jsonl (lifecycle log) State machines: Task: pending - in_progress - completed Worktree: absent - active - removed | kept两个状态机分别管理各自的生命周期磁盘上的三类持久化文件是恢复的依据文件角色.tasks/task_N.json每个任务一个 JSON 文件含id、subject、status、worktree绑定字段.worktrees/index.jsonworktree 注册表记录名称、路径、分支、task_id、状态.worktrees/events.jsonl追加式生命周期事件日志从源码结构看崩溃后不需要会话内存——.tasks/.worktrees/index.json即可重建全部现场。文档的原话是Conversation memory is volatile; file state is durable.会话记忆是易失的磁盘状态是持久的。3. 工作原理五步完整流程3.1 第一步先创建任务持久化目标TASKS.create(Implement auth refactor) # - .tasks/task_1.json statuspending worktreeTaskManager 的实现细节任务 ID 通过扫描目录下已有的task_*.json取最大 ID 1 得到_max_id天然支持崩溃后重启续编号每个任务文件包含id、subject、description、status初始pending、owner、worktree初始空串、blockedBy、created_at/updated_at等字段见createstatus只允许pending/in_progress/completed三个值update方法会显式校验非法状态并抛出ValueError源码。3.2 第二步创建 worktree 并绑定任务WORKTREES.create(auth-refactor, task_id1) # - git worktree add -b wt/auth-refactor .worktrees/auth-refactor HEAD # - index.json gets new entry, task_1.json gets worktreeauth-refactor传入task_id会自动把任务从pending推进到in_progress。绑定逻辑的核心代码文档摘录与 TaskManager.bind_worktree 实现一致def bind_worktree(self, task_id, worktree): task self._load(task_id) task[worktree] worktree if task[status] pending: task[status] in_progress self._save(task)WorktreeManager.create 的完整实现包含多层防护比文档示例更丰富名称校验re.fullmatch(r[A-Za-z0-9._-]{1,40}, name)只允许 1–40 个字符的字母、数字、.、_、-防止路径注入查重若index.json中已存在同名 worktree 直接报错任务存在性校验传了task_id但任务不存在时报错执行 git 命令git worktree add -b wt/name .worktrees/name base_ref分支统一加wt/前缀base_ref默认为HEAD可传master、某个 commit 等写注册表 回写任务先追加 entry 到index.json含name、path、branch、task_id、status: active、created_at再调用tasks.bind_worktree回写任务文件事件三连成功路径发worktree.create.before→worktree.create.after任何异常则发worktree.create.failed并向上抛出。注意一个从源码结构可以看出的一致性策略create失败时不会留下半绑定状态——index 只在 git 成功后写入任务绑定也紧随其后异常直接抛出由上层agent loop 的 handler捕获为错误文本。3.3 第三步在 worktree 中执行命令subprocess.run(command, shellTrue, cwdworktree_path, capture_outputTrue, textTrue, timeout300)对应WorktreeManager.run隔离的本质就是cwd参数指向了隔离目录。实现的额外细节命令先经过一个危险命令黑名单过滤rm -rf /、sudo、shutdown、reboot、 /dev/命中即返回Error: Dangerous command blockedworktree 名称不存在或路径被删时返回明确错误而不是静默执行超时 300 秒超时返回Error: Timeout (300s)输出合并 stdout stderr 后截断到 50000 字符防止撑爆上下文窗口。配套的status方法源码在指定 worktree 内执行git status --short --branch工作区干净时返回 Clean worktree。3.4 第四步收尾——keep 或 remove任务结束后有两个显式出口worktree_keep(name)目录保留供后续使用index.json中状态置为kept并记录kept_at源码同时发出worktree.keep事件worktree_remove(name, complete_taskTrue)删除目录、完成绑定任务、发出事件一个调用搞定拆除 完成。文档摘录的remove核心逻辑与 WorktreeManager.remove 一致def remove(self, name, forceFalse, complete_taskFalse): self._run_git([worktree, remove, wt[path]]) if complete_task and wt.get(task_id) is not None: self.tasks.update(wt[task_id], statuscompleted) self.tasks.unbind_worktree(wt[task_id]) self.events.emit(task.completed, ...)实际源码在此之外还做了三件事forceTrue时给 git 追加--force参数拆除后把 index 中对应条目的status置为removed并记录removed_at条目保留而非删除注册表可追溯历史失败时发worktree.remove.failed事件。注意complete_task会同时调用unbind_worktree清空任务上的worktree字段保持两侧引用一致。3.5 第五步事件流Event Bus每个生命周期步骤都追加写入.worktrees/events.jsonl例如{ event: worktree.remove.after, task: {id: 1, status: completed}, worktree: {name: auth-refactor, status: removed}, ts: 1730000000 }EventBus 是 append-only 的emit把{event, ts, task, worktree[, error]}序列化为一行 JSON 追加到文件list_recent(limit)读取最后 N 行钳制在 1–200 之间解析失败的行会标记为parse_error而不是抛异常。完整事件类型清单worktree.create.before/worktree.create.after/worktree.create.failedworktree.remove.before/worktree.remove.after/worktree.remove.failedworktree.keeptask.completed4. 对模型暴露的工具面s12 的 agent loopagent_loop把上述能力封装为 17 个工具注册进TOOLS列表和TOOL_HANDLERS分发表分为四组组工具说明基础bash/read_file/write_file/edit_file与工作区同风格的原子文件与 shell 工具bash超时 120s、同样有危险命令过滤任务平面task_create/task_list/task_get/task_update/task_bind_worktree任务板 CRUDtask_list输出形如[] #1: subject ownerx wtauth-refactor一眼看到状态、负责人和 worktree 绑定执行平面worktree_create/worktree_list/worktree_status/worktree_run/worktree_keep/worktree_remove每个 worktree 操作都受 index.json 约束worktree_remove支持force和complete_task布尔参数可观测worktree_events读取最近 N 条生命周期事件系统提示词SYSTEM明确引导模型的行为模式For parallel or risky changes: create tasks, allocate worktree lanes, run commands in those lanes, then choose keep/remove for closeout.——即把 worktree 当作并行执行通道execution lanes来使用。5. 相对 s11 的变化文档的对比表完整继承了 s12 的增量价值这里原文保留ComponentBefore (s11)After (s12)CoordinationTask board (owner/status)Task board explicit worktree bindingExecution scopeShared directoryTask-scoped isolated directoryRecoverabilityTask status onlyTask status worktree indexTeardownTask completionTask completion explicit keep/removeLifecycle visibilityImplicit in logsExplicit events in.worktrees/events.jsonl6. 运行与验证6.1 环境要求Python 依赖见 requirements.txtanthropic0.25.0、python-dotenv1.0.0、pyyaml6.0环境变量脚本通过load_dotenv(overrideTrue)加载.env必须设置MODEL_ID源码第 50 行缺失会直接 KeyErrorAPI key 走ANTHROPIC_API_KEY可选ANTHROPIC_BASE_URL指向兼容端点git 是硬前提启动时detect_repo_root用git rev-parse --show-toplevel定位仓库根WorktreeManager再用git rev-parse --is-inside-work-tree检查git_available。不在 git 仓库内时脚本仍能启动但所有worktree_*工具会返回 Not in a git repository. worktree tools require git. 错误。6.2 运行cd learn-claude-code python agents/s12_worktree_task_isolation.py启动后进入交互终端提示符s12 文档建议依次输入以下五个 prompt英文 prompt 效果通常更好也可用中文Create tasks for backend auth and frontend login page, then list tasks.Create worktree auth-refactor for task 1, then bind task 2 to a new worktree ui-login.Run git status --short in worktree auth-refactor.Keep worktree ui-login, then list worktrees and inspect events.Remove worktree auth-refactor with complete_tasktrue, then list tasks/worktrees/events.这五步恰好覆盖创建 → 绑定 → 隔离执行 → 保留 → 拆除完成的完整生命周期运行结束后检查.tasks/、.worktrees/index.json、.worktrees/events.jsonl即可验证每一步的落盘状态。7. 与当前 17 课体系的衔接需要说明版本背景README.md 记录了课程的重构映射——旧版 12 课中的 Task-bound worktreesold s12在新 17 课体系中被并入s13 Agent Teamspersistent teammates / atomic task claims / task-bound worktrees / typed protocolsREADME 在 Claude Code 架构拆解中也把 task-bound worktrees for parallel edits 列为 harness 的组成部分。也就是说s12 这套 worktree 隔离机制并没有被抛弃而是作为多 Agent 协作s13的一项基础能力被延续。从测试代码可以印证这一演进tests/test_agent_teams_runtime.py 中存在大量 worktree 相关用例例如队友持有过期 worktree 分配时的容错test_teammate_survives_stale_worktree_assignment、脏工作区默认拒绝删除test_remove_worktree_refuses_dirty_checkout_by_default、非法路径../escape永远不可认领test_invalid_or_unregistered_worktree_never_becomes_claimable等。可以推断s12 在单机场景建立的注册表 状态机 事件流三件套是 s13 多 Agent 场景下更复杂治理规则的地基。深入该主题可继续阅读 s13_agent_teams/README.md。8. 要点回顾分离两个平面.tasks/管目标与状态控制平面.worktrees/管目录与分支执行平面用 task_id 双向绑定绑定即推进create(name, task_id...)一次调用完成 git worktree 创建、index 登记、任务状态pending → in_progress三件事绑定写两侧隔离靠 cwd执行工具只是把subprocess.run的cwd指向 worktree 路径配合 300s 超时、50000 字符截断和危险命令过滤显式收尾keep保留 /remove(complete_taskTrue)拆除并完成任务index 中留下kept/removed痕迹供审计事件可观测 状态可恢复events.jsonl记录全部 before/after/failed 事件崩溃后凭磁盘文件即可重建无需依赖会话记忆。这套目录级隔离模式的最小实现不足 800 行含 agent loop 与工具 schema是构建任何多任务并行 Agent harness 时值得直接借鉴的参考设计。【免费下载链接】learn-claude-codeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1项目地址: https://gitcode.com/GitHub_Trending/an/learn-claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考