# Расширение dbt Wizard с помощью плагинов и хуков

Используйте плагины, чтобы устанавливать согласованные наборы расширений dbt Wizard CLI из маркетплейса. Плагин может объединять навыки, серверы Model Context Protocol (MCP), приложения и хуки жизненного цикла, позволяя команде распространять все компоненты рабочего процесса вместе.

Плагины и хуки доступны в интерактивных сеансах dbt Wizard CLI. Их нельзя установить в Studio IDE или на главной вкладке dbt Wizard.

## Основные понятия: плагины, маркетплейсы и хуки

* **Маркетплейс** — это локальный источник или Git-репозиторий, в котором опубликован один или несколько плагинов.
* **Плагин** — это именованный набор компонентов с манифестом `.dbt-wizard-plugin/plugin.json`.
* **Хук** запускает команду при событии жизненного цикла dbt Wizard, например при запуске сеанса, отправке запроса, до или после вызова инструмента, при запросе разрешения или завершении сеанса.

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

## Добавление маркетплейса

Добавьте маркетплейс из репозитория GitHub:

```bash
wizard plugin marketplace add OWNER/REPOSITORY --ref main
```

Вы также можете добавить локальный маркетплейс при его разработке или оценке:

```bash
wizard plugin marketplace add ./path/to/marketplace
```

Для репозитория, в котором маркетплейс расположен в подкаталоге, укажите путь для выборочного извлечения (sparse checkout):

```bash
wizard plugin marketplace add \
  https://github.com/OWNER/REPOSITORY \
  --sparse path/to/plugins
```

Выведите список настроенных источников и расположений их локальных снимков:

```bash
wizard plugin marketplace list
```

Перед установкой плагина проверьте снимок маркетплейса и файл `.dbt-wizard-plugin/plugin.json` плагина. Изучите все указанные в нём навыки, конфигурации серверов MCP, приложения, файлы хуков и исполняемые скрипты.

Используйте `wizard plugin --help`, чтобы просмотреть остальные команды управления плагинами в dbt Wizard CLI.

## Установка и проверка плагина

Выведите список доступных плагинов и сведения об их установке:

```bash
wizard plugin list
```

Установите плагин по его идентификатору `PLUGIN@MARKETPLACE`:

```bash
wizard plugin add PLUGIN_NAME@MARKETPLACE_NAME
```

Эквивалентная полная форма команды:

```bash
wizard plugin add PLUGIN_NAME --marketplace MARKETPLACE_NAME
```

После установки начните новый интерактивный сеанс. Используйте `/plugins` для просмотра загруженных плагинов. Если плагин объявляет хуки, используйте `/hooks`, чтобы проверить обработчики и их статус доверия, прежде чем разрешать их запуск.

Проверяйте хуки, прежде чем доверять им

Не используйте `--dangerously-bypass-hook-trust` как стандартный шаг настройки. Этот параметр позволяет включённым хукам запускаться без сохранённого подтверждения проверки при текущем запуске. Вместо этого проверяйте каждый хук и сохраняйте решение о доверии к нему.

## Проверка расширения

После установки проверяйте возможности по одной:

1. Убедитесь, что плагин установлен и включён, с помощью `wizard plugin list`.
2. Начните новый сеанс, чтобы dbt Wizard заново загрузил плагины и навыки.
3. Проверьте `/plugins` и `/hooks` на наличие предупреждений о загрузке или обработчиков хуков, которым ещё не предоставлено доверие.
4. Попросите dbt Wizard перечислить навыки или возможности MCP, которые должен предоставлять плагин.
5. Выполните запрос, использующий эту возможность только для чтения, прежде чем предоставлять доступ на запись или более широкие разрешения на использование инструментов.

Если плагин включает сервер MCP, его инструменты по-прежнему подчиняются [настройкам разрешений MCP](https://docs.getdbt.tech/docs/dbt-ai/wizard-mcp.md#approvals-and-tool-permissions). Плагин не обходит изолированную среду CLI или политику разрешений на использование инструментов.

## Обновление или удаление расширения

Обновите один из настроенных Git-маркетплейсов:

```bash
wizard plugin marketplace upgrade MARKETPLACE_NAME
```

Не указывайте имя, чтобы обновить все настроенные Git-маркетплейсы:

```bash
wizard plugin marketplace upgrade
```

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

Удалите плагин, когда он больше не нужен:

```bash
wizard plugin remove PLUGIN_NAME@MARKETPLACE_NAME
```

Отдельно удалите источник маркетплейса:

```bash
wizard plugin marketplace remove MARKETPLACE_NAME
```

Удаление маркетплейса и удаление установленного плагина — это отдельные операции. После очистки выведите оба списка, чтобы убедиться, что достигнуто нужное состояние.

## Выбор минимально необходимого механизма расширения

Используйте плагин, когда несколько возможностей нужно устанавливать и версионировать вместе. Для отдельной задачи проще проверить расширение меньшего масштаба:

| Потребность                                                                | Что использовать                                                                               |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Многократно используемые инструкции для команды                            | Проектный [навык](https://docs.getdbt.tech/docs/dbt-ai/wizard-skills.md) в `.agents/skills/`. |
| Инструменты из другого сервиса                                             | Настроенный [сервер MCP](https://docs.getdbt.tech/docs/dbt-ai/wizard-mcp.md).                 |
| Команда, запускаемая при событии жизненного цикла                          | Хук, распространяемый только из источника, которому доверяет ваша команда.                     |
| Навыки, инструменты, приложения и хуки, которые должны поставляться вместе | Плагин из проверенного маркетплейса.                                                           |

## Связанная документация

* [Использование навыков в dbt Wizard CLI](https://docs.getdbt.tech/docs/dbt-ai/wizard-skills.md)
* [Использование серверов MCP в dbt Wizard CLI](https://docs.getdbt.tech/docs/dbt-ai/wizard-mcp.md)
* [Разрешения и изолированная среда](https://docs.getdbt.tech/docs/dbt-ai/wizard-how-it-works.md#approval-and-sandboxing)
* [Справочник команд dbt Wizard](https://docs.getdbt.tech/docs/dbt-ai/wizard-cli-reference.md)