NokorinNishikino/kidai-snapshot-guard

💾 Kidai Snapshot Guard · 纪代快照守护

DSH 内部的自动备份管家 —— 关门前保存 · 开机后确认 · 一键回滚

简体中文 · English

✨ 为什么用？

DeepSeek Harness（DSH）的配置改动（装插件、更新、启停）一旦让 DSH 起不来，
最需要的是「改之前的样子」。纪代快照守护在 DSH 内部自动完成快照的
「保存 → 确认 → 恢复」闭环，并与外部的 Kidai Plugin Remote
共享同一份存储——DSH 起不来时，外部管理器照样能回滚。

- 💾 关闭前自动保存 —— 每次 DSH 正常关闭都保留一版最近良好快照
（配置 + 设置 + 第三方插件目录），滚动保留最新 3 份
- ✅ 开机自动确认 —— 每次成功启动，把待确认快照转为「已验证」（保留到下次成功运行）
- 📦 单 zip 备份 —— 整个快照一键导出 / 导入 / 恢复为一个离线 zip——DSH 起不来也能恢复
- 🔄 隔离自动恢复 —— 外部管理器的「一次性隔离」被打断时，下次启动自动还原隔离前配置
- 🔔 启动通知 —— 「纪代备份」页顶部显示启动成功 / 自动恢复提示
- 🧩 兼容读取 —— 兼容读取并恢复 dsh-plugin-guard 回滚与 dsh-config-manager 快照
- ✏️ 快照备注 —— 给任意快照加备注便于分辨（与外部管理器双向同步）

装好即用 —— 随 DSH 启动，无需任何操作；打开「设置 → 纪代备份」即可管理。

🚀 快速开始

安装

方式一：GitHub 直装（发布后可用）
dsh plugin --profile desktop add github:NokorinNishikino/kidai-snapshot-guard

方式二：本地开发（从 kidai-plugin-remote 仓库目录）
powershell -ExecutionPolicy Bypass -File scripts\install-guard.ps1

重启 DSH 后生效，打开「设置 → 纪代备份」即可使用。

卸载

dsh plugin --profile desktop remove kidai-snapshot-guard

或手动清理：从 profiles/desktop/package.json 移除 kidai-snapshot-guard
的依赖与 bundle 声明，再删除 node_modules/kidai-snapshot-guard 目录。

独立使用：KSG 是完全独立的备份插件，不需要 Kidai Plugin Remote 也能
自动快照、导出、恢复；外部管理器只是额外的外部回滚入口（DSH 起不来时用）。

然后在 DSH 内：

- 打开 设置 → 纪代备份 —— 管理快照、导出/导入、容量配额。
- 或用 /kidai-snapshot 斜杠命令查看只读摘要。

🔗 生态

| 仓库 | 职责 | 运行位置 |
|---|---|---|
| kidai-snapshot-guard（你在这里） | 快照、待确认→已验证、隔离恢复 | DSH 内部（插件） |
| kidai-plugin-remote | 外部管理与回滚界面 | DSH 之外 |
| kidai-plugin-remote-client | 同一管理器，原生窗口，零依赖 | DSH 之外 |

快照存储（$DSH_HOME/.kidai-snapshots）与守护目录（$DSH_HOME/guard/）
两端共享：在这里保存的快照，外部管理器同样可见、可回滚；反之亦然。

📸 技术细节

- 关闭时 — dispose 效果在关闭流程等待期间拍全量快照（配置 + 设置 +
第三方包目录）；同步的 exit 事件轻量快照（配置 + 设置，不含包目录）作为
兜底；30 秒内去重，一次关闭 = 一份快照。
- 启动时 — 待确认快照转为 verified；维护滚动 known-good 快照
（固定 id），profile 插件集变化时（30 秒监视器）刷新。
- 一次性隔离 — 读取外部管理器的隔离标记；若本次启动的 DSH 不是管理器
spawn 的那一个（PID 不匹配：管理器被杀，或直接从快捷方式启动），则还原
隔离前配置并清除标记——隔离只影响一次启动，无论谁启动 DSH。
- API — DSH webServer 上的 /api/kidai-snapshot/：status / list / save /
known-good / delete / export / exports / import / restore / foreign /
foreign-restore / settings / quota / meta / notice / note。
- 宿主友好 & 防御式 — 每个操作都有包裹，守护插件永远不会拖垮启动，
也不会阻塞关闭超过限定时间。

kidai-snapshot-guard/
├── lib/
│   ├── index.js    # 插件入口：启动钩子、关闭钩子、路由注册
│   ├── backup.js   # 快照引擎：创建/导出/导入/恢复、配额、隔离标记
│   ├── api.js      # webServer 路由 /api/kidai-snapshot/
│   └── client.js   # 「设置 → 纪代备份」页面（注入 DSH 设置区）
├── cordis.patch.yml
└── package.json    # dsh bundle 清单

📄 License

MIT