多AI智能体同仓协作不互踩:oh-my-cli租约制Git Worktree实战教程

原创2026-10-28 03:41:271,831 阅读

多AI智能体同仓协作不互踩:oh-my-cli租约制Git Worktree实战教程

在同一个代码仓库里并行跑多个 AI 编程智能体,最容易发生的就是文件互相覆盖、改动互相污染。oh-my-cli 是一个极简自主代码智能体 CLI,它用租约制 Git Worktree 机制解决这个问题:每个有写权限的智能体都能申请到一个隔离的 git worktree 工作区,任务验证完成后再自动归还。本文带你完整走一遍「申请租约 → 并行开发 → 交接审查 → 清理归还」的实战流程。

为什么多智能体同仓协作会"互踩"

两个会修改文件的智能体(mutating agents)同时写同一个工作区,会静默地互相覆盖或搞坏对方的改动。oh-my-cli 对此的态度是直接拒绝——共享工作区守护(workspace guard)会阻止第二个写者进入:

同一工作区的两个写者可能覆盖或损坏彼此的工作。请在父会话中顺序执行该任务,或将其委派到隔离工作区(独立的 clone 或 worktree)。

这个拒绝信息并非"死路",它明确指向了安全替代方案——也就是租约制 worktree,核心实现位于 src/worktree-lease.ts。注意"同一工作区"的判定很严格:软链路径别名、同一仓库的 linked worktree 都会折叠成同一身份(见 src/workspace-guard.ts),无法绕过守护。

30 秒上手:安装 oh-my-cli

需要 Node.js 22+。获取仓库并构建:

git clone https://gitcode.com/gh_mirrors/oh/oh-my-cli
cd oh-my-cli
npm install
npm run build
npm link

之后 oh-my-cli 命令即可全局使用(不想 link 时也可直接 node dist/index.js)。中文用户可配合 docs/ZH-CN.md 完成模型端点配置,首次运行建议先跑一次 oh-my-cli --doctor 只读自检。

租约制 Worktree 是什么

一句话:租约 = 仓库 × 任务 × 智能体,三者确定一份专属工作区。

  • 租约身份由三者做 SHA-256 哈希,取前 16 位作为 leaseId,派生出分支 lease/wt-<leaseId>(见 deriveLeaseIdentity)。
  • 同一「任务 + 智能体」重复申请永远得到同一份租约(幂等、可恢复);不同智能体绝不共享分支或工作区(碰撞安全)。
  • 工作区默认落在 <仓库>/.oh-my-cli/worktrees/<leaseId>,该目录已被 git 忽略;可用 --worktree-root 改到仓库外。
仓库 main (parent worktree)
├── .oh-my-cli/worktrees/d0a3e7bc.../   ← worker-1 的租约 (分支 lease/wt-d0a3...)
└── .oh-my-cli/worktrees/f2b81c09.../   ← worker-2 的租约 (分支 lease/wt-f2b8...)

两个智能体各改各的分支,主工作区全程不被触碰。

实战步骤:四步跑通一次并行协作

第一步:为每个智能体申请独立租约

给同一任务的两个 worker 分别申请租约:

# worker-1 的隔离工作区
oh-my-cli --create-worktree --workspace path/to/repo \
  --task-identity deploy-task --agent-identity worker-1

# worker-2 的隔离工作区
oh-my-cli --create-worktree --workspace path/to/repo \
  --task-identity deploy-task --agent-identity worker-2

创建成功时输出类似(完整示例见 README.md 租约章节):

Worktree lease (oh-my-cli.worktree-lease v1)
────────────────────────────────────────
action:   create
result:   ok
status:   created
lease:    d0a3e7bc65723c0e
branch:   lease/wt-d0a3e7bc65723c0e
worktree: ~/code/repo/.oh-my-cli/worktrees/d0a3e7bc65723c0e
base:     3a61045b781f
task:     deploy-task
agent:    worker-1

第二步:智能体在各自工作区并行干活

让每个智能体以对应的 worktree 路径作为 --workspace 启动即可。由于租约工作区与父仓库共享 git 对象库,提交、推送、diff 都与普通分支体验一致,但文件层面的改动完全隔离——互踩从物理上被杜绝。

第三步:随时查看并行工作区全景

oh-my-cli --list-workspaces --workspace path/to/repo

这是一个只读的租约工作区图(worktree graph):列出每个租约的分支、HEAD 提交、clean/dirty 状态(实现见 collectWorktreeGraph)。想要图形化视图,本地 web 交付面板里还有并行工作区雷达页,实时展示各智能体进度与租约状态(src/delivery-web-parallel-workspace-radar.ts)。

第四步:交接审查 + 清理归还

审查:合并前先要一份交接简报(branch、提交列表、改动文件、干净状态):

oh-my-cli --handoff --workspace path/to/repo \
  --task-identity deploy-task --agent-identity worker-1

清理:worker-1 的分支合入主干后,归还租约:

oh-my-cli --clean-worktree --workspace path/to/repo \
  --task-identity deploy-task --agent-identity worker-1

清理逻辑(cleanWorktreeLease)永不删工作:只使用非强制 git 命令删除 worktree 与分支,且分支必须先合入父 HEAD,否则直接拒绝。

智能体中途被取消怎么办:cancel 保留已提交工作

--clean-worktree 要求工作已合并;而任务被取消时更适合用 --cancel-worktree(cancelWorktreeLease):

  • 保留租约分支——智能体已提交的 commit 全部留存,日后可继续集成;
  • 只移除 worktree 目录;
  • 若存在未提交的改动,默认拒绝(fail-closed),明确加 --cancel-force 才允许丢弃。
oh-my-cli --cancel-worktree --workspace path/to/repo \
  --task-identity deploy-task --agent-identity worker-2

安全机制速览:失败即关闭(fail-closed)

租约的设计哲学是任何不确定都先拒绝,绝不猜测、绝不强删。常见拒绝原因与退出码如下:

场景 行为 退出码
创建/清理成功,或幂等的重复操作 正常完成 0
目标不是 git 仓库 / 父工作区有未提交改动 创建前拒绝 1
缺少 --task-identity 或 --agent-identity 视为歧义,拒绝 1
租约已处于部分/冲突状态 要求先显式清理 1
清理时存在未提交改动或未合并 commit 保留租约,拒绝删除 1
同时传了 create 与 clean 等用法错误 参数报错 2

配合幂等性(重复创建返回已有租约、清理不存在的租约是无操作),脚本中断后重跑也不会产生脏状态。输出中的主机主目录路径与密钥一律脱敏,凭据不会泄漏到日志。完整契约见 README.md,行为测试覆盖在 tests/unit/worktree-lease.test.ts 与 tests/integration/worktree.test.ts。

相关文件速查

路径 说明
src/worktree-lease.ts 租约核心:身份派生、创建/清理/取消、工作区图、交接简报
src/workspace-guard.ts 共享工作区守护:拒绝同区双写者
src/index.ts CLI 入口与 worktree 相关参数定义
src/delivery-web-parallel-workspace-radar.ts 并行工作区雷达可视化页面
docs/ZH-CN.md 简体中文安装与配置指南
docs/FIRST-RUN.md 从安装到首个任务的验证路径

常见问题

Q:为什么我的租约创建被拒了? 最常见原因:父工作区不干净。先 git commit 或 git stash,再执行 --create-worktree。拒绝信息会明确告知原因。

Q:智能体崩溃了,工作区怎么收尾? 用 --list-workspaces 确认残留租约,--handoff 查看已完成的工作,然后按需 --clean-worktree(已合并)或 --cancel-worktree(保留分支)。

Q:租约会污染主工作区吗? 不会。租约 worktree 默认放在 .oh-my-cli/worktrees/(git 忽略目录),所有 git 操作只动租约分支,父工作区全程只读对待。

租约制 Git Worktree 的本质,是把「多智能体协作」从口头约定变成了可验证的工程约束:谁在哪个工作区、改了什么、何时归还,全部可查、可审、可恢复。多智能体并行开发,从此不再互踩。

登录后查看全文
oh-my-cli