会话管理

会话（Session）是 SDK 自动持久化到磁盘的对话历史，包含所有工具调用、结果和响应。恢复会话后 Agent 拥有完整的上下文，无需重新读取文件或重复分析。

核心机制

三种会话操作：

• continue：自动找到当前目录最近的会话继续，无需追踪 ID
• resume：通过 session ID 恢复指定会话，支持跨进程重启
• fork：复制会话历史创建新分支，原会话不受影响，适合探索不同方案

会话存储路径：~/.claude/projects/<encoded-cwd>/<session-id>.jsonl，其中 <encoded-cwd> 是工作目录路径中非字母数字字符替换为 - 的结果。

Python vs TypeScript 自动管理：

• Python：使用 ClaudeSDKClient，内部自动追踪 session ID，每次 client.query() 自动延续同一会话
• TypeScript：使用 continue: true 选项，SDK 自动找到最近会话

关键细节

捕获 session ID（Python）：

async for message in query(prompt="Analyze the auth module", options=...):
    if isinstance(message, ResultMessage):
        session_id = message.session_id

恢复指定会话：

async for message in query(
    prompt="Now implement the refactoring you suggested",
    options=ClaudeAgentOptions(
        resume=session_id,
        allowed_tools=["Read", "Edit", "Write"],
    ),
):
    ...

Fork 会话：

async for message in query(
    prompt="Instead of JWT, implement OAuth2",
    options=ClaudeAgentOptions(resume=session_id, fork_session=True),
):
    if isinstance(message, ResultMessage):
        forked_id = message.session_id  # 新分支的 ID

TypeScript 持久化控制：设置 persistSession: false 可实现纯内存会话（不写磁盘），Python 始终持久化。

跨主机恢复：将 ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl 同步到目标主机，确保 cwd 路径一致。

与其他概念的关联

• agent-loop - 会话内的上下文积累和压缩
• file-checkpointing - 文件系统状态的快照（会话只保存对话历史）
• sessions 相关 API：list_sessions()、get_session_messages()、rename_session()、tag_session()

实践要点

• 会话只保存对话历史，不保存文件系统状态；文件回滚需使用 file-checkpointing
• resume 失败（返回新会话）最常见原因是 cwd 不匹配，检查工作目录是否一致
• 多用户应用中每个用户需要独立的 session ID，不能共用 continue: true
• 会话文件可用 listSessions() 枚举，可构建自定义会话选择器或清理逻辑
• 错误结束的会话（error_max_turns 等）也有 session_id，可以 resume 后继续