s18 Worktree 任务隔离：Worktree Isolation - Harness Engineering - 后端

# 三行速读

任务回答 “做什么”，worktree 回答 “在哪做”。
并行协作要靠目录隔离车道，不能只靠口头分工。
enter/closeout 生命周期记录决定后续可维护性。

# 先修知识

已理解 s17 的并行自治推进背景。
熟悉 Git worktree 基础概念。

# 读完后你应该能做到（可检验清单）

为不同任务分配独立 worktree 并并行推进。
解释 closeout 记录为什么是治理关键。
通过事件日志定位一次车道异常。

# 本篇要解决什么

并行任务一多，最常见冲突是 “同一目录互相覆盖改动”。s18 的核心是把任务目标和执行车道分离：

task 管 “做什么”；
worktree 管 “在哪做”。

# 用一个类比先理解

像多车道施工：

每个施工任务有自己的车道；
车道之间相互隔离；
收尾时决定保留车道还是封闭车道。

没有车道隔离，所有工程车挤在一条路上，必然互相阻塞。

# 为什么这一步必须现在做

s17 的自治队友会并行推进任务，如果没有目录隔离，冲突概率会急剧上升。s18 给并行执行提供了物理隔离层。

# 关键代码怎么读

# 1) 仓库根与隔离根目录

1
2
3

def detect_repo_root(cwd: Path) -> Path | None:
    ...
REPO_ROOT = detect_repo_root(WORKDIR) or WORKDIR

统一从 repo root 管理 worktree，可避免路径语义混乱。

# 2) EventBus 生命周期日志

1
2
3

class EventBus:
    def emit(self, event: str, task_id=None, wt_name=None, error=None, **extra):
        ...

并行系统必须可观测，事件日志是故障定位基础。

# 3) Task 与 worktree 绑定

1
2
3

def bind_worktree(self, task_id: int, worktree: str, owner: str = "") -> str:
    task["worktree"] = worktree
    task["worktree_state"] = "active"

这让任务状态与执行现场形成明确映射。

# 4) WorktreeManager 负责车道生命周期

1
2
3

class WorktreeManager:
    def create(self, name: str, task_id: int = None, base_ref: str = "HEAD") -> str:
        self._run_git(["worktree", "add", "-b", branch, str(path), base_ref])

创建、绑定、收尾都归一个管理器，职责清晰。

# 你可以怎么复现

为两个任务分别创建 worktree。
在两个目录并行修改同类文件。
做 closeout，记录 keep/remove 决策。

# 常见误区

误区 1：把 worktree 当 task 本身。
误区 2：只建不收，留下大量无主车道。
误区 3：缺少事件日志，难以审计并行流程。

# 一句话总结

s18 让并行协作从逻辑分工走到执行隔离，显著降低任务间冲突。

# 补充解读：隔离车道的生命周期管理

# A. `TaskManager.record_closeout`

1 2	def record_closeout(self, task_id: int, action: str, reason: str = "", keep_binding: bool = False) -> str: task["closeout"] = {"action": action, "reason": reason, "at": time.time()}

这一步把 “收尾决策” 显式记录下来，后续不会出现 “这个车道为什么留着” 的历史黑洞。

# B. `WorktreeManager._run_git` 的统一错误出口

统一封装 git 调用，让错误格式一致，便于上层处理。

# C. 索引文件 `index.json` 的意义

除了 git 自身信息，系统还需要业务维度（task_id、status、created_at），索引文件正是这层补充。

# D. `EventBus.list_recent` 对排障很实用

并行场景下最怕不可见。最近事件列表能快速定位卡在哪个生命周期节点。

# 进阶练习

增加 worktree_recover ，自动修复索引与实际目录不一致。
增加 “超过 N 天未关闭” 的车道巡检。
closeout 时自动生成变更摘要模板。

# 统一术语口径（本章）

Worktree Lane ：任务对应的隔离执行目录车道。
Closeout ：任务收尾决策（保留 / 移除 / 归档等）。
Lifecycle Event ：车道生命周期中的可观测事件。

# 章节衔接（从易到难）

本章解决 “并行执行隔离”。
下一章 s19 进入 “外部能力总线与统一控制面”。

Harness Engineering