用 dsh-session-health 給 DeepSeek Harness 會話文件做只讀健康檢查

DeepSeek Harness 插件 DeepSeek DSH 會話健康 zstd 會話與消息 2026-08-17 58 閱讀

前言

DeepSeek Harness（dsh）是 DeepSeek 開源的智能體運行時，官方倉庫把它概括成一句話：Everything is a plugin。模型、工具、技能、會話、沙箱、存儲、循環和界面，都按插件掛載。官方還強調另一件事：模型看見的內容會寫進只追加的會話日誌——系統提示、推理、工具調用與結果、子智能體調度，以及每一次上下文注入。

這套日誌默認不是普通文本。官方持久化子系統 dsh-session-persistence-jsonl 把每條會話存成帶校驗的 zstd 多幀串聯：一個文件裏首尾相接許多個 zstd frame，而不是單幀壓縮包。進程被強殺、寫入中斷、或者用單幀解碼 API 去讀多幀文件時，常見結果不是報錯，而是隻看見 header，誤判成「會話全空」。

dsh-session-health 把這件事做成模型可調用的工具：掃描 $DSH_HOME/sessions 下的會話文件，做幀級診斷，輸出健康報告和清理建議。它只讀，不改、不刪。下面按社區目錄頁、GitHub 倉庫 README / package.json / 源碼，以及 DeepSeek Harness 官方倉庫交叉覈對後整理。

這是什麼

dsh-session-health 是一款 會話與消息 類 DSH 插件，由社區組織 omdsh-dev 維護，倉庫在 omdsh-dev/dsh-session-health，許可證 MIT。包名是 @deepseek-ai/dsh-session-health，安裝後註冊工具 session_health，profile 層 id 爲 tool-session-health。社區目錄收錄於 2026-08-09，倉庫最近一次推送在 2026-08-14；本文覈對當日 GitHub API 顯示 8 星。

需要先分清兩層來源。DeepSeek Harness 本身由 DeepSeek AI 開發，官方倉庫是 deepseek-ai/deepseek-harness，目前仍是 developer preview，文檔寫明會有破壞性變更。本文引用的插件目錄 deepseek-harness-plugin.com 是獨立社區站點，About 頁寫明與 DeepSeek / High-Flyer（幻方）無從屬、背書或贊助關係，也不託管插件代碼。omdsh-dev 組織簡介同樣寫明：非官方社區插件收錄組織，與 DeepSeek 無隸屬或授權關係。

它解決的問題很具體：會話文件在磁盤上是不是完整的 zstd 多幀日誌，有沒有 torn write、結構損壞、空文件、明文 .jsonl 殘留，以及 stray 臨時文件。它不負責修復，也不改會話內容。

核心功能

幀級掃描，而不是整包解壓

倉庫 README 寫明：DSH 會話文件是多個 zstd frame 的串聯。官方文檔與社區討論（例如 Discussion #2165）也把 JSONL 會話描述成 concatenated Zstandard frames。dsh-session-health 因此先做 幀邊界掃描：用 DataView 按 RFC 8878 讀 magic、幀頭、塊頭，統計完整幀數，標出尾部截斷，不解碼 block 數據。源碼註釋寫明，這套掃描器與官方 scanZstdFrames 做過分幀差分；官方對非法結構 throw，本工具則返回結構化錯誤碼，方便診斷。

默認掃描根目錄是 $DSH_HOME/sessions。未設置 DSH_HOME 時，源碼回落到 ~/.dsh。會話文件的常見路徑是：

$DSH_HOME/sessions/<cwd 編碼>/<session-id>/session.jsonl.zstd

源碼 files.ts 還記錄了 Windows cwd 的編碼方式：\ 換成 -，盤符 C: 換成 C-，外層再用 -- 包起來。枚舉只走兩級目錄，識別 session.jsonl.zstd、明文 .jsonl，以及 *.tmp / *.tmp.zstd。

檢測項

幀級掃描能標出的問題，目錄頁與 README 一致，源碼 report.ts 再分成 errors 和 suspicious 兩桶：

類別 判定
missing 會話 id 解析不到文件
empty 0 字節文件
not-zstd 前 4 字節不是 zstd magic 28 b5 2f fd（明文 .jsonl 或損壞）
torn EOF 打斷幀尾部（寫入中斷）
reserved-header / reserved-block 幀頭或塊頭保留位非法
bad-header deep 模式：首幀不是 session header
empty-session 只有 1 幀（header）且超過 1 分鐘未更新
oversized-single-frame 單幀大於 1MB（源碼閾值 1_000_000 字節）
interrupted deep 模式：有 turn/start 無對應 turn/end
stray-file *.tmp 或非標準命名殘留

報告字段包括：root、scanned、errors、suspicious、totals（字節、幀數、事件批次估算）、detail、deep、suggestions。suggestions 按 issue 模板給出清理或修復建議，不自動執行。事件批次估算等於「幀數 - 1」，README 明確寫了這不是精確事件數。

只讀與路徑圍欄

這是插件反覆強調的邊界，目錄頁、README 和源碼註釋一致：

  • 只讀：不修改、不刪除任何文件。測試 files.spec 的 SH-06 用例覆蓋「掃描後文件字節數不變」。
  • 路徑圍欄：會話 id 只允許 [A-Za-z0-9._-]+，拒絕 ../、盤符、空白和控制字符；絕對路徑與最終文件都做 fs.realpath containment；枚舉用 lstat，符號鏈接直接跳過。
  • 輸入範圍固定：只看 sessions 目錄，無網絡、無執行面。
  • 零業務依賴：幀掃描器是獨立實現，不引入 zstd 原生庫。

deep: true 時纔會動態 import 官方解碼器 @deepseek-ai/dsh-session-persistence-jsonl/src/zstd.ts。解析失敗會明確降級，報告裏標 deep: "unavailable"，不會靜默當成掃描成功。deep 還有資源上限：壓縮文件超過 16MB 跳過；解壓字節超過 64MB 或事件數超過 20 萬就停止消費後續幀。

註冊的工具

插件導出 apply(ctx)，向 ctx.tools 註冊 session_health，超時 5000ms，輸出 JSON 文本。參數如下：

參數 類型 必填 說明
action string 是 scan / file / stats
path string file / stats 必需 會話根內的絕對路徑，或會話 id
deep boolean 否 深度分析（解碼事件統計），默認 false
detail boolean 否 scan 默認 true，列出異常文件；false 只出彙總

scan 掃整個 sessions 目錄；file 診斷單個會話；stats 只出 totals。scan 在 detail 爲 true 時，只把帶 issue 的文件放進 detail，不是全量清單。

安裝與啓用

目錄頁給出的安裝命令如下，在 DeepSeek Harness 終端運行：

dsh plugin add github:omdsh-dev/dsh-session-health

如需可復現安裝，目錄頁要求固定 commit 哈希。本文覈對時 main 最新提交是 72065059cec89c5577b19ee8aaa26ebc2c34fbbf（2026-08-14）：

dsh plugin add github:omdsh-dev/dsh-session-health#72065059cec89c5577b19ee8aaa26ebc2c34fbbf

倉庫 README 補充了 profile 寫法。web 與 headless 是 不同 profile：裝到 web 不會自動覆蓋 headless；dsh run 默認走 headless。Windows 路徑用正斜槓。

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

# 一次性任務（headless）profile
dsh plugin --profile headless add github:omdsh-dev/dsh-session-health

安裝後可用下面命令確認 layer 裏出現了 tool-session-health：

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

README 還給出運行驗證：

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

倉庫聲明已遷移到 @deepseek-ai/dsh@0.1.0-rc.6 依賴線，peer 依賴是 @deepseek-ai/cordis@^4.0.1、@deepseek-ai/dsh-tools 和 @deepseek-ai/dsh-invariants。package.json 的 engines.node 爲 ^22.19.0 || >=24.0.0。DeepSeek Harness 仍在 developer preview，裝插件前應對齊自己的 dsh 版本。

典型用法

工具由模型在會話裏調用。README 給出的可復現形態如下。

掃描整個會話目錄：

session_health { action: "scan" }

返回類似：

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

上面的 root 和 scanned: 39 來自倉庫 README 示例，不是你本機的實際數字。本機結果以掃描到的 $DSH_HOME/sessions 爲準。

只看彙總、不列異常文件：

session_health { action: "scan", detail: false }

診斷單個會話，並打開深度分析：

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

path 可以是會話 id，也可以是 sessions 根內的絕對路徑。越界、符號鏈接、含 ../ 的 id 都會被拒絕。stats 與 file 類似，但報告裏不帶 detail。

若只想讓智能體跑一遍目錄健康檢查，可以直接用 README 的 dsh run 例句。注意：這條命令走 headless profile，需要事先把插件裝進 headless，只裝 web 不夠。

適用場景與注意事項

適合這些情況：

  • 會話列表裏出現空白、打不開、或懷疑上次強殺把日誌寫斷
  • 想確認磁盤上的 session.jsonl.zstd 是否仍是合法多幀 zstd，而不是明文 .jsonl 或 0 字節文件
  • 需要一份 JSON 健康報告，再決定要不要手工清理 stray / 空會話
  • 給模型一個只讀工具，讓它回答「會話文件健康嗎」，而不是自己寫掃描腳本

使用前注意下面幾條，均能在目錄頁或倉庫裏覈對：

  1. 插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。安裝前應檢查源代碼倉庫和許可證；需要可復現安裝時固定 commit 哈希。這是目錄頁的原文警告。
  2. 它 只診斷、不修復。README 把後續修復指向 dsh-session-repair-skill；本文檢索時該倉庫地址無法打開，因此不要把它當成已經可安裝的配套工具。報告裏的 suggestions 也只是建議文本。
  3. deep 模式在 npm 0.1.0-rc.6 下可能不可用。README 寫明：@deepseek-ai/dsh-session-persistence-jsonl 的 npm tarball 仍不含 src/，根入口也不導出 zstd API，deep 會降級爲 decoder-unavailable。幀級掃描不受影響。
  4. 事件批次是估算值；單幀掃描超時爲 5 秒。會話特別多或文件特別大時，先用 scan + detail: false 看彙總。
  5. 社區目錄不是官方應用商店。裝任何 DSH 插件前，以 GitHub 源碼和許可證爲準。

小結

DSH 把一次運行寫成只追加的多幀 zstd 會話日誌，這讓「文件還在」不等於「文件健康」。dsh-session-health 做的是幀級、只讀、零業務依賴的診斷：掃 $DSH_HOME/sessions，標出 torn、損壞、空會話和 stray 文件，把結果交給模型和你，而不是替你改磁盤。

目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-session-health/

GitHub：https://github.com/omdsh-dev/dsh-session-health

相關文章

快速從零部署一個DeepSeek-R1服務 2025-04-05 使用 dsh-anchored-standard 爲 DeepSeek Harness 配置兩階段 Agent 預設 2026-08-17 用 dsh-web-ui 把 DeepSeek Harness 網頁界面補成工作臺 2026-08-17 用 modlens 給 DeepSeek Harness 的純文本模型補上視覺 2026-08-17 用 dsh-TUI 給 DeepSeek Harness 補上全屏終端界面 2026-08-17
羽毛球分组比赛记分
小程序二维码

欢迎使用《羽毛球分组比赛记分》微信小程序

小夜