一个 AI 干所有事？难怪你总觉得它不好用——OpenCode 子代理系统实战

这是「OpenCode 打造个人 AI 智能体」系列的第二篇。

上一篇我们讲了安装和基础使用，这一篇深入核心：子代理系统——让 AI 效率翻倍的秘密武器。

还没看第一篇？点这里 先搞定安装和配置。

---

你有没有遇到过这种情况：

让 AI 帮你重构一个模块，结果它改到一半开始搜文件，搜着搜着忘了原本要干什么。

问题不在 AI，在于你让它一个人干了所有事。

想想你的开发团队——架构师负责设计，开发负责写代码，测试负责找 bug。你不会让一个人包揽所有角色。

OpenCode 的子代理系统就是同样的思路：把 AI 拆成不同角色，各司其职，效率翻倍。

这一篇不讲概念，直接上实战——每个代理怎么用、什么场景用什么、怎么配合最高效。

---

一、主代理（Primary Agents）—— 你的主力队友

主代理是你直接对话的对象。在终端里按 Tab 键或者配置的快捷键就能切换。

1.1 Build —— 主力开发者

权限： 所有工具全开
场景： 日常开发的 80% 时间都在它身上

Build 是 OpenCode 的默认代理，也是能力最全的一个。它能读文件、写文件、执行命令、操作 Git、运行测试——凡是你能在终端做的事，它基本都能做。

典型用法：

“给这个函数加上单元测试”
“把 UserController 里的接口从 REST 改成 GraphQL”
“帮我重构这个模块，提取公共逻辑”

Build 执行的逻辑是：你说需求，它改代码，你 review 结果。 非常适合日常开发任务。

1.2 Plan —— 先想后做的架构师

权限： 受限——只读不写
场景： 需求分析、方案设计、代码审查

Plan 的设计哲学是 “先想清楚再动手”。它的所有写操作默认都是 ask（询问确认），所以不会不经允许就改你代码。

我自己的使用习惯是：遇到复杂需求，先切到 Plan 聊方案，确认方向对了再切回 Build 执行。

典型用法：

“分析一下这个模块的耦合度，给出重构方案”
“我想加一个仓库禁用状态功能，需要改哪些地方，给出最小改动方案”
“review 一下这段代码，有哪些潜在问题”

Plan 和 Build 的配合流程：

Plan → 分析需求，输出方案文档
   ↓ 确认方案没问题
Build → 按方案执行代码改动
   ↓ 改完了
Plan → Review 改动，检查是否遗漏

1.3 自定义主代理

如果你有特定的使用场景，可以自己定义主代理。在项目根目录的 opencode.json 中配置：

{
  "agents": {
    " Reviewer ": {
      "role": "primary",
      "permissions": {
        "read": true,
        "edit": false,
        "command": false
      },
      "prompt": "你是一个严格的代码审查员，只分析不修改，指出所有潜在问题"
    }
  }
}

这样你就多了一个只读的 Code Review 专用代理。

---

二、子代理（Subagents）—— 随时调用的专家

子代理不会被直接显示在主列表中，但你可以通过 @ 提及的方式随时调用它们。

2.1 Explore —— 代码搜索专家

权限： 只读，不能写文件
速度： 极快（使用更轻量的模型）
场景： 快速搜索、定位代码、理解项目结构

Explore 是我按 Tab 切换最频繁的子代理。当 Build 正在执行一个长任务，突然需要查什么东西时，我不会中断 Build，而是直接 @explore 让它去搜。

典型用法：

@explore 帮我找到所有使用了 JWT 鉴权的文件
@explore 搜索一下项目中哪里定义了 OrderStatus 这个枚举
@explore 看看这个模块的目录结构

实战经验： 在重构一个老模块时，我需要知道所有引用了 oldHelper() 函数的地方。直接 @explore 找到所有引用了 oldHelper 的代码，几秒就返回结果，比手动 grep 快多了。

2.2 General —— 通用执行者

权限： 全部（除了 todo）
速度： 可配置模型
场景： 独立执行多步骤复杂任务、并行工作

General 的特殊之处在于它可以独立执行多步骤任务而不阻塞主对话。这在处理耗时任务时特别有用。

典型用法：

@general 帮我做以下几件事：
1. 检查所有 API 接口的响应格式是否统一
2. 找出不一致的地方
3. 给出统一的格式建议

2.3 系统子代理（自动运行，不可选）

有两个系统级的子代理不需要手动调用：

子代理	作用	触发条件
Compactor	压缩长对话上下文	上下文过长时自动触发
Summarizer	创建会话摘要	会话结束时自动触发

它们的存在是为了解决大模型最头疼的问题：上下文窗口溢出。OpenCode 会自动管理，你不需要操心。

---

三、实战场景：一个完整的多代理协作流程

光说概念不够，看一个我真实的项目场景。

背景： 我需要给 ERP 的订单模块加一个"批量修改物流公司"的功能。

步骤 1：Plan 分析（先搞清影响范围）

切换到 Plan 代理：

当前代理：Plan
输入："分析订单发货模块的代码，我要加一个批量修改物流公司的功能，给出影响范围"

Plan 分析后告诉我：

• 涉及 3 个文件：OrderController.java、OrderService.java、order-list.vue
• 需要新增一个批量 API 接口
• 前端需要加一个批量操作的弹窗
• 需要注意并发问题（同时修改多个订单的物流信息）

步骤 2：Build 执行（开始写代码）

切换到 Build 代理：

Tab 切换到 Build
输入："按 Plan 的方案执行，先建后端 API，再改前端"

Build 开始干活：创建接口、修改 Service、写前端弹窗。我在旁边看着它一步步执行。

步骤 3：Explore 辅助搜索（不中断主流程）

Build 执行到一半，需要查某个配置在哪里：

@explore 找到系统中物流公司的配置在哪里

Explore 秒回：在 LogisticsConfig.java 第 42 行。Build 继续干活，整个过程没有中断。

步骤 4：Plan 复查（检查有没有遗漏）

改完后切回 Plan：

帮我 review 刚才的改动，有没有遗漏什么边界情况

Plan 发现了一个问题：没有处理订单已发货状态下不允许修改物流公司的校验。

步骤 5：Build 补完（修复遗漏）

切回 Build 修复这个遗漏，完成。

整个过程我没有手动打开过一个文件，没有自己跑过一次搜索。 这就是多代理协作的效率。

和第一篇的安装配置配合起来： 如果你还没配置好 OpenCode，先看OpenCode 打造个人 AI 智能体（一）：从安装到高效使用技巧把环境搭好，回来直接跟着这个流程练一遍。

---

四、如何选择：什么场景用什么 Agent

给你一个快速参考表：

场景	推荐 Agent	原因
写新代码、改 Bug	Build	全权限，直接干活
需求分析、方案设计	Plan	安全，先确认再执行
搜索定位代码	Explore	速度快，不干扰主任务
多步骤独立任务	General	可并行，不阻塞
Code Review	Plan	只读模式，安全
紧急线上问题排查	Explore → Build	先搜索定位 → 再修复
重构老模块	Plan → Build → Plan	先分析 → 执行 → 复查

---

五、自定义代理：把你的团队角色映射成 AI

除了内置的代理，你可以根据自己的项目需求创建自定义代理。下面分享几个我常用的自定义思路：

代码格式化专员

{
  "agents": {
    "Formatter": {
      "role": "primary",
      "permissions": {
        "read": true,
        "edit": true,
        "command": true
      },
      "prompt": "你只负责格式化代码，按照项目的代码规范调整缩进、命名、注释格式，不改业务逻辑"
    }
  }
}

数据库迁移专家

{
  "agents": {
    "DBMigrator": {
      "role": "primary",
      "permissions": {
        "read": true,
        "edit": true,
        "command": false
      },
      "prompt": "你负责数据库迁移脚本的编写和审查，熟悉 Flyway 和 Liquibase，确保每次迁移都是幂等的"
    }
  }
}

通过这种方式，你可以把团队里不同人的职责都对应到不同的代理上，分工协作，各司其职。

---

最后

多代理的核心价值不是 AI 有多强，而是让合适的 AI 做合适的事。

想写代码用 Build，想设计方案用 Plan，想快速搜索用 Explore——每个代理做自己最擅长的事，比你让一个 AI 干所有事要高效得多。

收藏建议： 把下面的速查表截图存到手机里，下次用 OpenCode 的时候对照着用。

场景	推荐代理	原因
写新代码、改 Bug	Build	全权限，直接干活
需求分析、方案设计	Plan	安全，先确认再执行
搜索定位代码	Explore	速度快，不干扰主任务
多步骤独立任务	General	可并行，不阻塞
Code Review	Plan	只读模式，安全
紧急线上问题排查	Explore → Build	先搜索定位 → 再修复
重构老模块	Plan → Build → Plan	先分析 → 执行 → 复查

---

如果这篇文章对你有帮助：

• 点赞收藏，下次用 OpenCode 的时候翻出来对照着用
• 评论区聊聊：你平时用 AI 编程遇到过什么痛点？子代理能帮你解决吗？

下一篇预告： OpenCode 的记忆体（Memory）系统——它怎么跨会话记住你的项目上下文，为什么说这是 OpenCode 区别于其他工具的关键能力。

---

系列目录

• ✅ 第一篇：OpenCode 介绍、安装、使用技巧
• ✅ 第二篇：子代理系统——Build、Plan、Explore 怎么用（本篇）
• ⬜ 第三篇：记忆体 Memory——让 AI 真正了解你的项目
• ⬜ 第四篇：技能系统——内置与自定义技能
• ⬜ 第五篇：工具链深度探索
• ⬜ 第六篇：实战——用 OpenCode 搭建完整开发工作流