isayrhythm/dsh-plugin-repo-snapshot

dsh-plugin-repo-snapshot

给 DeepSeek Harness（DSH）用的工作区加密快照备份插件。

把当前项目（含 .git）打包、加密，然后存到你自己的目录或你自己的阿里云 OSS 里。解密私钥只留在本机，任何时候都不上传。设置页里可视化配置，可随时开关。

.env / .git / 源码历史 / 全局配置，通通上传阿里云 OSS

为什么需要它

AI 编程工具把工作区内容传到云端，这件事本身可以是有价值的（对话级回退、跨设备恢复）。问题在于怎么做：

| | 静默上传 | 本插件 |
|---|---|---|
| 是否告知 | 不告知 | 设置页明确展示目标位置 |
| 是否可关闭 | 无法关闭 | 一键开关 |
| 加密密钥归属 | 服务端持有，用户无法解密 | 本机私钥，服务端拿不到 |
| 敏感文件 | 照样打包（甚至给 .git 开绿灯放行） | 默认拦截，并报告拦截数量 |
| 数据去向 | 厂商服务器 | 你的目录 / 你的 bucket |
| 上传了什么 | 看不到 | 每次快照都提示文件数与跳过数 |

核心区别不是“传不传”，而是数据最终归谁控制。

功能

- 加密快照：AES-256-GCM 加密归档，AES 密钥用本机 RSA-4096 公钥封装（RSA-OAEP-SHA256）
- 两种目的地：本机目录 / 阿里云 OSS（零 SDK 依赖，用官方 V1 签名直接 PUT）
- 设置界面：DSH 设置页内置「仓库快照备份」分区，可开关、填 OSS 参数、测试连接、立即备份
- 敏感文件拦截：.pem / .key / id_rsa / *_rsa / .env / .npmrc / .git-credentials / .ssh 等
- 跳过即报告：敏感、超大、被排除的文件都会计数并在对话里说明
- 内容未变则跳过：避免重复上传相同内容
- 包含 .git：可保留完整提交历史，也可关掉

安装

从 npm / GitHub

dsh plugin --profile web add dsh-plugin-repo-snapshot

包内声明了 dsh.bundle.patch，安装时会自动把插件行插入 composition，无需手工改配置。

从本地目录（开发）

cd           # 例如 ~/.dsh/profiles/web
pnpm add link:/path/to/dsh-plugin-repo-snapshot

然后在 profile 的 cordis.patch.yml 里挂载：

- insert:
- id: repo-snapshot
name: dsh-plugin-repo-snapshot

改完必须重启 dsh web：插件本体是 ESM 模块、客户端 bundle 也只在启动时加载，热重载不会重新导入它们。

依赖

只需 archiver（打包）；OSS 上传用 Node 内置 fetch + node:crypto 自行签名，不依赖 ali-oss。

npm install

使用

重启后打开 设置 → 仓库快照备份。

1. 启用 开关决定是否创建快照
2. 存储位置 选「本机目录」或「阿里云 OSS」
- 选 OSS 时填 Region（如 oss-cn-hangzhou）、Bucket、AccessKey ID、AccessKey Secret
- 建议用只有该 bucket 写权限的 RAM 子账号
3. 点 保存并测试连接 验证配置（会在目标位置写入并删除一个探针文件）
4. 点 立即备份一次 立即生成一份快照；也可等会话开始自动触发

阿里云 OSS 建议

- 权限策略最小化：只给目标 bucket 的 PutObject / DeleteObject
- 想让密钥不落盘？把设置页的 AK/SK 留空，改用环境变量：

export ALIYUN_OSS_ACCESS_KEY_ID=LTAI...
export ALIYUN_OSS_ACCESS_KEY_SECRET=...

快照长什么样

/////
├── snapshot.tar.gz.enc    # 加密后的归档
└── snapshot.key.enc       # 被本机公钥封装过的 AES 密钥

归档内部：

manifest.json              # 时间、工作区、文件清单、跳过统计
files/        # 真实文件内容

加密格式

"RSNAP2" | 算法(1B) | IV长度(1B) | IV | 认证标签长度(2B, BE) | 标签 | 密文

- 算法 1 = AES-256-GCM（默认，带完整性校验），2 = AES-256-CTR
- AES 密钥随机生成，用 /repo-snapshot/keys/public.pem 封装
- 私钥只在本机：/repo-snapshot/keys/private.pem

恢复

从目的地取回某次快照的 snapshot.tar.gz.enc 和 snapshot.key.enc，然后：

node scripts/decrypt.mjs \
--input  snapshot.tar.gz.enc \
--key    snapshot.key.enc \
--private-key ~/.dsh/repo-snapshot/keys/private.pem \
--output ./restored

Windows 下私钥默认在 C:\Users\\.dsh\repo-snapshot\keys\private.pem。

脚本同时兼容 v1（AES-256-CTR，16 字节 IV 前缀）旧格式。
⚠️ 丢了 private.pem 就无法恢复——这是设计使然，没有任何后门。

配置参考

设置页写入 /repo-snapshot/settings.json，优先于 cordis.patch.yml 里的配置。

| 配置项 | 默认 | 说明 |
|---|---|---|
| enabled | true | 总开关 |
| oss.provider | local | local / aliyun |
| oss.region | — | 如 oss-cn-hangzhou |
| oss.bucket | — | bucket 名 |
| oss.prefix | repo-snapshots/ | 对象键前缀 |
| oss.signatureVersion | auto | OSS 签名方案：auto（先试 V4，失败回退 V1）/ v4 / v1 |
| oss.localDir |  | 本机模式根目录；前缀会追加在其后 |
| encryption.enabled | true | 是否加密 |
| encryption.algorithm | aes-256-gcm | aes-256-gcm / aes-256-ctr |
| scan.includeGit | true | 是否包含 .git |
| scan.excludePatterns | node_modules, dist, .venv, … | 裸目录名匹配任意层级 |
| scan.maxFileSizeMB | 5 | 单文件上限，超限跳过并计数 |
| scan.excludeSensitiveFiles | true | 敏感文件拦截 |
| trigger | session-start | session-start / pre-step / both / manual |
| dedupe | true | 内容未变时跳过 |
| maxSnapshotsPerSession | 5 | 防止失控 |
| injectStatusMessage | true | 在对话中提示快照结果 |

HTTP 接口

宿主注册了四个路由，供设置页调用（也可脚本化）：

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /plugins/repo-snapshot/status | 当前配置（密钥已脱敏）、密钥指纹、最近快照 |
| POST | /plugins/repo-snapshot/settings | 保存设置，接受扁平字段名或点号路径 |
| POST | /plugins/repo-snapshot/test | 探测目的地是否可用 |
| POST | /plugins/repo-snapshot/backup-now | 立即备份，可传 workspacePath |

开发

npm install
node --check lib/index.js     # 宿主半边
node --check lib/client.js    # 客户端半边
npm run keygen                # 可选：预生成密钥对

结构：

lib/index.js      # 宿主：扫描 / 打包 / 加密 / 上传 / HTTP 路由
lib/client.js     # 浏览器：settings.section 设置界面
cordis.patch.yml  # bundle patch，声明插件行
scripts/          # keygen / decrypt

客户端 bundle 遵循 DSH 的 window.__ModuleLoader__.load({ id, factory }) 约定，直接写纯 JS 即可，不需要打包器。

安全说明

- private.pem 与 settings.json（可能含 AK/SK）都写在 /repo-snapshot/，已在 .gitignore 中排除
- 私钥文件权限设为 0600
- AK/SK 也可完全走环境变量，不落盘
- 快照只增不减：插件不负责删除旧快照，请自行制定保留策略

故障排查

OSS 报签名错误 / 403

插件默认 signatureVersion: auto：先按 V4（OSS4-HMAC-SHA256） 签名，失败再回退 V1。
两种都失败时，错误信息会同时列出两次尝试的 HTTP 状态与服务端返回，便于定位。

- 若明确知道 bucket 只接受某一种，可在 settings.json 里固定：
{ "oss": { "signatureVersion": "v4" } }

- V4 的凭据作用域使用去掉 oss- 前缀的 region（oss-cn-hangzhou → cn-hangzhou），插件会自动转换
- 403 也可能是 RAM 权限不足：需要目标 bucket 的 PutObject 与 DeleteObject

设置页看不到「仓库快照备份」

客户端 bundle 只在 dsh web 启动时加载，改完插件必须重启；另外确认 profile 的 cordis.patch.yml 里已挂载该插件行。

重启后快照上传到旧位置

设置优先级是 settings.json > cordis.patch.yml。检查 /repo-snapshot/settings.json 是否残留了旧值。

已知限制

- 超过 maxFileSizeMB 的文件会被跳过（有计数提示）；大仓库的 Git pack 文件可能被漏掉，必要时调大该值
- 尚未提供「从 OSS 一键下载并恢复」的脚本，目前从控制台或 ossutil 取回两个文件后跑 decrypt.mjs
- 客户端界面依赖 DSH 的 settings.section Slot，DSH 大版本升级后可能需要适配
- 快照是全量的，每次都会重新打包整个工作区；增量备份尚未实现

License

MIT