如果你想在 OpenCode 里配置一套可复用的多 Agent 项目开发流程，推荐采用下面这套结构：

• 模型配置放用户级：~/.config/opencode/opencode.json，适合放 provider、model、MCP、default_agent 和 API Key。
• Agent 文件放项目级：.opencode/agents/，适合进 Git，团队共享和 review。
• 主 Agent 只做编排：orchestrator 负责拆解、路由、汇总和验收判断，不直接写代码。
• 子 Agent 分工执行：architect 做方案，executor 写代码，reviewer 审查验证，bulk 做机械修改，vision 读图，commenter 补注释。
• 视觉能力低频使用时走委托：主模型保持纯文本，只有需要读图时才调用 vision 子 Agent。

这套方案的核心是：问题拆解 → 子 Agent 分工 → 权限隔离 → reviewer 验证闭环。

---

一、场景背景

单 Agent 做项目开发时，经常会遇到几个问题：

1. 职责混乱：同一个 Agent 同时做需求分析、方案设计、代码实现和自我审查。
2. 权限过大：Agent 既能改文件，又能执行 bash，还能联网，误操作风险较高。
3. 自审偏差：实现和审查由同一个模型完成，容易漏掉自己生成代码里的问题。
4. 视觉成本难控：偶尔需要读截图或设计稿，但如果主 Agent 一直用视觉模型，成本和模型选择都会被绑定。
5. 团队难复用：每个人临时写 prompt，流程无法标准化，也不方便 code review。

所以更工程化的做法是：把开发流程拆成多个职责清晰的 Agent，并用权限配置限制每个 Agent 能做什么。

本文使用 7 个 Agent：

Agent	类型	职责	示例模型	权限原则
orchestrator	primary	需求拆解、任务路由、结果汇总、验收判断	glm-5.2	只读和调用子 Agent，禁止 edit/bash/联网
architect	subagent	需求澄清、方案设计、接口划分、测试矩阵	claude-opus-4-8	只读，不改代码
executor	subagent	按方案实现、调试、运行验证命令	glm-5.2	可 edit，bash 需确认
reviewer	subagent	读 diff、运行验证、报告阻塞问题	gpt-5.5	只读，bash 白名单限验证命令
bulk	subagent	变量重命名、样板代码、测试补齐等机械任务	glm-5.2	可 edit，禁 bash
vision	subagent	读取截图、设计稿、错误截图、代码图片	kimi-k2.6	hidden，只读图，不做技术决策
commenter	subagent	补充代码注释和文档注释	glm-5.1	可 edit，禁 bash/联网

---

二、技术方案

2.1 推荐目录结构

OpenCode 配置分两层：用户级和项目级。

推荐结构如下：

~/.config/opencode/
└── opencode.json

项目目录/
├── .opencode/
│   └── agents/
│       ├── orchestrator.md
│       ├── architect.md
│       ├── executor.md
│       ├── reviewer.md
│       ├── bulk.md
│       ├── vision.md
│       └── commenter.md

两层配置的建议分工：

层级	路径	放什么	原因
用户级	~/.config/opencode/opencode.json	provider、model、MCP、API Key、default_agent	跨项目复用，避免密钥进仓库
项目级配置	opencode.json 或 .opencode/opencode.json	与项目强绑定的配置	团队共享
项目级 Agent	.opencode/agents/	Agent markdown 文件	便于 Git 管理和 review

当用户级和项目级同时存在时，OpenCode 会做深度合并；同名字段以项目级为准。也就是说：团队强约束放项目级，个人密钥和偏好放用户级。

---

2.2 配置 provider 和 model

以原文中的 ModelVerse 接入点为例，OpenAI 兼容接入点通常需要配置：

• name：展示名。
• npm：SDK 包名，OpenAI 兼容接入点使用 @ai-sdk/openai-compatible。
• options.apiKey：接入点密钥。
• options.baseURL：接口地址，示例为 https://api.modelverse.cn/v1。
• models：模型声明，Agent 中引用的模型 ID 必须提前声明。

示例配置如下，真实 API Key 不要提交进仓库：

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "orchestrator",
  "mcp": {
    "playwright": {
      "command": ["npx", "-y", "@playwright/mcp@latest"],
      "enabled": true,
      "type": "local"
    }
  },
  "provider": {
    "modelverse": {
      "name": "ModelVerse",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "apiKey": "<your-modelverse-api-key>",
        "baseURL": "https://api.modelverse.cn/v1"
      },
      "models": {
        "glm-5.2": { "name": "GLM-5.2" },
        "glm-5.1": { "name": "GLM-5.1" },
        "claude-opus-4-8": { "name": "Claude Opus 4.8" },
        "gpt-5.5": { "name": "GPT-5.5" },
        "kimi-k2.6": {
          "name": "KiMi-2.6",
          "attachment": true,
          "tool_call": true,
          "temperature": true,
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          },
          "family": "kimi",
          "limit": {
            "context": 128000,
            "output": 16000
          }
        },
        "glm-5v-turbo": {
          "name": "GLM-5V-Turbo",
          "attachment": true,
          "tool_call": true,
          "temperature": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "family": "glm",
          "limit": {
            "context": 128000,
            "output": 8192
          }
        }
      }
    }
  }
}

这里有一个常见坑：

如果 Agent 中写了：

model: modelverse/glm-5.2

那么 glm-5.2 必须存在于 provider.modelverse.models 中，否则 OpenCode 启动或调用时可能直接报错。

---

2.3 视觉模型配置：modalities 和 attachment 必须同时声明

如果某个模型需要处理图片，必须关注两个字段：

字段	作用	漏配后果
modalities.input 包含 image	告诉 OpenCode 该模型支持图片输入	客户端可能直接拦截图片输入，提示模型不支持 image input
attachment: true	告诉 OpenCode 该模型支持附件上传	附件链路可能无法工作

但要注意：这两个字段只是让 OpenCode 客户端放行，并不代表模型服务端一定支持视觉能力。模型和接入点本身也必须真实支持图片输入。上线前建议用官方文档或最小多模态请求验证。

---

2.4 配置 Agent：一个 Agent 就是一份 Markdown 文件

在 OpenCode 中，一个 Agent 通常是一份带 frontmatter 的 Markdown 文件。

frontmatter 负责声明：

• description：Agent 描述，也是 orchestrator 路由的重要依据。
• mode：primary 表示主 Agent，subagent 表示子 Agent。
• model：绑定模型，如 modelverse/glm-5.2。
• permission：工具权限。
• hidden：是否隐藏，适合 vision 这种只希望被委托调用的 Agent。

description 很关键，建议写清楚“当需要什么时使用”。如果描述太模糊，orchestrator 的任务路由就容易出错。

---

2.5 主 Agent：orchestrator

orchestrator 是唯一主 Agent，只做编排，不直接写代码。

---
description: 主编排。拆解需求、调用规划 Agent、派发实现与审查任务、控制返工与验收。默认不直接修改代码。
mode: primary
model: modelverse/glm-5.2
permission:
  read: allow
  glob: allow
  grep: allow
  edit: deny
  bash: deny
  webfetch: deny
  websearch: deny
  lsp: deny
  todowrite: allow
  question: allow
  task:
    "*": deny
    "architect": allow
    "executor": allow
    "reviewer": allow
    "bulk": allow
    "vision": allow
    "commenter": allow
---
你是编排者，职责严格限定为：需求拆解、任务路由、汇总子 Agent 结果、控制返工与验收。

绝对禁止：
- 禁止自行产出代码实现、补丁、命令脚本。
- 禁止自行产出审查结论或最终技术方案。
- 禁止自行回答本应由子 Agent 完成的工作。
- 禁止编辑文件、执行 bash、联网搜索。

你必须做且只做以下动作：
1. 读取需求与上下文，明确目标、边界、验收标准和风险等级。
2. 复杂任务或者目标不够清晰的任务，调用 architect。
3. 方案明确后，调用 executor 实现。
4. 低风险机械任务调用 bulk。
5. 每次代码修改后调用 reviewer 审查和验证。
6. 若验证失败，返回 executor 修复，不要自己改。
7. 只根据 reviewer 的客观验证结果和风险等级做验收判断。

---

2.6 子 Agent：architect / executor / reviewer / bulk / vision / commenter

architect：方案设计

---
description: 规划与架构。当需要需求澄清、方案设计、接口划分、数据流设计、测试矩阵或验收标准时使用。只读代码库，产出决策完整的方案，不修改代码。
mode: subagent
model: modelverse/claude-opus-4-8
permission:
  read: allow
  glob: allow
  grep: allow
  edit: deny
  bash: deny
  webfetch: deny
  websearch: deny
---
你负责规划与架构。先理解相关代码和约束，再输出决策完整的方案。
方案必须包括模块划分、接口变化、数据流、错误处理边界、测试矩阵和验收标准。
不写实现代码，不修改文件。

executor：代码实现

---
description: 实现与执行。当需要跨文件修改、调试、构建、运行测试或修复返工时使用。根据既定方案完成代码修改，运行项目规定的验证命令。
mode: subagent
model: modelverse/glm-5.2
permission:
  read: allow
  glob: allow
  grep: allow
  edit: allow
  bash: ask
---
你负责按方案实现。修改前先确认影响范围，修改后运行项目规定的验证命令。
返回内容必须包括：修改摘要、影响文件、运行命令、测试结果和未解决风险。

reviewer：审查验证

---
description: 审查与验证。当需要读取 diff、运行验证命令、发现阻塞问题或判断是否返工时使用。只读 diff，运行项目规定的验证命令，只报告阻塞性问题，不修改代码。
mode: subagent
model: modelverse/gpt-5.5
permission:
  read: allow
  glob: allow
  grep: allow
  edit: deny
  bash:
    "*": deny
    "git status": allow
    "git diff*": allow
    "git show*": allow
    "git log*": allow
    "npm test*": allow
    "pnpm test*": allow
    "yarn test*": allow
    "go test*": allow
    "pytest*": allow
    "mvn test*": allow
    "gradle test*": allow
    "make test*": allow
    "npm run lint*": allow
    "npm run typecheck*": allow
    "tsc*": allow
---
你负责在独立上下文中审查代码。只报告阻塞性问题。
必须读取 diff，并尽可能运行项目声明的验证命令。
不修改代码，不提出无关风格建议。
返回内容必须包括：验证命令、执行结果、阻塞问题、是否建议返工。

bulk：低风险批量修改

---
description: 当需要变量重命名、样板代码、测试补齐等低风险机械任务时使用。处理明确、机械性的修改，遇复杂问题停止并交回编排者。
mode: subagent
model: modelverse/glm-5.2
permission:
  read: allow
  glob: allow
  grep: allow
  edit: allow
  bash: deny
---
你只处理明确、低风险、机械性的修改。
遇到需要架构判断、业务判断或跨模块影响的问题，必须停止并交回编排者。
你的修改结果必须进入 reviewer 验证，不能直接合并。

vision：视觉读图

---
description: 视觉读图。当需要读取图片内容、分析 UI 截图、比对设计稿或提取图片中的文字/代码/结构信息时使用。只读图并返回结构化描述，不做架构判断或代码实现。
mode: subagent
model: modelverse/kimi-k2.6
hidden: true
permission:
  read: allow
  glob: deny
  grep: deny
  edit: deny
  bash: deny
  webfetch: deny
  websearch: deny
---
你是专用的视觉读图 Agent，职责严格限定为：读取图片内容并返回结构化描述。

绝对禁止：
- 禁止产出代码实现、架构方案或技术决策。
- 禁止产出审查结论或验收判断。
- 禁止修改文件、执行命令或联网搜索。
- 禁止对图片内容进行推测性补充。

你必须做且只做以下动作：
- 读取用户提供的图片。
- 准确描述图片中的可见内容。
- 以结构化格式返回，便于编排者分发给其他 Agent。
- 若图片模糊、不完整或无法识别，明确说明限制，不要猜测。

commenter：代码注释

---
description: 代码注释。当需要为代码补充或完善注释、文档注释、函数说明时使用。只加注释不改业务逻辑，不执行命令。
mode: subagent
model: modelverse/glm-5.1
permission:
  read: allow
  glob: allow
  grep: allow
  edit: allow
  bash: deny
  webfetch: deny
  websearch: deny
---
你是专用的代码注释 Agent，职责严格限定为：为代码补充和完善注释，不改业务逻辑。

绝对禁止：
- 禁止修改函数签名、业务逻辑、控制流、数据结构。
- 禁止执行命令、联网搜索。
- 禁止产出架构方案或审查结论。

你必须做且只做以下动作：
- 读取目标代码，理解其功能与边界。
- 为函数、类、复杂逻辑补充注释。
- 优先使用项目已有注释风格。
- 不为显而易见的代码加冗余注释。
- 修改结果必须进入 reviewer 验证。

---

三、核心指标

这套多 Agent 配置不是看“Agent 数量多不多”，而是看下面几个工程指标是否达标。

3.1 权限隔离是否清晰

关键检查项：

• orchestrator 是否禁止 edit 和 bash。
• architect 是否只读。
• executor 是否可写但 bash 需要确认。
• reviewer 是否禁止改代码，只允许运行验证命令。
• vision 是否只负责读图，不参与架构和实现。

3.2 路由是否稳定

路由稳定性主要依赖 description。

建议每个 Agent 的 description 都写成类似：

当需要 xxx 时使用。负责 xxx，不负责 xxx。

否则 orchestrator 可能会把实现任务派给 architect，或者把架构判断派给 bulk。

3.3 验证闭环是否成立

至少要形成这个闭环：

需求 → architect 出方案 → executor 实现 → reviewer 读 diff 和运行验证 → orchestrator 汇总验收

如果项目没有测试、lint、typecheck 或类似验证命令，reviewer 的价值会下降。

3.4 视觉能力是否按需使用

主模型是否需要支持 vision，取决于读图频率：

方案	适合场景	优点	代价
主模型直接支持 vision	高频截图、设计稿、图片输入任务	简单直接	主 Agent 长期绑定视觉模型，成本和模型选择受影响
vision 子 Agent 委托	低频读图，主要是文本开发任务	主 Agent 可用纯文本模型，按需读图	多一层委托，需要配置正确

本文采用第二种方案：orchestrator 使用纯文本 glm-5.2，vision 使用 kimi-k2.6。

---

四、实测验证：用 HTML 五子棋跑通链路

原文使用一个 HTML 五子棋游戏验证了整套多 Agent 流程。

需求是：

做一个 HTML 五子棋游戏，双人轮流落子，判断胜负。

执行链路如下：

1. 用户把需求发给 orchestrator。
2. orchestrator 拆解需求，调用 architect。
3. architect 输出棋盘数据结构、胜负判定逻辑、交互流程和验收标准。
4. orchestrator 派 executor 实现 index.html 和游戏逻辑。
5. executor 修改完成后，orchestrator 调 reviewer。
6. reviewer 读取 diff，运行可用验证命令，报告阻塞问题或放行。
7. 如果需要补注释，再调用 commenter。
8. 最终五子棋可以运行，支持双人轮流落子和胜负判断。

（orchestrator 收到需求，开始拆解）

（architect 给出棋盘数据结构、胜负判定、交互逻辑的方案）

（executor 按 architect 方案落地 index.html 和游戏逻辑）

（reviewer 读 diff、跑验证，报告阻塞性问题或放行）

（五子棋跑起来，双人轮流落子，能判胜负）

这个实测的价值不在于五子棋本身，而在于验证了这条链路：

问题：单 Agent 职责混杂、权限过大、验证不独立
解决方案：7 个 Agent 分工 + 权限隔离 + reviewer 验证
验证：用 HTML 五子棋跑通需求、方案、实现、审查和运行结果

---

五、适用 / 不适用场景

5.1 适合使用这套方案的场景

• 团队希望标准化 AI 编程流程，而不是每个人随意 prompt。
• 项目需要共享 Agent 编排规则。
• 开发任务经常包含需求澄清、方案设计、代码实现、审查验证、注释等环节。
• 希望通过权限隔离降低误改代码、误执行命令的风险。
• 读图是低频需求，但偶尔需要分析截图、设计稿、错误截图。
• 希望不同模型承担不同任务，降低同源自审偏差。

5.2 不适合或不建议直接使用的场景

• 只是一次性小脚本，单 Agent 就够。
• 团队还没有明确模型接入点和 API Key 管理方式。
• 项目没有任何测试、lint、typecheck 或验证命令，reviewer 闭环较弱。
• 高频视觉任务占主导，此时主 Agent 直接使用视觉模型可能更简单。
• 不愿意维护 Agent Markdown 和权限策略，只想快速试验。

---

六、常见坑

6.1 把真实 API Key 提交进仓库

模型配置如果放项目级，一定要注意密钥泄露风险。更稳妥的方式是把含 API Key 的 provider 配置放在用户级：

~/.config/opencode/opencode.json

6.2 Agent 引用的模型没有在 provider 中声明

例如 Agent 中写：

model: modelverse/gpt-5.5

但 provider models 里没有 gpt-5.5，就可能启动或调用失败。

6.3 视觉模型漏配 attachment 或 modalities

需要读图的模型必须同时满足：

{
  "attachment": true,
  "modalities": {
    "input": ["text", "image"],
    "output": ["text"]
  }
}

只配其中一个不够。

6.4 orchestrator 权限过大

如果 orchestrator 既能 edit 又能 bash，它很容易绕过子 Agent 分工，直接实现或执行命令。这样多 Agent 编排就失去意义。

6.5 reviewer 没有验证命令

reviewer 最好至少能运行：

• git diff
• npm test / pnpm test
• npm run lint
• npm run typecheck
• pytest
• go test
• mvn test

具体命令按项目技术栈调整。

---

七、FAQ

Q1：为什么 orchestrator 不直接写代码？

因为 orchestrator 的职责是编排。如果它同时负责方案、实现和审查，会导致权限过大和自审偏差。更稳妥的做法是：executor 写代码，reviewer 独立验证，orchestrator 只汇总和判断是否返工。

Q2：为什么 Agent 要用 Markdown 文件？

Markdown 易读、易改、易进 Git review。相比把 prompt 塞进 JSON，Markdown 更适合团队维护职责说明、行为约束和权限边界。

Q3：为什么 reviewer 要用和 executor 不同的模型？

原文设计思路是降低同源自审偏差。executor 使用 glm-5.2，reviewer 使用 gpt-5.5。这不是唯一选择，核心原则是实现和审查尽量分离。

Q4：配置了 modalities.input 和 attachment 就一定能读图吗？

不一定。这两个字段只是让 OpenCode 客户端放行图片输入。模型和接入点服务端仍然必须真实支持视觉能力。上线前应查官方文档或用最小多模态请求验证。

Q5：低频读图为什么推荐 vision 子 Agent？

因为主 Agent 的大部分工作是拆解、路由和汇总，并不需要视觉能力。用 vision 子 Agent 可以让主模型保持纯文本，只在需要时调用视觉模型。

Q6：这套 7 Agent 配置可以直接复制到任何项目吗？

可以作为模板，但不建议无脑复制。你需要根据实际 OpenCode 版本、模型接入点、模型 ID、权限要求和项目验证命令做调整，尤其不要提交真实 API Key。

Q7：skill 在这里怎么用？

原文只提到 skill 是 permission 字段之一，用于控制 Agent 是否可以加载 skill，但没有提供具体 skill 配置样例。因此本文不扩展虚构用法。

---

九、参考链接

• OpenCode 配置 schema 示例：https://opencode.ai/config.json
• 示例 ModelVerse baseURL：https://api.modelverse.cn/v1