DSH 会话数据管理器项目说明

August 30, 2026 · View on GitHub

本文档提供插件的详细背景、数据行为、实现结构和维护约束。README 面向快速安装与使用，详细说明在这里维护。

核心目标

DSH 会为不同工作区、Agent 和子代理生成本地会话记录。随着使用时间增长，用户需要区分：

  • 正在运行的会话
  • 已经归档、但仍保留在普通列表之外的会话
  • 需要长期保留的备份会话
  • 已经移入回收站、仍可恢复的会话
  • 因为路径、工作区、运行时状态或持久化问题而异常的会话

本插件提供统一管理入口，让用户能够查看这些状态，并在不直接操作底层文件的情况下完成归档、恢复、备份、回收站和批量处理。

功能与行为

  • 在 DSH Web 页面显示 会话管理器 悬浮入口。
  • 提供全部、未归档、归档、异常、子代理、备份区和回收站视图。
  • 对所有普通会话计算独立计数，不与备份区、回收站混计。
  • 对子代理会话单独标记，避免因未挂到主工作区而被误判为未分组异常。
  • 对普通会话显示归档、恢复、移动工作区、一键修复未分组状态等操作。
  • 提供“清理无效索引”操作，删除 sessionQuery 已不可见会话的派生缓存、工作区悬空引用和归档标记，不删除日志文件。
  • 对归档会话提供移入备份区、移入回收站和恢复操作。
  • 备份区只提供恢复到归档状态，不提供直接彻底删除。
  • 回收站提供恢复和彻底删除操作。
  • 支持复选框、批量归档、批量恢复、批量备份、批量删除。
  • 支持按会话 ID、标题、路径和工作区搜索。
  • 右侧提供只读预览，可以展开、收起和临时调整宽度。

数据与状态

插件读取以下 DSH 数据：

  • 会话 header，包括 ID、创建时间、cwd、origin、agent preset 和父会话。
  • 工作区列表、会话分组和归档 ID 集合。
  • DSH 会话投影缓存（插件仅在移动、彻底删除、恢复和清理无效索引时修改；恢复时会先清理旧缓存，再通过冷读写回重建）。
  • sessionQuery 提供的表面事件、标题快照和预览数据。
  • 本插件自己的备份保留区清单和回收站清单。
  • 保留区中的原始持久化文件。

插件不会上传这些数据到外部服务。备份保留区和回收站位于 DSH profile 下：

$DSH_HOME/profiles/.session-manager-custom-backup
$DSH_HOME/profiles/.session-manager-custom-trash

插件升级或重装不会自动清除这些目录。

架构

Host 侧

Host 插件注册并处理：

POST /api/session-manager-custom

主要职责：

  • 读取会话索引、工作区归属、标题快照和表面事件。
  • 计算普通会话、归档、异常、子代理和保留区计数。
  • 提供详情、归档、恢复、移动、修复、清理无效索引和批量操作。
  • 管理备份区和回收站清单。
  • 在操作 live 会话前安全结束 Agent/Session 生命周期。
  • 在移动文件前后维护清单一致性，并对失败操作尝试回滚。
  • 在移入保留区或彻底删除时同步移除工作区引用、归档标记和投影缓存。
  • 恢复保留区会话时重新关联工作区、恢复归档标记，并立即通过 DSH 冷读重建投影缓存。

Client 侧

Client 插件通过 window.__ModuleLoader__.load(...) 注册，使用两个 DSH slot：

  • sidebar footer 入口
  • shell overlay 管理弹窗

Client 侧负责：

  • 请求 Host JSON API。
  • 渲染多个视图、搜索、批量操作和详情面板。
  • 管理列表和详情请求竞态。
  • 管理操作通知、确认框和右侧预览状态。
  • 处理面板打开、关闭、Escape 和窗口缩放。

预览范围

普通会话使用 DSH sessionQuery.readSurface() 返回当前表面。

备份区和回收站中的文件已经离开普通持久化索引，因此插件直接只读解析保留区文件：

  • 支持 .jsonl
  • 支持默认 .jsonl.zstd
  • 只解码完整 Zstandard frame
  • 最后一个未写完 frame 会被忽略
  • 预览过程不修改文件，也不尝试 repair

预览保留以下事件：

  • user/message
  • assistant/message
  • tool/call
  • tool/result

内部权限事件、chunk 和边界事件不会显示，但仍计入事件总数。

保留区生命周期

  1. 会话必须先归档。
  2. 移入备份区或回收站前，如果会话仍处于 live 状态，先安全结束其生命周期。
  3. 文件移动到保留区后，清单写入成功才算操作完成；清单失败会尝试将文件移回。
  4. 移动成功后会移除工作区引用、归档标记并删除该会话的投影缓存。
  5. 从保留区恢复时，文件回到原路径、重新关联工作区、恢复归档标记，并立即通过冷读重建投影缓存。
  6. 用户继续执行普通恢复归档，才会离开归档状态。
  7. 备份区没有直接彻底删除入口。
  8. 回收站彻底删除会同时移除清单项、目录、工作区引用、归档标记和投影缓存。
  9. 任一工作区、归档或缓存同步失败时，恢复会话会把文件送回保留区；移动或彻底删除则返回失败，不把部分同步当作成功。

安全与权限

本插件需要访问 DSH 的会话、工作区、归档状态和持久化文件。具体高风险操作包括：

  • 结束仍在运行的 Agent/Session
  • 移动实际持久化文件
  • 恢复、移入回收站和彻底删除

建议：

  • 在测试 profile 或备份环境中先验证。
  • 只对明确需要管理的会话执行操作。
  • 不要将本插件作为首次清理真实生产数据的唯一工具。

兼容性

  • 当前发布范围只验证 Windows 平台。
  • DSH 0.1.0-rc.7 是当前开发和验证基线。
  • 当前上游 master 是跟踪目标，尚未完成真实 DSH Web 集成复核。
  • DSH 仍处于 developer preview，内部服务、事件格式和持久化布局可能变化。
  • 插件依赖 DSH 内部 Agent/Session 生命周期接口，升级后可能需要同步更新。
  • 工作区、备份区或回收站路径如果以后改变，需要同步调整 Host 存储配置。

开发与验证

本文档不固定某个仓库的开发命令。当前仓库的开发检查、测试入口和发布检查以该仓库 README 为准。

测试使用临时 DSH_HOME，不会读取或写入真实 profile。

发布说明

  • README.md、docs/project.md、代码、测试与包元数据应随版本保持一致。
  • 公开发布不包含本地运维文档、私有标记文件、本机路径或真实用户数据。
  • 公开仓库根目录中的 scripts/install.ps1 用于本地 tarball 安装和更新，并依赖当前包目录布局；scripts/uninstall.ps1 使用内置稳定包名调用官方 DSH 卸载命令，再清理本插件的备份区和回收站目录，可以脱离仓库独立运行。
  • GitHub 仓库应添加 dsh-plugin topic。
  • 当前许可证为 MIT。