智能体开发中，频繁更新 DeepSeek Harness (DSH) 容易引入配置错误或依赖冲突，直接升级可能导致服务中断。dsh-safe-updater 通过隔离环境验证、配置校验和健康检查，确保升级过程可回滚。
该插件由 lucifer726 维护，用于从 npm 获取版本，克隆 profile 到隔离的 DSH_HOME，安装依赖，验证配置，启动临时 Web 服务器，并允许受控切换。若健康检查失败，会自动回滚到上一版本。
安装与默认配置¶
安装插件需要指定 profile 名称。下面以 web profile 为例：
dsh plugin --profile web add dsh-safe-updater
安装后，插件会插入默认配置，默认模式为 notify，不会静默替换正在运行的 Harness：
- insert:
- id: safe-updater
name: dsh-safe-updater
config:
mode: notify
channel: latest
profile: web
checkIntervalMs: 21600000
checkOnStart: true
核心模式¶
插件提供三种模式，通过配置文件或命令行覆盖 mode 字段来切换：
-
notify
检查并记录是否有新版本。不执行安装或重启操作。这是默认模式。 -
stage
克隆 profile，执行依赖安装、配置组装和 HTTP 冒烟测试。不执行实际重启。适合在升级前预演。 -
apply
在stage完成后，请求外部 supervisor 进行版本切换。此模式拒绝在没有外部 supervisor 的环境中运行。
典型用法¶
安装完成后，可以使用以下工具进行操作。
通用状态查看¶
dsh_update_status
该命令读取当前、可用、已暂存和回滚状态。
手动检查与暂存¶
手动触发检查或暂存特定版本：
# 手动检查当前版本
dsh-safe-updater check --current-version 0.1.1-rc.1
# 手动暂存指定版本
dsh-safe-updater stage --version 0.1.1-rc.1 --profile web
回滚操作¶
若暂存的版本健康检查失败，或在运行中需要回滚：
# 执行回滚
dsh-safe-updater rollback
Supervisor 模式¶
要实现自动激活，需在 Web profile 下运行 supervisor：
dsh-safe-updater supervise \
--version 0.1.1-rc.1 \
--profile web \
--host 127.0.0.1 \
--port 3080
当暂存的版本就绪，supervisor 会基于参数启动进程，等待 HTTP 健康检查，成功则提交切换，失败则返回到 previousVersion。
安全与信任模型¶
插件在设计上侧重安全隔离和执行可控：
- 执行安全：注册表版本字符串使用语义版本解析，候选命令使用参数数组（
shell: false），防止命令注入。 - 数据隔离：暂存环境不会复制
.credentials.yaml或其他运行时数据，防止敏感信息泄露。 - 状态存储：状态和锁文件存储在
~/.dsh/safe-updater下，具有受限权限和原子替换机制。 - 防递归：Smoke 模式会禁用更新计时器，防止递归触发暂存。
环境要求与依赖¶
使用该插件需满足以下条件：
- Node 版本：Node.js 版本需大于等于 22。
- Peer Dependencies：
@deepseek-ai/dsh-tools：版本范围>=0.1.1-rc.1 <0.2.0@deepseek-ai/schemastery：版本范围^3
总结¶
dsh-safe-updater 为 DSH 提供了一套严谨的自动化更新机制。它通过隔离环境验证和原子化回滚策略，降低了智能体开发中版本迭代的风险。配合 notify、stage、apply 三种模式，开发者可以根据场景选择检查、预演或自动切换。
