diff --git a/BEDIENUNGSANLEITUNG.md b/BEDIENUNGSANLEITUNG.md index 9279e55..08e202a 100644 --- a/BEDIENUNGSANLEITUNG.md +++ b/BEDIENUNGSANLEITUNG.md @@ -16,9 +16,10 @@ einfache Slash-Kommandos in der pi-Agent-Oberfläche. 6. [Automatischer Workflow: /optimize](#6-automatischer-workflow-optimize) 7. [Kleine Änderungen: /patch und /quick_check](#7-kleine-änderungen-patch-und-quick_check) 8. [Dokumentation generieren: /update_doku](#8-dokumentation-generieren-update_doku) -9. [TASK.md verstehen und nutzen](#9-taskmd-verstehen-und-nutzen) -10. [Typische Anwendungsfälle](#10-typische-anwendungsfälle) -11. [Fehlermeldungen und Lösungen](#11-fehlermeldungen-und-lösungen) +9. [Versionsverwaltung: /version](#9-versionsverwaltung-version) +10. [TASK.md verstehen und nutzen](#10-taskmd-verstehen-und-nutzen) +11. [Typische Anwendungsfälle](#11-typische-anwendungsfälle) +12. [Fehlermeldungen und Lösungen](#12-fehlermeldungen-und-lösungen) --- @@ -303,8 +304,12 @@ Phase 4: Runde 2/3: Judge prüft... ✓ PASS WITH CONCERNS nach Runde 2 Finale ShipIt-Prüfung... → SHIP +[Dialog: Version → v0.1.0 (empfohlen)] ``` +Während des Ablaufs zeigt die Statuszeile immer die aktuelle Aktivität: +`Coder implementiert…` → `Editiere src/main.rs…` → `Git-Commit…` → `Judge reviewt (Runde 1/3)…` + ### Beispiel: mehr Runden ``` @@ -476,7 +481,79 @@ Führt nach SHIP automatisch `/update_doku` aus. --- -## 9. TASK.md verstehen und nutzen +## 9. Versionsverwaltung: /version + +pi_coder verwaltet Versionsnummern im SemVer-Format (`vMAJOR.MINOR.PATCH`) automatisch — +basierend auf den Commit-Messages des generierten Codes. + +### Wie Commit-Messages die Version bestimmen + +Der Coder verwendet standardmäßig das Conventional-Commits-Format: + +| Commit-Prefix | Beispiel | Bump-Typ | +|---|---|---| +| `feat!:` oder `BREAKING CHANGE` | `feat!: API komplett überarbeitet` | major (v1.0.0 → v2.0.0) | +| `feat:` | `feat: CSV-Export hinzugefügt` | minor (v1.0.0 → v1.1.0) | +| `fix:`, `chore:`, andere | `fix: Crash bei leerer Datei` | patch (v1.0.0 → v1.0.1) | + +### Automatisch nach SHIP + +Nach einem erfolgreichen SHIP-Verdikt in `/optimize` oder `/shipit` erscheint automatisch +ein Dialog: + +``` +┌─ Version ──────────────────────────────────────────────┐ +│ Aktuelle Version: v1.2.3. Commits seit letztem Tag: │ +│ minor-Bump erkannt. │ +│ │ +│ patch → v1.2.4 │ +│ minor → v1.3.0 (empfohlen) │ +│ major → v2.0.0 │ +│ Überspringen │ +└─────────────────────────────────────────────────────────┘ +``` + +Du kannst den empfohlenen Wert bestätigen oder manuell einen anderen wählen. + +### Manuell aufrufen + +``` +/version +``` + +Nützlich wenn du den Tag nachträglich setzen möchtest oder nach manuellen Commits. + +### Was passiert nach der Auswahl + +1. Die Versionsnummer wird in die Projekt-Manifest-Datei geschrieben (falls vorhanden): + - `package.json` → `npm version --no-git-tag-version X.Y.Z` + - `Cargo.toml` → `version = "X.Y.Z"` in `[package]` + - `pyproject.toml` → `version = "X.Y.Z"` in `[project]` + - `VERSION` → Dateiinhalt `vX.Y.Z` +2. Commit: `chore: bump version to vX.Y.Z` +3. Git-Tag: `vX.Y.Z` wird gesetzt + +Wenn keine der genannten Dateien vorhanden ist, wird nur der Git-Tag gesetzt. + +### Erstes Mal — kein Tag vorhanden + +``` +┌─ Version ──────────────────────────────────────────────┐ +│ Noch kein Versions-Tag vorhanden. │ +│ │ +│ patch → v0.0.1 │ +│ minor → v0.1.0 (empfohlen) │ +│ major → v1.0.0 │ +│ Überspringen │ +└─────────────────────────────────────────────────────────┘ +``` + +Empfehlung: `v0.1.0` für ein frisches, funktionierendes Projekt; `v1.0.0` wenn es +sofort produktionsreif ist. + +--- + +## 10. TASK.md verstehen und nutzen `TASK.md` ist die persistente Aufgabenbeschreibung im Projektverzeichnis. Sie wird von allen Kommandos als Referenz gelesen. @@ -534,7 +611,7 @@ Die Checkboxen werden automatisch abgehakt: --- -## 10. Typische Anwendungsfälle +## 11. Typische Anwendungsfälle ### Neues Rust-Programm von Null @@ -566,6 +643,17 @@ Die Checkboxen werden automatisch abgehakt: /quick_check ``` +### Versionsnummer nach der Entwicklung setzen + +```bash +# Nach SHIP: Dialog erscheint automatisch +/optimize Neues Feature X --rounds 2 +# → SHIP → Dialog → "minor → v1.1.0" wählen → Tag gesetzt + +# Oder manuell: +/version +``` + ### Kommentarlosen Legacy-Code dokumentieren ```bash @@ -592,7 +680,7 @@ Die Checkboxen werden automatisch abgehakt: --- -## 11. Fehlermeldungen und Lösungen +## 12. Fehlermeldungen und Lösungen ### "Modell-Datei nicht gefunden" diff --git a/README.md b/README.md index f3aa255..7e88eed 100644 --- a/README.md +++ b/README.md @@ -130,8 +130,8 @@ und dann neu gestartet — ein laufender Inference-Request wird dabei abgebroche | `-ngl 999` | — | Alle Layer auf die GPU laden (999 = „alle"). Bei zu wenig VRAM reduzieren. | | `-fa on` | — | Flash Attention — schnellere Attention-Berechnung, weniger VRAM für den Attention-Pass. | | `--kv-unified` | — | Einheitlicher KV-Cache über alle Schichten. Effizienter bei langen Kontexten. | -| `--cache-type-k q8_0` | — | KV-Cache Keys in 8-Bit quantisiert. Spart ~50 % VRAM gegenüber fp16, minimaler Qualitätsverlust. | -| `--cache-type-v q8_0` | — | KV-Cache Values ebenfalls 8-Bit quantisiert. | +| `--cache-type-k q4_0` | — | KV-Cache Keys in 4-Bit quantisiert. Spart ~75 % VRAM gegenüber fp16 — nötig für 256K Kontext auf 2× 24 GB. | +| `--cache-type-v q4_0` | — | KV-Cache Values ebenfalls 4-Bit quantisiert. | | `--cont-batching` | — | Continuous Batching: neue Anfragen werden in laufende Batches eingefügt — höherer Durchsatz bei mehreren parallelen Anfragen. | | `--main-gpu 0` | — | GPU-Index (0 = erste der übergebenen GPUs) für Nicht-Tensor-Operationen. | | `--tensor-split 0.5,0.5` | — | Modell-Gewichte 50/50 auf zwei GPUs aufteilen. | @@ -141,7 +141,7 @@ und dann neu gestartet — ein laufender Inference-Request wird dabei abgebroche | Parameter | Wert | Erklärung / Wirkung | |---|---|---| -| `-c 131072` | 128K Tokens | Großes Kontextfenster: gesamte Codebasis + Gesprächsverlauf passt rein. **Hoher VRAM-Bedarf.** Reduziere auf `65536` wenn VRAM knapp. | +| `-c 262144` | 256K Tokens | Sehr großes Kontextfenster: gesamte Codebasis + langer Gesprächsverlauf passt rein. **Sehr hoher VRAM-Bedarf.** Reduziere auf `65536` wenn VRAM knapp. | | `-n 16384` | 16K Tokens | Maximale Ausgabelänge pro Anfrage. Für Kommentieraufgaben (`/update_doku`) nötig. | | `--temp 0.2` | — | Niedrige Temperatur: deterministisch, konsistenter Code. Erhöhe auf `0.4–0.6` für kreativere Lösungsansätze. | | `--top-p 0.95` | — | Nucleus Sampling: 95 % der Wahrscheinlichkeitsmasse. Passend zu temp 0.2. | @@ -153,8 +153,8 @@ und dann neu gestartet — ein laufender Inference-Request wird dabei abgebroche | Parameter | Wert | Erklärung / Wirkung | |---|---|---| -| `-c 131072` | 128K Tokens | Großes Kontextfenster: nötig bei langen /optimize-Runden, wo der Gesprächsverlauf stark anwächst. | -| `-n 8192` | 8K Tokens | Reviews müssen nicht länger sein. Spart Inferenz-Zeit. | +| `-c 262144` | 256K Tokens | Großes Kontextfenster: nötig bei langen /optimize-Runden, wo der Gesprächsverlauf stark anwächst. | +| `-n 16384` | 16K Tokens | Lange Reviews und Begründungen passen vollständig in die Ausgabe. | | `--temp 0.1` | — | Sehr niedrige Temperatur: maximale Konsistenz und Reproduzierbarkeit der Urteile. | | `--top-p 0.9` | — | Etwas enger als beim Coder — weniger Variation im Urteil gewünscht. | | `--batch-size 512` | — | Kleiner als beim Coder — Judge bekommt selten sehr lange Prompts. | @@ -236,19 +236,20 @@ Faustregel: KV-Cache ≈ `context_size × layers × head_dim × 2 × bytes_per_e Bei q8_0 (1 Byte/Element) und Qwen3-27B (28 Schichten, 128 Head-Dim, 32 Heads): KV-Cache ≈ `context_size × 28 × 128 × 32 × 2 × 1 Byte ≈ context_size × 0,23 MB` -| Kontext | KV-Cache (q8_0) | Empfehlung | +| Kontext | KV-Cache (q4_0) | Empfehlung | |---|---|---| -| 32 768 | ~7,5 GB | 1 × 24-GB-GPU | -| 65 536 | ~15 GB | 2 × 16-GB-GPU | -| 131 072 | ~30 GB | 2 × 24-GB-GPU | +| 32 768 | ~1,9 GB | 1 × 16-GB-GPU | +| 65 536 | ~3,7 GB | 1 × 24-GB-GPU | +| 131 072 | ~7,5 GB | 2 × 16-GB-GPU | +| 262 144 | ~15 GB | 2 × 24-GB-GPU — **aktuell gesetzt** | ### KV-Cache-Quantisierung | `--cache-type-k/v` | VRAM | Qualität | |---|---|---| | `f16` | 100 % (Basis) | Referenz | -| `q8_0` | ~50 % | Kaum merklich schlechter — **empfohlen** | -| `q4_0` | ~25 % | Sichtbarer Qualitätsverlust bei langen Kontexten | +| `q8_0` | ~50 % | Kaum merklich schlechter | +| `q4_0` | ~25 % | Merklicher Qualitätsverlust bei langen Kontexten — aber nötig für 256K Kontext auf 2× 24 GB. **Aktuell gesetzt.** | ### Parallelität (`--parallel`) @@ -282,11 +283,32 @@ wenn pi agent Folgeanfragen schnell hintereinander schickt. | `/judge [fokus]` | Judge | Code-Review gegen TASK.md + letzten Commit | | `/fix [hinweis]` | Coder | Judge-Kritik beheben, committen | | `/shipit` | Judge | Finale Freigabeprüfung | -| `/optimize [--rounds N] [--with-doku]` | beide | Vollautomatische Schleife bis PASS | -| `/optimize --continue [--rounds N] [--with-doku]` | beide | Judge→Fix-Schleife ab aktuellem Stand (überspringt Implementierung) | +| `/optimize [--rounds N] [--with-doku] [--continue]` | beide | Vollautomatische Schleife bis PASS | +| `/optimize ... [--test-cmd "cmd"] [--test-timeout N]` | beide | Externe Test-Suite im Loop ausführen | | `/patch <änderung>` | Coder | Gezielte Minimaländerung ohne Review | | `/quick_check [was]` | Judge | Schnelle Prüfung der letzten Änderung | +| `/version` | — | Versionsnummer erhöhen (SemVer + Git-Tag) | | `/update_doku` | Coder | Code kommentieren + README + Bedienungsanleitung | +| `/plan ` | Coder | Implementierungsplan in PLAN.md (kein Code) | +| `/continue` | Coder | Unterbrochenen Prozess fortsetzen | +| `/cancel` | — | Laufenden Loop nach aktuellem Schritt abbrechen | | `/new_project ` | — | Neues Projektverzeichnis + git init | Ausführliche Beschreibung aller Kommandos mit Beispielen: siehe **BEDIENUNGSANLEITUNG.md**. + +--- + +## Live-Aktivitätsstatus + +Während der Ausführung zeigt pi_coder in der Statuszeile, was gerade passiert: + +| Situation | Anzeige | +|---|---| +| Coder implementiert | `Coder implementiert…` | +| edit-Tool aktiv | `Editiere src/main.py…` | +| git commit | `Git-Commit…` | +| Judge reviewt (Runde 2/3) | `Judge reviewt (Runde 2/3)…` | +| Tests laufen | `Tests laufen…` | +| Fix-Phase | `Coder fixt Blocker…` | + +So ist jederzeit erkennbar, in welcher Phase sich der automatische Loop befindet.