Sessions 保持對話,而不是檔案系統。要快照和還原代理所做的檔案更改,請使用檔案檢查點。
resume 和 fork,以及關於跨主機恢復 sessions 的注意事項。
選擇一個方法
您需要多少 session 處理取決於您的應用程式的形狀。當您發送應該共享上下文的多個提示時,session 管理就會發揮作用。在單個query() 呼叫中,代理已經根據需要進行了盡可能多的轉換,並且權限提示和 AskUserQuestion 是在迴圈中處理的(它們不會結束呼叫)。
Continue、resume 和 fork
Continue、resume 和 fork 是您在query() 上設定的選項欄位(Python 中的 ClaudeAgentOptions,TypeScript 中的 Options)。
Continue 和 resume 都會拾取現有 session 並將其添加到其中。區別在於它們如何找到該 session:
- Continue 在當前目錄中找到最近的 session。您無需追蹤任何內容。當您的應用一次運行一個對話時效果很好。
- Resume 採用特定的 session ID。您追蹤 ID。當您有多個 sessions(例如,多使用者應用中每個使用者一個)或想要返回不是最近的 session 時需要。
自動工作階段管理
兩個 SDK 都提供了一個介面,可以為您跨呼叫追蹤工作階段狀態,因此您不需要手動傳遞 ID。將這些用於單一程序內的多輪對話。Python:ClaudeSDKClient
ClaudeSDKClient 在內部處理工作階段 ID。每次呼叫 client.query() 都會自動繼續同一工作階段。呼叫 client.receive_response() 以逐一查看目前查詢的訊息。將用戶端用作非同步內容管理器,以便為您處理連線設定和清除,或手動呼叫 connect() 和 disconnect()。
此範例針對同一 client 執行兩個查詢。第一個要求代理程式分析一個模組;第二個要求它重構該模組。因為兩個呼叫都通過同一用戶端執行個體,第二個查詢具有來自第一個查詢的完整內容,無需任何明確的 resume 或工作階段 ID:
Python
[done: success, cost: $0.0042]。
如需有關何時使用 ClaudeSDKClient 與獨立 query() 函式的詳細資訊,請參閱 Python SDK 參考。
TypeScript:continue: true
TypeScript SDK 沒有像 Python 的 ClaudeSDKClient 這樣的工作階段保持用戶端物件。相反,在每個後續 query() 呼叫上傳遞 continue: true,SDK 會在目前目錄中選取最近的工作階段。無需 ID 追蹤。
此範例進行兩個單獨的 query() 呼叫。第一個建立新的工作階段;第二個設定 continue: true,這會告訴 SDK 在磁碟上尋找並繼續最近的工作階段。代理程式具有來自第一個呼叫的完整內容:
TypeScript
實驗性 V2 工作階段 API(提供了具有
send / stream 模式的 createSession())已在 TypeScript Agent SDK 0.3.142 中移除。改用 query() 函式和本頁面上描述的工作階段選項。使用 session 選項與 query()
捕獲 session ID
Resume 和 fork 需要 session ID。從結果訊息上的session_id 欄位讀取它(Python 中的 ResultMessage,TypeScript 中的 SDKResultMessage),無論成功或錯誤,它都存在於每個結果上。在 TypeScript 中,ID 也可以作為初始化 SystemMessage 上的直接欄位更早獲得;在 Python 中,它嵌套在 SystemMessage.data 內。
Session ID: 5b3f2c1a-8d4e-4f6b-9a7c-2e1d0f9b8a6c。在接下來的章節中,您將此 ID 傳遞給 resume。
按 ID 恢復
將 session ID 傳遞給resume 以返回到該特定 session。代理從 session 中斷的任何地方拾取完整上下文。恢復的常見原因:
- 跟進已完成的任務。 代理已經分析了某些內容;現在您希望它根據該分析採取行動,而無需重新讀取文件。
- 從限制中恢復。 第一次運行以
error_max_turns或error_max_budget_usd結束(請參閱處理結果);以更高的限制恢復。在單次query()呼叫中,SDK 會在產生該錯誤結果後引發異常,因此在恢復前捕獲錯誤。 - 重新啟動您的進程。 您在關閉前捕獲了 ID,並想恢復對話。
SessionStore 適配器將記錄鏡像到共享存儲。
Fork 以探索替代方案
Forking 創建一個新 session,從原始 session 的歷史副本開始,但從該點開始分歧。fork 獲得自己的 session ID;原始的 ID 和歷史保持不變。您最終得到兩個獨立的 sessions,可以分別恢復。Forking 分支對話歷史,而不是文件系統。如果 forked 代理編輯文件,這些更改是真實的,對在同一目錄中工作的任何 session 都可見。要分支和還原文件更改,請使用文件檢查點。
session_id 中分析了一個 auth 模組,並想探索 OAuth2 而不失去 JWT 焦點的線程。第一個塊 forks session 並捕獲 fork 的 ID(forked_id);第二個塊恢復原始 session_id 以繼續沿著 JWT 路徑。您現在有兩個 session ID 指向兩個單獨的歷史:
forkedId 與原始 session ID 不同。恢復原始 session 仍然會繼續 JWT 線程,這確認了 fork 沒有修改原始歷史。
跨主機恢復
Session 文件是創建它們的機器的本地文件。要在不同的主機上恢復 session(CI 工作者、臨時容器、無伺服器),請選擇適合的方法:-
傳遞 session 存放區。 附加一個
sessionStore/session_store配接器,以便 SDK 將記錄鏡像到您自己的後端,另一個主機可以恢復它們。存放區查詢鍵衍生自工作目錄,因此請從與原始執行的cwd相符的目錄恢復。 -
移動 session 文件。 從第一次執行中保持
~/.claude/projects/<encoded-cwd>/<session-id>.jsonl,並在呼叫resume之前將其還原到新主機上~/.claude/projects/下的任何目錄內。 Claude Code 會搜尋超出目前專案目錄的範圍來尋找 ID;請參閱恢復 session 以了解確切的查詢順序以及如何處理重複副本。在 v2.1.223 之前,查詢範圍限於目前專案目錄及其 git worktrees;捆綁較舊 CLI 的 SDK 版本仍然以這種方式運作。 - 不依賴 session 恢復。 捕獲您需要的結果(分析輸出、決定、文件差異)作為應用程式狀態,並將其傳遞到新 session 的提示中。這通常比運送記錄文件更穩健。
listSessions() 和 getSessionMessages(),Python 中的 list_sessions() 和 get_session_messages()。使用它們構建自訂 session 選擇器、清理邏輯或記錄檢視器。
兩個 SDK 也公開用於查找和變更個別 sessions 的函數:Python 中的 get_session_info()、rename_session() 和 tag_session(),以及 TypeScript 中的 getSessionInfo()、renameSession() 和 tagSession()。使用它們按標籤組織 sessions 或給它們人類可讀的標題。
相關資源
- 代理迴圈如何工作:了解 session 中的轉換、訊息和上下文累積
- 文件檢查點:快照和還原代理在 session 中所做的文件更改
- Python
ClaudeAgentOptions:Python 的完整 session 選項參考 - TypeScript
Options:TypeScript 的完整 session 選項參考