# dsh-session-manager

> 为 DSH Web 界面补齐完整的会话管理能力：回收站删除、归档恢复、继续/暂停、未读标记、fork、工作区管理与上下文压缩阈值。

## Metadata

- Author: [@dream12347](https://github.com/dream12347)
- Repo: <https://github.com/dream12347/dsh-session-manager.git>
- GitHub: [dream12347/dsh-session-manager](https://github.com/dream12347/dsh-session-manager)
- Stars: 41
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `ai-worker`, `deeepseek-harness-plugins`, `deepseek-harness`, `deepseek-harness-plugin`, `dsh`, `dsh-plugin`
- Forks: 3
- Open Issues: 0
- Last push: 2026-08-20T09:50:48.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:dream12347/dsh-session-manager
```

## Wiki

## 一句话定位
为 DSH Web 界面补齐一套完整的会话管理能力：在设置页与对话顶部都能访问，支持删除（带回收站可恢复或彻底清除）、恢复已归档会话、继续/暂停会话、查看近期活动统计、打开日志目录、未读/已读标记、fork 到新聊天、工作区分组与排序管理，以及一个对所有 Agent 预设统一生效的上下文压缩阈值。

## 核心能力
- 删除会话并放入回收站（保留最近 10 条，最早的自动彻底清除），支持恢复或彻底删除
- 在设置页恢复"已归档"分组中的会话回到主列表
- 一键继续空闲会话或暂停正在运行的会话
- 在中心弹窗中查看会话近期活动统计（轮次、用户消息、助手消息、全部工具调用、活动窗口）
- 在系统文件管理器中打开会话的日志目录
- 会话行标题旁显示四态点（手动未读蓝、官方等待输入琥珀、官方完成提醒绿、运行中转圈），并向官方侧边栏同步注入蓝色未读点
- 一键 fork 当前会话到新聊天（调用官方 sessions.fork）
- 工作区分组展示会话、组内按最后使用时间排序，支持拖拽重排、置顶、重命名、删除工作区
- 在"通用设置"中调整上下文压缩阈值（17%–90%），对所有 Agent 预设统一生效并持久化

## 技术实现
- **语言**: TypeScript
- **关键依赖**: @deepseek-ai/cordis（插件运行时）、@deepseek-ai/dsh-host-webserver（HTTP 路由）、zod（请求/存储域 schema）、@deepseek-ai/dsh-storage-domain（持久化）、react 18（客户端 UI）
- **架构模式**: 标准的 DSH 插件双端结构。`src/index.ts` 是 host 端，通过 `ctx.webServer.register` 暴露 7 条 HTTP 路由（`/delete` `/restore` `/purge` `/trash` `/open-folder` `/pause` `/compaction-threshold`），并通过 `ctx.on('agent/pre-step', ...)` 钩子在每步强制应用阈值。`src/client/index.ts` 是 client 端，通过 `ctx.slots.inject` 注册到三个官方插槽：`settings.section`（独立"会话管理"分栏）、`settings.general.item`（压缩阈值滑块）、`conversation.session.header.utilities`（对话顶部的"对话管理"和"删除本对话"按钮）
- **入口文件**: `src/index.ts`（host）+ `src/client/index.ts`（client，导出 `dsh-session-manager/client`）

## 适用场景
当你日常用 DSH Web 跑大量会话、侧边栏列表越来越长、原生又没有"删除会话"入口时，本插件可以让你回收空间、找回误删的会话、给会话打未读标记方便回头继续、随时打开日志目录排查问题。如果你还关心 token 用量与上下文压缩策略，它也提供了一个全局阈值，无需逐个修改 Agent 预设。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | >= 0.1.0-rc.6 | 依赖 settings.section / settings.general.item / conversation.session.header.utilities 插槽，以及 ctx.sessionPersistence / ctx.workspaceRegistry / ctx.agents / ctx.storageDomain / ctx.agentPresets 服务 |
| Node | ^22.19.0 或 >=24.0.0 | package.json#engines 声明 |
| 平台 | macOS / Windows / Linux | 通过 `open`/`explorer`/`xdg-open` 在系统文件管理器中打开日志目录 |
| 原生模块 | 无 | host 端仅使用 node 内置模块（fs/path/child_process），client 端无原生依赖 |

## 安装方式
```bash
dsh plugin --profile web add github:dream12347/dsh-session-manager
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| 上下文压缩阈值 | 数字（17–90） | 当会话上下文用量达到模型窗口（100 万 token）的设定比例时自动压缩；保留最近 16% 原文；对所有 Agent 预设统一生效 | 80（即 0.8） |
| 回收站容量 | 数字 | 保留最近 N 条被删除的会话，超出后最早的条目自动彻底清理（不可恢复） | 10 |

> 上述两项的可见 UI 入口分别是"设置 → 通用设置 → 上下文压缩阈值"（滑块 17%–90%）和"设置 → 会话管理 → 回收站"折叠区。本插件无传统意义的外部配置文件。

## 常见问题

**Q: 安装后需要做什么？**

A: 安装后必须重启 `dsh web`。Host 插件和 client bundle 都在 DSH 启动时加载，不重启新功能不会出现。

**Q: 能不能删除正在运行的会话？**

A: 不能。删除按钮在运行中的会话上会被禁用，host 端也会拒绝请求并返回 `session-live`。当前打开但空闲的会话（不再思考）可以正常删除。多标签页场景请先确认该会话在所有标签页都已停止。

**Q: 回收站能保留多少条？满了怎么办？**

A: 最多保留 10 条。再删除新会话时，最早进入回收站的那条会被自动彻底清理（包括磁盘上的会话目录），无法再恢复。重要会话请及时在回收站里点"恢复"。

**Q: 子代理（subagent）会话被删了怎么办？**

A: 即使主会话已经删除，子代理会话变成"孤儿"也能在会话管理面板里直接清理，前提是它不在运行中。这样不会有无法清理的残留会话堆积。

**Q: "上下文压缩阈值"配置保存在哪里？重启后还在吗？**

A: 值持久化在 DSH 存储域 `dsh_delete_session`（`~/.dsh/storages/dsh_delete_session.json`）。如果默认 Agent 预设是用户预设，会同步写入对应 `agent.cordis.yml` 的 `compaction-basic` 配置；系统预设文件只读不会改写。每次 `agent/pre-step` 钩子都会把阈值套用到所有预设的压缩引擎上，所以保存即生效，重启后依然生效。

**Q: 未读标记和官方未读有什么区别？**

A: 官方未读是琥珀色（等待输入）和绿色（完成提醒）的点，点它们会"就地已读"——不跳转页面，只清除官方提醒。本插件的蓝色未读是手动标记，存在浏览器 localStorage 的 `dsh.session-unread.v1`（与其他会话管理插件互通），点空白处可标记未读，点蓝点可清除未读，打开会话自动已读。

**Q: 侧边栏的蓝色未读点会一直准确吗？**

A: 官方侧边栏的行元素不带会话 id 属性，本插件按标题文本匹配并用 MutationObserver 注入蓝色点。会话管理抽屉内部按真实会话 id 精确标记，不受影响。重复标题的会话在侧边栏会共享同一个蓝点，这是已知的边角情况。

## 上手难度
入门 — 安装一条命令、重启 DSH 即可使用，无需阅读文档或修改任何配置文件；唯一的"配置"是通用设置里的压缩阈值滑块。

## 已知问题与限制
- 不能删除正在思考中的会话；多标签页场景下如果别的标签页打开了同一个会话，请先在那边停止（src/index.ts:414-417）
- 侧边栏未读点按标题文本匹配，重复标题的会话在侧边栏共享同一个蓝点，会话管理抽屉不受影响（README.md:121）
- live 会话（当前进程内打开的会话）删除后，内存状态由 DSH 在重启时彻底清理；这是 DSH 自身行为，非本插件处理
- host 端为保持 WorkspaceRegistry 的缓存与存储域一致，会直接写入 `registry.state` 这个私有字段；README 与源码注释都标注这是对 DSH 升级脆弱的方案，DSH 升级后需要同步适配（src/index.ts:276-289）
- 已彻底删除的会话 id 会保留在浏览器 localStorage（防止 live 会话删除后刷新"复活"）与归档集合中（无害残留，不显示）（README.md:120）
- 安装后必须重启 `dsh web`，否则 host 插件与 client bundle 都不会生效（README.md:50）
- 压缩阈值的下限 17% 由"阈值必须大于引擎的保留比例 16%"这一硬性约束决定（src/index.ts:697-699 / src/client/index.ts:2235-2236）

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-session-manager](https://deepseek-plugin.org/plugins/dream12347/dsh-session-manager)
Wiki generated by AI (model: `MiniMax-M3`)