- Unerwünschte Änderungen rückgängig machen, indem Sie Dateien in einen bekannten guten Zustand zurücksetzen
- Alternativen erkunden, indem Sie zu einem Checkpoint zurückkehren und einen anderen Ansatz versuchen
- Von Fehlern wiederherstellen, wenn der Agent fehlerhafte Änderungen vornimmt
Wie Checkpointing funktioniert
Wenn Sie File Checkpointing aktivieren, erstellt das SDK Sicherungen von Dateien, bevor diese durch die Tools Write, Edit oder NotebookEdit geändert werden. Benutzermeldungen im Response-Stream enthalten eine Checkpoint-UUID, die Sie als Wiederherstellungspunkt verwenden können. Checkpointing funktioniert mit diesen integrierten Tools, die der Agent zum Ändern von Dateien verwendet:| Tool | Beschreibung |
|---|---|
| Write | Erstellt eine neue Datei oder überschreibt eine vorhandene Datei mit neuem Inhalt |
| Edit | Nimmt gezielte Änderungen an bestimmten Teilen einer vorhandenen Datei vor |
| NotebookEdit | Ändert Zellen in Jupyter-Notebooks (.ipynb-Dateien) |
File Rewinding stellt Dateien auf der Festplatte in einen vorherigen Zustand wieder her. Es setzt das Gespräch selbst nicht zurück. Der Gesprächsverlauf und der Kontext bleiben nach dem Aufrufen von
rewindFiles() (TypeScript) oder rewind_files() (Python) intakt.- Dateien, die während der Sitzung erstellt wurden
- Dateien, die während der Sitzung geändert wurden
- Den ursprünglichen Inhalt geänderter Dateien
Checkpointing implementieren
Um File Checkpointing zu verwenden, aktivieren Sie es in Ihren Optionen, erfassen Sie Checkpoint-UUIDs aus dem Response-Stream und rufen SierewindFiles() (TypeScript) oder rewind_files() (Python) auf, wenn Sie Dateien wiederherstellen müssen.
Das folgende Beispiel zeigt den vollständigen Ablauf: Aktivieren Sie Checkpointing, erfassen Sie die Checkpoint-UUID und Session-ID aus dem Response-Stream, und setzen Sie die Sitzung später fort, um Dateien zurückzuspulen. Jeder Schritt wird unten im Detail erläutert.
Checkpointing aktivieren
Konfigurieren Sie Ihre SDK-Optionen, um Checkpointing zu aktivieren und Checkpoint-UUIDs zu erhalten:
| Option | Python | TypeScript | Beschreibung |
|---|---|---|---|
| Checkpointing aktivieren | enable_file_checkpointing=True | enableFileCheckpointing: true | Verfolgt Dateiänderungen zum Zurückspulen |
| Checkpoint-UUIDs erhalten | extra_args={"replay-user-messages": None} | extraArgs: { 'replay-user-messages': null } | Erforderlich, um Benutzermeldungs-UUIDs im Stream zu erhalten |
Checkpoint-UUID und Session-ID erfassen
Mit der oben gezeigten Option
replay-user-messages hat jede Benutzermeldung im Response-Stream eine UUID, die als Checkpoint dient.Für die meisten Anwendungsfälle erfassen Sie die UUID der ersten Benutzermeldung (message.uuid); das Zurückspulen zu ihr stellt alle Dateien in ihren ursprünglichen Zustand wieder her. Um mehrere Checkpoints zu speichern und zu Zwischenzuständen zurückzuspulen, siehe Mehrere Wiederherstellungspunkte.Das Erfassen der Session-ID (message.session_id) ist optional; Sie benötigen sie nur, wenn Sie später zurückspulen möchten, nachdem der Stream abgeschlossen ist. Wenn Sie rewindFiles() sofort aufrufen, während Sie noch Meldungen verarbeiten (wie das Beispiel in Checkpoint vor riskanten Operationen zeigt), können Sie das Erfassen der Session-ID überspringen.Dateien zurückspulen
Um nach Abschluss des Streams zurückzuspulen, setzen Sie die Sitzung mit einer leeren Eingabeaufforderung fort und rufen Sie Wenn Sie die Session-ID und Checkpoint-ID erfassen, können Sie auch von der CLI aus zurückspulen:
rewind_files() (Python) oder rewindFiles() (TypeScript) mit Ihrer Checkpoint-UUID auf. Sie können auch während des Streams zurückspulen; siehe Checkpoint vor riskanten Operationen für dieses Muster.Häufige Muster
Diese Muster zeigen verschiedene Möglichkeiten, Checkpoint-UUIDs je nach Ihrem Anwendungsfall zu erfassen und zu verwenden.Checkpoint vor riskanten Operationen
Dieses Muster behält nur die neueste Checkpoint-UUID, aktualisiert sie vor jedem Agent-Turn. Wenn während der Verarbeitung etwas schief geht, können Sie sofort zum letzten sicheren Zustand zurückspulen und die Schleife unterbrechen.Mehrere Wiederherstellungspunkte
Wenn Claude Änderungen über mehrere Turns hinweg vornimmt, möchten Sie möglicherweise zu einem bestimmten Punkt zurückspulen, anstatt ganz nach hinten zu gehen. Wenn Claude beispielsweise eine Datei in Turn eins umgestaltet und Tests in Turn zwei hinzufügt, möchten Sie möglicherweise die Umgestaltung behalten, aber die Tests rückgängig machen. Dieses Muster speichert alle Checkpoint-UUIDs in einem Array mit Metadaten. Nach Abschluss der Sitzung können Sie zu jedem vorherigen Checkpoint zurückspulen:Ausprobieren
Dieses vollständige Beispiel erstellt eine kleine Utility-Datei, lässt den Agent Dokumentationskommentare hinzufügen, zeigt Ihnen die Änderungen und fragt dann, ob Sie zurückspulen möchten. Bevor Sie beginnen, stellen Sie sicher, dass Sie das Claude Agent SDK installiert haben.Testdatei erstellen
Erstellen Sie eine neue Datei namens
utils.py (Python) oder utils.ts (TypeScript) und fügen Sie den folgenden Code ein:Interaktives Beispiel ausführen
Erstellen Sie eine neue Datei namens Dieses Beispiel demonstriert den vollständigen Checkpointing-Workflow:
try_checkpointing.py (Python) oder try_checkpointing.ts (TypeScript) im selben Verzeichnis wie Ihre Utility-Datei und fügen Sie den folgenden Code ein.Dieses Skript fordert Claude auf, Dokumentationskommentare zu Ihrer Utility-Datei hinzuzufügen, und gibt Ihnen dann die Möglichkeit, zurückzuspulen und das Original wiederherzustellen.- Checkpointing aktivieren: Konfigurieren Sie das SDK mit
enable_file_checkpointing=Trueundpermission_mode="acceptEdits", um Dateiänderungen automatisch zu genehmigen - Checkpoint-Daten erfassen: Während der Agent läuft, speichern Sie die UUID der ersten Benutzermeldung (Ihr Wiederherstellungspunkt) und die Session-ID
- Zur Rückspulung auffordern: Nachdem der Agent fertig ist, überprüfen Sie Ihre Utility-Datei, um die Dokumentationskommentare zu sehen, und entscheiden Sie dann, ob Sie die Änderungen rückgängig machen möchten
- Sitzung fortsetzen und zurückspulen: Wenn ja, setzen Sie die Sitzung mit einer leeren Eingabeaufforderung fort und rufen Sie
rewind_files()auf, um die ursprüngliche Datei wiederherzustellen
Beispiel ausführen
Führen Sie das Skript aus dem selben Verzeichnis wie Ihre Utility-Datei aus.Sie sehen, dass der Agent Dokumentationskommentare hinzufügt, dann eine Eingabeaufforderung, die fragt, ob Sie zurückspulen möchten. Wenn Sie ja wählen, wird die Datei in ihren ursprünglichen Zustand zurückgesetzt.
- Python
- TypeScript
Einschränkungen
File Checkpointing hat die folgenden Einschränkungen:| Einschränkung | Beschreibung |
|---|---|
| Nur Write/Edit/NotebookEdit-Tools | Änderungen, die durch Bash-Befehle vorgenommen werden, werden nicht verfolgt |
| Gleiche Sitzung | Checkpoints sind an die Sitzung gebunden, die sie erstellt hat |
| Nur Dateiinhalt | Das Erstellen, Verschieben oder Löschen von Verzeichnissen wird durch Zurückspulen nicht rückgängig gemacht |
| Lokale Dateien | Remote- oder Netzwerkdateien werden nicht verfolgt |
Troubleshooting
Checkpointing-Optionen nicht erkannt
WennenableFileCheckpointing oder rewindFiles() nicht verfügbar ist, verwenden Sie möglicherweise eine ältere SDK-Version.
Lösung: Aktualisieren Sie auf die neueste SDK-Version:
- Python:
pip install --upgrade claude-agent-sdk - TypeScript:
npm install @anthropic-ai/claude-agent-sdk@latest
Benutzermeldungen haben keine UUIDs
Wennmessage.uuid undefined oder fehlend ist, erhalten Sie keine Checkpoint-UUIDs.
Ursache: Die Option replay-user-messages ist nicht gesetzt.
Lösung: Fügen Sie extra_args={"replay-user-messages": None} (Python) oder extraArgs: { 'replay-user-messages': null } (TypeScript) zu Ihren Optionen hinzu.
Fehler „No file checkpoint found for message”
Dieser Fehler tritt auf, wenn die Checkpoint-Daten für die angegebene Benutzermeldungs-UUID nicht vorhanden sind. Häufige Ursachen:- File Checkpointing war in der ursprünglichen Sitzung nicht aktiviert (
enable_file_checkpointingoderenableFileCheckpointingwar nicht auftruegesetzt) - Die Sitzung wurde nicht vollständig abgeschlossen, bevor versucht wurde, sie fortzusetzen und zurückzuspulen
enable_file_checkpointing=True (Python) oder enableFileCheckpointing: true (TypeScript) in der ursprünglichen Sitzung gesetzt war, verwenden Sie dann das in den Beispielen gezeigte Muster: Erfassen Sie die UUID der ersten Benutzermeldung, schließen Sie die Sitzung vollständig ab, setzen Sie sie dann mit einer leeren Eingabeaufforderung fort und rufen Sie rewindFiles() einmal auf.
Fehler „ProcessTransport is not ready for writing”
Dieser Fehler tritt auf, wenn SierewindFiles() oder rewind_files() aufrufen, nachdem Sie die Iteration durch die Antwort abgeschlossen haben. Die Verbindung zum CLI-Prozess wird geschlossen, wenn die Schleife abgeschlossen ist.
Lösung: Setzen Sie die Sitzung mit einer leeren Eingabeaufforderung fort und rufen Sie dann rewind auf der neuen Abfrage auf:
Nächste Schritte
- Sessions: Erfahren Sie, wie Sie Sitzungen fortsetzen, was zum Zurückspulen nach Abschluss des Streams erforderlich ist. Behandelt Session-IDs, Fortsetzen von Gesprächen und Session-Forking.
- Berechtigungen: Konfigurieren Sie, welche Tools Claude verwenden kann und wie Dateiänderungen genehmigt werden. Nützlich, wenn Sie mehr Kontrolle darüber haben möchten, wann Änderungen vorgenommen werden.
- TypeScript SDK-Referenz: Vollständige API-Referenz einschließlich aller Optionen für
query()und die MethoderewindFiles(). - Python SDK-Referenz: Vollständige API-Referenz einschließlich aller Optionen für
ClaudeAgentOptionsund die Methoderewind_files().