前言¶
在 DSH 的 Web 界面里使用智能体时，会话、工作区、预设和配置会逐渐增多。常见的操作诉求比较具体：会话太多需要分组和查找，误删后希望能恢复，长消息需要折叠，历史消息需要搜索，预设和配置需要在线编辑，定时任务需要稳定触发。
dsh-toolbox-web 是一个面向 dsh web 的工具箱插件，由 AbcdefgXW 维护，许可证为 MIT。它把会话管理、回收站、子目录管理、搜索、预设编辑、配置编辑、归档管理、定时心跳和长消息折叠放在同一个插件内，减少在多个入口之间来回切换的成本。
这是什么¶
dsh-toolbox-web 可以理解为 DSH Web 侧的管理工具箱。它作为 DSH 插件加载，运行环境要求 Node.js ≥ 22.13。
下面介绍它的核心能力、安装方式、典型用法，以及使用前需要注意的限制。
核心功能¶
会话管理¶
会话管理是工具箱中的基础部分，覆盖日常最常用的会话操作：
- 删除会话，删除动作会进入回收站。
- 复制会话。
- 移动会话。
- 重设工作区根。
- 标签分组。
- 查看会话内容。
- 对话管理中的截断和编辑能力，默认关闭，需要在设置中显式开启。
- 空会话自动标注。
这里的“删除”不是直接物理删除，而是移入回收站。
回收站¶
回收站用于保留被删除的会话或子目录。默认保留 30 天，可以在保留期内执行：
- 恢复。
- 彻底删除。
- 查看被删除会话的内容。
如果只是想临时移除一个会话，回收站提供了二次确认的空间。
子目录管理¶
工作区下可以维护目录结构，支持：
- 新建目录。
- 重命名目录。
- 删除目录。
- 复制目录。
- 将会话批量归属到指定目录。
这适合按项目、主题或工作流组织会话，避免会话列表过平。
搜索¶
搜索能力用于在会话内容中查找文本。它优先使用官方 SQLite 索引，并在结果上提供分组和过滤：
- 按可见会话、归档会话、回收站会话、子代理会话分组。
- 按时间范围过滤。
- 查看命中文本预览。
- 点击跳转到对应位置。
- 可选语义搜索。
需要注意，搜索默认关闭。使用自研搜索或语义搜索时，可能需要解压会话；使用结束后，如需彻底释放内存，需要重启 DSH 服务。
预设编辑¶
可以在工具箱中在线编辑 Agent 预设文件。
适合需要快速调整 Agent 行为、提示词或预设参数，而不希望手动进入文件系统修改文件的场景。
配置编辑¶
可以在工具箱中在线编辑 dsh 配置文件。配置编辑过程包含 YAML 校验和原子写。
这适合调整插件开关、心跳配置、回收站配置等设置项，但修改前仍应确认当前配置内容。
归档管理¶
归档管理用于处理官方归档会话，支持：
- 查看。
- 恢复。
- 删除。
如果会话被归入官方归档，可以通过这里统一查看和处理。
定时心跳¶
定时心跳用于让 DSH 按一定规则执行任务，例如巡检、汇报或周期性检查。
它支持两类调度：
- 间隔心跳：按固定分钟间隔触发。
- 定点定时：按每天、每周或每月指定时间点触发。
目标可以设置为：
- 主工作区根。
- 任意会话。
- 微信、QQ 或飞书 IM 渠道。
调度运行在 dsh 后端进程中，不要求网页一直打开。只要 dsh 服务在运行，心跳配置就可以生效。
IM 渠道推送是可选能力，依赖 dsh-msg-hub。未安装该服务时，相关 IM 目标不可用，心跳可以回退到主工作区根或指定会话。
长消息折叠¶
长消息折叠用于减少超长消息对阅读界面的影响。超过阈值行数的消息会自动折叠，点击后可以展开全部查看。阈值默认是 15 行，可以调整。
会话视图标签收纳¶
会话上方通常会有多个视图标签。工具箱提供一键收起和展开能力，默认折叠，并且会记住当前状态。
如果当前会话界面顶部标签较多，这个功能可以减少视觉干扰。
子代理会话独立管理¶
子代理会话不再和普通会话混在一起，而是按父会话分组管理。支持：
- 查看。
- 打开。
- 删除并进入回收站。
这适合排查某个父会话派生出的多个子代理会话。
释放内存¶
工具箱提供释放内存操作，用于清空插件缓存并尝试触发 GC。
它适合在长时间运行、内存占用上升后做一次主动清理。
安装与启用¶
使用 dsh 命令安装¶
推荐通过 dsh plugin 安装。下面命令会从 GitHub 仓库安装：
dsh plugin --profile web add github:AbcdefgXW/dsh-toolbox-web
也可以使用已发布的 npm 包名称安装：
dsh plugin --profile web add dsh-toolbox-web
dsh plugin add 会自动挂载插件自带的注册行。安装后不建议手动修改 profile 的 cordis.patch.yml 来再次插入本插件，否则可能出现 duplicate loader entry id 导致启动失败。
手动安装¶
如果需要从仓库手动安装，可以执行：
git clone https://github.com/AbcdefgXW/dsh-toolbox-web.git
cd dsh-toolbox-web
npm install --omit=dev
安装完成后，将插件放入 dsh 可加载的插件路径，并重启 dsh web。
启用插件¶
安装完成后，执行以下步骤：
- 重启
dsh web。 - 在浏览器中强刷页面，可以按
Ctrl+Shift+R。 - 打开左下角工具箱入口。
- 进入会话、回收站、子代理、子目录、搜索、预设、配置或归档等页面。
- 进入“设置 → 工具箱”，配置功能开关和定时心跳。
Windows 与 macOS 环境变量¶
在 Windows 或 macOS 部署时，需要设置 DSH_HOME 与 DSH_CHANNELS_CWD，让它们指向实际使用的 DSH 数据目录和工作区目录。
这两个变量用于让插件定位正确的会话、配置和工作区路径。
卸载¶
可以使用 dsh 命令卸载：
dsh plugin --profile web remove dsh-toolbox-web
如果手动卸载，需要从 profile 的 package.json 中移除 dsh-toolbox-web，删除相关依赖或软链，并删除插件状态数据。卸载后重启 dsh web。
典型用法¶
管理大量会话¶
如果会话已经很多，可以按下面的方式处理：
- 进入会话管理页。
- 给常用会话打标签。
- 将无关会话移动到更合适的目录。
- 对不再需要但可能还会查的会话执行删除，使其进入回收站。
- 需要恢复时，进入回收站选择恢复。
查找历史消息¶
当不确定某段回答出现在哪个会话时：
- 进入搜索页。
- 输入关键词。
- 按可见会话、归档会话、回收站会话或子代理会话筛选。
- 设置时间范围。
- 查看命中文本预览。
- 点击跳转到对应会话内容。
如果启用了语义搜索，也可以按相关度查找内容相近的会话。
修改预设或配置¶
当需要调整 Agent 预设或 dsh 配置时：
- 进入预设编辑页，修改 Agent 预设文件。
- 或者进入配置编辑页，修改
dsh配置文件。 - 保存前确认 YAML 校验结果。
- 保存后按功能要求重启
dsh，使配置完整生效。
配置定时心跳¶
如果需要定时触发任务：
- 进入“设置 → 工具箱 → 定时心跳”。
- 打开定时心跳开关。
- 设置间隔分钟数或定点定时规则。
- 填写提示语。
- 选择目标：主工作区根、任意会话或 IM 渠道。
- 如果需要推送到微信、QQ 或飞书，先安装并配置
dsh-msg-hub。
IM 渠道推送注意¶
IM 渠道推送是可选能力，依赖 dsh-msg-hub。
- 微信走模拟网页协议，即
ilinkai。主动频繁发消息存在账号风控风险，建议心跳间隔不低于 15 分钟。 - QQ 官方开放平台主动消息需要申请“主动消息权限”。未开通时，推送可能会静默失败。
- 飞书使用官方 API，合规风险相对较低。
如果未安装 dsh-msg-hub，IM 目标不可用，但主工作区根和指定会话的心跳仍可正常工作。
适用场景与注意¶
适合以下场景：
- 在
dsh web中维护多个工作区和大量会话。 - 需要回收站、标签、子目录来组织会话。
- 需要搜索历史会话内容。
- 需要在线编辑 Agent 预设或
dsh配置。 - 需要定时心跳执行周期性任务。
- 需要折叠长消息，减少阅读干扰。
使用前需要注意：
- 插件会读写 DSH 会话、配置等相关文件，因此会以当前
dsh进程权限运行。安装前应检查源码，并确认 MIT 许可证是否符合使用要求。 - 删除会话默认进入回收站，不是立即物理删除。
- 对话管理中的截断和编辑默认关闭，需要显式开启。
- 修改会话文件后，需要重启
dsh才能完整生效。 - 搜索默认关闭。使用自研搜索或语义搜索后，如需彻底释放内存，需要重启 DSH 服务。
- IM 渠道推送依赖
dsh-msg-hub，未安装时会自动回退到非 IM 目标。 - 微信主动推送存在风控风险，建议控制频率。
- QQ 主动消息需要开通相应权限，否则可能静默失败。
结尾¶
dsh-toolbox-web 的价值在于把 DSH Web 侧常见但分散的管理动作集中起来：会话可以分组、回收、搜索和编辑，预设和配置可以在线修改，长消息可以折叠，定时任务可以持续运行。
仓库地址：
https://github.com/AbcdefgXW/dsh-toolbox-web
