ChenChen913 / dsh-session-cleaner-cli

dsh-session-cleaner-cli 🐳🧹

English

深度清理 DeepSeek Harness（DSH）工作区会话的离线 CLI 工具：按工作区列出、勾选删除、回收站恢复，自动同步工作区账目与投影缓存。跨平台（Windows / macOS / Linux），零依赖。

---

为什么需要它

DSH 的会话持久化是纯追加式设计，GUI 里只有"归档"（仅仅隐藏，数据仍在磁盘），没有任何删除入口（见 SessionPersistence 服务：只有 create/append/load/inspect/list，没有 delete）。测试会话、废弃对话会永远堆积。

本工具在工作区账目（storages/workspace.json）与会话日志目录（sessions/<scope>/<id>/）两层上同步删除，实现"自由删除每一个工作区里的对话"。

快速开始

# 1. 先停止 GUI（工具检测到 3080 端口/进程时自动拒绝删除）
#    Windows: 在 deepseek-harness 仓库根目录运行 stop-dsh.cmd
#    macOS / Linux: 在运行 dsh web 的终端按 Ctrl+C，或 kill 对应进程

# 2. 交互式：选工作区 → 输入编号勾选（1,3 / 2-5 / all）→ 输入 DELETE 确认
node dsh-session-cleaner.mjs

# 3. 重新启动 GUI（重启后侧边栏即为最新状态）

CLI 版本：

node dsh-session-cleaner.mjs list                  # 只读列出全部工作区与会话
node dsh-session-cleaner.mjs delete <id> [id...]   # 删除指定会话（--yes 跳过确认）
node dsh-session-cleaner.mjs restore <批次ts>       # 恢复某次删除
node dsh-session-cleaner.mjs trash list            # 查看回收站
node dsh-session-cleaner.mjs prune-ghosts          # 摘除账目中数据已丢失的幽灵 id

安装 / 卸载

零依赖，Node.js ≥ 18 即可：

# 方式一：直接从 GitHub 用 npx 运行（无需克隆）
npx github:ChenChen913/dsh-session-cleaner-cli list

# 方式二：克隆
git clone https://github.com/ChenChen913/dsh-session-cleaner-cli.git
cd dsh-session-cleaner-cli
node dsh-session-cleaner.mjs

卸载就是删除仓库/脚本文件；若不再需要回收数据，可一并清空 ~/.dsh/trash 与 ~/.dsh/storages/backups。

命令一览

命令	作用
（无参数）	交互式：选工作区 → 勾选会话删除
list	列出全部工作区与会话（只读，服务运行时也可执行）
list -w <标题或路径>	只看某个工作区
delete <id> [id...]	删除指定会话（默认移入回收站；仍需输入 DELETE 确认）
restore <批次ts>	恢复某次删除（批次见 trash list）
trash list / trash empty	查看 / 清空回收站
prune-ghosts	摘除账目中"数据目录已丢失"的幽灵 id

通用参数：--home <目录>（默认 $env:DSH_HOME 或 ~/.dsh）、--pid-file <路径>（额外指定 dsh.pid 位置，服务存活检测用）、--dry-run、--purge（不入回收站直接抹除）、--yes、--force（跳过运行检测）。

工作原理

DSH 默认 JSONL 后端在磁盘上的形态：

~/.dsh/
  sessions/<工作区路径编码>/<会话id>/session.jsonl.zstd   ← 会话日志
  storages/workspace.json                                ← 工作区账目 + 归档集合
  storages/session_projcache.json                        ← 标题/统计投影缓存

删除一个会话 = 四步事务：

1. 备份：两份账目复制到 storages/backups/<时间戳>/
2. 移入回收站：日志目录 → .dsh/trash/<时间戳>/<id>/（--purge 直接删）
3. 同步账目：从 workspace.json 的 sessionIds 与 archivedSessionIds 摘除该 id，盖上 updatedAt
4. 清理缓存：删除 session_projcache.json 对应条目（会话重新打开后自动重建）

restore 是精确逆操作：目录移回、id 挂回原工作区、归档状态还原。

一个关键安全事实：DSH 工作区实体的 sessionIds getter 按"会话头索引"过滤（packages/workspace/workspace/src/entity.ts），因此即使账目残留已删除 id，重启后也不可见，且下一次账目写入时会自动修剪——工具与 harness 的收敛方向天然一致。

安全设计

• 运行检测：删除/恢复/清理前检测 127.0.0.1:3080 监听与 dsh.pid 进程存活，运行中拒绝执行并给出指引；进程检测用跨平台 0 信号探测，不依赖平台命令
• 目录校验：修改类操作前校验 --home 确实像 DSH_HOME（有 sessions/ 或 storages/），打错路径立即报错而不是误建目录
• 并发互斥：同一 DSH_HOME 上的修改操作持 .dsh-session-cleaner.lock（记录 pid），防止两个实例同时改写账目互相覆盖；持有者退出后的陈旧锁自动接管
• 回收站默认：删除 = 移动而非抹除，restore 可找回；确认后 trash empty
• 自动备份：每次写账目前先备份两份 JSON
• 确认提示：交互与 CLI 均需输入 DELETE 确认（--yes 显式跳过）
• 幽灵自愈：账目里指向已丢失数据的 id 标为"幽灵"，prune-ghosts 一次清干净

跨平台支持

平台	默认 DSH_HOME	停止 GUI 的方式	状态
Windows	C:\Users\<你>\.dsh	stop-dsh.cmd（或任务管理器结束进程）	开发/实测环境，CI 覆盖
macOS	~/.dsh	运行 dsh web 的终端按 Ctrl+C	CI 覆盖
Linux	~/.dsh	运行 dsh web 的终端按 Ctrl+C	CI 覆盖

• 工具自身零平台依赖：纯 Node.js 标准库，无原生模块、无外部命令调用
• 服务存活检测 = 端口探测 + 进程 0 信号探测（替代了早期版本依赖 Windows tasklist 的做法）
• 会话目录扫描不依赖工作区路径的编码方式（Windows 的 --C-Users-...-- 编码与 Unix 编码通吃）
• CI（GitHub Actions）矩阵：ubuntu / macos / windows × Node 18 / 20 / 24

配置

项	说明
DSH_HOME 环境变量 / --home	harness 数据目录，默认 ~/.dsh
--pid-file <路径>	额外指定 dsh.pid 位置（harness 装在非标准位置时用于运行检测）
--purge	删除时不入回收站
--dry-run	只预览
--force	跳过运行检测（仅在确认 GUI 已关闭时用）

数据与权限

• 只读写 DSH_HOME（~/.dsh）：不碰工作区项目文件、不碰 harness 代码
• 无网络请求：唯一的网络操作是连接本机 3080 端口做存活检测
• 不读不写凭据：settings.yaml、.anonymous-user-id 等一概不动
• 不动附件：图片等附件按内容哈希去重共享存放（attachments/v1），不属于单个会话，本工具不删除

兼容性

• 验证于 deepseek-harness mainline 47f943859bef60e4160492346772ded9b24f765a（2026-08-13），存储格式 workspace.json unit v2、session_projcache.json unit v3（工具保留 unit 块原样，只做字段级增删）
• 开发与实测环境：Windows 11 + Node 24；CI 覆盖 ubuntu / macos / windows × Node 18 / 20 / 24
• 支持带 BOM 的账目 JSON；不依赖任何压缩工具（标题来自投影缓存，不解析 zstd 日志）

故障排查

• 中文乱码：请在 Windows Terminal 运行；传统 cmd 先执行 chcp 65001
• 提示"检测到服务正在运行"：先关闭 GUI（Windows: stop-dsh.cmd；macOS/Linux: 停止 dsh web）；确认无服务时可用 --force
• 提示"不像是有效的 DSH_HOME"：--home 指错了目录，检查路径或 DSH_HOME 环境变量
• 提示"另一个 dsh-session-cleaner 进程"：有另一个清理实例在跑；确认没有后删除 ~/.dsh/.dsh-session-cleaner.lock
• 恢复后标题消失：正常现象——投影缓存条目在删除时被清掉，会话重新打开后由 harness 重建
• 删除了父会话：子代理会话不在工作区账目，以"未分组会话"列出，请一并处理

开发

npm test   # 13 项端到端测试：list/delete/restore/purge/prune/交互流/运行拒绝/未知id/锁/pid-file/目录校验/不完整批次

测试在临时 DSH_HOME 夹具上驱动真实 CLI 子进程，断言文件系统与账目双重结果；CI 见 .github/workflows/test.yml。

生态

• 收录于 GitHub dsh-plugin 主题页
• 被 awesome-dsh-plugins 雷达（topic 自动发现，8h 扫描）跟踪
• 精选列表：awesome-deepseek-harness
• 相关项目：fountunt/dsh-session-cleaner — 在运行中的 Web 运行时内删除会话的插件方案（GUI 删除按钮 + /api-ext/session.delete），与本工具（离线 CLI + 回收站/恢复/幽灵清理）互补：想要 GUI 内一键删除用前者，想要批量整理、可恢复、可清理幽灵账目用本工具

License & 安全报告

MIT © 2026 ChenChen913。本工具不处理任何凭据；安全问题请通过 GitHub Issues 反馈。