Agent 框架源码
第 5 节:模型可见即已记录,日志是唯一真源
dsh 的硬规矩是「模型可见即已记录」:每个请求都能从仅追加日志重建。assistant/message 进历史、assistant/attempt 只留日志;文件按 generation 排他发布,已提交路径绝不覆盖。代价是写放大与删不掉。
- 历史来源
- deriveMessages 投影从仅追加日志算出模型历史,纯函数
- 失败结算
- assistant/attempt只留日志不进模型历史,避免污染上下文
- 文件发布
- 旁边写新 generation已提交路径绝不重命名、替换或删除
- 格式迁移
- vN → vN+1 链式每个迁移包只负责一个相邻步骤
一条硬规矩:模型可见即已记录
dsh 架构文档里这句话是加粗的:每个模型请求都必须能从日志重建。新增任何模型可见输入,就得同时新增一个会话事件;想改已有消息的内容,得注册一个「纯消息投影」,而不是直接改内存数组。
「纯」这个字是重点。投影必须是 (事件) → 消息 的纯函数:同样的日志永远得到同样的结果,不依赖当前时间、不依赖进程内状态。因为独立读取器(导出、审计工具、另一个进程)会显式传入同一批处理器,重算一遍给你看。
Session 日志(仅追加,不可原地改)
│
├─ deriveMessages() 投影出模型历史
│ └─ 只读已提交事件,纯函数
│
├─ assistant/message 成功结算:嵌着产生它的完整紧凑流
├─ assistant/attempt 失败/重试/取消/流错误:只留日志,不进模型历史
│
└─ fork / 恢复 / transcript / 遥测 / 持久化
全部从这些持久结算派生,而非从内存快照
assistant/message 和 assistant/attempt 的区别就在这里:前者进了模型历史,后者只留在日志里供复盘。一次失败的重试如果也进历史,模型会以为自己说过那些话,上下文立刻被污染。
generation:为什么旧文件绝不覆盖
会话文件不是 session.json 一个名字写到黑,而是按版本世代(generation)命名:
| 情况 | 文件名 | 保护了什么 |
|---|---|---|
| JSONL v0 | session.jsonl[.zstd] |
向后兼容老会话 |
| v1 及以后 | session.vN.jsonl[.zstd] |
版本可辨,可并存 |
| 写入新版本 | 旁边排他发布新文件 | 已提交的世代路径绝不重命名、替换、删除 |
| 读取 | 选数值最高的规范 generation | 不被半成品或旧版覆盖 |
这套规则解决的是「升级过程中崩了怎么办」。如果就地改文件,改到一半断电,这个会话就废了。改成「旁边写一份新文件、排他发布」,最坏情况是留下一个多余的世代,原文件完好。
迁移也不是一个大函数,是相邻版本链:每个迁移包只负责一个 vN → vN+1,读取时把静态确定的相邻迁移链组合一次执行,然后返回校验过的当前逻辑事件。这样加版本只需要写一小段,不需要维护「从 v1 到 v9」的组合逻辑。
还有一条细节值得注意:只读打开(stat、list)不会发布后继文件,也不加载事件,只转换 header。这是为了让 list 这种高频操作不去碰几 MB 的正文。
代价:写放大与「删不掉」
仅追加日志不是免费的。要把账单说清楚,否则容易在自建系统里盲目照搬:
| 收益 | 代价 |
|---|---|
| 任何一次事故可完整复盘 | 文件只增不减,长期会话需要压缩或归档策略 |
| fork 只需按事件计数切开 | 切点语义要精确,切在 step 中间会留下半截调用 |
| 格式可演进,旧会话不废 | 每个版本要维护一条迁移链,测试量随版本线性增长 |
| 「模型看到什么」可被独立验证 | 投影必须是纯函数,任何依赖时钟或全局状态的写法都会破坏它 |
「删一条消息」是最典型的例子。用户要求删掉某句话,系统实际做的是追加一条撤销事件,而不是从文件里抹掉。所以合规场景要的是「可证明删除」时,这套结构需要额外的物理清除流程,不能只靠日志。
反过来说,如果你的场景不需要审计、不需要 fork、不需要跨版本迁移,那这套「日志即真源」就是过度设计。判断标准很简单:你会不会需要在三天后回答「模型当时到底看到了什么」。会,就值得;不会,内存消息数组够用。
下一节看日志里最重的一类事件:工具调用与结果,以及它们之间那七道关。
变更记录
| 日期 | 类型 | 改了什么 | 范围 |
|---|---|---|---|
| 新建 | 讲清日志即真源的收益与两笔代价,含物理删除的缺口 | 全页 |