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(通常是项目目录路径)隔离的状态存储:

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

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

Instance 的生命周期

并发安全

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

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

实例销毁

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

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

Last updated