Skip to main content
Session 是 SDK 在您的代理工作時累積的對話歷史。它包含您的提示、代理進行的每個工具呼叫、每個工具結果和每個回應。SDK 會自動將其寫入磁碟,以便您稍後可以返回它。 返回 session 意味著代理具有之前的完整上下文:它已經讀取的檔案、它已經執行的分析、它已經做出的決定。您可以提出後續問題、從中斷中恢復,或分支以嘗試不同的方法。
Sessions 保持對話,而不是檔案系統。要快照和還原代理所做的檔案更改,請使用檔案檢查點
本指南涵蓋如何為您的應用選擇正確的方法、自動追蹤 sessions 的 SDK 介面、如何捕獲 session ID 並手動使用 resumefork,以及關於跨主機恢復 sessions 的注意事項。

選擇一個方法

您需要多少 session 處理取決於您的應用程式的形狀。當您發送應該共享上下文的多個提示時,session 管理就會發揮作用。在單個 query() 呼叫中,代理已經根據需要進行了盡可能多的轉換,並且權限提示和 AskUserQuestion在迴圈中處理的(它們不會結束呼叫)。

Continue、resume 和 fork

Continue、resume 和 fork 是您在 query() 上設定的選項欄位(Python 中的 ClaudeAgentOptions,TypeScript 中的 Options)。 Continueresume 都會拾取現有 session 並將其添加到其中。區別在於它們如何找到該 session:
  • Continue 在當前目錄中找到最近的 session。您無需追蹤任何內容。當您的應用一次運行一個對話時效果很好。
  • Resume 採用特定的 session ID。您追蹤 ID。當您有多個 sessions(例如,多使用者應用中每個使用者一個)或想要返回不是最近的 session 時需要。
Fork 不同:它創建一個新 session,從原始 session 的歷史副本開始。原始 session 保持不變。使用 fork 嘗試不同的方向,同時保持返回的選項。

自動工作階段管理

兩個 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_turnserror_max_budget_usd 結束(請參閱處理結果);以更高的限制恢復。在單次 query() 呼叫中,SDK 會在產生該錯誤結果後引發異常,因此在恢復前捕獲錯誤。
  • 重新啟動您的進程。 您在關閉前捕獲了 ID,並想恢復對話。
此示例使用後續提示恢復捕獲 session ID 中的 session。因為您正在恢復,代理已經在上下文中具有先前的分析:
您應該會看到一個基於先前分析而構建的回應,而不是從頭開始。這確認了代理以其先前的上下文完整恢復了 session。
Claude Code 將 sessions 存儲在 ~/.claude/projects/<encoded-cwd>/*.jsonl 下。如果您設定了 CLAUDE_CONFIG_DIR 環境變數,請改為查看 $CLAUDE_CONFIG_DIR/projects/ 下。要找到您的 session 目錄,請將絕對工作目錄中的每個非英數字元替換為 -/Users/me/proj 變成 -Users-me-proj。對於轉換後的名稱超過 200 個字元的工作目錄,Claude Code 會截斷名稱並附加雜湊,因此在列出 projects/ 時,請匹配轉換後名稱的前 200 個字元。如果您在 CLAUDE_CONFIG_DIR 旁邊設定 CLAUDE_CODE_PROJECT_DIR_NAME,請改為查看 projects/ 中的該名稱。需要 TypeScript Agent SDK v0.3.234 或更新版本,或 Python Agent SDK v0.2.140 或更新版本。您可以從任何工作目錄恢復:
  • 跨目錄查詢:Claude Code 搜尋超出目前專案目錄以找到 ID;請參閱恢復 session 以了解確切的查詢順序以及如何處理重複副本。
  • 僅限同一機器:session 文件仍需要存在於目前機器上。
在 v2.1.223 之前,查詢的範圍限於目前專案目錄及其 git worktrees;捆綁較舊 CLI 的 SDK 版本仍然以這種方式運作。
要跨機器或在無伺服器環境中恢復 sessions,請使用 SessionStore 適配器將記錄鏡像到共享存儲。

Fork 以探索替代方案

Forking 創建一個新 session,從原始 session 的歷史副本開始,但從該點開始分歧。fork 獲得自己的 session ID;原始的 ID 和歷史保持不變。您最終得到兩個獨立的 sessions,可以分別恢復。
Forking 分支對話歷史,而不是文件系統。如果 forked 代理編輯文件,這些更改是真實的,對在同一目錄中工作的任何 session 都可見。要分支和還原文件更改,請使用文件檢查點
此示例基於捕獲 session ID:您已經在 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 的提示中。這通常比運送記錄文件更穩健。
兩個 SDK 都公開用於列舉磁碟上的 sessions 和讀取其訊息的函數:TypeScript 中的 listSessions()getSessionMessages(),Python 中的 list_sessions()get_session_messages()。使用它們構建自訂 session 選擇器、清理邏輯或記錄檢視器。 兩個 SDK 也公開用於查找和變更個別 sessions 的函數:Python 中的 get_session_info()rename_session()tag_session(),以及 TypeScript 中的 getSessionInfo()renameSession()tagSession()。使用它們按標籤組織 sessions 或給它們人類可讀的標題。