# 引用

> 这是 OpenCode V1 的文档。最新的 OpenCode V2 文档位于 https://opencode.ai/docs/llms.txt。

引用让 OpenCode 可以访问当前项目之外的目录。你可以用它在工作时提供文档、共享库、示例或其他仓库。

引用在 `opencode.json` 或 `opencode.jsonc` 中按别名配置。

```jsonc title="opencode.jsonc"
{
  "$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",
    },
  },
}
```

---

## 本地目录

使用 `path` 引用本地目录。

```jsonc title="opencode.jsonc"
{
  "references": {
    "docs": {
      "path": "../docs",
    },
  },
}
```

路径可以是：

- 相对于定义该引用的配置文件的路径
- 绝对路径，例如 `/home/user/docs`
- 相对于主目录的路径，例如 `~/docs`

你也可以使用字符串简写：

```jsonc title="opencode.jsonc"
{
  "references": {
    "docs": "../docs",
  },
}
```

---

## Git 仓库

使用 `repository` 引用 Git 仓库。OpenCode 会将该仓库放入本地仓库缓存中，并将检出的源代码作为引用目录提供。

```jsonc title="opencode.jsonc"
{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
    },
  },
}
```

`repository` 接受 Git URL、host/path 形式的引用以及 GitHub `owner/repo` 简写。可选的 `branch` 字段用于选择分支或 ref。未设置 `branch` 时，OpenCode 使用仓库的默认分支。

如果不需要指定分支、描述或其他选项，可以使用字符串简写：

```jsonc title="opencode.jsonc"
{
  "references": {
    "effect": "Effect-TS/effect",
  },
}
```

:::note
Git 引用会异步刷新。新配置的仓库可能需要一点时间才能完成克隆或更新。
:::

---

## 描述用途

添加 `description` 来说明代理应在何时使用某个引用。

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

OpenCode 会将带有描述的引用加入代理上下文。描述应简短、具体，足以区分内容相似的引用。没有描述的引用仍可通过自动补全和直接使用来访问，但不会告知代理。

---

## 隐藏自动补全条目

将 `hidden` 设置为 `true`，即可在 TUI 的 `@` 自动补全中隐藏某个引用。

```jsonc title="opencode.jsonc"
{
  "references": {
    "internal": {
      "path": "../internal",
      "description": "Use for internal implementation details",
      "hidden": true,
    },
  },
}
```

`hidden` 只影响自动补全。带有描述的隐藏引用仍会包含在代理上下文中。

---

## 使用引用

已配置的引用会出现在 TUI 的 `@` 自动补全中。输入 `@alias` 可附加引用的根目录，输入 `@alias/` 可搜索其中的文件。

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

对于带有描述的已配置引用，代理还会在系统上下文中收到它们的解析路径和描述，因此在相关时可以自行查看引用，无需你手动附加。

OpenCode 会自动允许引用目录通过其外部目录权限边界。常规的工具权限仍然适用；例如，无法编辑文件的代理不会因为某个目录被配置为引用而获得编辑权限。

---

## 配置字段

| 字段          | 本地 | Git | 说明                                         |
| ------------- | ---- | --- | -------------------------------------------- |
| `path`        | 是   | 否  | 本地引用目录                                 |
| `repository`  | 否   | 是  | Git URL、host/path 或 GitHub `owner/repo` 值 |
| `branch`      | 否   | 是  | 可选的 Git 分支或 ref                        |
| `description` | 是   | 是  | 说明何时使用该引用的指引                     |
| `hidden`      | 是   | 是  | 在 TUI 的 `@` 自动补全中隐藏该引用           |

引用别名不能为空，也不能包含 `/`、空白字符、反引号或逗号。