前言¶
DeepSeek Harness（DSH）把會話歷史存成逐批追加、帶校驗和的 zstd 幀。這條日誌是人與 DSH 之間交換記憶的唯一介質：一旦某條記錄在加載階段無法通過形狀校驗，整條歷史會報 SessionPersistenceCorruptionError，界面常見「history unavailable … must contain one tool-result block」——相當於人和系統一起「失憶」。
問題往往出在寫入與加載不對稱：寫入路徑不校驗消息形狀，第三方插件在 output.render() 返回裸字符串等違規形態時，寫入不會報錯，直到下次加載才暴露。社區維護的 dsh-session-doctor（imtokenxinluo）針對這類已落庫的損壞做體檢、備份後無損修復，並在 v1.1 起提供實時 watch 告警、v1.2 起提供 blame 事故歸因。下面介紹它是什麼、能做什麼、如何安裝與使用。
這是什麼¶
dsh-session-doctor 是會話體檢與修復工具，面向 DeepSeek Harness：用與 DSH 加載路徑相同的規則掃描存儲的會話日誌，找出會導致歷史加載失敗的損壞記錄，對已支持的那類形狀漂移做無損修復；每次修復前自動備份。維護者爲 imtokenxinluo，在 SkillHub 社區目錄中歸類爲「記憶」，倉庫見 GitHub，許可證 MIT。當前 npm 包版本爲 0.2.3（以 package.json 爲準）。
它與內核側「寫路徑守衛」、兄弟插件 dsh-contract-check 等形成互補：contract-check 偏事前靜態檢查，本工具的 watch 偏實時告警，scan/repair 偏事後修復，裝不裝互不影響。
核心功能¶
scan：按 loader 同款規則體檢¶
遍歷 sessions 根目錄或單個 .jsonl.zstd 文件，校驗每條事件，報告損壞會話、行號、seq、事件類型、涉及的 tool 名與原因。
repair：備份後無損修復（限定形態）¶
對單個損壞文件：先備份爲 <file>.<ts>.bak，再修復 tool-result 塊中 content 不是數組的記錄，幀級重寫（未損壞幀字節不變）；重寫產物複驗 0 失敗才落盤。未知損壞形態只報告、不自動修。
當前支持且不改字的三種形態：
| 形態 | 修法 |
|---|---|
content 爲裸字符串 |
包成 [{type:"text",text:…}] |
content 爲 null 或缺失 |
置爲 [] |
content 爲單個對象 |
包成 [obj] |
數字、布爾等無法安全推斷的形態一律不修。
watch（v1.1）：實時哨兵¶
訂閱 DSH session/event，對 live 會話新寫入的消息事件即時做 loader 同款校驗，違規立刻告警。事件在 append 後才發佈，watch 不阻止寫入、不改 live 文件；修復交給冷會話的 repair。
blame（v1.2）：突然關閉是不是 agent 乾的¶
只讀分析會話日誌：定位中斷斷點，回看斷點前工具調用鏈，匹配殺進程、關瀏覽器、自重啓 harness 等危險模式。雙重證據門檻下判定 AGENT-CAUSED、EXTERNAL 或 NO-ACCIDENT；日誌尾部 torn frame 會標註證據缺失。
safeguard（0.2.2 起）¶
一條命令串聯：冷備整棵 sessions 樹 → 體檢 → 修復 → 回讀校驗。冷備失敗則中止，絕不進入修復。
設置面板「會話體檢」（0.2.2 起）¶
GET /session-doctor/report 只讀展示結論；POST /session-doctor/repair 需顯式觸發修復。0.2.1 及更早裝進 profile 後僅有實時哨兵，無面板與上述路由；CLI 的 scan/repair/blame 仍可用。判斷是否含面板：看 node_modules/dsh-session-doctor/package.json 的 version，或該目錄下是否存在 lib/client.js。
完整損壞形態與「能修 / 只報告」說明見倉庫 docs/DEFECT-CATALOG.md。
安裝與啓用¶
README 寫明：獨立包，暫不註冊進 profile。CLI 不依賴 DSH 運行環境，需 Node >= 22，零運行時依賴（僅用 Node 內置模塊）。
在克隆或解壓倉庫後於項目根目錄執行：
npm link
也可直接運行：
node bin/dsh-session-doctor.js
作爲 DSH cordis 服務插件時，接縫在 src/，可通過 profile 註冊以啓用 watch；默認不裝。安裝任何 DSH 插件前，應自行查看源碼與 MIT 許可證；插件在 DSH 進程權限下運行，與宿主同權。
典型用法¶
掃描與修復單文件：
dsh-session-doctor scan <sessions-root>
dsh-session-doctor scan-file <file>
dsh-session-doctor repair <file> [--dry-run]
dsh-session-doctor blame <file|root>
動手前全局快照（先 dry-run，確認後再 apply）：
dsh-session-doctor safeguard <sessions-root> --backup-to <backup-dir>
dsh-session-doctor safeguard <sessions-root> --backup-to <backup-dir> --apply
順序固定爲：冷備 → 體檢 → 修復（每文件仍留 .bak）→ 重掃校驗。清單寫在 <backup-dir>/doctor-backup-manifest.json。
GUI 報 history unavailable 且提示 tool-result block 時：對該會話文件 scan-file 確認，再 repair。想查哪個插件違反 render 契約，可用倉庫腳本 scripts/audit-render-contract.mjs <插件 src/lib>。
適用場景與注意¶
| 場景 | 建議 |
|---|---|
| 歷史無法加載，懷疑 tool-result 形狀錯誤 | scan-file → repair |
| 擔心插件再次寫壞記錄 | profile 啓用 watch，或定期 scan |
| DSH 升級後懷疑舊會話 | 按倉庫 docs/PATCHES.md 覈對 |
| 瀏覽器或 DSH 突然關閉 | blame 只讀歸因 |
repair 只處理上述 content 非數組一族；其它損壞請依賴報告與冷備，勿指望自動改寫。長期增量冷備可與 dsh-session-backup 等分工並用；safeguard 側重「本次修復前」的就地快照。
SkillHub（https://www.skillhub.cn/plugins/imtokenxinluo/dsh-session-doctor）是社區插件目錄，與 DeepSeek / 幻方無官方從屬關係；DSH 生態理念是「一切皆插件」，本工具是社區在記憶與會話持久化邊界上的補充，而非官方內置能力。
結尾¶
dsh-session-doctor 把「加載時才爆炸」的會話損壞變成可掃描、可備份、可有限無損修復、可實時告警、可 blame 歸因的問題，適合長期跑 DSH、依賴歷史連續性的開發者。詳情與更新以倉庫 README 爲準。
- 社區目錄：https://www.skillhub.cn/plugins/imtokenxinluo/dsh-session-doctor
- GitHub：https://github.com/imtokenxinluo/dsh-session-doctor
