Show and tell: dsh-shelf — session lifecycle (export/archive/trash/search) for DSH

[zoahdev]

中文

dsh-shelf — DSH 会话生命周期管理。 每个用户都会攒下几百个会话，但官方 feature request #1990（无法删除会话）和 #1991（存档会话无法查看/恢复）一直没人接。dsh-shelf 是缺的那层书架。

功能

• dsh-shelf list / stats / search —— 会话清单、统计、头+正文搜索
• dsh-shelf export <id> --format md|json|jsonl —— 导出对话记录（Markdown 人类可读，JSONL 机器可读）
• dsh-shelf archive <id> / restore <id> —— 归档/恢复（移动，不是删除）
• dsh-shelf trash <id> / restore-trash <id> —— 回收站（可恢复）

安全模型

• 列表/统计/导出/搜索严格只读；
• 归档/回收站是移动目录，引擎从不删除任何东西；
• Zstandard 压缩会话会被识别并提示。

使用

npx dsh-shelf list
npx dsh-shelf search "parser bug"
npx dsh-shelf export <id> --format md
npx dsh-shelf archive <id>

零依赖、Node >=18、5/5 测试 + CI。仓库：https://github.com/zoahdev/dsh-shelf

为什么值得做

会话是 agent 的记忆资产，但整个生态只有"记忆"没有"书架"。生命周期管理（导出/归档/搜索/清理）是每个重度用户的刚需——先占住 CLI 层，再上 Web UI、FTS5 中文搜索、自动归档。

---

English

dsh-shelf - session lifecycle for DeepSeek Harness. Everyone accumulates hundreds of sessions, and official feature requests #1990 (no way to delete a conversation) and #1991 (archived sessions cannot be viewed/restored) have no answer yet. dsh-shelf is the missing shelf.

Features

• dsh-shelf list / stats / search - inventory, stats, header+body search
• dsh-shelf export <id> --format md|json|jsonl - transcripts (human-readable Markdown, machine-readable JSONL)
• dsh-shelf archive <id> / restore <id> - archive/restore (moves, never deletes)
• dsh-shelf trash <id> / restore-trash <id> - recoverable trash

Safety model

• List/stats/export/search are strictly read-only.
• Archive/trash move directories; the engine never deletes anything.
• Zstandard-compressed sessions are detected and reported.

Usage

npx dsh-shelf list
npx dsh-shelf search "parser bug"
npx dsh-shelf export <id> --format md
npx dsh-shelf archive <id>

Zero dependencies, Node >=18, 5/5 tests + CI. Repo: https://github.com/zoahdev/dsh-shelf

Why

Sessions are an agent's memory assets, but the ecosystem has "memory" plugins and no "shelf". Lifecycle management (export/archive/search/cleanup) is a hard need for every heavy user - CLI first, then Web UI, FTS5 Chinese search, and auto-archive.

[zoahdev]

v0.3.0: the shelf now has a face and speaks Chinese.

New

• dsh-shelf web — local zero-dependency web panel at http://127.0.0.1:4174: list, search, export (Markdown), archive, and trash from the browser. This is the direct answer to [Feature Request] Web UI: no way to delete a conversation/session #1990/[Feature Request] Web UI: archived sessions cannot be viewed or restored #1991 for people who don't want a CLI.
• Chinese search — CJK bigram tokenizer (zero-dependency): search 解析器 缓存 finds sessions containing those characters, aligning with the FTS5/Chinese discussion Feature proposal: configurable FTS5 tokenizer for session search (Chinese support) #1999 until the host exposes FTS5.

Safety (unchanged)

Moves are reversible (archive/trash -> restore); export is read-only; nothing is ever permanently deleted by the engine.

Status

• Repo: https://github.com/zoahdev/dsh-shelf · Release v0.3.0
• awesome-dsh-plugin PR SSH 隧道到开发机器上的 dsh，执行会直接失败 #652 (Sessions & Messages) is open for review
• Registry: dsh-shelf (verified) in dsh-subscribe

Next: DSH plugin wrapper (open the panel from dsh web), FTS5 when available, zstd export.

[zoahdev]

v0.4.0: install it as a DSH plugin, and zstd sessions now export too.

dsh plugin --profile web add github:zoahdev/dsh-shelf
# panel at http://127.0.0.1:4174 bound to the active profile (committed lib/, no build at install)

• Zstandard session logs are decoded via node:zlib (Node >= 22.19) for export.
• Shared zero-dependency server module powers both the CLI (dsh-shelf web) and the plugin.
• Tests 10/10 (zstd decode regression included) + web smoke.

Release: https://github.com/zoahdev/dsh-shelf/releases/tag/v0.4.0

The lifecycle gap (#1990/#1991) now has a one-command path: install, open the panel, export/archive/trash/search - all local, all reversible.

[zoahdev]

v0.5.0: the shelf now shows you the shape of your session library.

dsh-shelf report 14 --format html --out shelf-report.html   # offline dashboard

• Per-day activity bars, plain/zstd split, total bytes, largest sessions - self-contained HTML, zero dependencies, shareable.
• The web panel (dsh-shelf web / DSH plugin) now renders a 14-day activity chart above the session list.
• New engine APIs: topSessions, renderReportHtml (+ /api/report).

Tests: 12/12. Release: https://github.com/zoahdev/dsh-shelf/releases/tag/v0.5.0

Lifecycle gap -> now with a dashboard: install the plugin, open the panel, see where your sessions come from, export/archive/trash what you don't need. All local, all reversible.