OpenCode 学习指南OpenCode 是一个开源的 AI 编程助手，类似 Claude Code，但不绑定任何特定

OpenCode 是一个开源的 AI 编程助手，类似 Claude Code，但不绑定任何特定 AI 提供商。本指南帮助你快速理解项目结构、核心模块和关键设计思路。

项目概览
技术栈
Monorepo 结构
核心包详解：packages/opencode
Provider 系统（多模型支持）
Tool 系统（工具注册与执行）
Session 系统（会话管理）
Agent 系统（智能体）
Permission 系统（权限控制）
TUI 终端界面
Web App 与 Desktop App
Server 与 API
数据库与存储
配置系统
插件与扩展
基础设施与部署
开发指南
代码风格约定
推荐学习路径

1. 项目概览

OpenCode 是一个 客户端/服务端架构 的 AI 编程工具：

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   TUI 终端   │    │   Web App   │    │  Desktop App │
│  (SolidJS)  │    │  (SolidJS)  │    │   (Tauri)   │
└──────┬──────┘    └──────┬──────┘    └──────┬──────┘
       │                  │                  │
       └──────────┬───────┴──────────────────┘
                  │  HTTP / WebSocket
           ┌──────▼──────┐
           │  Hono Server │
           │  (API 层)    │
           └──────┬──────┘
                  │
     ┌────────────┼────────────┐
     │            │            │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ Session │ │ Provider│ │  Tool   │
│ 管理    │ │ 多模型  │ │  系统   │
└─────────┘ └─────────┘ └─────────┘
                  │
           ┌──────▼──────┐
           │   SQLite DB  │
           │  (Drizzle)   │
           └─────────────┘

核心特点：

100% 开源，不绑定任何 AI 提供商
支持 20+ AI 模型提供商（Anthropic、OpenAI、Google、本地模型等）
客户端/服务端分离：TUI 只是前端之一，也可用 Web/Desktop/移动端驱动
内置 LSP 支持、MCP 协议支持
精细的权限控制系统

2. 技术栈

类别	技术
运行时	Bun 1.3.10
语言	TypeScript 5.8
Monorepo	Bun Workspaces + Turborepo
AI SDK	Vercel AI SDK (`ai@5.x`)
Web 框架	Hono（服务端）、SolidJS（前端）
桌面框架	Tauri 2.x
数据库	SQLite + Drizzle ORM
TUI 渲染	@opentui/solid（SolidJS 的终端渲染）
代码解析	Tree-sitter
配置格式	JSONC（JSON with Comments）
函数式编程	Effect 库
Schema 验证	Zod 4.x
CSS	Tailwind CSS 4.x
部署	SST + Cloudflare Workers

3. Monorepo 结构

opencode/
├── packages/
│   ├── opencode/          ⭐ 核心引擎（CLI + Server + Agent 逻辑）
│   ├── app/               🌐 Web 前端（SolidJS + SolidStart）
│   ├── desktop/           🖥️ 桌面客户端（Tauri 封装 app）
│   ├── desktop-electron/  🖥️ 旧版 Electron 桌面端
│   ├── ui/                🎨 共享 UI 组件库（SolidJS）
│   ├── web/               📄 文档站（Astro）
│   ├── plugin/            🔌 插件 SDK（@opencode-ai/plugin）
│   ├── sdk/js/            📦 JavaScript SDK（供第三方集成）
│   ├── console/           ☁️ SaaS 控制台（后台管理）
│   │   ├── app/           - 控制台前端
│   │   ├── core/          - 控制台后端
│   │   ├── function/      - Serverless 函数
│   │   ├── mail/          - 邮件服务
│   │   └── resource/      - 资源管理
│   ├── enterprise/        🏢 企业版功能
│   ├── containers/        🐳 容器配置
│   ├── extensions/        🧩 扩展
│   ├── function/          ⚡ Serverless 函数
│   ├── identity/          🔐 身份认证服务
│   ├── storybook/         📖 组件文档
│   ├── util/              🛠️ 通用工具
│   ├── script/            📜 构建脚本
│   ├── slack/             💬 Slack 集成
│   └── web/               🌍 官网（Astro）
├── infra/                 🏗️ 基础设施定义（SST）
├── specs/                 📋 规格说明
├── sdks/                  📦 其他 SDK
├── nix/                   ❄️ Nix 构建
├── sst.config.ts          ☁️ SST 部署配置
├── turbo.json             🔄 Turborepo 配置
└── package.json           📦 根配置

包之间的依赖关系：

desktop ──→ app ──→ ui
                ──→ sdk/js
opencode（核心）──→ plugin
              ──→ util
app ──→ sdk/js（通过 API 通信）
console ──→ sdk/js

4. 核心包详解：packages/opencode

这是整个项目的心脏，包含 AI Agent 引擎、CLI、Server、工具系统等核心逻辑。

源码目录结构

packages/opencode/src/
├── agent/           🤖 Agent 定义与编排
├── provider/        🔗 AI 模型提供商抽象层
├── session/         💬 会话（对话）管理
├── tool/            🔧 工具系统（bash、read、edit、grep 等）
├── permission/      🔒 权限控制
├── server/          🌐 HTTP API 服务（Hono）
│   └── routes/      - API 路由定义
├── cli/             ⌨️ CLI 入口
│   └── cmd/
│       ├── tui/     - 终端 UI（SolidJS in Terminal）
│       ├── run.ts   - run 命令
│       ├── serve.ts - 启动 API Server
│       └── ...
├── config/          ⚙️ 配置加载与合并
├── storage/         💾 数据库层（SQLite + Drizzle）
│   └── migration/   - 数据库迁移
├── mcp/             🔌 Model Context Protocol
├── lsp/             📝 Language Server Protocol
├── project/         📁 项目管理
├── plugin/          🧩 插件加载
├── skill/           🎯 Skill 注册
├── command/         📋 自定义命令
├── bus/             📡 事件总线
├── auth/            🔐 OAuth 认证
├── file/            📄 文件操作
├── filesystem/      📂 文件系统工具
├── format/          🎨 输出格式化
├── global/          🌍 全局路径（XDG）
├── id/              🆔 ID 生成
├── ide/             💻 IDE 集成
├── patch/           🩹 Git patch 操作
├── pty/             🖥️ 伪终端
├── share/           📤 会话分享
├── shell/           🐚 Shell 操作
├── snapshot/        📸 会话快照
├── worktree/        🌳 Git worktree
├── env/             🌍 环境变量
├── flag/            🚩 Feature flags
├── control-plane/   🎛️ 工作区管理
├── acp/             🔄 Adaptive Control Plane
└── installation/    📦 安装管理

模块间的数据流

用户输入
  │
  ▼
CLI/TUI ──→ Session（创建/恢复会话）
               │
               ▼
           Agent（选择 agent: build/plan）
               │
               ├──→ Provider（调用 AI 模型）
               │       │
               │       ▼
               │    AI 返回 tool_call
               │       │
               │       ▼
               ├──→ Tool（执行工具: bash/read/edit...）
               │       │
               │       ▼
               │    Permission（检查权限）
               │       │
               │       ▼
               │    执行结果返回给 AI
               │
               ▼
           Storage（持久化到 SQLite）
               │
               ▼
           Server（通过 API 推送到前端）

5. Provider 系统（多模型支持）

核心文件： packages/opencode/src/provider/provider.ts

支持的提供商

类别	提供商
直接集成	Anthropic、OpenAI、Google、Azure、Mistral、Groq、Cohere、DeepInfra
通过 SDK	AWS Bedrock、X.AI、Together AI、Perplexity、OpenRouter、GitLab
特殊	GitHub Copilot（OpenAI 兼容 API）、自定义 OpenAI 兼容端点

工作原理

// 1. Provider 注册 —— 每个提供商声明自己的 ID、名称、认证方式
// 2. Model 发现 —— 从 models.dev API 获取模型元数据，或从本地快照加载
// 3. SDK 创建 —— 根据 providerID 动态创建对应的 AI SDK 实例
// 4. 调用 —— 统一通过 Vercel AI SDK 的 streamText/generateText 接口

关键设计

模型快照：构建时从 models.dev 拉取模型列表，打包为 models-snapshot.ts，运行时不需联网
动态发现：也支持运行时从 API 获取最新模型列表
Token 计费：使用 Decimal.js 精确追踪 token 使用量
插件扩展：可通过插件注册自定义 Provider

6. Tool 系统（工具注册与执行）

核心目录： packages/opencode/src/tool/

内置工具

工具	文件	功能
`bash`	`bash.ts`	执行 shell 命令，支持 tree-sitter 解析输出
`read`	`read.ts`	读取文件（支持行号偏移）
`edit`	`edit.ts`	编辑文件（字符串替换，21KB 的复杂实现）
`write`	`write.ts`	创建/覆盖文件
`glob`	`glob.ts`	文件模式匹配搜索
`grep`	`grep.ts`	文件内容搜索
`webfetch`	`webfetch.ts`	HTTP 请求
`websearch`	`websearch.ts`	网页搜索（Exa 集成）
`codesearch`	`codesearch.ts`	代码搜索
`task`	`task.ts`	子任务管理
`todowrite`	`todowrite.ts`	Todo 列表
`apply_patch`	`apply_patch.ts`	应用 Git patch
`skill`	`skill.ts`	调用 Skill
`lsp`	`lsp.ts`	LSP 代码操作（实验性）

工具注册机制

// registry.ts —— 工具注册表
// 1. 加载内置工具
// 2. 加载自定义工具（~/.config/opencode/tool/*.ts）
// 3. 加载 MCP 工具（通过 MCP 协议发现）
// 4. 加载插件工具
// 5. 根据模型能力过滤（有些模型不支持某些工具）

自定义工具

放置在 ~/.opencode/tool/ 或 ~/.config/opencode/tool/ 目录下的 .ts 文件会被自动加载。

7. Session 系统（会话管理）

核心目录： packages/opencode/src/session/

数据模型

Session（会话）
├── id, projectID, title, directory
├── parentID（子会话支持）
├── version（乐观锁）
├── time { created, updated, compacting, archived }
├── summary { additions, deletions, files, diffs }
└── share { url }

Message（消息）
├── id, sessionID
├── role: 'user' | 'assistant'
└── parts: Part[]

Part（消息部件）
├── type: 'text' | 'tool_call' | 'tool_result'
└── content: JSON

关键功能

多轮对话：消息持久化到 SQLite，支持断点恢复
消息压缩（Compaction）：长对话自动摘要压缩，避免超出上下文窗口
会话归档：支持归档旧会话
会话快照与分享：序列化会话用于分享
Prompt 模板：预设的提示词模板系统
子会话：Agent 可以创建子会话进行独立工作

8. Agent 系统（智能体）

核心文件： packages/opencode/src/agent/agent.ts

内置 Agent

Agent	模式	用途
build	primary	默认 Agent，拥有完整权限，用于开发工作
plan	subagent	只读 Agent，用于分析和代码探索，不允许编辑文件
sandbox	subagent	受限权限 Agent

Agent 配置结构

{
  name: string              // Agent 名称
  description?: string      // 描述
  mode: 'subagent' | 'primary' | 'all'  // 运行模式
  model?: { modelID, providerID }        // 绑定模型
  permission: Ruleset       // 权限规则集
  temperature?: number      // 温度参数
  steps?: number            // 最大步骤数
  options: Record<string, any>  // 额外选项
}

工作流程

用户消息 → Agent 接收
  → 构建 System Prompt（含工具描述、权限规则、项目上下文）
  → 调用 Provider（流式输出）
  → 解析 AI 响应（文本 / tool_call）
  → 若是 tool_call → 权限检查 → 执行工具 → 结果返回 AI
  → 循环直到 AI 返回最终文本响应

9. Permission 系统（权限控制）

核心文件： packages/opencode/src/permission/service.ts

设计理念

每个工具调用都经过权限检查，确保 AI 不会执行未授权的操作。

权限模型

{
  permission: string   // 权限名称（如 "bash:*", "edit:*.ts"）
  patterns: string[]   // 匹配模式
  action: 'allow' | 'deny' | 'ask'  // 行为
}

allow：自动允许
deny：自动拒绝
ask：弹出确认框询问用户

权限来源

Agent 定义中的默认权限
项目配置 (opencode.json)
全局配置
运行时用户选择（记忆到当前 session）

10. TUI 终端界面

核心目录： packages/opencode/src/cli/cmd/tui/

技术亮点

使用 @opentui/solid —— 将 SolidJS 的响应式系统渲染到终端
组件化开发，和写 Web 前端一样的体验
支持鼠标交互、键盘快捷键、剪贴板

TUI 组件结构

tui/
├── app.tsx              - 应用入口
├── routes/
│   ├── home.tsx         - 首页（session 列表）
│   └── session.tsx      - 会话界面
├── components/
│   ├── dialog.tsx       - 对话框系统
│   ├── model-picker.tsx - 模型选择器
│   └── ...
├── context/
│   ├── theme.tsx        - 主题（dark/light）
│   └── ...
└── hooks/               - 自定义 hooks

按键绑定

Tab：在 build/plan Agent 之间切换
@general：在消息中调用子 Agent
其他快捷键在 TUI 中可见

11. Web App 与 Desktop App

Web App (`packages/app`)

框架：SolidJS + SolidStart + Vite
通信：通过 WebSocket 连接到 OpenCode Server
UI 库：自研 @opencode-ai/ui（基于 Kobalte 无头组件）

Provider 层级（嵌套的 Context）：

Router → Settings → Permission → Layout → Notification
  → Models → Command → Highlights → Language
  → Server → Terminal → File → Prompt → Permissions
  → Comments → GlobalSDK → GlobalSync

Desktop App (`packages/desktop`)

框架：Tauri 2.x（Rust 后端 + Web 前端）
本质：将 packages/app 打包为原生桌面应用
额外能力：剪贴板、文件对话框、Shell 访问、自动更新

12. Server 与 API

核心目录： packages/opencode/src/server/

框架

使用 Hono 轻量 HTTP 框架，特点：

极小的运行时开销
中间件生态丰富
支持 OpenAPI spec 自动生成

主要路由

路径	功能
`/session/*`	会话 CRUD、消息发送
`/project/*`	项目管理
`/provider/*`	模型提供商管理
`/permission/*`	权限请求处理
`/config/*`	配置读写
`/file/*`	文件操作
`/pty/*`	伪终端流
`/mcp/*`	MCP 服务器管理

通信方式

REST API：常规请求
WebSocket：实时推送（消息流、状态变更）
SSE：Server-Sent Events（某些流式场景）

13. 数据库与存储

核心目录： packages/opencode/src/storage/

技术选型

数据库：SQLite（Bun 原生支持，零外部依赖）
ORM：Drizzle ORM（类型安全、轻量级）
迁移：时间戳命名的迁移文件

数据库位置

平台	路径
macOS/Linux	`~/.local/share/opencode/opencode.db`
Windows	`%APPDATA%/opencode/opencode.db`
自定义	`OPENCODE_DB` 环境变量

核心表

session     -- 会话
message     -- 消息
part        -- 消息部件（文本/工具调用/工具结果）
project     -- 项目
workspace   -- 工作区（关联 Git 分支）
account     -- 用户账户
permission  -- 权限规则
command     -- 自定义命令

Schema 风格（Drizzle）

// 使用 snake_case，避免手动映射列名
const table = sqliteTable("session", {
  id: text().primaryKey(),
  project_id: text().notNull(),
  created_at: integer().notNull(),
})

14. 配置系统

核心目录： packages/opencode/src/config/

配置优先级（低 → 高）

1. 远程 .well-known/opencode（组织默认配置）
2. 全局配置  ~/.config/opencode/opencode.json(c)
3. 环境变量  OPENCODE_CONFIG 指定的文件
4. 项目配置  ./opencode.json(c)
5. 本地配置  ./.opencode/opencode.json(c)
6. 内联配置  OPENCODE_CONFIG_CONTENT 环境变量
7. 托管配置  企业级管理配置（最高优先级）

配置示例

// opencode.jsonc
{
  // AI 模型配置
  "provider": {
    "anthropic": {
      "apiKey": "sk-..."
    }
  },

  // 默认模型
  "model": {
    "modelID": "claude-sonnet-4-20250514",
    "providerID": "anthropic"
  },

  // MCP 服务器
  "mcp": {
    "my-server": {
      "type": "stdio",
      "command": "node",
      "args": ["./mcp-server.js"]
    }
  },

  // 自定义指令
  "instructions": "You are a helpful coding assistant.",

  // 权限规则
  "permissions": [
    { "permission": "bash:*", "action": "ask" },
    { "permission": "edit:*.ts", "action": "allow" }
  ]
}

15. 插件与扩展

扩展点

扩展类型	位置	说明
自定义工具	`~/.opencode/tool/*.ts`	TypeScript 工具定义
自定义命令	`~/.opencode/commands/`	命令模板
自定义 Skill	`~/.opencode/skills/`	技能定义
MCP 服务器	`opencode.json` 中配置	通过 MCP 协议扩展工具
插件包	`~/.opencode/plugins/`	npm 包形式的插件

Plugin SDK

// @opencode-ai/plugin
import { defineTool } from "@opencode-ai/plugin"

export default defineTool({
  name: "my-tool",
  description: "A custom tool",
  parameters: z.object({ query: z.string() }),
  execute: async ({ query }) => {
    return { result: `Processed: ${query}` }
  }
})

16. 基础设施与部署

SST 配置 (`sst.config.ts`)

云平台：Cloudflare Workers + D1 Database
阶段：dev / production
保护：production 阶段受保护，防止意外删除

基础设施模块

infra/
├── app.ts         - Web 应用部署
├── console.ts     - SaaS 控制台后端
└── enterprise.ts  - 企业版功能

第三方服务

Stripe：计费
PlanetScale：MySQL 数据库（Console 使用）

17. 开发指南

环境准备

# 要求 Bun 1.3+
bun install

常用命令

# 开发模式（启动 TUI）
bun dev

# 指定目录运行
bun dev <directory>
bun dev .                    # 在 opencode 仓库根目录运行

# 启动 API Server（无头模式）
bun dev serve

# 启动 Web 界面
bun dev web

# 桌面应用开发
bun dev:desktop

# Web 前端开发
bun dev:web

# 控制台开发
bun dev:console

# 类型检查（必须从包目录运行）
cd packages/opencode && bun typecheck

# 测试（不能从根目录运行）
cd packages/opencode && bun test

# 构建独立可执行文件
./packages/opencode/script/build.ts --single

注意事项

测试不能从仓库根目录运行（有 guard）
类型检查用 bun typecheck，不要直接用 tsc
构建会从 models.dev API 拉取模型列表

18. 代码风格约定

详见 AGENTS.md

命名

优先单词命名：cfg, err, opts, dir, root 而不是 configObject, errorMessage
避免不必要的驼峰复合词

变量

优先 const，用三元替代 let + 赋值
只用一次的值直接内联，不要声明变量

控制流

避免 else，用 early return
避免 try/catch（除非必要）
优先函数式方法（map, filter, flatMap）而非 for 循环

解构

避免不必要的解构，用点号访问保持上下文

数据库 Schema

字段用 snake_case，避免手动映射

其他

避免 any 类型
依赖类型推断，减少显式类型标注
使用 Bun API（如 Bun.file()）

19. 推荐学习路径

第一阶段：理解全局

阅读本指南，建立整体印象
阅读 README.md 和 CONTRIBUTING.md
阅读 AGENTS.md 了解代码风格

第二阶段：核心引擎

按以下顺序阅读 packages/opencode/src/：

config/ → 理解配置加载机制
storage/ → 理解数据模型和数据库 schema
provider/provider.ts → 理解多模型抽象层（最大单文件，~54KB）
tool/ → 理解工具注册和执行，从 registry.ts 入手
session/ → 理解会话生命周期
agent/agent.ts → 理解 Agent 编排逻辑
permission/ → 理解权限控制
server/ → 理解 API 层

第三阶段：前端

packages/ui/ → 共享组件库
packages/app/src/app.tsx → Web 应用入口，理解 Provider 层级
cli/cmd/tui/ → TUI 实现，理解终端渲染

第四阶段：扩展系统

mcp/ → MCP 协议集成
lsp/ → LSP 集成
plugin/ → 插件系统
skill/ → Skill 系统

第五阶段：基础设施

sst.config.ts → 部署配置
infra/ → 基础设施定义
packages/console/ → SaaS 后台

附录：关键文件速查

要了解	去看
项目入口	`packages/opencode/src/index.ts`
CLI 命令定义	`packages/opencode/src/cli/cmd/`
AI 调用逻辑	`packages/opencode/src/provider/provider.ts`
工具定义	`packages/opencode/src/tool/*.ts`
会话管理	`packages/opencode/src/session/`
Agent 配置	`packages/opencode/src/agent/agent.ts`
数据库 Schema	`packages/opencode/src/storage/`
API 路由	`packages/opencode/src/server/routes/`
Web 前端入口	`packages/app/src/app.tsx`
TUI 入口	`packages/opencode/src/cli/cmd/tui/app.tsx`
配置加载	`packages/opencode/src/config/`
权限系统	`packages/opencode/src/permission/service.ts`
MCP 集成	`packages/opencode/src/mcp/`
插件 SDK	`packages/plugin/`
部署配置	`sst.config.ts` + `infra/`

OpenCode 学习指南

目录