# Генерация изображений Tencent Hunyuan · Нативный плагин DSH

Languages: [English](README.md) · [简体中文](README.zh-CN.md) · [繁體中文](README.zh-TW.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Português](README.pt.md) · [Español](README.es.md) · **Русский**

> Подключите **Hy-Image-3.5-preview** и **Hy-Image-3.0** от Tencent Hunyuan к
> [DSH (DeepSeek Harness)](https://deepseek.com) — с панелью генерации, локальной галереей,
> официальным двухшаговым выбором размера и пакетной генерацией.
> **Без нативных зависимостей. Работает на macOS, Windows и Linux.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node: ≥20](https://img.shields.io/badge/Node-%E2%89%A520-green)](https://nodejs.org)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-blue)](#)
[![CI](https://github.com/rayyugz/dsh-plugin-hunyuan-image/actions/workflows/ci.yml/badge.svg)](../../actions/workflows/ci.yml)

---

## ✨ Возможности

- **Две модели**
  - `hy-image-v3.5-preview` — протокол Chat/Messages; мультимодальный ввод, многораундовое
    редактирование, переписывание через цепочку рассуждений; вывод до **4K (4096×4096)**
  - `hy-image-v3` — классическая генерация изображения по тексту; переписывание промпта и официальные 37 предустановленных размеров
- **Официальный двухшаговый выбор размера** — **уровень разрешения × соотношение сторон**, то же
  взаимодействие, что и в веб-консоли Tencent TokenHub. Плагин преобразует ваш выбор в строку `WxH`,
  которую ожидает API, и гарантирует соблюдение официальных ограничений
  (v3.5: стороны в [256, 8192], площадь ≤ 16,777,216; v3.0: стороны в [512, 2048], площадь ≤ 1,048,576).
  В интерфейсе отображается точный размер, который будет отправлен.
- **Пакетная генерация** — генерация **1 / 2 / 4 изображений** в одном запросе (запускаются параллельно);
  результаты показываются по одному с индексным значком `1/4`. Частичные сбои сообщаются явно.
- **Локальная галерея**
  - Каждая успешная генерация **сохраняется автоматически** (хранилище JSON на чистом JS — без SQLite, без нативных модулей)
  - **Сетка миниатюр** и списочный вид
  - **Поиск по ключевым словам** (совпадение по промпту и по переписанному промпту) плюс фильтрация по модели и временному диапазону
  - **Панель подробностей** с полным промптом, моделью, размером, отметкой времени и локальным путём
  - **🔁 Сгенерировать снова** — в один клик подставляет исходный промпт и параметры
  - Множественный выбор и **пакетное удаление** (также удаляет локальные файлы), копирование промпта, копирование изображения
- **Настраиваемая папка сохранения** — по умолчанию `~/Pictures/DSH-Hunyuan-Image`, но можно указать
  любое место (рекомендуется несистемный диск). Нажатие **«Выбрать…»** открывает системный диалог выбора папки.
  **Изменения вступают в силу немедленно, перезапуск плагина не нужен.** Файлы раскладываются по месяцам в
  `<папка>/<YYYY-MM>/`, чтобы тысячи файлов не скапливались в одной директории.
- **Официальные расширенные параметры** (намеренно действуют в рамках сессии — см. [Ограничения и планы развития](#️-ограничения-и-планы-развития))

  | Параметр | К чему применяется | Описание |
  |---|---|---|
  | Seed `seed` | к обеим | Воспроизводит тот же результат |
  | Водяной знак `footnote` | к обеим | ≤ 16 символов, отрисовывается в правом нижнем углу |
  | Расширение через внешний поиск `use_search_tool` | v3.5 | Позволяет модели искать в интернете перед отрисовкой |
  | Ограничение площади референсного изображения `resize_max_pixels` | v3.5 | Ограничивает расход токенов на большие (4K/6K) референсные изображения |
  | Автоматическое переписывание промпта `revise` | v3.0 | Добавляет ~11 с; по умолчанию рекомендуется включить |

- **Референсные изображения** — загрузка с диска (преобразуется в data URL) или передача публичного URL.
  v3.5 принимает до 20 (≤ 20 MB каждое); v3.0 — до 3 (≤ 10 MB каждое).
- **Вызов моделью** — плагин регистрирует инструмент **`hunyuan_generate_image`**, поэтому достаточно
  просто сказать «нарисуй кота» в диалоге, и модель вызовет его.
- **Долговечные изображения** — удалённые URL Tencent истекают через **12 часов**; плагин сразу
  скачивает каждое сгенерированное изображение на диск, поэтому записи в галерее никогда не ломаются.

> 📌 Нереализованные функции честно перечислены в разделе
> [Ограничения и планы развития](#️-ограничения-и-планы-развития).
> Этот README описывает только то, что текущая версия действительно делает.

---

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

### Вариант 1 — Установка из Release (рекомендуется, без шага сборки)

1. Скачайте `dsh-plugin-hunyuan-image-1.0.0.tgz` со страницы [**Releases**](../../releases).
2. Распакуйте его в постоянную папку, например `~/dsh-plugins/`:

   ```bash
   mkdir -p ~/dsh-plugins
   tar -xzf dsh-plugin-hunyuan-image-1.0.0.tgz -C ~/dsh-plugins
   ```

3. В чате DSH скажите ассистенту:

   > Установи `~/dsh-plugins/package` как плагин DSH (используй `plugin_manager` с `install_bundle`).

4. Перезапустите DSH.

> Пошаговые инструкции по переустановке / на новой машине: [**INSTALL.md**](INSTALL.md)
> (также доступно на [简体中文](INSTALL.zh-CN.md)).

### Вариант 2 — Сборка из исходников (для разработчиков)

Требуется **Node ≥ 20** и **pnpm**.

```bash
git clone https://github.com/rayyugz/dsh-plugin-hunyuan-image.git
cd dsh-plugin-hunyuan-image

pnpm install
pnpm build                        # компиляция host-половины + сборка client-половины
node scripts/smoke-activate.mjs   # smoke-тест — должен вывести "全部通过"

# Привязка к профилю DSH
# macOS / Linux:
ln -s "$(pwd)" ~/.dsh/profiles/desktop/node_modules/dsh-plugin-hunyuan-image
# Windows (PowerShell, от имени администратора):
# New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-plugin-hunyuan-image" -Target "$PWD"
```

Затем добавьте имя плагина в `package.json` профиля (и в `dependencies`, и в
`dsh.profile.bundles`) и перезапустите DSH.

---

## ⚙️ Конфигурация

### 1. Получите API Key

1. Зарегистрируйтесь / войдите в [Tencent Cloud](https://cloud.tencent.com)
2. Активируйте [сервис TokenHub](https://console.cloud.tencent.com/tokenhub)
3. Создайте Key на [странице API Key](https://console.cloud.tencent.com/tokenhub/apikey) — он выглядит как `sk-...`
4. Включите **оплату по факту использования** для `hy-image-v3.5-preview` и `hy-image-v3` в разделе
   [Онлайн-инференс → Визуальные модели](https://console.cloud.tencent.com/tokenhub/inference?regionId=1&serviceType=VISION)

### 2. Заполните настройки плагина

Откройте панель плагина (кнопка **🖼 Hunyuan Image** под полем ввода) → вкладка **Settings**:

| Поле | Описание | По умолчанию |
|---|---|---|
| **API Key** | Key, созданный выше | — |
| **Папка сохранения** | Любая удобная; рекомендуется несистемный диск | `~/Pictures/DSH-Hunyuan-Image` |
| **Модель по умолчанию** | `hy-image-v3.5-preview` или `hy-image-v3` | v3.5-preview |
| **Разрешение по умолчанию** | См. [Размеры](#-размеры) | `1K` |
| **Соотношение сторон по умолчанию** | См. [Размеры](#-размеры) | `1:1` |
| **Водяной знак** | ≤ 16 символов, в правом нижнем углу | пусто |

Нажмите **Save**, затем **🔌 Test connection**, чтобы убедиться, что Key работает.

> ⚠️ **Примечание**: изображения хранятся в **подпапке по месяцу**, например
> `AI-images/2026-10/1791629683045-xxxx.png` — а не прямо в корне папки.

---

## 🖼 Размеры

Плагин повторяет официальный выбор в TokenHub: выберите **уровень разрешения** и **соотношение сторон**.

### Hy-Image-3.5-preview

| Уровень | Соотношения сторон | Примечания |
|---|---|---|
| `1K` / `1.5K` / `2K` | `21:9` `16:9` `4:3` `1:1` `2:3` `3:2` `3:4` `9:16` | Площадь ≈ 1M / 2.36M / 4.19M px |
| `4K` | те же | Площадь ≤ 16,777,216 px; например, 16:9 → `5461x3072` |
| `Auto` | — | `size` не отправляется; модель решает сама |

### Hy-Image-3.0

| Уровень | Соотношения сторон | Примечания |
|---|---|---|
| `720P` / `1K` | `1:1` `3:4` `4:3` `9:16` `16:9` `3:5` `5:3` | Должны выполняться условия: стороны ∈ [512, 2048] и площадь ≤ 1,048,576 |
| `Auto` | — | Модель выбирает из официальных 37 предустановок |

**Ориентировочная справка по размерам** (что фактически отправляется):

```
v3.5  1K   16:9 = 1365x768      1:1 = 1024x1024
      2K   16:9 = 2731x1536     1:1 = 2048x2048
      4K   16:9 = 5461x3072     1:1 = 4096x4096
v3.0  720P 16:9 = 1280x720      1:1 = 960x960
      1K   16:9 = 1365x768      1:1 = 1024x1024
```

Все 62 комбинации проверяются программно на соответствие официальным ограничениям.

---

## 📚 Использование галереи

| Действие | Как |
|---|---|
| **Поиск** | Поле поиска вверху (задержка 300 мс; совпадение по промпту / переписанному промпту / ключевым словам) |
| **Фильтр** | По модели и по временному диапазону |
| **Множественный выбор** | Флажок на карточке или через оверлей при наведении |
| **Пакетное удаление** | Выберите элементы → сверху появится панель пакетных действий |
| **Просмотр одного изображения** | Оверлей при наведении или открытие панели подробностей |
| **Сгенерировать снова** | 🔁 в панели подробностей — переключает обратно на генератор и подставляет промпт и параметры |
| **Копировать промпт** | 📋 в панели подробностей |
| **Копировать изображение** | 🖼 в панели подробностей (если в браузере нет `ClipboardItem`, копируется локальный путь) |

---

## ⚠️ Ограничения и планы развития

### Ограничения (накладываемые API Tencent или хостом DSH)

| Пункт | Подробности |
|---|---|
| **Срок жизни удалённого URL изображения** | Всего 12 часов — этот плагин сразу скачивает каждое изображение на диск, поэтому записи в галерее постоянны |
| **Размер референсного изображения** | v3.5 ≤ 20 MB каждое; v3.0 ≤ 10 MB каждое |
| **Количество референсных изображений** | v3.5 ≤ 20; v3.0 ≤ 3 |
| **Водяной знак** | ≤ 16 символов UTF-8 |
| **`generate_max_pixels` ограничен 2K** | Более высокие разрешения должны идти через `size` (этот плагин делает так через уровень разрешения) |
| **Многораундовое редактирование** | Только v3.5. Плагин сохраняет возвращаемый сервером `assembled_history`, но интерфейса для многораундового редактирования пока нет |
| **Расширенные параметры не сохраняются** | Переключатели внешнего поиска, ограничения площади референса и переписывания действуют **только в текущей сессии** и сбрасываются при повторном открытии панели. Это сделано намеренно — так не остаётся скрытого состояния, которое потом сложно диагностировать |

### Пока не реализовано

| Функция | Статус | Причина |
|---|---|---|
| **Автоматическая кнопка «открыть галерею» при упоминании галереи** | ❌ | Требуется прослушивание событий сообщений сессии и внедрение кнопки действия; в v1.0 не подключено |
| **Диалог экспорта / «Сохранить как»** | ⚠️ заглушка | DSH пока не предоставляет плагинам диалог «Сохранить как»; вызов возвращает явную причину, а не падает молча |
| **Отправка в WeChat / Feishu** | ⚠️ заглушка | DSH пока не предоставляет плагинам канал обмена в мессенджерах |
| **Перетаскивание изображения в диалог** | ❌ | Зависит от того, экспонирует ли DSH события перетаскивания |
| **Интерфейс многораундового редактирования** | ❌ | Уровень данных готов (`assembledHistory`); не хватает только интерфейса |
| **Официальный маркетплейс плагинов DSH** | ❌ | Требуется проверка командой DSH |
| **Многоязычный интерфейс панели** | ❌ | Интерфейс внутри панели сейчас **только на китайском**; локализованы лишь название и описание плагина (EN/ZH). Эти переведённые README — временное решение |

Отзывы и pull request'ы очень приветствуются — открывайте [Issue](../../issues).

---

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

### Структура проекта

```
dsh-plugin-hunyuan-image/
├── package.json              # манифест плагина (dsh.bundle.patch + dsh.client)
├── cordis.patch.yml          # патч загрузчика Cordis: объявляет строку host-плагина
├── icon.svg / locale/        # отображаемые метаданные (иконка + заголовок и описание EN/ZH)
├── scripts/
│   ├── build-client.mjs      # собирает TS/TSX в формат таблицы модулей клиента DSH
│   └── smoke-activate.mjs    # smoke-тест активации (запускать перед перезапуском DSH)
├── src/
│   ├── server.ts             # ★ Host-половина: точка входа плагина Cordis (apply + inject)
│   ├── client.ts             # ★ Client-половина: регистрирует composer dock + оверлей панели
│   ├── types.ts              # контракты данных между модулями
│   ├── size-presets.ts       # уровень разрешения + соотношение сторон → "WxH" (с проверкой ограничений)
│   ├── host/
│   │   └── routes.ts         # HTTP-эндпоинты хоста: /hunyuan/api/* и /hunyuan/file
│   ├── client-services/
│   │   ├── rpc.ts            # обёртка fetch клиент → хост
│   │   ├── config-client.ts  # кеш конфигурации + обновления
│   │   ├── bus.ts            # шина событий (выбор папки, выбор файла, …)
│   │   └── file-url.ts       # локальный путь изображения → загружаемый URL
│   ├── services/
│   │   ├── config.ts         # сохранение конфигурации (JSON, атомарная запись)
│   │   ├── storage.ts        # управление локальными файлами + скачивание изображений (путь следует за конфигурацией на лету)
│   │   ├── hunyuan.ts        # шлюз API Hunyuan (v3 + v3.5)
│   │   └── gallery.ts        # JSON-галерея (индекс в памяти + атомарная запись, без нативных зависимостей)
│   └── slots/
│       ├── generator-panel.tsx   # панель генерации (вкладка «Generate» оверлея)
│       ├── gallery-panel.tsx     # панель галереи (вкладка «Gallery» оверлея)
│       └── settings-panel.tsx    # панель настроек (вкладка «Settings» оверлея)
├── README.md + 7 translations (.zh-CN · .zh-TW · .ja · .ko · .pt · .es · .ru)
├── INSTALL.md / INSTALL.zh-CN.md
└── LICENSE
```

### Заметки об архитектуре

- **Две точки входа**: `dist/server.js` — это Host-половина (процесс Node.js), а `dist/client.js` —
  Client-половина (браузер). Последняя должна быть в формате `window.__ModuleLoader__.load({id, factory})`,
  который создаёт `scripts/build-client.mjs` через esbuild; JSX принудительно компилируется в
  `React.createElement`, потому что таблица модулей DSH предоставляет `React`, но **не** `react/jsx-runtime`.
- **Точка входа UI**: клиент регистрирует единственный слот `conversation.composer.dock` (кнопку).
  Нажатие открывает оверлей с тремя вкладками: Generate / Gallery / Settings.
- **Client ↔ host**: клиент вызывает хост через `fetch('/hunyuan/api/<method>')`; изображения
  отдаются через `/hunyuan/file?path=<абсолютный путь>` (доступ ограничен файлами внутри
  настроенной папки сохранения, чтобы предотвратить обход пути).
- **Без нативных зависимостей**: галерея — это JSON-файл, а не SQLite, поэтому она нормально
  загружается в условиях ограничений подписи кода / hardened runtime приложения DSH и не требует
  пересборки на Windows или Linux.

### Локальная сборка

```bash
pnpm install
pnpm build         # tsc → dist/ (host), esbuild → dist/client.js (client)
pnpm typecheck     # tsc --noEmit
node scripts/smoke-activate.mjs
```

### Режим отладки

Запустите DSH с `--plugin-debug=hunyuan-image` для подробного логирования.

---

## 🤝 Участие в разработке

Issues и pull request'ы приветствуются.

- 🐛 Нашли баг → [откройте bug report](../../issues/new?template=bug.md)
- 💡 Есть идея → [откройте feature request](../../issues/new?template=feature.md)
- 🔧 Присылаете код → fork, branch, PR

---

## 📄 Лицензия

MIT © [rayyugz](https://github.com/rayyugz)

---

## 🙏 Благодарности

- Команде Tencent Hunyuan за API
- Команде DSH за платформу плагинов
- Всем, кто сообщает об issues и помогает улучшать этот плагин