Piano di refactoring della presentazione del canale

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Stato

• ReplyPayload.presentation trasporta l’interfaccia semantica dei messaggi.
• ReplyPayload.delivery.pin trasporta le richieste di fissaggio dei messaggi inviati.
• Le azioni di messaggistica condivise espongono presentation, delivery e pin invece di components, blocks, buttons o card nativi del provider.
• Il core renderizza o degrada automaticamente la presentazione tramite le capacità in uscita dichiarate dal plugin.
• I renderer di Discord, Slack, Telegram, Mattermost, MS Teams e Feishu consumano il contratto generico.
• Il codice del control plane del canale Discord non importa più contenitori UI basati su Carbon.

​

Problema

• Il core possiede un hook di rendering cross-context modellato su Discord tramite buildCrossContextComponents.
• channel.ts di Discord può importare l’interfaccia nativa Carbon tramite DiscordUiContainer, che porta dipendenze UI runtime nel control plane del plugin del canale.
• L’agente e la CLI espongono vie di fuga per payload nativi come components di Discord, blocks di Slack, buttons di Telegram o Mattermost e card di Teams o Feishu.
• ReplyPayload.channelData trasporta sia suggerimenti di trasporto sia envelope UI nativi.
• Il modello generico interactive esiste, ma è più ristretto dei layout più ricchi già usati da Discord, Slack, Teams, Feishu, LINE, Telegram e Mattermost.

​

Obiettivi

• Il core decide la migliore presentazione semantica per un messaggio in base alle capacità dichiarate.
• Le estensioni dichiarano capacità e renderizzano la presentazione semantica in payload di trasporto nativi.
• La Web Control UI resta separata dall’interfaccia nativa della chat.
• I payload nativi dei canali non sono esposti tramite la superficie di messaggistica condivisa dell’agente o della CLI.
• Le funzionalità di presentazione non supportate degradano automaticamente alla migliore rappresentazione testuale.
• Il comportamento di recapito, come fissare un messaggio inviato, è metadato generico di recapito, non presentazione.

​

Non obiettivi

• Nessuno shim di compatibilità all’indietro per buildCrossContextComponents.
• Nessuna via di fuga nativa pubblica per components, blocks, buttons o card.
• Nessuna importazione core di librerie UI native dei canali.
• Nessun seam SDK specifico per provider per i canali inclusi.

​

Modello target

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

• Il blocco di testo interactive viene mappato a presentation.blocks[].type = "text".
• Il blocco di pulsanti interactive viene mappato a presentation.blocks[].type = "buttons".
• Il blocco di selezione interactive viene mappato a presentation.blocks[].type = "select".

​

Metadati di recapito

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

• delivery.pin = true significa fissare il primo messaggio recapitato con successo.
• notify ha valore predefinito false.
• required ha valore predefinito false; i canali non supportati o il fissaggio non riuscito degradano automaticamente continuando il recapito.
• Le azioni manuali di messaggistica pin, unpin e list-pins restano per i messaggi esistenti.

​

Contratto di capacità runtime

type ChannelPresentationCapabilities = {
  supported: boolean;
  buttons?: boolean;
  selects?: boolean;
  context?: boolean;
  divider?: boolean;
  tones?: MessagePresentationTone[];
};

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

• Risolvi il canale di destinazione e l’adapter runtime.
• Richiedi le capacità di presentazione.
• Degrada i blocchi non supportati prima del rendering.
• Chiama renderPresentation.
• Se non esiste alcun renderer, converti la presentazione in fallback testuale.
• Dopo un invio riuscito, chiama pinDeliveredMessage quando delivery.pin è richiesto e supportato.

​

Mappatura dei canali

• Renderizza presentation in componenti v2 e contenitori Carbon in moduli solo runtime.
• Mantieni gli helper dei colori di accento in moduli leggeri.
• Rimuovi le importazioni di DiscordUiContainer dal codice del control plane del plugin del canale.

• Renderizza presentation in Block Kit.
• Rimuovi l’input blocks di agente e CLI.

• Renderizza testo, contesto e divisori come testo.
• Renderizza azioni e selezione come tastiere inline quando configurato e consentito per la superficie di destinazione.
• Usa il fallback testuale quando i pulsanti inline sono disabilitati.
• Sposta il fissaggio del topic ACP in delivery.pin.

• Renderizza le azioni come pulsanti interattivi quando configurato.
• Renderizza gli altri blocchi come fallback testuale.

• Renderizza presentation in Adaptive Cards.
• Mantieni le azioni manuali pin/unpin/list-pins.
• Implementa opzionalmente pinDeliveredMessage se il supporto Graph è affidabile per la conversazione di destinazione.

• Renderizza presentation in schede interattive.
• Mantieni le azioni manuali pin/unpin/list-pins.
• Implementa opzionalmente pinDeliveredMessage per il fissaggio dei messaggi inviati se il comportamento dell’API è affidabile.

• Renderizza presentation in messaggi Flex o template dove possibile.
• Ripiega sul testo per i blocchi non supportati.
• Rimuovi i payload UI di LINE da channelData.

• Converti la presentazione in testo con formattazione conservativa.

​

Passaggi di refactor

1. Riapplica la correzione di rilascio Discord che separa ui-colors.ts dall’interfaccia basata su Carbon e rimuove DiscordUiContainer da extensions/discord/src/channel.ts.
2. Aggiungi presentation e delivery a ReplyPayload, alla normalizzazione dei payload in uscita, ai riepiloghi di recapito e ai payload degli hook.
3. Aggiungi lo schema MessagePresentation e gli helper di parsing in un sotto-percorso SDK/runtime ristretto.
4. Sostituisci le capacità dei messaggi buttons, cards, components e blocks con capacità di presentazione semantica.
5. Aggiungi hook dell’adapter runtime in uscita per rendering della presentazione e fissaggio del recapito.
6. Sostituisci la costruzione dei componenti cross-context con buildCrossContextPresentation.
7. Elimina src/infra/outbound/channel-adapters.ts e rimuovi buildCrossContextComponents dai tipi dei plugin dei canali.
8. Modifica maybeApplyCrossContextMarker per allegare presentation invece dei parametri nativi.
9. Aggiorna i percorsi di invio di plugin-dispatch per consumare solo presentazione semantica e metadati di recapito.
10. Rimuovi i parametri di payload nativi di agente e CLI: components, blocks, buttons e card.
11. Rimuovi gli helper SDK che creano schemi nativi degli strumenti di messaggistica, sostituendoli con helper dello schema di presentazione.
12. Rimuovi envelope UI/nativi da channelData; mantieni solo i metadati di trasporto finché ogni campo rimanente non viene revisionato.
13. Migra i renderer di Discord, Slack, Telegram, Mattermost, MS Teams, Feishu e LINE.
14. Aggiorna la documentazione per la CLI dei messaggi, le pagine dei canali, l’SDK dei plugin e il ricettario delle capacità.
15. Esegui la profilazione del fanout delle importazioni per Discord e gli entrypoint dei canali interessati.

​

Test

• Test di normalizzazione della presentazione.
• Test di degradazione automatica della presentazione per blocchi non supportati.
• Test del marcatore cross-context per plugin dispatch e percorsi di recapito core.
• Test della matrice di rendering dei canali per Discord, Slack, Telegram, Mattermost, MS Teams, Feishu, LINE e fallback testuale.
• Test dello schema degli strumenti di messaggistica che dimostrino la rimozione dei campi nativi.
• Test della CLI che dimostrino la rimozione dei flag nativi.
• Regressione sulla pigrizia delle importazioni dell’entrypoint Discord relativa a Carbon.
• Test di fissaggio del recapito per Telegram e fallback generico.

​

Questioni aperte

• delivery.pin dovrebbe essere implementato per Discord, Slack, MS Teams e Feishu nel primo passaggio, o inizialmente solo per Telegram?
• delivery dovrebbe infine assorbire campi esistenti come replyToId, replyToCurrent, silent e audioAsVoice, o restare focalizzato sui comportamenti post-invio?
• La presentazione dovrebbe supportare direttamente immagini o riferimenti a file, oppure per ora i media dovrebbero restare separati dal layout UI?

​

Correlati

• Panoramica dei canali
• Presentazione dei messaggi