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
95
FUNKTIONSWEISE.md
Normal file
95
FUNKTIONSWEISE.md
Normal file
|
|
@ -0,0 +1,95 @@
|
|||
# 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.
|
||||
Loading…
Reference in a new issue