kpt-labs-vault/README.md
2026-06-23 07:00:43 +02:00

634 lines
18 KiB
Markdown

# 🚀 KPT-LABS Agent OS — System Recovery & Onboarding Guide
> **Letzte Aktualisierung:** 23.06.2026 07:00 | **Version:** 2.0.0
> **Vault Hash:** `v1.0-20260619-1400`
---
## 📋 Inhaltsverzeichnis
1. [System-Übersicht](#-system-übersicht)
2. [Schnellstart (5 Minuten)](#-schnellstart-5-minuten)
3. [Wichtige Pfade](#-wichtige-pfade)
4. [Datenbank-Schema](#-datenbank-schema)
5. [API-Keys & Credentials](#-api-keys--credentials)
6. [Services & Ports](#-services--ports)
7. [Disaster Recovery](#-disaster-recovery)
8. [Umzug auf Neuen PC](#-umzug-auf-neuen-pc)
9. [Automatische Prozesse](#-automatische-prozesse)
10. [Cron-Jobs](#-cron-jobs)
11. [Troubleshooting](#-troubleshooting)
12. [Kontakt & Support](#-kontakt--support)
---
## 🔍 System-Übersicht
Das KPT-LABS Agent OS ist ein **Multi-Agent Dashboard** mit folgenden Kernkomponenten:
| Komponente | Beschreibung | Port/Ort |
|------------|-------------|----------|
|| **Dashboard** | Next.js Web-UI | `http://localhost:3000` |
|| **Datenbank** | SQLite (better-sqlite3) | `dashboard/data/kptlabs.db` |
|| **Obsidian Vault** | Wissensdatenbank | `E:\OpenCode_Projekte\obsidianVault` |
|| **Hermes Gateway** | Telegram/Discord Bot | `localhost:8642` |
|| **Ollama** | LLM API (lokal) | `localhost:11434` |
> **Hinweis**: LiteLLM Proxy, Redis, Scanner und Memory (ChromaDB) wurden entfernt (2026-06-22).
> KPT-LABS nutzt jetzt **OpenRouter direkt** (Primary + Fallback) + **Ollama als lokalen Fallback**.
> Re-Implementierungsplan für LiteLLM: `05-Dashboard/Ideen/LiteLLM-Re-Implementation.md`
### Architektur-Diagramm
```
┌─────────────────────────────────────────────────────────────┐
│ KPT-LABS Agent OS │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Dashboard │ │ Hermes │ │ Telegram/Discord │ │
│ │ (Next.js) │ │ Gateway │ │ Bots │ │
│ │ Port 3000 │ │ Port 8642 │ │ │ │
│ └──────┬───────┘ └──────┬──────┘ └──────────┬──────────┘ │
│ │ │ │ │
│ └─────────────────┼─────────────────────┘ │
│ │ │
│ ┌──────┴──────┐ │
│ │ Ollama │ ← LLM API (lokal, free) │
│ │ :11434 │ │
│ └─────────────┘ │
│ ┌─────────────┐ │
│ │ OpenRouter │ ← Backup (API Keys) │
│ │ (direkt) │ │
│ └─────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ SQLite DB │ │ Obsidian │ │
│ │ (kptlabs) │ │ Vault │ │
│ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
---
## 🚀 Schnellstart (5 Minuten)
### Voraussetzungen
- Node.js 18+ & npm
- Git
- Ollama (optional, für lokale LLM)
- Obsidian (optional, für Vault)
### Git Setup (bereits konfiguriert)
```bash
# Git ist bereits initialisiert im Vault
cd obsidianVault
git status
# Erste Commits sind bereits vorhanden
git log --oneline
# Auto-Commit bei jedem System Snapshot (stündlich)
# Manuell committen:
git add -A
git commit -m "📝 update: Beschreibung"
```
### Git als Backup nutzen
```bash
# Remote Repository setzen (GitHub/GitLab)
git remote add origin <REPO_URL>
git push -u origin main
# Auf neuem PC klonen
git clone <REPO_URL> obsidianVault
```
### Installation
```bash
# 1. Repository klonen
git clone <REPO_URL> KPT-LABS
cd KPT-LABS
# 2. Dashboard
cd dashboard
npm install
npm run build
npm start
# 3. Ollama (optional, für lokale LLM)
# Ollama installieren: https://ollama.com
ollama pull llama3.1:8b
# 4. Hermes Gateway (optional)
hermes setup
hermes gateway start
# 5. Öffne Dashboard
open http://localhost:3000
```
### Erste Schritte
1. Login: `FK@KPT-LABS` / `admin`
2. System → Obsidian Tab → Sync prüfen
3. Chat senden → Token-Tracking testen
---
## 📁 Wichtige Pfade
### Windows (aktuell)
```
E:\OpenCode_Projekte\KPT-LABS\
├── dashboard/ → Next.js Dashboard
│ ├── src/
│ │ ├── app/api/ → API-Routen
│ │ ├── components/ → React-Komponenten
│ │ └── lib/ → Bibliotheken
│ ├── data/kptlabs.db → SQLite Datenbank
│ └── package.json
├── hermes-workspace/ → Hermes Frontend
├── obsidianVault/ → Wissensdatenbank
│ ├── Home.md
│ ├── 00-Meta/
│ ├── 01-Wissensdatenbank/
│ ├── 02-Projekte/
│ ├── 03-Ideenpool/
│ ├── 04-Sessions/
│ ├── 05-Dashboard/
│ └── 06-Notizen/
└── docker-compose.yml
```
### Linux/Mac (Zielpfade)
```
~/KPT-LABS/
├── dashboard/
├── hermes-workspace/
└── obsidianVault/
```
### Wichtige Dateien
| Datei | Zweck | Backup? |
|-------|-------|---------|
| `dashboard/data/kptlabs.db` | Hauptdatenbank | ✅ Täglich |
| `obsidianVault/` | Wissensdatenbank | ✅ Git |
| `dashboard/.env` | API-Keys | ✅ Verschlüsselt |
| `~/.hermes/config.yaml` | Hermes Config | ✅ |
| `~/.hermes/auth.json` | Credentials | ✅ |
---
## 🗄️ Datenbank-Schema
### Kern-Tabellen
```sql
-- Benutzer & Sessions
users (id, username, password_hash, role)
sessions (id, session_key, user_id, agent_id, title)
messages (id, session_id, role, content, agent_id, metadata)
-- API-Keys & Provider
api_keys (id, name, key, provider, is_active, preferred_models, priority)
provider_health (provider, model, status, avg_latency_ms, success_count, fail_count)
-- Token-Tracking
token_usage (id, session_id, agent_id, provider, model, input_tokens, output_tokens, cost_usd, latency_ms)
token_budgets (agent_id, period, token_limit, cost_limit_usd)
model_latency (provider, model, latency_ms, status)
-- Features
scheduled_tasks (id, name, agent_id, prompt, cron_expression, is_active)
agent_teams (id, name, leader_agent_id, status)
team_members (team_id, agent_id, model, role)
session_exports (id, session_id, format, file_path)
obsidian_sync_log (id, session_id, success, file_path, tokens_saved)
agent_state (id, uptime_seconds, total_sessions, total_messages, health_status)
```
### Wichtige Queries
```sql
-- Aktive Sessions heute
SELECT COUNT(*) FROM sessions WHERE date(created_at) = date('now');
-- Token-Verbrauch letzte 24h
SELECT SUM(total_tokens) FROM token_usage WHERE created_at >= datetime('now', '-1 days');
-- Provider Status
SELECT provider, status, avg_latency_ms FROM provider_health;
-- Offene Tasks
SELECT * FROM tasks WHERE status != 'done';
```
---
## 🔑 API-Keys & Credentials
### Provider-Konfiguration
| Provider | API-Key env var | Status |
|----------|----------------|--------|
| OpenRouter Primary | `OPENROUTER_KEY_PRIMARY` | ✅ Primär |
| OpenRouter Fallback1 | `OPENROUTER_KEY_FALLBACK1` | ✅ Fallback |
| NVIDIA | `OPENROUTER_KEY_FALLBACK2` | ⚠️ Inaktiv |
| Ollama (lokal) | — | ✅ Lokaler Fallback (llama3.1:8b, gemma4:12b) |
### Hermes Auth
```bash
# Credentials anzeigen
hermes auth list
# API Keys in .env hinterlegen:
# OPENROUTER_KEY_PRIMARY=sk-or-...
# OPENROUTER_KEY_FALLBACK1=sk-or-...
# Token-Status prüfen
hermes status
```
### Sicherheitshinweise
- 🔒 **Nie** API-Keys in Git committen
- 🔒 `.env` Dateien sind in `.gitignore`
- 🔒 `hermes auth.json` ist verschlüsselt
- 🔄 Keys regelmäßig rotieren (monatlich)
---
## 🌐 Services & Ports
| Service | Port | Starten | Status |
|---------|------|---------|--------|
| Dashboard | 3000 | `npm start` (in dashboard/) | 🟢 |
| Hermes Gateway | 8642 | `hermes gateway start` | 🟢 |
| Ollama | 11434 | `ollama serve` | 🟢 |
> **Hinweis**: LiteLLM Proxy, Redis, Scanner und Memory (ChromaDB) wurden entfernt.
> Nutze stattdessen Ollama direkt (:11434) und OpenRouter als Backup.
---
## 🚨 Disaster Recovery
### Szenario 1: Datenbank-Crash
```bash
# 1. Letztes Backup finden
ls -la dashboard/data/backups/
# 2. Backup wiederherstellen
cp dashboard/data/backups/kptlabs_<TIMESTAMP>.db dashboard/data/kptlabs.db
# 3. Dashboard neu starten
cd dashboard
npm start
```
### Szenario 2: Obsidian Vault beschädigt
```bash
# Git Repository wiederherstellen
cd obsidianVault
git checkout .
git pull
# Falls kein Git: Backup-Ordner nutzen
cp -r /path/to/backup/obsidianVault/* obsidianVault/
```
### Szenario 3: Kompletter System-Verlust
Siehe [Umzug auf Neuen PC](#umzug-auf-neuen-pc) — das ist die komplette Wiederherstellung.
### Szenario 4: API-Key abgelaufen
```bash
# 1. Neuen Key in .env eintragen
echo "OPENROUTER_API_KEY=neuer_key" >> dashboard/.env
# 2. Dashboard neu starten
cd dashboard
npm run build
npm start
# 3. Testen
curl http://localhost:3000/api/system
```
---
## 💻 Umzug auf Neuen PC
### Schritt 1: Auf altem PC exportieren
```bash
# Obsidian Vault klonen
cd obsidianVault
git add -A
git commit -m "pre-migration backup"
git push
# Datenbank sichern
cp dashboard/data/kptlabs.db kptlabs_backup.db
# Hermes Config sichern
cp ~/.hermes/config.yaml hermes_config_backup.yaml
cp ~/.hermes/auth.json hermes_auth_backup.json
```
### Schritt 2: Auf neuem PC importieren
```bash
# 1. Repository klonen
git clone <REPO_URL> KPT-LABS
cd KPT-LABS
# 2. Dashboard installieren
cd dashboard
npm install
cp ../kptlabs_backup.db data/kptlabs.db
npm run build
npm start
# 3. Obsidian Vault klonen
cd ..
git clone <OBSIDIAN_GIT_URL> obsidianVault
# 4. Hermes wiederherstellen
mkdir -p ~/.hermes
cp hermes_config_backup.yaml ~/.hermes/config.yaml
cp hermes_auth_backup.json ~/.hermes/auth.json
# 5. Docker starten
docker-compose up -d
```
### Schritt 3: Verifizieren
```bash
# Dashboard öffnen
open http://localhost:3000
# System Status prüfen
curl http://localhost:3000/api/system | jq '.status'
# Obsidian Sync prüfen
curl http://localhost:3000/api/obsidian/sync | jq '.vaultStats'
```
---
## ⏰ Automatische Prozesse
### Context Compression
- **Wann**: Bei 70% Token-Limit
- **Was**: Alte Nachrichten werden zusammengefasst
- **Config**: `app_settings.context_compression`
### Auto-Session-Save
- **Wann**: Alle 5 Nachrichten
- **Was**: Markdown-Datei in Obsidian Vault
- **Ort**: `04-Sessions/Daily/YYYY-MM-DD_agent.md`
### Token-Tracking
- **Wann**: Jeder API-Request
- **Was**: Input/Output Tokens, Kosten, Latenz
- **Wo**: `token_usage` Tabelle
### Provider Health Check
- **Wann**: Jeder API-Request
- **Was**: Erfolgsrate, Latenz, Cooldown
- **Wo**: `provider_health` Tabelle
---
## 📅 Cron-Jobs
| Job | Zeit | Script |
|-----|------|--------|
| System Snapshot | Stündlich | `python system_snapshot_v2.py` |
| Daily Backup | 03:00 | `python daily_backup.py` |
| Obsidian Sync Check | Alle 6h | `python obsidian_sync_check.py` |
| Weekly Report | Montag 09:00 | `python weekly_report.py` |
> **Hinweis**: Alle Cron-Jobs laufen als **standalone Python Scripts** — keine Next.js API-Calls mehr.
> Das umgeht das Auth/Redirect Problem.
---
## 🔧 Troubleshooting
### Dashboard startet nicht
```bash
# Logs prüfen
cd dashboard
npm run build 2>&1 | tail -20
# Port prüfen
netstat -ano | findstr :3000
# Neu starten
pkill -f next
npm start
```
### Datenbank-Fehler
```bash
# Prüfen
sqlite3 dashboard/data/kptlabs.db "SELECT count(*) FROM sessions;"
# Reparieren
sqlite3 dashboard/data/kptlabs.db ".dump" > backup.sql
rm dashboard/data/kptlabs.db
sqlite3 dashboard/data/kptlabs.db < backup.sql
```
### Obsidian Sync Fehler
```bash
# Manuell synchronisieren
curl -X POST http://localhost:3000/api/obsidian/sync \
-H "Content-Type: application/json" \
-d '{"action":"list-sessions"}'
```
### API-Key Probleme
```bash
# Testen
curl http://localhost:3000/api/system
# Neustart mit frischem Port
pkill -f next && sleep 2 && npm start
```
---
## 📊 System-Metriken (Live)
| Metrik | Aktualisierung | API |
|--------|---------------|-----|
| Sessions | Echtzeit | `/api/chat/sessions` |
| Token Usage | 10s | `/api/system` |
| Provider Health | 10s | `/api/system` |
| Obsidian Sync | 10s | `/api/obsidian/sync` |
| Agent State | 10s | `/api/agent-state` |
| Feedback | Echtzeit | `/api/feedback` |
---
## 📝 Changelog
### v1.0.0 (2026-06-19)
- ✅ Initiale Version
- ✅ Dashboard mit KPI Widget
- ✅ Context Compression
- ✅ Auto-Session-Save zu Obsidian
- ✅ Feedback-Loop System
- ✅ Agent State Tracking
- ✅ Cron-Jobs (Backup, Report, Sync)
- ✅ Disaster Recovery Guide
---
## 👥 Rollen
| Rolle | Zugriff | Beschreibung |
|-------|---------|-------------|
| **Admin** | Voll | Alles |
| **Agent** | Eingeschränkt | Chat, Tools |
| **Viewer** | Read-Only | Dashboard ansehen |
---
## 🔗 Nützliche Links
- **Dashboard**: http://localhost:3000
- **Hermes Docs**: https://hermes-agent.nousresearch.com/docs
- **OpenRouter**: https://openrouter.ai/keys
- **Obsidian**: https://obsidian.md
---
## 🤖 Opencode Integration
Opencode ist ein CLI-basierter AI-Coding-Agent (ähnlich Claude Code / Codex). Er kann direkt auf dem KPT-LABS Codebase arbeiten.
### Installation
```bash
# Opencode installieren
npm install -g opencode-ai
# Oder via Go
go install github.com/opencode-ai/opencode@latest
```
### Konfiguration für KPT-LABS
Opencode nutzt Ollama direkt oder OpenRouter als Backup:
```bash
# ~/.config/opencode/config.yaml
# Option A: Ollama (lokal, kostenlos)
model: "llama3.1:8b"
base_url: "http://localhost:11434/v1"
api_key: "ollama"
# Option B: OpenRouter (Backup)
# model: "openrouter/anthropic/claude-sonnet-4"
# base_url: "https://openrouter.ai/api/v1"
# api_key: "sk-or-..."
```
Oder als Umgebungsvariablen:
```bash
# Ollama
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_API_KEY=ollama
export MODEL=llama3.1:8b
# OpenRouter (Backup)
# export OPENAI_BASE_URL=https://openrouter.ai/api/v1
# export OPENAI_API_KEY=sk-or-...
# export MODEL=openrouter/anthropic/claude-sonnet-4
```
### Opencode starten
```bash
# Im Projektverzeichnis
cd E:\OpenCode_Projekte\KPT-LABS
# Interaktiver Modus
opencode
# Mit direktem Prompt
opencode "Erstelle eine neue API Endpoint für X"
# Im Dashboard-Verzeichnis
cd dashboard
opencode "Fix the build error in tasks/route.ts"
```
### Opencode vs Hermes vs OWL
| Tool | Typ | Best Use Case |
|------|-----|---------------|
| **OWL** (ich) | Telegram-Agent | Orchestrierung, Planung, Multi-Step Tasks |
| **Hermes** | Gateway + Telegram Bot | Bot-Commands, Cron-Jobs, Notifications |
| **Opencode** | CLI Coding Agent | Code schreiben, Refactoring, Debugging |
| **Claude Code** | CLI Coding Agent | Komplexe Features, Code Reviews |
### Workflow: Opencode + OWL zusammen
1. **OWL** plant die Aufgabe und erstellt Specs
2. **Opencode** implementiert den Code
3. **OWL** testet und verifiziert
4. **Hermes** deployed und monitored
```bash
# Beispiel: Neues Feature bauen
# 1. OWL erstellt Spec in Vault
# 2. Opencode liest Spec und implementiert
cd E:\OpenCode_Projekte\KPT-LABS
opencode "Lies E:\OpenCode_Projekte\obsidianVault\02-Projekte\Feature-X.md und implementiere es"
# 3. OWL testet
python -m pytest tests/
```
### Opencode Regeln für KPT-LABS
- **Immer** im Projekt-Root starten (`E:\OpenCode_Projekte\KPT-LABS`)
- **Vor** großen Änderungen: Vault-Backup committen
- **Nach** Änderungen: `git add -A && git commit -m "..."`
- **Nie** API-Keys in Code hardcoden — immer `.env` nutzen
- **Datenbank-Änderungen**: Migration-Script in `system/migrations/` erstellen
### Opencode + Vault Sync
Opcode kann Vault-Dateien lesen/schreiben:
```bash
# Vault-Notiz erstellen
opencode "Erstelle eine technische Dokumentation für das YouTube-Watcher System in E:\OpenCode_Projekte\obsidianVault\02-Projekte\YouTube-Watcher.md"
# Vault-Notiz lesen und implementieren
opencode "Lies die Spec in 02-Projekte\Feature-X.md und implementiere Phase 1"
```
---
## ⚠️ Checkliste für neuen Agenten
- [ ] Diese Datei gelesen
- [ ] Dashboard geöffnet und Login getestet
- [ ] Obsidian Vault Pfad geprüft
- [ ] API-Keys vorhanden (`.env`)
- [ ] Ollama läuft (`ollama serve`)
- [ ] Erste Chat-Nachricht gesendet
- [ ] Token-Tracking geprüft
- [ ] Backup getestet
---
*Diese Datei wird automatisch aktualisiert. Nicht manuell bearbeiten.*
*Generiert von: KPT-LABS Agent OS v1.0.0*
*Bei Fragen: Erstelle ein Issue im Repository oder kontaktiere den Admin.*