OpenCode 架构文档

最新推荐文章于 2026-06-07 18:22:59 发布

原创最新推荐文章于 2026-06-07 18:22:59 发布 · 254 阅读

4 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#AI编程

# OpenCode 架构文档

> 最后更新: 2026-04-18

## 1. 系统概述

OpenCode 是一个 AI 编程助手，提供终端 UI（TUI）和 HTTP API，用于与大型语言模型交互并执行软件开发任务。

### 技术栈

- **运行时**: Bun
- **Web 框架**: Hono
- **AI SDK**: Vercel AI SDK (`@ai-sdk/*`)
- **数据库**: SQLite + Drizzle ORM
- **UI**: SolidJS + Ink-style TUI
- **Effect**: effect 框架用于依赖注入和服务层

---

## 2. 目录结构

```
src/
├── index.ts # CLI 入口（Yargs）
├── cli/ # CLI 命令和 TUI 组件
│ ├── cmd/ # 命令（run, serve, tui, account 等）
│ └── tui/ # 终端 UI 组件
├── session/ # 会话管理
│ ├── session.sql.ts # 数据库表定义
│ ├── message.ts # 消息处理
│ └── prompt.ts # 提示词构建
├── tool/ # 工具定义
│ ├── bash.ts # Shell 执行
│ ├── read/write/edit # 文件操作
│ ├── grep/glob # 搜索
│ ├── task.ts # 任务管理
│ └── registry.ts # 工具注册
├── server/ # HTTP API
│ ├── server.ts # Hono 服务器
│ └── routes/ # 路由处理
│ ├── session.ts
│ ├── project.ts
│ ├── pty.ts
│ └── ...
├── storage/ # 数据持久化
│ ├── db.ts # 数据库连接
│ ├── schema.sql.ts # 共享 schema
│ └── json-migration.ts # 迁移工具
├── provider/ # AI Provider
│ ├── transform.ts # 响应转换
│ └── copilot/ # Copilot 集成
├── project/ # 项目管理
│ ├── project.sql.ts # 项目表
│ └── worktree.ts # Git worktree
├── account/ # 账户管理
├── auth/ # 认证
├── permission/ # 权限系统
├── config/ # 配置加载
├── effect/ # Effect 运行时
├── control-plane/ # 云端工作区
├── skill/ # 技能系统
├── mcp/ # MCP 客户端/服务端
├── bus/ # 事件总线
└── util/ # 工具函数
├── log.ts
├── filesystem.ts
├── process.ts
└── ...
```

---

## 3. 数据库 Schema

### 表关系

```
project (1) ──> session (N)
session (1) ──> message (N)
message (1) ──> part (N)
session (1) ──> todo (N)
project (1) ──> permission (1)
```

### 主要表

| 表名 | 用途 |
| ------------ | -------------------------------- |
| `project` | 项目配置、worktree、git 信息 |
| `session` | 会话、摘要、权限、工作区 |
| `message` | 消息（角色、内容、时间戳） |
| `part` | 消息部分（工具调用、推理、文本） |
| `todo` | 待办事项（会话内） |
| `permission` | 规则集权限 |
| `account` | 账户信息 |
| `workspace` | 云端工作区 |

---

## 4. 核心服务（Effect）

`src/effect/runtime.ts` 合并四个服务层：

```typescript
Layer.mergeAll(AccountService.defaultLayer, AuthService.defaultLayer, PermissionService.layer, QuestionService.layer)
```

### AccountService

- 账户管理：`active`, `list`, `orgs`, `use`, `token`, `login`

### AuthService

- 认证处理：登录、令牌验证

### PermissionService

- 权限检查：规则集匹配（allow/deny/ask）

### QuestionService

- 用户交互：问题确认、选择

---

## 5. API 端点

基于 Hono 的 REST API：

| 路由 | 方法 | 用途 |
| ------------- | -------- | ---------------- |
| `/project` | GET/POST | 项目 CRUD |
| `/session` | GET/POST | 会话 CRUD |
| `/pty` | WS | 伪终端 |
| `/provider` | GET | AI Provider 信息 |
| `/permission` | GET | 权限查询 |
| `/question` | POST | 用户交互 |
| `/mcp` | GET/POST | MCP 服务 |
| `/file` | GET/POST | 文件操作 |
| `/config` | GET/POST | 配置管理 |
| `/event` | GET | SSE 事件流 |

---

## 6. 工具系统

### 内置工具

| 工具 | 功能 |
| ------------ | -------------- |
| `bash` | Shell 命令执行 |
| `read` | 读取文件 |
| `write` | 写入文件 |
| `edit` | 编辑文件 |
| `glob` | 模式匹配 |
| `grep` | 内容搜索 |
| `task` | 任务委派 |
| `todo` | 待办管理 |
| `webfetch` | HTTP 获取 |
| `websearch` | 网页搜索 |
| `codesearch` | 代码搜索 |
| `skill` | 技能调用 |
| `lsp` | LSP 查询 |
| `question` | 用户问题 |

### 工具注册

`src/tool/registry.ts` 加载：

1. 内置工具（`src/tool/*.ts`）
2. 自定义工具（配置目录 `tool/` 或 `tools/`）
3. 插件工具

---

## 7. 配置系统

### 级联优先级

1. 远程 well-known
2. 全局配置
3. 自定义 provider
4. 项目配置
5. `.opencode` 文件
6. 托管配置

### 配置格式

支持 JSONC（带注释的 JSON）

---

## 8. 事件系统

- **Local Bus**: 进程内事件
- **Global Bus**: 跨实例事件

---

## 9. 工作流

```
CLI 输入 (Yargs)
│
▼
配置加载 (config/)
│
▼
数据库连接 (storage/)
│
▼
认证检查 (auth/)
│
▼
会话管理 (session/)
│
▼
提示词构建 (prompt.ts)
│
▼
AI Provider 调用 (provider/)
│
▼
工具执行 (tool/)
│
▼
响应渲染 (TUI 或 JSON)
```