资源引用

要点

opencode.json 顶层的 references 键把当前项目之外的资源挂载进会话并赋予别名：本地目录用 path（支持相对、绝对、~/ 路径），Git 仓库用 repository（完整 URL、host/path 或 GitHub owner/repo 简写，可选 branch）。加 description 告诉 agent 何时使用；设 "hidden": true 可从 TUI 的 @ 自动补全中隐藏但仍进入上下文。用 @别名 附加、@别名/ 搜索文件。引用路径自动越过外部目录权限边界，普通工具权限仍然生效。

References 让 OpenCode 可以访问当前项目之外的目录。每个引用获得一个别名，用于把内容附加到对话中。

{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "回答产品功能相关问题时使用"
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "基于 SDK 编写代码时使用"
    }
  }
}

本地目录

使用 path 字段引用本地目录。相对路径以项目根目录为基准解析，绝对路径直接使用，~/ 开头的路径解析到主目录：

{
  "references": {
    "shared": { "path": "~/projects/shared-libs" }
  }
}

不需要额外选项时，字符串即 path 的简写形式：

{
  "references": {
    "shared": "~/projects/shared-libs"
  }
}

Git 仓库

使用 repository 字段引用 Git 仓库。完整的 Git URL、host/path 形式、GitHub owner/repo 简写均可。仓库会克隆到缓存中并异步刷新，保持引用内容最新：

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

branch 字段指定分支或 ref；省略时使用默认分支。与本地目录一样，字符串值同样是不需要 branch 时的简写。

描述用途

添加 description 告诉 agent 每个引用的用途、何时查阅。没有描述的引用不会主动推送给 agent：

{
  "references": {
    "design-system": {
      "path": "../design-tokens",
      "description": "实现 UI 组件或设计令牌时使用"
    }
  }
}

隐藏自动补全项

设置 "hidden": true 让引用不出现在 TUI 的 @ 自动补全菜单里。带描述的隐藏引用仍参与 agent 的上下文：

{
  "references": {
    "archive": {
      "path": "../legacy-archive",
      "description": "迁移工作所需的历史背景",
      "hidden": true
    }
  }
}

使用引用

在 TUI 中输入 @ 加别名即可把引用内容附加到消息中；输入 @别名/ 可以模糊搜索其中的文件。相关快捷键见快捷键。

被引用的目录会自动越过权限文档中描述的外部目录权限边界，工具无需额外批准即可读取；普通工具级权限规则继续生效。

配置字段

字段	本地	Git	说明
path	✓		引用的本地目录
repository		✓	Git URL、host/path 或 owner/repo
branch		✓	可选分支或 ref，默认取默认分支
description	✓	✓	告诉 agent 何时使用该引用
hidden	✓	✓	从 TUI @ 自动补全中排除

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