3.3 多项目与多 Worktree 支持

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

---

3.3.1 project/ 模块概述

OpenCode 的设计目标之一是让单个 Server 实例能同时服务多个项目和不同的 Worktree。这个需求催生了 project/ 模块的设计。

project/ 模块包含五个文件：

文件	职责
instance.ts	实例管理——项目实例的创建、获取、销毁
project.ts	项目信息——识别项目的 VCS 类型和结构
state.ts	状态管理——按目录隔离的状态存储
vcs.ts	版本控制——Git 操作封装
bootstrap.ts	初始化引导——首次打开项目时的启动流程

3.3.2 Instance.state() 模式——实例级状态隔离的实现

在 2.3.3 节我们介绍了 Instance.state() 模式。这里从多项目的角度进一步解析。

问题场景：假设用户用 OpenCode Server 同时管理两个项目：

项目 A: /home/user/project-a (Python 项目)
项目 B: /home/user/project-b (TypeScript 项目)

Session 模块、Tool 模块、Config 模块等都有各自的状态。如果两个项目共享同一份状态，就会发生混乱——项目 A 的配置可能会影响项目 B。

解决方案：State.create() 实现了按 key（通常是项目目录路径）隔离的状态存储：

// state.ts 的核心逻辑（简化版）
export namespace State {
  const stores = new Map<string, Map<string, any>>()

  export function create<S>(
    getKey: () => string,    // 通常是 () => Instance.directory
    init: () => S,           // 初始化函数
    dispose?: (s: S) => Promise<void>
  ): () => S {
    const id = Symbol()      // 每个 state 有唯一标识
    return () => {
      const key = getKey()   // 获取当前项目目录
      let store = stores.get(key)
      if (!store) {
        store = new Map()
        stores.set(key, store)
      }
      if (!store.has(id)) {
        store.set(id, init()) // 惰性初始化
      }
      return store.get(id)
    }
  }
}

这样，当代码运行在项目 A 的上下文中时，state() 返回项目 A 的状态；当运行在项目 B 的上下文中时，返回项目 B 的状态。两者完全隔离。

             ┌── state() ──► 项目 A 的 Bus 订阅列表
Instance A ──┤
             └── state() ──► 项目 A 的 Config

             ┌── state() ──► 项目 B 的 Bus 订阅列表
Instance B ──┤
             └── state() ──► 项目 B 的 Config

3.3.3 多项目并发场景下的状态管理

Instance 的生命周期：

create (首次访问)
    │
    ▼
provide (设置上下文，执行业务逻辑)
    │  可被多个请求并发调用
    │  每个请求在 context.provide() 包裹中执行
    ▼
dispose (清理资源)
    │
    ├── State.dispose(directory)   清理所有 Instance State
    ├── cache.delete(directory)    从缓存中移除
    └── GlobalBus.emit("disposed") 通知全局事件总线

并发安全：

Instance.provide() 使用了一个 cache Map 来确保同一个目录只创建一个实例：

let existing = cache.get(input.directory)
if (!existing) {
  existing = iife(async () => {
    // 创建新实例
  })
  cache.set(input.directory, existing)
}

这里使用 Promise 作为缓存值是一个巧妙的设计——即使多个请求同时到达，cache.set() 只会执行一次，后续请求会等待同一个 Promise 的完成。这在不使用锁的情况下实现了线程安全（在 JavaScript 的单线程事件循环中，这种方式是安全的）。

实例销毁：

Instance.disposeAll() 方法会清理所有实例，通常在 Server 关闭时调用：

async disposeAll() {
  const entries = [...cache.entries()]
  for (const [key, value] of entries) {
    const ctx = await value.catch(() => undefined)
    if (!ctx) { cache.delete(key); continue }
    await context.provide(ctx, async () => {
      await Instance.dispose()
    })
  }
}

注意它使用了 context.provide() 包裹每个实例的销毁操作，确保在正确的上下文中执行清理逻辑。这是 Instance State 模式的一致性保证——所有对 Instance State 的访问都必须在正确的 Instance 上下文中。