Der Adapter-Contract der Konnektoren: Kanäle und Limits

Die Kanäle, auf denen Ihre Kunden ohnehin sind

Ein AI-Workspace ist am nützlichsten dort, wo die Konversation ohnehin stattfindet. Für viele Unternehmen ist das nicht die Web-Oberfläche, die Sie ausrollen; es sind die Messaging-Kanäle, die Menschen ohne Nachzudenken öffnen - WhatsApp-Gruppen, Telegram-Chats, Discord-Server, Slack-Workspaces. Simmetric Chat behandelt diese Kanäle als Oberflächen erster Klasse derselben Knowledge Base: Ein Konnektor bindet einen Kanal an ein Workspace und an ein Dokumentenarchiv, und jede Frage, die auf diesem Kanal ankommt, wird von derselben Retrieval-Pipeline beantwortet wie der interne Chat.

Das Wort im Titel - Adapter-Contract - benennt die Designregel, die das sicher macht. Jede Plattform spricht ein eigenes Protokoll mit eigenen Credential-Semantiken; jede läuft daher hinter einem dedizierten Adapter, und alles, was die Adapter gemeinsam haben, ist ein festes Vokabular aus Feldern und Limits. Das Ergebnis liest sich wie eine Sicherheitsrichtlinie: ein Konnektor pro Kanal, ein Binding pro Konnektor, ein Korpus pro Binding.

Dieser Artikel geht das Contract aus Bedienerperspektive durch: was Sie bei der Erstellung eines Konnektors konfigurieren, welche Oberflächen sich in der v0.28-Ära geändert haben (der Edit-Zweig), wie die Limits das Workspace vor externem Verkehr schützen und was passiert, wenn das Korpus keine zitierbare Antwort hat.

Nur Enterprise-Edition: connectors_enabled steht in der Community-Lizenz auf false, die Adapter-Registry ist dort leer, und das Admin-Panel zeigt statt des Formulars den Upgrade-Hinweis. Fakten: FACT-CENSUS.md F-CONN-1.

Was Sie bei der Erstellung konfigurieren

Das Erstellformular liegt unter Settings → Conversations → Connectors und fragt zwei Feldklassen ab. Die Binding-Felder benennen die Integration: ein name, der die Instanz identifiziert, die platform (eine aus telegram, discord, slack, whatsapp), der Secret-Token des Kanals und das workspace, das der Konnektor bedient. Die Verhaltensfelder formen die Konversation: das Archiv-Binding, das den Korpus bestimmt, die Willkommensnachricht an den, der die Konversation eröffnet, die Fallback-Nachricht samt fallbackLocale für den Fall ohne zitierbare Quellen, und die beiden Limits - Rate-Limit und Tagessessions, wobei 0 unbegrenzt bedeutet.

Drei dieser Felder sind nach der Erstellung unveränderlich, und diese Unveränderlichkeit ist kein Implementierungsdetail - sie ist das Vertrauensmodell. Plattform und Secret-Token definieren, wer mit dem Korpus sprechen darf; das Workspace definiert, was erreichbar ist. Ändert sich eines davon, ändert sich die Identität der Integration, und das Contract antwortet mit einem neuen Konnektor statt mit einer Mutation. Das Schema der v0.28-Reihe trägt diese Regeln wörtlich: Willkommens- und Fallback-Nachrichten deckeln bei 4000 Zeichen, Plattform und Token sind create-only, und die PUT rührt sie nie an.

Credentials bleiben designbedingt serverseitig. Die App ruft die APIs des Kanals mit den vom Administrator hinterlegten Credentials auf; der Secret-Token wird nach der Erstellung nie wieder in der Oberfläche gespiegelt, und das Routing des Konnektors lebt in Ihrer eigenen Infrastruktur - der Kanal spricht mit Ihrem Server, Ihr Server spricht mit der eigenen Knowledge Base.

Die Adapter-Schicht

Jede Plattform läuft hinter einem eigenen Adapter, und die Registrierung jedes Adapters entspricht exakt dem, was die Plattform verlangt:

• Telegram - ein Bot-Token von @BotFather, mit Unterstützung von Polling wie Webhook (die Karte trägt die zugehörigen Modus-Schaltflächen).
• Discord - ein Bot-Token aus dem Developer Portal plus Message-Intents; der Adapter liest die Kanäle, für die der Bot autorisiert ist.
• Slack - ein Bot-Token und das Signing Secret der Slack-App; Message-Events kommen über den konfigurierten Webhook.
• WhatsApp - der Secret-Token der Business API des Anbieters; der Adapter ruft die API des Providers auf.

In der Adapter-Schicht sterben die Unterschiede zwischen den Plattformen. Webhook-Verifikation, Intent-Scope, Polling-Schleifen, Normalisierung der Nachrichtenform - alles lebt hinter dem Adapter der jeweiligen Plattform, und der Rest des Produkts sieht genau einen Formfaktor: den Konnektor-Datensatz. Die Adapter-Registry selbst ist gated: In Community ist sie dem Konstrukt nach leer, sodass eine Community-Instanz geschlossen fehlschlägt, bevor externer Verkehr das Workspace erreicht.

Bearbeiten: die mutable Oberfläche seit v0.28.1

Vor v0.28.1 bedeutete das Anpassen eines Konnektors: löschen und neu anlegen. Die Änderungen der v0.28-Reihe fügen einen Edit-Zweig hinzu: Das Overflow-Menü der Konnektor-Karte trägt einen Edit-Eintrag, der einen vorausgefüllten Dialog über exakt die mutable Oberfläche öffnet - via PUT /api/connectors/:id:

• Mutabel - der Name, das Archiv-Binding, Willkommens- und Fallback-Nachrichten, die Fallback-Sprache und beide Limits (leer = null; 0 = unbegrenzt).
• Unveränderlich - die Plattform, der Bot-Token, das Workspace.

Der isEnabled-Schalter bleibt auf der Karte (er pausiert das Routing, ohne die Konfiguration zu löschen), und die Mutation wird wie jede andere Admin-Aktion auditiert: Der Endpoint protokolliert das Event chat_connector.updated, gleichrangig mit dem DELETE-Zweig und seinem chat_connector.deleted. Der Edit-Zweig zählt für die Bedienergeschichte in einer bestimmten Hinsicht: einen Kanal an ein neu aufgebautes Archiv zu binden oder nach einem Vorfall ein Limit zu straffen, kostet nicht mehr die Identität des Konnektors.

Der Antwortweg und der Fallback

Jede Frage, die von einem Kanal kommt, durchläuft dieselbe Pipeline wie ein interner Chat: hybride Suche über das gebundene Archiv, Quellenzitierung, Synthese - dann wandert die belegte Antwort auf den ursprünglichen Kanal zurück. Das Archiv-Binding ist der stille Kern des Contract: Es ist das, was eine externe Konversation fundiert.

Wenn die Suche keine gültigen zitierbaren Elemente ergibt, antwortet das Contract mit der Fallback-Nachricht - einer konfigurierten Antwort in der konfigurierten fallbackLocale. Ein externer Kanal empfängt nie eine nicht fundierte Generierung, solange der Fallback aktiv ist; die Besucherin liest den Fallback statt einer sicheren Behauptung ohne Substanz darunter.

Limits als Schleuse des Workspace

Rate-Limit und Tagessessions sind das Schutzschild des Contract gegen externen Verkehr:

• 0 = unbegrenzt (der Sentinel-Wert des Routers).
• N = das Maximum pro Konnektor - für Anfragen wie für Sessions pro Tag.

Zusammen mit isEnabled können Sie die Knowledge Base an einen öffentlichen Kanal binden und den Wirkungsradius begrenzt halten: Ein entgleister Bot, ein gescrapeter Kanal oder ein unerwartetes Publikum verbraucht höchstens den konfigurierten Anteil des Workspace. Deaktivieren, straffen oder neu binden - jeweils eine einzige Bearbeitung (der v0.28.1-Zweig), ohne Neuanlage.

Zum Weiterlesen

Die Anleitung trägt die komplette Bedienerprozedur - das Formular Feld für Feld, die Adapter-Tabelle pro Plattform, das Audit-Verhalten - unter /de/docs/connectors:

• Konnektoren - die Anleitung
• Fakten dieses Beitrags: Zeilen FACT-CENSUS.md F-CONN-1 (die Ausgabe-Schranke), F-CONN-2 (der v0.28.1-Edit-Zweig), F-LIC-1 (die Aktivierung durch Einfügen des Schlüssels - ohne Serverzugriff)

Provenance: Simmetric Chat-Pakete connector.schema.ts (Feldformen + Limits), routes/connectors.ts (Router + Limiter), CHANGELOG.md v0.28.1, license.ts (connectors_enabled) am vom Census fixierten Dokumentenstand v0.28.1 (SHA aca5b8ff).