前言¶

DeepSeek Harness（dsh）发布节奏快，候选版本也常见。决定能否正常启动的配置往往集中在少数文件里：settings.yaml、profile 的 patch 与 manifest、agent preset、AGENTS.md 等。cordis.patch.yml 里错一行，就可能导致 dsh 起不来。手工改配置、直接 npm 升版本，缺少「可验证的快照」和「失败可恢复」的路径，运维成本会集中在一次误操作上。

下面介绍社区插件 dsh-plugin-safe-upgrade（维护者 MovieMaker93，分类 admin-security）。它在 $DSH_HOME 内用 git 记录关键配置的变更历史，在每次成功启动后标记 known-good 配置，并通过 /upgrade、/rollback 与可选的 systemd 启动守卫，把升级做成「先校验、后切换、失败自动回滚」的流程。插件不是 DeepSeek 或 dsh 官方出品，仅使用 dsh 公开的插件接口；问题应在本仓库 issues 反馈，而非 dsh 主项目。

这是什么¶

dsh-plugin-safe-upgrade 面向以 systemd 服务方式运行、且通过 npm 安装 @deepseek-ai/dsh 的 Linux 环境，提供：

• 安全相关的配置历史（含密钥写入 git 前的拒绝策略）；
• 带空闲检测与多阶段校验的 guarded upgrade；
• 启动失败或 Web UI 异常时的 automatic rollback；
• Web UI 命令与 dsh-safe-upgrade CLI 两种入口。

当前 package 版本为 0.4.0（MIT）。SkillHub 目录页：dsh-plugin-safe-upgrade；源码与说明：GitHub - MovieMaker93/dsh-plugin-safe-upgrade。

核心功能¶

配置历史（Config history）¶

对影响 dsh 能否启动的文件（settings.yaml、profile patch/manifest、agent preset、AGENTS.md 等）的每次编辑，会在 $DSH_HOME 下的 git 仓库中延迟数秒自动提交；后续新建的 profile 与 preset 目录也会被纳入跟踪。Session、credentials、cache、node_modules 等不会被跟踪；若文件内容包含字面量密钥，secret guard 会在写入 git 之前直接拒绝。

Known-good 启动标记¶

每次 dsh 启动后，插件检查插件加载器中的失败插件、未完成加载的插件以及损坏的 preset。若启动健康，会为当前配置打 good-<time> 标签，并记录当时运行的 dsh 版本（每个配置与版本组合只标记一次）。

/upgrade：旁路安装与自动回滚¶

升级流程不在最后一刻之前动正在运行的服务：新版本安装到旁路目录，在 $DSH_HOME 的临时副本中对每个 profile 执行 dsh --dump-config 校验，再次确认空闲后停止 dsh、交换 install 目录并启动。若新版本无法恢复健康，会自动恢复先前的 install 与配置。停机时间主要是目录交换加一次启动（README 描述为几秒量级）。

升级前会用运行中版本与目标版本分别打开每一份已存 session 的副本；若「今天能打开的 session」在升级后将无法打开，则中止升级。若 session 依赖的 agent preset 在新版 dsh 中已不存在（例如 0.1.7 不再读取的 ~/.dsh/.agent-presets），插件会在 profile patch 中补充 legacy preset 副本以便继续对话。回滚时若存在「仅在新版上继续过的 session」，会给出警告。

新版启动后，还会在 headless Chromium 中加载真实 Web UI；若出现 “Failed to load plugins” 等浏览器侧失败，升级会回滚——用于捕获服务端日志里看不到的客户端问题。

README 说明：dsh --dump-config 并非只读（0.1.7 会改写 cordis.yml 等），因此校验始终在配置副本上进行，live $DSH_HOME 不会被 dry run 或被拒绝的 upgrade 写入。

警告策略（failOnWarnings）¶

升级、dry run、回滚会报告在新版本中已无匹配项的 patch，以及未导致插件失败但已记录的错误。开启 failOnWarnings 可将这些视为失败：dry run 失败、升级在动 dsh 前停止（配置警告）或回滚（启动警告）、手动回滚会被撤销；自动恢复不会因警告而被撤销。

/rollback¶

可回到任意 known-good 启动或近期配置快照。目标配置在停止 dsh 前会先校验；若标签对应另一 dsh 版本且该版本的 install 副本仍在，会一并换回对应 install。

可选：Boot guard 与 Telegram¶

Boot guard 通过 systemd drop-in 在每次启动前校验配置；若连续三次启动失败，会恢复本机可回退的最新 known-good 配置并再次启动 dsh（也覆盖手工改坏配置的情况）。同一账户运行，且 15 分钟内最多执行一次，避免循环。升级与回滚依赖 systemd；配置历史与健康检查在无 systemd 时仍可用。

可选 Telegram 通知覆盖每次 upgrade、rollback 与 recovery。

环境要求¶

• dsh 0.1.5 或更高，通过 npm 安装（node_modules 中含 @deepseek-ai/dsh），以 systemd 服务（系统或用户单元）运行。
• Linux，需 git、npm、cp、systemd-run；Node 22+。
• 可选：Chromium 或 Chrome 用于 Web UI 检查；缺失时跳过并以 warning 报告。
• Session 检查会复制 $DSH_HOME/sessions，需相邻磁盘有足够空间。
• 插件自身无额外 npm 依赖。

安装与启用¶

插件以 dsh 进程同一账户运行；安装前请阅读源码与 MIT 许可证，确认符合你的安全策略。

README 给出的安装步骤如下：

git clone https://github.com/MovieMaker93/dsh-plugin-safe-upgrade ~/.dsh/plugins/safe-upgrade
dsh plugin --profile web add link:$HOME/.dsh/plugins/safe-upgrade
sudo systemctl restart dsh          # or whatever your unit is called

dsh plugin add 会将包注册为 profile bundle，插入 safe-upgrade 行。首次启动后插件会启动配置历史，并将本次启动标记为 good。

可选启动守卫（以拥有该 systemd unit 的用户执行一次）：

node ~/.dsh/plugins/safe-upgrade/bin/dsh-safe-upgrade.mjs install-guard --unit dsh

典型用法¶

Web UI¶

在 Web UI 中输入命令并回车：

任务结束时会通过浏览器通知（若已授权）或页内 toast 提示。

命令行¶

dsh-safe-upgrade status
dsh-safe-upgrade upgrade latest --dry-run
dsh-safe-upgrade upgrade 0.1.7-rc.2
dsh-safe-upgrade rollback good-20260928-190522
dsh-safe-upgrade check-ui        # does the web UI actually load right now?
dsh-safe-upgrade sessions        # which sessions fail to open, and which can't be continued
dsh-safe-upgrade sessions --fix-presets   # add legacy presets for sessions whose preset is gone
dsh-safe-upgrade install-guard --unit dsh [--remove]

sessions 在 $DSH_HOME/sessions 的副本上运行，不会修改 live session。--fix-presets 会用当前运行的 dsh 合成 legacy preset 后再写入 profile 的 cordis.patch.yml；若 profile 配置了 patchReload: live 可无需重启即生效（详见 README 截断后的说明）。

升级整体流程可参考 README 中的 supervisor 示意图：host 侧检查空闲 → systemd-run 拉起 supervisor → 快照、旁路安装、dump-config、session 对比 → 停止并交换 install → 启动、HTTP 与健康标记 → headless Web UI → 失败则恢复 install.prev 与 pre-upgrade 配置。

适用场景与注意¶

适合：长期用 systemd 托管 dsh、需要频繁跟进 latest/next、又希望配置与版本变更可审计、可回退的 self-hosted 或单机运维场景。

注意：

• 升级与回滚必须 systemd；仅想要配置 git 历史与健康检查时，可不依赖完整升级路径。
• 插件与 dsh 同权限访问 $DSH_HOME；安装前请自行审查 GitHub 仓库 行为与依赖面。
• 社区插件目录 SkillHub 与 DeepSeek / 幻方无官方从属关系；DSH 生态强调「一切皆插件」，本插件是其中的 admin-security 类补充，而非官方应用商店条目。

结尾¶

dsh-plugin-safe-upgrade 把「改配置」和「升版本」从一次性赌博，变成有历史、有校验、有 known-good 标签与自动回滚的操作链。若你的 dsh 已按 README 要求跑在 systemd 上，可按上文命令安装，先用 upgrade latest --dry-run 与 /rollback 列表熟悉行为，再在生产环境执行真实升级。

• 目录页：https://www.skillhub.cn/plugins/MovieMaker93/dsh-plugin-safe-upgrade
• GitHub：https://github.com/MovieMaker93/dsh-plugin-safe-upgrade