dsh-plugin-repo-snapshot

English | 简体中文

给 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 profile 目录>          # 例如 ~/.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

使用

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

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

阿里云 OSS 建议

权限策略最小化：只给目标 bucket 的 PutObject / DeleteObject

想让密钥不落盘？把设置页的 AK/SK 留空，改用环境变量：

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

快照长什么样

<目的地>/<prefix>/<日期>/<会话ID>/<snap_...>/
├── 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 密钥随机生成，用 <DSH_HOME>/repo-snapshot/keys/public.pem 封装
私钥只在本机：<DSH_HOME>/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 就无法恢复——这是设计使然，没有任何后门。

配置参考

设置页写入 <DSH_HOME>/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`	`<DSH_HOME>`	本机模式根目录；前缀会追加在其后
`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）都写在 <DSH_HOME>/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。检查 <DSH_HOME>/repo-snapshot/settings.json 是否残留了旧值。

已知限制

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

License

MIT

dsh-plugin-repo-snapshot

English | 简体中文

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

.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 profile 目录>          # 例如 ~/.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

使用

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

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

阿里云 OSS 建议

权限策略最小化：只给目标 bucket 的 PutObject / DeleteObject

想让密钥不落盘？把设置页的 AK/SK 留空，改用环境变量：

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

快照长什么样

<目的地>/<prefix>/<日期>/<会话ID>/<snap_...>/
├── 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 密钥随机生成，用 <DSH_HOME>/repo-snapshot/keys/public.pem 封装
私钥只在本机：<DSH_HOME>/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 就无法恢复——这是设计使然，没有任何后门。

配置参考

设置页写入 <DSH_HOME>/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`	`<DSH_HOME>`	本机模式根目录；前缀会追加在其后
`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）都写在 <DSH_HOME>/repo-snapshot/，已在 .gitignore 中排除
私钥文件权限设为 0600
AK/SK 也可完全走环境变量，不落盘
快照只增不减：插件不负责删除旧快照，请自行制定保留策略

故障排查

OSS 报签名错误 / 403

若明确知道 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。检查 <DSH_HOME>/repo-snapshot/settings.json 是否残留了旧值。

已知限制

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

License

MIT

isayrhythm/dsh-plugin-repo-snapshot

dsh-plugin-repo-snapshot

为什么需要它

功能

安装

从 npm / GitHub

从本地目录（开发）

依赖

使用

阿里云 OSS 建议

快照长什么样

加密格式

恢复

配置参考

HTTP 接口

开发

安全说明

故障排查

已知限制

License

Community comments

isayrhythm/dsh-plugin-repo-snapshot

dsh-plugin-repo-snapshot

为什么需要它

功能

安装

从 npm / GitHub

从本地目录（开发）

依赖

使用

阿里云 OSS 建议

快照长什么样

加密格式

恢复

配置参考

HTTP 接口

开发

安全说明

故障排查

已知限制

License

Community comments