OpenCrabs 多 Agent 编排实战:用 spawn_agent 并行分发任务(git worktree 隔离原理一次讲清)
OpenCrabs 多 Agent 编排实战:用 spawn_agent 并行分发任务(git worktree 隔离原理一次讲清)
OpenCrabs 是一个单二进制运行的自主 AI Agent,内置 spawn_agent 等多 Agent 编排工具,可以把大任务拆成多个子 Agent 并行执行,并自动为每个子 Agent 分配独立的 git worktree 隔离工作区,避免并行写同一份代码时互相踩坑。本文面向新手,讲清它的用法和隔离原理。
🧩 为什么需要多 Agent 编排
单个 Agent 处理"重构 + 写测试 + 代码审查"这类复合任务时,会面临两个问题:
- 上下文挤兑:所有子任务的细节都挤在同一个上下文窗口里,越聊越长;
- 文件冲突:如果让多个任务共享同一份工作目录,三个子 Agent 写同一批文件就是"构造性冲突"——不是可能冲突,是一定冲突。
OpenCrabs 的方案是:父 Agent 作为调度者,把独立子任务"派生"给后台运行的子 Agent,每个子 Agent 有独立会话、独立上下文、独立工作区,干完活自动把结果推回父会话。
🚀 用 spawn_agent 并行分发任务
spawn_agent 是 OpenCrabs 内置的工具,主 Agent 在执行时可以直接调用,你只需要在对话里下达像"把这三个任务并行分派给子 Agent"这样的自然语言指令。它的核心参数如下:
| 参数 | 作用 | 适用场景 |
|---|---|---|
prompt |
子 Agent 要执行的任务指令(必填) | 所有场景 |
label |
可读的短标签,如 refactor-auth |
方便追踪多个子 Agent |
provider / model |
单独指定这个子 Agent 用的模型 | 规划用强推理模型、写码用快模型 |
read_only |
只读权限,只能读文件和搜索 | 探索、代码审查、调研 |
allow_nested |
是否允许它再派生子 Agent | 纯工人设为 false 更安全 |
include_brain |
是否预注入 SOUL.md 等工作区文件 | 需要完整工作区规则时 |
模型调用 spawn_agent 的典型形态(源码定义见 src/brain/tools/subagent/spawn.rs):
spawn_agent({ prompt: "Plan the refactor", provider: "zai", model: "glm-5" })
spawn_agent({ prompt: "Implement the plan", provider: "deepseek", model: "deepseek-coder" })
spawn_agent({ prompt: "Review the diff", provider: "zai", model: "glm-5" })
三个任务同时派出,主对话不用干等——子 Agent 在后台 tokio 任务里独立运行,完成后结果自动投递回父会话,无需轮询。
🤝 五个配套工具组成完整编排闭环
spawn_agent 不是孤立的,src/brain/tools/subagent/mod.rs 中定义了完整的五件套:
| 工具 | 用途 |
|---|---|
spawn_agent |
派生子 Agent,返回 agent_id |
wait_agent |
等待某个子 Agent 完成并拿到输出(默认超时 300 秒) |
send_input |
向运行中的子 Agent 追加指令 |
close_agent |
关闭子 Agent |
resume_agent |
唤醒已完成的子 Agent 继续工作 |
其中 wait_agent 对 ID 解析做了容错:支持 UUID 前缀、按 label 匹配,匹配失败时会列出所有活动子 Agent 让你自我纠正,新手用错 ID 也不会直接"死胡同"。实现见 src/brain/tools/subagent/wait.rs。
🔒 为什么必须用 git worktree 隔离
回到开头的"文件冲突"问题。子 Agent 继承父目录,如果同时派生三个子 Agent 改同一代码库,三方会写入同一批字节且没有任何仲裁。
OpenCrabs 的答案是 git worktree:
git worktree为同一个仓库创建多份独立的"检出",共享底层.git对象库。每个子 Agent 拿到自己专属的检出目录和分支,各写各的,物理上互不干扰。
隔离的关键细节都在 src/brain/tools/subagent/worktree.rs 中:
- 自动切树:派生子 Agent 时自动执行
git worktree add --detach,路径放在~/.opencrabs/worktrees/<agent_id>——在仓库旁边而非内部,不会被父仓库的 glob、构建或git add误扫; - 独立分支:子 Agent 在切出的树上执行
git switch -c subagent/<short-id>,父仓库的 HEAD 完全不动; - 降级安全:不在 git 仓库里、或 git 拒绝切树时,子 Agent 就退回父目录继续跑——隔离是增强,不是硬依赖;
- 构建缓存零拷贝:在支持 clonefile 的文件系统(如 APFS)上用
cp -c克隆target/构建缓存,共享磁盘块、几乎零开销;不支持则冷启动,宁慢不错。
🧹 自动清理:有活留下,没活删除
子 Agent 结束后,OpenCrabs 会检查它留下的树里"有没有活":
- 有活(有提交、HEAD 离开了起始 commit,或有未提交的改动)→ 保留树,并在回传给父 Agent 的结果里附上提示:
This agent worked in its own checkout and left changes there.
Branch: `subagent/<short-id>`
Path: `~/.opencrabs/worktrees/<agent_id>`
Review with `git -C <path> status`, and land it with `git merge <branch>`
- 没活 → 执行
git worktree remove --force自动清理,不留垃圾。
这个设计对应 worktree.rs 的 has_work() 与 cleanup():宁可多留一个分支,也绝不静默丢弃子 Agent 的工作成果。
📋 一个典型的并行分发流程
假设你对 OpenCrabs 说:"把这三个 issue 并行修掉",父 Agent 内部大致这样运转:
- 父 Agent 调用
spawn_agent三次,分别派生fix-issue-1/fix-issue-2/fix-issue-3; - 每个子 Agent 自动获得独立会话 + 独立 worktree 分支,互不干扰地改代码;
- 子 Agent 完成时,完整输出(尾部 4000 字符预览 + 全量报告落盘到
~/.opencrabs/tmp/detached/)推送回父会话; - 父 Agent 汇总三份结果向你汇报,有改动的分支会被明确列出,等你 review 后 merge。
除了单会话内的这套原生工具,OpenCrabs 还提供脚本级编排方案(fan-out、管道、断点续跑),见官方指南 src/docs/reference/DYNAMIC_WORKFLOWS.md;多模型分工(规划/执行/审计各用不同模型)则可以直接使用内置的 Multi-Agent 技能。
🎯 新手快速上手清单
- 直接在对话里派活:用自然语言说"并行派子 Agent 处理……",模型会自动选择
spawn_agent,无需手写任何命令; - 审查类任务加只读:让代码审查、调研类子 Agent 带
read_only,它只能读不能写,天然安全; - 在 git 仓库内工作:隔离 worktree 才会生效,子 Agent 的改动落在独立分支上;
- 关注结果里的分支提示:子 Agent 留有改动时会告诉你分支名和路径,review 后手动
git merge合入——脚本提议,人来拍板。
安全提示:子 Agent 默认自动批准工具调用,但它拿不到递归派生工具(
spawn_agent等)和危险系统工具,防止"Agent 套娃"失控。
掌握 spawn_agent + worktree 隔离这套组合拳,你就让 OpenCrabs 从"一个助手"升级为"一支可并行干活的队伍"。

