DSH 將每個會話存儲爲一個目錄，其中包含每個格式生成的單個不可變文件。升級到 0.1.5 後，遷移的最終步驟是一個封閉式詞彙審計：每條消息必須攜帶 source.kind，且該值必須來自一個固定的 15 個值集合。任何過時的值都會導致整個遷移中止，從而使會話無法打開。即便會話列表正常顯示，點擊打開時也會收到通用的 gateway/internal 錯誤。
dsh-sessions-diagnosis 插件通過在 CLI、代理工具或 DSH Web UI 中運行 DSH 官方的遷移鏈，來解決這一問題。
核心功能¶
該插件提供三種核心能力：
- 診斷：運行 DSH 發佈的官方遷移鏈，報告的原因與 Harness 實際遇到的完全一致。它會將每個會話分類爲
ok、unmigrated、repairable、unrepairable等，並指出具體的錯誤字段。 - 修復：生成有效的當前格式後繼者。原始文件不會被修改。當 DSH 的 codec 無法訪問時，如果規則匹配，會進行原地修復（帶字節級備份且可撤銷）。
- 可視化：在 DSH Web UI 的 Settings → Session diagnosis 中提供儀表板。顯示所有會話的判定結果、原因，並提供預覽修復步驟的“一鍵修復”功能。
安裝與啓用¶
使用官方安裝命令將插件添加到 Web Profile：
dsh plugin --profile web add github:YouHui1/dsh-sessions-diagnosis
該命令會下載預構建的 JavaScript，無需構建步驟或依賴安裝。安裝後，重啓 DSH 並刷新瀏覽器。儀表板將出現在 Settings → Session diagnosis 中。
典型用法¶
插件提供了一個名爲 dsh-session-doctor 的命令行工具。
掃描與診斷¶
# 查看會話存儲中的內容
dsh-session-doctor scan
# 對所有會話進行分類診斷
dsh-session-doctor diagnose
# 診斷特定會話的詳情
dsh-session-doctor diagnose <id>
修復會話¶
# 對特定會話進行試運行（不寫入任何內容）
dsh-session-doctor repair <id>
# 執行修復
dsh-session-doctor repair <id> --apply
# 修復所有可修復的會話
dsh-session-doctor repair --all --apply
# 撤銷本次工具進行的修復
dsh-session-doctor rollback <id>
# 使用 DSH 的 codec 驗證所有會話
dsh-session-doctor verify
測試與演練¶
# 創建一個模擬的損壞會話（低風險規則：過時的 source.kind）
dsh-session-doctor demo
# 創建一個模擬的損壞會話（中風險規則：過時的描述符版本）
dsh-session-doctor demo --scenario descriptor
# 刪除演示會話
dsh-session-doctor demo --remove --apply
注意：demo 命令寫入一個僞造的損壞會話，該會話不會進入你的真實會話存儲。它使用默認的 <tmp>/dsh-session-doctor-demo 作爲存儲目錄，並拒絕 --root 指向真實存儲的命令。
適用場景與注意事項¶
- 無需重啓：修復會話不需要重啓 DSH，DSH 會在打開時解析世代，修復後的會話在下一次點擊時即可打開。
- 數據安全：原始文件從未被修改。演示會話被隔離在獨立存儲中，不會污染你的會話列表。
- 生態背景：該插件遵循 DSH “一切皆插件”的理念，通過 Cordis patch 機制集成。安裝前建議檢查源碼與許可證（MIT）。
總結¶
dsh-sessions-diagnosis 是一套針對 DSH 升級後會話遷移問題的診斷與修復工具。它提供了 CLI 和 Web UI 兩種操作方式，通過複用 DSH 官方邏輯而非猜測，確保了修復的準確性。
