前言¶

在多台 Windows 机器或不同 DSH Home 之间开发时，插件版本、主题、模型选项和 home/profile 补丁往往各自漂移：本机装过某次固定提交，另一台仍停留在旧清单，凭据和 NAS 路径混进仓库又会带来安全风险。手工拷贝 node_modules 或整目录复制，既难核对运行版本，也无法在增删插件后让其他电脑一致跟进。

下面介绍社区插件 dsh-environment-sync（维护者 vb2250158，SkillHub 分类为「记忆」）：通过私有或公开 Git 仓库保存插件清单、可移植设置与加密凭据，在 Web 与 Desktop 两种宿主间按固定提交安装与恢复，聊天、附件、运行日志和本机资料库不上传。

这是什么¶

dsh-environment-sync 是开源的 DSH 环境同步与个人插件管理组件（仓库 vb2250158/dsh-environment-sync）。它在管理面板提供「环境同步」能力：把整套 DSH 插件与共享配置纳入 Git 工作流，其他电脑用同一同步密钥拉取并应用。

资料中说明：本 release 需要 DSH 0.2.1-alpha.1 或兼容的 0.2 发行版；更细的兼容说明见仓库内 docs/dsh-0.2-compatibility.md。package.json 当前版本为 0.7.18。

核心功能¶

同步范围与边界¶

• 通过 Git 同步整套 DSH 插件与共享配置；公开、私有插件均在清单中使用固定提交（完整 40 位提交号）。
• 私有环境仓库保存清单、配置和加密凭据；聊天、附件、运行日志和本机资料库不上传。
• Web 与 Desktop 共用插件版本清单、主题、模型等可移植设置；清单中的 profile 标记导出来源，不阻止两种宿主相互导入。实际安装写入明确指定的目标 profile，不复制 node_modules。
• 网络地址、NAS 路径、资料库位置等设备相关设置不进入共享配置；机器专用字段可登记在本机 private-sync.local.yaml。

清单与配置格式¶

• environment.json 格式 2 保存同步范围；旧格式 1 只读迁移。
• config/plugins.json 保存精确版本与来源；原作者和 fork 信息随记录保留。
• 0.7.0 起，Home 下 .agent-presets/<id>/ 可随共享环境上传并恢复（含 agent.cordis.yml、可选 preset.yml、技能与二进制资产等）；environment.json.agentPresets 记录文件、执行权限与明确删除。
• 0.7.1 起，.dsh-agent-presets-sync-baseline.json 区分已受管文件与尚未恢复的远端文件；该基线只留在本机。

凭据与插件元数据¶

• .credentials.yaml 与 plugins/subscriptions/auth.json 共同加密到 credentials.enc.json，使用 AES-256-GCM 和 scrypt。
• 同步密钥保存在本机 private-sync.key，不进入仓库；不能在新电脑上重新生成代替原有密钥，只能从能解密当前快照的机器经安全渠道传递。
• 管理页插件展示名、作用范围与说明来自各插件自带的 catalog.json（字段含 name、scope：session / global、description 等），与 config/plugins.json 中的版本和来源分开维护。

Web 与 Desktop 行为要点¶

• 环境同步客户端在管理面板首次打开时读取完整状态，启动时不预热插件目录；刷新、操作后状态更新与并发状态请求合并仍可用。
• Web 两阶段安装：在冻结锁文件安装完成后，仅启用本次新增且声明 dsh.bundle 的包；已有 bundle 的启停与顺序保留；启用失败会恢复原 profile。
• Desktop 安装与恢复通过官方 pluginManager，不写入源码 link: 覆盖，也不启动 Web Host；安装后不提前启用新包，环境应用后再同步 bundle 选择，完全退出并重新打开后生效。

管理面板日常操作（资料摘要）¶

子目录中的插件可使用形如 github:owner/repository#<40位提交>&path:packages/plugin 或 git+https://... 的 specifier；安装前读取该提交子目录的 package.json 核对包名与版本。

安装与启用¶

资料中的首次安装面向已构建的 Windows DSH 源码环境，需设置 DSH_SOURCE_ROOT。兼容检查使用 DSH 0.1.3-alpha.1 源码接口（上游提交 d347e703908d0406b7a7ef80e3a0e594d86b2215）；本插件不更新或覆盖 DSH 源码。

步骤如下：

1. 克隆本插件的 v0.6.1 发布标签并记录其完整提交（资料原文要求；与 package.json 的 0.7.18 并存，以 README 首次安装段落为准）。
2. Git 须已获得私有环境仓库读取权限。
3. 在 PowerShell 执行 bootstrap（将 <owner>、<private-environment> 换成你的仓库）：

./scripts/bootstrap-environment.ps1 -SourceRoot <DSH源码目录> -Repository https://github.com/<owner>/<private-environment>.git

4. 首次进入「插件 → 环境同步 → 配置」，填写与原电脑相同的同步密钥，点击「拉取并应用」。密钥仅保存在本机 private-sync.key。
5. 保留安装目录中的恢复运行时；本机 Recover DSH.vbs 可在不依赖 DSH 页面时打开恢复窗口。

日常启动：重启电脑后可双击 DSH Home 中的 Start DSH.vbs 启动服务，再打开本机 DSH 页面。

说明：已抓取资料未给出 SkillHub 一键式 dsh plugin add ... 安装命令；请以 README 的 bootstrap 与面板内环境同步流程为准。

典型用法与维护¶

换机或新目录接入¶

经过 bootstrap 与密钥配置后，在新机器上执行「拉取并应用」，即可按共享清单安装固定提交版本的插件并应用可移植配置；NAS、Web Server 等本机项保持目标电脑原有值。

日常协作式同步¶

本机改插件或共享 settings 后使用「上传改动」；其他电脑「检查更新」后「拉取并应用」。资料建议：重复同步应无新提交，可作为同步是否健康的简单信号。

遗留未完成事务（维护窗口）¶

若 profile 中存在 applying、restore-failed 等遗留事务，资料要求不要直接点重试、拉取并应用或上传；应先只读核对 profile、清单、锁文件与进程，再在维护窗口运行接管脚本（备份目录须位于该 DSH Home 的 backups 下）：

node scripts/takeover-stale-transactions.mjs `
  --dsh-home <绝对 DSH Home> `
  --profile <profile> `
  --repository <绝对私库克隆> `
  --backup-directory <DSH Home/backups/本轮目录> `
  --confirm-preserve-current `
  --acknowledge-unverified-installation `
  --confirm-exclusive-maintenance

该入口只备份并移出遗留 journal，不恢复快照、不安装、不上传、不重启；完成后需另行按当前清单走官方安装入口并核对运行版本。

适用场景与注意¶

适合谁：在多台 Windows 电脑或不同 DSH Home 之间需要一致插件清单、主题/模型与加密凭据，又希望用 Git 做版本与冲突管理的 DSH 用户；使用私有环境仓库保存 config/plugins.json 与加密快照的团队或个人。

务必注意：

1. 插件在 DSH 进程权限下运行；安装前应阅读仓库源码与 LICENSE，确认来源与许可。
2. 固定提交必须已推送到远端且稳定可取；仅本地或未从分支头可达的提交会在取包阶段失败，并可能弄脏本机仓库、阻塞下次同步。核对时使用完整提交号。
3. 密钥、解密后的凭据、资料库与会话数据不得提交或出现在日志、分享内容中。
4. 浏览器配套扩展需在浏览器扩展管理页手动「加载已解压的扩展程序」，与插件清单是两回事；扩展更新需重新加载扩展并刷新已打开页面。
5. 首次接入不会卸载清单之外的已有插件；磁盘版本正确不等于页面已生效，需重启并核对运行版本。
6. 仓库内未提交的外部改动会被保留并阻止覆盖；冲突按文件选择整份版本，不要随意 reset / clean。

结尾¶

dsh-environment-sync 把 DSH 的插件与可移植环境收成可 Git 协作的清单与加密凭据，区分本机专用路径与会话数据，并在 Web/Desktop 间按固定提交安装与恢复。目录页与源码：

• SkillHub：vb2250158/dsh-environment-sync
• GitHub：https://github.com/vb2250158/dsh-environment-sync