OpenCrabs 多 Agent 编排实战:用 spawn_agent 并行分发任务(git worktree 隔离原理一次讲清)

原创2026-10-21 15:41:212,300 阅读

OpenCrabs 多 Agent 编排实战:用 spawn_agent 并行分发任务(git worktree 隔离原理一次讲清)

OpenCrabs 是一个单二进制运行的自主 AI Agent,内置 spawn_agent 等多 Agent 编排工具,可以把大任务拆成多个子 Agent 并行执行,并自动为每个子 Agent 分配独立的 git worktree 隔离工作区,避免并行写同一份代码时互相踩坑。本文面向新手,讲清它的用法和隔离原理。

OpenCrabs 多 Agent 并行会话列表界面,展示多个子 Agent 会话

🧩 为什么需要多 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 任务里独立运行,完成后结果自动投递回父会话,无需轮询。

OpenCrabs 多 Agent 分屏并行工作界面,多个子 Agent 同时执行工具调用

🤝 五个配套工具组成完整编排闭环

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 中:

  1. 自动切树:派生子 Agent 时自动执行 git worktree add --detach,路径放在 ~/.opencrabs/worktrees/<agent_id>——在仓库旁边而非内部,不会被父仓库的 glob、构建或 git add 误扫;
  2. 独立分支:子 Agent 在切出的树上执行 git switch -c subagent/<short-id>,父仓库的 HEAD 完全不动;
  3. 降级安全:不在 git 仓库里、或 git 拒绝切树时,子 Agent 就退回父目录继续跑——隔离是增强,不是硬依赖;
  4. 构建缓存零拷贝:在支持 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 内部大致这样运转:

  1. 父 Agent 调用 spawn_agent 三次,分别派生 fix-issue-1 / fix-issue-2 / fix-issue-3;
  2. 每个子 Agent 自动获得独立会话 + 独立 worktree 分支,互不干扰地改代码;
  3. 子 Agent 完成时,完整输出(尾部 4000 字符预览 + 全量报告落盘到 ~/.opencrabs/tmp/detached/)推送回父会话;
  4. 父 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 从"一个助手"升级为"一支可并行干活的队伍"。

登录后查看全文
opencrabs