技术架构核心

整体架构设计

OpenCode 采用了典型的客户端-服务器 (Client-Server) 架构，这种设计使其能够支持多种客户端，并提供了良好的扩展性。

架构层次

OpenCode 的架构可以分为以下几个层次：

1. 服务器层 (Server Layer)

• 运行 HTTP 服务器，通过 OpenAPI 3.1 规范暴露端点
• 负责处理所有业务逻辑和状态管理
• 支持独立运行模式 (opencode serve)
• 默认监听在 127.0.0.1:4096

2. 客户端层 (Client Layer)

• TUI (Terminal User Interface)：终端界面，是主要的交互方式
• Desktop App：桌面应用程序（Beta 版本），支持 macOS、Windows、Linux
• IDE Extensions：VS Code 等 IDE 扩展
• CLI：命令行界面
• Web UI：Web 界面
• SDK Client：开发者可以通过 SDK 创建自定义客户端

3. 插件层 (Plugin Layer)

• 支持本地插件和 npm 插件
• 通过事件钩子 (Hooks) 系统扩展功能
• 可以添加自定义工具

架构优势

这种分层架构的设计理念体现在：

• 多客户端支持：同一个服务器可以同时服务多个客户端，例如 TUI 和 IDE 扩展可以同时连接
• 远程控制：TUI 前端只是可能的客户端之一，这意味着可以从移动应用远程驱动在本地计算机上运行的 OpenCode
• API 驱动：所有功能都通过 HTTP API 暴露，便于第三方集成
• 可扩展性：插件系统允许在不修改核心代码的情况下扩展功能

核心组件

1. 会话管理 (Session Management)

会话是 OpenCode 的核心抽象，代表一次完整的对话和工作流程。

graph TD
    A[会话创建] --> B{会话类型}
    B -->|主会话| C[Build Agent]
    B -->|主会话| D[Plan Agent]
    B -->|子会话| E[General Agent]
    B -->|子会话| F[Explore Agent]

    C --> G[消息交互]
    D --> G
    E --> G
    F --> G

    G --> H{工具调用}
    H -->|读| I[文件操作]
    H -->|写| J[代码编辑]
    H -->|执行| K[Bash 命令]
    H -->|搜索| L[代码搜索]

    I --> M[响应生成]
    J --> M
    K --> M
    L --> M

每个会话包含：

• Messages: 消息历史，包括用户消息和 AI 响应
• Parts: 消息的具体部分，可以是文本、工具调用等
• Todo List: 任务列表，用于跟踪工作进度
• Status: 会话状态（运行中、空闲、错误等）
• Agent: 当前使用的代理类型
• Model: 使用的 AI 模型配置

2. 代理系统 (Agent System)

OpenCode 内置了多个代理，每个代理有不同的职责和权限：

主代理 (Primary Agents)

• Build Agent: 默认代理，拥有所有工具权限，用于开发工作
• Plan Agent: 只读代理，用于分析和代码探索
  • 默认拒绝文件编辑
  • Bash 命令执行前需要询问
  • 适合探索不熟悉的代码库或规划变更

子代理 (Subagents)

• General Agent: 通用代理，用于复杂研究和多步骤任务
• Explore Agent: 快速、只读代理，用于探索代码库

3. 工具系统 (Tool System)

工具是代理与系统交互的接口。OpenCode 提供了丰富的内置工具：

• 文件操作工具: read, write, edit - 用于读取、写入和编辑文件
• 搜索工具: grep - 在文件中搜索文本，支持正则表达式
• 代码搜索工具: glob - 通过文件名模式匹配查找文件
• Shell 工具: bash - 执行命令行操作
• 网络工具: webfetch - 获取网页内容
• 任务管理工具: task - 启动子代理处理复杂任务
• 待办工具: todowrite, todoread - 管理任务列表
• Git 工具: bash 集成 Git 操作
• LSP 工具: 自动加载 LSP 服务器为 LLM 提供代码上下文

4. 权限系统 (Permission System)

权限系统是 OpenCode 的重要安全机制，可以精细控制代理的行为：

权限级别：

• "allow" - 允许所有操作，无需批准
• "ask" - 执行前提示用户批准
• "deny" - 禁用该工具

可配置的工具权限：

• edit: 文件编辑权限
• bash: Bash 命令执行权限
• webfetch: 网络抓取权限

权限层次：

1. 全局配置 (Global Config)
2. 代理特定配置 (Agent-specific Config)
3. 具体命令级别权限 (Command-level Permissions)

5. 插件系统 (Plugin System)

插件系统是 OpenCode 扩展能力的核心：

插件加载方式

• 本地插件: .opencode/plugins/ 或 ~/.config/opencode/plugins/
• npm 插件: 在 opencode.json 中配置

插件功能

• 事件钩子: 订阅各种系统事件
• 自定义工具: 添加新的工具供代理使用
• 上下文注入: 在会话压缩时注入自定义上下文

可用事件类型

• Command Events: 命令执行
• File Events: 文件操作
• Message Events: 消息处理
• Permission Events: 权限响应
• Session Events: 会话生命周期
• Tool Events: 工具执行
• TUI Events: 用户界面交互
• LSP Events: 语言服务协议

6. 配置系统 (Configuration System)

OpenCode 使用灵活的配置系统：

配置层级

1. 全局配置: ~/.config/opencode/opencode.json
2. 项目配置: opencode.json
3. 命令行参数

配置项

• 模型配置 (Models)
• 代理配置 (Agents)
• 工具配置 (Tools)
• 权限配置 (Permissions)
• LSP 服务器配置
• MCP 服务器配置
• 主题配置 (Themes)
• 快捷键配置 (Keybinds)

LSP 集成

OpenCode 原生集成了 LSP (Language Server Protocol)，这是其区别于其他 AI 编码工具的重要特性。

LSP 工作原理

sequenceDiagram
    participant Agent as AI Agent
    participant LSP as LSP Server
    participant FS as File System

    Agent->>LSP: 请求代码上下文
    LSP->>FS: 扫描文件
    FS-->>LSP: 返回文件信息
    LSP->>LSP: 语法分析、符号解析
    LSP-->>Agent: 返回结构化信息
    Agent->>Agent: 基于上下文生成代码

LSP 能力

• 自动加载: 根据项目类型自动加载合适的 LSP
• 代码补全: 基于项目上下文的智能补全
• 符号跳转: 快速定位函数、类、变量的定义
• 语法检查: 实时检测语法和语义错误
• 重构支持: 安全地进行代码重构

开发者价值

LSP 集成的价值在于：

• 代理能够理解项目的整体结构
• 提供更准确的代码建议
• 减少上下文错误
• 支持复杂的重构操作

模型无关性设计

OpenCode 的架构强调模型无关性，这是其重要的设计哲学。

多提供商支持

OpenCode 支持通过 Models.dev 连接 75+ LLM 提供商：

• Anthropic (Claude)
• OpenAI (GPT)
• Google (Gemini)
• 本地模型
• OpenCode Zen (优化过的模型)

设计优势

模型无关性的设计带来了以下优势：

• 避免厂商锁定: 不依赖单一提供商
• 成本优化: 可以选择性价比最高的模型
• 技术演进: 随着模型发展，差距会缩小，价格会下降
• 灵活性: 不同任务可以使用不同模型

数据流架构

OpenCode 的数据流体现了其模块化和可扩展的设计：

flowchart LR
    User[用户输入] --> TUI[TUI/客户端]
    TUI --> Server[HTTP Server]
    Server --> Agent[Agent Router]
    Agent --> LLM[LLM Provider]
    LLM --> Agent
    Agent --> Tool[Tool Executor]
    Tool --> FileSystem[文件系统]
    Tool --> Shell[Shell]
    Tool --> LSP[LSP Server]
    Tool --> Web[Web Fetch]

    FileSystem --> Agent
    Shell --> Agent
    LSP --> Agent
    Web --> Agent

    Agent --> Server
    Server --> TUI
    TUI --> User

    Plugin[插件系统] -.-> Tool
    Plugin -.-> Agent

这种数据流设计保证了：

• 清晰的关注点分离
• 易于测试和调试
• 支持并行处理
• 良好的错误隔离

参考资料

• OpenCode GitHub 仓库
• OpenCode Server 文档
• OpenCode Agents 文档
• OpenCode Plugins 文档