claudecode学习 第 18 章 · Session 生命周期

目标：讲清 Session 的完整生命周期------创建（新/续/恢复）、三套持久化文件（transcript .jsonl、file-history @v、session-env）、session metadata 结构、busy→idle 状态转换、跨 session 的知识延续机制（Memory vs transcript）、history.jsonl 的用途。这是运行时纵深的第一章------从"Agent 怎么工作"到"Agent 的状态怎么保存和恢复"。 受众：专业程序员。本机版本 2.1.220。

---

18.1 Session 是什么

Session（会话）是 Claude Code 的最小活动单元 。每次敲 claude 启动，就是一个新 session 诞生。

Session = 一组持久化的 messages + 元数据 + 文件变更追踪 + 环境快照。 它不是内存里的临时对话------它是磁盘上的可恢复状态。

---

18.2 Session 的三种启动姿态

claude                    # 新建（默认）
claude -c / --continue    # 继续当前目录最近一次 session
claude -r / --resume      # 选择历史 session 恢复（支持 ID 前缀或搜索词）

新建

新的 sessionId、新的 transcript、新的 file-history。CLAUDE.md 重新加载、memory 重新检索、skills 重新注册。Memory 文件是唯一跨 session 持久化的知识（Ch07）------其他都是新 session 的空白状态。

续最近一次（-c）

在当前工作目录下找最近一次 session，读取它的 transcript（.jsonl），把所有历史 messages 重新注入 context。用户看到的是"上次对话继续"------所有之前的上下文都在。

底层机制：旧 transcript 从磁盘读出 → messages 数组重建 → 和新的 system prompt 合并 → Ch14 的 compaction 摘要也被保留。

选择恢复（-r）

claude -r            # 列出所有历史 session 供选择
claude -r abc123     # 按 sessionId 前缀匹配
claude -r "thesis"   # 按关键词搜索（匹配 name 或 cwd）

---

18.3 Session Metadata

每次启动时写入 ~/.claude/sessions/{pid}.json：

{
  "pid": 17345,
  "sessionId": "2932430a-4f95-4ae4-93ce-d188636cb407",
  "cwd": "/Users/jsl",
  "startedAt": 1785336055458,
  "procStart": "Wed Jul 29 14:40:53 2026",
  "version": "2.1.220",
  "peerProtocol": 1,
  "kind": "interactive",
  "entrypoint": "cli",
  "name": "jsl-41",
  "nameSource": "derived",
  "status": "busy",
  "updatedAt": 1785421492053,
  "statusUpdatedAt": 1785421492053
}

关键字段：

字段	含义
pid	OS 进程 ID，文件名 {pid}.json 的来源
sessionId	全局唯一 UUID，关联 transcript、file-history、session-env
kind	"interactive"（REPL）或 headless（-p）
status	"busy"（运行中）→ "idle"（已结束）
name	会话名称，默认从 cwd 派生，可在 session 列表页改名
peerProtocol	客户端协议版本，兼容性检查
entrypoint	"cli" = 终端启动

---

18.4 Session 的持久化：三套文件

第一套：Transcript（.jsonl）

~/.claude/projects/<sanitized-cwd>/<sessionId>.jsonl

每行一个 JSON 对象，按时间顺序记录 session 中每一个事件 。这是 session 的核心数据-------c 恢复就从它重建 messages。

当前 transcript 的事件类型统计（近 1500 行）：

事件类型	数量	内容
assistant	589	LLM 回复（text 块 + tool_use 块）
user	358	用户输入（text + tool_result 块）
last-prompt	105	最近一次 prompt 快照
mode	100	模式切换（default/plan/auto）
permission-mode	100	权限模式变更
ai-title	100	AI 生成的对话标题
file-history-snapshot	55	文件状态全量快照
file-history-delta	22	文件变更增量
system	57	系统消息（compaction 通知、提醒）
attachment	48	Hook 输出、agent 列表更新
queue-operation	4	后台任务队列操作

每种事件有独立的结构。assistant 消息携带 message.context_management（Ch14 的 compaction 标记）、uuid、timestamp、attributionSkill/attributionAgent 等来源标记（Ch10）。

第二套：File History（~/.claude/file-history/<sessionId>/）

~/.claude/file-history/2932430a-.../
├── 0525a6f49ad91b1a@v1      ← 某文件第 1 次修改的快照
├── 0525a6f49ad91b1a@v2      ← 同文件第 2 次修改的快照
├── 2ee4ec8d3cec3325@v1
├── 2ee4ec8d3cec3325@v2
└── ...

文件命名格式：<路径哈希>@v<版本号>。

• Hash 保护文件路径隐私
• 每 Edit/Write 一次，版本号 +1
• Transcript 中的 file-history-snapshot（全量）和 file-history-delta（增量）事件记录变更时机

作用：回滚。如果 Claude 改错文件，可以从 file-history 恢复之前任意版本。

第四套：Shell Snapshots（~/.claude/shell-snapshots/）

~/.claude/shell-snapshots/snapshot-zsh-<timestamp>-<random>.sh

Session 启动时自动拍摄当前 shell 环境的快照------所有环境变量、alias、shell 函数。两个用途：

1. 跨 session 恢复环境变量（-c 继续时重建环境）
2. 调试------排查"为什么这次行为不同"时可以对比环境差异

本机有 2 个文件，共 280KB------完整的 shell 环境。

第五套：Backups（~/.claude/backups/）

~/.claude/backups/  ← 5 个文件，60KB

配置自动备份。settings.json、CLAUDE.md 等关键文件在修改前自动备份。从二进制确认：配置变更操作（/config、手动编辑 settings）会触发备份。

与 file-history 的区别：file-history 管项目文件 （Claude 改的代码），backups 管Claude Code 自身的配置文件。

第三套：Session Env（~/.claude/session-env/<sessionId>）

SessionStart hook（Ch12）通过 $CLAUDE_ENV_FILE 写入的环境变量存储在这里。Session 启动时创建，结束时清理。

---

18.5 Session 状态转换

启动 → "busy"
  │
  ├─→ Agent 循环运行 → "busy"
  ├─→ /compact → "busy"（压缩也是 Agent 工作）
  ├─→ Ctrl+C 或 /clear → session 终止，status 可能不更新
  └─→ Ctrl+D 或正常退出 → "idle"
       └─→ updatedAt / statusUpdatedAt 更新为当前时间

"idle" 不代表被销毁 。Transcript、file-history、metadata 全部保留在磁盘上。-c 或 -r 可以从 idle session 恢复。

---

18.6 跨 Session：什么延续，什么不延续

保留（跨 session）	丢弃（仅当前 session）
Memory 文件（Ch07）	对话 messages------除非 -c 恢复
CLAUDE.md + rules（每次重新加载）	Compaction 摘要（Ch14）
settings.json	session-env 临时文件
File history（@v 快照）	session 级权限 allow 规则
已安装的 plugins/skills	Agent 的"当前工作进度"
history.jsonl（用户输入日志）	打开的 plan file

核心设计：

• Memory → 跨 session 的知识延续（"用户偏好函数式风格"）
• Transcript → session 内的对话 延续（-c 恢复）
• File history → 文件安全网（随时回滚）

三个系统互补，不重叠。

---

18.7 history.jsonl：用户输入日志

~/.claude/history.jsonl

每行一条用户输入，不限于单个 session：

{
  "display": "分析 src/auth.ts 的认证逻辑",
  "pastedContents": {},
  "timestamp": 1784200824990,
  "project": "/Users/jsl",
  "sessionId": "e36137fb-83a0-4241-8a74-498decd350ef"
}

只记录用户输入------不记录 assistant 回复、不记录工具调用。

两个用途：

1. 终端 ↑ / Ctrl+R 搜索历史输入
2. /cost 等命令按 session 聚合统计

粘贴的大段内容会以 hash 引用方式存储（"contentHash": "363c0100b428736e"），避免 history.jsonl 膨胀。实际内容存在 ~/.claude/paste-cache/。

---

18.8 本章核心带走

1. Session 是最小活动单元。 每次 claude 启动 = 新 session = 新 UUID + 新 transcript + 新 file-history。

2. 三套持久化文件 ：transcript（.jsonl------所有事件）、file-history（@v------文件版本快照）、session-env（SessionStart 环境注入）。

3. -c 续对话靠 transcript 重放。 旧 transcript 读出 → messages 重建 → 和新的 system prompt 合并。compaction 摘要也被保留。

4. Memory 管跨 session 知识，transcript 管 session 内对话。 两个系统不重叠。-c 回到上次对话，memory 记住你的偏好。

5. "busy" → "idle"：idle 不销毁------所有文件保留，随时可恢复。

6. history.jsonl 只记用户输入 ------↑/Ctrl+R 的数据源。大段粘贴内容走 paste-cache 避免膨胀。

---