dsh-image-format-converter

Readme

# dsh-vision-fix-lmstudio

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![DSH](https://img.shields.io/badge/DSH-0.1.2--rc.1%2B-brightgreen)](https://github.com/deepseek-ai/deepseek-harness)
[![Platform](https://img.shields.io/badge/platform-win%20%7C%20linux%20%7C%20macOS-lightgrey)]()

**Починка ошибки `400: 'url' field must be a base64 encoded image`** при работе с локальными
vision-моделями в LM Studio из DeepSeek Harness Desktop.

Плагин конвертирует изображения, отправляемые в модель, в подходящий формат — **на лету, до
того как запрос уйдёт в провайдер**. Просто отметьте галочками модели, для которых конвертация
включена, и нажмите «отправить».

---

## 🎯 Какую проблему решает

LM Studio и большинство локальных vision-моделей ожидают изображения в **JPEG** и падают с
ошибкой `400: 'url' field must be a base64 encoded image` при попытке отправить WebP.

Облачные провайдеры (OpenAI, Anthropic, DeepSeek и др.) — наоборот, часто принимают только
**WebP** или PNG, и отправка JPEG в них приводит к ошибке или заметной потере качества.

До этого плагина приходилось выбирать что-то одно:

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

Теперь — один раз настроили галочки в UI DSH, и забыли.

---

## 📦 Установка

### Через DSH CLI

```bash
dsh plugin --profile web add github:MORIC/dsh-vision-fix-lmstudio
```

### Через магазин плагинов

Откройте **DSH Desktop → Настройки → Плагины** (или «Магазин плагинов»), найдите
**«Формат изображений»** и нажмите «Установить».

### Вручную

Склонируйте репозиторий и добавьте его как плагин:

```bash
git clone https://github.com/MORIC/dsh-vision-fix-lmstudio.git
cd dsh-vision-fix-lmstudio
pnpm install
pnpm build
dsh plugin --profile web add .
```

---

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

1. Откройте **DSH → Настройки → Формат изображений**.
2. Появится список всех ваших провайдеров и моделей, сгруппированный по провайдеру.
3. Поставьте галочки напротив моделей, которые **должны получать сконвертированные картинки**.
   Модели без галочки получают изображения в исходном формате.
4. Настройки применяются автоматически — ничего нажимать не нужно, справа снизу появится
   «Сохранено».

### Быстрые действия

- **Кнопки «Вкл / Выкл» у каждого провайдера** — массово включить или отключить все модели
  одного провайдера одним кликом.
- **Поиск** — фильтр по имени провайдера или модели. Полезно, когда моделей десятки.
- **«Дополнительные шаблоны»** — ручной список wildcard-масок для случаев, когда нужной
  модели ещё нет в списке (или вы хотите отключить целого провайдера разом):

  ```
  lmstudio/*
  openai/gpt-4-vision-preview
  ```

  Строка, начинающаяся с `#`, игнорируется.

---

## 🔧 Тонкая настройка

Все параметры конвертации задаются в `cordis.patch.yml` в корне пакета и применяются
ко всем моделям, для которых включена конвертация:

```yaml
- insert:
    - id: image-format-converter
      name: 'dsh-image-format-converter'
      config:
        targetFormat: jpeg       # jpeg | png | webp
        jpegQuality: 90          # 1..100
        pngCompression: 6        # 0..9
        webpQuality: 85          # 1..100
        convertOversized: true   # уменьшать ли слишком большие картинки
        maxDimension: 2048       # максимальная сторона, px
```

Чтобы изменить — поправьте `cordis.patch.yml` и перезапустите DSH.

> **Скоро**: выбор формата в самом UI, без правки yml. Следите за обновлениями.

---

## 🖥️ Требования

| Компонент | Версия |
|---|---|
| DeepSeek Harness | `0.1.2-rc.1` или новее |
| Node.js | ≥ 20 |
| DSH Desktop | `2.0.5`+ (если используете десктоп-версию) |
| ОС | Windows 10/11, Linux, macOS |

**`sharp`** (используется для конвертации) устанавливается автоматически с пре-собранными
бинарниками для всех популярных платформ. Если установка падает на этапе сборки — см.
[документацию sharp](https://sharp.pixelplumbing.com/install).

---

## 🩺 Диагностика

### Плагин не появился в настройках

Откройте **F12 → Console** в окне DSH и посмотрите на ошибки. Также проверьте, что при
запуске DSH в его логах есть строка:

```
[image-format-converter] Активен; target=jpeg; excluded=0
```

### Список моделей пустой

Проверьте прямой запрос к роуту плагина (порт DSH виден в адресной строке браузера):

```
http://127.0.0.1:<port>/image-format-converter/models
```

Если ответ `{"providers":[],"warning":"…"}` — пришлите текст `warning` в
[Issues](https://github.com/MORIC/dsh-vision-fix-lmstudio/issues): там будет видно,
какой именно метод `llm` не отвечает на вашей версии DSH.

### Картинки не конвертируются

В логах хоста DSH при отправке сообщения с картинкой должны пробегать строки:

```
[image-format-converter] image/webp → image/jpeg (234567 → 89123 байт)
[image-format-converter] lmstudio/… в списке исключений — пропускаем
```

Если строк нет — значит либо модель без галочки (проверьте UI), либо `excludedModels`
пуст (т.е. всё включено). Если строка есть, но в LM Studio всё равно ошибка — пришлите
содержимое строки в Issues.

---

## 🤝 Совместимость с другими плагинами

- **`dsh-plugin-wallpaper-engine`** — работает независимо, конфликтов нет.
- **Любые другие `llm/stream`-хуки** — плагин защищён от повторной обработки одного
  запроса (через `WeakSet`), так что если несколько плагинов патчат `llm/stream`, каждый
  обработает запрос ровно один раз.

---

## 🛠️ Разработка

```bash
git clone https://github.com/MORIC/dsh-vision-fix-lmstudio.git
cd dsh-vision-fix-lmstudio
pnpm install
pnpm build       # собирает lib/index.js и lib/client.js
```

### Структура

```
src/
  index.ts        # хост-часть: конвертация, HTTP-роут /models, llm/stream-хук
  client.tsx      # клиентская секция настроек (React)
  shared.ts       # общие типы + BASE_PATH

lib/              # скомпилированный результат (закоммичен)
scripts/
  postbuild-client.mjs   # переименовывает client.iife.js → client.js
cordis.patch.yml  # манифест плагина для DSH
```

### Как это работает

1. При `llm/stream` плагин смотрит на поле `options.provider/model` — это ключ модели.
2. Сверяет его с `excludedModels` (wildcard `lmstudio/*` поддерживается).
3. Если модели нет в списке исключений — проходит по `messages[].content[]`, находит блоки
   типа `image`, читает байты аттачмента, конвертирует через `sharp`, сохраняет как новый
   аттачмент и подменяет блок.
4. Если конвертировать нечего или модель исключена — просто передаёт управление дальше.

---

## 📄 Лицензия

MIT — см. [LICENSE](LICENSE).

---

Если плагин сэкономил вам вечер — поставьте ⭐ репозиторию и
[откройте Issue](https://github.com/MORIC/dsh-vision-fix-lmstudio/issues) с описанием
вашего сценария: чужие кейсы помогают другим быстрее понять, что это работает не только
у них.