openclaw/plugin-sdk/channel-outbound. Use
openclaw/plugin-sdk/channel-inbound para la orquestación de recepción, contexto y despacho.
El núcleo se encarga de las colas, la durabilidad, el monitor y drenaje de entrada
duradero (createChannelIngressMonitor, createChannelIngressDrain y
openChannelIngressDrain), la política genérica de reintentos, el ciclo de vida
de adopción del turno (turnAdoptionLifecycle / bindIngressLifecycleToReplyOptions), los hooks,
los recibos y la herramienta compartida message. El plugin se encarga de
las llamadas nativas de envío, edición y eliminación, la normalización del destino,
los hilos de la plataforma, las citas seleccionadas, los indicadores de notificación,
el estado de la cuenta, la inspección de entrada y la codificación de la carga útil,
las claves de carril, los predicados que impiden reintentos, la autorización opcional
de sustitución y los efectos secundarios específicos de la plataforma.
Monitores de entrada duraderos
UsecreateChannelIngressMonitor(...) cuando un canal deba conservar los eventos
de transporte aceptados antes de despacharlos. Combina una cola y un drenaje de entrada
del canal con el ciclo de vida compartido de admisión, sondeo, depuración, entrega y
cierre. Use el nivel inferior createChannelIngressDrain(...) solo cuando el transporte
se encargue de un contrato de admisión o bombeo sustancialmente diferente.
Las opciones obligatorias son:
El monitor serializa las admisiones para que el aplazamiento de anexión no pueda
invertir un carril. Los retrasos acotados predeterminados para anexar son
0, 100 y 300 ms; si se agotan,
se rechaza el callback del transporte en lugar de despachar un evento que no se hizo
duradero. En el momento de la reclamación, decodifica la carga útil versionada, vuelve
a ejecutar inspect y rechaza cualquier discrepancia del identificador o del
carril antes de la entrega.
deliver recibe onAdopted, onDeferred, onAdoptionFinalizing,
onAbandoned y abortSignal. Devolver sin una transferencia explícita marca
como adoptado un evento terminal sin despacho. admission siempre es
exclusive. Una transferencia diferida mantiene retenida la reclamación, mientras
que el cierre o la cancelación permiten volver a intentar el trabajo no adoptado. El
monitor realiza el seguimiento de la entrega independientemente de la resolución de la
reclamación porque la adopción puede crear una lápida para una fila antes de que se
resuelva la promesa de entrega del canal.
La configuración opcional incluye retrasos personalizados de anexión, un bloque de
opciones drain para políticas avanzadas de ordenación, concurrencia y
reintentos del drenaje, un abortSignal externo, un reloj, informes de errores
del bombeo, una fábrica de errores de detención y una política de admisión.
El monitor devuelto expone admit, start, pause,
stop, waitForIdle, isRunning y isStopped.
stop primero resuelve las admisiones aceptadas; después cancela y
descarta el drenaje, espera al bombeo y a las entregas activas, y vuelve a descartarlo
para cerrar la condición de carrera de la creación diferida.
Mantenga en el plugin la ocultación específica del transporte, la validación del
sobre sin procesar, la clasificación de los errores que no deben reintentarse y la
forma de la carga útil persistente. Los transportes Webhook solo deben confirmar
después de que se resuelva admit; los transportes sin repetición deben
señalar el agotamiento de la anexión duradera en lugar de despachar silenciosamente.
Adaptador
La mayoría de los plugins definen un adaptadormessage:
Supresión del eco saliente
Cuando una plataforma pueda volver a entregar como entrante el propio mensaje saliente del plugin, llame arecordOutboundMessageIdentity(...) con el canal, la cuenta, la
conversación y una identidad estable del mensaje o del origen de la plataforma. La
ruta compartida de turnos entrantes descarta las identidades coincidentes durante
una ventana acotada de 30 segundos antes de registrar la sesión o despachar al
agente; una identidad de origen puede reservarse antes del envío o actualizarse
cuando se elimina una ruta de canal para cerrar las condiciones de carrera de
entrega. isRecentOutboundMessageIdentity(...) expone la misma consulta para los diagnósticos y las
pruebas del canal. No mantenga una caché TTL local del canal paralela para la misma
identidad estable.
Saneamiento de texto sin formato
UsesanitizeForPlainText(...) cuando un adaptador saliente necesite convertir las
etiquetas de formato HTML compatibles en marcado de texto ligero. De forma
predeterminada, se conservan los marcadores existentes de negrita y tachado del
estilo de chat. Pase { style: "markdown" } solo cuando el canal vuelva a analizar el
resultado como Markdown:
**bold** y ~~strikethrough~~; la cursiva y el
código en línea conservan _italic_ y los marcadores de acento grave en
ambos estilos. Seleccione el estilo en el límite del canal en lugar de reescribir
el texto de los marcadores después del saneamiento.
Evidencia de entrega
UnMessageReceipt registra el resultado devuelto por un adaptador de canal. Los
identificadores concretos de mensajes de la plataforma demuestran que la ruta de
envío de la plataforma aceptó el mensaje; no demuestran que el dispositivo de un
destinatario lo mostrara o leyera. Los recibos sin identificadores de mensajes de
la plataforma solo son metadatos locales del recibo. Los canales con confirmaciones
de lectura o estados de entrega al dispositivo deben realizar el seguimiento de
esos datos mediante una ruta independiente y específica del canal.
Si un adaptador de canal puede demostrar que reintentar un fallo no puede duplicar
un envío visible para el destinatario y que no comenzó ninguna llamada capaz de
finalizarlo, lance new PlatformMessageNotDispatchedError("...", { cause: error }) desde
openclaw/plugin-sdk/error-runtime. De este modo, el núcleo puede borrar la evidencia obsoleta del
intento de envío y reintentar de forma segura la intención en cola. Solo el
adaptador que controla el límite del despacho final puede realizar esta afirmación.
Nunca use el marcador después de que comience una llamada de finalización/envío ni
cuando esta devuelva un resultado ambiguo; un marcado incorrecto puede duplicar
mensajes.
Adaptadores salientes existentes
Si el canal ya tiene un adaptadoroutbound compatible, derive el adaptador
de mensajes en lugar de duplicar el código de envío:
Envíos duraderos
Los auxiliares de envío en tiempo de ejecución también se encuentran enchannel-outbound:
sendDurableMessageBatch(...)withDurableMessageSendContext(...)deliverInboundReplyWithMessageSendContext(...)- auxiliares de streaming/progreso de borradores, como
resolveChannelDraftStreamingChunking(...)
sendDurableMessageBatch(...) devuelve un resultado explícito:
Use
payloadOutcomes cuando un lote combine cargas útiles enviadas, suprimidas y
fallidas. No deduzca la cancelación de un hook a partir de un resultado vacío de
entrega directa heredada.
Admisión de entregas diferidas
Usemessage.durableFinal.admitDeferredDelivery(...) cuando una cuenta resuelta no pueda aceptar de forma segura
entregas salientes o diferidas administradas por el núcleo. El núcleo llama a este
hook de forma síncrona antes del trabajo saliente en directo, incluidas las rutas
que omiten la persistencia en cola, y de nuevo antes de reproducir una intención
recuperada. El contexto incluye cfg, channel,
to, accountId y un phase de
live o recovery.
Devuelva { status: "allowed" } para continuar. Devuelva
{ status: "permanent_rejection", reason } cuando la entrega no deba persistirse, enviarse directamente ni
reproducirse. Un rechazo en directo falla antes de la creación de la cola, los
hooks de mensajes o el trabajo de la plataforma. Un rechazo durante la recuperación
marca el registro en cola como fallido y omite la conciliación y la reproducción.
Omitir el hook significa que está permitido.
El hook es una decisión de admisión síncrona, no una ruta de envío. Lea únicamente
la configuración o el estado de ejecución ya cargados; no realice operaciones de E/S
de red, del sistema de archivos ni otras operaciones asíncronas. Las pruebas de contrato deben ejercitar ambas fases y ambas
variantes de resultado mediante ChannelMessageDurableFinalAdapter desde
openclaw/plugin-sdk/channel-outbound.
Despacho de compatibilidad
Ensamble el despacho de respuestas entrantes mediantedispatchChannelInboundReply(...)
desde channel-inbound. Mantenga la entrega de la plataforma en el adaptador de entrega; use
channel-outbound para adaptadores de mensajes, envíos duraderos, confirmaciones, vista previa
en vivo y opciones del pipeline de respuestas.