Initial: Mesh-Skills, Configs, Scripts
This commit is contained in:
root
@@ -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-*`.
|
||||
Reference in New Issue
Block a user