前言¶

DeepSeek Harness (DSH) 在處理模型請求失敗時，通常會將錯誤歸一化，例如在界面顯示“本輪運行失敗”。對於開發者而言，上游返回的具體 401、403、429 或 400 錯誤詳情往往隱藏在這一句描述背後。當需要排查密鑰失效、速率限制或請求體格式問題時，缺乏原始報文會導致調試困難。

dsh-request-error-dump 是一款 DSH 插件，旨在解決這一問題。它在模型請求失敗時，將完整的原始請求體和上游錯誤響應體寫入本地文件，保留完整的上下文信息。

核心功能¶

該插件專注於捕獲模型推理過程中的失敗場景，記錄內容包含以下四個區塊：

1. 請求信息 (request)：記錄 URL、HTTP 方法、請求頭（支持脫敏）、請求體原文 (body.raw) 及解析視圖 (body.json)。
2. 響應信息 (response)：記錄狀態碼、狀態文案、響應頭、以及上游返回的原始響應體 (body.raw) 和解析視圖。
3. 傳輸層異常 (transportError)：記錄 DNS 查詢失敗、TLS 握手錯誤、連接超時等網絡層面的異常。
4. DSH 上下文 (dsh)：記錄當前輪次 (turn)、步驟 (step)、提供商 (provider)、失敗原因 (failure) 以及關聯 ID (correlation)。

此外，插件支持配置 bodyFormat（僅 raw / 僅 parsed / 兩者皆有）和 redactHeaders（指定需要脫敏的請求頭名），默認開啓零配置模式，僅抓取模型請求。

安裝與啓用¶

本插件無運行時依賴，安裝後需重啓 DSH 以使配置生效。

# 從 GitHub 安裝
dsh plugin --profile desktop add github:exynos967/dsh-request-error-dump

安裝完成後，失敗的請求記錄將默認保存在 ~/.dsh/request-error-dump/ 目錄下。

配置說明¶

所有配置項均有默認值，不配置亦可正常運行。如需調整，需在 profile 的 cordis.patch.yml 中進行覆蓋：

- id: request-error-dump
  config:
    outDir: ~/.dsh/request-error-dump      # 落盤目錄
    maxFiles: 50                           # 保留最新的文件數量，0 表示不清理
    maxCaptureBytes: 0                     # 單體體積上限（字節），0 表示不截斷
    bodyFormat: both                        # raw / parsed / both
    redactHeaders: ['authorization', 'api-key', 'cookie']  # 脫敏頭列表
    flushDelayMs: 1500                     # 等待上下文補全的延遲時間（毫秒）
    ignoreAborted: true                     # 用戶取消時不記錄
    modelRequestsOnly: true                 # 是否僅抓取模型請求
    excludeUrls: ['/user/balance']          # 排除的 URL 列表（正則匹配）
    log: true                               # 是否在日誌中輸出落盤提示

關鍵參數說明：
* maxCaptureBytes：默認爲 0，表示不截斷請求體。一旦截斷，json 視圖將標記爲 truncated: true。
* redactHeaders：默認脫敏 authorization、api-key 等常見憑證頭。設爲 [] 可關閉脫敏（存在隱私風險）。
* flushDelayMs：默認 1500ms。插件會等待 agent/request-error 事件來補全 DSH 側的上下文信息。設爲 0 則立即寫入。
* excludeUrls：默認排除 /user/balance，防止桌面版餘額組件輪詢導致的垃圾日誌。

判定與隱私¶

插件通過兩條信號判斷是否爲“模型請求”：
1. 權威信號：DSH 循環派發 agent/request-error 事件認領。
2. 兜底信號：請求結構符合模型調用特徵（POST 且 JSON body 包含 model 或 modelId 字段，或命中特定路徑形態）。

隱私邊界：由於請求體通常包含系統提示詞、源碼、工具結果甚至密鑰，插件默認僅脫敏請求頭中的憑證，正文一律原樣保存。請勿在不可信環境或共享目錄中開啓此插件。

誠實邊界¶

插件並非完美，存在以下限制：
* 判定精度：並非 100% 精確，極端情況（自定義網關且無 model 字段）可能漏抓。
* 捕獲範圍：不抓取流中途失敗、FormData/Blob/ReadableStream 請求體（讀取即消費）。
* 前置錯誤：不抓取發請求之前就失敗的錯誤（如密鑰未配置、路由無適配器）。
* 無修改能力：純觀察者模式，不重試、不注入、不修改請求。

結語¶

dsh-request-error-dump 通過攔截 HTTP 請求層，填補了 DSH 標準錯誤處理與開發者調試需求之間的空白。它以零運行時依賴和透明的工作機制，幫助開發者快速定位模型調用失敗的根本原因。

插件目錄 | GitHub 倉庫