前言¶
本地部署的 DeepSeek Harness（DSH）把对话和会话落在本机磁盘上，没有配套的云端账号或统一存储。你在办公室电脑聊到一半的任务，回到家另一台机器上往往只能从头开新会话，或靠手工拷贝 session 目录，路径和工作区登记还要自己对齐。
dsh-github-sync 做的是把会话（以及会话引用的附件）推到你自己的私有 GitHub 仓库，在 B 机拉下来后改写工作区路径并登记进项目列表，接着聊。不依赖自建服务器，也没有插件自带的账号体系，只有你的仓和 fine-grained 访问令牌。
这是什么¶
插件全名 dsh-github-sync，维护者为 mount9527，在 DSH 社区目录中归类为「记忆」。当前包版本为 0.5.1（见仓库 package.json），许可证 MIT。
一句话定位：把 DSH 会话同步到私有 GitHub 仓，用于 Windows / macOS 下的跨设备接力。同步是纯手动的，不点不动，没有后台定时任务。
核心功能¶
装好后左侧边栏会出现「GitHub 同步」面板。README 中归纳的能力如下。
| 能力 | 说明 |
|---|---|
| 上传会话 | 勾选本地会话推送；连带引用到的图片等附件；一批文件合成一个原子提交 |
| 下载会话 | 从远端拉回后改写头帧里的 cwd 到本机工作区，并通过宿主服务注册进项目列表，一般无需重启即可继续聊 |
| 上传文件夹 | 默认关闭，在设置里开启后，可选工作区子目录，按排除清单过滤后推到 <项目>/files/ |
| 下载文件 | 默认关闭，开启后把远端文件写回工作区（同名冲突另存副本，路径做了防穿越） |
| Agent 工具 | 可对 agent 说「把这条会话推到 GitHub」等；宿主侧先 preview 出清单，确认后再 execute |
传输过程带文件级进度条，可展开明细、单文件跳过、在文件之间取消；面板里的工作区选择、勾选与开关会记在浏览器本地。每条会话旁有同步徽标（已同步、本地更新、远端更新、未上传、活跃等），便于判断要不要推或先拉。
仓库侧典型布局：
README.md # 自动生成的索引（每次上传重写）
manifest.json # 会话 id → 路径、原始 cwd、sha、附件列表
<项目>/sessions/<id>.jsonl.zstd # 会话本体
<项目>/attachments/<sha>.<ext> # 附件
<项目>/files/<相对路径> # 可选的文件夹同步内容
多设备上传前会合并远端索引，避免互相覆盖记录；两端都改过同一会话时，预览会标 blocked，可先下载或明确选一边覆盖。
安装与启用¶
从插件市场安装（推荐）：在 DSH 的「插件」里搜索 dsh-github-sync，安装后启用即可。
从本地目录安装（开发或自用）可按 README 任选其一：
- DSH →「插件」→ 添加插件 → 本地目录，选中插件所在文件夹。
- 由 agent 调用
plugin_manager install_bundle，target填该文件夹的绝对路径。 - 在 profile 的
package.json里增加"dsh-github-sync": "link:<路径>"，并把它加入dsh.profile.bundles。
运行环境要求：node >= 20.0.0，dsh >= 0.2.1-rc.5（见 package.json 的 engines）。
大陆网络若 npm 官方源较慢，README 建议用镜像安装包（与 DSH 插件市场安装是不同路径，按需使用）：
npm install dsh-github-sync --registry=https://registry.npmmirror.com
镜像同步有延迟，刚发版时可能没有最新版。客户端改动后按 F5 刷新页面；宿主代码改动需重载插件（重启 DSH，或在插件管理器里关闭再启用）。
首次配置¶
- 建空的私有仓：在 GitHub 新建仓库，不要勾 README、不要勾
.gitignore，类型选 Private。首次提交时仓里已有文件会多一次合并。 - 建 fine-grained PAT：打开
https://github.com/settings/tokens?type=beta→ Generate new token。Repository access 选 Only select repositories 且只勾这一个仓；Contents 为 Read and write；Metadata Read-only（勾 Contents 后通常会带上）；其它权限保持 No access。令牌只显示一次，复制后尽快填入面板。 - 面板填写并测试：右上角设置 → 仓库地址（
owner/repo或完整 URL）+ 访问令牌 → 测试连接。成功时显示连接正常 · owner/repo。公开仓会被拒绝；401常见为令牌未粘全，404多为仓名错误或令牌未授权到该仓。
没连上仓库时，面板顶部有「开始配置」向导，步骤与上面一致。
典型用法¶
面板操作¶
所有写操作必须先预览：预览会为每个文件标注 upload / skip / blocked / copy 及原因，确认后才执行。被 blocked 远端更新 挡住的行，行尾有「先下载」按钮。
日常可在面板中：勾选本地会话 →「预览上传」；或勾选远端会话 →「下载会话」。配合搜索、「只看未同步」「选未同步」「同步此工作区（N）」批量处理。顶部可查看远端索引里的设备与最近活动时间，以及历史记录（落盘在 $DSH_HOME/github-sync/history.jsonl）。
对 Agent 说¶
README 列出的自然语言示例包括：
- 「把这条会话推到 GitHub」
- 「远端都有哪些会话」
- 「从远端把某某会话拉到这个工作区」
对应工具会先 phase=preview 给出清单，再在用户确认后以 phase=execute 执行。
适用场景与注意¶
适合谁：在多台电脑之间用同一套私有 GitHub 做「会话接力」的 DSH 用户；希望对话和附件进自有仓、不经过第三方同步服务的团队或个人。
安全与边界（据 README）：
- 插件默认只同步对话；文件夹/文件同步需在设置里显式打开，未开启时相关接口返回 403。
- 只允许私有仓；密钥类文件名（如
.env*、*.pem、id_rsa等）上传会被硬阻断。 - Token 由宿主保存在
$DSH_HOME/.credentials.yaml，面板不回显。写操作范围主要限于$DSH_HOME/github-sync/、下载/删除会话与附件时的$DSH_HOME/sessions/与$DSH_HOME/attachments/，以及（开启后）当前工作区。 - 不启动子进程、不执行外部命令、不访问 GitHub 以外域名——上述不变量由仓库内
tools/audit-safety.mjs做发布前静态检查。
安装前建议：插件以当前 DSH 宿主进程权限运行，安装前应自行查看源码与 MIT 许可证，确认令牌权限范围与仓的私密性符合你的安全要求。
其它限制：附件随会话引用上传，单文件超过 25MB 会跳过并在预览告警；只处理 version: 4 的会话格式。Git 历史会累积 blob，长期可用 git filter-repo 或重建空仓等方式回收空间；README 建议「一个项目一个仓」便于清理。
结尾¶
dsh-github-sync 用你自己的私有 GitHub 仓补上 DSH 本地版没有云端存储的空缺：手动上传/下载、原子提交、跨机改写 cwd 并登记会话，让多台设备在同一条对话上接力。社区目录页：https://www.skillhub.cn/plugins/mount9527/dsh-github-sync；源码与完整说明：https://github.com/mount9527/dsh-github-sync。
