Axl的JSONL事件日志为何是权威?追加写、确定性重放与重启对账的代码级解析
Axl的JSONL事件日志为何是权威?追加写、确定性重放与重启对账的代码级解析
在 Axl 中,每个 AI Agent 会话的全部历史都不落在数据库,而是落在一个只追加(append-only)的 JSONL 事件日志文件里。这个日志就是 Axl 唯一的权威数据源(source of truth):内存投影、索引和 UI 状态都由它派生,随时可丢弃重建。本文将从代码层面拆解 Axl 的三块基石:原子追加写、确定性重放与重启对账,帮你理解"事件溯源(Event Sourcing)"在 Agent 框架中如何真正落地。
🧱 一条铁律:事件日志是唯一"权威"
Axl 的开发文档把这条原则列为项目十条不可妥协的规则之一:
- The JSONL event log is authoritative.
- The daemon is the only owner of the agent loop.
原文见 DEVELOPMENT_GUIDE.md。文档对"权威"的定义非常干脆(DEVELOPMENT_GUIDE.md):
- 事件日志是权威的;内存投影、索引、UI 状态都是派生品,用完即弃;
- 修改规范状态的代码,必须先追加事件,再更新派生状态。
每个会话对应一个 <sessionId>.jsonl 文件,默认存放在 ~/.axl/sessions/ 下(DEVELOPMENT_GUIDE.md)。这种"一个会话一个文件"的布局让对账、隔离和迁移都变得极其简单——这也是后文重启对账能成立的前提。
| 数据 | 地位 | 丢了会怎样 |
|---|---|---|
sessions/*.jsonl 事件日志 |
权威(authoritative) | 会话历史丢失,不可接受 |
| 内存中的事件树、投影 | 派生(derived) | 重新读日志即可重建 |
| TUI / Web 端 UI 状态 | 派生(disposable) | 客户端重新订阅即可恢复 |
✍️ 原子追加写:appendDurably 的四步写路径
追加写的核心实现在 jsonl-event-log.ts 的 appendDurably 函数里。它保证了一条铁律:事件行要么完整存在,要么完全不存在,不会出现"半行"。
四步走:
- 记录写前大小:打开文件后先
stat拿到写前偏移量before; - 固定位置写入:把"编码后的事件 +
\n"按before + written偏移逐段写入,而不是依赖操作系统缓冲的普通 append; - 刷盘:写完整行后执行
handle.sync()(fsync),确保落盘; - 失败即回滚:任何一步抛错,立即
truncate(before)回到写前大小并再次 fsync,把半行数据彻底抹掉。
配合另外两处细节,写入路径才称得上"坚固":
- 串行化:所有
append/read操作通过 jsonl-event-log.ts 中的 Promise 链enqueue排队,多个写入者不可能交错出"你一行我一字节"; - 先脱敏、后落盘:
append在入队前先用redactEventForStorage抹掉密钥等敏感字段;事件编码后若超过MAX_CANONICAL_EVENT_BYTES,会走"外置大对象(blob externalization)"的降级路径,实在无法无损外置则抛出EventLogMigrationRequiredError,由 daemon 隔离该会话并提示axl session migrate-events迁移。
文件与目录的权限也很克制:ensureLogFile 创建目录 0o700、文件 0o600,且用 wx+ 模式保证"已存在则不覆盖"(jsonl-event-log.ts)。
⚡ 崩溃恢复:写到一半断电,日志会怎样?
即使有原子写保护,仍存在一个窗口:进程在 sync 完成前被杀(断电、OOM)。此时文件末尾可能残留一截不完整的行(torn tail)。
Axl 的读路径把它当作一等公民处理,核心是纯函数 decodeEventLogBytes(jsonl-event-log.ts):
- 按
\n切分,只有以换行结尾的完整行才算已提交; - 最后一个换行之后的字节全部视为 torn tail,被排除在
cleanByteLength之外; - 任何已提交行解析失败则抛出带文件路径和行号的
EventLogCorruptionError,而不是静默跳过。
随后的 readAndRecover(jsonl-event-log.ts)会调用 truncateDurably(truncate + fsync)把 torn tail 持久化地从文件中截掉,并返回 recoveredBytes 供上层感知恢复了多少字节。
更妙的是测试侧还有一条"固定点"不变式:event-reader-fuzz.ts 作为 fuzz 入口,要求"对干净前缀重新解码的结果必须与第一次完全一致"——读路径对任意(哪怕随机生成的)输入都是确定性的,这正是"权威日志"敢于被机器反复校验的底气。
🔁 确定性重放:把录制的会话日志当回归测试
replay.ts 提供了一个把日志当作"可执行规约"的能力(replay.ts 的 replaySessionLog)。它的流程是严格的五连:
- 打开源日志并构建 SessionTree——单次按追加顺序扫描即可检测重复 ID、父事件缺失、环、多个根、跨会话事件;
- 工具调用完整性校验:
verifyToolCallIntegrity沿每个分支检查每个tool.result恰好回应本分支上同一个callId、同一个工具名的tool.call;分支尖端允许有未应答的调用(中断的会话可以"工具做到一半"就结束); - 重新追加:把源日志的每个事件通过普通的持久写路径逐条追加到一个空的目标日志(目的路径非空直接报错);
- 读回:重新读取目标日志;
- 逐字节比对:
JSON.stringify(读回) !== JSON.stringify(源)即抛出ReplayError——"重放与源日志发生分歧"。
注意这里模型响应和工具结果都是从录制的日志中"打桩"取出的,没有任何东西真实运行。换句话说:写入路径 + 读回路径 + 树重建这条链路本身就是被测对象,任何让"读出来 ≠ 写进去"的改动都会在测试里暴露。相关用例见 replay.test.ts 与 jsonl-event-log.test.ts。
⚖️ 重启对账:daemon 如何用命令台账自查
真正的难点不在日志本身,而在**"接受了命令、但还没来得及写日志就崩了"**的中间态。Axl 的答案是双账本对账:
- 命令日志(Command Journal):command-journal.ts 记录两类条目——
accepted(含幂等键、方法、operationId、请求哈希)和succeeded/failed。它回答"我答应过什么"; - 会话事件日志:回答"实际发生了什么"。对账时以它为准。
daemon 启动流程(daemon.ts 的 start()):
DataDirectoryLock.acquire——同一数据目录只允许一个 daemon 独占,杜绝双写;scanLegacyEvents()——扫描sessions/*.jsonl,把需要迁移的旧格式日志隔离(quarantine)而非带着跑;CommandJournal.open+commandJournal.reconcile(...)——对每条"已接受但无完成记录"的命令,回调reconcileAcceptedMutation完成对账。
对账的精髓在 session-manager.ts:
| 场景 | 对账动作 |
|---|---|
| 日志不存在 | 视同命令从未生效;session.delete 就真的删,session.create 则静默返回,客户端凭幂等键重试 |
| 日志存在 | 用 operationId 过滤日志事件作为"证据":根事件必须是 session.created 且 operationId 匹配,否则报 corrupt_session |
证据只到一半(如 interrupt.requested 有了但终态没有) |
走恢复路径 abortRecoveredDelivery / abortRecoveredTurn 补记终态事件,而不是让会话卡死 |
这就是"权威日志"的直接收益:内存里的一切都不重要,重启后拿命令台账去问日志,就能把每个悬空操作收敛到一个确定的答案——要么补完、要么判死、要么放行重试。
✅ 快速清单:这套设计的可迁移要点
- 单一事实源:规范状态只存在于只追加日志;派生状态随时重建(DEVELOPMENT_GUIDE.md);
- 原子性靠"回滚"而非"锁":固定偏移写 + fsync + 失败 truncate 回滚(jsonl-event-log.ts);
- 换行即提交:无换行结尾的尾部字节一律视为 torn tail 并持久截断(jsonl-event-log.ts);
- 确定性双保险:读路径 fuzz 固定点校验(event-reader-fuzz.ts)+ 整日志重放逐字节比对(replay.ts);
- 对账以日志为准:命令台账只负责"找回悬空操作",最终裁定权在会话日志(session-manager.ts);
- 写之前先脱敏:敏感值在落盘前被抹除,日志可安全用于重放与审计(jsonl-event-log.ts)。
📁 延伸阅读:相关源码位置
- 事件日志读写与恢复:packages/kernel/src/jsonl-event-log.ts
- 会话树与完整性校验:packages/kernel/src/session-tree.ts
- 确定性重放:packages/kernel/src/replay.ts
- 读路径 fuzz 入口:packages/kernel/src/event-reader-fuzz.ts
- daemon 启动与对账:packages/daemon/src/daemon.ts
- 命令日志:packages/daemon/src/command-journal.ts
- 会话对账实现:packages/daemon/src/session-manager.ts
- 项目原则与数据布局:docs/DEVELOPMENT_GUIDE.md