​
會話管理

Claude Code SDK 提供會話管理功能，用於處理對話狀態、持久化和恢復。本指南涵蓋了會話如何在 SDK 中創建、管理、持久化到檔案以及恢復。

​
會話架構

Claude Code SDK 實現了基於檔案的會話管理系統，處理對話持久化和狀態恢復。

​
會話檔案結構

會話以結構化格式持久化到本地檔案系統： 
~/.config/claude/
├── sessions/
│   └── sessions.json          # 會話元數據和狀態
└── projects/
    └── {project-hash}/
        └── {session-id}.jsonl # 會話記錄

​
會話元數據格式

sessions.json 檔案存儲所有會話的元數據： 
interface SessionMetadata {
  id: string
  name: string
  status: 'active' | 'completed' | 'interrupted'
  createdAt: Date
  updatedAt: Date
  completedAt?: Date
  projectPath: string
  transcriptPath: string
  metadata: {
    model?: string
    tools?: string[]
    lastMessageId?: string
  }
}

​
會話記錄格式

會話記錄以 JSONL（JSON Lines）檔案格式存儲，每行代表一個訊息或事件： 
{"type":"user","uuid":"abc123","timestamp":"2024-01-01T10:00:00Z","message":{"content":"Hello Claude"}}
{"type":"assistant","uuid":"def456","parentUuid":"abc123","timestamp":"2024-01-01T10:00:01Z","message":{"content":[{"type":"text","text":"Hello! How can I help?"}]}}
{"type":"checkpoint","sessionId":"session123","commit":"a1b2c3d","timestamp":"2024-01-01T10:00:02Z","label":"Initial state","id":"chk456"}
JSONL 檔案中的每一行代表：
  • 用戶訊息：來自用戶的輸入
  • 助手訊息：來自 Claude 的回應
  • 檢查點：對話中保存的狀態（例如，完成任務後）
  • 工具使用：工具被調用及其結果的記錄

​
會話生命週期

​
創建和初始化

當會話開始時，SDK 執行幾個初始化步驟：
  1. 生成會話 ID：為會話創建唯一標識符
  2. 創建項目目錄：設置項目特定的存儲位置
  3. 初始化記錄檔案：為對話創建空的 JSONL 檔案
  4. 存儲初始元數據：記錄會話創建時間和配置

​
獲取會話 ID

會話 ID 在您開始對話時在初始系統訊息中提供。您可以捕獲它以供後續使用： 
import { query } from "@anthropic-ai/claude-code"

let sessionId: string | undefined

const response = query({
  prompt: "幫我構建一個網頁應用程式",
  options: {
    model: "claude-sonnet-4-20250514"
  }
})

for await (const message of response) {
  // 第一個訊息是包含會話 ID 的系統初始化訊息
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`會話已開始，ID：${sessionId}`)
    // 您可以保存此 ID 以供稍後恢復
  }
  
  // 處理其他訊息...
  console.log(message)
}

// 稍後，您可以使用保存的 sessionId 來恢復
if (sessionId) {
  const resumedResponse = query({
    prompt: "從我們停止的地方繼續",
    options: {
      resume: sessionId
    }
  })
}

​
會話狀態持久化

SDK 自動將會話狀態持久化到磁碟：
  • 每次訊息交換後：記錄被更新
  • 工具調用時：工具使用和結果被記錄
  • 在檢查點：重要的對話狀態被標記
  • 會話結束時：最終狀態被保存

​
會話恢復

SDK 支援從先前的對話狀態恢復會話，實現連續的開發工作流程。

​
從會話檔案恢復

import { query } from "@anthropic-ai/claude-code"

// 使用會話 ID 恢復先前的會話
const response = query({
  prompt: "從我們停止的地方繼續實現身份驗證系統",
  options: {
    resume: "session-xyz", // 來自先前對話的會話 ID
    model: "claude-sonnet-4-20250514",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// 對話繼續，包含先前會話的完整上下文
for await (const message of response) {
  console.log(message)
}

​
錯誤處理和恢復

​
處理中斷的會話

import { query } from '@anthropic-ai/claude-code'
import { readFile } from 'fs/promises'
import { homedir } from 'os'
import { join } from 'path'

// 檢查會話是否被中斷
const checkSessionStatus = async (sessionId: string) => {
  const metadataPath = join(homedir(), '.config/claude/sessions/sessions.json')
  const metadata = JSON.parse(await readFile(metadataPath, 'utf-8'))
  
  const session = metadata.find(s => s.id === sessionId)
  
  if (session?.status === 'interrupted') {
    console.log('會話被中斷。準備恢復...')
    
    // SDK 內部處理載入記錄
    return {
      canResume: true,
      sessionId: sessionId
    }
  }
  
  return { canResume: false }
}

// 恢復中斷的會話
const resumeInterrupted = async (sessionId: string) => {
  const status = await checkSessionStatus(sessionId)
  
  if (status.canResume) {
    const response = query({
      prompt: "讓我們從停止的地方繼續",
      options: {
        resume: status.sessionId
      }
    })
    
    for await (const message of response) {
      console.log(message)
    }
  }
}
Claude Code SDK 的會話管理系統為維護對話狀態和實現開發任務的無縫恢復提供了強大的基礎，所有這些都通過一個簡單的基於檔案的方法實現，不需要外部基礎設施。