Pi Agent 源码级教程
E06

会话 —— 一行一条,坏行报行号

1,584 字 · 含 95 行代码 · 约 9 分钟

E05 的历史压得动,但还在内存里。关掉终端就归零——这不是小问题,它意味着 「记忆」和「进程」被绑死了。

这一章把历史挪到文件里。最小的做法是 JSONL:一行一条消息,追加写,从头读。

三个问题:

  1. 为什么是追加写,不是每次覆盖整份?
  2. 文件坏了,怎么让错误自带修复入口?
  3. 存下来的东西,凭什么保证下次能读回同样的形状?
text
  Session.append(msg) --> 文件末行 +1                       |  Session.load(file) --> 逐行 JSON.parse --> messages[]                            |                            '-- 坏行: 抛 `${file}:${行号} 不是合法 JSON`

一、本章终点:先跑起来

bash
cd examples/mini-agentnode src/demo-session.ts
text
本轮结束 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 -->

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

三个理由,按重要性排:

  1. 协议只有一句话。 「一行一条 JSON」不需要 schema、不需要迁移脚本、不需要 驱动。出问题时 Get-Content 就能看,Select-String 就能查。
  2. 坏行是局部的。 第 7 行坏了,前 6 行还能读(如果你把「抛错」改成「跳过并 记录」)。数据库文件坏了,通常是整库打不开。
  3. 追加写天然可审计。 谁在什么时候写了什么,文件本身就是日志。

什么时候该换?同时满足两条就该换:需要按内容检索(「上周那次会话里提过 compact.ts 吗」)和会话数量上百。在那之前,SQLite 只让你多一个部署依赖。


四、入口:两轮 + 一次重载

<!-- file: examples/mini-agent/src/demo-session.ts -->

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 行坏数据 看完就可以删

自检

  1. load 里如果去掉 if (!line.trim()) return,第一次读一个正常文件会怎样?
  2. turn() 里的 slice(session.messages.length) 去掉,跑两轮后文件有几行?
  3. 想让「第 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 会打印一条被钩子改写过的工具结果。