前言¶
DSH 自带的「归档」只是把会话从侧边栏隐藏：会话日志目录、session_projcache 里的投影缓存行、工作区记账和归档标记都还留在磁盘上，而且没有批量删除入口。想回收空间，只能逐个会话找路径手动删。
下面介绍的插件 dsh-archived-purge（维护者 5D-artist，分类 admin-security，许可证 MIT，当前版本 1.1.0）在「设置 → 归档清理」里补上一页：按工作区分组列出全部归档会话，支持全选和逐条勾选，确认后一次删掉所选会话及其本地存储。它只做删除，不改变归档行为本身。
安装¶
官方安装命令如下，直接执行即可：
dsh plugin --profile desktop add github:5D-artist/dsh-archived-purge
Desktop 也可以在「设置 → 插件 → 添加插件」里填仓库地址：
https://github.com/5D-artist/dsh-archived-purge
装好后刷新页面（Host 端通常已热加载，浏览器端 bundle 需要重新加载）。
使用步骤¶
按 README 的流程，删除前不需要手工准备任何文件：
- 打开「设置 → 归档清理」，页面按工作区分组，显示标题、最后活动时间、占用体积。
- 点顶部「全选」或逐行勾选，实时看到已选条数与总体积。
- 点「删除所选」，在弹窗里选择是否一并深度清理，确认。
删除不可撤销。列表不会自动清理任何东西，只有确认后的选中项才会被删。
删除范围¶
| 项目 | 是否删除 | 说明 |
|---|---|---|
| 会话日志目录 | ✅ | <DSH_HOME>/sessions/--<cwd>--/<session-id>/ |
| 投影缓存行 | ✅ | <DSH_HOME>/storages/session_projcache/sessions/<session-id>.json |
| 工作区记账 | ✅ | 公开 API Workspace.detachSession |
| 全局归档集合 | ✅ | workspaceRegistry.unarchiveSession |
| subagent 子会话日志 | ✅ | 仅 origin: 'subagent' 的后代 |
附件 attachments/v1/objects/ |
⚙️ 可选 | 只在没有剩余日志引用时删除 |
| 请求图缩放缓存 | ⚙️ 可选 | cache/attachments/request-images/，可重建 |
| 该批会话写出的工作区文件 | ⚙️ 手动勾选 | 只认 write / edit / present 的路径 |
| fork 出来的普通会话 | ❌ | 只按 subagent 血缘级联 |
深度清理与孤儿附件¶
深度清理是 1.1.0 新增的可选步骤。删除对话框里可以勾选「无人引用的附件」和「请求图缩放缓存」，并逐项勾选该批会话写出的工作区文件。附件存储是内容寻址且不可变的，插件按「先读后删」实现：先读完所有剩余日志收集 sha256 摘要，再删对象；删单个会话后它独占的对象自然成为孤儿。三条规则是读不全就不删、10 分钟内的新对象保留、绝不碰日志之外的索引文件。
工作区文件同理：只列日志里 write / edit / present 的显式目标，必须位于会话 cwd 内，且排除 DSH_HOME、插件自身目录、.git / node_modules，服务端重新扫描核对，默认不勾选。
另有一个独立入口「清理孤儿附件」：不删会话也能执行，先 dry-run 报数字，再确认执行。
安全护栏与失败反馈¶
- 运行中拒绝：用 Host 的
workspace/session-activity瀑布判定，而不是「在内存里就算运行中」。归档只是隐藏会话，最近用过的归档会话仍驻留在ctx.sessions里。 - 整批前置检查：任一目标（含 subagent 后代）仍在运行就整批不删，并说明是哪一类工作（对话 / 任务 / 子代理 / 定时任务）。
- 驻留会话的记账延后回收：文件可以立刻删，但内存中的会话不能立刻从工作区记账里摘掉，否则会掉进侧边栏「未分组」；记账与归档标记保留到下次启动，由
finalizePending()收尾，页面只提示「另有 N 个已删除会话的记账将在下次启动时自动回收」。 - 入口与路径校验：
sessionId必须匹配^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$，POST 校验同源，待删路径必须落在sessions/或投影缓存根内。 - 不重写注册表：归档集合与工作区记账都通过公开 service 方法修改。
- 失败可读：被拒绝或失败时逐条列出会话与原因，不再只弹一句
HTTP 400。
删除接口的状态码约定：400 只用于非法 JSON，403 只用于跨源，405 / 415 用于方法与 Content-Type；「没删成」属于业务结果，用 200 + ok: false + message 表达。
Host 路由¶
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /plugins/archived-purge/state |
归档列表（标题、工作区、体积、最后活动、active / activity / resident） |
| POST | /plugins/archived-purge/delete |
删除选中会话，可选深度清理 |
| POST | /plugins/archived-purge/scan |
只读预演：释放多少附件、缓存多大、产出物清单 |
| POST | /plugins/archived-purge/gc |
孤儿附件清扫，dryRun: false 才真删 |
| POST | /plugins/archived-purge/client-error |
客户端挂载失败上报 |
兼容性与已知限制¶
实测环境：DSH 0.2.1-rc.5（Desktop，Windows）。需要 Host 服务 webServer、workspaceRegistry、sessions、sessionPersistence；存储布局对应 0.2.x 的 v4 会话日志、workspace.json schema v2、session_projcache 单记录文件、attachments/v1/objects。仅 Web 客户端（dsh.client.platform = web）。
已知限制：
- 只能删除归档集合中的会话，活动会话需先归档。
- 附件 GC 是全量扫描，会话越多、日志越大耗时越长。
- 10 分钟宽限期内的附件对象不会被回收。
- 驻留会话的记账在下一次启动时回收（DSH 没有让第三方插件把会话逐出
ctx.sessions的公开接口）。 - 工作区产出物只认
write/edit/present的显式路径，pwsh/ffmpeg等命令产出的文件不在清单里。 - 归档时间不是持久字段，列表用最后活动时间排序。
适用场景与注意¶
适合长期积累会话、磁盘被归档日志占满、需要批量回收的开发者。插件会真实删除本地文件，运行时以当前 DSH 进程的权限执行，安装前应检查源码与许可证（MIT），并确认目标 DSH 版本满足 engines.dsh（>=0.2.1-rc.0）。
源码与维护说明在 https://github.com/5D-artist/dsh-archived-purge；社区目录页在 https://www.skillhub.cn/plugins/5D-artist/dsh-archived-purge。该目录是独立站点，与 DeepSeek / 幻方无官方从属关系。
