- 撤銷不需要的變更,透過將檔案還原到已知的良好狀態
- 探索替代方案,透過還原到 checkpoint 並嘗試不同的方法
- 從錯誤中恢復,當代理程式進行不正確的修改時
checkpointing 如何運作
當您啟用檔案 checkpointing 時,SDK 會在透過 Write、Edit 或 NotebookEdit 工具修改檔案之前建立檔案備份。回應串流中的使用者訊息包含一個 checkpoint UUID,您可以將其用作還原點。 Checkpoint 適用於代理程式用來修改檔案的這些內建工具:檔案回溯將磁碟上的檔案還原到先前的狀態。它不會回溯對話本身。呼叫
rewindFiles()(TypeScript)或 rewind_files()(Python)後,對話歷史記錄和上下文保持不變。- 在工作階段期間建立的檔案
- 在工作階段期間修改的檔案
- 修改檔案的原始內容
實現 checkpointing
若要使用檔案 checkpointing,請在您的選項中啟用它,從回應串流中捕捉 checkpoint UUID,然後在需要還原時呼叫rewindFiles()(TypeScript)或 rewind_files()(Python)。
以下範例顯示完整流程:啟用 checkpointing、從回應串流中捕捉 checkpoint UUID 和工作階段 ID,然後稍後恢復工作階段以回溯檔案。下面詳細說明每個步驟。本節中的範例使用提示「重構驗證模組」。在包含驗證模組的專案中執行它們,或變更提示以命名您專案中存在的檔案,以便您可以觀看檔案變更並查看回溯如何還原它們。
1
啟用 checkpointing
配置您的 SDK 選項以啟用 checkpointing 並接收 checkpoint UUID:
2
捕捉 checkpoint UUID 和工作階段 ID
設定
replay-user-messages 選項後(如上所示),回應串流中的每個使用者訊息都有一個 UUID,可作為 checkpoint。對於大多數使用案例,捕捉第一個使用者訊息 UUID(message.uuid);回溯到它會將所有檔案還原到其原始狀態。若要儲存多個 checkpoint 並回溯到中間狀態,請參閱多個還原點。捕捉工作階段 ID(message.session_id)是可選的;只有在您想要稍後回溯(在串流完成後)時才需要它。如果您在仍在處理訊息時立即呼叫 rewindFiles()(如在危險操作前進行 checkpoint 中的範例所做的),您可以跳過捕捉工作階段 ID。3
回溯檔案
若要在串流完成後回溯,請使用空提示恢復工作階段,並使用您的 checkpoint UUID 呼叫 如果您捕捉了工作階段 ID 和 checkpoint ID,您也可以從 CLI 回溯。此命令需要
rewind_files()(Python)或 rewindFiles()(TypeScript)。您也可以在串流期間回溯;請參閱在危險操作前進行 checkpoint 以了解該模式。claude 可執行檔,該檔案來自安裝 Claude Code,並且不是由 SDK 套件安裝的。SDK 為您啟用 checkpointing,但當您直接執行 claude -p 時,您必須設定 CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING 環境變數:--rewind-files 旗標不會出現在 claude --help 輸出中,但 CLI 會如上所示接受它。常見模式
這些模式顯示根據您的使用案例捕捉和使用 checkpoint UUID 的不同方式。在危險操作前進行 checkpoint
此模式只保留最新的 checkpoint UUID,在每個代理程式轉向前更新它。如果在處理期間出現問題,您可以立即回溯到最後的安全狀態並跳出迴圈。 執行此範例前,請將your_revert_condition(Python)或 yourRevertCondition(TypeScript)替換為您自己的檢查,例如錯誤偵測或驗證失敗;此範例中未定義預留位置。
多個還原點
如果 Claude 在多個轉向中進行變更,您可能想要回溯到特定點而不是一直回到開始。例如,如果 Claude 在第一個轉向中重構檔案,在第二個轉向中新增測試,您可能想要保留重構但撤銷測試。 此模式將所有 checkpoint UUID 儲存在具有中繼資料的陣列中。工作階段完成後,您可以回溯到任何先前的 checkpoint:試試看
此完整範例建立一個小型公用程式檔案,讓代理程式新增文件註解,向您顯示變更,然後詢問您是否想要回溯。 開始之前,請確保您已安裝 Claude Agent SDK。1
建立測試檔案
建立一個名為
utils.py(Python)或 utils.ts(TypeScript)的新檔案,並貼上以下程式碼:2
執行互動式範例
在與您的公用程式檔案相同的目錄中建立一個名為 此範例演示完整的 checkpointing 工作流程:
try_checkpointing.py(Python)或 try_checkpointing.ts(TypeScript)的新檔案,並貼上以下程式碼。此指令碼要求 Claude 將文件註解新增到您的公用程式檔案,然後為您提供回溯和還原原始檔案的選項。- 啟用 checkpointing:使用
enable_file_checkpointing=True和permission_mode="acceptEdits"配置 SDK 以自動批准檔案編輯 - 捕捉 checkpoint 資料:當代理程式執行時,儲存第一個使用者訊息 UUID(您的還原點)和工作階段 ID
- 提示回溯:代理程式完成後,檢查您的公用程式檔案以查看文件註解,然後決定是否要撤銷變更
- 恢復和回溯:如果是,請使用空提示恢復工作階段,並呼叫
rewind_files()以還原原始檔案
3
執行範例
從與您的公用程式檔案相同的目錄執行指令碼。您會看到代理程式新增文件註解,然後出現一個提示,詢問您是否想要回溯。如果您選擇是,檔案會還原到其原始狀態。
- Python
- TypeScript
限制
檔案 checkpointing 有以下限制:疑難排解
Checkpointing 選項無法識別
如果enableFileCheckpointing 或 rewindFiles() 無法使用,您可能使用的是較舊的 SDK 版本。
解決方案:更新到最新的 SDK 版本:
- Python:
pip install --upgrade claude-agent-sdk - TypeScript:
npm install @anthropic-ai/claude-agent-sdk@latest
使用者訊息沒有 UUID
如果message.uuid 是 undefined 或遺失,您沒有接收 checkpoint UUID。
原因:未設定 replay-user-messages 選項。
解決方案:將 extra_args={"replay-user-messages": None}(Python)或 extraArgs: { 'replay-user-messages': null }(TypeScript)新增到您的選項。
“No file checkpoint found for message” 錯誤
當指定的使用者訊息 UUID 的 checkpoint 資料不存在時,會發生此錯誤。 常見原因:- 檔案 checkpointing 未在原始工作階段上啟用(
enable_file_checkpointing或enableFileCheckpointing未設定為true) - 在嘗試恢復和回溯之前,工作階段未正確完成
enable_file_checkpointing=True(Python)或 enableFileCheckpointing: true(TypeScript),然後使用範例中顯示的模式:捕捉第一個使用者訊息 UUID,完全完成工作階段,然後使用空提示恢復並呼叫 rewindFiles() 一次。
“File rewinding is not enabled” 錯誤
當您嘗試在未啟用 checkpointing 的情況下執行非互動式回溯時,會發生此錯誤:執行裸露的claude -p 搭配 --rewind-files,或執行 SDK 工作階段(包括已恢復的工作階段),其選項未啟用 checkpointing。SDK 僅在執行回溯的工作階段上啟用 enable_file_checkpointing(Python)或 enableFileCheckpointing(TypeScript)時,才會在內部設定 CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING 環境變數;裸露 CLI 永遠不會設定它。
解決方案:對於裸露 CLI,在執行命令時設定環境變數:
enable_file_checkpointing=True(Python)或 enableFileCheckpointing: true(TypeScript),如本頁面的範例所示。
“ProcessTransport is not ready for writing” 錯誤
當您在完成回應迭代後呼叫rewindFiles() 或 rewind_files() 時,會發生此錯誤。當迴圈完成時,與 CLI 程序的連線會關閉。
解決方案:使用空提示恢復工作階段,然後在新查詢上呼叫回溯:
後續步驟
- Sessions:了解如何恢復工作階段,這是在串流完成後回溯所需的。涵蓋工作階段 ID、恢復對話和工作階段分叉。
- Permissions:配置 Claude 可以使用哪些工具以及如何批准檔案修改。如果您想更好地控制何時進行編輯,這很有用。
- TypeScript SDK reference:完整的 API 參考,包括
query()的所有選項和rewindFiles()方法。 - Python SDK reference:完整的 API 參考,包括
ClaudeAgentOptions的所有選項和rewind_files()方法。