第 13 章：持久化、回放与可观测性

本章解决的问题

AI 产品不只是“聊天”。会话保存、恢复、回放、审计和监控都需要明确设计。这一章讲这些能力如何落在 Agent 平台里。

交互图解：Session Log、Surface 与多种投影 · 查看图解导读

大白话理解

一个可靠的 Agent 产品需要回答：

• 上次聊到哪了？
• 用户点击重试时，系统当时看到什么？
• 工具为什么执行失败？
• 哪些行为需要审计？
• 系统变慢时瓶颈在哪？

这些问题的答案通常都来自会话事件日志。

必须掌握的概念

1. Persistence

持久化把会话事件保存到磁盘。

常见后端：

• JSONL
• SQLite

2. Replay

回放按事件顺序重建会话。模型请求是否可重建，取决于是否所有模型可见内容都已记录。

3. Projection

Projection 从事件流计算当前视图。例如：

• 消息数量
• 当前 todo
• token 使用
• 工具调用树

4. Observability

可观测性包括：

• 日志
• 遥测
• 指标
• 追踪

5. Checkpoint

Checkpoint 在关键边界强制 flush，降低崩溃丢失。

DeepSeek Harness 对应实现

DeepSeek Harness 将持久化设计为插件：

• 监听 session/event。
• 响应 session/flush。
• 使用 JSONL 或 SQLite backend。

session-checkpoint-policy 在模型请求和工具执行前做 flush。

session-projection 从事件流驱动纯投影。

session-telemetry-otel 可以把记录交给 OpenTelemetry。

进一步阅读：

• packages/session/session-persistence/README.md
• packages/session/session-projection/README.md
• docs/testing.md

代码示例

简化事件持久化

interface StoredEvent {
  seq: number
  type: string
  data: unknown
}

class JsonlSessionStore {
  constructor(private path: string) {}

  async append(event: StoredEvent): Promise<void> {
    const line = JSON.stringify(event) + '\n'
    await appendFile(this.path, line, 'utf8')
  }

  async readAll(): Promise<StoredEvent[]> {
    const text = await readFile(this.path, 'utf8')
    return text
      .split('\n')
      .filter(Boolean)
      .map(line => JSON.parse(line) as StoredEvent)
  }
}

真实实现还要处理 flush、写批处理、损坏恢复和原子性。

简化 Projection

function countMessages(events: StoredEvent[]): number {
  return events.filter(event =>
    event.type === 'user/message' || event.type === 'assistant/message',
  ).length
}

面试怎么问

问：会话恢复要保存什么？

回答要点：

• 原始事件日志。
• 会话元数据。
• 请求头或模型路由信息。
• 不能只保存 UI 文本。

问：如何保证模型请求可回放？

回答要点：

• 模型可见内容必须可重建。
• 请求配置和工具结果要记录。
• 原始流可保留用于展示。
• 派生历史和原始日志要能对应。

问：前端如何做调试和监控？

回答要点：

• 展示事件时间线。
• 显示请求、工具调用和错误。
• 保留 session id 和 message id。
• 用结构化日志方便搜索。

自测题

1. JSONL 和 SQLite 各有什么特点？
2. 为什么不能只用 UI 文本保存会话？
3. Projection 和持久化的区别是什么？
4. 可观测性对 Agent 产品为什么重要？

本章小结

持久化、回放和可观测性是 Agent 产品可靠性的基础。它们共同依赖一个原则：先有完整事件日志，再有各种投影和监控。

进一步阅读：

• packages/session/session-persistence/README.md
• packages/session/session-projection/README.md