05 — Prompt-Routing verstehen

🎯

Grundlagen

Was ist Prompt-Routing?

Die Brücke zwischen natürlicher Sprache und ausführbaren Systembefehlen.

Prompt-Routing ist das Herzstück des Claw Code Systems. Es wandelt einen Benutzer-Prompt wie "Erstelle einen neuen Branch für das Login-Feature" in eine geordnete Liste passender Befehle und Tools um.

Das Routing basiert auf einem Token-basierten Scoring-Algorithmus, der im PortRuntime.route_prompt() implementiert ist. Statt einfacher String-Suche analysiert das System die semantische Übereinstimmung zwischen Prompt und verfügbaren Kommandos.

💡

Warum Token-basiert?

Tokenisierung ermöglicht eine robuste Übereinstimmung, auch wenn Benutzer unterschiedliche Formulierungen verwenden. "git-branch", "git branch" und "branch" werden als gleichwertige Tokens erkannt.

Der Tokenisierungs-Prozess

"Erstelle/git-branch" → ["erstelle", "git", "branch"] → Set{"erstelle", "git", "branch"}

Der Prompt wird in eindeutige Tokens umgewandelt, die dann mit den Tokens aller Befehle und Tools verglichen werden.

⚙️

Algorithmus

Der Routing-Algorithmus

4 Phasen von der Eingabe bis zum gerouteten Ergebnis.

Der Routing-Algorithmus arbeitet in vier klar definierten Phasen. Jede Phase transformiert die Daten weiter, bis am Ende eine priorisierte Liste von Matches steht.

Tokenisierung

Der Prompt wird normalisiert: Slash und Bindestriche werden in Leerzeichen umgewandelt, alles zu Kleinbuchstaben, Duplikate entfernt.

normalize("git-branch create") → "git branch create"

Scoring

Für jeden Befehl und jedes Tool wird ein Score berechnet. Der Score basiert auf der Überlappung zwischen Prompt-Tokens und Entry-Tokens (Name, Source-Hint, Responsibility).

score = matching_tokens / total_tokens

Fair-Share-Selektion

Der beste Treffer aus jeder Kategorie (Command, Tool) wird garantiert in die Ergebnisliste aufgenommen. Das stellt sicher, dass keine Kategorie übersehen wird.

result = [best_command, best_tool, ...]

Auffüllung & Sortierung

Die verbleibenden Plätze werden mit den nächstbesten Treffern aufgefüllt, sortiert nach Score. Das Limit kann über Parameter konfiguriert werden.

final = sorted(remaining, key=score)[:limit]

🐍

Implementierung in runtime.py

Der Algorithmus ist in der Methode PortRuntime.route_prompt(prompt: str, limit: int = 10) implementiert. Die Methode gibt eine Liste von RoutedMatch-Objekten zurück.

🧩

Vorverarbeitung

Tokenisierung erklärt

Wie Text in vergleichbare Einheiten umgewandelt wird.

Tokenisierung ist der Schlüssel zu robustem Text-Matching. Das Claw Code System verwendet eine mehrschrittige Normalisierung, um maximale Flexibilität zu gewährleisten.

Die 4 Normalisierungsschritte

Schritt	Transformation	Beispiel
1. Trennzeichen	`/` und `-` → Leerzeichen	`"git/branch-create"` → `"git branch create"`
2. Whitespace	Mehrfache Leerzeichen → Einzelnes	`"git branch"` → `"git branch"`
3. Kleinschreibung	Alle Zeichen lowercase	`"Git Branch"` → `"git branch"`
4. Deduplizierung	Set aus eindeutigen Tokens	`["git","git","branch"]` → `{"git","branch"}`

Token-Quellen für Entries

Jeder Befehl und jedes Tool hat mehrere Text-Quellen, die tokenisiert werden:

Name — Der eindeutige Identifier ("git-branch")
Source-Hint — Woher der Befehl stammt ("git_commands")
Responsibility — Was der Befehl tut ("Create and manage branches")

python

# Beispiel: Tokenisierung eines Befehls
Befehl: git-branch
Name-Tokens: {"git", "branch"}
Source-Tokens: {"git", "commands"}
Responsibility-Tokens: {"create", "and", "manage", "branches"}

# Kombinierte Token-Menge
Entry-Tokens: {"git", "branch", "commands", "create", "manage", "branches"}

💡

Performance-Optimierung

Alle Befehls- und Tool-Tokens werden beim Systemstart vor-tokenisiert und im Speicher gehalten. Das Routing ist daher extrem schnell, auch mit ~150 Befehlen und ~100 Tools.

📊

Bewertung

Scoring-Mechanismus

Wie die Übereinstimmung zwischen Prompt und Entry berechnet wird.

Das Scoring ist das mathematische Herz des Routing-Algorithmus. Es quantifiziert, wie gut ein Prompt zu einem bestimmten Befehl oder Tool passt.

Die Scoring-Formel

algorithm

score(prompt_tokens, entry_tokens) = |prompt_tokens ∩ entry_tokens| / |prompt_tokens|

# Beispiel-Rechnung
Prompt: "create new git branch"
Prompt-Tokens: {"create", "new", "git", "branch"}

Entry: git-branch
Entry-Tokens: {"git", "branch", "create", "manage", "branches"}

Intersection: {"create", "git", "branch"} → 3 Tokens
Score: 3 / 4 = 0.75

Gewichtung der Token-Quellen

Nicht alle Tokens sind gleich wichtig. Der Algorithmus wendet implizite Gewichtungen an:

🏷️

Name

Exakte Befehlsnamen haben höchste Priorität

1.0×

📦

Source-Hint

Herkunft des Befehls (z.B. "git")

0.8×

📝

Responsibility

Beschreibung der Funktionalität

0.6×

Score-Interpretation

Score-Bereich	Bedeutung	Beispiel
0.9 – 1.0	Exakter/exakter naher Treffer	Prompt: "git commit" → Befehl: git-commit
0.7 – 0.9	Sehr gute Übereinstimmung	Prompt: "commit changes" → Befehl: git-commit
0.5 – 0.7	Gute Übereinstimmung	Prompt: "save code" → Befehl: git-commit
0.3 – 0.5	Mittelmäßige Übereinstimmung	Prompt: "update repo" → Befehl: git-pull
0.0 – 0.3	Schwache Übereinstimmung	Prompt: "hello world" → Befehl: git-commit

⚠️

Score ist relativ

Der Score hängt von der Länge des Prompts ab. Ein langer Prompt mit vielen Tokens kann nie einen perfekten Score erreichen, selbst wenn alle relevanten Keywords enthalten sind. Betrachte den Score immer im Kontext der anderen Ergebnisse.

🔍

Anwendung

Praktische Beispiele

Konkrete Routing-Szenarien und ihre Ergebnisse.

Hier sind vier typische Routing-Szenarien, die zeigen, wie der Algorithmus verschiedene Prompts verarbeitet.

Beispiel 1: Git-Operation

🔎 Prompt

"Erstelle einen neuen Branch für das Login-Feature"

✅ Top-Matches

1. git-branch — Score: 0.67 ("git", "branch", "create")
2. git-checkout — Score: 0.33 ("branch")
3. Bash — Score: 0.22 ("create")

Beispiel 2: Datei-Operation

🔎 Prompt

"Lies den Inhalt der package.json Datei"

✅ Top-Matches

1. Read — Score: 0.80 ("read", "file")
2. Grep — Score: 0.40 ("file")
3. Glob — Score: 0.40 ("file", "json")

Beispiel 3: Code-Analyse

🔎 Prompt

"Analysiere die Codebasis nach Fehlern"

✅ Top-Matches

1. parity-audit — Score: 0.50 ("code", "audit")
2. summary — Score: 0.50 ("code", "analyze")
3. Grep — Score: 0.40 ("search", "code")

Beispiel 4: Mehrdeutiger Prompt

🔎 Prompt

"commit"

✅ Top-Matches

1. git-commit — Score: 1.00 (exakter Match)
2. git-push — Score: 0.00 (verwandt, aber kein Token-Match)
3. Bash — Score: 0.00

💡

Bessere Ergebnisse durch präzisere Prompts

Je spezifischer der Prompt, desto besser das Routing. Statt "commit" lieber "commit changes to git" verwenden, um Verwechslungen zu vermeiden und den gewünschten Kontext zu liefern.

🖥️

CLI

route-Befehl verwenden

Interaktives Testen des Routing-Algorithmus.

Der route-Befehl ermöglicht es, den Routing-Algorithmus direkt zu testen und zu verstehen, wie Prompts verarbeitet werden.

Grundlegende Verwendung

bash

# Einen Prompt routen
$ python3 -m src.main route "Erstelle einen neuen Branch"

Routed Matches (Top 10):

1. [COMMAND] git-branch — Score: 0.67
Tokens matched: git, branch, create

2. [TOOL] Bash — Score: 0.33
Tokens matched: create

3. [COMMAND] git-checkout — Score: 0.33
Tokens matched: branch

Optionen und Parameter

Parameter	Beschreibung	Standard
`--limit N`	Anzahl der zurückgegebenen Matches	10
`--min-score 0.X`	Minimaler Score für Ergebnisse	0.0
`--json`	Ausgabe als JSON	false
`--no-tools`	Nur Befehle zurückgeben	false
`--no-commands`	Nur Tools zurückgeben	false

Erweiterte Beispiele

bash

# Limit auf 5 Ergebnisse setzen
$ python3 -m src.main route "Lies die Datei" --limit 5

# Nur Befehle, kein Tool-Routing
$ python3 -m src.main route "Speichern" --no-tools

# JSON-Ausgabe für Weiterverarbeitung
$ python3 -m src.main route "Analyse" --json | jq '.matches[0]'

# Minimaler Score von 0.5
$ python3 -m src.main route "commit" --min-score 0.5

Debugging mit dem route-Befehl

Der route-Befehl ist ein wertvolles Werkzeug zum Debugging:

Warum wurde ein Befehl nicht gefunden? → Prüfe die Token-Überschneidung
Wie kann ich den Score verbessern? → Füge Keywords aus Name/Source/Responsibility hinzu
Welche Befehle sind für ein Thema verfügbar? → Teste mit generischen Prompts

bash

# Alle git-bezogenen Befehle finden
$ python3 -m src.main route "git" --no-tools --limit 20

1. git-branch — Score: 1.00
2. git-commit — Score: 1.00
3. git-checkout — Score: 1.00
4. git-push — Score: 1.00
5. git-pull — Score: 1.00
...

✅

Pro-Tipp: Routing in Scripts verwenden

Nutze die --json-Option, um Routing-Ergebnisse in Shell-Scripts oder andere Programme zu integrieren. Die JSON-Ausgabe enthält alle Metadaten zu den Matches.

🎓

Zusammenfassung

Wichtigste Konzepte

Die Schlüsselelemente des Prompt-Routing im Überblick.

🔄

4-Phasen-Algorithmus

Tokenisierung → Scoring → Fair-Share → Auffüllung

🧮

Token-basiertes Matching

Normalisierung und Mengen-Operationen für robuste Übereinstimmung

⚖️

Fair-Share-Prinzip

Jede Kategorie (Commands, Tools) ist garantiert vertreten

📏

Score 0.0 – 1.0

Relative Übereinstimmung basierend auf Token-Schnittmenge

🎉

Du verstehst jetzt Prompt-Routing!

Mit diesem Wissen kannst du effektivere Prompts formulieren, das System debuggen und eigene Routing-Strategien entwickeln. Probiere den route-Befehl mit verschiedenen Prompts aus, um das Verhalten zu erkunden.

← Zurück zur Übersicht Nächstes Kapitel →