智能体协同工作架构设计

opencode专栏其他内容：

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. 请求参数格式

   // Query 参数
   GET /api/users?page=0&size=10&keyword=john
   
   // Body 参数
   POST /api/users
   {
     "username": "john",
     "email": "john@example.com",
     "password": "123456"
   }
   

3. 响应数据结构

   {
     "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 的并行执行策略：

// 并行调用多个子智能体
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. 共享配置文件

   # api-contract.yaml
   endpoints:
     - path: /api/users
       method: GET
       response: UserListResponse
   

3. 使用 Skills 共享知识

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

3. 技术栈检测策略

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

3.1 文件检测法

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

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"

文件映射表：

3.2 配置检测法

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

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 混合检测法

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

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 根据检测结果自动分配任务：

# Orchestrator 配置示例
task_allocation:
  backend:
    java: "@backend-java"
    python: "@backend-python"
  
  frontend:
    vue: "@frontend-vue"
    react: "@frontend-react"

分配逻辑：

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 条件分配

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

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）

5.2 时序图

5.3 状态图

6. 设计模式总结

6.1 核心模式

6.2 设计原则检查清单

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

7. 总结

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

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

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