重启也不失忆:用 JSONL 给 Agent 会话做持久化

Agent 的多轮上下文通常保存在内存中,程序一退出就会丢失。掘金“从零构建 Agent”系列第十篇展示了如何用 JSONL 保存完整消息、工具调用关系和会话标识,并在重启后恢复历史,让 Agent 跨进程继续对话。

在开发 Agent 应用时,很多开发者都会遇到一个基础但容易被忽略的问题:模型能记住上下文,是因为每一轮请求都把历史消息一起发了过去;可一旦程序退出,这些保存在内存里的历史也会随之消失。重新创建一个 Agent,得到的只能是一个没有任何前文的新会话。

掘金技术社区“从零构建 Agent”系列的第十篇,聚焦的就是这个问题:如何让 Agent 把多轮对话保存到磁盘,并在程序重启后恢复原来的会话。文章以一个读取文件的工具调用流程为例,展示了基于 JSONL 的会话持久化方案,包括消息保存、逐行追加、会话标识管理以及跨进程恢复等实现细节。

为什么连续对话还需要持久化

在前一篇中,Agent 已经可以实现连续对话:第一轮问答保留在 agent.state.messages 中,第二次请求会把这些消息和新问题一起发送给模型,模型才能基于前文作答。

但这种方式依赖当前进程。只要程序持续运行,历史记录就可以继续使用;程序一旦退出,内存中的消息就不复存在。如果希望今天关闭程序,明天打开后还能接着提问,就需要把消息保存到进程之外。

所谓会话持久化,就是将会话内容写入磁盘文件,使其在程序退出后仍然保留。下一次启动时,程序再读取这些内容,新 Agent 就能继续使用原来的历史。模型理解上下文的方式并没有变化,变化的是历史消息可以跨越两次程序运行。

文章沿用了该系列此前的示例:用户要求 Agent 读取 note.txt 第 2 行,模型调用 read 工具取得文件中的验证代号,再回复用户。这段对话通常包含四条消息:

  • 用户提出读取要求
  • 模型请求调用 read
  • read 返回读取结果
  • 模型给出最终回答

因此,保存的对象不能只是最后显示在终端里的结果,而应当是完整的消息对象及其顺序。工具调用与工具结果之间的对应关系,也需要通过原有的调用标识保留下来。

JSONL 结构:文件头加逐条消息记录

会话会不断产生新消息。如果文件采用 JSONL 格式,每一行保存一个独立的 JSON 对象,就可以在文件末尾追加新记录,而不必每次重写此前的全部内容。

在该示例中,作者使用 pi 的原生 JSONL 会话存储。第一行是文件头,保存会话基本信息;后续行记录会话内容。完成一轮读取后,文件结构可以理解为:

  • 第 1 行:文件头,标识这是哪个会话
  • 第 2 行:用户提出读取要求
  • 第 3 行:模型请求调用 read
  • 第 4 行:read 返回读取结果
  • 第 5 行:模型给出回答

在给出的结构示意中,文件头包含 kind: "header"、version: 4、id: "chapter-10" 和 cwd 等字段。后续记录使用 kind: "entry",并通过 type: "message" 表示该行承载的是一条消息。

每条消息外层还有用于组织会话文件的字段,例如记录标识、父记录标识、顺序编号等。文章特别提醒,要区分两种标识:外层的消息记录标识用于组织会话文件,消息内部的工具调用标识则用于关联一次工具调用及其结果。恢复会话时,这两层关系都需要保留。

保存与恢复的完整路径

按照示例实现,持久化流程被拆成三步:准备会话文件、写入消息、加载消息并交给新 Agent。

在保存侧,应用先通过 JsonlSessionRepo 创建和打开磁盘会话。代码中指定保存目录后,调用 repo.create() 创建会话。该方法会准备目录和文件头,再创建绑定到该文件的 Session 对象。

保存一条完整消息的入口是 session.appendMessage(message)。以工具结果消息为例,消息本身已经包含调用标识和读取到的代号。pi 会为其增加会话记录信息,再将整条记录写入文件。其内部路径包括:

  • Session 将消息包装成记录
  • JsonlSessionStorage.appendEntry() 补齐父记录、顺序编号、时间戳等字段
  • appendMutation() 将记录写入文件
  • encodeMutation() 将记录转为 JSON 文本并在末尾加换行
  • fs.appendFile() 将这行文本追加到会话文件

真正把编码结果交给文件系统的语句是:

await this.fs.appendFile(this.metadata.path, encodeMutation(mutation))

先把记录编码成一行,再追加到文件末尾,这就是消息落盘的核心动作。

在恢复侧,新进程需要把文件中的记录读回来,再还原为按对话顺序排列的消息。示例代码给出了三步:

const session = await repo.open(metadata);
const entries = await session.findEntriesOnBranch({ order: "oldestFirst" });
const { messages } = buildSessionContext(entries);

这三行依次完成从文件到消息的转换。得到的数组仍然包含原来的用户输入、工具调用、工具结果和回答。将其传给新 Agent 的 initialState.messages,Agent 初始化时就会接收这份历史。下一次提问时,历史与新问题一起发给模型,就能接着原来的对话回答。

也就是说,恢复过程可以概括为:文件中的 JSON 文本,变成有序的会话记录,再变成新 Agent 的历史消息。文章也指出,加载文件不会重新执行工具调用,工具结果会直接作为历史内容使用。

跨进程实验验证与常见注意点

为了验证效果,示例程序先后启动两个独立进程。第一个进程读取随机代号并保存会话,退出后,第二个进程加载会话并追问这个代号。

为便于观察,第一个进程保存成功后会删除原始 note.txt。第二个进程收到的新问题不包含代号,需要从恢复的历史消息中取得。

运行 node labs/10-session-persistence.ts 后,预期输出节选显示:

phase: save, pid: 41001
restored roles: (empty)
file content: "用途:验证会话恢复\n本次验证代号:read-841273"
final answer: read-841273
saved roles: user -> assistant -> toolResult -> assistant
source file removed; save process will exit
phase: resume, pid: 41002
restored roles: user -> assistant -> toolResult -> assistant
source file exists: false
final answer: read-841273
saved roles: user -> assistant -> toolResult -> assistant -> user -> assistant

两个 PID 表明问答发生在不同进程中;restored roles 表明第二个进程已经取得原来的四条消息。对照最初文件内容与第二次回答,代号保持一致。追问结束后,保存的消息从四条增加到六条,说明新的一问一答也进入了同一会话。

文章同时提醒,这些输出用于观察结果,不会自动断言模型回答正确;请求或保存失败时程序会报错,运行结束后,父进程会清理实验创建的临时目录和会话文件。

对于正在搭建 Agent 工具的开发者来说,这个示例的价值在于把会话持久化拆成了几个明确边界:会话基本信息由文件头记录,消息按原始结构保存,追加写入依赖 JSONL,恢复时再还原为有序历史。这样,重启后的 Agent 就能根据之前的用户输入、工具结果和回答继续对话,并将新产生的消息接着保存。

文章还列出了源码核对入口,包括 repo.ts 中的会话创建与打开、session.ts 中的消息包装与查询、codec.ts 中的文件记录编码、storage.ts 中的文件写入与加载,以及 context.ts 中的记录到消息转换。对于希望自行实现 Agent 会话存储的读者,这些模块提供了一个可直接对照的参考路径。

原创文章,作者:点点,如若转载,请注明出处:https://www.dian8dian.com/chong-qi-ye-bu-shi-yi-yong-jsonl-gei-agent-hui-hua-zuo-chi

Like (0)
点点的头像点点
Previous 2026年10月7日 下午2:00
Next 2026年10月7日

相关推荐

  • 多个 AI Agent 同时改内容,osFoundry Merge Station 把审阅入口放到同一处

    当多个 AI agent 开始直接修改笔记、数据管道和文档时,团队协作的问题会很快从“能不能改”转向“改在了哪里”。osFoundry 提供的 Merge Station 试图把这类分散变更集中到同一个审阅列表,让来自 agent、同事和本地 sandbox 的提交在同一处查看、比较、批准或拒绝。

    2026年11月10日
    00
  • AI 编程把代码写快了,却把 CI 卡住了:Linear 的持续集成改造记录

    AI Agent 让代码产出更快,但 Linear 发现验证代码的 CI 成为新瓶颈。通过更换运行环境、优化编译器、减少关键路径开销和降低重复初始化成本,Linear 在测试套件接近四倍增长的情况下,将 PR 等待时间从 6 分钟以上压缩到略高于 5 分钟,并把单次测试的 runner 时间削减约一半。

    2026年9月23日
    00
  • Stack Overflow for Agents 上线三个月后,开始回答“AI 编程助手如何信任知识”这个问题

    上线三个月后,Stack Overflow for Agents 不再只强调把 Agent 的答案保存下来,而是开始解决 AI 编程助手更现实的问题:知识如何可信、可控、可复用。

    AI编程 2026年9月17日
    00
  • AI Agent 的动作门控阈值,不能只靠网格搜索选最高分

    在 AI Agent 调用工具前加“动作门控”并不新鲜:评分器给拟执行动作打出 0 到 1 的分数,超过阈值就执行,否则放弃或转人工。Dev.to AI 的一篇文章提醒,真正容易出错的是阈值怎么调。如果在有限标注数据上对多个候选阈值做网格搜索,再挑期望收益最高者,离线报告容易虚高。文章把这种现象称为“赢家诅咒”:多个带噪声估计中的最大值天然偏高。

    2026年10月20日
    00
  • 当 Agent 长时间运行:Goodfire 用“内部探针”降低失控监测成本

    Goodfire 推出面向 AI Agent 的低成本监控方案:不再让第二个模型全程审查输出,而是通过内部探针读取模型运行状态。测试显示,监控约 100 万次交互的成本约为 185 美元。

    2026年10月10日
    00
  • 从“会思考”到“能点击”:Kotlin 与 Python 桥接让手机端 Agent 具备执行能力

    手机端 AI Agent 要从聊天式推理走向真实操作,首先得解决两个基础问题:怎样读取当前屏幕,怎样调用系统完成点击、输入和启动应用。

    AI编程 2026年10月13日
    00
  • 让 ChatGPT 直接操作 Laravel 应用:一次基于 OAuth 的 GPT Action 工程实践

    开发者通过 Laravel、OAuth 与 GPT Action,让 ChatGPT 能以用户身份调用现有应用 API。这一实践揭示了对话式 Agent 接入 Web 系统时的关键工程问题。

    2026年8月25日
    00
  • 27B 编码智能体本地化:16.5GB 文件如何进入单张 24GB GPU

    POCKET-27B-Pi 以 16.5GB Q4_K_M GGUF 文件给出 27B 编码智能体的本地部署样本:混合注意力结构压低 64K 上下文 KV 缓存,使权重与缓存可进入单张 24GB GPU,并在 Terminal-Bench 2.1 测试中展现出高于原始模型的完成率。

    AI编程 12 mins ago
    00
  • Claude Code 重构 Projects:并行多会话让 AI 编程从单线程走向协作

    Anthropic 重构 Claude Code Projects 后,开发者可以在同一项目内并行运行多个独立会话,让 AI 同时处理测试、重构和 Bug 修复。AI 编程助手正在从单线程问答工具,转向多任务协作系统。

    2026年9月19日
    00
  • MCP注册表达到54,988条:用URL参数缩小服务器候选名单

    MCP 注册表在 2026-11-02 计数为 54,988 条,人工浏览已难以完成筛选。通过 URL 参数组合下载量、运行方式、许可证、维护状态等条件,开发者可以把筛选过程变成可复用、可分享的查询。

    2026年11月4日
    00
  • 当 Agent 开始参与架构讨论:Whiteboard 把软件设计前置环节搬进同一个界面

    Whiteboard 是 YC W26 推出的开源桌面应用,它把架构设计、白板协作和 Agent 参与放在同一个界面中,试图重新定义 AI 时代的软件设计前置流程。

    2026年9月26日
    00
  • 当 AI 编程助手说“测试通过”:OpenHarnX 想先验证它到底改了什么

    当 Coding Agent 声称测试通过时,开发者如何确认它没有悄悄修改测试?开源项目 OpenHarnX 尝试通过锁定测试副本、沙箱验证和签名证据,为 AI 编程结果提供独立核查机制。

    2026年10月8日
    00
  • 单个 Agent 不够用的时候:拆解 MyCodeAgent 中多 Agent 团队协作的设计与退场

    MyCodeAgent 曾推出实验性多 Agent 协作系统 AgentTeams,尝试通过团队创建、任务分发、结果收集和协调者合并,让多个 Agent 并行处理代码重构、测试等复杂任务。该机制最终被移除,但其设计揭示了 AI 编程工具在处理大型工程任务时必须面对的任务分解、上下文隔离和状态同步问题。

    AI编程 2026年9月2日
    00
  • AI Agent 费用失控的解法:把预算上限做成一次 403 调用失败

    当 AI Agent 自主调用工具、运行循环、生成结果时,开发者最容易忽视的不是模型能力,而是费用边界。Dev.to 上一篇文章提出,Agent 的预算上限不应只呈现为仪表盘里的数字,而应该写进工具调用层:一旦超出预算,系统就返回一次类似 403 的调用拒绝,而不是等到账单出现后再复盘。

    2026年10月26日
    00
  • 把安全审计交给编程 Agent 前,Cloudflare 给它加了一道独立复核

    Cloudflare 开源 security-audit-skill,将 AI 编程 Agent 的安全审计拆成发现、验证、记录和复核流程,要求漏洞结论必须有原始代码可验证的证据。

    AI编程 2天前
    00
  • 65 行 CLAUDE.md 规则实测:让 Claude Code 少写 80% 无效代码

    掘金作者实测发现,给 Claude Code 加一份 65 行 CLAUDE.md 规则后,AI 生成代码从 380 行、12 个文件降至 75 行、2 个文件,过度设计和顺手修改明显减少。

    AI编程 2026年8月27日
    00
  • Spring AI 实战复盘:单测全绿,为何 AI 产品仍会失效

    一位开发者在 Spring AI 项目中写了 80 多个单元测试,全部通过,但用户仍遇到 AI 自行生成「岗位描述为空」的回复。该案例显示,AI 应用工程化不能只依赖传统单测,还需要行为测试、评估基线和完整的上下文设计。

    AI编程 2026年9月29日
    00
  • ZCode 被曝在登录状态下打包上传 Git 历史,本地 AI 编程工具的隐私边界再受拷问

    ZCode 被曝在登录状态下自动打包并上传用户完整 Git 历史至云端,且无法本地解密,引发开发者对闭源 AI 编程工具隐私边界的担忧。

    2026年9月19日
    00
  • Spring AI 让内部订单和运维 API 被 Claude 调用:Java MCP Server 实践

    当运维同事想在 Claude 中查询一笔订单时,他能做的只是把订单 ID 粘贴到聊天框,等待模型回复无法访问数据库,再手动把日志贴回去。这类场景暴露出一个现实问题:企业内部有订单服务、库存服务和日志平台,但 AI 客户端并不能直接触达这些系统。Dev.to AI 的一篇技术文章给出的方案,是用 Spring AI 构建一个 MCP Server,把 Java 端点转换成 Claude 和 Cursor 可以直接调用的工具。按照文章说法,示例代码是一个完整项目,即使没有 LLM API key 也可以运行。对于需要让 AI 调用内部订单或运维 API 的团队,这提供了一个不必逐个修改客户端的接入路径。文章将问题拆开:MCP 不是为了解决“模型不够聪明”,而是解决“模型够不到你的系统”。如果产品经理使用 Claude Desktop 查询数据,后端工程师使用 Cursor 写代码并顺带查看生产订单,自研支持代理也需要查订单,那么三种客户端就意味着三种集成方式。其中,Claude Desktop 需要 MCP 配置,Cursor 需要 .cursor/mcp.json,自研代理需要 JSON Schema 完成 function calling。开发者要为每种客户端写三套描述、三套参数校验和三套错误处理。如果下个月出现第四种客户端,集成工作还要再来一次。MCP 的价值在于把 M×N 变成 M+N:所有 M 个客户端实现同一协议,所有 N 个系统也暴露同一协议,中间不再需要两两配对。文章用充电接口作类比:在 USB-C 出现之前,圆口、扁口、排线各自对应特定设备;接口统一后,充电器只需要供电,手机只需要接收。MCP 在 AI 工具调用中扮演的,就是这种统一接口角色。文章还纠正了两个常见误解。第一,MCP 不是模型能力,而是一种传输协议,和 HTTP 处于类似层级。模型并不知道 MCP 存在,它看到的只是“这里有一些工具,以及这些工具参数长什么样”。真正把 MCP 工具列表转换成模型可理解的 Function Calling 格式的,是 Host。第二,写好 MCP Server 并不意味着模型一定会正确使用它。工具名称、描述和参数文档是否清晰,会直接影响模型选择。例如,一个查询接口如果只写成“query order”,模型在想查用户时也可能调用;如果写成“按订单号查询订单详情;订单号以 SO 开头”,命中率会发生变化。因此,文章强调的重点不仅是“如何暴露 API”,还包括“如何让模型正确调用”。这篇实践文章把 MCP 从协议概念落到了 Java 工程语境。对于已有 Spring AI 和内部 API 体系的团队,真正的变化不在于让模型“更会回答”,而在于把订单、库存、日志等系统以统一方式暴露给多个 AI 客户端。这也把接口设计的要求前移了。过去,API 文档主要给人看;在 MCP 场景中,工具描述还要给模型看。命名是否准确、参数说明是否足够具体、错误返回是否可被理解,都会影响 AI 是否能正确执行任务。对于需要在 Claude、Cursor 和自研控制台之间复用内部能力的团队来说,MCP Server 更像是一层新的接口治理。

    2026年11月11日
    00
  • 长会话 Agent 如何避免上下文失控:DeepSeek Harness 的压缩与目标管理方案

    DeepSeek Harness 通过上下文压缩与目标管理两套机制,解决长会话 Agent 中 token 膨胀、工具输出过载和目标漂移问题,为长时任务提供工程化思路。

    AI编程 2026年9月14日
    00