dsh-polza

[!WARNING] Неофициальный плагин. Проект не связан с Polza.ai, DeepSeek или их правообладателями и не поддерживается ими. API Polza может измениться в любой момент; используйте плагин на свой риск и проверяйте списания в официальном кабинете. Плагин не хранит API-ключ и не выполняет платежи.

Unofficial plugin. Not affiliated with or endorsed by Polza.ai or DeepSeek. Use at your own risk.

Баланс Polza.ai и статистика расхода для Web GUI DeepSeek Harness.

Плагин показывает доступный баланс в футере сайдбара и открывает панель с расходом по периодам, графиком по дням, разбивкой по моделям и историей генераций с фильтрами.

Что показывает

• Баланс организации: amount, available, резерв и всего потрачено.
• Чип в сайдбаре (левый нижний угол): текущий баланс организации (без вычета резерва) и траты за текущий день без учёта резервации, смена цвета при пересечении порогов.
• Расход по ключу: сегодня, с понедельника, за месяц, за всё время — точные цифры из GET /api/v1/key.
• История: график по дням, топ моделей, типы запросов, таблица генераций с фильтрами по типу, статусу и модели, gen_id каждой записи и разбивка по токенам и строкам цены при наведении. Стоимость запроса показывается без округления до копеек.
• Лимит ключа: остаток и период сброса, если лимит задан.

Баланс — общий по организации. История и расход — только по тому API-ключу, которым пользуется DSH: Polza не отдаёт историю других ключей по API-ключу.

Денежные цифры «без учёта резервации» совпадают с кабинетом Polza: баланс — это amount (не available), а траты за день и «Расход · период» — это usage-сводка ключа минус reservedAmount (для свёртки по истории — без строк pending). Удержания за незавершённые генерации Polza включает в usage-сводки и в available-баланс, поэтому их нужно вычитать. График «Расход по дням» и разбивки (модели, типы) тоже показывают осевшие суммы; счётчики запросов и токенов учитывают все строки, включая выполняющиеся.

Установка

Из npm:

dsh plugin --profile web add dsh-polza

Обновление до последней версии:

dsh plugin --profile web add dsh-polza@latest

Перезапустите dsh web. Плагин появится в футере сайдбара и в списке панелей.

Из GitHub — если нужна ветка main или конкретный коммит:

dsh plugin --profile web add github:XaPoHbomj/dsh-polza

Из локальной папки — для разработки:

dsh plugin --profile web add /path/to/dsh-polza
# или
dsh plugin --profile web add "link:$PWD"

Для разработки:

pnpm install
pnpm run build     # собирает lib/client.js
pnpm run watch     # пересобирает client при изменениях

Host-часть читается напрямую из src/host, перезапуск нужен только после её изменений. Client-часть подхватывается HMR после пересборки.

Ключ

Плагин не хранит ключ сам. Он разрешает ссылку через ctx.credentials:

# ~/.dsh/.credentials.yaml
version: 1
refs:
  POLZA_API_KEY: pza_...

Порядок источников стандартный для DSH: сохранённый файл, окружение запуска, .env проекта, ~/.dsh/.env. Ключ остаётся на хосте и никогда не попадает в браузер; в ответах и логах его нет.

Если нужен отдельный ключ только для статистики, заведите, например, POLZA_STATS_KEY и укажите его в конфиге.

Конфигурация

Строка плагина в профиле:

- id: polza
  name: dsh-polza
  config:
    apiKeyRef: POLZA_API_KEY
    refreshSeconds: 60
    lowBalanceThreshold: 100
    criticalBalanceThreshold: 20
    historyMaxPages: 100

Поле	По умолчанию	Смысл
apiKeyRef	POLZA_API_KEY	имя ссылки в credential-хранилище
apiBaseUrl	https://polza.ai/api	базовый URL Polza API
routePrefix	/polza/api	префикс read-only роутов
refreshSeconds	60	период автообновления панели и чипа, TTL кэша
lowBalanceThreshold	100	жёлтый порог баланса, ₽
criticalBalanceThreshold	20	красный порог баланса, ₽
historyMaxPages	100	сколько страниц по 100 записей читать для агрегатов
requestTimeoutMs	15000	таймаут одного запроса к Polza
allowRemote	false	разрешить роуты не только с loopback

Поля refreshSeconds, lowBalanceThreshold, criticalBalanceThreshold и historyMaxPages помечены как живые: их можно менять на странице Plugins → Polza без перезапуска. Остальные поля применяются после перезапуска профиля.

historyMaxPages ограничивает стоимость агрегатов. Если генераций за период больше, панель показывает «частично», а точный итог берёт из сводки ключа. Увеличение значения даёт более полный график и разбивку ценой большего числа запросов к Polza. Точный итог из сводки ключа действует только без фильтров: фильтры типа запроса, статуса или модели сужают выборку, и для них расход считается по загруженной истории.

Локальный кэш истории

Завершённые и упавшие генерации не меняются, поэтому плагин сохраняет нормализованные строки в локальный JSON-кэш:

~/.dsh/cache/dsh-polza/<fingerprint>.json

<fingerprint> — первые 20 символов SHA-256 от значения API-ключа. Сам ключ в файл не попадает. При следующем открытии периода плагин загружает только первую страницу истории (чтобы увидеть новые запросы), а остальное берёт из кэша. Это убирает повторную загрузку тысяч записей при переключении «Неделя / Месяц» и после перезапуска DSH.

• completed и failed считаются неизменными и кэшируются. pending участвует в таблице, графиках и итогах с текущими (возможно неполными) данными и перечитывается: первая страница — при каждом открытии периода, «застрявшие» строки на старых страницах — по id, не чаще раза в 2 минуты и не более 25 за проверку. Кнопка «Обновить» сбрасывает этот лимит и перечитывает их сразу.
• Файл ограничен 60 000 строк и хранит записи не старше 180 дней.
• Ошибка записи кэша не ломает панель: плагин просто работает без него.
• Смена ключа автоматически переключает кэш на новый fingerprint.

Неофициальность

Это независимый open-source плагин. Он работает через публичный API Polza.ai, который не является стабильным контрактом: поля, лимиты и поведение могут измениться без предупреждения. Ни автор плагина, ни DeepSeek, ни Polza.ai не несут ответственности за возможные ошибки в отображении баланса или расхода. Сверяйте критичные суммы с официальным кабинетом.

Безопасность

• Роуты только GET, без CORS-заголовков и с проверкой loopback.
• Ключ не логируется и не возвращается ни в одном ответе.
• GET /v1/key возвращает только маску ключа; она и показывается в шапке.
• Роуты read-only: плагин не пополняет баланс, не меняет ключи и лимиты.

Метаданные истории и лимит 10 000

Polza отдаёт в meta.total и meta.totalPages не больше 10 000 и 100 соответственно, даже когда записей больше. Это не жёсткий предел данных: страницы после сотой продолжают возвращать строки, пока не встретится неполная или пустая страница. Плагин больше не доверяет totalPages и читает историю до фактического конца (в пределах historyMaxPages).

При этом /v1/history/generations с API-ключом показывает только генерации этого ключа. Если в кабинете Polza счётчик больше, разница обычно приходится на другие ключи, площадку или веб-использование — по API-ключу они недоступны. Для истории всего аккаунта нужен JWT личного кабинета, который плагин сознательно не использует.

Лицензия

MIT. См. LICENSE.

Ограничения

• Polza не отдаёт статистику по всем ключам аккаунта с API-ключом; для этого нужен JWT личного кабинета, которого плагин сознательно не использует.
• available может быть меньше amount из-за резерва под выполняющиеся запросы и лимитов ключа.
• Агрегаты по моделям и график строятся по загруженной части истории; точные итоги периода — по /v1/key.