前言¶
在 DeepSeek Harness（DSH）裏做帶工具調用的對話時，會話歷史會按幀寫入本地的 session.v4.jsonl.zstd。上游對消息結構有硬性約定：助手消息裏聲明瞭幾個工具調用，緊跟着就必須有同樣數量、一一對應的工具結果，中間不能夾別的塊。DSH 會把一條助手消息切成多段；若順序變成「工具調用 → 文本 → 工具調用」，切開之後就會出現「某次調用的結果不再是緊接的下一條」，請求會被拒收，且錯誤會在每一輪重放。
手工改 zstd 幀、搬備份既慢又容易碰壞 seq 連續性。下面介紹社區插件 dsh-session-fix：在 DSH 設置頁裏掃描會話、選中後一鍵修復，並在失敗時回滾。
這是什麼¶
dsh-session-fix（GitHub：CalamitySpiritKite/dsh-session-fix）由維護者 CalamitySpiritKite（作者署名：汐）發佈，分類爲 admin-security，MIT 許可，當前包版本 0.1.1。
它只做一件事：把 assistant/message 裏落在工具調用之後的 text / reasoning 塊挪到所有 tool-call 塊前面，使結構符合「非調用塊在前、調用塊在後」，從而消除 tool_use ids were found without tool_result blocks immediately after 一類錯誤。不刪記錄、不改記錄類型、不改動 user / assistant 聊天正文字節。
典型報錯與真因¶
適合用它的情況包括：每輪對話都失敗，報錯類似：
messages.3.1: `tool_use` ids were found without `tool_result` blocks
immediately after: call_xxxxxxxx (INVALID_REQUEST)
或會話打不開、歷史加載失敗，但會話文件仍在磁盤上。
若問題是憑據失效、網絡超時、版本不兼容、配置讀不進去，應另查原因，不要指望本插件。
核心功能¶
設置頁一鍵流程¶
安裝並重啓 DSH 後，在 設置 → 會話修復 中：掃描本地會話、勾選需要處理的條目、執行修復。插件跑在 DSH 進程內，不需要退出 DSH；需先切換到別的會話，不要修復當前正在打開、仍在追加寫入的那條（列表中會標爲「被佔用」）。
修改範圍與校驗¶
- 會話日誌是一串 zstd 幀；僅重壓改過的幀（checksum 與 DSH 寫法一致），未改幀原樣複製，幀數與邊界不變。
- 修復完成後從磁盤重讀自查：記錄數不變、
seq連續、殘留病竈爲 0、調用與結果配對完整；任一項失敗則當場回滾。
備份與回退¶
修復前原文件在同目錄改名爲：
session.v4.jsonl.zstd.before-fix-2026-10-31_20-15-33
要回退：去掉 .before-fix-<時間戳> 後綴，覆蓋回 session.v4.jsonl.zstd。默認同一會話只保留最近 3 份備份，更早的自動清理；可在插件配置裏用 keepBackups 調整（最少留 1 份，剛寫入的那份不刪）。
能修與不能修¶
| 情況 | 說明 |
|---|---|
| 能修 | 上述「工具調用之間夾了文本/reasoning」導致的 pairing 錯誤 |
| 不修 | 文件整段丟失、seq 斷檔、調用與結果數量對不上、幀無法解壓、報錯不屬於結構類 |
| 不碰 | 當前打開中的會話、其它會話目錄、記憶與附件、非本會話的備份前綴 |
安裝與啓用¶
本插件爲標準 DSH 插件包（dsh.bundle.patch + dsh.client）。在 profile 目錄（默認 %USERPROFILE%\.dsh\profiles\<profile>）執行，使用 pnpm，不要用 npm（profile 爲 pnpm 工作區）。安裝前需本機有 git。
從 GitHub 安裝（README 推薦）：
# 在 profile 目錄裏（默認 %USERPROFILE%\.dsh\profiles\<profile>）
pnpm add github:CalamitySpiritKite/dsh-session-fix
裝完後確認 cordis.patch.yml 含：
- id: dsh-session-fix
name: dsh-session-fix
然後重啓 DSH，左側設置會出現「會話修復」。
卸載：pnpm remove dsh-session-fix，並刪除 cordis.patch.yml 中對應條目，再重啓。
本地改代碼可用 pnpm add link:<clone 目錄絕對路徑>（README 中的本地鏈接方式）；社區目錄頁與 GitHub 倉庫爲獨立信息源，安裝命令以 README 爲準。
適用版本與環境¶
- 會話格式 v4（
session.v4.jsonl.zstd） - Node ≥ 22.15（需內置 zstd 支持；桌面版自帶運行時一般滿足）
- README 寫明在 DSH 0.2.1-rc 系列上實測
典型用法與自測（可選）¶
日常用法：切換離開待修會話 → 打開 設置 → 會話修復 → 掃描 → 選中 → 修復 → 回到該會話繼續對話。
倉庫提供只讀/臨時目錄寫入的自測腳本（路徑按本機會話目錄替換）：
node tools/selftest.mjs "%USERPROFILE%\.dsh\sessions\<某個>\session.v4.jsonl.zstd"
node tools/e2e.mjs "%USERPROFILE%\.dsh\sessions\<某個>\session.v4.jsonl.zstd"
適用場景與注意¶
適合：已在 DSH 中遇到 tool_use / tool_result 結構錯誤、且 session.v4.jsonl.zstd 仍在的開發者或運維。
務必知曉：
- 插件以當前 DSH 進程權限讀寫會話目錄；安裝前應閱讀源碼與 MIT 許可證，確認可接受其備份與原子替換行爲。
- 會話記錄是唯一真源，無回收站；勿在運行中刪除會話目錄，刪除前先複製備份。
- DSH 生態強調「一切皆插件」；SkillHub 目錄頁 爲社區收錄，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-session-fix 針對 v4 會話裏「助手塊順序寫壞」這一具體故障，用設置頁掃描、備份、修復與自檢閉環，避免手工編輯 zstd。更多信息見 目錄頁 與 GitHub 倉庫。
