dsh-session-cleaner
DSH (DeepSeek Harness) 会话回收站与清理管理器 · Trash bin & session cleaner for DeepSeek Harness
dsh-session-cleaner 为 DSH 增加可逆的会话回收站：把不想要的会话移入回收站而非直接删除，随时可
恢复或彻底清除；并内置重名防误删、对话内容预览、定期自动清空能力，界面主题与 DSH
主体完全一致。
It adds a reversible trash bin to DSH: move unwanted sessions into the trash instead of hard-deleting
them, restore or purge them anytime — with a name-collision guard, conversation preview, scheduled
auto-purge, and a UI themed exactly like the DSH main body.
说明 / Note：npm 上另有同名裸包 dsh-session-cleaner（fountunt 发布，专注 live store detach）。
本包是功能完整的回收站方案（移入/恢复/彻底清除/定期清空/防误删/预览），两者互不冲突；
为避免混淆，本包以 scoped 名 @new-256/dsh-session-cleaner 发布。
功能特性 / Features
- 🗑️ 可逆回收站 Reversible trash：移入回收站（物理目录移至
dsh-home/.session-cleaner-trash\<id>\，
清理 workspace.json / session_projcache），可随时恢复或彻底清除。
- ⚠️ 重名防误删 Name-collision guard：从 React Fiber 精确提取 sessionId，永不按标题猜 id；
二次确认弹窗展示同名会话摘要与首条指令对照。
- 💬 对话内容预览 Conversation preview：多帧 zstd 解压 + JSONL 提取（标题/轮次/用户与助手消息/
首条指令高亮）。
- 🧹 定期自动清空 Scheduled auto-purge：会话移入回收站 N 天后自动彻底删除（可开关、可调天数与
检查间隔），回收站内展示剩余天数/过期状态。
- 🎨 主题与 DSH 主体一致 DSH-native theming：内嵌官方 design-platform 设计令牌（light/dark），
全部组件使用
--dsw-alias-* 语义变量；主界面注入的弹窗同步跟随。
- 🔒 安全加固：Session ID 路径穿越校验；残留条目清理；活跃会话（openStep/pendingCalls）拒绝删除。
安装 / Install
要求：DSH Desktop ≥ 0.3.15（@deepseek-ai/dsh >= 0.1.1-rc.2），Node ≥ 20。
方式一：npm 安装（推荐） / Install from npm (recommended)
dsh plugin --profile web add @new-256/dsh-session-cleaner
安装后 bundle 补丁层自动注册插件（dsh.bundle.patch → cordis.patch.yml，id: session-cleaner）。
方式二：本地包安装 / Install from a local package
dsh plugin --profile web add <本包路径>
方式三：手动放置 / Manual install
把 lib/index.mjs 放到 dsh-home 根目录（如 session-cleaner.plugin.mjs），并在用户层补丁
dsh-home/cordis.patch.yml 增加：
- insert:
- id: session-cleaner
name: file:///C:/.../dsh-home/session-cleaner.plugin.mjs
config:
verbose: false
机器特定配置（verbose、以及曾经用过的 trashDirName）写在用户层补丁的同 id 行即可整体覆盖
bundle 层默认值。
使用 / Usage
回收站显示规则 / Trash list semantics
| 条目状态 | 是否显示 |
|---|
| 已在回收站且不在当前列表 | ✅ 显示 |
| 已归档会话（含删除时归档、workspace.json 仍标记归档） | ✅ 显示（「已归档」标记） |
| 会话仍在「当前列表」（sessions 目录中未归档可见会话） | ❌ 隐藏（视为陈旧/重复备份） |
数据布局 / On-disk layout
dsh-home/
├── .session-cleaner-trash/
│ └── <sessionId>/
│ ├── .trash-info.json # { deletedAt, title, originalWorkspacePath, originalSessionDir, targetWsId, projRecord, isSubagent, isArchived }
│ └── session-data/ # 原会话物理目录
├── session-cleaner-settings.json # 定期清空设置（保留天数/开关/检查间隔）
└── sessions/… # 未受影响
HTTP API
| 方法 | 路径 | 说明 |
|---|
| GET | /api/session-cleaner/sessions | 会话列表（含 archived/subagent/visible/live 标记） |
| GET | /api/session-cleaner/trash | 回收站列表（服务端过滤 + 过期/剩余天数计算） |
| GET/POST | /api/session-cleaner/settings | 读取 / 保存定期清空设置 |
| POST | /api/session-cleaner/purge-expired | 立即清理已过期条目 |
| GET | /api/session-cleaner/preview?sessionId= | 对话内容预览（zstd 解压 + JSONL 提取） |
| POST | /api/session-cleaner/delete | { sessionId, confirm: "DELETE" } 移入回收站 |
| POST | /api/session-cleaner/restore | { sessionId } 恢复 |
| POST | /api/session-cleaner/purge | { sessionId, confirm: "PURGE" } 或 confirm: "PURGE-ALL" |
| GET | /session-cleaner | 管理页 |
开发 / Development
# 语法检查
node --check lib/index.mjs
# 逻辑冒烟测试（临时 dshHome 上验证 移入/过滤/过期清理/恢复/归档还原/安全校验）
node smoke-test.mjs
布局：lib/index.mjs 单文件宿主插件（export const name = 'session-cleaner' + apply(ctx, config)）；
无 client 半边（注入脚本由 webserver/index-inject 事件服务端下发）。
兼容性 / Compatibility
| 项 | 值 |
|---|
@deepseek-ai/dsh | >= 0.1.1-rc.2（测试于 0.1.2-alpha.5） |
| DSH Desktop | >= 0.3.15 |
| Node.js | >= 20 |
FAQ
- 恢复后会话跑到哪了？ 恢复会还原 workspace.json 的 sessionIds（原工作区）；若删除时是归档会话，
会同时写回
archivedSessionIds（归档区，侧边栏不可见，需先取消归档）。
- 回收站里的「剩余 N 天」不更新？ 刷新列表即可；倒计时由服务端按
deletedAt + retentionDays 计算。
- 为什么某些回收站条目不见了？ 该 sessionId 仍存在于当前会话列表（未归档），属于陈旧/重复备份，
按规则自动隐藏（对应用户要求：回收站不显示当前列表中的会话）。
- 自动清空已启用但没删除？ 检查管理页设置卡片是否开启、保留天数是否正确；
也可点「立即清理已过期」手动触发。
License
MIT © 2026 new-256 (chenglong)
