OpenCode 架构分析

本文档基于 OpenCode 源代码进行详细架构分析，使用 Mermaid 图表可视化核心架构组件和数据流。

目录

1. 项目概述
2. 整体架构
3. 核心模块详解
4. 数据流与通信机制
5. 关键技术栈
6. 设计模式与特色
7. 扩展机制
8. 部署与运行

---

项目概述

OpenCode 是一个功能强大的 AI 驱动开发工具，采用 TypeScript 编写，基于 Bun 运行时。它提供了：

• CLI 终端界面 - 命令行交互模式
• Web 应用 - 基于 SolidJS 的 Web 界面
• 桌面应用 - 基于 Tauri 的跨平台桌面客户端
• VS Code 扩展 - IDE 集成
• HTTP API 服务 - RESTful API 和 WebSocket 支持

项目采用 Monorepo 架构，使用 Turbo 进行构建编排，支持多客户端、多 AI 提供商、可扩展的插件系统。

---

整体架构

架构层次图

Monorepo 包结构

---

核心模块详解

1. CLI 入口 (packages/opencode/src/index.ts)

CLI 使用 yargs 进行命令解析，提供丰富的命令集：

关键命令：

命令	功能	入口文件
run	执行 AI 对话	cli/cmd/run.ts
serve	启动 HTTP 服务器	cli/cmd/serve.ts
session	会话管理	cli/cmd/session.ts
mcp	MCP 服务器管理	cli/cmd/mcp.ts
agent	Agent 配置管理	cli/cmd/agent.ts
pr	Pull Request 操作	cli/cmd/pr.ts
debug	调试工具集	cli/cmd/debug/

2. Agent 系统 (packages/opencode/src/agent/agent.ts)

Agent 系统定义了不同类型的行为模式和权限配置：

Agent 模式分类：

• primary - 主 Agent，用户直接交互
• subagent - 子 Agent，由主 Agent 调用
• all - 可作为主或子 Agent

权限规则示例：

// build Agent 的默认权限
{
  "*": "allow",           // 默认允许所有操作
  "doom_loop": "ask",     // 无限循环需要询问
  "read": {
    "*.env": "ask",       // .env 文件需要询问
    "*.env.*": "ask",     // .env.local 等需要询问
  },
  "question": "allow",    // 允许提问
}

3. Session 系统 (packages/opencode/src/session/index.ts)

Session 管理用户与 AI 的对话会话，支持会话分叉、回滚、压缩等功能：

Session 核心字段：

字段	类型	说明
id	SessionID	ULID 格式，时间排序
slug	string	人类可读标识
projectID	ProjectID	所属项目
parentID	SessionID?	父会话（fork 时）
title	string	会话标题
version	string	OpenCode 版本
summary	object?	代码变更统计
share	object?	分享 URL
revert	object?	回滚信息

4. Tool Registry (packages/opencode/src/tool/registry.ts)

Tool 系统提供 AI 可调用的工具集：

工具特性：

• 每个工具独立定义参数 schema（Zod）
• 支持 init() 初始化和 execute() 执行
• 输出自动截断处理（Truncate.output()）
• 权限系统控制访问

5. Provider 系统 (packages/opencode/src/provider/provider.ts)

支持多 AI 提供商的统一抽象：

AI SDK 统一接口：

使用 Vercel AI SDK (ai package) 统一调用：

import { streamText } from "ai"

const result = streamText({
  model: provider.getModel(providerID, modelID),
  messages: [...],
  tools: toolRegistry.tools(),
})

6. Server (packages/opencode/src/server/server.ts)

HTTP 服务基于 Hono 框架：

服务器配置：

Server.listen({
  port: 4096,
  hostname: "0.0.0.0",
  mdns: true,           // 服务发现
  mdnsDomain: "opencode",
  cors: ["https://app.opencode.ai"],
})

---

数据流与通信机制

1. CLI 请求流程

2. Server/Web 请求流程

3. Event Bus 系统

事件定义示例：

// BusEvent 定义
BusEvent.define("session.error", z.object({
  sessionID: SessionID.zod.optional(),
  error: MessageV2.Assistant.shape.error,
}))

// 发布事件
Bus.publish(Event.Error, { sessionID, error })

// 订阅所有事件
bus.subscribeAll().pipe(
  Stream.runForEach((event) => handleEvent(event))
)

4. Sync Event (Event Sourcing)

Sync Event 特性：

• 版本化事件（支持版本迁移）
• 幂等处理（检查序列号）
• 事务性保证
• 可重放（用于同步/恢复）

---

关键技术栈

运行时与构建

核心依赖

类别	技术	版本	用途
运行时	Bun	1.3.11	JS 运行时、文件系统、HTTP
HTTP	Hono	4.10.7	Web 服务器框架
UI	SolidJS	1.9.10	响应式 UI 框架
桌面	Tauri	2.0	跨平台桌面应用
AI SDK	ai (Vercel)	6.0.138	统一 AI 接口
Effect	effect	4.0.0-beta.43	函数式效果系统
ORM	drizzle-orm	1.0.0-beta.19	数据库 ORM
验证	Zod	4.1.8	Schema 验证
工具	Remeda	2.26.0	函数式工具库
文档	Astro	5.7.13	文档网站
组件	Kobalte	0.13.11	Headless UI

AI 提供商 SDK

---

设计模式与特色

1. Effect-TS 服务架构

OpenCode 使用 Effect-TS 实现依赖注入和服务管理：

服务定义模式：

// 1. 定义接口
export interface Interface {
  readonly get: (id: string) => Effect.Effect<Info>
  readonly list: () => Effect.Effect<Info[]>
}

// 2. 创建服务类
export class Service extends ServiceMap.Service<Service, Interface>()("@opencode/ModuleName") {}

// 3. 实现 Layer
export const layer = Layer.effect(Service, Effect.gen(function* () {
  const config = yield* Config.Service  // 依赖注入
  // ... 实现逻辑
  return Service.of({ get, list })
}))

// 4. 组合依赖
export const defaultLayer = layer.pipe(
  Layer.provide(Config.defaultLayer),
)

// 5. 创建运行时
const { runPromise } = makeRuntime(Service, defaultLayer)
export async function get(id: string) {
  return runPromise((svc) => svc.get(id))
}

2. InstanceState 模式

项目级状态管理，支持工作树隔离：

工作树支持：

• 每个工作树独立状态
• 避免跨工作树数据污染
• 支持并行开发

3. Permission 系统

细粒度的权限控制：

权限规则合并：

// 合并多层规则（优先级：用户 > Agent > 默认）
Permission.merge(defaults, agentRules, userRules)

4. LSP 集成

完整的 Language Server Protocol 支持：

---

扩展机制

1. MCP (Model Context Protocol)

支持外部 MCP 服务器集成：

MCP 配置：

{
  "mcp": {
    "servers": {
      "my-server": {
        "url": "https://mcp.example.com/sse",
        "type": "sse",
        "auth": { "type": "oauth" }
      }
    }
  }
}

2. Plugin 系统

插件可扩展工具、Hook 和配置：

自定义工具示例：

// .opencode/tools/my-tool.ts
export default {
  description: "My custom tool",
  args: {
    input: z.string(),
  },
  execute: async (args, ctx) => {
    return `Result: ${args.input}`
  },
}

3. Skill 系统

基于 Markdown 的技能定义：

SKILL.md 示例：

---
name: commit
description: Generate git commit message
---

Create a commit message following conventional commits format...

---

部署与运行

开发模式

# CLI 开发
bun dev

# Web 开发
bun dev:web

# Desktop 开发
bun dev:desktop

# Console 开发
bun dev:console

构建命令

# 类型检查
bun typecheck

# 构建所有包
bun build

# 测试（包内）
cd packages/opencode && bun test

服务启动

# 启动 HTTP 服务
opencode serve --port 4096

# 运行 CLI TUI
opencode

# 运行单次命令
opencode run "分析这个项目"

配置优先级

配置文件位置：

位置	路径	用途
系统	/Library/Application Support/opencode/	系统级配置
项目	.opencode/config.jsonc	项目配置
用户	~/.opencode/config.jsonc	用户配置
环境	OPENCODE_* 环境变量	运行时覆盖

SST 云部署

项目支持 SST (Serverless Stack) 部署：

// sst.config.ts
export default {
  config(input) {
    return { name: "opencode", region: "us-east-1" }
  },
  stacks(app) {
    // 云函数、存储等资源定义
  },
}

---

总结

OpenCode 是一个设计精良的 AI 开发工具，具有以下核心特点：

1. 模块化 Monorepo - 清晰的包结构，职责分离
2. Effect-TS 架构 - 函数式依赖注入，类型安全
3. 多客户端支持 - CLI/Web/Desktop/IDE 一体化
4. 多 AI 提供商 - 15+ 提供商统一接口
5. Event Sourcing - SyncEvent 保证数据一致性
6. 扩展性 - MCP/Plugin/Skill 多层扩展
7. 权限系统 - 细粒度操作控制
8. LSP 集成 - 完整 IDE 功能支持

该项目展示了现代 TypeScript 项目的最佳实践，特别是在：

• 服务架构设计（Effect-TS）
• 事件驱动通信（Bus/SyncEvent）
• 多平台客户端（SolidJS/Tauri）
• AI SDK 集成（Vercel AI SDK）
• 扩展系统设计（MCP/Plugin）

---

附录：关键文件路径

文件	路径	说明
CLI 入口	packages/opencode/src/index.ts	主程序入口
Agent 系统	packages/opencode/src/agent/agent.ts	Agent 定义
Session 管理	packages/opencode/src/session/index.ts	会话管理
Tool Registry	packages/opencode/src/tool/registry.ts	工具注册
Provider	packages/opencode/src/provider/provider.ts	AI 提供商
Server	packages/opencode/src/server/server.ts	HTTP 服务
Bus Event	packages/opencode/src/bus/bus-event.ts	事件定义
Sync Event	packages/opencode/src/sync/index.ts	同步事件
Permission	packages/opencode/src/permission/	权限系统
LSP	packages/opencode/src/lsp/	LSP 集成
MCP	packages/opencode/src/mcp/	MCP 支持
Skill	packages/opencode/src/skill/	技能系统
Plugin	packages/opencode/src/plugin/	插件系统
Web App	packages/app/src/	Web 应用
Desktop	packages/desktop/	桌面应用
SDK	packages/sdk/js/src/	JavaScript SDK
UI 组件	packages/ui/src/	共享 UI
工具函数	packages/util/src/	工具库

---