dsh-session-persistence-mysql：DSH 的 MySQL 持久化后端

前言¶

DeepSeek Harness (DSH) 的会话持久化通常使用 JSONL 等文件后端。当需要更高的数据可靠性、读写分离能力或分布式部署时，使用数据库作为后端是更稳健的方案。dsh-session-persistence-mysql 插件实现了 SessionPersistence 接口，将事件溯源的 SessionEvent 日志持久化到 MySQL，并提供了与 JSONL 后端等价的读写行为。

插件介绍¶

该插件由 sandersyao 维护，是一个 MIT 许可证的开源项目。它作为 DSH 的一个具体实现（seam），注册 ctx.sessionPersistence，支持事务追加、无撕裂尾部、崩溃恢复等特性。

安装与启用¶

在代码中引入并注册插件：

import { MysqlSessionPersistence } from '@sandersyao/dsh-session-persistence-mysql'

await ctx.plugin(MysqlSessionPersistence, {
  connection: { tablePrefix: process.env.SESSION_TABLE_PREFIX ?? process.env.MYSQL_TABLE_PREFIX },
})

注册后，ctx.sessionPersistence 即变为 MySQL 驱动。

核心能力¶

MySQL 持久化后端：将会话事件以追加日志的形式存储在数据库中。
读写分离支持：配置读库后，读取操作使用读连接池，写入操作使用写连接池。未配置读库时，读写共用写连接。
事务追加与无撕裂尾部：事件以事务形式追加，保证日志顺序连续且原子性，避免文件写入时产生的撕裂问题。
崩溃恢复：支持在崩溃后通过合成关闭符恢复未完成的会话，已提交记录不重写。
惰性实例化：会话头部仅在第一次追加事件时与事件批次一起原子写入。
死锁重试：遇到 ER_LOCK_DEADLOCK (1213) 错误时，会执行有界退避重试。
模式与迁移：启动时自动测试连接、创建表并验证模式版本。

配置与使用¶

插件通过环境变量配置。配置项分为插件专属的 SESSION_* 和通用的 MYSQL_*。插件优先读取 SESSION_*，未设置时回退到 MYSQL_*。这种方式允许同一个 MySQL 部署被多个插件独立配置（如各自使用不同的数据库或表前缀）。

配置优先级示例：
- SESSION_HOST / MYSQL_HOST：写主机，默认 127.0.0.1。
- SESSION_USER / MYSQL_USER：数据库用户，必填。
- SESSION_DATABASE / MYSQL_DATABASE：目标数据库，必填。
- SESSION_TABLE_PREFIX / MYSQL_TABLE_PREFIX：表前缀，默认为空，必填。
- SESSION_READ_HOST / MYSQL_READ_HOST：读库主机，为空则读写共用写连接。
- SESSION_SCHEMA_AUTO_MIGRATE / MYSQL_SCHEMA_AUTO_MIGRATE：是否自动迁移 Schema，默认 true。

启用自动迁移：

SESSION_SCHEMA_AUTO_MIGRATE=true
SESSION_HOST=127.0.0.1
SESSION_USER=root
SESSION_PASSWORD=secret
SESSION_DATABASE=dsh_session
SESSION_TABLE_PREFIX=dsh_

存储布局¶

插件在 MySQL 中创建两张数据表和一个元数据表（由表前缀决定）：
- ${prefix}sessions：存储会话头部（SessionHeader）。仅在首次追加事件时写入，惰性创建。
- ${prefix}events：追加日志表，主键为 (session_id, seq)。
- ${prefix}_meta：存储已应用的 Schema 版本。

生态与同伴插件¶

该插件通常与以下插件配合使用，以形成完整的分布式 DSH 部署：
- dsh-storage-mysql：切换默认存储后端为 MySQL。
- dsh-credentials-mysql：切换默认凭证后端为 MySQL。
- dsh-workspace-bootstrap：声明式初始化默认工作区，确保空数据库下能正常启动。

已知限制与注意事项¶

无删除/归档 API：插件接口不提供删除或归档会话的方法，清理存储需要通过 SQL 的 DELETE 操作在数据库层面离线执行。
list() 无分页与过滤：list() 方法不支持分页和过滤条件，仅返回所有会话。
跨进程租约模式限制：cluster.lease 模式仅支持单主写入，多主或读写分离拓扑下需谨慎使用。
明文存储：默认以明文存储会话事件，敏感内容（对话、工具结果）需依赖应用层加密或 MySQL 的透明数据加密（TDE）。
TLS 强制推迟：SESSION_SSL_REQUIRED 当前为预留配置，尚未强制执行 TLS 加密。
版本锁定：插件依赖 @deepseek-ai/dsh-session-persistence 和 @deepseek-ai/dsh-session 的 ^0.2.0-rc.x 版本。

结语¶

dsh-session-persistence-mysql 为 DSH 提供了基于 MySQL 的可靠会话存储方案，适合需要事务保证和高可用性的生产环境。使用前需了解其关于删除、分页和加密的限制，并根据场景配置读写分离或 TLS。