前言¶
在 DeepSeek Harness（DSH）裏跑帶圖會話時，若本地附件庫裏的對象文件被刪或丟失，同一條會話可能每一輪都在發請求前就失敗，界面反覆出現 執行出錯 · DeepSeek Messages transport failed（code TRANSPORT）。換網絡、代理或 API Key 往往無效，同機其它會話卻正常——這是因爲錯誤發生在請求準備階段讀附件，與網絡無關。手動改 zstd 會話日誌或只能新開對話，成本高且易誤操作。下面介紹社區插件 dsh-fix-attachments（維護者 xuzhunzhi）：在 agent 請求失敗時自動把讀不出來的圖片降級爲佔位文本並重試，另提供離線 CLI 做批量掃描與修復。
這是什麼¶
dsh-fix-attachments 是面向 DSH 桌面使用場景的社區插件（MIT，npm 包名 dsh-fix-attachments，當前 package 版本 0.1.0）。它針對「內容尋址附件對象不在 <DSH_HOME>/attachments/v1/objects/<sha256前2位>/<sha256> → prepareImages 拋 ATTACHMENT_NOT_FOUND → 適配器兜底包成 TRANSPORT」這條鏈路做止血：不恢復已丟失的圖片字節，但讓該會話可以繼續發消息。
插件形態與離線 CLI 共用同一套「視圖上是否真有讀不出的圖」判定；平時推薦裝進 profile，進程內自愈，無需每次手改日誌。
怎麼判斷是不是這個問題¶
對照 README 中的特徵，若高度吻合即可考慮安裝：
- 某條會話每輪失敗，文案爲
DeepSeek Messages transport failed（TRANSPORT）。 - 失敗很快（約 20–60 毫秒），尚未發出 HTTP 請求——這是與真網絡故障區分的關鍵。
- DSH 自動退避重試若干次仍失敗，而同機其它會話正常。
- 該會話歷史裏曾讀圖、傳圖；對象文件可能已被清理或丟失。
核心功能¶
進程內插件（推薦）¶
插件掛在 agent loop 的 agent/request-error waterfall（與官方上下文溢出恢復、圖片預算 offload 同類擴展點）。請求失敗時：
- 檢查失敗碼是否爲
TRANSPORT/ATTACHMENT_NOT_FOUND。 - 掃描當前視圖
session.surface.nodes（已被 compaction 陰影的老消息排除），逐個檢查圖片引用對應對象是否存在；已標記 offloaded 的跳過。 - 對缺失對象調用官方機制
session.append('image/offload', { targets })，將圖片換成佔位文本；隨後await ctx.sessions.flush(session)做持久化。 - 返回
{ kind: 'retry' }，讓該輪立即重試（不消耗 provider 重試預算，也不記llm/retry）。 - 若無缺圖可修，則
next()，把真實網絡錯誤交給下游。
設計要點：依據「視圖上是否真有讀不出的圖」而非猜測錯誤鏈，避免掩蓋真網絡故障；同一輪修復次數受 maxRepairsPerTurn 上限約束，修過的圖變爲 offloaded 後不會反覆觸發。
離線 CLI¶
DSH 無法啓動，或需要對所有會話做體檢時，可使用包內 CLI（需 Node ≥ 22.15）：
node cli/bin/dsh-fix-attachments.mjs scan
node cli/bin/dsh-fix-attachments.mjs fix --apply
node cli/bin/dsh-fix-attachments.mjs backups --session <id>
node cli/bin/dsh-fix-attachments.mjs restore --session <id> --apply
CLI 逐幀解壓 session.vN.jsonl.zstd，自行計算 compaction 陰影集，追加帶 checksum 的 image/offload 幀；寫前備份、寫後複覈。運行中若 DSH 仍在跑、日誌末尾撕裂、或會話格式版本不支持，會拒絕寫入（CLI 僅認會話格式 v4）。
安裝與啓用¶
通過 DSH 插件命令安裝到 desktop profile（npm 已發佈，也可在插件中心一鍵裝）：
dsh plugin --profile desktop add dsh-fix-attachments
若不走 npm，資料中給出的源碼安裝方式爲：
dsh plugin --profile desktop add github:xuzhunzhi/dsh-fix-attachments
裝完重啓 DSH 即可，無其它必填配置。資料明確：不要爲安裝手寫 profile 的 package.json 或 patch 裏的 insert 行；安裝只走 dsh plugin ... add，由包內 cordis.patch.yml 聲明 entry。
可選配置在 profile 的 cordis.patch.yml 中按 entry id 覆蓋（config 爲整體替換）：
- id: dsh-fix-attachments
config:
objectsRoot: 'D:\other-dsh-home\attachments\v1\objects'
maxRepairsPerTurn: 3
確認插件已加載：查看留痕文件（每次修復會更新計數）：
cat ~/.dsh/storages/dsh-fix-attachments-state.json
mountedAt 有值表示已掛載；repairs / lastRepair 反映實際修復次數與涉及的 seq。
典型用法與邊界¶
日常：安裝插件並保持啓用。某輪因缺圖觸發 TRANSPORT 時，用戶側往往只感到「卡了一下」，同一會話可繼續對話。
批量或 DSH 起不來：先退出 DSH，再 scan 看影響範圍，fix --apply 寫入前務必理解 CLI 會改會話日誌；需要時用 restore --apply 回滾。
務必知曉的邊界（來自上游 README）：
- 圖片不會回來；對象字節丟失無法還原，只是讓會話可繼續。
- 不修根因；附件對象仍可能再次消失，長期仍建議保持插件啓用。
- 只處理圖片塊；
file等類型不參與prepareImages，不在修復範圍。 - 插件在當前 DSH 進程權限下運行，安裝前請自行審閱 GitHub 源碼 與 MIT 許可證；社區項目與 DeepSeek AI 無隸屬關係。
兼容性（資料記載）：DSH 0.2.1-rc.5 實測可用；Windows / macOS / Linux；同一缺陷在上游 discussions 中仍有報告，本插件屬於社區側止血方案。
結尾¶
若你遇到「單會話每輪 DeepSeek Messages transport failed、毫秒級失敗且歷史含圖」這一類問題，dsh-fix-attachments 提供進程內自動 offload 重試與離線修復兩套手段，避免只能棄用會話或手改 zstd 日誌。
