DeepSeek Harness简称dsh，是一套插件化架构的开源Agent运行框架，目前处于开发者预览阶段，项目迭代节奏很快。新版本除新增功能特性之外，还会修复安全缺陷，部分迭代版本会存在不向前兼容的破坏性改动。大量使用者升级时很容易混淆本体程序和插件扩展两套独立体系，误以为更新本体程序，插件就会自动同步升级，最终出现Web界面报错、插件加载失败、会话异常、功能不可用等各类故障。
Harness更新分为两个完全独立层级：本体程序负责Web界面、核心调度逻辑、CLI命令行、基础运行时；各类插件属于扩展组件，用来新增工具调用、数据处理、第三方对接能力。本体更新不会自动更新插件，更新插件也不会改动本体程序，两者拥有完全独立的发布周期，升级操作必须分开执行。本文完整梳理更新前准备、本体三种升级方案、插件更新手段、更新后校验流程，附带全套可直接复制执行的命令，整理高频故障与解决办法，降低版本迭代带来会话、配置丢失风险。
一、更新前准备：版本记录、会话备份、环境校验
正式执行更新操作之前，不能直接执行升级命令。预览版软件升级存在异常风险，网络中断、版本不兼容、依赖出错，都有可能破坏本地会话记录、自定义配置。提前做好准备，一旦升级出错拥有回退修复的能力，准备工作包含记录版本、备份会话数据、校验本地运行环境三个部分。
阿里云部署AI Agent：OpenClaw/Hermes Agent全网最简单，只需两步，详情👉访问阿里云OpenClaw/Hermes一键部署专题页面了解。
Token Plan Token 最便宜/支持多模型切换：👉访问订阅阿里云百炼Token Plan AI大模型服务 。支持多模型切换，用于多模态模型灵活调用，实现多模型、多工具、多场景下的额度共享与统一管理，兼顾灵活性、稳定性与安全性，大幅降低企业使用大模型的门槛与成本。
1、记录当前运行版本
升级前先记录本地版本号，升级结束之后用来对比确认升级真正生效；遇到新版本存在bug，也可以依据版本信息执行降级操作。
# npm全局安装查看版本
dsh --version
# npx临时运行模式查看版本
npx @deepseek-ai/dsh --version
# 查看线上官方最新发布版本号，用来做对照
npm view @deepseek-ai/dsh version
2、会话与配置数据备份
所有用户会话数据默认保存在~/.dsh/sessions目录，是日常使用最重要的数据。升级前复制整个目录做备份。
Linux / macOS备份命令：
cp -r ~/.dsh/sessions ~/.dsh-sessions-backup
如果本地修改过自定义profile配置、密钥配置文件，建议对整个.dsh目录完整备份，最大限度规避丢失风险。
cp -r ~/.dsh ~/.dsh-full-backup
注意：Windows系统用户，
.dsh目录存放在用户家目录，可通过%USERPROFILE%\.dsh访问，可手动复制文件夹完成备份。不要轻易直接删除整个.dsh目录，目录内存放会话、密钥、profile全部配置，删除会造成全部本地数据丢失，仅在已经完整备份之后才可以做重置操作。
3、校验本地运行环境
第一确认磁盘剩余存储空间充足，升级本体、拉取插件会下载大量依赖包，磁盘空间不足会直接中断更新；第二保证网络稳定，升级全程终端窗口保持打开，中途关闭终端、切断网络，会造成依赖文件残缺损坏；第三校验Node运行环境，dsh对Node版本有硬性最低要求，如果版本过低，升级完成后程序直接无法启动。
# 校验node版本，要求>=v22.19
node -v
如果输出版本低于v22.19，需要升级Node运行环境，否则后续全部升级命令会报错无法执行。
二、本体程序三种升级方式，匹配对应安装来源
本体升级方案取决于最开始的安装方式，不同安装途径命令不可混用。npx临时运行模式执行npm全局更新不会生效；源码构建环境执行npm包更新命令也不会产生效果，必须匹配对应方案。
方式一：npx临时运行模式（无需全局安装）
npx模式不会在系统写入全局程序包，每次执行启动命令会远程拉取npm仓库包，理论不需要手动执行升级，直接运行启动命令就会使用最新版本。
npx @deepseek-ai/dsh web
部分场景npm本地缓存会保留旧版本，反复运行启动命令依旧运行旧代码，这时需要清理npm缓存，强制重新拉取新版本包。
# 清理npm缓存
npm cache clean --force
rm -rf ~/.npm/_npx
# 重新启动web服务，强制拉取最新本体
npx @deepseek-ai/dsh@latest web
Windows平台可以执行npm config get cache获取缓存实际路径，手动删除_npx缓存文件夹。
方式二：npm全局安装模式
当初执行npm install -g @deepseek-ai/dsh全局安装，可以直接使用npm更新命令升级本体包。
npm update -g @deepseek-ai/dsh
更新完成立刻校验版本号确认升级生效：
dsh --version
Linux/macOS经常出现EACCES权限报错，代表npm全局目录缺少写入权限，可以增加sudo管理员权限执行：
sudo npm update -g @deepseek-ai/dsh
权限报错另一种解决思路：放弃全局安装，改用npx模式运行，规避系统目录读写权限限制。更新完成版本号没有变化，可以更换npm镜像源，解决网络下载异常。
方式三：源码本地构建部署模式
如果从GitHub仓库git clone下载源码，本地编译构建运行dsh，不能使用npm更新包命令。需要进入源码本地存放目录，拉取远端最新源代码，重新安装依赖并且执行构建脚本。
首先切换源码本地目录，示例路径~/dev/deepseek‑harness替换为你的真实存放路径。
cd ~/dev/deepseek‑harness
如果你在本地修改过源码，直接git pull会产生代码冲突，先用git stash临时保存本地自定义修改，避免改动直接丢失。
# 临时保存本地自定义代码修改
git stash
# 拉取远程仓库最新源代码
git pull
拉取代码之后必须重新安装依赖，执行build构建，这一步不能省略，只拿到源码文本，没有编译产物，Web服务会直接启动失败。
npm install
npm run build
# 构建完成之后启动web服务
npm run dsh web
更新确认没有问题之后，恢复之前本地的自定义修改：
git stash pop
三、插件独立更新：可视化插件市场、命令行批量更新
本体升级完成不等于全部更新完毕，插件需要独立升级。本体更新不会同步更新插件，新版本本体可能弃用旧版插件接口，不更新插件就会出现功能异常。更新插件前提：环境已经部署DSH Plugin Hub组件，为插件市场提供基础依赖。
方式一：Web插件市场可视化更新（优先推荐）
图形界面可以直观查看插件新版本，观察更新进度，核对插件来源，适合普通使用者。
- 启动dsh web服务，打开浏览器访问WebUI页面，进入设置页面，打开插件中心，切换到已安装插件列表；
- 插件行末尾出现更新按钮，就代表该插件存在新版本；
- 点击更新，核对插件包名称与来源，确认之后等待下载安装进度；
- 更新全部结束，刷新Web页面，新版本插件才正式加载生效；
- 多个插件需要升级，分批逐个点击更新。
更新按钮置灰，代表本地已经是线上最新版本；浏览器缓存异常也会造成按钮置灰，清除浏览器缓存，刷新插件市场页面即可恢复。
方式二：命令行更新插件，适合脚本自动化运维
不方便打开WebUI界面、服务器无图形环境，使用命令行做覆盖安装，直接拉取线上最新版本实现插件升级。
更新单个指定插件包：
dsh plugin --profile web add <插件包名>
该命令识别本地已安装插件，直接覆盖升级至最新版本。
单条命令批量更新web环境全部已安装插件：
dsh plugin --profile web update
注意：headless无后台模式的插件，需要单独指定profile参数更新，两套环境插件互相独立，不会同步更新。
dsh plugin --profile headless update
插件升级出现异常，可以先移除故障插件，之后重新覆盖安装：
dsh plugin --profile web remove <插件包名>
dsh plugin --profile web add <插件包名>
四、更新完成之后完整校验，规避假更新现象
很多使用者执行完升级命令直接开始使用，由于缓存、下载失败，程序依旧运行旧版本，也就是“假更新”。更新结束需要做四项校验，确认本体、Web界面、插件、系统日志全部正常。
校验本体版本号，和升级之前记录的版本做对比
dsh --version npm view @deepseek‑ai/dsh version校验WebUI界面正常打开，无白屏、弹窗报错
默认访问地址http://127.0.0.1:3080，端口被占用可以手动指定端口启动服务：dsh web --port 8080进入插件市场已安装列表，核对插件版本已经刷新，无红色异常标记。
查看WebUI系统通知、启动日志，确认不存在update相关报错。
五、高频故障现象、根因以及对应处理方案
| 故障现象 | 产生原因 | 处理操作 |
|---|---|---|
| 执行升级本体，版本号完全没有变化 | npx模式存在npm旧缓存残留 | 执行npm cache clean --force && rm -rf ~/.npm/_npx清理缓存，重新启动web |
| npm update‑g抛出EACCES权限错误 | npm全局目录缺少写入权限 | sudo npm update -g @deepseek‑ai/dsh；改用npx模式运行本体 |
| 更新下载依赖长时间超时失败 | npm源网络访问缓慢 | 更换npm镜像源，重新执行更新指令 |
| git pull报告代码冲突 | 本地源码仓库做过自定义修改 | git stash保存改动，执行git pull，更新后执行git stash pop恢复本地修改 |
| 插件市场更新按钮灰色无法点击 | 已是最新版本；浏览器缓存干扰 | 无需更新；清除浏览器缓存，刷新页面 |
| 插件更新完成，插件功能异常不可用 | 新版本本体与旧插件存在版本不兼容 | 重启dsh web，卸载故障插件后重新安装npm来源插件包 |
| 更新中途终端关闭，升级进程中断 | 网络断开、终端被意外关闭 | 分开重新执行本体、插件更新命令，不要一次性批量操作 |
| 无法确认升级是否真正生效 | 没有对比本地版本与线上版本 | dsh --version查看本地，npm view @deepseek‑ai/dsh version查看线上版本做对比 |
补充隐性问题：升级Web页面空白，优先关闭代理工具，清除浏览器缓存更换浏览器访问；更新之后会话打不开，优先使用前期备份的sessions目录恢复数据，或者使用会话检测插件修复损坏会话文件。
六、更新实操常见疑问解答
Q1：更新本体程序，旧会话记录会不会丢失？
正常升级本体不会修改会话存储目录。但是该项目处于开发者预览，存在破坏性变更风险，每一次升级前务必定执行会话备份命令，不能跳过备份直接升级。
cp -r ~/.dsh/sessions ~/.dsh‑sessions‑backup
Q2：源码模式git pull拉取代码，忘记执行build构建会发生什么？
git pull只同步源代码文本，缺少编译构建产物，直接启动web会报错，Web界面无法打开，build编译步骤不可省略。
Q3：是不是每一个新版本都要立刻升级？
dsh处于开发者预览阶段，如果当前版本运行稳定，没有遇到bug，可以不必第一时间升级；遇到已知缺陷或者需要新版本功能，才执行升级。升级前查阅官方发布说明，确认新版本是否有破坏性改动，评估插件兼容风险。
Q4：npx模式是否需要手动卸载旧版本？
npx不会做系统级安装，不需要卸载程序包，清理npm缓存文件夹即可清除旧版本缓存。
Q5：升级后会话全部消失怎么办？
预览版本部分大版本迭代会修改会话存储数据库格式，不支持自动迁移。优先使用升级前备份的~/.dsh‑sessions‑backup备份目录做数据恢复。没有备份，需要回退旧版本手动导出会话，再升级新版本导入。
七、完整更新流程总结
整套升级流程可以概括为：升级前做好备份记录版本 → 根据当初安装方式升级本体 → 独立升级插件（可视化优先，命令行用于自动化） → 更新完成执行全套版本、界面、插件、日志校验。
绝大多数升级故障根源，就是混淆本体程序和插件两套独立更新逻辑，执行一次本体升级之后，误以为插件同步完成，忽略插件单独更新步骤，最终出现各类功能异常。
npx临时运行模式更新负担最低，每次启动自动拉新版本，只需要留意npm缓存造成版本滞留；npm全局安装用户定期执行全局更新命令，注意权限报错；源码构建用户，git拉取代码之后必须完成npm install与build编译，不可跳过。插件更新优先Web插件市场，自动化脚本、服务器环境使用dsh plugin系列命令。
升级过程一旦出现异常，优先查看终端控制台输出报错信息，绝大多数问题提示会直接打印在终端。尽量不要直接删除.dsh整个目录，该目录存储全部会话、密钥、profile配置，删除会全部丢失，只有已经完整备份前提下，才可以做目录重置。
升级校验全部通过、Web界面正常打开、历史会话正常加载、插件功能恢复正常，代表完整升级工作完成。后续新版本迭代，可以复用整套操作流程，规避版本迭代带来的数据丢失、功能异常风险。
