Pi Agent Theme-Anpassung
Pi Agent unterstützt die Anpassung der Farben der Terminal-Oberfläche.
Dieses Kapitel behandelt, wie man integrierte Themes verwendet und benutzerdefinierte Themes erstellt.
Theme-Übersicht
Pi Agent verwendet Theme-Dateien im JSON-Format, um alle Farben in der TUI-Oberfläche zu definieren.
Jedes Theme muss51 erforderliche Tokens + 4 optionale Tokens (thinkingMax, scrollbarThumb, searchMatchBg, searchMatchText)definieren, die Farben für verschiedene Oberflächenelemente wie Kern-UI, Nachrichtenhintergründe, Markdown-Darstellung, Syntaxhervorhebung und Editor-Ränder abdecken.
Integrierte Themes
Pi Agent wird mit zwei integrierten Themes geliefert:
| Theme-Name | Anwendungsfall | Beschreibung |
|---|---|---|
| dark | Dunkler Terminalhintergrund (Standard) | Geeignet für dunkle Terminals, die von den meisten Entwicklern verwendet werden |
| light | Heller Terminalhintergrund | Geeignet für Terminals mit hellen Themes |
Beim ersten Start erkennt Pi Agent automatisch die Hintergrundfarbe deines Terminals und wählt dark oder light aus.
Gib im interaktiven Modus /settings ein und wechsle direkt in den Theme-Optionen:
/settings
Du kannst auch das Feld theme in settings.json schreiben und den Wert von theme auf den Theme-Namen ändern:
Beispiel
"theme": "light"
}
Benutzerdefinierte Themes erstellen
Erstellen Sie zuerst das Theme-Verzeichnis und die Datei:
mkdir -p ~/.pi/agent/themes vim ~/.pi/agent/themes/my-theme.json
Definieren Sie dann die Theme-Datei. Das Folgende ist ein vollständiges Beispiel für ein benutzerdefiniertes Theme:
Beispiel
"name": "my-theme",
"vars": {
"blue": "#0066cc",
"gray": 242,
"orange": "#ffaa00",
"green": "#0055AA"
},
"colors": {
"accent": "blue",
"border": "blue",
"borderAccent": "#00ffff",
"borderMuted": "gray",
"success": "green",
"error": "#ff0000",
"warning": "#ffff00",
"muted": "gray",
"dim": 240,
"text": "",
"thinkingText": "gray",
"selectedBg": "#2d2d30",
"userMessageBg": "#2d2d30",
"userMessageText": "",
"customMessageBg": "#2d2d30",
"customMessageText": "",
"customMessageLabel": "blue",
"toolPendingBg": "#1e1e2e",
"toolSuccessBg": "#1e2e1e",
"toolErrorBg": "#2e1e1e",
"toolTitle": "blue",
"toolOutput": "",
"mdHeading": "orange",
"mdLink": "blue",
"mdLinkUrl": "gray",
"mdCode": "#00ffff",
"mdCodeBlock": "",
"mdCodeBlockBorder": "gray",
"mdQuote": "gray",
"mdQuoteBorder": "gray",
"mdHr": "gray",
"mdListBullet": "#00ffff",
"toolDiffAdded": "green",
"toolDiffRemoved": "#ff0000",
"toolDiffContext": "gray",
"syntaxComment": "gray",
"syntaxKeyword": "blue",
"syntaxFunction": "#00aaff",
"syntaxVariable": "orange",
"syntaxString": "green",
"syntaxNumber": "#ff00ff",
"syntaxType": "#00aaff",
"syntaxOperator": "blue",
"syntaxPunctuation": "gray",
"thinkingOff": "gray",
"thinkingMinimal": "blue",
"thinkingLow": "#00aaff",
"thinkingMedium": "#00ffff",
"thinkingHigh": "#ff00ff",
"thinkingXhigh": "#ff0000",
"thinkingMax": "#ff0088",
"bashMode": "orange"
}
}
Aktiviere dann dein Theme in settings.json:
Beispiel
"theme": "my-theme"
}
Wenn du die aktuell verwendete benutzerdefinierte Theme-Datei bearbeitest, lädt Pi Agent das Theme automatisch per Hot-Reload neu, sodass du Änderungen sofort ohne weiteres Zutun siehst.
Ladeorte für Theme-Dateien
Pi Agent sucht Theme-Dateien an den folgenden Orten.
Themes, die an unterschiedlichen Orten abgelegt werden, haben unterschiedliche Sichtbarkeitsbereiche und Ladebedingungen.
| Ort | Geltungsbereich |
|---|---|
| Integriert | dark, light immer verfügbar |
| ~/.pi/agent/themes/*.json | Globale Themes, für alle Projekte verfügbar |
| .pi/themes/*.json | Projektthemen, die erst geladen werden, nachdem dem Projekt vertraut wurde |
| Pi-Pakete | themes/-Verzeichnis im Paket |
| --theme path | Vorübergehend über die Kommandozeile geladen |
Farbwertformate
Pi Agent unterstützt vier Farbwertformate:
| Format | Beispiel | Beschreibung |
|---|---|---|
| Hex-Farbe | "#ff0000" | 6-stellige hexadezimale RGB-Farbe |
| 256-Farben-Palette | 39 | xterm-256-Farben-Palette-Index (0-255) |
| Variablenreferenz | "blue" | Verweist auf eine in vars definierte Variable |
| Terminal-Standardfarbe | "" | Verwendet die Standard-Vordergrund-/Hintergrundfarbe des Terminals |
Der Abschnitt vars wird verwendet, um wiederverwendbare Farbvariablen zu definieren, auf die in colors namentlich verwiesen wird.
Nachdem die Primärfarben in Variablen extrahiert wurden, erfordert eine Änderung des Farbschemas nur die Bearbeitung an einer Stelle, was die Pflege des Themes erleichtert.
Farb-Token-Kategorien
Jedes Token in colors entspricht der Farbe einer Kategorie von Elementen in der Oberfläche.
Nachfolgend sind alle Token nach Zweck in sechs Kategorien unterteilt, um das Nachschlagen zu erleichtern.
Kern-UI (11)
Diese Gruppe steuert die Farben grundlegender Oberflächenelemente wie Editor und Statusleiste.
| Token | Zweck |
|---|---|
| accent | Primärfarbe (Logo, ausgewählte Elemente, Cursor) |
| border | Normaler Rahmen |
| borderAccent | Hervorhebungsrahmen |
| borderMuted | Weicher Rahmen für den Editorbereich |
| Erfolg | Erfolgsstatus |
| error | Fehlerstatus |
| warning | Warnstatus |
| muted | Sekundärtext |
| dim | Tertiärtext (noch weniger hervorgehoben) |
| text | Standardtextfarbe (normalerweise leer gelassen) |
| thinkingText | Text des KI-Schlussfolgerungsprozesses |
Hintergrund & Inhalt (11 erforderlich + 3 optional)
Diese Gruppe steuert den Hintergrund und den Text von ausgewählten Elementen, Nachrichtenblasen und Tool-Ausgabebereichen.
| Token | Zweck |
|---|---|
| selectedBg | Hintergrund des ausgewählten Elements (aktueller Eintrag in der Liste) |
| userMessageBg | Hintergrund der Benutzernachricht |
| userMessageText | Text der Benutzernachricht |
| customMessageBg | Hintergrund der erweiterten Nachricht |
| customMessageText | Text der erweiterten Nachricht |
| customMessageLabel | Titel-Tag-Farbe für erweiterte Nachrichten |
| toolPendingBg | Hintergrund während der Tool-Ausführung |
| toolSuccessBg | Hintergrund bei erfolgreicher Tool-Ausführung |
| toolErrorBg | Hintergrund bei fehlgeschlagener Tool-Ausführung |
| toolTitle | Titeltext der Tool-Karte |
| toolOutput | Tool-Ausgabetext |
| scrollbarThumb | Farbe des Scrollbar-Daumens im Vollbildmodus (optional, fällt auf selectedBg zurück, wenn nicht definiert) |
| searchMatchBg | Hintergrund für Suchtreffer (optional, fällt auf selectedBg zurück, wenn nicht definiert) |
| searchMatchText | Text für Suchtreffer (optional, fällt auf text zurück, wenn nicht definiert) |
Markdown-Darstellung (10)
Diese Gruppe steuert die Farben der Markdown-Elemente in KI-Antworten.
| Token | Zweck |
|---|---|
| mdHeading | Überschrift |
| mdLink | Linktext |
| mdLinkUrl | Link-URL-Adresse |
| mdCode | Inline-Code |
| mdCodeBlock | Codeblock-Inhalt |
| mdCodeBlockBorder | Codeblock-Rahmen |
| mdQuote | Blockzitat-Text |
| mdQuoteBorder | Blockzitat-Rahmen |
| mdHr | Trennlinie |
| mdListBullet | Listenmarker |
Syntaxhervorhebung (9)
Diese Gruppe steuert die Farben der Syntaxhervorhebung innerhalb von Codeblöcken.
| Token | Zweck |
|---|---|
| syntaxComment | Kommentar |
| syntaxKeyword | Schlüsselwort |
| syntaxFunction | Funktionsname |
| syntaxVariable | Variablenname |
| syntaxString | String |
| syntaxNumber | Number |
| syntaxType | Type |
| syntaxOperator | Operator |
| syntaxPunctuation | Interpunktion |
Rahmen der Reasoning-Stufen (7)
Diese Gruppe steuert die Indikatorfarbe der aktuellen Reasoning-Stufe am Editor-Rand.
| Token | Entsprechende Stufe |
|---|---|
| thinkingOff | Reasoning aus |
| thinkingMinimal | Minimales Reasoning |
| thinkingLow | Geringes Reasoning |
| thinkingMedium | Mittleres Reasoning |
| thinkingHigh | Hohes Reasoning |
| thinkingXhigh | Extrahohes Reasoning |
| thinkingMax | Maximales Reasoning (optional) |
thinkingMax ist ein optionales Token. Wenn es nicht definiert ist, wird auf die Farbe von thinkingXhigh zurückgegriffen.
Diff & Bash-Farben (4)
Diese Gruppe steuert die Diff-Hervorhebung und die Prompt-Farben im Bash-Modus — diejenigen, die Sie beim Bearbeiten von Code am häufigsten sehen.
| Token | Zweck |
|---|---|
| toolDiffAdded | Hinzugefügte Diff-Zeilen (normalerweise grün) |
| toolDiffRemoved | Entfernte Diff-Zeilen (normalerweise rot) |
| toolDiffContext | Diff-Kontextzeilen (dezent halten) |
| bashMode | Prompt-Farbe im Bash-Modus |
HTML-Exportfarben
Wenn Sie /export verwenden, um eine Sitzung als HTML zu exportieren, können Sie im Theme Farben für die exportierte Seite definieren:
Beispiel
"export": {
"pageBg": "#18181e",
"cardBg": "#1e1e24",
"infoBg": "#3c3728"
}
}
Wenn die Exportkonfiguration weggelassen wird, leitet die exportierte Seite Farben automatisch von userMessageBg ab.
Tipps zur Theme-Erstellung
Die folgenden Tipps helfen dabei, dass sich dein benutzerdefiniertes Theme in verschiedenen Terminals konsistent verhält.
- Dunkle Terminals: Verwende helle, gesättigte Farben mit ausreichend hohem Kontrast
- Helle Terminals: Verwende tiefere, weichere Farben; der Kontrast kann entsprechend verringert werden
- Farbharmonie: Orientiere dich an ausgereiften Farbschemata wie Nord, Gruvbox und Tokyo Night als Grundlage
- Gründlich testenStelle die korrekte Darstellung über verschiedene Nachrichtentypen, Tool-Zustände, Markdown-Inhalte und langen Textumbruch hinweg sicher