OpenCode v2 已经把“一个模型包办所有工作”升级为可配置的多智能体工作流。真正影响团队效率的，不是智能体数量，而是任务如何拆分、上下文如何隔离、哪些角色可以写代码，以及失败时怎样回到可审计的主流程。本文基于 2026 年 11 月 2 日更新的官方文档，给出一套适合企业代码库的落地方案。

一、为什么单智能体在企业项目中很快遇到瓶颈

在个人小项目里，让一个 AI 同时搜索代码、阅读依赖、设计方案、修改文件和执行测试，往往已经够用。但进入中大型代码库后，同一条会话会迅速混入大量不同性质的信息：业务背景、历史实现、第三方源码、测试日志、临时猜测和最终决策。上下文越长，并不等于结果越可靠。

单智能体常见的三个问题是：

1. 上下文污染：依赖调研和日志噪声挤占了真正需要保留的业务约束。
2. 权限过宽：为了完成实现而开放的写文件和命令权限，也被用于本应只读的调研阶段。
3. 成本不可控：复杂任务持续迭代，没有明确的步骤上限和停止条件。

OpenCode v2 的多智能体设计并不是简单地“多开几个聊天窗口”，而是把主流程与专业工作单元分开。主智能体负责与用户持续交互和汇总决策，子智能体在独立子会话里完成边界清楚的工作，再把结论返回主流程。

二、先看懂 OpenCode v2 的智能体模型

2.1 主智能体：直接承接用户目标

官方文档把直接与用户交互的智能体定义为主智能体，配置模式为 primary。OpenCode 内置两个主智能体：

主智能体	默认定位	适合任务	风险边界
Build	完整开发执行	修改代码、执行命令、运行测试	工具能力完整，应配合权限规则
Plan	分析与规划	代码理解、方案设计、变更评审	默认对编辑和命令操作更谨慎

使用者可以在会话中用 Tab 键，或配置的 switch_agent 快捷键，在主智能体之间切换。一个实用原则是：先让 Plan 把问题定义清楚，再让 Build 执行已经确认的变更。

2.2 子智能体：隔离的专业工作单元

子智能体的模式是 subagent。它们可以由主智能体根据描述自动调用，也可以通过 @名称 手动指定。OpenCode v2 内置三个子智能体：

子智能体	核心能力	是否适合写入工作区	典型用途
General	多步骤通用任务	可以，取决于权限	独立实现、复杂排查、并行工作包
Explore	快速探索本地代码库	否，偏只读	找文件、追调用链、回答仓库结构问题
Scout	调研外部文档与依赖源码	否，偏只读	核对上游实现、研究依赖、对照外部资料

这三个角色的关键差异，不是“谁更聪明”，而是信息来源和操作边界不同。Explore 关注当前工作区，Scout 关注外部依赖与文档，General 则承担需要多步执行的通用任务。

2.3 隐藏智能体：不要误当成业务角色

官方还列出了 Compaction、Title 和 Summary 三个隐藏的系统智能体。它们分别负责长上下文压缩、会话标题生成和摘要生成，不能在界面里像普通智能体一样选择。

企业做用量统计时应注意：这些系统动作也可能消耗模型调用。如果平台只按“用户可见消息数”统计成本，容易低估长会话的真实消耗。

三、推荐的企业五段式工作流

把所有任务都交给 Build 并不是多智能体。更稳妥的方式，是让每个阶段只拥有完成本阶段所需的上下文与权限。

用户目标
  ↓
Plan：澄清范围、风险与验收标准
  ↓
Explore：定位本地实现和影响面
  ↓
Scout：核对依赖、协议与官方资料
  ↓
Build / General：实施变更并运行验证
  ↓
Review 子智能体：只读复核差异与风险

3.1 Plan：先建立“变更契约”

Plan 阶段至少应产出四项内容：

• 要解决的业务问题，而不是表面报错；
• 明确的修改范围和禁止修改范围；
• 可执行的验证命令；
• 失败时的回退方式。

如果计划里还存在“可能修改 A，也可能重构 B”这类分叉，就不应立即进入 Build。先通过 Explore 找到证据，缩小范围后再执行。

3.2 Explore：只回答代码库内部问题

Explore 最适合处理“在哪里”和“如何关联”：入口在哪、配置从哪里加载、某字段经过哪些层、测试覆盖了哪些路径。它的输出应该是带文件位置和调用关系的事实清单，而不是直接生成大段补丁。

一个高质量的 Explore 任务描述可以这样写：

@explore 请只读分析订单取消流程：
1. 找到 HTTP 入口、应用服务和仓储实现；
2. 标出状态校验、事务边界和事件发布位置；
3. 列出已有测试与缺口；
4. 不修改任何文件。

3.3 Scout：把外部研究从主上下文剥离

升级框架、接入 SDK 或排查依赖行为时，外部资料往往比本地代码还多。让 Scout 单独研究官方文档和上游源码，可以避免把大量无关页面塞进主会话。

@scout 核对目标 SDK 当前稳定版的重试语义：
- 只使用官方文档与上游源码；
- 区分连接失败、限流和业务错误；
- 给出结论对应的版本与源码位置；
- 不对本地仓库做任何修改。

3.4 Build 与 General：一个负责主线，一个负责工作包

Build 适合保留最终决策、修改核心文件和运行整体验证。General 更适合被拆成独立工作包，例如补单元测试、迁移配置样例或检查另一个模块。

不要让两个可写智能体同时修改同一个文件。并行化的前提应是写入集合不重叠，或者其中一个任务严格只读。否则节省的时间很容易被冲突处理抵消。

3.5 Review：最后设置只读闸门

实现完成后，再调用一个不可写的审查智能体检查 git diff、测试结果和验收标准。审查结论返回主会话，由 Build 修复；审查智能体本身不直接改代码，这样可以保留清晰的“发现问题—决定修复—执行修复”链路。

四、用 JSON 配置主智能体与子智能体

下面是一份可作为项目起点的 opencode.json。示例使用通用模型占位符，实际模型 ID 应以 opencode models 的输出为准。

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "planner": {
      "description": "分析需求、影响面和验收标准，不修改代码",
      "mode": "primary",
      "model": "provider/reasoning-model",
      "temperature": 0.1,
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "builder": {
      "description": "按已确认计划实施并验证变更",
      "mode": "primary",
      "model": "provider/coding-model",
      "temperature": 0.2,
      "steps": 30
    },
    "reviewer": {
      "description": "只读审查差异、测试和安全风险",
      "mode": "subagent",
      "temperature": 0.1,
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

这里有两个容易忽略的细节。

第一，description 不只是给人看的说明，也会影响主智能体是否选择该子智能体。因此应写清任务条件、预期输出和限制，不要只写“代码专家”。

第二，v2 文档明确提示旧字段 maxSteps 已弃用，应改用 steps。升级后如果发现步骤限制没有生效，首先检查是否仍在使用旧字段。

五、用 Markdown 文件沉淀可复用角色

除了 JSON，OpenCode 还支持用 Markdown 文件定义智能体：项目级目录是 .opencode/agents/，全局目录是 ~/.config/opencode/agents/。文件名就是智能体名称。

例如建立 .opencode/agents/security-reviewer.md：

---
description: 审查当前变更中的认证、授权、输入校验和敏感信息风险
mode: subagent
temperature: 0.1
tools:
  write: false
  edit: false
permission:
  webfetch: deny
  bash:
    "*": ask
    "git diff*": allow
    "git log*": allow
---

你是只读安全审查员。先读取变更差异和相关测试，再按严重级别输出问题。
每个问题必须包含证据位置、影响、触发条件和最小修复建议。
不要修改文件，不要提交代码，不要输出或复述任何凭据。

Markdown 方式很适合纳入 Git 管理。角色定义可以像代码一样走评审，避免每个开发者在本机维护一套无法审计的提示词。

六、任务权限：限制“谁可以调用谁”

工具权限回答的是“智能体能做什么”，任务权限回答的是“主智能体可以启动哪些子智能体”。企业环境必须同时约束这两层。

例如，规划智能体只允许调用只读研究角色，不允许发起可写的通用实现角色：

{
  "agent": {
    "planner": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "explore": "allow",
          "scout": "allow",
          "reviewer": "allow"
        }
      }
    }
  }
}

配置通配符时要特别注意规则顺序。官方文档说明后匹配的规则优先，因此通常应先写宽泛规则，再写具体例外。上线前应通过小型验证任务确认实际命中结果，不要只凭肉眼判断配置。

七、上下文隔离不是信息丢失

子智能体在自己的子会话中工作，主会话只接收整理后的结果。这能减少噪声，但前提是交接格式稳定。建议每个子任务统一返回五部分：

1. 结论；
2. 证据位置；
3. 未确认事项；
4. 风险与影响；
5. 建议的下一步。

result:
  conclusion: "取消接口在应用服务层缺少幂等校验"
  evidence:
    - "src/order/cancel-service.ts:42"
    - "tests/order/cancel-service.test.ts:18"
  unknowns:
    - "生产消息队列是否启用重复投递"
  risks:
    - "重复退款"
  next_action:
    - "先补失败用例，再增加幂等键检查"

这样的输出比“我已经检查过，建议增加校验”更适合主智能体继续工作，也便于人类复核。

官方还提供父会话与子会话之间的导航能力：可以通过配置的 session_child_cycle 和反向快捷键，在父会话、子会话 1、子会话 2 之间循环查看。遇到结论可疑时，应进入子会话看原始证据，而不是让主智能体反复转述。

八、并行执行的正确打开方式

多智能体最诱人的能力是并行，但不是所有任务都应该并行。可以用下面的判断表：

任务关系	是否并行	示例
完全独立、只读	推荐	Explore 查本地，Scout 查上游
修改不同文件且接口稳定	可以	一个补文档，一个补独立测试
共享设计结论	先串行后并行	先定接口，再分别实现前后端
修改同一文件或同一迁移	不推荐	两个智能体同时改数据库脚本
后一步依赖前一步输出	串行	先复现故障，再修复

并行子任务应包含明确的完成条件和写入集合。可以在任务描述里直接声明：

允许修改：tests/payment/**
禁止修改：src/**、数据库迁移、依赖锁文件
完成条件：新增失败用例并确保测试可稳定复现

如果无法写清这些边界，说明任务还没有拆到适合并行的粒度。

九、成本控制：限制步骤，而不是盲目压缩回答

多智能体会增加调用次数，但合理拆分通常能减少无效上下文。成本治理应关注以下四个指标：

• 每类智能体的调用次数与 Token；
• 子任务一次成功率；
• 平均步骤数以及触发 steps 上限的比例；
• 被主流程采用的结论比例。

steps 可以限制智能体在被要求返回纯文本总结之前的最大迭代次数。例如快速检索任务可以设置为 5 到 8 步，复杂实现可以更高，但必须有明确上限。

{
  "agent": {
    "quick-locator": {
      "description": "快速定位符号和调用位置",
      "mode": "subagent",
      "steps": 6,
      "temperature": 0.1,
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

降低成本的重点不是让所有角色都使用最便宜的模型，而是把高价值推理留给规划、复杂实现和最终审查，把文件定位、格式检查等确定性任务交给更轻量的角色。

十、失败治理：子智能体卡住时主流程怎么办

企业工作流不能假设每个子任务都会成功。建议约定三类退出状态：

• completed：已完成，并给出证据；
• partial：完成部分工作，列出缺口；
• blocked：缺少权限、信息或外部条件。

当子智能体连续搜索仍无进展时，应返回已经验证的范围，而不是继续扩展搜索。主智能体根据证据决定补充输入、换角色或终止任务。不要通过扩大写权限来“试试看”，更不要让失败的只读调研自动升级成可写执行。

对于可写任务，还应增加以下保护：

1. 修改前记录工作区状态；
2. 只修改任务允许的路径；
3. 不覆盖用户已有的未提交变更；
4. 验证失败时保留失败证据；
5. 提交、发布、删除等外部动作必须单独授权。

十一、从零落地的最小步骤

11.1 第一周：先做三个只读角色

从 Explore、Scout 和 Review 开始，不急着让多个智能体同时写代码。为每个角色定义输入模板、输出格式和禁止事项，用十个真实任务观察结论质量。

11.2 第二周：加入 Plan 与 Build 闸门

要求中高风险变更先经过 Plan，再由 Build 执行。把验收命令写进计划，审查智能体最后对照计划检查结果。

11.3 第三周：只并行独立工作包

选择写入集合完全不重叠的任务试点并行。例如一个子任务补 API 文档，另一个子任务补独立模块测试。记录冲突率、返工率和总耗时。

11.4 第四周：建立用量与质量看板

同时看成本和结果，不要只排名 Token。一个使用量低但结论经常被推翻的角色，并不比高 Token、一次完成的角色更省钱。

十二、常见反模式

12.1 角色很多，但描述都一样

“你是资深工程师”无法形成路由依据。每个 description 都应明确何时使用、信息来源、能否写入和输出格式。

12.2 所有子智能体都开放写权限

调研角色不需要写权限。权限越多，越难判断某项变更由谁产生，也越容易在错误假设下修改代码。

12.3 用子智能体代替需求澄清

如果业务目标本身不清楚，拆成五个子任务只会并行地产生五套假设。先由 Plan 或人类确认目标，再进行技术拆分。

12.4 只看主会话，不保留子会话证据

主会话中的摘要可能省略边界条件。关键决策应能回溯到子会话、文件位置、命令结果或官方资料。

12.5 并行修改同一热点文件

这会制造合并冲突、覆盖变更和重复测试。热点文件应指定唯一写入者，其他角色只提交建议或差异说明。

十三、安全与治理清单

上线前可以用下面的清单做一次快速检查：

• 主智能体和子智能体职责是否可区分；
• Explore、Scout、Review 是否默认只读；
• task 权限是否限制主智能体可调用的角色；
• 通配符规则是否按“宽泛在前、具体在后”验证；
• 是否使用 steps，并清理已弃用的 maxSteps；
• 提示词和角色定义是否纳入版本管理与评审；
• 子任务是否返回证据、未知项和退出状态；
• 并行任务的写入路径是否互不重叠；
• 凭据、客户数据和内部地址是否禁止进入提示词；
• 发布、提交、删除和外部消息是否保留最终确认闸门；
• 用量看板是否区分主智能体、子智能体和隐藏系统调用。

十四、总结

OpenCode v2 的多智能体能力，真正的价值不是让更多 Agent 同时工作，而是把复杂开发过程变成可分工、可限制、可回溯的流水线。

一套稳健的企业实践可以概括为：Plan 定义目标，Explore 理清本地代码，Scout 核对外部事实，Build 保持唯一主线，General 承担边界明确的工作包，Review 在最后提供只读复核。再用 steps 控制迭代，用工具权限和任务权限构成双重边界，用父子会话保存完整证据。

先从只读角色开始，再逐步开放写入与并行，比一开始追求“全自动开发团队”更容易获得稳定收益。多智能体的成熟标志也不是角色数量，而是每个结论都能找到证据，每次写入都有明确责任，每项外部动作都有清楚授权。

参考资料

1. OpenCode 官方文档：Agents
2. OpenCode 官方文档：Permissions
3. OpenCode 官方文档：Configuration
4. OpenCode 官方仓库