Page Agent API и инструменты WebMCP

Модуль 0.133.0 предоставляет Agent API 1.23 по адресу window.GLIT.wysiwyg.agent.v1. Через него скрипт или агент может прочитать структуру документа, изменить блоки и вызвать доступные действия сохранения, истории и предпросмотра.

Способы вызова

Способ	Как работает
Page Agent API	Доверенный скрипт страницы вызывает методы JavaScript напрямую
WebMCP	Браузер предоставляет те же действия как зарегистрированные инструменты
MCP-replacement	Адаптер вызывает Page Agent API в обычной браузерной сессии, если WebMCP недоступен

Все способы работают в браузерной сессии с правами текущего пользователя. После перехода на другую страницу снова запросите список инструментов: их имена могут содержать суффикс сессии.

Для изменения документа вызывайте API: его операции проверяют данные и состояние редактора. Используйте contentUid для выбора документа и blockUid для выбора блока.

Получение документа и доступных действий

Откройте документ в редакторе.
Убедитесь, что window.GLIT.wysiwyg.agent.v1 доступен.
Вызовите listEditors() и выберите нужный редактор со статусом готовности.
Получите его возможности через capabilities({contentUid}).
Прочитайте состояние через inspect({contentUid}).
Передайте прочитанную editorVersion в операцию изменения.

Пример ниже предназначен для страницы с одним готовым редактором и установленным пакетом starter.notice. При нескольких редакторах приложение должно выбрать нужный contentUid явно.

JavaScript

const api = window.GLIT?.wysiwyg?.agent?.v1;
if (!api) throw new Error('Откройте редактор с поддержкой Page Agent API');

const editors = api.listEditors().filter(item => item.ready);
if (editors.length !== 1) {
  throw new Error('Нужно выбрать один готовый документ');
}
const {contentUid} = editors[0];
const capabilities = api.capabilities({contentUid});
const snapshot = api.inspect({contentUid});
const extensions = capabilities.runtimeExtensions;
const notice = extensions?.declarativeBlocks.find(
  block => block.extensionId === 'starter.notice' && block.type === 'notice',
);
if (!extensions || !notice) throw new Error('Учебный блок сообщения недоступен');

const result = await api.apply({
  contentUid,
  expectedEditorVersion: snapshot.editorVersion,
  operations: [{
    op: 'insertExtensionBlock',
    expectedDigest: extensions.digest,
    extensionId: notice.extensionId,
    blockType: notice.type,
    schemaVersion: notice.schemaVersion,
    data: {title: 'Сообщение', text: 'Текст', showText: true},
  }],
});

Идентификатор, тип и схему своего блока получите из runtimeExtensions.declarativeBlocks. Если документ изменился после чтения, снова вызовите inspect() и проверьте, какие изменения ещё нужны. Повторная вставка без проверки может создать дубликат.

Операции с расширениями

Операция	Поля
`insertExtensionBlock`	`expectedDigest`, `extensionId`, `blockType`, `schemaVersion`, `data`; необязательные `parentBlockUid`, `index`
`updateExtensionData`	`expectedDigest`, `blockUid`, `data` — полная замена данных по схеме
`moveExtensionBlock`	`expectedDigest`, `blockUid`; необязательные `parentBlockUid`, `index`
`deleteExtensionBlock`	`expectedDigest`, `blockUid`
`runExtensionCommand`	`expectedDigest`, `command`, `blockUid`, `input`
`insertRuntimeTemplate`	`document` — строка с `RuntimeTemplateDocument`; необязательный `index`

Для этих операций передавайте expectedEditorVersion и только одну операцию за вызов apply(). Шаблон содержит extensionDigest внутри document.

Для вызова команды JavaScript-расширения найдите её в nativeCommands. Проверьте тип целевого узла, входные данные по inputSchema и результат по outputSchema. Команды из toolbarActions доступны агенту только при отдельной регистрации.

В ответе capabilities также есть типы узлов (nativeNodeTypes), узлы для шаблонов (nativeTemplateNodeTypes) и декларативные блоки: их поля, вид и именованные области содержимого. Точные определения лежат в page-agent.ts, page-agent-tools.ts и extension-agent.ts из архива TypeScript.

Сохранение результата

В Битрикс apply() ждёт автосохранения и возвращает версию документа на сервере. Если редактор открыт из поля, после этого примените результат к полю и сохраните форму. Согласование и публикация выполняются в обычном порядке.

Метод applyAgentOperations() элемента <glit-wysiwyg> синхронно меняет документ в редакторе. Сохранение и публикацию при таком вызове выполняет приложение.

Через API также доступны шаблоны, медиабиблиотека, режимы экрана, история, контрольные версии и предпросмотр. Перед вызовом проверьте capabilities: набор действий зависит от интеграции.

Каталог инструментов WebMCP

В таблице указаны базовые имена инструментов. Сигнатуры и типы результатов приведены в справочнике JavaScript API.

Инструмент	Метод JavaScript	Доступность
`glit_wysiwyg_capabilities`	`capabilities({contentUid}?)`	Базовый редактор
`glit_wysiwyg_list_editors`	`listEditors()`	Базовый редактор
`glit_wysiwyg_inspect`	`inspect({contentUid})`	Базовый редактор
`glit_wysiwyg_list_templates`	`listTemplates({contentUid, kind?, query?})`	Базовый редактор
`glit_wysiwyg_get_template`	`getTemplate({contentUid, providerId, id})`	Базовый редактор
`glit_wysiwyg_insert_template`	`insertTemplate({contentUid, providerId, id, expectedEditorVersion?, index?, parentBlockUid?})`	Базовый редактор
`glit_wysiwyg_apply_operations`	`apply({contentUid, expectedEditorVersion?, operations})`	Базовый редактор
`glit_wysiwyg_set_responsive_variant`	`setResponsiveVariant({contentUid, variantCode})`	Базовый редактор
`glit_wysiwyg_browse_media`	`browseMedia({mediaType, collectionId?, page?, pageSize?, query?})`	Bitrix
`glit_wysiwyg_upload_media`	`uploadMedia({mediaType, collectionId, fileName, dataBase64, mimeType?})`	Bitrix
`glit_wysiwyg_list_history`	`listHistory({contentUid, beforeId?, blockUid?, changesOnly?})`	Bitrix
`glit_wysiwyg_list_block_catalog`	`listBlockCatalog({contentUid, query?, cursor?})`	Bitrix
`glit_wysiwyg_compare_revisions`	`compareRevisions({contentUid, fromRevisionId, toRevisionId})`	Bitrix
`glit_wysiwyg_restore_revision`	`restoreRevision({contentUid, revisionId, blockUid?})`	Bitrix
`glit_wysiwyg_set_revision_pinned`	`setRevisionPinned({contentUid, revisionId, pinned})`	Bitrix
`glit_wysiwyg_create_checkpoint`	`checkpoint({contentUid, comment?})`	Bitrix
`glit_wysiwyg_create_preview`	`preview({contentUid})`	Bitrix

В базовом редакторе доступно восемь инструментов, в интеграции Битрикс — все семнадцать. Медиабиблиотека и история работают через серверную часть Битрикс; одного modelContext для них недостаточно.

Режимы экрана

setResponsiveVariant() переключает размер рабочей области и возвращает настройки предпросмотра. Метод не меняет содержимое документа.

Параметры для отдельных размеров экрана меняйте через responsiveData, responsiveStyles и responsiveHidden. Общие значения задавайте через data и styles. Коды режимов получите из capabilities; не задавайте mobile без проверки конфигурации.

История и восстановление

changesOnly: true требует blockUid.
В beforeId передаётся числовой идентификатор для загрузки следующей страницы истории.
В cursor каталога блоков передаётся строка из поля next предыдущего ответа.
compareRevisions() принимает два разных идентификатора версий.
restoreRevision() меняет рабочее состояние документа. Для просмотра без изменений используйте чтение или сравнение версий.