dsh-tui-session-manager

dsh-TUI · 一个为 dsh-TUI 生态打造的插件

给 dsh-TUI 的会话管理器：一条 /sessions 命令打开全屏面板，按工作区分组浏览、 过滤、多选，然后真正删除保存的会话 —— 并把宿主删除路径留下的状态残留一并清掉。

A session manager for dsh-TUI: /sessions opens a full-screen browser grouped by workspace, with filtering, multi-select and real deletion — including the state leftovers the host's own delete path does not touch.

为什么需要它 / Why

dsh-TUI 0.11.x 的适配层其实已经实现了真正的删除（channel.deleteSession(id)： 递归删除会话日志目录、清 resume 标记、last-used.json 与 agent-view 记录）， 但没有任何 UI 调用它 —— 命令表、/resume 选择器、工作区菜单里都没有入口。 缺的是入口，不是能力。本插件不重写删除逻辑，只补上入口。

两件常被问到的事，这里一次说清：

• 列表里的空会话从哪来？ DSH 的「新建会话」是立即落盘的：TUI 进程启动、 切换工作区（switchWorkspace → newSession）或 /new 之后，会话日志就已经存在。 若随后 /resume 到别处或直接退出，它就留成一个只有 4 条元数据帧、0 条消息的 空壳，标题回退成目录名。按 e 可一键筛出它们。
• 这些空壳占空间吗？ 不占。每个约 312~466 B，宿主列表还有 revision 缓存。 真正占空间的是历史调试留下的 *.bak-* 备份，那是另一回事。

功能 / Features

• /sessions 全屏管理器：按工作区分组、/ 实时过滤（标题 / 工作目录 / id）。
• e 三态过滤：全部 → 只看空壳 → 隐藏空壳。
• 空壳行标注体积（empty·312B），头部显示总数、空壳数与当前视图。
• 多选批量删除（a 全选当前可见集），删除前 y/n 确认。
• 删除后清扫宿主不碰的四处残留，杜绝 /resume 里的幽灵条目。
• 无构建、无运行时依赖、纯 ESM：装进 profile 即用。

安装 / Install

git clone https://github.com/BoweiDuan/dsh-tui-session-manager.git
dsh plugin --profile dsh-tui add ./dsh-tui-session-manager

装完重启 dsh-tui（profile 的 patchReload: live 也可能让它热加载）。卸载：

dsh plugin --profile dsh-tui remove dsh-tui-session-manager

用法 / Usage

在对话里输入：

/sessions

全屏管理器打开，对话保持干净（命令返回静默成功）。

按键	作用
↑ ↓ / k j	移动光标
space / x / enter	勾选或取消当前会话
a	全选 / 全不选（仅当前可见集）
d	删除已勾选（先弹 y / n 确认）
/	输入过滤词（匹配标题、工作目录、id）
e	循环过滤：全部 → 只看空壳 → 隐藏空壳
esc	退出过滤 / 取消确认 / 关闭面板

清理空壳的标准动作：/sessions → e → a → d → y。

删除结果在底部汇总：deleted N, refused M。当前正在使用的会话会被宿主拒绝 （与宿主语义一致，不是本插件的限制）。refused 也覆盖日志已丢失的情况。

空会话判定 / Empty artifacts

只有三个条件全部满足才算空壳（保守：宁可漏掉一个，也不隐藏或误删有内容的会话）：

kind !== 'subagent'                  // 子代理天然无人类消息，排除
&& hasPrompt === false               // 宿主证明没有人类消息；日志不可读时为 true
&& bytes < 4096                      // 4 条元数据帧约 312~466 B
&& title.source === 'fallback'       // 标题仍是目录名回退

bytes 缺失、标题来源非 fallback、kind 无法识别 —— 一律不判为空。 判定只读宿主 channel.listSessions() 已给出的摘要字段，不读会话日志。

安全 / Safety

• 会话 id 必须匹配 ^[A-Za-z0-9][A-Za-z0-9_-]*$ 才会被当作文件名或 map 键使用， 其它一律跳过并报告。
• 每次清扫在首次改动某个 JSON 文件前备份为 <file>.bak-sweep-<YYYYMMDD-HHMMSS>。
• 无法解析的 JSON 原样保留，不做猜测性修改。
• 清扫过程不抛异常：单步失败计入结果行，不影响其它步骤。
• 删除不可撤销（没有回收站）：勾选时请看清，确认时 y 是唯一入口。

兼容 / Compatibility

• dsh-TUI 0.11.x；接缝 ctx.tuiScenes（全屏场景）与 ctx.commands（斜杠命令）。
• 两者都做软探测：宿主不提供时插件保持 idle，不会让启动失败。
• 场景只使用宿主注入的 props.React 与 props.ui，不引入自带 React （TUI 的 reconciler 只认宿主自己的 React 19 元素）。
• Node ^22.19 || >=24。

开发 / Development

npm test        # node --test，无依赖、无构建

测试覆盖：命令/场景注册与注销、无声成功返回、缺接缝时保持 idle、 空壳判定的四个条件与边界、e 三态过滤、a 只作用于可见集、 id 白名单与 dryRun、以及在临时 $DSH_HOME / $DSH_TUI_HOME 上真实落盘的清扫。

结构 / Layout

index.js            插件契约（name / apply）：注册 /sessions 命令与全屏场景
scene.js            全屏管理器界面 + 空壳判定（使用宿主注入的 React 与 ui kit）
sweep.js            删除后的残留清扫（支持 dryRun）
debug.js            诊断日志（$DSH_TUI_HOME/session-manager.log，64 KiB 上限）
cordis.patch.yml    向 profile 插入插件行
test/               契约测试、判定测试与清扫落盘测试
docs/design/        设计说明

许可 / License

MIT © 2026 BoweiDuan