前言¶
在 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
