# KI-Assistent (v1.37) – Einrichtung N8N + Kimi

Der Assistent läuft so: **Portal-Chat → N8N-Webhook → Kimi (Moonshot API) mit 6 Portal-Tools → Antwort zurück ins Portal.**

> **Stand: Der Workflow ist auf dem Produktivsystem (hocks.eu) bereits serverseitig eingerichtet und aktiv.**
> Die Datei `assist-workflow.json` in diesem Ordner ist die dokumentierte Referenz-Version.
> Der produktive Workflow wurde direkt in die N8N-Datenbank eingespielt, weil die lokale
> N8N-API in Version 2.x keinen zuverlässigen programmatischen Import erlaubt (401-Problem).
> Bei einem Re-Import auf einem anderen System müssen die drei Platzhalter im Code-Node belegt werden.

## 1. Architektur des Workflows

Ein einzelner Workflow **„Mieterportal – KI-Assistent (Kimi)"**, Webhook `POST mp-assist`, drei Nodes:

1. **Webhook Portal** (`n8n-nodes-base.webhook`, typeVersion 2, responseMode `responseNode`)
   – produktive URL: `http://n8n:5678/webhook/mp-assist` (internes Docker-Netz `npm_default`).
   – Wichtig: Der Node braucht die Property **`webhookId`** (gleich der Node-ID) auf Root-Ebene,
     sonst registriert n8n den Webhook bei `responseMode: responseNode` nicht (404 „not registered").
2. **Assistent (Kimi + Tools)** (`n8n-nodes-base.code`, typeVersion 2, runOnceForAllItems)
   – Prüft den Header `x-assist-secret` selbst gegen das Shared Secret.
   – Ruft `https://api.moonshot.ai/v1/chat/completions` (Modell `kimi-k2.6`) per
     `this.helpers.httpRequest` auf, mit OpenAI-kompatiblem **Tool-Calling** für genau die
     6 Portal-Endpunkte unter `/api/assist/tools/…` (Schleife, max. 6 Runden).
   – **Kein `temperature`-Parameter** senden – `kimi-k2.6` akzeptiert nur `temperature: 1`,
     sonst 400 „invalid temperature".
   – **Kein `URLSearchParams`** im Sandbox-Code verwenden – nicht verfügbar; Query-Strings
     manuell mit `encodeURIComponent` bauen.
   – 429 (Rate-Limit) wird abgefangen und als freundliche Meldung zurückgegeben.
3. **Antwort an Portal** (`n8n-nodes-base.respondToWebhook`, typeVersion 1.1)
   – `respondWith: json`, Body `={{ { antwort: $json.antwort } }}`.

Der langchain-basierte Entwurf (AI-Agent-Node) wurde verworfen: Die `@n8n/n8n-nodes-langchain`-
Nodes liefen auf diesem Server nicht zuverlässig. Der Code-Node-Ansatz hat keine externen
Abhängigkeiten und keine Credentials (alle Geheimnisse als Literale im Code-Node).

## 2. Geheimnisse (Platzhalter im Workflow-JSON)

| Platzhalter im Code-Node | Bedeutung | Wo konfiguriert |
|---|---|---|
| `<ASSIST_SHARED_SECRET>` | Header `x-assist-secret` zwischen Portal und n8n | `portal.env` (ASSIST_SHARED_SECRET) |
| `<ASSIST_KEY>` | Header `x-assist-key` für die 6 Tool-Endpunkte | `portal.env` (ASSIST_API_KEY) |
| `<KIMI_API_KEY>` | Moonshot-API-Key (`sk-…`) | Code-Node, Konstante ganz oben |

## 3. Portal-Env auf dem Server

In `/opt/mieterportal/portal.env` (nur auf dem VPS, gitignored):

```bash
N8N_ASSIST_WEBHOOK=http://n8n:5678/webhook/mp-assist
ASSIST_SHARED_SECRET=<langes-zufaelliges-geheimnis-1>
ASSIST_API_KEY=<langes-zufaelliges-geheimnis-2>
```

Danach: `cd /opt/mieterportal && docker compose up -d`.

## 4. Kosten

Kimi `kimi-k2.6`: ~0,4 US-Cent pro Frage (Systemprompt + Tool-Schleife). Bei 20 Fragen/Tag
typisch unter 5 €/Monat. Aufladung des Moonshot-Kontos ab ~5 $.

## 5. Test

Im Portal als Verwaltung: **KI-Assistent** in der Navigation → „Welche Wohnungen stehen leer?"
Der erste Aufruf dauert ggf. 10–60 s (Tool-Schleife).

Serverseitig direkt testbar:

```bash
docker exec mp-api node -e "fetch('http://n8n:5678/webhook/mp-assist',{method:'POST',headers:{'Content-Type':'application/json','x-assist-secret':'<SECRET1>'},body:JSON.stringify({frage:'Welche Wohnungen stehen leer?',verlauf:[],benutzer:'E2E'})}).then(async r=>console.log(r.status,await r.text()))"
```

## Fehlerbilder

| Fehlermeldung | Ursache |
|---|---|
| „not registered" (404) | Workflow nicht aktiv, `webhookId` am Webhook-Node fehlt, oder n8n neu gestartet ohne Outbox-Eintrag |
| „invalid temperature" (400) | `temperature != 1` im Kimi-Payload |
| „Assistent antwortet nicht (N8N Status 500)" | Kimi 429 (Rate-Limit, kurz warten) oder Code-Fehler – Executions in n8n prüfen |
| Antwort „Tool … nicht erreichbar" | Portal-Tool-Endpunkte nicht erreichbar (Netz `npm_default`, `x-assist-key`) |

## Datenschutz-Hinweis

Das Tool `mieter_kontakt` liefert personenbezogene Daten an Kimi (Serverstandort Singapur,
Training laut Anbieter-AGB möglich). Wer das vermeiden will, entfernt den Tool-Eintrag aus
dem `TOOLS`-Array im Code-Node – alle anderen Tools liefern nur Bestands- und Zahlen-Daten.