idleRain/dsh-clean-sessions

dsh-clean-sessions

零第三方运行时依赖的命令行工具,用于清理
DSH(DeepSeek Harness) 的已归档会话:
删除归档名单中的会话日志目录,并同步归档名单与工作区槽位,不留幽灵条目与死槽位。

English · 开发与发布见 CONTRIBUTING.md

为什么需要它

DSH 的"归档"只是 /storages/workspace.json 中 global.archivedSessionIds
里的一个 id,而会话日志位于 /sessions///。安全删除必须
同时移除磁盘目录并从配置中摘除 id,而 DSH 持久层没有删除接口,GUI 也只提供归档与
取消归档,本工具补齐这一空缺。

安装

需要 Node.js >= 22.18。

npm install -g dsh-clean-sessions
或免安装直接运行
npx dsh-clean-sessions --help

使用

dsh-clean-sessions                  # 预览,不修改任何文件
dsh-clean-sessions --apply --yes    # 真正执行删除并同步配置

选项

| 选项 | 说明 |
|---|---|
| --apply | 真正执行删除与配置更新,默认只输出预览 |
| --yes | 跳过删除前的确认提示,仅配合 --apply 使用 |
| --min-age  | 最近多少分钟内有写入的归档会话视为可能活跃,默认 30,设为 0 关闭守卫 |
| --include-recent | 强制纳入最近有写入的归档会话,默认排除 |
| --backup  | 把会话目录移入备份目录而非直接删除,不能位于 DSH 主目录之内 |
| --no-config | 只删除磁盘目录,不同步 workspace.json 配置 |
| --home  | 指定 DSH 主目录,默认读取 $DSH_HOME 或 ~/.dsh |
| --lang  | 提示语言,默认检测主机语言 |
| --version / --help | 输出版本号 / 显示帮助 |

示例

dsh-clean-sessions --apply --backup "D:\dsh-trash\2026-09-16"   # 先备份再删除
dsh-clean-sessions --home "D:\data\dsh"                         # 指定自定义 DSH 主目录

安全说明

1. 默认仅预览,必须显式传入 --apply 才会修改文件;删除前有确认提示,非交互环境默认拒绝。
2. 只处理归档名单内的会话;最近写入的会话默认跳过,无法读取的会话目录按可能活跃处理。
3. 位于 sessions 根目录之外的目录疑似符号链接逃逸,只列出并跳过,不会删除。
4. --backup 备份目录不能位于 DSH 主目录之内,工具会在删除任何文件前拒绝。
5. 若 dsh 正在运行,改完配置必须重启 dsh,否则内存中的旧名单会被写回并产生幽灵条目。
6. 附件存储与 session_projcache.json 单文件缓存不会被清理。

许可证

MIT

English

A zero-runtime-dependency CLI to clean up archived sessions of
DSH (DeepSeek Harness):
it removes the session log directories listed in the archive and syncs the
archive list and workspace slots, leaving no ghost entries behind.

Development and release notes: CONTRIBUTING.md · 中文文档见上

Why this exists

An archived DSH session is only an id in global.archivedSessionIds inside
/storages/workspace.json, while session logs live in
/sessions///. Safe deletion means removing
the directories and dropping the ids from the config; DSH has no deletion API
and the GUI only offers archive/unarchive, so this tool fills the gap.

Install

Requires Node.js >= 22.18.

npm install -g dsh-clean-sessions
or run without installing
npx dsh-clean-sessions --help

Usage

dsh-clean-sessions                  # preview, changes nothing
dsh-clean-sessions --apply --yes    # delete and sync the config

Options

| Option | Description |
|---|---|
| --apply | 实际执行删除并更新配置；默认仅预览 |
| --yes | 跳过确认提示；仅与 --apply 一起使用 |
| --min-age  | 将在此分钟数内写入的会话视为可能处于活动状态；默认 30，0 禁用此保护 |
| --include-recent | 强制包含最近写入的会话（默认跳过） |
| --backup  | 将会话目录移动到备份目录而不是删除；必须位于 DSH 主目录之外 |
| --no-config | 仅删除磁盘上的目录，跳过 workspace.json 同步 |
| --home  | DSH 主目录；默认为 $DSH_HOME 或 ~/.dsh |
| --lang  | 消息语言；默认自动检测 |
| --version / --help | 打印版本 / 显示帮助 |

示例

dsh-clean-sessions --apply --backup "D:\dsh-trash\2026-09-16"   # 删除前先备份
dsh-clean-sessions --home "D:\data\dsh"                          # 自定义 DSH 主目录

安全说明

1. 默认仅预览；需要 --apply 才会进行任何更改。确认提示会保护破坏性运行，非交互式 stdin 默认为否。
2. 仅处理已归档的会话；最近写入的会话默认跳过，无法读取的会话目录被视为可能处于活动状态。
3. 解析到会话根目录之外的目录（符号链接或 junction 逃逸）会被列出并跳过，绝不删除。
4. --backup 必须位于 DSH 主目录之外；该工具会在删除任何内容之前拒绝此类路径。
5. 如果 dsh 正在运行，请在配置更改后重启它，否则内存中的归档列表会被写回，幽灵条目会重新出现。
6. 附件存储和 session_projcache.json 单文件缓存绝不会被触及。

许可证

MIT