第 4 章 · M4 会话持久化与中断恢复
第 4 章 · M4 会话持久化与中断恢复
- 4.1 M4 功能说明:中断后接着上次继续
- 4.2 M4 总体架构:包结构与组件协作
- 4.3 会话日志:为什么是 append-only JSONL + 存在哪里
- 4.4 消息格式、写入时机(持久化 sink)与崩溃安全
- 4.5 待办快照:为什么TodoWrite整份覆盖写
- 4.6 resume:回放重建 Session + 中断检测
4.1 M4 功能说明:中断后接着上次继续
本篇涉及到的源码列表:
com.minicc.persistence.SessionStore.java
com.minicc.persistence.TodoSnapshotStore.java
com.minicc.cli.command.ResumeCommand.java
com.minicc.persistence.SessionPaths.java
com.minicc.session.Session.java
com.minicc.cli.command.ClearCommand.java
com.minicc.cli.Renderer.java
M3 我们做完了,现在这个 Agent 已经会读代码、能改代码、执行命令之前还会先问过你。
但它有一个根本的局限:这些状态都只保存在内存里。
一旦你关掉终端,或者程序意外崩溃,整段对话和刚建好的待办进度就都丢失了,下次只能从头再来。
从这一章开始,我们进入第四个里程碑 M4,目标是把会话写进磁盘,下次启动后还能原样读回来。
M4 这一版交付什么
M4 要做的事情可以归成三件,它们合起来让 Agent 第一次有了跨进程、跨时间的连续性。
- 会话日志(append-only 的 JSONL):每一条用户消息、assistant消息、工具结果,都按发生顺序原样追加到一个
.jsonl文件里,一行一条。它只追加、不改写,是会话历史的唯一真相源。 - 待办快照:在日志之外,再额外存一个只放"当前待办列表"的小文件,每次更新就整份覆盖写一遍,供
/resume和界面快速读取当前进度。 /resume命令:把上次(或者你指定的某次)会话读回内存,重建会话历史与待办,接着上次的进度继续。
这一版完成之后,昨天没做完的任务,今天启动 mcc 再 /resume 就能接着做。
更重要的是,它为后面的里程碑准备了一个前提:原始历史始终完整落盘。之后 M6 的上下文压缩只精简发给模型的那段窗口,压缩掉多少内容,原文都还在,/resume 时仍然能拿回完整记录。
落盘是自动的,你不需要手动保存
我们先说明一个容易被忽略的点:M4 的落盘是边做边写、全自动的。
你正常和 Agent 对话、让它改文件,每一步都已经写进了磁盘上的日志文件。
所以你不需要任何"保存"动作。哪怕直接把终端窗口关掉,甚至机器突然断电,已经写进去的部分都完好无损。
会话文件默认放在 ~/.mcc/projects/<你的项目路径>/ 目录下,一个项目一个目录、一次会话一个文件。
命令行里是什么样的
我们用一个跨越两次启动的例子来看。符号沿用前几章:行首的 ⏺ 是一步动作,⎿ 是这一步的结果。
我们先看第一次会话。你让 Agent 做一个多步任务,它建立了待办清单、开始执行,执行到一半你把终端关了。
> 给 OrderService 的 placeOrder 加去重,避免同一请求重复下单
⏺ 先理清现状,我建一个待办清单
⏺ TodoWrite(todos=[...])
⎿ ☐ 阅读 OrderService / OrderController 现状
☐ 为 placeOrder 增加 dedupKey 并做去重
☐ 同步更新 CheckoutJob 的调用
☐ 新建"重复请求不产生重复订单"的测试
⏺ Read(file_path=/Users/wangzheng/codecrush/src/main/java/OrderService.java)
⎿ 1 package com.example;
…(共 180 行)
[这时你直接关掉了终端]过程中发生的每一条消息,都已经写进了磁盘上的 .jsonl 文件,待办清单也存了一份快照。
第二天你重新启动 mcc,输入 /resume,它会把上次这段会话读回来,并把恢复结果打印出来。
> /resume
⎿ 已恢复会话(24 条消息) · 待办 4 项:
☑ 阅读 OrderService / OrderController 现状
▶ 为 placeOrder 增加 dedupKey 并做去重
☐ 同步更新 CheckoutJob 的调用
☐ 新建"重复请求不产生重复订单"的测试渲染方式和 M2 的待办一致:已完成的会被划掉,进行中的会高亮。你这样就能看出上次做到哪里、接下来该做什么。
此时整段历史已经重新放进上下文,所以你可以直接追问上次的细节,它能够根据这段历史回答。
> 我们刚才改到哪一步了?
⏺ 上次我已经读完了 OrderService 和 OrderController,正打算在 placeOrder
入口加一个 dedupKey 去重。还没有修改 CheckoutJob,测试也还没写。要我接着往下做吗?你回复「继续」,它就接着上次的进度往下做。
/resume 和 /clear 正好相反
我们在这里再区分一对容易混淆的命令。
/clear(M1 就有)是"清空当前会话、从头开始"。在 M4 里,它会切换到一个全新的会话文件,但旧日志仍然留在磁盘上,以后仍然能用 /resume 恢复。
/resume 则相反,是"接上某个旧会话继续写",恢复之后的新消息会继续追加到被恢复的那个文件里。
一个是开新账本,一个是续旧账本。
本章的学习路线
接下来的五节,我们把上面这些能力一块块细化成代码。
- 4.2 我们先讲总体架构:M4 要复用 M1–M3 的哪些结构、新增了哪个包、一次"落盘到恢复"的全过程怎么走。
- 4.3 我们讲会话日志的两个基础问题:为什么选 append-only 的 JSONL,以及文件到底存在哪里。
- 4.4 我们讲一行一条消息的格式、写入时机(怎么在
Session上挂一个落盘 sink),以及崩溃安全。 - 4.5 我们讲待办快照:为什么日志之外还要单独存一份,以及为什么它用整份覆盖写。
- 4.6 我们讲
/resume的回放重建,以及其中需要专门处理的中断检测。
读完这一章,这个 Agent 就能把会话保留下来:关掉终端不丢进度,重启之后用 /resume 就能接着上次继续。
4.2 M4 总体架构:包结构与组件协作
本篇涉及到的源码列表:
com.minicc.persistence.SessionStore.java
com.minicc.persistence.SessionPaths.java
com.minicc.persistence.TodoSnapshotStore.java
com.minicc.persistence.SessionLoader.java
com.minicc.cli.Repl.java
com.minicc.cli.Renderer.java
com.minicc.cli.command.ResumeCommand.java
com.minicc.cli.command.ClearCommand.java
com.minicc.session.Session.java
com.minicc.config.MccConfig.java
com.minicc.MccApplication.java
上一节我们把 M4 要做什么、在命令行里长什么样讲清楚了。
这一节我们来看它的整体结构:要复用 M1–M3 的哪些结构、新增了哪个包、一次"落盘到恢复"的全过程怎么在各组件之间流动。
你先掌握这张结构图,后面几节逐个讲每个组件时,你就知道它在整体里处在什么位置。
M4 的接入点只有一个关键处
M4 延续"后续里程碑只新增、少改动既有代码"的原则,而且这一次对既有代码的改动很少。
它对既有代码最主要的一处接入,就是在 Session 上挂一个会写盘的 sink。
我们回想一下 M1:对会话历史的所有追加,都封装在 Session 的几个 append 方法里。当时就是在为这一步做准备。
现在我们只要在这几个方法里,让它在修改内存的同时把同一条消息写入日志,就一处接入、全部覆盖了,既不漏消息,也不用在控制循环各处零散插入写盘代码。
除此之外,M4 几乎全是新增:一个负责持久化的新包,一个 /resume 命令,以及启动时生成会话文件、注入 sink 的几行代码。
ModelClient、上下文组装器、工具接口、审批、取消、提问这些,M4 都不需要修改。
包结构的增量
M4 是建在 M3 之上的,所以我们重点看它相对 M3 新增和修改的部分。
mini-claude-code/
├─ src/main/java/com/minicc/
│ ├─ persistence/ // 新:整个包(会话持久化这一件事)
│ │ ├─ SessionStore.java // 新:append-only JSONL 日志的追加与读取(内含 Message 的 JSON 序列化)
│ │ ├─ SessionPaths.java // 新:按项目路径推导会话目录与 <sessionId>.jsonl
│ │ ├─ TodoSnapshotStore.java // 新:待办快照的整份覆盖写 / 读取
│ │ └─ SessionLoader.java // 新:把日志回放成内存 Session(含中断检测)
│ ├─ cli/
│ │ ├─ Repl.java // 改:注册 /resume 命令
│ │ ├─ Renderer.java // 改:渲染"已恢复"提示
│ │ └─ command/
│ │ ├─ ResumeCommand.java // 新:/resume 命令
│ │ └─ ClearCommand.java // 改:/clear 时切到新会话文件
│ ├─ session/
│ │ └─ Session.java // 改:持有 SessionStore / sessionId;append* 时写盘
│ ├─ config/
│ │ └─ MccConfig.java // 改:新增 stateDir
│ └─ MccApplication.java // 改:启动时生成 sessionId、构造 sink 注入 Session我们可以把这些改动归成三类。
第一类是一个全新的 persistence 包,它只负责会话持久化这一件事,内部分成四个类,各自负责一项:路径推导、日志读写、待办快照、回放重建。
第二类是在 Session 上接入 sink,这是前面说的那一处关键接入,也是 M4 对既有逻辑唯一实质性的改动。
第三类是命令行上的配套改动:新增 /resume 命令、让 /clear 切换新文件、渲染"已恢复"提示,以及启动时把 sink 装进去。
persistence 包里的四个角色
这个新包里有四个类。我们先看一下各自的职责,后面几节会逐个展开。
SessionStore:会话日志的读写。往日志追加一条消息、把整段历史读回来,都走它。消息的 JSON 序列化也封装在这个类里面。SessionPaths:根据项目路径算出会话文件该放在哪、叫什么名字。TodoSnapshotStore:待办快照的整份覆盖写与读取。SessionLoader:把日志回放成内存里的Session,其中包含需要专门处理的中断检测。
一次"落盘到恢复"的全过程
我们用上一节那个跨两次启动的例子,把整条链路串一遍。
第一次会话:边做边落盘
第一步,启动。 MccApplication 生成一个新的 sessionId(一个 UUID),由 SessionPaths 算出日志文件路径,构造 SessionStore 和 TodoSnapshotStore 注入 Session。
第二步,用户输入需求。 Session.appendUserMessage 在内存里追加一条用户消息,同时 SessionStore 把这同一条消息追加进日志。
第三步,模型返回assistant消息。 控制循环调用 Session.appendAssistant,内存追加这条assistant消息(它要调用的工具就挂在这条消息上),同时写入日志。
第四步,工具执行完。 Session.appendToolResult 把工具结果转换成一条消息,追加到内存里,同时写入日志。
第五步,待办更新。 模型调用 TodoWrite 成功后,AgentLoop 调用一次 Session.writeTodoSnapshot(),把当前完整的待办列表整份覆盖写进快照文件。
第六步,用户关掉终端。 用户不需要做任何保存动作,因为每一步都已经落盘了。
下次启动:把会话读回来
第七步,用户输入 /resume。 ResumeCommand 通过 SessionPaths 找到本项目最近一次的 .jsonl 文件。
第八步,回放。 SessionLoader 逐行把 JSON 读回成消息,重建内存里的会话历史。回放时它会做一次中断检测,把上次中途被打断留下的"悬空工具调用"摘掉,保证重建出来的历史对模型是合法的(细节放到 4.6)。
第九步,恢复待办并渲染。 SessionLoader 读回待办快照,重建 TodoList,Renderer 打印出"已恢复 N 条消息、M 项待办"。
第十步,继续写同一个文件。 这是一个关键点:恢复之后不换新文件,而是继续往被恢复的那个 .jsonl 追加。这样这次会话就是上次的延续,整条历史仍然在一个文件里。
4.3 会话日志:为什么是 append-only JSONL + 存在哪里
本篇涉及到的源码列表:
com.minicc.persistence.SessionPaths.java
从这一节开始,我们进入 M4 的核心:会话日志。
会话历史用一个文件承载,这个文件只追加、不改写,格式是 JSONL(一行一个 JSON 对象)。
这一节我们回答两个基础问题:为什么是 append-only 的 JSONL,以及这个文件到底存在磁盘的什么地方。至于一行里具体存了什么、什么时候写入,我们放到下一节再讲。
为什么是"只追加"的日志
我们本可以把整段会话历史序列化成一个大 JSON,每次变化就整份覆盖写一遍。但我们没这么做,而是选了"每新增一条消息就往文件尾部追加一行"。这个选择有三个理由。
第一个理由是崩溃安全。 这是最重要的一条,值得我们单独来讲一下。
append(追加)是所有写文件的方式里最不容易写坏的一种。它只往文件末尾加内容,从不触碰前面已经写好的部分。
设想另一种做法:整份覆盖写。如果程序在覆盖到一半时崩溃,原来那份完整的文件已经被覆盖坏了,新的内容又没写完,两份都不完整。
而 append 最坏的情况,也只是最后那一行没写完整。前面所有已经写好的消息都完好无损,读回来时把那半行跳过即可。
第二个理由是它要作为真相源。 内存里的历史在后面的里程碑里会被压缩精简掉,但日志永远是完整的原文。
/resume 要读它,M6 压缩的"原文"也以它为准。既然是真相源,就不能让它有被改写、被写坏的风险,只追加是最稳妥的。
第三个理由是顺序本身就是语义。 一次会话,本质上就是一串按时间发生的消息:用户说了什么,模型要调用哪个工具,工具返回了什么,然后又是下一轮。
一行一条消息、按发生顺序排列的 JSONL,正好对应这个时间线。读回来的时候按行顺序回放一遍,会话就重建出来了,不需要额外的机制去还原消息之间的先后关系。
文件存在哪里
会话文件按"一个项目一个目录、一次会话一个文件"来组织,这样同一台机器上不同项目的会话互不混淆。
位置可以分成三层。
状态根目录默认是 ~/.mcc,可以用配置项 stateDir 来修改。M5 的长期记忆、M6 的工具结果落盘也都放在这个根目录下,所以我们把它作为一个通用的状态目录先引入。
项目目录是把项目的绝对路径"清洗"成一个安全的目录名得来的:非字母数字的字符一律替换成 -。
比如项目 /Users/wangzheng/codecrush,清洗后就对应目录 ~/.mcc/projects/-Users-wangzheng-codecrush/。这样做的好处是,不管原始路径里有什么斜杠、空格、中文,得到的目录名在各个平台上都合法。
会话文件叫 <sessionId>.jsonl,sessionId 就是启动时生成的那个 UUID。同目录下还有一个 <sessionId>.todos.json,是下一节之后要讲的待办快照。
这套路径推导封装在 SessionPaths 里:
// 源码位置:com.minicc.persistence.SessionPaths.java
// 本项目的会话目录:<stateDir>/projects/<清洗后的项目路径>/
public Path projectDir(Path projectRoot) {
String safe = sanitize(projectRoot.toAbsolutePath().normalize().toString());
return stateDir.resolve("projects").resolve(safe);
}
// 某次会话的日志文件:<projectDir>/<sessionId>.jsonl
public Path sessionLog(Path projectRoot, String sessionId) {
return projectDir(projectRoot).resolve(sessionId + ".jsonl");
}
// 把任意路径清洗成安全目录名:非字母数字一律转 '-'
private static String sanitize(String name) {
return name.replaceAll("[^a-zA-Z0-9]", "-");
}sanitize 这一行正则,就是整套路径规则的关键。它很简单,但已经够用。
怎么找到"最近一次"会话
/resume 不带参数时,要恢复的是"本项目最近一次"会话。这个"最近"也由 SessionPaths 来定位。
做法很直接:SessionPaths 列出项目目录下所有的 .jsonl 文件,按文件的修改时间选出最新的那一个,取它的文件名(去掉 .jsonl 后缀)就是要恢复的 sessionId。
// 源码位置:com.minicc.persistence.SessionPaths.java
// 本项目最近一次会话的 sessionId(供 /resume 不带参数时恢复最近一次)
public Optional<String> latestSessionId(Path projectRoot) {
Path dir = projectDir(projectRoot);
if (!Files.isDirectory(dir)) {
return Optional.empty();
}
try (Stream<Path> files = Files.list(dir)) {
return files
.filter(p -> p.getFileName().toString().endsWith(".jsonl"))
.max(Comparator.comparingLong(p -> p.toFile().lastModified())) // 按修改时间取最新
.map(p -> /* 去掉 .jsonl 后缀,剩下的就是 sessionId */ ...);
} catch (IOException e) {
return Optional.empty();
}
}下一节我们进入日志的内部:一行里到底存了什么,这一行是在什么时机被写进去的,以及崩溃安全具体是怎么保证的。
4.4 消息格式、写入时机(持久化 sink)与崩溃安全
本篇涉及到的源码列表:
com.minicc.session.Session.java
com.minicc.persistence.SessionStore.java
上一节我们讲了会话日志为什么是 append-only 的 JSONL、文件存在哪里。
这一节我们看日志内部的三个问题:一行里到底存了什么,这一行是在什么时机被写进去的,以及崩溃安全具体靠什么保证。
一行就是一条消息,和内存用同一种类型
我们先说一个在设计上比较直接的决定:日志里存的,就是内存历史里用的那几种消息,没有另外一套格式。
M1 的时候我们就确定了,会话历史直接用 Spring AI 的消息类型来承载:用户说的话是 UserMessage,模型的回复是 AssistantMessage,工具的返回是 ToolResponseMessage。助手要调用的工具,就挂在 AssistantMessage 上的 ToolCall 里。
M4 的日志沿用这同一套类型。内存里放的是什么,日志里追加的就是什么。
磁盘上的格式用一个 messageType 字段区分类型,只保留回放真正需要的字段。一段日志大致长这样(为了方便看,我们手动换了行):
{"messageType":"USER","text":"给 OrderService 的 placeOrder 加去重"}
{"messageType":"ASSISTANT","text":"先看一下现状","toolCalls":[{"id":"c1","type":"function","name":"Read","arguments":"{\"file_path\":\"/.../OrderService.java\"}"}]}
{"messageType":"TOOL","responses":[{"id":"c1","name":"Read","responseData":"...180 行..."}]}
{"messageType":"ASSISTANT","text":"已完成,placeOrder 现在会按 dedupKey 去重……","toolCalls":[]}写入时机:在 Session 的 append* 上挂一个 sink
接下来是关键问题:这些消息是在什么时候被写进日志的?
写入发生在 Session 每次追加消息的时候:内存修改完成之后,同一条消息就写入日志。
我们在 4.2 说过,M1 把"对会话历史的所有追加"都封装在 Session 的三个方法里。现在我们要做的,就是在这三个方法里,让它修改完内存,再往日志追加同一条消息。
// 源码位置:com.minicc.session.Session.java
// 追加一条用户消息,并落盘同一条 UserMessage
public void appendUserMessage(String text) {
UserMessage message = new UserMessage(text);
history.add(message); // 先修改内存
store.append(message); // 再把同一条写入磁盘
}
// 追加模型这一轮的assistant消息,并落盘同一条(工具调用就挂在这条消息上)
public void appendAssistant(AssistantMessage message) {
history.add(message);
store.append(message);
}
// 把一次工具执行结果作为观察追加到历史,并落盘同一条 ToolResponseMessage
public void appendToolResult(ToolResponseMessage message) {
history.add(message);
store.append(message);
}这里的 store 就是那个落盘 sink,类型是 SessionStore。它只做两件事:追加一条消息、把整段历史读回来。
// 源码位置:com.minicc.persistence.SessionStore.java
// 追加一条消息:序列化成一行、以 APPEND 方式写入(append-only,一行一条)
public synchronized void append(Message message) {
if (logFile == null) {
return; // 未绑定文件时是空操作
}
try {
Files.createDirectories(logFile.getParent()); // 目录按需创建
String line = json.writeValueAsString(message) + "\n";
Files.writeString(logFile, line, CREATE, APPEND); // append-only
} catch (IOException | RuntimeException e) {
System.err.println("写入会话日志失败(已忽略,会话仍在内存中):" + e.getMessage());
}
}为什么落盘要放在 Session 而不是控制循环里? 因为对历史的追加已经全部封装在 Session 这三个方法里。在这里接入 sink,就一处接入、全部覆盖,既不会漏掉任何一条消息,也不用在控制循环的各个位置单独插入写盘代码。这正是 M1 当初把历史维护封装进 Session 的好处。
崩溃安全:先修改内存,再同步追加
现在我们把崩溃安全讲清楚。它就体现在上面几行代码的顺序里。
第一,先修改内存,再落盘,而且落盘是同步追加。 就算程序正好在 append 的那一刻被强制终止,最坏的结果也只是最后一条消息没写上。已经写进去的部分完好无损,日志不会损坏。
第二,行顺序就是会话顺序。 消息是在 Session 被顺序调用时一条条写进去的,所以 JSONL 里的行顺序,就等于会话的发生顺序。回放时按行读即可,不需要别的机制去重排。
第三,写盘失败不拖垮主流程。 万一遇到磁盘满、没权限之类的 IO 异常,append 只记一条告警、然后继续运行,绝不把异常抛给控制循环。会话在内存里仍然正常,只是这一次没落盘。
这第三点是 M4 错误处理的总原则:持久化是一条尽力而为的旁路,它的任何失败都应该降级成"没有持久化",而不是让整个 Agent 用不了。 用户的任务不该因为写日志出了问题就被打断。
读回来时怎么处理不完整的一行
既然最坏的情况会留下半行不完整的 JSON,我们读回来的时候就要能处理这种情况。
readAll 逐行解析日志,对解析失败的那一行,跳过并告警,而不是让整个恢复失败。
// 源码位置:com.minicc.persistence.SessionStore.java
// 读回整段历史:逐行解析成消息列表(供回放)
public List<Message> readAll() {
if (logFile == null || !Files.exists(logFile)) {
return List.of();
}
List<Message> messages = new ArrayList<>();
for (String line : Files.readAllLines(logFile)) {
if (line.isBlank()) {
continue;
}
try {
messages.add(json.readValue(line, Message.class));
} catch (Exception lineError) {
System.err.println("跳过损坏的会话日志行:" + lineError.getMessage()); // 通常就是末尾那半行
}
}
return messages;
}解析失败的通常就是末尾那一行(上次崩溃时没写完的半行),跳过它,前面那些完整的消息仍然能恢复。
关于并发
你可能担心:M2 里只读工具是并行执行的,它们的结果会不会同时往日志里写、把文件写乱?
不会写乱。工具虽然并行执行,但它们的结果是由 appendToolResult 串行回填的。这个回填发生在调度器把全部结果收集齐、按原始顺序成对渲染的阶段,M2 第七节讲过。所以日志的写入实际上是串行的。
我们还在 append 上加了 synchronized 作为保护,即使以后出现并发写入,也不会把文件写乱。
下一节我们讲待办快照:既然待办的完整历史已经在日志里了,为什么还要在日志之外单独再存一份。
4.5 待办快照:为什么TodoWrite整份覆盖写
本篇涉及到的源码列表:
com.minicc.persistence.TodoSnapshotStore.java
com.minicc.agent.AgentLoop.java
上一节我们把会话日志讲完了:一行一条消息、append-only、崩溃安全。
有了这份完整的日志,待办的历史也在里面,恢复时从日志里把它读出来就可以了。
但 M4 还是在日志之外,单独为待办多存了一份文件,叫待办快照。这一节我们讲清楚这件事:为什么还要多存一份,以及它和日志相反、为什么用整份覆盖写。
日志里已经有待办的全部历史
我们先确认一个事实:待办的完整历史,确实已经记录在会话日志里了。
每次模型调用 TodoWrite,这就是一条assistant消息(带工具调用)加上一条工具结果消息,和别的消息一样被 append 进了日志。
所以从信息完整性上说,日志已经够了,待办的每次变化都有记录。
那为什么还要单独存一份
问题不在信息是否完整,而在当前进度能不能直接读出来。
我们设想一下,/resume 恢复之后要立刻把当前的待办进度显示出来。如果只靠日志,就要把整个日志从头读一遍,找到最后一次 TodoWrite 的调用,再把它的参数解析出来,才能知道现在的待办是什么样。
这个过程比较繁琐。而待办又需要被频繁、即时地读取:/resume 一结束就要显示,界面上随时也可能要用。
所以我们再保存一个只放"当前待办列表"的文件。要读取当前进度,我们直接读这一个文件、反序列化即可。
这是一种常见的做法:用一份"最新态快照"给"完整日志"做投影。
日志和快照的关系,可以看成账本和余额。日志这个账本只追加、不修改,记下每一次变化;快照这个余额只保留当前列表,要看当前进度,直接读它即可。
账本保证任何时候都能追溯完整历史,余额保证可以直接读到当前状态。两者分工明确,互为补充。
整份覆盖写,和日志正好相反
正因为快照只关心"当前"这一个状态,它的写法和日志恰好相反。
日志是 append,只往后追加、不修改前面的内容。快照是整份覆盖写:每次待办一有变化,就把当前完整的列表重新写成一个 JSON 文件,覆盖掉原来的内容。
这件事封装在 TodoSnapshotStore 里:
// 源码位置:com.minicc.persistence.TodoSnapshotStore.java
// 整份覆盖写当前待办列表(每次 TodoWrite 后调用)
public synchronized void write(List<TodoItem> todos) {
if (snapshotFile == null) {
return; // 未绑定文件时是空操作
}
try {
Files.createDirectories(snapshotFile.getParent());
Files.writeString(snapshotFile, json.writeValueAsString(todos),
CREATE, WRITE, TRUNCATE_EXISTING); // 覆盖写,不追加
} catch (IOException | RuntimeException e) {
System.err.println("写入待办快照失败(已忽略):" + e.getMessage());
}
}关键就是那个 TRUNCATE_EXISTING:打开文件时先把原内容清空,再写入新的完整列表。
你或许会问,覆盖写不是在 4.3 里说过,崩溃时容易把文件写坏吗,为什么这里又用上了?
因为两者的角色不同。待办快照可以随时重新生成。就算它写坏了、丢失了,我们还能从日志里把待办重新算出来,所以用覆盖写即可。
日志是真相源,不能损坏,才必须用 append。
至于写盘失败,待办快照和日志遵循同样的原则:记录一条告警、继续运行,绝不拖垮主流程。
读回来就更简单了,把文件内容反序列化成待办列表即可;文件不存在或者损坏,就返回一个空列表兜底。
什么时候写快照
待办在内存里的更新,仍然是由 TodoWrite 这个工具完成的,这一点 M4 没有修改。
但快照的写入不放在工具里面,而是由控制循环在这次 TodoWrite 成功之后触发。
// 源码位置:com.minicc.agent.AgentLoop.java
if (TodoWriteTool.NAME.equals(call.name()) && !result.error()) {
renderer.todoList(session.todos().items()); // 完整勾选清单渲染给人看
session.writeTodoSnapshot(); // M4:整份覆盖写当前列表
}快照文件和会话日志放在同一个目录下,名字叫 <sessionId>.todos.json,和日志的 <sessionId>.jsonl 一一对应。待办里的那个 TodoItem 直接复用了 M2 定义的结构,本来就能直接 JSON 序列化,这里不用做任何额外转换。
恢复时怎么用快照
/resume 恢复待办的时候,就不用再遍历整份日志,直接读快照、重建 TodoList 就可以了。
因为快照本身就是最新态,读出来是什么,当前进度就是什么,不需要从日志里一步步重算。
恢复出来的待办会交给 Renderer 渲染,格式和 M2 的待办展示完全一致:已完成的划掉,进行中的高亮。
⎿ 已恢复会话(24 条消息) · 待办 4 项:
☑ 阅读 OrderService / OrderController 现状
▶ 为 placeOrder 增加 dedupKey 并做去重
☐ 同步更新 CheckoutJob 的调用
☐ 新建"重复请求不产生重复订单"的测试用户可以马上知道进度:哪些已经完成,当前进行到哪一步,还剩哪些没做。
下一节我们讲 /resume 的回放重建,以及整个 M4 里需要专门处理的地方:中断检测。
4.6 resume:回放重建 Session + 中断检测
本篇涉及到的源码列表:
com.minicc.cli.command.ResumeCommand.java
com.minicc.persistence.SessionLoader.java
com.minicc.session.Session.java
com.minicc.cli.Renderer.java
前面几节我们把"怎么把会话写下来"讲完了。这一节我们讲反过来的那一部分:怎么把会话读回来。
这就是 /resume 命令。它的实现很简单,就是把日志逐行读回内存。但其中有一个地方需要专门处理,就是中断检测,我们重点讲一下它。
/resume 做什么
/resume 这个命令,M1 的文档里就已经列出来了,只是当时标注"后续版本提供"。M4 把它补上。
它的行为有三条。
/resume(不带参数):恢复本项目最近一次会话。上一节讲过,SessionPaths会按文件修改时间选出最新的那个.jsonl。/resume <sessionId>:恢复你指定的那次会话。- 恢复成功之后,后续的新消息会继续追加到被恢复的那个
.jsonl里,也就是续旧账本,不新建文件。
命令本身的实现很短:它先找到文件,再构造出对应的 sink,然后把恢复工作交给 SessionLoader。
// 源码位置:com.minicc.cli.command.ResumeCommand.java
public boolean run(String args) {
Path projectRoot = session.workingDir();
Optional<String> sessionId = (args == null || args.isBlank())
? paths.latestSessionId(projectRoot) // 不带参数:最近一次
: Optional.of(args.strip()); // 指定 sessionId
if (sessionId.isEmpty()) {
renderer.info("没有可恢复的会话。");
return false;
}
String id = sessionId.get();
SessionStore store = new SessionStore(paths.sessionLog(projectRoot, id));
TodoSnapshotStore todoStore = new TodoSnapshotStore(paths.todoSnapshot(projectRoot, id));
SessionLoader.Result result = loader.restore(session, id, store, todoStore);
if (result.messageCount() == 0) {
renderer.info("没有可恢复的会话。");
return false;
}
renderer.resumed(result.messageCount(), result.todos()); // 打印"已恢复 N 条消息、M 项待办"
return false;
}如果找不到会话,或者日志为空、读不出可恢复的消息,命令会给出提示,停留在当前会话,不报错退出。
回放:把日志放回内存
真正执行恢复的是 SessionLoader.restore。它可以概括为:把日志里的消息按行顺序放回 Session 的内存历史。
因为日志和内存用的是同一种消息类型,这里不需要做类型转换,直接放回去即可。
// 源码位置:com.minicc.persistence.SessionLoader.java
public Result restore(Session session, String sessionId, SessionStore store, TodoSnapshotStore todoStore) {
List<Message> messages = dropDanglingToolCalls(store.readAll()); // 读回 + 中断检测
if (messages.isEmpty()) {
return new Result(0, List.of()); // 没有可恢复的消息,保持当前会话不变
}
session.clear(); // 清空当前会话内存
session.attachPersistence(sessionId, store, todoStore); // 续写同一文件:新消息追加到被恢复的日志
for (Message message : messages) {
session.replay(message); // 只修改内存,不写入 sink
}
List<TodoItem> todos = todoStore.read(); // 从快照恢复待办
session.restoreTodos(todos);
return new Result(session.size(), todos);
}这段代码里有两个点,值得我们单独说明一下。
第一个点,没有可恢复的消息时,保持当前会话不变。 如果读出来是空的,我们直接返回,不修改当前会话。这样可以避免恢复失败时,把用户正在使用的会话清空。
第二个点,回放用的是 replay,不是正常的 append。 这里很容易出错。
我们回想一下 4.4:Session 的正常 append 方法是"既修改内存又落盘"。现在这些消息本来就是从日志里读出来的,如果回放时还走正常 append,就会把它们又原样写回日志一遍,日志里的每条消息都会重复。
所以 Session 专门留了一个 replay 方法,只修改内存、不写入 sink:
// 源码位置:com.minicc.session.Session.java
// 回放:把日志里读出的一条消息放回历史。与 append* 的区别是只修改内存,不写入 sink
public void replay(Message message) {
history.add(message);
}回放全部结束之后,后续的新消息才重新走"又改内存又落盘"的正常路径。
中断检测:摘掉悬空的工具调用
现在到了这一节我们需要专门处理的地方。
我们先看一个会出问题的场景。假设上次会话正好停在某个工具执行到一半的时候:模型说"我要调用 Edit",这条assistant消息已经写进日志了,但 Edit 还没执行完、或者结果还没来得及回填,你就按了 Ctrl-C,或者进程被强制终止了。
结果就是,日志里有一条"要求调用 Edit"的assistant消息,却找不到与它配对的工具结果消息。
如果原样把它回放进内存,历史里就留下了一个"有调用、没结果"的悬空工具调用。再把这段历史发给模型,大多数模型会直接报协议错误,因为在它们的协议里,一个工具调用必须配一个工具结果。
M4 的处理办法,是在回放之前先扫一遍消息,把这些"没有配对结果的工具调用"摘掉。
处理思路分成两步:先把所有已经出现过结果的工具调用 id 收集起来;再逐条检查assistant消息,只保留那些"有结果"的工具调用。
// 源码位置:com.minicc.persistence.SessionLoader.java
private List<Message> dropDanglingToolCalls(List<Message> messages) {
// 1) 先收集所有已出现结果的 toolCallId
Set<String> resolved = messages.stream()
.filter(message -> message instanceof ToolResponseMessage)
.flatMap(message -> ((ToolResponseMessage) message).getResponses().stream())
.map(ToolResponseMessage.ToolResponse::id)
.collect(Collectors.toSet());
List<Message> cleaned = new ArrayList<>();
for (Message message : messages) {
if (message instanceof AssistantMessage assistant) {
List<AssistantMessage.ToolCall> calls =
assistant.getToolCalls() == null ? List.of() : assistant.getToolCalls();
// 2) 只保留"有结果"的工具调用
List<AssistantMessage.ToolCall> kept = calls.stream()
.filter(call -> resolved.contains(call.id()))
.toList();
// 调用全被摘光、又没有文本 → 整条assistant消息丢弃
if (kept.isEmpty() && (assistant.getText() == null || assistant.getText().isBlank())) {
continue;
}
// 摘掉一部分时,换一条只带剩余调用的assistant消息;没摘就原样保留
if (kept.size() == calls.size()) {
cleaned.add(assistant);
} else {
// 保留 metadata:里面有思考模式的 reasoningContent,丢掉后恢复的工具调用轮次回传会被拒。
cleaned.add(AssistantMessage.builder()
.content(assistant.getText() == null ? "" : assistant.getText())
.properties(assistant.getMetadata())
.toolCalls(kept)
.build());
}
} else {
cleaned.add(message);
}
}
return cleaned;
}这里对assistant消息分了几种情况处理,我们按情况说明一下。
一条assistant消息的工具调用如果全被摘掉了,而它本身又没有任何文本,那这条消息就没有剩下的内容了,我们把整条丢掉。
如果只摘掉了一部分(它调了好几个工具,有的有结果有的没有),就换成一条只带着"有结果的那几个调用"的新assistant消息。正文和 metadata 都原样保留。
metadata 里有思考模式的 reasoningContent。重建时如果把它丢掉,恢复会话后再带工具调用去请求模型,模型会拒绝这次请求。
如果它的调用一个都不用摘,我们就原样保留。
这样处理完,重建出来的历史里,每个工具调用都配得上一个结果,发给模型就不会报协议错误了。
恢复之后
回放把历史重建好、中断检测去掉不完整的工具调用、待办从快照读回来之后,Renderer 就把恢复结果打印出来:
⎿ 已恢复会话(24 条消息) · 待办 4 项:
☑ 阅读 OrderService / OrderController 现状
▶ 为 placeOrder 增加 dedupKey 并做去重
☐ 同步更新 CheckoutJob 的调用
☐ 新建"重复请求不产生重复订单"的测试到这里,整段历史已经重新放进上下文,待办进度也已经显示出来,你可以直接接着上次往下做了。
