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 界面语言实时切换。

目录

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

特性 Features

• 🆚 版本对比 — 读取本地 checkout 的 tag / commit,与 origin 的 dsh-v* tags 对比(git ls-remote,只读)。GitHub 直连超时自动切换 gh-proxy.com 镜像;成功结果缓存 60 秒,重复打开秒回。
• 🛡️ 更新前先确认 — 检测到新版本只展示对比与更新内容,绝不自动执行;并醒目提示「更新期间整个页面可能突然变空白」的真实原因(构建阶段会替换网页资源文件),由你点击「开始更新」后才真正动手。
• ⚡ 一条龙更新 — git fetch --tags → 自动暂存本地改动 → git checkout → 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

• 路径统一经 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」按钮;点开可看到版本对比面板而非报错。

常见排障

配置 Configuration

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

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

API 路由 API

安全 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