7.0 KiB
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）；已有数据库保持其既有模式。已存格式版本与描述符不同的单元拒绝 version-mismatch，盖有非当前物理布局版本的数据库会直接拒绝——不做迁移，预发布立场。失败携带稳定的 StorageError 代码，写入 resolve 后即已持久。
理解实现
实现细节——点击展开
本后端是在单个 node:sqlite 连接之上的文档按行布局，设计目标是让每次按键更新都是一条预处理语句。
设计理念
- 每行一份文档。 每个单元表都变成一张物理 STRICT 表
u_<unit>_<table> (key TEXT PRIMARY KEY, value TEXT)，其value列保存记录的 JSON 文本；全局单例存放在共享的unit_globals表中。一个键的更新恰好触碰一行——这就是把高频变更领域路由到这里的原因。 - 单语句原子性。 每个写入原语都是一条预处理语句，因此 SQLite 的逐语句原子性无需显式事务即可满足 KV 约定；写入顺序仍由调用方负责（领域层的写入链）。
- 名称在 DDL 之前校验。 单元名与表名在进入 DDL 之前必须匹配
UNIT_NAME_RE，因此任何外部输入都不会被插值进 SQL 标识符。 - 版本明确报错。 物理布局版本存放在
PRAGMA user_version（全新数据库最后盖戳）；单元格式版本存放在units表中。任何其他已标记值都会被拒绝——不做迁移。
打开顺序
打开数据库与会话持久化 SQLite 后端一致：mkdir 父目录 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 值解析、关闭 |
src/invariant.ts |
不变式伴生插件（无运行时不变式：版本是打开时检查） |
进一步探索
当本后端视角不够用时阅读以下页面：子系统参考是权威约定，兄弟后端展示了另一种介质。
- 存储子系统——后端约定、领域语义与生成的 API。
- 存储包映射——家族的各包及其在仓库中的位置。
- JSON 存储后端——面向小而可检查数据的人类可读介质。
- 领域 KV 存储 Agent Note——后端家族背后的设计与被推迟的会话后端迁移。
模型体验
已存领域记录
模型看到什么
无。本后端不贡献提示词、工具或 schema；它在 ctx.storage 后面持久化非会话领域数据，只供宿主侧消费方使用。
Token 影响
实时请求 token 为零。
KV Cache 影响
无：本后端从不触碰实时请求前缀。
已知限制与延期工作
这些限制说明本后端何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是任务积压。
- 同步驱动阻塞事件循环——每次写入都是一次同步
DatabaseSync调用；阻塞只持续一条语句，在领域数据规模下可以接受。 - 没有忙等待或重试策略——持有写锁的竞争连接会立即拒绝操作，而不是等待；领域层的写入链在单进程内串行化写入，跨进程协调属于范围外。
- 只打开当前的物理布局版本——任何其他已标记的
user_version都会被拒绝而不是迁移（预发布立场）。 - 打开顺序与会话包重复——
openDatabase与会话持久化 SQLite 的打开顺序一致；提取到共享介质层的工作被推迟到计划的会话后端迁移。
开发备注
维护者的工作上下文——点击展开
无。