# Funktionsweise
Wie die Coder/Judge-Erweiterung für pi aufgebaut ist, wie `/optimize` abläuft und warum sie so gebaut ist. Bedienung:
[BEDIENUNGSANLEITUNG.md](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](#aufbau)
- [Ablauf von /optimize](#ablauf-von-optimize)
- [Einrichtung auf dem Rechner](#einrichtung-auf-dem-rechner)
- [Designentscheidungen](#designentscheidungen)
- [Bekannte Grenzen](#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
```mermaid
flowchart TB
S["/optimize Auftrag
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 `