dsh-auto-sync

English | 中文

DeepSeek Harness 插件，将 DSH home 目录自动纳入版本控制并推送到用户自有的 git 远端。

插件把 DSH 写入 home 的内容作为工作树管理：会话记录、记忆文件、设置、profile 插件及其依赖树，另可镜像指定的项目目录。目标远端由用户指定；插件不连接本项目运营的任何服务器，也不携带任何凭据。

目录

• 备份范围
• 设计约束
• 工作原理
• 环境要求
• 安装
• 首次运行
• /dsh-sync 命令
• 设置页
• 配置
• 备份线
• 恢复
• 安全模型
• 运行行为
• 排错
• 开发
• 许可

备份范围

凭据文件 /.credentials.yaml 默认被排除，见安全模型。

设计约束

1. 存储位置由用户控制。 远端为普通 git 仓库：私有 GitHub 或 GitLab 仓库、内网服务器、NAS 上的裸仓库。
2. 失败必须可见。 停止工作却没有提示的备份工具比没有备份更糟。每次运行的结果都会记录；备份线超过 48 小时未成功会在 DSH 日志中报告。

工作原理

插件经 profile 的 bundle 层注册，运行在宿主进程中。它只负责调度：热备份线在进程内完成小规模提交，完整快照以分离进程运行，避免应用退出截断快照。

┌──────────────────────────────┐
turn/end ───────▶│  热备份线（进程内）           │──▶ 分支  dsh-hot
定时 ───────────▶│  复制 → 提交 → 推送           │
└──────────────────────────────┘

┌──────────────────────────────┐
定时 ───────────▶│  cold-sync.mjs（分离进程）    │──▶ 分支  dsh-snapshot
关闭 ───────────▶│  镜像 → 提交 → 推送           │
└──────────────────────────────┘
│
└───────────────▶ workspace-sync.mjs
分支  dsh-workspace

每条备份线独占一个分支和一份独立的 git 工作区副本，因此任意两条线不会争用同一个 index——这是并发备份产生 index.lock: File exists 的原因。退出时的快照不会与热备份提交冲突。

配置按以下优先级读取：

1. profile 补丁中 Cordis 条目的 config；
2. /sync-plugin/config.json；
3. 内置默认值。

配置文件已声明的键优先于补丁层：插件管理器会重写 profile 补丁，而配置文件由用户维护。

环境要求

目录镜像、加锁与进程管理均由 Node 内置模块实现，不调用平台特化工具。

安装

从桌面应用安装

1. 在侧栏打开插件页。
2. 选择添加插件，填入本目录的绝对路径。
3. 启用 dsh-auto-sync 组合包。
4. 重启 DeepSeek Harness。

从命令行安装

dsh plugin --profile desktop add link:/path/to/dsh-auto-sync

首次运行

首次启动且无配置时，插件写入一份带说明的模板到 /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 不提供）。

命令产生的修改均写回配置文件，结果可 diff。

界面语言

命令输出与首次引导支持中文与英文，取值顺序为：配置中的 locale → 环境变量 DSH_AUTO_SYNC_LOCALE → DSH 界面语言（宿主提供时）→ 默认 en。日志信息固定为英文，便于在 issue 中引用。

设置页

桌面版与 Web 版的「设置 → 插件」提供自动备份页签，与斜杠命令读写同一份配置文件：

• 填写或修改远端地址；首次配置保存后立即执行初始化，无需重启；
• 查看各备份线的分支、启用状态、上次成功时间与最后一次错误；
• 指定同时备份的项目目录，清空即关闭项目线；
• 手动触发一次快照。

实现分为两部分：

客户端为无构建步骤的原生浏览器脚本，经 window.__ModuleLoader__.load 加载并复用宿主提供的 React。

接口

接口只处理页面使用的字段，其余键原样保留。写操作要求 Origin 与 Host 同源，不一致返回 403。

不提供 webServer 的 profile 不注册这些路由，插件其余功能不受影响。

配置

配置文件位于 /sync-plugin/config.json。

顶层键

默认忽略规则：

.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

lines.snapshot

lines.workspace

示例

{
"remote": "git@github.com:you/dsh-backup.git",
"worktree": "/home/you/.dsh-backup",
"locale": "zh",
"lines": {
"hot": {
"intervalMs": 900000,
"paths": [".sync-status.json"]
},
"snapshot": {
"intervalMs": 43200000,
"profile": "desktop",
"includeNodeModules": true
},
"workspace": {
"enabled": true,
"source": "/home/you/projects/app",
"exclude": [".git", "node_modules", "dist"]
}
}
}

备份线

hot → dsh-hot

频繁变化的小文件。文件复制进该线的工作区副本后提交并推送。默认在对话轮结束后 30 秒触发，并有 15 分钟下限，保证长时间工具调用期间状态仍能落盘。

snapshot → dsh-snapshot

home 的完整镜像，附带所配置 profile 的依赖清单与依赖树。link: 依赖按清单条目记录，克隆后由包管理器恢复；已发布依赖固化进分支。

运行时机：每日一次、退出时一次，以及启动时发现上次快照早于间隔的补跑。重复重启会重置倒计时，补跑避免了该问题。

workspace → dsh-workspace

镜像指定的项目目录，使代码与其描述状态一同版本化。默认关闭。构建产物与依赖缓存被排除，排除列表可配置。

release → GitHub Release 资产

完整备份的另一种形态：将 home 打包为 tar.gz 并作为 release 资产发布。

两种完整备份并存的原因：

日常增量使用 snapshot，长期归档与灾难恢复使用 release。

以 3.4 GB 的 home 实测（排除依赖），归档体积约 369 MiB。

"release": {
"enabled": true,
"repo": "",
"tagPrefix": "dsh-backup-",
"keep": 5,
"intervalMs": 604800000,
"includeNodeModules": false,
"includeSecrets": false,
"partSizeBytes": 1500000000
}

• repo 为空时由 git 远端推导为 owner/name。
• 超过 partSizeBytes 时分割为 .part000、.part001 等，并生成记录各部分 sha256 的 manifest.json。
• keep 限制保留数量；超出时优先删除较早的 tag，且仅考虑带本线 tagPrefix 的 tag。
• .credentials.yaml 默认排除；includeSecrets: true 会将其打入归档，在公开仓库上等同于泄露密钥。

上传前可先预演：

node release-backup.mjs --dry-run

输出归档体积、分片数与目标仓库。

传输在 GitHub CLI 存在时使用 gh，否则使用 REST API 加 token。该顺序是必要的：在 TLS 中间人代理环境下，Node 的 fetch 会因 UNABLE_TO_VERIFY_LEAF_SIGNATURE 失败，而 gh 使用独立的信任链。REST 路径的 token 依次取自 DSH_AUTO_SYNC_GITHUB_TOKEN、GITHUB_TOKEN、gh auth token。

恢复

恢复整个 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，不应推送。

接管而非覆盖已有仓库。 home 已是带远端的 git 仓库时，其历史与远端配置原样保留；插件只新增分支与工作区副本，不重写、变基或强推历史，也不修改已指向其他位置的远端。

从不强推。 推送被拒绝时合并远端顶端并重试一次，冲突以本地快照为准。历史只增不改。

配置无法导出 home 之外的文件。 lines.hot.paths 相对 home 解析，越界即拒绝。

对会话失败开放。 备份错误不会进入会话事件链；失败通过状态文件与日志上报，对话照常进行。

运行行为

并发

每条线独占工作区副本与 index。快照脚本获取锁文件，重叠触发（定时器、启动补跑、退出钩子）串行执行。超过一小时的锁视为废弃。

失败处理

可观测性

/sync-plugin/status.json 按线记录上次成功时间与最后一次错误：

{
"version": 1,
"updatedAt": "2026-01-01T00:00:00.000Z",
"lines": {
"hot": { "lastSuccessAt": "2026-01-01T00:00:00.000Z" },
"snapshot": { "lastSuccessAt": "2026-01-01T00:00:00.000Z" },
"workspace": { "lastError": "push failed", "lastErrorAt": "2026-01-01T00:00:00.000Z" }
}
}

超过 48 小时未成功的备份线在启动时报告到 DSH 日志。

排错

备份暂停，remote 为空。
在 /sync-plugin/config.json 中设置 remote 后重启 DSH，或执行 /dsh-sync setup <地址>。

推送报 could not read Username。
插件运行环境没有终端，git 无法交互输入。配置免口令 SSH key，或预先保存凭据到 credential helper。

出现 index.lock: File exists。
本插件按设计避免同一 index 上的并发。出现该错误说明上一个 DSH 进程未正常退出，删除对应工作区副本 .git 目录下的陈旧锁文件。

快照线未运行。
确认 lines.snapshot.enabled，检查 status.json。常见原因为 PATH 中缺少 git，启动时会报告。

工作区副本因检出其他分支被拒绝。
插件不会接管检出了其他分支的目录。将 worktree 指向其他位置，或删除该陈旧目录。

中文命令输出未生效。
确认 locale 为 "zh"，或设置 DSH_AUTO_SYNC_LOCALE=zh。

开发

仓库无运行时依赖。测试在系统临时目录中创建一次性仓库，并对推送到远端的内容断言，包含反向用例：密钥、日志与构建产物不得出现在任何分支。

node tests/e2e.mjs           # 初始化、热提交、快照、推送
node tests/verify-remote.mjs # 对远端实际内容断言
node tests/edge.mjs          # 项目线、接管已有仓库、未配置启动、路径逃逸
node tests/onboard.mjs       # 远端校验、引导消息、命令、中英文一致性
node tests/api.mjs           # 设置页接口：校验、持久化、跨站拦截
node tests/client.mjs        # 客户端脚本：模块工厂、页签注册

许可

MIT，见 LICENSE。