前言¶
在 DeepSeek Harness（DSH）里，用 dsh plugin add 装好的第三方插件都落在某个 profile 的 node_modules 下。换一台机器或重装环境时，profile 从零开始，只能凭记忆逐个补装插件名、版本和安装来源。本地目录或已下载的 .tgz 装上的插件，同样没有现成的「整包带走」办法。
dsh-plugin-git-sync（维护者 daoyan2142）把当前 profile 里已安装的第三方插件打成带源码的 .tgz，推到你自己控制的 GitHub 或 Gitee 仓库；在另一台机器上拉取清单、比对版本、校验 SHA-256 后再安装。仓库里存的是包本体而不只是名称列表，目标机不必仍能从原始 registry 拿到同一版本。
这是什么¶
- 名称：
dsh-plugin-git-sync（联网工具类插件） - 版本 / 许可：1.0.0，MIT
- 运行环境：DSH 0.2.x（需
pluginManager的listBundles、installBundle；在 0.2.2-rc.1 上开发与测试）、Node.js ≥ 22.12 - 目录页：skillhub.cn 插件页
- 源码：github.com/daoyan2142/dsh-plugin-git-sync
DSH 生态是「一切皆插件」；社区目录（如 SkillHub）独立于 DeepSeek / 幻方，并非官方应用商店。本插件以当前 DSH 进程权限运行，安装前请自行审阅源码与许可证。
核心功能¶
推送侧（机器 A）¶
- 调用
listBundles()，只处理已安装的第三方插件。 - 解析每个包目录，打成以
package/为根的 tar.gz。 - 对每个 tarball 计算 SHA-256；超过平台单文件上限时拆成
.partNNN分片上传。 - 先上传
sync/packages/*，最后写入sync/manifest.json，避免上传中断时清单里出现尚未存在的包。
拉取侧（机器 B）¶
- 下载
sync/manifest.json，与本地已装版本对比。 - 将结果分为 install（未安装）、same（版本一致）、differ（版本不一致）。
- 下载对应 tarball（或拼接分片），校验 SHA-256 后调用
pluginManager.installBundle(tgz)。 - 安装新 Host 模块后需重启 DSH。
设计上的几个要点¶
- 仓库携带 tarball 与哈希，减轻对远程 registry 的依赖；从本地路径或
.tgz安装的插件，源码会一并打进包。 - 导出是增量且幂等的：每次推送会重写相同路径的包；不会自动删除——在 A 上卸载的插件仍会留在仓库里，需在 B 手动处理，或删除
sync/packages/中对应文件并改manifest.json。 - 插件不会读写仓库中
sync/以外的路径。 - 大文件分片上限：GitHub 单片 768 KiB，Gitee 单片 4 MiB（见 README 说明）。
安装与启用¶
市场（上架后）：
Plugins → Discover → 搜索 "Git Sync" → Install
npm 或 Release 中的 .tgz：
# npm 发布后
dsh plugin --profile web add dsh-plugin-git-sync
# 本地或 Release 的 tarball
dsh plugin --profile web add ./dsh-plugin-git-sync-1.0.0.tgz
包为纯 ESM，无构建步骤、无运行时依赖。安装后需重启 DSH 以加载 Host 模块；通过市场安装时会热挂载。
配置¶
打开 Settings → Git 插件同步，填写下表字段：
| 字段 | 说明 |
|---|---|
| Platform | GitHub 或 Gitee；切换平台会成组切换下方三项，且 GitHub / Gitee 各保留一套设置，互不覆盖 |
| Token (PAT) | 存入 DSH credentials 服务；界面只显示已配置 / 未配置。GitHub 建议 Fine-grained token，Contents: Read and write（限定仓库）；Gitee scope projects |
| Repository | owner/repo、完整 URL 或 git@host:owner/repo.git；仓库须已存在 |
| Branch | 如 main、master；空仓库需先初始化（例如 README）才有可提交分支 |
非敏感配置：<profile>/.git-sync/settings.json。令牌引用名为 GIT_SYNC_GITHUB_TOKEN 或 GIT_SYNC_GITEE_TOKEN，写在 ~/.dsh/.credentials.yaml，不会进入 settings.json 或远端仓库。建议使用私有仓库（README Security 一节）。
示例结构（平台切换时 platform 字段指向当前 UI 所显示的一侧）：
settings.json
platform: "gitee"
profiles:
github: { repo: "…", branch: "main" }
gitee: { repo: "…", branch: "master" }
远端仓库布局：
sync/
├─ manifest.json
└─ packages/
├─ some-plugin-1.2.0.tgz
└─ @scope/name → scope__name-1.0.0.tgz
典型用法¶
机器 A：首次导出¶
- 选择平台，粘贴 Token，点 保存。
- 填写
owner/repo与分支，点 保存设置。 - 点 验证仓库，确认 Token、仓库名与分支可读。
- 点 导出并推送；结果行会显示上传包数量。
机器 B：恢复¶
- 相同平台、仓库、分支；Token 可用同权限的另一枚。
- 点 拉取并对比，查看 install / same / differ 三组。
- 对 install 组点 安装全部缺失插件。
- 对 differ 组按行 覆盖（显示
local → remote）。 - 重启 DSH。
日常更新¶
在 A 上增删或升级插件后再次 导出并推送；在 B 上 拉取并对比，对版本变化的行执行 覆盖。插件不会在导出前读取远端以推断变更，而是以本地当前安装集为准全量写回。
适用场景与注意¶
适合：多台开发机、重装系统后快速对齐同一 DSH profile 的第三方插件；希望把插件集（含非 npm 来源的安装）备份到自建 Git 仓库。
注意：
- 令牌仅授予目标仓库的 contents 写权限即可；仍须信任插件代码与所同步的第三方包内容。
- 卸载不会从远端同步删除，需手动维护
sync/与manifest.json。 - 依赖 DSH 0.2.x 的
pluginManagerAPI；版本不匹配时勿假定行为一致。
结尾¶
dsh-plugin-git-sync 把「已装插件集合」当作可版本化的数据，经 GitHub 或 Gitee 在多机间搬运，并用清单与 SHA-256 约束安装过程。进一步了解可访问 SkillHub 目录页 与 GitHub 仓库（含 中文 README）。
