oh-my-claudecode 怎么启用 Native Team Worktree Mode 并验证 worker worktree 隔离？-编程实验室

oh-my-claudecode 怎么启用 Native Team Worktree Mode 并验证 worker worktree 隔离？

【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode

在 oh-my-claudecode 的omc team多 worker 会话中，多个 worker 默认在同一个共享工作区里改动文件，容易互相踩到同一份 checkout。Native Team Worktree Mode 是 docs/TEAM-WORKTREE-MODE.md 描述的启用路径：把每个 worker 放进专属的 git worktree，同时任务、mailbox、status、manifest 等协调状态仍集中在 leader 工作区的团队级协调根目录下，做到"改动隔离、状态不分裂"。

该模式有几个必须知道的前提（均以仓库文档为准）：

这是opt-in / config-gated的 rollout，默认不生效，不要假设 worktree 模式是默认行为；docs/MIGRATION.md 将该能力标注为 "Unreleased: Native Team Worktree Mode (Opt-In)"。
目标 runtime 是runtime-v2；旧版runtime.ts只保留 read/status 和 cleanup 兼容性。
不需要新增依赖，生命周期操作基于 git worktrees 加上现有 team CLI/API 面。
启动前 leader 仓库必须是干净的：如果 leader 仓库处于 dirty 状态，启动会拒绝provisioning worktrees，而不是带着不安全的基线继续。

启用 worktree 模式：两种配置方式

启用只需设置team.ops.worktreeMode或环境变量OMC_TEAM_WORKTREE_MODE，二者都写在 src/cli/commands/team.ts 的omc team帮助文本里：

Worktrees (opt-in): set team.ops.worktreeMode or OMC_TEAM_WORKTREE_MODE=detached|branch to launch workers from .omc/team/ /worktrees/ . Status includes workspace/worktree metadata.

方式一：环境变量（会话级，临时启用）

export OMC_TEAM_WORKTREE_MODE=detached # 或 branch

方式二：配置文件（持久启用）

配置由 src/config/loader.ts 加载，用户配置位于~/.config/claude-omc/config.jsonc，项目配置位于.claude/omc.jsonc：

// .claude/omc.jsonc { "team": { "ops": { "worktreeMode": "detached" } } }

取值范围要留意两处文档口径：CLI 帮助文本展示环境变量取值为detached|branch；而配置加载器对team.ops.worktreeMode允许的完整集合是disabled、off、detached、branch、named（见 src/config/loader.ts），不在集合内的值会直接报错。解析顺序以 src/team/runtime-v2.ts 为准：OMC_TEAM_WORKTREE_MODE优先于配置文件中的team.ops.worktreeMode。

启动团队并让 worker 进入 worktree

配置生效后，用正常的omc team启动命令拉起团队，例如文档中的示例：

omc team 3:claude "fix failing tests"

worktree 模式下 worker 从<repo>/.omc/team/<team-name>/worktrees/<worker-name>启动（<team-name>、<worker-name>由运行时按团队与 worker 生成，不是手动指定的目录名）。判断下一步的信号：

启动正常：worker 的 cwd 就是其worktree_path，即对应 worktree 目录。
启动被拒：leader 仓库 dirty 时启动会拒绝 provisioning——这是文档明确的行为，先清理或提交 leader 工作区再试。
分支/路径不匹配时，运行时会失败而不是复用错误的 workspace；已有且干净、兼容的 worker worktree 可以复用。

验证 worker worktree 隔离

验证分三层，全部来自 docs/TEAM-WORKTREE-MODE.md 的 workspace contract 与 "CLI and status expectations"。

1. JSON status：确认契约字段

omc team status <team-name> --json

把<team-name>换成你启动时使用的团队名。JSON 消费方应能直接读到以下字段，不需要去读私有状态文件：

workspace_mode：worktree 会话应为worktree，共享工作区行为为single；
worktree_mode、team_state_root：后者应指向 leader 工作区内的<repo>/.omc/state/team/<team-name>；
每个 worker 的 worktree 元数据：worktree_repo_root、worktree_path、worktree_branch、worktree_detached、worktree_created。

2. 人类可读 status：确认改动落在哪

omc team status <team-name>的输出格式（格式来自 src/cli/commands/team.ts，下列为按该格式标注的示例，值以你的实际团队为准）：

workspace_mode=worktree worktree_mode=detached team_state_root=<repo>/.omc/state/team/<team-name> worker=worker-1 working_dir=<repo>/.omc/team/<team-name>/worktrees/worker-1 worktree_repo_root=<repo> worktree_path=<repo>/.omc/team/<team-name>/worktrees/worker-1 worktree_branch=... worktree_detached=true worktree_created=true

重点核对：workspace_mode=worktree、每个 worker 的worktree_path位于.omc/team/<team-name>/worktrees/之下、team_state_root指向 leader 侧的协调根而不是 worker 自己的目录。

3. 隔离边界：协调状态没有复制到 worker 侧

按文档契约，OMC_TEAM_STATE_ROOT会把 worker 指回 leader 拥有的协调根，worker 在 worktree 内不应新建或改动本地.omc/state；worktree 根目录会安装带备份/恢复保护的AGENTS.md。检查 worker worktree 目录内是否存在意外生成的.omc/state，即可确认状态没有被分裂。

清理行为与已知边界

shutdown/cleanup 只会移除"新创建且干净"的 worktree 和运行时创建的分支（安全时）；dirty 的 worker worktree 会被保留并以 warning/event 形式上报，不会被强制清理。复用中的 worktree 也保留。
回滚（rollback）可能移除新建的干净 worktree 与运行时创建的分支；被复用的 worktree 不受影响。
orphan-cleanup是破坏性逃生舱，可能删除 worktree 恢复元数据和根AGENTS.md备份。存在这类证据时，调用方必须在手动保留或明确放弃受影响的 worker worktree/备份之后，才传acknowledge_lost_worktree_recovery: true。
若你还需要 worktree 被删除后 OMC 状态仍然存活，docs/REFERENCE.md 给出的是另一个正交开关：设置OMC_STATE_DIR，让状态写入集中目录而不是随 worktree 删除的本地.omc/。