多AI智能体同仓协作不互踩:oh-my-cli租约制Git Worktree实战教程
多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 的本质,是把「多智能体协作」从口头约定变成了可验证的工程约束:谁在哪个工作区、改了什么、何时归还,全部可查、可审、可恢复。多智能体并行开发,从此不再互踩。