dsh-plugin-snapshot 0.3.5 → 0.3.6

package/README.en.md

@@ -1,8 +1,8 @@
 # dsh-plugin-snapshot
 
-**Pre-upgrade snapshots, one-step rollback and a static health check for DeepSeek Harness plugins.**
+**Checks and upgrades your installed DSH plugins automatically — a snapshot before every upgrade, automatic rollback on failure, plus one-click rollback and a static health check.**
 
-One plugin, three tools.
+One plugin = automatic upgrades + three tools + a Settings panel.
 
 - npm: https://www.npmjs.com/package/dsh-plugin-snapshot
 - repo: https://github.com/Uesccda/dsh-plugin-snapshot
@@ -32,6 +32,17 @@ It deliberately does **not** install, remove or toggle plugins: that is what the
 
 ---
 
+## Settings panel
+
+After install, **Settings → Plugin Updates** shows a three-tab panel:
+
+| Tab | Contents | Writes |
+| --- | --- | --- |
+| **Updates** | plugins with changes (updatable / major / prerelease / below-local / incompatible), per-row update, update-all | yes |
+| **Snapshots** | list, create, restore | yes |
+| **Diagnostics** | installed / enabled / missing / incompatible / untested / native counts, conflict table, review priority | no |
+
+All write operations go over same-origin HTTP with three guards: custom header, `application/json`, Origin check; plus a 1.5 s throttle per endpoint.
 ## Usage
 
 Just talk to the model:
@@ -72,6 +83,29 @@ Nothing else is written except the three profile manifests on restore.
 
 ---
 
+## Auto-update
+
+**Disabled by default.** Set `"autoUpdate": true` explicitly to enable it — installing a snapshot tool should not silently rewrite your dependency tree.
+
+When enabled, it runs 45 seconds after DSH starts:
+
+```
+checkUpdates  ->  filter (exclude list + scope)
+  ->  lock probe: drop packages currently held by DSH
+  ->  snapshot
+  ->  per-package install (pnpm add --save-exact --ignore-scripts)
+  ->  four-state verdict: read the on-disk version, trust no exit code
+  ->  layered rollback on failure (package-level / full)
+```
+
+| Mechanism | What it does |
+| --- | --- |
+| **Lock probe** | directory rename + `.node` open probe, removes packages that cannot be replaced |
+| **Four-state verdict** | on-disk version present means success; only NO_MATCHING_VERSION / UNSUPPORTED_ENGINE / FETCH_404 count as failure |
+| **Layered rollback** | partial success reverts only failed items; full failure restores then reinstalls |
+| **Transient retry** | network failures retried at 8s / 30s / 90s; deterministic failures are not retried |
+
+Results are written to `~/.dsh-plugin-snapshot/auto-update.json` and shown at the top of the Updates tab.
 ## Configuration
 
     {

package/README.md

@@ -1,8 +1,8 @@
 # dsh-plugin-snapshot
 
-**给 DeepSeek Harness 的插件做升级前快照、一键回滚和静态体检。**
+**自动检查并升级你安装的 DSH 插件——升级前自动打快照，失败自动回滚；也能一键回滚与静态体检。**
 
-一个插件，三个工具。
+一个插件 = 自动升级 + 三个工具 + 一个设置页面板。
 
 - npm: https://www.npmjs.com/package/dsh-plugin-snapshot
 - 仓库: https://github.com/Uesccda/dsh-plugin-snapshot
@@ -32,6 +32,17 @@
 
 ---
 
+## 设置页面板
+
+装好后，**设置 → 插件更新** 会出现一个三页签面板：
+
+| 页签 | 内容 | 写操作 |
+| --- | --- | --- |
+| **插件更新** | 列出有变化的插件（可更新 / 主版本变更 / 预发布 / 低于本地 / 不兼容），每行可单独更新，右上角可全部更新 | 是 |
+| **快照** | 快照列表、创建、恢复 | 是 |
+| **诊断** | 已装 / 已启用 / 缺失 / 不兼容 / 未验证 / 原生 计数，冲突表与检查优先级 | 否 |
+
+面板所有写操作都走同源 HTTP，并带三重守卫：自定义请求头、`application/json`、Origin 校验；同一接口 1.5 秒内只接受一次。
 ## 怎么用（对话示例）
 
 你不用记命令，直接跟模型说：
@@ -103,6 +114,29 @@ profile 目录下的三份清单：
 
 ---
 
+## 自动更新
+
+**默认关闭。** 需要在插件配置里显式写 `"autoUpdate": true` 才会启用——装一个快照工具不应该静默改整个依赖树。
+
+启用后，DSH 启动 45 秒执行一次：
+
+```
+checkUpdates  →  过滤（排除名单 + 档位）
+  →  占用探针：把正被 DSH 锁住的包剔出本轮
+  →  打快照
+  →  逐包安装（pnpm add --save-exact --ignore-scripts）
+  →  四态判定：回读磁盘版本，不信退出码
+  →  失败时分层回退（包级 / 整体）
+```
+
+| 机制 | 作用 |
+| --- | --- |
+| **占用探针** | 目录 rename + `.node` 读写探测，提前剔掉装不上的包，避免白跑 |
+| **四态判定** | 磁盘版本到位即判成功；只有 NO_MATCHING_VERSION / UNSUPPORTED_ENGINE / FETCH_404 三个致命码判失败 |
+| **分层回退** | 部分成功只退失败项，全部失败才整体恢复，恢复后补 `pnpm install` |
+| **瞬时重试** | 网络类失败按 8s / 30s / 90s 退避重试三次；确定性失败不重试 |
+
+结果写入 `~/.dsh-plugin-snapshot/auto-update.json`，面板「插件更新」页顶部显示上次结果。
 ## 配置项
 
 在插件配置里可写：

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsh-plugin-snapshot",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "type": "module",
-  "description": "Snapshots, one-step rollback, static diagnostics, auto-update with lock probe and four-state verification for DeepSeek Harness plugins.",
+  "description": "Automatically checks and upgrades your installed DSH plugins: snapshot before every upgrade, automatic rollback on failure, plus one-click rollback and static diagnostics.",
   "keywords": [
     "deepseek-harness",
     "dsh",