外部目录与仓库 References

References 将当前项目以外的文档、共享库或示例仓库作为可访问上下文。它们按别名配置在 opencode.json 或 opencode.jsonc 的 references 中。

本地目录

{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../docs",
      "description": "Use for product behavior and documentation conventions"
    }
  }
}

path 可以相对定义它的配置文件，也可以使用绝对路径或 ~/ 路径。不需要额外属性时，可使用字符串简写，例如 "docs": "../docs"。

别名不能为空，也不能包含 /、空白、反引号或逗号。选择容易区分的名称，避免与任务中的其他上下文混淆。

Git 仓库

Git reference 使用 repository，支持 Git URL、host/path 或 GitHub owner/repo 简写。branch 可选择分支或 ref；省略时使用仓库默认分支。

OpenCode 会将仓库 materialize 到本地仓库缓存，再把检出的源码作为 reference 目录。克隆和更新异步进行，新配置不一定马上可用；不要把保存配置成功当成已经获得完整源码。

Git 配置用 repository 而不是 path，本地配置使用 path 而不是 repository。branch 仅适用于 Git 类型。

描述与隐藏的区别

带 description 的 reference 会把说明和解析后路径加入 Agent 系统上下文，帮助它判断何时主动查看。没有描述时，仍可通过补全和直接引用使用，但不会向 Agent 主动介绍。

hidden: true 只隐藏 TUI 的 @ 补全条目。若仍有 description，隐藏的 reference 仍加入 Agent 上下文；它不是访问控制或秘密保护设置。

在任务中使用

@alias 添加根目录上下文，@alias/ 补全其中的文件。也可以直接输入已配置别名下的文件，例如 @docs/README.md，说明需要比较的行为或约定。

OpenCode 自动允许 reference 目录通过 external-directory 边界，普通工具权限仍然适用。一个不能编辑文件的 Agent 不会仅因为目录被配置成 reference 就得到编辑权限；反过来，配置 reference 本身也不保证目录只读。

核对加载

确认别名规则、相对路径基准、Git 分支和缓存完成状态，再检查 description 是否让 Agent 知道其用途。涉及写操作时，分别检查普通编辑和 shell 权限，不要只看目录是否出现在补全列表。