跳到正文
本地目录

引用

引用让 OpenCode 可以访问当前项目之外的目录。你可以用它在工作时提供文档、共享库、示例或其他仓库。

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

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",
    },
  },
}

使用 path 引用本地目录。

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

路径可以是：

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

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

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

使用 repository 引用 Git 仓库。OpenCode 会将该仓库放入本地仓库缓存中，并将检出的源代码作为引用目录提供。

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

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

如果不需要指定分支、描述或其他选项，可以使用字符串简写：

opencode.jsonc
{
  "references": {
    "effect": "Effect-TS/effect",
  },
}

添加 description 来说明代理应在何时使用某个引用。

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

OpenCode 会将带有描述的引用加入代理上下文。描述应简短、具体，足以区分内容相似的引用。没有描述的引用仍可通过自动补全和直接使用来访问，但不会告知代理。

将 hidden 设置为 true，即可在 TUI 的 @ 自动补全中隐藏某个引用。

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

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

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

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

对于带有描述的已配置引用，代理还会在系统上下文中收到它们的解析路径和描述，因此在相关时可以自行查看引用，无需你手动附加。

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

字段本地Git说明
path是否本地引用目录
repository否是Git URL、host/path 或 GitHub owner/repo 值
branch否是可选的 Git 分支或 ref
description是是说明何时使用该引用的指引
hidden是是在 TUI 的 @ 自动补全中隐藏该引用

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