541 lines
14 KiB
Markdown
541 lines
14 KiB
Markdown
# 🚀 KPT-LABS Agent OS — System Recovery & Onboarding Guide
|
|
|
|
> **Letzte Aktualisierung:** 2026-06-19 14:00 | **Version:** 1.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:5555` |
|
|
| **Datenbank** | SQLite (better-sqlite3) | `dashboard/data/kptlabs.db` |
|
|
| **Obsidian Vault** | Wissensdatenbank | `E:\OpenCode_Projekte\obsidianVault` |
|
|
| **Hermes Gateway** | Telegram/Discord Bot | `localhost:8642` |
|
|
| **LiteLLM Proxy** | LLM API Proxy | `localhost:4000` |
|
|
| **Redis** | Cache/Session Store | `localhost:6379` |
|
|
| **Memory Service** | Agent Memory | `localhost:5002` |
|
|
|
|
### Architektur-Diagramm
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ KPT-LABS Agent OS │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
|
|
│ │ Dashboard │ │ Hermes │ │ Telegram/Discord │ │
|
|
│ │ (Next.js) │ │ Gateway │ │ Bots │ │
|
|
│ │ Port 5555 │ │ Port 8642 │ │ │ │
|
|
│ └──────┬───────┘ └──────┬──────┘ └──────────┬──────────┘ │
|
|
│ │ │ │ │
|
|
│ └─────────────────┼─────────────────────┘ │
|
|
│ │ │
|
|
│ ┌──────┴──────┐ │
|
|
│ │ LLM APIs │ │
|
|
│ │ (OpenRouter │ │
|
|
│ │ Anthropic │ │
|
|
│ │ OpenAI...) │ │
|
|
│ └─────────────┘ │
|
|
│ │
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
|
|
│ │ SQLite DB │ │ Obsidian │ │ Docker │ │
|
|
│ │ (kptlabs) │ │ Vault │ │ (LiteLLM,Redis) │ │
|
|
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Schnellstart (5 Minuten)
|
|
|
|
### Voraussetzungen
|
|
- Node.js 18+ & npm
|
|
- Git
|
|
- Docker & Docker Compose
|
|
- 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. Docker Services (LiteLLM, Redis)
|
|
docker-compose up -d
|
|
|
|
# 4. Hermes Gateway (optional)
|
|
hermes setup
|
|
hermes gateway start
|
|
|
|
# 5. Öffne Dashboard
|
|
open http://localhost:5555
|
|
```
|
|
|
|
### 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 | `OPENROUTER_API_KEY` | ✅ Aktiv |
|
|
| Anthropic | `ANTHROPIC_API_KEY` | ⬜ Optional |
|
|
| OpenAI | `OPENAI_API_KEY` | ⬜ Optional |
|
|
| DeepSeek | `DEEPSEEK_API_KEY` | ⬜ Optional |
|
|
|
|
### Hermes Auth
|
|
```bash
|
|
# Credentials anzeigen
|
|
hermes auth list
|
|
|
|
# Neuen Key hinzufügen
|
|
hermes auth add openrouter
|
|
hermes auth add anthropic
|
|
|
|
# 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 | 5555 | `npm start` (in dashboard/) | 🟢 |
|
|
| Hermes Gateway | 8642 | `hermes gateway start` | 🟢 |
|
|
| LiteLLM Proxy | 4000 | `docker-compose up -d` | 🟢 |
|
|
| Redis | 6379 | `docker-compose up -d` | 🟢 |
|
|
| Memory Service | 5002 | `docker-compose up -d` | 🟢 |
|
|
|
|
### Docker Services
|
|
```bash
|
|
# Starten
|
|
cd KPT-LABS
|
|
docker-compose up -d
|
|
|
|
# Stoppen
|
|
docker-compose down
|
|
|
|
# Logs
|
|
docker-compose logs -f
|
|
|
|
# Status
|
|
docker-compose ps
|
|
```
|
|
|
|
---
|
|
|
|
## 🚨 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:5555/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:5555
|
|
|
|
# System Status prüfen
|
|
curl http://localhost:5555/api/system | jq '.status'
|
|
|
|
# Obsidian Sync prüfen
|
|
curl http://localhost:5555/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 | API-Call |
|
|
|-----|------|----------|
|
|
| Daily Backup | 03:00 | `POST /api/cron/backup` |
|
|
| Weekly Report | Montag 09:00 | `POST /api/cron/weekly-report` |
|
|
| Obsidian Sync Check | Alle 6h | `GET /api/obsidian/sync` |
|
|
|
|
### Cron-Jobs verwalten
|
|
```bash
|
|
# Liste
|
|
hermes cron list
|
|
|
|
# Erstellen
|
|
hermes cron create "Name" "Prompt" "Schedule"
|
|
|
|
# Manuell ausführen
|
|
hermes cron run <ID>
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 Troubleshooting
|
|
|
|
### Dashboard startet nicht
|
|
```bash
|
|
# Logs prüfen
|
|
cd dashboard
|
|
npm run build 2>&1 | tail -20
|
|
|
|
# Port prüfen
|
|
netstat -ano | findstr :5555
|
|
|
|
# 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:5555/api/obsidian/sync \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"action":"list-sessions"}'
|
|
```
|
|
|
|
### API-Key Probleme
|
|
```bash
|
|
# Testen
|
|
curl http://localhost:5555/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:5555
|
|
- **Hermes Docs**: https://hermes-agent.nousresearch.com/docs
|
|
- **OpenRouter**: https://openrouter.ai/keys
|
|
- **Obsidian**: https://obsidian.md
|
|
|
|
---
|
|
|
|
## ⚠️ Checkliste für neuen Agenten
|
|
|
|
- [ ] Diese Datei gelesen
|
|
- [ ] Dashboard geöffnet und Login getestet
|
|
- [ ] Obsidian Vault Pfad geprüft
|
|
- [ ] API-Keys vorhanden (`.env`)
|
|
- [ ] Docker Services laufend
|
|
- [ ] 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.*
|