Представление сообщений

• текстовые разделы
• небольшой текст контекста/нижнего колонтитула
• разделители
• кнопки
• меню выбора
• заголовок карточки и тон

​

Контракт

import type {
  MessagePresentation,
  ReplyPayloadDelivery,
} from "openclaw/plugin-sdk/interactive-runtime";

type MessagePresentation = {
  title?: string;
  tone?: "neutral" | "info" | "success" | "warning" | "danger";
  blocks: MessagePresentationBlock[];
};

type MessagePresentationBlock =
  | { type: "text"; text: string }
  | { type: "context"; text: string }
  | { type: "divider" }
  | { type: "buttons"; buttons: MessagePresentationButton[] }
  | { type: "select"; placeholder?: string; options: MessagePresentationOption[] };

type MessagePresentationAction =
  | { type: "command"; command: string }
  | { type: "callback"; value: string };

type MessagePresentationButton = {
  label: string;
  action?: MessagePresentationAction;
  /** Legacy callback value. Prefer action for new controls. */
  value?: string;
  url?: string;
  webApp?: { url: string };
  /** @deprecated Use webApp. Accepted for legacy JSON payloads only. */
  web_app?: { url: string };
  priority?: number;
  disabled?: boolean;
  reusable?: boolean;
  style?: "primary" | "secondary" | "success" | "danger";
};

type MessagePresentationOption = {
  label: string;
  action?: MessagePresentationAction;
  /** Legacy callback value. Prefer action for new controls. */
  value?: string;
};

type ReplyPayloadDelivery = {
  pin?:
    | boolean
    | {
        enabled: boolean;
        notify?: boolean;
        required?: boolean;
      };
};

• action.type: "command" запускает нативную slash-команду через командный путь ядра. Используйте это для встроенных командных кнопок и меню.
• action.type: "callback" переносит непрозрачные данные Plugin через путь взаимодействий канала. Channel plugins не должны переинтерпретировать callback-данные как slash-команды.
• value — устаревшее непрозрачное callback-значение. Новые элементы управления должны использовать action, чтобы channel plugins могли сопоставлять команды и callbacks без догадок по тексту.
• url — кнопка-ссылка. Она может существовать без value.
• webApp описывает кнопку channel-native веб-приложения. Telegram отрисовывает ее как web_app и поддерживает только в приватных чатах. web_app по-прежнему принимается в свободных JSON-пейлоадах для совместимости, но TypeScript-производители должны использовать webApp.
• label обязателен и также используется в текстовом fallback.
• style носит рекомендательный характер. Рендереры должны сопоставлять неподдерживаемые стили с безопасным значением по умолчанию, а не прерывать отправку.
• priority необязателен. Когда канал объявляет ограничения действий и элементы управления нужно отбросить, ядро сначала сохраняет кнопки с более высоким приоритетом и сохраняет исходный порядок среди кнопок с одинаковым приоритетом. Когда все элементы управления помещаются, сохраняется авторский порядок.
• disabled необязателен. Каналы должны явно включить это через supportsDisabled; иначе ядро понижает отключенный элемент управления до неинтерактивного fallback-текста.
• reusable необязателен. Каналы, поддерживающие повторно используемые нативные callbacks, могут оставить действие доступным после успешного взаимодействия. Используйте это для повторяемых или идемпотентных действий, таких как обновить, проверить или подробнее; не задавайте его для обычных одноразовых подтверждений и разрушительных действий.

• options[].action имеет то же значение команды/callback, что и кнопочный action.
• options[].value — устаревшее выбранное значение приложения.
• placeholder носит рекомендательный характер и может игнорироваться каналами без нативной поддержки выбора.
• Если канал не поддерживает выбор, fallback-текст перечисляет метки.

​

Примеры производителей

{
  "title": "Deploy approval",
  "tone": "warning",
  "blocks": [
    { "type": "text", "text": "Canary is ready to promote." },
    { "type": "context", "text": "Build 1234, staging passed." },
    {
      "type": "buttons",
      "buttons": [
        { "label": "Approve", "value": "deploy:approve", "style": "success" },
        { "label": "Decline", "value": "deploy:decline", "style": "danger" }
      ]
    }
  ]
}

{
  "blocks": [
    { "type": "text", "text": "Release notes are ready." },
    {
      "type": "buttons",
      "buttons": [{ "label": "Open notes", "url": "https://example.com/release" }]
    }
  ]
}

{
  "blocks": [
    {
      "type": "buttons",
      "buttons": [{ "label": "Launch", "web_app": { "url": "https://example.com/app" } }]
    }
  ]
}

{
  "title": "Choose environment",
  "blocks": [
    {
      "type": "select",
      "placeholder": "Environment",
      "options": [
        { "label": "Canary", "value": "env:canary" },
        { "label": "Production", "value": "env:prod" }
      ]
    }
  ]
}

openclaw message send --channel slack \
  --target channel:C123 \
  --message "Deploy approval" \
  --presentation '{"title":"Deploy approval","tone":"warning","blocks":[{"type":"text","text":"Canary is ready."},{"type":"buttons","buttons":[{"label":"Approve","value":"deploy:approve","style":"success"},{"label":"Decline","value":"deploy:decline","style":"danger"}]}]}'

openclaw message send --channel telegram \
  --target -1001234567890 \
  --message "Topic opened" \
  --pin

{
  "pin": {
    "enabled": true,
    "notify": true,
    "required": false
  }
}

​

Контракт рендерера

const adapter: ChannelOutboundAdapter = {
  deliveryMode: "direct",
  presentationCapabilities: {
    supported: true,
    buttons: true,
    selects: true,
    context: true,
    divider: true,
    limits: {
      actions: {
        maxActions: 25,
        maxActionsPerRow: 5,
        maxRows: 5,
        maxLabelLength: 80,
        maxValueBytes: 100,
        supportsStyles: true,
        supportsDisabled: false,
      },
      selects: {
        maxOptions: 25,
        maxLabelLength: 100,
        maxValueBytes: 100,
      },
      text: {
        maxLength: 2000,
        encoding: "characters",
        markdownDialect: "discord-markdown",
      },
    },
  },
  deliveryCapabilities: {
    pin: true,
  },
  renderPresentation({ payload, presentation, ctx }) {
    return renderNativePayload(payload, presentation, ctx);
  },
  async pinDeliveredMessage({ target, messageId, pin }) {
    await pinNativeMessage(target, messageId, { notify: pin.notify === true });
  },
};

type ChannelPresentationCapabilities = {
  supported?: boolean;
  buttons?: boolean;
  selects?: boolean;
  context?: boolean;
  divider?: boolean;
  limits?: {
    actions?: {
      maxActions?: number;
      maxActionsPerRow?: number;
      maxRows?: number;
      maxLabelLength?: number;
      maxValueBytes?: number;
      supportsStyles?: boolean;
      supportsDisabled?: boolean;
      supportsLayoutHints?: boolean;
    };
    selects?: {
      maxOptions?: number;
      maxLabelLength?: number;
      maxValueBytes?: number;
    };
    text?: {
      maxLength?: number;
      encoding?: "characters" | "utf8-bytes" | "utf16-units";
      markdownDialect?: "plain" | "markdown" | "html" | "slack-mrkdwn" | "discord-markdown";
      supportsEdit?: boolean;
    };
  };
};

​

Поток рендеринга ядра

1. Нормализует пейлоад представления.
2. Разрешает outbound-адаптер целевого канала.
3. Читает presentationCapabilities.
4. Применяет общие ограничения возможностей, такие как количество действий, длина меток и количество вариантов выбора, когда адаптер их объявляет.
5. Вызывает renderPresentation, когда адаптер может отрисовать пейлоад.
6. Возвращается к консервативному тексту, когда адаптер отсутствует или не может выполнить рендеринг.
7. Отправляет получившийся пейлоад через обычный путь доставки канала.
8. Применяет метаданные доставки, такие как delivery.pin, после первого успешно отправленного сообщения.

​

Правила деградации

• title первой строкой
• блоки text как обычные абзацы
• блоки context как компактные строки контекста
• блоки divider как визуальный разделитель
• метки кнопок, включая URL для кнопок-ссылок
• метки вариантов выбора

• Telegram с отключенными inline-кнопками отправляет текстовый fallback.
• Канал без поддержки выбора перечисляет варианты выбора как текст.
• Кнопка только с URL становится либо нативной кнопкой-ссылкой, либо fallback-строкой URL.
• Необязательные ошибки закрепления не приводят к сбою доставленного сообщения.

​

Сопоставление провайдеров

​

Представление и InteractiveReply

• текст
• кнопки
• списки выбора

• заголовок
• тон
• контекст
• разделитель
• кнопки только с URL
• общие метаданные доставки через ReplyPayload.delivery

import {
  adaptMessagePresentationForChannel,
  applyPresentationActionLimits,
  interactiveReplyToPresentation,
  normalizeMessagePresentation,
  presentationPageSize,
  presentationToInteractiveControlsReply,
  presentationToInteractiveReply,
  renderMessagePresentationFallbackText,
} from "openclaw/plugin-sdk/interactive-runtime";

• InteractiveReply, InteractiveReplyBlock, InteractiveReplyButton, InteractiveReplyOption, InteractiveReplySelectBlock и InteractiveReplyTextBlock
• normalizeInteractiveReply(...)
• hasInteractiveReplyBlocks(...)
• interactiveReplyToPresentation(...)
• presentationToInteractiveReply(...)
• presentationToInteractiveControlsReply(...)
• resolveInteractiveTextFallback(...)
• reduceInteractiveReply(...)

• используйте buildApprovalPresentationFromActionDescriptors(...) вместо buildApprovalInteractiveReplyFromActionDescriptors(...)
• используйте buildApprovalPresentation(...) вместо buildApprovalInteractiveReply(...)
• используйте buildExecApprovalPresentation(...) вместо buildExecApprovalInteractiveReply(...)

​

Закрепление доставки

• pin: true закрепляет первое успешно доставленное сообщение.
• pin.notify по умолчанию равно false.
• pin.required по умолчанию равно false.
• Необязательные ошибки закрепления деградируют и оставляют отправленное сообщение без изменений.
• Обязательные ошибки закрепления приводят к сбою доставки.
• Для сообщений, разбитых на части, закрепляется первая доставленная часть, а не последняя.

​

Контрольный список автора Plugin

• Объявляйте presentation из describeMessageTool(...), когда канал может отрендерить или безопасно деградировать семантическое представление.
• Добавьте presentationCapabilities в runtime-адаптер исходящих сообщений.
• Реализуйте renderPresentation в runtime-коде, а не в коде настройки Plugin на уровне управления.
• Не допускайте попадания нативных UI-библиотек в горячие пути настройки/каталога.
• Объявляйте общие ограничения возможностей в presentationCapabilities.limits, когда они известны.
• Сохраняйте окончательные ограничения платформы в рендерере и тестах.
• Добавьте fallback-тесты для неподдерживаемых кнопок, списков выбора, URL-кнопок, дублирования заголовка/текста и смешанных отправок message плюс presentation.
• Добавляйте поддержку закрепления доставки через deliveryCapabilities.pin и pinDeliveredMessage только тогда, когда провайдер может закрепить id отправленного сообщения.
• Не раскрывайте новые нативные для провайдера поля карточек/блоков/компонентов/кнопок через общую схему действий сообщений.

​

Связанные документы

• CLI сообщений
• Обзор SDK Plugin
• Архитектура Plugin
• План рефакторинга представления каналов