- ホーム
- プラグイン
- セッションとメッセージ
- dsh-session-cleaner
dsh-session-cleaner
thao712/dsh-session-cleaner
Preview and permanently delete archived Sessions, per-conversation folders, attachments, and workspace files; keep out/ deliverables and clean orphan conversation folders.
インストール
dsh plugin --profile web add github:thao712/dsh-session-cleanerREADME
会话清理 / Session Cleanup
A DeepSeek Harness plugin that previews and permanently deletes archived Sessions together with their per-conversation folders, Session logs, projection checkpoints, unreferenced attachments, spilled tool output, and the files they produced in the workspace. It adds a Settings → Session cleanup page and resolves each Session's real project or conversation folder for one-click inspection.
一个 DeepSeek Harness 插件:在 设置 → 会话清理 中选择已归档的会话,先完整预览,再点击两次确认永久删除。
删除范围
对每个选中的已归档会话,插件会清理:
- 会话专用目录(可选)(session-archive):
<工作区>/conversations/<时间_标题>/,包括work/、out/、session.json与AGENTS.md副本;同时从conversations/index.json移除该会话的映射。会话清理里该选项默认关闭;需要整目录删除时才勾选。若要保留out/,使用独立的“对话目录”清理。 - 会话日志:
<DSH_HOME>/sessions/<项目目录>/<会话ID>/(当前与历史格式文件、锁文件)。 - 投影检查点:
<DSH_HOME>/storages/session_projcache/sessions/<会话ID>.json,并同步session_projcache存储域内存。 - 工作区归档记录:从
workspace域的归档集合、置顶集合和项目sessionIds中移除;不会删除整个工作区或其他会话。 - 仅被这些会话引用的附件:图片对象、文件对象与文件引用硬链接;删除前扫描所有其余会话,仍被引用的附件保留。
- 会话的工具输出溢出目录:
dsh-spill-*根下以session-<sha256(id)[0..12]>命名的目录(包括当前与以往进程的默认根)。 - 会话在工作区产生的文件:来源包括
write/edit/str_replace_editor/present的显式路径,以及会话时间窗内新建文件的目录扫描(用于 shell、Python 等命令生成的中间脚本和最终产物)。会话目录内的文件随目录整体删除,不会重复列出。 - 可选的附件请求缓存:
<DSH_HOME>/cache/attachments/request-images,可重建,不影响其他会话。 - 对话目录清理(独立功能):扫描每个工作区
conversations/下的所有目录,包括会话记录已不存在的残留目录。每个目录可以选:- 保留 out:删除
work/与AGENTS.md副本,保留out/、session.json和其他未知文件; - 全部删除:删除整个目录,并移除
index.json中指向它的条目。 目录清理只处理目录内容,不删除会话日志/附件;会话记录仍用上面的“会话清理”。
- 保留 out:删除
安全模型
- 只处理 当前已归档 且 未被 Harness 加载 的会话。
ctx.sessions里存在 Session 只说明它被加载,不代表正在工作;归档后可能留下空闲 Agent。此时界面显示“已打开(需重启)”,勾选框禁用,必须先重启 Harness(归档状态会保留)再清理,否则删除后会话会以“未分组”残留。 - “运行中”按
ctx.agents.get(id)?.status === 'running'判断,包含等待审批/回答的回合;它与“已打开但空闲”是两个不同状态,分别显示“运行中”和“已打开(需重启)”。 - 预览与执行都由 Host 重新推导候选;浏览器只提交选择项,不能指定任意路径。
- Host 在执行时再次核对:路径必须位于工作区/会话目录内、不是符号链接、路径链上不能有 symlink/Junction、不是目录、不在受保护前缀中。工作区之外的文件、仍被其他会话引用的文件、引用状态未知的文件都不可删除,不是仅仅“默认不勾选”。
- 会话专用目录必须位于某个工作区下,且目录内
session.json的sessionId、workspace、folder与当前会话完全匹配;删除前会扫描其余会话(包括运行中会话的 live events),目录仍被其他会话使用时保留。index.json只移除当前会话的条目,并做读回校验;不会重建或覆盖其他条目。 - 受保护区域:
DSH_HOME的会话/存储/附件/缓存/配置目录、Harness 安装目录、系统目录、用户主目录下的.ssh/.aws/.gnupg/.kube/.config,以及任何session.*.jsonl*/session.json/conversations/index.json/workspace.json/settings.yaml/ 凭据文件。 - 预览会返回短期
previewToken;执行删除必须携带该 token,且 token 绑定会话选择、选项和候选集合。选择或候选发生变化时,必须重新预览。 - 工作区文件默认不勾选:工作区之外的文件、仍被其他会话引用的文件、会话开始前已存在的文件(例如被
edit的既有源码);前两类即使手动勾选也不会被 Host 接受。 - 删除前需要两次点击确认(“永久删除所选内容” → “确认永久删除”);操作不可撤销。
安装
从 GitHub 安装(当前为 GitHub-only 分发,不依赖 npm):
dsh plugin --profile <profile> add github:THao712/dsh-session-cleaner
包名是 dsh-session-cleaner-thao712。Desktop 用户也可以通过 dsh-market 的插件页安装。
本地开发时,把本地仓库绝对路径作为 bundle 安装:
plugin_manager install_bundle target: <仓库绝对路径>
安装完成后刷新页面,打开 设置 → 会话清理。刷新是为了载入新的 Client bundle;Host 路由只接受当前已登录的 Harness 页面请求。
使用
- 勾选要删除的已归档会话。
- 每条会话右侧的 文件夹图标 会优先打开 session-archive 为该对话创建的会话专用目录;没有专用目录时,回退到日志中的
working_directory/文件路径推导出的项目根目录,再回退到cwd或工作区目录。目录已被删除时只回退到仍存在的上层目录,不会创建目录。 - 选择清理范围(附件、工作区文件、时间窗扫描、工具输出溢出目录、图片请求缓存)。会话目录清理默认关闭;需要整目录删除时再勾选“同时整目录删除会话专用目录(不保留 out)”。
- 点击 预览清理,逐项检查路径;可取消任意文件或附件。工作区外、共享引用、引用状态未知的文件会被禁用,不能删除。
- 点击 永久删除所选内容,再点击 确认永久删除。Host 会核对本次预览 token;若预览后选择或候选发生变化,需要重新预览。
- 查看结果报告;若侧边栏仍显示已删除会话,刷新页面。
- 对话目录清理(同一页面下方):勾选要处理的
conversations/<目录>,选择 保留 out 或 全部删除,先 预览目录清理,再两次确认执行。该列表包含没有会话记录的残留目录;已打开(需重启)的目录需要先重启 Harness。
接口与实现
- Host:
dsh-session-cleaner-thao712的index.js,注册POST /dsh-session-cleaner/api,使用connection.requestRejection()做 Host/Origin 围栏与登录态校验。 - Client:
client.js注册settings.section(idsession-cleaner)。 preview返回短期previewToken;delete必须携带该 token,并重新推导候选、比较指纹,避免执行用户没看过的预览。- 对话目录:
folders返回目录清单与previewToken;folders-delete必须携带 token,并重新扫描、比较目录大小/修改时间/状态指纹。删除前再次校验目录位于conversations/直接子目录、不是 symlink/Junction、元数据匹配(有session.json时),并拒绝仍被 Host 加载的目录。 - 会话日志路径由 JSONL 后端的确定性布局推导,并在删除前再次校验目录名与根目录归属。
- 删除顺序:先完成会话目录/检查点/日志的文件系统删除,成功后才 detach/unarchive;失败时保留归档状态和原工作区位置。
- 兼容
@local/session-archive:读取conversations/index.json与每个目录的session.json,并消费working-directory/change事件,因此相对工具路径会按会话专用目录解析。 - 附件按
sha256:<hex>解析到attachments/v1/objects、file-objects与files。
已知边界
- Harness 的持久化接口没有删除 API;会话日志与附件对象必须由本插件直接删除文件。Agent 正在运行、或 Session 仍被 Host 加载的会话都会被拒绝;前者请先停止,后者请关闭会话或重启 Harness。否则删除会让它在侧边栏以“未分组”残留。
- 对话目录清理独立于会话清理:它只处理
conversations/下的文件,不删除会话日志、投影检查点或附件;保留 out只删除work/和AGENTS.md,保留out/、session.json及未知顶层文件;全部删除删除整个目录并移除index.json中指向该目录的条目。残留目录、未归档会话目录都会列出。 - 对话目录删除前会扫描所有会话日志与当前 live events,仍被其他会话使用(cwd 或显式文件路径位于该目录)的目录会阻止删除;运行中/已加载目录也会禁用。但其他进程、未提交草稿、外部程序直接引用目录内文件的情况无法完全证明安全。
- 工作区文件候选依赖工具调用记录与文件创建时间;扫描到的文件默认不勾选,需要在预览中确认。通过 shell 修改既有文件(而非新建)不会自动列出。
- 会话专用目录只在该目录存在且
session.json完整匹配当前会话时才会删除;缺少或损坏session.json时只清理日志,不会猜测目录。目录仍被其他会话使用、含未知顶层项、或其余会话引用状态未知时,整目录删除会被阻止。 - 自定义
baseDir的会话在日志里有working-directory/change时可由 facts 识别;若applyDirectory:false且没有切换过目录,且 baseDir 不是默认conversations,列表和预览可能无法自动发现目录。此时建议先用默认 baseDir 或让会话切换一次目录。 - 共享引用检查其余会话日志与当前 live events 中的工具路径;其他进程、未提交草稿、外部程序直接引用同一附件对象的情况仍无法完全证明安全。相关文件/附件会被保留或要求逐项确认。
- 运行中状态和“已打开”都只在当前 Host 进程内检测;另一个 Host 进程若仍打开同一会话,本插件无法看到它的写入锁。请确保该会话没有被其他进程使用。归档不会自动卸载 Agent;清理这些会话前请重启一次 Harness。
- 预览与确认之间文件内容可能变化;执行时会重新推导候选、校验预览 token,并拒绝已失效的路径,但不会比较预览时与执行时的文件哈希。重要文件请在确认前重新预览。
- 若其他进程正占用日志或附件,Windows 可能拒绝删除;报告会列出失败项,可关闭占用后重试。
- 会话搜索索引是派生索引;删除后会在后台触发一次对账。若部署禁用了搜索,残留行会在下一次成功搜索时被清除。
- 删除文件后可能顺带移除因此变空的父目录(仅限工作区/会话目录边界内,且只移除空目录)。
- 未自动清理 OS 临时目录中的
dsh-workspace-changes-*、dsh-subprocess-*等进程级临时目录;它们没有稳定的会话映射。 - 不会自动级联删除未归档的子会话、分叉或子代理会话;它们有独立的会话日志。若它们仍使用父会话目录,父目录会保留;若要清理这些会话,请先归档再分别选择。
- 归档的会话如果 Agent 仍在运行,或 Session 仍被 Host 加载,插件会拒绝删除;后者显示“已打开(需重启)”。先重启 Harness(归档状态不会丢),再回来清理。
测试
npm test
回归测试覆盖:预览 token 单次使用、工作区外文件、不可读的其余会话、symlink/Junction 祖先、投影缓存实际删除、共享会话目录、未知目录项、索引保留其他条目、默认选项、运行中会话引用、detach 失败、嵌套 baseDir,以及对话目录的保留 out/全部删除、残留目录、已加载目录阻止。
License
MIT © 2026 THao712