Jotaro Space
DeepSeek Harness Session Data Plane：持久化、Projection、Title、Query
JotaroRD
  2026-08-14 01:08:00   2026-09-04 18:20:23  

模块定位

packages/session 是围绕 core/session 的 durable data plane。core/session 负责 live session log；packages/session 负责把 log 存下来、投影给 UI、生成标题、上报 telemetry。

相关目录：

  • packages/session/session-persistence
  • packages/session/session-persistence-jsonl
  • packages/session/session-persistence-sqlite
  • packages/session/session-projection
  • packages/session/session-projection-cache
  • packages/session/session-title
  • packages/session/session-telemetry
  • packages/session-query/*

Persistence Seam

持久化不是写在 Session 类里。Persistence backend 订阅 session/event，在 session/flush 做 durability checkpoint。

1
2
3
4
5
6
7
flowchart LR
  A["Session.append"] --> B["session/event"]
  B --> C["persistence service"]
  C --> D["JSONL backend"]
  C --> E["SQLite backend"]
  A --> F["session/flush"]
  F --> C

这种设计让 live session 不绑定具体存储。JSONL 和 SQLite backend 是可替换 provider。

Checkpoint Policy

session-checkpoint-policy 会在语义关键点应用 durability checkpoint，例如模型调用和工具执行边界。它 wrap ctx.llm 和 ctx.tools，不是改 Session 本身。

这有助于避免“模型已经看到了工具结果，但结果还没落盘”的不一致。

Projection

UI 不应该每次都扫完整 raw log 自己算状态。session-projection 定义 projection units，session-projection-cache 可以缓存投影 checkpoint，session-stats 提供统计投影。

Projection 的对象包括：

  • 会话摘要。
  • 消息/工具 UI 视图。
  • conversation counts。
  • wall time。
  • 其他 log-derived values。

Title

Session title 有一个 service，允许一个 provider 注册。没有模型 provider 时有 deterministic fallback。有模型 provider 时，可以从首个 eligible human message 或所有 eligible prompts 生成标题。

这看似小功能，但它体现了同一条原则：标题也是 log-derived state，而不是 UI 随便猜一个。

Telemetry

Session telemetry 会从 session activity 投影上报数据，并执行 redaction。OTel backend 支持不同模式：

  • FULL。
  • FEEDBACK_ONLY。
  • DISABLED。

反馈门控很重要：用户反馈可以决定哪些 session activity 可以上报。

Session Query

session-query/ 是 sibling group，不属于 persistence internals。它提供：

  • logical corpus。
  • bounded reads。
  • lineage。
  • event relationships。
  • semantic filtering。
  • SQLite full-text search。
  • model-facing query tools。

这说明“怎么存”和“怎么查”是两个能力面。

常见坑

第一，persistence backend 不应该直接改 live session 行为。它观察事件并响应 flush。

第二，projection cache 是派生物。事实源仍是 session log。

第三，只能注册一个 title provider。多个 provider 并存会让标题语义不确定。

第四，telemetry 不是 raw dump，要经过 projection 和 redaction。

继续读源码

  • packages/session/README.md
  • packages/session/session-persistence/README.md
  • packages/session/session-projection/README.md
  • packages/session-query/README.md
  • docs/subsystems/persistence.md