dschlueter
e1796c0ccc
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>
95 lines
7.3 KiB
Markdown
95 lines
7.3 KiB
Markdown
# 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<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.
|