Pi Agent Sitzungsverwaltung

Das Sitzungsverwaltungssystem von Pi Agent ist eine seiner leistungsstärksten Funktionen.

Dieses Kapitel beschreibt detailliert das Speichern, Fortsetzen, Verzweigen und Exportieren von Sitzungen.


Mechanismus der Sitzungsspeicherung

Jede Konversation wird automatisch als Sitzungsdatei im JSONL-Format gespeichert, abgelegt in~/.pi/agent/sessions/einem nach Projektpfad kategorisierten Verzeichnis.

Der Verzeichnisname wird vom absoluten Pfad des Projekts abgeleitet: Schrägstriche werden durch Bindestriche ersetzt, und er wird beidseitig mit -- umschlossen.

Der Dateiname wird durch Verkettung des Erstellungszeitstempels und der Sitzungs-UUID gebildet.

Intern ist jede Sitzung als Baumstruktur organisiert – das bedeutet, du kannst an jedem historischen Knoten abzweigen, ohne vorherigen Gesprächsinhalt zu verlieren.

~/.pi/agent/sessions/
└── --Users-example-projects-example-demo--/        # 目录名为项目路径,斜杠已替换为连字符
    ├── 2026-08-31T02-40-11-000Z_019fc2a1-93b4-7c22-8d5e-2b3c4d5e6f7a.jsonl    # 时间戳_UUID.jsonl
    ├── 2026-08-31T04-12-38-000Z_2c8f71ba-4a19-4e63-9d02-7f5a6b8c9d0e.jsonl
    └── 2026-08-31T08-55-02-000Z_5e3d92f4-8b26-47ac-a174-9c0d1e2f3a4b.jsonl

Interne Struktur von Session-Dateien

Die erste Zeile einer Session-Datei besteht aus festen Metadaten, die die Session-Formatversion, die Session-ID, den Erstellungszeitpunkt und das Arbeitsverzeichnis erfassen.

Diese Metadaten besitzen keine id- und parentId-Felder und nehmen nicht am Konversationsbaum teil.

Ab der zweiten Zeile ist jede Zeile ein Eintrag, alle mit id- und parentId-Feldern, die zusammen die Baumstruktur bilden.

Zu den Eintragstypen gehören message, compaction, branch_summary, label, custom usw.

Durch /fork oder /clone erstellte Sessions haben in den Metadaten der ersten Zeile zusätzlich ein parentSession-Feld, das auf die ursprüngliche Session-Datei verweist.

{"type":"session","version":3,"id":"019fc2a1-93b4-7c22-8d5e-2b3c4d5e6f7a","timestamp":"2026-08-31T02:40:11.000Z","cwd":"/Users/example/projects/example-demo"}
{"type":"message","id":"m1","parentId":null,"message":{"role":"user","content":[{"type":"text","text":"帮我实现登录功能"}]}}
{"type":"message","id":"m2","parentId":"m1","message":{"role":"assistant","content":[{"type":"text","text":"好的,我用 JWT 来实现"}]}}

Das Session-Verzeichnis kann ebenfalls angepasst werden; die Priorität von hoch nach niedrig ist: das Argument --session-dir, die UmgebungsvariablePI_CODING_AGENT_SESSION_DIRund die in settings.jsonsessionDir。


Session-Optionen beim Start

Steuern Sie das Session-Verhalten beim Start über Kommandozeilenargumente:

$ pi -c
Resumed session abc123-def456 (42 messages, model claude-sonnet-4-5)

$ pi -r
┌ 选择要恢复的会话:
│ > abc123  快速审查      3 分钟前
│   def456  重构认证模块  2 小时前
└

$ pi --session ~/.pi/agent/sessions/--Users-example-projects-example-demo--/2026-08-30T09-15-04-000Z_019fbb5d-7a2e-7f31-b5c4-1a2b3c4d5e6f.jsonl
Resumed session 019fbb5d-7a2e-7f31-b5c4-1a2b3c4d5e6f

$ pi --session abc123
Resumed session abc123-def456

$ pi --fork abc123
Forked to session 9f2e7a01-5c48

$ pi --name "重构认证模块"
Session renamed: 重构认证模块

$ pi --no-session
Temporary session (will not be saved)

Befehle zur Sitzungsverwaltung

Sobald Sie sich im interaktiven Modus befinden, decken die folgenden Befehle die tägliche Verwaltung von Sessions ab.

BefehlFunktionAnwendungsfall
/resumeHistorische Sessions durchsuchen und fortsetzenZu einer vorherigen Konversation wechseln und weiterarbeiten
/newEine neue Sitzung startenEine brandneue Aufgabe starten, die nichts mit dem Verlauf zu tun hat
/name <name>Sitzungsnamen festlegenDer Sitzung einen leicht zu merkenden Namen geben
/sessionSitzungsinformationen anzeigenDateipfad, Nachrichtenanzahl, Token-Nutzung und Kosten anzeigen
/treeDen Sitzungsbaum-Browser öffnenZu einem beliebigen Knoten im Konversationsbaum springen
/forkSitzung forkenEine neue Sitzung aus einer vorherigen Benutzernachricht erstellen
/cloneSitzung klonenDen aktuell aktiven Zweig in eine neue Sitzungsdatei kopieren
/export <file>Als HTML- oder JSONL-Datei exportierenLokale Archivierung oder Offline-Freigabe
/shareSitzung teilenAls GitHub Gist hochladen und dabei einen teilbaren Link generieren

/resume Sitzungsauswahl

Die Eingabe von /resume oder der Start mit pi -r öffnet die Sitzungsauswahl für das aktuelle Projekt.

Sie können Zeichen direkt in die Liste eingeben, um Sitzungen zu filtern; die übrigen Bedienungstasten sind wie folgt:

AktionTasteBeschreibung
Sitzungen filternZeichen direkt eingebenDie Sitzungsliste des aktuellen Projekts in Echtzeit anhand der Eingabe filtern
Pfadanzeige umschaltenCtrl+PArbeitsverzeichnispfad der Sitzungen anzeigen oder ausblenden
Sortierung umschaltenCtrl+SZwischen Sortiermethoden wechseln
Nur benannte Sitzungen anzeigenCtrl+NAuf Sitzungen filtern, die benannt wurden
UmbenennenCtrl+RNamen der ausgewählten Sitzung ändern
DeleteCtrl+DVor der Ausführung bestätigen; wenn das System den trash-Befehl hat, wird statt direktem Löschen in den Papierkorb verschoben.

Sitzungsbaum (/tree)

Dies ist die einzigartigste Funktion von Pi Agent – Sitzungen werden als Baumstruktur gespeichert, und Sie können an jedem historischen Knoten abzweigen.

Baumstruktur

Im Folgenden sehen Sie eine typische Sitzungsbaumstruktur:

├─ user: "帮我实现一个登录功能..."
│  └─ assistant: "好的,我来实现..."
│     ├─ user: "用 JWT 方案..."
│     │  └─ assistant: "使用 JWT 实现..."
│     │     └─ user: "测试通过了"  ← 当前活跃分支
│     └─ user: "还是用 Session 方案..."
│        └─ assistant: "使用 Session 实现..."

In diesem Beispiel haben Sie ausgehend vom selben Ursprung zwei Ansätze erkundet, JWT und Session, und die Gespräche für jeden Ansatz sind vollständig erhalten.

Baum-Browser-Operationen

Nach dem Öffnen von /tree verwenden Sie die folgenden Tasten, um sich im Baum zu bewegen und auszuwählen.

AktionTastenkürzelBeschreibung
Nach oben/unten bewegen↑/↓Cursor zwischen sichtbaren Einträgen bewegen
Bild auf/ab←/→Bild auf / Bild ab
Einklappen/AusklappenCtrl+←/Ctrl+→ oder Alt+←/Alt+→Zweigsegmente einklappen/ausklappen oder springen
Label festlegenShift+LLabel für den ausgewählten Knoten festlegen
Zeitstempel umschaltenShift+TZeitstempel für Eintrags-Labels ein-/ausblenden (Labels werden mit Shift+L festgelegt)
Auswahl bestätigenEnterAktuellen Knoten auswählen
CancelEscape / Ctrl+CDen Tree-Browser beenden
Filtermodus umschaltenCtrl+ODurch Filtermodi wechseln (nur im /tree-Browser wirksam)

Filtermodi

Filtermodi bestimmen, welche Einträge im Tree-Browser angezeigt werden; drücken Sie Ctrl+O, um durch sie zu wechseln.

ModeAngezeigter Inhalt
defaultStandardansicht, klappt Tool-Aufrufdetails ein
no-toolsAlle Tool-Aufrufe und Ergebnisse ausblenden
user-onlyNur Benutzernachrichten anzeigen
Nur beschrifteteNur beschriftete Einträge anzeigen
allAlle Einträge anzeigen

Wenn Sie eine Benutzernachricht auswählen, wird ihr Text in den Editor eingefügt, sodass Sie sie bearbeiten und erneut senden können, wodurch ein neuer Branch erstellt wird.

Wenn Sie eine KI-Antwort oder einen Tool-Aufruf auswählen, springen Sie direkt zu dieser Position, sodass Sie das Gespräch von dort aus fortsetzen können.


Unterschiede zwischen /tree, /fork und /clone

Alle drei können zu einer historischen Position zurückkehren; der Unterschied liegt darin, ob eine neue Sitzungsdatei erstellt wird und wie viel der Konversation sichtbar ist.

BefehlAusgabeViewTypische VerwendungBranch-ZusammenfassungEin-Satz-Merkhilfe
/treeGleiche SitzungsdateiVollständiger GesprächsbaumAlternative Ansätze innerhalb derselben Sitzung erkundenOptionale ZusammenfassungMehrere Ideen zusammen verwalten für einen einfachen Vergleich
/forkNeue SitzungsdateiNur Benutzernachrichten anzeigenNeue Sitzung aus einem früheren Prompt startenKeineVon einem historischen Punkt aus neu starten, vollständig unabhängig
/cloneNeue SitzungsdateiAktueller aktiver BranchAktuelle Arbeit kopieren und fortfahrenKeineVor dem Fortfahren eine Kopie erstellen und einen Fallback behalten

Branch-Zusammenfassung

Wenn du über /tree von einem Branch zu einem anderen springst, kann Pi Agent eine Zusammenfassung des aufgegebenen Branches für dich erstellen.

Diese Zusammenfassung wird an der neuen Position angehängt, damit du weißt, was der vorherige Branch getan hat:

ModeVerhaltenAnwendungsfall
Keine Zusammenfassung generiertDirekt springen, ohne jegliche Informationen über den aufgegebenen Branch zu behaltenDer aufgegebene Versuch hat keinen erhaltenswerten Wert
StandardzusammenfassungVerwende den Standard-Prompt, damit die KI den verworfenen Branch zusammenfasstNur eine grobe Vorstellung davon haben, was zuvor gemacht wurde
Benutzerdefinierte ZusammenfassungGib den Fokus an, und die KI fasst entsprechend deinen Bedürfnissen zusammenBestimmte Schlussfolgerungen mitnehmen möchten, wie z. B. aufgetretene Fallstricke

Du kannst das Zusammenfassungsverhalten in~/.pi/agent/settings.jsonsteuern:

Beispiel

{
  "branchSummary": {
    "reserveTokens": 16384,
    "skipPrompt": false
  }
}

EinstellungskipPromptauf true setzen, um den Prompt "ob eine Zusammenfassung generiert werden soll" beim Navigieren mit /tree zu überspringen.

Nach Überspringen der Aufforderung wird standardmäßig keine Zusammenfassung generiert, und es springt direkt zur Zielposition.


Sitzungen exportieren und teilen

Sitzungen können als lokale Dateien exportiert oder direkt hochgeladen werden, um einen Freigabelink zu erzeugen.

Als HTML exportieren

Der Export erzeugt eine Seite als einzelne Datei, die direkt in einem Browser geöffnet werden kann und für die Offline-Ansicht geeignet ist.

# 导出到默认位置
/export

# 导出到指定文件
/export ~/Desktop/my-session.html

Als GitHub Gist teilen

Wenn du keine Dateien hochladen möchtest, verwende den Befehl /share, um einen Online-Link zu erzeugen.

/share

Nach der Ausführung wird ein privater GitHub Gist erstellt und ein teilbarer HTML-Link generiert.

Kommandozeilen-Export

Bestehende Sitzungen können exportiert werden, ohne in den interaktiven Modus zu wechseln.

$ pi --export session.jsonl output.html
Exported to output.html (128 KB)

Wenn du an einem Open-Source-Projekt arbeitest und Sitzungen zu Forschungszwecken veröffentlichen möchtest, kannst du dirpi-share-hfansehen, ein Tool, das Sitzungen in Hugging Face-Datasets veröffentlichen kann.

Weitere Erweiterungen