PostgreSQL 会话存储 velobase/dsh-postgres

dsh-postgres

English · 架构 · 部署

面向 DeepSeek Harness 的社区 PostgreSQL 会话持久化插件。
实现原生 SessionPersistence / SessionHandle，支持 namespace 隔离，允许多个 DSH 根上下文共享一个连接池。

当前为 0.1 alpha，尚未发布到 npm。 类型检查和构建不代表数据库正确性已经得到验证。
尚未完成 PostgreSQL 集成、故障恢复及完整 DSH 宿主流程的运行验证。

存储边界

保存完整的原生会话头、追加式事件、分支继承关系和继承事件数量，涵盖消息与工具调用结果。
沿用 DSH 的界面、Agent 循环和会话语义。

| 数据或职责 | 归属 |
| 会话头、原生事件 | 本插件 / PostgreSQL |
| 用户认证、namespace 选择、权限 | 宿主应用 |
| 工作区、投影缓存、设置 | 既有 DSH 存储服务 |
| 图片、音频、附件原文件 | 附件插件 / 对象存储 |
| 账号、扣费、凭据 | 宿主已有服务 |
| 正在运行的模型请求、进程状态 | 运行时 |

版本与安装

初版针对 Node.js 22.18+、Cordis ~4.0.5、DSH 会话与持久化包 0.2.1-rc.3。PostgreSQL 部署目标为 16+，数据库运行验证尚未完成。
DSH 预发布 API 必须匹配，不能用 npm 的 latest 标签推断接口新旧。
不实现旧 PersistenceCoordinator 接口，也不自动迁移历史会话格式。

git clone https://github.com/velobase/dsh-postgres.git
cd dsh-postgres
npm ci
npm run typecheck
npm run build
npm pack

把生成的 velobase-dsh-postgres-0.1.0-alpha.1.tgz 安装到宿主的包环境。
通过环境或密钥管理系统提供 DSH_PG_URL，然后执行一次显式数据库迁移：

node dist/migrate.js

默认 schema 是 dsh_postgres，可用 DSH_PG_SCHEMA 覆盖。
迁移使用事务与部署锁，可重复执行；运行时仅校验 schema 版本，不自动执行 DDL。

单用户宿主

宿主需要已经提供 ctx.sessions。在其装配中替换已有的会话持久化 provider，不要为同一服务同时挂载两个 provider。

import PgSessionPersistence from '@velobase/dsh-postgres'

ctx.plugin(PgSessionPersistence, {
connectionString: process.env.DSH_PG_URL!,
namespace: 'personal',
})

这是原生 Cordis 服务插件。桌面、CLI、Web 的具体 bundle/profile 装配由宿主负责，本仓库不修改任何宿主产品。

多用户共享服务

import { PostgresDatabase, createPostgresSessionPlugin } from '@velobase/dsh-postgres'

// 每个应用进程创建一次，数据库已提前迁移。
const database = new PostgresDatabase({
connection: { connectionString: process.env.DSH_PG_URL },
})
await database.ready()
const SessionPlugin = createPostgresSessionPlugin(database)

// 已认证账号的 DSH 根上下文：
accountContext.plugin(SessionPlugin, { namespace: account:${authenticatedAccount.id} })

// 整个应用退出：先释放账号上下文，再关闭共享数据库资源。
await database.close()

namespace 从服务端认证身份确定，固定在一个服务实例上。所有查询、主键和写租约都带 namespace；不能直接信任浏览器传来的租户参数。这是应用层查询隔离，不是 PostgreSQL RLS。

不需要每用户一个数据库、schema、连接池或服务器。每个共享数据库对象只有一个续租循环，空闲写句柄不占用已借出的 SQL 连接。也可以传入宿主已有的 pg.Pool，其关闭责任仍属于宿主。

持久化与故障语义

- create 立即持久化会话头；空会话重启后仍存在。
- append 在事务内校验序号并写入整批事件，启用 synchronous_commit=on。
最终持久性仍受 PostgreSQL/WAL 配置影响。
- flush 排空原生事件缓冲并检查写入所有权。
- 读取走主库的同一个 MVCC 快照。
- 写入在同一事务内检查 namespace、持有者令牌与租约有效期。
- 默认租约 60 秒，每三分之一个周期续租。进程崩溃后，其他进程等待租约过期才能接管。
这是故障检测参数，不限制模型运行时间；过期句柄不会自行恢复写权限。
- 写入结果不确定时停止该句柄，重新打开后检查已提交前缀，避免盲目重放。
- 事件以 JSON 文本保存，完整保留转义的 NUL 与孤立 UTF-16 代理项，不为适配 JSONB 删字符。

当前限制

目前没有自动化运行测试套件，尚未完成数据库集成验证。首版不包含 HTTP API、UI、RLS、账号系统、旧日志导入、工作区/KV、搜索、凭据、附件或 spill 存储。
仅迁移会话并不代表整个 DSH 已经不依赖磁盘。

原生 list() 返回该 namespace 的全部会话，不擅自截断；公开 HTTP API 应由宿主分页。
完整日志读取会验证全部事件，大历史性能尚未测量。
会话持久化可以支持重启后重新打开历史，不能自动恢复执行中的模型或工具请求，数据库写租约也不能阻止外部工具副作用。

开源与贡献

MIT 许可证。参考 DeepSeek Harness 与 agentserver 的公开实现，保留原始版权与来源，详见 NOTICE。本项目属于独立社区项目。

请按独立逻辑拆分 commit，并参考 CONTRIBUTING.md、 SECURITY.md 和 CODE_OF_CONDUCT.md。
DSH 间接依赖的 Zod 安全更新已在本仓库开发依赖中覆盖；该覆盖不会自动传递给宿主，宿主处理方式见部署文档。