References

将本地目录和 Git 仓库添加为项目引用。

引用（References）让 OpenCode 能够访问当前项目之外的目录。你可以用它们让文档、共享库、示例或其他仓库在你工作时保持可用。

引用通过别名在 opencode.json 或 opencode.jsonc 中配置。

{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use for product behavior and documentation conventions",
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "Use for JavaScript SDK implementation details",
    },
  },
}

Local Directories

使用 path 引用本地目录。

{
  "references": {
    "docs": {
      "path": "../docs",
    },
  },
}

路径可以是：

• 相对于定义该引用的配置文件
• 绝对路径，例如 /home/user/docs
• 相对于你的主目录，例如 ~/docs

你也可以使用字符串简写形式：

{
  "references": {
    "docs": "../docs",
  },
}

Git Repositories

使用 repository 引用一个 Git 仓库。OpenCode 会将该仓库具体化到本地仓库缓存中，并将检出的源码作为引用目录提供。

{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
    },
  },
}

repository 接受 Git URL、host/path 形式的引用，以及 GitHub 的 owner/repo 简写形式。可选的 branch 字段用于指定分支或引用。不指定 branch 时，OpenCode 使用仓库的默认分支。

当你不需要指定分支、描述或其他选项时，可以使用字符串简写形式：

{
  "references": {
    "effect": "Effect-TS/effect",
  },
}

Note: Git 引用是异步刷新的。新配置的仓库可能需要一点时间才能完成克隆或更新。

Describe Usage

添加 description 来说明 Agent 应该在什么情况下使用该引用。

{
  "references": {
    "design-system": {
      "path": "../design-system",
      "description": "Use when implementing UI components or design tokens",
    },
  },
}

OpenCode 会将带有描述的引用包含在 Agent 上下文中。描述应当简短且具体，以便区分内容相似的引用。没有描述的引用仍然可以通过自动补全和直接使用来访问，但不会主动展示给 Agent。

Hide Autocomplete Entries

将 hidden 设为 true，可以在 TUI 的 @ 自动补全中省略该引用。

{
  "references": {
    "internal": {
      "path": "../internal",
      "description": "Use for internal implementation details",
      "hidden": true,
    },
  },
}

hidden 只影响自动补全。带有描述的隐藏引用仍会包含在 Agent 上下文中。

Use References

已配置的引用会出现在 TUI 的 @ 自动补全中。输入 @alias 可附加引用根目录，输入 @alias/ 可在其中搜索文件。

Compare this implementation with @sdk/src/client.ts

Agent 也会在其系统上下文中收到已配置引用（带描述的）的解析路径和描述，因此在相关的情况下，即使你没有手动附加，Agent 也可以查看该引用。

OpenCode 会通过其外部目录权限边界自动允许引用目录。常规的工具权限依然适用；例如，一个无法编辑文件的 Agent 不会因为某个目录被配置为引用而获得编辑权限。

Configure Fields

引用别名不能为空，也不能包含 /、空白字符、反引号或逗号。