API di ingresso del canale

L'ingresso dei canali è il confine sperimentale di controllo degli accessi per gli eventi in entrata dei canali. I Plugin gestiscono i dati specifici della piattaforma e gli effetti collaterali; il core gestisce la policy generica: elenchi di consentiti per messaggi diretti e gruppi, voci per messaggi diretti nell'archivio di associazione, controlli delle route, controlli dei comandi, autorizzazione degli eventi, attivazione tramite menzione, diagnostica oscurata e ammissione.

Usa openclaw/plugin-sdk/channel-ingress-runtime per i nuovi percorsi di ricezione. Il sottopercorso precedente openclaw/plugin-sdk/channel-ingress rimane esportato come facciata di compatibilità deprecata per i plugin di terze parti.

Risolutore di runtime

   defineStableChannelIngressIdentity,  resolveChannelMessageIngress,} from "openclaw/plugin-sdk/channel-ingress-runtime"; const identity = defineStableChannelIngressIdentity({  key: "platform-user-id",  normalize: normalizePlatformUserId,  sensitivity: "pii",}); const result = await resolveChannelMessageIngress({  channelId: "my-channel",  accountId,  identity,  subject: { stableId: platformUserId },  conversation: { kind: isGroup ? "group" : "direct", id: conversationId },  event: { kind: "message", authMode: "inbound", mayPair: !isGroup },  policy: {    dmPolicy: config.dmPolicy,    groupPolicy: config.groupPolicy,    groupAllowFromFallbackToAllowFrom: true,  },  allowFrom: config.allowFrom,  groupAllowFrom: config.groupAllowFrom,  accessGroups: cfg.accessGroups,  route,  readStoreAllowFrom,  command: hasControlCommand ? { allowTextCommands: true, hasControlCommand } : undefined,});

Non precalcolare gli elenchi di consentiti effettivi, i proprietari dei comandi o i gruppi di comandi. Il risolutore li ricava dagli elenchi di consentiti non elaborati, dai callback dell'archivio, dai descrittori delle route, dai gruppi di accesso, dalla policy e dal tipo di conversazione.

Risultato

I plugin inclusi devono utilizzare direttamente le proiezioni moderne:

L'autorizzazione degli eventi rimane disponibile nel grafo ordinato ingress.graph e nel codice motivo determinante ingress.reasonCode; non viene emessa alcuna proiezione separata dell'evento.

Gli helper SDK deprecati di terze parti possono ricostruire internamente le strutture precedenti. I nuovi percorsi di ricezione inclusi non devono riconvertire i risultati moderni in DTO locali.

Gruppi di accesso

Le voci accessGroup:<name> rimangono oscurate. Il core risolve autonomamente i gruppi statici message.senders e chiama resolveAccessGroupMembership solo per i gruppi dinamici che richiedono una ricerca sulla piattaforma. I gruppi mancanti, non supportati o la cui risoluzione non riesce negano l'accesso per impostazione predefinita.

Modalità degli eventi

Usa mayPair: false per reazioni, pulsanti, callback e comandi nativi.

Route e attivazione

Usa i descrittori di route per le policy di stanza, argomento, gilda, thread o route annidate:

route: {  id: "room",  allowed: roomAllowed,  enabled: roomEnabled,  senderPolicy: "replace",  senderAllowFrom: roomAllowFrom,  blockReason: "room_sender_not_allowlisted",}

Usa channelIngressRoutes(...) quando un plugin dispone di diversi descrittori di route facoltativi; filtra i rami disabilitati mantenendo generici i dati delle route e ordinandoli in base alla precedence di ciascun descrittore.

Il controllo delle menzioni è un controllo di attivazione. Una menzione mancante restituisce admission: "skip", affinché il kernel del turno non elabori un turno di sola osservazione. La maggior parte dei canali deve lasciare l'attivazione dopo i controlli del mittente e dei comandi. Le superfici di chat pubblica che devono silenziare il traffico senza menzioni prima del rumore prodotto dall'elenco di mittenti consentiti possono scegliere activation.order: "before-sender" quando l'aggiramento tramite comandi testuali è disabilitato. I canali con attivazione implicita, come le risposte nei thread dei bot, possono passare activation.allowedImplicitMentionKinds; la proiezione activationAccess.shouldBypassMention indica quindi quando un comando o un'attivazione implicita ha aggirato una menzione esplicita.

Oscuramento

I valori non elaborati dei mittenti e le voci non elaborate degli elenchi di consentiti sono esclusivamente input del risolutore. Non devono comparire nello stato risolto, nelle decisioni, nella diagnostica, nelle istantanee o nei dati di compatibilità. Usa ID opachi per soggetti, voci, route e diagnostica.

Verifica

pnpm test src/channels/message-access/message-access.test.ts src/plugin-sdk/channel-ingress-runtime.test.tspnpm plugin-sdk:api:check