Come funziona il checkpointing
Quando abiliti il checkpointing dei file, l’SDK crea backup dei file prima di modificarli tramite gli strumenti Write, Edit o NotebookEdit. I messaggi dell’utente nel flusso di risposta includono un UUID di checkpoint che puoi utilizzare come punto di ripristino.Il ripristino dei file ripristina i file su disco a uno stato precedente. Non ripristina la conversazione stessa. La cronologia della conversazione e il contesto rimangono intatti dopo la chiamata a
rewindFiles() (TypeScript) o rewind_files() (Python).RewindFilesResult conta ogni percorso saltato nel suo campo skippedLinks. Il salto richiede Claude Code v2.1.216 o successivo; prima di v2.1.216, un ripristino scriveva ed eliminava attraverso i link nei percorsi tracciati.
Implementare il checkpointing
Per utilizzare il checkpointing dei file, abilitalo nelle tue opzioni, acquisisci gli UUID di checkpoint dal flusso di risposta, quindi chiamarewindFiles() (TypeScript) o rewind_files() (Python) quando hai bisogno di ripristinare.
Gli esempi in questa sezione utilizzano il prompt “Refactor the authentication module”. Eseguili in un progetto che contiene un modulo di autenticazione, oppure modifica il prompt per nominare file che esistono nel tuo progetto, in modo da poter osservare i file cambiare e vedere il ripristino ripristinarli.
Questo esempio abilita il checkpointing, acquisisce l’UUID di checkpoint e l’ID di sessione dal flusso di risposta, quindi riprende la sessione in seguito per ripristinare i file. I commenti numerati dell’esempio corrispondono ai passaggi che seguono.
1
Abilita il checkpointing
Configura le opzioni dell’SDK per abilitare il checkpointing e ricevere gli UUID di checkpoint:
L’esempio principale in Implementare il checkpointing imposta anche la modalità di autorizzazione su
acceptEdits, che approva le modifiche ai file dell’agente senza un prompt. Per ulteriori informazioni, vedi Modalità di autorizzazione.2
Acquisisci l'UUID di checkpoint e l'ID di sessione
Con l’opzione
replay-user-messages impostata, ogni messaggio dell’utente nel flusso di risposta ha un UUID che funge da checkpoint.Per la maggior parte dei casi d’uso, acquisisci il primo UUID del messaggio dell’utente (message.uuid); il ripristino ad esso ripristina tutti i file al loro stato originale. Per archiviare più checkpoint e ripristinare a stati intermedi, vedi Più punti di ripristino.L’acquisizione dell’ID di sessione (message.session_id) è facoltativa; ne hai bisogno solo se vuoi ripristinare in seguito, dopo il completamento del flusso. Se stai chiamando rewindFiles() immediatamente mentre stai ancora elaborando i messaggi (come fa l’esempio in Checkpoint prima di operazioni rischiose), puoi saltare l’acquisizione dell’ID di sessione.3
Ripristina i file
Per ripristinare dopo il completamento del flusso, riprendi la sessione con un prompt vuoto e chiama Il flag
rewind_files() (Python) o rewindFiles() (TypeScript) con il tuo UUID di checkpoint. Abilita il checkpointing anche sulle opzioni della sessione ripresa e chiama il ripristino dall’interno del ciclo di risposta. Puoi anche ripristinare durante il flusso. Vedi Checkpoint prima di operazioni rischiose per quel modello.Se acquisisci l’ID di sessione e l’ID di checkpoint, puoi anche ripristinare dalla CLI. Questo comando richiede l’eseguibile claude, che proviene da installazione di Claude Code. L’SDK abilita il checkpointing per te, ma quando esegui claude -p direttamente devi impostare la variabile di ambiente CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING:--rewind-files non appare nell’output di claude --help, ma la CLI lo accetta come mostrato. Quando il ripristino ha successo, il comando stampa Files rewound to state at message <checkpoint-uuid> e esce senza inviare un prompt.Modelli comuni
Questi modelli mostrano diversi modi per acquisire e utilizzare gli UUID di checkpoint a seconda del tuo caso d’uso.Checkpoint prima di operazioni rischiose
Questo modello mantiene solo l’UUID di checkpoint più recente, aggiornandolo prima di ogni turno dell’agente. Se qualcosa va storto durante l’elaborazione, puoi immediatamente ripristinare all’ultimo stato sicuro e uscire dal ciclo. Prima di eseguire questo esempio, sostituisciyour_revert_condition (Python) o yourRevertCondition (TypeScript) con il tuo controllo personale, come il rilevamento di errori o un errore di convalida; il segnaposto non è definito nell’esempio.
Più punti di ripristino
Se Claude effettua modifiche su più turni, potresti voler ripristinare a un punto specifico piuttosto che all’inizio. Ad esempio, se Claude effettua il refactoring di un file nel turno uno e aggiunge test nel turno due, potresti voler mantenere il refactoring ma annullare i test. Questo modello archivia tutti gli UUID di checkpoint in un array con metadati. Dopo il completamento della sessione, puoi ripristinare a qualsiasi checkpoint precedente:Prova
Questo esempio completo crea un piccolo file di utilità, fa aggiungere all’agente commenti di documentazione, ti mostra le modifiche, quindi ti chiede se vuoi ripristinare. Prima di iniziare, assicurati di avere Claude Agent SDK installato.1
Crea un file di test
Crea un nuovo file chiamato
utils.py (Python) o utils.ts (TypeScript) e incolla il seguente codice:2
Esegui l'esempio interattivo
Crea un nuovo file chiamato
try_checkpointing.py (Python) o try_checkpointing.ts (TypeScript) nella stessa directory del tuo file di utilità e incolla il seguente codice.Questo script chiede a Claude di aggiungere commenti doc al tuo file di utilità, quindi ti dà la possibilità di ripristinare e ripristinare l’originale.3
Esegui l'esempio
Esegui lo script dalla stessa directory del tuo file di utilità.Vedrai l’agente aggiungere commenti doc, quindi un prompt che ti chiede se vuoi ripristinare. Se scegli sì, il file viene ripristinato al suo stato originale.
- Python
- TypeScript
Limitazioni
Il checkpointing dei file ha le seguenti limitazioni:Troubleshooting
Le opzioni di checkpointing non vengono riconosciute
SeenableFileCheckpointing o rewindFiles() non sono disponibili, potresti essere su una versione SDK più vecchia.
Soluzione: Aggiorna alla versione SDK più recente:
- Python:
pip install --upgrade claude-agent-sdk - TypeScript:
npm install @anthropic-ai/claude-agent-sdk@latest
I messaggi dell’utente non hanno UUID
Semessage.uuid è undefined o mancante, non stai ricevendo gli UUID di checkpoint.
Causa: L’opzione replay-user-messages non è impostata.
Soluzione: Aggiungi extra_args={"replay-user-messages": None} (Python) o extraArgs: { 'replay-user-messages': null } (TypeScript) alle tue opzioni.
Errore “No file checkpoint found for this message”
Questo errore si verifica quando i dati di checkpoint non esistono per l’UUID del messaggio dell’utente specificato. Cause comuni:- Il checkpointing dei file non era abilitato sulla sessione originale (
enable_file_checkpointingoenableFileCheckpointingnon era impostato sutrue) - La sessione non è stata completata correttamente prima di tentare di riprendere e ripristinare
enable_file_checkpointing=True (Python) o enableFileCheckpointing: true (TypeScript) fosse impostato sulla sessione originale, quindi utilizza il modello mostrato negli esempi: acquisisci il primo UUID del messaggio dell’utente, completa la sessione completamente, quindi riprendi con un prompt vuoto e chiama rewindFiles() una volta.
Errore “File rewinding is not enabled”
Questo errore si verifica quando tenti un rewind non interattivo senza checkpointing abilitato: eseguire il bareclaude -p con --rewind-files, o eseguire una sessione SDK, inclusa una ripresa, le cui opzioni non abilitano il checkpointing. L’SDK imposta la variabile di ambiente CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING internamente solo quando enable_file_checkpointing (Python) o enableFileCheckpointing (TypeScript) è abilitato sulla sessione che esegue il rewind; il bare CLI non la imposta mai.
Soluzione: Per il bare CLI, imposta la variabile di ambiente quando esegui il comando:
enable_file_checkpointing=True (Python) o enableFileCheckpointing: true (TypeScript) sulla sessione ripresa, come fanno gli esempi su questa pagina.
Errore “ProcessTransport is not ready for writing”
Questo errore si verifica quando chiamirewindFiles() o rewind_files() dopo aver terminato l’iterazione attraverso la risposta. La connessione al processo CLI si chiude quando il ciclo si completa.
Soluzione: Riprendi la sessione con un prompt vuoto, quindi chiama rewind sulla nuova query. L’esempio principale sotto Implement checkpointing mostra la chiamata resume-and-rewind in entrambi i linguaggi, al commento contrassegnato Step 3.
Passaggi successivi
- Sessions: scopri come riprendere le sessioni, che è obbligatorio per il ripristino dopo il completamento del flusso. Copre gli ID di sessione, la ripresa delle conversazioni e il forking delle sessioni.
- Permissions: configura quali strumenti Claude può utilizzare e come vengono approvate le modifiche ai file. Utile se vuoi più controllo su quando avvengono le modifiche.
- TypeScript SDK reference: riferimento API completo incluse tutte le opzioni per
query()e il metodorewindFiles(). - Python SDK reference: riferimento API completo incluse tutte le opzioni per
ClaudeAgentOptionse il metodorewind_files().