前言¶
DSH 把會話日誌寫成 session.vN.jsonl[.zstd]，事件之間靠 turn / step 的嵌套和順序維持可讀性。一旦某個事件的座標寫錯了——比如在沒有打開 turn 的情況下寫 tool/ptc-dispatch-start——整個會話在當前 reader 眼裏就變成了 corrupt session，只會報一句「會話損壞」，不會告訴你是哪一條事件、哪一步出了問題。想自己翻文件定位，就得手工解壓、逐行 parse。
下面介紹的 dsh-session-doctor 就是爲這一類問題做的：它只讀、不寫，替你把違反 reader 檢查規則的事件逐個點出來。它對應 deepseek-harness Discussions #11971、#11981、#11121 這一類生命週期問題的排查場景。
這是什麼¶
dsh-session-doctor 是 aturzone 維護的 DSH 插件，分類爲 admin-security，目錄頁顯示星標 0，README 自己標註爲「插件早期、使用 pre-release tag」。
它做的事情可以一句話概括：逐條解碼 session.vN.jsonl[.zstd] 裏的事件，重放當前 reader 生效的 turn/step/scope 規則，然後報出具體是哪個序號、哪種事件類型、哪條規則不再成立。全程只讀，不會寫入會話文件。
它能查到什麼¶
README 列出的檢查項有四類：
- turn/step 座標完整性：
turn/start/turn/end/step/start/step/end的嵌套與順序。 - 在同一個未結束的 turn 內 step 編號重新開始。
- turn/step 作用域內的事件被寫到了作用域之外：
request/header、request/context、tool/ptc-dispatch-start、tool/ptc-dispatch、assistant/message、tool/call、tool/result的替換記錄等。 - 行級損壞：非法 JSON、缺失 header、非事件行。
需要留意它的定位：這是一個「與當前 V4 reader 對齊的簽名檢測器」，不是完整的格式校驗器。它不重新實現 message payload 校驗、格式遷移，也不處理 zstd 之外的壓縮 framing。所以它給出的結論是「這裏違反了哪些規則」，而不是「這個文件格式上還對不對」。
安裝¶
從 npm 安裝（插件處於早期，用 next 這個預發佈 tag）：
dsh plugin --profile web add dsh-session-doctor@next
從 Git 倉庫安裝，命令會觸發 package 的 prepare 構建：
dsh plugin --profile web add git+https://github.com/aturzone/dsh-session-doctor.git
package.json 裏的 engines 限定 dsh >=0.2.2-rc.1 <0.3.0、node >=24.9.0，前者依賴 @deepseek-ai/cordis ^4.1.0，後者 @deepseek-ai/dsh-tools >=0.2.2-rc.1 <0.3.0。項目使用 zstd 解壓，所以 Node 版本要求不低。許可證是 MIT。
作爲 bundle 啓用¶
裝好之後 bundle 只往配置裏插入一行插件聲明。插件會註冊一個面向模型調用的 session_doctor 工具，掃描 $DSH_HOME/sessions（也可以傳 sessionsRoot 參數），返回和 CLI 相同的報告，同樣是只讀。
如果想在本地 checkout 上用覆蓋文件做開發調試，README 給的做法是先寫 overlay：
# overlay.yml
- insert:
- id: session-doctor-dev
name: /absolute/path/to/dsh-session-doctor/src/index.ts
然後帶着 patch 啓動：
pnpm dsh web --patch ./overlay.yml
這一步的意義是把源碼路徑直接掛進正在運行的 dsh，不必先打包發佈。
當 CLI 用¶
不想走模型工具、只想在腳本里巡檢一遍時，可以直接調命令行：
session-doctor [--home <DSH_HOME>] [--sessions-root <dir>] [--json] [--all-generations]
參數行爲按 README 整理：
- 默認先找
$DSH_HOME/sessions，找不到再退回~/.dsh/sessions。 - 默認只檢查每個會話裏版本號最高的那個 canonical generation；加
--all-generations會把保留下來的更早版本一起校驗，比如session.v3.jsonl與session.v4.jsonl並存的情況。 --sessions-root既可以傳會話根目錄，也可以只傳某一個 workspace bucket，例如--sessions-root .../sessions/--my-project--。- 退出碼：
0乾淨、1發現可疑 generation、2用法或 I/O 出錯。--json打印結構化報告，便於接進別的腳本。
這些退出碼可以直接當 CI 裏的判定條件用。
輸出長什麼樣¶
README 給的示例輸出大概長這樣：
session root: /home/me/.dsh/sessions
sessions: 12 scanned, 1 with reader-incompatible signatures
✗ --home-me-project--/session-8bc9…
file: …/session.v4.jsonl.zstd
events: 41, version: 4
- seq 22 tool/ptc-dispatch-start: turn-scope: tool/ptc-dispatch-start outside an open turn
- seq 23 tool/ptc-dispatch: turn-scope: tool/ptc-dispatch outside an open turn
報告會落到具體文件、事件總數、版本號和出問題的序號，拿到之後可以直接去對應位置看上下文。
適用場景與注意¶
適合這幾類人：會遇到 corrupt session 報錯、想自己定位而不是等上游修的 DSH 使用者；想審計一批歷史會話是否適用當前 V4 reader 規則的維護者；想在 CI 裏蹲住會話落盤格式變化的項目。
使用前需要注意三點。
- 插件以當前 dsh 進程的權限運行，安裝前應當自己過一遍源碼，確認
cordis.patch.yml這類 patch 沒有超出預期。許可證是 MIT，但「MIT」不等於「可以無腦裝」。 - 它是檢測器，不是修復工具。README 明確說目前沒有 repair 或 quarantine 能力，報告給出缺陷之後，要不要把壞掉的 generation 挪走仍是人工決策。
- 規則對齊的是發佈時的 V4 reader，future 格式版本（
session-format-vN-to-vN+1）需要跟着更新這個插件。另外默認只掃最高 generation，歷史版本不傳--all-generations就看不到，這是設計使然，不是漏檢。
社區目錄（skillhub.cn）是獨立站點，與 DeepSeek、幻方沒有官方從屬關係，插件列表別當成官方應用商店來引用。
結尾¶
dsh-session-doctor 的價值在於把「會話損壞」這種沒法再往下查的報錯，拆成「第幾行、哪種事件、哪條規則違規」。它只讀、不改文件、不承諾修復，代價是要跟 dsh reader 的版本一起維護規則。排查 corrupt session 時，先把這個插件跑一遍，比手工解 zstd 再逐行 parse 省事。
- 目錄頁：https://www.skillhub.cn/plugins/aturzone/dsh-session-doctor
- GitHub：https://github.com/aturzone/dsh-session-doctor
