04-智能体协同工作架构设计

骤跌2026-02-12 12:13

智能体协同工作架构设计

opencode专栏其他内容：

文章目录

  • 智能体协同工作架构设计
    • [1. 协同工作模式](#1. 协同工作模式)
      • [1.1 Orchestrator 模式（推荐）](#1.1 Orchestrator 模式（推荐）)
      • [1.2 直接调用模式](#1.2 直接调用模式)
      • [1.3 工作流模式](#1.3 工作流模式)
    • [2. 架构设计原则](#2. 架构设计原则)
      • [2.1 单一职责原则（SRP）](#2.1 单一职责原则（SRP）)
      • [2.2 API 契约原则](#2.2 API 契约原则)
      • [2.3 并行执行原则](#2.3 并行执行原则)
      • [2.4 松耦合原则](#2.4 松耦合原则)
    • [3. 技术栈检测策略](#3. 技术栈检测策略)
      • [3.1 文件检测法](#3.1 文件检测法)
      • [3.2 配置检测法](#3.2 配置检测法)
      • [3.3 混合检测法](#3.3 混合检测法)
    • [4. 任务分配策略](#4. 任务分配策略)
      • [4.1 自动分配](#4.1 自动分配)
      • [4.2 条件分配](#4.2 条件分配)
      • [4.3 手动指定](#4.3 手动指定)
    • [5. 协同工作流程图](#5. 协同工作流程图)
      • [5.1 完整协作流程（Mermaid）](#5.1 完整协作流程（Mermaid）)
      • [5.2 时序图](#5.2 时序图)
      • [5.3 状态图](#5.3 状态图)
    • [6. 设计模式总结](#6. 设计模式总结)
      • [6.1 核心模式](#6.1 核心模式)
      • [6.2 设计原则检查清单](#6.2 设计原则检查清单)
    • [7. 总结](#7. 总结)

1. 协同工作模式

在 OpenCode 中，多智能体协同工作主要有以下几种模式：

1.1 Orchestrator 模式（推荐）

架构：

复制代码 
用户
  ↓
Orchestrator（协调者）
  ↓
┌──────────┬──────────┐
↓          ↓          ↓
Backend   Backend   Frontend
(Java)   (Python)   (Vue)
  └──────────┬──────────┘
             ↓
       结果汇总

特点：

  • 一个主智能体（Orchestrator）负责协调
  • 多个子智能体并行执行任务
  • Orchestrator 负责检测技术栈、分配任务、整合结果
  • 适合复杂的多技术栈项目

适用场景：

  • 全栈开发（前后端分离）
  • 多语言项目（Java + Python）
  • 需要统一协调的复杂任务

1.2 直接调用模式

架构：

复制代码 
用户
  ↓
主智能体（Build/Plan）
  ↓
需要时调用 @subagent
  ↓
返回结果继续处理

特点：

  • 主智能体按需调用子智能体
  • 串行执行，任务一个接一个
  • 适合简单的专项任务

适用场景：

  • 单一技术栈的简单任务
  • 代码审查（调用 @code-reviewer）
  • 文档编写（调用 @docs-writer）

1.3 工作流模式

架构：

复制代码 
步骤1 → 步骤2 → 步骤3 → 步骤4
   ↓       ↓       ↓       ↓
Agent1  Agent2  Agent3  Agent4

特点：

  • 预定义的工作流程
  • 每个步骤由特定智能体处理
  • 前一个步骤的输出作为后一个步骤的输入

适用场景：

  • CI/CD 流程
  • 标准化的开发流程
  • 代码审查 → 修复 → 测试 → 部署

2. 架构设计原则

2.1 单一职责原则（SRP）

原则：每个智能体只负责一个具体的职责。

示例：

复制代码 
❌ 不好的设计：
FullstackAgent（既做前端又做后端）

✅ 好的设计：
- FrontendAgent（前端开发）
- BackendJavaAgent（Java后端）
- BackendPythonAgent（Python后端）
- DevOpsAgent（部署运维）

好处：

  • 职责清晰，易于维护
  • 可以并行开发
  • 便于测试和调试

2.2 API 契约原则

原则：前后端必须通过明确的 API 契约进行通信。

API 契约内容：

  1. URL 路径和 HTTP 方法

    复制代码 
    GET    /api/users          # 获取用户列表
POST   /api/users          # 创建用户
GET    /api/users/{id}     # 获取用户详情
PUT    /api/users/{id}     # 更新用户
DELETE /api/users/{id}     # 删除用户

  2. 请求参数格式

    json 复制代码 
    // Query 参数
GET /api/users?page=0&size=10&keyword=john

// Body 参数
POST /api/users
{
  "username": "john",
  "email": "john@example.com",
  "password": "123456"
}

  3. 响应数据结构

    json 复制代码 
    {
  "code": 200,
  "data": {
    "id": 1,
    "username": "john",
    "email": "john@example.com"
  },
  "message": "success"
}

  4. 错误码定义

    复制代码 
    200 - 成功
400 - 请求参数错误
401 - 未认证
403 - 无权限
404 - 资源不存在
500 - 服务器错误

  5. 认证方式

    复制代码 
    Authorization: Bearer <JWT_TOKEN>

好处：

  • 前后端可以独立开发
  • 便于并行工作
  • 便于测试和文档化

2.3 并行执行原则

原则：独立的任务应该并行执行，提高效率。

示例：

复制代码 
用户：实现用户管理系统

串行执行（低效）：
BackendAgent 开发 API（10分钟）
  ↓
FrontendAgent 开发页面（10分钟）
  ↓
总计：20分钟

并行执行（高效）：
BackendAgent 开发 API ─┐
                       ├→ 同时进行（10分钟）
FrontendAgent 开发页面─┘
  ↓
总计：10分钟

Orchestrator 的并行执行策略：

javascript 复制代码 
// 并行调用多个子智能体
await Promise.all([
  task({ 
    subagent_type: 'backend-java', 
    prompt: '实现用户管理API...' 
  }),
  task({ 
    subagent_type: 'frontend-vue', 
    prompt: '实现用户管理页面...' 
  })
])

2.4 松耦合原则

原则：智能体之间应该尽量减少依赖，通过明确的接口通信。

实现方式：

  1. 通过 Orchestrator 中转

    复制代码 
    Agent A → Orchestrator → Agent B

  2. 共享配置文件

    yaml 复制代码 
    # api-contract.yaml
endpoints:
  - path: /api/users
    method: GET
    response: UserListResponse

  3. 使用 Skills 共享知识

    复制代码 
    java-api Skill ─┐
                ├→ 共享的 API 规范
vue-api Skill ──┘

3. 技术栈检测策略

Orchestrator 需要自动检测项目使用的技术栈，以便调用正确的子智能体。

3.1 文件检测法

通过检测特定文件的存在来判断技术栈：

python 复制代码 
def detect_tech_stack(project_root):
    # Java 检测
    if exists(f"{project_root}/pom.xml") or exists(f"{project_root}/build.gradle"):
        return "java"
    
    # Python 检测
    if exists(f"{project_root}/requirements.txt") or exists(f"{project_root}/pyproject.toml"):
        return "python"
    
    # Node.js 检测
    if exists(f"{project_root}/package.json"):
        with open(f"{project_root}/package.json") as f:
            content = json.load(f)
            # 检测 Vue
            if "vue" in content.get("dependencies", {}):
                return "vue"
            # 检测 React
            if "react" in content.get("dependencies", {}):
                return "react"
        return "nodejs"
    
    return "unknown"

文件映射表：

技术栈 检测文件
Java pom.xml, build.gradle
Python requirements.txt, pyproject.toml, setup.py
Vue package.json (含 vue 依赖)
React package.json (含 react 依赖)
Django manage.py
Spring Boot pom.xml (含 spring-boot 依赖)

3.2 配置检测法

通过读取配置文件内容来判断：

python 复制代码 
def detect_framework(project_root):
    # 读取 package.json 检测前端框架
    if exists(f"{project_root}/package.json"):
        with open(f"{project_root}/package.json") as f:
            pkg = json.load(f)
            deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
            
            if "vue" in deps:
                version = deps["vue"]
                if version.startswith("3"):
                    return "vue3"
                return "vue2"
            
            if "react" in deps:
                return "react"
            
            if "@angular/core" in deps:
                return "angular"
    
    # 读取 pom.xml 检测 Java 框架
    if exists(f"{project_root}/pom.xml"):
        with open(f"{project_root}/pom.xml") as f:
            content = f.read()
            if "spring-boot" in content:
                return "spring-boot"
            if "quarkus" in content:
                return "quarkus"
    
    return "unknown"

3.3 混合检测法

结合多种方法提高检测准确性：

python 复制代码 
def detect_project_type(project_root):
    """
    综合检测项目类型
    返回: {
        "backend": "java" | "python" | null,
        "frontend": "vue" | "react" | null,
        "frameworks": {
            "backend": "spring-boot" | "fastapi" | "django" | null,
            "frontend": "vue3" | "vue2" | "react18" | null
        }
    }
    """
    result = {
        "backend": None,
        "frontend": None,
        "frameworks": {
            "backend": None,
            "frontend": None
        }
    }
    
    # 检测后端
    if exists(f"{project_root}/pom.xml"):
        result["backend"] = "java"
        # 进一步检测框架
        with open(f"{project_root}/pom.xml") as f:
            if "spring-boot" in f.read():
                result["frameworks"]["backend"] = "spring-boot"
    
    elif exists(f"{project_root}/requirements.txt"):
        result["backend"] = "python"
        # 检测 Python 框架
        with open(f"{project_root}/requirements.txt") as f:
            content = f.read()
            if "fastapi" in content:
                result["frameworks"]["backend"] = "fastapi"
            elif "django" in content:
                result["frameworks"]["backend"] = "django"
            elif "flask" in content:
                result["frameworks"]["backend"] = "flask"
    
    # 检测前端
    if exists(f"{project_root}/package.json"):
        with open(f"{project_root}/package.json") as f:
            pkg = json.load(f)
            deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
            
            if "vue" in deps:
                result["frontend"] = "vue"
                version = deps["vue"]
                result["frameworks"]["frontend"] = "vue3" if version.startswith("3") else "vue2"
            
            elif "react" in deps:
                result["frontend"] = "react"
                result["frameworks"]["frontend"] = "react"
    
    return result

4. 任务分配策略

4.1 自动分配

Orchestrator 根据检测结果自动分配任务：

yaml 复制代码 
# Orchestrator 配置示例
task_allocation:
  backend:
    java: "@backend-java"
    python: "@backend-python"
  
  frontend:
    vue: "@frontend-vue"
    react: "@frontend-react"

分配逻辑：

python 复制代码 
def allocate_tasks(requirement, project_info):
    tasks = []
    
    # 后端任务
    if project_info["backend"] == "java":
        tasks.append({
            "agent": "@backend-java",
            "task": f"实现后端API: {requirement}"
        })
    elif project_info["backend"] == "python":
        tasks.append({
            "agent": "@backend-python",
            "task": f"实现后端API: {requirement}"
        })
    
    # 前端任务
    if project_info["frontend"] == "vue":
        tasks.append({
            "agent": "@frontend-vue",
            "task": f"实现前端页面: {requirement}"
        })
    
    return tasks

4.2 条件分配

根据任务的特定条件分配：

python 复制代码 
def allocate_by_condition(task):
    # 数据库相关任务
    if "database" in task or "sql" in task:
        return "@database-expert"
    
    # 安全相关任务
    if "security" in task or "auth" in task or "login" in task:
        return "@security-expert"
    
    # 性能优化任务
    if "performance" in task or "optimization" in task:
        return "@performance-expert"
    
    # 默认分配
    return "@general"

4.3 手动指定

用户在提示中明确指定：

复制代码 
实现用户登录功能：
- @backend-java 负责后端API开发
- @frontend-vue 负责前端页面开发
- @security-expert 负责安全审查

5. 协同工作流程图

5.1 完整协作流程（Mermaid）

渲染错误: Mermaid 渲染失败: Parse error on line 5: ...类型} D -->|Java| E[调用@backend-java] ----------------------^ Expecting 'AMP', 'COLON', 'DOWN', 'DEFAULT', 'NUM', 'COMMA', 'NODE_STRING', 'BRKT', 'MINUS', 'MULT', 'UNICODE_TEXT', got 'LINK_ID'

5.2 时序图

FrontendAgent BackendAgent Orchestrator 用户 FrontendAgent BackendAgent Orchestrator 用户 发现pom.xml → Java 发现package.json → Vue par [并行执行] 所有文件已创建 API契约已对齐 1. 输入需求：实现博客系统 2. 检测项目结构 3a. 分配后端任务 创建ArticleController 创建ArticleService 返回后端结果 3b. 分配前端任务 创建ArticleList.vue 创建article.ts store 返回前端结果 4. 验证API契约一致性 5. 返回完整结果

5.3 状态图

重试
需求分析
技术栈检测
Java项目
Python项目
前端项目
任务分配
并行执行
执行成功
执行失败
错误处理
结果汇总
契约验证
验证通过
验证失败
协调修正
返回结果

6. 设计模式总结

6.1 核心模式

模式 描述 适用场景
Orchestrator 协调者模式，统一管理和调度 复杂多智能体协作
Worker 工作模式，执行具体任务 后端/前端开发
Router 路由模式，根据条件分发 技术栈检测和分配
Aggregator 聚合模式，汇总多个结果 结果整合

6.2 设计原则检查清单

  • 每个智能体职责单一且明确
  • 前后端通过 API 契约通信
  • 独立任务并行执行
  • 智能体间松耦合
  • 错误处理和重试机制完善
  • 结果验证和质量保证

7. 总结

智能体协同工作架构设计的核心要点：

  1. 选择合适的模式：根据项目复杂度选择 Orchestrator、直接调用或工作流模式
  2. 明确职责边界：每个智能体只负责一个领域
  3. 定义 API 契约：确保前后端接口一致
  4. 并行执行任务：提高效率
  5. 自动化检测：智能体自动检测技术栈并分配任务
  6. 完善的错误处理：确保协作流程稳定可靠

通过合理的架构设计，可以实现高效、可靠的多智能体协作开发。

相关推荐
wotaifuzao20 小时前
为什么 if/else 是嵌入式系统的慢性毒药?
stm32·重构·freertos·状态机·架构设计·事件驱动·表驱动
我只会写Bug啊2 天前
【软考】系统架构设计师-论文范文（一）
大数据·系统架构·信息系统项目管理师·架构设计·系统分析师
IvanCodes3 天前
OpenCode安装部署详细教程
ai·开源·ai编程·opencode
鸿乃江边鸟3 天前
opencode及oh my opencode安装
大模型·opencode
骤跌4 天前
01-OpenCode 智能体系统概述（精炼版）
智能体·opencode
叶庭云4 天前
OpenCode：开源 AI Coding Agent 技术与行业分析
lsp·开源社区·多智能体协作·规范驱动开发·ai编程工具·opencode·plan/build双模式
paopao_wu4 天前
OpenCode：你的AI编程助手
ai·ai编程·opencode
成茂峰4 天前
软考高级·系统架构设计师 | 五、软件工程基础知识
系统架构·软件工程·软考高级·架构设计
骤跌5 天前
OpenCode接入千问模型指南
千问大模型·opencode·qwen-plus·qwen-max
热门推荐
01GitHub 镜像站点02Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services03openclaw配置教程（linux+局域网ollama）04UV安装并设置国内源05Linux下V2Ray安装配置指南06openclaw使用nginx反代部署过程 与disconnected (1008): pairing required解决07AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南08Vue-skills的中文文档09OpenClaw Chrome扩展使用教程 - 浏览器中继控制10在Trae中使用Pencil MCP