Плагины

Коротко

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

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

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

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

Самый маленький плагин из поставки отвечает на «привет». Вот он целиком: 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. Положите папку в plugins/ рядом с программой (в исходниках это корень репозитория) или поставьте папку или архив .zip из раздела плагинов в программе.
2. Включите плагин там же. Код запускается при включении, до этого ядро читает только манифест.
3. Скажите или напишите Рине «привет».

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

Манифест

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

Имя папки при установке проверяется: оно должно подходить под ^[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.

Хуки

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

Поля класса

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

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

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

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

Фразы

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

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

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

Потоки

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

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

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

Состояние

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

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

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

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

Инструменты

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

В 4.0 инструменты плагинов заводятся, но вызвать их пока нечем. Встроенные команды ведут к встроенным инструментам, у своих команд пользователя нет вида «инструмент», в протоколе нет метода для вызова по имени, а языковая модель реестр не видит. Инструменты объявляют заранее: так их права и подтверждения проверены уже сейчас, а звать их будет модель в следующих версиях. Чтобы плагин работал голосом сегодня, отвечайте на фразу в on_command, как все плагины из поставки.

Значение по умолчанию до run не доходит. Ядро пересобирает Param на своей стороне без поля default, поэтому необязательный аргумент может просто не прийти. Берите значение сами: args.get("sides") or 6, как в dice.

PluginTool

Param

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

Вызов и ответ

• run(args) возвращает текст ответа. Через процесс уходит строка: любое значение ядро приведёт к str, None станет пустой строкой.
• Исключение внутри run превращается в неудачу инструмента с кодом internal, трассировка — в журнал плагина.
• confirm_required=True — ядро спросит пользователя перед каждым вызовом. Для опасного разрешения это обязательно: без подтверждения такой инструмент не создаётся.
• Список инструментов ядро узнаёт при запуске. Изменили tools() — выключите и включите плагин.

Разрешения

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

• То, что плагину не выдаётся, и имена не из каталога ядро отбрасывает и пишет в журнал плагина: «Не выдано разрешений: …».
• Инструмент, которому нужно не выданное или не перечисленное в манифесте, не заводится вовсе. В журнале будет «Инструмент «имя» не заведён: просит […]».
• Опасное разрешение требует confirm_required=True.

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

Вкладка

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

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

Элементы

Правила

• Вкладка обновляется целиком: после каждого 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.

Поля схемы

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

Плагин запускается из корня программы, и пакет 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;
• имя подходит под правило из раздела «Манифест», и папка ложится прямо внутрь plugins/;
• архив распаковывается не больше чем в 50 МиБ: размер считается до распаковки.

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

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

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

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

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

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

Провод

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

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

Ядро → плагин

Плагин → ядро

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

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

Граница

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

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

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

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

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

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

python tools/test_plugins.py

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

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

Список покупок: фраза, два инструмента, вкладка с полем и плитка, которая появляется, только когда есть что купить. Манифест — в разделе «Манифест». Этот код запускается на настоящем 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": []
  }
]

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

Всё, что лежит в plugins/ программы, — рабочие образцы. Колонка «Хуки» собрана по их коду.