docs: Betriebshandbuch (Skill-Lebenszyklus, Hermes, Pflege, Dry-Run, Rollback)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5.5
@@ -18,7 +18,10 @@ Anfrage → n8n → Router-Service ──▶ Stufe 3 Embedding-Classifier (CPU)
|
||||
| [docs/PLAN.md](docs/PLAN.md) | Architektur und Betrieb: Proxmox, Pflege, Autohealing, Lifecycle, Finetuning, Problemerkennung, Portabilität |
|
||||
| [docs/adr/](docs/adr/) | Architekturentscheidungen |
|
||||
| [docs/spec/](docs/spec/) | Spezifikationen der Komponenten |
|
||||
| [docs/IMPLEMENTATION.md](docs/IMPLEMENTATION.md) | Arbeitspakete, Teststrategie, Ablauf des Deployments |
|
||||
| [docs/IMPLEMENTATION.md](docs/IMPLEMENTATION.md) | Arbeitspakete, Teststrategie, Stand der Verifikation, Ablauf des Deployments |
|
||||
| [docs/BETRIEB.md](docs/BETRIEB.md) | Skill-Lebenszyklus, Rolle von Hermes, Pflege per Prompt, Dry-Run aufheben, Rollback |
|
||||
| [n8n/README.md](n8n/README.md) | Workflows und Import |
|
||||
| [platform/proxmox/README.md](platform/proxmox/README.md) | Proxmox-Ablauf (OpenTofu + Ansible) |
|
||||
|
||||
## Repo-Struktur
|
||||
|
||||
@@ -39,7 +42,8 @@ sites/knaster/ standortspezifisch: Inventar, Registry
|
||||
make dev # venv + Abhängigkeiten
|
||||
make test # Unit- und Integrationstests
|
||||
make lint # ruff
|
||||
make validate # Compose-, Workflow- und Konfigurationsprüfung
|
||||
make validate # Konsistenz Registry/Skills/LiteLLM/Healer/Policy/Katalog + Placement
|
||||
make compose-check # docker compose config für alle Rollen
|
||||
```
|
||||
|
||||
Alle Aktionen gegen Infrastruktur laufen standardmäßig im **Dry-Run** (`KNASTER_DRY_RUN=true`).
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
# Betrieb: Skill-Lebenszyklus, Hermes, Pflege, Freischaltung
|
||||
|
||||
## 1. Lebenszyklus eines Skills
|
||||
|
||||
```
|
||||
Hermes schreibt SKILL.md
|
||||
│
|
||||
draft ──(Mensch/Agent: aktivieren)──▶ active, Stufe 0
|
||||
│ läuft auf dem starken Modell mit Skill-Text,
|
||||
│ sammelt verifizierte Fälle
|
||||
Service-Routine: stabil ≥ 95 % ────┤
|
||||
▼
|
||||
request_graduation (Freigabe)
|
||||
│ Hermes erzeugt Varianten →
|
||||
│ POST /v1/skills/{name}/graduate
|
||||
▼
|
||||
promote_skill (Freigabe) ──▶ active, Stufe 1 (schwaches Modell)
|
||||
│
|
||||
Drift (Pass-Rate < 80 %) ──▶ demote_skill (automatisch) ──▶ demoted (Stufe 0)
|
||||
│
|
||||
≥ 300 Trainingsfälle, Stufe-1-Rate < 90 % ─▶ train_adapter (Freigabe) ──▶ Lifecycle-Pipeline
|
||||
```
|
||||
|
||||
Stufe 2 (Programm) und Stufe 3 (Classifier) gibt es, wenn der Skill `execution: program|classifier` deklariert und die passende Stufe freigegeben ist. Programme liegen in `knaster/programs.py` und gehen wie normaler Code durch ein Review. Classifier entstehen aus gelabelten Fällen (`EmbeddingClassifier.train`) und liegen unter `config/classifiers/<name>.json`.
|
||||
|
||||
## 2. Rolle von Hermes
|
||||
|
||||
Hermes läuft als Skill-Autor mit dem starken Modell. Er zeigt auf LiteLLM, Alias `tier0-strong`. Hermes steht **nicht** im Pfad jeder Anfrage.
|
||||
|
||||
| Auslöser | Hermes tut | Schnittstelle |
|
||||
|---|---|---|
|
||||
| Job `graduate_skill` (über n8n `knaster-jobs`) | 10–30 realistische Varianten erzeugen, Graduierung aufrufen. Schlägt sie fehl, den Skill anhand von `failures` überarbeiten | `POST /v1/skills/{name}/graduate` |
|
||||
| Job `merge_skills` | zwei Skills zu einem zusammenführen, alten Skill auf `retired` setzen | Git-Commit in `skills/`, dann `POST /v1/skills/reload` |
|
||||
| Neue Aufgabenklasse (häufige `no_skill`-Fälle) | neuen `SKILL.md`-Entwurf schreiben (`status: draft`) | Git-Commit + Reload |
|
||||
|
||||
Skills sind Dateien im Repo. Jede Änderung ist dadurch ein nachvollziehbarer Commit und lässt sich zurückdrehen.
|
||||
|
||||
## 3. Pflege per Prompt (Beispiele)
|
||||
|
||||
```
|
||||
> routine
|
||||
Service-Routine
|
||||
Befunde:
|
||||
- Drift: zusammenfassung Pass-Rate 72% (n=40)
|
||||
Automatisch erledigt:
|
||||
- P-12: Skill zusammenfassung auf Stufe 0 zurückstufen → Skill zusammenfassung auf Stufe 0 zurückgestuft
|
||||
Offene Vorschläge (genehmige P-x / lehne P-x ab):
|
||||
- P-13 [low] LoRA-Adapter für rechnungen trainieren – 412 verifizierte Fälle, Stufe-1-Rate 86%
|
||||
|
||||
> genehmige P-13
|
||||
P-13 executed: Kandidat 7f3e… (adapter) angelegt und Build gestartet
|
||||
|
||||
> wechsle tier1-general auf qwen3-32b-awq
|
||||
Vorschlag P-14 [medium] Basismodell von tier1-general auf qwen3-32b-awq wechseln …
|
||||
Bestätige mit „genehmige P-14“.
|
||||
```
|
||||
|
||||
Freitext, der keinem Befehl entspricht, bildet ein kleines Modell auf einen Befehl ab. Der Agent fragt dann mit „Meinst du …?“ zurück.
|
||||
|
||||
## 4. Dry-Run aufheben (schrittweise)
|
||||
|
||||
1. Eine Woche mit `KNASTER_DRY_RUN=true` laufen lassen. Die Healer-Ergebnisse stehen als `[dry-run] …` in den Antworten bzw. Logs.
|
||||
2. `KNASTER_DRY_RUN=false` setzen. Interne Aktionen (Slot-Status, Skill-Stufen, Kandidaten) liefen schon vorher. Jetzt werden auch Jobs per Webhook verschickt.
|
||||
3. Infrastruktur-Aktionen einzeln freischalten, über `config/healer-rules.yaml` → `enabled_actions: [restart_container]`, später `restart_vm`. `reboot_host` bleibt freigabepflichtig (Policy) und läuft nur im Wartungsfenster.
|
||||
|
||||
## 5. Rollback-Wege
|
||||
|
||||
| Was | Wie |
|
||||
|---|---|
|
||||
| Adapter/Basismodell | Prompt `rollback <slot>` → Freigabe |
|
||||
| Skill-Stufe | Prompt `stufe <skill> zurück` bzw. Git-Revert der SKILL.md |
|
||||
| Treiber/Engine | Proxmox-Snapshot der GPU-VM (vor jedem Update anlegen) |
|
||||
| Konfiguration | Git-Revert und Neustart des Router-Containers |
|
||||
Reference in New Issue
Block a user