# OpenCode多代理系统：6代理7阶段工作流的生产级实践

> 本文深入解析一个生产级多代理OpenCode系统，包含6个专业代理、6个可复用技能、严格的权限隔离和7阶段执行工作流，专为大规模代码库的AI辅助软件工程而设计。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-23T19:14:58.000Z
- 最近活动: 2026-05-23T19:27:08.469Z
- 热度: 163.8
- 关键词: OpenCode, 多代理系统, AI辅助开发, 代码审查, 权限隔离, 工作流, 软件工程, 质量门禁, 子代理, Codex
- 页面链接: https://www.zingnex.cn/forum/thread/opencode-67
- Canonical: https://www.zingnex.cn/forum/thread/opencode-67
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者**: Rozariozaro
- **来源平台**: GitHub
- **原始标题**: opencode-subagents
- **原始链接**: https://github.com/Rozariozaro/opencode-subagents
- **发布时间**: 2026年5月23日

---

## 项目概述：多代理AI辅助工程

这是一个为OpenCode设计的生产级多代理系统，将结构化、确定性、高质量的AI辅助软件工程引入大规模代码库。系统实现了6个代理、6个技能，具备严格的关注点分离、确定性委托和强质量门禁。

设计目标：
- 🍎 iOS/macOS开发
- 🔀 Kotlin Multiplatform (KMP)项目
- 🖥️ 后端服务
- 🐳 Docker/DevOps工作流
- 📦 长生命周期模块化代码库
- 🤖 规模化AI辅助开发

核心原则：**先读后写**，所有实现必须经过专用审查员，每个代理仅拥有其所需权限。

---

## 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                     ORCHESTRATOR                        │
│         (规划 · 委托 · 验证 · 报告)                        │
└────────┬──────────┬──────────┬──────────┬──────────────┘
         │          │          │          │
    ┌────▼───┐ ┌────▼────┐ ┌──▼──────┐ ┌▼──────────┐
    │EXPLORE │ │IMPLEMENT│ │REVIEWER │ │DOC-WRITER │
    │        │ │   -ER   │ │         │ │           │
    │只读    │ │写·编辑  │ │批准/    │ │仅文档     │
    │分析员  │ │构建·测试 │ │拒绝     │ │           │
    │        │ │         │ │         │ │           │
    └────────┘ └─────────┘ └─────────┘ └───────────┘
         │
    ┌────▼──────┐
    │WEBSEARCH  │
    │           │
    │仅网络获取 │
    │(无本地    │
    │文件读取)  │
    └───────────┘
```

**执行流程**: Orchestrator → Explore/Websearch → Plan → Implement → Review → (Doc-write) → Report

---

## 代理详解

| 代理 | 模式 | 模型 | 温度 | 角色 |
|------|------|------|------|------|
| orchestrator | 主代理 | claude-sonnet-4.6 | 0.1 | 中央协调器；分析意图、规划、委托、验证 |
| explore | 子代理 | claude-haiku-4.5 | 0.0 | 只读分析员；发现架构、追踪依赖、识别约定 |
| implementer | 子代理 | claude-sonnet-4.6 | 0.2 | 代码执行者；编写/编辑代码、运行构建/测试 |
| reviewer | 子代理 | claude-opus-4.6 | 0.1 | 质量门禁；验证正确性、一致性、可维护性 |
| doc-writer | 子代理 | claude-haiku-4.5 | 0.2 | 文档维护者；仅更新变更日志、README和文档 |
| websearch | 子代理 | claude-sonnet-4.6 | 0.1 | 技术研究分析员；框架对比、OSS发现、API研究 |

### 代理职责

#### 🎯 Orchestrator
唯一的主代理。拥有完整的7阶段工作流。

**关键约束**: 无编辑权限 — 只能规划和委托，不能写代码。

这强制了工作流纪律：Orchestrator不能绕过委托流程，必须依赖专业代理执行具体任务。

#### 🔍 Explore
只读代码库分析员。发现架构、追踪调用图、识别约定和模式。

**温度0.0**: 最大化确定性，确保代码库分析可复现。

#### 🔨 Implementer
精确执行实现计划。拥有编辑+受保护的bash权限。

**关键约束**: 遵循Orchestrator计划，不做架构决策。

#### 🔬 Reviewer
使用最强模型(Opus)的质量门禁。只读权限，不能直接修复问题，只能批准或拒绝并提供结构化反馈。

这防止了"边审边改"的混乱，确保问题被明确记录和追踪。

#### 📝 Doc-Writer
仅限于文档文件。仅在Reviewer批准后激活，不能触碰源代码。

#### 🌐 Websearch
仅网络获取，无本地文件访问。用于框架对比、API版本检查、OSS发现和弃用验证。

---

## 技能系统

| 技能 | 触发词 | 用途 |
|------|--------|------|
| diagnose | "debug this", "diagnose" | 5阶段循环: 复现→最小化→假设→插桩→修复 |
| zoom-out | "zoom out", 不熟悉的代码段 | 架构映射；显示更广泛的上下文、调用者、依赖 |
| graphify | 知识图谱请求 | 生成HTML+JSON知识图谱，带社区检测 |
| websearch | 研究、对比、查找、调查 | 高级技术研究分析员技能 |
| handoff | 会话收尾、上下文交接 | 将对话压缩为结构化交接文档 |
| grill-with-docs | 压力测试计划 | 根据领域模型和现有文档挑战计划 |

---

## 7阶段执行工作流

Orchestrator遵循严格的7阶段执行模型：

```
阶段1: 分析      → 解析意图，识别歧义，估算复杂度
阶段2: 探索      → @explore (代码库) 和/或 @websearch (外部)
阶段3: 规划      → 将发现综合为显式实现计划
阶段4: 实现      → @implementer 带完整计划+上下文+验证命令
阶段5: 审查      → @reviewer 在标记完成前查看所有变更
阶段6: 文档      → @doc-writer 仅在Reviewer批准后
阶段7: 报告      → 总结变更、注意事项、后续事项
```

### 并行委托规则

- ✅ Explore + Websearch 可并行运行(独立，无共享状态)
- ✅ 独立实现子任务可并行运行(无文件重叠)
- ❌ Review 总是串行(必须整体查看所有变更)
- ❌ Doc-writer 从不与Reviewer并行运行

---

## 权限矩阵

| 代理 | 读取 | 编辑 | Bash | 委托 | 网络 | 技能 |
|------|------|------|------|------|------|------|
| Orchestrator | ✅ | ❌ | ❌ (只读git) | ✅ | ❌ | 全部 |
| Explore | ✅ | ❌ | ❌ (git/grep) | ❌ | ❌ | graphify, zoom-out, diagnose |
| Implementer | ✅ | ✅ | ✅ (受保护) | ❌ | ✅ | — |
| Reviewer | ✅ | ❌ | ❌ (git/grep) | ❌ | ❌ | zoom-out, graphify |
| Doc-Writer | ✅ (仅文档) | ✅ (仅文档) | ❌ (git/grep) | ❌ | ❌ | — |
| Websearch | ❌ | ❌ | ❌ | ❌ | ✅ | — |

**注意**: Bash权限按代理限制 — Orchestrator仅允许只读git命令；Explore、Reviewer和Doc-Writer仅允许git、grep和find；Implementer有受保护的bash(破坏性操作需确认)。

---

## 设计决策与理由

| 决策 | 理由 |
|------|------|
| Explore与Implementer分离 | 强制"先读后写"纪律；防止幻觉实现 |
| Reviewer只读 | 防止直接"修复"问题；确保结构化、可操作的反馈 |
| Doc-writer限于文档文件 | 防止文档传递期间意外修改源代码 |
| Orchestrator无编辑权限 | 防止绕过委托工作流；强制关注点分离 |
| Explore温度0.0 | 最大化代码库分析的确定性和可复现性 |
| 最多2次重试循环 | 防止无限循环；重复失败后升级给用户 |
| Reviewer使用Opus | 质量门禁值得最强模型；捕捉细微缺陷 |

---

## 基准测试结果

在真实iOS项目(FoodNutritions)上验证：

| 任务复杂度 | 单代理 | 多代理 | 胜者 | 备注 |
|-----------|--------|--------|------|------|
| 简单(只读) | 快速准确 | 增加开销 | 单代理 | 简单任务无需委托 |
| 中等(单文件) | 遗漏1个缺陷 | 捕获所有缺陷 | **多代理** | Reviewer捕获+1关键缺陷 |
| 复杂(多文件) | 遗漏3个缺陷 | 捕获所有缺陷 | **多代理** | Reviewer捕获+3阻塞缺陷 |

**ROI**: 约3K token的协调开销在中等+复杂度任务上物有所值。

测试套件: 12个基准案例(T01-T12)，涵盖：
- 完整工作流验证
- 技能触发准确性
- 权限边界执行
- 拒绝循环处理
- Doc-writer激活条件

---

## 安装与使用

### 前提条件
- OpenCode已安装
- GitHub Copilot或Anthropic API访问
- Node.js (用于zod验证插件)

### 安装步骤

```bash
# 克隆仓库到项目
git clone https://github.com/Rozariozaro/opencode-subagents.git
cd your-project
cp -r opencode-subagents/.opencode .
cp opencode-subagents/opencode.json .

# 安装依赖
cd .opencode && npm install

# 启动OpenCode
opencode
```

Orchestrator代理是主入口点，其他代理自动作为子代理调用。

### 配置

编辑opencode.json设置首选默认模型：
```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "google/gemini-3.5-flash"
}
```

代理模型在.opencode/agents/中单独配置。

---

## 实践启示

这个系统展示了规模化AI辅助开发的几个关键原则：

1. **专业化分工**: 不同代理专注于特定任务，提升整体质量
2. **权限最小化**: 每个代理仅拥有完成任务所需的最小权限
3. **确定性流程**: 7阶段工作流确保可预测的执行路径
4. **质量门禁**: Reviewer作为独立检查点，防止缺陷流入
5. **可复用技能**: 将常见任务封装为可复用组件

对于希望在大型代码库中应用AI辅助工程的团队，这个系统提供了一个经过验证的架构模板。