6.2 内置 Agent：build

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-17

---

OpenCode 内置了 7 个 Agent，它们构成了系统的"Agent 生态骨架"。其中，build 是最核心的——它是用户默认交互的主 Agent，承担了绝大部分编码任务。本节将详细分析 build Agent 及其他内置 Agent 的配置与设计。

6.2.1 build Agent：默认主角

build: {
  name: "build",
  description: "The default agent. Executes tools based on configured permissions.",
  options: {},
  permission: PermissionNext.merge(
    defaults,
    PermissionNext.fromConfig({
      question: "allow",
      plan_enter: "allow",
    }),
    user,
  ),
  mode: "primary",
  native: true,
},

build 是 OpenCode 的"全能 Agent"——没有专属 Prompt（使用 Provider 默认 Prompt），没有指定模型（使用全局默认模型），没有步数限制。它的核心特征体现在权限配置上。

build 的默认权限

权限通过三层合并构成最终规则集：

第一层：defaults（全局默认权限）

const defaults = PermissionNext.fromConfig({
  "*": "allow",                    // 默认允许所有工具
  doom_loop: "ask",                // 循环检测时需要询问用户
  external_directory: {
    "*": "ask",                    // 访问外部目录默认需要询问
    [Truncate.GLOB]: "allow",      // 截断输出目录允许访问
    ...Object.fromEntries(
      skillDirs.map((dir) => [path.join(dir, "*"), "allow"])
    ),                             // Skill 目录允许访问
  },
  question: "deny",                // 默认不允许 question 工具
  plan_enter: "deny",              // 默认不允许进入 Plan 模式
  plan_exit: "deny",               // 默认不允许退出 Plan 模式
  read: {
    "*": "allow",                  // 允许读取所有文件
    "*.env": "ask",                // 读取 .env 文件需要询问
    "*.env.*": "ask",              // 读取 .env.* 文件需要询问
    "*.env.example": "allow",      // 但 .env.example 允许直接读
  },
})

这套默认权限的设计透露出几个安全理念：

1. 开放但有边界："*": "allow" 表示默认信任 Agent 使用所有工具，但对敏感操作（如读取环境变量文件、访问项目外目录）设置了额外的检查点。

2. 环境变量保护：.env 文件通常包含 API 密钥、数据库密码等敏感信息。OpenCode 借鉴了 GitHub 的 Node.gitignore 模式，对 *.env 和 *.env.* 文件实施"先问再读"策略，同时允许 .env.example（示例配置文件）自由读取。

3. 外部目录管控：external_directory 权限限制了 Agent 访问项目目录之外的文件。默认设为 "ask"——Agent 可以访问，但需要用户确认。这防止了 AI 意外修改系统文件或其他项目的代码。

第二层：build 专属权限叠加

PermissionNext.fromConfig({
  question: "allow",     // build 允许使用 question 工具（向用户提问）
  plan_enter: "allow",   // build 允许进入 Plan 模式
})

build 作为主 Agent，需要与用户交互的能力（question），也需要在复杂任务前进行规划（plan_enter）。这些能力对子 Agent 通常是不必要的——子 Agent 执行明确的任务，不需要"反过来问用户问题"。

第三层：用户自定义权限

const user = PermissionNext.fromConfig(cfg.permission ?? {})

用户可以在 opencode.json 中自定义权限规则，这些规则以最高优先级合并，覆盖前两层的默认值。

权限合并的语义

PermissionNext.merge() 函数将多层权限按顺序合并。后面的规则覆盖前面的同名规则：

PermissionNext.merge(defaults, buildSpecific, user)
//                    ↑ 最低优先级      ↑ 中间     ↑ 最高优先级

这意味着如果用户在配置中设置了 "bash": "deny"，即使 defaults 允许所有工具、build 没有显式限制 bash，最终 build Agent 也无法使用 bash 工具。

6.2.2 plan Agent：只读规划模式

plan: {
  name: "plan",
  description: "Plan mode. Disallows all edit tools.",
  options: {},
  permission: PermissionNext.merge(
    defaults,
    PermissionNext.fromConfig({
      question: "allow",
      plan_exit: "allow",
      external_directory: {
        [path.join(Global.Path.data, "plans", "*")]: "allow",
      },
      edit: {
        "*": "deny",
        [path.join(".opencode", "plans", "*.md")]: "allow",
        [/* 计划文件路径 */]: "allow",
      },
    }),
    user,
  ),
  mode: "primary",
  native: true,
},

plan Agent 是 build 的"只读版"——它可以阅读代码、搜索文件、与用户讨论方案，但禁止编辑任何文件，唯一的例外是 .opencode/plans/ 目录下的计划文件。

这种设计实现了一种"先规划、后执行"的工作流：

1. 用户进入 Plan 模式（通过 plan_enter 工具或 /plan 命令）。

2. Agent 切换到 plan 角色，只能读取和分析代码。

3. Agent 制定计划并写入 .opencode/plans/ 目录。

4. 用户确认后，Agent 退出 Plan 模式（plan_exit）回到 build 角色开始执行。

系统会在模式切换时注入相应的 Prompt：进入 Plan 模式时注入 plan.txt（强调只读约束），退出时注入 build-switch.txt（解除只读限制）。

6.2.3 general Agent：通用子 Agent

general: {
  name: "general",
  description: `General-purpose agent for researching complex questions 
    and executing multi-step tasks. Use this agent to execute 
    multiple units of work in parallel.`,
  permission: PermissionNext.merge(
    defaults,
    PermissionNext.fromConfig({
      todoread: "deny",
      todowrite: "deny",
    }),
    user,
  ),
  options: {},
  mode: "subagent",
  native: true,
},

general 是默认的子 Agent——当主 Agent 使用 Task 工具委托子任务但不指定特定 Agent 时，就会使用 general。

值得注意的是，general 禁用了 Todo 工具（todoread 和 todowrite 设为 "deny"）。这是因为 Todo 列表是主 Agent 的协调工具，子 Agent 管理自己的 Todo 会导致 Todo 列表混乱——多个子 Agent 同时修改同一个 Todo 列表可能产生冲突。

6.2.4 explore Agent：搜索专家

explore: {
  name: "explore",
  permission: PermissionNext.merge(
    defaults,
    PermissionNext.fromConfig({
      "*": "deny",           // 默认禁止所有工具
      grep: "allow",         // 只允许搜索类工具
      glob: "allow",
      list: "allow",
      bash: "allow",
      webfetch: "allow",
      websearch: "allow",
      codesearch: "allow",
      read: "allow",
      external_directory: {
        [Truncate.GLOB]: "allow",
      },
    }),
    user,
  ),
  description: `Fast agent specialized for exploring codebases...`,
  prompt: PROMPT_EXPLORE,
  options: {},
  mode: "subagent",
  native: true,
},

explore 是一个高度受限的专家 Agent。它的权限策略是"默认拒绝、白名单允许"（"*": "deny" + 具体工具 "allow"），与 build 的"默认允许、黑名单拒绝"形成鲜明对比。

explore 只能使用搜索类工具（grep、glob、read、bash 等），不能编辑文件、不能创建 Todo、不能委托子任务。这种设计确保了 explore 是一个安全的只读操作者——主 Agent 可以放心地将搜索任务委托给它，无需担心它产生副作用。

explore 还拥有专属 Prompt（prompt/explore.txt）：

You are a file search specialist. You excel at thoroughly navigating 
and exploring codebases.

Your strengths:
- Rapidly finding files using glob patterns
- Searching code and text with powerful regex patterns
- Reading and analyzing file contents

Guidelines:
- Do not create any files, or run bash commands that modify 
  the user's system state in any way

Prompt 再次强化了"只读"约束——即使权限系统意外放行了某个写入操作，Prompt 层面也明确禁止了修改行为。这种双重保障（权限 + Prompt）是 Agent 安全设计的典型模式。

6.2.5 辅助型 Agent：compaction、title、summary

这三个 Agent 都具有 hidden: true 属性，用户无法直接与它们交互，它们服务于系统内部功能：

compaction Agent

compaction: {
  name: "compaction",
  mode: "primary",
  native: true,
  hidden: true,
  prompt: PROMPT_COMPACTION,
  permission: PermissionNext.merge(defaults, 
    PermissionNext.fromConfig({ "*": "deny" }), user),
  options: {},
},

专门用于生成上下文压缩摘要。所有工具都被禁用（"*": "deny"）——它只需要阅读对话历史并生成摘要文本，不需要任何工具。

title Agent

title: {
  name: "title",
  mode: "primary",
  native: true,
  hidden: true,
  temperature: 0.5,       // 适中的随机性
  prompt: PROMPT_TITLE,
  permission: PermissionNext.merge(defaults,
    PermissionNext.fromConfig({ "*": "deny" }), user),
  options: {},
},

用于生成会话标题。值得注意的是它设置了 temperature: 0.5——标题生成需要一定的创造性（不能总是生成一样的标题），但又不能太离谱。

summary Agent

summary: {
  name: "summary",
  mode: "primary",
  native: true,
  hidden: true,
  prompt: PROMPT_SUMMARY,
  permission: PermissionNext.merge(defaults,
    PermissionNext.fromConfig({ "*": "deny" }), user),
  options: {},
},

用于生成 PR 风格的会话摘要。其 Prompt 要求"2-3 句话、第一人称、只描述变更不描述过程"。

6.2.6 Truncate.GLOB 的特殊处理

在所有 Agent 初始化完成后，系统还执行了一个全局修补步骤：

// 确保所有 Agent 都允许访问 Truncate 输出目录
for (const name in result) {
  const agent = result[name]
  const explicit = agent.permission.some((r) => {
    if (r.permission !== "external_directory") return false
    if (r.action !== "deny") return false
    return r.pattern === Truncate.GLOB
  })
  if (explicit) continue

  result[name].permission = PermissionNext.merge(
    result[name].permission,
    PermissionNext.fromConfig({ external_directory: { [Truncate.GLOB]: "allow" } }),
  )
}

回顾第 5 章的内容，当工具输出过长时，系统会将内容截断并写入临时文件（由 Truncate.GLOB 定义的路径）。为了让 Agent 能够读取这些截断后的完整输出，系统确保所有 Agent 都有权限访问截断输出目录——除非用户显式地拒绝了该路径。

这个"除非显式拒绝"的检查（explicit 变量）体现了对用户意志的尊重：如果用户真的想禁止某个 Agent 访问截断输出，系统不会越权覆盖。

6.2.7 内置 Agent 的设计哲学

纵观这 7 个内置 Agent 的设计，可以提炼出几个设计原则：

1. 权限最小化：每个 Agent 只拥有完成其职责所需的最小权限。explore 只能搜索，compaction 不能使用任何工具。

2. 关注点分离：每个 Agent 有明确的单一职责。title 只生成标题，summary 只生成摘要，不会有一个 Agent 既生成标题又编辑文件。

3. 双重安全：权限系统（硬限制）和 Prompt（软限制）共同约束 Agent 行为。即使一层失效，另一层仍能提供保护。

4. 用户优先：用户的自定义权限总是以最高优先级合并，用户甚至可以通过 disable: true 完全禁用某个内置 Agent。

---

下一节，我们将深入分析 Agent 的辅助功能——标题生成、摘要生成、上下文压缩、探索搜索和代码生成，理解它们的 Prompt 设计和调用方式。