dsh-sync

DSH 跨设备同步插件。通过使用者自己的私有 HTTPS Git 仓库或 SFTP 服务器同步会话、附件、配置及选定工程，支持在线安全范围应用、离线恢复及经确认的插件升级。

• 当前版本：0.6.0；许可证：MIT。
• 公开源码／安装包：https://github.com/vxdeus/dsh-sync
• 公开软件与私人备份完全分开：发布包不含作者的同步仓库、服务器连接信息、账号、密钥、令牌、会话、附件或工程数据。
• 首次安装没有预配置远端。安装、启动及打开面板不自动上传或下载；已有本机配置不会被安装初始化覆盖。

环境与安装

需要带插件管理器的 DeepSeek Harness，运行时 Node.js 24 或更高版本。SFTP 另需本机可用的 OpenSSH ssh / sftp。在线应用及插件升级取决于宿主提供的接口；不可用时明确禁用，不会绕过授权或降级为直接覆盖会话文件。

在 DSH 插件管理器中安装 GitHub Release 的 dsh-sync.tgz 或带版本号安装包，并核对同一 Release 的 SHA256SUMS。随后完全退出并重新打开 DSH，再刷新原有网页。仅刷新网页不能保证更新宿主插件的模块缓存。

入口：设置 → 跨机同步，或侧边栏底部的同步。

配置自己的存储

配置文件位于当前 DSH_HOME 下的 dsh-sync.json；未设置 DSH_HOME 时为用户目录下的 .dsh/dsh-sync.json。它只留在本机，不进入同步快照。请在本机编辑，勿将真实配置提交到公开源码仓库或贴入聊天。

私有 HTTPS Git

新建仅自己／授权协作者可访问的私有数据仓库，使用独立同步分支。下面仅是不可连接的占位示例，请替换仓库和账号：

{
  "backend": "gitee",
  "repoUrl": "https://git.example.invalid/your-account/private-sync.git",
  "branch": "dsh-sync",
  "username": "your-account",
  "token": "",
  "privateRepoConfirmed": false,
  "profiles": ["desktop"],
  "includeAttachments": true,
  "maxExtraBytes": 209715200,
  "extras": []
}

gitee 是保留的 Git 后端配置名，界面也沿用 Gitee 标签。Git 传输使用 HTTPS 用户名／令牌认证；不同提供商的兼容性和权限要求需自行验证。

令牌可只设置在本机环境变量 DSH_SYNC_TOKEN，或写入本机配置的 token 字段。使用最小必要仓库权限，不把凭据嵌入 URL。亲自确认数据仓库为私有后才将 privateRepoConfirmed 改为 true；这是本机确认声明，插件不会自动查询或更改远端可见性。

不得将本项目的公开源码仓库作为个人同步目标。 插件会拒绝此目标。切换仓库、分支或账号会隔离 Git 工作副本；更换旧设备配置后建议先下载核对，不强制推送覆盖远端。

自己的 SFTP 服务器

不提供托管服务器、共享账号、预置主机公钥或私钥。每台设备自行生成／保管密钥，并由服务器管理员授权设备公钥。在本机配置：

• backend：sftp。
• sftp.host：自己的服务器域名或地址；port：SSH 端口。
• sftp.username：自己获授权的服务器用户。
• sftp.remoteRoot：安全的 /data/ 子目录，例如 /data/my-sync；须按服务器 SFTP 可见路径配置。
• sftp.privateKeyPath：本机私钥绝对路径，私钥不经过网页、不进入同步。
• sftp.hostKey：通过可信独立渠道核对的完整 ssh-ed25519 服务器公钥。不要关闭主机身份校验，也不要盲目信任首次网络扫描结果。

密钥需可用于非交互式 OpenSSH 认证。账户、密钥和目录访问权限由使用者管理。Git 和 SFTP 备份相互独立；切换存储不会搬运或删除旧备份。面板保存存储选择不会自动传输。

日常使用

源设备上传

1. 先检查状态与同步范围。工程／额外文件须手动添加自定义映射，例如逻辑名 my-project。
2. 可执行本地预演：它会扫描并暂存本机数据；已配置 Git 时还可能创建本地提交，不是只读检查，但不推送或访问远端。
3. 明确确认后上传。仅当显示远端回读／哈希核验成功时，才视为备份成功。超时后可能显示待确认，不自动重复推送。
4. 同一时刻只在一台设备编辑。不是实时双向同步，也不自动合并两台设备的分叉历史。

目标设备下载与恢复

1. 安装兼容版本插件，并配置自己的仓库凭据或 SFTP 授权。各设备按相同逻辑名映射工程，本机目标路径可以不同。
2. 默认在线模式只应用宿主允许的安全范围：冷历史通过原生接口导入；已加载、分叉、格式不支持的会话及忙碌工程保留，运行时配置等推迟应用。查看未应用项，不能将部分应用当成全量成功。
3. 仅下载／离线恢复只产生暂存计划，不覆盖现有会话或工程。检查结果后完全退出 DSH，再运行该结果给出的恢复命令。需可运行 Node.js 24+；不要在另一台机器复用生成的本机恢复脚本。
4. 恢复核对源哈希及下载时的目标基线，覆盖前验证备份；冲突时停止，不自动改权限。内容相同的只读附件保持原样。失败计划不可重跑，先检查日志并重新下载。
5. 恢复中失败会尝试回滚，仍可能出现需人工处理的不完整回滚。请保留日志和备份；本插件不替代独立备份。

离线计划会记录本次宿主端口并检测监听，但仍须自行确认所有相关 DSH 进程已退出。不提供自动关机、自动关闭 DSH、配套桌面宿主补丁或一键授权新设备的功能。

下载尚未完整应用时会阻止后续上传，避免用旧本机快照覆盖远端。不要轻易勾选覆盖未应用远端内容；只有核对并明确接受丢弃风险后才能使用此选项。

跨设备插件升级

快照可携带已安装插件的精确版本、支持的本地安装包和升级说明。目标设备下载后仅检测差异；用户选中具体插件并再次确认后才交给宿主插件管理器安装。模型调用另需本次插件管理授权。

不自动批准依赖构建脚本，不自动降级，不自动重启。远端说明及本地插件包都属于不受信任输入，请先核对来源；安装插件意味着允许代码在宿主环境执行。若返回待重启，由使用者手动重启。安装后重新下载恢复计划，以免使用安装前的旧基线。

同步范围、隐私与限制

• 包含：指定 profile 的安装声明／锁文件、允许的会话与 storages / state 文件、.agent-presets、可选附件、已有 dsh-pet 配置和明确添加的自定义项。
• 不直接复制：node_modules、模型／OAuth 登录凭据、integrations、IM 聊天存储、运行时、缓存、同步配置、私钥和令牌。插件包按白名单另行归档，不直接归档 profile。
• 本机搜索覆盖诊断与额度预测缓存不跨机覆盖；真实费用账本与搜索用量日志仍在允许范围内。
• 默认排除工程依赖、Git 历史和构建产物。凭据路径过滤不能识别任意正文中的秘密。会话、附件、插件配置、脚本和工程可能本来就包含隐私／密码；上传前自行审查。
• 私人快照及默认 Git 提交可能记录设备主机名、系统用户名和配置账号，并非匿名同步。私有 Git / SSH 提供访问控制和传输保护，不提供客户端端到端加密。Git 历史可能保留已删除的内容；SFTP 历史快照和未引用对象暂不自动清理。
• 目录名及部分文本中的用户目录可做占位符转换；压缩历史内部路径和自定义工程内容不保证跨盘符自动修复。迁移后可能需重新定位工程。
• 单项自定义同步默认上限 200 MiB；缺失、超限或未映射项目可能阻止上传，避免静默丢失旧备份。
• IM 机器人历史不在同步范围内；同步 DSH 会话不等于两个 QQ 机器人自动续接话题。

模型工具

工具	用途
dsh_sync_status	只读检查配置、范围及插件升级提醒
dsh_sync_extras	添加／移除／查看本机工程映射，不传输
dsh_sync_upload	明确要求后上传；dryRun: true 本地预演
dsh_sync_download	mode: online 安全在线范围；mode: offline 下载并生成离线计划
dsh_sync_update_plugins	仅安装用户明确确认的当前计划中所选插件

开发与发布

node scripts/test.mjs
node scripts/verify-public.mjs
node scripts/release.mjs
node scripts/smoke-package.mjs

隔离测试使用合成临时数据，不需要真实用户配置或访问真实仓库。Windows 的符号链接测试取决于系统权限；若沙箱重写 junction 元数据，必须在正常 Windows 环境复核，不能通过移除安全断言宣称测试通过。原生宿主集成测试需单独配备支持的 Host，默认不访问真实 profile。

打包使用 npm 标准格式及显式文件白名单，并核对归档成员、字节和 SHA256。不上传任何备份，不执行 npm publish，不自动创建 GitHub Release。公开发布步骤及市场提交见 PUBLISHING.md，版本说明见 CHANGELOG.md。