Worktrees Orchestration Protocol 是一套带有明确倾向的安全编排协议,用于把 Git worktree 当作相互隔离的编码通道来管理。它的核心价值在于为编排器提供一致的 OMO 工作流,覆盖并行智能体、高风险实验、集成审查与清理等场景。
用途与定位 这是仅限编排器使用的工作流。@fixer、@designer 等专家角色可以被分配 worktree 通道内的任务,但通道规划、分支与路径选择、文件归属、委派、diff 校验、集成以及清理都由编排器负责。
目录与状态跟踪 所有 worktree 都位于默认路径 .slim/worktrees/<slug>/,不得把 worktree 创建为主仓库的同级目录。可使用可选的本地元数据清单 .slim/worktrees.json 维持结构性跟踪,其结构包含 version、updatedAt 与 lanes 数组;每个 lane 记录 slug、branch、path、base、purpose、owner、status、areas、createdAt。若该文件不存在,应在初始化通道时创建,并在通道转换、集成或清理时保持更新。默认将其视为本地工作流元数据,若要把纳入提交的项目约定,需先询问用户。
安全准则 在执行任何 Git 变更命令前,编排器必须遵守以下保护措施。
-
预检清单:确认当前目录位于 Git 仓库内;检查当前分支、基础分支以及是否有未提交改动;查看 git worktree list 输出以避免路径或分支冲突;确保分支名(如 omos/<slug> 或项目自定义约定)在本地或远程尚不存在;在创建嵌套 worktree 前确保 .slim/worktrees/ 已被 Git 忽略。
-
强制用户确认:在执行 git worktree add 或 git worktree remove、分支创建/删除/重命名、merge/rebase/cherry-pick、git prune 或 git worktree prune,以及破坏性命令(如 git reset --hard、git clean、git push --force 或删除有未提交改动的 worktree 目录)之前,必须获得用户的明确确认。未经用户对该具体操作的明确确认,绝不执行破坏性命令、删除分支、移除有未提交改动的 worktree 或清理未提交改动。
-
忽略文件设置:在创建或清理通道前,检查现有 .gitignore 与 .ignore。若存在托管区块则原地更新,否则追加。只添加缺失的精确行,不重复条目,不修改无关规则。.gitignore 中添加 .slim/worktrees/ 与 .slim/worktrees.json 的托管块;.ignore 中添加允许 OpenCode 读取的允许列表区块,包括 !.slim/、!.slim/worktrees.json、!.slim/worktrees/、!.slim/worktrees/**。
工作流 阶段一:规划与设置。确定任务范围并选定简短的 <slug>;拟定分支名,默认 omos/<slug>;校验仓库安全性,向用户请求确认以初始化通道;创建前确保托管忽略区块存在;运行 git worktree add -b <branch-name> .slim/worktrees/<slug> <base-commit/branch>;在 .slim/worktrees.json 中登记元数据。
阶段二:执行与委派。所有子智能体都以 worktree 路径(如 .slim/worktrees/<slug>)为工作目录运行;不要修改主检出用于通道工作;构建、测试和编辑操作都隔离在通道内;按通道跟踪文件或文件夹归属,避免并行智能体之间的合并冲突;仅在用户要求提交或批准本地检查点提交时,才在 worktree 内提交进展。
阶段三:集成与校验。在合并或集成 worktree 分支前,对变更行为及其重要边界应用相称的最终状态验证计划,运行仓库或发布说明要求的检查;生成并展示 worktree 分支与集成分支的清晰 diff;请求用户确认集成;从主检出或用户批准的集成检出执行已批准的集成(如 merge 或 cherry-pick)。
阶段四:清理与回收。清理通道前确保托管忽略区块符合上述规则;确保所有改动已安全合并或归档;确认 worktree 没有未提交改动;请求用户批准移除 worktree;使用 git worktree remove .slim/worktrees/<slug> 安全移除;更新 .slim/worktrees.json,将通道标记为已归档或移除。
适用与不适用场景 适用于:可能破坏当前工作环境的高风险或破坏性重构;需要在不同上下文间切换而无需提交半成品工作的并行任务或缺陷修复;在不同分支上运行独立的后台智能体;可能被丢弃的探索性试验或原型开发;隔离第三方包或复杂升级;用户明确要求为特定任务使用 worktree。
不适用于:简单的单文件改动、文档更新或小缺陷修复;尚未完全初始化或存在 worktree 难以支持的复杂多子模块状态的 Git 仓库。