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。