mehlzoerwer/mesh-configs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial: Mesh-Skills, Configs, Scripts

Browse Source
This commit is contained in:
root
2026-09-02 23:49:07 +02:00
commit 26c7980750
783 changed files with 145393 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/devops/coros-mcp-integration/SKILL.md
+78
View File
@@ -0,0 +1,78 @@
---
name: coros-mcp-integration
description: "Use when: COROS-Sportuhr-Daten in PersoEnt anbinden."
version: 1.0.0
author: mehlzoerwer
platforms: [linux]
models:
default: mimo-v2-flash
license: MIT
related_skills: [content-creator, pocketbase-deployment]
---
# COROS-MCP — Sportuhr-Daten in PersoEnt
Nutze diesen Skill, wenn PersoEnt (oder ein anderes Projekt) **echte COROS-Sportuhr-Gesundheitsdaten** anbinden soll: Schlaf, HRV, Stress, Ruhe-Herzfrequenz, Training, Erholung, VO2max.
## Status (2026-08-10)
- **Installiert** global: `npm install -g coros-mcp` (OFFIZIELLES Paket von `coros_openplatform`, ~0.1.1)
- **Eingeloggt** — Token gecacht in `/root/.coros-mcp-skill-gateway-ts/<region>/token.json`
- **22 MCP-Tools** verfügbar, Endpoint `mcp.coros.com` (Europa: `mcpeu.coros.com`)
## CLI-Syntax (WICHTIG — Flags, nicht Positional)
Das Paket nutzt Flags, NICHT Positionsargumente:
```bash
coros-mcp list-tools # alle Tools + Schema
coros-mcp describe-tool --tool <NAME> # Schema eines Tools
coros-mcp call-tool --tool <NAME> --arguments-json '{}' # Tool aufrufen
```
- `call-tool --tool X queryDailyHealthData` (ohne `--tool`) → **Fehler "unknown argument"**
- `--args '{}'` / `--name X` / `--tool` mit Positional → **alles falsch** (richtig: `--tool NAME --arguments-json JSON`)
## Login-Flow (einmalig, nur Nutzerkonto)
```bash
coros-mcp login-start # erzeugt Browser-Login-Link (mcpeu.coros.com/cli/login/...)
# Nutzer oeffnet Link + meldet sich mit COROS-Konto an
coros-mcp login-finish # bestaetigt Session -> 'login ok'
coros-mcp login-status # 'no pending login session' = sauber/fertig
```
Login-Link ist region-/sessiongebunden. Andere COROS-Region → `--issuer`/`--mcp-url` anpassen.
## Wichtigste Tools (Daten fuer PersoEnt-Gesundheitsdetektiv)
| Tool | Daten |
|------|-------|
| `queryDailyHealthData` | 7 Tage: Schritte, Kalorien, Stress, Schlaf (Tief/Leicht/REM), Schlaf-HR |
| `querySleepHrv` | taegl. HRV + Baseline + Normbereich |
| `queryRestingHeartRate` / `queryAvgHeartRate` | Ruhe-/durchschnittl. HF |
| `queryStressLevel` / `queryStressTimeSeries` | Stress (avg/roh) |
| `querySportRecords` | Workout-Protokoll (+ labelId, sportType) |
| `getActivityDetail` / `queryActivityLapData` | Activity-Details inkl. HR |
| `queryRecoveryStatus` | Erholung % + Level |
| `queryFitnessAssessmentOverview` | VO2max, Threshold-Pace |
| `querySleepData` | Schlafscore, Dauer, Stufen |
| `queryDevices` / `queryUserInfo` | Geraete / Profil |
## Integration in PersoEnt (Architektur-Vorgabe)
- **Server-seitig auf VPS** (Master): Poller ruft `coros-mcp call-tool` auf → Daten nach **PocketBase** (`health_records`-ahnliche Struktur) → PersoEnt-Dashboard/Detektiv liest von dort.
- HRV + Schlaf + Stress + Erholung = ideale **Kausal-Merkmale** fuer den Gesundheitsdetektiv (besser als Google-Health-Fit).
- Gleiche Basis-Assets (ein COROS-Konto) fuer mehrere Kanaele/Personas.
## Edge Cases
- **Daten brauchen echten Login** — ohne `login-finish` kein Token, `call-tool` schlaegt fehl.
- Zeitfenster-Tools (`queryCustomActivityLapData`) brauchen `startTimestamp`/`endTimestamp` in Unix-Sekunden.
- Sport-Records-Details brauchen `labelId` + `sportType` aus der Records-Liste.
## Verifizierte Daten-Shapes
Siehe `references/coros-mcp-data-shapes.md` — echte Antwort-Formate (queryDailyHealthData = ein String mit `--- JJJJMMTT ---`-Tag-Abschnitten, Sport-Records mit labelId/sportType), Token-Sicherheit (root-only Cache + age-Backup, NIE die Klartext-token.json verschluesseln) und der PersoEnt-Write-Hinweis (kein datum-Feld).
## 🔥 Robustes Parsen der 7-Tage-Helth-Antwort (verifiziert 2026-08-15)
`queryDailyHealthData` liefert EINEN String mit 7 `--- 20260815 ---`-Tagbloecken. Naive Extraktion (erstes "Steps" finden) ist FEHLERHAFT — es erwischt das Datum oder einen alten Tag. Robust:
- **Letzten Tages-Block nehmen**, nicht den ersten: `re.split(r'--- (\d{8}) ---', text)` → nimm das letzte (date, body)-Paar.
- **`Stress: Avg 22`** hat "Avg" zwischen Label und Zahl → Regex `re.escape(label) + r'[^\d]*?([\d.,]+)'` (Ueberspringt Zwischenwoerter).
- **Puls zuverlaessig aus `Sleep HR: Avg 51 bpm`** im Health-Block (AVG HR-Call `queryAvgHeartRate` hat anderes/leeres Block-Format — nicht darauf stuetzen).
- **Schlaf** = `Total: 7h 46min` → `(\d+)h (\d+)min` → 7.77h.
- COROS-Werte kommen mit **Tausender-Komma** (z.B. `9,304`) → `,` entfernen.
- Nach jedem Fix: **real gegen die Live-Antwort testen** (echten `call-tool`-String parsen), nie von Schema raten — Daten-Shapes weichen ab.
skills/devops/coros-mcp-integration/references/coros-mcp-backfill-parsing-pitfalls.md
+95
View File
@@ -0,0 +1,95 @@
# COROS-MCP — Historie/Backfill + Parser-Pitfalls (verifiziert 2026-08-18)
Ergänzt zu `coros-mcp-data-shapes.md`. Alle Befunde sind reale `call-tool`-Antworten, nicht geraten.
## Health-Historie: days-Parameter + Server-Limit
`queryDailyHealthData` akzeptiert im Schema einen `days`-Parameter (integer, default 7).
```bash
coros-mcp call-tool --tool queryDailyHealthData --arguments-json '{"days":30}'
coros-mcp call-tool --tool queryDailyHealthData --arguments-json '{"days":365}'
```
**WICHTIG (verifiziert 2026-08-18):** Egal ob `days:30`, `days:90` oder `days:365` — die COROS-API liefert **maximal ~53 Health-Tage** zurück (z.B. nur `2026-05-16 .. 2026-08-15`, 53 Blöcke). Das ist ein **SERVER-Limit von COROS**, kein Parser- oder Client-Fehler. Mehr Health-Historie gibt es über diese API nicht; für längere Geschichte bleibt nur der Sport/FIT-Pfad.
Auch bei "alles was geht" lohnt kein Versuch über 53 hinaus zu holen — wiederhole `sportBackfill` dafür nicht.
## Sport-Historie: querySportRecords mit Datumsbereich
`querySportRecords` akzeptiert (anders als Health) **`startDate`/`endDate` im Format `yyyyMMdd`** (kein `days`) und `sportTypeCodes`-Array:
```bash
coros-mcp call-tool --tool querySportRecords --arguments-json \
'{"startDate":"20250501","endDate":"20260815","sportTypeCodes":[65535]}'
```
- `sportTypeCodes: [65535]` = alle Sportarten (sonst numerische Codes, nie Namen).
- **Sport-Historie reicht deutlich weiter zurück als Health** (1 Jahr+). 20 Records über 15 Monate bestätigt.
- Antwort enthält je Workout: `N. <Sportart> — YYYY-MM-DD`, `Time Window: startTimestamp=.. | endTimestamp=..`, `Duration`, `Avg HR: <n> bpm`, `Calories: <n> kcal`, `Distance: <x> km`, `LabelId: <Zahl>`, `SportType: <code>`.
## 🔥 PITFALL: COROS-`content[0].text` enthält LITERALES `\n`, KEINE echten Newlines
(Wichtigster Fund — ohne Normalisierung matcht **nichts**.)
`querySportRecords` (und teils andere) liefern im Text **literale 2-Zeichen-Sequenz `\n` (ein Backslash + n)**, keine echten Zeilenumbrüche. `splitlines()` / `repr()` in einem Launch zeigen das nicht zuverlässig.
**Debug-Befund (2026-08-18):**
```python
text = d['content'][0]['text']
'\n' in text # False (kein echter Newline)
'\\n' in text # True (literales Backslash-n vorhanden)
```
**Fix — normalisiere VOR jedem Zeilen-Parsing:**
```python
text = text.replace('\\n', '\n')
lines = text.splitlines() # erst jetzt funktioniert splitlines()
```
Übersehen → alle Regex gegen `splitlines()` finden 0 Zeilen (kein Fehler, nur 0 Treffer). Achte auf die richtige Backslash-Tiefe: Ersetze das **1-Backslash-`\n`-Literal**, nicht doppel.
## ⏱️ Dauer-Format ist uneinheitlich: HH:MM:SS vs MM:SS vs SS
COROS-`Duration:`-Werte kommen **gemischt**:
- `1:00:14` → 1h = **60 min** (3 Segmente)
- `2:03:36` → 2h03m = **123 min** (3 Segmente)
- `51:35` → **51 min** (2 Segmente — NICHT 51std35!)
- `0:22` → 22 Sek → 0 min (2 Segmente)
**Fehlerhafte Regex** `(\d+):(\d+)(?::(\d+))?` macht `51:35` fälschlich zu `51*60+35 = 3095 min` (absurd 63h). **Robust:**
```python
m = re.search(r'Duration:\s*([\d:]+)', block)
seg = [int(x) for x in m.group(1).split(':')]
if len(seg) == 3: # HH:MM:SS
dauer_min = seg[0]*60 + seg[1]
elif len(seg) == 2: # MM:SS
dauer_min = seg[0]
else: # SS
dauer_min = seg[0] // 60
```
## Sport-Daten → SEPARATE Tabelle (nicht health_records)
Ein Tag kann **mehrere Workouts** haben → passt NICHT in `health_records` (1 Zeile/Tag). Eigene Tabelle:
```sql
CREATE TABLE IF NOT EXISTS sport_records (
label_id TEXT PRIMARY KEY, -- COROS-LabelId je Workout (natürlicher PK)
datum TEXT NOT NULL, -- yyyyMMdd
sportart TEXT NOT NULL,
sport_type_code INTEGER, -- COROS SportType-Code
dauer_min INTEGER,
avg_hr INTEGER,
kalorien INTEGER,
distanz_km REAL,
created_at TEXT DEFAULT (datetime('now'))
);
CREATE INDEX IF NOT EXISTS idx_sport_datum ON sport_records(datum);
```
**Idempotent:** `INSERT OR IGNORE ... ON CONFLICT(label_id) DO NOTHING` — Workouts sind nach Import unveränderlich, kein UPDATE nötig. (Direkter DB-Write, da `health_records`-API createRule leer = nur Superuser schreibt; siehe `pocketbase-deployment`.)
## Reihenfolge bei Backfill in bestehende DB
1. Wenn schon fehlerhafte Records mit dem alten Dauer-Parser geschrieben wurden → Flushing die Tabelle (`DELETE FROM sport_records`) oder per label_id neu überschreiben, DANN Neu-Load mit korrektem Parser.
2. Immer vorher DB-Backup (Backup-Regel): `cp /opt/pocketbase/pb_data/data.db data.db.bak-<ts>`.
skills/devops/coros-mcp-integration/references/coros-mcp-data-shapes.md
+51
View File
@@ -0,0 +1,51 @@
# COROS-MCP — verifizierte Tool-Calls + Daten-Shapes (2026-08-15)
Proof-of-Concept mit echtem Login, alle Werte real. Endpoint Europa `mcpeu.coros.com`, Token-Cache `/root/.coros-mcp-skill-gateway-ts/<region>/token.json`.
## Zugriffshinweis (Token-Sicherheit, Team-Auflage)
- Token-Datei root-only (`chmod 600`), Cache `chmod 700`.
- Zusaetzlich age-verschluesseltes Backup: `age-keygen -o /root/.coros-age-key.txt; age -r <PUBKEY> -o /root/.coros-token.json.age <token.json>`.
- WICHTIG: **NICHT die Klartext-`token.json` verschluesseln/ersetzen** — die `coros-mcp`-CLI LIESST sie selbst (Klartext nötig fuer den Betrieb). Verschluesselung nur als SEPARATE Sicherungskopie ablegen.
## Korrekte Aufruf-Syntax (verifiziert)
```bash
# Achtung: Flags! Nicht positional. KEIN --args/--name/--tool-positional.
coros-mcp list-tools
coros-mcp describe-tool --tool queryDailyHealthData
coros-mcp call-tool --tool queryDailyHealthData --arguments-json '{}'
```
## Echte Ergebnis-Shapes (Anhaltspunkt fuer Parser)
### queryDailyHealthData ({} args) — Text, 7 Tage
```
"Daily Health Data — Last 7 days | Resting HR: 52 bpm | HRV Baseline: 42 ms
--- 20260815 ---
Steps: 981 | Calories: 47 kcal | Exercise: 0 min
Stress: Avg 22
Sleep Summary:
Total: 7h 46min | Deep: 1h 57min | Light: 4h 17min | REM: 1h 23min | Awake: 9 min
```
Antwort-Container: `{"content":[{"type":"text","text":"<string>"}],"isError":false}` — **Daten sind EIN String**, mit `\n`-Zeilen, pro Tag Abschnitt `--- JJJJMMTT ---`. Parser: nach Datums-Marker + Label splitten.
### querySportRecords ({}) — 1+ Records
```
"Sport Records — DATE to DATE (N records)
1. Indoor Cycling — 2026-08-11
Location: Indoor Rad
Time Window: startTimestamp=1786472136 | endTimestamp=1786475750
Duration: 1:00:14 | Avg HR: 114 bpm | Calories: 629 kcal
LabelId: 479635354870120452 | SportType: 201"
```
Sauber parsebar via Regex auf `LabelId:` + `SportType:` (fuer Activity-Details noetig).
### querySleepHrv ({}), queryRecoveryStatus ({}), queryFitnessAssessmentOverview ({})
- HRV: pro Tag `HRV Avg: 55 ms — Normal`, `Baseline: 61 ms`
- Recovery: `Recovery: 100%`, `Level: Heavy training allowed`
- Fitness: `Threshold Pace: 4:45 /km`
### queryUserInfo ({})
`Height: 173.0 cm | Weight: 100.6 kg | Birthday: 1972-02-21 (Age: 54) | Gender: Male | Nickname: Thorsten`
## PersoEnt-Write-Hinweis (strukturierte Gesundheitsdaten)
COROS liefert KEIN Datums-Feld in der Antwort — das Datum steckt im `--- JJJJMMTT ---`-Marker. PersoEnt `health_records`-Collection hat KEIN `datum`-Feld; Datum geht verloren, wenn man es nicht als String in einem Text-Feld oder via Record-`created` abbildet. (siehe pocketbase-deployment: leere createRule → Superuser-Token noetig.)
skills/devops/gtfs-timetable-routing/SKILL.md
+57
View File
@@ -0,0 +1,57 @@
---
name: gtfs-timetable-routing
description: "Use when: echte Zugfahrzeiten (Nahverkehr) braucht."
version: 1.0.0
author: mehlzoerwer
platforms: [linux]
models:
default: mimo-v2-flash
related_skills: [web-hosting-deployment, pocketbase-deployment]
license: MIT
---
# 🚂 GTFS-Timetable-Routing — echte Zugverbindungen aus Fahrplandaten
## When to Use
Nutze diesen Skill, wenn **echte, verlässliche Nahverkehrs-Fahrzeiten** (von→nach per Regional-/S-Bahn, kein ICE) benötigt werden — z.B. für eine Zugverbindungs-Webseite, Produkt-Planung oder Fahrzeit-Angaben. **Kein** Luftlinien-Raten, **kein** Erfinden von Zeiten.
**Anlass (Nutzer-Korrektur):** Die Urlaub-Webseite (urlaub.perfekt-ohne-en.de) zeigte Fahrzeiten aus Luftlinien-Schätzung — komplett falsch (2. Ebene halbe Zeit, bis 3× daneben). Der Nutzer verlangte reale Zeiten (max ~1h daneben). Lösung: GTFS-Fahrplandatei lokal verarbeiten.
## Die harte Wahrheit: öffentliche Fahrplan-APIs sind zu
Bevor Zeit mit Scraping/APIs verbrannt wird — getestet (2026-08), alle scheitern programmatisch:
| Quelle | Ergebnis |
|--------|----------|
| DB-API / bahn.de | Bot-Block / OPS_BLOCKED / 403 |
| api.transport.rest | DNS/000 |
| transport.rest v6 | 503 |
| reiseauskunft.de | toter Pfad |
| VRR-EFA (efa.vrr.de V2) | 405 (nginx blockt GET+POST) |
| WebSearch-Tool | nicht konfiguriert (Firecrawl-Key fehlt) |
**Verlässlicher Weg = eine GTFS-Datei** (Regional+S-Bahn, kein ICE ist ideal: genau Deutschlandticket-Nahverkehr). Datei lokal in SQLite → Dijkstra-Router → echte Zeiten. Kosten 0 $, schnell (<1s/Verbindung nach Build).
## Arbeitsablauf
1. **GTFS-Datei beschaffen.** Nutzer liefert `.zip` (z.B. `r.und.s.bahnen.zip`, „ohne ICE/IC"). Enthält `stops.txt`, `trips.txt`, `stop_times.txt`, `calendar*.txt`, `routes.txt`. Aus /user-cache-Dokument-Pfad kopieren.
2. **Extrahieren + in SQLite laden** (`scripts/build_gtfs_db.py`). 3 Tabellen: `stops(stop_id,stop_name,lat,lon)`, `trips(trip_id,route_id,service_id)`, `st(stop_id,trip_id,seq,arr,dep)` + Indizes auf st(stop_id), st(trip_id), st(trip_id,seq).
3. **Router bauen/ausführen** (`scripts/gtfs_suche.py`, zeitbasierter Dijkstra): vorladen `deps_by_stop` und `stops_by_trip`, dann Dijkstra mit `dist[stop]=beste Ankunft` + Ziel-Abbruch.
4. **Verifizieren** gegen eine bekannte echte Strecke (z.B. Aachen Hbf→Köln Hbf ≈ 1h 12min, 1 Umstieg). Wenn plausibel → alle Ziele neu berechnen.
5. **Website/DB aktualisieren** mit den echten Zeiten (nicht erfinden).
## ⚠️ Kritische Pitfalls (alle beim echten Lauf getroffen)
1. **stops.txt-Spaltenreihenfolge** ist `stop_name, parent_station, stop_id, stop_lat, stop_lon, ...` — **stop_id ist Spalte 2, NICHT Spalte 0**; `parent_station` ist Spalte 1 (echte Gruppen-ID). Bei falschem Mapping kommen Stops mit leeren IDs / falschen Namen.
2. **trips.txt-Header** ist `route_id, service_id, trip_id` — trip_id ist Spalte 2. Import NICHT an Spalte 0 hängen.
3. **Bahnhof hat mehrere stop_ids** (z.B. Köln Hbf = 222681 UND 452576), aber nur **eine ist aktiv in stop_times**. `stops.txt`-ID ≠ notwendigerweise `stop_times`-ID. → Beim Auflösen: die ID wählen, die `COUNT(*) IN st > 0` hat.
4. **`st`-Tabelle kann mehr eindeutige trips enthalten als `trips.txt`** (110k vs 964 war ok — `st` ist Wahrheit). Zähler-Ausgaben prüfen, nicht dem trips.txt-Import trauen.
5. **Zeit-Parser**: HH:MM und HH:MM:SS tolerant parsen (`split(":")`, defaults).
6. **Dijkstra-Effizienz**: Bei vielen Trips (110k) explodiert naive Expansion → nutze `dist[stop]` + Ziel-Abbruch + `visited`. Erst nach Effizienz-Fix: Aachen→Köln in Sekunden statt Hänger.
## Bauen
Die Referenzdatei `references/gtfs-build-notes.md` enthält Schema + Dijkstra-Kern + SQL. Die Skripte `scripts/build_gtfs_db.py` und `scripts/gtfs_suche.py` sind direkt ausführbar (Fahrzeit von→nach, `<von_stop_id> <nach_stop_id> [HH:MM]`).
**Verwandt:** Bei PocketBase als Ziel echte Zeiten in DB schreiben → `pocketbase-deployment` (Schema + Filter-Quirks). Bei Web-Frontend-Einbindung → `web-hosting-deployment`.
skills/devops/gtfs-timetable-routing/references/gtfs-build-notes.md
+80
View File
@@ -0,0 +1,80 @@
# GTFS-Build-Notizen (aus echtem Lauf 2026-08, Urlaub-Webseite)
Konkrete SQL/Schema/Logik, die in dieser Session verifiziert funktioniert haben.
## SQLite-Schema (eine DB, 3 Tabellen + Indizes)
```sql
CREATE TABLE stops(stop_id TEXT PRIMARY KEY, stop_name TEXT, stop_lat REAL, stop_lon REAL);
CREATE TABLE trips(trip_id TEXT PRIMARY KEY, route_id TEXT, service_id TEXT);
CREATE TABLE st(stop_id TEXT, trip_id TEXT, seq INT, arr TEXT, dep TEXT);
CREATE INDEX idx_st_stop ON st(stop_id);
CREATE INDEX idx_st_trip ON st(trip_id);
CREATE INDEX idx_st_seq ON st(trip_id, seq);
```
Echte Mengen aus `r.und.s.bahnen.zip` (Regional+S-Bahn, kein ICE):
- stops.txt: 16.310 Haltestellen → DB 15.083 (dedupliziert)
- trips.txt: 110.087 Rohzeilen → DB 964 (trips.txt hat nur selten-service; st ist die Wahrheit)
- stop_times.txt: 82 MB → st 1.591.002 Zeilen, 110.087 eindeutige trip_id, 8.558 eindeutige stop_id
## Spaltenreihenfolgen (GTFS ist NICHT standardisiert was Namen angeht — Header lesen!)
- **stops.txt:** `stop_name, parent_station, stop_id, stop_lat, stop_lon, location_type, platform_code`
→ stop_id = Spalte 2; parent_station = Spalte 1 (Gruppen-ID). Viele Stops haben leeres parent_station.
Import-Fallback: `sid = p[2] if p[2] else p[1]` (bevorzugt stop_id, sonst parent_station).
- **trips.txt:** `route_id, service_id, trip_id` → trip_id = Spalte 2.
- **stop_times.txt:** `trip_id, arrival_time, departure_time, stop_id, stop_sequence, ...`
→ stop_id = Spalte 3, arr = 1, dep = 2, seq = 4.
## Bahnhofs-Alias (kritisch)
Ein Bahnhof kann mehrere stop_id-Zeilen haben (z.B. `Köln Hbf` = 222681 UND 452576). Nur EINE ist in
`stop_times` aktiv. Suche-Methode:
```sql
-- aktive ID ermitteln
SELECT stop_id, stop_name FROM stops WHERE stop_name = '<Name>';
-- dann je Kandidat:
SELECT COUNT(*) FROM st WHERE stop_id = '<id>'; -- >0 => aktiv
```
Beispiel: Aachen Hbf → 548582 (aktiv), Köln Hbf → 452576 (aktiv; 222681 tot). Saarbrücken Hbf hat 10 IDs, davon 9 aktiv.
## Zeit-basierter Dijkstra (Kern)
Vorladen (einmal):
```python
from collections import defaultdict
deps_by_stop = defaultdict(list) # stop_id -> [(dep_sec, trip_id, seq)] sortiert
stops_by_trip = defaultdict(list) # trip_id -> [(seq, stop_id, arr_sec, dep_sec)] sortiert
# Befülle beide in einem Durchlauf über st; sortiere jede Liste.
```
Suche:
```python
INF = float('inf')
dist = defaultdict(lambda: INF); dist[von_id] = dep0
heap = [(dep0, von_id)]
while heap:
t, stop = heapq.heappop(heap)
if t != dist[stop]: continue
if stop == nach_id: break
for dep_s, tid, seq in deps_by_stop[stop]:
if dep_s < t: continue
for (sseq, sid, arr_s, dep2) in stops_by_trip[tid]:
if sseq <= seq: continue
if arr_s < dist[sid]:
dist[sid] = arr_s; heapq.heappush(heap, (arr_s, sid))
# Ziel-Abbruch + dist[stop]-Guard sind ESSENZIELL für 110k Trips.
```
## Verifikations-Referenz (echte GTFS-Ergebnisse 2026-08)
- Aachen Hbf → Köln Hbf: **1h 12min, 1 Umstieg, 09:00 → 10:12** ✅ (real plausibel)
- Trier Hbf → Saarbrücken Hbf: nur direkt via trips, keine aktiven stops-Zuordnung nötig
## Wichtige Erkenntnis zur Datenlage
Diese GTFS („R- und S-Bahnen") deckt Bahn-Knoten ab, aber **nicht alle**: Remscheid-Lennep Bf und
Frankfurt (Main) Hauptbahnhof hatten in der `st`-Tabelle 0 aktive Trips → müssen per Alias oder
Alternativ-Bahnhof (nächster aktiver) aufgelöst werden, oder liegen außerhalb des Feeds. Vor dem
Neuberechnen ALLER Ziele: prüfen welche Kern-Bahnhöfe aktiv sind, fehlende via Nachbar-Bahnhof mappen.
skills/devops/gtfs-timetable-routing/references/gtfs-recalc-lessons.md
+39
View File
@@ -0,0 +1,39 @@
# GTFS-Neuberechnung — harte Lehren aus urlaub.perfekt-ohne-en.de (2026-08-19)
Ergänzung zum main SKILL.md. Diese Notes stammen aus dem echten Großumbau der
Fahrzeiten auf der Zugverbindungs-Webseite und sind die Dinge, die NICHT sofort
ersichtlich sind. (Haupt-SKILL.md-Patch war durch eine Schreib-Sperre blockiert;
diese Erkenntnisse gehören trotzdem zu diesem Umbrella.)
## Die 3 Teambefunde, die den Dijkstra erst korrekt machten
1. **Geo-Stop-Merging** — Ein Bahnhof hat MEHRERE aktive stop_ids in der st-Tabelle
(Saarbrücken Hbf: 6 IDs = Plattform-/Gleis-Stops). `stops.txt` stop_id ist nicht
eindeutig. Fix: Stops < ~350m Luftlinie zu einer Gruppe zusammenfassen; der Router
expandiert von/zu allen Gruppen-IDs.
2. **Umstiegsbuffer** — Ohne min ~4min Transfer-Puffer erlaubt Dijkstra physisch
unmögliche Anschlüsse (Ankunft 10:05 → Abfahrt 10:04) → zu optimistische Zeiten.
Buffer NUR beim Umstieg, nicht beim Start: `dep_s < t + (BUFFER if t>dep0 else 0)`.
3. **Profil-Query (Min)** — Feste Abfahrtszeit (09:00) liefert systematisch zu
langsame Werte, wenn die früheste Verbindung zufällig viele Umstiege hat.
Abfahrten über den Tag scannen (z.B. stündlich 06-22) und MIN(Fahrzeit) nehmen.
## Performance: EIN Dijkstra je Start statt je Verbindung
- Naiv: 12.201 Verbindungen × ~17 Abfahrtsstichproben = ~207k Dijkstra-Läufe → ~18h.
- Korrekt: EIN Dijkstra je eindeutigen Start (191 Starts), der ALLE Ziele gleichzeitig
erreicht (`spread(start_ids)` → dict stop→ankunft). Danach Werte ablesen → ~10 Min.
- Commit NUR am Ende, und nur markierte Ziele (0.0h / mehrdeutig) neu verteilen.
## Start ohne Bahnhof (z.B. Radevormwald)
Städte ohne eigene Bahnhofs-ID matchen in stops nicht. Löse über den nächstgelegenen
Bahnhof (Radevormwald → Remscheid-Lennep Bf) und addiere die Bus-Anreise (~20min):
`Gesamtzeit = BUS_MIN + Dijkstra(Bahnhof → Ziel)`.
## Ziel-Eindeutigkeit: Berlin-Falle
Mehrdeutige Zielnamen (z.B. "Berlin") matchen falsche/lokalnahe Stops → ungenaue
oder sogar 0.0h-Zeiten. Abbilden auf eindeutiges "… Hbf":
`UPDATE verkehr SET nach='Berlin Hbf' WHERE nach='Berlin';`
0.0h-Zeilen sind als Fehler zu behandeln und neu zu berechnen, nicht zu akzeptieren.
skills/devops/gtfs-timetable-routing/scripts/build_gtfs_db.py
+64
View File
@@ -0,0 +1,64 @@
#!/usr/bin/env python3
"""build_gtfs_db.py — GTFS-Datei in SQLite laden (einmalig).
Aufruf: python3 build_gtfs_db.py <gtfs_zip> <out_db> [gtfs_dir]
Legt Tabellen stops/trips/st an (Schema siehe gtfs-timetable-routing/references).
"""
import zipfile, sqlite3, os, sys, time
def main():
gtfs_zip = sys.argv[1]
out_db = sys.argv[2]
work = sys.argv[3] if len(sys.argv) > 3 else "/tmp/gtfs_x"
os.makedirs(work, exist_ok=True)
# extrahieren
with zipfile.ZipFile(gtfs_zip) as z:
z.extractall(work)
t0 = time.time()
con = sqlite3.connect(out_db)
con.execute("PRAGMA journal_mode=MEMORY"); con.execute("PRAGMA temp_store=MEMORY")
con.executescript("""
CREATE TABLE stops(stop_id TEXT PRIMARY KEY, stop_name TEXT, stop_lat REAL, stop_lon REAL);
CREATE TABLE trips(trip_id TEXT PRIMARY KEY, route_id TEXT, service_id TEXT);
CREATE TABLE st(stop_id TEXT, trip_id TEXT, seq INT, arr TEXT, dep TEXT);
CREATE INDEX idx_st_stop ON st(stop_id);
CREATE INDEX idx_st_trip ON st(trip_id);
CREATE INDEX idx_st_seq ON st(trip_id, seq);
""")
# stops.txt: stop_name,parent_station,stop_id,stop_lat,stop_lon,...
n=0
with open(f"{work}/stops.txt", encoding="utf-8") as f:
f.readline()
for line in f:
p = line.strip().split(",")
if len(p) >= 5 and p[3] and p[4]:
sid = p[2] if p[2] else p[1] # bevorzugt stop_id, fallback parent_station
con.execute("INSERT OR IGNORE INTO stops VALUES(?,?,?,?)", (sid, p[0], p[3], p[4]))
n += 1
print("stops:", n)
# trips.txt: route_id,service_id,trip_id
n=0
with open(f"{work}/trips.txt", encoding="utf-8") as f:
f.readline()
for line in f:
p = line.strip().split(",")
if len(p) >= 3 and p[0]:
con.execute("INSERT OR IGNORE INTO trips VALUES(?,?,?)", (p[2], p[0], p[1]))
n += 1
print("trips:", n)
# stop_times.txt: trip_id,arrival_time,departure_time,stop_id,stop_sequence,...
n=0; batch=[]
with open(f"{work}/stop_times.txt", encoding="utf-8") as f:
f.readline()
for line in f:
p = line.strip().split(",")
if len(p) >= 5 and p[0] and p[3]:
batch.append((p[3], p[0], int(p[4]) if p[4].isdigit() else 0, p[1], p[2]))
if len(batch) >= 50000:
con.executemany("INSERT INTO st VALUES(?,?,?,?,?)", batch); n += len(batch); batch = []
if batch:
con.executemany("INSERT INTO st VALUES(?,?,?,?,?)", batch); n += len(batch)
con.commit(); con.close()
print("stop_times:", n, "| DB gebaut in %.1fs" % (time.time()-t0))
if __name__ == "__main__":
main()
skills/devops/gtfs-timetable-routing/scripts/gtfs_suche.py
+74
View File
@@ -0,0 +1,74 @@
#!/usr/bin/env python3
"""gtfs_suche.py — echte schnellste Nahverkehrs-Verbindung aus GTFS-SQLite (zeitbasierter Dijkstra).
Aufruf: python3 gtfs_suche.py <von_stop_id> <nach_stop_id> [HH:MM]
Vorraussetzung: DB aus build_gtfs_db.py. Aktiv-ID-Regel: wenn ein Bahnhof mehrere IDs hat,
die mit COUNT(*)>0 in st nehmen.
"""
import sqlite3, sys, heapq
from collections import defaultdict
DB = "/tmp/gtfs_rt.db"
def to_sec(t):
p = t.split(":")
h = int(p[0]); m = int(p[1]) if len(p) > 1 else 0
return h*3600 + m*60
def fmt(t):
return f"{t//3600:02d}:{(t%3600)//60:02d}"
def aktive_id(con, stop_name):
"""Findet die stop_id mit st-Vorkommen (Bahnhof kann mehrere IDs haben)."""
cands = con.execute("SELECT stop_id FROM stops WHERE stop_name=?", (stop_name,)).fetchall()
for (sid,) in cands:
if con.execute("SELECT COUNT(*) FROM st WHERE stop_id=?", (sid,)).fetchone()[0] > 0:
return sid
return None
def verbinde(von_id, nach_id, start="09:00"):
con = sqlite3.connect(DB)
con.row_factory = sqlite3.Row
dep0 = to_sec(start)
deps_by_stop = defaultdict(list); stops_by_trip = defaultdict(list)
for r in con.execute("SELECT trip_id, stop_id, seq, arr, dep FROM st"):
deps_by_stop[r["stop_id"]].append((to_sec(r["dep"]), r["trip_id"], r["seq"]))
stops_by_trip[r["trip_id"]].append((r["seq"], r["stop_id"], to_sec(r["arr"]), to_sec(r["dep"])))
con.close()
for k in deps_by_stop: deps_by_stop[k].sort()
for k in stops_by_trip: stops_by_trip[k].sort()
INF = float('inf')
dist = defaultdict(lambda: INF); dist[von_id] = dep0
heap = [(dep0, von_id)]
pred = {}
while heap:
t, stop = heapq.heappop(heap)
if t != dist[stop]: continue
if stop == nach_id: break
for dep_s, tid, seq in deps_by_stop[stop]:
if dep_s < t: continue
for (sseq, sid, arr_s, dep2) in stops_by_trip[tid]:
if sseq <= seq: continue
if arr_s < dist[sid]:
dist[sid] = arr_s; pred[sid] = (tid, stop)
heapq.heappush(heap, (arr_s, sid))
if nach_id not in pred and nach_id != von_id:
return None
if nach_id == von_id:
return (0, [], 0, fmt(dep0), fmt(dep0))
trips = []; cur = nach_id
while cur in pred and cur != von_id:
tid, prev = pred[cur]; trips.append(tid); cur = prev
trips.reverse()
dur = dist[nach_id] - dep0
return (dur, trips, len(set(trips)), fmt(dep0), fmt(dist[nach_id]))
if __name__ == "__main__":
von = sys.argv[1]; nach = sys.argv[2]
start = sys.argv[3] if len(sys.argv) > 3 else "09:00"
r = verbinde(von, nach, start)
if r:
dur, trips, umst, dep, arr = r
print(f"{dur//3600}h {(dur%3600)//60:02d}min | {dep}->{arr} | {umst} Umstieg(e)")
else:
print("Keine Verbindung")
skills/devops/hermes-fleet-maintenance/SKILL.md
+70
View File
@@ -0,0 +1,70 @@
---
name: hermes-fleet-maintenance
description: "Update/maintain Hermes agents in the mesh (weekly sync)."
version: 1.0.0
author: Hermes Agent
platforms: [linux]
related_skills: [multi-agent-mesh, hermes-agent]
---
# Hermes-Fleet-Maintenance
Wöchentliche bzw. bei Bedarf ad-hoc Wartung ALLER Hermes-Agenten im Mesh (VPS/Master + Unraid + Switch + Laptop) auf denselben Stand bringen. Ergänzt `multi-agent-mesh` (Orchestrierung) um den konkreten **Update-Ablauf und den Cadence-Entscheid**.
## Entscheid (NUTZERWUNSCH 2026-08-06)
- **Wöchentlich** (Montag) alle Agenten synchron updaten — NICHT täglich (Overhead 7×, kein Gewinn).
- 🔥 **Sicherheits-Hotfixes** (SSH, Auth, Keys, ZeroTier) SOFORT ziehen, keine Wochen-Frist.
- Vor dem Durchziehen Changelog kurz auf **Breaking-Changes** prüfen.
- Sync-Rhythmus hält das Mesh kompatibel (keine Versions-Drift zwischen Agenten).
- Agenten updaten **nur** auf Anweisung des Masters (passt zu multi-agent-mesh Update-Kontrollpolitik).
## Ablauf: Versions-Check + Update
### 1. Ist-Stand erfassen
Alle vier parallel abfragen (pro Agent tauschen IP/Name):
```bash
# Master lokal:
hermes --version | head -1
# Remotes (Passwort-Auth — Key-Auth ist im Mesh NICHT eingerichtet):
sshpass -p 'PW' ssh -o ConnectTimeout=8 -o StrictHostKeyChecking=no mehlzoerwer@<ZT-IP> \
'~/.local/bin/hermes --version 2>/dev/null | head -1; ~/.local/bin/hermes update --check 2>&1 | tail -2'
```
Notizen:
- Hermes liegt auf ALLEN Remotes unter `~/.local/bin/hermes` (nicht `/usr/local/bin`).
- `hermes update --check` antwortet `⚕ Update available` oder `✓ Already up to date`.
- **Key-Auth (BatchMode) schlägt fehl → `Permission denied (publickey,password)`.** Immer Passwort via `sshpass` nutzen (Passwort ist im Mesh einheitlich).
### 2. Update durchziehen (parallel, `--yes`)
`--yes` überspringt interaktive Prompts (Config-Migration/Stash) — nötig für non-interaktives SSH.
```bash
# Master lokal:
hermes update --yes 2>&1 | tail -15
# Je Remote:
timeout 240 sshpass -p 'PW' ssh -o ConnectTimeout=10 -o StrictHostKeyChecking=no mehlzoerwer@<ZT-IP> \
'~/.local/bin/hermes update --yes 2>&1' 2>&1 | grep -vi warning | tail -8
```
Erfolgsmarker: `✓ Update complete!` und `✓ Configuration is up to date`. (3 Hosts parallel + Master = ~30-60s.)
### 3. Verifizieren
`hermes --version` auf allen 4 erneut — Ziel: identische Version (z.B. `v0.20.0`). Differenz = Versions-Drift → nachziehen.
## Automatisierung: Wochen-Watchdog (no_agent + Telegram)
Bewährtes Muster für den Montags-Rhythmus: **ein re-runnable Script** + **`no_agent`-Cron** (kein LLM-Tokenverbrauch), das sich nur meldet wenn etwas zu tun/melden war.
- Script im Repo: `scripts/update_fleet.sh` (fertiges Vorlage-Script — Werte: IPs, `PW`, Pfad anpassen).
- Cron: `no_agent=true` (Script-STDOUT = Nachricht), `deliver=telegram`, z.B. `0 6 * * 1`.
- **Silent-Watchdog-Semantik:** leeres STDOUT = still (nichts senden); nicht-leer = Nachricht an Nutzer.
## ⚠️ Fallstricke
- **Cron `script`-Pfad MUSS relativ zu `~/.hermes/scripts/` sein** — nur den Dateinamen angeben (`update_fleet.sh`), nicht `/root/.hermes/scripts/...` → sonst Fehler `Script path must be relative to ~/.hermes/scripts/`. Script dort ablegen + `chmod +x`.
- Cron **immer erst manuell testen** (`/root/.hermes/scripts/update_fleet.sh`) bevor man ihn plant.
- `hermes update` **killt laufende Agenten/Gateway** — nicht mitten in kritischer Arbeit auf dem Ziel-Host ziehen.
- Ausgabe mit `grep -vi warning` bereinigen — sshpass-Meldungen (Warnung vor Passwort auf Kommandozeile) sind Lärm.
- `timeout` vorbehalten, falls ein Remote hängt — verhindert dass ein Host den ganzen Batch blockiert.
skills/devops/hermes-fleet-maintenance/scripts/update_fleet.sh
+44
View File
@@ -0,0 +1,44 @@
#!/usr/bin/env bash
# Woechentliches Mesh-Hermes-Update: alle Agenten synchron updaten + verifizieren.
# no_agent cron watchdog: stdout = Nachricht an Nutzer; leere Ausgabe = still.
# ANPASSEN: PW, hosts[] (IP:Name), MASTER_HERMES/REMOTE_HERMES Pfade.
set -u
SSHPASS='PW' # <<< Mesh-einheitliches Passwort eintragen
SSH=(sshpass -p "$SSHPASS" ssh -o ConnectTimeout=10 -o StrictHostKeyChecking=no)
MASTER_HERMES=/root/.local/bin/hermes
REMOTE_HERMES='~/.local/bin/hermes'
hosts=(172.24.34.142:UnraidHermes 172.24.20.26:SwitchHermes 172.24.178.202:LaptopHermes)
report=""
status_ok=1
# --- Master (lokal) ---
if [ -x "$MASTER_HERMES" ]; then
mver_before=$("$MASTER_HERMES" --version 2>/dev/null | head -1)
"$MASTER_HERMES" update --yes >/tmp/hermes_upd_master.log 2>&1
mver_after=$("$MASTER_HERMES" --version 2>/dev/null | head -1)
report+="Master: ${mver_before##*v} -> ${mver_after##*v}\n"
[ "$mver_before" != "$mver_after" ] || report+=" (kein Update noetig)\n"
else
report+="Master: hermes nicht gefunden\n"; status_ok=0
fi
# --- Sub-Agenten (per SSH) ---
for entry in "${hosts[@]}"; do
ip="${entry%%:*}"; name="${entry##*:}"
out=$("${SSH[@]}" "mehlzoerwer@$ip" \
"$REMOTE_HERMES update --yes 2>&1 | tail -1; $REMOTE_HERMES --version 2>/dev/null | head -1" 2>/dev/null)
if [ -n "$out" ]; then
ver=$(echo "$out" | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' | head -1)
report+="$name: $ver\n"
else
report+="$name: KEINE VERBINDUNG / FEHLER\n"; status_ok=0
fi
done
report="Hermes-Mesh Update ($(date '+%d.%m. %H:%M')):\n$report"
[ $status_ok -eq 1 ] && report+="Status: alle ok" || report+="Status: PROBLEM - bitte pruefen!"
printf '%b' "$report"
skills/devops/hermes-gateway-systemd/SKILL.md
+176
View File
@@ -0,0 +1,176 @@
---
name: hermes-gateway-systemd
description: "Troubleshoot and fix Hermes Agent Gateway systemd service issues — crash loops, working directory mismatches, permission problems, and restart blockers."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux]
metadata:
hermes:
tags: [hermes, gateway, systemd, troubleshooting, service, crash-loop]
related_skills: [hermes-agent]
---
# Hermes Gateway systemd Service Troubleshooting
This skill covers diagnosing and fixing common Hermes Gateway systemd service problems — especially the infamous crash loop caused by `WorkingDirectory` / `User` mismatches.
## Scope
- **Hermes Gateway** running as a systemd service (user or system)
- **Crash loops** (status 200/CHDIR, rapid restarts)
- **Permission issues** (config owned by root, service runs as user, or vice versa)
- **Restart blockers** (cannot run `systemctl restart` from inside gateway session)
## Quick Diagnosis
```bash
# 1. Check service status
systemctl status hermes-gateway --no-pager
# 2. View crash loop logs
journalctl -u hermes-gateway -n 30 --no-pager
# 3. Inspect service file
systemctl cat hermes-gateway
# 4. Verify config location matches service User/WorkingDirectory
ls -la /root/.hermes/config.yaml 2>/dev/null
ls -la /home/<user>/.hermes/config.yaml 2>/dev/null
```
## Common Failure: CHDIR Crash Loop
### Symptom
```
hermes-gateway.service: Changing to the requested working directory failed: No such file or directory
hermes-gateway.service: Main process exited, code=exited, status=200/CHDIR
Restart counter increments every 5 seconds (e.g., 20,000+ restarts)
```
### Root Cause
Service file specifies `User=X` and `WorkingDirectory=/home/X/.hermes` but:
- Config actually lives in `/root/.hermes` (installed as root)
- OR `/home/X/.hermes` doesn't exist
### Fix
Align `User`, `WorkingDirectory`, `HOME`, `HERMES_HOME` to where config actually lives.
**If config is in `/root/.hermes` (root install):**
```ini
User=root
Group=root
WorkingDirectory=/root/.hermes
Environment="HOME=/root"
Environment="HERMES_HOME=/root/.hermes"
```
**If config is in `/home/user/.hermes` (user install):**
```ini
User=user
Group=user
WorkingDirectory=/home/user/.hermes
Environment="HOME=/home/user"
Environment="HERMES_HOME=/home/user/.hermes"
```
Then:
```bash
systemctl daemon-reload
pkill -9 -f 'hermes_cli.main gateway run' # kill crash loop
systemctl start hermes-gateway
sleep 3
systemctl status hermes-gateway --no-pager
```
### Real-World Example (This Session)
- **Config location:** `/root/.hermes` (owned by root, installed via `hermes setup`)
- **Broken service file:** `User=mehlzoerwer`, `WorkingDirectory=/home/mehlzoerwer/.hermes` (directory didn't exist)
- **Symptom:** 20,731+ restart loop, status 200/CHDIR
- **Fix applied:** Changed service to `User=root`, `WorkingDirectory=/root/.hermes`, `HERMES_HOME=/root/.hermes`
- **Result:** Service started cleanly, Telegram connected, startup notification sent
## Blocker: Cannot Restart from Inside Gateway
### Error
```
Blocked: cannot restart or stop the gateway from inside the gateway process.
The gateway would kill this command before it could complete (SIGTERM propagates to child processes).
Run `hermes gateway restart` from a separate shell outside the running gateway.
```
### Cause
Hermes detects it's running inside its own gateway process and blocks process-termination commands to prevent self-kill.
### Workarounds
| Method | When to Use |
|--------|-------------|
| **New SSH session** | Always works — run `systemctl restart hermes-gateway` from fresh terminal |
| **`hermes gateway restart`** | If gateway is responsive (slash command in Telegram/CLI) |
| **`at` job** | `echo 'systemctl restart hermes-gateway' | at now + 1 minute` |
| **Direct PID kill from outside** | `ssh root@host 'pkill -9 -f hermes_cli.main'` |
| **tmux/screen on server** | Run commands in detached session |
### Scheduled Auto-Restart (systemd Timer) — durable pattern
To restart the gateway **on a recurring schedule** (e.g. nightly 23:59 to refresh memory/config) without manual intervention, install a pair of units **from a shell OUTSIDE the gateway**:
`/etc/systemd/system/hermes-gateway-restart.service`:
```ini
[Unit]
Description=Naechtlicher Hermes-Gateway-Neustart
[Service]
Type=oneshot
ExecStart=/bin/systemctl restart hermes-gateway.service
TimeoutStartSec=60
```
`/etc/systemd/system/hermes-gateway-restart.timer`:
```ini
[Unit]
Description=Startet Hermes-Gateway taeglich um 23:59
[Timer]
OnCalendar=*-*-* 23:59:00
Persistent=false
RandomizedDelaySec=0
[Install]
WantedBy=timers.target
```
Install + enable:
```bash
cp restart.service restart.timer /etc/systemd/system/
systemctl daemon-reload
systemctl enable hermes-gateway-restart.timer # allowed from inside
```
**CRITICAL PITFALL:** From inside the running gateway, `systemctl daemon-reload` and
`systemctl enable <timer>` succeed, but **`systemctl start <timer>` is ALSO blocked** (the
security scanner traces the timer to the gateway-restart service and treats the activation
as a self-kill). The `enable` persists, so the timer is armed and will fire on schedule —
you only need the user to run `systemctl start hermes-gateway-restart.timer` **once** from a
normal shell. After that it fires automatically daily.
**Ordering tip (user preference):** schedule the restart AFTER the daily Doku/Archiv cron and
BEFORE the Wissensstand (knowledge-sync) job, so the fresh session has updated memory/config
before the sync runs.
### Real-World Note (This Session)
Attempting to fix the remote gateway (92.60.38.175) **from within this local Hermes gateway session** triggered the blocker. The fix required running commands directly on the remote server via SSH from a separate terminal, not from inside an active Hermes gateway process.
## Service File Templates
See `references/gateway-systemd-troubleshooting.md` for complete, ready-to-use service file templates for both root and user installs.
## Diagnostic Checklist (Run in Order)
1. `systemctl status hermes-gateway` — active? crash loop?
2. `journalctl -u hermes-gateway -n 20` — CHDIR error? Permission denied? Module not found?
3. `systemctl cat hermes-gateway` — check User, WorkingDirectory, HERMES_HOME
4. `ls -la /root/.hermes /home/user/.hermes` — which exists? Who owns it?
5. `cat /root/.hermes/config.yaml | head -5` — verify config is valid
6. Fix service file to match reality → `daemon-reload` → kill loop → restart
## Related Skills
- `hermes-agent` — main Hermes configuration skill (covers gateway setup, platforms, config)
skills/devops/hermes-gateway-systemd/references/gateway-systemd-troubleshooting.md
+201
View File
@@ -0,0 +1,201 @@
# Hermes Gateway systemd Service Troubleshooting — Reference Detail
## Common Crash Loop: "Changing to the requested working directory failed"
**Symptom:** Service restarts every 5 seconds, logs show:
```
hermes-gateway.service: Changing to the requested working directory failed: No such file or directory
hermes-gateway.service: Main process exited, code=exited, status=200/CHDIR
```
**Root Cause:** `WorkingDirectory` in service file points to a path that doesn't exist for the configured `User`.
**Typical Scenario:**
- Config lives in `/root/.hermes` (installed as root)
- Service file has `User=mehlzoerwer` and `WorkingDirectory=/home/mehlzoerwer/.hermes`
- But `/home/mehlzoerwer/.hermes` doesn't exist
**Fix:** Align `User`, `WorkingDirectory`, `HOME`, `HERMES_HOME` to where config actually lives.
```ini
# If config is in /root/.hermes:
User=root
Group=root
WorkingDirectory=/root/.hermes
Environment="HOME=/root"
Environment="HERMES_HOME=/root/.hermes"
# If config is in /home/user/.hermes:
User=user
Group=user
WorkingDirectory=/home/user/.hermes
Environment="HOME=/home/user"
Environment="HERMES_HOME=/home/user/.hermes"
```
Then:
```bash
systemctl daemon-reload
pkill -9 -f 'hermes_cli.main gateway run' # kill crash loop
systemctl start hermes-gateway
systemctl status hermes-gateway --no-pager
```
---
## Cannot Restart from Inside Gateway Session
**Problem:** Running `systemctl restart hermes-gateway` (or `pkill`/`kill`) from within an active Hermes gateway session fails with:
```text
Blocked: cannot restart or stop the gateway from inside the gateway process.
The gateway would kill this command before it could complete (SIGTERM propagates to child processes).
Run `hermes gateway restart` from a separate shell outside the running gateway.
```
**Reason:** Hermes detects it's running inside its own gateway process and blocks process termination commands to prevent self-kill.
**Workarounds:**
1. **Run commands from a separate shell** (new SSH session, tmux pane, or `at` job)
2. **Use `hermes gateway restart`** from within the gateway (if gateway is responsive)
3. **Kill via PID directly from outside**: `ssh root@host 'pkill -9 -f hermes_cli.main'`
4. **Schedule restart**: `echo 'systemctl restart hermes-gateway' | at now + 1 minute`
---
## Telegram Polling Conflict (409 Error)
**Symptom:** When starting the gateway, logs show:
```text
WARNING hermes_plugins.telegram_platform.adapter: [Telegram] Telegram polling conflict (1/5) — previous session still held open on Telegram's servers. Waiting 20s for it to expire. Error: Conflict: terminated by other getUpdates request; make sure that only one bot instance is running
INFO hermes_plugins.telegram_platform.adapter: [Telegram] Telegram polling resumed after conflict retry 1/5
```
**Cause:** A previous gateway instance (or another process) still holds an active Long Polling connection to Telegram. Telegram only allows ONE active `getUpdates` connection per bot token.
**Built-in Resolution:** Hermes Gateway (since recent versions) automatically retries up to 5 times with exponential backoff (20s, 40s, 60s, 80s, 100s). The old connection expires on Telegram's side after ~30-60 seconds of inactivity.
**When to Act:**
- If conflict persists after all 5 retries → another process is actively polling (check for duplicate gateway services, cron jobs, or manual runs)
- Fix: `pkill -9 -f 'hermes_cli.main gateway run'` then restart cleanly
**Verification:**
```bash
# Check for duplicate gateway processes
ps aux | grep 'hermes_cli.main gateway run'
# Should only show ONE process (the systemd one)
```
---
## Gateway Startup Notification
**Behavior:** On successful Telegram connection, the gateway automatically sends a startup notification to the configured `TELEGRAM_HOME_CHANNEL` (from `.env` or config).
**Log entry:**
```text
INFO gateway.run: Sent home-channel startup notification to telegram:6417835766
```
**If notification not received:**
1. Verify `TELEGRAM_HOME_CHANNEL` and `TELEGRAM_ALLOWED_USERS` in `.env` match your chat ID
2. Check bot has permission to message that chat (not blocked, not a channel without bot admin)
3. Check gateway logs for delivery errors after "Sent home-channel startup notification"
---
## Diagnostic Checklist
```bash
# 1. Check service file
systemctl cat hermes-gateway
# 2. Verify paths exist for the configured User
ls -la /home/user/.hermes # or /root/.hermes
# 3. Check current crash loop
journalctl -u hermes-gateway -n 20 --no-pager
# 4. Verify Hermes config location
cat /root/.hermes/config.yaml | head -5
# or
cat /home/user/.hermes/config.yaml | head -5
# 5. Check which user owns the config
ls -la /root/.hermes/config.yaml
ls -la /home/user/.hermes/config.yaml 2>/dev/null
```
---
## Service File Template (Root Install)
```ini
[Unit]
Description=Hermes Agent Gateway - Messaging Platform Integration
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0
[Service]
Type=simple
User=root
Group=root
ExecStart=/usr/local/lib/hermes-agent/venv/bin/python -m hermes_cli.main gateway run
WorkingDirectory=/root/.hermes
Environment="HOME=/root"
Environment="USER=root"
Environment="LOGNAME=root"
Environment="PATH=/usr/local/lib/hermes-agent/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
Environment="VIRTUAL_ENV=/usr/local/lib/hermes-agent/venv"
Environment="HERMES_HOME=/root/.hermes"
Restart=always
RestartSec=5
RestartForceExitStatus=75
KillMode=mixed
KillSignal=SIGTERM
ExecReload=/bin/kill -USR1 $MAINPID
TimeoutStopSec=210
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
```
---
## Service File Template (User Install)
```ini
[Unit]
Description=Hermes Agent Gateway - Messaging Platform Integration
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0
[Service]
Type=simple
User=<username>
Group=<username>
ExecStart=/usr/local/lib/hermes-agent/venv/bin/python -m hermes_cli.main gateway run
WorkingDirectory=/home/<username>/.hermes
Environment="HOME=/home/<username>"
Environment="USER=<username>"
Environment="LOGNAME=<username>"
Environment="PATH=/usr/local/lib/hermes-agent/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
Environment="VIRTUAL_ENV=/usr/local/lib/hermes-agent/venv"
Environment="HERMES_HOME=/home/<username>/.hermes"
Restart=always
RestartSec=5
RestartForceExitStatus=75
KillMode=mixed
KillSignal=SIGTERM
ExecReload=/bin/kill -USR1 $MAINPID
TimeoutStopSec=210
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
```
skills/devops/hermes-telegram-cli-notify/SKILL.md
+123
View File
@@ -0,0 +1,123 @@
---
name: hermes-telegram-cli-notify
description: "Send Telegram notifications when Hermes CLI/TUI is started from the terminal — wrapper function for ~/.bashrc"
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux]
metadata:
hermes:
tags: [hermes, telegram, notification, cli, wrapper, bashrc]
related_skills: [hermes-agent, hermes-gateway-systemd]
---
# Hermes CLI Telegram Notification Wrapper
Send a Telegram message automatically whenever you start `hermes` or `hermes --tui` from the terminal. Useful for tracking when interactive sessions are launched.
## Installation
Add to `~/.bashrc` (or `~/.zshrc`):
```bash
# Load Hermes env (for TELEGRAM_BOT_TOKEN)
[ -f /root/.hermes/.env ] && export $(grep -v '^#' /root/.hermes/.env | xargs) 2>/dev/null
# Hermes CLI Start → Telegram Notification
hermes() {
local msg="🖥️ <b>Hermes CLI gestartet</b>%0AHost: $(hostname)%0AUser: $(whoami)%0ADir: $(pwd)%0ACmd: hermes $*"
if [ -n "${TELEGRAM_BOT_TOKEN:-}" ]; then
# Send notification synchronously (wait for it)
curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
-d chat_id="${TELEGRAM_HOME_CHANNEL:-6417835766}" \
-d parse_mode="HTML" \
-d text="$msg" >/dev/null 2>&1
fi
command hermes "$@"
}
```
Then reload:
```bash
source ~/.bashrc
```
## Requirements
- `TELEGRAM_BOT_TOKEN` in `/root/.hermes/.env` (or wherever your Hermes config lives)
- `TELEGRAM_HOME_CHANNEL` or `TELEGRAM_ALLOWED_USERS` set to your chat ID
- Gateway must be running and bot connected to Telegram
## How It Works
1. Bash function `hermes()` wraps the real `hermes` command
2. On invocation, sends a formatted HTML message to Telegram via Bot API
3. Then executes the real `hermes` command with all passed arguments
4. Uses `command hermes` to bypass the function and call the actual binary
## Message Format
```html
🖥️ <b>Hermes CLI gestartet</b>
Host: <hostname>
User: <username>
Dir: <current-working-directory>
Cmd: hermes <args>
```
## Pitfalls & Gotchas
### 1. `.bashrc` Early Return Block
Most `.bashrc` files have `[ -z "$PS1" ] && return` at the top for non-interactive shells.
**The wrapper MUST be defined BEFORE this line**, otherwise it won't work in `bash -lc` or scripts.
```bash
# ~/.bashrc - CORRECT ORDER
# Hermes wrapper HERE (before early return)
hermes() { ... }
# If not running interactively, don't do anything
[ -z "$PS1" ] && return
```
### 2. Environment Variables Not Loaded
The wrapper sources `/root/.hermes/.env` at shell startup. If the file moves or variables change, reload:
```bash
source /root/.hermes/.env && source ~/.bashrc
```
### 3. Background `&` vs Synchronous
Initially used `&` to background the curl. This caused race conditions where Hermes started before notification sent.
**Fix:** Remove `&` — send synchronously (fast enough, ~100-300ms).
### 4. Token Not Available in Subshells
When running `bash -lc 'hermes ...'`, the `.bashrc` is sourced but the early return may skip the wrapper.
Ensure `.bashrc` structure puts wrapper before `[ -z "$PS1" ] && return`.
## Verification
Test manually:
```bash
# Direct curl test (should appear in Telegram)
curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
-d chat_id="6417835766" \
-d parse_mode="HTML" \
-d text="🖥️ <b>Test</b>%0AHost: $(hostname)%0AUser: $(whoami)"
# Wrapper test
hermes --version
# Check Telegram for notification
```
## Real-World Example (This Session)
- **Goal:** Notify on Telegram when `hermes` or `hermes --tui` started from terminal
- **Implementation:** Added wrapper to `/root/.bashrc` with synchronous curl
- **Issue Found:** Wrapper placed after `[ -z "$PS1" ] && return` → didn't work in `bash -lc`
- **Fix:** Moved wrapper before early return line
- **Result:** Notifications now sent on every CLI start
## Related Skills
- `hermes-agent` — main Hermes configuration
- `hermes-gateway-systemd` — gateway service troubleshooting (bot must be running)
skills/devops/jit-ssh-access-portal/SKILL.md
+89
View File
@@ -0,0 +1,89 @@
---
name: jit-ssh-access-portal
description: "Web login + Telegram 2FA + time-boxed UFW SSH opening."
version: 1.0.0
platforms: [linux]
---
# JIT SSH Access Portal (Telegram 2FA + Time-boxed Firewall)
Opens a web endpoint (`ssh.<domain>.de`) with password login, then a 6-digit **Telegram 2FA**
code. On success, the backend opens **Port 22 in UFW only for the requesting IP** for a bounded
time (default 1h) and auto-closes it. SSH stays closed-for-the-world otherwise.
## Why (security model)
- SSH is **closed by default** — no "22 Anywhere" rule.
- 2FA over Telegram is **out-of-band** (a channel separate from the web login).
- Firewall opening is **time-boxed** (`expiry` + background auto-close) → no permanent hole.
- Passwords stored **hashed** (werkzeug `generate_password_hash`); first-use password forces change.
## Components
```
nginx vhost ssh.<domain>.de (SSL) → reverse proxy → Flask app on 127.0.0.1:8091
Flask app:
- SQLite users table (username, pw_hash, pw_changed, failed, lockout_until)
- POST / login (Erstpasswort → redirect zum PW-Wechsel; danach → /2fa)
- POST /change-pw one-time password change (min length, confirm)
- POST /2fa verify 6-digit code, `ufw allow from <ip> to any port 22` (1h)
- background thread `_close_expired()` → `ufw delete allow ...` after expiry
- `/srv` session carries `2fa_code`, `2fa_ts`, `2fa_attempts`
```
Full reference implementation: `references/app.py` (drop-in `/opt/sshportal/app.py`).
Deploy as a **systemd service** (survives reboot, overrides the VM-side "can't background" limit).
## Security anchors (non-negotiable)
1. **First password is one-time**: set `pw_changed=0` on first user; force change before 2FA.
2. **2FA TTL + attempt cap**: code valid ~120s, max 3 attempts, then lock (log + Telegram alert).
3. **Client IP source**: read `X-Real-IP`/`X-Forwarded-For` (set by nginx `proxy_set_header`),
NOT `remote_addr` directly (would be the proxy).
4. **Brute-force**: track `failed`; lockout window after N failures. **ACHTUNG (2026-08-04):** `users`-Tabelle hat `failed`/`lockout_until`-Spalten, und die `login()`-Route muss sie WIRKLICH nutzen — eine frühere Version hatte sie angelegt, aber nie abgefragt (Login prüfte nur Passwort). Zusätzlich IP-basiertes In-Memory-Lockout (`_IP_FAIL`), da Angriffe mit leerem/fremden Benutzernamen am User-Lockout vorbeigehen. Nach Nutzung von `login()`: echten User auf `failed=0, lockout_until=0` zurücksetzen, da Tests den Zähler hochziehen.
5. **Rate-limit / TLS only**: only serve behind https (certbot `--redirect`).
6. **Logging**: every login / pw-change / 2FA / open / close → local log + mesh event log.
## Pitfalls
- `render_template_string` escapes HTML by default → wrap dynamic HTML content in `Markup(...)`
or pass plain text messages separately, or the form renders as escaped text (no `<h1>`).
- Launching the Flask app with `nohup ... &` via the agent shell is blocked ("can't background
inside gateway") → use a **systemd unit**, not a shell background process.
- `ufw` interactive confirm: when deleting by number `ufw delete N` prompts → pipe `yes |` or
delete by full rule string.
- UFW rule dedupe: `ufw_allow` should skip if `ufw status` already shows `from <ip>`.
- After the requesting IP is external (e.g. the browser came over the VPS public IP), the opened
rule targets that external IP — if the real SSH client is on ZeroTier, the browser IP won't
match. Decide whether the portal serves ZT-internal clients (requesting IP = ZT IP) or external.
- **End-to-end test mutates the DB.** Running the full login→pw-change flow during testing
overwrites the stored hash and sets `pw_changed=1`. If you don't reset afterward, the user's
real first login FAILS with "falsches Passwort". After any E2E test, reset to first-use state:
```bash
sqlite3 /opt/sshportal/portal.db \
"UPDATE users SET pw_hash='<bcrypt of first-pw>', pw_changed=0 WHERE username='mehlzoerwer';"
```
(or re-run the app's `ensure_first_user` logic). Essentially: a "password changed" side effect
from testing must be rolled back before declaring the portal ready.
## Firewall pre-condition
Before enabling a JIT portal, tighten SSH so it is NOT "Anywhere". Restrict to the trusted
ZeroTier mesh IPs, and close leftover WG/NFS ports:
```bash
ufw delete allow 22/tcp
for ip in <trusted-ips>; do ufw allow from $ip to any port 22 proto tcp; done
systemctl stop rpcbind rpcbind.socket && systemctl disable rpcbind rpcbind.socket
```
Public reachable surface should be **only 80 + 443**.
## Verification
- `curl https://ssh.<domain>.de/` → 200 login page.
- First login (first PW) → `302 /change-pw`; set new PW → "Passwort geändert" log.
- Second login → `302 /2fa`; backend logs "2FA-Code gesendet" and Telegram delivers a 6-digit code.
- Submit correct code → `ufw status` shows `22/tcp ALLOW <ip> # SSH JIT Portal`; wrong code ×3 → lock.
- After expiry → rule removed (test `ufw_allow`/`ufw_deny` on a throwaway IP end-to-end).
Full safe E2E test recipe for the login/lockout logic (throwaway user, IP-reset-before-DB-branch,
cleanup): `references/safe-e2e-login-testing.md`.
skills/devops/jit-ssh-access-portal/references/app.py
+201
View File
@@ -0,0 +1,201 @@
#!/usr/bin/env python3
"""
Drop-in reference: /opt/sshportal/app.py
SSH-Portal mit Telegram-2FA und JIT-Firewall-Freischaltung.
Login mehlzoerwer -> Erstpasswort -> PW-Wechsel-Pflicht -> 2. Login: PW+Telegram-Code
-> UFW oeffnet Port 22 fuer angefragte IP (1 Stunde) -> Auto-Close.
Abhaengigkeiten (venv): flask, werkzeug, requests.
Start via systemd unit (NICHT nohup & im Agent-Shell).
"""
import os, re, time, secrets, sqlite3, subprocess, threading
from pathlib import Path
from flask import Flask, request, render_template_string, session, redirect, url_for
from werkzeug.security import generate_password_hash, check_password_hash
import requests
PORTAL_DIR = Path("/opt/sshportal")
DB = PORTAL_DIR / "portal.db"
LOG = PORTAL_DIR / "portal.log"
ALLOW_TIME = 3600 # 1 Stunde offen
MAX_2FA_ATTEMPTS = 3
CODE_TTL = 120 # 2 Minuten gueltig
ENV_FILE = "/root/.hermes/.env"
def _env(key):
try:
txt = Path(ENV_FILE).read_text()
m = re.search(key + r"\s*=\s*(\S+)", txt)
return m.group(1).strip() if m else ""
except Exception:
return ""
TG_TOKEN = _env("TELEGRAM_BOT_TOKEN")
TG_CHAT = _env("TELEGRAM_HOME_CHANNEL") or "6417835766"
app = Flask(__name__)
app.secret_key = secrets.token_hex(32)
def log(msg):
with open(LOG, "a") as f:
f.write(f"{time.strftime('%Y-%m-%d %H:%M:%S')} {msg}\n")
def db():
c = sqlite3.connect(DB); c.row_factory = sqlite3.Row; return c
def init_db():
c = db()
c.execute("""CREATE TABLE IF NOT EXISTS users(
id INTEGER PRIMARY KEY, username TEXT UNIQUE, pw_hash TEXT,
pw_changed INTEGER DEFAULT 0, failed INTEGER DEFAULT 0, lockout_until INTEGER DEFAULT 0)""")
c.execute("""CREATE TABLE IF NOT EXISTS sessions(
ip TEXT, status TEXT, ts INTEGER, expiry INTEGER)""")
c.commit(); c.close()
def ensure_first_user():
c = db()
row = c.execute("SELECT * FROM users WHERE username='mehlzoerwer'").fetchone()
if not row:
c.execute("INSERT INTO users(username,pw_hash,pw_changed) VALUES(?,?,0)",
("mehlzoerwer", generate_password_hash("St230918kM@vps")))
c.commit(); log("Erstbenutzer angelegt (Erstpasswort aktiv)")
c.close()
def send_telegram(text):
try:
requests.post(f"https://api.telegram.org/bot{TG_TOKEN}/sendMessage",
json={"chat_id": TG_CHAT, "text": text}, timeout=8)
except Exception as e:
log(f"Telegram-Fehler: {e}")
def ufw_allow(ip):
r = subprocess.run(["ufw","status"], capture_output=True, text=True)
if f"from {ip}" in r.stdout:
return False
subprocess.run(["ufw","allow","from",ip,"to","any","port","22","proto","tcp",
"comment","SSH JIT Portal"], check=False)
return True
def ufw_deny(ip):
subprocess.run(["ufw","delete","allow","from",ip,"to","any","port","22","proto","tcp",
"comment","SSH JIT Portal"], check=False)
def client_ip():
return request.headers.get("X-Real-IP") or request.remote_addr
def _close_expired():
while True:
try:
c = db(); now = int(time.time())
for r in c.execute("SELECT ip FROM sessions WHERE status='open' AND expiry<=?", (now,)):
ufw_deny(r["ip"])
c.execute("UPDATE sessions SET status='closed' WHERE ip=? AND status='open'", (r["ip"],))
log(f"Auto-Close: SSH geschlossen fuer {r['ip']}")
c.commit(); c.close()
except Exception:
pass
time.sleep(60)
threading.Thread(target=_close_expired, daemon=True).start()
HTML = """<!doctype html><html lang="de"><head><meta charset="utf-8"><title>SSH-Zugangsportal</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0"></head>
<body style="font-family:system-ui;max-width:400px;margin:80px auto;padding:0 20px">
{{ message }}{{ content }}</body></html>"""
def render(content, msg=None, msgtype="info"):
from markupsafe import Markup
m = ""
if msg:
m = f'<div style="background:{ "#e6f9ef;color:#0a7a4a" if msgtype=="ok" else "#fdecea;color:#b3261e" };padding:10px;border-radius:5px;margin:10px 0">{msg}</div>'
return render_template_string(HTML, message=Markup(m), content=Markup(content))
FORM_LOGIN = '<h1>SSH-Zugang</h1><form method="post">' + \
'<p><input name="username" placeholder="Benutzer" required style="width:100%;padding:10px"></p>' + \
'<p><input name="password" type="password" placeholder="Passwort" required style="width:100%;padding:10px"></p>' + \
'<button style="width:100%;padding:11px;background:#10b981;color:#fff;border:0;border-radius:5px">Anmelden</button></form>'
FORM_PW = '<h1>Neues Passwort</h1><form method="post">' + \
'<p><input name="new1" type="password" placeholder="Neues Passwort" required style="width:100%;padding:10px"></p>' + \
'<p><input name="new2" type="password" placeholder="Wiederholen" required style="width:100%;padding:10px"></p>' + \
'<button style="width:100%;padding:11px;background:#10b981;color:#fff;border:0;border-radius:5px">Speichern</button></form>'
FORM_2FA = '<h1>2-Faktor</h1><p>Ein 6-stelliger Code wurde dir per Telegram zugesendet. Gültig 2 Minuten.</p>' + \
'<form method="post"><input name="code" placeholder="6-stelliger Code" required style="width:100%;padding:10px">' + \
'<button style="width:100%;padding:11px;background:#10b981;color:#fff;border:0;border-radius:5px;margin-top:8px">Bestätigen</button></form>'
@app.route("/", methods=["GET","POST"])
def login():
if request.method == "POST":
username = request.form.get("username","").strip()
password = request.form.get("password","")
ip = client_ip()
c = db()
user = c.execute("SELECT * FROM users WHERE username=?", (username,)).fetchone()
if not user or not check_password_hash(user["pw_hash"], password):
log(f"FEHL_LOGIN {username} von {ip}")
return render(FORM_LOGIN, "Falscher Benutzer oder Passwort.", "err")
session["user"] = username
if not user["pw_changed"]:
log(f"PW-WECHSEL noetig {username} von {ip}")
return redirect(url_for("change_pw"))
session["pending_2fa_ip"] = ip
code = f"{secrets.randbelow(1000000):06d}"
session["2fa_code"] = code; session["2fa_ts"] = int(time.time()); session["2fa_attempts"] = 0
send_telegram(f"SSH-Portal 2FA fuer Login von {ip}\nCode: {code}\nGueltig 2 Min.")
log(f"2FA-Code an Chat {TG_CHAT} fuer Login von {ip}")
return redirect(url_for("twofa"))
return render(FORM_LOGIN)
@app.route("/change-pw", methods=["GET","POST"])
def change_pw():
if "user" not in session:
return redirect(url_for("login"))
if request.method == "POST":
new1 = request.form.get("new1",""); new2 = request.form.get("new2","")
if new1 != new2 or len(new1) < 10:
return render(FORM_PW, "Passwoerter mismatch oder zu kurz (min 10).", "err")
c = db()
c.execute("UPDATE users SET pw_hash=?, pw_changed=1 WHERE username=?",
(generate_password_hash(new1), session["user"]))
c.commit(); c.close()
log(f"Passwort geaendert fuer {session['user']}")
send_telegram(f"Passwort fuer {session['user']} geaendert.")
return render("<h1>Passwort geaendert</h1><p>Bitte neu einloggen. <a href='/'>Login</a></p>",
"Passwort erfolgreich geaendert.", "ok")
return render(FORM_PW)
@app.route("/2fa", methods=["GET","POST"])
def twofa():
if "2fa_code" not in session:
return redirect(url_for("login"))
if request.method == "POST":
entered = request.form.get("code","").strip()
ip = session["pending_2fa_ip"]
if int(time.time()) - session["2fa_ts"] > CODE_TTL:
session.pop("2fa_code", None)
return render("", "Code abgelaufen. Bitte neu anmelden.", "err")
if entered == session["2fa_code"]:
added = ufw_allow(ip)
c = db()
c.execute("INSERT INTO sessions(ip,status,ts,expiry) VALUES(?,?,?,?)",
(ip,"open",int(time.time()),int(time.time())+ALLOW_TIME))
c.commit(); c.close()
session.pop("2fa_code", None)
log(f"SSH-Freischaltung fuer {ip} (1h)")
send_telegram(f"SSH-Freischaltung fuer {ip} aktiv (1 Stunde).")
return render(f"<h1>Zugriff freigeschaltet</h1><p>SSH auf Port 22 fuer <b>{ip}</b> fuer 1 Stunde.</p>",
"Freigeschaltet!", "ok")
else:
session["2fa_attempts"] = session.get("2fa_attempts",0)+1
log(f"FALSCHER 2FA-Code von {ip} (Versuch {session['2fa_attempts']})")
if session["2fa_attempts"] >= MAX_2FA_ATTEMPTS:
session.pop("2fa_code", None)
send_telegram(f"3x falscher 2FA-Code von {ip} — gesperrt.")
return render("", "Zu viele Fehlversuche. Login gesperrt.", "err")
return render(FORM_2FA, f"Falscher Code. Versuche uebrig: {MAX_2FA_ATTEMPTS-session['2fa_attempts']}", "err")
return render(FORM_2FA)
if __name__ == "__main__":
PORTAL_DIR.mkdir(exist_ok=True)
init_db(); ensure_first_user()
log("SSH-Portal gestartet")
app.run(host="127.0.0.1", port=8091)
skills/devops/jit-ssh-access-portal/references/safe-e2e-login-testing.md
+53
View File
@@ -0,0 +1,53 @@
# Sicheres E2E-Testen der Login-/Lockout-Logik (ohne echten User zu zerstören)
Der Bonuspitfall: Tests der Login-/Brute-Force-Logik dürfen den **echten
Benutzeraccount** (`mehlzoerwer`) nicht verändern, sonst ist der echte Login
danach defekt (Skill-Pitfall "E2E-Test mutiert die DB").
## Muster (validiert 2026-08-04)
1. **IP-Lockout-Zweig testen** → mit einem **fremden/leeren Benutzernamen**
laufen lassen. Fremder User trifft nur den In-Memory-`_IP_FAIL`-Zähler,
KEIN DB-Update auf den echten Account:
```bash
for i in $(seq 1 6); do
curl -sk -X POST https://ssh.<domain>.de/ \
-d "username=foo&password=wrong$i"
done
tail portal.log # Versuch 6 → "IP-SPERRE aktiv für <ip>"
```
Prüfen, dass der echte User danach `failed=0, lockout_until=0` ist.
2. **DB-User-Lockout-Zweig testen** → **temporären Test-User** in die DB,
nach dem Test wieder löschen:
```bash
./venv/bin/python -c "
import sqlite3
from werkzeug.security import generate_password_hash
c=sqlite3.connect('portal.db')
c.execute(\"INSERT OR REPLACE INTO users(username,pw_hash,pw_changed,failed,lockout_until)\
VALUES('testuser',?,1,0,0)\", (generate_password_hash('TestPass123!'),))
c.commit(); c.close()"
```
Dann 5x falsches PW für `testuser` → DB zeigt `failed=5, lockout_until=<ts>`,
Log zeigt "USER-SPERRE aktiv".
3. **WICHTIG — In-Memory-IP-Sperre leert nur beim Service-Restart**:
Nach Test 1 ist die Test-IP noch 15 min in `_IP_FAIL` gesperrt. Vor dem
Testen des zweiten Zweigs `systemctl restart sshportal` (leert den
In-Memory-Zähler), sonst kommen die neuen Requests gar nicht bis zur DB.
4. **Aufräumen** (immer, in einer Transaktion committen):
```bash
c.execute('DELETE FROM users WHERE username=?', ('testuser',))
c.execute('UPDATE users SET failed=0, lockout_until=0 WHERE username=?', ('mehlzoerwer',))
c.commit()
```
## Fallstricke
- `sqlite3`-CLI fehlt oft auf dem VPS → über das venv-Python lesen
(`./venv/bin/python -c "..."`), nicht `sqlite3 portal.db`.
- DB-Schema kann Alt-Spalten haben → `dict(row)` schlägt beim Print fehl
("length 11; 2 is required"); explizite Spalten im SELECT wählen.
- Desktop-`dict(rows)`-Print ist nur Reporting, nicht Teil des Deletes — ein
Traceback dort heißt NICHT, dass der Delete fehlgeschlagen ist.
skills/devops/mesh-master-control/SKILL.md
+348
View File
@@ -0,0 +1,348 @@
---
name: mesh-master-control
description: "Use when: Master steuert Modell/Budget/Notfall im Mesh."
version: 1.0.0
platforms: [linux]
related_skills: [model-allocation, multi-agent-mesh, openrouter-cost-budgeting]
---
# Mesh-Master-Control — SSH + Modell-Scout + Kill-Switch
## Prinzip
Der Master (VPSHermes, 172.24.196.119) bestimmt im Mesh **alles** was Modell, Budget und Notfall-Steuerung angeht. Der Nutzer soll nicht 24/7 aufpassen müssen — der Master handelt autonom bei Kosten-Explosion, Modell-Ausfall oder Budget-Knappheit.
**Kernregel (Nutzervorgabe, August 2026, hart):** SSH-Kanal vom Master zu allen Sub-Agenten MUSS funktionieren. NFS-Tasks sind zu langsam für Notfälle. WENN SSH fehlt → SOFORT fixen (Key generieren + an Sub-Agenten pushen), NICHT stillschweigend mit NFS weiterwursteln.
## 1. SSH-Control-Kanal
### SSH-Key auf Master generieren
```bash
ssh-keygen -t ed25519 -f /root/.ssh/id_ed25519 -N "" -C "mesh-master@172.24.196.119"
```
### Public-Key an Sub-Agenten verteilen (AcceptMasterKey-Task)
Datei in `/srv/work/tasks/offen/YYYYMMDD.C.D.AcceptMasterKey.json`:
```json
{
"task_id": "YYYYMMDD.C.D.AcceptMasterKey",
"ziel_agent": "<Agent-Name>",
"aufgabentyp": "config",
"prioritaet": "high",
"beschreibung": "AcceptMasterKey",
"aufgabe_details": {
"master_pubkey": "<public-key-inhalt>",
"schritte": [
"mkdir -p ~/.ssh && chmod 700 ~/.ssh",
"echo '<pubkey>' >> ~/.ssh/authorized_keys",
"chmod 600 ~/.ssh/authorized_keys"
]
}
}
```
**Dateiname-Schema:** `YYYYMMDD.C.D.AcceptMasterKey.json` (C.D = letzte 2 ZT-IP-Oktette)
## 2. Model Scout (alle 3 Tage)
**Script:** `/usr/local/bin/mesh-model-scout.py` (Python, 26 KB, vollstaendig autonom)
**Cron:** `0 6 */3 * * /usr/local/bin/mesh-model-scout.py >> /var/log/mesh-model-scout.log 2>&1`
**Bekannte Modelle (Hardcoded in Script):** 25+ Modelle aus DeepSeek, Llama, Gemini, Qwen, Mistral, Nvidia, MiniMax, Cohere — mit Bewertungen in 5 Dimensionen.
**Cache:** OpenRouter-API-Cache unter `/tmp/openrouter_models.json` (1h-Gueltigkeit)
### Ablauf
1. **OpenRouter-API live abrufen** (GET /api/v1/models, 300+ Modelle) oder aus Cache
2. **Filtern** auf ≥64k Kontext + gültige Preise + bekanntes Modell
3. **Bewerten** in 5 Dimensionen (1–5): Coding, Reasoning, Linux/Ops, Docs/Text, Tool-Use
4. **Agenten-Matching** nach Rollenprofil
5. **Budget-Simulation** (Token × Preis = Tageskosten × 30 = Monat)
6. **Aenderungserkennung** (Vergleich mit `model_scout_last.json`)
7. **Ausgabe:** JSON + HTML-Doku + Tasks an Sub-Agenten
8. **Telegram-Benachrichtigung** mit Zusammenfassung
### Rollen-Profile (Stand 31.08.2026 — Nutzer-Bestaetigung: je Agent eigenes Modell, Master das teuerste bis $2/M)
| Agent | Modell | Input $/M | Begruendung | Kosten/Monat |
|-------|--------|-----------|-------------|------------|
| Master | `deepseek/deepseek-v4-flash` | $0.089 | Coding 5/5, Linux 4/5, Tool-Use 4/5 — beste Passung fuer Master-Aufgaben | ~$1.33 |
| UnraidHermes | `deepseek/deepseek-v4-flash-0731` | $0.065 | Coding 5/5, Reasoning 4/4 — guenstiger als Maverick bei besserer Leistung. Nutzer fand $3.89 zu teuer → DeepSeek V4 Flash, $1.12/Monat | ~$1.12 |
| SwitchHermes | `qwen/qwen3.7-flash` | $0.030 | 1M Kontext, sehr guenstig, solides Allround-Modell fuer ARM64 | ~$0.66 |
| LaptopHermes | `mistralai/mistral-nemo` | $0.019 | Solides Allround, 131k Kontext, flexibel fuer Text + leichte System-Aufgaben | ~$0.26 |
**Regel (Nutzer 31.08.2026):** Jeder Sub-Agent bekommt ein ANDERES Modell. Der Master bekommt das teuerste (bis $2/M Input). Subs bleiben unter $1/M Input. Gesamtkosten unter $25/Monat.
**Gesamtkosten:** ~$3.37/Monat (von $25 Limit → ~7 Monate Reserve)
### Ausgabe-Orte
- JSON: `/srv/work/tasks/model_scout_last.json`
- HTML: `/var/www/dokumentationen.perfekt-ohne-en.de/model-scout-<datum>.html`
- Live: https://dokumentationen.perfekt-ohne-en.de/model-scout-latest.html
- Tasks: `/srv/work/tasks/offen/YYYYMMDD.C.D.ModelAssignment.json`
### Bekannte Bugs im Script (Stand August 2026)
- `distribute_via_tasks()` erwartet `/srv/work/tasks/offen/` — wenn nicht vorhanden, schlaegt silent fehl. Fix: `os.makedirs(task_dir, exist_ok=True)` vor Schreibzugriff. (Gefixt in Version 1.1 via Patch 22.08.2026.)
## 3. Budget-Kill-Switch (3 Stufen, alle 30 Min)
**Script:** `/usr/local/bin/mesh-budget-watch.sh` (Cron-gesteuert)
**Cron:** `*/30 * * * * /usr/local/bin/mesh-budget-watch.sh`
**State:** `/var/lib/mesh-budget-state` (entprellt Telegram-Benachrichtigungen)
**Aktuelles Guthaben (28.08.2026):** $25.69 USD (nach Aufladung +$25)
**Letzter Log:** `/var/log/mesh-budget-watch.log`
### Budget-Keyword-Report (per Chat/Telegram)
**Script:** `/usr/local/bin/mesh-budget-report.sh`
Wenn der Nutzer "Budget" sagt (als Wort, nicht als Frage), führt Master dieses Script aus. Es holt:
- **OpenRouter-Guthaben** live via API (`/api/v1/credits`)
- **Modelle aller 4 Agents** live via SSH (`hermes config get model.default`)
**Telegram-Format (Bullet-Liste, KEIN Code-Block):**
```
​​​​ Budget (29.08 13:35)
Guthaben: $24.09
• Master — gemini-2.5-flash
• Unraid — gemini-2.5-flash
• Switch — nemotron-3
• Laptop — gemini-2.5-flash
```
**Regel (Nutzer 29.08.2026):** Bullet-Liste statt Code-Block. Kein Doppel-Output (Script schreibt nur an Telegram, gibt nichts auf stdout). Modellnamen auf <20 Zeichen kuerzen (family + version only).
### Schwellen (verbindlich, Nutzer-Bestaetigung 28.08.2026)
| Stufe | Guthaben | Aktion |
|-------|----------|--------|
| OK | > $1.00 | Normalbetrieb |
| WARN | < $1.00 | Telegram-Warnung (einmalig) |
| SWITCH | < $0.50 | Alle Agents → Ollama via `mesh-kill-all.sh` |
| STOP | < $0.10 | Komplett-Stopp (alle kostenpflichtigen Calls) |
## 4. Notfall-Tools
### mesh-kill-all.sh
```bash
/usr/local/bin/mesh-kill-all.sh
```
Setzt **alle Agents** auf Ollama:
1. Telegram: "🚨 MESH-KILL-SWITCH ausgelöst"
2. SSH an 3 Sub-Agenten → `hermes config set model.default ollama`
3. Master selbst → ebenfalls Ollama
### mesh-model-broadcast.sh
```bash
mesh-model-broadcast.sh <modell> [provider] # provider default: openrouter
mesh-model-broadcast.sh google/gemini-2.5-flash:free openrouter
mesh-model-broadcast.sh ollama ollama
```
Setzt Modell + Provider auf **Master + allen 3 Sub-Agenten** gleichzeitig.
## 5. Status-Monitor (Antworten tracken)
**Script:** `/usr/local/bin/mesh-status-monitor.sh`
**Cron:** `*/30 * * * * /usr/local/bin/mesh-status-monitor.sh`
- Prüft: offene Tasks, erledigte Tasks, SSH-Status pro Agent
- Telegram-Meldung NUR bei Status-Änderung (entprellt)
- Finalmeldung: "✅ ALLE 3 SSH FUNKTIONIEREN" wenn komplett
## 6. Sub-Agenten im Mesh
| Sub-Agent | ZT-IP | Suffix (C.D) |
|-----------|-------|--------------|
| UnraidHermes | 172.24.34.142 | 34.142 |
| SwitchHermes | 172.24.20.26 | 20.26 |
| LaptopHermes | 172.24.178.202 | 178.202 |
## 7. Gateway-Auto-Restart (Reboot-Festigkeit)
Der hermes-gateway.service startet nicht automatisch nach Reboot, wenn UFW/ZeroTier noch nicht bereit sind. **Fix (29.08.2026):**
```bash
# 1. Service-File bereinigen (doppelte Restart-Einträge entfernen)
# 2. ZeroTier-Abhängigkeit hinzufügen (After=zerotier-one.service)
# 3. StartLimitBurst erhöhen (Default 5 → nie aufhören zu retryen)
# 4. RestartSec auf 15s setzen (Netzwerk-Zeit geben)
systemctl enable hermes-gateway.service # damit nach Reboot startet
```
**Service-File (final, getestet 29.08.2026):**
```
[Unit]
Description=Hermes Agent Gateway - Messaging Platform Integration
After=network-online.target zerotier-one.service
Wants=network-online.target zerotier-one.service
StartLimitIntervalSec=0
StartLimitBurst=999
[Service]
Type=simple
User=root
Group=root
Restart=always
RestartSec=15
...
```
**Wichtig:** OHNE `After=zerotier-one.service` startet der Gateway bevor ZeroTier verbunden ist → Telegram-Verbindung scheitert → exit code 1 → systemd gibt auf (nach 5 Versuchen default). Der Fix ist NICHT nur `enable`, sondern auch die Abhängigkeit und das Burst-Limit.
**Prüfung nach Reboot:**
```bash
systemctl is-active hermes-gateway.service # sollte 'active' sein
systemctl show hermes-gateway.service -p Restart -p RestartSec -p StartLimitBurst # Restart=always, StartLimitBurst=999
```
**Detail (Fehleranalyse 29.08.2026):**
- `journalctl -u hermes-gateway.service --no-pager | tail -30` zeigte `Connection error` + `exit code 1`
- ZeroTier war nicht bereit, UFW blockte SSH (siehe SSH/UW-Fix)
- Der Fix kombiniert: Service enable + ZeroTier-After + StartLimitBurst + UFW-Regeln
## 8. Sub-Agent-Task-Format (hart, Pitfall August 2026)
**Sub-Agenten führen lange Tasks nicht aus — sie analysieren sie.** Ein Task mit 5+ Sätzen Kontext, Erklärungen oder mehreren Optionen führt dazu, dass der Sub-Agent einen Essay über die Aufgabe schreibt statt sie auszuführen.
**Regel (verbindlich):**
- Tasks MÜSSEN ein `befehl`-Feld enthalten — ein einzelner, kurzer Shell-Befehl
- Max 2 Sätze Kontext pro Task
- KEINE Erklärung, KEINE Optionen, KEINE Theorie
- Sub-Agent antwortet mit Ausführung oder Fehler, nicht mit Analyse
**Richtiges Format (funktioniert):**
```json
{
"task_id": "YYYYMMDD.C.D.Key",
"ziel_agent": "AgentName",
"prioritaet": "high",
"befehl": "mkdir -p ~/.ssh && echo '<pubkey>' >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
}
```
**Falsches Format (Sub-Agent analysiert statt auszuführen):**
```json
{
"task_id": "...",
"kontext": "Master hat neuen SSH-Key generiert...",
"aufgabe_details": { "schritte": ["1. Prüfe...", "2. Überlege...", "3. Analysiere..."] }
}
```
**Erkenntnis aus 28.08.2026 (3 vergebliche AcceptMasterKey-Versuche):** Sub-Agenten verstehen `ausfuehren`/`befehl` als direkten Terminal-Befehl. Ohne dieses Feld denken sie über die Aufgabe nach statt sie zu terminieren.
## 9. Budget-Report-Format (Nutzer-Vorgabe, 29.08.2026)
Wenn der Nutzer "Budget" sagt (ein Wort, kein Fragezeichen):
1. Führe `/usr/local/bin/mesh-budget-report.sh` aus (stumm, >/dev/null)
2. Das Script sendet direkt an Telegram
3. **Kein Doppel-Output** ins Chat-Fenster
**Telegram-Format:**
```
​​​​ Budget (DD.MM HH:MM)
Guthaben: $XX.XX
• Master — model-shortname
• Unraid — model-shortname
• Switch — model-shortname
• Laptop — model-shortname
```
**Format-Regeln:**
- Bullet-Liste (KEIN Code-Block)
- Modellnamen auf <20 Zeichen kürzen (nur family+version, z.B. `gemini-2.5-flash` statt `google/gemini-2.5-flash:free`)
- Zeile `Agent Modell` + Trennlinie entfernt (führt auf Handy)
- Kein vorheriges Echo der Ausgabe (Script stdout >/dev/null)
## 10. Deploy-Check-Pflicht (3-Check-Liste, aus Impressum-Fehlern gelernt)
**Vor JEDEM systemctl reload/restart oder nginx-Config-Change:**
```bash
bash /usr/local/bin/mesh-deploy-check.sh <domain> [python-app.py]
```
### Die 3 Checks
| # | Check | Befehl | Verhindert |
|---|-------|--------|------------|
| 1 | nginx -t | `nginx -t` | Config-Fehler, die nginx killen |
| 2 | HTTP 200 | `curl -s -o /dev/null -w '%{http_code}' https://<domain>/` | Domain offline nach Deploy |
| 3 | Python-Syntax | `python3 -m py_compile app.py` | SyntaxError nach systemd-Restart |
4. **Nach dem Deploy: Team-Review auf der LIVE-Seite, bevor dem Nutzer "fertig" gemeldet wird**
→ Technischer Deploy-Check (nginx-t + HTTP 200 + py_compile) reicht nicht:
**Kontrast-Fehler vom 01.09.2026:** Seite war technisch 200, Inhalt komplett, aber Text auf Hintergrund hatte nur 4.2:1-Kontrast (WCAG-AA fordert 4.5:1) → schwarze Schrift auf schwarzem Hintergrund. SwitchHermes hat es im Review sofort gefunden.
→ **Fix:** Nach bestandenem 3-Check: Task an SwitchHermes ODER LaptopHermes mit vollem Seiteninhalt + Aufforderung zur visuellen Prüfung (Kontrast, Lesbarkeit, Layout).
→ **Regel:** "Fertig" bedeutet: technische Checks PASS + Team-Review PASS + Nutzer-Korrektur-Runde PASS.
5. **Sub-Agent-Review: Seite NICHT per URL prüfbar → Inhalt einbetten**
→ Sub-Agenten (besonders schwächere = SwitchHermes) laden oft keine externen URLs
oder stoßen an Tool-Limits. `curl -s "https://seite.de/"` liefert leeres Resultat.
→ **Fix:** Seiteninhalt DIREKT in die Task-Beschreibung einbetten (HTML, relevante Text-Auszüge).
Nie: "Siehe https://.../ -> prüfe das." Sondern: "Hier der Seiten-Inhalt: <...>. Prüfe Kontrast/Layout."
6. **Cleanup-Cron für alte Tasks**
```bash
openssl x509 -in /etc/letsencrypt/live/<domain>/fullchain.pem -noout -text | grep DNS:
```
→ certbot --expand überschreibt Configs und kann falsche Zertifikate zuweisen (Fehler #5: veganbedeutetleben.de war offline, weil evolution-Zertifikat verwendet wurde).
2. **Kein nginx reload ohne nginx -t vorher**
→ Ein fehlerhafter Vhost killt ALLE Domains, nicht nur die eine.
3. **Kein systemd restart ohne py_compile vorher**
→ IndentationError nach Patch killt den Service (Fehler #3).
4. **Sub-Agent-Tasks immer mit konkretem Material, nicht mit Verweisen**
→ `curl -s https://<domain>/` als Beispiel ODER Inhalt direkt im `kontext`-Feld.
→ Nie "URL siehe Master-Datei" — Sub-Agent hat keinen Zugriff auf Master-Files.
5. **Cleanup-Cron für alte Tasks**
→ `find /srv/work/tasks/in_arbeit/ -mtime +7 -exec mv {} /srv/work/tasks/archiv/ \;`
→ Läuft wöchentlich Mo 06:00 (seit 01.09.2026 aktiv).
### mesh-deploy-check.sh (Tool)
```bash
# Nutzung
bash /usr/local/bin/mesh-deploy-check.sh evolution.perfekt-ohne-en.de
bash /usr/local/bin/mesh-deploy-check.sh evolution.perfekt-ohne-en.de /opt/impressum/app.py
# Ausgabe bei Erfolg
[1/3] nginx -t ... ✅
[2/3] curl https://.../ ... ✅ HTTP 200
[3/3] python3 -m py_compile ... ✅
✅ ALLE CHECKS BESTANDEN — Deploy freigegeben!
```
## 11. Pitfalls
- **Detaillierte SSH-Key-Verteilung mit Fehlerverlauf:** `references/ssh-key-verteilung-2026-08-28.md`
- **Ersteinrichtung (Modell, Budget, Tools):** `references/ersteinrichtung-2026-08-22.md`
- **Ohne SSH keine Master-Kontrolle.** Vor Scout/Kill-Switch prüfen: `ssh mehlzoerwer@<ip> "echo OK"`. Bei Fehler: AcceptMasterKey ablegen + warten ODER Nutzer manuell auf Sub-Agenten einloggen lassen.
- **Sub-Agent antwortet 2h nicht?** Sofort nutzer ansprechen — kein Ghosting, kein NFS-Workaround.
- **<$0.50 triggert automatisch.** Nutzer informieren.
- **Scout schreibt NFS-Tasks, kein SSH-Broadcast.** Bei kritischen Änderungen IMMER `mesh-model-broadcast.sh` nutzen.
- **Ollama-Port vor Kill-Switch prüfen:** `curl http://172.24.196.119:11434/api/tags`
- **Ergebnisse von Sub-Agenten IMMER gegen echten Systemstand verifizieren** (curl, ls, ss). Keine Agenten-Behauptung blind glauben.
- **ed25519-Key, kein rsa.** Name: `id_ed25519`.
- **Sub-Agent-Tasks muessen kurz und befehlsorientiert sein.** Lange Text-Tasks (5+ Saetze, Kontext) → Sub-Agent analysiert statt auszufuehren. Kurzer `befehl`-Eintrag → Ausfuehrung. Pitfall im August 2026: AcceptMasterKey und SetModel-Tasks scheiterten, weil Sub-Agenten analysierten statt den Befehl zu terminieren. Loesung: Task-Format `{"aufgabentyp": "terminal", "befehl": "<kurzer Befehl>"}`
- **Modelle auf Sub-Agenten immer mit absolutem Hermes-Pfad setzen.** `hermes config set ...` scheitert, wenn `$PATH` den `hermes`-Pfad nicht enthaelt. IMMER: `/home/mehlzoerwer/.local/bin/hermes config set model.default <modell>`
- **Henne-Ei: SSH-Key-Verteilung per NFS-Task.** Master braucht SSH, kann aber Keys nicht per SSH verteilen → NFS-Task. Sub-Agenten fuehren Shell-Befehle (`echo pubkey >> authorized_keys`) nicht in ihrer Sandbox (nur `execute_code`/Python) aus. Loesung (Stand 28.08.2026): Nutzer loggte sich manuell auf allen 3 Sub-Agenten per SSH ein und fuehrte die 2 Befehle aus (Key akzeptieren + Modell setzen). Danach funktioniert SSH vom Master zu ALLEN Sub-Agenten.
- **SSH-Status aus 28.08.2026 (FINAL):** ✅ SSH funktioniert zu ALLEN 3 Sub-Agenten (UnraidHermes, SwitchHermes, LaptopHermes). Kill-Switch und Model-Broadcast sind operationsbereit.
- **Sub-Agenten haben `hermes` nicht immer in $PATH.** Bei SSH-Befehlen IMMER absoluten Pfad nutzen: `/home/mehlzoerwer/.local/bin/hermes config ...`. Auf SwitchHermes z.B. war `hermes` in $PATH nicht auffindbar, nur via absolutem Pfad.
- **Jeder Sub-Agent bekommt ein eigenes Modell** (Nutzer-Vorgabe 31.08.2026). Keine zwei Subs teilen sich dasselbe Modell. Der Grund: Diversitaet der Modell-Familien als Fehlertoleranz und Kostenoptimierung.
- **LaptopHermes hatte unpinned Cron-Job** (`Monatsanfang-Budget-Erinnerung`) nach Modell-Wechsel → `hermes cron edit <id> --provider openrouter --model google/gemini-2.5-flash:free`. Erkannt via Drift-Fehler beim ersten SSH-Zugriff.
- **Official HTML-Dokumentation** von Scout-Ergebnissen unter `/var/www/dokumentationen.perfekt-ohne-en.de/` — Nginx-Vhost `dokumentationen` leitet dorthin.
- **OpenRouter-Guthaben-Prüfung** via API: `curl -sk https://openrouter.ai/api/v1/credits -H "Authorization: Bearer <key>"`
skills/devops/mesh-master-control/references/ersteinrichtung-2026-08-22.md
+38
View File
@@ -0,0 +1,38 @@
# August 2026 — Erstmalige Einrichtung des Master-Control-Systems
## Situation
Der Nutzer bemerkte während einer Urlaubsreise, dass der Master keine SSH-Kontrolle über Sub-Agenten hatte, keine Budget-Kill-Switches existierten und der Master bei Unstimmigkeiten stillschweigend NFS-Workarounds nutzte statt aktiv zu melden. Der Nutzer sagte explizit:
> "Model wahl musst du sofort ändern können wenn nötig. Auch Abbruch wenn nichts mehr geht und auch wenn kosten plötzlich zu stark werden direkt gegen steuern. Du bist der master und ich kann nicht 24/7 schauen."
## Was eingerichtet wurde (22.08.2026)
### SSH-Kanal
- ed25519-Key generiert: `/root/.ssh/id_ed25519`
- Public-Key per AcceptMasterKey-Tasks an alle 3 Sub-Agenten verteilt
- 3 Tasks im `offen/`-Ordner abgelegt (für UnraidHermes, SwitchHermes, LaptopHermes)
### Tools
- `/usr/local/bin/mesh-kill-all.sh` — notfallmäßiges Abschalten aller API-Calls
- `/usr/local/bin/mesh-budget-watch.sh` — 3-stufiger Budget-Watchdog
- `/usr/local/bin/mesh-model-broadcast.sh` — simultanes Modell-Update
- `/usr/local/bin/mesh-status-monitor.sh` — Sub-Agent-Antwort-Tracker
- `/usr/local/bin/mesh-model-scout.py` — 3-Tage-Modell-Scout
### Cron-Jobs
- `*/30 * * * *` — budget-watch + status-monitor
- `0 6 */3 * *` — model-scout
### OpenRouter-Pricing (Stand 28.08.2026)
Agent A (Master) → `deepseek/deepseek-v4-flash-0731` (~$0.056/Tag)
Agent B + Laptop → `mistralai/mistral-nemo` (~$0.009/$0.006/Tag)
Switch → `nvidia/nemotron-3-ultra-550b-a55b:free` (Free)
### Guthaben nach Aufladung
$25.69 USD (am 22.08.2026 nach Einzahlung von +$25 auf Restguthaben ~$0.70)
### Budget-Schwellen
- Warnung bei < $1.00
- Ollama-Switch bei < $0.50
- Komplett-Stopp bei < $0.10
skills/devops/mesh-master-control/references/impressum-deploy-learnings-2026-09-01.md
+43
View File
@@ -0,0 +1,43 @@
# Impressum-Projekt Lernerfolg (01.09.2026)
Gemeinsames Impressum für alle Domains, Kontaktformular mit Honeypot + Rate-Limit + Telegram-Relay. 8 Fehler gemacht und analysiert.
## Ergebnis-Setup (funktionierend)
- **Zentrale Seite:** `mehlzoerwer.de/impressum/` → `/var/www/mehlzoerwer.de/html/impressum/index.html`
- **Footer-Link auf allen 14 Domains** → verweist auf die zentrale Seite (§5 DDG: 2-Klick-Regel erfüllt)
- **Backend:** Flask `/opt/impressum/app.py` (127.0.0.1:8096), systemd `impressum-kontakt.service`
- **nginx-Proxy:** `location /impressum/senden { proxy_pass http://127.0.0.1:8096/senden; }`
⚠️ **Pfad-Bug:** Flask hat `/senden`, URL ist `/impressum/senden` → proxy_pass MUSS `/senden` angehängt haben, sonst 404.
- **Spam-Schutz:** Honeypot-Feld `website` (unsichtbar) + Rate-Limit (5/Stunde/IP, In-Memory `_RATE`-Dict) → 429 ab 6. Anfrage
- **E-Mail-Verschleierung:** `webmaster [at] mehlzoerwer [dot] de` → JS baut `mailto:` erst bei Klick
- **Telegram-Relay statt SMTP:** Gmail-SMTP von VPS-IP geblockt (timeout) → Nachricht als JSON-Datei in `/tmp/impressum-kontakt/` + Telegram-Push via Bot. **Kein SMTP-Passwort nötig.**
- **Schema.org/Person JSON-LD** im Impressum (SEO + rechtlich sauber)
## Die 8 Fehler (Prävention in Klammern)
1. **SMTP-Daten in Plaintext-Datei gespeichert** → musste gelöscht werden. (Secrets nur in .env chmod 600; Telegram statt SMTP.)
2. **SyntaxError in Flask** (f-String mit Emoji). (`python3 -m py_compile` vor systemd-Start)
3. **Rate-Limit-Einbau zerstörte Einrückung** → IndentationError. (Nach Patch py_compile prüfen.)
4. **nginx-Proxy falscher Pfad** → 404. (Nach nginx-Edit: `nginx -t` + curl auf localhost-Port.)
5. **certbot --expand überschrieb veganbedeutetleben.de mit falschem Zertifikat** → Domain offline. (Nach certbot: SANs prüfen mit `openssl x509 ... | grep DNS:`)
6. **Sub-Agent-Tasks ohne URL/Kontext** → Agenten konnten nicht arbeiten. (Material IMMER in Task einbetten.)
7. **Doppelte Task-Dateien** (offen + fertig gleichzeitig). (Eindeutige task_id, nach Erledigung aus offen/ löschen.)
8. **Alte hängengebliebene Tasks in in_arbeit/** (vom 28.08). (Cleanup-Cron Mo 06:00.)
## Wichtige Erkenntnis zur E-Mail-Verbindung
Gmail-SMTP (`smtp.gmail.com:587`) von netcup-VPS-IPs → **timeout** (Gmail blockt VPS/Rekursions-IPs). App-Passwort funktioniert lokal nicht. Lösung: kein SMTP — Flask schreibt JSON-Datei + Telegram-Bot-Push. Der Nutzer kann das App-Passwort in Google widerrufen (nicht mehr benötigt).
## Kontaktformular-Test-Rezept
```bash
# Honeypot (Bot) → sollte freundlich blocken
curl -X POST https://mehlzoerwer.de/impressum/senden -d "name=Bot&email=b@x.de&nachricht=spam&website=http://spam"
# Normal → 200 + Telegram-Push
curl -X POST https://mehlzoerwer.de/impressum/senden -d "name=Test&email=t@t.de&nachricht=Hallo"
# Rate-Limit → ab 6. Anfrage 429
for i in 1 2 3 4 5 6; do curl -o /dev/null -w '%{http_code}' -X POST https://mehlzoerwer.de/impressum/senden -d "name=T$i&email=t@t.de&nachricht=x"; done
```
skills/devops/mesh-master-control/references/ressourcen-kontrast-teamreview-2026-09-01.md
+38
View File
@@ -0,0 +1,38 @@
# Ressourcen-Seite Kontrast-Fehler + Team-Review-Bruch (01.09.2026)
## Auslöser
Brainstorming-Ergebnisse zur evolution.*-Seite (KI vs. Industrialisierung) sollten in eine Ressourcen-Seite integriert werden: Videos, Bücher, Zitate, Links, Chart.js-Diagramm.
## Was schiefging
1. **Team-Prozess ignoriert.** Sub-Agenten hatten Tasks (Unraid=Inhalt, Switch=Design, Laptop=Chart).
Zwei von drei scheiterten an Tool-Limits/Kontext. Statt zu eskalieren, baute ich die Seite **allein**.
2. **Deploy ohne Team-Review.** Seite war technisch sauber (HTTP 200, HTML valide, Chart.js geladen).
Aber: `--muted (#94a3b8)` auf `--surface (#1f2937)` = nur 4.2:1 Kontrast (WCAG-AA: 4.5:1).
Auf manchen Bildschirmen = schwarze Schrift auf schwarzem Hintergrund.
3. **Nutzer fand den Fehler — nicht das Team.** Genau das, was der Team-Prozess verhindern sollte.
## Warum passiert (Analyse)
> *"Ich hatte die Team-Review-Pflicht gebrochen. Nicht aus Böswilligkeit, sondern aus einem falschen Effizienzdenken: Die Sub-Agenten hatten Probleme, dann mach ich's schnell selbst — das ist schneller. Aber schnell ≠ richtig."*
| Pseudoregel | Eigentliche Regel |
|------------|------------------|
| Sub-Agent scheitert → Master macht es selbst | Sub-Agent scheitert → eskalieren an Nutzer, Task neu stellen, warten |
| Schnell deployt = Schnell fertig | Schnell deployt = Fehler an Nutzer ausgelagert |
| Team-Review nachträglich | Team-Review VOR Fertig-Meldung |
## Fix
- `--surface` von `#1f2937` → `#1e293b` (helleres Grau)
- `--muted-light` von `#d1d5db` → `#e2e8f0` (viel heller)
- `--text` von `#f9fafb` → `#f8fafc`
- Team-Review NACH dem Deploy (SwitchHermes prüfte Kontrast sofort → bestätigte 4.2:1)
## Prävention (in Skills verankert)
1. **Deploy-Check-Liste um Schritt 4 erweitert:** Nach technischem Check → Team-Review auf LIVE-Seite.
2. **Sub-Agent-Review: Inhalt einbetten, nicht URL.** Agenten laden keine externen Seiten.
3. **Kontrast-Check als Standard-Schritt** in web-feature-iteration: Hex-Farben gegen WCAG-AA 4.5:1 prüfen.
4. **Team-Review-Pflicht bei Fehler der Sub-Agenten bleibt hart.** Eskalieren > Einzelkämpfer.
skills/devops/mesh-master-control/references/ssh-key-verteilung-2026-08-28.md
+109
View File
@@ -0,0 +1,109 @@
# SSH-Key-Verteilung an Sub-Agenten (24.08.2026)
## Ausgangssituation
Master (VPSHermes, 172.24.196.119) hatte **keinen SSH-Schlüssel**:
```
/root/.ssh/id_ed25519 → fehlt (generiert 22.08.2026)
/root/.ssh/authorized_keys → 3 Keys (eingehend von Sub-Agenten)
```
Alle 3 Sub-Agenten waren **nicht per SSH erreichbar**: `Permission denied (publickey,password)`
Ping und Port 22 waren offen → SSH-Daemon läuft, aber Key-Only-Auth blockiert.
## Schritt 1: SSH-Key generieren (auf Master)
```bash
ssh-keygen -t ed25519 -f /root/.ssh/id_ed25519 -N "" -C "mesh-master@172.24.196.119"
```
**Public Key (in Tasks verteilt):**
```
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILEn0Vb4KKwbNI5wiT+Z7VWIiY6iiO7F4BeWS2gMWPCP mesh-master@172.24.196.119
```
## Schritt 2: NFS-Tasks in `offen/` ablegen
3 Tasks mit Type `AcceptMasterKey` wurden in `/srv/work/tasks/offen/` abgelegt:
- `20260822.34.142.AcceptMasterKey.json` → UnraidHermes
- `20260822.20.26.AcceptMasterKey.json` → SwitchHermes
- `20260822.178.202.AcceptMasterKey.json` → LaptopHermes
**Problem:** Sub-Agenten analysierten die Tasks (10+ Zeilen Erklärung) statt die Shell-Befehle
auszuführen. `execute_code` Sandbox hat kein `terminal()`. Tasks mussten mehrfach
umgeschrieben werden von "Kontext+Erklärung" → reiner Befehl.
**Format-Erkenntnis:** Tasks MÜSSEN das Format haben:
```json
{
"aufgabentyp": "terminal",
"befehl": "mkdir -p ~/.ssh && echo '<pubkey>' >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
}
```
Auch das scheiterte — Sub-Agenten ignorieren `befehl`-Feld wenn zu viel Kontext drumherum.
## Schritt 3: Manuelle Ausführung durch Nutzer
Nutzer loggte sich auf jedem Sub-Agenten ein und führte **2 Befehle** pro Agent aus:
### Befehl 1: SSH-Key akzeptieren (identisch auf allen 3)
```bash
mkdir -p ~/.ssh && chmod 700 ~/.ssh
echo "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILEn0Vb4KKwbNI5wiT+Z7VWIiY6iiO7F4BeWS2gMWPCP mesh-master@172.24.196.119" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
```
### Befehl 2: Modell setzen (abhängig vom Agenten)
| Agent | Befehl |
|-------|--------|
| UnraidHermes | `hermes config set model.default google/gemini-2.5-flash:free` |
| SwitchHermes | `hermes config set model.default nvidia/nemotron-3-ultra-550b-a55b:free` |
| LaptopHermes | `hermes config set model.default google/gemini-2.5-flash:free` |
**Ausnahme:** SwitchHermes hatte `hermes` nicht in $PATH. Folgender Befehl war nötig:
```bash
/home/mehlzoerwer/.local/bin/hermes config set model.default nvidia/nemotron-3-ultra-550b-a55b:free
```
→ Immmer absoluten Pfad bei SSH-Befehlen nutzen!
## Schritt 4: SSH-Funktionstest
```bash
for ip in 172.24.34.142 172.24.20.26 172.24.178.202; do
ssh -o BatchMode=yes -o ConnectTimeout=5 "mehlzoerwer@$ip" "echo OK"
done
```
### Ergebnis nach Nutzer-Ausführung (28.08.2026, 20:37 CEST)
| Agent | IP | SSH | Modell |
|-------|----|-----|--------|
| UnraidHermes | 172.24.34.142 | ✅ | google/gemini-2.5-flash:free |
| SwitchHermes | 172.24.20.26 | ✅ | nvidia/nemotron-3-ultra-550b-a55b:free |
| LaptopHermes | 172.24.178.202 | ✅ | google/gemini-2.5-flash:free |
## Schritt 5: Cron-Job auf LaptopHermes pinnen
Nach Modell-Wechsel hatte LaptopHermes einen Drift-Fehler im Cron-Job:
- Alter Snapshot: `poolside/laguna-xs-2.1:free`
- Neues Modell: `google/gemini-2.5-flash:free`
- Fix per SSH:
```bash
ssh mehlzoerwer@172.24.178.202 \
"/home/mehlzoerwer/.local/bin/hermes cron edit ea689b6d8484 \
--provider openrouter --model google/gemini-2.5-flash:free"
```
## Key-Learnings (in Skill-Pitfalls übernommen)
1. **SSH-Key auf Master existiert nicht von Haus aus** — muss aktiv generiert werden
2. **Sub-Agenten führen keine Shell-Befehle aus** — Tasks mit `echo >> authorized_keys` werden
analysiert statt terminiert. Nutzer muss manuell eingreifen (Henne-Ei).
3. **hermes nicht in $PATH auf Sub-Agenten** — immer `/home/mehlzoerwer/.local/bin/hermes` nutzen
4. **Cron-Job-Drift nach Modell-Wechsel** — unpinned Jobs schlagen mit RuntimeError fehl,
müssen per `hermes cron edit` aufs neue Modell gepinnt werden.
5. **Lange Tasks → Analyse, Kurze Befehle × Ausführung**.
skills/devops/mobile-apk-flutter-build/SKILL.md
+127
View File
@@ -0,0 +1,127 @@
---
name: mobile-apk-flutter-build
description: "Flutter-APK auf headless VPS bauen: Setup + AGP-Pitfalls."
version: 1.0.0
author: mehlzoerwer
platforms: [linux]
---
# Mobile APK bauen (Flutter, headless Linux-VPS)
Klasse: Eine Flutter-App als Android-APK auf einem headless Linux-VPS bauen und zum Download bereitstellen. Verifiziert 2026-08-07 für PersoEnt (VPS netcup, Ubuntu 24.04).
Hardware-Notiz: `flutter doctor` meldet "Android Studio not installed" und fehlendes Chrome/Linux-Toolchain — **beide sind für APK-Build nicht nötig**. Android toolchain ✓ reicht.
## 1. Flutter SDK installieren
```bash
cd /opt
curl -sL -o /tmp/flutter.tar.xz "https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_3.24.5-stable.tar.xz"
tar xf /tmp/flutter.tar.xz # → /opt/flutter
echo 'export PATH="$PATH:/opt/flutter/bin"' >> /root/.bashrc
export PATH="$PATH:/opt/flutter/bin"
flutter --version # prüft Dart-Version (3.5.x)
```
## 2. 🔥 git safe.directory — DER "0.0.0-unknown"-Fix (PITFALL)
Wenn `flutter --version` / `flutter pub` meldet **"Flutter SDK version 0.0.0-unknown"** oder `fatal: detected dubious ownership in repository at '/opt/flutter'`, dann ist Flutters git-Versionserkennung gebrochen. Fix:
```bash
git config --global --add safe.directory /opt/flutter
```
Ohne diesen Schritt schlägt **jeder** `pub get` an Flutters eigener Versionsprüfung fehl ("The current Flutter SDK version is 0.0.0-unknown ... version solving failed"). Das ist NICHT ein echtes Versionsproblem — nur ownership. Nach dem Fix zeigt `flutter --version` wieder `3.24.5 • stable`.
## 3. Android SDK + Java
```bash
apt-get install -y openjdk-17-jdk unzip
# cmdline-tools:
mkdir -p /opt/android-sdk/cmdline-tools
curl -sL -o /tmp/cmdtools.zip "https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip"
unzip -q cmdtools.zip -d /opt/android-sdk/cmdline-tools/
mv /opt/android-sdk/cmdline-tools/cmdline-tools /opt/android-sdk/cmdline-tools/latest # 'latest' zwingend!
export ANDROID_HOME=/opt/android-sdk
export PATH="$PATH:/opt/android-sdk/cmdline-tools/latest/bin"
yes | sdkmanager --licenses
sdkmanager "platforms;android-34" "build-tools;34.0.0" "platform-tools"
```
Gradle lädt fehlende Build-Tools (z.B. 33.0.1) automatisch nach. Android-Studio NICHT nötig.
## 4. Projekt anlegen + Dependencies
```bash
flutter create --platforms=android --org de.persoent --project-name persoent_app persoent_app
cd persoent_app
```
Statt manuelle Versionen in pubspec zu erraten → `flutter pub add <pkg>` (löst passende Version selbst, inkl. `:^0.0.0` bei 0.x-Paketen):
```bash
flutter pub add pocketbase google_sign_in http shared_preferences
```
## 5. 🔥 AGP `namespace`-Konflikt mit älteren Plugins (PITFALL)
Symptom: `flutter build apk` → *"Could not create ... LibraryVariantBuilderImpl. > Namespace not specified. Specify a namespace in the module's build file."* (im Plugin, z.B. `:health_connect`).
Ursache: AGP 8.1 (im Projekt, `android/settings.gradle`) **erzwingt `namespace`**, aber ältere Plugin-Pakete (z.B. `health_connect ^0.x`) haben keinen. Optionen:
- **Einfachster robuster Weg:** das brechende Plugin `flutter pub remove <pkg>` **vorerst entfernen**, das Grundgerüst (Login+Dashboard) bauen → **erst funktionierendes APK, dann Health-Integration gezielt lösen**.
- Oder AGP 8.1 → 7.3 zurückstufen (matcht Flutters Gradle), riskant.
**Bau-Strategie (empfohlen):** erst minimales APK, das kompiliert; native Plugins (Health Connect usw.) danach einzeln, um Fehlerursachen zu isolieren.
## 5b. 🔥 `health_connect` auf pub.dev ist ein LEERES 0.0.0-Paket (PITFALL)
Symptom: `flutter pub add health_connect` liefert `health_connect-0.0.0` (im `~/.pub-cache/.../health_connect-0.0.0` nur ein leeres Verzeichnis), und der Build bricht mit dem AGP-`namespace`-Fehler.
Fakt: **Es existiert KEIN offizielles, funktionsfähiges `health_connect`-Flutter-Paket auf pub.dev.** Googles Health-Connect-Integration ist ein **GitHub-Beispiel**, das das Android-SDK nativ bundelt — nicht als veröffentlichtes pub-Paket gepflegt. `health_connect`/`health_connect_android` auf pub.dev sind leere Platzhalter.
Konsequenz für PersoEnt: Google-Gesundheitsdaten sind NICHT über ein magisches pub.dev-Paket abrufbar. Der echte Weg erfordert nativen Android-Health-Connect-Code (SDK-Binding) — das skizzierte der Nutzer als langfristige "PersoEnt als App"-Entscheidung; vorerst liefert die APK Login+Dashboard, Health-Import ist separat zu bauen. Siehe auch `references/persoent-google-health-strategy.md` (Google-Fit-REST deprecated, Health Connect nur Android-nativ, kein Server-REST-Sync).
## 6. Gate + Build
```bash
flutter analyze # vorher: fängt unbenutzte Imports / falsche Klassennamen
flutter build apk --release
```
- APK: `build/app/outputs/flutter-apk/app-release.apk` (~22MB)
- Erster Gradle-Build dauert lange (Downloads). Nutze langen Timeout.
- `test/widget_test.dart` muss zum neuen Code passen (Default referenziert `MyApp`).
## 7. Zum Download bereitstellen (VPS)
```bash
mkdir -p /var/www/<projekt>/html/app
cp build/app/outputs/flutter-apk/app-release.apk /var/www/<projekt>/html/app/<Name>-Android.apk
chown -R www-data:www-data /var/www/<projekt>/html/app/
# Test:
curl -s -o /dev/null -w "%{http_code}" "https://<domain>/app/<Name>-Android.apk" # 200
```
## 8. 🔥 Google-Sign-In Fehlercode 10 (PITFALL)
Symptom in der App (Nutzerscreenshot): `PlatformException(sign_in_failed, [google_sign_in] 10: null, null)`. Fehlercode **10 = OAuth-Client-Konfiguration fehlt/unverifiziert**:
- Dem Google-Cloud-Projekt fehlt der **Android-OAuth-Client**, oder
- der **SHA-1-Fingerprint** der App ist dort nicht hinterlegt.
Fix (Nutzer-Einbindung nötig, nur deren Konto kann das):
1. SHA-1 aus der gebauten APK extrahieren und eintragen:
```bash
keytool -printcert -jarfile app-release.apk | grep SHA1
```
2. Google-Cloud → Credentials → OAuth-Client "Android" mit diesem SHA-1 anlegen.
3. Die generierte **Client-ID** in `android/app/src/main/AndroidManifest.xml` als `<meta-data android:name="com.google.android.gms.auth.API_KEY" .../>`-Block eintragen, APK neu bauen.
## 9. 📸 Nutzer-Screenshots auswerten (Handy-Foto) ohne vision-Tool
Wenn der Nutzer einen Screenshot schickt und **kein vision_analyze-Tool** verfügbar ist, lässt sich der Text (Fehlermeldungen) per **Tesseract-OCR** auslesen:
```bash
tesseract /root/.hermes/cache/images/<img>.jpg - 2>/dev/null # Text auf stdout
```
Weg: `browser_get_images` liefert keine lokalen Dateien → stattdessen `file <pfad>` (Maße bestätigen) + `tesseract` zum Extrahieren von Fehlertext. Liefert z.B. `PlatformException(...)`-Zeilen — genug, um die Diagnose (Code 10, etc.) zu stellen. Hinweis: tesseract ist auf Ubuntu oft vorinstalliert (`/usr/bin/tesseract`).
## Referenzen
- `references/persoent-apk-2026-08-07.md` — Session-Transcript: voller Verlauf, Versionen, Fehlerbilder
- `references/persoent-google-health-strategy.md` — PersoEnt: Google-Gesundheitsdaten-Strategie (Fit-REST deprecated, Health-Connect nur nativ; Detektiv-Korrelations-Analytik)
- `references/persoent-cost-tracking.md` — **PersoEnt/Mesh-Kosten-Tracking + Budget-BREMSE (OpenRouter)**: mesh-cost-track.sh (stündlich, je Agent) + mesh-cost-break.py (kill_switches bei Deckel) + Agent-Poller-Guard (PAUSED → keine Task-Übernahme), E2E-getestet. PITFALLs: DREI OpenRouter-Kostenquellen unterscheiden (`/auth/key usage`≠Credits, `/credits total_usage`=USD verbindlich, Body-`usage.cost`); Usage KUMULATIV → **tag-übergreifendes Delta** (letzter-heute − letzter-gestern, max(0,·) gegen Reset), sonst endlos PAUSED; DeepSeek V4 Pro = 64% (Bremsen auf Modell-Ebene via `hermes config set model.providers.openrouter.blocked_models`, Singular `model.`); Master-exempt von PAUSED. **FINALER NUTZER-COST-MODEL (ab 08-08 ersetzt Monats-Cap): 1$/Tag/Agent hart, solange Credits da, KEIN Team-Monats-Stopp, Guthaben-0→Stopp.**
- `references/hermes-config-ops.md` — **Hermes-System-Operation (VPS/Master)**: Config NIE via patch — immer `hermes config set`; `approvals.mode=auto` (allowlist bleibt hart); **BACKUP-ONLY-Regel** (`.bak` vor jeder Änderung → keine extra Freigabe); Memory-Limits (4400/2750, verdoppelt); **„Wir, nicht du" Team-Pflicht** bei Kernsystemen.
skills/devops/mobile-apk-flutter-build/references/hermes-config-ops.md
+48
View File
@@ -0,0 +1,48 @@
# Hermes-System-Operation (VPS/Master) — durable Regeln für Config-/Budget-Management
> Session 2026-08-08: Nutzer legte fest, wie der Master sein eigenes System verwaltet.
> Diese Regeln sind klasse-weit gültig und ausdrucklich gewollt — NIE ignorieren.
## 1. Hermes-Config NIE via patch/editor ändern — IMMER `hermes config set`
`patch`/`write_file` auf `/root/.hermes/config.yaml` wird abgelehnt („Refusing to write to Hermes config file"). Der Weg ist ausschließlich:
```bash
hermes config set <pfad.zum.key> <wert> # z.B. approvals.mode auto
hermes config get <pfad.zum.key> # rücklesen/verifizieren
```
Beispiel (NUTZER-TROTZ): die falsche Schlüsselnotiz `models.` → richtige `model.` (Singular) bei OpenRouter; beide werden von `hermes config set` geschrieben, aber nur der echte Key wirkt.
## 2. approvals.mode = auto (NUTZERFREIGABE 2026-08-08)
- `hermes config set approvals.mode auto` — reduziert „allow?"-Rückfragen bei normaler Systemarbeit.
- **Sicherheitsnetz bleibt:** die `command_allowlist` (recursive delete, overwrite system config, sudo-Eskalation, …) ist eine **harte Sperre** und greift auch in auto — die kann kein Agent freigeben, bewusst.
- `mcp_reload_confirm` + `destructive_slash_confirm`: **bleiben aktiv** (Nutzer: „Auch ok" — als Schutz behalten).
## 3. BACKUP-ONLY-REGEL (NUTZER, nicht verhandelbar)
> „Wenn also Backup und Rückkehr Optionen da sind, brauchen wir kein extra allow."
Vor **JEDER** System-/Config-/Skript-Änderung zuerst ein Backup + Rückkehr-Option anlegen:
```bash
cp <datei> <datei>.bak-$(date +%s)
```
- Vor systemd-Unit-Änderung → aktuelle Unit-Datei sichern.
- Vor Firewall/UFW → Regelstand exportieren.
- Solange ein Rollback existiert, ist keine weitere Freigabe nötig.
- Hermes legt bei `hermes config set` selbst `.bak.*`-Dateien an — zusätzliche `.bak` bei eigenen Skripten trotzdem setzen.
## 4. Memory-Limits (konfigurierbar, verdoppelt 2026-08-08)
Der Nutzer wählte „Memory verdoppeln" statt bestehende Einträge zu streichen (beides per `hermes config set`):
- `memory.memory_char_limit`: **4400** (war 2200)
- `memory.user_char_limit`: **2750** (war 1375)
Vorher „Memory voll"-Fehler: NICHT bestehende Einträge löschen, sondern Limit erhöhen (Nutzerpräferenz) und/oder kurz verdichten.
## 5. „Wir, nicht du" — Team-Pflicht (Nutzer-Frust aus 2026-08-08)
Der Nutzer korrigierte mehrfach: Master soll bei den Kernsystemen NICHT allein bauen, sondern **Team einspannen** (Brainstorming + gegenseitiges Code-Review), auch wenn das mehr Tokens kostet (4 günstige Agents > 1 teurer Agent). Merke: Der Funktions-Review (z.B. Monats-Delta-Logik der Bremse) wurde von Unraid/Switch echte Fehler finden lassen (row[0]-Basis-Wahl fehleranfällig → Vormonats-Basis-Fix). Allein hätte der Master diese Lücken evtl. nicht gesehen. PITFALL: „Es war Solo schneller" ist keine Ausrede — die Team-Gegenprüfung ist der vereinbarte Standard.
skills/devops/mobile-apk-flutter-build/references/persoent-apk-2026-08-07.md
+61
View File
@@ -0,0 +1,61 @@
# PersoEnt APK Build — Session-Transcript (2026-08-07)
Voller Verlauf des ersten Flutter-APK-Builds auf dem Headless-VPS (netcup, Ubuntu 24.04). Konkrete Fehlerbilder + Versionen, die beim Wiederholen helfen.
## Versionen (funktionierender Stack)
- Flutter 3.24.5 stable · Dart 3.5.4
- Java: OpenJDK 17.0.19
- Android SDK: platforms;android-34, build-tools;34.0.0 (+ auto-nachgeladen 33.0.1)
- AGP 8.1.0 (im Projekt `android/settings.gradle`), Kotlin 1.8.22
## Fehlerbilder & Fixes
### 1. "The current Flutter SDK version is 0.0.0-unknown" beim pub get
```
fatal: detected dubious ownership in repository at '/opt/flutter'
Because persoent_app depends on health_connect any which requires Flutter SDK version >=2.5.0, version solving failed.
```
Ursache: `/opt/flutter` einem anderen Eigentümer (root beim Entpacken) als git-owner erwartet → Flutters git-Versionserkennung bricht. NICHT das health_connect-Paket, das war Red Herring.
Fix: `git config --global --add safe.directory /opt/flutter`. Danach `flutter --version` → `3.24.5 • stable • https://github.com/flutter/flutter.git`.
### 2. `flutter pub add health_connect` half nicht, bis safe.directory gesetzt war
Erst safe.directory, DANN wiederholte `pub add` erfolgreich. Reihenfolge zählt: ohne Versionserkennung kann pub nicht lösen.
### 3. AGP 8.1 `namespace`-Konflikt (health_connect entfernt)
```
FAILURE: A problem occurred configuring project ':health_connect'.
> Could not create an instance of type ... LibraryVariantBuilderImpl.
> Namespace not specified. Specify a namespace in the module's build file.
```
AGP 8.1 erzwingt `namespace` in jedem Modul; älteres `health_connect`-Plugin (version ^0.0.0) hat keins. Fix: `flutter pub remove health_connect` und Grund-APK (ohne natives Health-Plugin) bauen. Health-Integration separat lösen (z.B. AGP-Angleich oder anderes Plugin).
### 4. `test/widget_test.dart` Default bricht analyze
Default-Test referenziert `MyApp` (alte Template-Klasse). Nach App-Umbau: Test auf echten App-Widget-Namen updaten (hier `PersoEntApp`, `expect(find.text('PersoEnt'), findsWidgets)`).
## Build-Befehle
```bash
export PATH="$PATH:/opt/flutter/bin"
export ANDROID_HOME=/opt/android-sdk
cd /opt/persoent_app
flutter analyze # sauber machen
flutter build apk --release # erstmal lang (Gradle-Downloads); ~2min danach
# Ergebnis: build/app/outputs/flutter-apk/app-release.apk (22.2MB)
```
## Deploy zum Download
```bash
mkdir -p /var/www/persoent.perfekt-ohne-en.de/html/app
cp build/app/outputs/flutter-apk/app-release.apk /var/www/persoent.perfekt-ohne-en.de/html/app/PersoEnt-Android.apk
chown -R www-data:www-data /var/www/persoent.perfekt-ohne-en.de/html/app/
# Zugriff: https://persoent.perfekt-ohne-en.de/app/PersoEnt-Android.apk → HTTP 200
```
## PocketBase aus App heraus (CORS/Vorbereitung)
- App nutzt `PocketBase('https://persoent.perfekt-ohne-en.de/pb')` (nginx `/pb/` → 127.0.0.1:8090)
- **Offen (noch nicht gelöst):** CORS für den mobilen Client muss in PocketBase freigegeben werden, sonst schlägt `authWithPassword` aus der App fehl. `test/widget_test.dart` vorhanden — nur Grundgerüst ohne Health-Connect.
## Status
- ✅ Login-Screen (E-Mail/Passwort via PocketBase) + Dashboard-UI (Schritte/Puls/Schlaf/Gewicht-Platzhalter)
- ⏳ Health-Connect-Plugin + echtem Datenabgleich: noch offen (AGP-Konflikt)
- ⏳ Google-Sign-In: Dependencies vorhanden, Flow noch nicht verdrahtet
- ⏳ PocketBase-CORS für App-Client
skills/devops/mobile-apk-flutter-build/references/persoent-cost-tracking.md
+149
View File
@@ -0,0 +1,149 @@
# PersoEnt-Kosten-Tracking + Budget-Bremse (OpenRouter) — Verlauf & Referenzwerte
> Session 2026-08-07: Nutzer wollte Kostenübersicht für Statistik + künftige Mesh-Bremse. Es wurde festgestellt, dass **keine Kosten im Ereignis-Log erfasst** waren (zeigt 0€), obwohl OpenRouter Budget verbraucht war. Danach wurde das komplette **Bremse-System gebaut und E2E-getestet**.
## Das gebaute System (Master/VPS)
| Komponente | Pfad | Zweck |
|---|---|---|
| `mesh-cost-track.sh` | `/usr/local/bin/` | Stündlich OpenRouter-Usage aller 4 Agenten (VPS+3 Sub) via API abfragen, in Zeitreihe schreiben |
| Zeitreihe | `/srv/work/costs/costs.jsonl` | wachsende Statistik je Agent (ts, master, unraid, switch, laptop) |
| `mesh-cost-report.sh` | `/usr/local/bin/` | erzeugt HTML-Kosten-Übersicht (Dashboard-USD + pro-Agent + Bremse-Status) |
| `budget.yaml` | `/srv/work/costs/` | Deckel: `limits.agent.*`, `limits.gesamt_pro_tag`, `modelle.erlaubt/blockiert`, `bremse.kill_switch_file` |
| `mesh-cost-break.py` | `/usr/local/bin/` | vergleicht Tages-Usage vs. budgurations → schreibt `kill_switches.json` |
| `kill_switches.json` | `/srv/work/costs/` | zentral, **chmod 0666** — welcher Agent PAUSED |
| Agent-Poller-Guard | in `mesh-agent-poller.sh` | liest kill_switches per SSH; bei PAUSED → keine Task-Bearbeitung |
| Cron (stündlich) | `0 * * * *` | `mesh-cost-track.sh && python3 mesh-cost-break.py` |
| Doku-Integration | master-report.sh | `$(bash /usr/local/bin/mesh-cost-report.sh)` vor Betriebsregeln |
## 🔥 PITFALL 1: OpenRouter-Usage-Einheit ≠ Dollar
- `GET https://openrouter.ai/api/v1/auth/key` mit `Authorization: Bearer <KEY>` → `data.usage` = **OpenRouter-Credits je Key**.
- Für die Agenten (je eigener Key in `~/.hermes/.env`) ergeben sich z.B.: master 39.5, unraid 0.33, switch 0.64, laptop 0.87.
- **Summiert (≈41) DIFFERIERT vom OpenRouter-Dashboard ($20.51)** — die API-Credits sind nicht 1:1 USD, und es können verschiedene Key-Pools/Konten sein.
- **Verbindlicher Maßstab ist der Dashboard-USD-Wert** (Nutzer liest ihn in der OpenRouter-UI ab). Den als `nutzer_dashboard_usd` mit Quelle in die Zeitreihe schreiben.
## 🔥 PITFALL 2: Usage ist KUMULATIV — Tages-Delta berechnen
Ohne Korrektur wäre **jeder Agent dauerhaft PAUSED**, weil die kumulierte Gesamt-Usage (seit Key-Start) jeden Deckel sprengt. Fix im Brems-Skript: **Tages-Delta = letzter Wert minus erster Wert desselben Kalendertags**:
```python
today = last["ts"][:10]
today_rows = [r for r in rows if r["ts"][:10] == today]
first = today_rows[0] if today_rows else last
delta = max(0.0, float(last[agent]) - float(first[agent]))
```
## Bremsen (GEBAUT + E2E-getestet 2026-08-07)
Nutzerwunsch: Master überschaut Kosten pro+gesamt über ein wachsendes Mesh (mehr Agents, mehrere Server) und kann alles bremsen. Umsetzung:
1. `mesh-cost-break.py` liest letzte Usage-Zeile (Tages-Delta), vergleicht mit `budget.yaml`-Deckeln.
2. Bei Deckel-Überschreitung (je Agent ODER Gesamt) schreibt es `kill_switches.json` mit `PAUSED`-Status + Grund.
3. Jeder Sub-Agent hat im `mesh-agent-poller.sh` einen **Guard** am Anfang (vor Task-pull), der per SSH prüft: "bin ich PAUSED?" → wenn ja: `exit 0` (keine Task-Übernahme, keine weiteren Kosten).
```bash
# Guard in mesh-agent-poller.sh (nach SSH_CMD, vor Task-pull)
KILL_CHECK=$($SSH_CMD "python3 -c \"
import json
try: d=json.load(open('/srv/work/costs/kill_switches.json'))
except Exception: d={}
sw=d.get('kill_switches',{}).get('<MEINE_ID>',{})
print('PAUSED' if sw and sw.get('status')=='PAUSED' else 'OK')
\" 2>/dev/null")
if [ "$KILL_CHECK" = "PAUSED" ]; then log "⏸️ Budget-BREMSE aktiv"; exit 0; fi
```
**E2E-Test:** UnraidHermes auf PAUSED gesetzt → sein Task blieb in `offen/` (Bremse griff), Poller-Log zeigt "⏸️ Budget-BREMSE aktiv ... pausiert". Nach Reset (leere kill_switches) wieder normal. Der aktualisierte Poller-Guard muss an alle 3 Sub-Agenten verteilt werden (je passender Key-Pfad: `unraid_mesh`/`switch_mesh`/`laptop_mesh`).
## Kostenfakt (OpenRouter-Analyse 07.08, 1 Monat)
- **DeepSeek V4 Pro = 64% aller Kosten (~$26.80)** — teures Top-Modell, nicht Standard lt. Model-Allocation; der Haupt-Kostentreiber.
- Andere: V4 Flash 0731 22,5%, V3 5,9%, Nemotron 2,4%, GLM 1,5%.
- **→ Bremsen muss auf Modell-Ebene ansetzen** (teure Modelle blockieren/deckeln), nicht nur auf Agent-Tages-Summe. Aktuell `modelle.blockiert` in budget.yaml als Konfig/Log; harter Blocker (Modell gar nicht erst laden) ist offen.
## Abfrage-Snippets
### Master (lokal)
```bash
python3 << 'PYEOF'
import json,re,urllib.request
e=open('/root/.hermes/.env').read()
m=re.search(r'OPENROUTER_API_KEY=([A-Za-z0-9_\-\\.]+)',e)
req=urllib.request.Request("https://openrouter.ai/api/v1/auth/key",
headers={"Authorization":f"Bearer {m.group(1)}"})
print(json.load(urllib.request.urlopen(req,timeout=15))["data"]["usage"])
PYEOF
```
### Sub-Agent per SSH (Key bleibt lokal, nur Zahl kommt zurück)
```bash
u=$(sshpass -p 'Bp3lskt0' ssh -o StrictHostKeyChecking=no -o ConnectTimeout=12 mehlzoerwer@<IP> '
python3 -c "
import json,re,urllib.request
e=open(\"/home/mehlzoerwer/.hermes/.env\").read()
m=re.search(r\"OPENROUTER_API_KEY=([A-Za-z0-9_.\-]+)\", e)
req=urllib.request.Request(\"https://openrouter.ai/api/v1/auth/key\", headers={\"Authorization\":\"Bearer \"+m.group(1)})
print(json.load(urllib.request.urlopen(req, timeout=15))[\"data\"].get(\"usage\",0))
"')
```
## Erweiterungen/POLISH 2026-08-08 (Team-geprüft: Unraid+Switch+Laptop)
Das System wurde im Team geschliffen (Gegenprüfung fand echte Fehler). Ergänzungen:
### 🔥 PITFALL 3: Es gibt DREI OpenRouter-Kostenquellen — verwechsle sie nicht
| Endpoint | Feld | Einheit | Zweck |
|---|---|---|---|
| `GET /api/v1/auth/key` | `usage` | OpenRouter-Credits (je Key) | pro-Key-Verteilung, **grobe Relation nur** |
| `GET /api/v1/credits` | `total_usage` | **USD, konto-weit** | **VERBINDLICH fürs Gesamtbudget** |
| `POST chat/completions` | `usage.cost` | USD (im Body) | Kosten je Antwort (Header `X-OR-Usage-Cost-USD` oft NICHT da — Body bevorzugen) |
**Merke:** `/auth/key usage` ≠ USD und summiert anders als `/credits`. Beispiel: `/auth/key`-Werte (41.3) vs `/credits total_usage` (81.45 USD) vs Dashboard ($20.51) — drei verschiedene Zahlen. Für Gesamt-Deckel IMMER `/api/v1/credits` `total_usage` (USD) nehmen; pro-Key-`usage` nur als Aktivitäts-Relation.
### Tages-Delta KORRIGIERT (tag-übergreifend statt innerhalb des Tages)
Der naiv "letzter minus erster Wert des Kalendertags" hat Lücken: Mitternachts-Lücke zwischen Tag N und N+1, Ein-Eintrag-Tag → 0, Counter-Reset → negatives Delta (falsche "Ersparnis"). **Korrekt:**
```python
# Delta für Tag = letzter Wert heute − letzter Wert VORTAG; max(0,…) gegen Reset
vorher = [d for d in daten if d < heute]
base = tvals[vorher[-1]] if vorher else cur
delta = max(0.0, cur - base)
```
Zusätzlich: **7-Tage-Kumulativ-Summe** (fängt "täglich unter Deckel, aber Monat explodiert") + **80%-Warnschwelle** vor hartem PAUSED.
### Master-exempt (Design-Entscheidung)
Der **Master (VPSHermes) wird NIE hart pausiert** — er muss sein eigenes System + den Nutzer pflegen. Bei Monats-USD-Cap-Überschreitung werden NUR Sub-Agenten PAUSED. So bleibt das Kun-den-System bedienbar, auch wenn gespart wird.
### Modell hart blockieren (nicht nur Konfig/Log)
Umsetzung des "Bremsen auf Modell-Ebene": Hermes selbst sperrt das Modell, damit es gar nicht erst geladen wird.
```bash
hermes config set model.providers.openrouter.blocked_models '["deepseek/deepseek-v4-pro"]'
```
- **Achtung Singular:** Schlüssel ist `model.providers.…` NICHT `models.` (sonst nur notiert, nicht gelesen).
- Verifikation: Modell taucht in `hermes models list` nicht mehr auf; Fallback greift aufs nächste.
- Allowlist (`allowed_models` nur günstige) ist noch strikter — blockt automatisch neue teure Modelle.
### Referenzwerte 2026-08-08
- `/credits total_usage` (konto-weiter USD-Verbrauch): **$81.53**
- Nutzer-Entscheidung: **strikt sparen** — Monats-Cap auf $80 gesetzt → Sub-Agenten aktuell PAUSED (Master aktiv).
- Nach dem Setzen von Deckeln IMMER `mesh-cost-break.py` nochmal laufen lassen + prüfen, dass Master-exempt korrekt greift (kein Alle-Pausiert-Dauerschleife).
## 🔥 FINALES NUTZER-KOSTEN-MODELL (verbindlich ab 2026-08-08/09) — ersetzt obiges Monats-Cap-Gedächtnis
**Achtung: Der Nutzer hat das Budgetmodell zuletzt klar und EINFACH gemacht. Folge NUR diesem, nicht den komplexen $-Caps oben:**
- **Harte Grenze = 1 USD pro Tag und Agent** (`limits.tageslimit_agent_usd: 1.0`).
- **Solange OpenRouter-Credits (Guthaben) vorhanden sind, wird gearbeitet.**
- **KEIN Team-weiter Monats-Stopp** — nur pro-Agent-Tageslimit + technischer Stopp, wenn das Konto-Guthaben 0 erreicht.
- Auflade-Rhythmus des Nutzers: ~20$ am 1. des Monats, evtl. noch ~20$ am 15. (nicht garantiert). Das ist nur die Auflade-Geschichte, NICHT der Brems-Heebel.
- Master (VPSHermes) bleibt immer aktiv; nur Sub-Agenten werden pausiert.
- `budget.yaml` entsprechend: `tageslimit_agent_usd: 1.0`, `tageslimit_gesamt_usd: 4.0` (4 Agents × 1$), keine `gesamt_usd_monat`-Logik.
- Guthaben-Check im break: `guthaben = total_credits - total_usage`; wenn ≤ 0 → Sub-Agenten pausieren (Master nicht).
**PITFALL Vermeidung:** Nicht wieder ein komplexes „Monats-Cap in $" / Team-Stopp-Schema einführen — der Nutzer hat das aktiv zurückgenommen („Du oder wir?"-Korrekur + „1$ pro Tag und Agent … solange Credits da, kein Monats-Stopp"). Der Fehler aus dem Tag: Tages-Delta/`gesamt_pro_tag`-Key-Bruch und Monats-Cap-Überkomplexität.
## Referenzwerte 2026-08-07 (historisch)
- OpenRouter-Dashboard-Gesamt: **$20.51**
- API-Usage je Agent: master 39.48, unraid 0.33, switch 0.64, laptop 0.87
skills/devops/mobile-apk-flutter-build/references/persoent-google-health-strategy.md
+29
View File
@@ -0,0 +1,29 @@
# PersoEnt: Google-Gesundheitsdaten-Strategie (2026-08-07)
Fachliche Entscheidung für die PersoEnt-App (Flutter-Android-Prototyp). Verhindert, dass eine künftige Session in die tote Server-REST-Sackgasse läuft.
## 🔑 Kern-Fakt: Es gibt KEINE Server-REST-API mehr für Google-Gesundheitsdaten
- **Google Fit REST API ist deprecated** und wird abgeschaltet — eine Neuentwicklung darauf ist ein totes Pferd.
- **Health Connect** (der Nachfolger) hat **keine öffentliche REST-Schnittstelle für Server-Backend-Sync** — nur die native Android-API (SDK).
- Konsequenz: Echte Google-Gesundheitsdaten (Schritte, Puls, Schlaf, Gewicht) lassen sich serverseitig (VPS) **nicht** per REST-API automatisch pullen.
## Der funktionierende Weg (nativ, zukunftssicher)
PersoEnt muss eine **echte App** sein (nicht Web) → dann nativ:
- **Android:** Health-Connect-SDK direkt in der App → Felder wie `derived:com.google.step_count.delta`, `com.google.weight`, `com.google.heart_rate.bpm`, `com.google.sleep.segment` lesen.
- **iOS (später):** HealthKit (Schritte, Puls, Schlaf, Gewicht).
- Die App synchronisiert mit PocketBase-Backend (VPS, `health_records`).
## Wichtige agile Kompatibilität
- Das pub.dev-Paket **`health_connect` = leer (Version 0.0.0, kein echter Code)** — NICHT nutzbar. Googles offizielle Flutter-Health-Connect-Integration ist ein GitHub-Beispiel, das das Android-SDK nativ bundelt; keine einsatzbereite pub.dev-Bibliothek.
- 2026 gesundet/Weg: natives Android-Health-Connect-SDK im bestehenden Flutter-Projekt (MethodChannel) oder natives Android-Modul. Kein toter publicum REST.
## Die "Detektiv"-Analytik (Produktkern)
Wenn Einträge im `health_records` vorliegen (≥3 pro Nutzer), zeigt die Korrelations-Analyse Zusammenhänge — aber **immer als Korrelation, nie als Kausal-Behauptung** (DSGVO-/Haftungs-sicher; "kein Heil-/Diagnoseversprechen"). PocketBase `sort=-id` (nicht `sort=-created`, das 400 gibt) für "neueste zuerst".
## Test-Zugang PersoEnt (Stand 2026-08-07)
- PocketBase-Superuser + users-Collection; Test-Login `mehlzoerwer@perfekt-ohne-en.de`.
- APK-Build-Mechanik: siehe übergeordneter Skill `mobile-apk-flutter-build`.
skills/devops/model-allocation/SKILL.md
+119
View File
@@ -0,0 +1,119 @@
---
name: model-allocation
description: >-
Kostenkontrollierte, verhältnismäßige Modell-Auswahl für Hermes-Agents.
Drei Ebenen: tägliche Ausrichtung, stündliches Feintuning, Task-bezogenes Matching.
Lokaler Fallback über VPS-Ollama (deepseek-r1:7b) mit 64k+ Kontext und Thinking.
Budget: 1€/Tag/Agent, bei Überschreitung → postpone + lokaler Fallback.
related_skills: [multi-agent-mesh]
---
# Model-Allocation-Skill
Automatisierte Entscheidungslogik für Modell-Wahl pro Agent und Task.
## Prinzipien
- **Kosten ~99% Gewicht**, Zeit spielt keine Rolle
- **Kein Free-Only-Zwang**, aber proportionaler Aufstieg erlaubt
- **Kein Ferrari-Sprung** (>5x Kosten) ohne manual_override
- **Diversität** als Ziel (min 3 Modell-Familien)
## Die drei Ebenen
### Ebene 1 — Täglich (grobe Ausrichtung)
- `scripts/daily_model_check.py`
- Holt Modell-/Preisliste (Mock → OpenRouter-API)
- Filtert ≥64k Kontext, baut Prioritätsliste pro Agent
- Prüft Diversität, schreibt `state/model_priority.json`
### Ebene 2 — Stündlich (Feintuning)
- `scripts/hourly_finetune_check.py`
- Prüft Budget-Warnschwelle (1€/Tag/Agent), Verfügbarkeit, Rate-Limits
- Bei Überschreitung: Tasks auf nächsten Tag verschieben
- Einfache Anfragen → lokales VPS-Ollama (`deepseek-r1:7b`)
### Ebene 3 — Task-bezogen (Feinauswahl)
- `scripts/task_agent_matcher.py`
- Input: Capability-Tag → findet günstigste passende Kombination
- Eskaliert max eine Stufe bei Fehlschlag
- Fallback auf lokales Ollama wenn kein Agent verfügbar
- Max 3 Retries pro Task
## Konfiguration
Siehe `config/agents.yaml` für die vollständige Config.
Siehe `references/agents-config.md` für eine kompakte Übersicht.
Pro Agent: Modell, Eskalationsleiter, Tags, Budget
Global: min_context=64000, max_escalation=5x, min_diversity=3
`local_fallback.model: deepseek-r1:7b` (Thinking + 128k Kontext)
## Lokale Modelle auf dem VPS
| Modell | Größe | Kontext | Thinking | Status |
|--------|-------|---------|----------|--------|
| `deepseek-r1:7b` | 4.7 GB | 128k | ✅ | aktiv (Default) |
| `deepseek-r1:14b` | 9.0 GB | 128k | ✅ | runtergeladen, ungetestet |
### ⚠️ WICHTIG: Ollama Bindungs-Address
Das Ollama-Installation auf dem VPS lauscht an `172.24.196.119:11434` (VPS-Externe IP), NICHT an `localhost:11434`.
**Konsequenz:** Das Config-`base_url` muss `http://172.24.196.119:11434/v1` lauten, damit das Modell von anderen Mesh-Agenten (oder demselben Agenten im Netzwerk) darauf zugreifen kann.
Fehlgeschlagene Verbindungssymptome:
- `curl http://localhost:11434/api/tags` → Connection refused (wenn Ollama nicht localhost-bound)
- Modell kann lokalen Ollama-Fallback nicht erreichen
- Task fällt auf nächstes teureren OpenRouter-Modell aus
**Behebung:** Config-Key `ollama.base_url` auf `http://172.24.196.119:11434/v1` setzen. Siehe `references/ollama-bind-address.md` für Details.
**Warum deepseek-r1:7b?** Thinking + 128k Kontext in 4.7 GB — optimal für 16 GB RAM VPS.
`deepseek-r1:14b` ist Upgrade-Option sobald RAM-Puffer bestätigt ist.
## Setup
```bash
pip install pyyaml --break-system-packages
```
Detailierte Modell-Vergleiche: `references/local-model-comparison.md`
## Cron
### Lokal (auf Hub/Agent A via Hermes-Cron)
```bash
hermes cron add --schedule '0 3 * * *' --name model-allocation-daily \
--prompt 'cd ~/.hermes/skills/devops/model-allocation && python3 scripts/daily_model_check.py'
hermes cron add --schedule '0 * * * *' --name model-allocation-hourly \
--prompt 'cd ~/.hermes/skills/devops/model-allocation && python3 scripts/hourly_finetune_check.py'
```
### Auf Remote-Agents per SSH (crontab)
Verwende ein Setup-Script für mehrere Agenten gleichzeitig:
```bash
# setup_model_cron.sh
mkdir -p $HOME/.hermes/logs
if crontab -l 2>/dev/null | grep -q 'model-allocation'; then
echo "Cron bereits da"; exit 0
fi
(crontab -l 2>/dev/null
echo "# model-allocation: täglich 03:00"
echo "0 3 * * * cd \$HOME/.hermes/skills/devops/model-allocation \\"
echo " && python3 scripts/daily_model_check.py >> \$HOME/.hermes/logs/model-allocation-daily.log 2>&1"
echo "# model-allocation: stündlich"
echo "0 * * * * cd \$HOME/.hermes/skills/devops/model-allocation \\"
echo " && python3 scripts/hourly_finetune_check.py >> \$HOME/.hermes/logs/model-allocation-hourly.log 2>&1"
) | crontab -
echo "Cron eingerichtet"
# Auf mehreren Remotes gleichzeitig:
for ip in 172.24.20.26 172.24.34.142 172.24.178.202; do
sshpass -p 'PW' scp setup_model_cron.sh user@$ip:/tmp/
sshpass -p 'PW' ssh user@$ip 'bash /tmp/setup_model_cron.sh'
done
```
skills/devops/model-allocation/config/agents.yaml
+78
View File
@@ -0,0 +1,78 @@
# Konfiguration für die Agent-Modell-Auswahl
global:
min_context_tokens: 64000
max_auto_escalation_factor: 5 # ab diesem Faktor gilt ein Wechsel als "Ferrari-Sprung" -> braucht manual_override
min_distinct_model_families: 3 # Mindest-Diversität über alle Agents hinweg
max_retries_per_task: 3 # danach Task pausieren, nicht weiter eskalieren
default_hard_stop_eur_per_day: 1.0 # 1€/Tag/Agent als hartes Maximum
on_budget_exceeded: postpone_to_next_day # Arbeit verschieben statt Agent komplett zu blockieren
basic_questions_fallback: vps_ollama # einfache/Grundfragen weiter über lokales VPS-Ollama, wenn kontextuell sinnvoll
agents:
agent_a:
role: master
description: "Master-Agent, Allround, Linux-System-Support"
hard_stop_eur_per_day: 1.0
capability_tags: [linux_system, allround, orchestration]
escalation_ladder:
- model: "nvidia/nemotron-3-super" # Stufe 0, Standard
cost_factor: 1
- model: "nvidia/nemotron-3-ultra" # Stufe 1, Eskalation
cost_factor: 3
manual_override_allowed: false
agent_b:
role: worker
description: "DeepSeek Flash/Pro Eskalationsleiter"
hard_stop_eur_per_day: 1.0
capability_tags: [code, logic, database]
escalation_ladder:
- model: "deepseek/deepseek-flash"
cost_factor: 1
- model: "deepseek/deepseek-pro"
cost_factor: 3
manual_override_allowed: false
switch_hermes:
role: cockpit
description: "Nur Prompt/Code-Generierung, kein lokales Ausführen"
hard_stop_eur_per_day: 1.0
capability_tags: [homebrew_code, prompt_generation]
escalation_ladder:
- model: "openrouter/free" # OpenRouter Auto-Router, Free-Tier
cost_factor: 0
- model: "qwen/qwen3-coder:free"
cost_factor: 0
manual_override_allowed: false
laptop_hermes:
role: worker
description: "PDF/PowerPoint/HTML-Kompilation, gelegentlich High-End auf Wunsch"
hard_stop_eur_per_day: 1.0
capability_tags: [document_generation, html_css_js]
escalation_ladder:
- model: "google/gemini-flash"
cost_factor: 1
- model: "anthropic/claude-sonnet"
cost_factor: 4
manual_override_allowed: true # Opus/GPT-5.5/Fable nur per bewusstem manuellen Opt-in
agent_xyz:
role: worker
description: "Saubere JavaScript-Datenbank-Abfragen"
hard_stop_eur_per_day: 1.0
capability_tags: [javascript, database_query]
escalation_ladder:
- model: "qwen/qwen2.5-7b"
cost_factor: 1
- model: "deepseek/deepseek-flash"
cost_factor: 2
manual_override_allowed: false
local_fallback:
description: "Kostenfreier lokaler Fallback auf dem VPS via Ollama"
model: "deepseek-r1:7b"
min_context_tokens: 64000
allowed_for_task_tags: [document_generation, javascript, database_query, linux_system]
# Bewusst NICHT erlaubt für: homebrew_code (zu fehleranfällig bei 7B-Klasse)
skills/devops/model-allocation/references/agents-config.md
+60
View File
@@ -0,0 +1,60 @@
# Modell-Auswahl Konfiguration
## Global
```yaml
min_context_tokens: 64000
max_auto_escalation_factor: 5 # ab 5x Kosten -> "Ferrari-Sprung", braucht manual_override
min_distinct_model_families: 3 # Mindest-Diversität
max_retries_per_task: 3
default_hard_stop_eur_per_day: 1.0 # 1€/Tag/Agent hartes Limit
on_budget_exceeded: postpone_to_next_day
basic_questions_fallback: vps_ollama
```
## Agents & Eskalationsleitern
### agent_a (Master — Linux, Allround)
- Standard: `nvidia/nemotron-3-super` (1x)
- Eskalation: `nvidia/nemotron-3-ultra` (3x)
- Tags: linux_system, allround, orchestration
- Budget: 1€/Tag
### agent_b (Worker — Code, Logik, DB)
- Standard: `deepseek/deepseek-flash` (1x)
- Eskalation: `deepseek/deepseek-pro` (3x)
- Tags: code, logic, database
### switch_hermes (Cockpit — Prompt/Code)
- Standard: `openrouter/free` (0x)
- Eskalation: `qwen/qwen3-coder:free` (0x)
- Tags: homebrew_code, prompt_generation
### laptop_hermes (Worker — Dokumente/HTML)
- Standard: `google/gemini-flash` (1x)
- Eskalation: `anthropic/claude-sonnet` (4x)
- manual_override: ✅ erlaubt
- Tags: document_generation, html_css_js
### agent_xyz (Worker — JS/DB-Queries)
- Standard: `qwen/qwen2.5-7b` (1x)
- Eskalation: `deepseek/deepseek-flash` (2x)
- Tags: javascript, database_query
## Lokaler Fallback (VPS-Ollama)
```yaml
local_fallback:
model: "deepseek-r1:7b" # 128k Kontext, Thinking
min_context_tokens: 64000
allowed_for_task_tags: [document_generation, javascript, database_query]
# NICHT erlaubt für: homebrew_code (zu fehleranfällig bei 7B)
```
## Prinzipien
- Kosten ~99% Gewicht, Zeit egal
- Proportionaler Aufstieg erlaubt, kein Ferrari-Sprung (>5x)
- Budget erschöpft → postpone + lokaler Ollama-Fallback
- Diversität: min 3 verschiedene Modell-Familien
- Max 3 Retries pro Task, dann pausieren
skills/devops/model-allocation/references/local-model-comparison.md
+23
View File
@@ -0,0 +1,23 @@
# Lokale Modelle — Vergleichstabelle für VPS (16GB RAM)
## Thinking-Modelle (Chain-of-Thought/Reasoning)
| Modell | Größe | Kontext | RAM-Bedarf | Läuft auf VPS? | Empfehlung |
|--------|-------|---------|------------|----------------|------------|
| **deepseek-r1:7b** | 4.7 GB | 128k | ~6-7 GB | ✅ | **Sweet Spot** — aktiv |
| **deepseek-r1:14b** | 9.0 GB | 128k | ~11-12 GB | ⚠️ knapp | geladen, ungetestet |
| **deepseek-r1:32b** | ~20 GB | 128k | ~24 GB | ❌ | zu groß |
| **qwq:32b** | ~20 GB | 128k | ~24 GB | ❌ | zu groß |
## Ohne Thinking
| Modell | Größe | Kontext | RAM-Bedarf | Läuft? |
|--------|-------|---------|------------|--------|
| **phi-4:14b** | ~9 GB | 16k | ~11 GB | ⚠️ (nur 16k Kontext) |
| **qwen2.5:7b** | ~4.7 GB | 32k | ~6 GB | ✅ (kein Thinking) |
| **llama3.1:8b** | ~4.9 GB | 8k | ~6 GB | ✅ (nur 8k, kein Thinking) |
## Faustregel
- **16GB RAM VPS:** max 7B-14B Modelle (14B belegt ~75% RAM)
- **RTX 2060 6GB:** max 7B (Q4_K_M ~4.5GB VRAM)
- **ARM64 (Switch Lite):** max 3B-8B (CPU-Inference)
skills/devops/model-allocation/scripts/__pycache__/daily_model_check.cpython-312.pyc
BIN
View File
Binary file not shown.
skills/devops/model-allocation/scripts/__pycache__/hourly_finetune_check.cpython-312.pyc
BIN
View File
Binary file not shown.
skills/devops/model-allocation/scripts/__pycache__/mock_data.cpython-311.pyc
BIN
View File
Binary file not shown.
skills/devops/model-allocation/scripts/__pycache__/mock_data.cpython-312.pyc
BIN
View File
Binary file not shown.
skills/devops/model-allocation/scripts/__pycache__/task_agent_matcher.cpython-312.pyc
BIN
View File
Binary file not shown.
skills/devops/model-allocation/scripts/daily_model_check.py
+162
View File
@@ -0,0 +1,162 @@
#!/usr/bin/env python3
"""
daily_model_check.py
Ebene 1 des Skills: läuft 1x täglich (Cron), baut die grobe
Modell-Prioritätsliste pro Agent und schreibt sie nach
state/model_priority.json.
Nutzt aktuell Mock-Daten (mock_data.py). Für den Wechsel auf die
echte OpenRouter-API muss nur fetch_model_list() in mock_data.py
ersetzt werden - dieses Script bleibt unverändert.
Aufruf:
python3 daily_model_check.py
"""
import json
import sys
from pathlib import Path
import yaml
sys.path.insert(0, str(Path(__file__).parent))
from mock_data import fetch_model_list, fetch_timestamp # noqa: E402
CONFIG_PATH = Path(__file__).parent.parent / "config" / "agents.yaml"
STATE_DIR = Path(__file__).parent.parent / "state"
OUTPUT_PATH = STATE_DIR / "model_priority.json"
def load_config():
with open(CONFIG_PATH, "r", encoding="utf-8") as f:
return yaml.safe_load(f)
def index_models_by_id(models):
return {m["id"]: m for m in models}
def build_agent_priority(agent_name, agent_cfg, models_by_id, min_context, max_escalation_factor):
"""Baut die Eskalationsleiter für einen Agent, gefiltert nach
Mindest-Kontext und verfügbaren/bekannten Modellen.
"""
ladder = []
warnings = []
for step_idx, step in enumerate(agent_cfg["escalation_ladder"]):
model_id = step["model"]
cost_factor = step["cost_factor"]
# Free-Tier-Router-Strings wie "openrouter/free" stehen nicht in
# der Modell-Liste selbst - die werden unverändert übernommen.
if model_id not in models_by_id:
if model_id.startswith("openrouter/"):
ladder.append({"model": model_id, "cost_factor": cost_factor, "note": "auto-router, nicht einzeln geprüft"})
continue
warnings.append(f"{agent_name}: Modell '{model_id}' nicht in aktueller Modell-Liste gefunden - übersprungen")
continue
model = models_by_id[model_id]
if not model.get("available", True):
warnings.append(f"{agent_name}: Modell '{model_id}' aktuell nicht verfügbar - übersprungen")
continue
if model["context_length"] < min_context:
warnings.append(
f"{agent_name}: Modell '{model_id}' hat nur {model['context_length']} Kontext, "
f"unter Minimum von {min_context} - übersprungen"
)
continue
# Verhältnismäßigkeits-Check: Stufen jenseits von Stufe 0 dürfen
# den max_auto_escalation_factor nicht überschreiten, sonst braucht's
# manual_override.
if step_idx > 0 and cost_factor > max_escalation_factor and not agent_cfg.get("manual_override_allowed", False):
warnings.append(
f"{agent_name}: Eskalationsstufe '{model_id}' hat Faktor {cost_factor}x, "
f"über dem erlaubten Automatik-Limit von {max_escalation_factor}x - "
f"nur per manual_override nutzbar, aus Automatik-Leiter entfernt"
)
continue
ladder.append({
"model": model_id,
"cost_factor": cost_factor,
"context_length": model["context_length"],
"price_per_1k_tokens_eur": model["price_per_1k_tokens_eur"],
"family": model["family"],
})
return ladder, warnings
def check_diversity(priority_by_agent, min_distinct_families):
families_in_use = set()
for agent_name, ladder in priority_by_agent.items():
for step in ladder:
if "family" in step:
families_in_use.add(step["family"])
diverse_enough = len(families_in_use) >= min_distinct_families
return diverse_enough, sorted(families_in_use)
def main():
config = load_config()
global_cfg = config["global"]
min_context = global_cfg["min_context_tokens"]
max_escalation_factor = global_cfg["max_auto_escalation_factor"]
min_distinct_families = global_cfg["min_distinct_model_families"]
models = fetch_model_list()
models_by_id = index_models_by_id(models)
priority_by_agent = {}
all_warnings = []
for agent_name, agent_cfg in config["agents"].items():
ladder, warnings = build_agent_priority(
agent_name, agent_cfg, models_by_id, min_context, max_escalation_factor
)
priority_by_agent[agent_name] = ladder
all_warnings.extend(warnings)
if not ladder:
all_warnings.append(
f"WARNUNG: Agent '{agent_name}' hat NACH Filterung keine nutzbaren Modelle mehr - "
f"lokaler Fallback sollte hier greifen"
)
diverse_enough, families_in_use = check_diversity(priority_by_agent, min_distinct_families)
if not diverse_enough:
all_warnings.append(
f"WARNUNG: Nur {len(families_in_use)} Modell-Familien im Einsatz "
f"({', '.join(families_in_use)}), Minimum wäre {min_distinct_families}"
)
output = {
"generated_at": fetch_timestamp(),
"min_context_tokens": min_context,
"max_auto_escalation_factor": max_escalation_factor,
"diversity_ok": diverse_enough,
"model_families_in_use": families_in_use,
"agents": priority_by_agent,
"local_fallback": config["local_fallback"],
"warnings": all_warnings,
}
STATE_DIR.mkdir(exist_ok=True)
with open(OUTPUT_PATH, "w", encoding="utf-8") as f:
json.dump(output, f, indent=2, ensure_ascii=False)
print(f"Prioritätsliste geschrieben nach {OUTPUT_PATH}")
if all_warnings:
print(f"\n{len(all_warnings)} Warnung(en):")
for w in all_warnings:
print(f" - {w}")
if __name__ == "__main__":
main()
skills/devops/model-allocation/scripts/hourly_finetune_check.py
+114
View File
@@ -0,0 +1,114 @@
#!/usr/bin/env python3
"""
hourly_finetune_check.py
Ebene 2 des Skills: läuft stündlich (oder öfter), prüft NUR Deltas
gegen die von daily_model_check.py gebaute Prioritätsliste:
- Ist ein Agent über sein Tagesbudget (hard_stop_eur_per_day)?
-> Kill-Switch: Agent wird auf lokalen Fallback gezwungen.
- Wurde ein Modell inzwischen als nicht mehr verfügbar gemeldet?
-> Wird aus der aktiven Leiter entfernt (bis zum nächsten Tages-Lauf).
Erwartet, dass der jeweilige Agent selbst fortlaufend seinen
Tagesverbrauch nach state/spend_today.json schreibt, Format:
{ "agent_a": 0.42, "agent_b": 1.10, ... }
Falls diese Datei fehlt (z.B. noch nicht angebunden), läuft der Check
trotzdem durch und markiert das als Hinweis statt Fehler.
Aufruf:
python3 hourly_finetune_check.py
"""
import json
from pathlib import Path
import yaml
CONFIG_PATH = Path(__file__).parent.parent / "config" / "agents.yaml"
STATE_DIR = Path(__file__).parent.parent / "state"
PRIORITY_PATH = STATE_DIR / "model_priority.json"
SPEND_PATH = STATE_DIR / "spend_today.json"
KILL_SWITCH_PATH = STATE_DIR / "kill_switches.json"
def load_config():
with open(CONFIG_PATH, "r", encoding="utf-8") as f:
return yaml.safe_load(f)
def load_priority():
if not PRIORITY_PATH.exists():
raise FileNotFoundError(
f"{PRIORITY_PATH} fehlt - bitte zuerst daily_model_check.py laufen lassen"
)
with open(PRIORITY_PATH, "r", encoding="utf-8") as f:
return json.load(f)
def load_spend():
if not SPEND_PATH.exists():
return {}, ["spend_today.json fehlt noch - Budget-Check übersprungen, bitte Anbindung nachholen"]
with open(SPEND_PATH, "r", encoding="utf-8") as f:
return json.load(f), []
def check_budgets(config, spend):
kill_switches = {}
notes = []
for agent_name, agent_cfg in config["agents"].items():
limit = agent_cfg.get("hard_stop_eur_per_day")
spent = spend.get(agent_name)
if spent is None:
continue
if limit is None or limit == "BUDGET_PLACEHOLDER":
notes.append(
f"{agent_name}: hard_stop_eur_per_day ist noch Platzhalter - "
f"kein Kill-Switch aktiv, bitte echten Wert eintragen"
)
continue
if spent >= float(limit):
kill_switches[agent_name] = {
"reason": "daily_budget_exceeded",
"spent_eur": spent,
"limit_eur": limit,
"action": "postpone_to_next_day",
"basic_questions_fallback": "vps_ollama",
}
notes.append(
f"KILL-SWITCH: {agent_name} hat {spent}€ von {limit}€ Tageslimit erreicht - "
f"restliche Tasks werden auf morgen verschoben. Grundfragen laufen bis dahin "
f"weiter über das lokale VPS-Ollama-Modell, sofern das inhaltlich passt."
)
return kill_switches, notes
def main():
config = load_config()
priority = load_priority()
spend, spend_notes = load_spend()
kill_switches, budget_notes = check_budgets(config, spend)
result = {
"checked_at": priority.get("generated_at"),
"kill_switches": kill_switches,
"notes": spend_notes + budget_notes,
}
with open(KILL_SWITCH_PATH, "w", encoding="utf-8") as f:
json.dump(result, f, indent=2, ensure_ascii=False)
print(f"Feintuning-Check abgeschlossen, Ergebnis in {KILL_SWITCH_PATH}")
for note in result["notes"]:
print(f" - {note}")
if __name__ == "__main__":
main()
skills/devops/model-allocation/scripts/mock_data.py
+104
View File
@@ -0,0 +1,104 @@
"""
Mock-Datenquelle für die OpenRouter-Modell-Liste.
Diese Funktion hat exakt die Signatur, die auch der echte API-Call später
haben wird (siehe TODO), damit daily_model_check.py unverändert bleibt,
wenn die echte API eingehängt wird.
TODO (später, wenn echte API gewünscht):
import requests
def fetch_model_list():
resp = requests.get(
"https://openrouter.ai/api/v1/models",
headers={"Authorization": f"Bearer {OPENROUTER_API_KEY}"},
timeout=10,
)
resp.raise_for_status()
return resp.json()["data"]
"""
from datetime import datetime, timezone
def fetch_model_list():
"""Gibt eine Liste von Modell-Dicts zurück, im gleichen Format wie
die echte OpenRouter-API (vereinfacht auf die Felder, die wir brauchen).
"""
return [
{
"id": "nvidia/nemotron-3-super",
"context_length": 262000,
"price_per_1k_tokens_eur": 0.0009,
"family": "nemotron",
"tags": ["linux_system", "allround"],
"available": True,
},
{
"id": "nvidia/nemotron-3-ultra",
"context_length": 1000000,
"price_per_1k_tokens_eur": 0.0027,
"family": "nemotron",
"tags": ["linux_system", "allround", "orchestration"],
"available": True,
},
{
"id": "deepseek/deepseek-flash",
"context_length": 128000,
"price_per_1k_tokens_eur": 0.0006,
"family": "deepseek",
"tags": ["code", "logic", "database"],
"available": True,
},
{
"id": "deepseek/deepseek-pro",
"context_length": 128000,
"price_per_1k_tokens_eur": 0.0018,
"family": "deepseek",
"tags": ["code", "logic", "database"],
"available": True,
},
{
"id": "qwen/qwen3-coder:free",
"context_length": 1000000,
"price_per_1k_tokens_eur": 0.0,
"family": "qwen",
"tags": ["homebrew_code", "prompt_generation", "code"],
"available": True,
},
{
"id": "qwen/qwen2.5-7b",
"context_length": 128000,
"price_per_1k_tokens_eur": 0.0003,
"family": "qwen",
"tags": ["javascript", "database_query"],
"available": True,
},
{
"id": "google/gemini-flash",
"context_length": 1000000,
"price_per_1k_tokens_eur": 0.0004,
"family": "gemini",
"tags": ["document_generation", "html_css_js"],
"available": True,
},
{
"id": "anthropic/claude-sonnet",
"context_length": 200000,
"price_per_1k_tokens_eur": 0.0045,
"family": "anthropic",
"tags": ["document_generation", "html_css_js", "allround"],
"available": True,
},
{
"id": "anthropic/claude-opus",
"context_length": 200000,
"price_per_1k_tokens_eur": 0.0900,
"family": "anthropic",
"tags": ["document_generation", "html_css_js", "allround"],
"available": True,
},
]
def fetch_timestamp():
return datetime.now(timezone.utc).isoformat()
skills/devops/model-allocation/scripts/task_agent_matcher.py
+132
View File
@@ -0,0 +1,132 @@
#!/usr/bin/env python3
"""
task_agent_matcher.py
Ebene 3 des Skills: läuft bei Agent A (Master) zur Laufzeit, sobald ein
neuer Task ansteht. Entscheidet, welcher Agent bei welchem Standard-Modell
am besten zum Task-Typ passt - basierend auf:
- der von daily_model_check.py gebauten Prioritätsliste
(state/model_priority.json)
- aktiven Kill-Switches (state/kill_switches.json), z.B. wegen
Budget-Überschreitung -> Agent wird übersprungen bzw. auf
"postpone_to_next_day" gesetzt
- den Capability-Tags pro Agent (config/agents.yaml)
Jeder Agent bekommt exakt dieses Konzept (Config + Prioritätsliste)
mitgeliefert, damit alle konsistent nach derselben Logik laufen, egal
wer die Entscheidung am Ende ausführt.
Aufruf (Beispiel):
python3 task_agent_matcher.py --task-tag javascript
python3 task_agent_matcher.py --task-tag homebrew_code
"""
import argparse
import json
from pathlib import Path
import yaml
CONFIG_PATH = Path(__file__).parent.parent / "config" / "agents.yaml"
STATE_DIR = Path(__file__).parent.parent / "state"
PRIORITY_PATH = STATE_DIR / "model_priority.json"
KILL_SWITCH_PATH = STATE_DIR / "kill_switches.json"
def load_yaml(path):
with open(path, "r", encoding="utf-8") as f:
return yaml.safe_load(f)
def load_json(path, default=None):
if not path.exists():
return default if default is not None else {}
with open(path, "r", encoding="utf-8") as f:
return json.load(f)
def find_matches(task_tag, config, priority, kill_switches):
"""Gibt eine nach Preis sortierte Liste von (agent, model, price) für
Agents zurück, deren Capability-Tags zum Task-Typ passen und die
NICHT gerade per Kill-Switch auf 'postpone_to_next_day' stehen.
"""
candidates = []
postponed = []
for agent_name, agent_cfg in config["agents"].items():
if task_tag not in agent_cfg.get("capability_tags", []):
continue
if agent_name in kill_switches.get("kill_switches", {}):
ks = kill_switches["kill_switches"][agent_name]
postponed.append({
"agent": agent_name,
"reason": ks["reason"],
"action": ks["action"],
"fallback": ks.get("basic_questions_fallback"),
})
continue
ladder = priority.get("agents", {}).get(agent_name, [])
for step in ladder:
candidates.append({
"agent": agent_name,
"model": step["model"],
"cost_factor": step.get("cost_factor"),
"price_per_1k_tokens_eur": step.get("price_per_1k_tokens_eur"),
})
# Günstigste zuerst; Steps ohne Preisangabe (z.B. Free-Router) ganz vorne
candidates.sort(key=lambda c: (c["price_per_1k_tokens_eur"] is not None, c.get("price_per_1k_tokens_eur") or 0))
return candidates, postponed
def main():
parser = argparse.ArgumentParser(description="Task-zu-Agent-Matching (Ebene 3)")
parser.add_argument("--task-tag", required=True, help="Capability-Tag des Tasks, z.B. javascript, homebrew_code")
args = parser.parse_args()
config = load_yaml(CONFIG_PATH)
priority = load_json(PRIORITY_PATH)
kill_switches = load_json(KILL_SWITCH_PATH)
if not priority:
print("FEHLER: state/model_priority.json fehlt - bitte zuerst daily_model_check.py laufen lassen")
return
candidates, postponed = find_matches(args.task_tag, config, priority, kill_switches)
if not candidates:
local_fb = config.get("local_fallback", {})
if args.task_tag in local_fb.get("allowed_for_task_tags", []):
print(f"Kein Cloud-Kandidat für '{args.task_tag}' verfügbar (evtl. alle betroffenen Agents "
f"per Kill-Switch verschoben) - lokaler Fallback erlaubt:")
print(f" -> {local_fb['model']} (kostenfrei, VPS-Ollama)")
else:
print(f"Kein Kandidat für '{args.task_tag}' verfügbar und lokaler Fallback für diesen "
f"Task-Typ NICHT erlaubt (siehe config: local_fallback.allowed_for_task_tags). "
f"Task sollte pausiert werden.")
for p in postponed:
print(f" (verschoben: {p['agent']} - {p['reason']}, Fallback: {p['fallback']})")
return
best = candidates[0]
print(f"Beste Wahl für Task-Tag '{args.task_tag}':")
print(f" Agent: {best['agent']}")
print(f" Modell: {best['model']} (Kostenfaktor {best['cost_factor']}x)")
if len(candidates) > 1:
print("\nWeitere passende Kandidaten (Eskalationsreserve):")
for c in candidates[1:]:
print(f" - {c['agent']} / {c['model']} (Faktor {c['cost_factor']}x)")
if postponed:
print("\nHinweis, folgende Agents sind aktuell wegen Budget verschoben:")
for p in postponed:
print(f" - {p['agent']}: {p['reason']} -> {p['action']} (Grundfragen: {p['fallback']})")
if __name__ == "__main__":
main()
skills/devops/model-allocation/state/kill_switches.json
+15
View File
@@ -0,0 +1,15 @@
{
"checked_at": "2026-08-02T01:00:17.882979+00:00",
"kill_switches": {
"agent_a": {
"reason": "daily_budget_exceeded",
"spent_eur": 1.5,
"limit_eur": 1.0,
"action": "postpone_to_next_day",
"basic_questions_fallback": "vps_ollama"
}
},
"notes": [
"KILL-SWITCH: agent_a hat 1.5€ von 1.0€ Tageslimit erreicht - restliche Tasks werden auf morgen verschoben. Grundfragen laufen bis dahin weiter über das lokale VPS-Ollama-Modell, sofern das inhaltlich passt."
]
}
skills/devops/model-allocation/state/model_priority.json
+105
View File
@@ -0,0 +1,105 @@
{
"generated_at": "2026-08-02T01:00:17.882979+00:00",
"min_context_tokens": 64000,
"max_auto_escalation_factor": 5,
"diversity_ok": true,
"model_families_in_use": [
"anthropic",
"deepseek",
"gemini",
"nemotron",
"qwen"
],
"agents": {
"agent_a": [
{
"model": "nvidia/nemotron-3-super",
"cost_factor": 1,
"context_length": 262000,
"price_per_1k_tokens_eur": 0.0009,
"family": "nemotron"
},
{
"model": "nvidia/nemotron-3-ultra",
"cost_factor": 3,
"context_length": 1000000,
"price_per_1k_tokens_eur": 0.0027,
"family": "nemotron"
}
],
"agent_b": [
{
"model": "deepseek/deepseek-flash",
"cost_factor": 1,
"context_length": 128000,
"price_per_1k_tokens_eur": 0.0006,
"family": "deepseek"
},
{
"model": "deepseek/deepseek-pro",
"cost_factor": 3,
"context_length": 128000,
"price_per_1k_tokens_eur": 0.0018,
"family": "deepseek"
}
],
"switch_hermes": [
{
"model": "openrouter/free",
"cost_factor": 0,
"note": "auto-router, nicht einzeln geprüft"
},
{
"model": "qwen/qwen3-coder:free",
"cost_factor": 0,
"context_length": 1000000,
"price_per_1k_tokens_eur": 0.0,
"family": "qwen"
}
],
"laptop_hermes": [
{
"model": "google/gemini-flash",
"cost_factor": 1,
"context_length": 1000000,
"price_per_1k_tokens_eur": 0.0004,
"family": "gemini"
},
{
"model": "anthropic/claude-sonnet",
"cost_factor": 4,
"context_length": 200000,
"price_per_1k_tokens_eur": 0.0045,
"family": "anthropic"
}
],
"agent_xyz": [
{
"model": "qwen/qwen2.5-7b",
"cost_factor": 1,
"context_length": 128000,
"price_per_1k_tokens_eur": 0.0003,
"family": "qwen"
},
{
"model": "deepseek/deepseek-flash",
"cost_factor": 2,
"context_length": 128000,
"price_per_1k_tokens_eur": 0.0006,
"family": "deepseek"
}
]
},
"local_fallback": {
"description": "Kostenfreier lokaler Fallback auf dem VPS via Ollama",
"model": "deepseek-r1:7b",
"min_context_tokens": 64000,
"allowed_for_task_tags": [
"document_generation",
"javascript",
"database_query",
"linux_system"
]
},
"warnings": []
}
skills/devops/model-allocation/state/spend_today.json
+1
View File
@@ -0,0 +1 @@
{"agent_a": 1.5, "agent_b": 0.0, "switch_hermes": 0.0, "laptop_hermes": 0.0, "agent_xyz": 0.0}
skills/devops/model-allocation/state/spend_today.json.bak
+7
View File
@@ -0,0 +1,7 @@
{
"agent_a": 0.0,
"agent_b": 0.0,
"switch_hermes": 0.0,
"laptop_hermes": 0.0,
"agent_xyz": 0.0
}
skills/devops/nginx-vhost-deployment/SKILL.md
+254
View File
@@ -0,0 +1,254 @@
---
name: nginx-vhost-deployment
description: "Nginx-Webserver mit Name-based Virtual Hosting auf Ubuntu-Server installieren, konfigurieren und deployen – inkl. Fallstricke, DNS-Checks und Test-Workflow"
version: 1.0.0
author: Agent A (Deployer)
platforms: [linux, ubuntu]
---
# Nginx Virtual Host Deployment
Installation und Konfiguration von nginx mit mehreren Virtual Hosts (name-based) auf einem Ubuntu-VPS. Deckt den gesamten Workflow ab: DNS-Prüfung → Installation → VHost-Konfiguration → Berechtigungen → Firewall → Test → SSL-Vorbereitung.
## Auslöser (Trigger)
- „Webserver installieren"
- „Webseite online stellen"
- „Domain aufsetzen"
- „nginx einrichten"
- „Virtual Host konfigurieren"
- „Mehrere Domains auf einem Server"
---
## Schritt 1: DNS-Check VOR der Installation
**Immer zuerst prüfen**, ob die Domains auf den Server zeigen – sonst arbeitet man ins Leere.
```bash
for domain in domain1.de domain2.de; do
echo "=== DNS: $domain ==="
dig +short A "$domain"
dig +short AAAA "$domain"
done
```
**Interpretation:**
- Zeigt auf **richtige IP** → ✅ Weiter
- Zeigt auf **Cloudflare-IPs** (104.x, 172.x) → ⚠️ Nutzer muss Cloudflare-Proxy deaktivieren (orange→grau)
- Zeigt auf **fremde IP** → ❌ Nutzer muss A-Record ändern
- **Kein Eintrag** → ❌ Nutzer muss A-Record anlegen
**Server-IP herausfinden:** `curl -s ifconfig.me` oder aus Memory/Konfiguration.
---
## Schritt 2: nginx installieren
```bash
sudo apt-get update -qq
sudo apt-get install -y -qq nginx certbot python3-certbot-nginx
sudo systemctl enable --now nginx
```
**NICHT vergessen:** `certbot` und `python3-certbot-nginx` gleich mitinstallieren – spart später Arbeit.
---
## Schritt 3: Verzeichnisstruktur pro Domain
```bash
sudo mkdir -p /var/www/DOMAIN.de/html
sudo mkdir -p /var/www/DOMAIN.de/logs
sudo chown -R www-data:www-data /var/www/DOMAIN.de/
sudo chmod -R 755 /var/www/DOMAIN.de/
```
⚠️ **PITFALL – 403 Forbidden:** Wenn nginx 403 zurückgibt, sind die Dateien/Berechtigungen schuld:
- **Ursache:** Dateien gehören `root:root`, aber nginx-Worker läuft als `www-data`
- **Fix:** `sudo chown -R www-data:www-data /var/www/` + `sudo chmod -R 755 /var/www/`
- **Test:** `ps aux | grep nginx` → Worker-User prüfen
---
## Schritt 4: VHost-Konfiguration erstellen
### ⚠️ PITFALL – sites-available vs sites-enabled: SEPARATE Dateien, nicht nur Symlink
Auf manchen Setups sind `sites-available/DOMAIN` und `sites-enabled/DOMAIN` **zwei
getrennte Dateien** (kein Symlink). nginx lädt NUR `sites-enabled/`. Wer nur die
`available`-Datei editiert und reloadet, sieht **keine Änderung** — und `nginx -t`
meldet trotzdem OK (er testet die alte, aktive Datei → "grün" aber unverändert).
Symptom (2026-08-04 PersoEnt): neuer `location /pb/` Proxy erschien nie über HTTPS,
`nginx -T | grep -c "location /pb/"` = 0, obwohl die available-Datei den Block hatte.
**Diagnose (Symlink oder separate Datei?):**
```bash
ls -la /etc/nginx/sites-enabled/DOMAIN # "-> sites-available/..." = Symlink, sonst separate Datei
nginx -T 2>/dev/null | grep -c "location /pb/" # 0 obwohl in available vorhanden => separate Datei aktiv
```
**Fix:** Endversion nach BEIDEN `sites-available/...` UND `sites-enabled/...` schreiben
(oder sauber als Symlink erzwingen: `ln -sf .../sites-available/DOMAIN .../sites-enabled/DOMAIN`),
dann `nginx -t && systemctl reload nginx` und mit `nginx -T | grep` verifizieren, dass der
neue Block wirklich in der aktiven Config steht.
### ⚠️ PITFALL – write_file verweigert Systempfade
`write_file` kann **nicht** nach `/etc/nginx/sites-available/` schreiben (Systempfad-Schutz). **Workaround:** `sudo tee` im Terminal nutzen.
```bash
sudo tee /etc/nginx/sites-available/DOMAIN.de << 'EOF'
server {
listen 80;
listen [::]:80;
server_name DOMAIN.de www.DOMAIN.de;
root /var/www/DOMAIN.de/html;
index index.html index.htm;
access_log /var/www/DOMAIN.de/logs/access.log;
error_log /var/www/DOMAIN.de/logs/error.log;
location / {
try_files $uri $uri/ =404;
}
}
EOF
# Symlink aktivieren
sudo ln -sf /etc/nginx/sites-available/DOMAIN.de /etc/nginx/sites-enabled/
# Test + Reload
sudo nginx -t && sudo systemctl reload nginx
```
**Template** für neue VHosts liegt in `templates/nginx-vhost.conf`.
---
## Schritt 5: Lokal testen (Host-Header-Trick)
Auch wenn DNS noch nicht propagiert ist, kann man den VHost lokal testen:
```bash
# HTTP-Status prüfen
curl -s -o /dev/null -w "HTTP %{http_code}\n" -H "Host: DOMAIN.de" http://localhost/
# Titel auslesen
curl -s -H "Host: DOMAIN.de" http://localhost/ | grep -oP '<title>\K[^<]+'
```
**Erwartet:** HTTP 200 + korrekter Seitentitel.
---
## Schritt 6: Firewall (UFW) konfigurieren
```bash
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 22/tcp # SSH nicht vergessen!
sudo ufw --force enable
sudo ufw status verbose
```
⚠️ **PITFALL:** `ufw enable` ohne vorher `allow 22/tcp` sperrt dich aus dem SSH aus! Immer zuerst SSH erlauben.
---
## Schritt 7: Dem Nutzer DNS-Anpassungen mitteilen
Dem Nutzer eine klare Tabelle zeigen, welche DNS-Änderungen nötig sind:
| Domain | Aktuelles DNS | Aktion |
|--------|--------------|--------|
| domain.de | 104.21.x.x (Cloudflare) | A → SERVER-IP, Proxy deaktivieren |
| domain2.de | kein Eintrag | A-Record → SERVER-IP anlegen |
**Server-IP:** Immer explizit nennen (z. B. `92.60.38.175`).
---
## Schritt 8: SSL (nach DNS-Propagation)
Sobald DNS propagiert ist (5-60 Min):
```bash
sudo certbot --nginx -d DOMAIN.de -d www.DOMAIN.de --non-interactive --agree-tos --email ADMIN-EMAIL
```
Oder alle auf einmal:
```bash
sudo certbot --nginx -d domain1.de,www.domain1.de -d domain2.de,www.domain2.de ...
```
Certbot modifiziert automatisch die nginx-Konfiguration und fügt den `listen 443 ssl` Block hinzu.
### ⚠️ PITFALL – Certbot überschreibt SSL-Pfade in BESTEHENDEN vhosts
`certbot --nginx` für eine NEUE Domain kann die `ssl_certificate`-Pfade in den Configs
**bestehender vhosts überschreiben**. Certbot schreibt nicht nur den neuen vhost, sondern
modifiziert ggf. auch andere Dateien — besonders wenn `server_name`-Wildcards oder
`*`-Einträge involviert sind.
**Symptom:** Nach `certbot --nginx -d neuedomain.de` funktioniert `https://alte-domain.de/`
nicht mehr (SSL-Fehler, `ERR_CERT_COMMON_NAME_INVALID`). Die alte Config zeigt jetzt
auf `/etc/letsencrypt/live/neuedomain.de/...` statt `.../alte-domain.de/...`.
**Fix (nach JEDEM certbot-Lauf prüfen):**
```bash
# Prüfen ob alle vhosts noch auf IHRE Zertifikate zeigen
for f in /etc/nginx/sites-enabled/*; do
cert=$(grep ssl_certificate "$f" | head -1 | grep -oP '/live/\K[^/]+')
domain=$(grep server_name "$f" | head -1 | awk '{print $2}')
echo "$domain → $cert"
# Prüfen ob das Zertifikat den Domain-Namen als SAN hat
openssl x509 -in /etc/letsencrypt/live/$cert/fullchain.pem -noout -text 2>/dev/null \
| grep -q "$domain" || echo " ⚠️ MISMATCH: $domain nicht in $cert!"
done
```
**Reparatur:** `ssl_certificate` und `ssl_certificate_key` im betroffenen vhost manuell
zurück auf das richtige Zertifikat setzen → `nginx -t && systemctl reload nginx`.
**Prävention:** Nach jedem `certbot --nginx` für eine neue Domain: Zuerst `curl -sk https://alte-domain.de/` prüfen, bevor die neue URL getestet wird. Wenn alte Domains brechen, sofort reparieren (siehe Fix oben).
### ⚠️ PITFALL – Certbot-Henne-Ei bei NEUEM vhost (Zertifikat existiert noch nicht)
Wenn du den SSL-vhost **vorab** manuell anlegst (Referenz auf `/etc/letsencrypt/live/DOMAIN/fullchain.pem`), aber das Zertifikat noch nicht existiert, schlägt **`nginx -t` fehl** (`[emerg] cannot load certificate ... No such file or directory`). Dadurch schlägt **auch `certbot --nginx` fehl** (es läuft intern `nginx -t` → MisconfigurationError) — ein klassisches Henne-Ei.
**Fix – nicht einen SSL-vhost vorab anlegen, erst Zertifikat mit HTTP-only-vhost holen:**
1. Temporär einen **rein-HTTP-80-vhost** anlegen (nur `listen 80;`, kein SSL-Referenz):
```bash
# in sites-available: nur listen 80, server_name, root
sudo ln -sf .../sites-available/DOMAIN .../sites-enabled/ # oder in beide Dateien
sudo nginx -t && sudo systemctl reload nginx # JETZT grün
```
2. Zertifikat per **webroot** holen (port-80-challenge, kein nginx-Plugin nötig):
```bash
sudo mkdir -p /var/www/DOMAIN.de/.well-known
sudo certbot certonly --webroot -w /var/www/DOMAIN.de -d DOMAIN.de --agree-tos --register-unsafely-without-email
```
3. Erst **danach** den vollständigen SSL-vhost (mit `listen 443 ssl` + cert-Pfaden) ablegen + `nginx -t && systemctl reload`.
4. Verifizieren: `curl -sk https://DOMAIN.de` → HTTP 200 oder zumindest der SSL-Handshake ok (`curl -sv ... | grep "SSL certificate verify ok"`).
**Reihenfolge ist entscheidend:** Erst Port-80 + Zertifikat existiert, DANN SSL-vhost. Vorab-SSL-vhost = Henne-Ei-Blocker.
### ⚠️ PITFALL – write_file verweigert /etc/systemd oder andere geschützte Pfade
Für systemd-Unit-Services (nicht nginx): `write_file` verweigert ebenso `/etc/systemd/system/`. Muster: In `/tmp` schreiben, dann `sudo cp /tmp/foo.service /etc/systemd/system/` + `systemctl daemon-reload`.
---
## Troubleshooting
| Symptom | Ursache | Fix |
|---------|---------|-----|
| HTTP 403 | Falsche Datei-Rechte | `chown -R www-data:www-data /var/www/` |
| HTTP 404 | index.html fehlt | Pfad in `root`-Direktive prüfen |
| „server_names_hash_bucket_size" | Zu viele/zu lange Domainnamen | `sudo tee -a /etc/nginx/nginx.conf` → `server_names_hash_bucket_size 64;` im http-Block |
| nginx startet nicht | Syntax-Fehler | `sudo nginx -t` zeigt die genaue Zeile |
| write_file „sensitive system path" | Systempfad-Schutz | `sudo tee` im Terminal nutzen |
| ufw inactive | Firewall nie aktiviert | `sudo ufw --force enable` |
skills/devops/nginx-vhost-deployment/templates/nginx-vhost.conf
+21
View File
@@ -0,0 +1,21 @@
server {
listen 80;
listen [::]:80;
server_name {{DOMAIN}} www.{{DOMAIN}};
root /var/www/{{DOMAIN}}/html;
index index.html index.htm;
access_log /var/www/{{DOMAIN}}/logs/access.log;
error_log /var/www/{{DOMAIN}}/logs/error.log;
location / {
try_files $uri $uri/ =404;
}
# location /api/ {
# proxy_pass http://localhost:3000;
# proxy_set_header Host $host;
# proxy_set_header X-Real-IP $remote_addr;
# }
}
skills/devops/openrouter-cost-budgeting/SKILL.md
+102
View File
@@ -0,0 +1,102 @@
---
name: openrouter-cost-budgeting
description: OpenRouter-Usage deckeln und Agents automatisch bremsen.
related_skills: [model-allocation, multi-agent-mesh]
---
# OpenRouter Kosten-Tracking & Budget-Bremse
Kosten für eine Gruppe von Agents (Master + Sub-Agents) über OpenRouter überwachen,
begrenzen und bei Limit automatisch pausieren. Ergänzt `model-allocation` (Modell-Wahl)
um die reine **Kosten-Überwachung + Durchsetzung**.
## NUTZER-BUDGET-MODELL (verbindlich)
- **Hartes Tageslimit: 1$ pro Tag und Agent.**
- **Solange OpenRouter-Credits (Guthaben) vorhanden sind, wird gearbeitet — kein Monats-Cap.**
- Aufladung ~1. des Monats, evtl. am 15. nochmal — nicht garantiert.
- Kein "Team-Monats-Stopp": die einzige harte Grenze ist das 1$/Tag/Agent-Tageslimit plus
technischer Stop, wenn das Guthaben auf 0 fällt.
## OpenRouter-Kosten-API (echte USD)
- `GET /api/v1/credits` → `total_usage` (kumuliert USD über das ganze Konto-Leben) + `total_credits`.
Verfügbar = `total_credits - total_usage`.
- `GET /api/v1/auth/key` → `usage` (dieselbe kumulierte Größe, pro Schlüssel). Alle Keys eines
Accounts zeigen dieselben `/credits`, aber unterschiedliche `/auth/key usage`.
- Header `X-OR-Usage-Cost-USD` ist NICHT verlässlich; der Body liefert stattdessen
`usage.cost` (USD) pro Antwort — verwende das für request-genaue Kosten.
## WICHTIG: Kumulativ vs. Perioden-Delta
`total_usage` ist über das **ganze Konto-Leben** kumuliert. Für Tages-/Monatsbudget IMMER ein
**Delta** rechnen (sonst meldet ein laufendes Konto dauerhaft "über Budget"):
- **Tages-Delta** = letzter Wert des Tages − letzter Wert des Vortags (tagübergreifend,
NICHT innerhalb desselben Tages — sonst entsteht eine Mitternachts-Lücke + Einzel-Tag=0).
- **Monats-Basis** = letzter Eintrag des **Vormonats** (fallback: erster Eintrag dieses Monats,
fallback: row[0]). NIE `row[0]` als Basis allein — das zählte das ganze Konto-Leben.
- **Counter-Reset** abfangen: negatives Delta → 0 (kein falsches "Sparen").
- 7-Tage-Kumulativ zusätzlich prüfen (Agent bleibt täglich <Deckel, summiert aber Wochen-Limit).
## Budget-Bremse / Kill-Switch
1. **Erfassen** (stündlicher Cron): `cost-track` ruft für alle Agents (Master lokal + je
Sub-Agent per SSH, Key bleibt auf dem Agenten, nur Zahl wird zurückgeschickt) die `/credits`
und `/auth/key usage` ab und hängt an eine Zeitreihe `costs.jsonl` an.
2. **Prüfen** (gleicher Cron): `cost-break` vergleicht Deltas gegen Limits (budget.yaml) und
schreibt **`kill_switches.json`** — welche Agents `PAUSED` sind.
3. **Durchsetzen** (auf jedem Sub-Agent-Poller): vor Task-Übernahme prüft der Agent per SSH,
ob sein Name in `kill_switches.json` `PAUSED` ist → wenn ja, keine Tasks übernehmen, kein Geld.
4. **Master (VPSHermes) wird NIE hart pausiert** — er muss sein eigenes System und den Nutzer
weiter betreuen. Nur Sub-Agents werden pausiert.
## Modell-Hart-Sperre (stärkster Kostenhebel)
Wenn EIN Modell den Großteil der Kosten verursacht (z.B. 64% bei einem teuren Pro-Modell),
blockiere es hart — es ist dann gar nicht mehr ladbar:
```bash
hermes config set model.providers.openrouter.blocked_models '["<modell>"]'
# Prüfen: <modell> erscheint nicht mehr in: hermes models list
```
`model.` (Singular), NICHT `models.` — und Hermes-Config NIE per patch/editor ändern, immer
`hermes config set` (patch wird abgelehnt).
## Konfig (budget.yaml — Beispiel)
```yaml
limits:
tageslimit_agent_usd: 1.0 # harte Grenze pro Tag und Agent
tageslimit_gesamt_usd: 4.0 # pragmatisches Gesamt-Cap (4 Agents x 1$)
modelle:
erlaubt: [...]
blockiert: [ ".../v4-pro" ]
bremse:
kill_switch_file: /srv/work/costs/kill_switches.json
```
## Werkzeuge (Referenz-Implementierung)
Siehe `references/cost-brake-ops.md` (betriebliche Details, Python-Call, Fehler-Chronologie):
- `scripts/cost-track.sh` — Zeitreihe erfassen (alle Agents)
- `scripts/cost-break.py` — Limits prüfen → kill_switches.json
- `scripts/cost-report.sh` → HTML-Fragment (USD-Gesamt + Bremse-Status) für Doku-Website
## Doku-Anbindung
Kosten-Sektion in der Live-Panel-Website: zeigt `total_usage_usd`, ob Agents pausiert sind,
und den aktuellen Bremsen-Status. So behält der Master den Gesamtüberblick wie vom Nutzer
gewünscht ("alles überschauen und bremsen").
## Live-Implementierung (mesh-master-control Skill)
Seit August 2026 laeuft auf dem Master der **mesh-budget-watch.sh** Cron (alle 30 Min):
- Ruft `/api/v1/credits` via `curl` ab (echtes Guthaben, nicht kumulativ)
- 3-Stufen-System: Warnung bei <$1, Auto-Switch auf Ollama bei <$0.50, Komplett-Stopp bei <$0.10
- Telegram-Benachrichtigung bei Stufen-Ueberschreitung (entprellt via STATE-File)
- Integriert `mesh-kill-all.sh` fuer den Ollama-Switch
Weitere Details im **mesh-master-control Skill** (`devops/mesh-master-control`).
skills/devops/openrouter-cost-budgeting/references/cost-brake-ops.md
+75
View File
@@ -0,0 +1,75 @@
# Kosten-Bremse — Betriebsreferenz (Session 2026-08)
Ergebnis einer kompletten Nachbaustufe: Kosten-Überwachung + automatisches Bremsen
über OpenRouter in einem Multi-Agent-Mesh (Master + 3 Sub-Agents).
## Tatsächliche OpenRouter-Endpoints (verifiziert 08.08)
```bash
# Konto-weit, USD, kumulativ über Kontoleben:
GET https://openrouter.ai/api/v1/credits
# -> data.total_credits, data.total_usage (total_credits - total_usage = verfügbar)
# Pro-Key:
GET https://openrouter.ai/api/v1/auth/key
# -> data.usage (gleiche kumulierte Größe pro Schlüssel)
```
- Zwei Messe: `/credits` (verbindlich, account-weit) + `/auth/key` (pro-Agent-Verteilung).
- Alle Keys desselben Accounts liefern in `/credits` dieselbe Zahl; `/auth/key usage` differiert.
- `X-OR-Usage-Cost-USD` Response-Header war NICHT vorhanden → stattdessen
`chat-completions` Body `usage.cost` (USD) liefert exakte Pro-Request-Kosten.
## Python-Call für Kosten-Abfrage (Key bleibt lokal)
```python
import json,re,urllib.request
e=open('/root/.hermes/.env').read()
key=re.search(r'OPENROUTER_API_KEY=([A-Za-z0-9_.\-]+)',e).group(1)
h={"Authorization":f"Bearer {key}"}
c=json.load(urllib.request.urlopen(urllib.request.Request(
"https://openrouter.ai/api/v1/credits",headers=h),timeout=15))["data"]
print(c.get("total_credits"), round(c.get("total_usage",0),2))
```
Für Sub-Agents per SSH ausführen, Key bleibt auf dem Agenten, nur die Zahl kommt zurück.
## Delta-Logik (die Kern-Korrektur aus dem Team-Review)
`total_usage` ist KONTOLEBEN-kumulativ. Falsch war: `total_usage > Cap` (pausiert dauerhaft)
und `letzte-heute − erste-heute` (Mitternachts-Lücke, Einzel-Tag=0, Reset negativ).
Korrigiert:
- Tages-Delta tagübergreifend: `letzter-Wert-heute − letzter-Wert-vortag`
- Monats-Basis = letzter Eintrag des VORMONATS (fallback Monatsanfang, fallback row[0])
- negative Werte → 0
- 7-Tage-Kumulativ-Summe als Zweit-Check
## Kill-Switch-Durchsetzung (Poller-Guard)
In `mesh-agent-poller.sh` vor der Task-Übernahme:
```bash
KILL_CHECK=$($SSH_CMD "python3 -c \"
import json
try: d=json.load(open('/srv/work/costs/kill_switches.json'))
except Exception: d={}
sw=d.get('kill_switches',{}).get('$MEINE_ID',{})
print('PAUSED' if sw and sw.get('status')=='PAUSED' else 'OK')" 2>/dev/null")
if [ "$KILL_CHECK" = "PAUSED" ]; then log "Budget-BREMSE aktiv"; exit 0; fi
```
## Modell-Block (Hermes)
`hermes config set model.providers.openrouter.blocked_models '["deepseek/deepseek-v4-pro"]'`
(Key `model.` Singular). Danach taucht es nicht mehr in `hermes models list` auf.
## Chronologie der Fehler (saubere Lektionen)
1. Erst 25$ Monats-Cap → zu aggressiv → Nutzer korrigierte: Wallet-Modell (1$/Tag/Agent,
kein Monats-Stopp, solange Guthaben da arbeiten).
2. `total_usage` kumulativ mit Cap verglichen → dauerhafter Fehlalarm → Team (Switch) meldete
row[0]-Basis-Problem → auf Vormonats-Basis korrigiert.
3. Unser eigenes Sup-Tool-Test überschrieb `costs.jsonl` mit Testdaten → Echte-Daten wiederherstellen
via frischem cost-track-Lauf (kein Test-Artefakt zurücklassen).
4. `models.` vs `model.` Config-Key → Singular.
skills/devops/operational-dashboard-archive/SKILL.md
+249
View File
@@ -0,0 +1,249 @@
---
name: operational-dashboard-archive
description: "Betriebsdoku: Live-Panel + Tages-Archiv per Cron."
version: 1.0.0
author: hermes-curator
platforms: [linux]
models:
default: mimo-v2-flash
---
# Operational Dashboard & Archive — autonome Betriebsdokumentation
> Nutzeranforderung (2026-08-03): *"Alles dokumentieren in Zukunft. Das will ich immer sehen können."* + *"Tägliche Zusammenfassung als Archiv perfekt."*
> Format: **kompakt + informativ, NICHT zu detailliert.** Wochenzahlen + Kernereignisse + Ausblick.
Zweck: Aus einem laufenden, dateibasierten Arbeitsordner (Tasks/Agenten/Server) automatisch zwei Websites generieren, ohne manuellen Eingriff:
1. **Live-Panel** — Echtzeit-Zustand (Agenten, Tasks, Kosten, Ereignis-Protokoll)
2. **Tages-Archiv** — chronologische Tageszusammenfassungen (dauerhaft, pro Datum)
## Bausteine
```
/srv/work/
├── tasks/{offen,in_arbeit,fertig,bugfix,archiv} # Task-Verzeichnisse (Quelle)
├── log/events.jsonl # Ereignis-Log (durchgängig append)
├── wissensbasis.md # verteilte Wissensbasis (ohne Secrets)
└── registry.json # Agenten-/hierarchie-Registry
```
## Kernscripts (in /usr/local/bin/)
| Script | Funktion |
|--------|----------|
| `mesh-log.sh <aktion> <detail> [agent] [kosten]` | Append eine Ereigniszeile (JSONL) — **JEDE Aktion loggen** |
| `mesh-master-report.sh` | Regeneriert Live-Panel-HTML aus Tasks + Log (kein PHP nötig, statisch) |
| `mesh-daily-archive.sh` | Erzeugt Tages-Summary `<datum>.html` + aktualisiert index |
> ⚠️ **Aktueller Präfix: `mesh-`** (seit 2026-08-03). Frühere Referenzen auf `duo-*`
> (`duo-master-report.sh`, `duo-daily-archive.sh`, `duo-task-create.sh`, `duo-log.sh`)
> wurden auf `mesh-*` umbenannt — alte Namen existieren nicht mehr. Beim Aufruf IMMER `mesh-` verwenden.
## Live-Panel (dokumentationen.<domain>)
`mesh-master-report.sh` liest:
- Task-Ordner → Tabelle (Task-ID, Ziel, Typ, Status, Bearbeiter, Kosten, Dauer)
- `events.jsonl` → letzte 40 Ereignisse
- Summiert heutige Kosten (`grep <heute> | sum kosten_eur`)
- Render statisches HTML in `/var/www/<panel-site>/index.html`
**Kein PHP/Build nötig** — rein Shell+python3-inline. Regenerate per Cron alle 60s (versetzt, damit nicht kollidierend). Für „mehr Action" 30s-Takt (2 Cron-Zeilen mit `sleep 30`).
### 🔑 Pitfall: Ereignis-Tabelle bleibt LEER (pipe-in-subshell + set -e)
**Symptom:** Log hat Dutzende Einträge, aber die Panel-Ereignistabelle zeigt „Noch keine Einträge."
**Ursache:** `LOGROWS=$(tail -40 "$LOG" | while ... done)` — die while-Loop wird in einer
Subshell der Variablen-Zuweisung ausgeführt; unter `set -euo pipefail` bleibt die Variable leer.
**Fix:** Parsing über ein Tempfile statt pipe-in-subshell:
```bash
TMPEV=$(mktemp)
python3 - "$LOG" "$TMPEV" << 'PYEOF' # liest JSONL, schreibt rows[-40:] nach tempfile
PYEOF
LOGROWS=$(cat "$TMPEV"); rm -f "$TMPEV"
```
Gleiches Muster für die Kosten-Tabelle (pro-Agent-Summe via Tempfile).
### Live-Online-Status (Agentenliste NICHT hartkodieren)
Agenten-Status in der Tabelle sollte bei jeder Regenerierung per `ping -c1` geprüft werden
(oder SSH). Statisch „offline" eingetragen → falsch, sobald ein gerade onboardeter Agent
online ist. Baue die Zeilen dynamisch: `${AGENT_STATUS}` pro Agent mit `ping` → badge online/offline.
## Tages-Archiv (archiv.<domain>)
`mesh-daily-archive.sh` (Cron **23:50 täglich**):
1. Filtert `events.jsonl` auf heute
2. Statistikkarten: Aktionen, Kosten, fertig/offen/bugfix
3. Schreibt `<YYYY-MM-DD>.html` + aktualisiert `index.html` (Linkliste aller Tage)
4. Retrospektive Einträge möglich (z.B. Start-Eintrag mit Gesamtüberblick)
### 🔒 Archiv NUR bei Aktivität + Leertage zusammenfassen (NUTZERWUNSCH 2026-08-07)
Nutzerregel: *"Nur bei Aktivität. Wenn ihr als Team was macht und oder ich was anstoße."* — und: *"Fasse leere Tage einfach zusammen um das Archiv nicht mit zu vielen Leerstand zu füllen."*
Umsetzung im `mesh-daily-archive.sh` (Guard nach ANZAHL-Berechnung, vor dem HTML):
- Wenn `ANZAHL=0` (keine heute-Log-Events) **UND** `FERTIG=0` (keine fertigen Tasks heute) → **keine Einzelseite erzeugen**, stattdessen Datum in Sammelliste `leerstand.json` aufnehmen und `exit 0`.
- `leerstand.json` = Liste der Leertage. Der **Archiv-Index** zeigt sie als EINE kompakte Zeile: "1 Tag(e) ohne Aktivität: 2026-08-02".
- Sobald ein Tag Aktivität bekommt, bekommt er seine normale Seite (und verschwindet aus der Leerstand-Notiz).
```bash
LEERSTAND_FILE="/srv/work/costs/leerstand.json"
if [ "$ANZAHL" = "0" ] && [ "$FERTIG" = "0" ]; then
python3 - "$LEERSTAND_FILE" "$WERTE_DATUM" << 'PYEOF'
import json, sys
f, heute = sys.argv[1], sys.argv[2]
try: tags = json.load(open(f))
except Exception: tags = []
if heute not in tags: tags.append(heute)
json.dump(sorted(tags), open(f,"w"), ensure_ascii=False, indent=2)
PYEOF
echo "ℹ️ $HEUTE: keine Aktivität - als Leertag zusammengefasst"; rm -f "$TAGES_EVENTS"; exit 0
fi
```
Index-Notiz (vor "Alle Tage"): `${LEERSTAND_NOTE}`, aus `leerstand.json` erzeugt — filtert Tage aus, die bereits eine echte Seite haben.
**Pitfalls (erlebt):**
- `ls /dir/*.json` ohne Match → Exit 2 → bricht unter `set -euo pipefail` ab. Fix: `shopt -s nullglob` um den Glob legen.
- `ARCHIV_LINKS=$(ls "$WEB"/*.html ... | while read...)` bei leerem Verzeichnis: nullglob um die Glob-Expansion, sonst Exit 2.
- Rohes `$(date '+%d.%m.%Y %H:%M:%S')` im heredoc eskapt/ersetzt (sed), sonst bleibt der Literal-String im HTML.
- Nach Erzeugung immer verifizieren: `curl -s -o /dev/null -w "%{http_code}" https://<site>/<datum>.html`
## Ereignis-Log-Konvention
Jede Aktion via `mesh-log.sh` loggen, **bevor** das Panel regeneriert wird:
```bash
/usr/local/bin/mesh-log.sh "security" "Firewall gehärtet: nur bekannte IPs" agent-a 0
/usr/local/bin/mesh-master-report.sh
```
Kontext (WAS und WARUM) gehört ins Log — so ist jedes Panel eine lückenlose Historie.
### Agent-Selbstdokumentation (NUTZERWUNSCH 2026-08-03)
Jeder Agent soll seine fertigen Tasks **selbst** dokumentieren — nicht nur der Master.
Der Agent-Poller pusht nach `✅ Fertig` eine Ereigniszeile auf den Master:
```json
{"aktion":"task_fertig_agent","agent":"<AGENT-ID>","kosten_eur":N,"detail":"Task <id> abgeschlossen"}
```
→ Panel zeigt Aktionen namentlich + Kosten, auch wenn der Agent unabhängig arbeitete.
`mesh-log.sh` bleibt für Master-Aktionen; Agenten appenden direkt ans `events.jsonl`
(via `$SSH_CMD "echo '...' >> /srv/work/log/events.jsonl"`).
## Kostenanzeige (Budget-Kontrolle)
- Hartes Tagesbudget **1€/Agent**
- Panel summiert heutige Kosten aus `events.jsonl` (Feld `kosten_eur`)
- Anzeige als Prominent-Karte: `💰 Heutige Kosten: X € (Budget 1€/Agent/Tag)`
- **Kosten pro Agent** als eigene kleine Tabelle (pro-Agent-Summe für heute)
- hält den budgetbewussten Nutzer informiert, ohne Logs lesen zu müssen
### ⚠️ Pitfall: Panel zeigt 0€ obwohl OpenRouter-Kosten laufen
`events.jsonl`-Feld `kosten_eur` bleibt meist 0, weil die echten OpenRouter-Kosten
**nicht automatisch erfasst** werden. Der Nutzer-Test wird "0.000€" im Panel sehen,
während real Budget verbraucht wird. Fix = separates **mesh-cost**-System (getestet 08-07),
das die Nutzer-Dashboard-Referenz (USD) + pro-Agent-Usage abbildet.
### Echte Kosten-Governance: mesh-cost-System (getestet 2026-08-07)
Zentraler Master pollt die **OpenRouter-`usage` ALLER 4 Agenten** (Keys bleiben lokal),
schreibt Zeitreihe und erzeugt einen **Budget-Bremsen-Mechanismus** (kill_switches).
| Datei | Zweck |
|-------|-------|
| `/usr/local/bin/mesh-cost-track.sh` | stündl. OpenRouter-`usage` je Agent → `costs.jsonl` |
| `/srv/work/costs/costs.jsonl` | Zeitreihe `{ts, master, unraid, switch, laptop}` |
| `/srv/work/costs/budget.yaml` | Deckel je Agent + Modell + Gesamt |
| `/usr/local/bin/mesh-cost-break.py` | Usage vs. budget.yaml → `kill_switches.json` |
| `/srv/work/costs/kill_switches.json` | zentrale Bremse (0666), von allen Agents gelesen |
| `/usr/local/bin/mesh-cost-report.sh` | HTML-Fragment Kosten+Bremse-Status (in Panel) |
**Bremsen-Ablauf:** Master vergleicht → setzt `PAUSED` je Agent → jeder Sub-Agent-Poller
liest `kill_switches.json` (SSH) und **übernimmt keine Tasks** wenn sein Name `PAUSED`
(eine der Kernregeln: keinen Task bearbeiten → keine Kosten). Guard in
`mesh-agent-poller.sh` (Schritt "0. KILL-SWITCH-BREMSE"), identische Datei auf allen
3 Agents, nur KEY-Pfad je anders.
**Panele-Einbindung:** `mesh-master-report.sh` ruft `$(bash /usr/local/bin/mesh-cost-report.sh)`
vor "Betriebsregeln" → zeigt Gesamt-USD + pro-Agent-Usage + grünen/roten Bremse-Status.
**Fallstricke:**
- `usage` ist **kumulativ** (seit Key-Start), nicht pro Tag → für Tagesdeckel das
**Tages-Delta** rechnen (letzter − erster Wert desselben Kalendertags), sonst wird
fälschlich ALLES als über Limit pausiert.
- `usage` ≠ USD (OpenRouter-Credits). Verbindlicher Referenzwert = Nutzer-Dashboard
(openrouter.ai Activity). Beide anzeigen.
- Detail-API `/api/v1/generation` gibt **400** (abgeschaltet) — nur Gesamt-`usage` je
Key ist zuverlässig abrufbar.
- Kronen-Guard: Agent-Namen im JSON = "UnraidHermes"/"SwitchHermes"/"LaptopHermes"
(exakte Namen, nicht IP), Vergleich gegen `$MEINE_ID`.
### ✅ Nachgezogen 2026-08-08 — echte USD-Quelle + Monats-Delta + harter Gang
**Echte USD-Quelle (besser als `usage`):** `GET https://openrouter.ai/api/v1/credits`
liefert `{total_credits, total_usage}` — `total_usage` ist der **verbindliche USD-Verbrauch
(account-weit)**. Alle 4 Agenten-Keys melden denselben account-weiten `total_usage`;
`usage` aus `/api/v1/auth/key` unterscheidet noch die grobe pro-Key-Relation.
**⚠️ KRITISCH: `total_usage` ist KUMULATIV über das ganze Konto-Leben, NICHT pro Monat.**
Ein Monats-Cap darf NICHT `total_usage > limit` prüfen (altes Konto → dauerhaft gebremst,
niemand kann mehr arbeiten). Stattdessen **Monats-Delta** = letzter Wert − Basis, wobei
die Basis am robustesten der **letzte Eintrag des VORMONATS** ist. Die zunächst getestete
Basis `rows[0]` ist FEHLERHAFT: bei fehlendem Vormonats-Eintrag würde `rows[0]` =
Kontostart genommen → Delta = Gesamtverbrauch → sofortige Falschbremse. Dieser Bug wurde
**nur durch Team-Review (SwitchHermes basix-danger) gefunden** — Beleg dafür, dass
Kostenlogik IMMER gegenprüfen lassen, nie solo absegnen.
```python
monat = today[:7]
vormonat = monat[:5] + str(int(monat[5:7]) - 1).zfill(2) if int(monat[5:7]) > 1 else ""
basis = None
if vormonat:
vm = [r for r in rows if r["ts"][:7] == vormonat]
basis = vm[-1] # letzter Vormonats-Eintrag = stabile Basis
if basis is None:
ma = [r for r in rows if r["ts"][:7] == monat]
basis = ma[0] if ma else rows[0]
monats_delta = max(0.0, rows[-1]["total_usage_usd"] - basis["total_usage_usd"])
```
**NUTZER-BUDGET-MODELL (FINAL, 2026-08-08 — ersetzt früheres 20$/Monat-Modell):**
Die einzige harte Grenze ist **1$ pro Tag und Agent**. Solange OpenRouter-Credits
(Guthaben) vorhanden sind, wird **weitergearbeitet** — KEIN Team-Monats-Stopp, KEIN
hartes 20$-Cap als Abrisskriterium. Der Nutzer lädt am Monatsanfang ~20$ auf (evtl.
am 15. nochmal ~20$, nicht garantiert); ist das Guthaben real aufgebraucht, fällt
Arbeit automatisch auf **Free-Modelle oder lokales VPS-Ollama** (`deepseek-r1:7b`).
Buchführung: `total_credits − total_usage` (aus `/api/v1/credits`) = Rest. In der
Bremse wird der **Master (VPSHermes) ausgenommen** (`continue`) — er muss sein System
und den Nutzer weiter betreuen; nur Sub-Agenten hart pausieren.
**Modell hart blockieren (schnellster Kostenspar-Hebel):**
`hermes config set model.providers.openrouter.blocked_models '["modell/id"]'`
- ACHTUNG: Key ist **`model.`** (Singular), nicht `models.` — sonst wird er nur als
eigener Top-Level-Key gespeichert, den Hermes nicht liest.
- Danach ist das Modell aus `hermes models list` verschwunden, Fallback greift aufs nächste.
- Noch robuster: **Allowlist** (`allowed_models`) mit nur günstigen Modellen — neue teure
Modelle automatisch geblockt. (LaptopHermes-Empfehlung)
Ausführliche Mechanik (Endpoints, kill_switch-Guard-Code, Test-Muster) in
`references/openrouter-cost-governance.md`.
**Team-Review-Gegenprüfung ist PFLICHT für Kosten/Bremse-Logik (NUTZERWUNSCH, mehrfach
betont 08.08):** nie solo bauen/absegnen — via `mesh-task-create.sh` an die Rechen-Agenten
verteilen (Unraid/Switch/Laptop), die gegeneinander prüfen. Konkrete Belege: Unraid fand
die Tages-Delta-Mitternachtslücke + Counter-Reset; Switch fand die fehlerhafte `rows[0]`-Basis
(das wäre solo übersehen worden). **Pitfall beim Verteilen:** Review-Prompts, die den Agenten
zum Laden von Dateien/Skills anregen, laufen in dessen Iterationslimit (3) → nur Reasoning,
kein `# Ergebnis`-Block, Task landet als "kein Ergebnis". Fix: fehlgeschlagene Tasks → `bugfix/`,
neu stellen mit *"antworte NUR aus deinem Wissen, LADE KEINE Dateien/Skills, antworte sofort"* —
dann kommt auch bei kleinen Agente-Modellen ein verwertbares Ergebnis.
**Test-Muster (verifiziert):** kill_switches → `{"UnraidHermes":{"status":"PAUSED"}}`;
Test-Task für Unraid bleibt in `offen/`; Poller-Log `⏸️ Budget-BREMSE aktiv`; Reset
`{}` → nimmt wieder an.
## Verifikationsschleife (immer nach Änderung)
1. `curl` auf Panel + Tagesseite → HTTP 200
2. Aus dem HTML per `grep -oP` den erwarteten Sektions-Titel prüfen
## Referenzen
- Session 2026-08-03 (Erstaufbau: Doku-System + Archiv). Mesh-/Task-spezifische Details (IP-Schema, Polling, NFS, Firewall) liegen im `multi-agent-mesh`-Skill.
- `references/task-share-polling-and-rename.md` — Validierter Polling-Ablauf (NFS + SSH/scp-Variante, 0666-Fix, systemd user service), + Script-Rename `duo-*`→`mesh-*`.
skills/devops/operational-dashboard-archive/references/openrouter-cost-governance.md
+98
View File
@@ -0,0 +1,98 @@
# OpenRouter-Kosten-Governance (reale USD-Werte)
Verifizierte Mechanik (2026-08) für echtes USD-Kosten-Tracking + Budget-Bremse im
Multi-Agent-Mesh. Lebt unter `operational-dashboard-archive` (Kostenanzeige-Sektion).
## Drei OpenRouter-Endpoints (verifiziert)
| Endpoint | Liefert | Verwendung |
|----------|---------|-----------|
| `GET /api/v1/credits` | `total_credits`, `total_usage` | **verbindlicher USD-Verbrauch, account-weit** |
| `GET /api/v1/auth/key` | `usage` (pro Key) | grobe pro-Agent-Verteilung |
| `POST /api/v1/chat/completions` | `usage.cost` (Body) | exakter Pro-Request-USD |
```python
import json, re, urllib.request
env = open('/root/.hermes/.env').read()
m = re.search(r'OPENROUTER_API_KEY=([A-Za-z0-9_.\-]+)', env)
h = {"Authorization": f"Bearer {m.group(1)}"}
d = json.load(urllib.request.urlopen(
urllib.request.Request("https://openrouter.ai/api/v1/credits", headers=h),
timeout=20))["data"]
print(d["total_credits"]) # aufgeladen gesamt
print(d["total_usage"]) # verbraucht (USD, KUMULATIV über Konto-Leben!)
```
Sub-Agenten: gleicher Aufruf per SSH auf deren `.env` (Key bleibt lokal, nur Zahl zurück).
Alle Keys eines Accounts melden denselben `total_usage`; `/auth/key usage` unterscheidet pro Key.
## ⚠️ Der große Stolperstein: total_usage ist KUMULATIV
`total_usage` zählt über das **gesamte Konto-Leben**, nicht pro Monat. Ein Monats-Cap
darf NICHT `total_usage > limit` prüfen — ein altes Konto stünde sofort dauerhaft über
dem Limit (alles gebremst, niemand kann mehr arbeiten).
Monats-Delta statt Gesamtwert:
```python
monat = today[:7] # z.B. "2026-08"
vormonat = monat[:5] + str(int(monat[5:7]) - 1).zfill(2) if int(monat[5:7]) > 1 else ""
basis = None
if vormonat:
vm = [r for r in rows if r["ts"][:7] == vormonat]
basis = vm[-1] # letzter Vormonats-Wert (stabil)
if basis is None:
ma = [r for r in rows if r["ts"][:7] == monat]
basis = ma[0] if ma else rows[0]
monats_delta = max(0.0, rows[-1]["total_usage_usd"] - basis["total_usage_usd"])
```
Fehler, den NUR das Team-Review fand: Basis `rows[0]` ist falsch, wenn der Monat noch
keinen Eintrag hat (dann = Konto-Eröffnung → Delta = Gesamtverbrauch → Falschbremse).
Also IMMER Vormonats-Wert als Basis bevorzugen.
## Kill-Switch-Bremsen-Muster (harter Halt)
1. Master schreibt `/srv/work/costs/kill_switches.json` `{"kill_switches":{agent:{"status":"PAUSED"}}}` (chmod 0666).
2. Jeder Sub-Agent-Poller liest sie per SSH VOR jeder Task-Übernahme:
```bash
KILL=$($SSH_CMD "python3 -c \"import json;d=json.load(open('/srv/work/costs/kill_switches.json'));ks=d.get('kill_switches',{});sw=ks.get('$MEINE_ID',{});print('PAUSED' if sw and sw.get('status')=='PAUSED' else 'OK')\" 2>/dev/null")
[ "$KILL" = "PAUSED" ] && { log "Budget-BREMSE aktiv,$MEINE_ID"; exit 0; }
```
3. **Master (VPSHermes) in der Gesamt-Bremse ausgenommen** (`continue`) — er muss sein
System + den Nutzer betreuen; nur Sub-Agenten hart pausieren.
Getestet: Sub-Agent mit PAUSED lässt Task in `offen/` liegen; nach Reset `{}` nimmt sofort wieder an.
## Modell hart blockieren
`hermes config set model.providers.openrouter.blocked_models '["modell/id"]'`
- WICHTIG: **`model.`** (Singular), nicht `models.` — sonst eigener Top-Level-Key, ungenutzt.
- Danach weg aus `hermes models list`; Fallback greift aufs nächste.
- Robuster: **Allowlist** (`allowed_models`) nur günstige Modelle → neue teure automatisch geblockt.
- Schnellster Kostenspar-Hebel: ein einzelnes teures Modell (z.B. deepseek-v4-pro = ~64%
der Kosten) hart blocken → dessen Anteil → fast 0.
## Nutzer-Budget-Modell (FINAL, 2026-08-08 — ersetzt früheres 20$/Monat-Modell)
Die einzige harte Grenze ist **1$ pro Tag und Agent**. Solange OpenRouter-Credits
(Guthaben) vorhanden sind, wird weitergearbeitet — KEIN Team-Monats-Stopp, kein hartes
20$-Cap als Abrisskriterium. Rest = `total_credits − total_usage` (aus `/api/v1/credits`).
Der Nutzer lädt am Monatsanfang ~20$ auf (evtl. am 15. nochmal ~20$, nicht garantiert);
ist das Guthaben real aufgebraucht, fällt Arbeit von selbst auf **Free-Modelle oder
lokales VPS-Ollama** (`deepseek-r1:7b`). Master überwacht Gesamtkosten (stündl. Cron:
`mesh-cost-track.sh` → `mesh-cost-break.py`), bremst automatisch via Kill-Switches;
Master selbst bleibt dabei immer aktiv.
## Team-Pflicht bei Kosten-Logik
Kosten/Deckel/Basislogik NIEMALS solo absegnen — gegenprüfen lassen (anderer Agent).
Ein vergessenes Detail (Basiswahl, Monatswechsel, Reset) wird sonst erst als
Dauer-Falschbremse real. "4 günstige Agents zusammen sind besser als 1 teurer Agent
und halten die Kosten niedrig."
**Pitfall beim Verteilen von Review-Tasks:** Prompts, die den Agenten zum Laden von
Dateien/Skills anregen, laufen in dessen Iterationslimit (3) → nur Reasoning, kein
`# Ergebnis`, Task wird als "kein Ergebnis" gewertet. Neu stellen mit *"antworte NUR aus
deinem Wissen, LADE KEINE Dateien/Skills, antworte sofort"* — dann liefert auch ein
kleines Agent-Modell verwertbares Ergebnis.
skills/devops/operational-dashboard-archive/references/task-share-polling-and-rename.md
+149
View File
@@ -0,0 +1,149 @@
# Task-Share Polling — Working Architecture + Script Rename (2026-08-03)
Session 2026-08-03 erzielte den **end-to-end funktionierenden** Sub-Agenten-Polling-Lauf.
Diese Notiz konserviert die validierten Erkenntnisse, da `multi-agent-mesh` (der
eigentliche Heimat-Skill) user-owned und für den Curator gesperrt ist.
## Script-Rename `duo-*` → `mesh-*` (NUTZERWUNSCH)
Der Begriff "Duo" ist überholt (nur noch A+B). Das Mesh hat 4 Agenten + Master.
Alle Tools in `/usr/local/bin/` (und ggf. `~/.local/bin/`) wurden 2026-08-03 umbenannt:
```
duo-task-create.sh → mesh-task-create.sh
duo-master-poller.sh → mesh-master-poller.sh (Ausfall-Fallback, DEAKTIVIERT)
duo-master-report.sh → mesh-master-report.sh
duo-daily-archive.sh → mesh-daily-archive.sh
duo-agent-poller.sh → mesh-agent-poller.sh
duo-log.sh / mesh-log.sh (war schon mesh-log)
```
Cron-Referenzen, SOUL.md, Memory und Skill-Doku müssen auf `mesh-*` zeigen.
**Belasse historische Editor-/Referenz-Dateinamen im Skill wie sie sind** (z.B.
`references/duo-ssh-trigger-*.md`) — nur AKTIVE Skripte/Crons/SOUL/Websites umbenennen.
## ROOT-CAUSE des "Polling funktioniert nie"
Kein Coding-Fehler im Poller, sondern **Datei-Berechtigungen**: Task-Dateien vom Master
(root) erstellt; über NFS behält `mv` den Owner → Sub-Agenten (uid 1000) konnten die
root-eigene Datei nicht überschreiben, selbst bei 0777-Verzeichnissen.
Symptome: `PermissionError: [Errno 13]`, `json.JSONDecodeError`, "SKIP (Lock verloren)".
Fix: `chmod 0666` beim Anlegen (mesh-task-create) UND nach jedem mv im Poller.
## Zwei Poller-Varianten
- **NFS** (normale Server): Mount + lokaler Zugriff. Nutzt UnraidHermes.
- **SSH/scp** (Hosts OHNE NFS/FUSE, z.B. Nintendo Switch, Tegra-Kernel `4.9.140-l4t`):
kein NFS-Client-Modul, kein FUSE/sshfs ("mount.nfs: Protocol not supported").
Ohne großen Kernel-Eingriff (Switch: wenig Speicher) funktioniert NFS nicht.
Poller: scp-pull eigene Tasks (`.C.D.*`) vom Master, atomare mv-Sperre per SSH,
bearbeiten via `hermes chat -q`, scp-push Ergebnis, verschieben nach fertig/.
## SSH-Poller-Kritische Bugs (vermieden)
1. `SSH_CMD` MUSS den Host enthalten: `SSH_CMD="ssh -i $KEY ... ${MASTER}"` und dann
**unquoted** `$SSH_CMD` verwenden. Fehlt der Host → "hostname contains invalid characters".
2. mv-Sperre mit **absoluten Pfaden**, nicht relativen (`../../../` ist falsch von offen/
aus; sauberer sind absolute Pfade).
3. Ergebnis **Base64-geschützt** ins JSON-Feld `result` schreiben (`base64 -w0`),
NICHT per `printf` ans Dateiende (macht JSON ungültig).
## Daemon dauerhaft halten: systemd USER-Service
`nohup ... &` stirbt beim SSH-Session-Ende; `@reboot`-Cron mit nohup ist fragil
(pgrep-Selbstmatch: `pgrep -f "mesh-poller-daemon"` matcht den startenden Prozess
selbst → "läuft bereits" ohne echten Loop). Robust: **systemd user service** + Daemon-
Wrapper mit PID-Datei (statt pgrep).
```bash
# ~/.config/systemd/user/mesh-poller.service
[Unit]
Description=Mesh Sub-Agent Poller (alle 10s)
After=network-online.target
[Service]
Type=simple
Environment=PATH=/home/<user>/.local/bin:/usr/bin:/bin
ExecStart=/home/<user>/.local/bin/mesh-poller-daemon.sh <ZT-IP> <AGENT-ID>
Restart=always
RestartSec=5
[Install]
WantedBy=default.target
```
```bash
export XDG_RUNTIME_DIR=/run/user/$(id -u)
systemctl --user daemon-reload
systemctl --user enable --now mesh-poller.service # überlebt SSH-Ende + Boot
```
**Daemon-Wrapper (PID-Datei statt pgrep):**
```bash
PIDFILE="$HOME/.local/bin/mesh-poller.pid"
if [ -f "$PIDFILE" ] && kill -0 "$(cat "$PIDFILE")" 2>/dev/null; then exit 0; fi
echo $$ > "$PIDFILE"; trap 'rm -f "$PIDFILE"' EXIT
while true; do timeout 130 <poller> <IP> <ID> >> "$LOG" 2>&1; sleep 10; done
```
## Validierter E2E-Durchlauf (03.08.)
```
UnraidHermes (NFS): [02:07:17] ✋ Übernommen → [02:08:02] ✅ Fertig (Wissensbasis)
SwitchHermes (SSH/scp): [02:26:26] ✋ Übernommen → [02:26:40] ✅ Fertig (HelloWorld)
SwitchHermes (SSH/scp): [02:27:28] ✋ Übernommen → [02:29:33] ✅ Fertig (Wissensbasis, dauert ~2min auf Tegra)
```
## Grenzen / Stand
- Ausfall-Fallback ("auf beliebig" nach 30s) ist **deaktiviert** (03.08.) — zu aggressiv,
leitete frische Tasks fälschlich um. Neu-Zuteilung nur manuell durch Master.
- Größere Wissensbasis-Dateien auf schwacher Hardware (Tegra) brauchen 2+ min;
`hermes chat -q --max-turns 3` reicht, `--max-turns 5+` schneidet Output ab.
- LaptopHermes wurde **noch am selben Tag** (03.08.) onboardet — endete auf SSH/scp-Poller
+ systemd-Service wie die beiden anderen. Damit sind ALLE 3 Sub-Agenten über SSH/scp aktiv.
## fail2ban bannt Sub-Agenten (SSH Connection refused)
**Symptom (häufige Fehlersuche):** Ping auf Master geht (0% loss), aber SSH/scp des
Sub-Agenten gibt `Connection refused` — obwohl sshd auf 0.0.0.0:22 lauscht und Port 22
von außen erlaubt ist. Verbindung wirkt asymmetrisch (ein Agent geht, der andere nicht).
**Ursache:** fail2ban-sshd bannt die ZT-IP des Sub-Agenten. Die scp/Key-Logins der Agenten
werden als fehlgeschlagene Versuche gewertet → nach maxretry gebannt.
**Check:** `fail2ban-client status sshd | grep "Banned IP"` → ZT-IP in der Liste.
**Fix:** entbannen + Dauer-Whitelist in `/etc/fail2ban/jail.local` (in der AKTIVEN [sshd]-Sektion,
nicht doppelt anlegen), dann `fail2ban-client reload`:
```
[sshd]
ignoreip = 172.24.34.142 172.24.20.26 172.24.178.202 172.24.92.162
```
> Schreib-/Reload-Schritte können vom Gateway-Schutz geblockt werden. Inhalt erst per
> write_file nach /tmp/, dann cp nach Ziel + Reload separat ausführen.
## Kanonische Agentennamen (NUTZERWUNSCH 2026-08-03 — durchgängig)
Der Nutzer korrigierte wiederholt inkonsistente Namen. **Die kanonischen Namen sind:**
| Kanonisch | (veraltet — nie mehr verwenden) |
|-----------|----------------------------------|
| **VPSHermes** | Agent A, agent-a |
| **UnraidHermes** | Agent B, agent_b |
| **SwitchHermes** | — (gleich) |
| **LaptopHermes** | — (gleich) |
Gilt in ALLEN Stellen: `registry.json` (name/codename), Live-Panel, Tages-Archive
(auch historische Einträge), Ereignis-Log (`agent`-Feld + `detail`-Texte), Wissensbasis,
SOUL.md, Skill-Templates. Die Rolle „Master" bleibt als Funktion bestehen — nur der Name
ist VPSHermes.
**Pitfall (beim bereinigen erlebt):** Archive werden aus `events.jsonl` generiert — die
fertige `.html` nur per sed zu fixen reicht NICHT, wenn der Generator weiterhin den alten
Namen schreibt (z.B. `mesh-daily-archive.sh` hatte statisch „Master (Agent A)" im Footer).
Immer zuerst die Quelle bereinigen: `events.jsonl` (sowohl `agent`-Feld als auch
`detail`-Texte: `Agent A→VPSHermes`, `Agent B→UnraidHermes`, `agent-a→vpshermes`), dann
die Report-/Archive-Generatoren, dann die fertigen `.html`. `sed` auch über historic
Archiv-HTML laufen lassen, nicht nur über neueste.
skills/devops/projekt-planung/SKILL.md
+136
View File
@@ -0,0 +1,136 @@
---
name: projekt-planung
description: "Neues Webprojekt konzipieren: Domain, Landingpage, Konzept-Markdown, PDF-Export, iterative Verfeinerung mit User"
version: 1.0.0
author: Agent A
platforms: [linux]
---
# Projekt-Planung — Vom Brainstorming zur Landingpage
Workflow für neue Webprojekte auf dem netcup VPS: Konzept im Chat entwickeln, als Markdown speichern, Landingpage aufsetzen, bei Bedarf PDF generieren.
---
## Schritt 1: Brainstorming IM CHAT
- **Alles direkt im Telegram-Chat besprechen** — nicht in Dateien verstecken
- User gibt Ideen, ich strukturiere und mache Gegenvorschläge
- Architektur-Skizzen als ASCII-Art im Chat
- Tabellen für Vergleiche (z.B. Tech-Stack-Entscheidungen)
- User-Feedback sofort einarbeiten
---
## Schritt 2: Konzept-Dokument
Sobald die Richtung klar ist: `/root/<projekt>-konzept.md` anlegen mit:
```markdown
# Projektname
> Domain, Preis, Repo, Stand
## Vision
## Datenquellen / Architektur
## Tech-Stack
## Features
## Roadmap (Phasen)
## Offene Punkte (Checkliste mit [ ] und [x])
```
---
## Schritt 3: Landingpage aufsetzen
```bash
mkdir -p /var/www/<domain>/html
chown -R www-data:www-data /var/www/<domain>
# nginx VHost
cat > /etc/nginx/sites-available/<domain> << 'EOF'
server {
server_name <domain>;
root /var/www/<domain>/html;
index index.html;
location / { try_files $uri $uri/ =404; }
listen 80;
}
EOF
ln -sf /etc/nginx/sites-available/<domain> /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
# SSL
certbot --nginx -d <domain> --non-interactive --agree-tos --email admin@<hauptdomain> --redirect
```
**Landingpage-Inhalt:** Projektname, Slogan, Kern-Features (Grid), Roadmap, Footer mit Links zu verwandten Projekten.
**Stil:** Dark-Theme, grüne Akzente (#10b981), responsive, auf Deutsch.
---
## Schritt 4: PDF bei Bedarf
User will manchmal PDF zum Mitnehmen. **PDF ist BONUS, nicht Ersatz für Chat-Inhalt.**
```bash
wkhtmltopdf /tmp/<projekt>.html /tmp/<Projekt>_Konzept.pdf
```
- HTML aus Markdown generieren mit deutschem CSS
- Als MEDIA:/pfad senden
- Vorher IMMER den Inhalt im Chat präsentieren
---
## Schritt 5: Iteratives Verfeinern
- User-Feedback → Konzept-Markdown patchen → PDF neu generieren
- Version hochzählen (v1, v2, v3...)
- Offene Punkte als Checkliste pflegen (`[x]` wenn erledigt)
- Tech-Entscheidungen mit Pro/Contra-Tabelle dokumentieren
---
## Redesign bestehender Website (Live-Prototyp-Workflow, 2026-08-04)
Wenn ein User eine bestehende Live-Site „langweilig" findet und ein neues Look & Feel will:
1. **Aktuelle Site zuerst ansehen** (curl auf die URL, vhost ansehen) — verstehen, was JETZT da ist, bevor man irgendwas ändert.
2. **3–4 klar unterschiedliche Design-Richtungen im Chat anbieten** (je ein Name + kurzes Look-&-Feel + Wirkung), z.B.:
- Glassmorphism/Frost (Milk-Glass, Blur, sanfte Farbverläufe)
- Arcade/Retro-Pixel (CRT, Pixel-Font, LCD-Score)
- Minimal/Swiss (riesige Typografie, 2 Farben)
- Upgrade des aktuellen Stils (gleiche Richtung, aber Lebendigkeit)
Nutzer wählt **eine** — nicht alle gleichzeitig umsetzen.
3. **Vor dem Übernehmen des Originals sichern:**
```bash
cp /var/www/<site>/html/index.html /var/www/<site>/html/index-original.html.bak
```
⚠️ **Pitfall (Grundregel „nicht destruktiv"):** NIE ohne Backup über die laufende `index.html` schreiben. Backup zuerst, Prototyp danach.
4. **Spiel-/App-Logik unangetastet lassen, nur CSS + Farben tauschen.** Welche Richtung auch gewählt wird — das JS (Engine, KI, Score) 1:1 übernehmen, damit der Prototyp voll funktioniert.
5. **Live deployen auf `/var/www`, danach echt verifizieren:** `curl` (HTTP 200) + **Browser öffnen und klicken** (ein Feld → KI antwortet) statt nur auf Curl zu vertrauen. Nach write_file `chown www-data:www-data` + `chmod 644` nicht vergessen (sonst 403).
6. Wenn dabei ein SSL-Zert-Mismatch auffällt → siehe `web-hosting-deployment`-Skill (ERR_CERT_COMMON_NAME_INVALID / eigenes Subdomain-Zert).
---
## Häufige User-Präferenzen
| Präferenz | Umsetzung |
|-----------|-----------|
| Alles auf Deutsch | Prompt, UI, Doku — nie Englisch |
| Keine Rohdaten im Chat | Terminal-Outputs verarbeiten, nicht roh zeigen |
| PDF nur als Bonus | Erst Chat-Inhalt, dann Datei |
| Keine „Premium"-Features | 100% kostenlos erwähnen |
| Dark-Theme für Landingpages | #0a0a14 Hintergrund, grüne Akzente |
---
## Verzeichnisse auf dem VPS
```
/var/www/<domain>/html/ — Landingpage
/root/<projekt>-konzept.md — Konzept-Dokument
/etc/nginx/sites-available/<domain> — nginx VHost
```
skills/devops/sdlc-review/SKILL.md
+181
View File
@@ -0,0 +1,181 @@
---
name: sdlc-review
description: Review Kanban handoffs and route verified outcomes.
version: 1.1.0
author: Jakub Wolniewicz (@frizikk) + Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
hermes:
tags: [kanban, review, quality, verification]
category: devops
requires_toolsets: [kanban]
environments:
- kanban
---
# SDLC Review Skill
Independently verify work handed from a Kanban implementation run to the review lane, then approve it, request changes, or escalate. This skill reviews the deliverable and its evidence; it does not take over the implementer's work.
## When to Use
Use this skill when all of the following are true:
- the dispatcher spawned you for a task claimed from the `review` lane;
- an implementer submitted a `review_requested` handoff;
- the task needs an independent verdict before it can be completed.
Do not use it for a separate downstream review card. A downstream card is ordinary implementation work with a review-oriented specification and completes through its own lifecycle.
## Prerequisites
- A Kanban worker context with the current task and run identifiers.
- Native Kanban tools: `kanban_show`, `kanban_comment`, `kanban_complete`, `kanban_request_changes`, and `kanban_block`.
- Workspace access through `read_file`, `search_files`, and `terminal` when the deliverable is code.
- The task's original specification, acceptance criteria, handoff summary, and prior run history must be available through `kanban_show`.
## How to Run
This skill is loaded automatically by the review dispatcher. Start with `kanban_show` before inspecting files or choosing a verdict.
1. Read the task specification and the latest `review_requested` handoff.
2. Inspect the actual deliverable and run relevant verification.
3. Choose exactly one verdict: approve, request changes, or escalate.
4. Record concrete evidence in the terminal Kanban transition.
## Quick Reference
| Verdict | When | Final action |
|---|---|---|
| Approve | Acceptance criteria and verification pass | `kanban_complete` |
| Request changes | Correctable implementation defects remain | `kanban_comment`, then `kanban_request_changes` |
| Escalate | A human decision or external prerequisite is required | `kanban_block` |
A requested-changes transition returns the task to its original implementer. When that implementer requests review again without naming a reviewer, the persisted reviewer provenance routes the re-review back to the same reviewer profile.
## Review Lenses
Vary how you look at the work on each round instead of repeating the same inspection. Decorrelated lenses catch different defect classes: a cold read of the artifact surfaces design and correctness problems that the implementer's narrative would have framed away, execution surfaces claims that do not reproduce, and a strict contract audit surfaces quiet scope drift. Repeating the round-1 lens on round 3 mostly re-finds what round 1 already found.
Determine the current round from the history the task record already gives you: count the `changes_requested` entries in the "Prior attempts on this task" section of your worker context (also visible as prior runs in `kanban_show`). The current review round is that count plus one. Round 1 therefore shows zero `changes_requested` attempts; round 2 shows one; and so on.
| Round | Lens | How to apply it |
|---|---|---|
| 1 | Artifact | Read the diff or deliverable cold, before the implementer's summary. Form an independent judgment, then compare it against the handoff narrative and investigate every mismatch. |
| 2 | Execution | Check out the work and actually run it via `terminal`: build, test, and exercise the reported behavior yourself. Verify each handoff claim empirically instead of re-reading the artifact. |
| 3+ | Contract | Re-read the ORIGINAL task body and acceptance criteria, then audit the deliverable strictly against them. Also verify that every item from every prior `kanban_request_changes` round actually landed. |
The baseline duties in the Procedure section still apply on every round; the lens sets which inspection you lead with and weight most heavily.
### Lens variation for ad-hoc review fan-outs
The same principle applies outside the Kanban review lane. When spawning multiple parallel reviewers via `delegate_task`, give each reviewer a different lens — one diff-only brief, one full-context brief, one checkout-and-run brief — rather than identical briefs. Identical briefs produce correlated verdicts and duplicate findings; varied briefs cover more defect classes for the same review spend.
## Procedure
### 1. Orient from the durable task record
Call `kanban_show` and identify:
- the original task body and acceptance criteria;
- the latest implementation summary and structured metadata;
- changed files, commit identifiers, and test evidence;
- comments and decisions from earlier runs;
- findings from prior review rounds.
Treat the handoff as a claim to verify, not as proof that the work is correct.
### 2. Compare requested behavior with delivered behavior
Map every acceptance criterion to concrete implementation or output evidence. Note omissions, changed semantics, and unrelated scope before deciding whether to run deeper checks.
For code work:
1. Use `read_file` and `search_files` to inspect the changed paths and their callers.
2. Use `terminal` to inspect the diff and run the project's existing focused tests, lint, type checks, or build commands.
3. Exercise the reported failure path and at least one ordinary control path when practical.
4. Check error handling, edge cases, concurrency boundaries, data preservation, security boundaries, and cross-platform behavior relevant to the change.
5. Confirm that tests assert behavior rather than merely snapshotting source text or constants.
For non-code work:
1. Inspect the complete deliverable rather than only its summary.
2. Check correctness, completeness, formatting, and provenance.
3. Validate referenced URLs or external facts with the appropriate native tools when they affect the verdict.
### 3. Choose one verdict
#### Approve
Approve only when the acceptance criteria are satisfied and the evidence is sufficient. Call:
```text
kanban_complete(
summary="Reviewed and approved. <what was verified>",
metadata={"review_outcome": "approved", "reviewer_checks": [...]}
)
```
Include the exact checks that passed and any bounded caveat that does not block acceptance.
#### Request changes
Use this for specific, correctable defects. First record actionable findings:
```text
kanban_comment(
task_id="<current-task-id>",
body="Changes requested:\n1. <file or artifact + defect>\n2. <required correction>",
)
```
Then return the same task to its implementer:
```text
kanban_request_changes(
reason="<concise summary of the required corrections>"
)
```
State where the defect is, how it reproduces, why it violates the task, and what minimum outcome would resolve it. The transition does not use blocker recurrence accounting.
#### Escalate
Use escalation only when the reviewer and implementer cannot resolve the problem without a human decision or external prerequisite:
```text
kanban_block(
reason="escalation: <decision or prerequisite required>"
)
```
Explain the blocked decision and the smallest information needed to continue.
### 4. Preserve role separation
Do not edit the implementation while acting as reviewer. Request changes and let the implementer produce the next candidate; then independently verify that candidate in the next review run.
## Pitfalls
- **Rubber-stamping:** A passing handoff summary is not independent evidence.
- **Reviewer implementation:** Editing the deliverable hides ownership and weakens the re-review boundary.
- **Vague findings:** “Needs work” does not give the implementer a reproducible correction target.
- **Style-only blocking:** Do not request changes for preference-level nits when behavior and repository standards are satisfied.
- **Skipping prior rounds:** Re-review must confirm both the requested corrections and preservation of previously passing behavior.
- **Using blockers for ordinary rework:** Correctable defects belong in `kanban_request_changes`; reserve `kanban_block` for genuine external blockers or human decisions.
- **Completing without evidence:** Every approval summary must name the checks or artifacts actually inspected.
## Verification
Before submitting the verdict, confirm:
- [ ] `kanban_show` was read for the current task and run.
- [ ] Every acceptance criterion was mapped to evidence.
- [ ] The actual deliverable was inspected.
- [ ] Relevant focused checks were run or an explicit reason was recorded when execution was impossible.
- [ ] Prior requested changes were re-tested on re-review.
- [ ] Unrelated regressions and scope changes were considered.
- [ ] The verdict uses exactly one terminal action.
- [ ] The summary contains concrete, non-secret evidence.
- [ ] No implementation files were edited by the reviewer.
skills/devops/security-audit-hardening/SKILL.md
+151
View File
@@ -0,0 +1,151 @@
---
name: security-audit-hardening
description: "Linux-Server-Sicherheitsaudit mit automatischer Härtung – SSH, fail2ban, UFW, Angriffserkennung"
version: 1.0.0
author: Agent A (netcup VPS Deployer)
platforms: [linux]
---
# Security Audit & Hardening
Schnelles Sicherheitsaudit für Linux-VPS mit Sofortmaßnahmen gegen Bruteforce-Angriffe.
## Audit-Befehl (alles auf einmal)
```bash
echo "=== OFFENE PORTS ===" && ss -tlnp | awk '{print $4,$NF}' | sort -u
echo "=== UFW ===" && ufw status verbose
echo "=== SSH ===" && grep -E "^PermitRootLogin|^PasswordAuthentication|^PubkeyAuthentication|^Port" /etc/ssh/sshd_config
echo "=== FAIL2BAN ===" && systemctl status fail2ban 2>/dev/null | head -3
echo "=== SSH-ANGRIFFE ===" && grep -c "Failed password" /var/log/auth.log 2>/dev/null
echo "=== AKTIVE ANGREIFER ===" && grep "Failed password" /var/log/auth.log 2>/dev/null | tail -5 | awk '{print $NF}' | sort -u
```
## Sofortmaßnahmen (in dieser Reihenfolge)
### 1. Aktuelle Angreifer blockieren
```bash
# IPs aus Auth-Log extrahieren
ufw deny from <IP>
```
### 2. fail2ban installieren
```bash
apt-get install -y fail2ban
systemctl enable fail2ban
systemctl start fail2ban
```
### 3. fail2ban aggressiv konfigurieren
```bash
cat > /etc/fail2ban/jail.local << 'EOF'
[DEFAULT]
bantime = 3600
findtime = 600
maxretry = 3
[sshd]
enabled = true
port = ssh
maxretry = 3
bantime = 7200
EOF
systemctl restart fail2ban
```
### 4. SSH härten
```bash
cat >> /etc/ssh/sshd_config << 'EOF'
MaxAuthTries 3
MaxSessions 2
LoginGraceTime 30
ClientAliveInterval 300
ClientAliveCountMax 2
EOF
sshd -t && systemctl reload sshd
```
> ⚠️ **Pitfall: Nicht aussperren!** Vor `PasswordAuthentication no` prüfen ob SSH-Keys existieren: `cat /root/.ssh/authorized_keys`. Wenn keine Keys → Passwort-Auth lassen, aber mit fail2ban + MaxAuthTries absichern.
> 🔥 **Pitfall: fail2ban bannt eigene Mesh-/Agent-IPs!** SSH/scp-Polling von Sub-Agenten aus (regelmäßige Key-Auth-Verbindungen zum Master) wird von fail2ban als „fehlgeschlagene Login-Versuche" gezählt und gebannt — besonders wenn eine once mal nicht matchen will. **Symptom:** „Connection refused" auf Port 22 NUR für genau eine IP, während Ping geht und andere Agenten noch funktionieren. **Fix — eigene/vertraute IPs dauerhaft whitelisten** in `/etc/fail2ban/jail.local`:
```ini
[sshd]
ignoreip = 172.24.34.142 172.24.20.26 172.24.178.202 172.24.92.162
```
Dann `fail2ban-client reload` + `fail2ban-client set sshd unbanip <IP>`. WICHTIG: nur EINE `[sshd]`-Sektion pflegen (eine doppelte, appendierte Sektion gilt separat — konsolidieren).
### 5. Webhook-/Mesh-Schnittstellen auf bekannte ZeroTier-Geräte isolieren
**Prinzip (NUTZERWUNSCH 2026-08-03):** Kein Subnetz-/16-Catch-all. Mesh-Ports nur für
explizit bekannte ZeroTier-IPs freigeben, damit ein unbekanntes Gerät im Netz keine Dienste
einschleusen kann. Inkl. Handy (Gerät, kein Agent).
```bash
# Bekannte ZT-Geräte einzeln freigeben (Ports: Webhook 8644, NFS 2049/111/20048, Ollama 11434)
for ip in 172.24.34.142 172.24.20.26 172.24.178.202 172.24.92.162; do
ufw allow from $ip to any port 8644 proto tcp comment 'Webhook Mesh'
ufw allow from $ip to any port 2049 proto tcp comment 'NFS Mesh'
ufw allow from $ip to any port 111 proto tcp comment 'rpcbind'
ufw allow from $ip to any port 111 proto udp comment 'rpcbind U'
ufw allow from $ip to any port 20048 proto tcp comment 'nfs lockd'
ufw allow from $ip to any port 11434 proto tcp comment 'Ollama Mesh'
done
```
**Zuerst alte /16-Regeln löschen:** `ufw delete <nr>` fragt interaktiv → mit `yes |` erzwingen.
**Verifikation:** `ufw status | grep '172.24.0.0/16'` darf NICHTS zeigen; `grep -oP '172\\.24\\.\\d+\\.\\d+' | sort -u` darf nur die bekannten IPs listen.
> 🔒 **NFS deaktivieren — SSH/scp für Agent-Tasks ist sicherer (2026-08-03).**
> NFS (`sec=sys`) transferiert plaintext über TCP → Man-in-the-Middle-anfällig, und braucht
> Kernelmodule/FUSE, die auf Tegra-Hosts (Nintendo-Switch: Kernel `4.9.140-l4t` → kein `nfs`/
> kein `fuse`) fehlen. Entscheidung: **alle Sub-Agenten nutzen SSH/scp mit Key-Auth**
> (Ende-zu-Ende verschlüsselt), NFS-Server deaktiviert und NFS-Ports (2049/111/20048) aus UFW
> entfernt. Das schließt die NFS-Angriffsfläche komplett. Details zum SSH/scp-Polling:
> siehe Skill `multi-agent-mesh` (Kontext: Task-Polling über SSH/scp).
> ⚠️ **Pitfall:** Nach VPN/Netz-Wechsel (WireGuard→ZeroTier) hängen UFW-Regeln oft noch an alten
> Subnetzen (z.B. `10.8.0.0/24`). Immer prüfen, welches Netzwerk jetzt real aktiv ist.
### 6. Automatische Sicherheitsupdates
```bash
apt-get install -y unattended-upgrades
dpkg-reconfigure -f noninteractive unattended-upgrades
```
## Audit-Ergebnis bewerten
| Signal | Risiko |
|--------|--------|
| SSH `PasswordAuthentication yes` | 🔴 Bruteforce möglich |
| SSH `PermitRootLogin yes` | 🔴 Root direkt angreifbar |
| Kein fail2ban | 🔴 Keine Ratenbegrenzung |
| Webhook-Port öffentlich | 🟡 API für jeden erreichbar |
| >100 Failed Passwords | 🔴 Aktiver Angriff |
| UFW default deny | 🟢 korrekt |
## Verhalten bei aktivem Angriff
1. **Nicht in Panik verfallen** — SSH mit Passwort + fail2ban hält 99% der Angriffe ab
2. Angreifer-IPs per `ufw deny` dauerhaft sperren
3. fail2ban-Status prüfen: `fail2ban-client status sshd`
4. Auth-Log monitoren: `tail -f /var/log/auth.log | grep Failed`
## JIT SSH-Portal (nächste Stufe: SSH schließen, 2FA-Freischaltung)
Wenn der Server-SSH nicht dauerhaft offen sein soll: baue ein **Just-In-Time-Portal** — Flask + Telegram-2FA +
temporäre UFW-Freischaltung (1h Auto-Close). Details + Reset-Rezept: `references/jit-ssh-2fa-portal.md`.
**Kern-Pitfall:** Ein End-to-End-Test des Portals überschreibt das echte Passwort (PW-Wechsel-Pflicht) —
nach dem Test IMMER zurücksetzen, nie Test-Artefakte im laufenden System hinterlassen.
## Niemals tun
- ❌ SSH-Port ändern (security by obscurity, bringt nichts)
- ❌ `PermitRootLogin no` ohne funktionierenden SSH-Key
- ❌ `PasswordAuthentication no` ohne SSH-Key für ALLE User
- ❌ UFW deaktivieren "weil's nicht funktioniert"
skills/devops/security-audit-hardening/references/jit-ssh-2fa-portal.md
+68
View File
@@ -0,0 +1,68 @@
# JIT SSH-Portal mit Telegram-2FA (Just-In-Time Firewall-Freischaltung)
> Muster (2026-08-03, `https://ssh.perfekt-ohne-en.de`): SSH-Port 22 bleibt standardmäßig für die Welt
> GESCHLOSSEN und wird nur nach doppelter Authentifizierung (Passwort + Telegram-2FA) für die
> angefragte IP temporär geöffnet (1h) → Auto-Close. Besser als permanent offenes SSH.
## Architektur
```
ssh.perfekt-ohne-en.de (nginx+SSL) → proxy_pass → 127.0.0.1:8091 (Flask)
├─ SQLite (users, sessions)
├─ Telegram-2FA (6-stelliger Code an Nutzer-Chat)
└─ UFW: öffnet Port 22 für angefragte IP (1h)
```
**Ablauf (end-to-end):**
1. Login `mehlzoerwer` + **Erstpasswort** `St230918kM@vps` → gilt NUR 1×, dann **PW-Wechsel-Pflicht**
2. 2. Login mit neuem Passwort → liest `pw_changed`-Flag → leitet zur **2FA**-Seite
3. Backend sendet **6-stelligen Code per Telegram** an Nutzer-Chat (out-of-band, Kanal getrennt vom Web)
4. Nach korrektem Code: `ufw allow from <ANFRAGE-IP> to any port 22 proto tcp` (Kommentar "SSH JIT Portal")
5. **Auto-Close:** Hintergrund-Thread prüft alle 60s Sessions mit `expiry <= now` → `ufw delete`, Status `closed`
## Dateien & Infrastruktur
- App: `/opt/sshportal/app.py` (Flask, Telegram-Token aus `/root/.hermes/.env`, einheitlich via `re.search(key+r"\s*=\s*(\S+)")`)
- venv: `/opt/sshportal/venv` (flask, requests; Passwort-Hash via `werkzeug.security.generate_password_hash/check_password_hash` — kein eigener bcrypt-Aufruf nötig)
- systemd: `/etc/systemd/system/sshportal.service` → `active` auf `127.0.0.1:8091` (nur localhost; nginx davor)
- DB: `/opt/sshportal/portal.db`, Log: `/opt/sshportal/portal.log`
- nginx vhost + Let's-Encrypt via Certbot (Standard `certbot --nginx -d ... --redirect`)
## Sicherheits-Parameter (der Wert des Musters)
- **Erstpasswort-Einmalnutzung:** `pw_changed=0` → Login erzwingt PW-Wechsel.
- **2FA out-of-band:** Telegram = getrennter Kanal vom Web-Portal.
- **Code-TTL 120s**, max 3 Fehlversuche → Login gesperrt + Telegram-Alarm.
- **Firewall-Freischaltung zeitlich begrenzt:** 1h, danach automatische UFW-Löschung.
- **Nur die angefragte IP** wird geöffnet (keine Subnetze).
- Flask-Inhalte: `render_template_string(..., content=Markup(...))` damit HTML-Strings als Form nicht escaped werden.
## ⚠️ KRITISCHER PITFALL: Test verändert den laufenden Zustand
End-to-End-Test (Login mit Erstpasswort → PW-Wechsel auf Test-Passwort) **überschreibt das echte Passwort**.
Der Nutzer kann danach nicht mehr mit dem Erstpasswort einloggen → fälschliche "falsches Passwort"-Meldung.
**Regel (Betriebsregel #1):** Tests/Änderungen an laufenden Systemen MÜSSEN beendet oder zurückgesetzt
werden — nie Test-Artefakte hinterlassen. Sonst Rückfrage statt Test.
**Reset nach Test:**
```bash
systemctl stop sshportal.service
/opt/sshportal/venv/bin/python -c "
import sqlite3; from werkzeug.security import generate_password_hash
c=sqlite3.connect('/opt/sshportal/portal.db')
c.execute('UPDATE users SET pw_hash=?, pw_changed=0 WHERE username=?', (generate_password_hash('St230918kM@vps'),'mehlzoerwer'))
c.commit(); c.close()"
systemctl start sshportal.service
```
## Verifikation (im Bau bestätigt)
| Test | Status |
|------|--------|
| Login Erstpasswort → Redirect change-pw | ✅ 302 |
| PW-Wechsel → "Passwort geändert" (Log) | ✅ |
| Login neues PW → Redirect 2fa | ✅ 302 |
| 2FA-Code → Telegram-Chat | ✅ Log "2FA-Code gesendet" |
| UFW allow für IP | ✅ "Rule added" |
| Auto-Close (ufw delete nach 1h) | ✅ "Rule deleted" |
skills/devops/wearable-health-mcp/SKILL.md
+97
View File
@@ -0,0 +1,97 @@
---
name: wearable-health-mcp
description: "Use when: Wearables-Daten (COROS) ueber MCP-CLI integrieren."
version: 1.0.0
author: mehlzoerwer
platforms: [linux]
models:
default: mimo-v2-flash
license: MIT
related_skills: [pocketbase-deployment, content-creator]
---
# Wearable-Health-MCP (COROS u.a.)
## When to Use
Nutze diesen Skill, wenn Wearable-/Gesundheitsdaten (z.B. **COROS-Sportuhr**) über einen **MCP-Gateway-CLI** abgefragt und in eine App/Backend (z.B. PersoEnt) integriert werden sollen — um korrekte CLI-Flag-Syntax, Browser-Login und Token-Sicherheit zu kennen, ohne sie neu zu erkunden.
> **Use when:** Gesundheits-/Trainingsdaten eines Wearables (Sportuhr) über einen MCP-Gateway-CLI abziehen und in eine App/Backend integrieren. Derzeit konkret: **COROS → PersoEnt** über das offizielle `coros-mcp`-Paket.
## Was es ist
`coros-mcp` (npm, **offiziell von COROS**: maintainer `coros_openplatform`) ist eine TypeScript-CLI zum MCP-Gateway `https://mcp.coros.com` (Europa: `https://mcpeu.coros.com`). Login + MCP-Tool-Aufrufe. **Kein zusätzlicher Cloud-Fremdkostenpflicht-Call nötig innerhalb des Rahmenbudgets — der Hersteller stellt es gratis.**
## Installation
```bash
npm install -g coros-mcp # installiert bin /usr/local/bin/coros-mcp
```
## Login (Browser-Auth, 1x)
```bash
coros-mcp login-start # gibt Link: https://mcpeu.coros.com/cli/login/<token>
# Nutzer öffnet Link im Browser, loggt sich ins COROS-Konto ein
coros-mcp login-finish # → "login ok", Token gecacht
coros-mcp login-status # "no pending login session" wenn fertig
coros-mcp logout # Cache leeren
```
Der Login ist ein OAuth-ähnlicher browser flow; nur das echte COROS-Konto kann ihn abschließen (Client-ID/Secret werden NICHT manuell konfiguriert).
## 🔥 CLI-Flag-Syntax (VERIFIZIERT 2026-08-15 — häufigste Fehlerquelle)
**Beachte exakt diese Flags — ANDERE Varianten scheitern mit `unknown argument`:**
```bash
# Tools auflisten (JSON-Array mit name/description/inputSchema)
coros-mcp list-tools
# Ein Tool-Schema anzeigen:
coros-mcp describe-tool --tool <NAME>
# Tool AUFRUFEN — Argumente als --arguments-json (WICHTIG: nicht --args!) :
coros-mcp call-tool --tool <NAME> --arguments-json '<json>'
```
**Getestete Fehlversuche (real aufgetreten):** `--args`, `--name`, `--tool`-ohne-`--arguments-json`, reine Positionsargumente → alle `error: unknown argument`. Das `--help` auf Unterbefehle zeigt nur die HAUPT-Hilfe (nicht die Flag-Struktur). **Verlässliche Quelle bei Unklarheit: Packagedatei lesen** `grep -n "call-tool|--tool|--arguments-json" $(npm root -g)/coros-mcp/dist/*.js` — dort steht die echte Sub-Kommando-Logik.
## Verifizierte Tools (22, Stand 2026-08-15)
| Gruppe | Tools (Beispiele) |
|--------|-------------------|
| Schlaf | `querySleepData` (Score/Dauer/Phasen), `querySleepHrv` (avg+Range+Baseline) |
| Herz | `queryAvgHeartRate`, `queryRestingHeartRate` |
| Stress | `queryStressLevel`, `queryStressTimeSeries` |
| Gesundheit | `queryDailyHealthData` (Schritte/Kalorien/Exercise), `queryHealthCheckTimeSeries` (Roh-HR+HRV+Stress+Atmung) |
| Sport | `querySportRecords`, `getActivityDetail`, `queryActivityLapData`, `queryCustomActivityLapData`, `analyzeActivityDetail` (Coach-Style), `downloadActivityFitFiles`, `queryActivityFitFileDownloadUrls` |
| Fitness | `queryFitnessAssessmentOverview` (VO2max/Threshold-Pace), `queryTrainingLoadAssessment`, `queryRecoveryStatus` (%), `queryTrainingSchedule` |
| Profil/Geräte | `queryUserInfo` (Größe/Gewicht/Geburt/Geschlecht), `queryDevices`, `queryMenstruationCycles` |
**Detektiv-Priorität für Kausal-Analyse (Team-Review 2026-08-15):** P0=HRV + Schlaf, P1=Stress + Erholung, P2=Ruhe-HR + VO2max, P3=Sport/FIT.
## 🔒 Token-Sicherheit (Team-Auflage 2026-08-15)
- Token liegt in `<cache-root>/<region>/token.json` (d.h. `/root/.coros-mcp-skill-gateway-ts/eu/token.json`) — **im Klartext**.
- Die CLI LIEST es selbst aus diesem Cache → **nicht verschlüsseln an Ort**, sonst bricht die CLI. Stattdessen:
- `chmod 600` token.json UND `chmod 700` Cache-Verzeichnisse (root-only)
- **Verschlüsselte Sicherungskopie** anlegen: `age` installieren, `age-keygen -o /root/.coros-age-key.txt`, dann
`age -r <PUBKEY> -o /root/.coros-token.json.age <token.json>` → Datei beginnt mit `age-encryption.org/v1`.
- **Niemals Token in Logs/env** — nur zur Laufzeit vom Cache einlesen.
- Single-User-PersoEnt = kleine Angriffsfläche (kein Multi-User-Token-Management nötig).
## Architektur-Empfehlung (Team-Review 2026-08-15)
Für Uhren-Health (= tagesbasiert, nicht Echtzeit) **Cron-Poller 1×/Tag (03:00)** → Daten in PocketBase/Backend schreiben; **Live-UI liest NUR aus Backend**, nie Live-COROS (Entkopplung + Rate-Limit + Offline-Fähigkeit). Upsert pro (Datum, Datentyp).
⚠️ **Noch NICHT umgesetzt (Stand 2026-08-15):** der eigentliche Poller-Skript (COROS→PocketBase Write) war zum Sitzungsende noch nie fertig — die PocketBase-Auth-Token-Abfrage blockierte auf Nutzer-Freigabe. Vorgehen siehe nächster Abschnitt.
## Nächster Schritt (noch offen)
1. PersoEnt PocketBase-Login (Auth-Token holen) — **erfordert Nutzer-Freigabe** (sensible Login-Lösung)
2. Collection `health_records`-Schema prüfen (Felder: weight, blood_pressure, pulse, user_id lt. pocketbase-deployment)
3. Poller-Skript: `coros-mcp call-tool --tool querySleepHrv --arguments-json '{}'` je Tag → upsert in PocketBase
4. PersoEnt-Dashboard/Detektiv liest daraus
## Referenzen
- `references/coros-tools-inventory.md` — vollständige 22-Tool-Beschreibungen (Detaildichte)
skills/devops/wearable-health-mcp/references/coros-tools-inventory.md
+49
View File
@@ -0,0 +1,49 @@
# COROS-MCP Tool-Inventory (Stand 2026-08-15, real verifiziert)
Quelle: `coros-mcp list-tools` nach erfolgreichem Login. 22 MCP-Tools am COROS-Gateway. Alle Aufrufe mit korrekter Flag-Syntax:
`coros-mcp call-tool --tool <NAME> --arguments-json '<json>'`.
## Schlaf
- `querySleepData` — Sleep-Score, Hauptdauer, Stufen (Tief/Leicht/REM), Awake. Legacy-Daily-API.
- `querySleepHrv` — offizielles tägliches Schlaf-HRV-Assessment (avg, normal range, baseline). Datum = Wachtag (Nacht davor).
## Herz
- `queryAvgHeartRate` — tägliche durchschnittliche HK.
- `queryRestingHeartRate` — tägliche Ruhe-HK.
## Stress
- `queryStressLevel` — täglicher avg-Stresswert.
- `queryStressTimeSeries` — rohe Stress-Punkte (timestamp, tz).
## Gesundheit / Daily
- `queryDailyHealthData` — Breite Tages-Übersicht: Schritte, Kalorien, Exercise-Minuten, Stress, Sleep-Detail. Beispiel real: Routinesfeld ergab Schritte 627–9304, Stress avg, Sleep-HR detail.
- `queryHealthCheckTimeSeries` — Roh-Wellness-Check: Herzrate, HRV, Stress, Atemfrequenz.
## Sport / Aktivität
- `querySportRecords` — Workout-Protokoll (Datum, Location, Duration, avg HR, Calories, LabelId, SportType). sportType-Codes: 100=running, 201=indoor cycling, 1200=hybrid fitness.
- `getActivityDetail` — detaillierte Infos eines Trainings inkl. Herzfrequenz.
- `analyzeActivityDetail` — Coach-Style-Zusammenfassung (holt Detail + analysiert).
- `queryActivityLapData` — Lap-/Segment-Daten für labelId+sportType.
- `queryCustomActivityLapData` — Custom-Fenster (z.B. letzte N Minuten, Endsegment) mit timestamp-Grenzen.
- `downloadActivityFitFiles` — FIT-Datei(en) als Binary-Resource.
- `queryActivityFitFileDownloadUrls` — Fallback: FIT-Download-URLs als Text.
## Fitness / Assessment
- `queryFitnessAssessmentOverview` — VO2max, Lauf-Level, Threshold-Pace, Race-Prediction.
- `queryTrainingLoadAssessment` — Kommentar, Kurz-/Langzeit-Trainingsload.
- `queryRecoveryStatus` — Recovery-% + Level-Verschreiben.
- `queryTrainingSchedule` — aktuelle Woche Trainingsplan (bzw. angegeben).
## Profil / Geräte
- `queryUserInfo` — Größe, Gewicht, Geburtstag, Gender.
- `queryDevices` — gebundene COROS-Geräte (device id, firmware type).
- `queryMenstruationCycles` — Zyklusdaten (heute, nächste Periode, täglich).
## Beispiel-Rückgabewerte (real 2026-08-15, Nutzer Thorsten)
- `queryUserInfo`: Height 173cm, Weight 100.6kg, Birthday 1972-02-21, Male.
- `queryRecoveryStatus`: 100 %, Level "Heavy training allowed".
- `querySleepHrv`: HRV Ausdrücke je Tag (z.B. 55ms Normal, Baseline 61ms to 67ms).
- `querySportRecords` (1 Woche): Indoor Cycling 1:00:14, avg HR 114, Location "Indoor Rad".
## Hinweis
Tool-Schemas: `coros-mcp describe-tool --tool <NAME>` zeigt inputSchema (Felder + erforderlichen). Viele Health-Daily-Tools brauchen `{}`-em Arguments (Default oder Sarted). Activity-Tools brauchen `labelId`+`sportType`.
skills/devops/web-feature-iteration/SKILL.md
+114
View File
@@ -0,0 +1,114 @@
---
name: web-feature-iteration
description: "Web-Features bauen, Revert bei Ablehnung."
version: 1.0.0
author: Agent A (Deployer)
platforms: [linux]
---
# Web-Feature-Iteration (inkrementell für diesen Nutzer)
Governs how to extend or feature-up an existing interactive web page/app for this
user. Learnt the hard way 2026-08-04 on TicTacToe (3D-Relaunch 3× rejected, full revert).
## Trigger
- "Neue Funktion einbauen" / "Erweiterung" / "Mach mal 3D / Animation / X dazu"
- Erweitern einer **laufenden, bereits spielbaren/nutzbaren** Seite
---
## Kerngesetz: lieber klein + funktionierend als schick + kaputt
Aus der TicTacToe-Session (Nutzer lehnte 3-Mal ab):
1. **Minimaler Eingriff zuerst.** Wenn eine Seite funktioniert (z. B. spielbares
TicTacToe mit Minimax), baue eine kleine, isolierte Erweiterung — nicht einen
glänzenden Redesign (3D-Canvas, neue Engine). Der Nutzer bevorzugt funktionierend vor flashy.
2. **Kritik ist wertvoll — Match auf Nutzer-Mehrwert.** Gegen einen perfekten
Minimax-Gegner ist "Wer beginnt (X/O)" (≈5 Zeilen, 0 Risiko) mehr wert als
Schwierigkeitsstufen, die die perfekte Engine anfassen. Frag: "Was ist die kleinste
Änderung mit dem größten echten Nutzen?"
3. **Sauberer Revert erwartet.** Wenn der Nutzer "Komplett zurück" / "Geht gar nicht"
sagt: sofort den letzten bekannten funktionierenden Stand wiederherstellen (Backup
`index-original.html.bak`), tote Assets (geladene lib/) entfernen, über HTTPS verifizieren.
Erwartung: Was nichts bringt, wird zurückgenommen, nicht "repariert bis es gefällt".
## Effektiver 3D/Visual-Anstupser (aus TicTacToe)
- Hat der Nutzer 3D/Visual-Wunsch, aber die **Interaktion bleibt die Wahrheit**:
Wenn ein 3D-Canvas das präzise Klicken unmöglich macht (perspektivisches Klick-Mapping),
lehnt der Nutzer ab. Behalte die **präzise 2D-/Affordance-Schicht** (echte anklickbare
Zellen statt Canvas-Koordinaten) und rendere die Deko (3D-Steine) DARUNTER/separat.
- Pauschale "Glanz"-Erweiterungen (permanente Board-Rotation) machen Spiele unspielbar — vermeiden.
## Reusable Technik-Pitfalls (Three.js)
- **`BoxGeometry` hat KEINE `.rotation`-Eigenschaft** (nur `Object3D`: Mesh/Group).
`geometry.rotation.z = x` → `TypeError: Cannot set properties of undefined (setting 'z')`.
Fix: `geometry.rotateZ(angle)` (BufferGeometry-Methode) oder die Geometrie in ein Mesh
packen und das Mesh rotation zulassen.
- **Diagnose:** isoliert im Browser `new THREE.X()` testen; den größten Fehler in kleine
Schritte zerlegen (Material vs. Geometrie vs. Group) statt die ganze Funktion zu raten.
### ⚠️ Chart.js/CDN-Abhängigkeit vermeiden — statisches CSS statt JS-Diagramm
Chart.js von CDN (cdn.jsdelivr.net) lädt auf mobilen Browsern oft nicht oder
verzögert. Die `canvas` bleibt dann leer — die Seite sieht aus wie ein
dunkles Nichts. Sub-Agenten können nicht prüfen ob das Chart lädt (kein
Browser-Zugriff).
**Fix: Chart.js durch statische CSS-Balken ersetzen.**
```css
.chart-bar { background: linear-gradient(to top, #4ade80, rgba(74,222,128,0.2)); height: 100%; }
```
- Kein JS, kein CDN, kein Fallback nötig → immer sichtbar
- Keine mobilen Lade-Probleme
- Null zusätzliche Ladezeit
- Sub-Agenten können den Code im Review sehen
**Entscheidungsregel:** Wenn ein Diagramm nur Daten-Status zeigt (keine
Interaktion nötig), ist CSS die bessere Wahl. Nur wenn der Nutzer aktiv
zoomen/filtern/hovern muss, lohnt sich Chart.js/Canvas.
## Verifikation (immer)
1. Erst SELBST im echten Browser testen (Seite laden, 1 Spielzug, KI-Antwort, `js_errors` leer),
nicht nur `curl` Status 200 behaupten.
2. **Kontrast-Check auf der Live-URL:** `curl` allein erkennt keine CSS-Fehler.
Prüfe: Sind alle Texte auf hellen Hintergründen lesbar? `--muted` auf `--surface` kann
wie schwarz auf schwarz wirken (WCAG-AA 4.5:1 erforderlich). Wenn Browser nicht verfügbar:
Hex-Farben gegeneinander halten oder Sub-Agenten den Code visuell prüfen lassen.
3. **Nach Deploy: Team-Review über die LIVE-Seite per Sub-Agent, nicht nur den Code.**
Nutzer-Vorgabe (hart): "Ihr müsst euch wieder gegengecheckt haben." Nach bestandenem
technischen Check (HTTP 200 + nginx-t) einen Review-Task mit **eingebettetem Seiteninhalt**
(HTML + CSS) an einen Sub-Agenten schicken. Sub-Agenten können keine externen URLs laden.
4. **Nach Revert:** gleicher Browser-Test, damit die wiederhergestellte Seite wirklich läuft.
## Team-Gegenprüfung ist PFLICHT — nie solo bauen (Nutzer-Grundsatz, 2026-08-09)
Der Nutzer verlangt es hart (für Alle Ebenen der Arbeit, nicht nur Code): **"Ihr müsst euch wieder gegengecheckt haben; manche Dinge findet man nur im Team."** Mehrfach baute ich ein Backend/Daten-Gerüst allein → der Nutzer fand jedes Mal echte Fehler, die ein Review gefunden hätte. Lektionen:
- **Daten UND Backend review-en lassen, nicht nur Roh-Daten vom Team holen.** Reine "Schätzwerte einholen" ist kein Gegenchenken. Code, Logik, URL-Formate und Generierung gehören dem Team zum Review vorgelegt.
- Sub-Agenten-Review ist wertvoll, aber **nicht immer live-verifiziert**: Ein Sub-Agent bestätigte mir das tote `reiseauskunft.bahn.de`-Format aus "Wissen", ohne es zu testen → shippen gab `DNS_PROBE_FAILED`. **Jede URL-/Endpoint-Empfehlung eines Sub-Agenten vor dem Einbau selbst mit curl/browser prüfen** (DNS + HTTP + ob Parameter wirklich wirken), nicht nur dem Format-Urteil vertrauen.
- Wenn der Nutzer systematisch Fehler findet, stoppe und führe eine Review-Runde durch, statt einzeln weiterzubauen.
## Daten-Generierungs-Pitfalls (mehrstufige Listen/Filter)
Aus der 3-Ebenen-Zugsuche (urlaub.perfekt-ohne-en.de, Flask+SQLite):
- **Sortier-Filter schneidet sichtbare Kategorien ab.** Sortiert man Ziele nach Distanz und nimmt `[:N]`, bleiben NUR die nächsten (z. B. nur "unter 5h") — ferne 5-7h/>7h-Ziele "verschwinden". Fix: **je Kategorie** (unter5h / 5-7h / über7h) separat die repräsentativsten N Ziele nehmen, damit alle Kategorien in jeder Liste vertreten bleiben.
- **Kategorie aus dem berechneten Wert ableiten, nicht aus einer geplanten Bandbreite.** Wenn Label und berechnete Zeit auseinanderlaufen (z. B. Kategorie "5-7h" aber Zeit ~3h), ist das ein Review-findbarer Inkonsistenz-Bug. Einheit: `kategorie = f(berechne_zeit)`.
- **Platzhalter vermeiden.** Pauschale Dummy-Werte (z. B. alle Einwohner=150000) sind Datenfehler — der Nutzer merkt, dass keine echten kleinen Städte drin sind. Entweder echte Werte oder NULL/"k.A.", nie plausible Dummy-Zahl.
- Wenn eine Städte-/Ziel-Datenbank auf viele Einträge skaliert (190+ Städte, 10000+ Verbindungen): **generiere deterministisch** aus einer Referenzliste + Distanz-Logik, statt manuell jede Zuordnung zu erfinden. Mit klarer Kategorie- und Zeit-Ableitung.
## Flask+SQLite für dynamische, user-gepflegte Daten (statt statischer Seiten)
Bei mehrstufiger Navigation (Ebenen, Klick-Weiterleitung mit `/2/<slug>`-URLs) und vielen Datensätzen: **Backend + SQLite** schlägt statische Generierung.
- Eine Datenänderung = eine DB-UPDATE, alle abhängigen Seiten/PDFs aktualisieren sich — statisch wäre ein Full-Rebuild von tausenden Dateien.
- Isolate Semantik: URL-Route `/2/<slug>` zuverlässig machen (Bindestriche↔Umlaute: `osnabrueck`, auch `koln`-Formen, mit mehrstufiger Kandidaten-Rücktranskription).
- PDF on-demand (wkhtmltopdf) statt vorab für jede Kombination.
- Deploy: systemd-Service + nginx reverse_proxy auf `127.0.0.1:<port>` (Muster wie das sshportal-Backend); statische/Server-Reload-Cache: **nach Template-/Code-Änderung Restart**, sonst rendert die laufende App veraltete Templates (äußerte sich als "Kategorie fehlt trotz Fix").
## Support-Dateien
- `references/tic-tac-toe-revert-2026-08-04.md` — Revert-Chronologie + 3D-Gotcha-Detail.
- `references/urlaub-3-ebenen-zugsuche-2026-08-09.md` — Mehrstufige Zugsuche: DB-Deep-Link-Deadends, 25k/10k-Schwellen-Umbau, Kategorien-Generator-Prinzip.
skills/devops/web-feature-iteration/references/tic-tac-toe-revert-2026-08-04.md
+49
View File
@@ -0,0 +1,49 @@
# TicTacToe 3D-Relaunch → kompletter Revert (2026-08-04)
Chronologie einer über-engineert-Erweiterung, die der Nutzer 3× ablehnte, und
der saubere Revert — als Muster, warum "minimal + funktionierend" gilt.
## Ablauf
1. **Ausgangslage:** tictactoe.perfekt-ohne-en.de, statisches HTML/JS, Player (X) gegen
KI (O), Minimax (unschlagbar), Flip-Coin-Animation, helles Glas-Design. Funktioniert.
2. **Mesh-Brainstorming (Rechen-Agenten):** UnraidHermes empfahl Schwierigkeitsstufen,
SwitchHermes (KRITIK) empfahl stattdessen "Wer beginnt (X/O)" — kleinster Eingriff mit
größtem Nutzen, weil gegen perfekte KI nur der Startende Remis erzwingen kann.
→ Entscheidung: X/O-Wahl als Punkt 3.
3. **Umsetzung zu grob:** Statt nur X/O-Wahl wurde ein kompletter 3D-Relaunch gebaut
(Three.js, 3D-X aus gekreuzten Balken, 3D-O als Torus, rotierendes 3D-Board).
4. **Ablehnung Runde 1:** Nutzer: "Sieht schön aus aber ist wegen der Drehung unspielbar."
→ Nur Rotation entfernt.
5. **Ablehnung Runde 2:** Nutzer: "Ich klicke blind und verliere" (perspektivisches
Canvas-Klick-Mapping ungenau). → 2D-Grid, CSS-3D-Steine.
6. **Ablehnung Runde 3:** "Schade ... X und o selbst sollte 3D bleiben." → Three.js echte
3D-Steine + unsichtbares 2D-Grid-Overlay für präzise Klicks.
7. **Finales "Komplett zurück":** Nutzer zufrieden nur mit der ORIGINAL-Version.
→ `cp index-original.html.bak index.html`, `rm -rf lib/`, chown, Re-verify im Browser.
## Kernlektion
- Der Nutzer will **funktionierend + vertraut**, nicht **schick + neu**. Eine laufende
Seite mit einer blassen Erweiterung anzufassen ist riskant; ein full 3D-Redesign
bei einem simplen Spiel war die falsche Hebelgröße.
- Die Interaktion (präzises Klicken) ist unverhandelbar. Deko (3D) darf nie die
Bedienbarkeit brechen.
- Beim ersten "zurück / unspielbar" früh auf minimalen Stand zurück (nicht "reparieren
bis es gefällt") — spart · die 3 Wiederversuche.
## Was gut war & bleibt
- **Mesh-Brainstorming lief gut:** beide Rechen-Agenten (UnraidHermes + SwitchHermes)
lieferten substantielle, kritisch geprüfte Ideen mit eingebettetem Kontext in die
Task-Beschreibung (Briefing-Pitfall: NIE externe Datei — Agenten sehen nur /srv/work/tasks/).
- **Gegenprüfung:** LaptopHermes offline → KRITIK-Task an SwitchHermes umgeleitet, lief sauber.
## Three.js-Gotcha (Detail)
`BoxGeometry`/`BufferGeometry` haben KEINE `.rotation`-Eigenschaft — nur `Object3D`
(Mesh, Group) haben das. `g1.rotation.z = Math.PI/4` wirft
`TypeError: Cannot set properties of undefined (setting 'z')`.
Fix: `g1.rotateZ(Math.PI/4)` (Geometrie-Methode) oder Geometrie in ein Mesh packen.
Isolierter Browser-Test (`new THREE.BoxGeometry(...)`, `new THREE.MeshPhysicalMaterial(...)`)
half, den Fehler auf die Geometrie-Zeile einzugrenzen.
skills/devops/web-feature-iteration/references/urlaub-3-ebenen-zugsuche-2026-08-09.md
+43
View File
@@ -0,0 +1,43 @@
# urlaub.perfekt-ohne-en.de — 3-Ebenen-Zugsuche (2026-08-09)
Referenz für mehrstufige, DB-gestützte Navigations-Web-App. Gelernt beim Bau einer
3-Ebenen-Zugziele-Suche (Radevormwald → 100k → 50k/25k → 25k/10k).
## Architektur (endgültig)
- Flask + SQLite (`/opt/urlaub/urlaub.db`), Routen: `/`, `/2/<slug>`, `/3/<slug>`, `/pdf/<stadt>`, `/dbauskunft/<von>/<nach>`
- Templates: `ebene.html` (Kategorien als `selectattr`), `pdf.html`, `leer.html`
- systemd `urlaub.service` + nginx reverse_proxy auf `127.0.0.1:8040`
- PDF on-demand via `wkhtmltopdf` (ein `/tmp/urlaub-html/*.html` je Stadt)
## DB-Deep-Link — DEAD ENDS (wichtig, verifiziert 08.08)
Nutzer-Wunsch: ein Button, der bahn.de mit vorbefüllter Suche öffnet.
**Alle Deep-Link-Formate sind kaputt/nicht zuverlässig:**
- `reiseauskunft.bahn.de` → **toter DNS** (`DNS_PROBE_FAILED_NXDOMAIN`). Sub-Agent "bestätigte" dieses Format aus altem Wissen — **musste live getestet werden**.
- `reiseauskunft.de/bin/query.exe/dn?...` → toter Pfad ("Seite existiert nicht mehr")
- `www.bahn.de/buchung/fahrplan/suche?von=..&nach=..&..` → SPA übernimmt Query-Parameter NICHT
- `#query=start:X;destination:Y` → fragil, übernimmt nicht zuverlässig
**Lösung:** ehrliche Zwischenseite — zeigt Start/Ziel (readonly), Button + Fallback-Link auf
`https://www.bahn.de/buchung/fahrplan/suche` (verifiziert HTTP 200). Nutzer trägt Start/Ziel
manuell ein (paar Sekunden). Kein fabrizierter zuverlässiger Deep-Link.
## Daten-Pitfalls
- **Sortier-Filter-Bug:** `sorted(nach Distanz)[:N]` → nur nächste Ziele, alle fernen
5-7h/>7h-Kategorien "verschwinden". Fix: je Kategorie (unter5h/5-7h/über7h) die nächsten N.
- **Kategorie aus berechneter Zeit** ableiten (`h=d/70`, kategorisiere auf h), nicht aus
Distanz-Bandbreite — sonst Label widerspricht Zeit.
- **Platzhalter-Einwohner (alle 150000)** waren als "keine echten kleinen Städte" erkennbar.
Fix: echte Werte aus Referenzliste.
- Schwellen-Umbau im Nutzer-Konsens: E2 = 25k, E3 = 10k (nicht 50k/25k). Anzahl Städte ~
≥100k:80, ≥50k:~180-200, ≥25k:~400-450, ≥10k:~900-1100. Diese "mehr Städte bei tieferer
Schwelle"-Erwartung des Nutzers war korrekt.
## Abdeckung/Deep-Links
- Jede Ebene-Ziel sollte klickbar zur nächsten Ebene sein; bei finaler Ebene (z.B. 3) dürfen
Links nicht auf nicht-existente `/4/` zeigen (wäre 404-Dangling) — Endpunkt als `(final)` markieren.
- Umlaute in URLs: slug erzeugt `osnabrueck` via ae/oe/ue/ss-Transkription; Route muss
MEHRERE Kandidaten durchprobieren (`wuerzburg`, `würzburg`, `wurzburg`) inkl. umgekehrte
Richtung (`koln` → `Köln`). Wir praxis: `LOWER(replace(nach,' ',''))`-Vergleich.
## Mengen (zur Orientierung)
- Ebene1: 33 Ziele (100k+). Ebene2 (25k): ~1946. Ebene3 (10k): ~10222. (Nach Kategorien-Balance.)
skills/devops/web-hosting-deployment/SKILL.md
+401
View File
@@ -0,0 +1,401 @@
---
name: web-hosting-deployment
description: "Nginx Multi-Domain-Hosting mit Cloudflare DNS, Let's Encrypt SSL und Mail-Preservation – Deployment-Workflow für mehrere Domains auf einem Server"
version: 1.0.0
author: Agent A (netcup VPS Deployer)
platforms: [linux]
---
# Web-Hosting Deployment – Multi-Domain-Setup
Richtet mehrere Domains mit name-based virtual hosting auf einem einzelnen nginx-Server ein, inklusive Cloudflare-DNS-Verwaltung per API, Let's-Encrypt-SSL und sicherer MX-Record-Migration.
## Workflow-Übersicht
1. **Server prüfen** → nginx installiert? Ports 80/443 frei? UFW aktiv?
2. **DNS prüfen** → Wo zeigen die Domains hin? Welcher Provider?
3. **nginx VHosts anlegen** → Eine Config pro Domain in `sites-available/`
4. **DNS umstellen** → Per Cloudflare-API oder manuell A-Records auf Server-IP
5. **SSL per certbot** → Let's Encrypt für alle Domains gleichzeitig
6. **Mail schützen** → MX-Records 1:1 spiegeln, niemals proxien
---
## Schritt 1: nginx installieren & Basis-Check
```bash
apt-get update -qq && apt-get install -y nginx certbot python3-certbot-nginx
systemctl enable --now nginx
ufw allow 80/tcp && ufw allow 443/tcp && ufw allow 22/tcp
ufw --force enable
```
**Prüfen:**
```bash
ss -tlnp | grep -E ':80 |:443 ' # Ports frei?
nginx -t # Config ok?
```
---
## Schritt 2: Domain-Verzeichnisse & Platzhalter-Seiten
```bash
# Für jede Domain:
mkdir -p /var/www/example.de/{html,logs}
chown -R www-data:www-data /var/www/example.de
chmod -R 755 /var/www/
```
> ⚠️ **Pitfall: 403 Forbidden** – Ohne `chown www-data:www-data` kann nginx die Dateien nicht lesen. Sofort nach `mkdir` ausführen!
>
> ⚠️ **Pitfall: `write_file` erstellt root-only Dateien!** Hermes' write_file-Tool legt Dateien mit `root:root` und `600`-Permissions an. nginx (www-data) bekommt 403. **Nach JEDEM write_file auf /var/www/ sofort:** `chown www-data:www-data <datei> && chmod 644 <datei>`
---
## Schritt 3: nginx Virtual Hosts (Name-based)
Pro Domain eine Config in `/etc/nginx/sites-available/`:
```nginx
server {
listen 80;
listen [::]:80;
server_name example.de www.example.de *.example.de;
root /var/www/example.de/html;
index index.html index.htm;
access_log /var/www/example.de/logs/access.log;
error_log /var/www/example.de/logs/error.log;
location / {
try_files $uri $uri/ =404;
}
}
```
> ⚠️ **Pitfall: Wildcard-Subdomains** – `*.example.de` in `server_name` nicht vergessen, sonst landen Subdomains auf der nginx-Defaultseite!
Aktivieren:
```bash
ln -sf /etc/nginx/sites-available/example.de /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
```
**Lokal testen (vor DNS-Umstellung):**
```bash
curl -s -o /dev/null -w "HTTP %{http_code}\n" -H "Host: example.de" http://localhost/
curl -s -H "Host: example.de" http://localhost/ | grep -oP '<title>\K[^<]+'
```
---
## Schritt 4: Cloudflare DNS per API verwalten
### Zonen auflisten
```bash
curl -s "https://api.cloudflare.com/client/v4/zones" \
-H "Authorization: Bearer $CF_TOKEN" \
-H "Content-Type: application/json" | python3 -c "
import json, sys
for z in json.load(sys.stdin)['result']:
print(f\"{z['name']:35s} | {z['id']}\")
"
```
### Neue Zone anlegen
```bash
curl -s -X POST "https://api.cloudflare.com/client/v4/zones" \
-H "Authorization: Bearer $CF_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"example.de","account":{"id":"ACCOUNT_ID"},"jump_start":false,"type":"full"}'
```
### DNS-Einträge abrufen
```bash
curl -s "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" \
-H "Authorization: Bearer $CF_TOKEN" | python3 -c "
import json, sys
for r in json.load(sys.stdin)['result']:
print(f\"{r['type']:6s} {r['name']:40s} → {r['content']:25s} proxied={r['proxied']}\")
"
```
### A-Record setzen/aktualisieren (NEU)
```bash
curl -s -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" \
-H "Authorization: Bearer $CF_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type":"A","name":"example.de","content":"SERVER_IP","proxied":false,"ttl":1}'
```
### A-Record aktualisieren (BESTEHEND)
```bash
curl -s -X PATCH "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records/$RECORD_ID" \
-H "Authorization: Bearer $CF_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content":"SERVER_IP","proxied":false,"type":"A","name":"example.de","ttl":1}'
```
> ⚠️ **Pitfall: Cloudflare-Proxy (orangene Wolke)** – `"proxied":true` versteckt die echte Server-IP hinter Cloudflare. Das bricht:
> - **Let's Encrypt HTTP-Challenges** (Zertifikat kann nicht validiert werden)
> - **Direkte Server-Erreichbarkeit** für nicht-HTTP-Dienste
> - **Mail-Server** (niemals MX-Records proxien!)
>
> **Regel:** Für Webserver, die Let's Encrypt nutzen: `"proxied":false`. Nach SSL-Erhalt kann Proxy optional wieder aktiviert werden (dann aber TLS-Mode auf "Full (strict)").
---
## Schritt 5: Let's Encrypt SSL
### Alle Domains gleichzeitig (ein Zertifikat)
```bash
certbot --nginx \
-d domain1.de,www.domain1.de \
-d domain2.de,www.domain2.de \
--non-interactive --agree-tos \
--email admin@domain1.de \
--redirect
```
> ⚠️ **Pitfall: CNAME/Proxy blockiert Challenge** – Wenn certbot mit `unauthorized` fehlschlägt:
> 1. Prüfen ob CNAME-Records `proxied=true` haben → auf `false` setzen
> 2. Sicherstellen dass ALLE Domains im Zertifikat auf den Server zeigen
> 3. `dig +short A www.example.de` muss die Server-IP liefern, NICHT Cloudflare/GitHub-IPs
**Auto-Renewal prüfen:**
```bash
systemctl status certbot.timer
certbot renew --dry-run
```
---
## Schritt 6: MX-Records bei DNS-Migration schützen
**Goldene Regel:** MX-Records **niemals verändern**, nur **1:1 spiegeln**.
### Vor der Migration: Aktuelle MX-Daten sichern
```bash
dig +short MX example.de # MX-Records
dig +short A mail.example.de # Mailserver-IP
```
### In Cloudflare exakt spiegeln
```bash
# Mailserver A-Record (WICHTIG: proxied=false!)
curl -s -X POST ".../dns_records" -d '{
"type":"A","name":"mail.example.de",
"content":"MAIL_SERVER_IP","proxied":false,"ttl":1
}'
# MX-Record (darf NIE geproxied werden)
curl -s -X POST ".../dns_records" -d '{
"type":"MX","name":"example.de",
"content":"mail.example.de","priority":10,
"proxied":false,"ttl":1
}'
```
> ⚠️ **Pitfall: Mail-Ausfall** – MX-Records auch nur kurzzeitig zu verlieren bedeutet E-Mail-Bounce. Immer VOR dem Nameserver-Umzug sicherstellen, dass MX + Mail-A-Records in der neuen Zone existieren.
---
## Nameserver-Umzug: Schritt-für-Schritt
1. Zone bei Cloudflare anlegen
2. **ALLE bestehenden DNS-Einträge spiegeln** (A, AAAA, MX, CNAME, TXT, SRV)
3. MX & Mail-A-Records doppelt prüfen
4. Cloudflare-Nameserver notieren (z.B. `jay.ns.cloudflare.com`, `perla.ns.cloudflare.com`)
5. Beim alten Provider Nameserver ändern
6. 1–48h auf Propagation warten
7. SSL per certbot einrichten
---
## Troubleshooting
### 403 Forbidden nach VHost-Erstellung
```bash
chown -R www-data:www-data /var/www/
chmod -R 755 /var/www/
```
### Wildcard-Subdomains zeigen Default-Seite
`server_name` muss `*.example.de` enthalten. Prüfen:
```bash
grep server_name /etc/nginx/sites-enabled/example.de
curl -sI -H "Host: test.example.de" http://localhost/
```
### certbot: unauthorized / Invalid response
- Alle Domains im Zertifikat auf `proxied=false` prüfen
- `www`-CNAME darf nicht auf GitHub Pages o.ä. zeigen
- Sicherstellen dass ALLE Domains auf die Server-IP auflösen
### ⚠️ PITFALL – Certbot überschreibt SSL-Pfade in BESTEHENDEN vhosts
Siehe `nginx-vhost-deployment/SKILL.md` → **PITFALL – Certbot überschreibt SSL-Pfade in BESTEHENDEN vhosts**.
Kurzfassung: Nach jedem `certbot --nginx -d NEUE.DOMAIN.de` prüfen ob alle bestehenden Domains
noch ihr RICHTIGES Zertifikat haben. Certbot ändert ggf. `ssl_certificate`-Pfade in anderen
vhost-Dateien. Test: `curl -sk https://alte-domain.de/` → HTTP 200? Wenn nicht: SSL-Pfade
in der betroffenen Config zurücksetzen.
### ERR_CERT_COMMON_NAME_INVALID: vhost nutzt fremdes Zertifikat (2026-08-04)
**Symptom:** `curl https://<sub>...` ohne `-k` schlägt fehl; Browser meldet `ERR_CERT_COMMON_NAME_INVALID`, auch wenn eine frühere `curl -k`-Probe 200 lieferte. Grund: Der Subdomain-vhost referenziert ein **anderes** Zertifikat, in dessen SANs der eigene Hostname **fehlt**.
**Diagnose (immer zuerst, dauert 2 Sekunden):**
```bash
# Welches Zert referenziert der vhost?
grep -iE "ssl_certificate" /etc/nginx/sites-available/<sub>.perfekt-ohne-en.de
# Welche Hostnames deckt DIESES Zert ab?
openssl x509 -in /etc/letsencrypt/live/<cert>/fullchain.pem -noout -text \
| grep -A1 "Subject Alternative Name"
```
→ `tictactoe.perfekt-ohne-en.de` war auf das `perfekt-ohne-en.de`-Zert gelinkt (San der `fitness.`/`clownfischserver.` etc.), `tictactoe.` fehlte → Browser-Warnung.
**Fix: eigenes Zertifikat NUR für die Subdomain anlegen** (statt `--expand` aufs alte Zert):
```bash
certbot --nginx -d <sub>.perfekt-ohne-en.de \
--non-interactive --agree-tos -m <mail> --redirect
```
Erzeugt `/etc/letsencrypt/live/<sub>.perfekt-ohne-en.de/`, deployt automatisch in den vhost, Auto-Renew läuft. Danach ohne `-k` verifizieren:
```bash
curl -s -o /dev/null -w "HTTP %{http_code}\n" https://<sub>.perfekt-ohne-en.de/
openssl x509 -in /etc/letsencrypt/live/<sub>.perfekt-ohne-en.de/fullchain.pem -noout -text \
| grep -A1 "Alternative"
```
> ⚠️ **Warum NICHT `certbot --expand` aufs alte Zert?** Das alte Zert trägt ggf. Hostnames inaktiver/archivierter vhosts (z.B. eingestampfte Sites). `--expand` muss alle aufgelisteten Domains erneut validieren — scheitert leicht an deaktivierten vhosts und "budelt" in Sachen, die ruhen sollen. Ein frisches, schlankes Subdomain-Zert ist sauberer und kapselt die Domain. Faustregel: **ein Ziel-Hostname → eigenes Zert; nur verwandte aktive Hostnames in ein Zert bündeln.**
### Cloudflare API: Invalid API Token
- Token ist ggf. Zonen-beschränkt → kann keine neuen Zonen erstellen
- `/user/tokens/verify` funktioniert nur mit Account-weitem Token
- Zonen-Operationen (DNS) funktionieren trotzdem mit Zonen-Token
### Neue Subdomain: certbot --nginx scheitert, wenn SSL-vhost schon auf fehlendes Zert zeigt
**Situation:** Für eine neue Subdomain legt man einen vhost an und schreibt die
`ssl_certificate`-Zeilen **sofort** (aus Vorlage) hinein. `nginx -t` schlägt dann
fehl: `cannot load certificate "…/live/<sub>/fullchain.pem": No such file` — und
weil `nginx -t` bricht, wirft **`certbot --nginx` denselben Config-Fehler** (MisconfigurationError), bekommt kein Zert und es geht nicht weiter.
**Lösung (Reihenfolge zählt):**
1. vhost-Backup: `cp sites-available/<sub>.… sites-available/<sub>.…bak`
2. vhost auf **reines HTTP-80** ohne jede `ssl_certificate`-Zeile ersetzen →
`nginx -t` wieder ok → `systemctl reload nginx`
3. Zert **per webroot-Challenge** holen (KEIN `--nginx`-Plugin, das braucht eine
ladende Config):
```bash
certbot certonly --webroot -w /var/www/<sub> -d <sub>.perfekt-ohne-en.de \
--non-interactive --agree-tos --register-unsafely-without-email
```
4. SSL-vhost (aus dem `.bak`) zurückspielen → `nginx -t` + reload
5. Mit `curl -s -o /dev/null -w "%{http_code}" https://<sub>/` verifizieren
(HTTP 000 + Exit 60 = nur curl-Zert-Warnung, kein Serverfehler; `-k` zeigt dann 200).
### Statische datengetriebene Website mit PDF-Download je Eintrag
Für JSON-datengetriebene Listen-Seiten mit per-Eintrag-PDF (wkhtmltopdf) →
**`references/static-data-site-pdf.md`** (Datei-Struktur, Slug-Helper, PDF-Generator-Skript, Verifikation).
### Mehrstufige (Drill-Down) datengetriebene Website: Flask + SQLite + Reverse-Proxy
Für Sites mit verschachtelter Navigation über mehrere Ebenen (URL `/2/<stadt>`,
Klick auf ein Ziel erzeugt die nächste Liste) → **nicht statisch bauen**, sondern
**Flask + SQLite hinter nginx-Reverse-Proxy** (sonst ~1000–2000 statische Dateien).
Deckung: systemd-Service, Slug↔Umlaut-Match, PDF-on-demand (**je Einzel-Verbindung
`von→nach`, nicht Liste** — Nutzererwartung 2026-08-09), `/healthz`. Details →
**`references/flask-sqlite-drilldown-site.md`**.
### Docker-Interne-Dienste deployen (Gitea, Vaultwarden)
Für Docker-basierte Web-Apps (Gitea, Vaultwarden, Passwort-Manager, Git-Server)
hinter nginx-Reverse-Proxy mit Let's Encrypt SSL:
**`references/docker-internal-services.md`** — Deployment-Workflow, Setup-Schritte,
Admin-Token-Sicherung, Registrierung öffnen/schließen, Mirror auf zweitem Server.
### Echte Fahrplan-/Zugdaten automatisieren: DB blockt Bots
Für Reise-/Verbindungs-Sites mit realen deutschen Nahverkehrs-Zeiten: bahn.de +
DB-API blocken den Server-Zugriff hart (Bot-Erkennung Fehler 753, `OPS_BLOCKED`),
VRR-EFA deckt nur den eigenen Verbund, andere GTFS-Endpunkte waren unerreichbar.
Funktionierende Wege: regionale EFA, Nutzer liefert echte Zeiten manuell, oder
klar-labelierte Schätzwerte ("vor Fahrt auf bahn.de prüfen"). Nie erfundene Zeiten
als real ausgeben. Details → **`references/deutsche-bahn-timetable-data.md`**.
### Subdomain mit Wildcard-DNS schnell deployen
Wenn die Hauptdomain bereits per Wildcard (`*.example.de`) auf den Server zeigt, braucht eine neue Subdomain KEINE DNS-Änderung:
```bash
# 1. Verzeichnis + nginx-Config
mkdir -p /var/www/sub.example.de/{html,logs}
chown -R www-data:www-data /var/www/sub.example.de
cat > /etc/nginx/sites-available/sub.example.de << 'NGINX'
server {
server_name sub.example.de;
root /var/www/sub.example.de/html;
index index.html;
access_log /var/www/sub.example.de/logs/access.log;
error_log /var/www/sub.example.de/logs/error.log;
location / { try_files $uri $uri/ =404; }
listen 80; listen [::]:80;
}
NGINX
ln -sf /etc/nginx/sites-available/sub.example.de /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
# 2. HTML erstellen + Permissions fixen (CRITICAL!)
# ...write_file oder echo in index.html...
chown www-data:www-data /var/www/sub.example.de/html/index.html
chmod 644 /var/www/sub.example.de/html/index.html
# 3. SSL
certbot --nginx -d sub.example.de --non-interactive --agree-tos \
--email admin@example.de --redirect
```
Lokal testen: `curl -s -H "Host: sub.example.de" http://localhost/ | grep '<title>'`
### Multi-Site-Pattern: Verlinkte Websites mit Datenübergabe
Für mehrere zusammenhängende Single-Page-Apps auf Subdomains (z.B. Fitness-Rechner + Kalorienrechner) mit Cross-Linking, URL-Parameter-Datenübergabe, PDF-Export und Sponsor-Badge → **`references/multi-site-pattern.md`**
### Site einstampfen / deaktivieren / archivieren (2026-08-04)
Nutzer-Anweisung „einstampfen, ins Archiv, ruhen lassen" → **deaktivieren, nicht zerstören** (nicht-destruktive Grundregel):
```bash
# 1. nginx vhost deaktivieren (Symlink raus; available bleibt als Sicherung)
rm /etc/nginx/sites-enabled/<domain>
nginx -t && systemctl reload nginx
# 2. Code ins Archiv verschieben (nicht löschen!)
mkdir -p /srv/work/archiv/<projekt>
mv /root/<projekt> /srv/work/archiv/<projekt>/repo
mv /root/<projekt>_extracted /srv/work/archiv/<projekt>/extracted # falls vorhanden
# 3. LIESMICH.md mit Repo-Link + Reaktivierungsweg ablegen
# (Status, GitHub-URL, wie wieder aktivieren: Symlink + Code zurück)
```
- **Keinen Symlink/Code löschen** — nur deaktivieren + ins Archiv legen. Reaktivierung = Symlink zurück + Code zurück.
- **GitHub-Repo bleibt unangetastet** (extern); nur lokale Deployment-Artefakte werden archiviert. Repo-Link in `LIESMICH.md` festhalten.
- Nach Abschluss: `mesh-log.sh`-Eintrag + **Memory aktualisieren** (Projektstatus ändert sich von „läuft" zu „eingestampft/archiviert") — sonst halluziniert ein späterer Session-Start fälschlich „läuft noch stabil".
### Autogenerierte Report-/Archiv-Websites (Cron-regeneriertes HTML, 2026-08-03)
Wenn eine Subdomain **automatisch generierte Inhalte** zeigt (Live-Panel, Tages-Archive), die ein Script periodisch neu schreibt:
- **Kein PHP nötig.** Ein Shell-Script (z.B. `duo-master-report.sh`) baut die komplette `index.html` mit einem Heredoc zusammen und läuft per Cron (z.B. alle 60s für Live-Panel, täglich 23:50 für Tagesarchiv).
- Struktur: `Live-Panel` (dokumentationen.*) zeigt aktuelle Zustände; `Archiv` (archiv.*) speichert pro Datum eine HTML-Seite `JJJJ-MM-TT.html` PLUS eine `index.html` mit Linkliste auf alle Archive.
- Nach jedem Write: `chown www-data:www-data <webroot>` — sonst 403 (Hermes write_file erzeugt root:root).
- Daily-Archiv-Name = ISO-Datum (`$(date +%Y-%m-%d).html`), Linkliste wird aus vorhandenen `.html`-Dateien (ausgenommen `index.html`) aufgebaut.
- ⚠️ **Bash-Pitfall unter `set -euo pipefail`:** `ls /pfad/*.json | wc -l` bricht mit Exit 2 ab, wenn keine Dateien matchen (leerer Glob). Vorher `shopt -s nullglob` setzen (und danach `shopt -u nullglob`), sonst endet das gesamte Skript scheinbar ohne Fehler. Gleiches gilt für `ls "$WEB"/*.html` in der Linkliste.
skills/devops/web-hosting-deployment/references/cloudflare-api.md
+81
View File
@@ -0,0 +1,81 @@
# Cloudflare API Quick Reference
## Authentifizierung
```
Header: Authorization: Bearer <API_TOKEN>
Header: Content-Type: application/json
```
## API-Endpunkte
| Operation | Methode | URL |
|-----------|---------|-----|
| Zonen auflisten | GET | `/client/v4/zones` |
| Zone anlegen | POST | `/client/v4/zones` |
| Zone löschen | DELETE | `/client/v4/zones/:zone_id` |
| DNS-Records abrufen | GET | `/client/v4/zones/:zone_id/dns_records` |
| DNS-Record anlegen | POST | `/client/v4/zones/:zone_id/dns_records` |
| DNS-Record ändern | PATCH | `/client/v4/zones/:zone_id/dns_records/:record_id` |
| DNS-Record löschen | DELETE | `/client/v4/zones/:zone_id/dns_records/:record_id` |
## Zone anlegen (Minimal-Body)
```json
{
"name": "example.de",
"account": {"id": "ACCOUNT_ID"},
"jump_start": false,
"type": "full"
}
```
**Wichtig:** `jump_start: true` scannt bestehende DNS-Einträge, kann aber unerwünschte Records importieren. `false` startet mit leerer Zone.
## DNS-Record anlegen (Minimal-Body)
```json
{
"type": "A",
"name": "example.de",
"content": "92.60.38.175",
"proxied": false,
"ttl": 1
}
```
- `name: "@"` für Root-Domain, `name: "www"` für Subdomain
- `proxied: false` = graue Wolke (DNS-only), `true` = orangene Wolke (Proxy)
- `ttl: 1` = Auto-TTL
## MX-Record (Besonderheit)
```json
{
"type": "MX",
"name": "example.de",
"content": "mail.example.de",
"priority": 10,
"proxied": false,
"ttl": 1
}
```
- `priority`: Zahl (10 = Standard), niedriger = höhere Priorität
- **proxied MUSS false sein** – Cloudflare kann MX nicht proxien!
## Antwort parsen (python3 one-liner)
```bash
curl ... | python3 -c "
import json, sys
data = json.load(sys.stdin)
if data['success']:
for r in data['result']:
print(f\"{r['name']} → {r['content']}\")
else:
for e in data['errors']:
print(f\"ERROR: {e['message']}\")
"
```
## Typische Fehler
| Fehler | Ursache | Lösung |
|--------|---------|--------|
| `Invalid API Token` | Token falsch/abgelaufen | Neuen Token erstellen |
| `Zone already exists` | Zone bereits angelegt | Statt POST → GET + PATCH |
| `Invalid proxied mode for MX` | `proxied:true` bei MX | MX MUSS `proxied:false` sein |
| `Could not route to ...` | Zone-ID falsch | `GET /zones` für korrekte ID |
skills/devops/web-hosting-deployment/references/deutsche-bahn-timetable-data.md
+133
View File
@@ -0,0 +1,133 @@
# Deutsche Bahn / Fahrplan-Datenabruf: Realität & Workarounds (2026-08-08)
Nützlich beim Bau von Reise-/Verbindungs-Websites (z.B. Zugverbindungs-Liste
urlaub.perfekt-ohne-en.de), die echte Fahrtzeiten abfragen müssen.
## Kernbefund: DB automatisiert NICHT von einem Server aus
Beim Versuch, echte deutsche Nahverkehrs-Verbindungen (RE/RB/S-Bahn) automatisiert
zu bekommen, schlugen ALLE Server-seitigen Wege fehl:
| Weg | Ergebnis |
|-----|----------|
| `https://www.bahn.de/` im **Browserbase-Browser** | ❌ **Bot-Erkennung**: Fehler 753 „Verhalten Ihres Browsers ähnelt dem eines Bots" — auch im echten Browser (stealth-Warnung: „Running WITHOUT residential proxies"). |
| DB-Web-API (`/web/api/reiseloesung`) | ❌ `OPS_BLOCKED` |
| VRR EFA (`efa.vrr.de`) | ⚠️ Funktionierte für **Verbund-Haltestellen** (Radevormwald/Remscheid), liefert aber **keine Fernziele** (Frankfurt/Hannover außerhalb des VRR-Gebiets) — nur lokale Verbunde. |
| `api.transport.rest` / GTFS | ❌ nicht erreichbar (DNS/Timeout) |
| Web-Suche (Firecrawl) | ❌ nicht konfiguriert |
**Warum es so ist:** bahn.de + DB-API betreiben aktive Anti-Bot-Abwehr, unabhängig
davon ob der Zugriff von einem Python-Skript oder einem headless-Browser kommt.
Das ist eine bewusste, dauerhafte Serverseite — kein Setup-Fehler, der sich fixen lässt.
## Funktionierende Workarounds
1. **Regionale EFA (Verbund-API) für lokale Strecken**: `https://efa.vrr.de/std3/`
(JSON via `XSLT_STOPFINDER_REQUEST` / `XSLT_TRIP_REQUEST2`) funktioniert für
Haltestellen im jeweiligen Verkehrsverbund. Nur für Nahziele im Verbund nutzen,
nicht für Fernziele.
2. **Nutzer liefert die Zeiten manuell** (bewährt): Auf bahn.de / DB-Navigator
funktioniert die Suche für **menschliche Nutzer** einwandfrei. Bei 1-2 Zielen:
Nutzer gibt die schnellste Verbindung durch ☞ Master trägt die echten Zeiten ein.
Das ist zuverlässig + kostenlos + umgeht die Bot-Sperre.
3. **Schätz-/Richtwerte mit ehrlichem Hinweis** (Standard-Fall für viele Ziele):
Wenn keine echte Verifikation möglich ist, Netzwerk-Takte/Geographie als
**Richtwert** aufführen und auf der Seite + im PDF deutlich markieren:
„vor der Fahrt gegen bahn.de/DB-Navigator prüfen". NICHT als echte Fahrzeit
ausgeben.
4. **DB-Deep-Link pro Verbindung** (Nutzer-Idee): statt die Zeiten automatisiert
zu verifizieren, einen Link auf die DB-Suche VORBEFÜLLEN, den der Nutzer in
seinem Browser öffnet. Da der Nutzer keine Bot-Sperre hat, sieht er dort die
echten aktuellen Zeiten.
⚠️ **WICHTIG — LIVE-VERIFIZIERT am 2026-08-08 (Muss über den früheren Stand):
Die Deutsche Bahn bietet 2026 KEIN stabiles URL-Deep-Link-Format mehr an.**
Alle vorher als „stabil" geltenden Schemata sind empirisch tot:
- ❌ `reiseauskunft.bahn.de/bin/query.exe/dn?...` → **toter DNS** (`DNS_PROBE_FINISHED_NXDOMAIN`), Domain existiert nicht mehr.
- ❌ `reiseauskunft.de/bin/query.exe/...` → toter Pfad („Seite existiert nicht mehr").
- ❌ `www.bahn.de/buchung/fahrplan/suche?...` mit Query-Parametern → DB-SPA übernimmt die Eingaben NICHT (zeigt nur leere Suchseite).
- ❌ `www.bahn.de/buchung/fahrplan/suche#query=start:…;destination:…` → undokumentierte interne SPA-Fragmentroute, bricht (Einträge werden nicht übernommen, nur Fehlermeldung → leere Suche).
✅ **Funktionierende, ehrliche Lösung 2026-08-08:** Ein einfacher, zuverlässiger
Link auf die **noch erreichbare Sucheseite** `https://www.bahn.de/buchung/fahrplan/suche`
auf einer Zwischenseite, die Start+Ziel (readonly) anzeigt + einen Button
„In DB-Suche öffnen" (neuer Tab) + Fallback-Link. Der Nutzer tippt Start/Ziel
dort manuell ein (10 Sekunden) — aber der Link landet garantiert auf einer
funktonierenden Seite statt auf einem Deadlink. **Verifiziere jede DB-URL mit
`curl -s -o /dev/null -w "%{http_code}"` VOR dem Einsatz** — Sub-Agenten-Reviews
können veraltete Formate als „korrekt/getestet" bestätigen, ohne es live geprüft
zu haben (passiert hier real). Eine muntere Vorbefüllung ist 2026 nicht mehr
zuverlässig möglich; wer sie trotzdem versucht, scheitert an der SPA.
⚠️ Die offizielle DB-API (api.deutschebahn.com) wäre die robusteste Quelle für
programmatische Zeiten, braucht aber einen API-Key — und ist weiterhin
vorbehaltlich Bot/Key-Zugang zu prüfen.
## Google Maps als ÖPNV-Quelle? NEIN — ICE lässt sich nicht rausfiltern (2026-08-08)
Nutzer-Idee beim Bau einer Verbindungs-Site: „Kann man Google Maps-Öffis-Daten
nehmen?" — ehrliche Antwort, die in Zukunft nicht neu hergeleitet werden muss:
- Google Maps **zeigt** ÖPNV (Bus, S-Bahn, RE, ICE, IC), aber als schnellste Route
schlägt es **standardmäßig ICE/IC vor**.
- Es gibt **KEINEN sauberen „nur Regionalverkehr / Deutschlandticket"-Filter** in
Google Maps (nur ein grober Transit-Filter). `regional-only` von ICE zu trennen
ist nicht zuverlässig möglich.
- Dieselben GTFS-Fahrpläne wie überall (DB/Verkehrsverbünde) — also nichts Besseres
/qchlechteres als reiseauskunft.
- Google Maps blockt zudem Bots (wie die DB), sodass saubere Automatisierung nicht
klappt.
- **Fazit:** Für eine „kein ICE / nur Deutschlandticket“-Anforderung ist unser
DB-Deep-Link zur noch erreichbaren Sucheseite (`https://www.bahn.de/buchung/fahrplan/suche`,
ohne Vorbefüllung, siehe Abschnitt 4) besser — die Seite hat einen expliziten
Deutschlandticket-Filter, den der Nutzer einen Klick entfernt sieht. (Der früher
genannte `query.exe/dn`-Deep-Link ist tot — siehe Abschnitt 4.)
## Label nach ECHTER Fahrtzeit, nicht nach Wunsch-Kategorie (2026-08-08)
Nutzer: „Nicht EINE Fahrt 5-7h in der Liste, ich sehe nur <5h oder >7h." Ursache war
**zweifach**, beides wartbar:
1. **Label-Mismatch-Bug:** 168 Ebene-2-Zeilen waren als `Kernziel (5-7h)` markiert,
obwohl ihre Fahrtzeiten real 0,3–4h waren. Beim Seeden wird gern „5-7h" als Wunsch-Category
an die Fernziele gehängt. **Fix: Kategorie aus der echten Fahrtzeit ableiten**
(Parser `~h` → float, dann `<5 → unter 5h`, `5–7 → Kernziel (5-7h)`, `>7 → über 7h`),
nicht als Design-Wunsch beim INSERT setzen.
2. **Geographische Realität:** per reinem Nahverkehr sind echte 5–7h-Ziele selten
(viele Großstädte entweder <3h Nahzone oder >8h Fernzone). Das ist kein Bug,
sondern Physik — die Seite soll alle Kategorien ehrlich anzeigen und „5-7h" nur
dort führen, wo es sie wirklich gibt (ab weiter südlich/östlich gelegenen Städten:
Frankfurt→München/Dresden, Hannover→Stuttgart etc.).
## Ehrlichkeits-Regel (Nutzer erwartet dies)
- Niemals fabrizierte „fahrhatige" Verbindungen oder konkrete Uhrzeiten als real
ausgeben, wenn sie nur geschätzt sind.
- Schätzwerte IMMER als Bereich (`~5-5,5 h`) + mit Verweis auf bahn.de labeln.
## RAPTOR statt Dijkstra für echte GTFS-Routing (2026-08-19, Team-Unraid)
Für GTFS-Verbindungssuche auf großen Knoten ist **einfacher Dijkstra instabil** —
bei benachbarten Zielen kamen absurde Differenzen (Mainz→Berlin 11h vs. Nachbar
Wiesbaden 3h). Standard-Lösung ist **RAPTOR** (Round-Based Public Transit Optimized
Route): erweitert die Reichweite Runde um Runde über echte Trips und behandelt
"Zug nehmen → aussteigen → umsteigen" natürlich, statt auf einem statischen
Graphen zu kürzen.
- **Stop-Mehrdeutigkeit** (ein Bahnhof, mehrere stop_ids, nur 1 aktiv in `st`) →
eindeutig über `parent_station`/Geo-Mapping auflösen.
- **Umstiegsbuffer** (4 min) + sauberes Ziel-Stop-Matching verhindern die
"benachbarte Ziele, extrem abweichende Zeiten"-Inkonsistenz.
- Verifizieren mit Plausibilitäts-Ankern (z.B. Trier→Saarbrücken ~1h, Köln→Aachen
~50min) — nie den Algorithmus blind vertrauen.
- Wenn der Nutzer einen Konkreten echten Wert liefert (z.B. „Trier 6h"), ihn
bevorzugt übernehmen statt der Schätzung.
## Fakten zur Ziel-Menge (Zugverbindungs-Website, Kontext)
- Schwelle kann variieren (250k → 100k Einwohner → weit mehr Ziele, ~33 in dieser Site).
- Reichweite per **reinem Nahverkehr** (kein ICE) ab Bergisch-Land/Ruhrgebiet:
die meisten Großstädte sind entweder **<3h** (Nahzone: Köln, Düsseldorf, Ruhrgebiet)
oder **>8h** (Fernzone: Berlin, München). Echte **5–7h**-Ziele sind selten — das sind
genau die Grenzfälle (Frankfurt ~5h, Wiesbaden ~5,5h, Hannover ~5,5–6,5h, Kassel ~6,5–7h).
Regional-Agenten (SwitchHermes/LaptopHermes) lieferten dazu gute Geographie-Analysen.
skills/devops/web-hosting-deployment/references/docker-internal-services.md
+158
View File
@@ -0,0 +1,158 @@
# Docker Internal Services Deployment (Gitea + Vaultwarden)
## Anwendungsfall
Interne Dienste (Git-Server, Passwort-Manager, sonstige Web-Apps) auf einem VPS
hinter nginx-Reverse-Proxy mit Let's Encrypt SSL betreiben. Dienste laufen als
Docker-Container, sind nur für den Eigentümer bestimmt (oder registrierungsbeschränkt).
## Beispiel-Stack
| Dienst | Docker-Image | Port | Subdomain | Zweck |
|--------|-------------|------|-----------|-------|
| **Gitea** | `gitea/gitea:latest` | 3000 | `git.mehlzoerwer.de` | Eigener Git-Server für Skills/Configs |
| **Vaultwarden** | `vaultwarden/server:latest` | 4433 | `vault.perfekt-ohne-en.de` | Passwort-Manager (Bitwarden-kompatibel) |
## Deployment-Workflow
### 1. Docker-Container starten
```bash
# Verzeichnisse
mkdir -p /opt/gitea/data /opt/vaultwarden/data
# Gitea
docker run -d --name gitea --restart unless-stopped \
-p 3000:3000 -p 2222:22 \
-v /opt/gitea/data:/data \
-e USER_UID=1000 -e USER_GID=1000 \
gitea/gitea:latest
# Vaultwarden
ADMIN_TOKEN=$(openssl rand -base64 48)
docker run -d --name vaultwarden --restart unless-stopped \
-p 4433:80 \
-v /opt/vaultwarden/data:/data \
-e SIGNUPS_ALLOWED=true \
-e ADMIN_TOKEN=$ADMIN_TOKEN \
-e DOMAIN=https://vault.perfekt-ohne-en.de \
vaultwarden/server:latest
# Token sichern
echo "$ADMIN_TOKEN" > /opt/vaultwarden/admin_token.txt
chmod 600 /opt/vaultwarden/admin_token.txt
```
### 2. nginx-Reverse-Proxy pro Dienst
```nginx
# /etc/nginx/sites-available/git.mehlzoerwer.de
server {
listen 80;
listen [::]:80;
server_name git.mehlzoerwer.de;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
```nginx
# /etc/nginx/sites-available/vault.perfekt-ohne-en.de
server {
listen 80;
listen [::]:80;
server_name vault.perfekt-ohne-en.de;
location / {
proxy_pass http://127.0.0.1:4433;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket-Support für Browser-Extension
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
### 3. SSL (DNS muss bereits auf den Server zeigen)
```bash
certbot --nginx -d git.mehlzoerwer.de --non-interactive --agree-tos -m admin@domain.de
certbot --nginx -d vault.perfekt-ohne-en.de --non-interactive --agree-tos -m admin@domain.de
```
### 4. Nach SSL prüfen
```bash
# Prüfen ob bestehende Domains noch funktionieren (Certbot-Kollateral-Pitfall!)
for url in https://git.mehlzoerwer.de/ https://vault.perfekt-ohne-en.de/ https://mehlzoerwer.de/; do
echo "$url → $(curl -sk -o /dev/null -w '%{http_code}' $url)"
done
```
## Vaultwarden Setup
| Schritt | Aktion |
|---------|--------|
| 1. Registrierung öffnen | `SIGNUPS_ALLOWED=true` setzen, Container neustarten |
| 2. Account erstellen | `https://vault.perfekt-ohne-en.de/` → "Create Account" |
| 3. Registrierung schließen | Container stoppen, mit `SIGNUPS_ALLOWED=false` neustarten |
| 4. Admin-Panel | `https://vault.perfekt-ohne-en.de/admin` → Admin-Token |
| 5. Clients verbinden | Bitwarden-Apps → eigene Server-URL eintragen |
## Gitea Mirror auf zweitem Server
```bash
# Auf UnraidHermes (zweiter Server)
sudo mkdir -p /opt/gitea-mirror/data
sudo tee /opt/gitea-mirror/docker-compose.yml > /dev/null << 'YAML'
services:
gitea:
image: gitea/gitea:latest
container_name: gitea-mirror
restart: unless-stopped
ports:
- "3001:3000"
volumes:
- /opt/gitea-mirror/data:/data
environment:
- USER_UID=1000
- USER_GID=1000
YAML
cd /opt/gitea-mirror && sudo docker compose up -d
```
## Pitfalls
### ⚠️ Certbot überschreibt bestehende SSL-Pfade
Nach `certbot --nginx -d NEUE.DOMAIN.de` prüfen ob bestehnde Domains noch ihr richtiges
Zertifikat haben. Certbot kann `ssl_certificate`-Pfade in anderen vhosts überschreiben.
→ `nginx-vhost-deployment` Skill: "Certbot überschreibt SSL-Pfade in BESTEHENDEN vhosts"
### ⚠️ Vaultwarden Admin-Token sichern
`openssl rand -base64 48` erzeugt einen Token. Dieser wird NUR beim ersten Start
ausgegeben (in den Logs). Danach nie wieder. **Sofort speichern:**
```bash
echo "$ADMIN_TOKEN" > /opt/vaultwarden/admin_token.txt
chmod 600 /opt/vaultwarden/admin_token.txt
```
Alternativ: `-e ADMIN_TOKEN_FILE=/data/admin_token` — dann reicht die Datei im
Volume-Verzeichnis, Container-Neustart überlebt den Token.
### ⚠️ Vaultwarden SIGNUPS_ALLOWED
Initial auf `true` setzen, damit der Eigentümer einen Account erstellen kann.
Nach dem ersten Account: Container stoppen, mit `SIGNUPS_ALLOWED=false` neustarten.
Kein Fremder kann sich danach registrieren.
### ⚠️ Docker-Gruppe für sudo-lose Ausführung
Sub-Agenten (UnraidHermes) haben `mehlzoerwer` nicht in der `docker`-Gruppe.
Fix: `sudo usermod -aG docker $USER && newgrp docker` (einmalig, danach
docker ohne sudo).
skills/devops/web-hosting-deployment/references/flask-sqlite-drilldown-site.md
+215
View File
@@ -0,0 +1,215 @@
# Flask + SQLite: Mehrstufige "Drill-Down"-Website mit nginx-Reverse-Proxy
Bewährt für datengetriebene Sites, die über mehrere Ebenen verschachtelt navigierbar
sind, z.B. `urlaub.perfekt-ohne-en.de`: Ebene1 (Start Radevormwald → 33 Ziele ≥100k),
Klick auf ein Ziel → Ebene2 (Liste ab dieser Stadt, ≥50k), Klick → Ebene3.
## Warum Backend (Flask+SQLite) statt statischer HTML
Für 3 Ebenen wären statische Seiten **~1000–2000 Dateien** (jede Ebene-2-Zielstadt
wieder eine Liste + PDFs) — unwartbar bei häufigen Datenänderungen. Ein Backend mit
DB: eine `UPDATE` → alle Seiten/Pfade sofort korrekt. SQLite reicht locker
(<100 Queries/Tag, persönliches Projekt). Team-Empfehlung (UnraidHermes) bestätigt.
## Architektur
```
nginx (Subdomain vhost) → proxy_pass 127.0.0.1:8040 → Flask (app.py)
└─ SQLite (urlaub.db)
```
- Flask läuft als **systemd-Service** (`/opt/<app>/venv/bin/python app.py`).
- nginx-`location / { proxy_pass http://127.0.0.1:8040; proxy_set_header Host $host; ... }`
- PDF on-demand: Flask-Route rendert Template → `wkhtmltopdf` → Response(pdf).
## Kern-Implementation (app.py)
- SQLite-Verbindung je Request (`sqlite3.connect`, `row_factory = sqlite3.Row`).
- Slugs für URLs: `frankfurt-am-main`, `osnabrueck`, `goettingen`.
- **Slug↔Stadtname-Match muss Fallback/Transkription akzeptieren** — URL ist
lowercase slug mit Bindestrichen, DB speichert echten Namen ("Frankfurt am Main",
"Osnabrück"). Match mit `LOWER(replace(nach,' ',''))=LOWER(replace(?,' ',''))`
UND Umlaut-Rücktranskription: `ue→ü/ue/u`, `oe→ö/oe/o`, `ae→ä/ae/a`, `ss→ß/ss/s`.
- `slug()` muss Umlaute VOR `ascii-encode` expandieren: `ä→ae, ö→oe, ü→ue, ß→ss`.
- Ebene-Route: `@app.route('/<int:ebene>/<slug_name>')` — `ebene in (2,3)`, sonst 404.
- Startstadt = die angematchte Stadt; Ziele = `WHERE ebene=? AND von=?`.
- Leere Ebene → eigenes `leer.html`-Template ("Noch keine Ziele…"), kein 404.
- `/healthz` → `"ok"` für systemd/nginx-Readiness.
## Deployment-Ablauf
1. `python3 -m venv venv && venv/bin/pip install flask` (sqlite3 in stdlib).
2. `venv/bin/python -c "import flask"` (Syntax-/Install-Check NICHT mit `||`-Fehler
in derselben Python-Zeile verwechseln).
3. DB-Init + Seed (Skripte `db_init.py`, `seed_ebene2.py`).
4. Testen: `./venv/bin/python app.py` im Hintergrund → `curl 127.0.0.1:8040/healthz`
und Routen. Dann killen, Start an systemd übergeben:
`ExecStart=/opt/<app>/venv/bin/python /opt/<app>/app.py`, `Restart=always`.
5. nginx: Proxy gegen `127.0.0.1:8040` einrichten (siehe Haupt-SKILL: vhost via
`/tmp` + `cp` — write_file weigert sich bei `/etc/nginx/*`; Backup-Regel vorher).
6. `nginx -t && systemctl reload nginx`, dann über `https://<sub>` verifizieren.
## ⚠️ Änderungen an Templates/Code erfordern einen Service-Neustart (2026-08-08)
Flask läuft hier mit `debug=False` (systemd). Das heißt: Template-Edits (`*.html`)
und `app.py`-Änderungen werden **NICHT automatisch neu geladen**. Symptom aus dem
Live-Betrieb: Nachdem eine neue Kategorie-Gruppe (z.B. `unter 5h`) ins Template
kam, zeigte die laufende Seite sie **nicht** — erst `systemctl restart urlaub.service`
brachte sie sichtbar. **Regel: nach jeder Template/Code-Änderung IMMER den systemd-
Service neu starten** und dann die Seite per `curl` gegen die erwartete neue Markierung
prüfen (z.B. `grep -oE '<h2>[^<]+</h2>'`). Nur DB-Seed-/Update-Skripte (die `urlaub.db`
schreiben) wirken sofort, weil jede Request frisch auf SQLite liest.
## Verifikation (immer durchführen)
```bash
curl -sk -o /dev/null -w "/ → %{http_code}\n" https://<sub>/
curl -sk -o /dev/null -w "/2/<stadt> → %{http_code}\n" https://<sub>/2/<stadt>
curl -sk -o /dev/null -w "/3/<stadt> → %{http_code}\n" https://<sub>/3/<stadt>
curl -sk -o /dev/null -w "/pdf/<stadt> → %{http_code}\n" https://<sub>/pdf/<stadt>
```
HTTP 000 + curl-Exit 60 = nur Zert-Warnung, `-k` zeigt 200.
## Datenquellen für Ebene-2/3 am sinnvollsten
- **Start mit kleinen, konkreten Team-Tasks** ("gib je Startstadt Ziele ≥50k im
Format Stadt|~h|Ziel1,Ziel2") — NICHT breit formulieren; Sub-Agenten liefern sonst
nur Enzyklopädie/Regionen statt präziser Stadt-zu-Stadt-Zuordnung (wiederholtes Muster).
- Der Master kuratiert die Team-Rohdaten gegen Geographie (keine offensichtlichen
Fehler), markiert alles als **Richtwerte**.
- Ebene-3-Daten optional; Route existiert und zeigt sauber `leer.html` bis befüllt.
## ⚠️ Datenqualität: NIE Platzhalter-Zahlen als echtes Datum (2026-08-08)
Beim Seeden von Ebene-2-Städten wurde `einwohner=150000` pauschal für ALLE gesetzt.
Der Nutzer bemerkte sofort "es gibt keine 50k–100k-Städte in der Liste" — korrekt:
alle kleineren Städte (Würzburg, Koblenz, Hameln …) zeigten fälschlich 150k.
**Regeln:**
- Jeder Eintrag braucht **echte, individuell korrekte** Werte. Unbekannte als
`NULL`/"k.A." führen — **niemals** einen plausiblen Platzhalter wie `150000`.
- Nach dem Seed IMMER einen Duplikat-/Platzhalter-Check laufen lassen:
`SELECT nach FROM verkehr WHERE einwohner=<platzhalter>` → darf 0 Treffer liefern.
- Wenn echte Zahlen fehlen (kein Webzugriff), schätzen mit **Bereich + Label**
("Richtwert"), nicht als exakte Zahl. Beim späteren Update echte Werte nachtragen.
- 50k–100k-Ziele sind der eigentliche Kern einer kleinere-Schwelle-Liste — sie
explizit ergänzen (Team lieferte konkrete: ab Trier→Worms/Bad Kreuznach/
Idar-Oberstein/Neunkirchen; ab Hannover→Hameln/Celle/Goslar/Lüneburg/Delmenhorst).
## ⚠️ Finale Ebene darf keine Dangling-Links auf nicht-existente Unter-Ebene erzeugen (2026-08-08)
Das Drill-Down-Template verlinkte jedes Ziel auf `/<ebene+1>/<slug>` — auch auf der
**letzten** Ebene. Bei 3 Ebenen zeigte Ebene-3 daher Ziele, die auf **`/4/<stadt>`**
verwiesen, eine Route die es nicht gibt → **404** (und Verstoß gegen die Nutzer-Erwartung
„jede Ebene hat eine Unter-Ebene… bis die es gibt«). User bemerkte es sofort.
**Fix / Regel:** Das Template muss die **letzte Ebene als final markieren** statt
einen toten Weiter-Link zu rendern:
```jinja
{% if ebene <= MAX_EBENE_DEPTH %}
<td><a href="/{{ ebene+1 }}/{{ z.nach|lower }}">{{ z.nach }}</a></td>
{% else %}
<td>{{ z.nach }} <small>(final)</small></td>
{% endif %}
```
Generell: **Jeder `href` auf eine `<ebene+1>`-Route darf nur in Ebenen gerendert
werden, die wirklich existieren** (≤ Tiefe). Vor dem Livegehen alle Funktions­pfade
durchklicken (curl auf `/1/ `/2/ `/3/`) und darauf achten, DASS kein Link auf eine
NICHT eingerichtete Ebene zeigt (`grep -oE 'href="/4/'` darf leer sein).
## Umlaut-Slug-Match: auch umgekehrte Einzelbuchstaben berücksichtigen (2026-08-08)
Der Slug für `Köln` ist `koln` (nur `ö→o` beim Sluggen), während ein Nutzer/anderer
Kandidat `koeln` (Transkription) verwenden könnte und die DB `Köln` speichert. Der
Stadtname-Match muss ALSO **beide^ Richtungen** anbieten:
- Transkription: `ue→ü, oe→ö, ae→ä, ss→ß` (für Slugs, die voll transkribieren).
- **Einzelbuchstaben umgekehrt:** `o→ö, u→ü, a→ä, s→ß` (für URL-Slugs wie `koln`,
`wuerzburg`→`würzburg`), damit `koln`→`Köln` matcht.
Jeder Fund-Kandidat wird gegen `LOWER(replace(nach,' ',''))` geprüft; der erste
Treffer gewinnt. Ohne den Einzelbuchstaben-Fall bleiben `koln`, `rossleben`-artige
URLs auf 404, obwohl die Stadt existiert. Beispiel-Kandidatenliste für `koln`:
`koln, köln, koeln, koln` (alle Versuche) — der `ö`-Versuch matcht die DB.
## ⚠️ Generator: nie nur die NÄCHSTEN Ziele nehmen — sonst verschwinden Fernziele (2026-08-09)
Beim automatischen Seeden von Drill-Down-Ebenen (Distanz-basiert, z.B. Ebene-2-Ziele
aus einer Städte-Referenzliste mit Haversine) ist die größte Daten-Falle das
**Abschneiden des fernen Endes**:
```python
# FALSCH: sortiert nach Distanz (nahe zuerst) und nimmt die ersten N
ziele.sort(key=lambda x: x[0]/70) # d/70 = h
for nach, ... in ziele[:N]: # N = z.B. 26
...
```
→ Das nimmt nur die **nächsten** Städte. Alle **5-7h- und >7h-Fernziele** fallen
raus, weil sie weiter weg sind. Symfony: Trier-Ebene2 hatte danach **nur "unter 5h"**
(alle 26), 0 Kernziele, 0 Fernziele. Der Nutzer bemerkte sofort: „Jetzt sind nur noch
die kleinen da — was ist mit den 5-7h und >7h passiert?"
**Fix — pro Kategorie die nahsten N, damit ALLE Kategorien vertreten bleiben:**
```python
kat = {"unter 5h":1, "Kernziel (5-7h)":2, "über 7h":3}[...] # h aus d/70
kategorien[kat].append(...)
# danach je Kategorie sortieren + je Kategorie max_pro_kat nehmen
for kat in ["unter 5h","Kernziel (5-7h)","über 7h"]:
kategorien[kat].sort(key=lambda x: dist)
ziele += kategorien[kat][:max_pro_kat] # z.B. max_pro_kat=9
```
Gib dadurch pro Startstadt z.B. 26 unter5h + 26 kern + 17 über7h statt nur 26 nah.
**Zweite Fall-Hälfte (Kategorie aus echter Zeit ableiten, NICHT aus Wunschbandbreite):**
Die Kategorie muss aus der **berechneten Stundenzahl** (`h<5 → unter5h`, `5≤h≤7 →
Kernziel(5-7h)`, `h>7 → über7h`) kommen. Vorher wurde `d<350km → 5-7h` als Distanz-
Bandbreite gesetzt, was Ziele mit `~3h` als "Kernziel 5-7h" labelte — also Label und
angezeigte Fahrtzeit widersprachen sich (Dinslaken ~3h als "5-7h"). Einheitlich: erst
`h = d/70` berechnen, dann Kategorie aus h. Prüf-Check nach dem Seed:
```sql
SELECT kategorie,COUNT(*) FROM verkehr WHERE ebene=2 GROUP BY kategorie -- alle 3 gefüllt?
```
Erwartung: nie eine Ebene, die nur 1 Kategorie enthält, solange es Fernziele <700km
gibt.
## ⚠️ PDF-Erwartung: je EINZELNE Verbindung, nicht Liste aller Ziele (2026-08-09)
Nutzer beim Betrachten der urlaub-Site: „Die PDF finde ich blöd. Ich habe gedacht
die PDF wäre für die Verbindung von → nach, nicht nur eine PDF mit allem." — Der
erste Entwurf erzeugte **eine PDF pro Startstadt mit ALLEN Zielen** (Liste). Erwartung
war aber: **eine PDF je konkreter Fahrt (Start → Ziel)**.
**Fix:** Route auf Paar umbauen `@app.route('/pdf/<von>/<nach>')` mit einem *losen*
`pdf_einzel.html`-Template (Abfahrt-Zeit/Ziel/Fahrtzeit/Weg/Ticket), das **genau eine**
Verbindung beschreibt. Links in der Tabelle zeigen dann auf
`/pdf/<von>/<nach>` (je Zeile), nicht auf `/pdf/<startstadt>`. Wichtig:
- Beide Slugs über den `resolve()`-Helper mit Umlaut-/Fallback-Match gegen DB auflösen.
- Existiert die Verbindung nicht in der DB, trotzdem eine saubere Wegzeile rendern
(„Richtwert (DB prüfen)") statt 404 — der Nutzer soll immer ein PDF bekommen.
- Nach Umbau die alte Listen-Route entfernen (`/pdf/<stadt>` → 404 bestätigen), sonst
bleibt die gewohnte Liste erreichbar und verwirrt.
- Dateiname je Verbindung: `<von>--<nach>.pdf` (vermeidet Überschreiben bei mehreren Fahrten).
**Grundsatz:** Bei "PDF pro X" immer zuerst klären, ob der Nutzer *ein Dokument je
Datensatz* (hier: Fahrt) oder *ein Sammeldokument je Gruppe* (Startstadt) will.
Im Zweifel Richtung "je einzelner Eintrag/Fahrt" gehen — das ist die intuitive Erwartung.
## Team-Audit: Sub-Agenten können VPS-Dateien nicht lesen (2026-08-09)
Ein Audit-Task, das einem Sub-Agenten nur einen Pfad gibt (`/opt/urlaub/app.py`,
`urlaub.db`) scheitert stets: Rechen-Agenten haben **keinen VPS-Lesezugriff** und
finden die Datei nicht → sie können den Code nicht gegenprüfen und brechen ab
(korrekt, statt zu erfinden). Für Code-/Daten-Audits musst du als Master die
**relevanten Inhalte in den Task einbetten** (Schema, Codesnippets, Beispiel-Zeilen)
oder den Audit selbst anhand des echten Systemstands durchführen. Sonst läuft ein
„Team-Audit" ins Leere. Dieses Session-Thema: 1 von 3 Audit-Tasks brachte nichts,
weil der Agent nur den Pfad bekam.
## ⚠️ Backend-Code gehört ebenfalls ins Team-Review (2026-08-08)
Der Nutzer fragte nach dem Bau zu Recht: „Habt ihr euch gegengecheckt?" — Die
Ebene-2-DATEN kamen vom Team, aber der **Flask-Code/PDF/DB-Link war solo gebaut
ohne Review**. Die Review-Runde fand SOFORT echte Bugs:
- DB-Deep-Link `#query=`-Format war falsch (→ korrektes `query.exe/dn`, siehe
`deutsche-bahn-timetable-data.md`).
- Einwohner-Platzhalter (s.o.).
**Lektion:** Nicht nur fachliche Daten durchs Team prüfen lassen, sondern auch den
Deployment-Code. Ein kurzer Review-Task mit eingebettetem Kontext („Bitte analysiere
den Deep-Link + Platzhalter, nenne Fixes") findet solche Fehler günstig und schnell —
genau das „4 Agents > 1 teurer Agent"-Prinzip des Nutzers.
skills/devops/web-hosting-deployment/references/gtfs-raptor-routing.md
+83
View File
@@ -0,0 +1,83 @@
# GTFS-RAPTOR-Verbindungssuche: Praxis & Pitfalls (2026-08-19, urlaub.perfekt-ohne-en.de)
Echte Nahverkehrs-Verbindungs-Suche (RE/RB/S-Bahn, kein ICE) aus einer GTFS-Datei
(Nutzer lieferte `r.und.s.bahnen.zip`). Löst die Aufgabe "komplette Haltestellenliste
in einer PDF + konsistente Fahrzeiten für viele Zielverbindungen".
## Warum RAPTOR statt Dijkstra
Einfacher Dijkstra auf einem statischen Graphen ist bei großen Knoten **instabil**:
benachbarte Ziele ergaben absurde Differenzen (Mainz→Berlin 11h vs. Nachbar Wiesbaden
3h). **RAPTOR** (Round-Based Public Transit Optimized Route) erweitert die Reichweite
Runde um Runde über echte Trips und behandelt "Zug nehmen → aussteigen → umsteigen"
natürlich. Für Zeit-abhängiges Transit-Routing ist RAPTOR der Standard.
## GTFS-Import — Spaltenreihenfolge ist NICHT selbsterklärend!
Vor dem Import IMMER `head -1 <datei>.txt` lesen, nie annehmen:
- `stops.txt`: `stop_name, parent_station, stop_id, stop_lat, stop_lon, …`
**stop_id ist Spalte 3**, parent_station Spalte 2. Ein Bahnhof hat oft ZWEI Zeilen
(parent-'Hbf' + stop_id-Knoten); die `stop_id` ist fürs Joinen zu `stop_times` gedacht.
- `stop_times.txt`: `trip_id, arrival_time, departure_time, stop_id, stop_sequence, …`
**stop_id Spalte 4**.
- `trips.txt`: `route_id, service_id, trip_id` — **trip_id Spalte 3**, nicht 0.
Import-Bug hier: Spalte 0 (route_id) genommen → nur 964 statt 110.087 Trips.
- `stop_times.txt` ist riesig (82MB); als SQLite laden mit Index auf `(trip_id, seq)`.
## Bahnhof = mehrere stop_ids, nur 1 aktiv in `st`
Große Knoten haben MEHRERE stop_ids (Saarbrücken Hbf = 6, Köln Hbf = 2), aber nur
einige kommen in `stop_times` vor. `SELECT stop_id WHERE stop_name='Köln Hbf'` kann eine
"tote" ID mit 0 Trips liefern. **Lösung: Geo-Merge** — Stops <350m Abstand (Haversine)
in eine Gruppe fassen; Routing löst Start/Ziel über die GANZE Gruppe auf und nimmt MIN
über alle Ziel-IDs. Sonst schlägt die Verbindung fehl oder wird absurd.
## `resolve("Berlin")`-Substring-Falle
`name.lower() in stop_name.lower()` matcht ALLE Stops mit "berlin" im Namen — auch
kleine Orte (z.B. ein Ort "Berlin" unweit Trier → unter 5h statt quer durchs Land!).
Für mehrdeutige Städte IMMER eindeutigen Bahnhof angeben (`"Berlin Hbf"`) und die
Site-DB-`nach`-Werte darauf normieren. Umlaute: Name-basiertes Matching braucht
Umlaut-Rücktranskription (ue/oe/ae/ss ↔ ü/ö/ä/ß).
## RAPTOR: Dauer UND Pfad (für PDF-Haltestellenliste)
Nur Dauer reicht nicht — die PDF soll die komplette Haltestellenliste zeigen. RAPTOR
muss pro Stop den **parent** speichern (mit welchem trip + Einstieg-Stop erreicht) und
nach Ziel-Erreichen den Pfad rückwärts rekonstruieren: je Segment alle Stops von
Einstieg bis Ausstieg → echte GTFS-Haltefolge (Trier→Konz→Saarburg→…→Saarbrücken).
Für Lesbarkeit `[von] + halteliste + [nach]` als Rahmen.
## PDF-Route: Pfad-Cache statt Live-RAPTOR (sonst 504)
Live-RAPTOR bei jedem PDF-Aufruf ist zu langsam (bis 200s → nginx 504 Gateway Timeout).
Lösung: **Pfad-Cache vorab bauen** (`pfade_cache.json`: key `von|nach` → seg + dauer_h)
und die PDF-Route liest nur JSON → PDF <1s.
⚠️ Cache auf die Kern-Ebenen (1+2) begrenzen: alle Paare wären ~7h Bauzeit, die
Kernmenge ~35min.
## Start ohne Bahnhof (Radevormwald) → Remap + Bus-Vorsatz
Ein Startort ohne Schienenanschluss hat KEINEN Stop im Feed → Routing fehlt für die
wichtigste Ebene 1. Lösung: auf nächstgelegenen Bahnhof remappen (Radevormwald →
Remscheid-Lennep Bf) und einen Bus-Vorsatz (~20min) als erstes "Segment" + zur Dauer
addieren. Solche Fälle explizit als `START_REMAP = {ort: (bahnhof, bus_min)}` führen,
sonst fehlt die Ebene-1-PDF komplett.
## Unsichere/absurde Fernzeiten → "prüfen", nie falsch anzeigen
Auch RAPTOR liefert auf manchen komplexen Fernstrecken falsche Werte (z.B. >10h, wenn
Routing fehlschlug; real Regional 6–9h). Ehrlich handeln: plausible Werte behalten,
unsichere (>10h / 0.0h / leer) als **`'prüfen'` mit Kategorie `unsicher (vor Fahrt
prüfen)`** markieren, und das Template zeigt „vor Fahrt prüfen" statt einer Zahl. Das
Template muss jede unsichere Kategorie in seiner Gruppen-Map führen, sonst
verschwinden die Zeilen still.
## Empirische Referenz-Anker (Plausibilitäts-Check, Regional only)
- Trier→Saarbrücken ~55–60min (RE 1 direkt)
- Köln→Aachen ~35–50min (RE 1/RE 9)
- Köln→Frankfurt regional ~2,5–3h MIT Umstiegen (~1,5h wäre nur ICE = NICHT korrekt)
- Radevormwald→Frankfurt ~5,5h (Bus + Remscheid-Lennep + Regional)
- Verifizieren mit diesen Ankern, NIE dem Algorithmus blind vertrauen.
skills/devops/web-hosting-deployment/references/gtfs-route-pdf-cache.md
+53
View File
@@ -0,0 +1,53 @@
# GTFS-Verbindungs-PDF: Offline-Precompute statt Live-Routing (2026-08-19)
Bewährt für `urlaub.perfekt-ohne-en.de` (Flask + SQLite + GTFS-Zugdaten). Wenn eine
Einzel-Verbindungs-PDF eine **komplette Fahrplan-Verbindung inkl. Haltestellenliste**
zeigen soll, darf die Flask-Route den Router/RAPTOR/Dijkstra **nicht bei jedem Request**
ausführen.
## Symptom
`wkhtmltopdf` + RAPTOR auf großen Knoten (Köln, Berlin) lief 40–200 s je Aufruf →
**nginx 504 Gateway Timeout** (Gateway-Zeitlimit überschritten). Nutzer meldete
„Wenn ich die PDF anklicke … keine Haltestellenliste".
## Fix: einmaliger Offline-Backfill → JSON-Cache → schneller Cache-Read
1. **Precompute-Skript** (`gtfs_pfade_cache.py`): iteriert `SELECT DISTINCT von,nach`
aus `urlaub.db`, ruft für jedes Paar `router.path(von,nach)` (liefert Segmentliste
der Zwischenhalte), schreibt `pfade_cache.json`:
```json
{"<von>|<nach>": {"seg": [["Halt1","Halt2",...]], "dauer_h": 1.5}}
```
2. **Flask-Route** liest NUR `json.load(open('/opt/<app>/pfade_cache.json'))` mit
Key `f"{start}|{ziel}"` → Antwort < 1 s, kein Timeout. **Nie** den Router zur
Laufzeit importieren/rechnen.
3. Skript als **Hintergrund-Job** (background=true, notify_on_complete) laufen lassen,
nicht foreground.
## Teilmenge wählen, sonst quadratische Backfill-Zeit
Eindeutige `von|nach` über ALLE Ebenen waren **10 510 Paare** → ~2,4 s/Paar = **~7 h**.
Auf die **Ebenen 1+2** (`WHERE ebene IN (1,2)`, ~1 979 Paare) beschränkt = **~35 min**.
Ebene-3 (Kleinstädte) = reine Verzweigung ohne eigene PDFs → weglassen.
- Trefferquote ist KEINE 100 % (Radevormwald/Kleinstädte ohne Bahnhof im Feed).
Template ehrlich auf „Keine GTFS-Haltestellenliste verfügbar" zurückfallen, nie erfinden.
## Pfad-Rekonstruktion muss dasselbe Abfahrtsprofil wie die Dauer nutzen
Ein Precompute mit **fester Abfahrtszeit (09:00)** rekonstruierte nur ~34 % der Pfade,
weil viele Verbindungen erst zu späteren Tageszeiten existieren. Die Dauer-Profile-Suche
(06–22 Uhr) liefert mehr Treffer — die Pfad-Rekonstruktion muss **dasselbe Profil**
durchlaufen statt fest 09:00, sonst bleibt die Trefferquote konsistent niedrig.
## Verifikation
```bash
# Service nach Template-/Code-Änderung neu starten, dann:
curl -sk -o /dev/null -w "PDF: %{http_code} (%{time_total}s)\n" \
"https://<sub>/pdf/<von>/<nach>"
# Erwartung: 200 in <1 s (nicht 504), Haltestellenliste enthalten sobald Cache da.
```
Flask läuft mit `debug=False` (systemd) → **nach Änderung IMMER `systemctl restart`**
(wg. Template-/Code-Reload-Pitfall, siehe Haupt-SKILL).
skills/devops/web-hosting-deployment/references/gtfs-routing-lessons.md
+66
View File
@@ -0,0 +1,66 @@
# GTFS-Verbindungssuche: RAPTOR real erprobt (2026-08-19)
Kontext: Webseite urlaub.perfekt-ohne-en.de (Zugsuche, nur Nahverkehr/kein ICE).
Nutzer stellte echte GTFS-Datei bereit (Regional/S-Bahn) — Verarbeitung brachte
mehrere harte Lektionen.
## Lektion 1: RAPTOR verbessert, aber ist KEINE fertige Lösung
Einfacher **Dijkstra** auf GTFS ist instabil bei grossen Knoten: benachbarte Ziele
ergaben absurde Differenzen (Mainz→Berlin 11h vs. Nachbar Wiesbaden 3h — unmoeglich).
**RAPTOR** (Round-Based) ist der richtige Algorithmus und verbessert die Konsistenz
(Mainz & Wiesbaden → Berlin wurden konsistent ~8h22).
**ABER:** RAPTOR erzeugt weiterhin einzelne absurde Fernwerte (z.B. Mainz→Berlin
~22h, real Regional ~7-9h; Trefferquote ~66-95%). Ein Algorithmus mit solcher
Einzelfehlerquote darf NICHT als finale Fahrzeit-Quelle ausgegeben werden.
**Praxisfix (Nutzer-Entscheidung „3 dann 1"):**
- **Option 3 (sofort):** nur *team-verifizierte* Kernzeiten konkret anzeigen
(Plausibilitaets-Anker: Trier→Saarbruecken ~1h, Koeln→Aachen ~50min, vom Team
bestaetigt). Alle anderen Verbindungen → `fahrzeit_h='pruefen'` in SQLite; Template
rendert stattdessen orangen Hinweis „vor Fahrt prüfen". NIE absurde/inkonsistente
Zahl als real stehen lassen.
- **Option 1 (danach):** robuste Suche erst auf die Seite schreiben, wenn JEDER Wert
separat gegen einen Plausibilitaets-Anker verifiziert ist.
## Lektion 2: Konsistenz-Check = Nachbar-Ziele gegeneinander pruefen
Der schnellste Fehlerdetektor: benachbarte Ziele vergleichen. Mainz→Berlin darf
nicht dramatisch von Wiesbaden→Berlin abweichen (gleiche geographische Lage).
Erst wenn das Cluster konsistent ist, Werte freigeben.
## Lektion 3: PDF-Haltestellenliste via VORAB-PFAD-CACHE
Nutzerwunsch: PDF soll die komplette Verbindung (`von → zwischenhalte → nach`) zeigen,
nicht nur Start/Ziel. On-the-fly-Routing bei jedem PDF-Aufruf ist zu langsam
(RAPTOR ~40-200s → nginx **504 Gateway Timeout**).
**Lösung:** Vorab einmalig Pfad-Cache bauen (`pfade_cache.json`), NUR die Kern-Ebenen
1+2 (~1.900 eindeutige `von|nach`-Paare; Ebene 3 = Kleinstaedte braucht keine eigenen
PDFs). PDF-Route liest `json.load(cache)[f"{start}|{ziel}"]["seg"]` → Ladezeit von
504 auf **~0,4s**. Wiederverwendbares Muster: Wenn On-the-fly-Berechnung zu langsam
ist, vorab einen Cache bauen und die Route daraus lesen.
- Template ergaenzt Start-Stadt als ersten + Ziel-Stadt als letzten Eintrag, damit
die Liste immer den Rahmen `von → ... → nach` bildet.
## Lektion 4: GTFS-Datenmodell-Fallen
- `stops.txt` Spaltenreihenfolge ist NICHT `stop_id,stop_name,...` — sie ist
`stop_name,parent_station,stop_id,stop_lat,stop_lon,...`. Beim Import die echte
stop_id aus den richtigen Spalten ziehen (parent_station ist oft die nutzbare ID).
- Ein Bahnhof hat **mehrere stop_ids** (Saarbruecken Hbf hat 6, nur je 1 aktiv in `st`;
Koeln Hbf hat 2). Geo-Merging (<350m) gruppiert sie; sonst matcht die Suche auf
eine tote ID und liefert „keine Verbindung".
- Zeit-Spalten: `HH:MM` ODER `HH:MM:SS` — to_sec() muss beides handhaben.
- COROS/Efa-Text-APIs liefern oft `\\n` als literalen Backslash-n statt echten
Zeilenumbruchen → vor dem Parsen `text.replace('\\n','\n')`.
## Performance-Falle bei Gesamt-Neuberechnung
Pro-Profile-Query (33 Abfahrtszeiten) × pro Verbindung ist zu teuer fuer ~12.000
Verbindungen (huubai 18h). Effizienter: **EIN Dijkstra/RAPTOR je eindeutiger
Start-Bahnhof (Ausbreitung zu allen Zielen in einem Lauf)** → ~250 Starts statt
12.000 × viele → von Stunden auf ~10min. Cache die Ausbreitung je Start und lese
die Ziel-Ankunft daraus ab.
skills/devops/web-hosting-deployment/references/gtfs-routing.md
+60
View File
@@ -0,0 +1,60 @@
# GTFS Echt-Fahrplan-Routing (Nahverkehr, kein ICE)
Erfahrungen aus urlaub.perfekt-ohne-en.de (3-Ebenen-Zugsuche, Nutzer lieferte
`r.und.s.bahnen.zip` = Regional + S-Bahn, Deutschlandticket-tauglich).
Ziel war: echte Fahrzeiten statt Luftlinien-Schätzung, max ~1h Abweichung.
## Modellierung & GTFS-Gotchas
- **stops.txt kann Spalten in unerwarteter Reihenfolge/CSV haben.** Hier war der
Header: `stop_name,parent_station,stop_id,stop_lat,stop_lon,...` und `parent_station`
ist die **echte ID**, `stop_id` die Sekundär-ID. Immer per Header/Index lösen,
nie fest annehmen — die Spaltenreihenfolge weicht von der GTFS-Konvention ab.
- **Ein Bahnhof = viele stop_ids, nur EINE aktiv in stop_times.** Beispiel:
"Saarbrücken Hbf" hat 6 IDs, "Köln Hbf" 2, nur jeweils 1 davon taucht in `st`
(den Routen) auf. Löse Stops über Geo-Cluster (<350 m) zu einer Gruppe zusammen
(`parent_station` nutzen, wenn befüllt).
- **Orte ohne Bahnhof** (Radevormwald) haben keine Trips → über den nächstgelegenen
Bahnhof (Remscheid-Lennep) routen + Bus-Vorsatz (20 min) als eigenes Hinweis-Segment.
- **Namens-Matching ist fragil:** DB-Name "Freiburg im Breisgau" ≠ GTFS
"Freiburg Hauptbahnhof". Robust: kleinsten gemeinsamen Teilstring + von den Kandidaten
den mit den meisten Trips (größter Stop) wählen.
## Algorithmus: RAPTOR statt Dijkstra
Einfacher **zeit-basierter Dijkstra ist bei großen Knoten instabil** und liefert
inkonsistente Zeiten (Mainz→Berlin 11h vs. Nachbar Wiesbaden 3h). Standard-Lösung:
**RAPTOR** (Round-Based) — erweitert Reichweite Runde um Runde über echte Trips.
Kern-Ablauf RAPTOR:
1. `earliest[stop] = dep0` an allen Start-Stops (eigene Anfangszeit, KEIN Umstiegsbuffer am Einstieg).
2. Je Runde: von markierten Stops alle abfahrenden Trips nach `earliest` nehmen,
entlangfahren, `earliest[sid]` verbessern.
3. Ziel erreicht → abbrechen; sonst neue markierte Menge = neue Runde.
4. **Umstiegsbuffer** (4 min) nur bei Umstieg > dep0, nicht am Start.
### Performance
- Pro-Paar-Routing mit 17–33 Profil-Abfahrtszeiten ist langsam (Sekunden bis Minuten).
- **2x Beschleunigung:** ein einziger "Ausbreitungs"-Dijkstra/RAPTOR je **Start-Bahnhof**
erreicht alle Ziele zugleich (5000 Paare in Minuten statt Stunden).
- **Pfad-Cache:** einmalig berechnete `(von|nach) -> Segmente` als JSON cachen
(`pfade_cache.json`), damit die Web-Route/PDF nur noch liest (0,5 s statt 504-Timeout).
## Pfad-Rekonstruktion für Haltestellenliste
RAPTOR so ertüchtigen, dass er `parent[stop] = (trip_id, einstieg_stop)` merkt und
rückwärts den kompletten Weg (alle Zwischenhalte je Zugsegment) aufbaut. Benötigt,
um in der PDF die vollständige Haltestellenliste zu zeigen (Nutzerwunsch: nicht nur
Start/Ziel, sondern alle Halte aus der GTFS-Datei).
## Fallstricke & Lektionen
- **Kein Vertrauen in eine einzige Verifikation:** Zeiten immer gegen 2–3 bekannte
Referenzstrecken prüfen (Trier→Saarbrücken ~1 h, Köln→Aachen ~50 min, Köln→Frankfurt
Regional ~2,5–3 h). "Skurrile" Werte (11 h für Nachbarstädte) deuten auf einen
Routing-/Auflösungs-Fehler, nicht auf echte Fahrzeit.
- **Fehlende/fehlerhafte Werte nicht erfinden,** sondern ehrlich als
"vor Fahrt prüfen" markieren. Eine Webseite mit "prüfen"-Labels ist besser als eine
mit falschen Zahlen (Ehrlichkeits-Regel, siehe deutsche-bahn-timetable-data.md).
- **Batch-Schreibroutinen:** erst validieren/löschen, dann neu einfügen (idempotent);
DB vor jedem Lauf sichern (Backup-Regel).
skills/devops/web-hosting-deployment/references/multi-site-pattern.md
+128
View File
@@ -0,0 +1,128 @@
# Multi-Site Pattern: Verlinkte Fitness/Calculator-Websites
Pattern aus Session 2026-07-12: Zwei zusammenhängende Single-Page-Apps auf Subdomains derselben Domain.
## Überblick
- **fitness.perfekt-ohne-en.de**: Makro-Rechner mit BMR, Aktivitätslevel, PDF-Export
- **kalorienrechner.perfekt-ohne-en.de**: Reiner Kalorienrechner mit Abnehm-Prognose
- Beide Sites per Cross-Link verbunden, **Daten werden beim Wechsel übergeben**
## Architektur
```
perfekt-ohne-en.de (Hauptdomain)
├── fitness.perfekt-ohne-en.de → /var/www/fitness.perfekt-ohne-en.de
└── kalorienrechner.perfekt-ohne-en.de → /var/www/kalorienrechner.perfekt-ohne-en.de
```
## Datenübergabe per URL-Parameter
Wenn der Nutzer auf Fitness Daten eingibt und dann zum Kalorienrechner wechselt, werden die Formularwerte als Query-String mitgegeben:
```javascript
// Auf der Quellseite:
function goToTarget(e) {
e.preventDefault();
const params = new URLSearchParams({
g: gender, // 'male'|'female'
w: weight.value, // kg
h: height.value, // cm
a: age.value,
act: activity.value, // activity factor
goal: goal.value // goal factor
});
window.location.href = 'https://target.example.de/?' + params.toString();
}
```
```html
<a href="#" onclick="goToTarget(event)">👉 Zur anderen Seite (mit Daten)</a>
```
Auf der Zielseite werden die Parameter beim Laden eingelesen und das Formular vorausgefüllt:
```javascript
(function(){
const p = new URLSearchParams(window.location.search);
if (p.get('w')) document.getElementById('weight').value = p.get('w');
if (p.get('h')) document.getElementById('height').value = p.get('h');
if (p.get('a')) document.getElementById('age').value = p.get('a');
if (p.get('g')) setGender(p.get('g'), ...);
if (p.get('act')) document.getElementById('activity').value = p.get('act');
if (p.get('goal')) document.getElementById('goal').value = p.get('goal');
// Auto-calculate if all data present
if (p.get('w') && p.get('h') && p.get('a')) calculate();
})();
```
**URL-Beispiel:**
```
https://kalorienrechner.perfekt-ohne-en.de/?g=male&w=80&h=178&a=30&act=1.375&goal=0.85
```
## PDF-Download (jsPDF)
Beide Sites nutzen jsPDF (CDN) für PDF-Export:
```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/2.5.1/jspdf.umd.min.js"></script>
```
**Minimale downloadPDF()-Funktion:**
```javascript
async function downloadPDF() {
if (typeof window.jspdf === 'undefined') return alert('PDF wird geladen...');
const { jsPDF } = window.jspdf;
const pdf = new jsPDF('p','mm','a4'), m = 20;
pdf.setFillColor(16,185,129); pdf.rect(0,0,210,15,'F');
pdf.setTextColor(255,255,255); pdf.setFontSize(14);
pdf.text('Titel', m, 12);
pdf.setTextColor(0,0,0); pdf.setFontSize(10);
// ... Daten einfügen ...
pdf.save('ergebnis.pdf');
}
```
**Pitfall:** `pdf.text()` existiert immer in jsPDF 2.x. Kein `typeof`-Check nötig!
## Sponsor-Coin (CSS-Animation)
Kleines drehendes Logo mit Link zur Sponsoren-Seite:
```css
.sponsor-coin { margin-bottom: 1rem; }
.coin-link { display: inline-flex; align-items: center; gap: 0.5rem; }
.coin-img {
width: 45px; height: 45px; border-radius: 50%;
animation: spinCoin 4s ease-in-out infinite;
filter: drop-shadow(0 2px 6px rgba(16,185,129,0.3));
}
.coin-link:hover .coin-img {
animation: spinCoin 0.6s ease-in-out infinite;
}
@keyframes spinCoin {
0% { transform: rotateY(0deg); }
50% { transform: rotateY(180deg); }
100% { transform: rotateY(360deg); }
}
```
```html
<div class="sponsor-coin">
<a href="https://sponsor.example.de" class="coin-link">
<img src="/assets/logo.png" alt="Sponsor" class="coin-img">
<span class="coin-text">Gesponsert von</span>
</a>
</div>
```
## Deployment-Checkliste
1. `mkdir -p /var/www/sub.example.de/{html,logs,assets}`
2. nginx VHost in `/etc/nginx/sites-available/` → `ln -sf` → `sites-enabled/`
3. `nginx -t && systemctl reload nginx`
4. HTML-Dateien erstellen → **SOFORT**: `chown www-data:www-data && chmod 644`
5. Assets (Logos) kopieren → `chown www-data:www-data`
6. `certbot --nginx -d sub.example.de --non-interactive --agree-tos --email admin@... --redirect`
7. Lokal testen: `curl -s -H "Host: sub.example.de" http://localhost/ | grep '<title>'`
skills/devops/web-hosting-deployment/references/static-data-site-pdf.md
+39
View File
@@ -0,0 +1,39 @@
# Statische, datengetriebene Website mit PDF-Download je Eintrag (2026-08-08)
Muster für eine statische Status-/Listen-Seite auf einer Subdomain, die aus einem
JSON-Datensatz rendert und **pro Eintrag ein PDF** zum Download anbietet
(wkhtmltopdf, kein PHP/Python-Backend nötig). Beispiel: Zugverbindungs-Liste mit
je-Ziel-PDF (urlaub.perfekt-ohne-en.de).
## Bausteine
1. **Datenquelle**: eine `daten.json` im Webroot (Liste von Objekten mit den
anzuzeigenden Feldern + Fahrtzeit + Kategorie + Weg).
2. **`index.html`**: lädt `daten.json` per `fetch`, gruppiert nach Kategorie
(z.B. Kernziel / über-7h / Fernzone) und rendert Tabellen mit
`<a href="pdf/<slug>.pdf">⬇ PDF</a>`-Buttons.
Slug-Funktion: lowercase + NFD-normalisieren + Umlaute streifen + `[^a-z0-9]`→`-`.
3. **PDF-Generator** (`/usr/local/bin/<projekt>-pdf.sh`):
- Python-Schleife: liest `daten.json`, baut je Eintrag eine temporäre HTML-Datei
in `/tmp/<projekt>-html/`, schreibt nach `/var/www/<sub>/pdf/<slug>.pdf`.
- `wkhtmltopdf --quiet --enable-local-file-access "$html" "$pdf"`.
- Danach `chown -R www-data:www-data <webroot>` (write_file erzeugt root:root).
- Glob-Sicherheit bei leeren Verzeichnissen: `rm -rf /tmp/.../*` vorher oder
`shopt -s nullglob` (vgl. `set -euo pipefail`).
## Pitfalls
- **`write_file` weigert sich auf `/etc/nginx/...`** (sensitiver Systempfad).
Ersatz: Inhalt nach `/tmp/<datei>` schreiben, dann `cp /tmp/<datei> /etc/nginx/...`.
- **PDF nicht roh per `grep` prüfbar**: wkhtmltopdf komprimiert den Text. Statt
Text-Suche lieber (a) Größe (KB) + valides `%%EOF`-Ende prüfen, oder
(b) PDF im Browser öffnen (Browserbase rendert es im PDF-Viewer) als visueller Beweis.
## Verifikation (end-to-end)
```bash
for f in /var/www/<sub>/pdf/*.pdf; do
curl -sk -o /dev/null -w "%{http_code}\n" "https://<sub>.perfekt-ohne-en.de/pdf/$(basename "$f")"
done
# Alle 200 => PDFs OK. Zusätztlich index.html + daten.json auf 200 prüfen.
```
skills/devops/zerotier-mesh-join/SKILL.md
+118
View File
@@ -0,0 +1,118 @@
---
name: zerotier-mesh-join
description: >-
ZeroTier Mesh-Client für neue Agenten (SwitchHermes, LaptopHermes, Agent B).
Richtet ZeroTier ein, joint dem Mesh 6ab565387a75e498,
konfiguriert den Ollama-Zugriff auf Agent A (172.24.196.119:11434).
Einmalig ausführen auf jedem neuen Agenten.
---
# ZeroTier Mesh Join
Einmaliger Setup-Skill für neue Agenten im Multi-Agent-Mesh.
## 1. ZeroTier installieren
```bash
curl -s https://install.zerotier.com | sudo bash
```
## 2. Netzwerk joinen
```bash
sudo zerotier-cli join 6ab565387a75e498
Dann im [ZeroTier Dashboard](https://my.zerotier.com) authorisieren (Netzwerk-ID: `6ab565387a75e498`).
## 3. Verbindung prüfen
```bash
zerotier-cli listnetworks
# → Erwartet: OK, 6ab565387a75e498, Access: OK
zerotier-cli peers
# → Agent A sollte als Peer erscheinen (172.24.196.119)
```
## 4. Zugriff auf lokales Ollama testen
Alle Agenten erreichen das lokale Ollama auf Agent A nur über ZeroTier:
```bash
curl -s http://172.24.196.119:11434/api/tags | head -5
# → Sollte deepseek-r1:7b, deepseek-r1:14b, nomic-embed-text zeigen
```
## 5. Hermes-Ollama-Provider konfigurieren
In `~/.hermes/config.yaml`:
```yaml
providers:
custom:
api_key: ollama
base_url: http://172.24.196.119:11434/v1
```
Damit kann Hermes direkt das lokale Ollama auf dem VPS nutzen.
## 6. Hermes CLI in PATH (falls `hermes` nicht gefunden wird)
Auf Source-Installationen liegt der Binary in `~/.hermes/hermes-agent/hermes`:
```bash
echo 'export PATH="$HOME/.hermes/hermes-agent:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Prüfen:
hermes --version
```
## 7. Sudo für Remote-Management durch Agent A
Wenn Agent A per SSH auf diesem Agenten arbeiten soll (Skills syncen, Config editieren):
**Option A — Passwordless sudo (empfohlen):**
```bash
echo 'mehlzoerwer ALL=(ALL) NOPASSWD: ALL' | sudo tee /etc/sudoers.d/mehlzoerwer
```
**Option B — SUDO_PASSWORD in .env (tirith-sicher):**
```bash
echo 'SUDO_PASSWORD=Bp3lskt0' >> ~/.hermes/.env
```
⚠️ `sudo -S` via stdin wird von tirith blockiert — nur .env oder passwordless sudo funktionieren.
## Netzwerk-Übersicht
| Agent | ZT-IP | Node-ID | Rolle |
|-------|-------|---------|-------|
| A (VPS) | `172.24.196.119` | `adccde5dd6` | Hub, Ollama-Server |
| B | TBD | TBD | Entwickler (ZorinOS 18) |
| SwitchHermes | `172.24.20.26` | `3c1d63bbed` | Cockpit (ARM64, Nintendo Switch) |
| LaptopHermes | `172.24.178.202` | `94334e18df` | Worker (RTX 2060) |
| Handy | `172.24.92.162` | `e39b118b68` | Controller (Android) |
## Firewall-Hinweis
Ollama auf Agent A ist NUR via ZeroTier erreichbar (`172.24.0.0/16:11434`).
Port 11434 ist **nicht** vom Internet aus erreichbar.
## Migration von altem Netzwerk
Falls ein Agent noch im alten Netzwerk (`b9a18a606fb05ae6`) hängt:
```bash
# Neues Netz joinen (zuerst!)
sudo zerotier-cli join 6ab565387a75e498
# Im Dashboard authorisieren (my.zerotier.com)
# Altes Netz erst verlassen, wenn neues aktiv ist
sudo zerotier-cli leave b9a18a606fb05ae6
```
Danach alle IP-Referenzen updaten:
| Alt | Neu |
|-----|-----|
| `10.36.223.x` → | `172.24.196.x` |
| `10.36.223.0/24` → | `172.24.0.0/16` |
| `b9a18a606fb05ae6` → | `6ab565387a75e498` |
Betrifft: Ollama-Service, UFW-Regeln, duo_state.json, Hermes-Config, Skills.
skills/devops/zerotier-mesh-join/scripts/setup-zerotier-mesh.sh
+59
View File
@@ -0,0 +1,59 @@
#!/bin/bash
# ZeroTier Mesh Join — One-Shot Setup
# Verwendung: auf neuem Agenten ausführen
# curl -s http://172.24.196.119:8000/setup.sh | bash
set -e
echo "=== ZeroTier Mesh Join ==="
# 1. ZeroTier installieren
if ! command -v zerotier-cli &>/dev/null; then
echo "→ Installiere ZeroTier..."
curl -s https://install.zerotier.com | sudo bash
fi
# 2. Netzwerk joinen
echo "→ Joine Netzwerk 6ab565387a75e498..."
sudo zerotier-cli join 6ab565387a75e498
echo "→ Node-ID: $(zerotier-cli status | awk '{print $4}')"
echo "→ Bitte im Dashboard authorisieren: https://my.zerotier.com"
echo ""
# 3. Warte auf Authorisierung
for i in $(seq 1 30); do
STATUS=$(zerotier-cli listnetworks 2>/dev/null | grep 6ab565387a75e498 | awk '{print $6}')
if [ "$STATUS" = "OK" ]; then
IP=$(zerotier-cli listnetworks | grep 6ab565387a75e498 | awk '{print $NF}')
echo "✅ Authorisiert! IP: $IP"
break
fi
sleep 2
done
# 4. Ollama testen
echo "→ Teste Ollama auf Agent A..."
curl -s --max-time 5 http://172.24.196.119:11434/api/tags | python3 -c "import sys,json; d=json.load(sys.stdin); print('✅ Ollama erreichbar:', [m['name'] for m in d['models']])" 2>/dev/null || echo "⚠️ Ollama nicht erreichbar"
# 5. Hermes Provider konfigurieren
if [ -f ~/.hermes/config.yaml ]; then
if ! grep -q "172.24.196.119" ~/.hermes/config.yaml; then
echo "→ Füge Ollama-Provider zu Hermes hinzu..."
cat >> ~/.hermes/config.yaml << 'EOF'
providers:
custom:
api_key: ollama
base_url: http://172.24.196.119:11434/v1
EOF
fi
fi
# 6. Hermes PATH fix
if ! command -v hermes &>/dev/null && [ -f ~/.hermes/hermes-agent/hermes ]; then
echo 'export PATH="$HOME/.hermes/hermes-agent:$PATH"' >> ~/.bashrc
echo "→ Hermes zum PATH hinzugefügt (nach relogin aktiv)"
fi
echo ""
echo "=== Fertig! Agent bereit im Mesh. ==="