Refactoring del ciclo di vita dei messaggi

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.

• Le primitive del core dovrebbero essere receive e send, non reply.
• Una risposta è solo una relazione su un messaggio in uscita.
• Un turno è una comodità per l’elaborazione in ingresso, non il proprietario della consegna.
• L’invio deve essere basato sul contesto: begin, rendering, anteprima o streaming, invio finale, commit, fail.
• Anche la ricezione deve essere basata sul contesto: normalizzazione, deduplicazione, instradamento, registrazione, dispatch, ack della piattaforma, fail.
• L’SDK pubblico dei plugin dovrebbe ridursi a una piccola superficie per i messaggi di canale.

​

Problemi

• Gli adapter in ingresso semplici usano runtime.channel.turn.run.
• Gli adapter avanzati usano runtime.channel.turn.runPrepared.
• Gli helper legacy usano dispatchInboundReplyWithBase, recordInboundSessionAndDispatchReply, helper per payload di risposta, suddivisione in parti delle risposte, riferimenti di risposta e helper runtime in uscita.
• Lo streaming di anteprima vive nei dispatcher specifici del canale.
• La durabilità della consegna finale viene aggiunta attorno ai percorsi esistenti dei payload di risposta.

Telegram polling update acked
  -> assistant final text exists
  -> process restarts before sendMessage succeeds
  -> final response is lost

​

Obiettivi

• Un unico ciclo di vita core per tutti i percorsi di ricezione e invio dei messaggi di canale.
• Invii finali durevoli per impostazione predefinita nel nuovo ciclo di vita dei messaggi dopo che un adapter dichiara un comportamento sicuro per il replay.
• Semantiche condivise per anteprima, modifica, streaming, finalizzazione, retry, recupero e ricevute.
• Una piccola superficie SDK dei plugin che i plugin di terze parti possano imparare e mantenere.
• Compatibilità per i chiamanti channel.turn esistenti durante la migrazione.
• Punti di estensione chiari per nuove capacità di canale.
• Nessun ramo specifico della piattaforma nel core.
• Nessun messaggio di canale token-delta. Lo streaming di canale rimane consegna tramite anteprima del messaggio, modifica, append o blocco completato.
• Metadati strutturati di origine OpenClaw per output operativi/di sistema, così che gli errori visibili del Gateway non rientrino nelle stanze condivise abilitate ai bot come nuovi prompt.

​

Non obiettivi

• Non rimuovere runtime.channel.turn.* nella prima fase.
• Non forzare ogni canale nello stesso comportamento di trasporto nativo.
• Non insegnare al core topic Telegram, stream nativi Slack, redazioni Matrix, schede Feishu, voce QQ o attività Teams.
• Non pubblicare tutti gli helper interni di migrazione come API SDK stabile.
• Non fare in modo che i retry riproducano operazioni di piattaforma non idempotenti già completate.

​

Modello di riferimento

• Chat
• Thread
• Channel
• Message
• metodi adapter come postMessage, editMessage, deleteMessage, stream, startTyping e recuperi della cronologia
• un adapter di stato per deduplicazione, lock, code e persistenza

• Intenti di invio in uscita durevoli prima delle chiamate dirette al trasporto.
• Contesti di invio espliciti con begin, commit e fail.
• Contesti di ricezione che conoscono la policy di ack della piattaforma.
• Ricevute che sopravvivono al riavvio e possono guidare modifiche, eliminazioni, recupero e soppressione dei duplicati.
• Un SDK pubblico più piccolo. I plugin inclusi possono usare helper runtime interni, ma i plugin di terze parti dovrebbero vedere un’unica API coerente per i messaggi.
• Comportamento specifico dell’agente: sessioni, trascrizioni, streaming a blocchi, avanzamento degli strumenti, approvazioni, direttive media, risposte silenziose e cronologia delle menzioni nei gruppi.

​

Modello core

core.messages.receive(...)
core.messages.send(...)
core.messages.live(...)
core.messages.state(...)

​

Termini dei messaggi

​

Messaggio

type ChannelMessage = {
  id: string;
  channel: string;
  accountId?: string;
  direction: "inbound" | "outbound";
  target: MessageTarget;
  sender?: MessageActor;
  body?: MessageBody;
  attachments?: MessageAttachment[];
  relation?: MessageRelation;
  origin?: MessageOrigin;
  timestamp?: number;
  raw?: unknown;
};

​

Destinazione

type MessageTarget = {
  kind: "direct" | "group" | "channel" | "thread";
  id: string;
  label?: string;
  spaceId?: string;
  parentId?: string;
  threadId?: string;
  nativeChannelId?: string;
};

​

Relazione

type MessageRelation =
  | {
      kind: "reply";
      inboundMessageId?: string;
      replyToId?: string;
      threadId?: string;
      quote?: MessageQuote;
    }
  | {
      kind: "followup";
      sessionKey?: string;
      previousMessageId?: string;
    }
  | {
      kind: "broadcast";
      reason?: string;
    }
  | {
      kind: "system";
      reason:
        | "approval"
        | "task"
        | "hook"
        | "cron"
        | "subagent"
        | "message_tool"
        | "cli"
        | "control_ui"
        | "automation"
        | "error";
    };

​

Origine

type MessageOrigin =
  | {
      source: "openclaw";
      schemaVersion: 1;
      kind: "gateway_failure";
      code: "agent_failed_before_reply" | "missing_api_key" | "model_login_expired";
      echoPolicy: "drop_bot_room_echo";
    }
  | {
      source: "user" | "external_bot" | "platform" | "unknown";
    };

​

Ricevuta

type MessageReceipt = {
  primaryPlatformMessageId?: string;
  platformMessageIds: string[];
  parts: MessageReceiptPart[];
  threadId?: string;
  replyToId?: string;
  editToken?: string;
  deleteToken?: string;
  url?: string;
  sentAt: number;
  raw?: unknown;
};

type MessageReceiptPart = {
  platformMessageId: string;
  kind: "text" | "media" | "voice" | "card" | "preview" | "unknown";
  index: number;
  threadId?: string;
  replyToId?: string;
  editToken?: string;
  deleteToken?: string;
  url?: string;
  raw?: unknown;
};

​

Contesto di ricezione

type MessageReceiveContext = {
  id: string;
  channel: string;
  accountId?: string;
  input: ChannelMessage;
  ack: ReceiveAckController;
  route: MessageRouteController;
  session: MessageSessionController;
  log: MessageLifecycleLogger;

  dedupe(): Promise<ReceiveDedupeResult>;
  resolve(): Promise<ResolvedInboundMessage>;
  record(resolved: ResolvedInboundMessage): Promise<RecordResult>;
  dispatch(recorded: RecordResult): Promise<DispatchResult>;
  commit(result: DispatchResult): Promise<void>;
  fail(error: unknown): Promise<void>;
};

platform event
  -> begin receive context
  -> normalize
  -> classify
  -> dedupe and self-echo gate
  -> route and authorize
  -> record inbound session metadata
  -> dispatch agent run
  -> durable outbound sends happen through send context
  -> commit receive
  -> ack platform when policy allows

• Ack di trasporto: comunica al Webhook o al socket della piattaforma che OpenClaw ha accettato l’envelope dell’evento. Alcune piattaforme lo richiedono prima del dispatch.
• Ack dell’offset di polling: avanza un cursore così che lo stesso evento non venga recuperato di nuovo. Non deve avanzare oltre lavoro che non può essere recuperato.
• Ack del record in ingresso: conferma che OpenClaw ha persistito abbastanza metadati in ingresso da deduplicare e instradare una riconsegna.
• Ricevuta visibile all’utente: comportamento opzionale di lettura/stato/digitazione; mai un confine di durabilità.

function shouldDropOpenClawEcho(params: {
  origin?: MessageOrigin;
  isBotAuthor: boolean;
  isRoomish: boolean;
}): boolean {
  return (
    params.isBotAuthor &&
    params.isRoomish &&
    params.origin?.source === "openclaw" &&
    params.origin.kind === "gateway_failure" &&
    params.origin.echoPolicy === "drop_bot_room_echo"
  );
}

type ReceiveAckPolicy =
  | { kind: "immediate"; reason: "webhook-timeout" | "platform-contract" }
  | { kind: "after-record" }
  | { kind: "after-durable-send" }
  | { kind: "manual" };

​

Contesto di invio

type MessageSendContext = {
  id: string;
  channel: string;
  accountId?: string;
  message: ChannelMessage;
  intent: DurableSendIntent;
  attempt: number;
  signal: AbortSignal;
  previousReceipt?: MessageReceipt;
  preview?: LiveMessageState;
  log: MessageLifecycleLogger;

  render(): Promise<RenderedMessageBatch>;
  previewUpdate(rendered: RenderedMessageBatch): Promise<LiveMessageState>;
  send(rendered: RenderedMessageBatch): Promise<MessageReceipt>;
  edit(receipt: MessageReceipt, rendered: RenderedMessageBatch): Promise<MessageReceipt>;
  delete(receipt: MessageReceipt): Promise<void>;
  commit(receipt: MessageReceipt): Promise<void>;
  fail(error: unknown): Promise<void>;
};

await core.messages.withSendContext(message, async (ctx) => {
  const rendered = await ctx.render();

  if (ctx.preview?.canFinalizeInPlace) {
    return await ctx.edit(ctx.preview.receipt, rendered);
  }

  return await ctx.send(rendered);
});

begin durable intent
  -> render
  -> optional preview/edit/stream work
  -> mark sending
  -> final platform send or final edit
  -> mark committing with raw receipt
  -> commit receipt
  -> ack durable intent
  -> fail durable intent on classified failure

type MessageDurabilityPolicy = "required" | "best_effort" | "disabled";

type RenderedMessageBatch = {
  units: RenderedMessageUnit[];
  atomicity: "all_or_retry_remaining" | "best_effort_parts";
  idempotencyKey: string;
};

type RenderedMessageUnit = {
  index: number;
  kind: "text" | "media" | "voice" | "card" | "preview" | "unknown";
  payload: unknown;
  required: boolean;
};

​

Contesto live

type MessageLiveAdapter = {
  begin?(ctx: MessageSendContext): Promise<LiveMessageState>;
  update?(
    ctx: MessageSendContext,
    state: LiveMessageState,
    update: LiveMessageUpdate,
  ): Promise<LiveMessageState>;
  finalize?(
    ctx: MessageSendContext,
    state: LiveMessageState,
    final: RenderedMessageBatch,
  ): Promise<MessageReceipt>;
  cancel?(
    ctx: MessageSendContext,
    state: LiveMessageState,
    reason: LiveCancelReason,
  ): Promise<void>;
};

type LiveMessageState = {
  mode: "partial" | "block" | "progress" | "native";
  receipt?: MessageReceipt;
  visibleSince?: number;
  canFinalizeInPlace: boolean;
  lastRenderedHash?: string;
  staleAfterMs?: number;
};

• Invio Telegram più anteprima modificabile, con finale nuovo dopo l’invecchiamento dell’anteprima obsoleta.
• Invio Discord più anteprima modificabile, annullamento su media/errore/risposta esplicita.
• Stream nativo Slack o anteprima bozza in base alla forma del thread.
• Finalizzazione del post bozza Mattermost.
• Finalizzazione dell’evento bozza Matrix o redazione in caso di mancata corrispondenza.
• Stream di avanzamento nativo Teams.
• Stream QQ Bot o fallback accumulato.

​

Superficie dell’adapter

import { defineChannelMessageAdapter } from "openclaw/plugin-sdk/channel-message";

type ChannelMessageAdapter = {
  receive?: MessageReceiveAdapter;
  send: MessageSendAdapter;
  live?: MessageLiveAdapter;
  origin?: MessageOriginAdapter;
  render?: MessageRenderAdapter;
  capabilities: MessageCapabilities;
};

type MessageSendAdapter = {
  send(ctx: MessageSendContext, rendered: RenderedMessageBatch): Promise<MessageReceipt>;
  edit?(
    ctx: MessageSendContext,
    receipt: MessageReceipt,
    rendered: RenderedMessageBatch,
  ): Promise<MessageReceipt>;
  delete?(ctx: MessageSendContext, receipt: MessageReceipt): Promise<void>;
  classifyError?(ctx: MessageSendContext, error: unknown): DeliveryFailureKind;
  reconcileUnknownSend?(ctx: MessageSendContext): Promise<MessageReceipt | null>;
  afterSendSuccess?(ctx: MessageSendContext, receipt: MessageReceipt): Promise<void>;
  afterCommit?(ctx: MessageSendContext, receipt: MessageReceipt): Promise<void>;
};

type MessageReceiveAdapter<TRaw = unknown> = {
  normalize(raw: TRaw, ctx: MessageNormalizeContext): Promise<ChannelMessage>;
  classify?(message: ChannelMessage): Promise<MessageEventClass>;
  preflight?(message: ChannelMessage, event: MessageEventClass): Promise<MessagePreflightResult>;
  ackPolicy?(message: ChannelMessage, event: MessageEventClass): ReceiveAckPolicy;
};

type MessageOriginAdapter<TRaw = unknown, TNative = unknown> = {
  encode?(origin: MessageOrigin): TNative | undefined;
  decode?(raw: TRaw): MessageOrigin | undefined;
};

type MessageCapabilities = {
  text: { maxLength?: number; chunking?: boolean };
  attachments?: {
    upload: boolean;
    remoteUrl: boolean;
    voice?: boolean;
  };
  threads?: {
    reply: boolean;
    topic?: boolean;
    nativeThread?: boolean;
  };
  live?: {
    edit: boolean;
    delete: boolean;
    nativeStream?: boolean;
    progress?: boolean;
  };
  delivery?: {
    idempotencyKey?: boolean;
    retryAfter?: boolean;
    receiptRequired?: boolean;
  };
};

​

Riduzione dell’SDK pubblico

• reply-runtime
• reply-dispatch-runtime
• reply-reference
• reply-chunking
• reply-payload
• inbound-reply-dispatch
• channel-reply-pipeline
• la maggior parte degli usi pubblici di outbound-runtime
• helper ad hoc per il ciclo di vita dello stream bozza

​

Relazione con il turn del canale

channel.turn.run
  -> messages.receive context
  -> session dispatch
  -> messages.send context for visible output

channel-owned dispatcher
  -> messages.receive record/finalize bridge
  -> messages.live for preview/progress
  -> messages.send for final delivery

​

Guardrail di compatibilità

• channel.turn.run e dispatchAssembledChannelTurn usano il callback di consegna del canale a meno che quel canale non fornisca esplicitamente un oggetto policy/opzioni durevoli verificato.
• channel.turn.runPrepared resta di proprietà del canale finché il dispatcher preparato non chiama esplicitamente il contesto di invio.
• Gli helper pubblici di compatibilità come recordInboundSessionAndDispatchReply, dispatchInboundReplyWithBase e gli helper direct-DM non iniettano mai una consegna generica durevole prima del callback deliver o reply fornito dal chiamante.

• La consegna finale durevole restituisce uno stato discriminato. handled_visible e handled_no_send sono terminali; unsupported e not_applicable possono ricadere sulla consegna gestita dal canale; failed propaga l’errore di invio.
• La consegna finale durevole generica è vincolata dalle capacità dell’adattatore, come consegna silenziosa, preservazione del destinatario della risposta, preservazione della citazione nativa e hook di invio dei messaggi. In caso di parità mancante, scegliere la consegna gestita dal canale, non un invio generico che modifica il comportamento visibile all’utente.
• Gli invii durevoli supportati da coda espongono un riferimento di intento di consegna. I campi di sessione pendingFinalDelivery* esistenti possono trasportare l’id dell’intento durante la transizione; lo stato finale è uno store MessageSendIntent invece di testo di risposta congelato più campi di contesto ad hoc.

• L’adattatore di invio generico esegue lo stesso comportamento di rendering e trasporto del vecchio percorso diretto.
• Gli effetti collaterali locali successivi all’invio sono preservati tramite il contesto di invio.
• L’adattatore restituisce ricevute o risultati di consegna con tutti gli id dei messaggi della piattaforma.
• I percorsi del dispatcher preparato chiamano il nuovo contesto di invio oppure restano documentati come esterni alla garanzia durevole.
• La consegna di fallback gestisce ogni payload proiettato, non solo il primo.
• La consegna di fallback durevole registra l’intero array di payload proiettati come un unico intento riproducibile o piano batch.

• La consegna del monitor iMessage registra i messaggi inviati in una cache echo dopo un invio riuscito. Gli invii finali durevoli devono ancora popolare quella cache, altrimenti OpenClaw può reimportare le proprie risposte finali come messaggi utente in ingresso.
• Tlon aggiunge una firma opzionale del modello e registra i thread partecipati dopo le risposte di gruppo. La consegna durevole generica non deve aggirare questi effetti; spostarli negli adattatori di rendering/invio/finalizzazione di Tlon oppure mantenere Tlon sul percorso gestito dal canale.
• Discord e altri dispatcher preparati possiedono già il comportamento di consegna diretta e anteprima. Non sono coperti da una garanzia durevole del turno assemblato finché i loro dispatcher preparati non instradano esplicitamente i finali tramite il contesto di invio.
• La consegna di fallback silenziosa di Telegram deve consegnare l’intero array di payload proiettati. Una scorciatoia a payload singolo può eliminare payload di fallback aggiuntivi dopo la proiezione.
• LINE, Zalo, Nostr e altri percorsi assemblati/helper esistenti possono avere gestione dei token di risposta, proxying dei media, cache dei messaggi inviati, pulizia di caricamento/stato o destinazioni solo callback. Restano sulla consegna gestita dal canale finché tali semantiche non sono rappresentate dall’adattatore di invio e verificate dai test.
• Gli helper Direct-DM possono avere un callback di risposta che è l’unica destinazione di trasporto corretta. L’uscita generica non deve dedurre da OriginatingTo o To e saltare quel callback.
• L’output di errore del Gateway OpenClaw deve restare visibile agli umani, ma gli echo della stanza creati da bot e taggati devono essere scartati prima dell’autorizzazione allowBots. I canali non devono implementarlo con filtri su prefissi di testo visibile se non come breve misura di emergenza; il contratto durevole è costituito da metadati di origine strutturati.

​

Archiviazione interna

type DurableSendIntent = {
  id: string;
  idempotencyKey: string;
  channel: string;
  accountId?: string;
  message: ChannelMessage;
  batch?: RenderedMessageBatch;
  liveState?: LiveMessageState;
  status:
    | "pending"
    | "sending"
    | "committing"
    | "unknown_after_send"
    | "sent"
    | "failed"
    | "cancelled";
  attempt: number;
  nextAttemptAt?: number;
  receipt?: MessageReceipt;
  partialReceipt?: MessageReceipt;
  failure?: DeliveryFailure;
  createdAt: number;
  updatedAt: number;
};

load pending or sending intents
  -> acquire idempotency lock
  -> skip if receipt already committed
  -> reconstruct send context
  -> render if needed
  -> reconcile unknown_after_send if needed
  -> call adapter send/edit/finalize
  -> commit receipt, mark unknown_after_send, or schedule retry

​

Classi di errore

type DeliveryFailureKind =
  | "transient"
  | "rate_limit"
  | "auth"
  | "permission"
  | "not_found"
  | "invalid_payload"
  | "conflict"
  | "cancelled"
  | "unknown";

• Ritentare transient e rate_limit.
• Non ritentare invalid_payload a meno che esista un fallback di rendering.
• Non ritentare auth o permission finché la configurazione non cambia.
• Per not_found, consentire alla finalizzazione live di ricadere dalla modifica a un nuovo invio quando il canale dichiara che è sicuro.
• Per conflict, usare le regole di ricevuta/idempotenza per decidere se il messaggio esiste già.
• Qualsiasi errore dopo che l’adattatore potrebbe aver completato I/O della piattaforma ma prima del commit della ricevuta diventa unknown_after_send a meno che l’adattatore non possa provare che l’operazione della piattaforma non è avvenuta.

​

Mappatura dei canali

​

Piano di migrazione

​

Fase 1: Dominio messaggi interno

• Aggiungi i tipi src/channels/message/* per messaggi, target, relazioni, origini, ricevute, capacità, intenti durevoli, contesto di ricezione, contesto di invio, contesto live e classi di errore.
• Aggiungi origin?: MessageOrigin al tipo di payload del bridge di migrazione usato dalla consegna delle risposte corrente, poi sposta quel campo in ChannelMessage e nei tipi di messaggio renderizzati mentre il refactor sostituisce i payload di risposta.
• Mantienilo interno finché adattatori e test non dimostrano la forma.
• Aggiungi unit test puri per transizioni di stato e serializzazione.

​

Fase 2: Core di invio durevole

• Sposta la coda in uscita esistente dalla durabilità dei payload di risposta agli intenti di invio messaggio durevoli.
• Consenti a un intento di invio durevole di trasportare un array di payload proiettato o un piano batch, non solo un payload di risposta.
• Preserva il comportamento corrente di ripristino della coda tramite conversione di compatibilità.
• Fai in modo che deliverOutboundPayloads chiami messages.send.
• Rendi la durabilità dell’invio finale l’impostazione predefinita e fallisci in modo chiuso quando l’intento durevole non può essere scritto nel nuovo ciclo di vita dei messaggi, dopo che l’adattatore dichiara la sicurezza del replay. I percorsi di compatibilità channel-turn e SDK esistenti restano direct-send per impostazione predefinita durante questa fase.
• Registra le ricevute in modo coerente.
• Restituisci ricevute e risultati di consegna al chiamante dispatcher originale invece di trattare l’invio durevole come un effetto collaterale terminale.
• Persiste l’origine del messaggio attraverso gli intenti di invio durevoli in modo che ripristino, replay e invii a blocchi preservino la provenienza operativa di OpenClaw.

​

Fase 3: Bridge del turno canale

• Reimplementa channel.turn.run e dispatchAssembledChannelTurn sopra messages.receive e messages.send.
• Mantieni stabili i tipi di fatto correnti.
• Mantieni il comportamento legacy per impostazione predefinita. Un canale assembled-turn diventa durevole solo quando il suo adattatore effettua esplicitamente l’opt-in con una policy di durabilità sicura per il replay.
• Mantieni durable: false come via di fuga di compatibilità per i percorsi che finalizzano modifiche native e non possono ancora eseguire replay in modo sicuro, ma non affidarti ai marcatori false per proteggere i canali non migrati.
• Imposta per impostazione predefinita la durabilità assembled-turn solo nel nuovo ciclo di vita dei messaggi, dopo che la mappatura del canale dimostra che il percorso di invio generico preserva la vecchia semantica di consegna del canale.

​

Fase 4: Bridge del dispatcher preparato

• Sostituisci deliverDurableInboundReplyPayload con un bridge del contesto di invio.
• Mantieni il vecchio helper come wrapper.
• Porta prima Telegram, WhatsApp, Slack, Signal, iMessage e Discord perché hanno già lavoro durable-final o percorsi di invio più semplici.
• Tratta ogni dispatcher preparato come non coperto finché non aderisce esplicitamente al contesto di invio. La documentazione e le voci del changelog devono dire “turni di canale assemblati” o nominare i percorsi dei canali migrati, invece di rivendicare tutte le risposte finali automatiche.
• Mantieni recordInboundSessionAndDispatchReply, gli helper direct-DM e helper di compatibilità pubblici simili preservandone il comportamento. Potranno esporre in seguito un’adesione esplicita al contesto di invio, ma non devono tentare automaticamente una consegna durevole generica prima della callback di consegna posseduta dal chiamante.

​

Fase 5: ciclo di vita live unificato

• Costruisci messages.live con due adattatori di prova:
  • Telegram per invio più modifica più invio finale obsoleto.
  • Matrix per finalizzazione della bozza più fallback di redazione.
• Poi migra Discord, Slack, Mattermost, Teams, QQ Bot e Feishu.
• Elimina il codice duplicato di finalizzazione dell’anteprima solo dopo che ogni canale ha test di parità.

​

Fase 6: SDK pubblico

• Aggiungi openclaw/plugin-sdk/channel-message.
• Documentalo come l’API preferita per i Plugin di canale.
• Aggiorna gli export dei pacchetti, l’inventario degli entrypoint, le baseline API generate e la documentazione dell’SDK dei Plugin.
• Includi MessageOrigin, gli hook di codifica/decodifica dell’origine e il predicato condiviso shouldDropOpenClawEcho nella superficie SDK channel-message.
• Mantieni wrapper di compatibilità per i vecchi sottopercorsi.
• Contrassegna nella documentazione gli helper SDK con nomi di risposta come deprecati dopo la migrazione dei Plugin in bundle.

​

Fase 7: tutti i mittenti

• notifiche Cron e Heartbeat
• completamenti di attività
• risultati degli hook
• prompt di approvazione e risultati di approvazione
• invii tramite strumento messaggi
• annunci di completamento dei subagent
• invii espliciti da CLI o Control UI
• percorsi di automazione/broadcast

​

Fase 8: deprecare Turn

• Mantieni channel.turn come wrapper per almeno una finestra di compatibilità.
• Pubblica note di migrazione.
• Esegui i test di compatibilità dell’SDK dei Plugin contro i vecchi import.
• Rimuovi o nascondi i vecchi helper interni solo dopo che nessun Plugin in bundle ne ha più bisogno e i contratti di terze parti hanno un sostituto stabile.

​

Piano di test

• Serializzazione e recupero degli intenti di invio durevoli.
• Riutilizzo della chiave di idempotenza e soppressione dei duplicati.
• Commit della ricevuta e salto del replay.
• Recupero unknown_after_send che riconcilia prima del replay quando un adattatore supporta la riconciliazione.
• Policy di classificazione degli errori.
• Sequenziamento della policy di ack di ricezione.
• Mappatura delle relazioni per invii di risposta, followup, sistema e broadcast.
• Factory di origine per errori del Gateway e predicato shouldDropOpenClawEcho.
• Preservazione dell’origine attraverso normalizzazione del payload, chunking, serializzazione della coda durevole e recupero.

• L’adattatore semplice channel.turn.run registra e invia ancora.
• La consegna legacy di turni assemblati non diventa durevole a meno che il canale non aderisca esplicitamente.
• Il bridge channel.turn.runPrepared registra e finalizza ancora.
• Gli helper pubblici di compatibilità chiamano per impostazione predefinita le callback di consegna possedute dal chiamante e non eseguono un invio generico prima di quelle callback.
• La consegna fallback durevole riesegue l’intero array di payload proiettati dopo il riavvio e non può lasciare i payload successivi non registrati dopo un crash anticipato.
• La consegna durevole di turni assemblati restituisce gli ID dei messaggi della piattaforma al dispatcher bufferizzato.
• Gli hook di consegna personalizzati restituiscono ancora gli ID dei messaggi della piattaforma quando la consegna durevole è disabilitata o non disponibile.
• La risposta finale sopravvive al riavvio tra completamento dell’assistente e invio alla piattaforma.
• La bozza di anteprima viene finalizzata sul posto quando consentito.
• La bozza di anteprima viene annullata o redatta quando una mancata corrispondenza di media/errore/target di risposta richiede la consegna normale.
• Lo streaming a blocchi e lo streaming di anteprima non consegnano entrambi lo stesso testo.
• I media trasmessi in streaming in anticipo non vengono duplicati nella consegna finale.

• Risposta a topic Telegram con ack di polling ritardato fino al watermark completato sicuro del contesto di ricezione.
• Recupero del polling Telegram per aggiornamenti accettati ma non consegnati coperto dal modello persistito di offset safe-completed.
• L’anteprima obsoleta Telegram invia un finale fresco e pulisce l’anteprima.
• Il fallback silenzioso Telegram invia ogni payload fallback proiettato.
• La durabilità del fallback silenzioso Telegram registra atomicamente l’intero array fallback proiettato, non un singolo intento durevole a payload singolo per iterazione del ciclo.
• Annullamento dell’anteprima Discord su media/errore/risposta esplicita.
• I finali dei dispatcher preparati Discord passano attraverso il contesto di invio prima che la documentazione o il changelog rivendichino la durabilità delle risposte finali Discord.
• Gli invii finali durevoli iMessage popolano la cache echo dei messaggi inviati del monitor.
• I percorsi di consegna legacy LINE, Zalo e Nostr non vengono bypassati dall’invio durevole generico finché non esistono i relativi test di parità dell’adattatore.
• La consegna tramite callback Direct-DM/Nostr resta autorevole a meno che non venga migrata esplicitamente a un target messaggio completo e a un adattatore di invio sicuro per il replay.
• I messaggi Slack tagged di errore del Gateway OpenClaw restano visibili in uscita, gli echo bot-room tagged vengono scartati prima di allowBots e i messaggi bot senza tag con lo stesso testo visibile seguono ancora la normale autorizzazione dei bot.
• Fallback dello stream nativo Slack ad anteprima bozza nei DM di primo livello.
• Finalizzazione dell’anteprima Matrix e fallback di redazione.
• Gli echo tagged OpenClaw di errore del Gateway nelle stanze Matrix da account bot configurati vengono scartati prima della gestione di allowBots.
• Gli audit a cascata degli errori del Gateway in stanze condivise Discord e Google Chat coprono le modalità allowBots prima di rivendicare protezione generica lì.
• Finalizzazione della bozza Mattermost e fallback con invio fresco.
• Finalizzazione del progresso nativo Teams.
• Soppressione del finale duplicato Feishu.
• Fallback per timeout dell’accumulatore QQ Bot.
• Gli invii finali durevoli Tlon preservano il rendering della model-signature e il tracciamento dei thread partecipati.
• Invii finali durevoli semplici per WhatsApp, Signal, iMessage, Google Chat, LINE, IRC, Nostr, Nextcloud Talk, Synology Chat, Tlon, Twitch, Zalo e Zalo Personal.

• File Vitest mirati durante lo sviluppo.
• pnpm check:changed in Testbox per l’intera superficie modificata.
• pnpm check più ampio in Testbox prima di atterrare il refactor completo o dopo modifiche all’SDK pubblico/export.
• Smoke live o qa-channel per almeno un canale capace di modifica e un canale semplice solo invio prima di rimuovere i wrapper di compatibilità.

​

Domande aperte

• Se Telegram debba alla fine sostituire la sorgente runner grammY con una sorgente di polling completamente durevole che possa controllare la riconsegna a livello di piattaforma, non solo il watermark di riavvio persistito di OpenClaw.
• Se lo stato durevole dell’anteprima live debba essere archiviato nello stesso record di coda dell’intento di invio finale o in uno store live-state affiancato.
• Per quanto tempo i wrapper di compatibilità restano documentati dopo il rilascio di plugin-sdk/channel-message.
• Se i Plugin di terze parti debbano implementare direttamente adattatori di ricezione o fornire solo hook normalize/send/live tramite defineChannelMessageAdapter.
• Quali campi della ricevuta siano sicuri da esporre nell’SDK pubblico rispetto allo stato runtime interno.
• Se effetti collaterali come cache self-echo e marker di thread partecipati debbano essere modellati come hook del contesto di invio, passaggi di finalizzazione posseduti dall’adattatore o subscriber delle ricevute.
• Quali canali abbiano metadati di origine nativi, quali richiedano registri outbound persistiti e quali non possano offrire una soppressione echo cross-bot affidabile.

​

Criteri di accettazione

• Ogni canale messaggi in bundle invia l’output finale visibile tramite messages.send.
• Ogni canale messaggi inbound entra tramite messages.receive o un wrapper di compatibilità documentato.
• Ogni canale di anteprima/modifica/stream usa messages.live per lo stato bozza e la finalizzazione.
• channel.turn è solo un wrapper.
• Gli helper SDK con nomi di risposta sono export di compatibilità, non il percorso consigliato.
• Il recupero durevole può rieseguire gli invii finali pendenti dopo il riavvio senza perdere la risposta finale o duplicare invii già sottoposti a commit; gli invii il cui esito sulla piattaforma è sconosciuto vengono riconciliati prima del replay o documentati come at-least-once per quell’adattatore.
• Gli invii finali durevoli falliscono chiusi quando l’intento durevole non può essere scritto, a meno che un chiamante non abbia selezionato esplicitamente una modalità non durevole documentata.
• Gli helper di compatibilità legacy channel-turn e SDK usano per impostazione predefinita la consegna diretta posseduta dal canale; l’invio durevole generico è solo ad adesione esplicita.
• Le ricevute preservano tutti gli ID dei messaggi della piattaforma per le consegne multi-parte e un ID primario per comodità di threading/modifica.
• I wrapper durevoli preservano gli effetti collaterali locali del canale prima di sostituire le callback di consegna diretta.
• I dispatcher preparati non vengono conteggiati come durevoli finché il loro percorso di consegna finale non usa esplicitamente il contesto di invio.
• La consegna fallback gestisce ogni payload proiettato.
• La consegna fallback durevole registra ogni payload proiettato in un unico intento rieseguibile o piano batch.
• L’output di errore del Gateway originato da OpenClaw è visibile agli esseri umani, ma gli echo di stanza authored-by-bot tagged vengono scartati prima dell’autorizzazione dei bot sui canali che dichiarano il supporto per il contratto di origine.
• La documentazione spiega invio, ricezione, live, stato, ricevute, relazioni, policy di errore, migrazione e copertura dei test.

​

Correlati

• Messaggi
• Streaming e chunking
• Bozze di progresso
• Policy di retry
• Kernel turn di canale