基于 OpenCode 构建 Multi-Agent 编程效率系统：从架构设计到工程落地

项目周期：2026.05 ~ 至今

角色：独立开发 / 架构设计

项目定位：基于 OpenCode 开源框架，构建 Multi-Agent 协作编程效率系统，实现复杂开发任务的智能拆解、并行编排与上下文感知。

---

一、项目背景与动机

在日常开发中，一个功能交付往往涉及需求分析、编码实现、代码审查、文档翻译、国际化适配、依赖管理、Changelog 生成等多个环节。传统方式下，这些任务需要开发者逐一切换上下文手动完成，效率损耗巨大。

OpenCode 作为一款 100% 开源的 AI 编程代理，提供了客户端/服务器分离的架构和强大的扩展能力。但要让 AI 真正理解项目规范、在正确时机执行正确任务、并以标准化的方式输出结果，需要在框架之上构建一套完整的 工作流编排系统。

本项目即是在 OpenCode 框架之上，设计并实现了一套 Multi-Agent 协作编程效率系统，将重复性的开发流程固化为标准化工作流模板，让多个 AI Agent 在统一规范下协同工作。

---

二、核心架构设计

2.1 整体架构

2.2 Multi-Agent 协作模式

系统设计了三种粒度的 Agent 分工：

层级	Agent	职责	协作关系
编排层	Build Agent	主控流程，任务拆解与调度	将子任务委派给 Specialist Agent
专业层	Triage Agent	Issue 自动分类与路由	接收 Build 下发的分类任务
	Duplicate PR Agent	重复 PR 检测	独立执行，结果回传
	General Subagent	并行搜索与多步复杂任务	通过 @general 调用
执行层	Custom Commands	固定流程自动化	由 Build 触发执行

关键设计：Agent 之间通过 模型切换 + 工具隔离 实现能力分化，而非简单的 prompt 区分。例如 Triage Agent 使用 minimax-m2.5 模型且仅暴露 github-triage 工具，Duplicate PR Agent 使用 claude-haiku-4-5 且仅暴露 github-pr-search 工具，从而在低成本模型上实现专业化的稳定输出。

---

三、工作流模板体系（30+）

3.1 设计理念

工作流模板的核心思想是：将固定流程编码为 AI Agent 可重复执行的标准化操作。每个模板定义了：

• 触发时机（when）：什么场景下执行
• 执行模型（model）：使用哪个模型
• 上下文规范（context）：需要哪些输入信息
• 输出格式（output）：产出物的格式和标准

3.2 核心工作流架构

3.3 关键工作流模板清单

编码规范与质量保障

工作流	模型	描述
Code Review	Claude Opus 4.7	对 diff 进行深度审查，结合 AGENTS.md 规范逐文件检查
AI Slop 清理	Claude Opus 4.7	自动检测并清除 AI 生成的低质量代码（冗余注释、不必要的 try/catch、any 类型绕过等）
拼写检查	Claude Haiku 4.5	对 Markdown 变更进行拼写和语法审查

上下文与知识管理

工作流	模型	描述
Learn	Claude Opus 4.7	从会话中提取非显而易见的经验，自动写入对应层级的 AGENTS.md 文件
Context 加载	自动	Agent 读取文件时自动加载父目录 AGENTS.md，逐层叠加项目规范

依赖与发布管理

工作流	模型	描述
AI Deps 分析	Claude Opus 4.7	扫描 AI SDK 依赖，分析可升级版本并生成 CHANGELOG 参考报告
Changelog 生成	GPT 5.4	从结构化提交历史生成用户可读的 UPCOMING_CHANGELOG.md
Commit 规范化	Kimi K2.5	基于 git diff 自动生成符合 Conventional Commits 规范的提交信息

多语言与国际化

工作流	模型	描述
并行翻译	Claude Opus 4.7	检出 git diff 中的英文文案变更，并行翻译为 17 种语言，保持术语一致性

社区运营自动化

工作流	模型	描述
Issue 搜索	Claude Haiku 4.5	通过 GitHub CLI 搜索重复/相关 Issue
Issue 自动分类	Minimax M2.5	自动打标签 + 指定负责人，基于团队路由规则

---

四、上下文感知系统（Context System）

4.1 设计目标

让 AI Agent 在操作任意文件时，自动获取该文件所在模块的编码规范、测试标准、架构约定，确保输出代码风格一致。

4.2 技术实现

核心机制：层级 AGENTS.md 文件自动加载

项目根目录
├── AGENTS.md                          # 全局规范
├── packages/
│   ├── opencode/
│   │   ├── AGENTS.md                  # 核心引擎规范（Effect 模式）
│   │   ├── test/
│   │   │   ├── AGENTS.md              # 测试规范
│   │   │   └── server/
│   │   │       └── AGENTS.md          # HTTP 中间件测试模式
│   │   └── src/server/routes/
│   │       ├── instance/
│   │       │   ├── AGENTS.md          # 路由层规范
│   │       │   └── httpapi/
│   │       │       └── AGENTS.md      # HTTP API 细节
│   ├── app/
│   │   └── AGENTS.md                  # 前端规范（SolidJS + Playwright）
│   ├── desktop/
│   │   └── AGENTS.md                  # Tauri 规范
│   └── desktop-electron/
│       └── AGENTS.md                  # Electron IPC 规范

加载逻辑：当 Agent 读取 packages/opencode/src/server/routes/instance/httpapi/xxx.ts 时，代理会自动加载路径上所有 AGENTS.md：

1. /AGENTS.md（全局）
2. /packages/opencode/AGENTS.md（包级别）
3. /packages/opencode/src/server/routes/instance/AGENTS.md（路由级别）
4. /packages/opencode/src/server/routes/instance/httpapi/AGENTS.md（模块级别）

4.3 Learn 命令——知识自动沉淀

用户完成某个调试/开发任务
       ↓
  人工触发 /learn
       ↓
Agent 回顾本次会话的所有交互
       ↓
提取非显而易见的 experience（隐藏的文件关联、误导性错误消息、API 陷阱等）
       ↓
自动写入对应模块层级的 AGENTS.md

关键约束：

• 不写显而易见的内容（已在文档中）
• 不写标准语言/框架行为
• 每条 insight 控制在 1-3 行
• 按模块粒度放置，而非集中堆在根目录

4.4 国际化术语一致性

为 17 个语言建立了术语词汇表（Glossary），确保跨语言翻译的术语一致性：

组件	内容
全局术语表	Do-Not-Translate 术语（OpenCode、CLI、TUI、MCP、LSP 等）
语言级术语表	每个语言的 Preferred Terms、翻译风格指南、禁忌表达
翻译工作流	自动加载对应语言的 Glossary，并行翻译所有语言

---

五、Skill 生态系统（60+）

5.1 设计理念

Skill 是可插拔的能力单元，每个 Skill 封装了一个特定领域的专业知识和工作模式。Agent 根据当前任务上下文自动选择合适的 Skill 调用。

5.2 Skill 架构设计

每个 Skill 由三要素构成：

Skill = 领域知识（Source of Truth） + 行为规范（Guidelines） + 测试模式（Test Patterns）

以 Effect Skill 为例：

• Source of Truth：自动 clone effect-smol 参考仓库到本地，Agent 直接搜索源码验证 API
• Guidelines：Effect v4 gen workflow、Schema 使用、Error 建模、Layer 组合模式
• Test Patterns：testEffect()、it.live()、scoped fixtures 等测试模式
• 防幻觉机制：核心约束——“不要凭记忆回答，先验证 .opencode/references/effect-smol”
• 决策支持：生成包含准确 API 签名的代码方案；对深入问题，指出可能的位置或模式

5.3 Skill 生态覆盖

领域分类	Skills 数量	典型场景
代码生成	12+	组件生成、API 开发、数据模型、迁移脚本
代码审查	8+	安全审查、性能分析、风格检查、依赖审计
安全审计	8+	OWASP 检查、认证授权、数据保护、注入检测
前端设计	10+	UI 组件、响应式布局、动画、可访问性
后端开发	10+	API 设计、数据库优化、缓存策略、错误处理
测试	7+	单元测试、E2E 测试、快照测试、覆盖率分析
DevOps	5+	CI/CD 配置、容器化、部署脚本、监控配置
文档	5+	API 文档、README 生成、注释规范化

---

六、GitHub 自动化集成

6.1 自定义 Tool 开发

基于 @opencode-ai/plugin SDK 开发了两个 GitHub 自动化工具：

github-triage Tool：

// 团队路由规则引擎
// 根据 Issue 内容自动推断标签 + 分配负责人
const TEAM = {
  desktop: ["adamdotdevin", "iamdavidhill", "Brendonovich", "nexxeln"],
  zen: ["fwang", "MrMushrooooom"],
  tui: ["kommander", "rekram1-node", "simonklee"],
  core: ["kitlangton", "rekram1-node", "jlongster"],
  docs: ["R44VC0RP"],
  windows: ["Hona"],
}

关键设计：

• 确定性规则引擎（同一 Issue 多次运行结果一致）
• 安全校验（不允许错误的路由分配）
• 自动纠错（Issue 不提及 nix 时自动移除 nix 标签）

github-pr-search Tool：

• 基于 GitHub Search API 的 PR 全文搜索
• 支持分页、排序、结果精简

6.2 Agent 工作流集成

GitHub Webhook 触发
       ↓
Triage Agent 自动分类
  ├── 打标签（windows/desktop/core/docs/zen/perf/nix）
  ├── 分配负责人（基于团队路由表）
  └── 输出处理结果
       ↓
Duplicate PR Agent 检测
  ├── 搜索相似 PR
  ├── 排除自身
  └── 返回潜在重复列表

---

七、工程实践亮点

7.1 模型分层策略

根据任务复杂度分配不同成本模型，实现性能与成本的平衡：

任务类型	模型选择	原因
代码生成/审查	Claude Opus 4.7	最高精度需求
Changelog 生成	GPT 5.4	大上下文窗口处理
Git 提交信息	Kimi K2.5	结构化任务，成本优化
Issue 搜索	Claude Haiku 4.5	快速轻量查询
Issue 自动分类	Minimax M2.5	规则驱动，低成本即可
翻译任务	Claude Opus 4.7 并行	质量要求高，并行降延迟

7.2 Nord 主题系统

基于 Nord 色彩系统设计了完整的 TUI 主题，覆盖 40+ 语义颜色变量：

• 差异对比（新增/删除/上下文/行号背景）
• Markdown 渲染（标题/链接/代码/引用/强调）
• 语法高亮（注释/关键字/函数/变量/字符串/数字/类型/操作符）
• UI 组件（主色/辅色/强调色/成功/警告/错误/信息）

7.3 TUI 插件系统

开发了 TUI Smoke Plugin 用于 TUI 插件调试：

• 命令注册与路由导航
• 对话框系统（Alert/Confirm/Prompt/Select）
• 插件本地堆栈管理
• Slot 系统集成（home_prompt、session_prompt_right、sidebar_content、home_bottom）
• 键盘快捷键配置
• 视觉后处理效果（Vignette）

---

八、项目总结与价值

核心成果

1. Multi-Agent 协作架构：将 Issue 分类、PR 检测、代码审查、依赖分析等任务分发到专门的 Agent，通过模型分层和工具隔离实现能力分化
2. 30+ 标准化工作流模板：覆盖需求分析 → 编码实现 → 代码审查 → 质量检查 → 文档同步 → 国际化翻译 → 变更记录 → 提交发布的完整链路
3. 层级上下文感知机制：通过 AGENTS.md 自动加载 + Learn 命令持续沉淀，确保 Agent 在所有模块的行为一致性
4. 60+ Skill 生态体系：覆盖代码生成、安全审计、前端设计、后端开发、测试、DevOps、文档等核心研发场景
5. 17 语言国际化系统：术语词汇表 + 并行翻译工作流，确保全球用户的本地化体验一致性

技术启示

• Agent 能力分化的关键不是 prompt，而是模型选择 + 工具隔离：低成本模型配合精准的工具暴露，可以在专业场景达到不亚于大模型的效果
• 上下文系统是 AI 编程工具的质量基石：层级 AGENTS.md 机制确保 AI 在操作任意模块时都有正确的规范指引
• 工作流模板化是实现 AI 工程化的有效路径：将重复性开发流程固化为标准化模板，让 AI 真正融入研发流水线

---

本文基于 OpenCode dev 分支源码分析撰写，数据截至 2026 年 5 月。项目持续迭代中。