Pi Agent Kontextverwaltung

Kontextverwaltung ist eine Kernkompetenz für die effiziente Nutzung von Pi Agent.

Dieses Kapitel erklärt, wie du das Verhalten der KI über Umgebungsdateien steuerst und wie du den Gesprächskontext verwaltest.

Übersicht über Kontextdateien

Pi Agent lädt beim Start automatisch Projektanweisungsdateien, sodass die KI deine Projektkonventionen, Befehle und Präferenzen versteht.

Diese Dateien sagen der KI, "wie in diesem Projekt gearbeitet wird."

AGENTS.md / CLAUDE.md

Dies sind die wichtigsten Kontextdateien für Pi Agent, geladen in der folgenden Reihenfolge:

  1. ~/.pi/agent/AGENTS.md- Globale Anweisungen, wirksam für alle Projekte
  2. AGENTS.md oder CLAUDE.md in übergeordneten Verzeichnissen ausgehend vom aktuellen Verzeichnis nach oben durchsuchen
  3. AGENTS.md oder CLAUDE.md im aktuellen Verzeichnis

Das Folgende istAGENTS.mdein vollständiges Beispiel, das im Projektstammverzeichnis abgelegt wird:

Beispiel

# Projektanweisungen

## Codestandards
- Der gesamte Code verwendet den TypeScript-Strict-Modus
- Funktionen müssen Rückgabetyp-Annotationen haben
- ESLint und Prettier verwenden, um den Code-Stil konsistent zu halten

## Arbeitsablauf
- `npm run check` ausführen, um nach Codeänderungen zu prüfen
- `npm test` vor dem Commit ausführen, um sicherzustellen, dass die Tests bestehen
- Führen Sie Produktions-Datenbankmigrationen nicht direkt auf Ihrem lokalen Rechner aus

## Sicherheitshinweise
- Schreiben Sie keine API-Schlüssel oder Passwörter in den Code
- Verwenden Sie Umgebungsvariablen für sensible Konfiguration

## Antwortstil
- Halten Sie Antworten prägnant und erklären Sie offensichtlichen Code nicht übermäßig
- Wenn Probleme auftreten, liefern Sie zuerst eine Lösung und erklären Sie dann die Ursache

Nach dem Aktualisieren von AGENTS.md verwenden Sie den Befehl/reloadzum Hot Reload; Pi Agent muss nicht neu gestartet werden.

Wenn Sie sowohl AGENTS.md als auch CLAUDE.md haben, lädt Pi Agent zuerst AGENTS.md.

Wenn Sie zuvor Claude Code verwendet haben, können Sie Ihre vorhandene CLAUDE.md direkt wiederverwenden.

Wenn AGENTS.override.md in einem Verzeichnis vorhanden ist, wird es anstelle der AGENTS.md und CLAUDE.md dieses Verzeichnisses geladen.

Um das Laden von Kontextdateien zu deaktivieren, verwenden Sie das Befehlszeilenargument:

$ pi --no-context-files
$ pi -nc   # 短形式

SYSTEM.md

SYSTEM.md wird verwendet, um den Standard-System-Prompt von Pi Agent vollständig zu ersetzen. Wenn Sie nur Inhalte anhängen möchten, verwenden Sie stattdessen APPEND_SYSTEM.md.

Beide haben eine globale und eine Projektebene, mit Pfaden und Auswirkungen wie folgt:

DateiStufeWirkung
~/.pi/agent/SYSTEM.mdGlobalErsetzt den Standard-System-Prompt
Projektstammverzeichnis/.pi/SYSTEM.mdProjektErsetzt den Standard-System-Prompt
~/.pi/agent/APPEND_SYSTEM.mdGlobalHängt nach dem Standard-System-Prompt an
Projektstammverzeichnis/.pi/APPEND_SYSTEM.mdProjektHängt nach dem Standard-System-Prompt an

In den meisten Fällen müssen Sie den System-Prompt nicht ändern.

AGENTS.md kann bereits den Großteil des Anpassungsbedarfs abdecken.

SYSTEM.md eignet sich für Szenarien, die eine tiefgehende Anpassung des KI-Verhaltens erfordern; unsachgemäße Änderungen können die Leistung der KI beeinträchtigen.

Kontextkomprimierung

Wenn eine Konversation sehr lang wird, füllt sich das Kontextfenster der KI allmählich.

Pi Agent löst dies durch Kontextkomprimierung – er fasst frühere Gesprächsinhalte automatisch zu einer kurzen Zusammenfassung zusammen und gibt so Kontextspeicher frei.

上下文压缩循环：消息追加、接近阈值、自动摘要、折叠早期消息

Automatische Komprimierung

Standardmäßig löst Pi Agent die Komprimierung automatisch aus, wenn der Kontext sich dem Modelllimit nähert.

Das Komprimierungsverhalten wird durch die Komprimierungskonfiguration in~/.pi/agent/settings.jsongesteuert:

Beispiel

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}
KonfigurationselementTypeStandardwertBeschreibung
compaction.enabledbooleschwahrOb die automatische Komprimierung aktiviert werden soll
compaction.reserveTokensnumber16384Anzahl der für LLM-Antworten reservierten Tokens
compaction.keepRecentTokensnumber20000Anzahl der neuesten Tokens, die unkomprimiert beibehalten werden

Die Auslösebedingung ist, wenn die Kontext-Token den verfügbaren Platz überschreiten, nachdem reserveTokens von contextWindow subtrahiert wurde.

Die Prüfung erfolgt nach Abschluss jeder Tool-Ausführung und bevor der nächste Benutzer-Prompt gesendet wird.

Manuelle Kompaktierung

Sie können die Kompaktierung auch jederzeit manuell auslösen:

/compact

Beim Kompaktieren können Sie benutzerdefinierte Anweisungen hinzufügen, um der KI mitzuteilen, worauf sie beim Zusammenfassen achten soll:

/compact 重点关注错误修复和 API 变更

Die Kompaktierung ist nur für den aktuellen Gesprächskontext irreversibel.

Die komprimierten Originalnachrichten sind weiterhin vollständig in der Sitzungsdatei erhalten. Verwenden Sie /tree, um zum Knoten vor der Kompaktierung zurückzuspringen, um Details abzurufen.

Wenn Sie vor der Kompaktierung ein vollständiges Backup behalten möchten, wird /clone empfohlen.

/clone kopiert den aktuellen aktiven Branch vollständig in eine neue Sitzungsdatei, geeignet als Backup vor der Kompaktierung.

/fork startet nur von einer bestimmten historischen Benutzernachricht aus, und Inhalte danach werden nicht in die neue Sitzung übernommen.

Anzeige des Inferenzprozesses

Modelle, die Reasoning-Ausgabe unterstützen, denken vor der Antwort nach.

Sie können die Anzeige des Reasoning-Prozesses über die folgenden Einstellungen steuern:

EinstellungTypeStandardwertBeschreibung
hideThinkingBlockbooleschfalseDen Reasoning-Prozess ausblenden und nur die endgültige Antwort anzeigen
showCacheMissNoticesbooleschfalseCache-Miss-Hinweise anzeigen und auch Token-Nutzungshinweise anzeigen, die durch Kompaktierung und Branch-Zusammenfassungen erzeugt werden

Verwenden SieCtrl+T, um die Anzeige des Reasoning-Prozesses jederzeit während der Unterhaltung ein- oder auszublenden.

Hot Reload (/reload)

Ob Sie nach dem Ändern der Konfiguration neu starten müssen, hängt davon ab, was Sie geändert haben.

Die folgende Tabelle fasst zusammen, wie gängige Änderungen wirksam werden. Bei Einträgen, die mit "Nein" markiert sind, führen Sie einfach /reload aus:

ÄnderungNeustart erforderlich?Beschreibung
AGENTS.md oder CLAUDE.md (Kontextdateien)neinSofort nach dem Ausführen von /reload neu laden
ErweiterungenneinSofort nach dem Ausführen von /reload neu laden
SkillsneinSofort nach dem Ausführen von /reload neu laden
Prompt-VorlagenneinSofort nach dem Ausführen von /reload neu laden
Theme-DateienneinSofort nach dem Ausführen von /reload neu laden
Tastaturkürzel-KonfigurationneinSofort nach dem Ausführen von /reload neu laden
Einige Einstellungen in ~/.pi/agent/settings.jsonJaEinige Konfiguration wird beim Start einmal eingelesen
Neu installierte ErweiterungspaketeJaPaketabhängigkeiten werden beim Start aufgelöst
auth.json-AnmeldedatenJaAnmeldedaten werden beim Start geladen

Kontextnutzung anzeigen

Die untere Statusleiste zeigt die Token-Nutzung und die Kosten des aktuellen Kontexts in Echtzeit an.

Verwenden Sie den/sessionBefehl, um detailliertere Informationen anzuzeigen:

/session

Beispielausgabe:

Session file: ~/.pi/agent/sessions/--Users-example-projects-example-demo--/2026-08-30T09-15-04-000Z_019fbb5d-7a2e-7f31-b5c4-1a2b3c4d5e6f.jsonl
Session ID:   abc123-def456
Messages:     42
Tokens:       85,432
Cost:         $0.52
Current model: claude-sonnet-4-20250514
Weitere Erweiterungen