OpenCode Go Limits — виджет для KDE Plasma

Лимиты OpenCode Go (5 часов / день / неделя / месяц) на панели KDE Plasma или на рабочем столе. Браузер не нужен, root не нужен.

Переписан с Windows-виджета на нативный Plasma 6 (QML). Пороги, цвета и тексты — как в оригинале. Автозапуск, «поверх всех окон» и запоминание позиции окна отданы штатным механизмам KDE — в порте их нет.

Возможности

• Четыре полосы — 5 часов, день, неделя, месяц: процент, полоса, обратный отсчёт до сброса.
• Дневная норма (/api/usage/cost-by-day) — месячный лимит / 31. Расход с полуночи виджет забирает с сервера (считаются только модели Go, бесплатные Zen стоят $0), так что число одно на всех ПК и дни локально никто не считает. Перерасход виден как есть: 137%, 200%.
• Цвета берутся из темы Plasma: зелёный до 60%, жёлтый 60–85%, красный от 85%.
• Опрос раз в N минут (по умолчанию 5), плюс кнопка ручного обновления.
• Данные общие на все экземпляры: обновил в одном месте — через ~3 секунды подтянулось везде, включая панель и рабочий стол.
• Уведомление KDE, когда выбранные окна проходят порог (по умолчанию 85%, по умолчанию выбраны только 5 часов). Одно на все экземпляры за окно сброса.
• На панели — компактная цифра: окно для значения и цвета выбирается в настройках. На рабочем столе — полная версия со всеми полосами.
• Настройки — штатным диалогом Plasma.

Требования

• KDE Plasma 6 (проверено на 6.6.4)
• python3, только стандартная библиотека
• tail из coreutils — им виджет читает общий журнал
• Вход в opencode (opencode auth login): токен и организация лежат в ~/.local/share/opencode/opencode.db. Лимиты берутся из консоли OpenCode, ключ opencode-go из auth.json не используется.

Установка (без root)

./install.sh

Кладёт пакет в ~/.local/share/plasma/plasmoids/org.opencode.limits/, файл уведомлений — в ~/.local/share/knotifications6/. Дальше добавьте виджет: правый клик по панели или рабочему столу → «Добавить виджеты» → OpenCode Go Limits.

Удаление:

./uninstall.sh

Как это работает

любой экземпляр ──раз в N минут──> backend.py ──HTTPS──> opencode.ai/console
                                        │                              ├─ /api/go/status (окна 5ч/нед/мес)
                                        │                              └─ /api/usage/models (расход дня с полуночи)
                                        ├─ читает токен и организацию из opencode.db
                                        ├─ пишет строку JSON в общий журнал usage.log
                                        └─ решает, кому слать уведомление (--threshold)

все экземпляры ──раз в 3 с──> tail -n 1 usage.log ──> рисуют полосы и отсчёт

Синхронизация — это и есть общий журнал: ответ любого экземпляра попадает в usage.log последней строкой, остальные её подбирают. Кнопка «Обновить» и отсчёты до сброса в итоге одинаковые везде. Запрашивает тот экземпляр, у которого сработал таймер.

• package/contents/ui/main.qml — виджет: таймеры, вызов backend, чтение журнала, уведомления.
• package/contents/code/backend.py — вход из opencode.db, сеть, нормализация ответа, журнал, уведомления, тексты ошибок.
• package/contents/code/logic.js — чистая логика: пороги цвета, отсчёт, тексты, разбор JSON.
• package/contents/ui/UsageBar.qml — одна полоса прогресса.
• package/contents/ui/configGeneral.qml + contents/config/main.xml — настройки.
• package/contents/notifications/opencode-limits.notifyrc — событие для KNotification.

Журнал usage.log и метка notified живут рядом с backend.py и удаляются вместе с пакетом при ./uninstall.sh.

Что не перенесено из Windows-версии и почему

Windows	Plasma	Причина
autostart (реестр Run)	—	виджет живёт вместе с сессией Plasma, запускать нечего
topMost, «без рамки»	—	порядком окон и оформлением ведают панель и рабочий стол
Сохранение координат окна	—	позицию хранит сама Plasma

Настройки

Правый клик по виджету → «Настроить OpenCode Go Limits». В полной версии есть кнопка с шестерёнкой.

• Интервал обновления (мин) — 1…120.
• Уведомлять о превышении порога — вкл/выкл.
• 5 часов / день / неделя / месяц — какие окна уведомляют (по умолчанию только 5 часов).
• Порог, % — 50…100, один на все выбранные окна.
• Цвет панели по лимиту — 5 часов / день / неделя / месяц (по умолчанию месяц).
• Значение на панели — 5 часов / день / неделя / месяц (по умолчанию день).

Проверка работоспособности

Без виджета видно, что вход найден и консоль отвечает:

python3 package/contents/code/backend.py --test

Разработка

python3 tests/test_backend.py     # нормализация, тексты ошибок, вход, журнал, уведомления
node tests/logic.test.js          # цвет/отсчёт/тексты, разбор JSON

Жива ли синхронизация, проверяется вручную: запустите backend.py — его строка попадёт в общий журнал, и все виджеты обновятся в течение ~3 секунд.

python3 package/contents/code/backend.py

Нюанс с правками QML: запущенный апплет держит старый код в памяти. После ./install.sh перезапустите plasmashell. Удаление и повторное добавление виджета тоже помогает, но перезапуск надёжнее:

plasmashell --replace &

Диагностика

Симптом	Что делать
ошибка: токен входа отклонён (401)	запустите opencode, чтобы он обновил токен
ошибка: консоль не знает эндпоинт лимитов (404)	изменился API, нужно обновить backend.py
ошибка: OpenCode не настроен	не установлен opencode или нет opencode.db
ошибка: opencode не вошёл в аккаунт: нет токена	opencode auth login
ошибка: у аккаунта opencode нет организации	проверьте workspace в консоли
ошибка: Нужна подписка OpenCode Go: аккаунт без тарифа Go	оформите подписку на opencode.ai/go
ошибка: Токен входа opencode истёк	запустите opencode, чтобы он обновил токен
ошибка: backend.py не ответил вовремя	нет сети или запрос длится дольше 30 с
Виджет есть, но показывает «—»	запустите backend.py --test и посмотрите текст ошибки
Второй виджет не обновляется	проверьте, что оба виджета одной версии: kpackagetool6 --type Plasma/Applet --list
После правок виджета ничего не изменилось	перезапустите plasmashell: plasmashell --replace &

Производительность

Оригинал работает только на Windows, так что прямого «до/после» нет. Ниже — разбор по ресурсам и замеры новой версии.

Что изменено по сравнению с оригиналом:

Область	Windows-версия	Plasma-версия
Процессы	exe-лаунчер → скрытый powershell.exe → WinForms	всё внутри plasmashell, 0 постоянных процессов
Старт	распаковка скрипта на диск + загрузка .NET/WinForms	распаковывать нечего
Периодичность	таймер 5 мин (сеть) + таймер 30 с (перерисовка ~12 контролов)	таймер 5 мин (сеть) + опрос журнала раз в 3 с + пересчёт отсчёта раз в 30 с
Синхронизация виджетов	нет (у каждого экземпляра своё состояние)	общий журнал: обновление в одном месте видят все
Разбор данных	ConvertFrom-Json → дерево PSObject на каждое поле	один JSON.parse
Отрисовка	пересоздание/перерисовка контролов WinForms	прямоугольники в сцене Qt, меняется только ширина
Повторный запуск	мьютекс + FindWindow	не требуется (экземпляр один на контейнер)
Хранение настроек	свой config.json + ручная запись	штатный конфиг Plasma
Смена ключа	требовался перезапуск (ключ кэшировался)	подхватывается на следующем обновлении

Замеры (этот ПК, Plasma 6.6.4, X11):

backend.py (вход + HTTPS + JSON):        ~0.60 с на вызов (раз в 5 минут)
RSS plasmashell без виджетов:            310 680 kB
RSS plasmashell с двумя виджетами:       311 412 kB   (+0.7 MB на два, ≈0.4 MB на экземпляр)
CPU plasmashell (45 с):                  0.067% без виджетов / 0.089% с виджетами

Сетевой запрос интерфейс не блокирует: backend.py стартует асинхронно через движок executable. Опрос журнала — короткоживущий tail -n 1 на единицы миллисекунд, постоянных процессов виджет не создаёт.

Методика: виджеты убирались и добавлялись через Plasma Scripting API, RSS брался из /proc/<pid>/status, CPU — из utime+stime за 45 секунд. Разница в CPU (+0.02%) — в пределах собственных колебаний plasmashell; в неё входит и опрос журнала (2 экземпляра × 15 запусков tail за 45 с). Ещё ~21 MB разово уходит на загрузку QML-модулей (plasma5support, KNotification) при первом создании виджета. В замере выше модули уже были загружены, поэтому видна только разница по экземплярам. Обновление данных — один процесс python3 на 0.6 с раз в 5 минут.

Внешние зависимости и лицензии

Доустанавливать ничего не нужно — всё уже есть в системе.

Компонент	Версия	Лицензия	Роль
KDE Plasma / plasmashell	6.x	GPL-2.0-or-later	среда выполнения виджета
Qt 6 (QtQuick, QML)	6.x	LGPL-3.0 / GPL	графика и JS-движок
KDE Frameworks 6 (Kirigami, KNotification, Plasma5Support)	6.x	LGPL-2.1-or-later	UI-компоненты, уведомления, запуск backend
Python 3 + стандартная библиотека	3.x	PSF-2.0	backend.py (json, urllib, sqlite3, fcntl)
coreutils (tail)	9.x	GPL-3.0-or-later	чтение общего журнала
Node.js	24.x	MIT	только для tests/logic.test.js (не нужен для работы)

Сам проект — под лицензией MIT.