@mzzsfy/dsh-maintain 0.5.2

package/README.md

@@ -0,0 +1,55 @@
+# @mzzsfy/dsh-maintain
+
+DeepSeek Harness 设置页插件:版本与进程运维一体化——监测 npm 新版本、一键升级、安全重启。
+
+设计文档见 [docs/design/dsh-maintain.md](../../docs/design/dsh-maintain.md)。
+
+## 功能
+
+- 版本监测:host 启动即检查一次,按轮询间隔重复检查(内存快照,不持久化);当前版本与追踪通道最新版对比,落后即提示。定时轮询为软依赖:宿主 timer 服务不可用时仅停用自动轮询,面板显示降级提示,手动检查与升级能力不受影响。
+- 追踪通道:在 npm dist-tags 间切换(latest / next / alpha 等,选项由检查结果动态生成),切换后按新通道判定。
+- 一键升级:两段式确认后按自定义命令模板执行,`{tag}` 执行时替换为追踪通道;命令可在设置面板直接查看与编辑,升级期间串行化(含跨进程锁文件:宿主被外部重启后,残留升级子进程的锁在有效期内仍拒绝新升级),超时 10 分钟强杀;升级后台执行,触发后可离开页面,右下角浮条持续提示进度,完成或失败时替换为结果提示,长时间无进展转提示刷新,回到页面即可重启生效;升级完成后自动重新检查版本。Windows 下升级报 EBUSY/EPERM 多为杀毒软件或索引服务锁定全局目录文件,稍候重试;超时强杀意味着安装可能只完成一半,重启宿主前先确认命令需否重跑。
+- 面板设置编辑:升级命令、轮询间隔、镜像地址均可在面板直接编辑保存,与 settings.yaml 等效(轮询间隔保存即重排,镜像地址保存即重查);host 侧拒绝空命令、非 http(s) 地址与带查询串/锚点的镜像地址(拼接 dist-tags 路径时 query 会吞掉路径),面板清空输入即恢复对应默认值。
+- 操作反馈:检查更新、通道切换、面板保存与升级触发的失败经全站浮出通知(@mzzsfy/dsh-toast)提示;页面加载失败与重启超时等状态提示仍在面板内展示。
+- 安全重启:两段式确认后 host 优雅退出(`appExit`,5 秒兜底强制);重启指令在响应发出后延迟执行,退出调度与响应冲刷解耦,客户端断连不影响宿主退出,浏览器先收到回执进入重启等待态;确认后面板立即提示重启进行中,轮询探测宿主恢复,且主文档连续多次探测可加载(宿主页面服务 fallback 已就绪并稳定)后再稍候片刻才刷新页面,避免启动窗口内刷新拿到 404,总时长 30 秒,超时提示转人工检查。动作路由带跨源守卫(Origin 与 Host 不符即 403,阻断跨站简单请求),与外层鉴权插件(如 dsh-web-startup-auth)互补;未部署鉴权插件时同源请求仍匿名可达。
+
+## 安装
+
+```sh
+dsh plugin --profile web add @mzzsfy/dsh-maintain
+```
+
+标准插件安装:包进入 profile node_modules(pnpm 标准布局,声明的 peer 由虚拟层链入),bundle patch 随下次 dsh 重启自动生效,无需手动编辑 cordis.patch.yml。
+
+发布前开发安装(拷贝进 store,行为与 registry 安装一致):
+
+```sh
+dsh plugin --profile web add file:./packages/dsh-maintain
+```
+
+注意:勿用 `link:` 或裸相对路径——那是符号链接模式,realpath 后 peer 从仓库目录解析会失败(这正是早期"必须手工拷贝部署"结论的成因,对标准安装不成立)。
+
+## 设置(settings.yaml,热加载)
+
+```yaml
+maintain:
+  channel: latest                                # 追踪通道,选项以检查返回的 dist-tags 为准
+  pollIntervalSec: 21600                         # 轮询间隔秒,仅正数启用周期检查,0/负数禁用
+  upgradeCommandTemplate: npm install -g @deepseek-ai/dsh@{tag}   # 可整体自改为任意命令,亦可在设置面板编辑
+  registryBase: https://registry.npmjs.org       # 官方源不可达时可改为镜像地址
+```
+
+升级命令、轮询间隔、镜像地址三项亦可在设置面板"版本与运维"页直接编辑保存(等效 settings.yaml,热生效)。
+
+## 重启须知
+
+- 重启依赖托管常驻(pm2 / systemd / nssm / Docker 等)自动拉起;手动终端启动的进程不会自动恢复。重启判定为三信号:失联恢复、宿主进程启动时刻(bootAt,容器内 pid 恒 1 场景的可靠信号)或 pid 变化。
+- 确认重启后本页以严格顺序轮询探测宿主恢复(任意时刻至多一拍在途),主文档连续多次探测可加载(页面服务就绪并稳定)后稍候片刻才整页刷新;面板后台探测请求失败或拿到 404 均属宿主退出与启动窗口的中间态,面板保持等待提示。重启请求本身收到明确 HTTP 回绝(如升级互斥 409、appExit 缺失 500)时立即提示失败,不进入等待轮询。若你手动刷新后浏览器显示 404,说明宿主仍在启动窗口内,稍候数秒再次刷新即可。轮询总时长 30 秒,超时通常是宿主未被进程管理器拉起(手动终端启动)、退出失败或启动过慢,请检查进程管理器后手动刷新排查。
+- 重启不检测运行中的 agent:最多 5 秒后强制退出,任务中断;会话已持久化,重开后可 resume。
+- 升级进行中重启请求被拒绝(409):升级子进程会在宿主退出后继续存活完成安装,此时重启会导致二次升级并发写全局目录,等待升级完成后重试。
+
+## 开发
+
+```
+cd packages/dsh-maintain && npm test
+```

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# The maintain bundle patch: inserts the version-monitor + upgrade + restart
+# plugin into the profile root as one entry. Applied by `dsh plugin add @mzzsfy/dsh-maintain`;
+# the row id addresses this plugin's host half, whose `/api/maintain/*`
+# routes serve the browser half rendered in the settings page.
+
+- insert:
+    - id: maintain
+      name: '@mzzsfy/dsh-maintain'

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@mzzsfy/dsh-maintain",
+  "description": "DSH 自身的版本管理:追踪 npm dist-tag 新版本、一键升级、安全重启",
+  "version": "0.5.2",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "external": [
+        "@mzzsfy/dsh-toast/client"
+      ]
+    }
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "npmPublish": "npm publish --access public --provenance=false --registry=https://registry.npmjs.org"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mzzsfy/dsh-plugin.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@mzzsfy/dsh-toast": "^0.1.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-settings": ">=0.1.2-alpha.2",
+    "@deepseek-ai/schemastery": ">=3.18.0",
+    "react": "^18.2.0"
+  },
+  "files": [
+    "src",
+    "test",
+    "cordis.patch.yml",
+    "README.md"
+  ]
+}