Ссылки

Ссылки дают OpenCode доступ к каталогам за пределами текущего проекта. С их помощью во время работы можно подключить документацию, общие библиотеки, примеры или другой репозиторий.

Ссылки настраиваются по псевдониму в opencode.json или 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, чтобы сослаться на локальный каталог.

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

Пути могут быть:

• Относительными к файлу конфигурации, в котором определена ссылка
• Абсолютными, например /home/user/docs
• Относительными к домашнему каталогу, например ~/docs

Также можно использовать сокращенную запись в виде строки:

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

Git-репозитории

Используйте repository, чтобы сослаться на Git-репозиторий. OpenCode загружает репозиторий в свой локальный кэш репозиториев и делает извлеченный исходный код доступным как каталог ссылки.

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

repository принимает Git URL, ссылки вида host/path и сокращенную запись GitHub owner/repo. Необязательное поле branch выбирает ветку или ref. Без branch OpenCode использует ветку репозитория по умолчанию.

Сокращенную запись в виде строки можно использовать, если не нужны ветка, описание или другие параметры:

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

Описание назначения

Добавьте description, чтобы объяснить, когда агенту следует использовать ссылку.

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

OpenCode добавляет ссылки с описаниями в контекст агента. Описания должны быть краткими и достаточно конкретными, чтобы различать ссылки с похожим содержимым. Ссылки без описаний остаются доступными через автодополнение и при прямом использовании, но агентам не предлагаются.

Скрытие из автодополнения

Установите для hidden значение true, чтобы исключить ссылку из автодополнения @ в TUI.

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

hidden влияет только на автодополнение. Скрытая ссылка с описанием по-прежнему включается в контекст агента.

Использование ссылок

Настроенные ссылки появляются в автодополнении @ в TUI. Введите @alias, чтобы прикрепить корневой каталог ссылки, или @alias/, чтобы искать файлы внутри него.

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

Агенты также получают в системном контексте разрешенные пути и описания настроенных ссылок, у которых есть описания, поэтому они могут изучить ссылку, когда это уместно, без ручного прикрепления с вашей стороны.

OpenCode автоматически пропускает каталоги ссылок через границу разрешений для внешних каталогов. Обычные разрешения инструментов по-прежнему действуют: например, агент, которому нельзя редактировать файлы, не получает доступ на редактирование только потому, что каталог настроен как ссылка.

Поля конфигурации

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