外部参考目录与仓库

适用 OpenCode V2 · 核验日期：2026-11-12。 来源：官方 References↗。本文为官方当前文档的中文操作指南；未在本站执行安装、认证或模型请求。

References 给项目外目录或仓库一个名称，供客户端附加并让代理查阅。

# 本地与远程配置#

json
复制
1{
2  "$schema": "https://opencode.ai/config.json",
3  "references": {
4    "docs": {
5      "path": "../product-docs",
6      "description": "用于查阅产品行为和术语"
7    },
8    "effect": { "repository": "Effect-TS/effect", "branch": "main" }
9  }
10}

相对本地路径从配置文件所在目录解析，支持绝对路径和 ~/。字符串简写只有以 ., /, ~ 开头时才是本地目录；用 ./docs，不要用 docs，后者会解释为 Git 仓库。

远程支持 GitHub owner/repo、Git URL、主机路径和 SCP 风格地址，不支持本地 file: 仓库。不指定分支时跟随远程默认分支。

# 怎样使用#

客户端附加根别名时，得到根目录的非递归文件列表，不会自动注入整个仓库。请明确请求：“读取已附加 docs 中的 api/authentication.md，解释认证流程。”

description 会把名称和路径加入代理指令，说明什么时候使用；未提供描述的引用仍可被客户端使用。hidden: true 仅隐藏交互选择项，不是访问控制，也不从 reference API 或有描述的代理指令中移除。

# 缓存与刷新#

远程仓库按 remote 和 branch 在全局数据目录缓存。首次异步克隆；加载、重载或接收新提示时检查是否需要刷新，上次尝试距今至少 24 小时才符合条件。失败尝试也受这一间隔限制，时间跨服务重启保留；闲置 Location 没有定时轮询。

提示不会等待克隆或刷新，附件与稍后工具读取可能见到不同版本。缓存由多个 Location 共享，刷新会 fetch 并 reset，不要把自己的编辑保存在缓存 checkout 中。

# 权限#

Reference 不授予额外工具权限。外部读取仍受 external_directory 规则约束，编辑还需 edit 权限。V2 默认允许外部目录访问；需要保持 V1 询问行为请在权限中显式配置 ask，见权限。别名不能为空，也不能含斜杠、反斜杠、空白、反引号或逗号。