2.2 Monorepo 结构剖析

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2025-02-17

---

2.2.1 根目录文件解读

在开始深入源码之前，先把根目录的关键文件梳理清楚：

opencode/
├── package.json        # 工作区根配置
├── tsconfig.json       # TypeScript 基础配置
├── turbo.json          # Turborepo 任务编排
├── sst.config.ts       # SST（云基础设施）配置
├── bunfig.toml         # Bun 配置
├── flake.nix           # Nix 开发环境
├── bun.lock            # 依赖锁文件
├── packages/           # 所有子包
├── sdks/               # IDE SDK
├── infra/              # 基础设施代码
├── specs/              # 设计规范文档
├── script/             # 全局脚本
├── patches/            # 第三方包补丁
└── nix/                # Nix 相关配置

package.json 的关键信息：

{
  "name": "opencode",
  "private": true,
  "type": "module",
  "packageManager": "[email protected]",
  "workspaces": {
    "packages": [
      "packages/*",
      "packages/console/*",
      "packages/sdk/js",
      "packages/slack"
    ]
  }
}

workspaces 字段定义了 Monorepo 中各子包的位置。Bun 会扫描这些路径下的所有 package.json，将它们作为工作区的成员管理。

衍生概念：什么是 Monorepo？

Monorepo（Monolithic Repository）是将多个相关项目放在同一个 Git 仓库中管理的策略。与之相对的是 Polyrepo（每个项目一个仓库）。

Monorepo 的优势：

• 代码共享简单：子包之间可以直接引用，无需发布到 npm

• 原子提交：修改跨多个子包的功能可以在一次 commit 中完成

• 统一的构建流程：通过 Turborepo 统一管理所有子包的构建、测试

• 依赖版本一致：所有子包使用同一版本的第三方依赖

Turborepo 的工作原理： Turborepo 是 Vercel 开发的 Monorepo 构建系统。它的核心能力是：

1. 任务编排：根据子包间的依赖关系确定构建顺序

2. 并行执行：没有依赖关系的任务会并行运行

3. 智能缓存：基于源文件的 Hash 判断是否需要重新构建

例如，当你运行 bun turbo typecheck 时，Turborepo 会分析所有子包的依赖关系，按拓扑排序并行执行类型检查，并缓存结果。

tsconfig.json：

{
  "extends": "@tsconfig/bun/tsconfig.json",
  "compilerOptions": {}
}

非常简洁——继承了 Bun 官方的 TypeScript 配置。各子包会有自己更详细的 tsconfig.json。

2.2.2 packages/ 目录总览——17 个子包的职责划分

packages/ 是整个项目的核心，包含 17 个子包。它们的职责与相互关系如下图：

                          ┌─────────────┐
                          │   desktop   │ (Tauri 桌面应用)
                          └──────┬──────┘
                                 │ 嵌入
                          ┌──────▼──────┐
                ┌────────►│     app     │◄────────┐
                │         │ (SolidJS    │         │
                │         │  Web 前端)  │         │
                │         └──────┬──────┘         │
                │                │ 使用           │
                │         ┌──────▼──────┐         │
                │         │     ui      │         │
                │         │ (共享组件库)│         │
                │         └─────────────┘         │
                │                                 │
         ┌──────┴──────┐                   ┌──────┴──────┐
         │     sdk     │ ◄─────────────── │   opencode   │
         │ (TS SDK,    │   OpenAPI 生成   │  (核心引擎)  │
         │  自动生成)  │                   │             │
         └─────────────┘                   └──────┬──────┘
                                                  │ 使用
                                           ┌──────▼──────┐
                                           │    plugin    │
                                           │ (插件接口   │
                                           │  类型定义)  │
                                           └─────────────┘

各子包的详细说明：

子包	路径	职责	技术栈
opencode	packages/opencode/	核心引擎。包含 CLI、Server、所有业务逻辑（Session、Tool、Agent、Provider 等）	TypeScript, Bun
app	packages/app/	Web 前端应用。提供浏览器界面来使用 OpenCode	SolidJS, Vite
ui	packages/ui/	共享 UI 组件库。被 app 和其他前端项目使用	SolidJS
sdk	packages/sdk/	TypeScript 客户端 SDK。从 OpenAPI 规范自动生成	OpenAPI Codegen
plugin	packages/plugin/	Plugin 接口的类型定义。Plugin 开发者依赖此包获得类型支持	TypeScript
web	packages/web/	官方网站 (opencode.ai)	Astro
console	packages/console/	云控制台（含 app、core、function、mail、resource 子模块）	—
enterprise	packages/enterprise/	企业版功能（SSO、审计日志等）	TypeScript
containers	packages/containers/	Docker 容器化支持	Dockerfile
desktop	packages/desktop/	桌面应用	Tauri (Rust + Web)
function	packages/function/	Serverless 函数（用于云端功能）	TypeScript
identity	packages/identity/	品牌资源（Logo SVG/PNG）	—
script	packages/script/	构建脚本和开发工具	TypeScript
slack	packages/slack/	Slack 集成	TypeScript
extensions	packages/extensions/	IDE 扩展（目前含 Zed 扩展）	TOML
docs	packages/docs/	文档	Markdown
util	packages/util/	跨包共享的工具函数	TypeScript

给读者的建议：本书的源码分析主要集中在 packages/opencode/（核心引擎）。当涉及前端、插件接口、SDK 等话题时，才会进入其他子包。如果你只想理解 OpenCode 的核心架构，只需要关注 packages/opencode/src/ 即可。

2.2.3 sdks/vscode/ —— VSCode 扩展

在 packages/ 之外，还有一个独立的 sdks/vscode/ 目录，包含 OpenCode 的 VSCode 扩展：

sdks/vscode/
├── src/            # 扩展源码
├── images/         # 扩展图标
├── package.json    # VSCode 扩展清单
├── esbuild.js      # 构建配置
└── README.md       # 扩展说明

VSCode 扩展通过与 OpenCode 的内嵌 HTTP Server 通信来提供编辑器内的 AI 功能。它不是 OpenCode 的运行必需品，而是一个可选的增强。

2.2.4 infra/ —— SST 基础设施即代码

infra/
├── app.ts          # Web App 部署
├── console.ts      # 控制台部署
├── enterprise.ts   # 企业版基础设施
├── secret.ts       # 密钥管理
└── stage.ts        # 环境阶段定义

衍生概念：SST（Serverless Stack）

SST 是一个用于在 AWS 上部署全栈应用的框架。它允许开发者用 TypeScript 代码定义云基础设施（Infrastructure as Code，IaC），而不是手动在 AWS 控制台中配置。

根目录的 sst.config.ts 就是 SST 的入口配置文件。这部分与 OpenCode CLI 的核心功能无关，主要用于部署 OpenCode 的 Web 版本和云端服务。

对于本书的读者来说，infra/ 目录不是重点。它的存在说明 OpenCode 不仅仅是一个 CLI 工具，还有完整的云端基础设施支撑其在线服务。