Ссылки

Добавляйте локальные директории и Git-репозитории как ссылки проекта.

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

Ссылки настраиваются по псевдониму (alias) в 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",
  },
}

Примечание: Git-ссылки обновляются асинхронно. Только что настроенному репозиторию может потребоваться время для завершения клонирования или обновления.

Описание использования

Добавьте 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 автоматически разрешает директории-ссылки через границу разрешения на внешние директории. Обычные разрешения инструментов по-прежнему применяются; например, агент, который не может редактировать файлы, не получает доступ на редактирование только потому, что директория настроена как ссылка.

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

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