第5章 会话与事件溯源：SessionLog 的秘密

为什么说"事件日志就是真相之源"——取消、回放、压缩都建立在它之上

5.1 本章导读

上一章里 ReactLoopAgent 反复调用 session.append(...)——TurnStart、StepStart、UserMessage、AssistantChunk、ToolCall、TurnEnd……本章揭开这个 session 的真面目：它不是简单的"聊天记录"，而是一个事件溯源（Event Sourcing）系统。理解了它，你就理解了本项目为什么能做到取消不丢数据、历史完整回放、上下文自动压缩。

5.2 什么是事件溯源

传统系统存"当前状态"，事件溯源存"发生的所有事"。类比银行账户：

对 Agent 会话来说，"流水"就是会话事件日志（Session Event Log）：用户说了什么、模型回了什么、调用了哪个工具、工具返回了什么、什么时候取消的——全部按顺序追加，只增不改。

5.3 SessionLog：内存追加式 WAL

SessionLog（📦 domain/session/event/model/entity/SessionLog.java）本质是一个内存中的追加式写前日志（WAL）。Agent 运行过程中产生的一切事件都先追加到这里，再由 ISessionEventStore 端口异步落库（MySQL 的 harness_session_event_log 表）。

事件类型是 sealed 接口 SessionEvent，分四大类：

每个事件有全局递增的 seq（序号），这是回放和投影的顺序依据。

5.4 SurfaceProjector：从事件到界面

事件日志是"原始流水"，但 UI 要的是"当前应该显示什么"。中间的翻译层是 SurfaceProjector（表面投影器）：

核心代码极简，却撑起整个 UI 渲染：

// SurfaceProjector.project()（简化）
for (SessionEvent event : events) {
    SurfaceIntent intent = intentOf(event);
    if (intent.surfaceOp() instanceof SurfaceOp.Append) {
        nodes.add(new SurfaceNode(event.seq(), event));
    } else if (intent.surfaceOp() instanceof SurfaceOp.Replace r) {
        // 按 r.targetSeq() 找到旧节点替换
    }
}

为什么需要 Replace？典型场景：AssistantChunk 流式追加时，UI 应该更新同一个气泡而不是每来一个 chunk 就加一个气泡。chunk 事件投影为 Replace（替换上一个未完成的气泡），完整 AssistantMessage 到来时再 Replace 成终态——界面上看到的就是"文字逐字浮现"的效果。

5.5 BasicCompactionEngine：上下文压缩

会话长了，把所有事件塞进 LLM 上下文会爆 token。本项目的压缩策略在 BasicCompactionEngine（📦 domain/agent/compaction/）：

5.6 事件溯源带来的三个超能力

回到本章开头的问题——为什么说事件日志是真相之源？因为它同时支撑了三件看似无关的事：

5.7 课程补充：SurfaceOp.Replace 的两个场景与两条派生路径的口径差异

本章第 5.4 节讲了 SurfaceOp 的 Append/Replace 两种操作，但只展开了一个场景（流式气泡的逐字浮现）。实际上 Replace 还有另一个关键用途，且系统里有两条独立的派生路径在不同的层用不同语义读事件日志——这一节补全这两个细节。

5.8.1 Replace 的第二个关键场景：压缩摘要遮蔽历史

第 5.5 节说过压缩引擎的策略是"保留最近 1/4 原文、其余 LLM 总结"。那这条总结怎么进事件流？它不追加在末尾——那样会和原文共存，模型会看到两份。正确做法是用 Replace 把前 3/4 的旧节点"遮蔽"掉：

// BasicCompactionEngine.compactNow()（简化）
// 找到待压缩区间的第一个和最后一个 surface seq
long startSeq = -1, endSeq = -1;
int msgIdx = 0;
for (SessionEvent event : events) {
    if (!event.isSurfaceEvent()) continue;
    if (msgIdx >= compactEnd) break;  // 越过保留区就停
    if (event.surfaceIntent().surfaceOp() instanceof SurfaceOp.Append) {
        if (startSeq < 0) startSeq = event.seq();
        endSeq = event.seq();
        msgIdx++;
    }
}
// 追加摘要消息，意图是 Replace [startSeq, endSeq]
session.append(SessionEventFactory.userMessage(
    0, 0, summaryMsg,
    new SurfaceIntent(new SurfaceOp.Replace(startSeq, endSeq), null)
));

日志里原始事件全在（不可篡改是事件溯源纪律），但任何下游投影这批事件时，startSeq..endSeq 区间内的节点都会被这条新摘要替换掉。这就是为什么叫"遮蔽"而不是"删除"——历史保留、可审计，但当前视图变化。

5.8.2 两条派生路径：deriveMessages vs extractChatMessages

同一个 SessionLog 至少有两个消费者去"看"事件：

这里有一个真实隐患（已记在 MEMORY.md）：前两条路径的口径不一致——LLM 看到的消息历史包含 ToolResult（工具结果是模型推理的依据），UI 聊天面板却不显示它们。带来的副作用是：用户看历史时不能直观地"看到模型读了什么文件、跑过什么命令"，只能从 SSE done 事件的 messages 数组里翻 tool 消息。

代码层面的修复思路（目前未做）：要么让 SurfaceProjector.extractChatMessages 可参数化（includeTools=true/false），要么把 UI 的对话视图改成"以折叠卡片展示工具结果"。从设计上看，extractChatMessages 是为"对话"服务的（聊天场景不应被工具噪音淹没），deriveMessages 是为"模型"服务的（必须完整才能继续推理）——两者用途不同、口径不同是正确的，关键是要让调用方知道自己在调哪个。

5.8.3 deriveMessages 的简易投影：Java 版为什么是 O(n²)

TS 版用增量缓存（按 surface node 索引），每次只在尾部追加新事件时更新缓存。Java 版为了"实现简单"选择了全量重算：

// SessionLog.deriveMessages()（简化）
public synchronized List deriveMessages() {
    List messages = new ArrayList<>();
    Set shadowed = new HashSet<>();
    List surfaceSeqs = new ArrayList<>();

    for (SessionEvent event : events) {              // O(n) 遍历
        if (!event.isSurfaceEvent()) continue;
        SurfaceOp op = event.surfaceIntent()?.surfaceOp();
        if (op == null) continue;

        if (op instanceof SurfaceOp.Append) {
            messages.add(projectMessage(event));     // O(1)
        } else if (op instanceof SurfaceOp.Replace r) {
            // Replace 的代价：遍历 surfaceSeqs 找出 [r.start, r.end] 内的 seq
            Iterator it = surfaceSeqs.iterator();
            Iterator mit = messages.iterator();
            while (it.hasNext()) {                   // O(k)，k = 当前 surface 数
                long seq = it.next();
                if (seq >= r.start() && seq <= r.end()) {
                    it.remove(); mit.next(); mit.remove();
                } else if (seq > r.end()) break;
                else mit.next();
            }
            messages.add(projectMessage(event));
        }
    }
    return Collections.unmodifiableList(messages);
}

每个 Replace 都要 O(k) 扫一次当前 surface，Append 也要遍历事件日志判断自己是不是 surface 事件——单次 deriveMessages() 是 O(n) × O(k) ≈ O(n²)。短会话（几十条）毫无感觉；长会话（几百条 + 多次压缩）会成为热点。derivedCache 字段已经在类里声明了但未启用（Java 注释："The TS version incrementally caches by surface node, but the Java version favors simplicity until profiling shows a hot path"）——这是一个留作未来优化的空间。

5.8 小结与下一章预告