tim
183 lines
8.6 KiB
Markdown
183 lines
8.6 KiB
Markdown
# parsecapere-prompts
|
|
|
|
> Modulare System-Prompts fuer die parsecapere.de Voice-LLM-Plattform.
|
|
> Single-Source-of-Truth fuer alles was das LLM als Anweisung liest.
|
|
|
|
---
|
|
|
|
## Warum dieses Repo existiert
|
|
|
|
Bisher standen die System-Prompts als **3000-Token-Monolithen** direkt in den
|
|
`.js`-Files des `llm-gateway`-Services. Drei harte Schmerzpunkte:
|
|
|
|
| Schmerz | Heute (Monolith) | Morgen (dieses Repo) |
|
|
|------------------------------------------|----------------------------------------|--------------------------------|
|
|
| Reviewable im PR / Diff | nein — Template-String ueber 200 Zeilen | ja — Markdown-Diffs |
|
|
| Versionierbar pro Baustein | nein — nur ueber gesamte `.js` | ja — Git-Commit pro Modul |
|
|
| Hot-Reload ohne Service-Restart | nein — `systemctl restart` (5s Downtime) | ja — Gitea-Webhook → Cache-Invalidate |
|
|
| Token-Effizienz pro Sub-Agent | nein — jeder bekommt alles | ja — nur was er braucht (40-50% Einsparung) |
|
|
|
|
Architektur-Hintergrund: `arch-flow/brainstorm/Sprache/2026-06-02 — Prompt-Modularisierung — Architektur und Composition.md`
|
|
plus `2026-06-02 — Master-Synthese — Prompt-Migration-Reihenfolge.md`.
|
|
|
|
---
|
|
|
|
## Ordner-Struktur (Ziel-Topologie)
|
|
|
|
```
|
|
parsecapere-prompts/
|
|
├── base/ # Immer dabei (Boilerplate fuer ALLE Sub-Agents)
|
|
│ ├── identity.md # Wer bin ich (parsecapere-KI, helfe Sprachlernern …)
|
|
│ ├── style.md # Antwort-Stil + Sprache (Deutsch, freundlich, kurz)
|
|
│ └── constraints.md # Sicherheit, Privacy (audience-Feld!), Anti-Halluzination
|
|
│
|
|
├── workflows/ # Pro Task-Typ relevant (nur einbauen wenn gebraucht)
|
|
│ ├── plan-before-action.md # record_thought / record_reflection-Disziplin
|
|
│ ├── error-recovery.md # Retry, Fallback, Backoff
|
|
│ ├── self-correction.md # Validate-Loop-Pattern (z.B. Kreuzwort-Grid)
|
|
│ ├── sub-agent-discipline.md # KEIN record_*, KEINE Tools ausserhalb des Sets
|
|
│ └── tool-scope-lock.md # Strikte Tool-Liste, kein Erfinden
|
|
│
|
|
├── tools-context/ # Erklaert dem LLM was Tools tun
|
|
│ ├── brick-creation.md # createPulse / createView / createRow semantics
|
|
│ ├── user-scoping.md # audience + ownerUserName (Cookie-K3)
|
|
│ ├── atomic-chain.md # Strikt-sequenzielle atomic_create_*-Aufrufe
|
|
│ ├── atomic-finalize.md # Layer+Solution atomar in einem Call
|
|
│ └── trace-viewer.md # Phase E — trace-events fuer Overwatch
|
|
│
|
|
├── personas/ # Pro Sub-Agent eine
|
|
│ ├── main-voice.md # User-Facing Voice (Session-Orchestrator)
|
|
│ ├── kreuzwort-builder.md # Sub-Agent fuer Kreuzwort-Aufgaben
|
|
│ ├── lueckentext-builder.md # Sub-Agent fuer Lueckentext-Aufgaben
|
|
│ ├── overwatch.md # Phase E — Read-Only-Beobachter (geplant)
|
|
│ └── doc-writer.md # Phase G — Code-Doku (geplant)
|
|
│
|
|
└── skill-index.md # Discovery-Index — was gibt's, mit welchem Trigger
|
|
```
|
|
|
|
**Drei Schichten** — von "immer" bis "spezifisch":
|
|
|
|
```
|
|
[ base/ ] ← immer da, Boilerplate
|
|
[ workflows/ ] ← Task-Typ
|
|
[ tools-context/] ← welche Tools nutzt der Agent
|
|
[ personas/ ] ← wer bin ich konkret ← Tie-Breaker, kommt zuletzt
|
|
```
|
|
|
|
> 💡 **Persona kommt zuletzt** im Compose-Output — sie darf alles davor ueberschreiben.
|
|
|
|
---
|
|
|
|
## Status-Stand (heute, 2026-06-02)
|
|
|
|
### Phase M2 — DONE
|
|
- Drei Personas 1:1 aus dem JS-Code extrahiert (siehe Commit `f4f147e`).
|
|
|
|
### Phase M3 — DONE (2026-06-02)
|
|
Module-Extraktion in 13 Commits. Aufteilung der 3 Monolithen in **11 wiederverwendbare Module**:
|
|
|
|
**`base/`** — universelle Basis fuer ALLE Personas:
|
|
- `base/identity.md` — Stream-Box-Sichtbarkeitsprinzip
|
|
- `base/style.md` — Deutsch / knapp / Success-Meldung / kein falsches Lob
|
|
- `base/constraints.md` — Anti-Halluzination + Trace-Bewusstsein
|
|
|
|
**`workflows/`** — Task-Typ-spezifische Patterns:
|
|
- `workflows/plan-before-action.md` — `record_thought` + `record_reflection` (Main-Voice)
|
|
- `workflows/sub-agent-discipline.md` — KEIN record_*, keine Voice-Tools (Sub-Agents)
|
|
- `workflows/tool-scope-lock.md` — strikte Tool-Liste, keine erfundenen Calls
|
|
- `workflows/self-correction.md` — Validate-Loop-Pattern (Kreuzwort)
|
|
- `workflows/error-recovery.md` — unstrukturierte Tool-Fehler, max 3 Versuche
|
|
|
|
**`tools-context/`** — Tool-Erklaerungen:
|
|
- `tools-context/brick-creation.md` — Pulse/View/Row + delete-Mapping (Main-Voice)
|
|
- `tools-context/atomic-chain.md` — strikt-lineare ID-Verkettung (Lueckentext)
|
|
- `tools-context/atomic-finalize.md` — All-in-One Layer+Solution (Kreuzwort)
|
|
|
|
**`personas/`** — auf das **wirklich Unique** getrimmt (Status `0.1.0 → 0.2.0`):
|
|
- `personas/main-voice.md` — User-Sprache-Tool-Tabelle + Anti-Halluzination + Scope-Escalation
|
|
- `personas/kreuzwort-builder.md` — Grid-Regeln + 6-Schritt-Workflow
|
|
- `personas/lueckentext-builder.md` — `__<gapId>__`-Pattern + Decoy-Regel + 4-Schritt-Workflow
|
|
|
|
Jede Persona hat im Frontmatter jetzt eine `required_prompt_modules`-Liste — Vorgriff auf M4.
|
|
|
|
### Phase M4 — DONE (2026-06-02)
|
|
- Drei Skill-Manifeste im Schwester-Repo
|
|
[`parsecapere-skills/composite/`](https://gitea.parsecapere.de/tim/parsecapere-skills/src/branch/main/composite)
|
|
angelegt: `main-voice.md`, `kreuzwort-builder.md`, `lueckentext-builder.md`.
|
|
- `skill-index.md` von Stub → populated. Verlinkt auf alle drei Manifeste.
|
|
- Persona-Frontmatter (`required_prompt_modules`) und Skill-Manifest sind heute
|
|
noch dupliziert — M5-Composer entscheidet welche Quelle Single-Source-of-Truth ist.
|
|
(Default-Plan: Skill-Manifest gewinnt, Persona-Frontmatter ist Backup-Hinweis.)
|
|
|
|
### Phase M5 — NEXT
|
|
- `mcp-gitea`-Service auf LLM-VPS (Tools: `load_skill`, `list_skills`, `load_prompt_module`).
|
|
- STDB-Cache (`gitea_section_cache`-Tabelle).
|
|
- Webhook-Endpoint `/webhook` fuer Cache-Invalidation.
|
|
|
|
Voller Plan: siehe Vault-Note `2026-06-02 — Master-Synthese — Prompt-Migration-Reihenfolge.md`.
|
|
|
|
---
|
|
|
|
## Compose-Order (zukuenftig fuer mcp-gitea)
|
|
|
|
Wenn ein Skill geladen wird, baut der Composer den finalen System-Prompt
|
|
in **dieser Reihenfolge** zusammen:
|
|
|
|
```
|
|
1. base/identity.md
|
|
2. base/style.md
|
|
3. base/constraints.md
|
|
4. workflows/* (deklariert im Skill-Manifest)
|
|
5. tools-context/* (abgeleitet aus required_tools)
|
|
6. personas/<persona>.md ← LETZTER, ueberschreibt frueheres
|
|
```
|
|
|
|
Der Compose-Algorithmus ist im Detail in
|
|
`arch-flow/brainstorm/Sprache/2026-06-02 — Prompt-Modularisierung — Architektur und Composition.md`
|
|
beschrieben.
|
|
|
|
---
|
|
|
|
## Cross-Repo
|
|
|
|
Dieses Repo (`parsecapere-prompts`) liefert die **Prompt-Bausteine**.
|
|
Zwei Schwester-Repos auf demselben Gitea (https://gitea.parsecapere.de):
|
|
|
|
| Repo | Inhalt |
|
|
|-------------------------|-------------------------------------------------------------------|
|
|
| `parsecapere-prompts` | dieses Repo — Module + Personas |
|
|
| `parsecapere-skills` | Skill-Manifeste (welche Module wann zusammensetzen) |
|
|
| `parsecapere-knowledge` | Lang-laufendes Wissen (z.B. Vokabel-Listen, Wortpool-Snapshots) |
|
|
|
|
---
|
|
|
|
## Architektur-DNA-Bezug
|
|
|
|
Dieses Repo respektiert:
|
|
|
|
- **Server denkt, Frontend rendert** — Composition passiert serverseitig im `mcp-gitea`-Service.
|
|
- **STDB als Smart-Cache** — Module werden bei Bedarf aus Gitea geholt + in STDB
|
|
(Tabelle `gitea_section_cache`) gecached. Webhook invalidiert pro Pfad.
|
|
- **Cookie-K1-K6** — Compose-Endpoint im LLM-Gateway ist intern (Service-Token,
|
|
nicht User-Cookie). Cross-Server-Auth via Token-Bundling (K5) wenn LLM im
|
|
Auftrag eines Users handelt.
|
|
- **Hard-Rules STDB-Migrationen** — neue Tabelle `gitea_section_cache` braucht
|
|
Pre-Backup + additive Migration (siehe `migrations/MIGRATIONS-HARD-RULES.md`).
|
|
- **Skill = Loadable Module** — kein Hard-Coded-Mapping, Discovery via
|
|
Trigger-Keywords (siehe `2026-06-01 — Skill-Sets als Loadable Modules …`).
|
|
|
|
---
|
|
|
|
## Hinweis fuer Tim's Review (M2-Aha-Moment)
|
|
|
|
Lies die drei `personas/*.md` der Reihe nach. Ziel: zum ersten Mal sehen,
|
|
**was der Voice-LLM bisher als Anweisung bekommen hat** — als reine,
|
|
lesbare Markdown-Texte ohne JS-Drumherum.
|
|
|
|
Erwartete Beobachtungen:
|
|
- Wieviel Boilerplate steht da drin? (→ M3 zieht das raus)
|
|
- Wo wiederholen sich die drei Personas? (→ M3 macht draus `base/` und `workflows/`)
|
|
- Wo ist Domain-Wissen? (→ bleibt in der Persona)
|
|
|
|
Notiere was dir auffaellt — das wird der Input fuer M3.
|