Project

Project 表示 OpenCode 工作的项目。

概述

Project 代表一个包含代码的工作目录，可以是版本控制仓库（Git）或非版本控制目录。它包含工作目录、沙箱、图标等元信息。

定义位置

packages/opencode/src/project/project.ts:19-42

属性说明

属性名类型必填说明
idstring是项目唯一标识符
worktreestring是工作树路径
vcs"git"否版本控制系统类型
namestring否项目显示名称
iconobject否项目图标配置
icon.urlstring-图标URL（data URI）
icon.overridestring-覆盖的图标URL
icon.colorstring-图标颜色（HEX）
timeobject是时间戳信息
time.creatednumber-创建时间（Unix时间戳）
time.updatednumber-最后更新时间
time.initializednumber-项目初始化时间（可选）
sandboxesstring[]是沙箱目录列表

TypeScript 类型定义

export type Project = {
  id: string
  worktree: string
  vcs?: "git"
  name?: string
  icon?: {
    url?: string
    override?: string
    color?: string
  }
  time: {
    created: number
    updated: number
    initialized?: number
  }
  sandboxes: string[]
}

事件

事件名类型说明
project.updatedinfo: Project项目更新

存储键结构

;["project", projectID]

典型使用场景

1. 从目录创建或获取项目

const { project, sandbox } = await Project.fromDirectory("/home/user/myapp")

console.log(project.id) // Git root commit hash 或 "global"
console.log(project.worktree) // /home/user/myapp
console.log(project.vcs) // "git"

2. 列出所有项目

const projects = await Project.list()

for (const project of projects) {
  console.log(`${project.name || project.id}: ${project.worktree}`)
}

3. 更新项目信息

await Project.update({
  projectID: project.id,
  name: "My Awesome App",
  icon: {
    color: "#3B82F6",
  },
})

4. 标记项目已初始化

await Project.setInitialized(project.id)

5. 获取项目的沙箱列表

const sandboxes = await Project.sandboxes(project.id)

for (const sandbox of sandboxes) {
  console.log(`Sandbox: ${sandbox}`)
}

6. 移除沙箱

await Project.removeSandbox(project.id, "/path/to/sandbox")

项目ID生成规则

OpenCode 使用以下规则生成项目 ID：

  1. Git 仓库: 使用 Git 根提交的 hash 作为 ID
  2. 非 Git 目录: 使用 "global" 作为 ID
  3. 缓存: 项目 ID 缓存在 .git/opencode 文件中

沙箱概念

沙箱是项目的独立工作目录副本，用于隔离不同会话的工作状态：

  • 主工作目录：project.worktree
  • 沙箱目录：存储在 project.sandboxes 数组中
  • 每个 Session 使用 directory 字段指向其工作目录（可能是主目录或沙箱）

图标发现

Project 支持自动发现项目图标：

  • 搜索 favicon.{ico,png,svg,jpg,jpeg,webp}
  • 选择最短路径的图标文件
  • 转换为 data URI 格式存储
  • 可以通过 icon.override 手动覆盖

对象关系

变更历史

版本变更内容日期
v1初始 Project 架构-
v1.1添加 icon 字段支持项目图标-
v1.2添加 sandboxes 字段支持沙箱-

相关文档