13. 会话与检查点

本节目标：搞懂 Claude Code 的「会话」和「检查点（Checkpoint）」两套机制，学会恢复中断的对话、给会话起名字、一键回退到任意历史节点，把代码改坏了也能救回来。

先搞清楚两个概念

用 Claude Code 干活，绕不开两个词：会话（Session） 和 检查点（Checkpoint）。新手容易把它们混为一谈，其实分工很明确。

打个比方。会话像你跟 Claude 的一段完整聊天记录，从「你好」到「活干完了」算一段。检查点像你聊天过程中给代码状态拍的一张快照，专门用来「出问题时一键回到这个时刻」。

会话管的是「对话本身」——恢复、切换、命名、分支
检查点管的是「代码状态」——回退文件、回退对话、或两者一起回退

两者关系紧密：检查点跟会话一起保存，恢复老会话时，里面的检查点也跟着回来。

Note

桌面应用、Web 版、VS Code 扩展各自维护自己的会话历史，互不相通。本章讲的是 CLI（终端）里的会话管理。

会话是怎么保存的

Claude Code 在你干活时，会自动把对话保存到本地一个叫「文本记录（transcript）」的文件里。位置默认是：

~/.claude/projects/<项目路径>/<会话ID>.jsonl

其中 <项目路径> 是你当前工作目录的路径，里面的非字母数字字符会被替换成 -。文件格式是 JSONL（每行一个 JSON 对象），记录每条消息、工具调用和元数据。

这意味着几件事：

你关掉终端、重启电脑，对话不会丢
跑了 /clear 清空上下文，旧对话也被存下来了，还能找回来
默认 30 天自动清理（可在 settings.json 里改）

Warning

这个 JSONL 文件是 Claude Code 的内部格式，版本间可能变化。别自己写脚本去硬解析它，官方提供更稳的接口（见下文「导出会话」）。

恢复会话的五种姿势

恢复会话是最高频的操作。Claude Code 给了一组入口，记住下面这张表就够用了：

命令	干什么
`claude --continue`	恢复当前目录里最近的一个会话
`claude --resume`	打开会话选择器，自己挑
`claude --resume <名字>`	直接恢复你起过名字的会话
`claude --from-pr <编号>`	恢复跟某个 PR 关联的会话
`/resume`	在会话进行中切换到另一个对话

最常用的就两个：想接着上次的活儿干，敲 claude --continue；想在一堆会话里挑，敲 claude --resume。

Tip

我自己习惯给重要会话起名字（下一节讲），下次直接 claude --resume auth-refactor 一秒回到现场，比翻列表快得多。

会话选择器看哪儿

跑 claude --resume 不带参数，会弹出一个交互式选择器。默认只显示当前 worktree 里的会话，加上用 /add-dir 把当前目录加进来的那些。

几个常用快捷键：

快捷键	作用
`↑` / `↓`	上下导航
`Enter`	恢复选中的会话
`Space`	预览会话内容
`Ctrl+R`	给会话重命名
`Ctrl+A`	显示这台电脑上所有项目的会话
`Ctrl+W`	显示当前仓库所有 worktree 的会话
`Ctrl+B`	只看当前 git 分支的会话
`/` 或任意字符	进入搜索模式，还能直接粘 PR 编号或 URL 找会话

每行会显示会话名（没起名就显示对话摘要）、距上次活动的时间、消息数和 git 分支。

给会话起个名字

并行干好几件事的时候，不给会话起名字真的会乱。命名有几种方式：

时机	怎么起
启动时	`claude -n auth-refactor`
会话进行中	`/rename auth-refactor`（名字会显示在输入栏上方）
在选择器里	选中会话按 `Ctrl+R`
接受计划时	在 Plan Mode 下接受计划，会自动从计划内容生成名字（前提是你没手动起过）

起完名字，下次直接 claude --resume auth-refactor 或会话内 /resume auth-refactor 就能回来。

Note

从 v2.1.196 起，就算你不手动命名，新会话也会自动得到一个默认显示名（比如 my-app-3f），方便在列表里认出来。但这个默认名不能用来恢复，只有你手动起的名字才行。

分支会话：试错不毁原路

有时候你想「换个思路试试，但又怕把当前对话搞砸」。这时候用分支（Fork）。

分支做的事很简单：把当前对话复制一份，把你切到副本里，原始对话原封不动。试错了不满意，回原路就行。

会话内分支：

/branch try-streaming-approach

省略名字的话，Claude Code 会拿对话里的第一个提示当分支名。

命令行分支（恢复的同时分叉）：

claude --continue --fork-session

Warning

分支后，你在原会话里用「允许此会话」批准的权限不会带过来，新分支得重新授权。另外，如果你在两个终端同时恢复同一个会话而不分叉，两边的消息会交错写进同一条文本记录里，挺乱的——想并行就老老实实 fork。

检查点：代码改坏了能救

会话管的是「对话」，检查点管的是「代码状态」。这套机制是全自动的，不用你配置。

工作原理就一句话：每次你发送提示前，Claude Code 都会自动给当前代码状态拍一张快照。

具体规则：

每个用户提示创建一个新的检查点
一个会话里最多保留最近 100 个检查点
检查点跟会话一起保存，恢复老会话时检查点也回来
30 天后自动清理（可配置）

Warning

检查点只跟踪 Claude 用文件编辑工具做的直接修改。下面这些它管不了：

Bash 命令改的文件（rm、mv、cp、npm install 改 package.json 之类）

你在 VS Code、终端等外部工具里手动改的文件

其他并发会话的修改

所以检查点是「本地临时撤销」，不是 Git 的替代品。长期历史和团队协作还是老老实实用 Git。

用 /rewind 回退

打开回退菜单有两种方式：

输入 /rewind
输入框为空时连按两次 Esc（如果输入框里有字，双 Esc 会清空输入，不打开菜单）

菜单会列出你这次会话发过的每一条提示。选中某个点，再选操作：

操作	效果
恢复代码和对话	代码和对话都回到那个点
恢复对话	只回退对话，代码保持现状
恢复代码	只回退文件，对话保持现状
从此处总结	把这个点之后的对话压成摘要，释放上下文
到此处总结	把这个点之前的对话压成摘要
算了	什么都不做，返回

前三个是「回退」，后两个是「压缩」。区别在于：回退会丢东西，压缩是把一段对话变成摘要、腾出上下文窗口（Context Window）空间，原始消息其实还留在会话记录里，Claude 需要时还能翻出来看。

Tip

这俩「总结」选项比 /compact 更精准——/compact 是把整个对话一锅端压缩，而你可以指定「只压前半段」或「只压后半段」。比如调试半天前面是冗长的探索过程、后面才是干货，就用「到此处总结」把前面压掉。

回退已经 /clear 掉的对话

如果你在同一进程里刚跑过 /clear，回退菜单顶部会多出一个 previous session 条目，选中它就能把清空前的对话捞回来。

前提有两个：Claude Code v2.1.191 或更高版本，并且你没退出 Claude Code、也没切到别的会话。一旦退出就没了，得用 /resume 从列表里找。

导出会话给别人看

想把一段对话分享出去、或者存档备查，用 /export。

最简单的用法——会话内输入：

/export

会弹个菜单，让你选「复制到剪贴板」或「存成纯文本文件」。文件里消息和工具输出都会渲染成可读文本。

想直接写到指定文件，跳过菜单：

/export 我的对话记录.txt

让脚本读会话数据

/export 给人看，给程序看要用别的接口：

跑一次拿结果：claude -p --output-format json "你的问题"，返回结构化 JSON，含结果、会话 ID、用量、成本
给已有会话追问：claude -p --resume <会话ID> --output-format json "总结一下我们改了啥"，再用 jq 取答案
响应会话事件：用钩子（Hook）或状态栏命令，它们能收到 transcript_path 字段
嵌入到应用里：用 Agent SDK（TypeScript/Python）按编程方式收每条消息

举个例子，给老会话发个追问并取结果：

claude -p --resume <session-id> --output-format json "summarize what we changed" | jq -r '.result'

跨设备继续干活

这里有个新手常有的误解：「会话存本地了，我换台电脑能不能直接接着干？」

答案是不能直接接。会话文本记录存在你这台电脑的 ~/.claude/projects/ 下，换台机器默认是看不到的。

但有几种「曲线救国」的法子：

用 claude -p --output-format json 把会话 ID 和关键内容导出，到新机器上用 --resume <session-id> 试着接（需要文本记录也在）
把对话用 /export 存成文本，到新机器上贴给 Claude 当上下文
用 Git worktrees 在同一台机器的不同目录跑隔离会话（不算跨设备，但思路类似）

真正想要「随时随地接着干」，靠的是 Web 版（claude.ai/code）和云端会话，那套体系跟 CLI 的本地会话是分开的。

小结

记住这两套机制的分工：

会话：--continue 接最近的、--resume 挑列表、-n 起名字、/branch 试错、/export 导出
检查点：自动拍快照、/rewind 或双 Esc 回退、能回代码/对话/两者、还能压缩腾上下文

代码改坏了别慌，先按两下 Esc。日常并行多任务，记得给会话起名字。Git 还是你的长期历史，检查点只是会话级的「本地撤销」。