OpenCode References 功能详解：让 AI 助手轻松看懂你的其他项目

你在用 OpenCode 写代码时，有没有遇到过这种情况：项目 A 需要参考项目 B 的设计规范，或者想让 AI 助手看懂公司内部的 SDK 实现？这时候，OpenCode 的 References 功能就派上用场了。

简单说，References 就是给 OpenCode 开一个"后门"，让它能访问当前项目之外的目录。不管是本地的文档文件夹，还是远端的 Git 仓库，都能变成 AI 助手的参考资料。

怎么配置

配置很简单，在项目根目录的 opencode.json 或 opencode.jsonc 里加个 references 字段就行。

引用本地目录

用 path 字段指定本地目录路径：

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

路径支持三种写法：

• 相对路径：相对于配置文件所在位置，比如 ../docs
• 绝对路径：比如 /home/user/docs
• Home 目录相对路径：比如 ~/docs

如果只是简单引用，可以用字符串简写：

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

引用 Git 仓库

用 repository 字段指定 Git 仓库。OpenCode 会把仓库克隆到本地缓存，然后像本地目录一样使用：

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

repository 字段很灵活，支持：

• Git URL：https://github.com/user/repo.git
• host/path 格式：github.com:user/repo
• GitHub 简写：user/repo

branch 是可选的，不填就用仓库默认分支。

同样，简单场景可以简写：

{
  "references": {
    "effect": "Effect-TS/effect",
  },
}

有一点要注意：Git 仓库是异步刷新的，新加的仓库可能需要等一会儿才能用。

高级玩法

给引用加说明

你可以给每个引用加个 description，告诉 AI 助手什么时候该用这个引用：

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

加了描述的引用会进入 AI 助手的上下文，它能根据你的问题自动判断要不要参考这些资料。没加描述的引用也能用，只是 AI 不会主动推荐。

描述写得简短具体就行，尤其是有多个相似引用时，能区分开就好。

从自动补全中隐藏

有些内部实现细节，你可能不想在自动补全列表里看到，但又想让 AI 能访问。这时候加个 hidden: true：

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

hidden 只影响 TUI 的自动补全列表，AI 助手照样能看到这个引用。

在 TUI 里怎么用

配置好之后，在 OpenCode 的终端界面里，输入 @ 就能看到所有引用的自动补全：

• @docs — 引用 docs 目录的根路径
• @docs/ — 搜索 docs 目录下的文件

比如你想让 AI 对比某个实现，可以说：

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

即使你不手动 @，AI 助手也能自动访问那些有描述的引用。它会根据上下文判断是否需要查看这些资料。

权限机制

引用目录会自动通过 OpenCode 的外部目录权限边界，但不会获得额外权限。比如一个没有编辑权限的 agent，不会因为你把某个目录设为引用就突然能编辑那里的文件了。

配置字段速查

最后提醒一下：引用的别名不能包含 /、空白字符、反引号或逗号，起名字的时候注意避开就好。