# 📦 @goodandready/dsh-clinebot

Нативное подключение провайдера ClineBot / ClinePass для DeepSeek Harness

0.6.15 подключает бюджетирование мультимодальных запросов, добавляет замер моделей и управление видимостью, переключатель автосинхронизации цен и закрывает оставшиеся находки аудита. Чат работает через нативный адаптер ctx.llm, требуется DSH 0.2.1-rc.2; старые llm-pi-ai, loopback-прокси и llm/stream удалены.

🇬🇧 English • 🇷🇺 Русский • 🇨🇳 中文说明

⭐ Если вам нравится этот плагин, поставьте ему звезду на GitHub — это покажет мне, что плагин вам полезен, и будет мотивировать меня развивать его дальше.

🐛 Если вы нашли баг или хотите предложить новый функционал, создайте issue на GitHub на любом языке — я рассмотрю ваше предложение и реализую полезные идеи в одной из следующих версий плагина.

--- ## ⚡ Обзор и решаемая проблема **ClinePass** (`https://cline.bot`) — сервис единой фиксированной подписки, предоставляющий разработчикам повышенные лимиты (в 2–5 раз выше стандартных) на передовые open-weights модели программирования и рассуждений через единый OpenAI-совместимый интерфейс (`https://api.cline.bot/api/v1`). Интеграция ClinePass в DeepSeek Harness (DSH) напрямую сопряжена со следующими сложностями: 1. **Отсутствие эндпоинта `/v1/models`**: запрос `GET /v1/models` к `api.cline.bot` возвращает `404 Not Found`, из-за чего динамический поиск моделей в DSH падает или оставляет список пустым. 2. **Специфический формат идентификаторов**: моделям требуется обязательный префикс `cline-pass/` (например, `cline-pass/deepseek-v4.1-flash`, `cline-pass/kimi-k3`). 3. **Отслеживание лимитов**: 5-часовые и недельные скользящие окна расхода токенов требуют прозрачной визуализации в интерфейсе. 4. **Безопасность ключей**: хранение API-токенов в открытых конфигурациях небезопасно. Плагин **`@goodandready/dsh-clinebot`** решает эти задачи «из коробки»: * 🚀 **Обновление в один клик**: Обновление плагина прямо из интерфейса DSH или через защищённый loopback-эндпоинт `/dsh-clinebot/update`. * ⚡ **SWR-кэширование квот и здоровья**: Мгновенный ответ (<2 мс) на запросы статуса с фоновым обновлением данных без блокировки UI. * 🔀 **Smart Quota-Aware Failover**: Автоматическая ротация аккаунтов в пуле при ошибках 429 и исчерпании квоты в стриме (с 30-секундной защитой от шторма; текущий запрос не повторяется, последующие запросы сразу идут через следующий аккаунт). * 🖥️ **Страница конфигурации плагина**: откройте установленный ClineBot и перейдите в настройки плагина. Там имя учётных данных, модели, квота и аккаунты. Отдельного пункта бокового меню нет. * 🔄 **Динамическая синхронизация моделей подписки**: автоматическое получение реального списка моделей из `GET /api/v1/users/me/plan` и мгновенное обновление провайдера DSH в один клик. В DSH регистрируются строго модели активного тарифа, а встроенный каталог служит справочником характеристик и запасным вариантом при недоступности API. * ⚠️ **Предупреждения об исчерпании квоты**: баннеры предупреждения при достижении 80% (внимание) и 95% (исчерпано) 5-часового лимита с таймером сброса. * 📈 **Метрики сессии**: Учет реального трафика DSH-чатов через провайдер ClineBot с момента запуска (успешные, прерванные и ошибочные запросы, токены prompt/completion, задержка стрима). * 📊 **Дашборд лимитов подписки (Usage)**: наглядные прогресс-бары расхода 5-часового и недельного скользящего окна из официального API `GET /users/me/plan/usage-limits`. * 🔑 **Сохранение ключа прямо из UI**: поле ввода ключа с маскировкой; сохранение напрямую в системный сервис `credentials` (`~/.dsh/.credentials.yaml`) без ручной правки файлов на сервере. * 🎯 **Управление моделями в пикере**: включение/выключение отображения конкретных моделей в диалогах чата. * 💬 **Слэш-команда `/cline` в чате**: просмотр остатка квот, предупреждений, статистики сессии, задержки и активной модели прямо из чата. --- ## 🏛️ Архитектура ```mermaid graph LR subgraph UI [Интерфейс DSH] Page["Отдельная страница (Настройки -> ClineBot)"] QuotaBar["Прогресс-бары 5h и недельного лимита + Баннер предупреждений"] KeyInput["Ввод и сохранение API-ключа"] ModelPick["Динамическая синхронизация моделей и пикер"] StatsCard["Метрики и статистика текущей сессии"] end subgraph PluginHost [Хост-часть dsh-clinebot] HttpEndpoints["API: /dsh-clinebot/*"] ClientCore["lib/cline-client.js"] ModelCatalog["lib/models.js (Встроенные + Динамические из плана)"] SlashCmd["Слэш-команда: /cline"] end subgraph DSHCore [Сервисы DSH] Credentials["Сервис credentials (~/.dsh/.credentials.yaml)"] end subgraph Upstream [Сервер Cline] ClinePass["api.cline.bot/api/v1/chat/completions"] ClineQuota["api.cline.bot/api/v1/users/me/plan/usage-limits"] ClinePlan["api.cline.bot/api/v1/users/me/plan"] end Page -->|GET /status & /usage| HttpEndpoints KeyInput -->|POST /save-key| HttpEndpoints ModelPick -->|POST /models/sync| HttpEndpoints HttpEndpoints --> Credentials HttpEndpoints --> ClientCore ClientCore --> ModelCatalog ClientCore -->|Чат| ClinePass ClientCore -->|Квоты| ClineQuota ClientCore -->|Тарифный план| ClinePlan ``` --- ## ✨ Структура модулей и возможности * **`lib/models.js`**: динамический каталог моделей подписки и встроенных шаблонов с поддержкой уровней рассуждения (`Off` / `Low` / `Medium` / `High` / `Max`), контекстных лимитов, пользовательских моделей (`customModels`) и парсинга тарифа (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`). * **Цены и модели**: кнопка **Ping** у модели вызывает `POST /models/probe` и показывает TTFT; кнопка **Применить видимость** сохраняет выбор видимых моделей и фильтр тарифа через `POST /models/visible`. Публичные цены могут автоматически подгружаться из models.dev для новых моделей; это отключается переключателем `priceAutoSync` (или `priceAutoSync: false`), ручная синхронизация остаётся доступной. * **`lib/cline-client.js`**: * `fetchUsageLimits`: параллельный опрос `GET /users/me/plan/usage-limits`, `GET /users/me/plan` и `GET /users/me` с кэшированием в памяти. * `sessionStats` / `recordSessionRequest`: счетчики сессии (запросы, токены, задержка, время). * `saveCredentialKey`: атомарная запись ключей в `~/.dsh/.credentials.yaml`. * `smokeChat`: замер задержки и тестовый пинг с фиксацией статистики. * **`lib/index.js`**: сервис Cordis, регистрация системных маршрутов (включая `/dsh-clinebot/models/sync`), расчет порогов предупреждения квоты и слэш-команды `/cline`. * **`lib/client.js`**: страница конфигурации строки плагина (`plugins.row.config`) с предупреждениями, статистикой сессии, синхронизацией моделей и запасной карточкой (`settings.plugin.item`). Пункта `settings.section` в боковом меню нет. --- ## 📦 Установка ```bash dsh plugin --profile web add @goodandready/dsh-clinebot ``` Перезапустите экземпляр DeepSeek Harness и обновите вкладку в браузере. --- ## 💬 Слэш-команда `/cline` в чате В любой сессии чата введите команду `/cline` для проверки остатка лимитов, предупреждений и статистики: ```text ### 🤖 ClinePass Status (ClinePass) * Пинг хоста: ✅ 210 мс * Активный ключ: CLINEBOT_API_KEY (credentials) * Модель по умолчанию: `cline-pass/deepseek-v4.1-flash` ⏱ 5-часовое окно: [████░░░░░░] 42% (сброс: 18:00) 📅 Недельное окно: [██████░░░░] 60% (сброс: 08.09) * Аккаунт: `developer@example.com` 📈 Статистика текущей сессии: * Запросов: 14 вызовов * Токены: ~8,450 (Промпт: 6,100 | Ответ: 2,350) * Задержка последнего ответа: 210 мс ``` --- ## ⚙️ Конфигурация (Настройки DSH и Web UI) В современном DeepSeek Harness (0.1.7+) настройки управляются через карточку в Web UI или `PUT /dsh-clinebot/config`, а секретные ключи безопасно хранятся в DSH Credentials (`~/.dsh/.credentials.yaml`). ```yaml dsh-clinebot: enabled: true baseUrl: https://api.cline.bot/api/v1 apiKeyEnv: CLINEBOT_API_KEY defaultModel: your-default-model disabledModels: [] customModels: [] modelReasoningDefaults: your-reasoning-model: high modelContextOverrides: [] statsPath: ~/.dsh/clinebot-stats.json statsRetentionDays: 95 dailyBudgetUsd: 0 monthlyBudgetUsd: 0 timeoutMs: 30000 smokeTimeoutMs: 60000 streamIdleTimeoutMs: 60000 accounts: - label: Team Key apiKeyEnv: CLINEBOT_API_KEY_2 ``` ### Параметры конфигурации | Параметр | Тип | По умолчанию | Описание | |:---|:---|:---|:---| | `enabled` | `boolean` | `true` | Включение моста провайдера ClineBot в DSH | | `baseUrl` | `string` | `"https://api.cline.bot/api/v1"` | Базовый URL OpenAI-совместимого API ClinePass | | `apiKeyEnv` | `string` | `"CLINEBOT_API_KEY"` | Имя переменной / ключа в хранилище credentials | | `defaultModel` | `string` | `"cline-pass/deepseek-v4.1-flash"` | Модель, выбираемая по умолчанию для чата и smoke-тестов | | `disabledModels` | `array` | `[]` | Список отключённых моделей (новые модели подписки включаются автоматически) | | `customModels` | `array` | `[]` | Пользовательские модели шлюза (`[{ id, name, contextLength, maxTokens, category, isReasoning }]`) | | `modelReasoningDefaults` | `object` | `{}` | Значения thinking effort по умолчанию для моделей (`low`, `medium`, `high`, `max`) | | `modelContextOverrides` | `array` | `[]` | Пользовательские переопределения размера контекста и лимита токенов | | `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | Путь к файлу персистентной аналитики использования токенов | | `statsRetentionDays` | `number` | `95` | Срок хранения дневной/часовой/сессионной телеметрии; 0 — хранить всё | | `dailyBudgetUsd` | `number` | `0` | Опциональный дневной лимит оценочных трат; 0 отключает | | `monthlyBudgetUsd` | `number` | `0` | Опциональный месячный лимит оценочных трат; 0 отключает | | `accounts` | `array` | `[]` | Дополнительные аккаунты для ротации квоты и failover (`[{ label, apiKeyEnv }]`) | | `activeAccount` | `string` | `""` | Принудительно закреплённый аккаунт (пусто для автоматического выбора least-used) | | `timeoutMs` | `number` | `15000` | Таймаут HTTP-запросов (мс) | | `smokeTimeoutMs` | `number` | `25000` | Таймаут тестового пинга инференса (мс) | | `streamIdleTimeoutMs` | `number` | `30000` | Таймаут ожидания между чанками SSE-потока (мс) | | `enabledModels` | `array` | *(устарело)* | Только для чтения в public config; отклоняется при `PUT /config` в пользу `disabledModels` | | `dynamicModels` | `array` | `[]` | Динамические модели, автоматически синхронизированные из тарифа | --- ## 🌐 Маршруты HTTP API Все маршруты регистрируются с префиксом `/dsh-clinebot/*` и защищены от межсайтовых запросов (разрешены same-origin и loopback). Управляющие эндпоинты ограничены лимитом 256 КиБ: ### Управляющие эндпоинты (макс. 256 КиБ) * `GET /dsh-clinebot/status` — Текущее состояние провайдера, активный аккаунт, квоты и статистика сессий. * `GET /dsh-clinebot/config` — Диагностический маршрут, возвращающий открытую конфигурацию (без секретов). * `PUT /dsh-clinebot/config` — Обновление параметров конфигурации (устаревший `enabledModels` блокируется). * `POST /dsh-clinebot/key/verify` — Проверка API-ключа на сервере `api.cline.bot` с возвратом email и тарифа. * `POST /dsh-clinebot/save-key` — Сохранение ключа в сервис credentials DSH под именем `CLINEBOT_API_KEY*`. * `POST /dsh-clinebot/models/sync` — Синхронизация списка моделей с официальным тарифом ClinePass. * `POST /dsh-clinebot/models/toggle` — Включение и отключение моделей через `disabledModels` с сохранением Volatile-ссылок. * `POST /dsh-clinebot/models/custom` / `DELETE /dsh-clinebot/models/custom` — Управление пользовательскими моделями. * `POST /dsh-clinebot/models/context` / `DELETE /dsh-clinebot/models/context` — Переопределение контекстного окна моделей. * `POST /dsh-clinebot/accounts` — Добавление аккаунта в пул ротации. * `POST /dsh-clinebot/accounts/delete` — Удаление аккаунта с атомарной защитой секретного ключа. * `POST /dsh-clinebot/accounts/active` — Назначение активного аккаунта из пула (или пусто для auto least-used). * `POST /dsh-clinebot/stats/reset` — Сброс счётчиков запросов и токенов. * `POST /dsh-clinebot/smoke` — Выполнение тестового пинга задержки. * `GET /dsh-clinebot/update/status` — Проверка наличия обновлений плагина. * `POST /dsh-clinebot/update/apply` — Обновление плагина с корректным завершением групп процессов и блокировками профиля. --- ## 🧪 Тестирование Запуск автоматического набора тестов: ```bash npm test ``` --- ## 📄 Лицензия MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)