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.
| Befehl | Funktion | Anwendungsfall |
|---|---|---|
| /resume | Historische Sessions durchsuchen und fortsetzen | Zu einer vorherigen Konversation wechseln und weiterarbeiten |
| /new | Eine neue Sitzung starten | Eine brandneue Aufgabe starten, die nichts mit dem Verlauf zu tun hat |
| /name <name> | Sitzungsnamen festlegen | Der Sitzung einen leicht zu merkenden Namen geben |
| /session | Sitzungsinformationen anzeigen | Dateipfad, Nachrichtenanzahl, Token-Nutzung und Kosten anzeigen |
| /tree | Den Sitzungsbaum-Browser öffnen | Zu einem beliebigen Knoten im Konversationsbaum springen |
| /fork | Sitzung forken | Eine neue Sitzung aus einer vorherigen Benutzernachricht erstellen |
| /clone | Sitzung klonen | Den aktuell aktiven Zweig in eine neue Sitzungsdatei kopieren |
| /export <file> | Als HTML- oder JSONL-Datei exportieren | Lokale Archivierung oder Offline-Freigabe |
| /share | Sitzung teilen | Als 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:
| Aktion | Taste | Beschreibung |
|---|---|---|
| Sitzungen filtern | Zeichen direkt eingeben | Die Sitzungsliste des aktuellen Projekts in Echtzeit anhand der Eingabe filtern |
| Pfadanzeige umschalten | Ctrl+P | Arbeitsverzeichnispfad der Sitzungen anzeigen oder ausblenden |
| Sortierung umschalten | Ctrl+S | Zwischen Sortiermethoden wechseln |
| Nur benannte Sitzungen anzeigen | Ctrl+N | Auf Sitzungen filtern, die benannt wurden |
| Umbenennen | Ctrl+R | Namen der ausgewählten Sitzung ändern |
| Delete | Ctrl+D | Vor 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.
| Aktion | Tastenkürzel | Beschreibung |
|---|---|---|
| Nach oben/unten bewegen | ↑/↓ | Cursor zwischen sichtbaren Einträgen bewegen |
| Bild auf/ab | ←/→ | Bild auf / Bild ab |
| Einklappen/Ausklappen | Ctrl+←/Ctrl+→ oder Alt+←/Alt+→ | Zweigsegmente einklappen/ausklappen oder springen |
| Label festlegen | Shift+L | Label für den ausgewählten Knoten festlegen |
| Zeitstempel umschalten | Shift+T | Zeitstempel für Eintrags-Labels ein-/ausblenden (Labels werden mit Shift+L festgelegt) |
| Auswahl bestätigen | Enter | Aktuellen Knoten auswählen |
| Cancel | Escape / Ctrl+C | Den Tree-Browser beenden |
| Filtermodus umschalten | Ctrl+O | Durch 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.
| Mode | Angezeigter Inhalt |
|---|---|
| default | Standardansicht, klappt Tool-Aufrufdetails ein |
| no-tools | Alle Tool-Aufrufe und Ergebnisse ausblenden |
| user-only | Nur Benutzernachrichten anzeigen |
| Nur beschriftete | Nur beschriftete Einträge anzeigen |
| all | Alle 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.
| Befehl | Ausgabe | View | Typische Verwendung | Branch-Zusammenfassung | Ein-Satz-Merkhilfe |
|---|---|---|---|---|---|
| /tree | Gleiche Sitzungsdatei | Vollständiger Gesprächsbaum | Alternative Ansätze innerhalb derselben Sitzung erkunden | Optionale Zusammenfassung | Mehrere Ideen zusammen verwalten für einen einfachen Vergleich |
| /fork | Neue Sitzungsdatei | Nur Benutzernachrichten anzeigen | Neue Sitzung aus einem früheren Prompt starten | Keine | Von einem historischen Punkt aus neu starten, vollständig unabhängig |
| /clone | Neue Sitzungsdatei | Aktueller aktiver Branch | Aktuelle Arbeit kopieren und fortfahren | Keine | Vor 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:
| Mode | Verhalten | Anwendungsfall |
|---|---|---|
| Keine Zusammenfassung generiert | Direkt springen, ohne jegliche Informationen über den aufgegebenen Branch zu behalten | Der aufgegebene Versuch hat keinen erhaltenswerten Wert |
| Standardzusammenfassung | Verwende den Standard-Prompt, damit die KI den verworfenen Branch zusammenfasst | Nur eine grobe Vorstellung davon haben, was zuvor gemacht wurde |
| Benutzerdefinierte Zusammenfassung | Gib den Fokus an, und die KI fasst entsprechend deinen Bedürfnissen zusammen | Bestimmte 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)
Weitere ErweiterungenWenn 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.