DSH 的会话、插件清单和设置分散在多台机器上时，恢复和迁移比较麻烦。现有的基于 Git 的方案通常需要 git 二进制支持，且处理冲突和合并比较复杂。minghuo/dsh-github-sync 插件通过 GitHub REST API 解决这些问题，把配置备份到私有仓库，并在另一台机器上按整机或单会话恢复。
核心能力¶
- 多机同步：支持在多台机器间同步会话、插件清单与设置。
- 纯 REST API：不依赖 git 二进制，沙箱环境也能用，token 不会落进配置文件。
- 独立目录：每台机器在仓库里拥有独立的
instances/<实例ID>/目录，互不重叠，无需合并文件。 - 恢复模式：支持按整机、工作区或单会话恢复，支持 dryRun 预览。
- 内容寻址：基于 SHA1 哈希比对，未变化的会话不重复上传。
- 浏览与阅读：本机或远端浏览会话清单，支持直接阅读 zstd 压缩的日志（需 Node ≥ 22.15）。
- 工作区重映射：恢复时可将远端的工作区目录名映射到本机路径，确保文件落在正确的位置。
- 本地快照：支持在推送前或恢复前自动拍快照，用于快速回滚。
- 安全与私有：强制私有仓库，令牌只写不回读，对状态修改请求校验同源。
安装与启用¶
在 Web UI 对应的 profile 下安装：
dsh plugin --profile web add github:minghuo/dsh-github-sync
安装完成后重启 dsh web 使插件生效。
配置与备份¶
- 在 GitHub 建一个私有仓库（插件不代建，公共仓库会被拒绝）。
- 创建一个 fine-grained PAT，只授权该仓库。权限勾选
Contents: Read and write（若使用 PR 模式，还需勾选Pull requests: Read and write）。 - 打开 Web UI → 设置 → GitHub 同步，填入仓库 URL（
owner/repo或完整 URL）、分支名和令牌，保存。 - 点击“验证仓库”确认可写且为私有，随后点击“立即备份”。
恢复与会话管理¶
在另一台机器上安装相同的插件并配置相同的仓库后，进入“会话备份”页面即可查看并恢复远程内容。
- 定时备份：在“概览 → 自动备份”中开启。设置
autoSync为 true，并指定intervalMinutes（最小 5 分钟），支持启动时备份一次。 - 浏览：
- 本机浏览：按工作区分组，显示会话数、体积、最近修改时间及最大日志文件名。
- 远端浏览：列出每台机器备份的工作区与会话统计信息。
- 恢复：支持整台机器、单个工作区或 dryRun 模式。恢复前会自动拍本地快照（
pre-restore-*）。 - 工作区重映射：解决两台机器上同一项目路径不同的问题，恢复时将远端目录名映射到本机路径。
- 阅读日志：点击会话名即可在页面内解压查看 zstd 日志文本。
同步内容与限制¶
同步内容¶
插件提供三类内容的同步开关，关闭某类既不上传也不会删除云端已有内容：
| 分组 | 默认 | 内容 | 排除项 |
|---|---|---|---|
sessions |
开 | $DSH_HOME/sessions/** |
*.tmp、session.lock、.dsh-mkdir* |
plugins |
开 | 各 profile 的 package.json、cordis.patch.yml、pnpm-lock.yaml、pnpm-workspace.yaml |
node_modules、cordis.yml、.dsh-market、.dsh-module-fallback |
settings |
关 | $DSH_HOME/settings.yaml |
— |
本地机密（如 .credentials.yaml、.anonymous-user-id）从不参与同步计划。
安全与已知限制¶
- 令牌安全：令牌只写不回读，存储在
settings命名空间或$DSH_HOME/dsh-github-sync/config.json。 - 私有强制：每次推送前会检查仓库元数据，
private !== true直接拒绝。 - 跨机恢复：不会改写会话 header 里的
cwd（日志体中的绝对路径保持原机器路径）。 - 文件限制：GitHub 单个 blob 上限 100 MB，默认跳过超过 45 MB 的文件。
- 树接口限制：会话目录树很大时，GitHub tree 接口可能返回
truncated，此时只做增量比对。 - 共存：与遗留的
~/.dshgit 仓库并存，插件不会触碰该目录。 - 不参与同步项：
$DSH_HOME/storages/workspace.json（工作区注册表）、$DSH_HOME/attachments（附件）不在同步范围内。
生态背景¶
DSH 理念是“一切皆插件”，该插件已上架 SkillHub 插件目录（独立站点，与 DeepSeek 无官方从属关系）。
