claudecode学习第 18 章 · Session 生命周期18.1 Session 是什么 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 函数。两个用途：

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

本机有 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 回复、不记录工具调用。

两个用途：

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

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

18.8 本章核心带走

Session 是最小活动单元。 每次 claude 启动 = 新 session = 新 UUID + 新 transcript + 新 file-history。
三套持久化文件：transcript（.jsonl——所有事件）、file-history（@v——文件版本快照）、session-env（SessionStart 环境注入）。
-c 续对话靠 transcript 重放。 旧 transcript 读出 → messages 重建 → 和新的 system prompt 合并。compaction 摘要也被保留。
Memory 管跨 session 知识，transcript 管 session 内对话。 两个系统不重叠。-c 回到上次对话，memory 记住你的偏好。
"busy" → "idle"：idle 不销毁——所有文件保留，随时可恢复。
history.jsonl 只记用户输入——↑/Ctrl+R 的数据源。大段粘贴内容走 paste-cache 避免膨胀。

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

18.1 Session 是什么

18.2 Session 的三种启动姿态

新建

续最近一次（-c）

选择恢复（-r）

18.3 Session Metadata

18.4 Session 的持久化：三套文件

第一套：Transcript（.jsonl）

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

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

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

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