# 📦 @goodandready/dsh-clinebot

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

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

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

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

--- ## ⚡ Обзор и решаемая проблема **ClinePass** (`https://cline.bot`) — сервис единой фиксированной подписки (\$9.99/мес), предоставляющий разработчикам повышенные лимиты (в 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-flash`, `cline-pass/kimi-k3`). 3. **Отслеживание лимитов**: 5-часовые и недельные скользящие окна расхода токенов требуют прозрачной визуализации в интерфейсе. 4. **Безопасность ключей**: хранение API-токенов в открытых конфигурациях небезопасно. Плагин **`@goodandready/dsh-clinebot`** решает эти задачи «из коробки»: * 🚀 **Обновление в один клик**: Обновление плагина прямо из интерфейса DSH или через защищённый loopback-эндпоинт `/dsh-clinebot/update`. * ⚡ **SWR-кэширование квот и здоровья**: Мгновенный ответ (<2 мс) на запросы статуса с фоновым обновлением данных без блокировки UI. * 🔀 **Smart Quota-Aware Failover**: Интеллектуальная ротация аккаунтов с обходом исчерпанных лимитов и авто-восстановлением при наступлении `resetsAt`. * 🖥️ **Отдельная страница в Настройках**: собственная полноэкранная страница в меню Настроек DSH (`Настройки → ClineBot`). * 🔄 **Динамическая синхронизация моделей подписки**: автоматическое получение реального списка моделей из `GET /api/v1/users/me/plan` и мгновенное обновление провайдера DSH в один клик. * ⚠️ **Предупреждения об исчерпании квоты**: баннеры предупреждения при достижении 80% (внимание) и 95% (исчерпано) 5-часового лимита с таймером сброса. * 📈 **Метрики сессии**: учет количества запросов, расчетных токенов (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: /api/plugins/dsh-clinebot/*"] ClientCore["lib/cline-client.js"] ModelCatalog["lib/models.js (Встроенные + Динамические из плана)"] SlashCmd["Слэш-команда: /cline"] end subgraph DSHCore [Сервисы DSH] Credentials["Сервис credentials (~/.dsh/.credentials.yaml)"] PiAi["Настройки: llm-pi-ai.providers.clinebot"] 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 HttpEndpoints -->|Атомарная мутация| PiAi ClientCore -->|Чат| ClinePass ClientCore -->|Квоты| ClineQuota ClientCore -->|Тарифный план| ClinePlan ``` --- ## ✨ Структура модулей и возможности * **`lib/models.js`**: каталог встроенных моделей ClinePass (11 моделей) и парсер моделей подписки (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`). * **`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`: замер задержки и тестовый пинг с фиксацией статистики. * `buildPiAiProvider`: генерация конфигурации провайдера для `llm-pi-ai` (`api: 'openai-completions'`). * **`lib/index.js`**: сервис Cordis, регистрация системных маршрутов (включая `/dsh-clinebot/models/sync`), расчет порогов предупреждения квоты и слэш-команды `/cline`. * **`lib/client.js`**: полнофункциональный раздел настроек (`settings.section`, order 28) с баннерами предупреждений, карточкой статистики сессии, кнопкой синхронизации моделей плана и аккордеоном плагина (`settings.plugin.item`). --- ## 📦 Установка ```bash dsh plugin --profile web add @goodandready/dsh-clinebot ``` Перезапустите экземпляр DeepSeek Harness и обновите вкладку в браузере. --- ## 💬 Слэш-команда `/cline` в чате В любой сессии чата введите команду `/cline` для проверки остатка лимитов, предупреждений и статистики: ```text ### 🤖 ClinePass Status (ClinePass ($9.99/mo)) * Пинг хоста: ✅ 210 мс * Активный ключ: CLINEBOT_API_KEY (credentials) * Модель по умолчанию: `cline-pass/deepseek-v4-flash` ⏱ 5-часовое окно: [████░░░░░░] 42% (сброс: 18:00) 📅 Недельное окно: [██████░░░░] 60% (сброс: 08.09) * Аккаунт: `developer@example.com` 📈 Статистика текущей сессии: * Запросов: 14 вызовов * Токены: ~8,450 (Промпт: 6,100 | Ответ: 2,350) * Задержка последнего ответа: 210 мс ``` --- ## ⚙️ Таблица конфигурации (`settings.yaml`) ```yaml dsh-clinebot: enabled: true baseUrl: https://api.cline.bot/api/v1 apiKeyEnv: CLINEBOT_API_KEY defaultModel: cline-pass/deepseek-v4-flash timeoutMs: 15000 smokeTimeoutMs: 25000 enabledModels: - cline-pass/deepseek-v4-flash - cline-pass/deepseek-v4-pro - cline-pass/kimi-k3 - cline-pass/qwen3.7-max dynamicModels: [] ``` ### Параметры конфигурации | Параметр | Тип | По умолчанию | Описание | |:---|:---|:---|:---| | `enabled` | `boolean` | `true` | Включение моста провайдера ClineBot | | `baseUrl` | `string` | `"https://api.cline.bot/api/v1"` | Базовый URL OpenAI-совместимого API ClinePass | | `apiKeyEnv` | `string` | `"CLINEBOT_API_KEY"` | Имя переменной / ключа в хранилище credentials | | `defaultModel` | `string` | `"cline-pass/deepseek-v4-flash"` | Модель, выбираемая по умолчанию | | `timeoutMs` | `number` | `15000` | Таймаут HTTP-запросов (мс) | | `smokeTimeoutMs` | `number` | `25000` | Таймаут тестового пинга (мс) | | `enabledModels` | `array` | `[...]` | Список моделей, активных в селекторе чата | | `dynamicModels` | `array` | `[]` | Динамические модели, автоматически синхронизированные из тарифа | --- ## 🧪 Тестирование Запуск автоматического набора тестов: ```bash npm test ``` --- ## 📄 Лицензия MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)