# Руководство по установке (официальная CLI DSH)

> ✅ **Возрождён как 0.3.0 (2026-10-05).** Это руководство охватывает возрождённый перехват транспорта — динамическая совместимость со всеми rc от `0.1.0-rc.8` до `0.2.1-rc.4`.

Это руководство использует только официальную команду `dsh plugin` DSH.

Руководства по установке: [EN](./INSTALL.md) · [中文](./INSTALL.zh.md) · [日本語](./INSTALL.ja.md) · [한국어](./INSTALL.ko.md) · [DE](./INSTALL.de.md) · [ES](./INSTALL.es.md) · [FR](./INSTALL.fr.md) · [IT](./INSTALL.it.md) · RU

README: [EN](./README.md) · [中文](./README.zh.md) · [日本語](./README.ja.md) · [한국어](./README.ko.md) · [DE](./README.de.md) · [ES](./README.es.md) · [FR](./README.fr.md) · [IT](./README.it.md) · [RU](./README.ru.md)

## 1. Установка

```bash
# npm (рекомендуется)
dsh plugin --profile web add dsh-llm-openai-completions -w
# локальный tgz (офлайн / предварительные сборки)
dsh plugin --profile web add /путь/к/dsh-llm-openai-completions-0.3.0.tgz -w
dsh web
```

В DSH Desktop: **Плагины → Добавить плагин → вставить имя npm, URL GitHub или абсолютный локальный путь** (префикс `file:` копирует; голый путь линкует), затем включить и полностью перезапустить десктоп-приложение.

## 2. Проверка установки

Проверьте композицию:

```bash
dsh --profile web --dump-default-config
```

Она должна содержать `llm-openai-completions` в собранном дереве. После загрузки строка журнала `[llm-openai-completions] short-circuit listener registered (prepend+global)` подтверждает, что слушатель каскада на месте.

## 3. Включить

Переключатель живёт в собственном разделе настроек плагина (по умолчанию **выкл** — ничего не захватывается, пока вы его не перебросите):

```yaml
# ~/.dsh/profiles/web/cordis.patch.yml (или Настройки → Плагины → dsh-llm-openai-completions)
llm-openai-completions:
  enabled: true
  providers:        # необязательный ручной список поверх автоопознанного набора
    - local-35b
```

Маршруты попадают в список захвата через галочку по маршруту в панели моделей dsh-thinking-levels (она пишет `providers` напрямую) или правкой списка вручную; переключатель `takeover` там зеркалится в `enabled` при переключении.

## 4. Устранение неполадок

| Симптом | Действие |
| --- | --- |
| `dsh` не найден | Установите или включите официальную CLI DSH. |
| Плагин показывается как «отключён» | Проверьте композицию профиля. |
| `MISSING_CREDENTIAL` | Сохраните ссылку `apiKeyEnv` маршрута через сервис учётных данных (страница Моделей в вебе пишет туда) или экспортируйте в среде запуска. |
| `does not declare "<модальность>" input` | Жёсткий шлюз модальностей отверг вложение, которое модель не декларирует — добавьте модальность в `input` модели в llm-pi-ai или смените модель. |
| Пользовательский шлюз возвращает `Unexpected message role` | Убедитесь, что маршрут действительно захвачен (`enabled: true` и маршрут опознан или в списке). |
| Текст thinking смешивается с телом | Проверьте, что `compat.thinkingFormat` настроен правильно для вашей модели. |

## 5. Удаление

```bash
dsh plugin --profile web remove dsh-llm-openai-completions
```

После этого перезапустите DSH — pi-ai обслуживает каждый маршрут без изменений (никакой регистрации адаптера, которую нужно раскручивать).