From e1796c0ccc2e73f222c71c2f7160dae22e5b1275 Mon Sep 17 00:00:00 2001 From: dschlueter Date: Fri, 16 Oct 2026 04:56:38 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20pi-Doku=20zusammengef=C3=BChrt,=20FUNKT?= =?UTF-8?q?IONSWEISE/CHANGELOG/LICENSE;=20mcp.json=20versioniert=20und=20v?= =?UTF-8?q?erlinkt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- BEDIENUNGSANLEITUNG.md | 207 ++++++++++++++++++++++++++++++----------- CHANGELOG.md | 53 +++++++++++ FUNKTIONSWEISE.md | 95 +++++++++++++++++++ LICENSE | 21 +++++ README.md | 97 +++++++------------ deploy-pi-config.sh | 27 +++--- mcp.json | 27 ++++++ tests/config.test.mjs | 11 +++ tests/scripts.test.mjs | 8 +- 9 files changed, 413 insertions(+), 133 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 FUNKTIONSWEISE.md create mode 100644 LICENSE create mode 100644 mcp.json diff --git a/BEDIENUNGSANLEITUNG.md b/BEDIENUNGSANLEITUNG.md index 322d691..9b6998b 100644 --- a/BEDIENUNGSANLEITUNG.md +++ b/BEDIENUNGSANLEITUNG.md @@ -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=/` 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 `/`, 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 "…" z. B. --rounds 5
--continue
--test-cmd"] + B["Bereitschaft prüfen
bis 3 min auf HTTP 200"] + C["Coder implementiert,
TASK.md, Commit
(entfällt mit --continue)"] + T["Tests extern ausführen
--test-cmd oder erkannt"] + J["Judge prüft
TASK.md, letzter Commit,
Test-Ergebnis"] + V{"Urteil"} + L{"Gleicher Schlüssel
wie Vorrunde
oder letzte Runde?"} + F["Coder repariert
Blocker, Major, Minor;
Commit"] + X["Abbruch:
manuell weiter mit
/judge und /fix"] + P["SHIP: Status in TASK.md,
Abschluss-Commit,
optional Version, Doku"] + S --> B --> C --> T --> J --> V + V -->|"PASS oder PASS WITH CONCERNS
mit --approve-concerns"| P + V -->|"sonst"| L + L -->|ja| X + L -->|nein| F --> T +``` + +- Die Tests führt die Extension selbst aus (`runTestsParallel`, Zeitlimit `--test-timeout`, Standard 120 s) und gibt + die Ausgabe dem Judge mit; der Judge führt dann keine Tests aus. +- Der Schleifenschlüssel ist der Blocker-Abschnitt, bei „Blocker: Keine“ der Major-Abschnitt, sonst der ganze Text. +- Mit `--interactive` pausiert die Schleife nach PASS und wartet bis 30 Minuten auf `/continue`. +- Jeder Schritt ist eine normale Nachricht in derselben pi-Sitzung; der Kontext wächst mit jeder Runde. + +## Einrichtung auf dem Rechner + +`deploy-pi-config.sh` legt die Dateien nach `~/.pi/agent/`: + +| Datei im Repo | Ziel | Art | +|---|---|---| +| `pi-coding-extension.ts` | `~/.pi/agent/extensions/pi-coding-extension.ts` | Symlink | +| `mcp.json` | `~/.pi/agent/mcp.json` | Symlink | +| `models.json` | `~/.pi/agent/models.json` | Kopie | +| `settings.json` | `~/.pi/agent/settings.json` | nur die Liste `packages` wird übernommen | + +pi lädt Extensions über Symlinks und bindet MCP-Server standardmäßig im **codemode** ein: Die Werkzeuge stehen nicht +einzeln im Prompt, das Modell ruft sie aus einem kurzen JavaScript auf. + +## Designentscheidungen + +| Entscheidung | Verworfene Alternativen | Grund | +|---|---|---| +| Ein Modell für beide Rollen, Rolle per System-Prompt | zwei Server bzw. Modelle für Coder und Judge | ein Modell spart GPU-Speicher; der Rollenwechsel kostet keinen Modellwechsel | +| Modell über `PI_CODER_MODEL`, Bereitschaft aus `baseUrl` des Modells | fester Port 8001; Extension-Kopie je Modell | eine Quelle für alle Modelle; Strata (Port 9090) und llama.cpp (8001) gehen ohne Codeänderung | +| Standard Strata statt llama.cpp (15.10.2026) | llama.cpp-Container auf `:8001` | Strata gibt die GPUs selbst frei und lädt bei Bedarf; der llama.cpp-Container blockierte GPU 1 dauerhaft | +| Extension und `mcp.json` als Symlink | Kopie bei jedem Deploy | Änderungen gelten sofort; `pi mcp add` landet im Repo und ist in `git diff` sichtbar; ein `cp` auf den Symlink bräche mit „same file“ ab | +| Urteilsregeln im Judge-Prompt (`judgeVerdictSection`) | freie Bewertung „Produktionsreife“ | ohne Regeln urteilte der Judge mit Strata am 15.10. in keiner Aufgabe PASS; Härtung über die Anforderungen hinaus steht jetzt unter „Hinweise“ | +| Kurze Berichte (`reportBrevityRules`, 16.10.) | ausführliche Prüfprotokolle | eine 12-Stunden-Sitzung erzeugte 777 000 Tokens; lange Berichte kosten Rechenzeit und bleiben im Kontext jeder Runde. Blocker und Major bleiben vollständig | +| Urteil auch mit Markdown erkennen (`## Urteil: **PASS**`) | nur exaktes `Urteil: PASS` | Strata schreibt Markdown; vorher lief die Schleife bei erfülltem Auftrag weiter | +| Schleifenschlüssel mit Major-Rückfall (`loopKey`) | nur Blocker vergleichen | zwei Runden mit „Blocker: Keine“ und verschiedenen Majors galten sonst als Schleife | +| MCP-Server Playwright (headless, System-Chrome) und Context7 im codemode | Klicks per `xdotool` auf dem Desktop; Dateisystem-, Git-, Fetch-Server; `npx ctx7 setup` | headless stört den Nutzer nicht, der Accessibility-Baum reicht jedem Textmodell; Context7 behebt veraltete APIs; die übrigen Server doppeln `bash`/`read`/`research_web`; `ctx7 setup` schreibt den Key im Klartext. codemode kostet für beide Server rund 870 Prompt-Tokens | +| `mcp.json` im Repo mit Verweis `${CONTEXT7_API_KEY}` | Key in der Datei; `mcp.json` nur lokal | reproduzierbare Einrichtung ohne Geheimnis im Repo | +| Feste Paketversionen (`@playwright/mcp@0.0.83`, `@upstash/context7-mcp@4.1.1`), mindestens zwei Wochen alt | `@latest` | ein kompromittiertes neues Paket würde sonst bei jedem Start geladen | + +## Bekannte Grenzen + +- **Coder und Judge sind dasselbe Modell:** Der Judge übersieht eher, was der Coder auch übersieht. Verdeckte + Abnahmetests (wie in `strata-betrieb/pi-test/`) prüfen unabhängig. +- **Langer Kontext:** Eine Sitzung sammelt alle Runden; in einer gemessenen Sitzung lag der Prompt im Median bei + 126 000 Tokens. Für jeden neuen Auftrag eine neue Sitzung beginnen. +- **pi-Updates:** Ein laufendes pi verträgt kein `pi update`; danach scheitert jede Modellanfrage, bis pi neu startet. +- **`pi -p` in Skripten** wartet auf stdin; dort immer `/`, siehe -[BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md#anderes-modell-für-die-schleife). +[BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md#modell-wählen). --- ## Voraussetzungen -- Docker mit NVIDIA-GPU-Support: - ```bash - # NVIDIA Container Toolkit installieren (falls nicht vorhanden) - distribution=$(. /etc/os-release; echo $ID$VERSION_ID) - curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - - curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list \ - | sudo tee /etc/apt/sources.list.d/nvidia-docker.list - sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit - sudo systemctl restart docker - ``` -- NVIDIA-GPU: empfohlen RTX 3090 (24 GB VRAM). Standard: GPU 1. Überschreibbar mit - `GPU_DEVICE=0 ./start-coding-server.sh`. Bei 3 GPUs: GPU 0 für Display reservieren. -- GGUF-Modell vorhanden unter: - `$HF_HOME/models/qwen3/Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS.gguf` - - Standard-Pfad: `HF_HOME=/home/dschlueter/nvme2n1p7_home/huggingface` - - Überschreibbar: `HF_HOME=/anderer/pfad ./start-coding-server.sh` -- [pi agent](https://github.com/earendil-works/pi) installiert (`~/.pi/`) +- [pi](https://pi.dev) installiert (`~/.pi/`). +- Ein Modell für Coder und Judge: + - **Standard:** der lokale Strata-Server auf `127.0.0.1:9090` (Betrieb: `~/nvme2n1p7_home/strata-betrieb`). + - **Alternative:** der llama.cpp-Server in Docker auf Port 8001 (unten). Dafür Docker mit NVIDIA Container Toolkit, + eine GPU mit 24 GB (Standard GPU 1, `GPU_DEVICE=…`) und das GGUF-Modell unter + `$HF_HOME/models/qwen3/Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS.gguf` + (Standard `HF_HOME=/home/dschlueter/nvme2n1p7_home/huggingface`). --- ## Installation ```bash -# 1. Repository klonen -git clone https://kitux.de/forgejo/dschlueter/pi_coder.git ~/pi_coder -cd ~/pi_coder - -# 2. Extension, Modell-Config und settings.json nach ~/.pi/agent/ deployen -./deploy-pi-config.sh - -# 3. pi agent neu laden (in der pi-Oberfläche) -# /reload - -# 4. Server starten -./start-coding-server.sh +git clone https://kitux.de/forgejo/dschlueter/pi_coder_2.git ~/pi_coder_v2 +cd ~/pi_coder_v2 +./deploy-pi-config.sh # verlinkt Extension und mcp.json, kopiert models.json, übernimmt settings.json (nur packages) ``` -Das Install-Skript sichert eine vorhandene `~/.pi/agent/settings.json` als `.bak` und -kopiert dann `settings.json` aus dem Repo. Damit ist der korrekte Default-Provider -(`llama-cpp-single/coding_model`) automatisch konfiguriert. - -Die Extension wird nicht kopiert, sondern verlinkt -(`~/.pi/agent/extensions/pi-coding-extension.ts` → Repo). Änderungen an `pi-coding-extension.ts` gelten -damit für jeden pi-Aufruf ab dem nächsten Start bzw. `/reload`, ohne erneutes Deploy. Das gilt auch für noch -nicht committete Änderungen. - -Nach späteren Änderungen an `models.json` oder `settings.json`: -```bash -./deploy-pi-config.sh # verlinkt die Extension, kopiert models.json, settings.json (nur packages) -# dann /reload in pi agent -``` +Danach pi im Projektordner starten. Was das Skript genau tut und wie man das Modell wählt: +[BEDIENUNGSANLEITUNG.md, Kapitel 2](BEDIENUNGSANLEITUNG.md#2-vorbereitung). --- -## Server starten / stoppen / status +## llama.cpp-Server (Alternative) ```bash -# Server starten (empfohlen — dauert 1–3 Minuten) -./start-coding-server.sh - -# Server auf anderer GPU starten +./start-coding-server.sh # startet den Container coding_model, wartet bis HTTP bereit (bis 5 min) GPU_DEVICE=0 ./start-coding-server.sh - -# Stoppen ./stop-coding-server.sh - -# Status prüfen ./status-coding-server.sh ``` -`start-coding-server.sh` startet den Container und wartet bis HTTP-ready (max. 5 Minuten — die -neue llama.cpp-Version prüft beim Start, ob Modell + KV-Cache in den VRAM passen, was -zusätzliche Zeit kostet). - -Wenn der Server bereits läuft und du `start-coding-server.sh` aufrufst, wird der laufende -Container zuerst per `docker rm -f` gestoppt und dann neu gestartet — ein laufender -Inference-Request wird dabei abgebrochen. +Ein erneuter Start entfernt einen laufenden Container zuerst (`docker rm -f`); eine laufende Anfrage bricht dabei ab. +Coder und Judge nutzen ihn mit `PI_CODER_MODEL=llama-cpp-single/coding_model pi`. --- @@ -261,15 +218,14 @@ und Extension-Guards gegen Regressionen. |---|---| | `pi-coding-extension.ts` | pi agent Extension (Kommandos, Tools, Hooks, Rollen-Logik) | | `models.json` | Provider- und Modell-Konfiguration für pi agent | -| `settings.json` | pi-agent-Settings (Default-Modell, aktivierte Modelle) — wird von Install-Skript deployt | +| `settings.json` | pi-Settings; `deploy-pi-config.sh` übernimmt daraus nur die Liste `packages` | +| `mcp.json` | MCP-Server für pi (Playwright, Context7), nach `~/.pi/agent/mcp.json` verlinkt | | `run-tests.sh` | Tests ausführen | | `tests/` | Testdateien (pure-logic, config, extension-guards, scripts) | | `start-coding-server.sh` | Single-Server starten (Port 8001, Coder + Judge) | | `stop-coding-server.sh` | Container stoppen | | `status-coding-server.sh` | Laufstatus anzeigen | -| `deploy-pi-config.sh` | Extension nach `~/.pi/agent/extensions/` verlinken, models.json + settings.json kopieren | -| `examples/` | Demo-Projekte (Python, Rust, Go, C, Bash, HTML/JS) für Live-Demos | -| `examples/restore-all.sh` | Examples nach Demo-Lauf in Ausgangszustand zurücksetzen | +| `deploy-pi-config.sh` | Extension und `mcp.json` nach `~/.pi/agent/` verlinken, `models.json` kopieren, `packages` aus `settings.json` übernehmen | --- @@ -292,7 +248,7 @@ und Extension-Guards gegen Regressionen. | `/cancel` | — | Laufenden Loop nach aktuellem Schritt abbrechen | | `/new_project ` | — | Neues Projektverzeichnis + git init | -Ausführliche Beschreibung aller Kommandos mit Beispielen: siehe **BEDIENUNGSANLEITUNG.md**. +Ausführliche Beschreibung aller Kommandos mit Beispielen: [BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md). --- @@ -326,3 +282,14 @@ inklusive eines laufenden `[MM:SS]`-Timers während jeder LLM-Inference-Phase: | Interactive-Pause | `⏸ PASS – warte auf /continue…` | Der Timer beweist, dass die LLM tatsächlich arbeitet. Steht er still, hängt der Prozess. + +--- + +## Documentation + +- [BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md) – Einrichtung, Modellwahl, alle Befehle, MCP-Server, Web-Tests, + schneller entwickeln, Fehlermeldungen +- [FUNKTIONSWEISE.md](FUNKTIONSWEISE.md) – Aufbau der Extension, Ablauf von `/optimize`, Designentscheidungen, Grenzen +- [CHANGELOG.md](CHANGELOG.md) – Änderungen und was beim Update zu tun ist +- [LICENSE](LICENSE) – MIT +- Strata-Server und Messwerte auf diesem PC: `~/nvme2n1p7_home/strata-betrieb` diff --git a/deploy-pi-config.sh b/deploy-pi-config.sh index 21398bf..7dc99d4 100755 --- a/deploy-pi-config.sh +++ b/deploy-pi-config.sh @@ -1,20 +1,25 @@ #!/usr/bin/env bash -# Verlinkt die Extension und kopiert models.json/settings.json aus dem Repo nach ~/.pi/agent/. -# Die Extension ist ein Symlink: Änderungen im Repo gelten ab dem nächsten pi-Start bzw. /reload. -# Erneut ausführen nur nach Änderungen an models.json oder settings.json. +# Verlinkt Extension und mcp.json und kopiert models.json/settings.json aus dem Repo nach ~/.pi/agent/. +# Extension und mcp.json sind Symlinks: Änderungen im Repo gelten ab dem nächsten pi-Start bzw. /reload, und +# `pi mcp add` schreibt direkt ins Repo. Erneut ausführen nur nach Änderungen an models.json oder settings.json. set -euo pipefail REPO="$(cd "$(dirname "$0")" && pwd)" mkdir -p ~/.pi/agent/extensions -# A previous, differing copy is kept as .bak before it is replaced by the symlink. -EXT=~/.pi/agent/extensions/pi-coding-extension.ts -if [ -f "$EXT" ] && [ ! -L "$EXT" ] && ! cmp -s "$EXT" "$REPO/pi-coding-extension.ts"; then - cp "$EXT" "$EXT.bak" - echo "Backup: pi-coding-extension.ts → pi-coding-extension.ts.bak" -fi -ln -sfn "$REPO/pi-coding-extension.ts" "$EXT" -echo "Verlinkt: ~/.pi/agent/extensions/pi-coding-extension.ts → $REPO/pi-coding-extension.ts" +# Links $1 (repo file) to $2; a previous, differing regular file is kept as .bak first. +link_file() { + local src="$1" dest="$2" + if [ -f "$dest" ] && [ ! -L "$dest" ] && ! cmp -s "$dest" "$src"; then + cp "$dest" "$dest.bak" + echo "Backup: $(basename "$dest") → $(basename "$dest").bak" + fi + ln -sfn "$src" "$dest" + echo "Verlinkt: $dest → $src" +} + +link_file "$REPO/pi-coding-extension.ts" ~/.pi/agent/extensions/pi-coding-extension.ts +link_file "$REPO/mcp.json" ~/.pi/agent/mcp.json cp "$REPO/models.json" ~/.pi/agent/models.json echo "Kopiert: models.json → ~/.pi/agent/" diff --git a/mcp.json b/mcp.json new file mode 100644 index 0000000..1795ed8 --- /dev/null +++ b/mcp.json @@ -0,0 +1,27 @@ +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": [ + "-y", + "@playwright/mcp@0.0.83", + "--browser", + "chrome", + "--headless", + "--isolated", + "--output-dir", + "/tmp/playwright-mcp" + ] + }, + "context7": { + "command": "npx", + "args": [ + "-y", + "@upstash/context7-mcp@4.1.1" + ], + "env": { + "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}" + } + } + } +} diff --git a/tests/config.test.mjs b/tests/config.test.mjs index 7ce1c33..beab7bf 100644 --- a/tests/config.test.mjs +++ b/tests/config.test.mjs @@ -7,6 +7,7 @@ import { readJson, readRepoFile } from "./helpers.mjs"; const models = readJson("models.json"); const settings = readJson("settings.json"); +const mcp = readJson("mcp.json"); test("models.json: Provider llama-cpp-single hat genau ein Modell coding_model auf Port 8001", () => { const p = models.providers["llama-cpp-single"]; @@ -54,3 +55,13 @@ test("settings.json enthält keine Modell-Auswahl (Nutzer-Präferenz bleibt erha assert.ok(!("defaultModel" in settings), "defaultModel soll nicht im Repo-settings sein"); assert.ok(!("enabledModels" in settings), "enabledModels soll nicht im Repo-settings sein"); }); + +test("mcp.json: Playwright und Context7 mit fester Version, Key nur als Umgebungsverweis", () => { + const servers = mcp.mcpServers; + assert.deepEqual(Object.keys(servers).sort(), ["context7", "playwright"]); + assert.ok(servers.playwright.args.includes("@playwright/mcp@0.0.83")); + assert.ok(servers.playwright.args.includes("--headless"), "Browser-Tests nie auf dem Desktop"); + assert.ok(servers.context7.args.includes("@upstash/context7-mcp@4.1.1")); + assert.deepEqual(servers.context7.env, { CONTEXT7_API_KEY: "${CONTEXT7_API_KEY}" }); + assert.doesNotMatch(JSON.stringify(mcp), /ctx7sk|--api-key/, "kein API-Key im Klartext"); +}); diff --git a/tests/scripts.test.mjs b/tests/scripts.test.mjs index a5f88a3..6975a17 100644 --- a/tests/scripts.test.mjs +++ b/tests/scripts.test.mjs @@ -45,8 +45,10 @@ test("install-Skript deployt settings.json mit vorherigem Backup", () => { assert.match(s, /pi-coding-extension\.ts/); }); -test("install-Skript verlinkt die Extension statt sie zu kopieren", () => { +test("install-Skript verlinkt Extension und mcp.json statt sie zu kopieren", () => { const s = readRepoFile("deploy-pi-config.sh"); - assert.match(s, /ln -sfn "\$REPO\/pi-coding-extension\.ts" "\$EXT"/); - assert.doesNotMatch(s, /cp "\$REPO\/pi-coding-extension\.ts"/, "cp auf den Symlink bricht mit 'same file' ab"); + assert.match(s, /ln -sfn "\$src" "\$dest"/); + assert.match(s, /link_file "\$REPO\/pi-coding-extension\.ts" ~\/\.pi\/agent\/extensions\/pi-coding-extension\.ts/); + assert.match(s, /link_file "\$REPO\/mcp\.json" ~\/\.pi\/agent\/mcp\.json/); + assert.doesNotMatch(s, /cp "\$REPO\/(pi-coding-extension\.ts|mcp\.json)"/, "cp auf den Symlink bricht mit 'same file' ab"); });