0 Fork 0

Files

T

Magolor 5e5b8bee6e fix(storage): unify versioned batch writes and deletion recovery

2026-10-26 13:04:41 +08:00

8.3 KiB

Raw Blame History

description, kind

description	kind
SQLite 存储后端：面向在单个数据库文件中选择、配置或排查按行存储文档的 KV 存储的宿主与维护者。	package-reference

@deepseek-ai/dsh-storage-sqlite

English | 中文

概述

dsh-storage-sqlite 是一个存储后端：把每个已路由单元托管在同一个 SQLite 数据库文件中，每条记录按行存储一份 JSON 文档，注册为后端 sqlite。单条记录更新替换一条数据行，这正是它适合高频定点写入的原因。当领域数据变动频繁、或部署偏好单一可查询数据库时选择它；当数据需要以纯文本文件形式可读时选择 JSON 后端。本后端只面向宿主侧：它不贡献提示词、工具或 schema，因此模型与 agent loop（智能体循环）永远不会看到它。

使用本包

当组合把频繁更新的领域数据保存在一个数据库中时使用本包：把相关领域路由到此后端，每个单元即作为表物化在配置的数据库文件中。

何时选择

当写入频繁且为定点更新时选择它——每个键映射到一条数据行，因此更新记录无需重写整个单元。对接受的旧单元首次修改时，还会在同一事务中更新其版本元数据。当人类需要以纯文本文件查看或编辑已存数据时选择 JSON。同步的 node:sqlite 驱动会在每次写入调用期间阻塞 JavaScript 线程，包括该首次事务；高写入率时须纳入考量。

配置

两个字段：数据库路径与 journal mode。:memory: 打开一个进程内数据库，其内容随进程消失。

- name: '@deepseek-ai/dsh-storage'
- name: '@deepseek-ai/dsh-storage-sqlite'
  config:
    path: /var/lib/dsh/data.db
- name: '@deepseek-ai/dsh-storage-domain'
  config:
    backend: sqlite

字段	默认值	含义
`path`	必填	SQLite 数据库文件路径，或 `:memory:`
`journalMode`	`wal`	Journal mode：`wal`、`delete`、`truncate` 或 `persist`

wal 适合本地磁盘；回滚日志模式（delete／truncate／persist）适合 WAL 共享内存文件不可用的文件系统，例如网络挂载。生成的配置目录是每个受支持字段及其 JSDoc 的穷尽式真源。

可观察行为

缺失的目录与数据库文件会以仅所有者可访问的权限创建（0o700／0o600）；已有数据库保持其既有模式。单元接受描述符的当前版本或 compatibleVersions，否则拒绝 version-mismatch。读取接受的旧单元时保留其版本戳；首次修改将数据与当前版本戳放在同一事务中提交。删除不存在的键或空批次时版本戳保持不变。未改动记录的值与其他单元保持不变；后端不转换应用值。盖有非当前物理布局版本的数据库会直接拒绝；领域兼容性不迁移数据库布局。Storage 检查使用 StorageError 代码；底层 SQLite 失败会向上传递，写入操作完成后即已持久化。

每个非空批量删除都使用一个事务，需要时在该事务内更新版本戳。事务失败时，只要 SQLite 成功回滚，数据与版本戳就保持原状，包括自动回滚的情况。BEGIN 失败会使整个批次保持未应用，允许在同一句柄上重试。如果回滚本身失败，后端会保留代码为 unknown-state 的 StorageError，其 cause 是包含两次失败的 AggregateError，并拒绝后续单元读写，以及正在等待或新发起的打开操作。此时事务结果未知。须关闭后端及其领域，再创建新后端检查已存状态，然后决定是否重试。混合记录与降级行为参阅领域版本。

理解实现

实现细节——点击展开

本后端是在单个 node:sqlite 连接之上的文档按行布局。按键写入复用预处理语句；版本升级会增加元数据更新与事务。

设计理念

每行一份文档。 每个单元表都变成一张物理 STRICT 表 u_<unit>_<table> (key TEXT PRIMARY KEY, value TEXT)，其 value 列保存记录的 JSON 文本；全局单例存放在共享的 unit_globals 表中。一个键的更新会替换一条数据行；推进单元版本戳时还会更新其元数据。
原子写入。 当前版本的单记录写入使用一条预处理语句。批量删除和对接受的旧单元首次修改共用一个事务助手；首次修改包含当前版本戳。成功回滚会保留数据与版本戳。写入顺序仍由调用方负责（领域层的写入链）。
名称在 DDL 之前校验。 单元名与表名在进入 DDL 之前必须匹配 UNIT_NAME_RE，因此任何外部输入都不会被插值进 SQL 标识符。
版本分别检查。 物理布局版本存放在 PRAGMA user_version（全新数据库最后盖戳），必须精确匹配。单元版本存放在 units 中，也接受拥有方声明的 compatibleVersions；记录转换由拥有方负责。

打开顺序

打开数据库时会以 0o700 创建父目录、以 0o600 独占创建缺失文件、应用 PRAGMA foreign_keys = ON 与 journal mode、检查 user_version、创建 units 与 unit_globals 元数据表，并在最后给全新数据库盖戳，让失败留下未盖戳的介质。

源码地图

文件	职责
`src/index.ts`	插件入口：后端注册、`path`／`journalMode` 配置、单元表
`src/schema.ts`	打开顺序、物理布局版本、元数据表、记录表命名
`src/unit.ts`	一个已打开单元：预处理语句、JSON 值解析、关闭

进一步探索

当本后端视角不够用时阅读以下页面：子系统参考是权威约定，兄弟后端展示了另一种介质。

存储子系统——后端约定、领域语义与生成的 API。
存储包映射——家族的各包及其在仓库中的位置。
JSON 存储后端——面向小而可检查数据的人类可读介质。
领域 KV 存储 Agent Note——后端家族背后的设计与被推迟的会话后端迁移。

模型体验

已存领域记录

模型看到什么

无。本后端不贡献提示词、工具或 schema；它在 ctx.storage 后面持久化非会话领域数据，只供宿主侧消费方使用。

Token 影响

实时请求 token 为零。

KV Cache 影响

无：本后端从不触碰实时请求前缀。

已知限制与延期工作

这些限制说明本后端何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是任务积压。

同步驱动阻塞事件循环——写入使用同步 DatabaseSync 调用；批量删除与对接受的旧单元首次修改会在 JavaScript 线程上持有事务。
没有忙等待或重试策略——持有写锁的竞争连接会立即拒绝操作，而不是等待；领域层的写入链在单进程内串行化写入，跨进程协调不在范围内。
只打开当前的物理布局版本——任何其他已标记的 user_version 都会被拒绝而不是迁移（预发布立场）。
版本检查保持单元级——per-record 布局请求不会让本后端增加逐记录版本戳或 JSON 的缺失文档恢复策略。
打开顺序与查询提供方重复——openDatabase 与 session-query-sqlite 都强制执行 SQLite 文件所有权约束，但两个包各自拥有不同的应用标识与 schema；没有共享介质辅助模块将二者耦合。

开发备注

维护者的工作上下文——点击展开

无。

8.3 KiB Raw Blame History Unescape Escape