@zhucy123/dsh-update

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

dsh-update · ⭯ 更新DSH

One-click update for your local DeepSeek Harness (DSH) checkout: compare versions → confirm → pull & rebuild → restart, all from a sidebar panel with live progress.

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

目录

• [特性](#特性-features)
• [界面速览](#界面速览-usage)
• [工作原理](#工作原理-how-it-works)
• [兼容性](#兼容性-compatibility)
• [要求](#要求-requirements)
• [安装](#安装-installation)
• [验证与排障](#验证与排障)
• [配置](#配置-configuration)
• [API 路由](#api-路由-api)
• [安全](#安全-security)
• [开发](#开发-development)
• [版本历史](#版本历史-changelog)
• [License](#license)

特性 Features

• 🆚 版本对比 — 读取本地 checkout 的 tag / commit,与 origin 的 dsh-v* tags 对比(git ls-remote,只读)。GitHub 直连超时自动切换 gh-proxy.com 镜像;成功结果缓存 60 秒,重复打开秒回。
• 🛡️ 更新前先确认 — 检测到新版本只展示对比与更新内容,绝不自动执行;并醒目提示「更新期间整个页面可能突然变空白」的真实原因(构建阶段会替换网页资源文件),由你点击「开始更新」后才真正动手。
• ⚡ 一条龙更新 — git fetch --tags → 按刚拉到的 tag 重算目标 → 核对必需路径 → 自动暂存本地改动 → git checkout <tag> → 删除已消失包残留的 lib/ → pnpm install → pnpm run clean → pnpm run build,以 text/event-stream 流式实时显示每步输出。Alpha tag 仍然可选,不会因为带 prerelease 被默认拒绝。
• 🛡️ 检出前健康检查 — 默认要求目标 tag 里存在 packages/client/ui-context-menu/package.json(提供 contextMenus)。缺少则拒绝检出,并说明继续会让 Web UI 停在 Failed to load plugins / N entries did not activate。确需覆盖时在面板点「仍要检出」,或设 allowMissingRequiredPaths: true。requiredPaths: [] 可关掉这道检查。
• 🧹 构建前强制 clean + 残留 lib/ — 旧版本 gitignore 的 lib/ 在包目录被新 tag 删掉后仍会留在磁盘(典型:旧 ui-context-menu/lib 继续注入 contextMenus)。检出后只删除白名单根目录(packages/、apps/)下「旧树有、新树没有」的包的 lib/;然后 pnpm run clean。clean 失败会中止并回滚,不再当作警告继续 build。
• ✅ 构建后核验 + 启动检查 — install 与 build 都成功只是第一步;自动重启打开时,还要等新进程的启动日志在观察窗口内没有插件加载失败。面板在重启前显示「正在检查启动」,结果写在 dsh-update-apply-*.log,下次打开面板能看到。
• 📄 本次更新内容 — 面板内展示该版本的 GitHub Releases 说明,按 DSH 界面语言显示中/英文段(失败降级为「查看 GitHub Releases →」链接)。
• 🔄 自动重启 + 一键重启 — 更新/回退成功约 2 秒后自动重启 dsh(由服务端定时器驱动,页面已变白/断线也会发生);也可点「重启DSH / 立即重启」手动触发;重启失败(如自动重启未生效)有明确兜底提示。
• ↩️ 版本回退 — 更新后悔了?在「已是最新」结果视图下拉选择任一历史 dsh-v* tag 回退,流程与更新完全一致(目标 tag 白名单 + git rev-parse --verify 核验)。
• 💾 本地改动安全 — 更新前自动 git stash push -u(含未跟踪文件,修复死循环冲突),成功后原样恢复;新版本改到同一文件时改动安全保存在 stash 不丢失,并明确提示;冲突视图提供「自动暂存并继续」。
• 🔙 失败自动回滚 — 已切到新版本后 install / clean / build 失败,或重启后的启动日志出现 did not activate、Failed to load plugins、HARNESS 插件加载失败,自动 git checkout 回原版本并重新 pnpm install、clean、build。构建退出码 0 还不算成功;自动重启打开时,要等启动日志在观察窗口内保持干净。
• ⚠️ 插件 peer 提示 — 更新前扫描 ~/.dsh/profiles/*/package.json、其直接依赖,以及 plugins/ 下的 package.json。Harness / dsh 相关 peerDependencies 罩不住目标版本时(WorkBuddy 一类钉版本),默认停下来列出冲突,确认后才继续。可改为 block 或 ignore。Alpha 不会因此从列表里消失。
• 🔒 并发保护 & 安全边界 — 同一时间只允许一个更新任务(重复触发返回 409);4 个 API 路由全部 loopback-only,仅本机浏览器可触发真实安装;重启路由额外拒绝代理转发。
• 🌍 跨平台 — Windows / Linux / macOS;git / pnpm 缺失时快速失败而非挂到超时,POSIX 无 pnpm 自动回退 corepack pnpm。

界面速览 Usage

1. 启动 dsh web,侧边栏底部、设置按钮上方出现「⭯ 更新DSH」圆形按钮。

2. 点击打开面板:自动检查并显示 本地版本 / 远程版本 / 是否可更新。

3. 有新版 → 预览「本次更新内容」→ 点「开始更新」,或在「指定版本(含 alpha)」里选一个 tag。构建阶段页面可能突然变空白。

4. 构建完成后会重启并检查插件是否加载成功。日志里若出现 Failed to load plugins / did not activate,会自动回到更新前的版本。页面恢复后重新打开面板,可看到上次结果。

5. 已是最新 → 可用「版本回退」下拉换到任一历史 dsh-v* tag(含 alpha),过程与更新相同。

工作原理 How it works

flowchart TD
    A[点击「⭯ 更新DSH」按钮] --> B[GET /api/dsh-update/status]
    B --> C{发现新版 dsh-v* tag?}
    C -- 否 --> D[已是最新<br/>提供「版本回退」]
    C -- 是 --> E[展示 本地 / 远程版本<br/>+ 本次更新内容<br/>「开始更新」按钮]
    E --> F[git fetch --tags<br/>直连失败 → gh-proxy 镜像]
    F --> R[按 fetch 结果重算最新 tag<br/>alpha 仍参与比较]
    R --> P{requiredPaths 都在?}
    P -- 否 --> Q[默认拒绝检出<br/>可显式覆盖]
    P -- 是 --> G[git stash push -u<br/>安全暂存本地改动]
    G --> H[git checkout &lt;tag&gt;]
    H --> OL[删除已消失包的残留 lib/]
    OL --> I[pnpm install]
    I --> J[pnpm run clean<br/>失败则回滚]
    J --> K[pnpm run build]
    K --> L{构建成功?}
    L -- 否 --> M[checkout 回原版本<br/>并重新 install/clean/build]
    L -- 是 --> N[重启并检查启动日志]
    N --> O{did not activate /<br/>Failed to load plugins?}
    O -- 是 --> M
    O -- 否 --> S[本次更新成功]

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

兼容性 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 镜像(可配置更换,见[配置](#配置-configuration))。
• Node.js ≥ 18(host 端使用全局 fetch / AbortController)、git、pnpm(POSIX 无 pnpm 时自动回退 corepack pnpm

…(truncated)