从一个真实场景说起
上个月我接手了一个活儿：给一个中等规模的后端项目补全单元测试，同时重构几个核心模块的异常处理逻辑。项目大概有三十多个文件，涉及数据库操作、外部 API 调用和消息队列。如果用传统方式，我得先读一遍代码，画依赖图，排优先级，然后一个一个文件改——保守估计两到三天。
我试了个新路子：用 OpenCode 的 Agent 编排能力，让 AI 自己拆任务、自己分配、并行推进。从发出指令到 PR 提交，前后不到四十分钟，中间我只需要做两轮 review。
这不是什么科幻场景。OpenCode 的 Agent 编排机制，本质上就是把“项目管理”这件事交给 AI 来做。这篇文章不聊空泛的概念，直接讲它是怎么做到的、以及你怎么用起来。
OpenCode 的 Agent 分层：不是你一个人在干活
很多人第一次用 OpenCode，习惯性地把它当成“终端版聊天助手”——问一句答一句。这其实是最大的误解。
OpenCode 的核心设计是 Agent 分层。你可以把主 Agent 理解成“坐在你面前的工程师”，它有两种工作模式：
Build：全工具权限，能读写文件、执行命令，适合直接上手开发
Plan：偏审慎模式，写文件和执行命令通常需要确认，适合先做方案规划
但真正的威力不在主 Agent 身上，而在于它能够 生成子 Agent。子 Agent 是通过 Task 工具生成的独立会话，每个都有自己的上下文窗口和工具权限。主 Agent 负责拆解任务、分配工作、汇总结果——就像项目经理带着一队工程师干活。
你可能会问：这和普通的“问 AI 一个问题”有什么区别？区别在于，普通 AI 是一次性推理，上下文有限，容易半路迷失。而 Agent 编排是 持续的任务推进——每个子 Agent 完成自己的小任务后返回结果，主 Agent 根据结果决定下一步。整个过程中，AI 不是在“回答问题”，而是在“执行项目”。
任务拆解：从“一句话需求”到“可执行计划”
任务拆解是编排的第一步，也是最关键的一步。OpenCode 在这方面有两种主流实现方式。
方式一：Blueprint 的“调研→规划→执行”流水线
我最早接触的是 @mathew-cf/opencode-blueprint 这个插件。它把整个工作流拆成五个专职 Agent：
Planner（规划者）：主 Agent，负责理解需求、调研代码库、制定计划
Investigator（调研员）：子 Agent，深入调研目录结构、代码模式、依赖关系
Reviewer（审查者）：子 Agent，审查计划和代码，检查遗漏和范围蔓延
Orchestrator（协调者）：主 Agent，执行计划、分配任务、验证结果
Worker（执行者）：子 Agent，在隔离的 git worktree 中实现单个原子任务
实际用起来是这样的：你告诉 Planner 想做什么，它会同时生成 3 到 5 个 Investigator，并行调研代码库的不同方面。调研完成后，Planner 整合信息，可能还会追问你几个澄清问题，最后产出一份结构化的实施计划。
这份计划通过 /execute 命令交给 Orchestrator。Orchestrator 为每个任务创建独立的 git worktree，生成对应的 Worker 子 Agent 去执行。每个 Worker 只负责一个原子任务，互不干扰。
这个流程的精髓在于 关注点分离：调研的人只管调研，执行的人只管执行，审查的人只管审查。每个 Agent 的上下文都很干净，不会因为混杂了太多职责而“精神分裂”。
方式二：swarm-control 的自动分解
如果你的需求没那么复杂，不想搞五六个 Agent 的流水线，swarm-control 提供了更轻量的方案。
它的思路更直接：你给一个任务描述，它自动分析涉及哪些文件，然后把任务拆成 1 到 4 个基于文件的子任务，最多生成 4 个 Worker 并行执行。
使用方式也非常简单：
/swarm_spawn "为 src/api/ 下所有 API 端点增加错误处理"
系统会自动识别 src/api/ 目录下的文件，按文件粒度拆解任务，每个 Worker 负责一个或几个文件。子任务之间有依赖关系时，会自动等待。如果多个 Worker 需要访问同一个文件，还有文件锁机制防止冲突。
两种方式各有适用场景：Blueprint 适合大型、多阶段的复杂项目；swarm-control 适合中等规模、文件粒度清晰的单一任务。
并行推进：别让 Agent 排队等着
任务拆完了，怎么让它们同时跑起来？这是编排能力的第二个核心问题。
依赖关系图（DAG）
opencode-agent-teams 插件提供了一个很干净的抽象：把任务定义成有向无环图（DAG）。
你可以用 team_create 定义一个团队计划，每个任务可以指定 depends_on 依赖：
team_create plan_id="research-feature" tasks=[
{id:"api", prompt:"研究用户认证需要的 API 端点", agent:"explore"},
{id:"db", prompt:"研究用户认证的数据库结构", agent:"explore"},
{id:"summary", prompt:"综合 API 和 DB 调研结果制定计划",
agent:"general", depends_on:["api","db"]}
]
执行 team_run 时，系统会对任务做拓扑排序，同一依赖层级的任务并行执行——api 和 db 同时跑，都完成后才执行 summary。
每个任务在后台都有自己的子会话，通过 OpenCode SDK 的 client.session.create 创建，parentID 指向当前会话。主会话不会被阻塞，你可以同时做其他事情。
更细致的并行控制
@hueyexe/opencode-ensemble 提供了更细粒度的控制。主 Agent 可以动态创建团队、添加任务、指定依赖，然后逐个生成队友：
主 Agent 先添加独立任务 → 记录任务 ID →
再添加依赖这些 ID 的后续任务 → 依次生成对应的子 Agent
每个子 Agent 运行在自己的 OpenCode 会话中，拥有独立的上下文窗口。你可以为每个子 Agent 指定不同的模型——比如让 GPT-5 做调研、Claude Opus 写代码、再让另一个模型做 review。不同模型各司其职，而不是一个模型干所有事。
opencode-matrixx 更进一步，内置了 14 个专职 Agent，覆盖了从架构设计、代码实现到安全审计的完整链路。你只需要说一个词 ultrawork，系统就会自动调度最合适的 Agent 组合并行推进。
实战：一个完整例子
说这么多理论，不如看一个完整的例子。假设我需要给一个支付模块增加幂等性处理——防止 Stripe 重复回调产生重复订单。
用 OpenCode + ensemble 插件，流程是这样的：
第一步：主 Agent 创建团队，先添加调研任务
team_tasks_add({
tasks: [
{ content: "梳理 checkout webhook 流程，识别幂等性风险点", priority: "high" }
]
})
// 返回 task_abc123
第二步：基于调研结果，添加实现任务
team_tasks_add({
tasks: [
{ content: "实现重复 webhook 的幂等性防护", priority: "high" }
]
})
// 返回 task_def456
第三步：添加依赖任务——测试依赖于实现完成
team_tasks_add({
tasks: [
{ content: "为重复 webhook 场景补充回归测试",
priority: "high", depends_on: ["task_def456"] }
]
})
// 返回 task_ghi789
第四步：生成对应的子 Agent
team_spawn({
name: "scout",
agent: "explore",
claim_task: "task_abc123",
prompt: "追踪 checkout webhook 流程，报告涉及的文件、数据模型和现有测试..."
})
team_spawn({
name: "api-dev",
agent: "build",
claim_task: "task_def456",
prompt: "实现幂等性防护，保持改动最小化..."
})
调研 Agent 先跑，返回报告后，实现 Agent 才开始写代码。测试 Agent 等实现完成后再执行。整个过程 串行依赖、并行独立——如果同时有多个互不依赖的任务，它们会一起跑。
几个落地时的注意事项
工具权限要卡死
不是所有 Agent 都应该能写代码。Blueprint 的做法值得参考：只有 Worker Agent 能写源代码，Planner、Orchestrator、Investigator、Reviewer 只能在 .blueprint/ 目录下写文件。权限控制通过 tool.execute.before 钩子在工具层面强制执行。状态要能持久化
Agent 跑着跑着可能断掉，或者你中途想看看进度。Blueprint 把所有状态存在项目根目录的 .blueprint/ 下，swarm-control 的状态存在 ~/.config/swarm-control/state.json。状态持久化意味着你可以随时中断、恢复、查看进度。子 Agent 的模型选择
不是所有任务都值得用最贵的模型。简单调研用便宜模型，核心代码实现用最强模型。OpenCode 支持在子 Agent 层面指定模型，可以根据任务复杂度动态分配。失败处理
swarm-control 的处理方式比较务实：某个子任务失败了，其他子任务继续执行，失败的标记为 ❌ 并显示错误详情。不会因为一个文件改不动就让整个任务卡死。
总结
OpenCode 的 Agent 编排能力，说白了就三件事：
拆：主 Agent 把大目标拆成小任务，可以手动定义依赖关系，也可以让系统自动分析
派：为每个任务生成独立的子 Agent，可以指定不同模型、不同权限
跑：无依赖的任务并行执行，有依赖的按拓扑顺序推进，主会话不被阻塞
这三个环节做扎实了，AI 就不再是“你问一句它答一句”的聊天工具，而是一个能自己推进项目的执行团队。
当然，编排能力不是万能的。任务拆得太粗，AI 容易迷失；拆得太细，协调开销又太大。最佳实践是结合具体项目的规模，选择合适的插件和拆解粒度——小项目用 swarm-control 足矣，大项目上 Blueprint 或 ensemble 的完整流水线。
说到底，Agent 编排的本质不是把人类排除在外，而是把人类从“拆任务、盯进度”的琐碎工作中解放出来，让你把精力花在真正需要判断力的地方——比如决定架构方向、review 关键代码、处理边界情况。剩下的，交给 Agent 们去并行推进就好。
