引言

软件开发领域正在发生变化。曾经作为单一工具运行的 AI 助手，现在开始作为协作系统工作——每个处理特定任务，同时协调更大目标。这种向多智能体架构的转变为开发工作方式开辟了新的可能性。

在这篇文章里，我想分享我探索 OpenCode 多智能体系统的经历。与其说这是一个"解决方案"，不如说是一次实践和观察的旅程。我将讨论在设计智能体配置方面的收获、如何看待工作流编排，并分享一些日常开发中的真实例子。希望能给你一些可能有用的见解给正在探索类似系统的人。

多智能体领域背景

在深入具体配置之前，我认为有必要了解更广泛的背景。几份行业报告和调查提供了对了解这技术挺有帮助。

市场观察

最近的行业分析表明 AI 智能体采用率显著增长。根据 Deloitte 2025 年技术预测报告，自主人工智能智能体市场预计这几年将达到可观的规模。企业采用越来越快，不少组织正在试验智能体 AI 试点项目。

Stack Overflow 2025 年开发者调查提供了也说出了我的心声，表明大多数智能体用户报告了时间节省和生产效率提升。研究论文还记录了当 AI 编码智能体成为日常工作一部分时的效率提升。

这些趋势表明，多智能体系统将在开发实践中变得越来越重要。对于现在正在试验这些工具的人来说，了解它们的优势和局限性是有价值的。

协议发展

我一直感兴趣的一个领域是 AI 智能体通信协议的标准化。就像语言服务器协议（LSP）为编辑器和语言工具之间创建了通用接口一样，新协议正在出来了，以标准化智能体与开发环境和外部服务的交互方式。

Zed Editor 在 2025 年推出的 Agent Client Protocol (ACP) 提供了一种标准化的方式，让编辑器连接不同的智能体。这解决了一个实际问题：当智能体与特定工具绑定时，在环境之间切换变得麻烦。ACP 实现了更模块化的方法，智能体和编辑器可以独立发展。

Anthropic 在 2024 年底提出的模型上下文协议 (MCP) 作为 AI 智能体工具集成的事实标准获得了关注。VS Code 和 Cursor 等主要平台的采用表明，围绕某些接口模式正在形成共识。

我在 OpenCode 配置中集成了这两个协议。实际好处是灵活性——能够交换组件或扩展功能而无需重大重构。我觉得实验的有用基础。

我的 OpenCode 配置：技术概述

这节来说说我一直在开发的实际配置。我将专注于技术方面，而不是将其呈现为理想解决方案。你的需求可能不同，我希望希望对你有启发你自己的实验。

配置结构

所有 OpenCode 配置都存储在 Nix 仓库中，分门别类整理好：

configs/
├── opencode.json          # 主配置文件
├── agent/                 # 各个智能体定义
│   ├── ask.md
│   ├── build.md
│   ├── plan.md
│   ├── mentor.md
│   ├── orchestrator.md
│   ├── unittest.md
│   ├── code-review.md
│   ├── debugger.md
│   ├── security.md
│   ├── refactor.md
│   ├── frontend.md
│   ├── backend.md
│   ├── client.md
│   ├── ops.md
│   ├── docs.md
│   ├── explore.md
│   └── migration.md
└── prompts/               # 核心智能体的系统提示词
    ├── ask.txt
    ├── build.txt
    └── plan.txt

我是这么搭的是慢慢调整出来的的。早期版本更简单，需要时就加了智能体。这里的关键洞察是配置总是在演变的——没有"最终"状态。

平台同步

我在 NixOS 和 macOS 上工作，这提出了一个实际挑战：保持配置一致性。同步脚本自动处理这个问题：

#!/usr/bin/env bash
# 从 Nix 仓库同步 OpenCode 配置到系统

set -e

# 检测平台并定位 Nix 仓库
if [ -d "/Users/eric/nix" ]; then
  NIX_REPO="/Users/eric/nix"
elif [ -d "/home/eric/nix" ]; then
  NIX_REPO="/home/eric/nix"
else
  echo "错误：未找到 Nix 仓库" >&2
  exit 1
fi

CONFIG_SRC_DIR="$NIX_REPO/configs"
CONFIG_DIR="$HOME/.config/opencode"

mkdir -p "$CONFIG_DIR"
cp -r "$CONFIG_SRC_DIR/"* "$CONFIG_DIR/"

echo "OpenCode 配置已同步"

这个脚本是我日常工作的一部分，确保两个环境使用相同的配置而无需手动干预。

智能体系统：设计与实现

这节来说说我一直在探索的多智能体架构。我想清楚地说明设计理念和实际考虑——不是说这是最优的，而是分享在我的经验中什么是有效的。

核心设计理念

这系统围绕从实验中出来了的三个原则构建：

1. 专业化：每个智能体专注于特定领域，具有明确定义的职责
2. 权限边界：不同的智能体有不同的能力级别，防止意外操作
3. 委托路径：明确何时使用哪个智能体的规则

这些原则是通过试错发展而来的。早期版本有职责重叠的智能体，这导致了困惑。当前设计是从观察协作何时中断并相应地进行改进中出来了的。

智能体生态系统概述

系统共包含 17 个智能体——3 个核心智能体和 14 个专业子智能体：

核心智能体

三个核心智能体作为不同任务类型的入口点：

ask - 只读顾问，用于概念性问题：

• 权限：只读（无写入、编辑或执行）
• 适用于：解释概念、不修改的审查、通用指导
• 行为：提供信息和解释，将行动导向的任务委托出去

plan - 复杂任务的架构规划：

• 权限：只读（从不修改文件）
• 适用于：设计实现方法、创建架构路线图
• 行为：分析需求、考虑权衡、产出结构化计划

build - 主要实现智能体：

• 权限：完全访问（读取、写入、编辑、执行）
• 适用于：编写新代码、修复 Bug、把活干完
• 行为：分析需求、生成代码、验证结果

专业子智能体

14 个专业子智能体覆盖特定领域：

架构与质量（4 个智能体）：

• mentor：提供架构和性能指导，不编写代码
• code-review：执行静态分析、风格检查和可维护性审计
• refactor：在保留功能的同时重构代码结构
• security：扫描漏洞和合规性问题

开发（4 个智能体）：

• frontend：专注于 React、Vue、CSS 框架和无障碍访问
• backend：处理 API 设计、业务逻辑和数据库架构
• client：专注于 SDK 开发和 Kotlin/Kotlin Multiplatform
• ops：管理 Docker、CI/CD、Nix 和部署配置

运维与测试（3 个智能体）：

• unittest：创建和优化测试套件
• debugger：诊断运行时问题和逻辑 Bug
• migration：处理框架升级和平台迁移

发现与文档（2 个智能体）：

• explore：导航代码库以识别模式和依赖关系
• docs：创建文档、README 和 API 规范

协调（1 个智能体）：

• orchestrator：协调多个智能体处理复杂工作流

权限系统

权限模型实现了渐进的访问级别：

这个模型是从实践经验发展而来的。早期版本有二元权限（可以/不能编辑），这导致智能体无法执行必要操作的情况。渐进模型在保持安全边界的同时提供了更多灵活性。

委托与工作流模式

有效使用多智能体系统需要了解何时使用哪个智能体，以及如何协调它们处理复杂任务。

委托框架

任务类型	复杂度	推荐智能体
概念解释	低	ask
简单代码更改	低-中	build
领域特定任务	中-高	专业智能体
跨域项目	高	orchestrator

这个框架是起点，别当死规矩。说白了，具体的智能体选择得看实际情况。

委托决策流程

常见工作流模式

通过实验，我识别出几种有用的模式：

模式 1：功能实现链

这个简单的链式结构适用于直接的功能实现。每个智能体验证前一个输出。

模式 2：Bug 解决流程

对于 Bug 修复，从诊断开始能帮到确保在实现修复之前理解实际问题。

模式 3：架构优化流程

性能优化在实现前进行明确的架构评估会受益。

模式 4：跨平台开发

对于具有独立组件的项目，并行执行可以显著减少开发时间。

MCP 集成

模型上下文协议 (MCP) 使智能体能够与外部服务交互。以下是我在实践中如何配置它。

MCP 服务概述

服务描述

Jina MCP 服务器：提供实时网络搜索、内容提取和学术论文搜索能力。当需要代码库之外的当前信息时很有用。

Context7：提供库和框架的最新文档。帮助智能体访问准确的 API 参考，而不依赖于可能过时的训练数据。

GitHub MCP：与版本控制工作流集成，使智能体能够创建分支、管理 issue 和处理 pull request。

配置示例

{
  "mcp": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1",
      "type": "remote",
      "enabled": true
    },
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    },
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      },
      "enabled": true
    }
  }
}

实际例子

这节分享我开发实践中的一些真实例子。目标是说明多智能体系统如何在实践中工作，包括成功和局限性。

例子 1：构建任务管理应用程序

背景：使用 React 前端和 FastAPI 后端开发任务管理应用程序。

方法：

1. 规划阶段：使用 plan 设计整体架构，使用 mentor 审查关键决策
2. 开发阶段：frontend、backend 和 docs 智能体并行运行
3. 集成阶段：使用 unittest 生成测试，使用 code-review 进行一致性检查
4. 部署阶段：使用 ops 配置 CI/CD

观察：

• 并行执行显著减少了开发时间
• 跨智能体一致性检查发现了几个问题
• orchestrator 有效处理了协调工作

指标（来自这个特定项目）：

指标	值
开发时间	1.2 周
测试覆盖率	89%
生产中的关键 Bug	1 个

例子 2：调试并发问题

背景：调查生产服务中间歇性出现的数据竞争条件。

方法：

1. 探索：使用 explore 配合不同的 MCP 服务（Context7 查找类似问题，Jina 搜索研究论文）
2. 诊断：使用 debugger 进行日志分析，使用 mentor 进行架构审查
3. 实现：使用 refactor 进行修复，使用 unittest 进行压力测试
4. 验证：使用 code-review 和 security 进行验证

观察：

• 多个视角（代码分析、社区知识、学术研究）提供了更完整的画面
• 分层验证方法发现了边缘情况
• 通过全面测试提高了对修复的统计置信度

关键收获

通过这些例子和其他经历，出现了几种模式：

1. 多视角有帮助：结合代码分析和外部研究通常能揭示单一智能体可能遗漏的洞察
2. 验证层很重要：每个阶段有专门的验证提高了整体质量
3. 并行执行效率：独立组件从并行执行中显著受益
4. 协调是关键：orchestrator 在管理复杂工作流中的作用至关重要

最佳实践

我觉得，以下是一些有用的实践：

1. 智能体选择

• 使用只读智能体（mentor、explore）进行分析和指导
• 仅在需要修改时使用完全访问智能体（build、refactor）
• 更改后始终使用 unittest
• 对处理敏感数据的任何代码使用 security

2. 工作流设计

• 复杂任务从 ask 或 plan 开始以获得方向
• 对独立组件使用并行执行
• 对依赖任务使用串行执行
• 以 code-review 结束以保证质量

3. 权限管理

• 使用前审查智能体权限
• 了解能力边界
• 对跨域协调使用 orchestrator

4. 版本控制

• 将配置更改提交到版本控制
• 记录重大修改的理由
• 跟踪哪些工作流模式效果好

5. 跨平台考虑

• 在所有目标平台上测试配置
• 尽可能自动化同步
• 保持文档更新

扩展系统

这配置设计为可扩展的。以下是常见扩展的实际例子。

添加新智能体

1. 创建智能体定义文件：

# configs/agent/my-custom-agent.md
---
description: 特定任务的自定义智能体
mode: subagent
model: opencode/gemini-3-flash
temperature: 0.5
permission:
  edit: allow
  write: allow
  bash: allow
---

# Role: 自定义智能体

你是[特定目的]的专门智能体。

## 核心指令
1. [指令 1]
2. [指令 2]

## 约束
- [约束 1]
- [约束 2]

2. 在 opencode.json 中注册：

{
  "agent": {
    "my-custom-agent": {
      "description": "自定义智能体描述",
      "mode": "subagent",
      "model": "opencode/gemini-3-flash",
      "prompt": "{file:./agent/my-custom-agent.md}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    }
  }
}

3. 同步并重启 OpenCode：

~/nix/scripts/sync-opencode.sh

修改系统提示词

编辑 configs/prompts/ 中的提示词：

• ask.txt：调整顾问行为
• plan.txt：修改规划方法
• build.txt：改变实现方法

添加 MCP 服务

{
  "mcp": {
    "my-service": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "enabled": true
    }
  }
}

结束语

这篇对 OpenCode 多智能体系统的探索之旅，说白了就是一次学习经历。这项技术仍在发展中，有许多关于有效模式和实践的东西有待发现。

我在这里分享的内容代表了我目前的理解——在我的情境中有效的事情，可能是有用的起点。领域发展迅速，我预计随着生态系统的成熟，许多方法将会演变。

这次旅程中的一些观察：

1. 多智能体系统是工具，不是解决方案：它们的价值取决于如何应用于实际问题
2. 实验是必不可少的：在一个情境中有效的方法在另一个情境中可能无效
3. 这领域发展特别快：新的协议、模式和能力 regularly 出现
4. 社区知识是有价值的：分享经验能帮到每个人改进

我希望这篇文章为正在探索类似系统的人提供了有用的见解。目标不是规定特定方法，而是为多智能体架构如何支持开发工作的集体理解做出贡献。

结尾小彩蛋：这篇文章其实是用多智能体系统写的——某种意义上说，它是自己"生"出来的。

---

参考文献

• Deloitte 2025 AI Agent 编排报告
• Agent Client Protocol (ACP) 规范
• 模型上下文协议 (MCP) 规范
• Stack Overflow 2025 AI 开发者调查
• OpenCode 文档
• Zed Editor "Bring Your Own Agent" 公告