OpenCode 架构设计与核心技术深度解析

项目简介

OpenCode 是一款强大的开源终端 AI 编程助手，使用 Go 语言构建。该项目由 SST 团队开发，后于 2025 年 9 月归档，核心开发者加入 Charmbracelet 团队，项目以 Crush 的名称继续发展。

“OpenCode is a powerful AI coding agent. Built for the terminal.” — GitHub

项目数据 (归档时):

整体架构

OpenCode 采用 六层分层架构 设计，实现了清晰的关注点分离：

flowchart TB
    subgraph "Entry Points"
        CLI["CLI (Cobra Command)"]
    end

    subgraph "Application Core"
        APP["App Orchestrator"]
        CONFIG["Config Service"]
    end

    subgraph "User Interface"
        TUI["Bubble Tea TUI"]
        PAGES["Pages (Chat/Logs)"]
        DIALOGS["Dialogs (Permission/Session)"]
    end

    subgraph "AI Processing"
        AGENT["Agent Service"]
        PROVIDER["LLM Providers"]
        PROMPT["Prompt Builder"]
    end

    subgraph "Tool Execution"
        TOOLS["Tool Registry"]
        PERM["Permission Service"]
        BUILTIN["Built-in Tools"]
        MCP_TOOLS["MCP Tools"]
    end

    subgraph "Data & Integration"
        DB["SQLite Database"]
        LSP["LSP Clients"]
        MCP_SRV["MCP Servers"]
    end

    CLI --> APP
    APP --> CONFIG
    APP --> TUI
    TUI --> PAGES
    TUI --> DIALOGS
    APP --> AGENT
    AGENT --> PROVIDER
    AGENT --> PROMPT
    AGENT --> TOOLS
    TOOLS --> PERM
    TOOLS --> BUILTIN
    TOOLS --> MCP_TOOLS
    APP --> DB
    APP --> LSP
    MCP_TOOLS --> MCP_SRV

核心设计原则

1. Client/Server 分离: TUI 前端与 HTTP 后端分离，支持远程操作
2. 事件驱动: 基于 Pub/Sub 模式的松耦合通信
3. 依赖注入: App Orchestrator 聚合所有服务
4. 类型安全: SQLC 生成类型安全的数据库操作代码

目录结构

opencode/
├── cmd/                    # CLI 入口点 (Cobra)
│   └── root.go            # 主命令定义与订阅初始化
├── internal/              # 核心应用逻辑
│   ├── app/               # App Orchestrator
│   │   └── app.go         # 服务聚合与初始化
│   ├── config/            # 配置加载与验证
│   ├── tui/               # Bubble Tea UI
│   │   ├── pages/         # Chat, Logs 页面
│   │   └── dialogs/       # Permission, Session 对话框
│   ├── llm/               # AI 处理层
│   │   ├── agent/         # Agent 编排
│   │   ├── provider/      # LLM Provider 抽象
│   │   ├── prompt/        # System Prompt 构建
│   │   └── tools/         # 工具接口与实现
│   ├── session/           # Session 生命周期管理
│   ├── message/           # 消息持久化
│   ├── history/           # 文件变更追踪
│   ├── permission/        # 权限请求处理
│   ├── lsp/               # Language Server 客户端
│   ├── db/                # SQLC 生成的查询
│   └── pubsub/            # 事件发布系统
├── scripts/               # 工具脚本
├── main.go                # 应用入口
├── go.mod / go.sum        # Go 依赖
└── sqlc.yaml              # SQL 代码生成配置

Bubble Tea TUI 框架

OpenCode 的终端界面基于 Bubble Tea 构建，这是一个实现 Elm Architecture 的 Go TUI 框架。

Elm Architecture 核心循环

flowchart LR
    M[Model] -->|View| V[View]
    V -->|User Input| MSG[Message]
    MSG -->|Update| M

三大核心函数:

组件层级

appModel (Root)
├── Pages
│   ├── ChatPage (主聊天界面)
│   │   ├── Editor (输入组件)
│   │   │   ├── Attachment Support (文件/符号附件)
│   │   │   ├── History Navigation (Ctrl+P/N)
│   │   │   └── Bash Mode (! 前缀)
│   │   └── Messages (消息渲染)
│   │       └── PartCache (渲染缓存优化)
│   └── LogsPage (日志页面)
└── Dialogs
    ├── PermissionDialog (权限确认)
    ├── SessionDialog (会话切换)
    ├── CommandDialog (命令面板)
    └── ModelDialog (模型选择)

事件处理流程

sequenceDiagram
    participant User
    participant TUI
    participant PubSub
    participant Agent
    participant Tools

    User->>TUI: 输入 Prompt
    TUI->>Agent: 发送消息
    Agent->>Tools: 调用工具
    Tools-->>PubSub: 发布 ToolResult 事件
    PubSub-->>TUI: 转发为 Bubble Tea Msg
    TUI->>TUI: Update() 更新状态
    TUI->>User: View() 渲染 UI

键盘快捷键

全局控制:

编辑器模式:

Event-Driven Pub/Sub 系统

OpenCode 使用泛型 Pub/Sub 模式 (pubsub.Event[T]) 实现组件间的松耦合通信。

事件类型

订阅初始化

// cmd/root.go - setupSubscriptions()
func setupSubscriptions() {
    // 为每种事件类型创建 goroutine
    go func() {
        for event := range pubsub.Subscribe[AgentEvent]() {
            // 转发为 Bubble Tea 消息
            program.Send(AgentEventMsg{Event: event})
        }
    }()
    // ... 其他事件类型
}

设计优势

1. 解耦: 发布者无需知道订阅者
2. 可扩展: 新增功能只需订阅相关事件
3. 异步: 不阻塞主 UI 线程
4. 可测试: 事件可被 Mock

Agent 服务与 LLM 集成

Agent 循环机制

Agent 服务通过 AI SDK 的 streamText 函数实现持续的 LLM 交互循环：

flowchart TD
    START[接收 Prompt] --> BUILD[构建 System Prompt]
    BUILD --> STREAM[调用 streamText]
    STREAM --> PROCESS{处理响应流}
    PROCESS -->|text-delta| RENDER[渲染文本]
    PROCESS -->|tool-call| EXEC[执行工具]
    EXEC --> PERM{需要权限?}
    PERM -->|Yes| ASK[请求用户授权]
    ASK --> APPROVED{批准?}
    APPROVED -->|Yes| RUN[执行工具]
    APPROVED -->|No| ABORT[中止]
    PERM -->|No| RUN
    RUN --> RESULT[工具结果]
    RESULT --> STREAM
    PROCESS -->|finish-step| CHECK{达到停止条件?}
    CHECK -->|No| STREAM
    CHECK -->|Yes| END[完成]
    RENDER --> PROCESS

System Prompt 构建

Prompt 采用分层组装：

1. Provider-specific System Prompt (针对不同 LLM 优化)
2. User System Prompt (可选自定义)
3. Agent-specific Prompt (Build/Plan 不同)
4. Environment Context (工作目录、日期、平台)
5. Custom Config Prompts (AGENTS.md, CLAUDE.md)

支持的 LLM Providers

OpenCode 通过 AI SDK 实现 Provider 抽象，支持 75+ 模型：

Agent 类型

Primary Agents (直接交互):

Subagents (专业助手):

切换方式: Tab 键切换 Primary Agent, @ 提及调用 Subagent

工具系统

工具注册架构

flowchart LR
    subgraph "Tool Registry"
        RESOLVE["resolveTools()"]
    end

    subgraph "Tool Sources"
        BUILTIN["Built-in Tools"]
        MCP["MCP Tools"]
        PLUGIN["Plugin Tools"]
    end

    BUILTIN --> RESOLVE
    MCP --> RESOLVE
    PLUGIN --> RESOLVE

    RESOLVE --> AGENT["Agent Service"]

Built-in 工具清单

文件操作:

搜索发现:

执行集成:

用户交互:

工具执行流程

sequenceDiagram
    participant Agent
    participant ToolRegistry
    participant Permission
    participant Tool
    participant FileSystem

    Agent->>ToolRegistry: 调用工具
    ToolRegistry->>Permission: ask()
    Permission->>Permission: 检查缓存
    alt 未缓存
        Permission->>User: 显示确认对话框
        User->>Permission: 批准/拒绝
        Permission->>Permission: 更新缓存 (支持通配符)
    end
    Permission->>Tool: execute()
    Tool->>FileSystem: 执行操作
    FileSystem-->>Tool: 结果
    Tool-->>Agent: 返回结果
    Agent->>Agent: 继续 LLM 循环

权限系统

权限状态:

通配符支持:

{
  "permission": {
    "bash": {
      "git *": "allow",
      "rm *": "ask",
      "sudo *": "deny"
    }
  }
}

级联批准: 批准一个权限会自动批准所有匹配的待处理请求。

LSP 集成

OpenCode 集成 Language Server Protocol 提供代码智能功能。

支持的功能

“While the LSP client implementation supports the full LSP protocol, currently only diagnostics are exposed to the AI assistant.” — DeepWiki

配置示例

{
  "lsp": {
    "go": {
      "command": "gopls",
      "args": ["serve"]
    },
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },
    "python": {
      "command": "pylsp"
    }
  }
}

LSP 反馈循环

flowchart LR
    EDIT[AI 编辑文件] --> NOTIFY[通知 LSP Server]
    NOTIFY --> DIAG[获取诊断信息]
    DIAG --> FEED[反馈给 LLM]
    FEED --> FIX[AI 修复问题]
    FIX --> EDIT

这使得 AI 能够获得类似 IDE 的实时反馈，提高代码质量。

MCP (Model Context Protocol) 集成

MCP 是一个标准化协议，允许 AI 助手与外部工具和服务交互。

传输类型

配置示例

{
  "mcpServers": {
    "sentry": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@sentry/mcp-server"]
    },
    "context7": {
      "type": "sse",
      "url": "https://mcp.context7.ai/sse"
    },
    "custom-tool": {
      "type": "stdio",
      "command": "/path/to/my-mcp-server",
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

动态工具注册

sequenceDiagram
    participant OpenCode
    participant MCPServer
    participant ToolRegistry

    OpenCode->>MCPServer: 连接
    MCPServer->>OpenCode: 返回可用工具列表
    OpenCode->>ToolRegistry: dynamicTool() 注册
    Note over ToolRegistry: MCP 工具与内置工具统一可用

    OpenCode->>MCPServer: 调用工具
    MCPServer->>MCPServer: 执行
    MCPServer->>OpenCode: 返回结果

官方 MCP Server 集成

Session 管理与持久化

Session 生命周期

stateDiagram-v2
    [*] --> Created: opencode 启动
    Created --> Active: 用户开始对话
    Active --> Active: 消息交互
    Active --> Compacting: Token 接近 95%
    Compacting --> NewSession: 自动总结
    NewSession --> Active
    Active --> Saved: 用户退出
    Saved --> Active: 恢复 Session
    Active --> [*]: 用户删除

数据持久化 (SQLite + SQLC)

核心表结构:

SQLC 类型安全:

version: "2"
sql:
  - engine: "sqlite"
    queries: "internal/db/queries.sql"
    schema: "internal/db/schema.sql"
    gen:
      go:
        package: "db"
        out: "internal/db"

Auto-Compact 机制

当对话 Token 接近模型上下文窗口的 95% 时，系统自动触发压缩：

1. 调用 AgentSummarizer 生成对话摘要
2. 创建新 Session 并附加摘要
3. 保持对话连续性

flowchart LR
    CHECK[检查 Token 使用率] --> TRIGGER{>= 95%?}
    TRIGGER -->|No| CONTINUE[继续对话]
    TRIGGER -->|Yes| SUMMARIZE[生成摘要]
    SUMMARIZE --> CREATE[创建新 Session]
    CREATE --> ATTACH[附加摘要]
    ATTACH --> CONTINUE

配置系统

配置文件优先级

1. 命令行参数 (最高)
2. ./.opencode.json (项目级)
3. $XDG_CONFIG_HOME/opencode/.opencode.json
4. $HOME/.opencode.json (最低)

完整配置结构

{
  "data": {
    "directory": ".opencode"
  },
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    },
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "baseURL": "https://api.openai.com/v1"
    },
    "local": {
      "baseURL": "http://localhost:11434/v1"
    }
  },
  "agents": {
    "coder": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 5000,
      "temperature": 0.7,
      "maxSteps": 50
    },
    "plan": {
      "model": "claude-3.7-sonnet",
      "permission": {
        "bash": "ask",
        "edit": "ask"
      }
    }
  },
  "lsp": {
    "go": { "command": "gopls" },
    "typescript": { "command": "typescript-language-server", "args": ["--stdio"] }
  },
  "mcpServers": {
    "example": {
      "type": "stdio",
      "command": "path/to/mcp-server"
    }
  },
  "shell": {
    "path": "/bin/bash",
    "args": ["-l"]
  },
  "autoCompact": true,
  "debug": false
}

与同类工具对比

“The ‘terminal-based AI coding agents’ trend is hot, and everyone is experimenting to see which tool will stick.” — Hacker News

设计亮点总结

架构优势

1. Client/Server 分离: TUI 与后端解耦，支持远程操作 (如手机 App)
2. Event-Driven Pub/Sub: 组件松耦合，易于扩展
3. 类型安全数据层: SQLC 生成的代码消除 SQL 注入风险
4. 可插拔 Provider: 统一接口支持 75+ LLM

技术选型理由

扩展性设计

flowchart TB
    subgraph "Core (不变)"
        AGENT["Agent Loop"]
        TUI["Bubble Tea TUI"]
        PUBSUB["Pub/Sub System"]
    end

    subgraph "可扩展 (Plugin)"
        TOOLS["Custom Tools"]
        MCP_EXT["MCP Servers"]
        PROVIDER["New Providers"]
    end

    TOOLS --> AGENT
    MCP_EXT --> AGENT
    PROVIDER --> AGENT

参考资料

官方资源

• OpenCode GitHub (Archived)
• OpenCode Documentation
• Crush GitHub (继任者)
• Bubble Tea Framework

深度分析

• How Coding Agents Actually Work: Inside OpenCode - 详细的代码级分析
• DeepWiki: OpenCode Architecture - 架构图解
• Model Context Protocol - MCP 官方规范

社区讨论

• Hacker News: Crush Launch
• OpenCode vs Aider vs Cursor Comparison

相关项目

• AI SDK (Vercel) - LLM Provider 抽象层
• SQLC - Go SQL 代码生成
• mcp-language-server - LSP 客户端实现参考