Get started

План рефакторингу представлення каналів

Стан

Реалізовано для спільних поверхонь агента, CLI, можливостей плагінів і вихідної доставки:

ReplyPayload.presentation переносить семантичний інтерфейс повідомлення.
ReplyPayload.delivery.pin переносить запити на закріплення надісланого повідомлення.
Спільні дії з повідомленнями надають presentation, delivery і pin замість нативних для провайдера components, blocks, buttons або card.
Ядро відтворює представлення або автоматично спрощує його відповідно до заявлених плагіном можливостей вихідної доставки.
Рендерери Discord, Slack, Telegram, Mattermost, MS Teams і Feishu використовують універсальний контракт.
Код площини керування каналом Discord більше не імпортує контейнери інтерфейсу на основі Carbon.

Канонічна документація тепер міститься в розділі Представлення повідомлень. Зберігайте цей план як історичний контекст реалізації; у разі змін контракту, рендерера або поведінки резервного варіанта оновлюйте канонічний посібник.

Проблема

Наразі інтерфейс каналів розділений між кількома несумісними поверхнями:

Ядро володіє міжконтекстним хуком рендерера у формі Discord через buildCrossContextComponents.
channel.ts Discord може імпортувати нативний інтерфейс Carbon через DiscordUiContainer, що додає залежності інтерфейсу середовища виконання до площини керування плагіном каналу.
Агент і CLI надають обхідні шляхи для нативних корисних даних, як-от components Discord, blocks Slack, buttons Telegram або Mattermost і card Teams або Feishu.
ReplyPayload.channelData містить як транспортні підказки, так і нативні оболонки інтерфейсу.
Універсальна модель interactive існує, але вона вужча за розвиненіші макети, які вже використовують Discord, Slack, Teams, Feishu, LINE, Telegram і Mattermost.

Через це ядро знає про форми нативних інтерфейсів, послаблюється ліниве завантаження середовища виконання плагінів, а агенти отримують забагато специфічних для провайдерів способів виразити той самий намір повідомлення.

Цілі

Ядро визначає найкраще семантичне представлення повідомлення на основі заявлених можливостей.
Розширення заявляють можливості та перетворюють семантичне представлення на нативні транспортні корисні дані.
Вебінтерфейс керування залишається відокремленим від нативного інтерфейсу чату.
Нативні корисні дані каналів не надаються через спільну поверхню повідомлень агента або CLI.
Непідтримувані функції представлення автоматично спрощуються до найкращого текстового представлення.
Поведінка доставки, як-от закріплення надісланого повідомлення, є універсальними метаданими доставки, а не представленням.

Нецілі

Без шару зворотної сумісності для buildCrossContextComponents.
Без публічних обхідних шляхів до нативних components, blocks, buttons або card.
Без імпортів бібліотек нативного інтерфейсу каналів у ядро.
Без специфічних для провайдерів поверхонь SDK для вбудованих каналів.

Цільова модель

Додайте до ReplyPayload поле presentation, яким володіє ядро.

type MessagePresentationTone = "neutral" | "info" | "success" | "warning" | "danger"; type MessagePresentation = {  tone?: MessagePresentationTone;  title?: string;  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 MessagePresentationButton = {  label: string;  value?: string;  url?: string;  style?: "primary" | "secondary" | "success" | "danger";}; type MessagePresentationOption = {  label: string;  value: string;};

Під час міграції interactive стає підмножиною presentation:

Текстовий блок interactive зіставляється з presentation.blocks[].type = "text".
Блок кнопок interactive зіставляється з presentation.blocks[].type = "buttons".
Блок вибору interactive зіставляється з presentation.blocks[].type = "select".

Зовнішні схеми агента та CLI тепер використовують presentation; interactive залишається внутрішнім застарілим допоміжним засобом аналізу й рендерингу для наявних виробників відповідей. У публічному API для виробників interactive вважається застарілим. Підтримка в середовищі виконання зберігається, щоб наявні допоміжні засоби схвалення та старіші плагіни продовжували працювати, тоді як новий код формує presentation.

Метадані доставки

Додайте поле delivery, яким володіє ядро, для поведінки надсилання, що не стосується інтерфейсу.

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

Семантика:

delivery.pin = true означає закріпити перше успішно доставлене повідомлення.
Типове значення notify — false.
Типове значення required — false; непідтримувані канали або невдале закріплення автоматично спрощують поведінку, продовжуючи доставку.
Ручні дії з повідомленнями pin, unpin і list-pins зберігаються для наявних повідомлень.

Поточне прив’язування теми Telegram ACP слід перенести з channelData.telegram.pin = true до delivery.pin = true.

Контракт можливостей середовища виконання

Додайте хуки рендерингу представлення та доставки до вихідного адаптера середовища виконання, а не до плагіна каналу площини керування.

type ChannelPresentationCapabilities = {  supported: boolean;  buttons?: boolean;  selects?: boolean;  context?: boolean;  divider?: boolean;  tones?: MessagePresentationTone[];  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;    };  };}; type ChannelDeliveryCapabilities = {  pinSentMessage?: boolean;}; type ChannelOutboundAdapter = {  presentationCapabilities?: ChannelPresentationCapabilities;   renderPresentation?: (params: {    payload: ReplyPayload;    presentation: MessagePresentation;    ctx: ChannelOutboundSendContext;  }) => ReplyPayload | null;   deliveryCapabilities?: ChannelDeliveryCapabilities;   pinDeliveredMessage?: (params: {    cfg: OpenClawConfig;    accountId?: string | null;    to: string;    threadId?: string | number | null;    messageId: string;    notify: boolean;  }) => Promise<void>;};

Поведінка ядра:

Визначити цільовий канал і адаптер середовища виконання.
Запросити можливості представлення.
Спростити непідтримувані блоки та застосувати універсальні обмеження можливостей перед рендерингом.
Викликати renderPresentation.
Якщо рендерера немає, перетворити представлення на резервний текст.
Після успішного надсилання викликати pinDeliveredMessage, коли запитано delivery.pin і ця можливість підтримується.

Зіставлення каналів

Discord:

Перетворювати presentation на компоненти v2 та контейнери Carbon у модулях лише для середовища виконання.
Зберігати допоміжні засоби кольорів акценту в легких модулях.
Видалити імпорти DiscordUiContainer з коду площини керування плагіном каналу.

Slack:

Перетворювати presentation на Block Kit.
Видалити вхідний параметр blocks агента та CLI.

Telegram:

Відтворювати текст, контекст і роздільники як текст.
Відтворювати дії та вибір як вбудовані клавіатури, якщо це налаштовано й дозволено для цільової поверхні.
Використовувати резервний текст, коли вбудовані кнопки вимкнено.
Перенести закріплення тем ACP до delivery.pin.

Mattermost:

Відтворювати дії як інтерактивні кнопки, якщо це налаштовано.
Відтворювати інші блоки як резервний текст.

MS Teams:

Перетворювати presentation на Adaptive Cards.
Зберегти ручні дії закріплення, відкріплення та перегляду списку закріплень.
За потреби реалізувати pinDeliveredMessage, якщо підтримка Graph надійна для цільової розмови.

Feishu:

Перетворювати presentation на інтерактивні картки.
Зберегти ручні дії закріплення, відкріплення та перегляду списку закріплень.
За потреби реалізувати pinDeliveredMessage для закріплення надісланого повідомлення, якщо поведінка API надійна.

LINE:

За можливості перетворювати presentation на повідомлення Flex або шаблонні повідомлення.
Для непідтримуваних блоків повертатися до тексту.
Видалити корисні дані інтерфейсу LINE з channelData.

Прості або обмежені канали:

Перетворювати представлення на текст із консервативним форматуванням.

Етапи рефакторингу

Повторно застосувати виправлення випуску Discord, яке відокремлює ui-colors.ts від інтерфейсу на основі Carbon і видаляє DiscordUiContainer з extensions/discord/src/channel.ts.
Додати presentation і delivery до ReplyPayload, нормалізації вихідних корисних даних, зведень доставки та корисних даних хуків.
Додати схему MessagePresentation і допоміжні засоби аналізу у вузькому підшляху SDK/середовища виконання.
Замінити можливості повідомлень buttons, cards, components і blocks на можливості семантичного представлення.
Додати до вихідного адаптера середовища виконання хуки для рендерингу представлення та закріплення доставленого повідомлення.
Замінити побудову міжконтекстних компонентів на buildCrossContextPresentation.
Видалити src/infra/outbound/channel-adapters.ts і вилучити buildCrossContextComponents із типів плагіна каналу.
Змінити maybeApplyCrossContextMarker, щоб він додавав presentation замість нативних параметрів.
Оновити шляхи надсилання диспетчеризації плагінів, щоб вони використовували лише семантичне представлення та метадані доставки.
Видалити нативні параметри корисних даних агента та CLI: components, blocks, buttons і card.
Видалити допоміжні засоби SDK, які створюють нативні схеми інструментів повідомлень, замінивши їх допоміжними засобами схеми представлення.
Видалити інтерфейсні/нативні оболонки з channelData; зберігати лише транспортні метадані, доки не буде перевірено кожне решту полів.
Мігрувати рендерери Discord, Slack, Telegram, Mattermost, MS Teams, Feishu і LINE.
Оновити документацію для CLI повідомлень, сторінок каналів, SDK плагінів і збірника рецептів можливостей.
Виконати профілювання розгалуження імпортів для Discord і зачеплених точок входу каналів.

Етапи 1–11 і 13–14 реалізовано в цьому рефакторингу для спільних контрактів агента, CLI, можливостей плагінів і вихідного адаптера. Етап 12 залишається глибшим проходом внутрішнього очищення приватних для провайдерів транспортних оболонок channelData. Етап 15 залишається подальшою перевіркою, якщо потрібні кількісні показники розгалуження імпортів поза межами перевірки типів і тестів.

Тести

Додати або оновити:

Тести нормалізації представлення.
Тести автоматичного спрощення представлення для непідтримуваних блоків.
Тести міжконтекстних маркерів для диспетчеризації плагінів і основних шляхів доставки.
Матричні тести рендерингу каналів для Discord, Slack, Telegram, Mattermost, MS Teams, Feishu, LINE і резервного тексту.
Тести схеми інструментів повідомлень, які доводять, що нативні поля вилучено.
Тести CLI, які доводять, що нативні прапорці вилучено.
Регресійний тест лінивості імпортів точки входу Discord, що охоплює Carbon.
Тести закріплення доставки, що охоплюють Telegram і універсальний резервний варіант.

Відкриті питання

Чи слід у першому проході реалізувати delivery.pin для Discord, Slack, MS Teams і Feishu, чи спочатку лише для Telegram?
Чи має delivery згодом увібрати наявні поля, як-от replyToId, replyToCurrent, silent і audioAsVoice, чи залишитися зосередженим на поведінці після надсилання?
Чи має представлення безпосередньо підтримувати зображення або посилання на файли, чи наразі медіа мають залишатися відокремленими від макета інтерфейсу?

Пов’язане

Was this useful?