@dsh-external/dsh-plugin-backup

Readme

# dsh-plugin-backup

一键导出 / 还原 DSH（DeepSeek Harness）已安装插件为 JSON 快照。浏览器设置页面板操作，零 patch，完全基于官方机制。

## 功能

- **一键导出**：把当前已安装的第三方插件（bundle 层栈 + insert 行 + 启停标记）、**自定义技能（`~/.dsh/skills/`）**和**配置文件（`~/.dsh` 根下，含 API Key / 模型提供商）**导出为 JSON 快照，浏览器下载 `dsh-plugins-<时间戳>.json`
- **一键还原（增量）**：从 JSON 快照还原——已安装的自动跳过，缺失的重新安装（bundle 进层栈重启生效 / 非 bundle 写 insert 行配置 HMR 实时挂载；技能与配置按原路径写回，凭据文件写 0600）

> ⚠️ **安全警告**：导出的 JSON **包含 API Key 等敏感凭据**（`.credentials.yaml` / `settings.yaml` / `qvl-vision.json`）。请将备份文件保存在安全位置，**切勿上传公开仓库或分享**。面板导出前会弹窗确认。

## 安装

```sh
# 方式一：CLI（装进 web profile，重启 web 生效）
dsh plugin --profile web add github:Eicbro3ding/dsh-plugin-backup

# 方式二：浏览器「插件」面板输入同样的源串
```

## 使用

1. 设置 → **插件备份**
2. **导出 JSON**：浏览器下载当前插件 + 技能清单快照
3. **导入还原**：选择之前导出的 JSON 文件，逐项显示 `已安装 / 已跳过 / 失败`

## 快照格式（version 3）

```json
{
  "version": 3,
  "exportedAt": "2026-08-15T05:34:47.411Z",
  "plugins": [
    { "name": "@dsh-external/dsh-usage-meter", "kind": "bundle", "source": "link:C:/Users/yanzh/dsh-usage-plugin", "id": "dsh-usage-meter", "disabled": false },
    { "name": "dsh-xxx", "kind": "plugin", "source": "dsh-xxx", "id": "dsh-xxx", "disabled": true }
  ],
  "skills": [
    { "name": "find-plugins", "root": "dsh", "files": [{ "path": "SKILL.md", "content": "..." }, { "path": "scripts/search-topic.mjs", "content": "..." }] }
  ],
  "config": {
    "files": [
      { "path": ".credentials.yaml", "content": "..." },
      { "path": "settings.yaml", "content": "..." },
      { "path": "qvl-vision.json", "content": "..." }
    ]
  }
}
```

`source` 即当时安装用的源串（`github:user/repo#ref` / `link:本地路径` / 版本号），还原时直接 `pnpm add <source>`。技能/配置文件为文本时存原文，二进制转 base64（`encoding: "base64"` 标记）。`config.files` 为 `~/.dsh` 根下全部配置文件（不含 `profiles/` 子目录，不含 `.anonymous-user-id`）。

## 原理

- 安装态来源：web profile 的 `package.json`（`dependencies` + `dsh.profile.bundles`）与 `cordis.patch.yml`（insert 行 + disabled 标记）
- 还原执行与 plugin-console 相同的官方机制：`pnpm add` + 层栈 reconcile + patch 行写入（配置 HMR 实时挂载）
- 官方/内置插件（`@deepseek-ai/*` 等）不导出、不还原；本地路径源跨机器还原会明确报失败
- 零 patch：不修改任何官方代码

## 开发

```sh
node --check lib/index.mjs && node --check lib/index.js
node tests/smoke.js   # 冒烟测试：导出 + 还原边界分支（只读，不装不删）
```

## 参考

- [plugin-console](https://github.com/vlln/plugin-registry/tree/main/packages/plugin/console)：同机制的插件管理控制台（本插件的实现参照）