Разработка плагинов

Плагин MindRoot — это Python-пакет, который добавляет агенту новые возможности (команды), внутренние компоненты (сервисы) и, при необходимости, собственные страницы интерфейса. В этом репозитории уже 10 коннекторов и 76 команд — их код можно использовать как эталон структуры.

Структура пакета

mr_your_service/ ├── plugin_info.json # манифест: имя, версия, команды, сервисы, настройки ├── pyproject.toml # сборка (package_data обязателен для static/ и templates/) ├── requirements.txt ├── README.md # русскоязычная документация └── src/ └── mr_your_service/ ├── __init__.py # from .mod import * ├── mod.py # команды и сервисы └── router.py # (опционально) FastAPI-роуты плагина

Манифест `plugin_info.json`

{ "name": "Битрикс24", "version": "1.0.0", "description": "Коннектор к Битрикс24: CRM, задачи, комментарии", "services": ["b24_rest_call"], "commands": ["b24_list_deals", "b24_create_deal"], "dependencies": { "requests": ">=2.28.0" }, "settings": [ { "key": "BITRIX24_WEBHOOK", "label": "Входящий вебхук", "required": true, "secret": true } ], "compliance": { "data_residency": "rf_only", "pii_fields": ["NAME", "PHONE", "EMAIL"], "redaction_supported": true } }

Команды в манифесте должны совпадать с кодом один в один. Наша проверка scripts/check_plugins.py сверяет манифест с зарегистрированными функциями и падает с ошибкой при расхождении.

Команда: то, что вызывает модель

Команда помечается декоратором @command(). Docstring — это и документация, и JSON-схема инструмента: из блоков «Параметры», «Пример» и «Результат» MindRoot собирает описание для модели. Пишите их по-русски и указывайте пример ровно в формате вызова.

from lib.providers.commands import command @command() async def b24_create_deal(title: str, opportunity: float = None, assigned_by_id: int = None, context=None) -> dict: """Создаёт новую сделку в CRM Битрикс24. Параметры: title - String. Название сделки, например "Поставка оборудования". opportunity - Number. Необязательный. Сумма сделки в рублях. assigned_by_id - Integer. Необязательный. ID ответственного менеджера. Пример: { "b24_create_deal": { "title": "Внедрение агента", "opportunity": 350000 } } Результат: { "ok": true, "deal_id": число } """ data = await _call('crm.deal.add', {'fields': {'TITLE': title}}, context) return { 'ok': True, 'deal_id': data.get('result') }

Сервис: переиспользуемая логика

Сервисы регистрируются декоратором @service() и доступны другим командам и агентам. Типичный пример — низкоуровневый вызов API с аутентификацией:

from lib.providers.services import service @service() async def b24_rest_call(method: str, params: dict = None, context=None) -> dict: """Выполняет произвольный метод REST API Битрикс24.""" ...

Секреты и конфигурация

Секреты читаются из context.agent['settings'] или переменных окружения — никогда не хранятся в коде и не пишутся в логи.
Помечайте секретные настройки полем "secret": true в манифесте: витрина и админка будут отображать их как скрытые поля.
Маскируйте секреты в сообщениях об ошибках и трассировке — в референсных коннекторах для этого есть функция _mask().
Изменяющие операции делайте отдельными командами и документируйте в compliance.notes требование подтверждения пользователя.

Как проверить плагин перед публикацией

# 1. Сверка манифеста и кода + разбор docstring-примеров как JSON python3 scripts/check_plugins.py # 2. Сборка реестра витрины (команды с описаниями попадут в карточку) python3 scripts/build_registry.py # 3. Генерация pyproject/setup/README из манифеста python3 scripts/scaffold_plugin_files.py

Проверка контролирует: наличие plugin_info.json, совпадение объявленных и зарегистрированных команд, полноту docstring (блоки «Параметры» и «Результат», валидный JSON-пример вызова).

Публикация в маркетплейсе

Заполните заявку в разделе «Разработчикам» — она попадает в очередь модерации.
Модерация проверяет безопасность: к каким системам обращается плагин, какие данные читает и куда передаёт.
Автоматическая проверка контракта (как в check_plugins.py) прогоняется на сервере MindRoot.ru.
После публикации вы получаете статистику установок и доход: комиссия платформы — 20%, выплаты дважды в месяц.

Ускорение разработки: шаблон коннектора с авторизацией, ретраями, маскированием секретов и обработкой лимитов API лежит в любом из наших плагинов — скопируйте ближайший по смыслу и замените вызовы API.