空间回收 was35/dsh-reclaim

dsh-reclaim

审计并安全回收 DeepSeek Harness 永久占用的磁盘空间。
审计并安全回收 DeepSeek Harness 永久占用的磁盘空间。

DSH 插件。功能已完成，尚未发布到 npm——安装方式见下方「安装」。

为什么有这个项目

DSH 官方明确不回收附件。@deepseek-ai/dsh-attachment-local 的 README 原文：

Images are kept forever — stored images are never deleted automatically, and nothing collects unreferenced objects.

官方也说明了推迟的原因：

Retention and garbage collection are deferred because resumed and forked sessions may share immutable objects …

也就是说，这不是漏做，而是一个需要先解决正确性问题的功能。dsh-reclaim 把它做出来，并且尊重官方指出的那条约束。

它做什么

- 审计会话、附件、可重建缓存各自占了多少、还有谁在用
- 按分档规则给风险分级：安全（可批量清理）/ 需确认（逐个查看）/ 危险（不可清理）/ 未分类（只报告）
- 清理不是删除：数据搬进插件自带的隔离区，可随时恢复。唯一不可恢复的动作，是你在界面上对某一批明确选择彻底清空——它只销毁隔离区里已经搬进去的批次，不碰活数据
- 只读的 Agent 审计工具（模型能查、不能删）

安装

装进一个带 web 层的 profile（也就是平时用来开界面的那个）：

从 GitHub 安装（尚未发布到 npm）
dsh plugin --profile web add "git+https://github.com/was35/dsh-reclaim.git#main"
dsh web

本仓库尚未提供 Release 包，所以上面那条 git+ 是目前唯一可用的安装路径。将来附上预构建包后，也可以下载后用 file:<路径> 安装——省去 clone 与依赖安装。

装完打开 设置 → 空间回收。

⚠️ 不要装进一个全新的空 profile。 dsh plugin --profile <新名字> add <包> 建出来的 profile 只带 @deepseek-ai/dsh-base，里面没有任何东西提供 web 连接层，插件会一直停在
pending (waiting for service: connection)，宿主启动失败。要用自己的 profile 时，让它包含
@deepseek-ai/dsh-web-app（例如以自带的 web 模板为底），再装本插件。

装好后想确认它在服务，可以直接问它：

curl -b <会话 cookie> http://127.0.0.1:<端口>/api/dsh-reclaim/health

已发布到 npm 时会多一条更短的路径：dsh plugin --profile web add @was35/dsh-reclaim。尚未发布，所以上面那条 git+https:// 才是当前可用的方式。

注意：上游占用的是无 scope 的包名 dsh-reclaim，本仓库改用 @was35/dsh-reclaim，两者互不冲突。
所以 add dsh-reclaim 装到的是上游版本，不是本仓库的改动。

支持的 DSH 版本

DSH 处于 developer preview，官方 README 明确写着「THERE WILL BE COMPATIBILITY-BREAKING CHANGES」。
而且它不强制检查插件声明的兼容范围（engines.dsh / dsh.manifestVersion 官方原话是"仅作声明"，安装器与加载器都不校验）。所以：装得上不等于跑得对，声明范围只能当文档读。

| 支持的 DSH | 状态 | 说明 |
| 0.1.5-rc.1 … 0.1.5-rc.3 | 已验证 | DSH 0.1.5-rc.1 宿主 + 0.1.5-rc.2 依赖包，真实数据 + 真实浏览器 |
| 0.1.7-rc.1 | 已验证 | 独立 home + 0.1.7-rc.1 的完整依赖树（277 个包）。能力探测 7/7 通过；该版本导出 dshCachePath，插件据此自动改选了新布局 cache/attachments/request-images；真实浏览器面板正常 |
| 0.1.6- | 推断，未实测 | 位于两个已验证版本之间，故一并纳入范围；真要依赖它之前建议先验一遍 |
| 0.2.0-rc.2 | 已验证 | 本仓库实测：隔离 home 里的 web profile 装上本插件，能力探测 7 present / 0 missing，request-images 解析到 cache/attachments/request-images，dshCachePathExported: true。npm run test:host 每次都会重跑并断言这三条（以前只是打印） |

版本范围的实现方式值得说明：必须逐 minor 串 OR 子句，
=0.1.5-rc.1 <0.3.0-0 || >=0.1.6-0 <0.1.7-0 || >=0.1.7-0 <0.1.8-0 || >=0.2.0-rc.1 <0.3.0-0。
engines.dsh 与 peerDependencies 里这段文本逐字相同，避免两者漂移。

用 <0.2.0-0 / <0.3.0-0 而不是 <0.2.0 / <0.3.0：prerelease 排序里数字标识符低于字母标识符，所以 0.2.0-0 < 0.2.0-rc.2，<0.3.0-0 把整条 0.3.0 线挡在外面。写成 <0.2.0 会按字面把 0.2.0 排除在外，只因为宿主判定时带 includePrerelease 才侥幸放行 0.2.0-rc.2（详见 docs/safety.md §7.4）。

为什么不写成「看起来更合理」的范围

顺手记在这里，免得后人（包括我自己）把它「简化」回去：

- >=0.1.5-rc.1 <0.3.0-0 不是「任意 0.1.x」。semver 规定：预发布版本只能被同一 major.minor.patch 且自身带预发布标识的比较器放行——所以这一条在 0.1.x 的预发布里只放行 0.1.5-rc.1/2/3：实测 0.1.6-0、0.1.6-rc.1、0.1.7-0、0.1.7-rc.1、0.1.8-rc.1 全为 false，而同一批的稳定版 0.1.6、0.1.7、0.1.8 以及整个 0.2.x 稳定版为 true。想要别的预发布版，就得为它单开一条同 tuple 的子句。
- 同理 >=0.1.0-rc.8 <0.2.0 会只剩 0.1.0-rc.8 一个版本——这正是 dsh-lsp-actions 记录过的 "broke fresh tarball installs"。
- 这条已经真的踩过一次。 曾经有一版把范围「简化」成 >=0.1.5-rc.1 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0，
以为逐 minor 的子句是冗余的。它不是：在默认语义下（任何不传 includePrerelease 的消费者）0.1.6-0、 0.1.6-rc.1、0.1.7-0、0.1.7-rc.1 四版全部落空，而 0.1.7-rc.1 正是上面版本表里列为「已验证」的那一版。
所以 >=0.1.6-0 <0.1.7-0 与 >=0.1.7-0 <0.1.8-0 现在显式写在范围里；>=0.2.0-rc.1 <0.3.0-0 也是同样的理由——0.2.0-rc. 是 tuple 为 0.2.0 的预发布版，只有同 tuple 且带预发布标识的比较器才放行它。

装好之后，一条请求就能看出当前宿主对不对得上——/health 的 capabilities 字段逐项列出本插件依赖的宿主接口在不在（ctx.effect、ctx.connection.fetch.register、ctx.get，以及 sessions / attachments / sessionQuery / tools 四个服务），每项都写明缺了会坏什么。版本对不上时，这是最快的诊断入口。
- 想表达多个 minor 的宿主，只能逐 minor 串 OR 子句，且每出一个新 minor 要手加一句：
=0.1.5-rc.1 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0。
注意每条带止于下一个 minor：写成 <0.2.0 会按字面把 0.2.0 整条线排除在外，写成 <0.3.0 又会悄悄囊括还没验证过的 0.3.x。
- @deepseek-ai/dsh-home-paths 的 latest dist-tag 是过期的旧版本（0.0.1-rc.3），无范围的安装会解析到化石版本。

验证方法（要加新版本时照做）：换 CLI 不够——插件从自己的安装位置解析依赖，所以必须同时让插件拿到那个版本的依赖树（例如在一个独立的 home 里，用该版本的 CLI 启动，并把依赖树一并指向该版本）。判据不能只看「能不能起来」，要看依赖层是否真的换了：要读的判据是 families[<请求图片族>].layout.dshCachePathExported——顶层并没有 layout 对象，照旧写法取值只会拿到 undefined 并误判成「版本不符」（见 docs/safety.md §8.1）。它在 0.1.5 上应为 false、在 0.1.6+ 上应为 true——如果与目标版本不符，说明插件拿到的仍是旧依赖，这次验证不算数。

怎么自己验一遍

仓库自带两层闭环，都不需要额外依赖：

npm test # 单元：node:test，零依赖
npm run test:host # 真宿主在环：装一遍、启一遍、探 /health
npm run test:all # 先单元、后宿主

npm run test:host 默认在 /tmp/dsh-reclaim-verify 下建一个一次性 web profile，跑完删掉； KEEP_HOME=1 npm run test:host 保留它，那个 profile 可以继续用来验别的插件。它不碰 desktop profile，并且自带一道拒绝真实 home 的守卫——把 VERIFY_HOME 指向 $HOME 会被直接拒绝（退出码 2）。

宿主那一层刻意不用测试替身：它证明的是宿主真的接受这份 manifest 与 patch。脚本还会显式断言 stderr 里没有 did not activate——宿主带着一个挂掉的插件条目也能正常启动，不断言这一条就会假绿。

/health 里的路径解析结果也是断言出来的，不只是打印出来给人看：request-images 必须解析到 cache 候选、dshCachePathExported 必须为 true、anomaly 必须为 null。这三条只有这一层验得到——单元那层把 @deepseek-ai/dsh-home-paths 换成了替身，真包的契约它证不了。加这三条之前它们只是三行 console.log，而 ok 与 capabilities 由后端能力探测产生，路径解析出错不会让它们变红，所以布局回归能在这一层一路绿着过去。

顺带说明为什么以前没有测试：lib/ 里唯一的裸 import 是 @deepseek-ai/dsh-home-paths，它只存在于宿主的 asar 内，所以在宿主体外一个模块都加载不了。test/hooks/ 用一个解析钩子把这一个 specifier 映到测试替身，生产代码一行不改；替身故意不导出 dshCachePath，让默认布局是确定的。

有一处两层都盖不到，写在 docs/safety.md §9 第 9 条：canonicalizeWatchPath 只在真的移动或还原时才被调用，而 /health 不会走到它，所以它在真包上的契约目前无人验证。

它凭什么判断

引用关系只认结构化字段，不在日志文本里搜哈希。 判定相对于「这一批保留下来的东西」，并遵循一条硬规则：

只要有任何一个会话的引用关系读不出来，「孤儿附件」这一档就整体暂停。

宁可少删，不可删错。完整的分档判定规则、安全保证与已知边界见 docs/safety.md；该文档第八节逐条记录了代码与本文档已知的出入——其中 §8.5（「危险」档只在界面成立，且第一版修复在引用图只读出一半时失败开放）与 §8.6（两条纵深防御守卫从未生效）已在本仓库修复并留档，仍然成立的是 §8.8：分级里标成「可批量清理」的附件与缓存字节，目前没有任何通路会真正释放。改动前先读那一节。

同一节还记下了修复之后的代价，因为它们是有意选择的：一条删除现在会多读一次引用关系（缓存命中时为零），被别的会话引用的会话会被服务端直接拒绝搬走，引用关系读不出来或没能证明读完时也拒绝——宁可少删，不可删错。

不做的事

不清理日志 / 备份目录 / 附件存储之外的临时文件（附件存储自己的原子写暂存区 attachments/v1/tmp 属于可重建残留，会清）；不管理 profiles/ 下的插件依赖；不做定时自动清理；不允许模型替用户删数据；不支持远端 / 共享存储后端。

上面这些不是设计目标，而是已经实现的行为：所有破坏性操作都要人在界面上明确确认，Agent 侧只有只读工具。

许可

MIT