前言¶
在 DSH（DeepSeek Harness）里跑智能体，会话和附件会长期留在本机：附件按内容寻址存储，同一张图被多个会话引用时磁盘上只有一份实体。界面里可以把会话标成「已归档」，但 DSH 核心的 sessionPersistence 与 attachments 并没有对外提供「删除会话」这类 API，想真正从磁盘清掉已归档对话，只能自己按规则改索引、动文件，还要避免误删仍被其他会话引用的附件。
dsh-archived-chat-cleanup 是社区插件（维护者 Htao-uu，目录分类 admin-security），专门处理「只删已归档会话 + 引用感知的附件垃圾回收」，并把整次操作做成可回滚、可崩溃恢复的事务。下面介绍它的定位、行为与用法；安装命令与参数均来自项目 README。
这是什么¶
一句话：删除已归档会话，级联其子代理子会话，扫描全库 sha256: 引用后只移除无人再用的附件实体，并清理 request-images 派生缓存；索引更新走运行中的服务，文件移动带 journal，失败可回滚。
包名：dsh-archived-chat-cleanup（npm 公开发布，许可证 MIT，要求 Node.js >= 20）。同一安装包内包含 Host 半（模型工具与 Remote API）和浏览器半（已归档会话「…」菜单项）。
- 目录页：skillhub 插件条目
- 源码与说明：GitHub 仓库
它解决什么问题¶
DSH 附件是内容寻址的：删除某个会话时，不能把它日志里出现过的 sha256:<64hex> 对应对象一律删掉，必须先确认是否还有存活会话（磁盘上的会话目录 + 内存里 live 的会话）在引用。
本插件只接受目标在 workspaceRegistry.archivedSessionIds 中的会话；非归档直接拒绝（session-not-archived）。它补齐了「安全删除已归档数据」这一环，避免手工删目录时被 workspaceRegistry 等内存缓存写回，或误删仍被引用的附件。
一次删除在做什么¶
一次删除调用按 README 描述的顺序执行，要点如下。
- 归档校验：目标必须在已归档集合里，否则中止。
- 运行中会话：
one模式若目标是 live 会话则整体拒绝（target-live）；all模式会跳过 live 及其子会话并在结果里报告（skippedLive），不删正在写的日志。 - 级联：递归包含目标下的子代理子会话，避免内部会话继续「永久引用」附件。
- 收集引用：完整读目标（及级联）会话日志中的
sha256:；再扫描除目标外的所有现存会话。 - 判定与删附件：仅当某附件哈希不再被任何存活会话引用时，才删除
attachments/v1/objects/、file-objects/、files/等实体；仍被引用则只随目标会话日志消失而去掉这条引用。任一存活会话日志读失败则整次操作 fail-closed 中止。 - 派生缓存：清理
<cacheRoot>/request-images与遗留的attachments/v1/request-images（按源对象与请求尺寸派生，无法精确归属单会话，看图时会自动重建）。 - 删会话与索引：会话目录、
session_projcache、message_feedback、workspace 归属与归档集合等，通过活着的服务/域更新，不直接手改易被缓存覆盖的索引文件。
事务与回滚¶
操作分三阶段：先把待删路径 rename 到隔离区并写 journal；再改索引（先快照原值）；成功后清空隔离区。任一步失败则先回滚索引，再逆序恢复文件。进程崩溃后下次启动会扫描 journal 恢复未完成事务；路径若不在会话根/附件根/缓存根内则 unsafe-path 中止。插件数据目录为 DSH_HOME/plugin-data/archived-cleanup/（含 transactions/、reports/）。
安装与启用¶
推荐在 DSH 插件管理器中输入包名 dsh-archived-chat-cleanup，或使用 CLI（与 README 一致）：
dsh plugin --profile web add dsh-archived-chat-cleanup
安装或升级后需要重启宿主，模块缓存按包说明符生效。本地开发可从源码目录安装：
dsh plugin --profile web add <插件目录的绝对路径>
安装前请自行查看仓库源码与 MIT 许可证；插件以当前 DSH 进程权限读写会话与附件目录。
典型用法¶
安装后有三个入口，行为相同的事务内核。
| 入口 | 说明 |
|---|---|
| 会话「…」菜单 | 仅在该会话已归档时显示「删除已归档会话…」（order 500）与「清理全部已归档会话…」（order 501）；需点两次才执行 |
模型工具 delete_archived_session |
参数 { mode: "one"\|"all", session_id?, dry_run?, confirm }；dry_run: true 只输出计划；真正删除需 confirm: true |
Remote 命名空间 archivedCleanup |
archivedCleanup/status、/preview、/deleteArchived，参数 { mode, sessionId, confirm } |
建议先 dry_run 或走 preview，确认计划后再 confirm: true 执行删除。
路径回退约定（README）：会话根 ctx.sessionPersistence.root（回退 Loader 配置或 DSH_HOME/sessions）；附件根 ctx.attachments.root（回退 DSH_HOME/attachments/v1）；派生缓存 ctx.attachments.cacheRoot（回退 DSH_HOME/cache/attachments）。
适用场景与注意¶
适合需要定期清理本机已归档对话、并希望附件按引用安全回收的 DSH 使用者。不适合用来删未归档会话，也不应在未确认 dry_run 结果的情况下批量 all 删除。
注意：all 会跳过当前 live 的已归档项以外的冲突场景以保护正在写的会话；若 journal 出现 rollback-incomplete，需人工查看 plugin-data/archived-cleanup/transactions/。社区目录站点与 DeepSeek / 幻方无官方从属关系，插件质量与维护节奏以仓库与维护者为准。
结尾¶
dsh-archived-chat-cleanup 把「只动已归档」「引用感知附件回收」「可回滚事务」绑在一次调用里，弥补 DSH 核心未提供会话删除 API 的空缺。进一步了解行为与测试说明见 GitHub README；在生态目录中检索见 skillhub 条目。
