# Ссылки

> Это документация 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`      | Нет       | Да  | Необязательная ветка или ref Git                    |
| `description` | Да        | Да  | Подсказка о том, когда использовать ссылку          |
| `hidden`      | Да        | Да  | Скрывает ссылку из автодополнения `@` в TUI         |

Псевдонимы ссылок не могут быть пустыми или содержать `/`, пробельные символы, обратные кавычки или запятые.