Ссылки

Ссылки дают ZubrCode доступ по имени к каталогам вне текущего проекта: документация, общие библиотеки, примеры, код другого репозитория. Опишите ссылку в opencode.json или opencode.jsonc, затем приложите её по имени, когда она понадобится.

opencode.jsonc

{
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use for product behavior and terminology"
    }
  }
}

После прикладывания docs попросите агента открыть нужный путь:

Прочитай приложенную ссылку docs и сделай резюме api/authentication.md.

Локальный каталог

path — локальный каталог: относительный путь считается от каталога файла конфигурации, поддерживаются абсолютные пути и ~/…. Короткая запись — просто строкой, когда других полей не нужно:

{
  "references": {
    "docs": "../docs",
    "shared": "~/work/shared"
  }
}

Заметка

Короткая строка — локальный путь, только если начинается с ., / или ~. Пишите ./docs, а не docs: голое docs трактуется как git-репозиторий.

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

repository — удалённый git-репозиторий; поддерживаются сокращение владелец/репозиторий, git-URL, формы хост/путь и scp-подобные адреса. Локальные file:-репозитории не поддерживаются. Без branch берётся ветка по умолчанию удалённого репозитория:

{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main"
    },
    "internal-sdk": {
      "repository": "git@gitlab.example.com:platform/sdk.git",
      "branch": "release/v2"
    }
  }
}

Хранение и обновление

Для каждого удалённого репозитория и ветки хранится одна рабочая копия в каталоге данных (zubrcode debug paths repos). Отсутствующие репозитории клонируются в фоне; существующие проверяются при загрузке ссылок и после новых запросов — не чаще, чем раз в 24 часа, — и сбрасываются на настроенную ветку. Запросы не ждут клонирования: вложение может содержать более старое содержимое, чем прочтённый позже файл.

Осторожно

Кешированные копии общие и могут обновиться во время работы агента: не правьте их — обновление сбросит изменения.

Подсказка и видимость

description рассказывает агентам, когда ссылка уместна: ссылки с описанием появляются в инструкциях агента вместе с именем и путём. Без описания ссылка доступна клиентам, но не рекламируется автоматически. hidden: true прячет ссылку из интерактивных выборщиков, но оставляет её в API и инструкциях.

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

Клиент прикладывает ссылку по её имени; вложение содержит нерекурсивный список файлов и каталогов корня. Нужен контент ниже корня — попросите агента открыть конкретный путь.

Ссылки не дают дополнительных разрешений: доступ вне проекта идёт по обычным правилам и external_directory, а для правки нужно ещё и разрешение edit (Разрешения).

Поля

Поле	Локальная	Git	Описание
path	обязательно	нет	путь к локальному каталогу
repository	нет	обязательно	удалённый git-репозиторий
branch	нет	необязательно	ветка для получения и переключения
description	необязательно	необязательно	подсказка, когда ссылкой пользоваться
hidden	необязательно	необязательно	скрыть из интерактивных выборщиков

Имя ссылки не может быть пустым или содержать /, \, пробелы, обратную кавычку и запятую: docs — допустимо, product docs и docs/api — нет.