Refactorplan voor kanaalpresentatie

​

Status

• ReplyPayload.presentation draagt semantische bericht-UI.
• ReplyPayload.delivery.pin draagt aanvragen om verzonden berichten vast te pinnen.
• Gedeelde berichtacties stellen presentation, delivery en pin beschikbaar in plaats van provider-native components, blocks, buttons of card.
• De kern rendert of degradeert presentatie automatisch via door Plugins gedeclareerde uitgaande capabilities.
• Discord-, Slack-, Telegram-, Mattermost-, MS Teams- en Feishu-renderers gebruiken het generieke contract.
• Discord-kanaalcode voor de control plane importeert geen door Carbon ondersteunde UI-containers meer.

​

Probleem

• De kern bezit een Discord-vormige cross-context renderer-hook via buildCrossContextComponents.
• Discord channel.ts kan native Carbon-UI importeren via DiscordUiContainer, waardoor runtime-UI-afhankelijkheden in de control plane van de kanaal-Plugin terechtkomen.
• De agent en CLI stellen native payload-uitwegen beschikbaar, zoals Discord components, Slack blocks, Telegram- of Mattermost-buttons en Teams- of Feishu-card.
• ReplyPayload.channelData draagt zowel transporthints als native UI-enveloppen.
• Het generieke interactive-model bestaat, maar is smaller dan de rijkere layouts die al worden gebruikt door Discord, Slack, Teams, Feishu, LINE, Telegram en Mattermost.

​

Doelen

• De kern bepaalt de beste semantische presentatie voor een bericht op basis van gedeclareerde capabilities.
• Extensies declareren capabilities en renderen semantische presentatie naar native transportpayloads.
• Web Control UI blijft gescheiden van chat-native UI.
• Native kanaalpayloads worden niet beschikbaar gesteld via het gedeelde agent- of CLI-berichtoppervlak.
• Niet-ondersteunde presentatiefuncties degraderen automatisch naar de beste tekstrepresentatie.
• Aflevergedrag zoals het vastpinnen van een verzonden bericht is generieke afleveringsmetadata, geen presentatie.

​

Niet-doelen

• Geen achterwaartse-compatibiliteitsshims voor buildCrossContextComponents.
• Geen openbare native uitwegen voor components, blocks, buttons of card.
• Geen kernimports van kanaal-native UI-bibliotheken.
• Geen provider-specifieke SDK-naden voor gebundelde kanalen.

​

Doelmodel

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-tekstblok mappt naar presentation.blocks[].type = "text".
• interactive-knoppenblok mappt naar presentation.blocks[].type = "buttons".
• interactive-selectieblok mappt naar presentation.blocks[].type = "select".

​

Afleveringsmetadata

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

• delivery.pin = true betekent dat het eerste succesvol afgeleverde bericht wordt vastgepind.
• notify is standaard false.
• required is standaard false; niet-ondersteunde kanalen of mislukt vastpinnen degraderen automatisch door aflevering voort te zetten.
• Handmatige berichtacties pin, unpin en list-pins blijven bestaan voor bestaande berichten.

​

Runtime-capabilitycontract

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>;
};

• Los het doelkanaal en de runtime-adapter op.
• Vraag om presentatie-capabilities.
• Degradeer niet-ondersteunde blokken en pas generieke capabilitylimieten toe vóór rendering.
• Roep renderPresentation aan.
• Als er geen renderer bestaat, converteer presentatie naar tekstfallback.
• Roep na succesvol verzenden pinDeliveredMessage aan wanneer delivery.pin is aangevraagd en wordt ondersteund.

​

Kanaaltoewijzing

• Render presentation naar components v2 en Carbon-containers in modules die alleen in runtime worden gebruikt.
• Houd helpers voor accentkleuren in lichte modules.
• Verwijder DiscordUiContainer-imports uit control-plane-code van de kanaal-Plugin.

• Render presentation naar Block Kit.
• Verwijder agent- en CLI-invoer blocks.

• Render tekst, context en scheidingslijnen als tekst.
• Render acties en selectie als inline toetsenborden wanneer geconfigureerd en toegestaan voor het doeloppervlak.
• Gebruik tekstfallback wanneer inline knoppen zijn uitgeschakeld.
• Verplaats ACP-topicvastpinnen naar delivery.pin.

• Render acties als interactieve knoppen waar geconfigureerd.
• Render andere blokken als tekstfallback.

• Render presentation naar Adaptive Cards.
• Behoud handmatige acties voor vastpinnen, losmaken en pins weergeven.
• Implementeer eventueel pinDeliveredMessage als Graph-ondersteuning betrouwbaar is voor het doelgesprek.

• Render presentation naar interactieve kaarten.
• Behoud handmatige acties voor vastpinnen, losmaken en pins weergeven.
• Implementeer eventueel pinDeliveredMessage voor het vastpinnen van verzonden berichten als API-gedrag betrouwbaar is.

• Render presentation waar mogelijk naar Flex- of templateberichten.
• Val terug op tekst voor niet-ondersteunde blokken.
• Verwijder LINE-UI-payloads uit channelData.

• Converteer presentatie naar tekst met conservatieve opmaak.

​

Refactorstappen

1. Pas de Discord-releasefix opnieuw toe die ui-colors.ts splitst van door Carbon ondersteunde UI en DiscordUiContainer verwijdert uit extensions/discord/src/channel.ts.
2. Voeg presentation en delivery toe aan ReplyPayload, normalisatie van uitgaande payloads, afleveringssamenvattingen en hook-payloads.
3. Voeg MessagePresentation-schema en parserhelpers toe in een smal SDK/runtime-subpad.
4. Vervang bericht-capabilities buttons, cards, components en blocks door semantische presentatie-capabilities.
5. Voeg runtime-uitgaande adapter-hooks toe voor presentatierendering en afleveringsvastpinnen.
6. Vervang cross-context componentconstructie door buildCrossContextPresentation.
7. Verwijder src/infra/outbound/channel-adapters.ts en verwijder buildCrossContextComponents uit kanaal-Plugin-typen.
8. Wijzig maybeApplyCrossContextMarker zodat deze presentation koppelt in plaats van native parameters.
9. Werk plugin-dispatch-verzendpaden bij zodat ze alleen semantische presentatie en afleveringsmetadata gebruiken.
10. Verwijder native payload-parameters voor agent en CLI: components, blocks, buttons en card.
11. Verwijder SDK-helpers die native berichttool-schema’s maken en vervang ze door presentatieschemahelpers.
12. Verwijder UI/native enveloppen uit channelData; behoud alleen transportmetadata totdat elk resterend veld is beoordeeld.
13. Migreer Discord-, Slack-, Telegram-, Mattermost-, MS Teams-, Feishu- en LINE-renderers.
14. Werk documentatie bij voor bericht-CLI, kanaalpagina’s, Plugin-SDK en capability-cookbook.
15. Voer import-fanoutprofilering uit voor Discord en getroffen kanaal-entrypoints.

​

Tests

• Tests voor presentatienormalisatie.
• Tests voor automatische presentatiedegradatie bij niet-ondersteunde blokken.
• Cross-context markertests voor plugin-dispatch en kernafleveringspaden.
• Kanaalrender-matrixtests voor Discord, Slack, Telegram, Mattermost, MS Teams, Feishu, LINE en tekstfallback.
• Tests voor berichttool-schema’s die bewijzen dat native velden verdwenen zijn.
• CLI-tests die bewijzen dat native flags verdwenen zijn.
• Regressietest voor importluiheid van Discord-entrypoint rond Carbon.
• Tests voor afleveringsvastpinnen voor Telegram en generieke fallback.

​

Open vragen

• Moet delivery.pin in de eerste pass worden geïmplementeerd voor Discord, Slack, MS Teams en Feishu, of eerst alleen voor Telegram?
• Moet delivery uiteindelijk bestaande velden opnemen zoals replyToId, replyToCurrent, silent en audioAsVoice, of gericht blijven op gedrag na verzending?
• Moet presentatie direct afbeeldingen of bestandsverwijzingen ondersteunen, of moet media voorlopig gescheiden blijven van UI-layout?

​

Gerelateerd

• Kanalenoverzicht
• Berichtpresentatie