docs: pi-Doku zusammengeführt, FUNKTIONSWEISE/CHANGELOG/LICENSE; mcp.json versioniert und verlinkt
Hinweise zu pi und der Coder/Judge-Erweiterung (MCP-Server, Web-Tests, schneller entwickeln, Fehlerbilder) aus strata-betrieb übernommen. Kapitel 2/3 und README auf Strata als Standard gebracht. deploy-pi-config.sh verlinkt jetzt auch mcp.json. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
9647b862c9
commit
e1796c0ccc
1 changed files with 411 additions and 131 deletions
|
|
@ -9,17 +9,19 @@ einsetzt, um Software automatisch zu schreiben, zu prüfen und zu verbessern —
|
|||
## Inhaltsverzeichnis
|
||||
|
||||
1. [Konzept: Coder und Judge](#1-konzept-coder-und-judge)
|
||||
2. [Vorbereitung](#2-vorbereitung)
|
||||
3. [Server starten und stoppen](#3-server-starten-und-stoppen)
|
||||
2. [Vorbereitung](#2-vorbereitung) (Modell wählen, Einrichten, pi aktualisieren)
|
||||
3. [Alternative: llama.cpp-Server (:8001)](#3-alternative-llamacpp-server-8001)
|
||||
4. [Neues Projekt anlegen](#4-neues-projekt-anlegen)
|
||||
5. [Manueller Workflow: /coder → /judge → /fix → /shipit](#5-manueller-workflow)
|
||||
6. [Automatischer Workflow: /optimize](#6-automatischer-workflow-optimize) (inkl. [Interactive-Modus](#interactive-modus))
|
||||
6. [Automatischer Workflow: /optimize](#6-automatischer-workflow-optimize) (inkl. [Schneller entwickeln](#schneller-entwickeln), [Interactive-Modus](#interactive-modus))
|
||||
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. [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)
|
||||
11. [Werkzeuge für pi: MCP-Server](#11-werkzeuge-für-pi-mcp-server)
|
||||
12. [Web-Anwendungen testen](#12-web-anwendungen-testen)
|
||||
13. [Typische Anwendungsfälle](#13-typische-anwendungsfälle)
|
||||
14. [Fehlermeldungen und Lösungen](#14-fehlermeldungen-und-lösungen)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -57,47 +59,67 @@ der Judge kritisiert direkt und konkret, der Coder repariert ohne Widerspruch.
|
|||
|
||||
## 2. Vorbereitung
|
||||
|
||||
### Server starten
|
||||
### Modell wählen
|
||||
|
||||
Coder und Judge sind **ein** Modell. Standard ist `strata/qwen3.8-flash-next-iq3_s`, der lokale Strata-Server auf
|
||||
`127.0.0.1:9090`. Seinen Betrieb (Start, GPU-Freigabe, Entladen nach 10 Minuten, Bilder) beschreibt
|
||||
`~/nvme2n1p7_home/strata-betrieb/BEDIENUNGSANLEITUNG.md`. Ist das Modell entladen, lädt Strata es bei der ersten
|
||||
Anfrage; die Bereitschaftsprüfung der Extension wartet darauf bis zu 3 Minuten.
|
||||
|
||||
Ein anderes Modell aus `models.json` setzt die Umgebungsvariable `PI_CODER_MODEL=<provider>/<id>` beim Start von pi,
|
||||
z. B. der llama.cpp-Server aus [Kapitel 3](#3-alternative-llamacpp-server-8001):
|
||||
|
||||
```bash
|
||||
cd ~/pi_coder
|
||||
./start-coding-server.sh
|
||||
PI_CODER_MODEL=llama-cpp-single/coding_model pi
|
||||
```
|
||||
|
||||
Ausgabe bei Erfolg:
|
||||
```
|
||||
[*] Verwende HF_HOME = /home/.../huggingface
|
||||
[*] GPU device = 1
|
||||
[✓] Single-Server (:8001) bereit
|
||||
```
|
||||
|
||||
Dauer: bis zu 5 Minuten (Modell wird in GPU-VRAM geladen; neuere llama.cpp-Versionen
|
||||
prüfen beim Start die VRAM-Verfügbarkeit, was zusätzliche Zeit kostet).
|
||||
|
||||
### Status prüfen
|
||||
Freie Eingaben (ohne Slash-Befehl) nutzen pis eigenes Standardmodell aus `~/.pi/agent/settings.json`.
|
||||
`--provider`/`--model` ändern es für einen Lauf, ohne die globalen Einstellungen anzufassen:
|
||||
|
||||
```bash
|
||||
./status-coding-server.sh
|
||||
pi --provider strata --model qwen3.8-flash-next-iq3_s
|
||||
```
|
||||
|
||||
```
|
||||
=== LLaMA-Server Status ===
|
||||
coding_model (Port 8001): Container=RUNNING HTTP=OK
|
||||
**Bilder** (Screenshots, `read` auf PNG/JPG, Browser-Screenshots) erreichen nur Modelle, die in `models.json`
|
||||
`"input": ["text", "image"]` haben. Strata ist so eingetragen. Bei anderen Modellen meldet pi „Current model does not
|
||||
support images“ und lässt das Bild weg.
|
||||
|
||||
### Einrichten
|
||||
|
||||
Einmalig und nach Änderungen an `models.json` oder `settings.json`:
|
||||
|
||||
```bash
|
||||
cd ~/pi_coder_v2
|
||||
./deploy-pi-config.sh
|
||||
```
|
||||
|
||||
### pi agent öffnen
|
||||
Das Skript **verlinkt** `pi-coding-extension.ts` und `mcp.json` nach `~/.pi/agent/`. Änderungen im Repo gelten
|
||||
damit ab dem nächsten pi-Start (oder `/reload`), auch noch nicht committete, und `pi mcp add` schreibt direkt ins
|
||||
Repo. `models.json` wird kopiert, aus `settings.json` nur die Liste `packages` übernommen. Eine abweichende alte
|
||||
Datei sichert das Skript vorher als `.bak`.
|
||||
|
||||
pi agent im Projektverzeichnis starten — das ist das Verzeichnis, in dem dein Code liegt,
|
||||
**nicht** `~/pi_coder`:
|
||||
### pi öffnen
|
||||
|
||||
pi im Projektordner starten, also dort, wo der Code liegt, nicht in `~/pi_coder_v2`:
|
||||
|
||||
```bash
|
||||
cd ~/MeinProjekt
|
||||
pi
|
||||
```
|
||||
|
||||
### pi aktualisieren
|
||||
|
||||
`pi update` ersetzt pis Programmdateien. Ein pi, das dabei läuft, findet danach Teile seines eigenen Codes nicht mehr,
|
||||
und jede Modellanfrage scheitert (siehe [Fehlermeldungen](#cannot-find-module--chunks-nach-pi-update)). Deshalb
|
||||
nur aktualisieren, wenn kein pi läuft, oder alle laufenden pi danach neu starten.
|
||||
|
||||
---
|
||||
|
||||
## 3. Server starten und stoppen
|
||||
## 3. Alternative: llama.cpp-Server (:8001)
|
||||
|
||||
Nur nötig, wenn Coder und Judge statt Strata das Modell `llama-cpp-single/coding_model` nutzen sollen: Qwen3.6-27B
|
||||
IQ4_XS im Docker-Container `coding_model` auf einer GPU. Danach pi mit `PI_CODER_MODEL=llama-cpp-single/coding_model`
|
||||
starten (siehe [Modell wählen](#modell-wählen)).
|
||||
|
||||
### GPU-Zuordnung
|
||||
|
||||
|
|
@ -120,7 +142,7 @@ nvidia-smi --query-gpu=index,name,memory.used,memory.free --format=csv
|
|||
### Server starten
|
||||
|
||||
```bash
|
||||
cd ~/pi_coder
|
||||
cd ~/pi_coder_v2
|
||||
./start-coding-server.sh
|
||||
```
|
||||
|
||||
|
|
@ -153,29 +175,6 @@ Falls die GGUF-Datei an einem anderen Ort liegt:
|
|||
HF_HOME=/mnt/daten/huggingface ./start-coding-server.sh
|
||||
```
|
||||
|
||||
### Anderes Modell für die Schleife
|
||||
|
||||
Ohne weitere Angabe arbeiten Coder und Judge mit `strata/qwen3.8-flash-next-iq3_s` (Strata, Port 9090). Das Modell
|
||||
liest auch Bilder (`"input": ["text", "image"]` in `models.json`): Screenshots, die pi mit dem `read`-Werkzeug
|
||||
öffnet, erreichen das Modell.
|
||||
|
||||
Web-Apps testet pi über den global eingetragenen MCP-Server `playwright` (headless Chrome, Werkzeuge
|
||||
`browser_*`), auch in der Coder/Judge-Schleife. Einrichtung und Grenzen: `~/nvme2n1p7_home/strata-betrieb`,
|
||||
BEDIENUNGSANLEITUNG, „Web-Anwendungen testen“. Ist das
|
||||
Modell entladen, lädt Strata es bei der ersten Anfrage und gibt vorher GPU 1 und 2 frei; die Bereitschaftsprüfung
|
||||
wartet darauf bis zu 3 Minuten. Eingerichtet ist das in `~/nvme2n1p7_home/strata-betrieb` (dort
|
||||
BEDIENUNGSANLEITUNG, „GPUs teilen“). Ein anderes Modell aus `models.json` setzt die Umgebungsvariable
|
||||
`PI_CODER_MODEL` beim Start von pi, als `<provider>/<id>`, z. B. der llama.cpp-Server auf Port 8001:
|
||||
|
||||
```bash
|
||||
PI_CODER_MODEL=llama-cpp-single/coding_model pi
|
||||
```
|
||||
|
||||
`--provider`/`--model` machen das Modell auch für freie Eingaben zum Standard dieses Laufs; die globalen
|
||||
Einstellungen bleiben unverändert. Die Bereitschaftsprüfung fragt den Endpunkt aus `baseUrl` des Modells ab. Der
|
||||
Provider `strata` (lokaler Strata-Server auf `127.0.0.1:9090`) steht in `models.json`; den Server startet man außerhalb
|
||||
dieses Repos.
|
||||
|
||||
---
|
||||
|
||||
## 4. Neues Projekt anlegen
|
||||
|
|
@ -446,6 +445,23 @@ den Rest automatisch ablaufen lassen:
|
|||
Die Implementierungsphase wird übersprungen — der Judge prüft sofort den aktuellen
|
||||
Stand und der Fix-Zyklus läuft automatisch bis PASS oder max. N Runden.
|
||||
|
||||
### Schneller entwickeln
|
||||
|
||||
Eine lange Sitzung an einem Tauri-Projekt mit Strata dauerte 12 Stunden, davon rund 9 Stunden Warten auf den
|
||||
nächsten Befehl (Messung: `~/nvme2n1p7_home/strata-betrieb/FUNKTIONSWEISE.md`, „Messwerte“). Was schneller macht, nach
|
||||
Wirkung:
|
||||
|
||||
1. **Eine Schleife statt einzelner Befehle.** Für einen weiteren Auftrag am selben Projekt
|
||||
`/optimize --continue "Zusatzauftrag …" --rounds 5 --test-cmd "…"` statt `/judge`, `/fix` und `/shipit` von Hand.
|
||||
Die Schleife geht ohne Pause von Prüfung zu Reparatur.
|
||||
2. **Neue pi-Sitzung je Auftrag** (pi neu starten). Der Kontext beginnt klein; in der gemessenen Sitzung lag der
|
||||
Prompt im Median bei 126 000 Tokens. Was pi wissen muss, steht in `TASK.md` und in Git.
|
||||
3. **Teure Builds erst zur Freigabe.** Im Auftrag z. B.: „In den Fix-Runden nur `cargo test` und `npm run build`;
|
||||
`npx tauri build` erst bei der Freigabe.“
|
||||
4. **Kurze Berichte** sind Standard (siehe [Konzept](#1-konzept-coder-und-judge)).
|
||||
5. Ein schnelleres Cloud-Modell (`PI_CODER_MODEL=openrouter/…`) ist die letzte Stufe: kostet Geld, und der Code geht
|
||||
nach außen.
|
||||
|
||||
### Loop-Erkennung
|
||||
|
||||
Wenn zweimal hintereinander dieselbe Beanstandung auftritt, bricht `/optimize` ab:
|
||||
|
|
@ -765,7 +781,67 @@ Die Checkboxen werden automatisch abgehakt:
|
|||
|
||||
---
|
||||
|
||||
## 11. Typische Anwendungsfälle
|
||||
## 11. Werkzeuge für pi: MCP-Server
|
||||
|
||||
Eingetragen in `mcp.json` dieses Repos, nach `~/.pi/agent/mcp.json` verlinkt (`pi mcp list` zeigt den Zustand). Sie
|
||||
gelten in jeder pi-Sitzung, auch in der Coder/Judge-Schleife:
|
||||
|
||||
| Server | Version | Zweck |
|
||||
|---|---|---|
|
||||
| `playwright` | `@playwright/mcp@0.0.83` | Web-Apps in einem headless Chrome bedienen (siehe [Kapitel 12](#12-web-anwendungen-testen)) |
|
||||
| `context7` | `@upstash/context7-mcp@4.1.1` | aktuelle Doku von Bibliotheken nachschlagen (`resolve-library-id`, `query-docs`), damit das Modell keine veralteten APIs erfindet; Anfragen gehen an `context7.com` |
|
||||
|
||||
**codemode:** pi beschreibt MCP-Werkzeuge dem Modell nicht einzeln. Das Modell schreibt ein kurzes JavaScript, das sie
|
||||
aufruft (`tools.mcp__context7__query_docs(...)`). Beide Server zusammen kosten so nur rund 870 Prompt-Tokens.
|
||||
|
||||
**Context7 benutzen:** im Auftrag den Server und die Bibliothek mit Version nennen, ein Thema je Frage, z. B.:
|
||||
|
||||
```
|
||||
Schlage mit context7 in der aktuellen Doku von Tauri 2 nach: Wie sende ich aus einem Rust-Command
|
||||
Fortschritts-Events an das Frontend? Kurzes Beispiel für beide Seiten, nenne die Bibliotheks-ID.
|
||||
```
|
||||
|
||||
In `/optimize`-Aufträgen hilft der Satz „Schlage unklare APIs mit context7 nach, bevor du sie benutzt.“
|
||||
|
||||
**API-Key:** `mcp.json` enthält nur den Verweis `"CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"`. Der Key selbst gehört in
|
||||
die Umgebung, z. B. `export CONTEXT7_API_KEY=…` in `~/.bashrc`. Fehlt die Variable, startet pi den Server **nicht**
|
||||
(`pi mcp list`: `context7: failed`, „Failed to resolve … env "CONTEXT7_API_KEY"“). Steht der `export` in `~/.bashrc`
|
||||
nach der Abfrage auf interaktive Shells, gilt das für Skripte, Cron und Dienste. Prüfen, ob der Key beim Server
|
||||
ankommt (zeigt nur die Länge):
|
||||
`tr '\0' '\n' < /proc/$(pgrep -f context7-mcp | head -1)/environ | grep '^CONTEXT7_API_KEY=' | cut -d= -f2- | wc -c`.
|
||||
Den Einrichtungsassistenten `npx ctx7 setup` nicht benutzen: Er schreibt den Key im Klartext in die Konfiguration.
|
||||
|
||||
**Weitere Server** nur bei Bedarf, z. B. Serena (Code-Navigation über Language Server, lohnt bei großen Projekten)
|
||||
oder ein Forgejo-Server (Issues, Pull Requests). Unnötig sind Dateisystem-, Git- oder Fetch-Server: Das können
|
||||
`bash`, `read` und `research_web` schon. Versionen fest wählen, nur eine Version, die mindestens zwei Wochen alt ist.
|
||||
|
||||
---
|
||||
|
||||
## 12. Web-Anwendungen testen
|
||||
|
||||
pi testet Web-Apps über den MCP-Server `playwright` in einem **headless** Chrome (der installierte, `--browser chrome`),
|
||||
nie über Klicks auf dem Desktop. Die Seite kommt als Text (Accessibility-Baum) beim Modell an; dafür reicht jedes
|
||||
Textmodell. Für die Optik kann pi Screenshots machen; die sieht nur ein bildfähiges Modell (siehe
|
||||
[Modell wählen](#modell-wählen)).
|
||||
|
||||
```bash
|
||||
pi --provider strata --model qwen3.8-flash-next-iq3_s
|
||||
# dann z. B.: Teste http://127.0.0.1:5173/ mit den Browser-Werkzeugen: fülle das Formular aus, sende es ab
|
||||
# und nenne das Ergebnis wörtlich. Mach danach einen Screenshot und prüfe das Layout.
|
||||
```
|
||||
|
||||
**Für Projekte** ist eine Playwright-Testsuite verlässlicher: reproduzierbar, auch in CI. Im Auftrag an `/optimize`:
|
||||
„Schreibe Playwright-E2E-Tests (`@playwright/test`, headless, `channel: 'chrome'`, `webServer` startet die App).“ und
|
||||
`--test-cmd "npm test && npx playwright test" --test-timeout 900`. `channel: 'chrome'` nutzt den installierten Chrome,
|
||||
`npx playwright install` ist dann nicht nötig.
|
||||
|
||||
Inhalte prüft man über Snapshot oder Testsuite; Screenshots kosten Zeit und sind ungenauer. Messwerte mit Strata und
|
||||
die Einrichtung anderer Agenten (Hermes, OpenCode): `~/nvme2n1p7_home/strata-betrieb/BEDIENUNGSANLEITUNG.md`,
|
||||
„Web-Anwendungen testen“.
|
||||
|
||||
---
|
||||
|
||||
## 13. Typische Anwendungsfälle
|
||||
|
||||
### Neues Rust-Programm von Null
|
||||
|
||||
|
|
@ -876,7 +952,7 @@ Die Checkboxen werden automatisch abgehakt:
|
|||
|
||||
---
|
||||
|
||||
## 12. Fehlermeldungen und Lösungen
|
||||
## 14. Fehlermeldungen und Lösungen
|
||||
|
||||
### "Urteil unklar: … Judge-Urteil nicht erkennbar"
|
||||
|
||||
|
|
@ -934,6 +1010,29 @@ HF_HOME=/korrekter/pfad ./start-coding-server.sh
|
|||
./start-coding-server.sh
|
||||
```
|
||||
|
||||
### "Cannot find module … chunks" nach pi update
|
||||
|
||||
```
|
||||
Cannot find module '…/pi-coding-agent/dist/bundle/chunks/openai-completions-….js'
|
||||
```
|
||||
|
||||
**Ursache:** pi wurde aktualisiert (`pi update`), während diese pi-Sitzung lief. Jede Modellanfrage scheitert sofort;
|
||||
`/optimize` läuft dann mit leeren Antworten durch, ohne zu arbeiten.
|
||||
|
||||
**Lösung:** pi beenden und neu starten, dann den Befehl wiederholen (bei `/optimize` mit `--continue`).
|
||||
|
||||
### pi -p hängt in Skripten
|
||||
|
||||
**Ursache:** `pi -p "…"` liest zusätzlich stdin, wenn das kein Terminal ist, und wartet auf dessen Ende.
|
||||
|
||||
**Lösung:** `pi … -p "…" </dev/null`.
|
||||
|
||||
### "Current model does not support images"
|
||||
|
||||
**Ursache:** Das gewählte Modell ist in `models.json` nicht als bildfähig eingetragen; pi lässt das Bild weg.
|
||||
|
||||
**Lösung:** Ein bildfähiges Modell wählen, z. B. Strata (siehe [Modell wählen](#modell-wählen)).
|
||||
|
||||
### "Agent is already processing a prompt"
|
||||
|
||||
**Ursache:** Ein Kommando wurde aufgerufen während pi agent noch auf eine Antwort wartet.
|
||||
|
|
@ -986,7 +1085,7 @@ Falls der Judge wiederholt Concerns findet, die du akzeptierst:
|
|||
|
||||
**Lösung:**
|
||||
```bash
|
||||
cd ~/pi_coder
|
||||
cd ~/pi_coder_v2
|
||||
./deploy-pi-config.sh
|
||||
# Dann /reload in pi agent
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue