62 lines
6.9 KiB
Markdown
62 lines
6.9 KiB
Markdown
# @deepseek-ai/dsh-session-persistence-sqlite
|
||
|
||
[English](README.md) | 中文
|
||
|
||
SQLite 持久会话持久化后端：第二个 `SessionPersistence` 实现（见[会话持久化](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)），用于验证抽象 seam 和共享 `runPersistenceContract` 套件真正与后端无关。它满足与 `dsh-session-persistence-jsonl` 相同的契约（仅追加、连续 seq、延迟实体化、在 load 时关闭中断轮次），但用 `node:sqlite` 行而非文件字节表达。
|
||
|
||
`locate(meta)` 返回 `undefined`：所有会话共享一个数据库，因此不存在真实的独立每会话 transcript 路径。
|
||
|
||
> **TODO：** 该后端直接调用 `node:sqlite`。如果采用 Cordis 数据库服务（`cordis/db` / `@cordisjs` SQL driver 插件），应改为通过该服务路由，而不在此保持原始 `DatabaseSync`；契约接口（`SessionPersistence`）不会变，只更换存储 driver。
|
||
|
||
## 存储模型
|
||
|
||
每个 `SessionEvent` 1:1 映射到 `events` 表中的一行 `(session_id, seq, type, time, data, source_event_seqs, surface_op)`；`data` 是作为 JSON 文本的事件 payload，因此行形态就是原样事件（包括 `assistant/chunk`，保持 `seq` 连续）。两个 `TEXT` 列 `source_event_seqs` 和 `surface_op` 可为空，存储事件可选接口元数据字段（见[会话接口](../../../.agents/notes/implemented/architecture/2026-06-18-session-surface.md)）。日志外元数据（`SessionHeader`）、每实体化 incarnation id 和每日志单调修订位于 `sessions` 行；`createdAt` 是存储在 strict `INTEGER` 列中的非负安全整数。单例状态行携带不可变存储 id。`sessions` 行只由第一次 `append` 写入，其存在性是延迟实体化信号（`list` 精确报告有行的会话）。
|
||
|
||
仓库支持的 Node 范围可不加 flag 使用 `node:sqlite`。数据库启用外键，并使用已配置 journal mode（默认 `wal`；WAL 共享内存文件不适用时使用 rollback mode）。`PRAGMA application_id` 标识规范持久化数据库，`PRAGMA user_version` 存储布局版本。新数据库必须没有 application identity 或用户定义 schema 对象；初始化在一个事务中创建全部表并盖上两个 pragma。非 pristine 无版本数据库、外部 application identity 和所有非当前版本在 journal-mode 变更前拒绝，因为该未发布格式无迁移。
|
||
|
||
在具有 POSIX mode 的文件系统上，后端为缺失目录请求 mode `0700`，并在 SQLite 打开前以 mode `0600` 排他创建缺失数据库；进程 umask 可进一步限制两者。新 WAL、共享内存和持久 rollback-journal sidecar 获得数据库最终的仅所有者 mode。现有目录、数据库文件和 sidecar 保留原 mode；除已存在数据库外的文件系统设置错误会使初始化失败。这些默认值防止宽松进程 umask 造成的意外暴露，但当其他 principal 能替换父目录中的数据库条目时，不保护数据库机密性或完整性。
|
||
|
||
## 行上的契约语义
|
||
|
||
- **Append = 事务。**`append` 围绕批次运行 `BEGIN`/`COMMIT`：它实体化 `sessions` 行（如果仍延迟），并 INSERT 每个事件，首先断言连续 seq 契约（第一个事件 `seq` 必须等于已存储 next-seq）。批次中失败（重复 seq 上的 UNIQUE 违规）会完全回滚，使已存储日志和内存游标保持一致。（`load()` 已平衡已存储日志，因此 `append` 不必修复崩溃尾部。）
|
||
- **延迟实体化。**`create()` 只在内存记录意图，第一次 `append` 前不写行。从未 append 的会话没有 `sessions` 行，因此不在 `list()` 中（它精确报告有行的会话）。
|
||
- **在 load 时关闭中断轮次。**`load()` 实现共享[崩溃恢复契约](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)：保留有效中断轮次，在一个事务中追加合成关闭事件，并只移除撕裂尾部行。已提交解析错误或序列缺口使会话无法加载。恢复会变更已存储行，因此下一次 append 从平衡日志和准确游标开始。
|
||
- **非变更检查。**`inspect()` 返回脱离的有效行前缀，不删除撕裂尾部行或追加恢复 closer，并保持轻量修订不变。
|
||
- **轻量修订。**`listSnapshots(signal?)` 组合不可变存储与数据库文件身份、每实体化 incarnation id，以及在每个变更事务中递增的每会话计数器。它在不解析事件行的情况下保持未变观察稳定，并区分独立存储和重建的同 id 日志。它在共享就绪和同步元数据查询前后检查取消；查询本身不可抢占。
|
||
|
||
## 配置（schemastery）
|
||
|
||
```ts
|
||
interface Config {
|
||
path: string // SQLite database file path, or ':memory:' for an in-process DB
|
||
journalMode?: 'wal' | 'delete' | 'truncate' | 'persist' // journal_mode pragma; default 'wal'
|
||
}
|
||
```
|
||
|
||
## 写入路径
|
||
|
||
与 JSONL 后端一样，插件将每个冻结 `session/event` 复制到每个实时会话的一个 controller，并启动急切 drain。并发事件共享当前事务；期间接纳的事件形成后续批次，`session/flush` 则等待当前和 pending 批次持久。Controller 对 fork 种子持久一次，保留写入游标，使 resume 绝不重新 append 已存储事件，并在 apply 时为实时会话播种，因为 HMR 不回放 `session/created`。Dispose 在关闭数据库前 drain 每个保留 controller。
|
||
|
||
## 模型体验
|
||
|
||
### 恢复的对话历史
|
||
|
||
#### 模型所见
|
||
|
||
SQLite 存储不贡献实时提示词或 schema。加载恢复与 JSONL 相同的接口历史，并保留之前的 header 用于重建；新 loop 组合当前 envelope。恢复将无持久调用的 assistant 请求平衡为 `TOOL_NOT_STARTED`；有持久调用但无结果时变为 `TOOL_OUTCOME_UNKNOWN`，它要求模型只重试只读或幂等工作，并验证可能副作用或请求用户。行元数据和原始分片不是消息。
|
||
|
||
#### Token 影响
|
||
|
||
实时请求为零 token。Resume 恢复已保留历史并支付当前 envelope，以及每个中断调用的引用修复结果。
|
||
|
||
#### KV 缓存影响
|
||
|
||
SQLite 存储不修改实时请求前缀。只有重建历史、当前 envelope 和模型路由匹配时，恢复 loop 才能重用提供方缓存；崩溃修复结果仅追加。
|
||
|
||
## 已知限制与待完成工作
|
||
|
||
- **`DatabaseSync` 是同步的**：每个 append 事务在整个期间阻塞事件 loop；对本地存储可接受，对繁忙多会话服务器是吞吐上限。
|
||
- **写入争用无等待或重试策略**：后端不设置 busy timeout，也不重试 locked-database 错误，因此其他连接持有写事务时操作立即拒绝。
|
||
- **只打开 pristine 新数据库或当前自有 `SCHEMA_VERSION`**：无版本 schema 对象、外部 application identity 和所有其他 schema 版本被拒绝，而不是迁移（未发布软件，无持久用户数据需要保留）。
|
||
- **不删除已存储会话**：行会累积，直到外部移除（seam 无删除接口；`ON DELETE CASCADE` 已为这种带外清理接线）。
|