dsh-plugin-snapshot 0.1.0 → 0.3.5

package/README.en.md

@@ -1,37 +1,95 @@
 # dsh-plugin-snapshot
 
-Pre-upgrade snapshots, one-step rollback and a static health check for DeepSeek Harness plugins.
+**Pre-upgrade snapshots, one-step rollback and a static health check for DeepSeek Harness plugins.**
 
-The built-in plugin_manager already installs, removes and toggles plugins. This plugin adds what it does not: a verifiable recovery point before you change anything, a way back when an upgrade goes wrong, and a clear view of which plugins collide.
+One plugin, three tools.
+
+- npm: https://www.npmjs.com/package/dsh-plugin-snapshot
+- repo: https://github.com/Uesccda/dsh-plugin-snapshot
+- compatible with DSH 0.2.0+ (tested on 0.2.2-rc.1)
+
+---
+
+## What problem it solves
+
+| The trouble you hit | What this does |
+| --- | --- |
+| A plugin upgrade fails halfway: manifests changed, dependencies not installed, unknown state | Takes a snapshot with fingerprint and hashes before upgrading, so you can always go back |
+| Dozens of plugins installed, no idea which collide or whose compatibility claim is stale | One scan reports installed / enabled / missing / incompatible / untested, plus a review priority |
+| No idea which plugins have newer versions, and afraid of auto-upgrading to a beta | Lists updatable items and marks prereleases separately instead of mixing them in |
+
+It deliberately does **not** install, remove or toggle plugins: that is what the built-in plugin_manager is for. Two implementations fighting over the same profile is the most common source of breakage in this ecosystem.
+
+---
+
+## The three tools
+
+| Tool | Does | Writes |
+| --- | --- | --- |
+| plugin_snapshot | create / list / restore snapshots of the profile manifests | only its own data dir, plus the three manifests on restore |
+| plugin_doctor | static diagnostic: install state, author-declared compatibility, duplicate patch ids, missing packages | read-only |
+| plugin_updates | compares the version resolved in pnpm-lock.yaml against the registry | read-only |
+
+---
+
+## Usage
+
+Just talk to the model:
+
+- "Take a snapshot before upgrading my plugins"
+- "Check my installed plugins for problems"
+- "Which plugins have updates available?"
+- "That upgrade failed, roll back to before it"
+
+---
 
 ## Install
 
     dsh plugin add dsh-plugin-snapshot
 
-Restart DSH (or let HMR pick it up), then the three tools are available.
+Restart DSH afterwards. Remove with:
 
-## Tools
+    dsh plugin remove dsh-plugin-snapshot
 
-### plugin_snapshot
+---
 
-Create, list and restore snapshots of the profile manifests (package.json, pnpm-lock.yaml, pnpm-workspace.yaml).
+## What a snapshot contains
 
-Every snapshot carries a manifest with the profile fingerprint, creation time, and per-file sha256. Restoring verifies the fingerprint first, so a snapshot from another profile is rejected; a hash mismatch only warns, because you may have edited the manifest by hand.
+The three profile manifests (package.json, pnpm-lock.yaml, pnpm-workspace.yaml) plus a manifest.json recording the profile fingerprint, creation time, per-file existence and sha256.
 
-### plugin_updates
+Restoring verifies the fingerprint first, so a snapshot from another profile is rejected. A hash mismatch only warns, because you may have edited the manifest by hand.
 
-Read-only version check. Compares the version resolved in pnpm-lock.yaml against the registry and reports updatable / major / uptodate / prerelease / failed / manual. Prereleases are never suggested, and GitHub sources are always flagged for manual review.
+Snapshots do **not** include node_modules. Dependencies must be reinstalled after a restore.
 
-### plugin_doctor
-
-Static diagnostic: declared vs installed vs enabled, author-declared DSH compatibility (an explicit incompatible is reported as incompatible, never as probably fine), duplicate cordis.patch.yml ids, missing packages and unparseable manifests. The returned priority is a rule-weighted score, not a crash probability.
+---
 
 ## Where data lives
 
     ~/.dsh-plugin-snapshot/snapshots/<timestamp>/
     ~/.dsh-plugin-snapshot/logs/
 
-Nothing else is written except the three profile manifests on restore. node_modules and the bundles list are never touched, and DSH is never started or stopped.
+Nothing else is written except the three profile manifests on restore.
+
+---
+
+## Configuration
+
+    {
+      "profileDir": "explicit profile directory (auto-detected when empty)",
+      "snapshotsKeep": 7,
+      "concurrency": 8,
+      "autoUpdate": false,
+      "autoUpdateScope": "patch",
+      "autoExclude": ["package-you-never-want-touched"]
+    }
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| autoUpdate | false | Disabled by default. Set true to check and update 45 s after DSH starts |
+| autoUpdateScope | patch | patch only / minor / major |
+| autoExclude | [] | packages never touched by auto-update |
+| snapshotsKeep | 7 | how many snapshots to retain |
+| concurrency | 8 | registry query parallelism |
 
 ## Limitations
 
@@ -39,6 +97,8 @@ Nothing else is written except the three profile manifests on restore. node_modu
 - Diagnostics are static evidence, not runtime verification
 - No scheduler: the plugin only exists while DSH runs
 
+---
+
 ## License
 
 MIT

package/README.md

@@ -1,84 +1,143 @@
 # dsh-plugin-snapshot
 
-给 DeepSeek Harness 的插件做**升级前快照、一键回滚和静态体检**。
+**给 DeepSeek Harness 的插件做升级前快照、一键回滚和静态体检。**
 
-DSH 官方的 plugin_manager 已经能装、卸、启停插件；本插件只补它没有的那一块：**改动之前先存一份能验身份的恢复点，出问题能退回来，装完之后能看清谁跟谁冲突**。
+一个插件，三个工具。
 
-## 为什么需要它
+- npm: https://www.npmjs.com/package/dsh-plugin-snapshot
+- 仓库: https://github.com/Uesccda/dsh-plugin-snapshot
+- 兼容: DSH 0.2.0 及以上（已在 0.2.2-rc.1 实测）
 
-插件升级失败时最难受的不是报错，而是"清单已经改了、依赖没装完、不知道回到了什么状态"。本插件在每次升级前把 profile 的三份清单（package.json / pnpm-lock.yaml / pnpm-workspace.yaml）存成一份带指纹与哈希的快照，任何时候都能退回去。
+---
+
+## 它解决什么问题
+
+| 你会遇到的麻烦 | 这个插件怎么处理 |
+| --- | --- |
+| 升级插件失败，清单已经改了、依赖没装完，不知道回到了什么状态 | 升级前先存一份带指纹和哈希的快照，任何时候都能退回去 |
+| 装了几十个插件，不知道谁跟谁冲突、谁的兼容声明已经过期 | 一次扫描给出：已装/已启用/缺失/不兼容/未验证，以及检查优先级 |
+| 不知道哪些插件有新版本，又怕自动升到测试版 | 列出可更新项，预发布版本单独标注、不混进"可升级"里 |
+
+它**默认不做**安装、卸载、启停——那是 DSH 自带的 plugin_manager 的事。两套实现打架是插件市场里最常见的坑，这里直接避开。
+
+---
+
+## 三个工具
+
+| 工具 | 做什么 | 会不会写文件 |
+| --- | --- | --- |
+| plugin_snapshot | 创建快照 / 列出快照 / 恢复到某个快照 | 只写自己的数据目录，恢复时覆盖 profile 的三份清单 |
+| plugin_doctor | 静态体检：安装状态、作者声明的兼容性、patch id 冲突、缺失的包 | 纯只读 |
+| plugin_updates | 以 lockfile 解析出的版本为基准，查 registry 有没有新版本 | 纯只读 |
+
+---
+
+## 怎么用（对话示例）
+
+你不用记命令，直接跟模型说：
+
+- **"升级插件前先给我打个快照"** → 调用 plugin_snapshot 的 create，返回快照名
+- **"看看我这些插件有没有问题"** → 调用 plugin_doctor，给出 48 个插件的体检结果
+- **"哪些插件可以升级"** → 调用 plugin_updates，列出可更新项
+- **"刚才那次升级失败了，退回到升级前"** → 调用 plugin_snapshot 的 restore
+
+---
 
 ## 安装
 
     dsh plugin add dsh-plugin-snapshot
 
-装好后重启 DSH（或启用 HMR 时自动生效），三个工具随即可用。
+装完重启 DSH（启用 HMR 时自动生效），三个工具随即可用。
+
+卸载：
+
+    dsh plugin remove dsh-plugin-snapshot
 
-## 提供的工具
+---
 
-### plugin_snapshot
+## 兼容性
 
-快照的创建、列表与恢复。
+本插件声明支持 DSH 0.2.0 及以上，并在 0.2.2-rc.1 实测通过：
 
-- action = "create"：把当前 profile 的三份清单存成一份快照，返回快照名
-- action = "list"：列出全部快照（时间、依赖数、是否带 manifest）
-- action = "restore" + name：恢复到指定快照；恢复前会先自动给现状再存一份
+    0.2.2-rc.1  compatible
+    0.2.1       compatible
+    0.2.0+      compatible
 
-每份快照都带 manifest：profile 指纹、创建时间、每个文件的存在性与 sha256。恢复时会先校验指纹——**别的 profile 的快照会被拒绝**；文件摘要对不上只告警（你可能手工改过清单）。
+如果你在别的 DSH 版本上使用，plugin_doctor 会如实显示为「未验证」而不是假装兼容。
 
-### plugin_updates
+---
 
-只读的版本检测。
+## 快照里存了什么
 
-- 以 pnpm-lock.yaml 里解析出来的版本为基准，去 registry 查候选版本
-- 输出每个插件的状态：updatable / major / uptodate / prerelease / failed / manual
-- 预发布版本不会被建议升级；主版本变更、GitHub 源一律标成需人工确认
+profile 目录下的三份清单：
 
-### plugin_doctor
+    package.json
+    pnpm-lock.yaml
+    pnpm-workspace.yaml
 
-静态体检。
+每份快照额外带一个 manifest.json，记录：profile 指纹、创建时间、每个文件是否存在、每个文件的 sha256。
 
-- 已声明 vs 已安装 vs 已启用，三者分开列
-- 按插件作者声明判定 DSH 版本兼容性：**明确写 incompatible 的判成不兼容，绝不显示成"大概率可用"**
-- 重复的 cordis.patch.yml 行 id、缺失的包、无法解析的清单
-- 给出"检查优先级"（规则加权，不是崩溃概率）
+恢复时会先比对 profile 指纹——**别的 profile 的快照会被拒绝**，避免把 A 环境的清单写进 B。文件摘要对不上只告警，因为你可能手工改过清单。
+
+⚠️ 快照**不包含 node_modules**。恢复之后需要让包管理器重新安装依赖。
+
+---
 
 ## 数据放在哪
 
     ~/.dsh-plugin-snapshot/snapshots/<时间戳>/
     ~/.dsh-plugin-snapshot/logs/
 
-只写这两个目录，以及恢复时写回 profile 的三份清单。不碰 node_modules，不改 bundles 清单，不启动或关闭 DSH。
+只写这两个目录，以及恢复时写回 profile 的三份清单。不碰 node_modules、不改 bundles 清单、不启动或关闭 DSH。
+
+---
 
 ## 安全边界
 
-- plugin_updates 与 plugin_doctor 是**纯只读**：只读文件、只发 GET 请求
-- plugin_snapshot 的 create 只写自己的数据目录；restore 需要显式传 name，且只覆盖三份清单
-- 不实现安装/卸载/启停——那是官方 plugin_manager 的职责，避免两套实现互相打架
+- plugin_doctor 与 plugin_updates 是**纯只读**：只读文件、只发 GET 请求
+- plugin_snapshot 的 create 只写自己的数据目录；restore 必须显式传 name
+- 两个只读工具（plugin_updates、plugin_doctor）只读文件、只发 GET 请求
+- 写操作（快照恢复、更新）会执行 pnpm，但只作用于 profile 中**已安装**的包，
+  只允许升到更高版本，拒绝降级与 dist-tag，并一律带 --ignore-scripts
+- 不结束任何进程
 
-## 配置
+---
 
-可选，写进 profile 的插件配置：
+## 配置项
 
-| 字段 | 默认 | 说明 |
-| --- | --- | --- |
-| profileDir | 自动定位 | 显式指定 profile 目录 |
-| registry | registry.npmjs.org | 检测用的源，也可用 DSH_REGISTRY |
-| dataDir | ~/.dsh-plugin-snapshot | 快照与日志目录 |
-| snapshotsKeep | 7 | 保留份数 |
-| concurrency | 8 | 检测并发 |
+在插件配置里可写：
+
+    {
+      "profileDir": "指定 profile 目录（留空则自动定位）",
+      "snapshotsKeep": 7,
+      "concurrency": 8,
+      "autoUpdate": false,
+      "autoUpdateScope": "patch",
+      "autoExclude": ["某个不想被自动更新的包"]
+    }
 
-profile 定位顺序：配置 > 环境变量 DSH_PROFILE_DIR > ~/.dsh/profiles/desktop > 扫描 profiles 目录取最近修改的。
+| 配置 | 默认 | 说明 |
+| --- | --- | --- |
+| autoUpdate | false | 是否在 DSH 启动 45 秒后自动检查并更新 |
+| autoUpdateScope | patch | 升级档位：patch 仅补丁版 / minor 含次版本 / major 含主版本 |
+| autoExclude | [] | 永不参与自动更新的包名列表 |
+| snapshotsKeep | 7 | 保留的快照份数 |
+| concurrency | 8 | 查询 registry 的并发数 |
 
 ## 已知限制
 
-- 快照只覆盖三份清单，不含 node_modules。恢复之后仍需让包管理器重新安装依赖
+- 快照只覆盖三份清单，不含 node_modules
 - 诊断基于静态扫描与作者声明，不代表运行时验证
-- 不做定时任务：插件只在 DSH 运行时存在
+- 自动更新**默认关闭**：需在插件配置里显式写 autoUpdate: true 才会启用
+- 插件只在 DSH 运行时存在，DSH 关闭期间不做任何事
+
+---
 
 ## 开发
 
-    npm test        # 5 项自测，用 stub 顶替 @deepseek-ai/dsh-tools
+    npm test      # 5 项自测，用 stub 顶替 @deepseek-ai/dsh-tools
+
+---
 
 ## 许可