第19章 OpenCode 参考配置指南:通过别名访问本地目录与远程仓库
参考资料 References 让 OpenCode 能够通过命名别名访问当前项目之外的目录。在 opencode.json 或 opencode.jsonc 中添加配置,然后在需要时在客户端附加对应的别名。
opencode.jsonc { "$schema": "https://opencode.ai/config.json", "references": { "docs": { "path": "../product-docs", "description": "用于产品行为和术语说明" } } }
附加 docs 别名后,指示智能体检查相关路径: "阅读附加的 docs 参考资料并总结 api/authentication.md 的内容。"
使用 references 指向文档、共享库、示例或其他仓库的源代码。
对本地目录使用 path: JSONC { "references": { "design-system": { "path": "../design-system", "description": "处理组件或设计令牌时使用" } } }
路径行为规则:
- 相对路径基于包含该配置文件的目录进行解析。 - 支持绝对路径。 - 支持以主目录为基准的路径,例如 ~/docs。
若无需其他字段,使用字符串简写形式: JSONC { "references": { "docs": "../docs", "shared": "~/work/shared" } }
对远程 Git 仓库使用 repository: JSONC { "references": { "effect": { "repository": "Effect-TS/effect", "branch": "main" }, "internal-sdk": { "repository": "git@gitlab.example.com:platform/sdk.git", "branch": "release/v2" } } }
支持的远程格式包括:
- GitHub owner/repo 简写 - Git URL - Host/path 格式 - SCP 风格远程地址
不支持本地 file:// 仓库。
使用字符串简写形式跟踪远程默认分支: JSONC { "references": { "effect": "Effect-TS/effect", "sdk": "gitlab.com/platform/sdk" } }
未指定 branch 时,OpenCode 将检出并刷新远程的默认分支。
分支名称可包含字母、数字、/、_、. 和 -,但不能以 - 开头或包含 ... JSONC { "references": { "sdk": { "repository": "example/sdk", "branch": "release/v2.1" } } }
OpenCode 会规范化每个远程地址,并在其全局数据目录下为每个远程和分支存储一个检出副本。若未显式指定分支,路径结构如下:
opencode/repos/
在典型的 Linux 安装环境中,Effect-TS/effect 存储于: ~/.local/share/opencode/repos/github.com/Effect-TS/effect
显式指定分支时,路径末尾会增加带编码的 @
缺失的仓库将异步克隆。当 references 加载或重新加载时,以及新的用户提示被 Location 接纳后,现有检出会在后台进行检查。 提示被接纳 → 后台开始刷新检查 → 智能体继续运行
满足以下任一条件时,检出即可更新:上次刷新尝试至少发生在 24 小时前,或未记录任何尝试。刷新操作会获取并重置到配置的分支或远程默认分支。 上次尝试:25 小时前 → 符合更新条件 上次尝试:2 小时前 → 跳过
刷新行为遵循以下规则:
- 时间戳在的服务重启后持久保存。 - 使用相同检出的 Location 共享其时间戳。 - 失败的尝试会被记录,并受 24 小时限制约束。 - Location 未使用时没有定期轮询。 - 克隆或刷新失败不会阻止其他 references 加载。
提示不会等待克隆或刷新完成。即使后续工具读取看到了更新的检出,附加内容仍可能包含较旧数据;新 reference 也可能在其检出准备就绪前出现。 创建附加 → 缓存内容 后台刷新完成 → 后续工具读取看到新内容
description 字段告知智能体何时使用某个 reference。带有 description 的 references 会在智能体指令中显示其别名和解析后的路径。 JSONC { "references": { "docs": { "path": "../docs", "description": "用于产品行为和术语说明" } } }
没有 description 的 references 对客户端仍可用,但不会自动通告。 JSONC { "references": { "archive": { "path": "../archive" } } }
设置 hidden 为 true 可从交互式客户端选择器中移除该 reference: JSONC { "references": { "internal": { "path": "../internal", "description": "用于内部服务行为", "hidden": true } } }
hidden 仅影响交互式可见性。该 reference 仍存在于 reference API 中,且若有 description,也会出现在智能体指令中。
客户端通过根别名附加 reference。附加内容包含根目录下直接文件和目录的非递归列表。 附加别名:docs 提问:"检查 docs/guides/deployment.md 并解释部署步骤。"
若需访问根目录之下的内容,请指示智能体检查特定路径。
References 不会授予额外的工具权限。访问活动 Location 之外的路径仍遵循常规工具规则和 external_directory 权限;编辑操作还需具备相应的编辑权限。 读取 ../product-docs/api.md 仅当活动权限允许该外部读取时,请求才会成功。
字段 | 本地 | Git | 描述 path | 必需 | 否 | 本地目录路径 repository | 否 | 必需 | 远程 Git 仓库 branch | 否 | 可选 | 要获取和检出的分支 description | 可选 | 可选 | 描述智能体何时应使用的指导 hidden | 可选 | 可选 | 从交互式客户端选择器中隐藏
完整的 Git 条目可使用所有兼容 Git 的字段: JSONC { "references": { "sdk": { "repository": "example/sdk", "branch": "main", "description": "用于 SDK 实现细节", "hidden": false } } }
别名不能为空,且不得包含 /、\、空白符、反引号或逗号。 有效:docs 无效:product docs 无效:docs/api