# 借鉴研究（Study of SuCriss/dsh-version-update）

> 目的：学习 SuCriss/dsh-version-update（Apache-2.0，v1.0.6）的机制，把其中确有价值的能力
> 用**全新原创代码**重实现进 dsh-versions，同时保持本项目 MIT 许可干净、零依赖、聚焦 dsh 主程序。

## 许可结论（重要）

- SuCriss 采用 **Apache-2.0**；本项目 dsh-versions 采用 **MIT**。
- Apache-2.0 允许被合入 MIT 项目，但**被复制代码须保留 Apache-2.0 标识并标注改动**，
  且那部分代码继续受 Apache-2.0 约束（对小型插件会造成“双重许可”的模糊）。
- 因此本项目的策略是：**只借鉴机制的“行为与安全不变量”，全部用原创代码、原创结构、
  原创命名实现**。功能思想（快照回滚、单槽安装、策略持久化、定时检查等）不受版权保护；
  只有对方的“具体代码表达”受保护。这样 dsh-versions 保持纯 MIT，无需 Apache-2.0 附带义务。
- 若今后确需直接复制其代码，须在对应文件头标注：`Derived from
  github.com/SuCriss/dsh-version-update (Apache-2.0)；Modified by shangdi178`，并保留其
  LICENSE 与 copyright 通知。

## 借鉴到的有价值机制（将原创重实现）

1. **快照回滚**（最高价值）
   - 升级前：同步、尽力而为地对当前安装目录做全量快照；失败只记日志，绝不阻塞升级。
   - 每个快照目录带 `meta.json`（version + at）；读取侧先校验元数据与 package.json，
     半途复制的残缺快照一律视为不可用，绝不覆盖可用安装。
   - 创建走“临时目录 + 完成后 rename”，避免崩溃残留。
   - 回滚 = 纯本地复制（免 npm、免网络、秒级）；先“改名旧目录”再拷贝，拷贝失败自动还原旧目录。
   - 修剪：优先清损坏快照，再按保留数清最旧的健康快照。
2. **单槽安装 + 升级前先快照**
   - 全进程单槽：同时只有一次全局安装（避免两个 install 竞争同一目录）；并发请求被拒而非排队。
   - sanitize 只接受精确已发布版本；npm 无 shell spawn 以避免命令行注入。
   - 升级前同步先做快照；安装日志尾部截断、可轮询、可断连恢复。
   - dispose 不杀正在运行的 install（半写的全局目录比丢进度更糟）；仅有超时才杀。
3. **策略 / 状态持久化**
   - 用户态策略存用户目录（在会被升级替换的包目录之外），面板可改、升级后仍在。
   - 写入原子（临时文件 + 同目录 rename）；读取宽容（逐字段回退到默认，坏文件绝不挡宿主启动）。
4. **定时自动检查 + 执行时间窗**
   - 每日 checkAt 定时检查；auto 模式在窗外“泊车”等待，窗开启自动续装（纯函数决策，可测）。
5. **重启交接（跨平台）**
   - 三步：payload 文件（不依赖 argv 引号）→ 脱离父进程的 relaunch 助手等旧 pid 消失、端口释放
     后原样拉起（沿用原 `--profile/--port/--patch`）→ 页面 watchdog 等新进程应答后自动 reload。
   - 可选：重启后新进程不可达时，助手用上一版本快照自动恢复再拉起。

## 不采用 / 本项目的取舍

- 本插件保持 **零依赖、单文件核心、聚焦 dsh 主程序**（SuCriss 是 13 模块 + react/schemastery peer 依赖）。
- 保留我们已有的 **Windows 打磨**（robocopy 备份回滚、npmmirror 双源、HTTP 端口探活、netstat 回退）
  作为稳健的默认升级路径，在其之上**叠加快照秒级回滚**。
- 不引入 agent 注入（双方都已移除该想法）。

## 交付范围（计划）

详见相应 CHANGELOG 条目。核心新增：快照秒级回滚 + 升级前自动快照 + 单槽安装 + 回滚/快照 UI。