会话 —— 一行一条,坏行报行号
E05 的历史压得动,但还在内存里。关掉终端就归零——这不是小问题,它意味着 「记忆」和「进程」被绑死了。
这一章把历史挪到文件里。最小的做法是 JSONL:一行一条消息,追加写,从头读。
三个问题:
- 为什么是追加写,不是每次覆盖整份?
- 文件坏了,怎么让错误自带修复入口?
- 存下来的东西,凭什么保证下次能读回同样的形状?
Session.append(msg) --> 文件末行 +1 | Session.load(file) --> 逐行 JSON.parse --> messages[] | '-- 坏行: 抛 `${file}:${行号} 不是合法 JSON`一、本章终点:先跑起来
cd examples/mini-agentnode src/demo-session.ts本轮结束 6 条重载 6 条roles: user > assistant > tool > assistant > user > assistantERR: tmp-e06.jsonl:7 不是合法 JSON三行说明三件事:两轮对话落下 6 条;重新从文件读回来还是 6 条、顺序一致;第 7 行
被人塞了一句 not-json,读的时候直接报行号。
roles 那一行是这一章最重要的证据:第一轮是完整的四条
(user → assistant → tool → assistant),第二轮是两条。工具调用和它的结果都
在文件里,不是「只存用户说了什么」。
| 文件 | 行数 | 本章变化 |
|---|---|---|
src/session.ts |
37 | 新增:追加写 + 逐行读 |
src/demo-session.ts |
47 | 新增:本章入口 |
| 合计 | 1,032 | E05 的 948 + 本章 84 |
二、37 行
<!-- file: examples/mini-agent/src/session.ts -->
import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";import { dirname } from "node:path";import type { AgentMessage } from "./types.ts";/** * 追加写、逐行读。一行一条消息,坏行直接报行号。 * 没有数据库、没有迁移:这类文件的全部协议就是「别改格式」。 */export class Session { file: string; messages: AgentMessage[] = []; constructor(file: string) { this.file = file; } static load(file: string): Session { const session = new Session(file); if (!existsSync(file)) return session; const lines = readFileSync(file, "utf8").split(/\r?\n/); lines.forEach((line, index) => { if (!line.trim()) return; try { session.messages.push(JSON.parse(line) as AgentMessage); } catch { throw new Error(`${file}:${index + 1} 不是合法 JSON`); } }); return session; } append(message: AgentMessage): void { mkdirSync(dirname(this.file), { recursive: true }); appendFileSync(this.file, JSON.stringify(message) + "\n", "utf8"); this.messages.push(message); }}load 里两个 if 各有分工。 !existsSync 是「第一次用」——不是错误,
返回空会话。!line.trim() 是「末尾的空行」——split 之后最后总会多一个空串,
不跳过它就会报「第 N 行不是合法 JSON」。
append 之前先 mkdirSync。 路径可能是 sessions/2026-11-10/a.jsonl,
目录不存在时 appendFileSync 报 ENOENT,而且报的是文件路径,很容易误判成权限
问题。
行号从 index + 1 来。 数组下标 0 对应文件第 1 行。少了这个 +1,你会去改
错的下一行,然后发现「怎么改都不行」——因为差了一行。
JSON.stringify(message) 不挑字段。 它把整个对象写进去,包括 kind、
display、isError。这就是 E02 说「note 必须留在 AgentMessage 层」的原因:
一旦你在存盘前把它拍成 user 消息,kind 就永远丢了。
三、为什么不直接上 SQLite
三个理由,按重要性排:
- 协议只有一句话。 「一行一条 JSON」不需要 schema、不需要迁移脚本、不需要
驱动。出问题时
Get-Content就能看,Select-String就能查。 - 坏行是局部的。 第 7 行坏了,前 6 行还能读(如果你把「抛错」改成「跳过并 记录」)。数据库文件坏了,通常是整库打不开。
- 追加写天然可审计。 谁在什么时候写了什么,文件本身就是日志。
什么时候该换?同时满足两条就该换:需要按内容检索(「上周那次会话里提过
compact.ts 吗」)和会话数量上百。在那之前,SQLite 只让你多一个部署依赖。
四、入口:两轮 + 一次重载
<!-- file: examples/mini-agent/src/demo-session.ts -->
/** * E06 的终点:跑两轮 → 关掉进程 → 重新加载,历史还在。 * 运行:cd examples/mini-agent && node src/demo-session.ts */import { appendFileSync, rmSync } from "node:fs";import { Session } from "./session.ts";import { runAgent } from "./loop.ts";import { toLlm } from "./messages.ts";import { readTool } from "./tools.ts";import { createMockProvider } from "./provider/mock.ts";const file = "tmp-e06.jsonl";rmSync(file, { force: true });const session = Session.load(file);async function turn(input: string): Promise<void> { session.append({ role: "user", content: input }); const result = await runAgent({ provider: createMockProvider(), tools: [readTool], messages: [...session.messages], maxTurns: 2, project: toLlm, }); for (const message of result.messages.slice(session.messages.length)) { session.append(message); }}await turn("读一下 README.md");await turn("再说一句");console.log(`本轮结束 ${session.messages.length} 条`);/* 换个「进程」:只从文件读,不碰内存 */const reloaded = Session.load(file);const roles = reloaded.messages.map((m) => m.role).join(" > ");console.log(`重载 ${reloaded.messages.length} 条`);console.log(`roles: ${roles}`);/* 坏行:文件第 7 行手动塞一句非 JSON */appendFileSync(file, "not-json\n", "utf8");try { Session.load(file);} catch (error) { console.log(`ERR: ${(error as Error).message}`);}turn() 里那个 slice(session.messages.length) 是这一章的隐蔽坑:runAgent
返回的是整个历史数组(包括你传进去的),不是「新增部分」。不切就 append,
每轮都会把旧消息重复写一遍,文件长度指数增长。
[...session.messages] 的拷贝也有原因:runAgent 内部会 push 新消息,直接传
session.messages 会让「跑模型」和「改会话」共用一个数组,length 就再也算不出
「新增部分」了。
五、这一版的三个洞
洞一:文件无限长。 会话跑一个月,load 每次都要读完整份文件。至少要有
「按行数截断」或「压缩时重写文件」(把已压掉的早期消息从磁盘上删掉)。注意:重写
就是覆盖写,和追加写的原子性不在一个量级,得先写临时文件再 rename。
洞二:并发写只有一个进程能赢。 两个 mini-agent 同时 append 到同一个文件,
小写入通常不会撕裂(内核保证 append 的原子性),但顺序不可预期——你会得到
一段交错的历史。真正的多进程会话需要「每会话一个锁文件」或「按会话分目录」。
洞三:没有版本号。 今天写的 {role:"note", kind:"summary"},明天你把 kind
改名成 type,旧文件就读不回来了。标准做法是第一行写一条 header:
{"type":"session","version":1},读到不认识的版本就拒绝而不是硬解。Pi 就是这么
做的(session-manager.ts:43 的 SessionHeader)。
六、代码地图
| 文件 | 关键符号 | 下一章怎么用 |
|---|---|---|
src/session.ts |
Session.load() / append() |
E08 的 --session 参数 |
src/demo-session.ts |
turn() 的 slice |
任何「跑完存盘」的循环都照抄 |
tmp-e06.jsonl |
6 行 + 1 行坏数据 | 看完就可以删 |
自检
load里如果去掉if (!line.trim()) return,第一次读一个正常文件会怎样?turn()里的slice(session.messages.length)去掉,跑两轮后文件有几行?- 想让「第 7 行坏掉」时前 6 行仍然可用,
load要改成什么样?这算不算更好的 默认行为?
参考答案:
第 1 题:会报 第 N+1 行不是合法 JSON——因为文件末尾的换行让 split 多出
一个空串。这个错误只在「文件以换行结尾」时出现,也就是几乎总是出现。
第 2 题:第 1 轮写 4 条(user/assistant/tool/assistant),第 2 轮如果整段 重写就是 4 + 6 = 10 条,且历史里出现重复的 user——模型会看到自己说过两遍同样的 话。轮数越多,重复越离谱。
第 3 题:把 throw 换成「记录 {line, error} 到 session.warnings,然后
continue」。这不一定是更好的默认:静默跳过会让「历史缺了一段」变得不可见;
更好的做法是默认抛(强制用户处理),另给一个 load(file, { skipBad: true })
的显式开关。
七、与 Pi 的对照(可选)
Pi 的会话在 packages/coding-agent/src/core/session-manager.ts,1,836 行,
而你是 37 行。多出来的部分主要不是存储,而是形状:
- 文件第一行是 header(
type: "session"),带版本与元信息; - 每条 entry 有 id 和 parent,可以还原分支树——
leafId决定「当前在哪个 分支上」; - 同一份文件既能投影出「给模型看的 messages」,也能投影出「给 UI 看的树」。
你的 JSONL 是线性的:一个文件一条时间线。这是有意的——先有线性,才谈得上分支。
八、下一章
工具、压缩、会话,三块都齐了。但它们只能在代码里改:想给 read 加一行审计日志、
想在每次工具调用前加权限检查,你都得动 tools.ts 和 loop.ts。
E07 做钩子:在「工具调用前 / 后」「每轮结束」这几个点上开孔,让扩展代码不改内核
也能插进去。node src/demo-hooks.ts 会打印一条被钩子改写过的工具结果。