前言¶
DeepSeek Harness（DSH）的会话日志、附件和存储快照都在本机 $DSH_HOME 下持续追加。换机器、重装或误删时，如果没有独立于 DSH 进程的备份，恢复往往只能靠手工拷贝目录，既难做增量，也难保留历史版本。常见做法是定期整目录打包或交给网盘同步，但要么每次全量、要么和 DSH 的文件布局与增量语义对不齐。
下面介绍社区插件 dsh-session-backup（维护者 misakalemon，分类：记忆）：把会话相关数据按物理文件增量同步到 WebDAV 或本地/网络目录，带 manifest、版本保留、排除规则、限速重试与 SHA-256 校验，并支持从设置页或 API 一键恢复。插件当前版本 0.1.0，GitHub 仓库见 misakalemon/dsh-session-backup；目录页见 SkillHub。DSH 生态是「一切皆插件」，SkillHub 为独立社区目录，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
dsh-session-backup 是 DSH 的会话远程备份插件（包名 @local/dsh-session-backup）。它在每次备份前调用 ctx.sessions.flush()，保证 live 会话尾部已落盘，再把 $DSH_HOME 下选定范围上传到远端，并在本地 $DSH_HOME/session-backup/ 维护锁、状态与运行历史。
备份单元是字节级文件，不是事件流；会话日志以 zstd 帧拼接存储，帧不可拆，因此增量粒度是整文件（README 给出中位约 0.4 MB、最大约 15 MB）。远端布局在统一前缀 <prefix> 下：
| 来源 | 本机路径 | 远端 key |
|---|---|---|
| 会话日志 | $DSH_HOME/sessions/** |
<prefix>/sessions/<相对路径> |
| 附件 | $DSH_HOME/attachments/** |
<prefix>/attachments/<相对路径> |
| 存储快照 | $DSH_HOME/storages/** |
<prefix>/storages/<相对路径> |
每次运行还会写入 <prefix>/manifest.json（各文件的 sha256、大小、mtime、上传时间），供下次运行判断能否跳过。
核心功能¶
增量、版本与删除策略¶
- 全量 + 增量：先用 size + mtime 快路径，再用 sha256 复核，减轻 mtime 抖动导致的重传。
- 版本历史：
versions.keep将旧版本存到<prefix>/versions/<key>/<时间>-<sha8>，超出份数自动淘汰最旧记录。 - 排除规则：支持
*.log、build、**/scratch/**、路径前缀等写法。 - 删除同步：默认
deleteMode: archive只增不删；设为mirror时远端镜像本地删除。
两种上传形态（archiveMode）¶
| 值 | 远端形态 | 增量 | 适合 |
|---|---|---|---|
mirror（默认） |
与本地同构目录树 + manifest.json |
文件级，只传变化文件 | 长期备份、按文件回滚 |
zip |
每次一个 STORE 的 .zip（不二次压缩） |
整包重传；内容未变则整轮跳过上传 | 便于双击查看或拷到 NAS / U 盘 |
zip 归档路径为 <prefix>/archive/<主机名>-<时间戳>.zip，保留份数由 archiveKeep（1–50，默认 3）控制。归档内路径与 mirror 一致；恢复时按 CRC-32 逐条目校验。
目标与 WebDAV 行为¶
target 可为 webdav（HTTP）或 dir（本地磁盘 / UNC）。两者 key 布局相同，恢复无差别。WebDAV 填「文件夹」式地址即可；插件会探测常见 DAV 根前缀、按需 MKCOL 建目录，并在服务端不支持 MOVE 时降级为 GET→PUT 流式复制以保留旧版本。
传输与校验¶
- 限速：
transfer.bandwidthKBps（0 表示不限）。 - 重试：
transfer.retries次指数退避；认证类错误立即失败。 - 校验：可选
verifyAfter与verifySample；设置页「校验备份」或POST /session-backup/api/verify可手动抽样回读 sha256。 - 断点续传：README 标明暂不支持；单文件 PUT 中断后下次整文件重传。
计划任务与面板¶
触发方式可组合：每轮对话结束去抖（onTurnEnd + debounceMs）、固定间隔（schedule.mode: interval）、每天固定时刻（daily）、启动延迟补偿（onStartup）。未配置目标或面板暂停时，自动触发静默跳过。
设置 →「远程备份」（README 亦写「会话远程备份」）提供服务器、计划与策略、mirror/zip、状态进度、最近 20 次运行、活动记录（最近 200 条）及恢复向导。管理 API 前缀为 /session-backup/api，需 DSH 连接鉴权（同源页面调用）。
安装与启用¶
已抓取 README 未给出形如 dsh plugin add … 的固定安装命令；请以 SkillHub 目录页 或仓库说明为准，从社区渠道安装后再启用。安装前应用当前 DSH 进程权限审阅源码与许可证（本仓库 private: true，以仓库实际许可为准）。
启用后任选一种配置方式（面板保存优先于 patch 文件）：
- 打开 DSH 设置 →「远程备份」，填写目标、凭据、范围与计划，保存即写入
$DSH_HOME/session-backup/config.json，用户名密码进入凭据库（DSH_BACKUP_USERNAME/DSH_BACKUP_PASSWORD），不落配置文件。 - 或在
cordis.patch.yml中为id: session-backup编写config，例如：
- id: session-backup
name: '@local/dsh-session-backup'
config:
enabled: true
target: webdav
archiveMode: mirror
prefix: dsh-session-backup/my-pc
remote:
url: https://dav.example.com/dav
usernameRef: DSH_BACKUP_USERNAME
passwordRef: DSH_BACKUP_PASSWORD
timeoutSeconds: 30
scope:
sessions: true
attachments: true
storages: true
maxAttachmentMB: 64
maxFileMB: 512
exclude: ['*.log', '**/scratch/**']
deleteMode: archive
versions:
keep: 5
transfer:
retries: 2
bandwidthKBps: 0
schedule:
mode: interval
onTurnEnd: true
debounceMs: 20000
onStartup: true
startupDelayMinutes: 3
target: dir 时将 remote.root 设为本地或共享目录路径。凭据也可用与 usernameRef / passwordRef 同名的环境变量覆盖。
典型用法¶
连通性自检与立即备份¶
配置 WebDAV 或目录目标并保存凭据后，在设置页执行连通性检测（对应 POST /session-backup/api/probe：写—读—删探针文件）。确认通过后点击「立即备份」，或调用：
POST /session-backup/api/run
请求体可带 { "trigger": "manual" }。运行前插件持有 backup.lock，同一时刻仅一个备份实例；抢不到锁则等下次触发。
暂停自动备份¶
需要临时停止计划任务时，在面板使用「暂停自动备份」，或 POST /session-backup/api/pause 传 { "paused": true }。暂停期间手动备份仍可用。
恢复¶
在设置页「恢复」卡片：指定非 $DSH_HOME 及其子目录的目标路径，可选前缀过滤，先勾「干跑」查看清单再执行。恢复逐文件校验 sha256；archiveMode: zip 时先校验整包 sha256 再解包。完成后将干净目录整体拷回 $DSH_HOME 即可。API 等价于 POST /session-backup/api/restore，参数 { to, prefixFilter, dryRun }。
开发者自测（仓库内）¶
维护者在 README 中给出 Node 冒烟与宿主测试入口（需在克隆后的插件目录执行，此处仅作能力说明引用）：
node test\smoke.mjs
node test\host.mjs
node test\zip.mjs
覆盖首传、跳过、mtime 抖动、版本 MOVE/降级、排除、镜像删除、zip 归档与恢复等场景。
适用场景与注意¶
适合：需要把 DSH 会话、附件、storages 快照备份到家用 NAS WebDAV、公司文件共享或第二块磁盘；希望对话结束后自动去抖备份，并保留若干文件版本以便回滚。
务必知晓：
- 插件以当前 DSH 进程权限读写本机与会远端；安装前检查源码与凭据存放方式。
- 增量是文件级；会话文件每次追加会导致整文件重传，消息量极大后上传量会上升（README 称约 16 万条消息后更明显）。
- 默认
deleteMode: archive不会删除远端多余文件；若要镜像删除需显式改为mirror。 - 不做端到端加密；隐私依赖 HTTPS 与 WebDAV 服务端权限。
- 状态与锁位于
$DSH_HOME/session-backup/（state.json、backup.lock、config.json）。
结尾¶
dsh-session-backup 把 DSH 会话相关数据做成可配置的 WebDAV/目录增量备份：mirror 或 zip、manifest 与版本目录、计划触发与恢复校验都在设置页和 /session-backup/api 内闭环。进一步细节与限制见 GitHub README，安装与展示见 SkillHub 插件页。
