139 lines
9.8 KiB
Markdown
139 lines
9.8 KiB
Markdown
# Einrichtung nach dem Start: alles integrieren
|
||
|
||
Diese Anleitung setzt dort an, wo `scripts/dev.sh --reset` (oder `--setup` plus `uv run aiw demo`) aufhört. Danach gibt es schon:
|
||
|
||
- Demo-Team mit den Nutzern admin (Plattform-Admin), entwicklung, fachbereich und freigabe (Freigeber in den Demo-Workspaces), Passwort aus `AIW_DEMO_PASSWORD`
|
||
- die Workspaces „Demo: Bestellservice“ (mit Shop-Datenbank), „Demo: MCP-Entwicklung“ und „Demo: Nur Chat“ (ohne Datenquellen, zum Vergleich)
|
||
- den Datenbank-Treiber PostgreSQL und die eingebauten Tools, nach Vorschlag eingestuft
|
||
|
||
Zum Abhaken in kurz: [Checkliste](checkliste.md). Diese Fassung ist für Entwicklung und Betrieb: mit `.env`, lokalen Diensten und Ports. Die reinen Klickwege stehen auch in der Online-Hilfe: *Für Plattform-Admins → Ersteinrichtung* (`/hilfe/plattform-admin#ersteinrichtung`) und *Für Workspace-Admins → Workspace startklar machen* (`/hilfe/workspace-admin#workspace-startklar-machen`). Ändert sich ein Klickweg, beide Stellen anpassen.
|
||
|
||
Alles Weitere richtest du als `admin` unter http://127.0.0.1:8765 ein. Reihenfolge: erst das Pflichtprogramm (1–2), dann, was du brauchst (3–8). Änderungen an `.env` wirken erst nach einem Neustart von `scripts/dev.sh`.
|
||
|
||
| Nr. | Was | Pflicht? | Ohne geht nicht … |
|
||
|---|---|---|---|
|
||
| 1 | Modell | ja | überhaupt eine Antwort |
|
||
| 2 | Tools prüfen | ja | Tool-Aufrufe (sonst gesperrt) |
|
||
| 3 | Munin (Gedächtnis) | nein | Merken über Chats hinweg |
|
||
| 4 | Hugin (Regeln, Skills, Befehle) | nein | Pakete, Slash-Befehle |
|
||
| 5 | Dokumenten-Auslese | nein | Office, PDF, Bilder in abgeglichenen Ordnern |
|
||
| 6 | Bitbucket | nein | Pushen und Pull Requests auf einen echten Server |
|
||
| 7 | Benachrichtigungen | nein | E-Mails zu Freigaben, Teams/Slack |
|
||
| 8 | Weiteres | nein | eigene Nutzer, Oracle, eigene MCP-Server |
|
||
|
||
## 1. Modell (Pflicht)
|
||
|
||
**Wo:** *Administration → Modelle und Zugänge*
|
||
|
||
1. **Endpunkt anlegen:** Name (z. B. „OpenAI“) und Basis-URL einer OpenAI-kompatiblen Responses API, z. B. `https://api.openai.com/v1`. Später kommt hier das AI Gateway dazu.
|
||
2. **API-Key hinterlegen:** am Endpunkt einen Key für *alle Teams* (lokal am einfachsten) oder je Team. Er wird verschlüsselt gespeichert; angezeigt werden nur die letzten Zeichen.
|
||
3. **Modell hinzufügen:** Modell-ID beim Anbieter (z. B. `gpt-6-luna`), Bezeichnung, Kontextgröße und, wenn du Kosten sehen willst, Preise je Million Tokens. Das erste Modell wird Standard.
|
||
4. **Verbindung testen** am Modell.
|
||
|
||
**Klappt, wenn:** In einem Demo-Workspace oben „Modell …“ steht und eine Beispielfrage unter *Ausprobieren* eine Antwort bekommt.
|
||
|
||
Ein Workspace kann unter *Einstellungen → Allgemein → Modell* ein anderes Modell wählen.
|
||
|
||
## 2. Tools prüfen (Pflicht)
|
||
|
||
**Wo:** *Administration → Tools*
|
||
|
||
Die Demo hat die eingebauten Tools nach Vorschlag eingestuft. Prüfe trotzdem:
|
||
|
||
- Stehen Tools auf *nicht eingestuft*, z. B. nach einem Update oder bei neuen MCP-Servern: *Vorschläge übernehmen* (nur eingebaute Tools) oder einzeln einstufen. Nicht eingestufte Tools sind für die KI gesperrt.
|
||
- Die Voreinstellung: `read` und `write_internal` erlaubt, `write_external` mit Freigabe, `destructive` gesperrt. Strenger geht es global hier oder je Workspace unter *Einstellungen → Tools*.
|
||
|
||
**Klappt, wenn:** Die Beispielfrage „Was hat sich in den letzten zwei Wochen im Repository geändert?“ Tool-Aufrufe zeigt (aufklappbar unter der Antwort) und keine Meldung „nicht verfügbar“.
|
||
|
||
## 3. Munin: Gedächtnis
|
||
|
||
Munin läuft als zentraler MCP-Dienst (Streamable HTTP). Du brauchst seine URL, für die Registrierung ggf. ein Token, und je Workspace einen Munin-Key; der Key bestimmt das Projekt in Munin.
|
||
|
||
**Plattform-Admin, einmalig:** *Administration → MCP-Server*
|
||
|
||
1. Server anlegen: Kurzname `munin`, Bezeichnung „Munin“, URL (z. B. `https://munin.intern/mcp`), **Art: Gedächtnis**. Der Host muss in `AIW_MCP_ALLOWED_HOSTS` stehen; lokal (`localhost`) erlaubt `scripts/dev.sh` ihn ohnehin.
|
||
2. *Tools abrufen*. Die Seite zeigt die Anleitung des Servers.
|
||
3. *Empfehlung übernehmen*: Lesen und Merken erlaubt, `forget` gesperrt. Löschen dürfen nur Menschen.
|
||
|
||
**Workspace-Admin, je Workspace:** *Einstellungen → MCP-Server → Zentrale Server*
|
||
|
||
4. Munin mit dem Munin-Key des Projekts freischalten.
|
||
|
||
**Klappt, wenn:** Im Chat „Merk dir: Deployments nie freitags nach 14 Uhr.“ einen Eintrag erzeugt, der unter *Gedächtnis* (Seitenleiste des Workspace) erscheint, und ein neuer Chat ihn auf Nachfrage kennt.
|
||
|
||
## 4. Hugin: Regeln, Skills und Befehle
|
||
|
||
Hugin ist das Register für geprüfte KI-Erweiterungen. Lokal zum Ausprobieren: im Repository `hugin` `scripts/demo.sh` starten (Server auf `http://127.0.0.1:8080`); den Integrations-Key „Softwareverteilung“ (`hi_…`, Tenant `shop`) findest du in `.demo/keys.txt`.
|
||
|
||
**Plattform-Admin, einmalig:** *Administration → Hugin*
|
||
|
||
1. Host eintragen, z. B. `http://127.0.0.1:8080` → „Hugin ist erreichbar“. Mit `AIW_HUGIN_URL` in `.env` ist er vorausgefüllt.
|
||
|
||
**Workspace-Admin, je Workspace:** *Einstellungen → Hugin*
|
||
|
||
2. Unter *Zugang* den Integrations-Key (`hi_…`) eintragen → Bifröst zeigt Tenant und Key-Name. In Hugin legt man ihn unter *Integrationen* mit den Rollen Lesen und Ausliefern an.
|
||
3. Pakete wählen (z. B. `pub-release-notiz`), *Abgleichen*, *Übernehmen*. Übernommene Pakete sind festgeschrieben; Updates prüft der Worker im Hintergrund.
|
||
|
||
**Plattform-Admin:** Falls unter *Tools* `load_skill`, `read_skill_file` oder `hugin_feedback` noch nicht eingestuft sind, jetzt einstufen.
|
||
|
||
**Klappt, wenn:** Im Chat `/` die Befehle aus Hugin vorschlägt und Antworten unten „Hugin: …“ mit den geltenden Paketen zeigen.
|
||
|
||
## 5. Dokumenten-Auslese für abgeglichene Ordner
|
||
|
||
Textdateien (Markdown, TXT, CSV …) liest Bifröst selbst. Für Office, PDF und Bilder braucht es den zentralen MCP-Server, der den Dateiinhalt als Base64 nimmt und Text liefert.
|
||
|
||
**Plattform-Admin:** *Administration → MCP-Server*
|
||
|
||
1. Server anlegen mit URL und **Art: Dokumenten-Auslese**, *Tools abrufen*.
|
||
2. Auf der Seite des Servers unter *Dokumenten-Auslese*: das Tool wählen, den Parameter für den Inhalt (Base64) und optional den für den Dateinamen. *Speichern*.
|
||
|
||
Die KI ruft dieses Tool nicht selbst auf; der Worker schickt neue und geänderte Dateien hin. Grenzen in `.env`: `AIW_DOC_MAX_MB`, `AIW_DOC_MAX_FILES`, `AIW_DOC_MAX_TEXT_KB`, `AIW_DOC_EXTRACT_TIMEOUT_SECONDS`.
|
||
|
||
**Klappt, wenn:** Unter *Daten → Abgeglichene Ordner* eine DOCX- oder PDF-Datei nach kurzer Zeit von „wird ausgelesen“ auf „lesbar“ wechselt. Ordner abgleichen geht am bequemsten in Chrome oder Edge.
|
||
|
||
## 6. Bitbucket: pushen und Pull Requests
|
||
|
||
Die Demo-Repositories liegen lokal (`file://…`); Branches der KI bleiben dort. Für einen echten Server:
|
||
|
||
**Workspace-Admin:** *Daten → Verbinden → Git-Repository* (oder eine vorhandene Quelle *Bearbeiten*)
|
||
|
||
1. HTTPS-URL, Ziel-Branch (meist `main`) und ein Token. Bei Bitbucket Data Center ein HTTP-Access-Token; bei anderen Servern (Gitea, Forgejo, GitLab, GitHub) Token plus Nutzername.
|
||
2. Unter *Pull Requests* „Bitbucket Data Center“ wählen. Ohne das kann man Branches nur pushen.
|
||
3. Der technische Account braucht Schreib- und Löschrechte auf `ai/*` (Branch Permission). Der Host muss in `AIW_GIT_ALLOWED_HOSTS` stehen.
|
||
|
||
**Klappt, wenn:** Nach einer Änderung durch die KI unter *Änderungen* „Branch pushen“ bzw. „Pull Request erstellen“ funktioniert und im Bereich *Repository → Pull Requests* die offenen PRs erscheinen.
|
||
|
||
## 7. Benachrichtigungen
|
||
|
||
**E-Mail (Plattform):** in `.env`
|
||
|
||
```bash
|
||
AIW_SMTP_HOST=smtp.intern
|
||
AIW_SMTP_PORT=587
|
||
AIW_SMTP_USER=...
|
||
AIW_SMTP_PASSWORD=...
|
||
AIW_SMTP_FROM=bifroest@firma.de
|
||
AIW_PUBLIC_URL=http://127.0.0.1:8765 # Basis für Links in E-Mails
|
||
```
|
||
|
||
Jede Person trägt ihre Adresse im *Profil* ein (Klick auf den Namen oben rechts). Stand der Zustellung: *Administration → Benachrichtigungen*.
|
||
|
||
**Teams oder Slack (je Workspace):** *Einstellungen → Allgemein → Benachrichtigungen*, Webhook-URL eintragen. Erlaubte Hosts stehen in `AIW_WEBHOOK_ALLOWED_HOSTS`.
|
||
|
||
**Klappt, wenn:** Ein Tool mit Freigabe (z. B. ein schreibendes MCP-Tool) eine E-Mail bzw. eine Nachricht an die Freigebenden auslöst.
|
||
|
||
## 8. Weiteres nach Bedarf
|
||
|
||
- **Eigene Nutzer und Teams:** *Administration → Teams* und *→ Nutzer*. Neue Nutzer bekommen ein Einmal-Passwort und setzen beim ersten Login ein eigenes. Im Workspace unter *Einstellungen → Mitglieder* aufnehmen; Rollen: Mitglied, Freigeber, Admin.
|
||
- **Oracle:** `scripts/dev.sh --oracle` startet Container und DB-Dienst (Port 8792). Treiber unter *Administration → Datenbank-Treiber* registrieren (URL und Schlüssel zeigt das Skript), *Tools abrufen*, einstufen; dann im Workspace eine Datenbank mit Service-Name `FREEPDB1` verbinden.
|
||
- **Eigene MCP-Server:** zentral unter *Administration → MCP-Server* oder je Workspace unter *Einstellungen → MCP-Server → Eigene Verbindungen*. Neue Tools einstufen (die Annotations sind nur ein Vorschlag). Was ein eigener Server mitbringen sollte, zeigt die Demo „MCP-Entwicklung“ (*MCP-Unterlagen*).
|
||
- **Globale Approver:** unter *Administration → Nutzer* einzelne Personen als *Globaler Approver* markieren; unter *Administration → Tools* bei einem Tool die Freigabestufe „global“ wählen. Solche Anträge entscheiden dann nur sie, nicht die Workspace-Admins.
|
||
|
||
## Abschluss: alles einmal durchprobieren
|
||
|
||
- [ ] Bestellservice: die acht Beispielfragen, darunter Repository, Bestelldaten mit Diagramm, Dokumente, Shop-Datenbank und die Rabatt-Änderung (Commit auf `ai/…`).
|
||
- [ ] MCP-Entwicklung: Annotations prüfen, Review gegen Code, langsamste Tools als Diagramm.
|
||
- [ ] Munin merkt sich etwas, Hugin-Befehl mit `/` funktioniert, eine DOCX wird lesbar.
|
||
- [ ] Antworten mit 👍/👎 bewerten; unter *Nutzung und Kosten* erscheinen Verbrauch und Rückmeldungen.
|
||
|
||
Ausführliche Prüfschritte stehen im [Testplan](testplan.md), die Bedienung in der Online-Hilfe (Knopf *Hilfe* oben).
|