一键更新 Zhucy123/dsh-update

dsh-update · ⭯ 更新DSH

一键更新本地 DeepSeek Harness（DSH）checkout：对比版本 → 确认 → 拉取并重新构建 → 重启，全程都在侧边栏面板里完成，进度实时可见。

dsh-update 是 DSH Web GUI 的 Profile Bundle 插件：在侧边栏底部（设置按钮上方）加一个「⭯ 更新DSH」圆形按钮。点击后对比本地 checkout 与远程 dsh-v 发布 tags；发现新版本时不自动动手，先展示本地/远程版本与本次更新内容，由你点「开始更新」后才执行 git fetch → checkout → pnpm install → clean → build，完成后自动（或一键）重启 dsh。插件界面中英双语，跟随 DSH 界面语言实时切换。

目录

- 特性
- 界面速览
- 工作原理
- 兼容性
- 要求
- 安装
- 验证与排障
- 配置
- API 路由
- 安全
- 开发
- 版本历史
- License

特性 Features

- 🆚 版本对比 — 读取本地 checkout 的 tag / commit，与 origin 的 dsh-v tags 对比（git ls-remote，只读）。GitHub 直连超时自动切换 gh-proxy.com 镜像；成功结果缓存 60 秒，重复打开秒回。
- 🛡️ 更新前先确认 — 检测到新版本只展示对比与更新内容，绝不自动执行；并醒目提示「更新期间整个页面可能突然变空白」的真实原因（构建阶段会替换网页资源文件），由你点击「开始更新」后才真正动手。
- ⚡ 一条龙更新 — git fetch --tags → 自动暂存本地改动 → git checkout <tag> → pnpm install → pnpm run clean → pnpm run build，以 text/event-stream 流式实时显示每步输出。
- 🧹 构建前自动 clean — 版本切换后旧版本残留的 gitignore lib/ 产物可能引用新源码中已不存在的导出，导致 MISSING_EXPORT；构建前自动执行 pnpm run clean 清掉过期产物（幂等，clean 失败仅警告）。
- ✅ 构建后核验 — install + build 都成功才算完成；build 成功后服务端重新读取 git 状态，面板显示 ✓ 已确认当前版本与更新目标一致。
- 📄 本次更新内容 — 面板内展示该版本的 GitHub Releases 说明，按 DSH 界面语言显示中/英文段（失败降级为「查看 GitHub Releases →」链接）。
- 🔄 自动重启 + 一键重启 — 更新/回退成功约 2 秒后自动重启 dsh（由服务端定时器驱动，页面已变白/断线也会发生）；也可点「重启DSH / 立即重启」手动触发；重启失败（如自动重启未生效）有明确兜底提示。
- ↩️ 版本回退 — 更新后悔了？在「已是最新」结果视图下拉选择任一历史 dsh-v tag 回退，流程与更新完全一致（目标 tag 白名单 + git rev-parse --verify 核验）。
- 💾 本地改动安全 — 更新前自动 git stash push -u（含未跟踪文件，修复死循环冲突），成功后原样恢复；新版本改到同一文件时改动安全保存在 stash 不丢失，并明确提示；冲突视图提供「自动暂存并继续」。
- 🔙 失败自动回滚 — 已切到新版本后 install/build 失败，自动 git checkout 回原版本（优先原 tag，否则原 commit），绝不把工作树留在半更新状态。
- 🔒 并发保护 & 安全边界 — 同一时间只允许一个更新任务（重复触发返回 409）；4 个 API 路由全部 loopback-only，仅本机浏览器可触发真实安装；重启路由额外拒绝代理转发。
- 🌍 跨平台 — Windows / Linux / macOS；git / pnpm 缺失时快速失败而非挂到超时，POSIX 无 pnpm 自动回退 corepack pnpm。

界面速览 Usage

1. 启动 dsh web，侧边栏底部、设置按钮上方出现「⭯ 更新DSH」圆形按钮。
2. 点击打开面板：自动检查并显示 本地版本 / 远程版本 / 是否可更新。
3. 有新版 → 预览「本次更新内容」→ 点「开始更新」；等待实时进度。构建阶段页面可能突然变空白——属正常现象，基本意味着更新已完成。
4. 完成后面板显示 ✓ 更新成功（从→到版本、当前 commit、更新目录）；约 2 秒后自动重启，页面恢复后刷新一次即可；或点「重启DSH」立即生效。
5. 已是最新 → 可用「版本回退」下拉回退到任一历史版本，过程与更新相同。

工作原理 How it works

flowchart TD
A[点击「⭯ 更新DSH」按钮] --> B[GET /api/dsh-update/status]
B --> C{发现新版 dsh-v tag?}
C -- 否 --> D[已是最新提供「版本回退」]
C -- 是 --> E[展示 本地 / 远程版本+ 本次更新内容「开始更新」按钮]
E --> F[git fetch --tags直连失败 → gh-proxy 镜像]
F --> G[git stash push -u安全暂存本地改动]
G --> H[git checkout <tag>]
H --> I[pnpm install]
I --> J[pnpm run clean]
J --> K[pnpm run build]
K --> L{成功?}
L -- 否 --> M[自动回滚到原版本面板显示失败原因]
L -- 是 --> N[构建后核验版本✓ 确认当前版本]
N --> O[约 2 秒后自动重启 dsh或点「立即重启」]

更新目标目录自动定位：从 dsh web 进程的 process.cwd() 向上逐级查找含 .git 的目录（dsh web 常从子目录如 apps/cli/src 启动）；可用环境变量或插件 config 覆盖，见配置。

兼容性 Compatibility

| 平台 | 支持 | 说明 |
| Windows | ✅ | pnpm 经 shell 走 .cmd shim；重启以 PowerShell -WindowStyle Hidden + windowsHide 静默拉起（v1.6.1，detached: false 修复 Node.js #51018）；更新默认走进程内路径，可选启用「后台分离」模式（v1.6.3 引入 / v1.7.0 起默认关闭，见下） |
| Linux | ✅ | pnpm 直接二进制运行；缺失时回退 corepack pnpm（v1.6.0） |
| macOS | ✅ | 与 Linux 相同；git / pnpm 缺失时快速失败而非挂到超时（v1.6.0） |

- 路径统一经 node:path 处理，不写死分隔符；git 命令跨平台。
- 重启机制跨平台：POSIX 用 detached: true（Node 内部 setsid）让新进程成为独立会话/进程组，脱离控制终端——关闭启动它的终端/窗口不影响服务，输出重定向到 tmpdir 日志文件，全程静默（v1.5.2 / v1.6.0）。
- systemd（Linux）托管时自动禁用自重启（supervisor 负责拉起）；launchd 等未识别场景默认允许自重启。
- Windows 后台分离更新（v1.6.3 引入，v1.7.0 起默认关闭）：Windows 上运行中的 dsh 服务可能占用旧 node_modules 文件句柄，进程内 pnpm install 删不掉被锁包（报 [WARN] Failed to remove ...）会失败并触发自动回滚。为此提供可选的「后台分离」模式：设 config.windowsDetachedUpdate: true 后，更新在 git 步骤（checkout）完成后自动移交 detached 后台进程——本进程退出释放句柄，后台进程等端口释放后执行 install → stash apply → clean → build，成功后自动重启 dsh、失败则回滚并写日志（%TEMP%\dsh-update-apply-.log）。代价是页面会在交接时断开，需稍后刷新。默认不启用：进程内路径进度全程可见、不会断开，只有真的撞上文件锁时才有必要开启。

要求 Requirements

- 已 clone 的 deepseek-harness checkout（git 仓库，含 dsh-v 发布 tag 的 origin）。
- 本机可访问 GitHub；不可达时插件自动走 gh-proxy.com 镜像（可配置更换，见配置）。
- Node.js ≥ 18（host 端使用全局 fetch / AbortController）、git、pnpm（POSIX 无 pnpm 时自动回退 corepack pnpm，Node 16.9+ 自带）。

安装 Installation

本插件以 Profile Bundle 形态分发：package.json 声明了 dsh.bundle（携带 cordis.patch.yml 配置层），所以 dsh plugin --profile web add 一条命令装完即自动激活——无需手动编辑任何配置文件。

方式一：从 npm 安装（推荐）

dsh plugin --profile web add @zhucy123/dsh-update
dsh web

注：dsh-update 这个裸名已被第三方注册为占位空壳包，故以 scoped 名 @zhucy123/dsh-update 发布；插件的 ID（侧边栏按钮、cordis 注册名、/api/dsh-update/ 路由前缀）仍是 dsh-update，安装后无感知差异。

方式二：从 GitHub 安装

dsh plugin --profile web add git+https://github.com/Zhucy123/dsh-update.git
dsh web

方式三：从本地源码目录安装（开发/测试）

link: 方式在 node_modules 里创建符号链接（symlink）指向你的源码目录，改源码后无需重新安装（host 端代码 lib/index.js 在下次启动服务时加载）。把下面的 <源码目录> 换成插件源码所在位置的绝对路径。

Windows (PowerShell)：

用 DSH 插件命令安装本地源码(link: 协议,符号链接,改源码即生效)
dsh plugin --profile web add link:<源码目录>
dsh web

Linux / macOS：

dsh plugin --profile web add link:<源码目录>
dsh web
npm / git 安装会在 web profile 目录里执行 pnpm add，成功后对账插件层：检测到本插件声明 dsh.bundle，会自动把它追加进 dsh.profile.bundles 并注册进 Cordis loader 树，一步装完即用；源码会被实际拷贝到 node_modules，改动源码需重新安装（不像 link: 是符号链接、改源码即生效）。

装完完全重启 DSH web（不是刷新页面，不是另开终端跑 dsh web，而要停掉旧进程后重新启动），然后在侧边栏底部、设置按钮上方应出现「⭯ 更新DSH」圆形按钮。

验证与排障

安装并重启后，可以核对以下几点：

1. 依赖已写入：~/.dsh/profiles/web/package.json 的 dependencies 里应有 "@zhucy123/dsh-update"（方式是 link: 或 git/npm）。
2. 已加入配置层：~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 列表里应有 @zhucy123/dsh-update（dsh plugin add 自动写入，无需手动编辑）。
3. 依赖已就位：~/.dsh/profiles/web/node_modules/@zhucy123/dsh-update 存在——link: 方式为指向源码目录的符号链接（Windows 下显示为 Junction），git / npm 方式为实际拷贝的目录，均属正常。
4. 重启后按钮可见：侧边栏底部设置按钮上方应出现「⭯ 更新DSH」按钮；点开可看到版本对比面板而非报错。

常见排障

| 现象 | 原因 / 处理 |
| 已 dsh plugin add 并重启，但按钮不出现 | 最常见：装完没有完全重启（不是刷新）。停掉旧 dsh web 进程再启动。 |
| 手动按 scoped 改名后按钮消失 / 报「ID 不匹配」 | 插件内部加载标识未与 scoped 包名同步。确认 cordis.patch.yml 的 name: 与 lib/client.js 的 load({ id }) / PLUGIN_ID 均为 @zhucy123/dsh-update（v1.6.2 已修复；旧版本或手动改名时需保持一致）。 |
| 安装时提示「declares no dsh.bundle」 | 装到的版本缺少 bundle 声明（旧版或打包遗漏 cordis.patch.yml）。确认版本 ≥ 1.2.0 后重新安装/更新。 |
| 出现「Failed to load plugins」 | 插件 host 端 lib/index.js 启动报错（多为依赖解析问题）。查看启动日志，确认 node_modules 依赖已装齐。 |
| 更新后提示 client bundles not found | 更新只做了 install 没做 build。面板会把 install + build 都成功才算完成；若手动操作务必补 pnpm run build。 |
| 更新后 build 报 MISSING_EXPORT / 重启打不开 | 旧版本残留的 lib/ 构建产物引用了新源码中已不存在的导出（典型：上游删除了某个包）。v1.3.0 起更新流程会在构建前自动执行 pnpm run clean；若手动操作，执行 pnpm run clean && pnpm run build 即可。 |
| 更新完成后再看仍显示「有更新」 | 面板只在打开时 / 点「重新检查」时刷新状态；更新前就开着的面板（或多标签页）仍停留在旧视图。点「重新检查」即可。v1.3.2 起完成面板还会显示构建后核验结果（✓ 已确认当前版本）。 |
| 点「更新」提示「已有更新正在执行中」 | v1.3.2 起的并发保护：同一时间只允许一个更新任务。等当前更新完成后再试。 |
| 打开面板后长时间停在「正在检查版本…」 | 版本对比要访问 GitHub（git ls-remote）。v1.3.3 起先直连（8 秒超时），失败自动走 gh-proxy.com 镜像；成功结果缓存 60 秒，重复打开秒回。直连与镜像都失败时显示「检查异常」。 |

配置 Configuration

更新目标目录默认自动定位（cwd 向上找 .git），可通过环境变量或插件 config 覆盖。插件 config 写在 profile 的 cordis.patch.yml 用户补丁层（安装方式一/二/三自动激活，config 为可选增强）。

| 环境变量 | 插件 config 字段 | 说明 | 默认值 |
| DSH_UPDATE_REPO_DIR | repoDir | 要更新的仓库根目录（覆盖自动定位） | cwd 向上查找含 .git 的目录 |
| DSH_UPDATE_GIT_PROXY | gitProxy | GitHub 镜像前缀，用于直连超时后的回退；空字符串 "" 关闭镜像回退 | https://gh-proxy.com/ |
| — | allowRestart | 是否允许自重启；systemd 托管时自动禁用 | true |
| — | autoRestart | 更新/回退成功后是否自动重启约 2 秒后 | true（受 allowRestart 约束） |
| — | windowsDetachedUpdate | Windows 是否启用「后台分离更新」（v1.6.3 引入，v1.6.4 起默认关闭）：设 true 时 git 步骤后移交 detached 进程执行 install/build，本进程退出释放文件锁（页面会断开）；默认 false 走进程内更新——面板全程显示实时进度、不会中途断开，若 pnpm install 因文件锁失败会自动回滚到更新前版本 | false |
| DSH_UPDATE_RESTART_SCRIPT | — | 已废弃（v1.1.0 起 UI 不再使用）；host 端 status 仍透传该值，仅为兼容 | — |

插件在运行时动态读取仓库目录等本地路径（process.cwd() / 环境变量），不会写死进源码。

API 路由 API

| 路由 | 方法 | 说明 |
| /api/dsh-update/status | GET | 版本对比（本地 tag/commit vs 远程最新 dsh-v tag），并返回本地历史 tag 列表供回退用；loopback-only |
| /api/dsh-update/release-notes?tag= | GET | 指定版本的更新说明（直连 GitHub Releases API，失败走镜像）；loopback-only |
| /api/dsh-update/run | POST | 流式执行更新/回退（text/event-stream JSON-lines 进度；并发保护 409）；loopback-only |
| /api/dsh-update/restart | POST | 一键重启 dsh（detached helper 按原始启动命令拉起新进程）；严格 loopback + Origin 校验，拒绝代理转发，supervisor 托管或 allowRestart: false 时禁用 |

安全 Security

- 4 个 API 路由全部 loopback-only（sec-fetch-site + Origin 校验），LAN / 手机来源一律 403；/restart 额外使用更严格的校验（trustedRestartRequest：仅接受本机直连、拒绝 x-forwarded-for 等代理头、Origin 必须与 Host 精确一致）。
- 更新会真实执行 git checkout + pnpm install + pnpm run build，因此只允许本机浏览器触发；所有 git 调用强制 GIT_TERMINAL_PROMPT=0（绝不交互式要凭据）。
- 回退目标必须是 dsh-v* 发布 tag（拒绝任意 ref），防异常调用把 checkout 引向任意引用。

隐私 / 开源安全

本仓库不包含任何用户本地数据。 源码中仅引用公开的产品名 deepseek-harness 与 DSH 默认端口 3080；不出现用户名、绝对工作目录、凭证、token 等。仓库只含 lib/、package.json、cordis.patch.yml、README.md、CHANGELOG.md、LICENSE，无 node_modules、.git、日志、环境变量或凭据文件，可安全开源。

开发 Development

git clone https://github.com/Zhucy123/dsh-update.git
cd dsh-update

安装依赖(如有)
pnpm install

本地 DSH 中通过符号链接安装(自动激活)
dsh plugin --profile web add link:$(pwd)

- lib/index.js — host 端（Node）：API 路由、更新/回退执行管线、stash / 冲突处理、自动回滚、自动重启。
- lib/client.js — 浏览器端（classic script，零构建）：侧边栏按钮 + 更新面板 + i18n。
- package.json — 声明 dsh.bundle（携带 cordis.patch.yml），dsh plugin add 一步激活。
- 改 host 端需重启 dsh web 生效；改客户端改源码即生效（link: 安装），硬刷新页面即可。

版本历史 Changelog

最新版本 v1.7.0（Windows 默认回到「进程内更新」：windowsDetachedUpdate 默认由 true 改为 false——更新全程在同一进程内执行，面板持续显示实时进度、不再中途断开刷新，想继续看到「页面变空白/进度可见」的旧体验直接可用；需要绕开 node_modules 文件锁时再显式设 true 启用后台分离模式）。完整逐版本记录见 CHANGELOG.md。

License

MIT © Zhucy123