升级 dsh 就是换到新版本：先查当前与最新版本，再按安装方式升级（npx 自动最新、npm update -g、源码 git pull 构建），必要时用 @版本号固定或降级。本文讲清升级与更新的区别、升级步骤、备份与版本管理技巧。
本文转自 DSH Plugin Hub 插件市场
升级 dsh 就是换到新版本：先查当前与最新版本，再按安装方式升级（npx 自动最新、npm update -g、源码 git pull 构建），必要时用 @版本号 固定或降级。本文讲清升级与更新的区别、三种升级方式、升级前备份，以及版本固定与降级的操作。
概览：升级 = 换版本，数据不受影响
升级只换程序本体版本号，~/.dsh 里的配置、会话、插件全部保留。 三条原则（来源）：
- 先查再升：对比当前版本与最新版本；
- 按安装方式升：npx / npm / 源码各有对应命令；
- 版本可管理：需要时可固定或降级。
先看升级路径总览：
| 场景 | 命令 | 说明 |
|---|---|---|
| 升级到最新版（npx） | npx @deepseek-ai/dsh web |
每次运行自动拉最新 |
| 升级到最新版（npm 全局） | npm update -g @deepseek-ai/dsh |
一条命令到位 |
| 升级到最新版（源码） | git pull + 重新构建 |
在仓库目录操作 |
| 固定到指定版本 | npm install -g @deepseek-ai/dsh@<版本号> |
阻止自动升级 |
| 降级到旧版本 | 同上，填旧版本号即可 | 出问题快速回退 |
第一步：检查当前与最新版本
先摸清版本现状再动手，避免盲目升级。 操作步骤：
- 打开终端，查看当前版本：
# 当前版本（全局安装）
dsh --version
# 当前版本（npx 方式）
npx @deepseek-ai/dsh --version
- 查看 npm 上的最新版本：
npm view @deepseek-ai/dsh version
- 对比版本号：当前版本低于最新版本，就需要升级；想了解新旧版本差异，可在 dsh-plugin.org 或官方发布页查看更新日志。
第二步：升级前备份（强烈推荐）
升级前备份数据目录，万一新版本有问题，随时回退。 数据都在 ~/.dsh 下：
# 备份（含配置、会话、插件清单）
cp -r ~/.dsh ~/.dsh.backup-$(date +%Y%m%d)
# 顺便记录当前版本号，方便回退对比
dsh --version > ~/.dsh.version.old
第三步：按安装方式升级
升级命令与安装方式一一对应，选你当初用的那条。 三种方式：
方式一：npx 方式（自动最新）
npx 每次运行都会拉取最新版，无需手动升级。 直接启动即可：
npx @deepseek-ai/dsh web
兜底：若启动的版本仍是旧的，说明缓存残留，强制刷新：
npm cache clean --force
rm -rf ~/.npm/_npx
npx @deepseek-ai/dsh web
方式二：npm 全局安装升级
当初用全局安装的，用 npm update -g 一步升级到最新版。 操作步骤：
# 升级到最新版
npm update -g @deepseek-ai/dsh
# 升级后核对版本
dsh --version
若当初用 pnpm / yarn 装的，用对应命令：
pnpm add -g @deepseek-ai/dsh@latest或yarn global add @deepseek-ai/dsh。
方式三：源码构建升级
当初 git clone 源码构建的，进仓库目录拉取最新代码后重新构建。 操作步骤：
# 进入源码仓库目录
cd ~/dev/deepseek-harness
# 拉取最新代码（本地有改动时先 git stash）
git pull
# 重新安装依赖并构建（与当初安装一致）
npm install
# 按仓库文档执行构建命令，例如 npm run build（以实际为准）
构建完成后重启 dsh web 即用上新版本。
第四步：固定或降级版本
新版不习惯、或插件与新版不兼容时，可以固定/降级版本。 操作步骤：
# 全局安装指定版本（@ 后接版本号）
npm install -g @deepseek-ai/dsh@0.1.0-rc.8
# 核对已回到目标版本
dsh --version
# npx 指定版本启动（临时用旧版验证）
npx @deepseek-ai/dsh@0.1.0-rc.8 web
固定版本后，npm update 不会自动升级，适合需要稳定环境的场景（来源）。想看 npm 上有哪些历史版本，执行 npm view @deepseek-ai/dsh versions。
第五步：升级后验证
升级完确认版本与功能正常，避免「假升级」。 操作步骤：
- 重新执行版本命令，确认版本号已更新；
- 重启 dsh web，确认页面正常打开；
- 打开设置 → 插件市场，确认已装插件正常加载（装过 DSH Plugin Hub 的话，会看到插件列表与版本）；
- 到通知中心与系统日志确认升级过程无报错。
升级失败？常见问题与解决
升级失败先看报错类型，再对症处理。 常见问题清单：
| 问题 | 可能原因 | 解决办法 |
|---|---|---|
| 升级后版本号没变 | 缓存残留 / 命令没执行成功 | 清缓存（npm cache clean --force）后重试，核对输出 |
npm update -g 报 EACCES |
全局目录无写权限 | sudo npm update -g @deepseek-ai/dsh，或改用 npx 方式 |
| 下载超时 | 默认 npm 源慢 | npm config set registry 换镜像后重试 |
git pull 报冲突 |
本地改过源码 | git stash → git pull → git stash pop |
| 升级后插件不工作 | 插件版本与新 dsh 不兼容 | 重启 dsh 后到插件市场重新安装该插件 |
| 升级后想回到旧版 | 新版有行为变化 | 用 npm install -g @deepseek-ai/dsh@<旧版本号> 降级 |
| 不知道有哪些版本可选 | 没查版本列表 | npm view @deepseek-ai/dsh versions 列出全部历史版本 |
| 升级后网页打不开 | 端口占用 / 服务未重启 | 重启 dsh web，检查 127.0.0.1:3080 端口 |
顺带一提：插件版本也要同步管理
升级 dsh 本体后，插件的兼容性也要留意。 在 DSH Plugin Hub 的插件页可查看插件标注的兼容版本；升级后进入设置 → 插件市场，对可更新的插件逐一更新，保持两者版本匹配。
总结速查
一句话：升级前备份并查版本，按安装方式升级（npx 自动 / npm update -g / git pull + 构建），需要稳定就 @版本号 固定，升级后重启验证。 四个提醒：
- 升级前记下旧版本号，出问题方便降级回退；
- npx 方式无需手动升级，只清缓存即可；
- 固定版本用
@版本号：npm install -g @deepseek-ai/dsh@<版本号>； - 升级后插件异常先重启，再考虑重新安装。
常见问题
dsh 升级和更新有什么区别？
日常语境下两者常混用：更新多指同步到最新补丁，升级多指换到更高或指定版本。本质都是换版本号，命令一样：npx 自动最新、npm 全局用 npm update -g、源码 git pull 重新构建。
怎么把 dsh 升级到最新版？
npx 方式每次运行自动拉最新；全局安装执行 npm update -g @deepseek-ai/dsh；源码构建在仓库目录 git pull 后重新构建。升级后重启 dsh web 并核对版本号（dsh --version）。
怎么看 dsh 当前版本和最新版本？
当前版本：dsh --version（全局）或 npx @deepseek-ai/dsh --version；最新版本：npm view @deepseek-ai/dsh version。两者对比即可判断是否需要升级。
怎么固定或降级 dsh 版本？
全局安装指定版本：npm install -g @deepseek-ai/dsh@<版本号>，例如 @0.1.0-rc.8；npx 同理用 npx @deepseek-ai/dsh@<版本号> web。固定后 npm update 不会自动升级，适合追求稳定的环境。
升级 dsh 后插件还能用吗？
通常可以。插件装在 profile 里，$DSH_HOME 数据不变，升级本体不影响已装插件；个别插件对新版本不兼容时，到设置 → 插件市场重新安装该插件即可。
本文转自 DSH Plugin Hub 插件市场，版权归属 DSH Plugin Hub 插件市场。
分类：更新与升级
原文地址：https://dsh-plugin.org/zh/tutorials/upgrade-dsh-guide
来源：dsh CLI README、DeepSeek Harness 官方文档 - Quickstart、dshplugin/dsh-plugin-hub
