OpenCode References 完全指南：用引用系统打通多项目知识库

OpenCode References 完全指南：用引用系统打通多项目知识库

在开发大型项目或微服务架构时，代码往往分散在多个仓库或目录中。你正在修改前端，却需要参考后端 API 的定义；你在写一个新的服务，却要复用另一个项目的工具函数。传统做法是打开多个终端窗口来回切换，或者手动复制代码片段。

OpenCode 的 References（引用系统）解决了这个问题。它允许你将项目外部的目录或 Git 仓库「挂载」到当前会话中，让 AI 助手在推理时自动读取这些外部代码，无需你手动切换上下文。

本文将全面介绍 OpenCode References 的配置方式、使用场景和高级技巧，帮助你彻底打通多项目知识库。

什么是 References？

References 是 OpenCode 提供的一种跨项目上下文机制。通过它，你可以：

• 引用本地其他目录（如共享库、文档目录）
• 引用远程 Git 仓库（自动克隆并缓存到本地）
• 为每个引用添加描述，让 AI 自主判断何时使用
• 通过 @ 快捷键快速搜索引用中的文件

配置在 opencode.json 或 opencode.jsonc 的 references 字段中，按别名组织：

{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use for product behavior and documentation conventions",
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "Use for JavaScript SDK implementation details",
    },
  },
}

配置完成后，你可以在 TUI 中用 @docs 或 @sdk 快速引用这些外部资源。

引用本地目录

本地目录是最常用的引用类型。使用 path 字段指向需要引用的目录路径：

{
  "references": {
    "shared-lib": {
      "path": "../shared-library/src",
      "description": "Use for shared utility functions and types",
    },
  },
}

路径支持三种写法：

• 相对路径：相对于 opencode.json 所在目录，如 ../docs
• 绝对路径：/home/user/projects/shared-lib
• 家目录路径：~/projects/shared-lib

如果不需要额外配置，还可以使用字符串简写：

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

OpenCode 会自动将引用目录加入外部目录白名单，无需额外配置权限。

实战场景：引用组件库

假设你正在开发主应用，同时维护一个独立的组件库：

{
  "references": {
    "ui-kit": {
      "path": "../ui-kit/src",
      "description": "Use when implementing UI components or matching existing design patterns",
    },
  },
}

此时在 TUI 中输入指令：

参考 @ui-kit/src/components/Button.tsx 的样式，在项目中创建一个新的 Card 组件

AI 助手会自动读取 Button.tsx 的代码风格、样式方案，然后以一致的模式生成 Card 组件。

引用 Git 仓库

References 支持直接引用远程 Git 仓库，OpenCode 会自动克隆并维护本地缓存。使用 repository 字段指定仓库地址：

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

repository 支持多种格式：

• GitHub owner/repo 简写：anomalyco/opencode
• 完整 Git URL：https://github.com/anomalyco/opencode.git
• SSH 地址：git@github.com:anomalyco/opencode.git

branch 字段可选，不指定时使用仓库的默认分支。

简写形式同样支持：

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

工作原理

当 OpenCode 启动时遇到 Git 引用，它会：

检查本地缓存中是否已有该仓库

如果没有，则自动执行 git clone

如果已有，异步执行 git fetch 保持更新

将仓库根目录挂载为可读的引用目录

注意：首次克隆需要网络连接，且大型仓库可能需要一些时间完成。Git 引用是异步刷新的，新配置的仓库可能需要片刻才能使用。

实战场景：引用框架源码

调试 Laravel 应用时，直接引用源码仓库：

{
  "references": {
    "laravel": {
      "repository": "laravel/framework",
      "branch": "11.x",
      "description": "Use when debugging Laravel framework internals or checking API signatures",
    },
  },
}

提问时自动关联：

查询 @laravel 中 Illuminate\\Support\\Facades\\Route 的实现，看看 facade 是如何代理方法的

AI 助手将直接读取 Laravel 框架源码给出精确回答。

描述让引用更智能

description 字段是一个被低估但极其重要的配置。它告诉 AI 助手「什么时候该用这个引用」：

{
  "references": {
    "design-system": {
      "path": "../design-system",
      "description": "Use when implementing UI components or design tokens",
    },
    "api-spec": {
      "path": "../api-spec",
      "description": "Use when implementing API clients or understanding endpoint behavior",
    },
    "db-migrations": {
      "path": "../database/migrations",
      "description": "Use when modifying database schema or writing queries",
    },
  },
}

关键行为：带有 description 的引用会被自动注入到 AI 助手的系统上下文中。这意味着即使你不手动 @ 引用，AI 也可能根据描述自主决定读取相关文件。没有 description 的引用只会在你主动 @ 使用时才被访问。

因此，建议为所有引用编写简短、具体的描述，让 AI 在恰当的时机主动利用这些外部知识。

隐藏引用

如果某个引用你希望 AI 能自主访问，但不想在 @ 自动补全列表中显示，可以设置 hidden: true：

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

hidden 只影响 TUI 中的 @ 自动补全列表。只要该引用有 description，AI 助手仍然能在推理时自动访问它。这适用于那些「AI 应该知道但不希望手动输入时干扰补全」的引用。

在对话中使用 References

配置完成后，在 TUI 中有两种使用方式：

1. 手动引用（@ 自动补全）

键入 @ 后，OpenCode 会弹出引用列表。选择一个引用后：

• @alias — 引用根目录
• @alias/ — 进入引用目录的下一级搜索

在提示词中使用：

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

AI 助手会将 @sdk/src/client.ts 的完整内容纳入上下文。

2. 自动上下文注入（带 description 的引用）

AI 助手自主决定何时读取引用中的文件。例如你问：

我需要添加一个新 API 路由来获取用户的订单历史

如果引用了 API 规范和数据库迁移目录，AI 主动读取相关文件后，可能会回答：

根据 @api-spec 中定义的订单接口规范，以及 @db-migrations 中的 orders 表结构，这是实现方案：

这种自动行为大幅减少了手动查找和切换的工作量。

配置字段汇总

| 字段 | 本地引用 | Git 引用 | 说明 |
|------|---------|---------|------|
| path | 是 | 否 | 本地目录路径 |
| repository | 否 | 是 | 仓库地址（URL 或 owner/repo） |
| branch | 否 | 是 | Git 分支或标签 |
| description | 是 | 是 | 使用场景描述 |
| hidden | 是 | 是 | 是否在 @ 补全中隐藏 |

别名限制：引用别名不能为空，且不能包含 /、空格、反引号或逗号。

权限说明

References 涉及外部目录访问，OpenCode 的处理方式值得注意：

• 引用目录被自动加入外部目录白名单，无需单独配置权限规则
• 但常规工具权限规则仍然适用。例如，如果某个 agent 的 allow 规则禁止了 write 操作，即使引用了外部目录，该 agent 也不能修改其中的文件
• Read 操作默认允许，因为 References 的设计初衷就是提供只读的上下文

进阶实践：多项目开发工作流

场景一：微服务联调

假设你在开发一个电商平台，包含 gateway、user-service、order-service、product-service 四个仓库：

{
  "references": {
    "gateway": { "path": "../gateway", "description": "API gateway routes and middleware" },
    "user-svc": { "path": "../user-service", "description": "User service models and handlers" },
    "order-svc": { "path": "../order-service", "description": "Order service logic and DB schema" },
    "product-svc": { "path": "../product-service", "description": "Product catalog and inventory logic" },
  },
}

当你修改 gateway 的路由时，可以直接引用 user-svc 和 order-svc 的类型定义，确保请求和响应类型一致。

场景二：Monorepo 中的包管理

对于使用 turborepo 或 nx 管理的 monorepo：

{
  "references": {
    "ui": { "path": "packages/ui/src", "description": "Shared UI components" },
    "utils": { "path": "packages/utils/src", "description": "Shared utility functions" },
    "types": { "path": "packages/types/src", "description": "Shared TypeScript type definitions" },
  },
}

引用 monorepo 内部包时，path 使用项目内相对路径即可。

场景三：参考开源项目

{
  "references": {
    "nextjs": { "repository": "vercel/next.js", "branch": "canary" },
    "trpc": { "repository": "trpc/trpc", "branch": "main" },
    "prisma": { "repository": "prisma/prisma", "branch": "main" },
  },
}

在实现某个功能时，参考知名项目的源码实现，AI 能给出更符合行业最佳实践的建议。

总结

OpenCode References 是一个简单但极其强大的功能。它打破了单项目上下文的限制，让 AI 助手能够跨目录、跨仓库地理解你的整个技术栈。合理配置 References，配合精确的 description，可以让 AI 在需要时自动调用外部知识，大幅减少手动切换上下文的成本。

配置建议：

• 优先用 description：为每个引用写清晰的使用场景描述
• 善用 Git 引用：引用框架源码或依赖库，调试时极为有用
• 注意权限边界：References 只解决「读到」的问题，写入仍受 agent 权限规则控制
• 合理控制数量：引用过多会增大 AI 上下文，建议控制在 5-8 个以内

在下一篇系列文章中，我们将探讨如何使用 OpenCode 的 LSP 集成来进一步提升 AI 助手的代码理解能力。