Plano de refatoração da apresentação de canais

​

Status

• ReplyPayload.presentation transporta a interface semântica da mensagem.
• ReplyPayload.delivery.pin transporta solicitações para fixar mensagens enviadas.
• As ações de mensagem compartilhadas expõem presentation, delivery e pin, em vez de components, blocks, buttons ou card nativos do provedor.
• O núcleo renderiza ou degrada automaticamente a apresentação por meio dos recursos de saída declarados pelo plugin.
• Os renderizadores do Discord, Slack, Telegram, Mattermost, MS Teams e Feishu consomem o contrato genérico.
• O código do plano de controle do canal Discord não importa mais contêineres de interface baseados no Carbon.

​

Problema

• O núcleo possui um hook de renderização entre contextos no formato do Discord por meio de buildCrossContextComponents.
• O channel.ts do Discord pode importar a interface nativa do Carbon por meio de DiscordUiContainer, o que incorpora dependências de interface em tempo de execução ao plano de controle do plugin de canal.
• O agente e a CLI expõem mecanismos de escape para payloads nativos, como components do Discord, blocks do Slack, buttons do Telegram ou Mattermost e card do Teams ou Feishu.
• ReplyPayload.channelData transporta tanto indicações de transporte quanto envelopes de interface nativa.
• O modelo genérico interactive existe, mas é mais limitado do que os layouts mais sofisticados já usados pelo Discord, Slack, Teams, Feishu, LINE, Telegram e Mattermost.

​

Objetivos

• O núcleo decide a melhor apresentação semântica para uma mensagem com base nos recursos declarados.
• As extensões declaram recursos e renderizam a apresentação semântica em payloads de transporte nativos.
• A interface Web Control permanece separada da interface nativa de chat.
• Os payloads nativos de canais não são expostos pela superfície compartilhada de mensagens do agente ou da CLI.
• Recursos de apresentação não compatíveis são automaticamente degradados para a melhor representação em texto.
• Comportamentos de entrega, como fixar uma mensagem enviada, são metadados genéricos de entrega, não de apresentação.

​

Fora do escopo

• Nenhuma camada de compatibilidade retroativa para buildCrossContextComponents.
• Nenhum mecanismo de escape nativo público para components, blocks, buttons ou card.
• Nenhuma importação, pelo núcleo, de bibliotecas de interface nativas de canais.
• Nenhuma interface de SDK específica de provedor para canais incluídos.

​

Modelo desejado

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

• O bloco de texto de interactive corresponde a presentation.blocks[].type = "text".
• O bloco de botões de interactive corresponde a presentation.blocks[].type = "buttons".
• O bloco de seleção de interactive corresponde a presentation.blocks[].type = "select".

​

Metadados de entrega

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

• delivery.pin = true significa fixar a primeira mensagem entregue com sucesso.
• O valor padrão de notify é false.
• O valor padrão de required é false; canais não compatíveis ou falhas ao fixar degradam automaticamente, permitindo que a entrega continue.
• As ações manuais de mensagem pin, unpin e list-pins permanecem disponíveis para mensagens existentes.

​

Contrato de recursos do runtime

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

• Resolver o canal de destino e o adaptador do runtime.
• Consultar os recursos de apresentação.
• Degradar blocos não compatíveis e aplicar limites genéricos de recursos antes da renderização.
• Chamar renderPresentation.
• Se não houver um renderizador, converter a apresentação em um fallback de texto.
• Após um envio bem-sucedido, chamar pinDeliveredMessage quando delivery.pin for solicitado e houver suporte.

​

Mapeamento de canais

• Renderizar presentation em componentes v2 e contêineres Carbon em módulos exclusivos do runtime.
• Manter os auxiliares de cores de destaque em módulos leves.
• Remover as importações de DiscordUiContainer do código do plano de controle do plugin de canal.

• Renderizar presentation em Block Kit.
• Remover a entrada blocks do agente e da CLI.

• Renderizar texto, contexto e divisores como texto.
• Renderizar ações e seleções como teclados embutidos quando configurado e permitido para a superfície de destino.
• Usar fallback de texto quando os botões embutidos estiverem desativados.
• Migrar a fixação de tópicos ACP para delivery.pin.

• Renderizar ações como botões interativos quando configurado.
• Renderizar outros blocos como fallback de texto.

• Renderizar presentation em Adaptive Cards.
• Manter as ações manuais pin/unpin/list-pins.
• Implementar opcionalmente pinDeliveredMessage se o suporte do Graph for confiável para a conversa de destino.

• Renderizar presentation em cartões interativos.
• Manter as ações manuais pin/unpin/list-pins.
• Implementar opcionalmente pinDeliveredMessage para fixar mensagens enviadas, caso o comportamento da API seja confiável.

• Renderizar presentation em mensagens Flex ou de modelo quando possível.
• Usar fallback de texto para blocos não compatíveis.
• Remover os payloads de interface do LINE de channelData.

• Converter a apresentação em texto com formatação conservadora.

​

Etapas da refatoração

1. Reaplicar a correção de versão do Discord que separa ui-colors.ts da interface baseada no Carbon e remove DiscordUiContainer de extensions/discord/src/channel.ts.
2. Adicionar presentation e delivery a ReplyPayload, à normalização de payloads de saída, aos resumos de entrega e aos payloads de hooks.
3. Adicionar o esquema MessagePresentation e auxiliares de análise em um subcaminho restrito do SDK/runtime.
4. Substituir os recursos de mensagem buttons, cards, components e blocks por recursos de apresentação semântica.
5. Adicionar hooks ao adaptador de saída do runtime para renderização da apresentação e fixação na entrega.
6. Substituir a construção de componentes entre contextos por buildCrossContextPresentation.
7. Excluir src/infra/outbound/channel-adapters.ts e remover buildCrossContextComponents dos tipos de plugins de canal.
8. Alterar maybeApplyCrossContextMarker para anexar presentation em vez de parâmetros nativos.
9. Atualizar os caminhos de envio do dispatcher de plugins para consumir somente apresentação semântica e metadados de entrega.
10. Remover os parâmetros de payload nativo do agente e da CLI: components, blocks, buttons e card.
11. Remover os auxiliares do SDK que criam esquemas nativos de ferramentas de mensagem, substituindo-os por auxiliares de esquema de apresentação.
12. Remover envelopes nativos/de interface de channelData; manter somente metadados de transporte até que cada campo restante seja revisado.
13. Migrar os renderizadores do Discord, Slack, Telegram, Mattermost, MS Teams, Feishu e LINE.
14. Atualizar a documentação da CLI de mensagens, das páginas de canais, do SDK de plugins e do guia prático de recursos.
15. Executar a análise de propagação de importações para o Discord e os pontos de entrada dos canais afetados.

​

Testes

• Testes de normalização da apresentação.
• Testes de degradação automática da apresentação para blocos não compatíveis.
• Testes de marcadores entre contextos para o dispatcher de plugins e os caminhos de entrega do núcleo.
• Testes da matriz de renderização de canais para Discord, Slack, Telegram, Mattermost, MS Teams, Feishu, LINE e fallback de texto.
• Testes do esquema de ferramentas de mensagem que comprovem a remoção dos campos nativos.
• Testes da CLI que comprovem a remoção das opções nativas.
• Regressão de carregamento tardio das importações do ponto de entrada do Discord abrangendo o Carbon.
• Testes de fixação na entrega abrangendo o Telegram e o fallback genérico.

​

Questões em aberto

• delivery.pin deve ser implementado para Discord, Slack, MS Teams e Feishu na primeira etapa ou inicialmente apenas para o Telegram?
• delivery deve futuramente incorporar campos existentes como replyToId, replyToCurrent, silent e audioAsVoice, ou permanecer focado em comportamentos posteriores ao envio?
• A apresentação deve oferecer suporte direto a imagens ou referências de arquivos, ou a mídia deve permanecer separada do layout da interface por enquanto?

​

Relacionado

• Visão geral dos canais
• Apresentação de mensagens