前言¶
DeepSeek Harness（DSH）运行时会在 home 目录下写入会话记录、记忆文件、配置以及 profile 插件及其依赖树。这些内容是用户在 DSH 中的工作成果与状态，通常没有纳入版本控制。手动备份这些文件容易遗漏或出错，而依赖应用退出时的文件系统快照往往不够可靠。
dsh-auto-sync 插件将 DSH home 目录自动纳入版本控制，并推送到用户自有的私有 git 仓库。它把 DSH 写入 home 的内容作为工作树管理，支持跨平台、可配置，且不对失败保持沉默。
是什么¶
dsh-auto-sync 是一个 DeepSeek Harness 插件，由维护者 wwwangzilin 开发，归类为联网工具。它将 DSH home 目录与用户指定的 git 远端关联，自动同步变化并持久化历史版本。
插件不连接本项目运营的任何服务器，也不携带任何凭据，远端由用户指定（可以是私有 GitHub/GitLab 仓库、内网服务器或 NAS 上的裸仓库）。
备份范围¶
插件默认备份以下内容：
- 会话记录：
<home>/sessions/** - 记忆文件：
<home>/memories/**、<home>/memory/** - 配置：
<home>/settings.yaml - Profile 插件：
<home>/profiles/<name>/ - 项目工作：用户指定的目录（可选）
凭据文件 <home>/.credentials.yaml 默认被排除，见安全模型。
工作原理¶
插件经 profile 的 bundle 层注册，运行在宿主进程中，只负责调度。备份分为两条线：
热备份线（进程内）
- 在对话结束时触发，复制、提交、推送到分支
dsh-hot。 - 每轮对话结束后 30 秒触发，并有 15 分钟下限，保证长时间工具调用期间状态仍能落盘。
完整快照（分离进程）
- 以分离进程运行，避免应用退出截断快照。
- 定时执行（默认每日一次）以及退出时执行，提交到分支
dsh-snapshot。 - 包含 home 完整镜像、profile 依赖清单与依赖树。
两条备份线独占一个分支和一份独立的 git 工作区副本，避免并发备份时出现 index.lock: File exists 冲突。
环境要求¶
| 组件 | 版本 |
|---|---|
| DeepSeek Harness | >= 0.2.0-rc.2 |
| Node.js | ^22.19 \|\| >=24 |
| git | 2.30+ |
git 须在 PATH 中，启动时探测。
安装与启用¶
从桌面应用安装¶
- 在侧栏打开插件页。
- 选择添加插件，填入本目录的绝对路径。
- 启用
dsh-auto-sync组合包。 - 重启 DeepSeek Harness。
从命令行安装¶
dsh plugin --profile desktop add link:/path/to/dsh-auto-sync
首次运行¶
首次启动且无配置时，插件写入一份带说明的模板到 <home>/sync-plugin/config.json，并记录一条警告：在设置 remote 之前备份处于暂停状态。
设置远端有两种方式：
命令方式（无需重启）
/dsh-sync setup git@github.com:you/dsh-backup.git
编辑配置文件后重启
{
"remote": "git@github.com:you/dsh-backup.git"
}
下次启动时，插件初始化仓库、为每条启用的备份线创建分支与工作区副本，并开始备份。
/dsh-sync 命令¶
需要 profile 提供 commands 服务（Web 与桌面 profile 提供，headless 与 ACP profile 不提供）。
| 命令 | 行为 |
|---|---|
/dsh-sync |
报告远端、各备份线及上次成功时间 |
/dsh-sync setup [地址] |
设置远端并执行首次初始化 |
/dsh-sync remote <地址> |
仅修改远端，不改动分支 |
/dsh-sync lines |
列出备份线及其分支 |
/dsh-sync workspace <路径> |
启用项目线并指定目录 |
/dsh-sync workspace off |
关闭项目线 |
/dsh-sync run |
立即安排一次快照 |
/dsh-sync doctor |
诊断 git、仓库、分支与工作区副本 |
命令产生的修改均写回配置文件，结果可 diff。
设置页¶
桌面版与 Web 版的「设置 → 插件」提供自动备份页签，与斜杠命令读写同一份配置文件：
- 填写或修改远端地址；首次配置保存后立即执行初始化，无需重启。
- 查看各备份线的分支、启用状态、上次成功时间与最后一次错误。
- 指定同时备份的项目目录，清空即关闭项目线。
- 手动触发一次快照。
配置¶
配置文件位于 <home>/sync-plugin/config.json。
顶层键¶
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
remote |
string |
"" |
备份远端地址，必填。支持 SSH 与 HTTPS。 |
remoteName |
string |
"origin" |
origin 已指向其他仓库时使用的远端名。 |
worktree |
string |
<home>-backup |
各备份线工作区副本的父目录，须位于 home 之外。 |
locale |
string |
"zh" |
命令与引导语言：zh 或 en。 |
exclude |
string[] |
见下文 | 追加到 home .gitignore 的忽略规则。 |
userName |
string |
"dsh-auto-sync" |
git 未配置身份时使用的提交者名称。 |
userEmail |
string |
"dsh-auto-sync@localhost" |
同上，邮箱。 |
home |
string |
$DSH_HOME 或 ~/.dsh |
覆盖 home 目录；显式 --home 优先于环境变量。 |
默认忽略规则：
.credentials.yaml
**/node_modules/
*.log
.DS_Store
Thumbs.db
sync-plugin/.sync-status.json
memory/memory.db-shm
memory/memory.db-wal
备份线键¶
每条线均接受 enabled 与 branch。
lines.hot
| 键 | 默认值 | 说明 |
|---|---|---|
paths |
[".sync-status.json"] |
每轮对话后提交的文件，相对 home；解析到 home 之外的路径会被拒绝。 |
debounceMs |
30000 |
最后一轮对话结束后的静默期。 |
intervalMs |
900000 |
无条件刷新间隔，保证长时间工具调用期间状态仍能落盘。 |
lines.snapshot
| 键 | 默认值 | 说明 |
|---|---|---|
intervalMs |
86400000 |
完整快照间隔。 |
profile |
"desktop" |
纳入依赖树的 profile。 |
includeNodeModules |
true |
在快照中重新纳入该 profile 的 node_modules。 |
files |
清单文件列表 | 与依赖树一同镜像的 profile 文件。 |
lines.workspace
| 键 | 默认值 | 说明 |
|---|---|---|
enabled |
false |
未设置 source 时该线保持空闲。 |
source |
"" |
要镜像的项目目录绝对路径。 |
exclude |
[".git", "node_modules", "dist", "build", "target", ".cache"] |
递归时跳过的目录或文件；设置后完全取代默认值。 |
release 备份线¶
完整备份的另一种形态：将 home 打包为 tar.gz 并作为 release 资产发布。
| 键 | 默认值 | 说明 |
|---|---|---|
enabled |
false |
是否启用。 |
repo |
"" |
GitHub 仓库，为空时由 git 远端推导为 owner/name。 |
tagPrefix |
"dsh-backup-" |
tag 前缀。 |
keep |
5 |
保留最近 N 份。 |
intervalMs |
604800000 |
发布间隔（7 天）。 |
includeNodeModules |
false |
是否包含 node_modules。 |
includeSecrets |
false |
是否包含凭据文件。 |
partSizeBytes |
1500000000 |
分片大小（约 1.5 GB）。 |
备份线类型¶
hot → dsh-hot¶
频繁变化的小文件。文件复制进该线的工作区副本后提交并推送。默认在对话轮结束后 30 秒触发，并有 15 分钟下限。
snapshot → dsh-snapshot¶
home 的完整镜像，附带所配置 profile 的依赖清单与依赖树。运行时机：每日一次、退出时一次，以及启动时发现上次快照早于间隔的补跑。
workspace → dsh-workspace¶
镜像指定的项目目录，使代码与其描述状态一同版本化。默认关闭。构建产物与依赖缓存被排除，排除列表可配置。
release → GitHub Release 资产¶
将 home 打包为 tar.gz 并作为 release 资产发布。适合长期归档与灾难恢复，存储为压缩包而非 git 历史。
恢复¶
恢复整个 home
git clone <远端地址> ~/.dsh
cd ~/.dsh
git checkout dsh-snapshot
dsh plugin --profile desktop install
恢复单个文件
git show dsh-snapshot:sessions/2026-01-01/....jsonl > restored.jsonl
恢复项目
git clone --branch dsh-workspace <远端地址> project
git log dsh-snapshot -- <路径> 给出单个文件的修订历史。
安全模型¶
默认排除凭据。首次运行时插件把 .credentials.yaml 及以上规则写入 home 的 .gitignore。该文件保存服务商 API Key，不应推送。
插件接管而非覆盖已有仓库。如果远端已存在内容，插件会将其视为初始历史，不再清空。
适用场景与注意¶
该插件适合需要为 DSH home 目录提供版本化备份的用户，尤其是需要长期保留历史状态或进行灾难恢复的场景。
插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。配置文件与命令输出均支持中文与英文，可通过 locale 字段或环境变量 DSH_AUTO_SYNC_LOCALE 控制。
总结¶
dsh-auto-sync 通过两条备份线（热备份线与完整快照）将 DSH home 目录纳入版本控制，支持增量更新与完整镜像，并提供 release 资产归档选项。备份线独立分支与工作区副本的设计避免了并发冲突，失败可见的机制避免了静默失败。配合配置文件与设置页，用户可以灵活控制备份范围与策略。
插件目录页：https://www.skillhub.cn/plugins/wwwangzilin/dsh-auto-sync
GitHub：https://github.com/wwwangzilin/dsh-auto-sync
