插件同步
English | 中文
你的插件,跟着你走。换机器也不用再重找插件。
插件的清单、版本和配置,存在你自己的 GitHub 私有仓库里——不是谁的云。你改插件,它自动备份;换了机器,它拉下清单、列出差异,你勾选、点一次就装回来。本地目录安装的插件连源码一起还原,密钥类配置一步都不离开本机,每个文件落地前先验校验和。
截图使用虚构示例数据(octocat、workstation),不含任何真实账号或机器信息。
做什么
- 清单:所有非安装自带的 bundle —— 名称、版本、启用状态、安装来源、声明的 row id。
- 来源:每个插件到底从哪来。本地目录优先读
.git的 origin,其次读包自己的repository字段,monorepo 会一直显示到子目录;查不到的标「来源未知」,不猜。 - 配置项:这些 row 在 profile 里的 override 层。离开本机前,令牌形态的值统一替换成
`;apiKeyEnv` 这类「指向密钥的环境变量名」原样保留,因为它本身不是密钥。 - 源码备份:从本地目录安装(
link:/file:)的插件没有 registry 版本可重装。它的源码以真实文件提交进同一个私有仓库,一次推送一个提交,在 GitHub 上能直接读、能看 diff、能搜索。还原时下载、校验 SHA-256、写盘,再 link 安装。 - 还原:缺失安装、版本替换、写入配置、切换启用状态,分组勾选。你没点,它不动;每条结果如实回报宿主真正做了什么。
- 更新检查:来源发布了比本机新的版本时给提示;npm 装的可以在这里一键更新,本地目录的留给你自己处理。
- 清理:每行一个「同步」开关(只影响这台机器);差异卡片里的「清理备份」可以删掉清单条目,也可以连带删掉仓库里的源码文件。
- 推送:插件变更后自动(30 秒防抖)+ 手动。
- 拉取:定时 + 手动;只算差异,绝不自己动手。
安装
本仓库本身就是可安装的 bundle(package.json 声明了 dsh.bundle)。用插件管理器指向这个目录或 GitHub 仓库,然后刷新页面:设置 → 插件同步。
dsh plugin --profile desktop add /绝对路径/plugin-sync
要求 DeepSeek Harness 0.2.x(settings.section、ctx.locale、ctx.pluginManager、ctx.configEditor、ctx.credentials 契约)。
登录
页面把两步都做成预填链接,不用记参数。默认数据仓库叫 dsh-plugin-sync-data:dsh-plugin-sync 这个名字留给插件本身的公开仓库,两个不撞名。
- ① 建私有仓库 →
github.com/new?name=dsh-plugin-sync-data&visibility=private,点 Create(空仓库,不要勾 README)。 - ② 生成令牌(已预填) → 细粒度令牌表单打开时,名称、描述、90 天有效期、
Contents: write都已填好。Repository access 选 Only select repositories 勾上刚建的仓库,Generate,复制github_pat_…。 - 粘进第一个输入框,点「从我的仓库里选」(令牌只用于这一次列仓库,不落盘),挑一个仓库,再点「校验并保存」——这时才真正登录并存令牌。登录后先拉取,不会把本机状态推上去:新机器只读,避免用空清单或旧版本覆盖共享 manifest。要让仓库第一次有内容,登录后点一次「推送」。
登录后,「更换仓库」→「从我的仓库里选」会列出令牌可写的全部仓库,选中后直接用已存的令牌复核可见性与写权限,不用重贴。一个 profile 只有一个活动仓库;两份互不干扰的存储 = 两个 DSH profile。
选到一个不是同步仓库的仓库会被拦住并确认:非空、没有 manifest 的仓库是别人的项目,页面会列出其中几个文件名,你确认后才写;同名文件但格式不对,直接拒绝。
经典令牌(repo scope)也能用,但权限更宽,不推荐。插件不读 git 凭据助手,也不读钥匙串。
仓库必须是私有的:配置会离开本机,公开仓库等于公布。公开仓库在登录时和每次推送前都会被拒,除非你勾选红色的「⚠ 允许公开仓库」。
仓库里有什么
根目录的 dsh-plugin-sync.json:
{
"schema": 1,
"updatedAt": "2026-11-05T05:10:00.000Z",
"devices": {
"3f2a91c0d4e8": { "name": "workstation", "updatedAt": "…" }
},
"plugins": {
"dsh-searxng-search": {
"version": "0.5.0",
"enabled": true,
"source": "local:dsh-searxng-search",
"repository": "https://github.com/octocat/dsh-searxng-search",
"repositoryFrom": "git-remote",
"config": { "searxng-search": { "proxy": "http://127.0.0.1:7890" } },
"snapshot": {
"format": "tree",
"path": "snapshots/dsh-searxng-search/0.5.0",
"commit": "9c33e2c…",
"files": 18,
"bytes": 292546,
"sha256": "…"
},
"redacted": 1,
"updatedAt": "…",
"by": "3f2a91c0d4e8"
}
}
}
本地插件的源码按真实文件放在 snapshots/<名字>/<版本>/ 下,通过 Git Data API 提交,所以一次推送就是一个提交,仓库保持可读:能直接在 GitHub 上翻源码、看两次备份之间的 diff、用仓库搜索。文件按内容寻址,没变的文件不重复上传;被删掉的文件在同一个提交里删除;可执行位保留。
收哪些文件:package.json 的 files 白名单(没写就全收),外加 package.json、cordis.patch.yml、locale/、assets/、scripts/、图标和 README。node_modules、.git、.env*、日志、软链永远不收。单文件超过 1 MiB 或整份超过 maxSnapshotBytes,整份拒绝,不会上传半份。
合并
两台机器写同一个文件。每次推送先读当前版本,把本机条目合进去,再用读到的版本号写回;返回 409 说明别人先写了,就重读再合并(最多三次)。本机没有的远端条目原样保留——这是并集,空机器推上去不会删掉任何东西。
配置
| 字段 | 默认 | 含义 |
|---|---|---|
repo |
空 | 私有仓库的 owner/name。 |
apiBase |
https://api.github.com |
GitHub Enterprise 时修改。 |
manifestPath |
dsh-plugin-sync.json |
清单文件的位置。 |
snapshotsPath |
snapshots |
源码备份的位置。 |
snapshotFormat |
tree |
tree 存真实文件;json 退回单文件 base64 快照。 |
deviceName |
主机名 | 写进清单的设备名。 |
deviceId |
自动派生 | 稳定身份,为空时按主机、平台、home 派生。 |
autoPush |
true |
插件变更后自动推送,30 秒防抖。 |
autoPull |
true |
定时拉取清单。 |
intervalMinutes |
15 |
定时周期,限制在 1–1440。 |
includeSnapshots |
true |
上传本地插件的源码。 |
maxSnapshotBytes |
4194304 |
单个插件的源码总量上限。 |
maxManifestBytes |
2097152 |
清单上限,超过直接拒绝。 |
excludedRows |
[] |
这台机器永不发布的 row id。 |
excludedPlugins |
[] |
这台机器不推送、也不参与差异的插件。 |
allowPublicRepo |
false |
允许公开的同步仓库。 |
页面里改的设置存在 ~/.dsh-plugin-sync/settings.json(在 profile 之外,不重写任何 profile 文件);cordis.patch.yml 里的 row 配置提供默认值。
安全说明
- 只接受回环浏览器的请求。
/state和/api要求自定义头x-dsh-plugin-sync: 1(它触发 CORS 预检,而路由从不回应预检,别的源发不出这个请求),对端必须是127.0.0.1/::1,Origin不在回环或Sec-Fetch-Site为cross-site一律拒绝。curl仍要带头,网页加不了这个头。这两个路由不在 Harness 会话登录之后:请让 Harness 只监听回环。 - 令牌绑定验证它的主机。 登录用 HTTPS(仅回环允许明文 HTTP)调
GET /user,并把 base 和令牌一起写进凭据记录;之后所有请求都用这个 base,改设置不可能把令牌送去别处,换 API 主机必须重贴令牌。 - 机密不外发。 脱敏分两层:敏感形态的键名 和 敏感形态的值(
ghp_…、github_pat_…、sk-…、xox…、AKIA…、PEM 私钥)都变成`;apiKeyEnv` 这类引用保留,因为它只是指向密钥的名字。 - 源码也要过扫描。 源码里出现令牌形态的值,整份拒绝并点名文件,粘进插件的 token 不可能进仓库。
- 清单不含本机路径。 本地插件的绝对路径被替换成
local:,还原靠源码备份。仓库路径(manifestPath、snapshotsPath、快照自身路径)会校验..、绝对路径和反斜杠,还原的每个文件落盘前都验校验和与路径。 - 来源不携带凭据。
https://user:token@github.com/o/r.git这类 remote 会被规范化成干净的 URL 再存储。 - 只按预期来源安装。 应用只接受
github:spec、https://github.com/…spec,或计划生成的那个精确name@version;其它一律拒绝(INSTALL_REFUSED/SOURCE_MISSING)。更新固定到探测到的具体版本。 - 公开仓库被拒两次:登录时一次,每次推送前再一次。唯一的口子是红色的「⚠ 允许公开仓库」:勾选会展开确认,写明清单、脱敏后的配置和源码都会公开,且推上去的提交留在 Git 历史里;宿主还会校验请求必须带
acknowledgePublic(ACK_REQUIRED)才肯保存。同步仓库必须保持私有。 - 令牌存在凭据记录
dsh-plugin-sync/github(存储文件权限 0600),插件自己的设置文件同样是 0600。没有任何路由会返回令牌,插件也不读 git 凭据或钥匙串。
存储与发布:调研结论
DSH 把 GitHub 来源装成仓库的根包(installBundle('github:owner/repo#v1.0.0'),pnpm 之前先用 git ls-remote 核对)。pnpm 无法安装 git 仓库的子目录,所以「一个仓库装多个 plugins//…」这条路走不通。
于是拆成两件事:
- 存储(当前版本)——一个私有仓库放清单和源码。多端同步够用,还原是插件自己的活:下载、校验、写到
~/.dsh-plugin-sync/plugins/…,有依赖就先装依赖,再installBundle(那个目录)。 - 发布(下一版)——每个插件一个公开仓库,带
package.json、cordis.patch.yml、v标签和dsh话题。之后任何 Harness 都能用github:owner/repo#v装,不再需要本插件。那是分发,不是同步,所以留成独立动作;市场 PR 仍然手动。
开发
node --check index.js && node --check client.js
node --test test/*.test.js
无构建步骤,无运行时依赖。
许可
MIT —— 见 LICENSE。