知识库
MD 更新：2026/5/12
Agent框架 编程代理 架构设计

OpenCode 架构设计

1. 项目定位

OpenCode 是一个开源 AI 编程代理，提供多种交互方式：

  • TUI（终端界面）— 核心体验
  • 桌面应用
  • IDE 扩展（VS Code 等）
  • Web 界面
  • CLI（命令行直接调用）

定位类似 Claude Code / Cursor，但完全开源，支持 30+ LLM 提供商。

2. 技术栈

层级技术
核心运行时Go（高性能后端）
前端/TUITypeScript + 终端 UI 框架
包管理Bun / npm
构建工具Turborepo（monorepo）
CI/CDGitHub Actions
通信协议HTTP REST API（OpenAPI 规范）
扩展协议MCP / ACP
配置格式JSON (opencode.json)

3. 系统架构总览

graph TB
    subgraph "用户界面层"
        TUI[TUI 终端界面]
        CLI[CLI 命令行]
        Web[Web 界面]
        IDE[IDE 扩展]
        Desktop[桌面应用]
    end

    subgraph "核心服务层"
        Server[HTTP Server<br/>opencode serve]
        SDK[JS/TS SDK<br/>@opencode-ai/sdk]
    end

    subgraph "Agent 引擎"
        Primary[Primary Agents]
        Sub[Subagents]
        Loop[Agent Loop<br/>Plan → Act → Observe]
    end

    subgraph "工具系统"
        BuiltIn[内置工具<br/>bash/edit/read/write/grep/glob]
        Custom[自定义工具]
        MCPTools[MCP 工具]
        ACPTools[ACP 工具]
    end

    subgraph "Provider 层"
        Anthropic[Anthropic]
        OpenAI[OpenAI]
        Google[Google]
        DeepSeek[DeepSeek]
        Ollama[Ollama]
        More[30+ 更多...]
    end

    subgraph "扩展层"
        Plugins[插件系统]
        Skills[Agent Skills]
        Rules[Rules 规则]
        LSP[LSP Servers]
    end

    subgraph "持久化"
        Sessions[会话管理]
        Config[配置系统]
        Memory[上下文记忆]
    end

    TUI & CLI & Web & IDE & Desktop --> Server
    SDK --> Server
    Server --> Primary & Sub
    Primary & Sub --> Loop
    Loop --> BuiltIn & Custom & MCPTools & ACPTools
    Loop --> Anthropic & OpenAI & Google & DeepSeek & Ollama & More
    Plugins & Skills & Rules & LSP --> Server
    Server --> Sessions & Config & Memory

4. 核心模块分析

4.1 Server（核心服务器）

OpenCode 采用 Client-Server 架构，即使在本地使用也启动一个 HTTP 服务器：

opencode serve [--port 4096] [--hostname 127.0.0.1]

设计思想：

  • 所有客户端（TUI/CLI/Web/IDE）共享同一个后端
  • 通过 OpenAPI 规范暴露 RESTful 接口
  • 支持 mDNS 发现（局域网内多设备协作）
  • 服务器管理全局状态、会话、配置

API 模块划分：

API 类别功能
Global全局状态
Project项目信息
Path & VCS路径与版本控制
Instance实例管理
Config配置读写
ProviderLLM 提供商管理
Sessions会话 CRUD
Messages消息收发
Commands命令执行
Files文件操作
Tools工具管理（实验性）
LSP/Formatters/MCP语言服务
AgentsAgent 管理
Events事件流（SSE）

4.2 Agent 系统

OpenCode 的 Agent 分为两类：

Primary Agents（主代理）

直接与用户交互的代理，拥有完整的工具集和上下文。

Subagents（子代理）

由主代理派生，执行特定子任务后返回结果。

内置 Agent 类型：

Agent用途
build编写代码、修改文件
plan分析规划，不执行修改
general通用对话
explore探索代码库
scout侦察/搜索
compaction上下文压缩
title生成会话标题
summary生成摘要

Agent 配置能力：

  • 独立模型选择（每个 Agent 可用不同 LLM）
  • 独立温度/TOP-P 设置
  • 独立工具权限
  • 独立 system prompt
  • max steps 限制
  • 可禁用/隐藏

4.3 工具系统

内置工具

工具功能
bash执行 shell 命令
edit编辑文件（查找替换）
write写入文件
read读取文件
grep内容搜索（ripgrep）
glob文件名匹配
lspLSP 语言服务（实验性）
apply_patch应用补丁
skillAgent 技能
todowrite任务列表管理
webfetch抓取网页
websearch网络搜索
question向用户提问

权限系统

{
  "permission": {
    "edit": "deny",      // 禁止
    "bash": "ask",       // 需确认
    "webfetch": "allow"  // 允许
  }
}

支持通配符："mymcp_*": "ask"

扩展工具来源

  1. 自定义工具 — 用户定义的工具
  2. MCP 服务器 — 标准 MCP 协议工具
  3. ACP 支持 — Agent Communication Protocol

4.4 Provider 层（LLM 提供商）

支持 30+ 提供商，核心包括：

类别提供商
一线厂商Anthropic, OpenAI, Google Vertex AI, Azure OpenAI
中国厂商DeepSeek, Moonshot AI, MiniMax
开源/本地Ollama, llama.cpp, LM Studio
云平台Amazon Bedrock, Cloudflare Workers AI, Groq
代理/网关Helicone, Cloudflare AI Gateway
其他Cerebras, Fireworks AI, Hugging Face, NVIDIA

配置方式：

{
  "provider": {
    "anthropic": {
      "apiKey": "sk-..."
    }
  }
}

4.5 插件系统

插件可 hook 到 OpenCode 的各种事件：

加载方式：

  1. 本地文件：.opencode/plugins/ 或 ~/.config/opencode/plugins/
  2. npm 包：在配置中声明

插件能力：

  • 监听事件（消息、工具调用等）
  • 注入环境变量
  • 添加自定义工具
  • 修改 compaction 行为
  • 发送通知

4.6 SDK

提供 JS/TS SDK（@opencode-ai/sdk），支持：

  • 类型安全的 API 调用
  • 启动内嵌服务器
  • 结构化输出（JSON Schema）
  • 会话/消息/文件管理
  • 事件订阅

5. 数据流

sequenceDiagram
    participant U as 用户
    participant TUI as TUI/CLI/Web
    participant S as Server
    participant A as Agent
    participant LLM as LLM Provider
    participant T as Tools

    U->>TUI: 输入消息
    TUI->>S: POST /sessions/:id/messages
    S->>A: 创建/继续 Agent
    A->>LLM: 发送消息 + 工具定义
    LLM-->>A: 返回工具调用请求
    A->>T: 执行工具（bash/edit/read...）
    T-->>A: 返回工具结果
    A->>LLM: 发送工具结果
    LLM-->>A: 返回最终回复
    A-->>S: 保存消息
    S-->>TUI: 推送事件（SSE）
    TUI-->>U: 显示回复

6. 配置体系

配置文件：opencode.json（项目级）+ 全局配置

{
  "$schema": "https://opencode.ai/config.json",
  "provider": { ... },
  "mcp": { ... },
  "permission": { ... },
  "plugin": [ ... ],
  "rules": [ ... ],
  "theme": "...",
  "keybinds": { ... }
}

配置层次：

  1. 全局配置（~/.config/opencode/）
  2. 项目配置（.opencode/）
  3. 环境变量
  4. CLI 参数

7. 核心设计思想

7.1 Client-Server 分离

即使是本地单机使用，也启动 HTTP 服务器。好处：

  • 多客户端共享状态
  • 便于远程访问
  • SDK 可编程控制
  • 天然支持 Web/IDE 集成

7.2 Provider 无关性

通过统一抽象层屏蔽 30+ LLM 差异，用户切换模型只需改配置。

7.3 Agent 多角色协作

不同 Agent 专职分工（build/plan/explore），避免单一 Agent 上下文过载。

7.4 工具权限最小化

默认工具无需权限，但可通过配置精细控制（allow/ask/deny）。

7.5 插件优先扩展

核心保持精简，通过 MCP/ACP/Plugin 三层扩展机制满足定制需求。

7.6 Monorepo 工程化

使用 Turborepo 管理多包（SDK、TUI、Server、CLI），统一构建和测试。

8. 与同类项目对比

特性OpenCodeClaude CodeCursorAider
开源✅❌❌✅
TUI✅✅❌✅
IDE 集成✅❌✅❌
Web UI✅❌✅❌
多 Provider30+Claude only多种多种
插件系统✅❌❌❌
MCP 支持✅✅✅❌
语言Go + TSTypeScriptTypeScriptPython

9. 可复用的架构模式

  1. Client-Server 本地架构 — 即使单机也用 HTTP 解耦，便于扩展
  2. Provider 抽象层 — 统一接口适配多 LLM
  3. Agent 角色分工 — 专职 Agent 避免上下文膨胀
  4. 工具权限矩阵 — allow/ask/deny 三级控制
  5. 三层扩展机制 — 自定义工具 + MCP + 插件
  6. SSE 事件流 — 实时推送 Agent 状态变化
  7. Monorepo + SDK — 核心逻辑复用，多端共享

10. 相关链接

11. 关联笔记

出站链接