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

1. Lesen: GET …/public-visitor-surface (chatbot, bots, apiHints.visitorChatbotPost, apiHints.chatGapsPost, apiHints.chatInteractionsPost).
2. 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).
3. 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.
4. Agenten: cockpit_get_bots_profile lesen; Config schreiben via cockpit_update_bots_profile (inkl. neuer Chatbot-Felder).
5. Gap-Logging: Host-Chat-Route ruft logQueryGap → POST …/chat-gaps (Rate-Limit, anonym).
6. 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).
7. Lücken lesen (Dashboard): GET …/chatbot-analytics/gaps?centerId=… — Tab Analytics → „Unbeantwortete Fragen“. bots-profile.analytics.gapsReadApi für Agenten.
8. Neue Bot-Features: zuerst mallpilot-chat-core — Chat-Prompt „Bot-Feature mallpilot“.
9. 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

• Cockpit steuert Frontends
• AgencyOS-Integration
• Chatbot KI-Transparenz (Redaktion)
• Signage & Companion Ablauf (Repo)