2.3 核心包 packages/opencode/src/ 的模块地图

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

---

packages/opencode/src/ 是整个 OpenCode 的大脑和心脏。这个目录包含了 37 个模块（子目录），每个模块负责一个明确的职责领域。本节将逐一介绍它们，并分析模块间的依赖关系。

2.3.1 全部 37 个模块目录概览

按功能分组，可以将这 37 个模块分为六大类：

核心业务模块

模块	目录	核心文件	职责
Session	session/	index.ts, processor.ts, llm.ts, compaction.ts	会话管理。OpenCode 的核心抽象——管理对话生命周期、消息处理、Agentic Loop
Tool	tool/	tool.ts, registry.ts, 20+ 个工具文件	工具系统。定义 Agent 能使用的所有工具（读写文件、执行命令等）
Agent	agent/	agent.ts, prompt/*.txt	Agent 定义。配置 AI 的行为模式、权限、Prompt
Provider	provider/	provider.ts, transform.ts, models.ts	多模型适配。统一对接 20+ 个 LLM Provider
MCP	mcp/	index.ts, auth.ts, oauth-*.ts	Model Context Protocol 客户端。连接外部工具生态
Permission	permission/	next.ts, index.ts, arity.ts	权限控制。管理 Agent 的行为边界

基础设施模块

模块	目录	核心文件	职责
Config	config/	config.ts, markdown.ts	配置系统。分层加载和合并配置
Storage	storage/	storage.ts	本地持久化。Session 数据、消息历史的文件存储
Bus	bus/	index.ts, bus-event.ts, global.ts	事件总线。模块间解耦通信
Scheduler	scheduler/	index.ts	定时任务。如 Snapshot 清理
Global	global/	index.ts	全局路径管理。XDG 规范的目录结构
Project	project/	instance.ts, project.ts, state.ts, vcs.ts	项目管理。多项目实例隔离
Auth	auth/	index.ts	认证。API Key 和 OAuth 凭据管理

用户界面模块

模块	目录	核心文件	职责
CLI	cli/	bootstrap.ts, cmd/*.ts, cmd/tui/	命令行界面。入口、子命令、TUI 渲染
Server	server/	server.ts, routes/*.ts, event.ts	HTTP 服务。API 路由和 SSE 推送

文件与版本控制模块

模块	目录	核心文件	职责
Snapshot	snapshot/	index.ts	Git 快照。文件变更前的安全网
File	file/	index.ts, ignore.ts, ripgrep.ts, watcher.ts	文件操作。搜索、监听、.gitignore 解析
Patch	patch/	index.ts	Diff 补丁。生成和应用代码变更
Worktree	worktree/	index.ts	Git Worktree 管理

扩展性模块

模块	目录	核心文件	职责
Plugin	plugin/	index.ts, codex.ts, copilot.ts	插件加载。动态加载和管理 Plugin
Skill	skill/	index.ts, skill.ts, discovery.ts	Skill 管理。发现和加载 Markdown Skill 文件
Command	command/	index.ts, template/	自定义命令。Slash Command 系统
ACP	acp/	agent.ts, session.ts, types.ts	Agent Client Protocol。IDE 集成协议

辅助模块

模块	目录	核心文件	职责
ID	id/	id.ts	标识符生成。有序 ULID 生成
Flag	flag/	flag.ts	环境变量。功能开关和配置覆盖
Env	env/	index.ts	环境检测
Format	format/	formatter.ts, index.ts	格式化工具
Shell	shell/	shell.ts	Shell 环境。检测和配置用户的 Shell
PTY	pty/	index.ts	伪终端。支持交互式终端操作
IDE	ide/	index.ts	IDE 检测。识别用户的开发环境
Installation	installation/	index.ts	安装信息。版本、更新检测
Share	share/	share.ts, share-next.ts	会话分享。生成可分享的会话链接
Question	question/	index.ts	交互式提问。Agent 向用户发起问答
Bun	bun/	—	Bun 运行时辅助。npm 包动态安装等
Util	util/	多个工具文件	公共工具函数。日志、文件系统、Token 计算等

2.3.2 模块间依赖关系图（DAG 分析）

理解模块间的依赖关系是读懂源码的关键。以下是核心模块的依赖关系图（箭头表示"依赖于"）：

┌──────────────────────────────────────────────────────┐
│                      CLI 层                           │
│  cli/ ─────► server/ ─────► session/ ─────► tool/    │
│                                │                │     │
│                                ▼                ▼     │
│                            agent/           registry/ │
│                                │                │     │
│                                ▼                ▼     │
│                           provider/          mcp/     │
└──────────────────────────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────┐
│                    基础设施层                          │
│  config/   bus/   storage/   permission/              │
│     │       │        │            │                   │
│     └───────┴────────┴────────────┘                   │
│                      │                                │
│                      ▼                                │
│               project/instance                        │
│                      │                                │
│                      ▼                                │
│               global/  util/  id/                     │
└──────────────────────────────────────────────────────┘

关键依赖路径：

1. CLI → Server → Session → Tool：这是请求处理的主路径。用户在 CLI 中输入 → Server 接收 → Session 管理对话 → Tool 执行操作。

2. Session → Agent → Provider：Session 需要知道使用哪个 Agent，Agent 需要知道使用哪个模型 Provider。

3. 几乎所有模块 → project/instance：Instance 提供了实例级别的状态管理能力，是整个系统的状态基座。

4. 几乎所有模块 → config/、bus/：配置和事件总线是横切关注点（Cross-Cutting Concerns）。

2.3.3 Instance 状态管理模式详解

在 OpenCode 源码中，你会频繁看到这样的代码模式：

const state = Instance.state(async () => {
  // 初始化状态
  return { /* ... */ }
})

这是 OpenCode 最核心的设计模式之一——Instance State 模式。让我们通过源码来理解它。

Instance 的定义（project/instance.ts）：

export const Instance = {
  async provide<R>(input: {
    directory: string
    init?: () => Promise<any>
    fn: () => R
  }): Promise<R> {
    // 为指定目录创建或获取一个实例上下文
    let existing = cache.get(input.directory)
    if (!existing) {
      existing = iife(async () => {
        const { project, sandbox } = await Project.fromDirectory(input.directory)
        return { directory: input.directory, worktree: sandbox, project }
      })
      cache.set(input.directory, existing)
    }
    const ctx = await existing
    return context.provide(ctx, async () => input.fn())
  },

  get directory() { return context.use().directory },
  get worktree() { return context.use().worktree },
  get project() { return context.use().project },

  state<S>(init: () => S, dispose?: (state: Awaited<S>) => Promise<void>): () => S {
    return State.create(() => Instance.directory, init, dispose)
  },
}

核心思想：

1. 每个项目目录是一个隔离的实例。当 OpenCode 管理多个项目时，每个项目有自己独立的状态空间。

2. Instance.state() 是一个状态工厂。它返回一个函数，调用该函数时会根据当前的 Instance.directory 返回对应的状态。如果状态不存在，则通过 init 函数创建。

3. 状态是惰性初始化的。只有在第一次访问时才会执行初始化逻辑。

4. 状态支持销毁。当实例被释放时，通过 dispose 回调清理资源。

衍生概念：单例模式与 Context 模式

传统的单例模式（Singleton Pattern）确保一个类只有一个实例。但在 OpenCode 中，需要的是**"按项目目录分片的多实例单例"**——同一个模块在不同项目目录下有不同的状态实例。

这通过 Context 工具类实现，本质上类似于 React 的 Context API 或 Java 的 ThreadLocal——在特定的执行上下文中携带隐式的状态信息，避免在函数调用链中层层传递参数。

这种模式在 OpenCode 中极为普遍。理解它是阅读源码的前提。

一个实际的例子——Bus（事件总线）如何使用 Instance State：

export namespace Bus {
  // 每个项目实例有独立的事件订阅列表
  const state = Instance.state(
    () => {
      const subscriptions = new Map<any, Subscription[]>()
      return { subscriptions }
    },
    async (entry) => {
      // 实例销毁时，触发通知并清理
      const wildcard = entry.subscriptions.get("*")
      if (wildcard) {
        for (const sub of [...wildcard]) {
          sub({ type: "server.instance.disposed", ... })
        }
      }
    },
  )
}

Global 模块——全局路径管理：

与 Instance 的实例级状态不同，Global 管理的是全局共享的路径信息：

export namespace Global {
  export const Path = {
    get home() { return process.env.OPENCODE_TEST_HOME || os.homedir() },
    data,        // ~/.local/share/opencode
    bin,         // ~/.local/share/opencode/bin
    log,         // ~/.local/share/opencode/log
    cache,       // ~/.cache/opencode
    config,      // ~/.config/opencode
    state,       // ~/.local/state/opencode
  }
}

OpenCode 遵循 XDG Base Directory 规范 来组织用户级文件：

衍生概念：XDG Base Directory 规范

XDG（X Desktop Group）Base Directory 规范定义了 Linux/macOS 上用户级配置、数据、缓存文件的标准存放位置：

环境变量	默认值	用途
$XDG_CONFIG_HOME	~/.config	配置文件
$XDG_DATA_HOME	~/.local/share	数据文件
$XDG_CACHE_HOME	~/.cache	缓存文件
$XDG_STATE_HOME	~/.local/state	状态文件

遵循这个规范意味着 OpenCode 的文件不会"污染"用户的 Home 目录，也方便用户迁移和清理。

理解了这些基础模式和目录结构后，我们就有了阅读后续章节源码分析的地图。接下来的第3章将从更高的视角审视 OpenCode 的整体架构设计。