dsh-postgres-backends
PostgreSQL durable backend family for DeepSeek Harness. 两个后端：
session-persistence-postgres：第三方 SessionPersistence 提供者，契约同官方 JSONL/SQLite 后端（append-only、contiguous-seq、惰性物化、load 时补关中断轮），落在 PostgreSQL 行而非文件字节或 node:sqlite。storage-postgres：第三方 storage.backend KV 后端，契约同官方 storage-json/storage-sqlite，一个数据库承载所有路由过来的 storage 域单元（workspace 注册表、message_feedback、session_projcache 等），文档行式（key TEXT / value JSONB）。
独立第三方仓库，不改动 DeepSeek Harness 源码。通过 profile 的 cordis.patch.yml 把默认持久化/存储后端替换为 PostgreSQL。
特性
- 事件溯源不变：每个
SessionEvent 映射一行 events 表，data 存 JSONB；sessions 表存 out-of-log metadata
- 追加 = 事务：
BEGIN/COMMIT 包住整批，中批失败整体回滚；单条 multi-row INSERT 批量写入
- 惰性物化：首笔
append 才写 sessions 行（list 只报有行的会话）
- 崩溃恢复：
load 时合成关闭事件（TOOL_NOT_STARTED / TOOL_OUTCOME_UNKNOWN）
- NUL 安全：DSH scope key 的 U+0000 经双层转义进出 JSONB（见下文）
- 异步驱动：使用
pg 连接池，不阻塞事件循环（优于官方 SQLite 的同步 DatabaseSync）
- 跨机共享：连远程 PostgreSQL 即可多机共享同一会话库
storage-postgres（KV 域存储）
- 文档行式：每条 KV 记录一行
kv_<unit>_<table>（key TEXT 主键 / value JSONB），单元身份与全局分别存 kv_units / kv_unit_globals
- 与 session 表隔离：
kv_ 前缀 + 独立 kv_units 注册表，与 sessions/events/persistence_state（带 store_id 版本戳）互不干扰
- 版本戳：每个单元首次 open 时在
kv_units 盖版本号；版本不符抛 version-mismatch，防止 schema 漂移
- NUL 安全：KV value 同样走
escapeNulText/unescapeNulText 双层转义进出 JSONB
- 隔离迁移：Console 迁移用独立 backend 实例（自有连接池，不挂运行时 hub），绝不与运行中的
storage.backend 注册表竞争
安装
1. 将本包加入 web profile
dsh plugin --profile web add dsh-postgres-backends
# 本地开发：dsh plugin --profile web add /home/weisanju/gitrepos/dsh-postgres-backends
2. 在 profile 补丁中替换默认 JSONL / JSON 后端
编辑 ~/.dsh/profiles/web/cordis.patch.yml：
# 禁用默认 JSONL 会话后端
- id: session-persistence-jsonl
disabled: true
- insert:
- id: session-persistence-postgres
name: 'dsh-postgres-backends'
config:
connectionString: 'postgres://postgres:postgres@localhost:5432/postgres'
# KV 存储后端（同一 PG 实例，独立 kv_* 表族）
- id: storage-postgres
name: 'dsh-postgres-backends/storage'
config:
connectionString: 'postgres://postgres:postgres@localhost:5432/postgres'
# 把 storage-domain 的默认后端从 json 路由到 postgres
# （patch 替换整行 config；routes 留空 = 全部域走 postgres）
- id: storage-domain
config:
backend: postgres
routes: {}
storage-domain 的 Config { backend, routes? }：backend 是默认路由，routes 按域覆盖。上面把默认改为 postgres、routes: {} 表示所有域都路由到 postgres。如需个别域保留 JSON，在 routes 里指明，如 routes: { session_projcache: json }。
3. 重启
cd <deepseek-harness-checkout> && dsh web --patch local-overlay.yml
PG Console（设置页 UI）
包内附带一个可选的 Settings 控制台（默认不启用），在设置页提供：
- 连接配置：host / port / user / password / database / poolMax 表单 + 测试连接 + 保存（存入
settings.yaml 的 pg-backends 命名空间，密码不回传浏览器）
- 会话迁移：JSONL ⇄ PostgreSQL 双向迁移，支持预览（dry-run）与真实迁移；源只读、目标增量写、幂等可重跑
启用方式：在 profile 补丁的 insert 里加一行：
- insert:
- id: pg-console
name: 'dsh-postgres-backends/console'
client 界面通过包的 dsh.client 声明自动挂载（设置页出现 "PostgreSQL Backends" section），API 走 /pg-console/api/*（受信 loopback 校验）。
配置存储：连接配置存放在独立的 ~/.dsh/pg-console.json（0600 权限），不写入 settings.yaml。原因：settings.yaml 顶层会被合并进每个 cordis 插件的 config，一个 pg-backends namespace 块会污染同名插件（哪怕只有部分字段、缺 password）导致主 PG 后端 client password must be a string 崩溃。独立文件彻底规避。
HTTP API（与 UI 等价，可脚本化）：
# 测试连接
curl -X POST http://127.0.0.1:3081/pg-console/api/connection.test \
-H 'content-type: application/json' \
-d '{"config":{"host":"localhost","port":5432,"user":"postgres","password":"postgres","database":"postgres"}}'
# → {"ok":true,"value":{"ok":true,"latencyMs":6}}
# JSONL → PG 真实迁移（dryRun:true 仅预览）
curl -X POST http://127.0.0.1:3081/pg-console/api/migrate.start \
-H 'content-type: application/json' \
-d '{"direction":"jsonl-to-pg","config":{"host":"localhost","port":5432,"user":"postgres","password":"postgres","database":"postgres"},"dryRun":false}'
迁移只复制不删除：源保持原样。迁移是事件级增量的——每次运行读取目标已提交的 seq 长度，只追加源中多出来的后缀（依赖 append 的 contiguity 校验保证 seq 连续无空洞），所以：
- 已完全同步的会话标记 target is up to date（零写入）
- 源在迁移过程中继续增长（如生产实例仍在写 JSONL）时，本次缺的尾部由下一次运行补上（标记 source changed mid-run）
- 迁移期间 PG 后端会分块插入（单事务内 4000 事件/批，规避 PostgreSQL 单条 INSERT 的 65535 绑定参数上限）
冲突处理策略（UI 下拉或 API onConflict 字段，默认 skip）：
skip（默认）：目标已有 → 不写；目标比源多 → 报告 target is ahead by N events（方向感知差异提示），绝不删除目标；目标比源少 → 增量续传overwrite：目标已有且与源不齐 → 整会话重建（先删目标行再用源全量重建，目标变成源的精确副本）。仅 PG 为目标时支持；反向（pg→jsonl）会拒绝，保护生产 JSONL 侧不被删除clone：目标 id 已存在 → 以 原id-clone 的新身份完整导入（seq 0..N 连续），目标原有副本保持不动
同步方向补课：迁移是单向复制，不是双向合并。JSONL 与 PG 是同一会话的两个事实源候选，但 DSH 的 append-only + 全局唯一 seq 模型不允许两侧同时各写各的（seq 冲突）。同一时刻只有一个后端在写：以 PG 为主后，PG 是权威、JSONL 只是历史（或手动 pg→jsonl 做备份/回滚）；反过来当 JSONL 是权威时，手动跑 jsonl→pg 增量同步副本。迁移总是手动触发——这是有意为之：自动周期同步会掩盖"何时切换"这个决定。
Storage 域迁移（JSON ⇄ PostgreSQL）
Console 设置页还提供 storage 域的双向迁移（~/.dsh/storages/*.json ⇄ kv_* 表），用于把默认 storage-json 的数据迁到 storage-postgres（或反向回滚/备份）。同样支持 dry-run 预览与 skip/overwrite 冲突策略。源只读、不删。
HTTP API：
# 列出两侧单元清单（json 侧 ↔ pg 侧：版本/记录数/是否有 global）
curl -X POST http://127.0.0.1:3081/pg-console/api/storage.list \
-H 'content-type: application/json' \
-d '{"config":{"host":"localhost","port":5432,"user":"postgres","password":"postgres","database":"postgres"}}'
# JSON → PG 真实迁移（dryRun:true 仅预览；onConflict: skip|overwrite）
curl -X POST http://127.0.0.1:3081/pg-console/api/storage.migrate \
-H 'content-type: application/json' \
-d '{"direction":"json-to-pg","config":{"host":"localhost","port":5432,"user":"postgres","password":"postgres","database":"postgres"},"dryRun":false,"onConflict":"skip","rebootstrap":true}'
rebootstrap（仅 json→pg、仅 workspace 单元）：把 PG 侧 workspace 单元的 global 改写为 initialized: false + 清空 workspaceIds。下次启动 WorkspaceRegistry.bootstrap() 会用当前 sessionPersistence.list()（现在已是 PG 会话）重建每个 workspace 的 sessionIds——这正是修复 Web UI 侧边栏 "Ungrouped sessions" 的机制：旧 workspace.json 里陈旧的 sessionIds 数组被清掉，按 cwd 重新分组归位。
迁移后需重启 dsh：storage-domain 路由到 postgres 是启动期读 config 决定的，运行中不切换；重启后才走 PG 读新数据。JSON 源文件不删（与 session 迁移同政策，留作回滚备份）。
迁移用隔离 backend 实例（自有连接池，不注册到运行时 hub），不会与运行中正开着的 workspace 域竞争。
配置项
| 键 | 必填 | 默认 | 说明 |
|---|
connectionString | 否 | — | PG 连接串（postgres://user:pass@host:port/db）；不填则用下方 host/port/user/password/database |
host / port / user / password / database | 否 | localhost / 5432 / postgres / postgres / postgres | 独立连接参数（未提供 connectionString 时使用） |
poolMax | 否 | 10 | 连接池最大客户端数 |
connectionTimeoutMillis | 否 | 0 | 取连接超时（毫秒）；0 = 无限等待（pg 默认）。建议设有限值，避免 PG 挂起时 connect() 无限阻塞 |
preparedSessionCacheSize | 否 | 5 | 保留的冷会话准备数 |
writeBatchMaxDelayMs | 否 | 200 | 批量写入合并窗口 |
schema | 否 | 当前用户 | 表所在 schema |
表结构（自动创建）
CREATE TABLE IF NOT EXISTS persistence_state (
singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
store_id TEXT NOT NULL
);
CREATE TABLE IF NOT EXISTS sessions (
id TEXT PRIMARY KEY,
version INTEGER NOT NULL,
created_at BIGINT NOT NULL,
cwd TEXT,
parent_session TEXT,
seed_length INTEGER,
origin TEXT,
delegation_depth INTEGER,
agent_preset TEXT,
incarnation TEXT NOT NULL,
revision BIGINT NOT NULL
);
CREATE TABLE IF NOT EXISTS events (
session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
seq INTEGER NOT NULL,
type TEXT NOT NULL,
time BIGINT NOT NULL,
data JSONB NOT NULL,
source_event_seqs JSONB,
surface_op JSONB,
ignorable INTEGER,
PRIMARY KEY (session_id, seq)
);
storage-postgres 表族（自动创建）
CREATE TABLE IF NOT EXISTS kv_units (
name TEXT PRIMARY KEY,
version INTEGER NOT NULL
);
CREATE TABLE IF NOT EXISTS kv_unit_globals (
unit TEXT PRIMARY KEY REFERENCES kv_units(name),
value JSONB NOT NULL
);
-- 每个单元的每张表:
CREATE TABLE IF NOT EXISTS kv_<unit>_<table> (
key TEXT PRIMARY KEY,
value JSONB NOT NULL
);
单元/表名经 UNIT_NAME_RE = /^[a-z][a-z0-9_]*$/ 校验后才进标识符（防注入）；记录 key 是参数化绑定，任意字符串。kv_units 的版本行在 open 时用 advisory-lock 事务 insert-or-check，并发进程不会竞争。
NUL 转义（为什么有这个设计）
DSH 的 agent-instructions 事件数据里，source.changes[].scope 用 真实 NUL（U+0000） 拼接
"目录 + 文件名"作为对账 key（如 ".\u0000AGENTS.md"，NUL 是 POSIX 文件名唯一保证不出现的字符）。
JSONL 文件后端能原样存储；但 PostgreSQL 的 text/JSONB 不允许 NUL，直接写入会报
SQLSTATE 22P05、"\u0000 cannot be converted to text"，症状表现为每轮对话
"本轮运行失败：unsupported Unicode escape sequence"。
因此本插件在 JSONB 边界做双层转义（不影响 DSH 本体）：
- 写入：真实 NUL → 6 字符字面量
\u0000；原文字面量 \u0000 → 7 字符 \\u0000
（防止解码时把用户原本的 \u0000 文本误还原成 NUL）；对象键同样转义
- 读出：
rowToEvent 里反向还原（\\u0000 → 原样，\u0000 → 真实 NUL）
实现见 src/schema.ts 的 escapeNulText / unescapeNulText，测试见
tests/pg.spec.ts 的 "round-trips NUL bytes" 用例。
已知边界
events_session_id_fkey（外键违规）：events.session_id → sessions(id) ON DELETE CASCADE。
正常写入顺序安全（appendBatch 在同一事务先物化 sessions 行再插 events）。若
sessions 行被外部删除（手动 DELETE/TRUNCATE），CASCADE 会连带清空该会话的
events，此时appendBatch 报 23503 foreign_key_violation 上抛（不静默自愈——自愈
补行会留下 seq 空洞，导致下次 load 报 corrupt）。处理：清库时连 events 一起清，
并重启实例让协调器重新从库 adopt。- 连接中断：空闲连接被 PG 断开（重启/网络分区）时 pooled client 报错，进程不会崩溃
（
pool.on('error') 只记日志），下一个 acquire 自动新建连接自愈。
开发
pnpm install
pnpm test # 需要本地 PostgreSQL
pnpm typecheck
测试套件使用独立的 dsh_test 数据库，绝不连接生产库。具体：
- 默认目标：
postgres://postgres:postgres@localhost:5432/dsh_test，首次运行时由 tests/helpers/db.ts 连到维护库 postgres 自动 CREATE DATABASE。
- 覆盖：设
DSH_PG_TEST_CONN=postgres://... 指向自定义测试库。
- 各 spec 的
beforeEach 会 DROP TABLE ... CASCADE 自己负责的表（session 表或 kv_* 表），所以测试间互不干扰；fileParallelism: false 保证串行。
⚠️ 不要把测试指向生产数据库。历史版本曾硬编码 5432/postgres，跑测试会 DROP 掉生产会话表，触发 events_session_id_fkey 外键错误。现版本已隔离修复。
许可
MIT
