# 📦 @goodandready/dsh-key-limits

Мониторинг лимитов квот, тарифных планов и балансов API-ключей в реальном времени для DeepSeek Harness

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

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

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

--- ## ⚡ Обзор и решаемая проблема Разработчики и исследователи искусственного интеллекта регулярно работают с десятком разных провайдеров LLM, корпоративными квотами и тарифными подписками одновременно (OpenCode GO, Ollama Cloud, Qwen Cloud, Kimi, GLM, MiniMax, Cline, DeepSeek, OpenRouter, Command Code). Без наглядного мониторинга квот непосредственно в DeepSeek Harness (DSH): - Сессии диалога внезапно падают с ошибками посреди генерации кода, когда 5-часовое окно или месячный лимит кредитов исчерпан. - Пользователь не видит, какой конкретно аккаунт или ключ привязан к активной модели текущего чата. - Постоянное переключение по десяткам личных кабинетов провайдеров отвлекает от работы. `dsh-key-limits` решает эту задачу, обеспечивая ненавязчивый фоновый контроль остатков квот и балансов прямо в веб-интерфейсе DSH. Плагин намеренно исключает громоздкий бухгалтерский учёт и тяжелые базы данных расходов, фокусируясь исключительно на живом контроле лимитов. --- ## 🏗️ Архитектура и схема движения данных ```mermaid graph LR subgraph Client ["Клиент Web UI (DSH)"] FC["FloatChip (Плавающий чип)"] CB["ActiveKeyButton (Кнопка в строке ввода)"] SC["Карточка настроек (settings.plugin.item)"] M["Модальные окна (Все лимиты / Активный ключ)"] end subgraph Backend ["Бэкенд плагина (Cordis)"] Router["HTTP API (/dsh-key-limits)"] CredStore["Защищённое хранилище учётных данных"] Updater["Локальный One-Click Updater"] end subgraph Providers ["Провайдеры и Реестры"] P1["OpenCode GO / Ollama / Qwen"] P2["Command Code / Cline / GLM"] P3["DeepSeek / OpenRouter / MiniMax"] NPM["Реестр npmjs.org"] end FC -->|Клик| M CB -->|Клик| M M -->|Опрос квот раз в 60с| Router SC -->|Сохранение ключей| Router SC -->|Проверка обновления| Updater Router --> CredStore Router -->|Параллельный опрос (таймаут 12с)| P1 Router -->|Параллельный опрос (таймаут 12с)| P2 Router -->|Параллельный опрос (таймаут 12с)| P3 Updater -->|Проверка версий и установка| NPM ``` --- ## ✨ Исчерпывающий разбор возможностей ### 1. Плавающий чип (`FloatChip`) - **Постоянный индикатор**: отображает минимальный оставшийся процент квоты среди всех ключей (или общее число активных аккаунтов). - **Свободное перемещение с защитой от вылета**: перетаскивается мышью и жестами с автоограничением границами окна (`viewport clamping`). Координаты сохраняются в `localStorage`. - **Окно всех лимитов**: клик открывает подробный список всех 9 аккаунтов с полосами заполнения, датами сброса и тарифами. ### 2. Кнопка в строке ввода сообщений (`ActiveKeyButton`) - Встроена в панель ввода сообщений (`conversation.composer.bar`, приоритет 10). - Автоматически инспектирует модель текущего диалога и отображает актуальный процент или денежный баланс именно для неё. - Клик открывает детальную модалку только активного ключа. ### 3. Очередность аккаунтов и «Активный всегда сверху» - **Ручной порядок (`order`)**: в настройках можно менять последовательность аккаунтов с помощью кнопок ▲ / ▼. - **Закрепление активного (`activeOnTop`)**: аккаунт, привязанный к открытому чату, автоматически выводится на первое место. По умолчанию включено. ### 4. Человекопонятный таймер сброса (`fmtReset`) - Если до сброса больше 24 часов: отображает дни, часы и минуты (например, `5д 5ч 19м`). - Если меньше 24 часов: только часы и минуты (например, `4ч 59м`). - Для истекших окон выводится статус обновления. ### 5. Спокойный и нативный дизайн - Вертикальный отступ **12px** между карточками исключает наплывы границ и слипание. - Нейтральные тона темы для нормальных остатков (>30%), предупреждающие янтарный (<30%) и красный (<15%) зарезервированы только для реального исчерпания. - Аккуратные прогресс-бары высотой 5px. ### 6. Индикатор пула и предиктивная аналитика - **Индикатор здоровья пула аккаунтов**: Ambient-сводка по пулам провайдеров (`healthy / warning / exhausted`) с мгновенным выявлением исчерпанных или недоступных ключей. - **Скорость расхода (Burn Rate) и время до исчерпания**: Расчёт скорости расхода квоты в час (`%/h`) и автоматический прогноз времени до опустошения (`осталось ~X.X ч`) на основе 24-часовых скользящих снимков в браузере. - **Обратный отсчёт до сброса лимита**: В тултипе плавающего чипа и на карточках подписок выводится точный таймер до ближайшего окна сброса (например, `Сброс через 2h 15m`). - **24-часовой SVG-спарклайн расхода**: Компактный встроенный график тренда расхода квоты с динамической подсветкой цветами системной темы. ### 7. Режим привязки к углу (Docked), хоткей Alt+K и Danger Toast - **Режим Docked**: Кнопка в заголовке чипа мгновенно прижимает его к правому нижнему углу и фиксирует позицию, чтобы чип не мешал при перетаскивании. - **Глобальный хоткей `Alt+K`**: Мгновенный вызов модального окна со всеми лимитами из любого места рабочего пространства. - **Предупреждение Danger Toast**: Ненавязчивое всплывающее уведомление, когда квота активного ключа падает ниже 15%, предотвращая внезапные обрывы генерации. ### 8. Зашифрованный бэкап и пакетное обновление (Refresh All) - **Зашифрованный экспорт и импорт**: Выгрузка всех добавленных ключей и подписок в зашифрованный AES-256-GCM файл с защитой паролем для удобного переноса между рабочими станциями или профилями. - **Принудительное обновление всех аккаунтов (Refresh All)**: Кнопка в заголовке модального хаба мгновенно опрашивает всех провайдеров с анимацией вращения и ограничением параллелизма. ### 9. Встроенное автообновление в один клик - Проверка наличия новой версии в карточке настроек. - Установка точной опубликованной версии из npm без ручного ввода консольных команд. - Защита: разрешены только loopback-запросы с совпадающим Origin. ### 10. Безопасность и архитектура хранения секретов - **Изоляция секретов**: Открытые API-ключи и сессионные куки (включая Ollama Cloud) хранятся исключительно в защищённом сервисе `credentials` платформы DSH. Локальный файл `subs.json` содержит только обезличенные метаданные и ссылки. - **Строгие права доступа**: Файл базы данных `subs.json` и временные файлы обмена создаются с правами доступа `0600` (чтение и запись только владельцу процесса), предотвращая локальную утечку данных. - **Очистка памяти при отзыве**: Кэш секретов в оперативной памяти сбрасывается перед каждым опросом; удалённые или отозванные ключи не задерживаются в памяти и не попадают в резервные копии (`POST /export`). - **Защита от утечек при редиректах**: Сетевой клиент опроса провайдеров работает с опцией `redirect: 'error'`, блокируя передачу конфиденциальных заголовков авторизации на сторонние домены при HTTP 301/302/307. - **Транзакционный откат**: Ошибки записи на диск вызывают откат структур в оперативной памяти и возвращают честный HTTP 500 вместо ложного сообщения об успехе. --- ## 🔌 Поддерживаемые провайдеры | ID провайдера | Название | Типы окон квот | Метод авторизации | |---------------|----------|----------------|-------------------| | `commandcode` | Command Code | Скользящее 5ч / Неделя / Месяц (тарифы GOAT, Pro, Max) | API-ключ (`user_...` или токен) | | `opencode-go` | OpenCode GO | Скользящее 5ч / Неделя / Месяц | Сессионная кука (`auth`) и Workspace ID | | `ollama` | Ollama Cloud | Сессия / Неделя / Месяц | API-ключ и сессионная кука | | `qwen` | Qwen Cloud | 5 часов / 1 неделя (Token Plan) | Сессионная кука и опциональный `sec_token` | | `kimi` | Kimi for Coding | Недельный лимит вызовов | API-ключ (`sk-kimi-...`) | | `glm` | GLM (Z.ai) | Дневной / Месячный лимит | API-ключ личного кабинета | | `minimax` | MiniMax Coding Plan | Квота Coding Plan | API-ключ (`sk-cp-...`) | | `cline` | Cline | 5 часов / Неделя / Месяц | Bearer API токен | | `siliconflow` | SiliconFlow (SiliconCloud) | Баланс и бонусы ($ / ¥) | API-ключ (`sk-...`) | | `anthropic` | Anthropic | Скорость вызовов (Requests/Tokens) | API-ключ (`sk-ant-...`) | | `groq` | Groq | Лимиты RPM и TPM | API-ключ (`gsk_...`) | | `gemini` | Google Gemini | Доступность API и модели | API-ключ (`AIza...`) | | `deepseek` | DeepSeek | Баланс лицевого счёта ($ / ¥) | API-ключ (`sk-...`) | | `openrouter` | OpenRouter | Баланс лицевого счёта ($ credits) | API-ключ (`sk-or-...`) | --- ## 📦 Быстрая установка Установка официального публичного пакета в профиль DSH: ```bash dsh plugin --profile web add @goodandready/dsh-key-limits ``` Перезапуск веб-интерфейса: ```bash dsh web --profile web ``` --- ## ⚙️ Параметры конфигурации ```yaml # Основная настройка: Настройки -> Плагины -> Key Limits (карточка настроек) или конфигурация профиля. # Миграция устаревших версий: ~/.dsh/profiles/web/settings.yaml plugins: '@goodandready/dsh-key-limits': storageDir: ~/.dsh/storages/dsh-key-limits refreshHours: 24 ui: floatChip: true composerBar: true activeOnTop: true order: [] ``` ### Таблица параметров | Параметр | Тип | По умолчанию | Описание | |----------|-----|--------------|----------| | `storageDir` | `string` | `~/.dsh/storages/dsh-key-limits` | Каталог хранения файла метаданных подписок `subs.json`. | | `refreshHours` | `number` | `24` | Интервал фонового опроса провайдеров в часах. | | `ui.floatChip` | `boolean` | `true` | Показывать плавающий перетаскиваемый чип-индикатор в интерфейсе. | | `ui.composerBar` | `boolean` | `true` | Показывать кнопку активного ключа в строке ввода сообщений (composer bar). | | `ui.activeOnTop` | `boolean` | `true` | Автоматически закреплять активный в диалоге аккаунт на самом верху списка. | | `ui.order` | `string[]` | `[]` | Пользовательский порядок отображения карточек (массив ID подписок). | --- ## 🌐 Маршруты REST API | Метод и путь | Доступ / Источник | Описание | |--------------|-------------------|----------| | `GET /dsh-key-limits/health` | Loopback / Same-Origin | Проверка работоспособности сервиса (`{ ok: true, name: "dsh-key-limits", status: "healthy" }`) | | `GET /dsh-key-limits/config` | Public / Web | Публичная конфигурация UI и схемы параметров провайдеров | | `GET /dsh-key-limits/active-sub` | Public / Web | Привязка подписки к активной сессии (`?sessionId=`) | | `GET /dsh-key-limits/subs` | Public / Web | Список всех настроенных подписок, карточек и балансов | | `POST /dsh-key-limits/subs` | Loopback / Same-Origin | Добавление, изменение или удаление подписки | | `POST /dsh-key-limits/refresh-all` | Loopback / Same-Origin | Принудительное обновление всех подписок (защита от одновременного выполнения / in-flight lock) | | `POST /dsh-key-limits/export` | Loopback / Same-Origin | Экспорт зашифрованного паролем бэкапа подписок (AES-256-GCM) | | `POST /dsh-key-limits/import` | Loopback / Same-Origin | Дешифрование и импорт бэкапа с дедупликацией | | `GET /dsh-key-limits/update` | Loopback / Same-Origin | Проверка наличия новых версий плагина в npm | | `POST /dsh-key-limits/update` | Loopback / Same-Origin | Запуск автоматического обновления через npm | --- ## 🛠️ Разработка и тестирование > **Примечание**: Опубликованный npm-пакет и релизный архив содержат только файлы рантайма (`lib/`, `cordis.patch.yml`, документацию и лицензию). Исходный код (`src/client/`, `test/` и скрипты сборки) находится в репозитории разработки. Для запуска тестов или пересборки клиентского бандла клонируйте репозиторий разработки. ```bash # Сборка монолитного клиентского бандла из src/client/ в lib/client.js npm run build:client # Запуск офлайн-тестов npm test ``` ### Структура проекта ``` . ├── lib/ │ ├── index.js # Точка входа Cordis-плагина и маршруты HTTP │ ├── client.js # Скомпилированный клиентский бандл │ ├── cards.js # Рендеринг и форматирование карточек │ ├── subs.js # Менеджер подписок и нормализация │ ├── provider-fetchers.js # Основные фетчеры и парсеры HTML │ ├── provider-extra-fetchers.js # Расширенные фетчеры (SiliconFlow, Anthropic, Groq, Gemini) │ ├── crypto-backup.js # Экспорт и импорт бэкапа AES-256-GCM │ ├── paths.js # Резолвер путей хранения │ └── plugin-updater.js # Безопасный апдейтер ├── src/client/ # Исходные модули браузерного интерфейса │ ├── 01-prelude.js # Изолированный CSS и инициализация React │ ├── 02-locale.js # Словари локализации (en, zh; ru через dsh-russian-lang) │ ├── 03-format.js # Форматирование времени и цветовые шкалы │ ├── 04-modals.js # AllLimitsModal и OneLimitModal │ ├── 05-bar.js # Кнопка ActiveKeyButton в строке ввода │ ├── 06-float.js # Draggable FloatChip │ ├── 07-settings.js # Карточка настроек, сортировка и апдейтер │ └── 08-apply.js # Инициализация плагина и регистрация слотов DSH ├── cordis.patch.yml # Манифест плагина для Cordis └── test/ # Набор тестов ``` --- ## 📄 Лицензия MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)