​
会话管理

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: "帮我构建一个 Web 应用程序",
  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 的会话管理系统为维护对话状态和实现开发任务的无缝恢复提供了强大的基础，所有这些都通过一个简单的基于文件的方法实现，无需外部基础设施。