前言¶

DSH 把對話過程持久化爲 $DSH_HOME/sessions 下的會話文件。這些文件不是單幀 zstd 壓縮塊，而是多個 zstd frame 的串聯——README 中舉例，一個 19MB 會話可包含 119,952 個 frame。若用單幀解碼 API 讀取多幀文件，往往只能看到 header，容易誤判爲「會話全空」。

排查這類問題時，通常需要手寫腳本逐幀掃描、比對結構。dsh-session-health 把這套診斷邏輯產品化爲 DSH 工具：模型或開發者可以直接問「會話文件健康嗎」，得到結構化報告與清理建議，而不必每次臨時寫分析腳本。它與 dsh-session-repair-skill（修復損壞會話）互補：本插件只讀診斷，repair 技能負責修復。

這是什麼¶

dsh-session-health 由 omdsh-dev 維護，歸類爲 admin-security。插件對 sessions 目錄下的多幀 zstd 會話文件做幀級掃描，檢測 torn、損壞、空會話、stray 文件等問題，輸出健康報告與清理建議。全程只讀，不修改或刪除任何文件。

npm 包名 @deepseek-ai/dsh-session-health，版本 0.0.1，MIT 許可。GitHub 倉庫：https://github.com/omdsh-dev/dsh-session-health。社區目錄頁：https://www.skillhub.cn/plugins/omdsh-dev/dsh-session-health。

插件註冊 session_health 工具（row id tool-session-health），統一輸出 JSON 文本。

核心功能¶

幀級掃描與檢測項¶

掃描器基於 RFC 8878 結構獨立實現（DataView 讀字節），與官方 scanZstdFrames 差分一致，零業務依賴。可識別的異常類別如下：

報告字段包括：root、scanned、errors、suspicious、totals（字節、幀數、事件批次估算）、detail、deep、suggestions。suggestions 按 issue 模板給出清理/修復建議，不自動執行。

工具參數¶

deep: true 時動態 import 官方解碼器做事件分佈與中斷檢測；若解碼器不可用，報告明確標註 deep: "unavailable"，幀級掃描仍正常進行。

安全模型¶

1. 只讀保證：絕不修改或刪除文件；測試覆蓋「掃描後文件字節數不變」（files.spec SH-06 用例）。
2. 路徑圍欄：session id 嚴格目錄名白名單；絕對路徑與最終文件均做 fs.realpath containment；枚舉用 lstat 拒絕 symlink。
3. 輸入範圍固定：僅 sessions 目錄，無網絡、無執行面。

安裝與啓用¶

插件已在 @deepseek-ai/dsh@0.1.0-rc.8 下完成全鏈路驗證。Node 要求 ^22.19.0 || >=24.0.0。

下面介紹從 GitHub 安裝的方式（README 推薦）。web 與 headless 是不同 profile：dsh run 默認使用 headless profile，在 web profile 安裝不會自動覆蓋 headless。

# 交互式（web）profile
dsh plugin --profile web add github:omdsh-dev/dsh-session-health

# 一次性任務（headless）profile —— dsh run 默認使用 headless
dsh plugin --profile headless add github:omdsh-dev/dsh-session-health

也可使用 npm pack 產物安裝：

dsh plugin --profile web add dsh-session-health-*.tgz

包內 dsh.bundle.patch 會在安裝後自動把插件加入 profile 的 layer stack。peer 依賴（@deepseek-ai/cordis、@deepseek-ai/dsh-tools）由 profile 的 healed profiles/node_modules 回退安裝提供。

驗證安裝是否生效：

dsh --profile web --dump-config | grep tool-session-health

啓動 DSH（lib 生產模式，勿全局安裝）：

npx -p @deepseek-ai/dsh@0.1.0-rc.8 dsh web

典型用法¶

掃描整個 sessions 目錄：

session_health { action: "scan" }

返回示例結構：

{"root":"C:\\Users\\admin\\.dsh\\sessions","scanned":39,"errors":{...},"suspicious":{...},"suggestions":[...]}

對單個會話做深度分析：

session_health { action: "file", path: "session-abc123", deep: true }

也可通過 dsh run 讓模型調用：

dsh run "使用 session_health 工具掃描會話目錄健康狀態"

適用場景與注意¶

適合誰

• 本地 sessions 目錄出現異常（會話「看起來是空的」、寫入中斷、殘留 tmp 文件）時，需要快速定位問題文件。
• 不想每次手寫 zstd 幀掃描腳本，希望模型在對話中直接查詢健康狀態。
• 與 dsh-session-repair-skill 配合：先用本插件診斷，再按需修復。

注意事項

1. 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與 MIT 許可證。
2. deep 模式依賴 @deepseek-ai/dsh-session-persistence-jsonl；在 npm 0.1.0-rc.8 下該 tarball 不含 src/、根入口不導出 zstd API，deep 會降級爲 decoder-unavailable，幀級掃描不受影響。
3. 事件批次估算 = 幀數 - 1，是估算值而非精確事件數，報告已註明。
4. Windows 路徑使用正斜槓（C:/...）。

結尾¶

dsh-session-health 把多幀 zstd 會話診斷從手工腳本變成可複用的 DSH 工具：只讀、幀級、帶路徑圍欄，輸出結構化報告與建議。若你維護本地 DSH 會話或排查持久化問題，可以把它裝進 profile 做一次基線掃描。

• 社區目錄：https://www.skillhub.cn/plugins/omdsh-dev/dsh-session-health
• GitHub：https://github.com/omdsh-dev/dsh-session-health