Rina Assistant

Плагины

Плагин добавляет Рине умения: отвечает на фразы, показывает свою вкладку и плитку на главном экране, объявляет инструменты для ядра. Здесь всё API версии 4: что писать, когда это вызывается и какие у плагина права и пределы.

Собрано из plugins/api.py (коммит 2f25107), 2 ноября 2026. Таблицы собраны из кода программы: поля, сигнатуры, умолчания, сроки и пределы взяты у самих классов и модулей, а пример в конце запускается при каждой сборке.

  • API 4
  • Схема вкладки 2
  • Python 3.12
Разделы
  1. Коротко
  2. Первый плагин
  3. Манифест
  4. Класс плагина
  5. Как ядро зовёт плагин
  6. Контекст: self.ctx
  7. Инструменты
  8. Разрешения
  9. Вкладка
  10. Плитка на главном экране
  11. Настройки
  12. Свои модули и зависимости
  13. Установка и обновление
  14. Совместимость
  15. Провод
  16. Граница
  17. Проверка и неполадки
  18. Пример целиком
  19. Примеры
  20. Плагины в поставке

Коротко

Плагин — папка с двумя файлами: plugin.json описывает плагин, в main.py лежит класс-наследник Plugin. Каждый включённый плагин ядро запускает отдельным процессом и обращается к нему само: передаёт фразы, спрашивает вкладку и плитку, передаёт нажатия.

С компьютером плагин работает через объявления. Инструменты с разрешениями уходят в реестр ядра, и там их проверяют так же, как встроенные: разрешения, подтверждение, запись в журнал. Разрешения перечислены в манифесте до первого запуска. Вкладка и плитка — данные, их рисует оболочка, поэтому в плагине нет ни строчки кода интерфейса.

Внутри своего процесса плагин остаётся обычным кодом на Python с правами пользователя. Где проходит граница, сказано в разделе «Граница».

Версия API4; ядро загружает версии от 4 до 4
Схема вкладкиверсия 2
Pythonвстроенный 3.12 ядра, без pip
Срок ответа10 с на вызов, 20 с на запуск

Первый плагин

Самый маленький пример отвечает на «привет». Вот он целиком: examples/plugins/greeter/.

plugin.json

{
  "id": "greeter",
  "name": "Приветствие",
  "version": "1.0.0",
  "author": "NeuroSync Foundry Team",
  "description": "Отвечает на приветствия. Скажи «привет» — и я отвечу.",
  "icon": "👋",
  "entry": "GreeterPlugin",
  "api_version": 4
}

main.py

"""
A greeting.

An example of the **smallest** plugin: no tools, no page, no permissions —
only phrase parsing. And so it should be: declaring a tool for the sake of
"hello" is pointless, and the API requires declaring nothing.
"""
from plugins.api import Plugin


class GreeterPlugin(Plugin):
    """A simple greeting plugin — a demonstration of on_command."""

    def on_enable(self):
        self.log("Плагин приветствия готов")

    def on_command(self, text):
        low = text.lower()
        if any(w in low for w in ("привет", "здравствуй", "хай", "hello")):
            name = self.ctx.get_setting("user_name", "друг")
            self.respond(f"Привет, {name}! Чем могу помочь?")
            return True
        if "пока" in low or "до свидания" in low:
            self.respond("До встречи! 🌸")
            return True
        return False
  1. Поставь папку или архив .zip из раздела плагинов в программе или положи папку в %APPDATA%\RinaAssistant\plugins\. Там лежат установленные плагины: обновление и удаление программы их не трогают.
  2. Включи плагин там же. Код запускается при включении, до этого ядро читает только манифест.
  3. Скажи или напиши мне «привет».

Если плагин не включается, причина написана в списке плагинов рядом с ним, а подробности — в его журнале.

Манифест

plugin.json в кодировке UTF-8. Ядро читает его без запуска кода, поэтому список плагинов виден до включения.

ПолеОбязательноПо умолчаниюЧто это
idда—Имя плагина. Настоящим именем служит имя папки: при установке папка называется по этому полю, а при загрузке ядро берёт имя папки, что бы ни стояло здесь. Отсюда же префикс инструментов plugin.<id>..
nameда—Как плагин называется в списке плагинов.
versionнет"1.0.0"Версия твоего плагина, для пользователя. Ядро её не сравнивает.
authorнет"unknown"Кто написал.
descriptionнет""Одна-две строки в списке плагинов: что он делает и как его позвать.
entryнет""Имя класса в main.py. Пусто — ядро возьмёт первый найденный класс-наследник Plugin; с именем надёжнее.
iconнет"🧩"Значок в списке и на вкладке: символ или эмодзи.
api_versionнет1Версия API, под которую написан плагин. Не указали — считается 1, и такой плагин не загрузится.
permissionsнет[]Что плагину нужно от компьютера: имена из каталога разрешений. Инструмент может просить только то, что перечислено здесь.
sendsнет""Что уходит наружу и кому — одна фраза для пользователя. Карточка плагина показывает её отдельной строкой до включения. Плагин с network.external без неё помечен «Выходит в интернет — что именно уходит, плагин не сообщил».

Имя папки при установке проверяется: оно должно подходить под ^[A-Za-z0-9_][A-Za-z0-9._-]*$ и не быть именем устройства Windows (con, prn, aux, nul, com1…com9, lpt1…lpt9, в том числе с расширением). Если собираетесь импортировать свои модули (см. ниже), бери имя, которое годится в Python: латиница, цифры, подчёркивание.

Манифест примера из раздела «Пример целиком»:

{
  "id": "shopping",
  "name": "Покупки",
  "version": "1.0.0",
  "author": "Твоё имя",
  "description": "Список покупок: голосом, на своей вкладке и плиткой на главном экране.",
  "icon": "🛒",
  "entry": "ShoppingPlugin",
  "api_version": 4,
  "permissions": []
}

Класс плагина

Класс наследует plugins.api.Plugin и переопределяет нужные хуки; остальные можно не трогать. Конструктор получает контекст. Если переопределяешь __init__, передай контекст дальше: super().__init__(context). После него доступны self.ctx и self.manifest.

Хуки

ХукКогда зовутЧто вернуть
on_enable()Плагин включили: процесс поднят, плагин представился ядру.Ничего. Здесь заводят своё: поток, кэш, первый запрос.
on_disable()Плагин выключают в программе. Когда я закрываюсь, этот хук не зовётся: процесс получает plugin.shutdown и завершается.Ничего. Закрой всё, что плагин успел открыть.
on_command(text: str) -> boolПришла фраза. Плагины слышат её раньше встроенных команд и своих команд пользователя, по очереди в алфавитном порядке id.True, если фраза твоя: дальше её никто не разбирает. False — фраза идёт дальше.
on_event(name: str, data: dict = None)Сейчас не зовётся: ядро 4.0 не рассылает плагинам событий. В плане это задача 4.0-H09.Ничего.
tools()Один раз при запуске плагина: описание инструментов уходит ядру вместе с приветствием. Потом при каждом вызове инструмента, чтобы найти его run.Список PluginTool. Держи метод быстрым и без побочных действий.
page()Пользователь открыл вкладку плагина, и после каждого on_action.Список элементов страницы. Вкладка появляется, если метод переопределён.
home()Оболочка рисует главный экран.Список элементов плитки. Пусто или None — плитки нет.
on_action(action: str, value=None)Нажата кнопка или отправлено поле на твоей вкладке или плитке.Ничего. После вызова ядро само спросит page() заново.
settings_schema()Её читает self.setting(), чтобы найти значение по умолчанию.Список полей из plugins.settings_spec.

Ошибка внутри хука плагин не роняет: ядро получает ответ с ошибкой, а трассировка попадает в журнал плагина.

Поля класса

ПолеПо умолчаниюЧто задаёт
page_title—Заголовок вкладки. Не задан — имя из манифеста.
page_icon—Значок вкладки. Не задан — значок из манифеста.

Удобные методы

МетодЧто делает
log(message)То же, что self.ctx.log.
respond(text)То же, что self.ctx.respond.
setting(key, default=None)Значение настройки: сохранённое, иначе умолчание из settings_schema(), иначе default.

Как ядро зовёт плагин

Каждый включённый плагин — отдельный процесс python -u plugins/host.py <папка> на интерпретаторе ядра. Разговор идёт по stdin и stdout кадрами того же формата, что у оболочки с ядром (см. «Провод»).

ЭтапЧто происходитСрок
ОбнаружениеЯдро читает манифесты. Код не запускается.—
ВключениеПоднимается процесс, плагин отвечает на plugin.hello, потом зовётся on_enable.20 с на приветствие
РаботаФразы, вкладка, плитка, нажатия, инструменты.10 с на каждый вызов
Выключениеon_disable, затем plugin.shutdown и завершение процесса.3 с и 2 с
Мой выходТолько plugin.shutdown.2 с

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

Фразы

Фраза приходит к плагинам раньше, чем к своим командам пользователя, встроенным действиям и языковой модели. Ядро спрашивает включённые плагины по очереди в алфавитном порядке id; первый, кто вернул True, забирает фразу. Отсюда два правила:

  • Бери только своё. Плагин, который откликается на любое «открой», перебьёт встроенный запуск программ. Узкий набор начальных слов, как у convert («переведи», «пересчитай»), безопаснее поиска слова внутри фразы.
  • Отвечай быстро. Каждая фраза — поход в твой процесс, и пока плагин думает, я молчу. Решение «моя или нет» должно занимать миллисекунды.

Вернули True и ничего не сказали — я промолчу. Ответ произносит self.respond(...).

Потоки

Запросы ядра выполняются в одном рабочем потоке, по одному: пока идёт долгий вызов, следующие ждут в очереди, и срок у них общий. Долгую работу (сеть, диск) делай в своём потоке и отвечай из памяти, как rates. Из своего потока можно звать ctx.respond, ctx.log, ctx.notify и настройки: отправка в процессе защищена замком.

Вывод и журнал

stdout процесса занят проводом, поэтому хост перенаправляет print в stderr. Всё, что плагин пишет в stderr, попадает в журнал плагина, последние 100 строк. В мой журнал этот вывод не идёт. Для сообщений о работе есть ctx.log.

Состояние

Поля экземпляра живут, пока жив процесс. Выключение, сбой или мой перезапуск их стирают. Всё, что должно остаться, храни в настройках.

Контекст: self.ctx

Через контекст плагин обращается к ядру. Других дверей нет: плагин не видит соседей, окно программы и реестр.

МетодЧто делаетКак идёт по проводу
log(message: str)Строка в журнал плагина. Её видно на странице плагина в программе.событие plugin.log, без ожидания
respond(text: str)Этот текст я скажу и покажу.событие plugin.respond, без ожидания
get_setting(key: str, default=None)Твоя настройка по ключу, или default.запрос plugin.setting.get; ждёт ответа до 5 с
set_setting(key: str, value)Записать настройку. Значение должно переживать JSON: строки, числа, bool, списки, словари.событие plugin.setting.set, без ожидания
notify(title, message)Уведомление из трея: заголовок и текст.событие plugin.notify, без ожидания
get_secret(name: str)Твой секрет по имени — токен, пароль, — или None. Хранится в диспетчере учётных данных Windows, не в настройках и не в экспорте; видны только твои.запрос plugin.secret.get; ждёт ответа до 5 с
set_secret(name: str, value: str) -> boolСохранить секрет: имя — буквы, цифры, ., -, _, до 64; значение — до 2560 байт. False — сохранить некуда.запрос plugin.secret.set; ждёт ответа до 5 с
delete_secret(name: str) -> boolЗабыть секрет. True, если он был.запрос plugin.secret.delete; ждёт ответа до 5 с

get_setting — единственный вызов, который ждёт ответа. Если ядро не ответило за 5 с, вернётся последнее значение, которое плагин читал или писал сам, иначе default.

Инструменты

Инструмент — действие, которое ядро выполняет от имени плагина. Плагин описывает его и ждёт вызова; когда звать, решает ядро.

Инструмент плагина — блок конструктора команд. Человек ставит его в свою команду рядом с другими шагами, и вызов идёт через реестр: аргументы проверяются, вызов пишется в журнал от имени команды. Инструмент с reads=True только отвечает: его ответ звучит, а шаг «Узнать» кладёт его под имя, чтобы вставить во фразу, — поэтому пиши такой ответ так, чтобы он вставал в предложение. Блоком не становится инструмент с confirm_required=True и инструмент с обязательным аргументом, который нельзя набрать руками. Фразой инструмент пока не вызывается: голосом плагин работает через on_command, вызов моделью — в 5.0.

PluginTool

ПолеОбязательноПо умолчаниюЧто это
nameда—Короткое имя. В реестре ядра инструмент живёт как plugin.<id>.<name>.
summaryда—Одна строка: что инструмент делает.
runнет—Функция run(args), её вызывает ядро. args — словарь уже проверенных аргументов.
paramsнет[]Аргументы: кортеж Param из core.tools.
permissionsнет[]Какие разрешения нужны. Каждое должно быть в манифесте.
confirm_requiredнетfalseСпрашивать подтверждение перед каждым вызовом.
readsнетfalseИнструмент только отвечает и ничего не меняет. Его ответ звучит, когда команда его выполняет, а шаг «Узнать» кладёт ответ под имя для подстановки во фразу.
titleнет""Название блока в конструкторе команд, два-три слова. Пусто — берётся summary.

Param

Те же аргументы, что у встроенных инструментов. Реестр проверяет их до вызова: лишний аргумент, неверный тип, число вне границ или значение не из choices до плагина не дойдут.

ПолеОбязательноПо умолчаниюЧто это
nameда—Имя аргумента, ключ в args.
typeда—Тип: string, integer, number, boolean, array, object.
descriptionда—Что это за аргумент. Обязательное поле: без описания Param не создаётся.
requiredнетtrueОбязателен ли аргумент.
choicesнет[]Допустимые значения. Пусто — любые.
minimumнет—Нижняя граница для чисел.
maximumнет—Верхняя граница для чисел.
defaultнет—Значение, если аргумент не пришёл.
labelsнет[]Как назвать человеку каждый из choices, в том же порядке. Без них конструктор покажет сами значения.

Вызов и ответ

  • run(args) возвращает текст ответа. Через процесс уходит строка: любое значение ядро приведёт к str, None станет пустой строкой.
  • Исключение внутри run превращается в неудачу инструмента с кодом internal, трассировка — в журнал плагина.
  • Отказать словами — raise ToolFailed("Город для погоды не задан.") из plugins.api: пользователь услышит эту фразу, вызов будет неудачей в журнале, трассировки не будет.
  • Две формы одного ответа — словарь {"say": …, "value": …}: say звучит вслух, value шаг «Узнать» вставляет во фразу пользователя. Строка служит обеими формами.
  • vary(*варианты) из plugins.api выбирает один из вариантов фразы и не повторяет последний. Первый вариант — самый простой: при RINA_PLAIN_SPEECH=1 (так работают проверки) выбирается всегда он.
  • confirm_required=True — ядро спросит пользователя перед каждым вызовом. Для опасного разрешения это обязательно: без подтверждения такой инструмент не создаётся.
  • Список инструментов ядро узнаёт при запуске. Изменили tools() — выключи и включи плагин.

Разрешения

Каталог разрешений один на ядро и плагины (core/permissions.py). Плагин перечисляет нужное в манифесте, а инструмент — в своём поле permissions.

ИмяНазваниеЧто разрешаетОпасноеПлагину
process.launchЗапуск программОткрывать приложения и папки, которые ты называешь.нетда
system.mediaГромкость и воспроизведениеМенять громкость и управлять плеером.нетда
system.lockБлокировка экранаБлокировать рабочий стол по команде.нетда
system.displayЯркость экранаДелать экран ярче или темнее по команде.нетда
system.windowsОкна программСворачивать, разворачивать и закрывать окна программ по команде. Окно закрывается так же, как крестиком: о несохранённом программа спросит сама.нетда
system.powerВыключение компьютераВыключать, перезагружать и усыплять компьютер. Каждое такое действие подтверждается отдельно.даникогда
screen.captureСнимок экранаДелать снимок экрана и сохранять его в «Изображения».нетда
network.localОбращение к локальным службамСпрашивать языковую модель, работающую на этом компьютере.нетда
network.externalВыход в интернетОткрывать поиск в браузере и обращаться к службам вне этого компьютера.нетда
files.readЧтение файловЧитать файлы, на которые ты укажешь.нетда
files.writeЗапись файловСоздавать и изменять файлы.даникогда
screen.readЧтение содержимого экранаВидеть, что происходит на экране. Понадобится, когда я научусь работать с компьютером.даникогда (заведено к 5.0)
input.synthesizeУправление мышью и клавиатуройНажимать и печатать от твоего имени. Понадобится, когда я научусь работать с компьютером.даникогда (заведено к 5.0)
  • То, что плагину не выдаётся, и имена не из каталога ядро отбрасывает и пишет в журнал плагина: «Не выдано разрешений: …».
  • Инструмент, которому нужно не выданное или не перечисленное в манифесте, не заводится вовсе. В журнале будет «Инструмент «имя» не заведён: просит […]».
  • Опасное разрешение требует confirm_required=True.

Разрешения описывают инструменты. Код плагина в своём процессе может обратиться к сети и без network.external; об этом раздел «Граница».

Вкладка

page() описывает вкладку плагина списком элементов из plugins.page_spec. Рисует их оболочка, какая бы она ни была. Вкладка появляется, если класс переопределил page(); заголовок и значок берутся из page_title и page_icon.

Схема смысловая. В ней нет полей о цвете, отступах и шрифте: плагин говорит «предупреждение» (Badge(..., "warn")), а как его показать, решает оболочка.

Элементы

ФункцияЧто это и что уходит оболочке
Title(text)
вид title
Заголовок раздела.
{"kind": "title", "text": "Покупки"}
Text(text)
вид text
Обычный текст.
{"kind": "text", "text": "Молоко, хлеб"}
Note(text)
вид note
Пояснение мельче и тише.
{"kind": "note", "text": "Обновлено в 9:40"}
Items(items)
вид items
Список строк.
{"kind": "items", "items": ["молоко", "хлеб"]}
Button(label, action, variant='normal')
вид button
Кнопка. Нажатие приходит в on_action(action); variant: normal или danger.
{"kind": "button", "text": "Очистить", "action": "clear", "variant": "danger"}
Input(action, placeholder='', value='', button='')
вид input
Поле ввода с кнопкой. Отправка приходит в on_action(action, введённый_текст); button — подпись кнопки.
{"kind": "input", "text": "Что купить", "action": "add", "variant": "Добавить", "value": ""}
Secret(action, placeholder='', button='')
вид secret
Поле для токена или пароля: набранное скрыто и приходит в on_action(action, введённое) один раз. Значения у поля нет — вернуть секрет на экран нельзя; хранить — через ctx.set_secret.
{"kind": "secret", "text": "Токен доступа", "action": "token", "variant": "Сохранить"}
Table(rows, headers=None)
вид table
Таблица: строки из ячеек и, если нужно, заголовки.
{"kind": "table", "items": [["USD", "1"]], "value": ["Код", "Курс"]}
Progress(value, text='')
вид progress
Полоса выполнения, value от 0 до 1; лишнее обрезается.
{"kind": "progress", "text": "Скачано 40 %", "value": 0.4}
Badge(text, variant='normal')
вид badge
Короткая метка состояния: normal, good, warn, danger.
{"kind": "badge", "text": "Готово", "variant": "good"}
Divider()
вид divider
Разделитель.
{"kind": "divider"}
Stat(value, caption='', icon='')
вид stat
Показатель для взгляда: значок, крупное значение и подпись под ним — для плитки главного экрана. Значок называется по смыслу (clear, rain, snow, dollar…), рисует его оболочка.
{"kind": "stat", "text": "+18°", "items": ["Ясно"], "variant": "clear"}
Card(children, title='')
вид card
Одна вещь целиком: заметка, результат, прибор. Заголовок необязателен.
{"kind": "card", "text": "Список"}
Group(children, title='')
вид group
Раздел страницы на одну тему: заголовок и то, что под ним.
{"kind": "group", "text": "Сегодня"}
Row(children)
вид row
Элементы рядом. На узком окне оболочка вправе поставить их столбиком.
{"kind": "row"}

Правила

  • Вкладка обновляется целиком: после каждого on_action ядро снова зовёт page(). Частичных обновлений нет, описывай текущее состояние.
  • Вложенность — не глубже 4 уровней, глубже оболочка обрежет с пометкой.
  • row в row не кладут.
  • Пустой контейнер не рисуется.
  • Незнакомый вид оболочка показывает заметно, с его именем: так плагин под более новую схему не теряет часть вкладки молча.
  • Всё описание вкладки уходит одним сообщением, а сообщение больше 1 МиБ ядро не примет и остановит плагин. Длинные списки режь.

Полное описание схемы — PAGE-SCHEMA-v2.

Плитка на главном экране

home() описывает плитку на главном экране теми же элементами, что и вкладку. Главный экран общий для всех плагинов, поэтому пустой ответ правилен для большинства из них.

  • На плитку попадают первые 4 элемента. Остальное обрезается, и оболочка знает, что плитка обрезана.
  • Плитку рисуют часто: всякий раз, когда пользователь приходит на главный экран. Собирай её из того, что уже знаешь. В сеть ходи по своему расписанию, в потоке.
  • На плитке могут быть поле и кнопки: их нажатия приходят в on_action, а плитка перерисовывается, когда оболочка снова рисует главный экран. Так сделан convert.
  • Есть ли у плагина плитка, ядро узнаёт один раз, при приветствии: по тому, переопределён ли home().

Настройки

Настройки плагина хранит ядро, в моём общем файле настроек, под ключом plugin_settings → id плагина. Поэтому они переживают сбой и перезапуск процесса, а плагину не нужно знать, где лежит файл.

  • self.ctx.get_setting(key, default) и self.ctx.set_setting(key, value) читают и пишут одно значение.
  • self.setting(key, default) вернёт сохранённое, иначе умолчание из settings_schema(), иначе default.
  • Значения проходят через JSON: кортеж вернётся списком, а объект не сохранится.

Панель настроек по схеме в 4.0 не строится. Ядро не спрашивает у плагина settings_schema(), и оболочке её не передаёт. Схема сейчас работает внутри плагина: из неё self.setting() берёт умолчания. Если пользователю нужно что-то менять, дай поле или кнопки на своей вкладке, как notes. В плане это задача 4.0-H08 на 4.0 Stable.

Поля схемы

ФункцияВидЧто это
Toggle(key, label, default=False, description='', icon='🔘')toggleПереключатель: да или нет.
Text(key, label, default='', description='', icon='✏️')textСтрока.
Choice(key, label, options, default=None, description='', icon='📋')choiceВыбор из списка options. Умолчание — первый вариант.
Slider(key, label, min=0, max=100, default=None, step=1, description='', icon='🎚️')sliderЧисло от min до max с шагом step. Умолчание — min.

Свои модули и зависимости

Плагин запускается из корня программы, и пакет plugins виден ему целиком. Свой модуль рядом с main.py импортируй через него: from plugins.convert.units import convert, как в convert. Для этого имя папки должно быть допустимым именем Python.

Доступны стандартная библиотека Python 3.12 и то, что установлено для ядра; core.tools.Param и plugins.* плагины используют открыто. Поля для зависимостей в манифесте нет, и pip во встроенном Python нет. Нужна небольшая библиотека на чистом Python — положи её в папку плагина и импортируй так же, через plugins.<папка>.

Внутренности ядра за пределами core.tools — не API: они меняются без предупреждения, а плагин, который на них опирается, сломается на следующем выпуске.

Установка и обновление

Ставить можно папку или архив .zip; в архиве плагин может лежать в корне или в одной вложенной папке. Перед копированием ядро проверяет:

  • есть plugin.json и main.py, манифест читается как JSON;
  • имя подходит под правило из раздела «Манифест», и папка ложится прямо внутрь папки плагинов;
  • имя не занято плагином из поставки;
  • архив распаковывается не больше чем в 50 МиБ: размер считается до распаковки.

Установка поверх плагина с тем же именем заменяет его папку целиком и выключает его. Новый код запускается только после того, как пользователь сам включит плагин снова: подложенный архив с чужим именем не наследует чужое согласие.

Обе установки пишутся в журнал безопасности.

Совместимость

Версия API растёт на несовместимых изменениях. Ядро загружает плагины с api_version от 4 до 4. Нижняя граница совпадает с текущей нарочно: плагин версий 1–3 отдавал готовый виджет Qt, а оболочку на C# такой виджет не нарисует.

Несовпадение не молчит. Пользователь увидит в списке плагинов одну из этих строк:

КогдаЧто написано
Плагин старшеПлагин написан под API 3, а нужна версия 4: страница описывается методом page(), а не create_page(). Обнови плагин.
Плагин новееПлагину нужна версия API 5, а я поддерживаю 4. Обнови меня.

Схема вкладки версионируется отдельно (сейчас 2). Новый вид элемента несовместимостью не считается: незнакомый вид оболочка обязана показать вместе с его именем.

Провод

Писать это руками не нужно, всё делает plugins/host.py. Раздел для тех, кто отлаживает плагин или хочет понимать, что происходит.

Кадр — четыре байта длины (big-endian) и JSON в UTF-8, тот же конверт, что у оболочки с ядром (протокол, §2–3). Кадр больше 1 МиБ ядро не читает и останавливает плагин.

Ядро → плагин

МетодЧто делает
plugin.helloПредставиться: манифест, версия API, есть ли вкладка и плитка, описание инструментов.
plugin.enableВызвать on_enable.
plugin.disableВызвать on_disable.
plugin.commandВызвать on_command(text); ответ — взята ли фраза.
plugin.eventВызвать on_event(name, data).
plugin.pageСобрать вкладку: page().
plugin.homeСобрать плитку: home().
plugin.actionВызвать on_action и вернуть вкладку заново.
plugin.callВызвать run инструмента по имени.
plugin.shutdownПопрощаться перед завершением процесса.

Плагин → ядро

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

МетодОткуда
plugin.respondctx.respond
plugin.logctx.log
plugin.notifyctx.notify
plugin.setting.getctx.get_setting; единственный запрос с ответом
plugin.setting.setctx.set_setting

На неизвестный метод любая сторона отвечает ошибкой: молчание ядро приняло бы за зависание.

Граница

Отдельный процесс — это не песочница. Плагин запускается тем же интерпретатором, с правами того же пользователя. subprocess, сеть и файлы внутри плагина работают.

Что разделение даёт на самом деле:

  • инструменты плагина проходят те же проверки, что встроенные: разрешения, подтверждение, журнал с именем плагина;
  • часть разрешений не выдаётся никогда, и инструмент, который их просит, не заводится;
  • обратиться к ядру плагин может только за пятью вещами из раздела «Провод»;
  • зависший или упавший плагин не забирает с собой меня и соседей.

Поэтому ставить чужой плагин — то же решение, что запустить скачанную программу: смотри, кто его написал. Угрозы этой поверхности разобраны в модели угроз: T-06, T-07, T-08, T-09, T-10.

Проверка и неполадки

В репозитории программы есть проверка плагинов:

python tools/test_plugins.py

Она поднимает настоящий менеджер, ставит плагин, включает его, просит вкладку, нажимает кнопку и убеждается, что сосед цел, когда один плагин завис.

Что видноПочему
Плагин не ответил на приветствие.Процесс не поднялся за 20 с: ошибка при импорте main.py (смотри журнал плагина) или тяжёлая работа на уровне модуля.
«Плагин не ответил за 10 с и был остановлен.»Хук работал дольше срока. Долгое — в поток.
Плагин упал.Процесс завершился сам: исключение вне хука, sys.exit, нехватка памяти.
Плагин прислал слишком большое сообщение…Вкладка или ответ больше 1 МиБ.
Плагин написан под API…Не указан или устарел api_version, см. «Совместимость».
Инструмент не заведёнОн просит разрешение, которого нет в манифесте или которое плагину не выдаётся.

Пример целиком

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

main.py

"""A shopping list: a phrase, two tools, a tab and a home tile."""
from core.tools import Param
from plugins.api import Plugin, PluginTool
from plugins.page_spec import Badge, Button, Card, Input, Items, Note, Row

#: Phrases the plugin takes. Narrow on purpose: plugins hear a phrase
#: before the built-in commands do.
OPENERS = ("добавь в покупки ", "в покупки ")


class ShoppingPlugin(Plugin):
    page_title = "Покупки"

    # --- the list lives in the plugin's settings, kept by the core ------
    def _items(self):
        return list(self.ctx.get_setting("items", []) or [])

    def _add(self, what):
        what = what.strip()
        if not what:
            return "Что добавить?"
        items = self._items()
        if what.lower() in (one.lower() for one in items):
            return f"«{what}» уже в списке."
        self.ctx.set_setting("items", items + [what])
        return f"Добавила «{what}»."

    def _clear(self):
        count = len(self._items())
        self.ctx.set_setting("items", [])
        return f"Список очищен, было {count}."

    # --- a phrase -------------------------------------------------------
    def on_command(self, text):
        low = text.lower().strip()
        for opener in OPENERS:
            if low.startswith(opener):
                self.respond(self._add(text.strip()[len(opener):]))
                return True
        return False

    # --- tools the core may call ----------------------------------------
    def tools(self):
        return [
            PluginTool(
                name="add",
                summary="Добавить строку в список покупок.",
                params=(Param("what", "string", "Что купить, например «молоко»."),),
                run=lambda args: self._add(str(args.get("what", ""))),
            ),
            PluginTool(
                name="clear",
                summary="Очистить список покупок.",
                confirm_required=True,
                run=lambda args: self._clear(),
            ),
        ]

    # --- the tab --------------------------------------------------------
    def page(self):
        items = self._items()
        return [
            Card([
                Items(items) if items else Note("Список пуст."),
                Input("add", placeholder="Что купить", button="Добавить"),
            ], title="Список"),
            Row([
                Badge(f"В списке: {len(items)}", "good" if items else "normal"),
                Button("Очистить", action="clear", variant="danger"),
            ]),
        ]

    def on_action(self, action, value=None):
        if action == "add":
            self._add(str(value or ""))
        elif action == "clear":
            self._clear()

    # --- the home tile: only when there is something to buy -------------
    def home(self):
        items = self._items()
        if not items:
            return []
        shown = ", ".join(items[:3]) + ("…" if len(items) > 3 else "")
        return [Card([Note(shown)], title=f"Купить: {len(items)}")]

Кнопка «Очистить» на вкладке стирает список сразу: пользователь нажал её сам. Инструмент clear просит подтверждение: его вызов может прийти не из рук пользователя.

Что уходит оболочке

Вкладка после «добавь в покупки молоко», поля «хлеб» и инструмента с «сыр», так, как её получает оболочка:

[
  {
    "kind": "card",
    "text": "Список",
    "children": [
      {
        "kind": "items",
        "items": [
          "молоко",
          "хлеб",
          "сыр"
        ]
      },
      {
        "kind": "input",
        "text": "Что купить",
        "action": "add",
        "variant": "Добавить",
        "value": ""
      }
    ]
  },
  {
    "kind": "row",
    "children": [
      {
        "kind": "badge",
        "text": "В списке: 3",
        "variant": "good"
      },
      {
        "kind": "button",
        "text": "Очистить",
        "action": "clear",
        "variant": "danger"
      }
    ]
  }
]

Инструменты, как их описание уходит ядру при приветствии:

[
  {
    "name": "add",
    "summary": "Добавить строку в список покупок.",
    "permissions": [],
    "confirm_required": false,
    "params": [
      {
        "name": "what",
        "type": "string",
        "description": "Что купить, например «молоко».",
        "required": true
      }
    ]
  },
  {
    "name": "clear",
    "summary": "Очистить список покупок.",
    "permissions": [],
    "confirm_required": true,
    "params": []
  }
]

Примеры

Примеры лежат в examples/plugins/ репозитория и в установщик не входят. Чтобы попробовать пример, поставь его папку из раздела плагинов в программе. Колонка «Хуки» собрана по их коду.

ПлагинЧто делаетХукиРазрешения
ЧасыСообщает текущее время и дату по запросу («сколько времени», «какая дата»).on_command, tools—
ПересчётПереводит величины: «5 км в мили», «20 °C в °F», «3 кг в фунты». Поле прямо на главном экране.on_command, tools, home, on_action—
КубикБросает игральный кубик или монетку по команде («брось кубик», «подбрось монету»).on_command, tools—
ПриветствиеОтвечает на приветствия. Скажи «привет» — и я отвечу.on_enable, on_command—
ЗаметкиБыстрые заметки: своя вкладка, настройки и команда «запиши…».on_enable, on_command, tools, page, on_action, settings_schema—

Плагины в поставке

Плагины из plugins/ программы приходят с установщиком и лежат рядом с ней; включаются они в разделе плагинов.

ПлагинЧто делаетХукиРазрешения
КурсКурс доллара и евро по Центробанку — плиткой на главном экране, по вопросу вслух и блоком в своих командах.on_enable, on_command, tools, homenetwork.external
ПогодаПогода сейчас и до вечера — плиткой на главном экране, по вопросу вслух и блоком в своих командах.on_enable, on_command, tools, page, home, on_actionnetwork.external