pi_coder_2/FUNKTIONSWEISE.md

Funktionsweise

Wie die Coder/Judge-Erweiterung für pi aufgebaut ist, wie /optimize abläuft und warum sie so gebaut ist. Bedienung: BEDIENUNGSANLEITUNG.md. Messwerte mit dem lokalen Strata-Server stehen im Repo strata-betrieb (~/nvme2n1p7_home/strata-betrieb/FUNKTIONSWEISE.md, „Messwerte“ und „Testreihe pi mit Strata“).

Inhalt

• Aufbau
• Ablauf von /optimize
• Einrichtung auf dem Rechner
• Designentscheidungen
• Bekannte Grenzen

Aufbau

Teil	Aufgabe
pi-coding-extension.ts	die Erweiterung: registriert /coder, /judge, /fix, /shipit, /optimize, /patch, /quick_check, /version, /update_doku, /plan, /continue, /cancel, /new_project und das Werkzeug apply_patch
Rollen	ein Modell für Coder und Judge; die Rolle setzt ein System-Prompt, den der Hook before_agent_start je nach currentRole einfügt. selectRole() stellt das Modell ein (PI_CODER_MODEL, Standard strata/qwen3.8-flash-next-iq3_s), deselectRole() stellt danach das vorige Modell für freie Eingaben wieder her
Aufträge an das Modell	Funktionen judgePrompt, judgeWithTestsPrompt, fixPrompt, shipitPrompt …; gemeinsame Teile in judgeVerdictSection() (Urteilsregeln, Ausgabeformat) und reportBrevityRules() (kurze Berichte)
Auswertung	parseVerdict() liest „Urteil: PASS / PASS WITH CONCERNS / FAIL“ (auch mit Markdown), parseShipVerdict() „SHIP / NO-SHIP“, loopKey() den Vergleichsschlüssel für die Schleifenerkennung
TASK.md	Auftrag im Projekt; /coder und /optimize legen sie an oder hängen einen „Zusatzauftrag“ an; die Extension setzt die Status-Häkchen
Bereitschaft	waitUntilModelReady() schickt bis zu 3 Minuten lang alle 3 s eine Anfrage mit max_tokens: 1 an den baseUrl des Modells und wartet auf HTTP 200

Ablauf von /optimize

flowchart TB
    S["/optimize Auftrag<br/>z. B. --rounds 5<br/>--continue<br/>--test-cmd"]
    B["Bereitschaft prüfen<br/>bis 3 min auf HTTP 200"]
    C["Coder implementiert,<br/>TASK.md, Commit<br/>(entfällt mit --continue)"]
    T["Tests extern ausführen<br/>--test-cmd oder erkannt"]
    J["Judge prüft<br/>TASK.md, letzter Commit,<br/>Test-Ergebnis"]
    V{"Urteil"}
    L{"Gleicher Schlüssel<br/>wie Vorrunde<br/>oder letzte Runde?"}
    F["Coder repariert<br/>Blocker, Major, Minor;<br/>Commit"]
    X["Abbruch:<br/>manuell weiter mit<br/>/judge und /fix"]
    P["SHIP: Status in TASK.md,<br/>Abschluss-Commit,<br/>optional Version, Doku"]
    S --> B --> C --> T --> J --> V
    V -->|"PASS oder PASS WITH CONCERNS<br/>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 </dev/null.
• Context7 ohne Key startet nicht: Fehlt CONTEXT7_API_KEY in der Umgebung (Skripte, Cron, Dienste), meldet pi mcp list context7: failed.
• Bilder nur mit einem Modell, das in models.json "input": ["text", "image"] hat.
• Tests der Extension (run-tests.sh) prüfen die reinen Funktionen und Konfigurationen, nicht das Zusammenspiel mit einem echten Modell.