Bots & Assistenten — Hub-Spec (Entwickler)

Status: Phase 1–5 live (Hub, APIs, MCP, UI-Cutover). Forum fg-chatbot unberührt.

Was

Ein zentraler Cockpit-Hub bündelt alle Einstellungen für Website-Chatbot, Companion-KI und Signage/Kiosk-KI. Redaktion konfiguriert an einer Stelle; v0-Bots und Agenten nutzen dieselbe Wahrheit über API/MCP.

Warum

Bot-relevante Felder liegen heute verstreut (Webseiten-Reiter Chatbot, Digital Experience → Companion, Signage AI Premium, Analytics-Modul). Für MallPilot/CityPilot und v0-Apps braucht es eine konfigurierbare, agentenlesbare Oberfläche — ohne laufende Bots zu brechen.

Wer ist betroffen

Rolle	Nutzen
Redaktion / Center-Betrieb	Ein Modul statt drei Einstiege
v0-Entwickler	Aggregierte Read-View + ein Bot-Baukasten (mallpilot-chat-core) für Website, Signage und Companion
Agenten (MCP/AgencyOS)	`cockpit_get_bots_profile` / `cockpit_update_bots_profile`
Signage/Companion	Gleiche v0-Architektur wie Website; Legacy-Runtime bis Migration

Architektur (Kurz)

UI-Fassade, Legacy-Speicher bleibt canonical:

Kanal	Speicher (unverändert)	Write heute
Website / v0	`AIConfiguration` (`appType=center_website`) + `themeOverrides`	`chatbotConfig` in website-config
Companion	`ShoppingCenter.companionConfig`	`PATCH …/companion-config`
Signage AI Premium	`signageTemplateOptions['ai-premium']`	`PUT …/signage-template-options`

Runtime — Ziel (alle v0-Kanäle): mallpilot-chat-core + Host POST /api/chat im v0-Projekt; Analytics über apiHints.chatInteractionsPost / chatGapsPost.

Runtime — Legacy (bis Migration): POST /api/ai/visitor-chatbot mit client=website|companion|kiosk (WordPress, alte SPA, noch nicht umgestellte Deploys). Kein neuer v0-Kanal darauf aufsetzen.

API

Aggregierte Read-View

GET /api/centers/{centerId}/bots-profile
GET /api/agencyos/v1/centers/{centerId}/bots-profile
PATCH /api/centers/{centerId}/bots-profile              # Partial — alle Kanäle
PATCH /api/agencyos/v1/centers/{centerId}/bots-profile
PATCH /api/centers/{centerId}/bots-profile/website      # nur chatbotConfig (Legacy-Alias)
GET /api/agencyos/v1/bots-profile/write-schema          # Schreib-Mapping

Liefert channels.website, channels.companion, channels.signage, shared, _sources — ohne API-Key-Klartext.

Public (v0 Runtime)

GET …/public-visitor-surface → data.bots zusätzlich zu data.chatbot.
apiHints.agencyosBotsProfileGet → AgencyOS (Bearer).

MCP

Tool	Status
`cockpit_get_bots_profile`	live
`cockpit_update_bots_profile`	live
`cockpit_bots_profile_schema`	live
`cockpit_update_center_website_config { chatbotConfig }`	unverändert (Legacy)

v0-Integration

Lesen: GET …/public-visitor-surface (chatbot, bots, apiHints.visitorChatbotPost, apiHints.chatGapsPost, apiHints.chatInteractionsPost).
Bot-UI (min. 0.8.1): Master-Chat /mallpilot-chat-core-kJyZM1UHiHR + github.com/sawmuedev/mallpilot-chat-core — Reference-Copy packages/mallpilot-chat/. Standard: MallPilotSearchBar (Hero) + ChatWidget + VoiceNavigator via MallPilotSiteShell; Config: getChatWidgetConfig(centerId).
Persona-Felder in data.chatbot: assistantName, triggerLabel, chatApiUrl, voiceEnabled (nur false explizit), primaryColor, avatarUrl, greetingMessage, quickTopics[], actions[], capabilities.wayfinding. Legacy-Felder (position, variant, Mally, …) bleiben für alte Frontends.
Agenten: cockpit_get_bots_profile lesen; Config schreiben via cockpit_update_bots_profile (inkl. neuer Chatbot-Felder).
Gap-Logging: Host-Chat-Route ruft logQueryGap → POST …/chat-gaps (Rate-Limit, anonym).
Interaction-Logging: Host-Chat-Route nach jeder Antwort → POST …/chatbot-interactions (source: chatbot, userQuery, aiResponse, optional Intent) — füllt Cockpit Chatbot-Reports/Trending (Rate-Limit, anonymisierte Query).
Lücken lesen (Dashboard): GET …/chatbot-analytics/gaps?centerId=… — Tab Analytics → „Unbeantwortete Fragen“. bots-profile.analytics.gapsReadApi für Agenten.
Neue Bot-Features: zuerst mallpilot-chat-core — Chat-Prompt „Bot-Feature mallpilot“.
Runtime (Soll): Website und Signage/Companion-v0 → Host POST /api/chat (docs/api-chat-route.production.example.ts); source bei Interaction-Logging: chatbot | companion | kiosk. Legacy: visitor-chatbot — siehe Public-API-Vertrag. v0 Copy-Paste: packages/mcp-cockpit-os/V0_CHATBOT_ANALYTICS_INSTRUCTION.md.

Agenten konfigurieren über MCP/AgencyOS; v0 konsumiert zur Laufzeit die Public Read-Pfade.

Kompatibilität

Kein Speicher-Umzug in Phase 1–4.
themeOverrides.chatbotEnabledFallback bleibt für Legacy-Center.
Alte Dashboard-Reiter ausgeblendet (Phase 5); fg-chatbot (Forum) bleibt unter Webseiten.

Phase 5 — UI-Cutover (live)

Ziel erreicht: Redaktion konfiguriert Bots nur noch unter /dashboard/bots-assistenten?tab=…. Legacy-APIs unverändert.

Bereich	Änderung
Webseiten-Reiter `chatbot`	`hubManaged` — aus Sidebar, Hub Tab Website & v0
Signage-Reiter `companion`	`hubManaged` — Hub Tab Companion & Signage
DE → Companion	Konfig-Tab entfernt; Link-Karte → Hub
`/dashboard/companion-app/config`	Redirect → Hub
Deprecation-Banner	Entfernt
`fg-chatbot`	Unberührt (Forum Custom)

Nicht angefasst: visitor-chatbot, companion-config PATCH, signage-template-options, chatbotConfig, data.chatbot / data.bots, AI-Premium-Template-Reiter in Signage-Konfig.

Smoke-Tests

pnpm --filter @mall-os/dashboard exec tsx scripts/smoke-bots-profile.ts

Prüft: public-visitor-surface (data.bots), visitor-chatbot (website/companion/kiosk), buildBotsProfile-Abgleich, Fallback ohne AIConfiguration-Zeile.

Betrieb

Keine neuen Env-Variablen in Phase 1–3. Auth wie website-config (Session / AgencyOS Bearer).

Links

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/developer-guide/bots-assistenten-hub

Was​

Warum​

Wer ist betroffen​

Architektur (Kurz)​

API​

Aggregierte Read-View​

Public (v0 Runtime)​

MCP​

v0-Integration​

Kompatibilität​

Phase 5 — UI-Cutover (live)​

Smoke-Tests​

Betrieb​

Links​

Was