Понятия

Интеграция#

Интеграция — то, что вы собрали в Настройках: название, адрес (slug), набор типизированных полей и то, как они показываются на островке (индикатор, строка плашки, карточка). Структура интеграции статична: скрипт присылает значения, но не может добавить поле, кнопку или элемент сверх того, что вы настроили. Одна интеграция даёт ровно один индикатор и одну строку плашки на островке — если нужно две строки, это две отдельные интеграции.

Выключенная интеграция отвечает на запись 409 integration_disabled и ничего не показывает; конфигурация и токен при этом сохраняются.

Slug (адрес)#

Slug — то, как скрипт находит интеграцию: /v1/integrations/{slug}/…, sparku push {slug} …. Правила:

• строчные латинские буквы, цифры и дефис;
• начинается с буквы или цифры, не заканчивается дефисом;
• не длиннее 32 символов.

Примеры годных slug: deploy, build, server, home-server. При импорте .sparku и совпадении адреса SparkU сам подбирает свободный: deploy → deploy-2.

Токен#

У каждой интеграции свой токен, выпущенный при её создании. Он хранится в Keychain и не защищает от других процессов вашей учётной записи — они и так имеют доступ к сокету. Его задача — адресация, защита от опечаток и чужих скриптов, а также выборочный отзыв доступа перевыпуском токена.

Где взять. Настройки SparkU → Свои интеграции → нужная интеграция → раздел «Подключение»: строка export SPARKU_TOKEN_<АДРЕС>=… и готовые примеры кода.

Как передавать. Заголовком Authorization: Bearer <токен> в каждом запросе.

Порядок поиска в CLI (sparku пробует по очереди, пока не найдёт непустое значение):

1. --token <токен>
2. --token-file <путь>
3. переменная окружения SPARKU_TOKEN_<АДРЕС> (адрес — заглавными буквами, дефисы → _; например для home-server — SPARKU_TOKEN_HOME_SERVER)
4. переменная SPARKU_TOKEN
5. переменная SPARKU_TOKEN_FILE (путь к файлу с токеном)

SPARKU_TOKEN без суффикса адреса удобен, когда скрипт пишет в одну интеграцию; SPARKU_TOKEN_<АДРЕС> — когда в несколько сразу.

Поля#

Поле — именованный типизированный слот: ключ (progress, cpu), тип (типы полей) и подпись. Ключ поля — строчные латинские буквы, цифры и _, начинается с буквы, не длиннее 32 символов (это же имя переменной окружения SPARKU_FIELD_<КЛЮЧ> для shell-действий кнопок, поэтому дефис в ключе не допускается). У интеграции не больше 32 полей.

Запись полей — всё или ничего: если хоть одно значение не проходит проверку, POST …/fields отклоняет весь запрос, и на островке не оказывается наполовину обновлённого состояния.

Островок: индикатор, строка, карточка#

Индикатор (свёрнутый островок, слот 28 pt)#

По одному на интеграцию. Стили:

Стиль	Что показывает	Источник
Значок	статичный SF Symbol	—
Кольцо	прогресс-кольцо со значком или числом внутри	поле progress или number с min/max
Значение	короткая строка до 4 символов	text, number, progress, state, bool
Эквалайзер	анимация как у «Медиа»	поле bool включает движение
Крутилка	вращающийся индикатор	поле bool включает вращение

Поле state можно назначить дополнительно (stateField) — его значение подменяет значок, цвет и анимацию индикатора, не меняя его тип.

Строка плашки (одна на интеграцию)#

Стиль	Что показывает	Источник
Текст	шаблон {title} · {progress}	любые поля через {ключ}
Таймер	живой отсчёт	поле time
Шкала	подпись и мини-полоса	поле progress или number с min/max
Аватары	стек кружков с инициалами, «+N» сверх трёх	поле list

Шаблон строки ({ключ}): подставляет значение в виде по умолчанию для типа поля. {{ и }} — литеральные скобки, форматных спецификаторов нет. Вид по умолчанию: число — до двух знаков после точки плюс единица (21°C, 120 ms), прогресс — 43%, состояние — его подпись, время — отсчёт до момента или время с момента (4:59, 1:02:03), список — число строк, булево — «да»/«нет». Нет значения — прочерк (—).

Карточка (раскрытый островок)#

Собирается из шаблона со слотами — свободной сетки нет, чтобы визуальный ряд оставался единым со встроенными интеграциями.

Шаблон	Прообраз	Слоты / поля
Значение	Валюта	главное (number/progress/text), подпись
Статус	агенты	главное (state), подпись, «с какого момента» (time)
Прогресс	Pomodoro	главное (progress/number), подпись, отсчёт (time)
Таймер	Pomodoro	главное (time), подпись, кольцо (progress)
Шкалы	Монитор ресурсов	2–4 поля progress/number (с min/max) рядом
Лимит	Claude Code	быстрое окно (progress), медленное окно (progress), подпись
Метрики	агенты	2–4 поля text/number/progress/state/bool/time колонками
Список	Календарь, Todo	одно поле list
Сейчас	Медиа	заголовок (text, обязательно), подпись, обложка (image), шкала (progress)
График	—	одно поле number — рисуется по накопленной истории

У карточки есть общая шапка и ряд из 0–3 элементов управления. Карточка может запрашивать обычную или широкую ширину (как встроенные интеграции), и подходящий компактный вариант.

Элементы управления и их действия#

Элемент — кнопка, кнопка-капсула, тумблер (управляет полем bool) или меню (выбирает значение поля state). До трёх на карточку. Что делает нажатие — решает человек в редакторе, а не скрипт:

Действие	Что происходит
event	посылает событие слушателям GET …/events / sparku listen; без слушателя элемент неактивен
url	открывает ссылку, файл или приложение (адрес — статический или {поле})
shell	выполняет команду; значения полей передаются только через переменные окружения SPARKU_FIELD_<КЛЮЧ>, никогда не подставляются в текст команды
shortcut	запускает команду приложения «Команды» по имени

Слушатель получает событие о любом нажатии независимо от того, какое действие настроено сверх этого.

Приоритет#

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

• Низкий
• Обычный — наравне со встроенными интеграциями SparkU (по умолчанию)
• Высокий — выше встроенных

При равном приоритете побеждает заявка, поданная последней. Обновление уже поданной заявки не выдвигает её вперёд: модуль, который раз в секунду сообщает прогресс, не отбирает дорожку у того, кто заявился после него.

Срок жизни значений (TTL)#

Значения полей живут только в памяти и не переживают перезапуск SparkU — конфигурация интеграции при этом сохраняется всегда. По умолчанию значения живут до перезапуска SparkU или до явного sparku end; интеграция может задать свой срок, а конкретный запрос — переопределить его параметром ?ttl=:

POST /v1/integrations/deploy/fields?ttl=5m
POST /v1/integrations/deploy/fields?ttl=90

ttl — число секунд или 5m / 1h30m (те же единицы, что у времени полей), не больше 7 дней. Пустой или отсутствующий параметр — срок из настроек интеграции. Каждая новая запись отсчитывает срок заново.

sparku push поддерживает тот же параметр флагом --ttl (см. CLI).

Привязка к процессу#

Срок не спасает от упавшего скрипта: он успел написать «Деплой 40 %» и умер, а островок показывает это до конца срока. Привязка решает это иначе — значения живут, пока жив процесс:

POST /v1/integrations/deploy/fields?bind=process   # процесс, который прислал запрос
POST /v1/integrations/deploy/fields?bind=4211      # процесс с этим PID
POST /v1/integrations/deploy/fields?bind=none      # снять привязку

Процесс завершился — значения снимаются сразу, как от sparku end. Привязка остаётся и у следующих записей без bind; новая bind её заменяет. Срок жизни при этом тоже действует: что наступит раньше.

bind=process — для программ, которые сами держат соединение (скрипт на Python, сервис на Node). curl и sparku завершаются сразу после запроса, поэтому им нужен PID скрипта: в shell это ?bind=$, а sparku push --bind подставляет его сам.

Notify-ограничение#

POST …/notify (вспышка + строка на несколько секунд) можно вызывать не чаще раза в 2 секунды на интеграцию. Более частый вызов получает 429 too_many_notices с заголовком Retry-After. Ограничение не связано с записью значений через fields — она принимается без ограничений, на экран просто попадает не чаще кадра.

История чисел#

Для графика (шаблон карточки «График») и тренда SparkU копит историю каждого числового поля: не больше одной точки в секунду (запись внутри той же секунды заменяет последнюю точку), 120 точек на поле, только в памяти — история пропадает вместе со значениями при перезапуске SparkU.