Перейти к содержимому

Написание расширения

Расширение добавляет в Moira типы нод в собственном пространстве имён, исходящие каналы коммуникации или оба вида вкладов. Собственные ноды используют тот же граф, что и встроенные: Moira проверяет конфигурацию, вызывает изолированный runner, сохраняет успешный результат под ID ноды и при сбое переходит по её связи error, если она есть. Без этой связи Moira записывает диагностику и приостанавливается на ноде для повторной попытки. Каналы коммуникации — это транспорты встроенной универсальной ноды user-notification и собственных уведомлений Moira «Ждёт вас» с напоминаниями; они не являются типами нод и не получают идентификаторы workflow или пользователя.

Код расширения не исполняется в процессах приложения Moira. Обычные обработчики нод и текста работают в дочерних процессах runner; бинарные обработчики — рядом с источником у владельца файлов. Эти границы изолируют падения, но не являются песочницей для враждебного кода: администратор должен устанавливать только доверенные расширения.

Структура бандла

Каждый установленный каталог содержит манифест и точку входа:

my-extension/
├── moira-extension.json
└── index.ts

Runner сканирует каталоги первого уровня внутри MOIRA_EXTENSIONS_DIR. Каталоги без манифеста игнорируются. Некорректный бандл отвергается с указанием причин, остальные продолжают работать. После добавления, удаления или изменения бандла перезапустите runner и Moira: оба каталога загружаются при старте процессов.

Манифест

{
"apiVersion": "moira.extensions/v1",
"name": "corporate-messenger",
"version": "1.0.0",
"entrypoint": "index.ts",
"nodes": [
{
"type": "corporate-messenger.send",
"title": "Отправить сообщение",
"description": "Отправляет сообщение в чат.",
"configSchema": {
"type": "object",
"required": ["chat", "text"],
"additionalProperties": false,
"properties": {
"chat": { "type": "string" },
"text": { "type": "string" }
}
},
"outputSchema": {
"type": "object",
"required": ["messageId"],
"additionalProperties": false,
"properties": { "messageId": { "type": "string" } }
}
}
],
"communicationChannels": [
{
"id": "corporate-messenger.notifications",
"title": "Уведомления корпоративного мессенджера",
"description": "Доставляет обычные уведомления в настроенный чат.",
"capabilities": {
"text": true,
"image": false,
"document": false,
"trustedDelivery": false
},
"configurationSchema": {
"type": "object",
"required": ["corporate-messenger.enabled", "corporate-messenger.default_chat"],
"additionalProperties": false,
"properties": {
"corporate-messenger.enabled": { "type": "boolean" },
"corporate-messenger.default_chat": { "type": "string", "minLength": 1 }
}
},
"enabledSetting": "corporate-messenger.enabled",
"settings": ["corporate-messenger.enabled", "corporate-messenger.default_chat"],
"permissions": {
"network": ["api.example.com"],
"secrets": ["corporate-messenger.token"]
}
}
],
"settings": [
{
"key": "corporate-messenger.enabled",
"type": "boolean",
"label": "Включить уведомления",
"defaultValue": "true"
},
{
"key": "corporate-messenger.default_chat",
"type": "string",
"label": "Чат уведомлений по умолчанию",
"required": true
},
{
"key": "corporate-messenger.token",
"type": "encrypted",
"label": "Токен бота"
}
],
"permissions": {
"network": ["api.example.com"],
"secrets": ["corporate-messenger.token"]
}
}
  • apiVersion должен быть равен moira.extensions/v1.
  • name задаёт пространство имён. Тип каждой ноды и ID каждого канала должны иметь вид <name>.<contribution>.
  • entrypoint должен разрешаться внутри каталога бандла.
  • configSchema, необязательная inputSchema и outputSchema — JSON Schema, которые компилируются при регистрации манифеста. Конфигурация и вход проверяются до вызова, результат — до записи в состояние workflow.
  • settings объявляет значения для универсального редактора настроек Moira.
  • Верхнеуровневый permissions выдаёт службы только обработчикам нод. У каждого канала коммуникации отдельный объект permissions; разрешения не переходят через эту границу.

Имена расширений, типы нод, ID каналов и ключи настроек должны быть уникальны. Ключ настройки обязан находиться в пространстве имён расширения; пространства встроенных настроек Moira зарезервированы. Бандл может не объявлять ноды и содержать только каналы; явный пустой массив nodes остаётся допустимым для совместимости с форматом манифеста версии 1.

Настройки

Поддерживаются типы string, number, boolean, json и encrypted. Определения остаются в манифесте, а не в базе. Удаление бандла скрывает определения; пользовательские значения сохраняются и снова становятся доступны после установки тех же определений.

Значения encrypted хранятся зашифрованными и маскируются в публичных ответах. Объявление json может содержать JSON Schema в поле validation: универсальный редактор принимает текст JSON, проверяет разобранную структуру и сохраняет точное значение JSON. Обработчик получает такую настройку как сериализованный текст JSON и разбирает её через JSON.parse.

Действующее JSON-значение null присутствует и передаётся допущенному обработчику как текст "null". Сам services.secret возвращает null, только если у настройки нет действующего значения. Сохранённые false, ноль и пустые строки также остаются значениями и не заменяются значением по умолчанию.

Настройки принадлежат пользователям. Обработчик получает значения пользователя, чьё исполнение запущено. Настройку adminOnly может изменить только администратор через аутентифицированный API или MCP-инструмент настроек, но общей для установки она не становится. Используйте adminOnly только для нод, которые должны выполняться от имени этого администратора.

Само объявление не выдаёт доступ. Чтобы прочитать значение, перечислите тот же ключ в permissions.secrets и вызовите services.secret(key). Необъявленный или невыданный ключ отвергается по имени, а выданный ключ без значения возвращает null.

Объявление канала коммуникации

Каждая запись communicationChannels объявляет один обычный исходящий транспорт:

  • id стабилен, находится в пространстве имени расширения и содержит не более 128 символов.
  • capabilities указывает поддержку текста, изображений и документов. Поле trustedDelivery только запрашивает возможность доставки чувствительных сообщений и само ничего не разрешает.
  • enabledSetting называет объявленную логическую настройку пользователя. Значение false отключает обычную доставку через этот канал для данного пользователя.
  • settings перечисляет несекретные псевдонимы конфигурации. configurationSchema проверяет объект ровно из этих значений до доставки. Обычный текстовый обработчик получает эту конфигурацию, а бинарный — отфильтрованные настройки, описанные ниже.
  • permissions.network и permissions.secrets канала действуют только для его обработчика. Секреты читаются через services.secret и не должны одновременно входить в settings.

Moira отвергает весь бандл, если канал ссылается на необъявленную настройку, использует чужое пространство имён, передаёт зашифрованное значение как обычную конфигурацию или расходится с объявлением точки входа. Значения включения, конфигурации и секретов разрешаются для текущего пользователя уведомления. Обработчик не получает его идентификатор, workflow, исполнение, репозиторий, артефакты или журналы.

Канал расширения участвует в веерной доставке встроенной ноды user-notification и уведомлений «Ждёт вас». Отсутствующий, отключённый, некорректно настроенный или не поддерживающий тип сообщения канал пропускается. Обычная доставка разрешает текущие настройки и вызывает обработчик без отдельной health-проверки runner. Сбой транспорта или обработчика считается неудачей канала с ограниченной очищенной причиной: без успешного соседнего канала общий результат равен all_failed, а с ним — partial. Ни один из результатов не раскрывает ответы эндпоинта или учётные данные.

Каждый установленный канал отображается карточкой в Settings > Notifications. Moira использует title, description, capabilities, enabledSetting и точные псевдонимы настроек из объявления; существующий редактор схем настроек отображает и сохраняет эти значения. Карточка показывает состояние «готов», «отключён», «требуется настройка» или «недоступен» и отправляет фиксированный тест через общий сервис с сохранёнными настройками текущего пользователя. Браузер передаёт только ID канала и не отправляет секреты или адрес получателя повторно. Удаление бандла убирает карточку и определения, но сохраняет пользовательские значения для переустановки. Зарегистрированный канал остаётся видимым, когда он отключён или не полностью настроен. Объявление trusted delivery и одобрение администратора показываются в пользовательской карточке без возможности изменения.

Обработчик

/* index.ts */ import { defineExtension, defineNode } from "@mcp-moira/extension-sdk";
const send = defineNode({
type: "corporate-messenger.send",
async handler({ config, signal, services }) {
const token = await services.secret("corporate-messenger.token");
if (!token) throw new Error("corporate-messenger.token не заполнен");
const response = await services.fetch("https://api.example.com/messages", {
method: "POST",
headers: {
authorization: `Bearer ${token}`,
"content-type": "application/json",
},
body: JSON.stringify({ chat: config.chat, text: config.text }),
signal,
});
if (!response.ok) throw new Error(`сообщение не принято: ${response.status}`);
const body = (await response.json()) as { id: string };
services.log("сообщение отправлено", { chat: String(config.chat) });
return { messageId: body.id };
},
});
export default defineExtension({ nodes: [send] });

Манифест — источник истины для схем. Схему можно повторить в defineNode, но тогда runner требует точного совпадения при первой загрузке кода дочерним процессом. Этот фрагмент экспортирует только ноду. Для объединённого манифеста выше реализуйте также канал ниже и экспортируйте оба вклада из одной точки входа: отсутствие объявленного обработчика в модуле приводит к отказу загрузки бандла.

Обработчик получает:

ЗначениеКонтракт
configКонфигурация после глубокой подстановки шаблонов и проверки по configSchema
inputСопоставленный вход вызова, проверенный по inputSchema, если она объявлена
executionId, nodeIdИдентификаторы вызова; другого состояния исполнения нет
signalСрабатывает при отмене или истечении срока
servicesЯвные возможности, выданные манифестом

ABI обработчика не передаёт базу Moira, конфигурацию приложения или службу файловой системы. Обычный дочерний процесс runner получает ограниченное окружение вместо секретов приложения. Это границы служб и процессов, а не запрет произвольного доверенного Node.js-кода: у процесса остаётся доступ к собственному runtime и файловой системе. Разрешения манифеста ограничивают выданные службы, но не делают недоверенный код безопасным для установки.

Обработчик канала коммуникации

Объявите транспорт через defineChannel и экспортируйте его в communicationChannels:

/* index.ts */ import { defineChannel, defineExtension } from "@mcp-moira/extension-sdk";
const notifications = defineChannel({
id: "corporate-messenger.notifications",
async handler({ message, settings, signal, services }) {
const token = await services.secret("corporate-messenger.token");
const chat = settings["corporate-messenger.default_chat"];
if (!token || typeof chat !== "string") throw new Error("канал не настроен");
const response = await services.fetch("https://api.example.com/messages", {
method: "POST",
headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
body: JSON.stringify({ chat, text: message.text }),
signal,
});
if (!response.ok) throw new Error(`сообщение не принято: ${response.status}`);
},
});
export default defineExtension({ communicationChannels: [notifications] });

Этот экспорт относится к манифесту только с каналом. Для объединённого манифеста выше поместите оба определения в один модуль и оставьте один итоговый экспорт:

export default defineExtension({ nodes: [send], communicationChannels: [notifications] });

Обычный текстовый обработчик получает переносимое сообщение, проверенные схемой несекретные настройки, сигнал отмены и только службы fetch и secret. Служб журналов и артефактов у него нет. Если defineChannel повторяет configurationSchema, она должна точно совпадать с манифестом.

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

Потоковая доставка файлов

Канал с поддержкой изображений или документов дополнительно объявляет binaryTransport и экспортирует binaryHandler. Включайте image/document capabilities только для поддерживаемых типов. Добавьте этот фрагмент в объявление канала, сохранив объявления token/default_chat и разрешив api.example.com в permissions.network канала:

{
"binaryTransport": {
"operations": [
{
"id": "upload",
"endpoint": { "url": "https://api.example.com/files" },
"method": "POST",
"credential": {
"header": "authorization",
"secret": "corporate-messenger.token",
"scheme": "Bearer"
},
"recipient": {
"field": "chat",
"setting": "corporate-messenger.default_chat"
},
"body": {
"mode": "multipart",
"fileField": "file",
"controls": { "caption": "caption", "format": "format", "silent": "silent" }
}
}
]
}
}

Добавьте этот метод в существующий объект defineChannel рядом с текстовым handler:

async binaryHandler({ message, signal, services }) {
signal.throwIfAborted();
await services.send("upload", {
caption: message.text,
format: message.format,
silent: message.silent,
});
}

Бинарный обработчик получает объявленные настройки обработчика, отмену и метаданные message.attachment: kind, filename, mimeType, size, sha256, а также open(), возвращающий ReadableStream<Uint8Array>. Он работает рядом с неизменяемым источником у workspace или сопряжённого контроллера, а не в текстовом runner. Облачного секрета и произвольного аутентифицированного fetch у него нет. Значения настроек, используемых любой объявленной операцией как recipient.setting или endpoint.baseUrlSetting, и все псевдонимы секретов исключаются и перед передачей владельцу, и перед вызовом дочернего процесса. Остальные объявленные настройки, например флаг включения или параметры форматирования, остаются доступны. Установленный манифест по-прежнему описывает операции; его статические метаданные не выдают исходящих полномочий.

Подготовка канала проверяет текущие полномочия и конфигурацию, не получая метаданных файла или содержимого сообщения. Она возвращает capabilities, идентификаторы разрешённых операций и реальные ограничения провайдера. Владелец проверяет тип и размер захваченного файла и весь выбранный план доставки до любого этапа провайдера. Явно выбранный неподдерживаемый канал отклоняет доставку; при неявном выборе неподдерживаемые каналы могут отфильтровываться, но отсутствие подходящих каналов означает сбой, а не успешную доставку файла. Во встроенном пути Telegram владелец выбирает подпись или отдельный текстовый этап, сохраняя полный текст сообщения без усечения.

services.send выбирает объявленную операцию и передаёт захваченный источник потоком. Облачная Moira повторно проверяет текущего инициатора, кадр workflow и digest конфигурации, разрешает фиксированный секрет и получателя и формирует запрос провайдера для выбранного владельцем этапа. Обработчик не задаёт URL, заголовки, credentials, адресата или готовый multipart. Вместо literal URL допустим объявленный несекретный baseUrlSetting с фиксированным путём; итоговый хост всё равно должен быть разрешён. Получатель raw-операции задаётся объявленным заголовком, не совпадающим с аутентификацией или framing. Поля получателя, файла и controls в multipart должны различаться.

Исходный ID доставки привязан к установленному бандлу и конфигурации канала. Изменения отклоняют старую доставку вместо перенаправления. Если этап провайдера уже мог начаться, исход остаётся неопределённым; чтение результата не повторяет этап. Отключение наблюдателя не доказывает отсутствия доставки.

Входной HTTP-прокси может закрыть соединение наблюдателя после простоя между событиями ввода-вывода. После потери ответа читайте результат по исходному ID доставки у владельца; такое отключение не разрешает повторную отправку.

Подтверждение доверенной доставки

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

  • установленный канал объявляет capabilities.trustedDelivery: true;
  • администратор независимо подтвердил ID этого канала;
  • персональная конфигурация пользователя корректна и включена;
  • адаптер через runner находится в рабочем состоянии.

Администратор смотрит объявления через GET /api/admin/communication/trusted-channels и сохраняет или отзывает независимое решение так:

PUT /api/admin/communication/trusted-channels/corporate-messenger.notifications
Content-Type: application/json
{ "approved": true }

Подтверждение действует на всю установку, записывается в аудит, переживает перезапуск runner и не добавляет сетевых разрешений или доступа к секретам. Оно не превращает обычный канал в доверенный. Доставка PIN встроенной lock-ноды остаётся привязана к Telegram: каналы расширений не получают PIN через веерную отправку обычных уведомлений.

Службы и разрешения

  • services.log(message, fields) пишет структурную запись runner. Не включайте значения из secret: журнал не ищет и не маскирует их.
  • services.fetch(url, init) разрешает только точные хосты из permissions.network. Перенаправления проверяются повторно, а при смене origin чувствительные заголовки удаляются.
  • services.secret(alias) возвращает выданную настройку как текст или null, если она не заполнена.
  • services.writeArtifact(name, content) требует permissions.artifacts: true. Артефакты возвращаются вместе с успешным результатом. Один артефакт ограничен 256 КиБ, весь вызов — 1 МиБ; превышение любого лимита роняет вызов.

Результаты, сбои и сроки

Успешный результат сохраняется под ID ноды. Поле messageId ноды send-message читается дальше как {{send-message.messageId}}. Ноды расширений не объявляют глобальные записи.

Каждый сбой получает именованную диагностику. Если есть connections.error, workflow переходит по этой связи:

ВидЗначение
invalid-inputКонфигурация или вход после подстановки не прошли схему
handler-errorОбработчик бросил исключение или точка входа не загрузилась
timeoutВызов превысил срок ноды
runner-unavailableRunner недоступен или дочерний процесс умер
invalid-outputВозвращённое значение не прошло outputSchema

Без связи error Moira записывает диагностику и приостанавливает работающее исполнение на той же ноде. Продолжение исполнения вызывает расширение повторно. Runner переиспользует контролируемый процесс обработчика между вызовами и может выполнять в нём несколько вызовов параллельно; после падения, превышения срока или отмены процесс заменяется. Не полагайтесь на локальное состояние процесса. Обработчик должен быть повторно входимым и безопасным для остановки.

Поле timeout ноды задаётся в миллисекундах; без него используется 30 000. Превышение срока, потерянный ответ или некорректный результат не доказывают отсутствия внешнего эффекта. До повтора проверьте квитанцию провайдера либо используйте поддерживаемый им контракт идемпотентности: новый вызов обработчика не является чтением результата предыдущего.

Нода расширения — один ожидаемый вызов с ограниченным сроком. SDK не предоставляет API для долговечной фоновой задачи, пробуждения агента или регистрации callback. Длительную операцию провайдера выразите явными нодами: запустите её, сохраните идентификатор в локальном результате, затем проверьте или получите результат той же операции. Ставьте cases на ноду с результатом либо выносите общее решение в отдельную condition-ноду. Не полагайтесь на сохранение не дождавшейся завершения promise или таймера после отмены или замены процесса.

Универсальный редактор workflow

Браузер не загружает frontend-код расширения. Он получает живой каталог типов нод из Moira и строит универсальную форму по configSchema. Поддерживаемые схемой примитивы, массивы, объекты, enum и вложенные поля редактируются в ней; требования к представлению описывайте схемой, а не JavaScript.

Если настроенный runner недоступен, валидация и редактор сообщают о недоступном реестре расширений, а не превращают все пользовательские типы в неизвестные. Если реестр доступен, но типа в нём нет, Moira называет неустановленное расширение.

Референсный пример

examples/extensions/webhook-notify содержит полную исходящую action-ноду и обычный текстовый канал коммуникации. Они используют общие объявленные персональные настройки эндпоинта, но имеют отдельные точные сетевые разрешения и доступы к секрету. У ноды есть именованный сбой ограничения частоты и результат messageId в её области; канал использует настроенного получателя по умолчанию и намеренно не запрашивает доверенную доставку. Это не входящий webhook-триггер. Копируйте и адаптируйте этот пример, а не служебные бандлы из tests/fixtures.

Команды установки и диагностики приведены в Self-hosting: включение расширений.