Zum Hauptinhalt springen

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​

RolleNutzen
Redaktion / Center-BetriebEin Modul statt drei Einstiege
v0-EntwicklerAggregierte 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/CompanionGleiche v0-Architektur wie Website; Legacy-Runtime bis Migration

Architektur (Kurz)​

UI-Fassade, Legacy-Speicher bleibt canonical:

KanalSpeicher (unverändert)Write heute
Website / v0AIConfiguration (appType=center_website) + themeOverrideschatbotConfig in website-config
CompanionShoppingCenter.companionConfigPATCH …/companion-config
Signage AI PremiumsignageTemplateOptions['ai-premium']PUT …/signage-template-options
Center-Wissen (Mall Pilot)AIConfiguration.parameters.centerKnowledgePATCH …/bots-profile/center-knowledge
Mall Pilot Chat (unified)AIConfiguration.parameters.mallPilotChat (+ Legacy Dual-Write)PATCH …/bots-profile mit mallPilotChat

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/centers/{centerId}/bots-profile/center-knowledge
PATCH /api/centers/{centerId}/bots-profile/center-knowledge
GET /api/agencyos/v1/centers/{centerId}/bots-profile/center-knowledge
PATCH /api/agencyos/v1/centers/{centerId}/bots-profile/center-knowledge
GET /api/agencyos/v1/bots-profile/write-schema # Schreib-Mapping

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

Center-Wissen ist nicht in public-visitor-surface — weder strukturiert noch als Fließtext.

ConsumerZugriff
Legacy visitor-chatbotSlice centerKnowledge serverseitig im Cockpit
v0 Host /api/chatGET …/visitor-knowledge mit COCKPIT_REGISTER_TOKEN (frt_…) — siehe apiHints.visitorKnowledgeGet
Agenten / MCPGET …/agencyos/v1/…/bots-profile/center-knowledge (Bearer) oder cockpit_get_center_knowledge
DashboardSession: GET …/bots-profile/center-knowledge

Vorschläge aus Claude (Freigabe)​

Center-Fakten aus Claude-Chats (capture_knowledge, kind center_fact) landen in center_knowledge_proposals (status draft) — nicht direkt live.

SchrittWo
Vorschlag anlegenAgencyOS/MCP: POST …/agencyos/v1/centers/knowledge-proposals oder cockpit_propose_center_knowledge
Liste + DiffGET …/knowledge-proposals?status=draft / cockpit_list_center_proposals
FreigabeDashboard: Bots & Assistenten → Center-Wissen → Vorschläge aus Claude oder cockpit_approve_center_proposal
Ablehnencockpit_reject_center_proposal

Nicht für Shop/Event/Offer-Inhalte — dafür content_push / Workflow-Freigabe.

Capture-Mapping: title → FAQ-Frage/Rationale, problem → Rationale, solution → proposed_value, context.center → Center-Auflösung, dedupe_key → Idempotenz, author_email aus Auth.

Public (v0 Runtime)​

GET …/public-visitor-surface → data.bots zusätzlich zu data.chatbot.
Ab 0.1.564: data.chatbot.resolved — aufgelöste Config pro Kanal (website, companion, kiosk). Signage: signage-surface → surface.chatbot.resolved. Handoff: V0_MALLPILOT_CHAT_SCHEMA.md.
Ab 0.1.568: consent.showIcon — Schild-Icon im Consent-Dialog (Default: an); v0/mallpilot-chat-core muss Feld auswerten (siehe Handoff-Doku).
apiHints.agencyosBotsProfileGet → AgencyOS (Bearer).
apiHints.visitorKnowledgeGet → Center-Wissen (Register-Token, nur serverseitig in v0 /api/chat).

MCP​

ToolStatus
cockpit_get_bots_profilelive
cockpit_update_bots_profilelive
cockpit_bots_profile_schemalive
cockpit_get_center_knowledge / cockpit_update_center_knowledgelive
cockpit_propose_center_knowledge / cockpit_list_center_proposals / cockpit_approve_center_proposal / cockpit_reject_center_proposallive (Vorschläge aus Claude, Freigabe vor Live)
cockpit_update_bots_profile { centerKnowledge }live (Alias)
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 chatbothubManaged — aus Sidebar, Hub Tab Website & v0
Signage-Reiter companionhubManaged — Hub Tab Companion & Signage
DE → CompanionKonfig-Tab entfernt; Link-Karte → Hub
/dashboard/companion-app/configRedirect → Hub
Deprecation-BannerEntfernt
fg-chatbotUnberührt (Forum Custom)

Nicht angefasst: visitor-chatbot, companion-config PATCH, signage-template-options, chatbotConfig, data.chatbot / data.bots.

Signage Companion-Optionen vs. Mall Pilot (ab 0.1.566)​

BereichWo konfigurierenInhalt
Mall Pilot (?tab=mall-pilot)Bots & Assistenten → Mall PilotChat-UI: Assistenten-Name, Begrüßung, Vorschläge, Voice, Disclaimer, Kanal-Overrides (Website / Companion / Kiosk)
Companion nach ScanSignage-Konfig → Companion (Template) oder Hub → Companion & Signage → „Companion nach Scan“Nur Shell: Farben, Quicklink-Akzente, Menü & Navigation (routeStepsEnabled, menuSearchEnabled, menuHintTitle, menuHintText), AI-Vorschlagsfragen-Toggle, Standard-Ziel-Shop — kein doppelter Chat-Block mehr

Digital Experience → Companion App verlinkt auf beide Hub-Reiter (Mall Pilot für Chat, Companion & Signage für Branding/Module).

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).

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