---
title: "DeepSeek Harness 怎么更新、回退与卸载"
seo_title: "DeepSeek Harness 更新与卸载：DSH 版本、Profile 和插件回退指南"
description: "DSH 更新命令、回退与卸载：默认使用 0.2.0-rc.2，也说明怎样卸载插件、插件被 0.2.0 停用后怎么办；从 0.1.5 升级前先检查 V4 会话、设置导入和模型 protocol 字段。"
canonical: https://52dsh.com/tutorials/dsh-update-uninstall/
authors: ["52DSH 编辑部"]
audience: []
outcomes: []
prerequisites: ["已确认当前 DSH 的启动方式和版本","已备份需要保留的 Profile、配置与 Session"]
difficulty: intermediate
estimated_action_time: null
next_steps: null
published_at: 2026-08-25
updated_at: 2026-10-04
verified_on: 2026-09-30
maintenance_status: community
verification_level: source_reviewed
risk_level: medium
dsh_version: 0.2.0-rc.2
plugin_id: null
tutorial_kind: null
related_plugin_url: null
---

# DeepSeek Harness 怎么更新、回退与卸载

DSH 更新命令、回退与卸载：默认使用 0.2.0-rc.2，也说明怎样卸载插件、插件被 0.2.0 停用后怎么办；从 0.1.5 升级前先检查 V4 会话、设置导入和模型 protocol 字段。

DSH 怎么更新或卸载，先看你要改变哪一层。更新程序、移除插件和清理数据是独立操作；本页按任务给出路径，保留原安装方式和备份后再动手。

| 你要完成的任务 | 从这里开始 | 完成标志 |
|---|---|---|
| 更新 DSH 程序 | [更新 DSH](#更新-dsh) | 实际启动版本正确，配置与最小任务正常 |
| 更新单个插件 | [更新或卸载插件](#更新或卸载插件) | 正确 Profile 的依赖、Bundle 与入口对应变化 |
| 只卸载一个插件 | [只卸载一个插件](#只卸载一个插件) | 依赖和 Bundle 层消失，重启后入口不再加载 |
| 不再使用 DSH 程序 | [卸载程序](#卸载程序) | 对应启动入口移除，所需数据仍可定位 |
| 决定保留哪些数据 | [保留或清理数据](#保留或清理数据) | 备份可恢复，清理范围和凭据撤销分别确认 |

**常用命令速查（2026-09-30 起本站默认 0.2.0-rc.2）：**

- 用 npx 启动：`npx @deepseek-ai/dsh@0.2.0-rc.2 web`
- npm 全局安装的更新：`npm install --global @deepseek-ai/dsh@0.2.0-rc.2`，再用 `dsh --version` 确认
- 只卸载一个插件：`npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web remove <package-name>`（包名换成 Profile 里的实际依赖键）

从 0.1.5 升级先读[升级前必读](#017-alpha1升级前先检查数据与设置)；升级到 0.2.0 后插件不工作，见[已装插件被停用](#升级到-020-后已装插件被停用)。执行前仍按下文确认安装方式并备份。

## 本次维护怎样选择版本

**2026-09-30 核对：npm latest 与 next 均为 `0.2.0-rc.2`，本站默认操作随之改为 `0.2.0-rc.2`；下面的程序与插件命令覆盖该版本。** 按固定源码比对，0.2.0-rc.2 相对 0.1.7-rc.2 **没有新的会话格式或设置迁移**：Settings 导入、V4 格式声明、JSONL 持久化、模型 `protocol` 规则和插件管理器说明都相同。从 0.1.5 系列升级则仍是跨到 0.1.7 以后的版本：会话会迁移为 V4 格式且旧程序不能降级读取，旧 `settings.yaml` 会被改名后逐项导入，模型配置里的 `protocol` 字段会导致官方适配器拒绝加载，插件安装前会检查版本兼容。**从 0.1.5 升级前，先完成[升级前必读](#017-alpha1升级前先检查数据与设置)**，停止写入并保存程序、配置、凭据与数据的匹配备份；升级后产生的数据不保证能合并回旧副本。

| 你的目标 | 从哪里继续 | 执行前确认 |
|---|---|---|
| 全新安装，或按本站默认方式更新 | [确认安装方式](#维护前先确认安装方式)，再进入上方任务入口 | 实际启动副本、Profile、备份与精确版本 |
| 已在使用 0.1.7 系列，升级到 0.2.0 | 按下方命令更新，仍先保存匹配备份 | 没有新的数据迁移；已保存的第三方模型选择可能需要重新选择（官方发行说明：pi-ai 目录更新，部分旧模型 ID 被移除） |
| 已在使用 0.1.5 系列，准备升级 | 先读[升级前必读](#017-alpha1升级前先检查数据与设置)，在隔离副本验收后再切换 | V4 会话、设置导入结果、模型 `protocol` 字段、插件兼容 |
| 暂不升级 | 可继续精确使用原版本，命令见下方历史快照 | 不会自动升级；新文档的操作说明以 0.2.0 为准 |
| 想试用 0.2.1-alpha.1 | 先读[0.2.1-alpha.1：升级前先看插件](#021-alpha1升级前先看插件) | 预发布版，本站默认仍是 0.2.0-rc.2；部分插件会被拒绝或可能出错 |

2026-10-04 核对：npm latest 与 next 均为 `0.2.0-rc.2`，alpha 为 `0.2.1-alpha.1`；下方历史通道表仅代表各自日期。版本依据：[官方 0.2.0-rc.2 Release](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.0-rc.2)、[固定 CLI 说明](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/apps/cli/reference/README.zh.md)与 [npm 通道](https://registry.npmjs.org/-/package/@deepseek-ai%2Fdsh/dist-tags)。

### 0.2.1-alpha.1：升级前先看插件

官方在 2026-10-03 发布了 [0.2.1-alpha.1](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.1-alpha.1)，只在 npm 的 `alpha` 通道。本站默认命令仍是 `0.2.0-rc.2`，不建议把这个预发布版当作日常版本。

- **数据**：相对 0.2.0-rc.2 没有新的会话格式或设置迁移。按固定源码比对，会话格式变更记录没有新增，设置模块、模型配置规则、插件 CLI 和插件兼容判断都相同。
- **插件**：兼容检查规则没变，但版本号变了，范围只写到 0.2.0 的插件会被拒绝。本站 10 月 2 日升级过教程的插件，按各自发布版本声明的范围计算，结果如下。

| 插件（本站固定版本） | 在 0.2.1-alpha.1 上 |
|---|---|
| dsh-TUI 0.12.0、Agent Teams 0.1.22、Vision Toolkit 0.1.46 | 被版本检查拒绝，声明的范围不包含 0.2.1-alpha.1 |
| Better Sidebar 0.24.1 | 通过版本检查；但它声明依赖 `@deepseek-ai/dsh-invariants`，该包在这个版本中已被移除，可能加载出错 |
| Vision Router 2.3.0、Ads 0.1.2、Mnemon 0.5.21、Mobile 0.5.3、Dream Skin 9.29.0、Auto Continue 0.12.1、Share 0.4.4 | 通过版本检查 |

通过版本检查只说明不会被拦截，本站没有在 0.2.1-alpha.1 上运行任何插件。官方发行说明还列出几项会影响插件的变更：移除各包的 `./invariant` 导出，子路径插件不再读取独立的 `package.json`，输入区统计入口拆分为 `activity` 和 `usage`。依赖这些接口的插件需要作者更新。

- **自动化任务**：发行说明写明自动化任务改为 Web 内置能力，旧的实验组合包选择会被自动清理，已有任务保留。
- **新参数**：`web` 新增 `--public-url`，用于反向代理后的对外地址；它不授予信任，浏览器可见的主机名仍要用 `--trusted-host` 指定（[固定 CLI 说明](https://github.com/deepseek-ai/deepseek-harness/blob/5badb15009ae1756c3afe0ae0cef1faafc290ccc/apps/cli/reference/README.zh.md)）。

只想试用时，先备份，再用精确版本新建一个独立 Profile，不要改动日常使用的 `web` Profile：

```bash
npx @deepseek-ai/dsh@0.2.1-alpha.1 --version
npx @deepseek-ai/dsh@0.2.1-alpha.1 --profile alpha-test --from-default-profile web
```

第二条命令从随附的 `web` 模板初始化名为 `alpha-test` 的新 Profile 并启动；这个 Profile 已经存在时要去掉 `--from-default-profile`。新 Profile 的依赖和用户 patch 都是空的，不带原有插件；但它仍位于同一个 `$DSH_HOME` 下，home 级的 `cordis.patch.yml` 对它同样生效，所以备份不能省。

被拒绝或停用的插件按[已装插件被停用](#升级到-020-后已装插件被停用)处理。以上为 2026-10-04 的固定源码与 npm 元数据审阅（commit `5badb15009ae1756c3afe0ae0cef1faafc290ccc`），本站没有运行 0.2.1-alpha.1。

## 维护前先确认安装方式

| 你平时的启动方法 | 如何定位当前副本 | 本次操作范围 |
|---|---|---|
| `npx @deepseek-ai/dsh@版本 web` | 记录原启动命令中的精确版本；未固定时先从原运行日志确认 | 下次调用选定版本，不等于全局安装 |
| 直接 `dsh web`，曾使用 npm 全局安装 | macOS/Linux 用 `command -v dsh`，Windows PowerShell 用 `Get-Command dsh`；再对照 `npm list -g --depth=0 @deepseek-ai/dsh` | 确认是当前 Node/npm 前缀中的全局包后再更新 |
| 仓库里的 `pnpm dsh web` | 在该仓库记录 `git rev-parse HEAD` 与 `git status --short` | 更新源码与构建产物，保留未提交修改 |

直接输入 `dsh` 也可能命中其他管理器或手工二进制。若解析路径与安装记录不符，先确认来源；不要因为命令同名就对另一个副本执行卸载。

## 第一步：记录当前版本和配置

先停止新的任务，并在当前使用的同一个终端中记录：

```bash
dsh --version
dsh --profile web --dump-config
```

下方命令只验证本页目标 CLI；它可能下载并运行该版本，不能用它反推你之前正在运行的版本：

```bash
npx @deepseek-ai/dsh@0.2.0-rc.2 --version
```

`--dump-config` 不启动 Web 应用，但会初始化缺失的 Profile 文件，因此并非零文件副作用。它会显示 Bundle、Profile patch、Home patch 和命令行 patch 的叠加结果，适合在升级前后做差异对比。输出中仍可能包含本机路径或其他部署信息，公开前要脱敏。

同时记录实际使用的 Profile 名称。插件安装、更新和移除都绑定 Profile；在 `web` 中安装的 Bundle，不会因为你对 `headless` 执行更新而自动同步。

## 第二步：备份该保留什么

升级前至少保存以下信息：

- `$DSH_HOME/profiles/<name>/package.json` 与 `pnpm-workspace.yaml` 与实际生成的锁文件；
- Profile 自身和 Home 级的 `cordis.patch.yml`；
- 需要保留的 Session 和工作区变更；
- 当前 DSH 版本、插件包版本、操作系统和验证日期。

`$DSH_HOME/.credentials.yaml`、`.env` 和 Provider Key 属于敏感资产。可以按你的密钥管理制度做加密备份，但不要把它们复制进 Git、普通压缩包、文章附件或公开工单。更新前使用 `git status --short` 检查真实工作区，避免把未提交内容误当成 DSH 版本变化。

## 更新 DSH

先完成上方安装方式确认、停止任务与备份。只更新程序这一层，验证后再更新必要插件。

### npx 方式

停止原 DSH 进程，明确选择本页目标：

```bash
npx @deepseek-ai/dsh@0.2.0-rc.2 --version
npx @deepseek-ai/dsh@0.2.0-rc.2 web
```

npx 可使用匹配的本地依赖，缺少时从 npm 缓存目录准备包；显式版本更便于对照日志。不要把 npm 缓存里有一个新包当作运行中的 Host 已更新。以后评估其他版本时，先核对精确包存在、Release 和数据兼容，再替换版本号。依据：[npm npx](https://docs.npmjs.com/cli/v11/commands/npx/)。

### npm 全局安装方式

仅适用于已确认用 npm 全局安装的副本，先停止旧进程：

```bash
npm install --global @deepseek-ai/dsh@0.2.0-rc.2
dsh --version
dsh --profile web --dump-config
dsh web
```

回到同一终端核对解析路径与 `--version`。如果仍显示旧版本，检查 Node 版本管理器、PATH 与多个安装前缀；不要连续混用 npm、pnpm 和手工文件覆盖。依据：[npm install](https://docs.npmjs.com/cli/v11/commands/npm-install/)。

### 源码方式

记录旧 commit 和工作区改动，在新的 checkout 检出已审核的目标 Tag；本页 `dsh-v0.2.0-rc.2` 对应 `639ed015397290b3745d163aafe02ffee4aa3f84`。在该副本按官方开发文档安装依赖并构建：

```bash
pnpm install
pnpm run build
pnpm dsh --version
pnpm dsh web
```

`pnpm dsh` 不自动构建，旧产物仍可能运行旧浏览器代码；命令能启动不代表更新已经生效。不要覆盖唯一源码副本或直接把移动的默认分支当作可回退版本。

## 更新或卸载插件

先读取实际 Profile 的 `package.json`，记录 dependencies 的包名与安装来源、锁文件及 `dsh.profile.bundles`。Git 地址、目录名和页面显示名不一定是移除命令需要的依赖键。以下以 `web` 为例；自定义 Profile 必须替换为你实际使用的名称。

### 升级到 0.2.0 后，已装插件被停用

0.2.0 起，DSH 会检查每个插件在 `peerDependencies` 中声明的 DSH 版本范围（只看 `@deepseek-ai/dsh` 和 `@deepseek-ai/dsh-*` 开头的依赖）。范围不包含当前版本时：

- **安装（`add`）**：用 npm 包名安装时，pnpm 运行前直接拒绝；其他来源在安装完成后检查，同样报告不兼容。
- **已经装好的插件**：Profile 启动时被标记为停用，不会加载。插件的依赖、文件和配置都还在，并没有被删除。
- 输出中会出现类似 `Plugin <包名>@<版本> is incompatible with dsh 0.2.0-rc.2: peerDependencies {...}` 的英文提示，列出不满足的依赖和范围。

很多为 0.1.x 发布的插件写的是 `^0.1.x` 这类范围，在 0.2.0 预发布版上同样不满足。按这个顺序处理：

| 情况 | 怎么做 |
|---|---|
| 插件已发布声明兼容 0.2.0 的版本 | 先读该版本的说明或本站教程，再用 `npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add <package-name>@<兼容版本>` 安装精确版本；声明兼容不等于已经实测 |
| 暂时没有兼容版本 | 继续按原组合使用旧 DSH 版本（命令里固定旧版本号），或先[只卸载这个插件](#只卸载一个插件)再升级 DSH |
| 一定要在新版本上试用旧插件 | 最后才考虑 `allow-version`：它只对精确的插件版本和精确的 DSH 版本生效，写入 Profile 的 `compatibility.json`；DSH 自己的提示是这样运行可能导致崩溃或数据丢失 |

本站插件目录在 2026-10-02 按这条规则复核了有专属教程的插件：常用插件的教程已更新到声明兼容 0.2.0-rc.2 的版本，不兼容的教程首屏有提示并标为待复查，见[插件中心](/plugins/)。依据：[兼容判断](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/boot/app-boot/src/plugin-compatibility.ts)、[启动时停用](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/boot/app-boot/src/compatibility-preflight.ts)。以上为固定源码审阅，本站没有运行不兼容插件。

### 更新一个插件

DSH 将插件参数转交给该 Profile 的 pnpm；范围更新可以使用：

```bash
npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web update <package-name>
```

它按依赖范围更新，不保证变成本站审核的精确版本。要采用专属教程的固定版本，先完成该版本权限、许可证、构建脚本与数据变化审阅，再使用教程给出的 `add <package>@<version>`；Git 插件使用所审完整 commit，不能盲目跟随分支。

本批 IM 示例与操作边界见 [dsh-im 接入与配置教程](/tutorials/xmanrui-dsh-im-install-config/)。更新后 CLI 会按实际安装状态整理 Bundle 列表；已运行进程保留启动时的 Bundle，必须重启对应 Profile。

### 只卸载一个插件

先按该插件文档关闭同步、远程入口或后台工作，再停止对应 Host。下面的包名占位符必须替换为实际依赖键：

```bash
npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web remove <package-name>
npx @deepseek-ai/dsh@0.2.0-rc.2 --profile web --dump-config
```

预期：依赖和相应 Bundle 层消失，重启同一 Profile 后插件入口不再加载。若入口仍在，检查是否启动了另一个 Profile、Home patch 或其他安装副本，不继续删除整个 Profile。

### dsh 移除插件后，lockfile 还在怎么办

在本文复核的 `0.2.0-rc.2` 中（与 0.1.7-rc.2 相同），`dsh plugin` 由内置插件管理器执行，与 Web 插件管理页共用同一套操作，并在操作前获取 Profile 写锁。0.2.0 起还可以用 `--profile desktop` 管理桌面端的插件，但要先打开一次桌面端完成初始化，再完全退出桌面端：

- **安装（`add`）**：pnpm 运行前先检查插件声明的 DSH 版本范围，不兼容会直接拒绝。安装失败时恢复运行前的 `package.json` 与 `pnpm-lock.yaml`，但 pnpm 已下载的文件可能保留。
- **卸载（`remove`）**：依次从 `dsh.profile.bundles` 移除、卸载运行时贡献、执行 `pnpm remove`，任一步失败就停止，可能留下部分依赖改动。
- **版本豁免**：`allow-version <package@version> --dsh-version <运行时版本> --accept-risk` 可以为不兼容的插件登记豁免，会打印风险警告并写入 Profile 的 `compatibility.json`。本站不建议为了"先装上再说"使用它。

锁文件仍存在本身不能证明卸载失败；本次源码审阅未确认删除锁文件可以修复某种特定故障，因此不要直接删锁文件或整个 Profile。

| 你看到的结果 | 下一步 |
|---|---|
| `add` 被拒绝，提示版本不兼容 | 保留原提示和插件版本；换用声明兼容当前 DSH 版本的插件版本，或暂不安装，见[已装插件被停用](#升级到-020-后已装插件被停用) |
| `remove` 返回非零状态 | 保留第一条错误、退出码和 Profile 路径；诊断日志在 Profile 的 `.plugin-manager/logs` 中；先解决该错误，不按"已卸载"继续 |
| `remove` 成功但界面还有入口 | 核对实际启动 Profile、依赖清单、Bundle 列表及 Home/用户 patch；重启原 Profile 后再检查 |
| 只是在锁文件中仍能搜到包名 | 区分直接依赖与其他包引用，保留锁文件及 manifest 差异；不要仅凭文本出现次数删除内容 |

提交问题时附 DSH/pnpm 版本、实际包名、执行命令、退出码与脱敏差异，不附凭据或完整配置。依据：[0.2.0-rc.2 插件 CLI](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/apps/cli/src/plugin.ts)、[插件管理器说明](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/boot/plugin-manager/README.zh.md)。本节为源码审阅，未运行安装、卸载或重建锁文件。0.1.5 系列由 CLI 直接转发给 pnpm，pnpm 返回 0 后才协调 `dsh.profile.bundles`，见[rc.1 插件管理固定源码](https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/apps/cli/src/plugin.ts)。

卸载依赖不会自动撤销外部账号授权，也不保证删除插件数据、附件或凭据。`--dump-config` 本身会初始化缺失 Profile，不能当作零副作用的目录检查。原理见 [Profile 与 Bundle 指南](/plugins/dsh-plugin-profile-guide/)。

## 卸载程序

先停止终端、服务管理器或启动项运行的 DSH，再按原安装方式处理。

| 原方式 | 移除程序入口 | 还会保留什么 |
|---|---|---|
| npx | 停止调用，移除自己配置的快捷方式或启动任务；通常没有常驻全局 DSH 包 | npm 缓存、DSH Home、Profile、Session、插件数据 |
| npm 全局包 | 确认解析路径与全局列表后执行下方命令 | DSH 业务数据和其他 npm 包；npx 仍能再次下载 DSH |
| 源码 checkout | 停止进程；确认路径、Git 改动与备份后，由你移除对应代码目录 | 放在源码目录之外的数据、独立工作区和平台凭据 |
| 其他管理器或手工二进制 | 按最初安装方式移除确切副本 | 不能用 npm 卸载命令推断它已被移除 |

仅对 npm 全局安装执行：

```bash
npm uninstall --global @deepseek-ai/dsh
npm list -g --depth=0 @deepseek-ai/dsh
```

再用 `command -v dsh` 或 PowerShell `Get-Command dsh` 核对入口；无结果是可能的正常状态，有结果则继续确认其来源。不要执行 npx 来“验证已卸载”，它可能重新准备该包。全局移除语义依据：[npm uninstall](https://docs.npmjs.com/cli/v11/commands/npm-uninstall/)。

缓存清理是另一项操作。可用 `npm config get cache` 定位当前 npm 缓存，但它由多个包共享，本页不提供全缓存删除命令，也不把清理缓存等同于删除 DSH 数据。

## 保留或清理数据

先从实际启动环境及配置定位 DSH Home；`DSH_HOME` 可覆盖默认位置，不要凭目录名猜测。停止写入后先做可恢复备份，再逐项决定。以下各项都不应假定会随卸载程序自动删除。

| 数据 | 定位与作用 | 处理顺序 |
|---|---|---|
| Profile 与锁文件 | 实际 DSH Home 下 `profiles/<name>`，包含依赖与 Bundle 组装 | 保存 manifest、锁文件、workspace 配置和 patch；不要为了移除一插件删整个 Profile |
| Home 配置 | DSH Home 下 `cordis.patch.yml`，跨 Profile 生效 | 单独保存并记录叠加关系 |
| Session 与工作区 | 按实际持久化/工作区配置定位；包括用户项目修改 | 先核对会话可读和项目 Diff，保留升级前未打开过的副本 |
| 插件状态与附件 | 按专属教程的 dataDir、缓存与保留策略定位 | 先停用 Bot/同步/任务，再选择性清理；TTL 不等于即时或全面删除 |
| 凭据与 `.env` | DSH Home 的 `.credentials.yaml`、Home/调用目录的 `.env`，以及启动环境 | 加密备份按密钥制度执行；外部撤销/轮换与本地引用删除分开 |
| 平台消息与授权 | 飞书、微信、Telegram 等平台侧 | 在平台核对撤销和留存，本机卸载无法证明平台消息已删除 |

若只是暂时不用，保留数据更便于恢复。若要清理，记录具体路径、备份位置和选择原因；不要递归删除整个用户目录或未经核实的 `$DSH_HOME`。DSH 凭据解析依据[rc.1 CLI 固定说明](https://github.com/deepseek-ai/deepseek-harness/blob/a66e4702047846cdaa10c66c9d3df3951f5ea70d/apps/cli/reference/README.zh.md)。

## 可复制的维护核对清单

```text
维护日期：
当前 DSH 版本及确认依据：
启动方式与命令解析路径：
实际 DSH Home / Profile：
插件实际包名、版本与安装来源：
目标版本及固定来源：
原始数据、配置与锁文件备份位置：
备份恢复检查结果：
如评估 0.1.6-alpha.1，协议/地址与旧 PTC/工作流配置核对结果：
升级到 0.1.7 时，V4 会话、设置导入日志、模型 protocol 字段和匹配备份核对结果：
[ ] 已停止旧进程与远程任务
[ ] 只改变本次批准的一层
[ ] 重启后版本和 Profile 正确
[ ] Bundle / 设置入口与预期一致
[ ] 如发生热更新错误，已逐项核对实际生效状态
[ ] 重要旧 Session 可读，数量与标题已对照
[ ] 可丢弃工作区的只读最小任务正常
[ ] 日志和工作区 Diff 无异常
[ ] 需要撤销的平台凭据已单独处理
结果、异常及是否回退：
```

以上是验证清单，不是本站已经执行的结果。卸载场景不必重新启动已移除的程序；核对入口、保留数据与凭据即可。

## 怎样验证升级结果

建议按以下顺序验收：

1. 再次执行 `--version`，确认实际启动的是目标版本；
2. 使用 `--dump-config` 对比 Bundle 与 patch 来源；
3. 启动对应 Profile，检查设置页和模型选择；
4. 在可丢弃工作区运行一个只读任务；
5. 只验证升级范围内的插件，不顺手启用更多能力；
6. 查看 Session、日志和工作区 Diff 是否出现异常。

模型、插件、权限和 Session 的变化应分别记录。需要完整安全边界时，结合[DSH 权限与沙箱指南](/tutorials/dsh-permissions-sandbox/)和[Session 恢复指南](/tutorials/dsh-session-guide/)复核。

### 程序启动了，但插件或文件打不开

先分层验收，避免把启动成功当成整套环境兼容：

| 层次 | 检查点 | 通过标志 |
|---|---|---|
| 实际程序 | 运行进程、启动入口和版本 | 当前 Host 确实使用目标版本，不只是磁盘包已更新 |
| 客户端模块 | 浏览器失败请求、模块 404、`loaded without registering` | 所需模块已加载；首页 HTTP 200 不足以证明这一点 |
| 浏览器与文件预览 | 同一 Host、同一非敏感文件的浏览器对照；请求与错误原文 | 目标文件可预览，不能只看交付卡片存在 |
| 当前预设与新会话 | 预设挂载、新会话创建、模型选择与最小文本任务 | 无 preset 配置错误；与旧历史读取分别验收 |
| 插件功能 | 设置入口、文件打开、低风险最小任务 | 目标功能可用；Bundle 挂载不等于功能验收 |
| 历史数据 | 重要会话正文与迁移错误 | 正文和最近记录可读；列表可见不足以证明恢复成功 |

[#5999 用户报告](https://github.com/deepseek-ai/deepseek-harness/discussions/5999)发生于 Windows 11、npm 全局安装、既有 Profile 从 `0.1.3-alpha.2` 升到 `0.1.5-alpha.1`，并包含外部插件 junction 直链。报告者遇到客户端模块 404、`loaded without registering` 与 `sidebarRight: no registered tab type claims`。截至 9 月 9 日，本页未复现该组合，也没有已确认的修复版本；这不是所有 Windows 或所有插件都会失效的结论。

先记录失败模块、请求状态、目标版本与 Profile 来源，不把首个报错模块认定为根因。配置和 Bundle 对照见[插件 Profile 指南](/plugins/dsh-plugin-profile-guide/)；若错误转向正文读取或迁移，按[会话打不开排查](/errors/dsh-session-open-failed/)处理，不继续在唯一数据上反复升级。

需要回退时选择自己已记录且与备份数据匹配的版本，不照搬报告者的降级目标。正常停止写入，保留现状副本，再恢复程序与对应数据；客户端恢复也不能替代历史会话验收。

## 回退到固定版本

npx 用户可以把命令重新指向升级前记录的版本。源码用户应切回已记录的 Tag 或 commit，并重新安装、构建。Profile 插件则应恢复已备份的 manifest 与锁定版本，再让包管理器根据那份状态安装；不要只恢复 `cordis.patch.yml`，因为 Bundle 依赖本身也必须与配置对应。

回退后仍要重启 Profile 并重新执行最小验证。新版已经写入的业务数据或 Session 不一定能被旧版无损读取；没有官方迁移承诺时，应保留升级前副本，避免直接在唯一数据上来回切换。

## 0.1.7-alpha.1：升级前先检查数据与设置

**从 0.1.5 升级到 0.1.7 或 0.2.0 前必读。** 本节 2026-09-22 按 `0.1.7-alpha.1`（`c36a83ff6bb95e3f82cf79f9be7c724270a8aa61`）核对；2026-09-24 比对 `0.1.7-rc.1`，2026-09-28 比对 `0.1.7-rc.2`，2026-09-30 再比对 `0.2.0-rc.2`（`639ed015397290b3745d163aafe02ffee4aa3f84`）：Settings 导入实现、V4 格式声明与 JSONL 持久化说明在这些版本中完全相同，本节适用于默认的 0.2.0-rc.2。本站没有执行升级或迁移。升级前停止写入，保存旧程序、实际 Session 根目录、Profile、配置、锁文件及受保护的凭据副本。独立 Profile 不代表数据根与凭据已隔离。

模型配置另有一项升级阻断：0.1.7 系列（rc.1、rc.2 相同）的官方 DeepSeek 适配器只使用 Messages API，配置中只要出现 `protocol` 字段就会拒绝加载。升级前先按[模型配置的 0.1.7-rc.1 小节](/tutorials/deepseek-harness-model-provider/#017-rc1官方适配器只用-messages)检查 Profile patch 与环境变量。

### V4 会话：保留旧日志不等于可以降级

新版持久化格式为 V4。固定 JSONL 后端对受支持的历史格式执行读取与校验：只读打开在内存中准备结果，不发布新版日志；写入打开通过校验后，在原日志旁发布 V4 后继文件，原日志保持不变。列表出现会话不代表历史正文、恢复与后续写入都已成功。

旧程序不支持降级读取 V4，也不能靠保留的旧日志自动回退。若迁移或恢复报错，停止写入，保存错误与日志路径，转[会话加载排障](/errors/dsh-session-open-failed/)。不要删除高版本文件、修改 header 或跳过事件来强行读取。回退应恢复旧程序和匹配的升级前数据副本，不承诺合并新版产生的对话。

上游另有面向开发者的批量迁移工具；本页不把它作为普通用户的必做命令。先在独立副本核对列表、历史正文、恢复、低风险新任务和重启后的持久化，再决定是否继续使用。

依据：[V4 格式与兼容性声明](https://github.com/deepseek-ai/deepseek-harness/blob/c36a83ff6bb95e3f82cf79f9be7c724270a8aa61/docs/persistence-changes/2026-09-16-session-format-v4.zh.md)、[固定 JSONL 读写与迁移规则](https://github.com/deepseek-ai/deepseek-harness/blob/c36a83ff6bb95e3f82cf79f9be7c724270a8aa61/packages/session/session-persistence-jsonl/README.zh.md)。

### 旧 settings.yaml：检查导入结果再继续配置

新版 Settings 将可编辑设置写入当前 Profile 的插件配置。Loader 加载完成后，如果实际 DSH Home 中存在旧 `settings.yaml`，会先将其改名为 `settings.yaml.imported`，再逐个导入 section。部分旧 section 会映射到新的条目 ID；被当前配置拒绝的项记录在日志中，仍保留在改名后的文件内，不会自动重试整次导入。

因此，看到 `settings.yaml.imported` 只证明改名发生，不证明所有设置都已生效。升级后应核对实际 Profile、关键设置与导入警告，保留升级前原文件；不要直接把旧文件覆盖回正在运行的新版 Home 来反复触发导入。回退也要恢复匹配的旧配置，不能只切换程序版本。

依据：[Settings 固定说明](https://github.com/deepseek-ai/deepseek-harness/blob/c36a83ff6bb95e3f82cf79f9be7c724270a8aa61/packages/settings/settings/README.zh.md)与[一次导入实现](https://github.com/deepseek-ai/deepseek-harness/blob/c36a83ff6bb95e3f82cf79f9be7c724270a8aa61/packages/settings/settings/src/index.ts)。本次仅补充这些数据与设置边界，未完成新版全部配置、模型或插件兼容验收。

## 历史版本记录

以下保留原章节标题与锚点，供旧环境对照。各节的默认版、通道与操作约定仅适用于所标日期；今天的版本选择见页首。

## 9 月 28 日：默认 0.1.7-rc.2

**历史快照：以下为 2026-09-28 至 09-29 的版本选择与通道值；本次选择见页首。**

当日默认精确版本为 **0.1.7-rc.2**（tag `dsh-v0.1.7-rc.2`，commit `477b4f420553e8a52c2fbccc464d7561b239c443`），npm latest 与 next 均指向它。之后 0.2.0-rc.1、0.2.0-rc.2 相继发布。继续使用 0.1.7 的用户可用精确版本维护：

```bash
npx @deepseek-ai/dsh@0.1.7-rc.2 --version
npx @deepseek-ai/dsh@0.1.7-rc.2 web
```

依据：[官方 0.1.7-rc.2 Release](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.7-rc.2)。

## 9 月 24 日：默认 rc.3 与 0.1.7-rc.1 怎样选择

**历史快照：以下为 2026-09-24 至 09-27 的版本选择与通道值；本次选择见页首。**

当日默认精确版本为 **0.1.5-rc.3**（tag `dsh-v0.1.5-rc.3`，commit `a4c74a91e06b00fe0b0937bde982170c526cc842`），相对 rc.2 只把 vendor 依赖固定为精确版本；npm next 为 `0.1.7-rc.1`，后为 `0.1.7-rc.2`。暂不升级到 0.1.7 的用户，仍可用精确版本维护 0.1.5 环境：

```bash
npx @deepseek-ai/dsh@0.1.5-rc.3 --version
npx @deepseek-ai/dsh@0.1.5-rc.3 web
```

0.1.5 系列的插件命令由 CLI 直接转发给 pnpm，行为见上方插件一节末尾。依据：[rc.2 至 rc.3 的比较](https://github.com/deepseek-ai/deepseek-harness/compare/dsh-v0.1.5-rc.2...dsh-v0.1.5-rc.3)。

## 9 月 22 日：默认 rc.2 与 0.1.7-alpha.1 怎样选择

**历史快照：以下为 2026-09-22 的版本选择与通道值；本次选择见页首。**

当日默认精确版本为 **0.1.5-rc.2**，npm latest 为 rc.2、next 为 `0.1.5-rc.3`；`0.1.7-alpha.1` 为主动评估的预发布版。当日本站未复核 rc.3 的操作差异，没有把 next 当作默认安装。0.1.7 系列的 V4 会话与设置导入检查保留在上方新版小节。

依据：[官方 0.1.7-alpha.1 Release](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.7-alpha.1)、[rc.2 固定 CLI](https://github.com/deepseek-ai/deepseek-harness/blob/fb2c4b9e698e30edb738bca4cf0618587db7d203/apps/cli/reference/README.zh.md)。

## 9 月 18 日：默认 rc.2 与 alpha.2 怎样选择

**历史快照：以下为 2026-09-18 的版本选择与通道值；本次选择见页首。**

当日默认精确版本为 **0.1.5-rc.2**，npm latest / next 均指向它；它仍是候选版，不保证稳定性或插件兼容。本文安装方式与维护命令按 rc.2 固定 CLI 和实现复核，未执行升级、数据迁移或第三方插件运行验收。下方按日期保留的旧版通道表仅代表当时状态。

| 目标 | 本次选择 | 验证重点 |
|---|---|---|
| 首次使用或按本站默认维护 | `0.1.5-rc.2`，精确命令见前部操作区 | 区分 npx、全局安装与源码副本，核对实际运行版本 |
| 已有环境运行正常 | 先保存旧程序、配置、凭据与数据的匹配备份 | latest 的变化不要求立即升级；回退不保证合并新版写入 |
| 需要新版模型、诊断或预览 | `0.1.6-alpha.2`，主动评估预发布 | 精确 npm 包存在，仍须隔离验证实际需求 |

alpha.2 固定提交为 `ddefc45fbc7f8e46dd73185e68295696d1297887`。升级前按症状查看[模型地址与视觉输入](/tutorials/deepseek-harness-model-provider/#016-alpha2地址与视觉输入)、[启动日志](/errors/web-ui-start-failed/#016-alpha2启动错误与日志)、[用户终端权限](/tutorials/dsh-permissions-sandbox/#016-alpha2用户终端与权限预设)和[Office 与文件差异](/tutorials/dsh-file-preview-delivery/#016-alpha2office-预览与文件差异)。新版插件管理与运行时卸载是另行复核的影响项，下文插件命令只覆盖 rc.2，不套用为 alpha.2 操作保证。

依据：[rc.2 固定 CLI](https://github.com/deepseek-ai/deepseek-harness/blob/fb2c4b9e698e30edb738bca4cf0618587db7d203/apps/cli/reference/README.zh.md)、[alpha.2 官方发行说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.6-alpha.2)。

## 9 月 16 日：是否评估 0.1.6-alpha.1

**历史快照：9 月 16 日默认操作为 0.1.5-rc.1；当前命令见页首本次维护选择。** 以下是 2026-09-16 核对的通道快照和 alpha.1 升级前检查，不表示本站已运行新版或完成迁移。下方 9 月 11 日及更早小节保留历史日期，不能用其中的旧通道值代替今天的选择。

| 目标版本 | 当前定位 | 适合怎样处理 |
|---|---|---|
| `0.1.5-rc.1` | 当日 npm latest 与本站固定基线 | 此处仅保留当日记录；当前维护从页首重新选择目标 |
| `0.1.5-rc.2` | npm next，候选预发布 | 有明确需求时独立评估，不把 next 当成默认安装 |
| `0.1.6-alpha.1` | GitHub 预发布，精确 npm 包已存在 | 需要新增能力时先备份，在隔离副本核对配置、模型和数据；包存在不等于兼容 |

alpha.1 固定提交为 `0a15e36e7f82b6ed45af6fa9759f29b40dcd965d`。当日补充未替换 rc.1 更新命令，也不把单独 Profile 当作完整的数据或凭据隔离。

| 受影响条件 | 升级前需要检查 |
|---|---|
| 使用内置 DeepSeek 适配器，尤其手动填过旧官方地址 | alpha.1 默认协议改为 Messages；核对地址覆盖与环境变量，按[模型配置的新版分支](/tutorials/deepseek-harness-model-provider/#016-alpha1升级后的协议与地址)区分官方地址和网关，不统一改所有 Provider |
| 自定义配置引用旧 PTC 包/服务或旧工作流执行器 | 官方说明 PTC 改为 `ptc-runtime` 系列，工作流改为 `workflow-ptc`；逐项检查引用，不做全局字符串替换。新版工作流依赖 Node PTC，不能假定支持 Python PTC |
| PTC 代码依赖进程环境或旧执行方式 | 新版 Node PTC 在独立进程中运行，程序可见 `process.env` 为空，并遵守会话文件策略；不能沿用原来读取环境的假设 |
| 修改正在运行的 Web 配置 | 解析/组合失败保留原配置；进入配置应用后激活失败可能部分生效，不保证整树事务回滚。记录错误和生效项，修正配置后重新检查 |
| 程序启动但部分能力不可用 | 新版允许可选条目失败后保留可用部分；必需条目失败会阻止启动。能打开首页不等于所有配置与插件可用 |

热更新结论以固定 [app-boot 说明](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/boot/app-boot/README.zh.md)和[配置监视实现](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/boot/app-boot/src/watch-config.ts)为准；同版本 CLI 总览仍有“事务方式”旧描述，不能据此承诺自动回滚。该差异不是让用户反复重试失败配置的理由。

升级前停止写入，保存旧程序版本、实际数据根、Profile、配置与锁文件，以及受保护的凭据备份。Session V2 到 V3 的转换有输入约束，且不负责迁移 `settings.yaml`；已有 V3 也不能仅凭格式名相同推断旧版能读取新版全部事件。回退恢复旧程序及匹配的旧数据副本，不承诺合并升级后的新对话，更不能删除事件或改 header 强行读取。

迁移依据：[固定格式转换说明](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/session/session-format-v2-to-v3/README.zh.md)；运行配置依据：[Node PTC](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/ptc-runtime/ptc-runtime-node/README.zh.md)、[工作流](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/workflow/workflow-ptc/README.zh.md)。发行摘要见[官方 alpha.1 Release](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.6-alpha.1)。

## 9 月 11 日：rc.1 与 rc.2 怎样选择

截至 2026-09-11，npm `latest` 仍为 `0.1.5-rc.1`，`next` 为 `0.1.5-rc.2`，`alpha` 为 `0.1.5-alpha.2`。rc.2 精确包已发布，固定提交为 `fb2c4b9e698e30edb738bca4cf0618587db7d203`；两版 rc 都是候选预发布版。本站默认安装仍锁定 rc.1，包已发布不代表本站运行验收通过。

| 你的需求 | 选择与检查 |
|---|---|
| 按本站默认路径安装 | 当日使用 rc.1；当前请按页首本次维护选择 |
| 评估反馈弹窗、文件卡片体验 | rc.2 增加点赞和点踩提交确认、失败保留草稿，并调整文件卡片与图标；先在隔离副本评估精确版本 |
| 解决预览或历史会话错误 | 先查错误类型，发行说明未宣称这些问题已全面修复 |

依据：[rc.2 发行说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-rc.2)、[npm 通道](https://registry.npmjs.org/-/package/@deepseek-ai%2Fdsh/dist-tags)。以下历史版本表保留原核查日期。文件侧栏异常见[浏览器与预览分流](/tutorials/dsh-file-preview-delivery/)，旧历史或新会话异常见[会话排障](/errors/dsh-session-open-failed/)。

## 当前默认 0.1.5-rc.1：按原版本选择升级路径

**历史章节：以下“当前”指 2026-09-10。保留原标题以兼容旧锚点；今天的默认版本与命令见页首选择说明。**

2026-09-10 18:25（UTC+08）之后的本次核对，latest / next 均为 `0.1.5-rc.1`，精确包已发布；alpha 仍为 `0.1.5-alpha.2`。当日操作命令更新到新 rc.1，下方 alpha.1 / alpha.2 的“默认保持旧 rc.1”说明均为此前快照，不是当前选择；本次选择以页首说明为准。

| 原环境 | 本次重点 |
|---|---|
| 0.1.2-rc.1 或更早 | 跨版本涉及 V3、SessionHandle、Agent/Inbox 与面板接口；先备份，再隔离验收 |
| 0.1.5-alpha.2 | 核对实际增量、默认模型与预览行为，仍需验收旧会话和插件 |
| 新用户 | 使用本页精确命令，候选版不等于稳定性保证 |

完整程序和数据备份后，分别检查运行版本、客户端、插件功能、历史正文。旧程序不能降级读取 V3，新版产生的数据不保证能合并回旧副本；发现迁移错误时按[会话排障](/errors/dsh-session-open-failed/)停止写入。此前插件验收不自动覆盖 rc.1。本次只审阅[固定 CLI](https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/apps/cli/reference/README.zh.md)与[发行说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-rc.1)，未执行升级。

## 0.1.5-alpha.2：先确认收益与插件边界

2026-09-10 核对：GitHub 新预发布为 `0.1.5-alpha.2`，精确 npm 包已发布，alpha 已指向新版；latest / next 仍为 `0.1.2-rc.1`，默认固定命令不变。下文 9 月 9 日 alpha.1 表格是历史快照。需要新能力时先看[alpha.2 专题](/tutorials/deepseek-harness-0-1-5-alpha-2/)。

本版调整 Web 全局面板接口：`sidebar.panellist` 与 `main`，原 `conversation` Slot 迁到 `main` 的 `conversation` key。使用旧面板插件时先核查实际注册和导航，不能沿用 alpha.1 的兼容验收。分别检查运行版本、客户端模块、目标插件功能、重要会话正文；列表或首页正常不等于全部通过。

文件体验验收可使用[无敏感内容的示例文件](/tutorials/dsh-file-preview-delivery/)，核对侧栏和 Host 原生动作。`present` 不保存文件副本；文件备份与 Session 备份分开确认。迁移仍遵守 V3 限制，正常停止写入后才恢复旧程序及匹配的数据副本。

本站仅核对[官方发布说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-alpha.2)与固定来源，未运行新版升级或迁移。

## 怎样选择目标版本

**2026-09-09 核对：当日默认命令保持 `0.1.2-rc.1`，仍为候选版。** GitHub 新预发布为 `0.1.5-alpha.1`，精确 npm 包已发布；当日没有运行新版升级、迁移或插件组合验证。

| 版本信息 | 本次核对 | 维护选择 |
|---|---|---|
| npm latest / next | 均为 0.1.2-rc.1 | 保留本页默认固定命令，执行前再查标签 |
| npm alpha | 0.1.5-alpha.1 | 预发布通道，不与 next 混用 |
| GitHub Release / 精确包 | 0.1.5-alpha.1，预发布 / npm 已发布 | 主动评估前先保存独立数据与恢复环境 |

Release 固定提交为 `5dda764ed3aa172535a7967b06ff95d9cbfe536a`；npm 元数据未提供 gitHead，包存在不等于源码构建一致性或运行兼容已经验证。版本变化见[新版专题](/tutorials/deepseek-harness-0-1-5-alpha-1/)。

### V3 会话：先确定怎样回退，再升级

新版只读 open 不发布迁移后继；写 open 在校验通过后生成新版日志并保留源文件。应用操作可能包含写入，不能仅凭按钮叫“查看”就当作零副作用。未知扩展事件可能导致迁移拒绝。

**旧程序不支持降级读取 V3；保留旧日志不等于新版产生的对话能回退。** 停止任务后保存程序、Profile、锁文件、所需 Session 和配置的完整副本；敏感凭据另行受保护保存。独立 Profile 不保证数据根和凭据隔离，不让两个进程同时操作同一份数据。

在副本验收列表、历史正文、恢复和低风险任务，再决定是否用于日常工作。回退时停止新版，恢复旧程序及其对应的数据副本；不要删除高版本 generation 或改 header 来让旧程序读取。不承诺自动反向迁移或合并升级后新写入的数据。

来源：[官方 Release](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-alpha.1)、[npm 通道](https://registry.npmjs.org/-/package/@deepseek-ai%2Fdsh/dist-tags)、[精确包](https://registry.npmjs.org/@deepseek-ai%2Fdsh/0.1.5-alpha.1)。详细数据行为见[Session 指南](/tutorials/dsh-session-guide/)。旧 SQLite、Session v2 用户仍需阅读[历史迁移与回退限制](#历史迁移与回退限制)，不能跳过中间版本变化。

## 历史迁移与回退限制

### alpha.3 前置检查：曾用 SQLite Session 就先暂停

DeepSeek Harness `0.1.2-alpha.3` 删除了可选的 SQLite 权威 Session 持久化后端，JSONL 成为唯一第一方实现。`0.1.2-alpha.3` 不会打开或自动迁移旧后端创建的数据库；这是一项数据兼容边界，不是普通界面设置变化。

如果当前或历史部署使用过该后端：

1. 不要覆盖旧程序、配置或唯一数据库副本；
2. 正常停止写入，并保留仍包含 SQLite 后端的完整旧环境；
3. 在数据副本上确认需要保留的 Session 能由旧版本读取；
4. 只有在逻辑内容、备份恢复和回退路径都可复核后，再隔离评估 alpha.3；
5. 没有部署对应的可靠导出步骤时暂停，不使用来源不明的迁移脚本。

现有 Web `/export` 与下载说明要求 JSONL 的每 Session 原始产物，不能据此声称它会把旧 SQLite 权威存储直接迁移到新版。本站因此不提供未经官方证据支持的一键转换命令。更多数据结构与判断见[DSH Session 使用与恢复指南](/tutorials/dsh-session-guide/)。

### 0.1.3-alpha.1 的 Session v2

2026-09-06 核对时，GitHub 最新为 alpha.1，精确 npm 包尚未发布；这是当时快照。其他旧版快照见[历史目标版本选择](#怎样选择目标版本)，不要把这段历史说明当作当前安装目标。

alpha.1 的 JSONL 后端在 `open` 旧日志时会为受支持格式生成相邻 generation，即使是 read 模式也可能产生新文件；`stat`／`list` 则不发布迁移产物。Session 锁限制写入者，不能同时让两个 DSH 进程操作同一数据目录来测试升级和回退。新版已知的历史会话加载性能回退也不是删除日志的理由。

建议的检查顺序：停止任务并保存原始数据 → 在副本准备目标环境 → 对照会话数量、标题与内容 → 验证一个最小任务及必要插件 → 记录结果再决定是否切换。失败时停止测试环境并恢复旧环境的完整副本；不要手动拼接不同 generation、删除锁文件或声称一定可逆。

完整范围见[0.1.3-alpha.1 专题](/tutorials/deepseek-harness-0-1-3-alpha-1/)与[Session 使用与恢复](/tutorials/dsh-session-guide/)。

### alpha.5 评估前后：不要把 alpha.4 当作目标版本

官方 `0.1.2-alpha.5` 修复了从 rc.2 或 alpha.3 升级 alpha.4 后可能无法启动、Session 列表标题消失的问题。在 2026-09-02 的历史评估中，目标应是 alpha.5，而不是中间的 alpha.4；当时 npm 默认版仍为 rc.2。当前通道请看本页开头，不能继续把这一历史建议当作最新目标。

升级前除了记录版本和配置，还应保存：来源版本、目标版本、Profile 名称、Session 数量、标题快照，以及至少一个重要旧会话能否打开。升级后在隔离副本依次验证启动、会话数量、标题、只读打开旧会话和创建低风险新会话。遇到失败时保留日志、配置和原数据副本，不要边排障边删除缓存或 Session。

alpha.5 的固定修复针对可重建的 Session 投影缓存兼容，并不构成任意损坏环境的恢复承诺。版本回退也只切换程序与匹配配置，不能保证新版写入的数据结构被旧版无损回读；因此本文不提供“一键恢复标题”或未经第一方证据支持的数据修复命令。

完整修复范围见 [alpha.5 升级修复与 alpha.4 重要变化](/tutorials/deepseek-harness-0-1-2-alpha-5/)。

### 更早 alpha 的历史记录

2026-08-28 的 alpha.1 发布时，npm 默认仍是 0.1.1-rc.2；这是历史事实，不是当前安装基线。原变化与评估条件保留在 [0.1.2-alpha.1 专题](/tutorials/deepseek-harness-0-1-2-alpha-1/)。

## 本文的验证范围

本文完成了固定 Release、CLI 插件转发与 Bundle 整理逻辑、配置层和 npm npx 说明的静态审阅。没有执行升级、卸载、数据迁移或第三方插件，也不承诺所有候选版本都能无损回退。

第一次安装请从[DeepSeek Harness 安装与 Web UI 指南](/tutorials/deepseek-harness-install-web-ui/)开始；只处理插件时，继续阅读[Profile、Bundle 与插件安装指南](/plugins/dsh-plugin-profile-guide/)。

## 原始来源

- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.1-alpha.1
- https://github.com/deepseek-ai/deepseek-harness/blob/5badb15009ae1756c3afe0ae0cef1faafc290ccc/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/5badb15009ae1756c3afe0ae0cef1faafc290ccc/packages/boot/app-boot/src/plugin-compatibility.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/boot/app-boot/src/plugin-compatibility.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/boot/app-boot/src/compatibility-preflight.ts
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.0-rc.2
- https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/apps/cli/src/plugin.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/settings/settings/src/index.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/docs/persistence-changes/2026-09-16-session-format-v4.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.7-rc.2
- https://github.com/deepseek-ai/deepseek-harness/blob/477b4f420553e8a52c2fbccc464d7561b239c443/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/477b4f420553e8a52c2fbccc464d7561b239c443/apps/cli/src/plugin.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/477b4f420553e8a52c2fbccc464d7561b239c443/packages/boot/plugin-manager/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/477b4f420553e8a52c2fbccc464d7561b239c443/packages/settings/settings/src/index.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/477b4f420553e8a52c2fbccc464d7561b239c443/docs/persistence-changes/2026-09-16-session-format-v4.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.7-rc.1
- https://github.com/deepseek-ai/deepseek-harness/compare/dsh-v0.1.5-rc.2...dsh-v0.1.5-rc.3
- https://github.com/deepseek-ai/deepseek-harness/blob/a4c74a91e06b00fe0b0937bde982170c526cc842/apps/cli/package.json
- https://github.com/deepseek-ai/deepseek-harness/blob/46a7f68b0922371ce7144b668b90e377d8e799f4/packages/settings/settings/src/index.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/46a7f68b0922371ce7144b668b90e377d8e799f4/packages/llm/llm-deepseek/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.7-alpha.1
- https://github.com/deepseek-ai/deepseek-harness/blob/c36a83ff6bb95e3f82cf79f9be7c724270a8aa61/docs/persistence-changes/2026-09-16-session-format-v4.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/c36a83ff6bb95e3f82cf79f9be7c724270a8aa61/packages/session/session-persistence-jsonl/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/c36a83ff6bb95e3f82cf79f9be7c724270a8aa61/packages/session/session-format-v3-to-v4/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/c36a83ff6bb95e3f82cf79f9be7c724270a8aa61/packages/settings/settings/src/index.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/c36a83ff6bb95e3f82cf79f9be7c724270a8aa61/packages/settings/settings/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/fb2c4b9e698e30edb738bca4cf0618587db7d203/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/fb2c4b9e698e30edb738bca4cf0618587db7d203/apps/cli/src/plugin.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/boot/app-boot/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/boot/app-boot/src/watch-config.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/session/session-format-v2-to-v3/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/ptc-runtime/ptc-runtime-node/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/workflow/workflow-ptc/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/apps/cli/src/plugin.ts
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-rc.2
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-rc.1
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-alpha.2
- https://github.com/deepseek-ai/deepseek-harness/discussions/5999
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-alpha.1
- https://github.com/deepseek-ai/deepseek-harness/blob/5dda764ed3aa172535a7967b06ff95d9cbfe536a/packages/session/session-format-v2-to-v3/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/5dda764ed3aa172535a7967b06ff95d9cbfe536a/packages/session/session-persistence-jsonl/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.3-alpha.2
- https://registry.npmjs.org/-/package/@deepseek-ai%2Fdsh/dist-tags
- https://registry.npmjs.org/@deepseek-ai%2Fdsh/0.1.3-alpha.2
- https://docs.npmjs.com/cli/v11/commands/npm-install/
- https://docs.npmjs.com/cli/v11/commands/npm-uninstall/
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.3-alpha.1
- https://github.com/deepseek-ai/deepseek-harness/blob/a66e4702047846cdaa10c66c9d3df3951f5ea70d/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/a66e4702047846cdaa10c66c9d3df3951f5ea70d/apps/cli/src/plugin.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/d347e703908d0406b7a7ef80e3a0e594d86b2215/packages/session/session-persistence-jsonl/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.2-alpha.1
- https://github.com/deepseek-ai/deepseek-harness/commit/cd5ef8148158c3a752a658978873241fdf8e2bbc
- https://registry.npmjs.org/@deepseek-ai%2Fdsh/latest
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.1-rc.2
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/apps/cli/src/plugin.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/docs/architecture.zh.md
- https://docs.npmjs.com/cli/v11/commands/npx
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.2-alpha.3
- https://github.com/deepseek-ai/deepseek-harness/blob/dd6322d604e00eec1ba5e0c8541159906a21094a/.agents/notes/implemented/simplification/2026-08-30-jsonl-only-session-persistence.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/dd6322d604e00eec1ba5e0c8541159906a21094a/packages/session-query/session-log-export/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.2-alpha.5
- https://github.com/deepseek-ai/deepseek-harness/blob/db6bdc3576c2d4e7c965e8e3ed0c2a731eed87f5/.agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md