前言¶
DeepSeek Harness 生態採用“一切皆插件”的理念。在開發智能體或使用 DSH 時，開發者常遇到這樣一個問題：文檔聲稱服務器支持某項 OpenAI 兼容協議特性，但在實際調用時卻因參數錯誤或流式處理異常而中斷。dsh-compat-probe 專門解決這一問題。
插件介紹¶
這是一個 DeepSeek Harness 插件，名爲 compat_probe。它發送五個微型 fixture 請求到目標 OpenAI 兼容服務器，並返回一個“協議卡”。這張卡由一組布爾值組成，精確描述服務器實際實現了哪些功能，而非文檔聲稱的內容。它主要用於回答那些會在 Harness 運行時導致崩潰的問題：服務器是否在線？GET /models 是否有響應？stream: true 是否返回 Server-Sent Events？服務器是接受 max_tokens、max_completion_tokens 還是兩者都拒絕？
核心功能¶
- 協議兼容性探測：兼容 OpenAI 服務器協議。
- Fixture 測試：發送五個微型請求並返回協議卡。
- 細節檢查：檢查協議實現細節，包括流式傳輸類型、
max_tokens、max_completion_tokens等。 - 無額外依賴：不包含 GGUF 權重，不啓動
llama-server或任何其他進程。 - 離線測試：支持離線測試（使用
node:httpmock）。
安裝與啓用¶
使用官方安裝命令進行添加：
dsh plugin --profile web add github:jwilson411/dsh-compat-probe
安裝器會讀取 dsh.bundle.patch 並將 cordis.patch.yml 追加到配置中。安裝後，需確保依賴版本正確，否則可能導致輸出格式不匹配：
npm install @deepseek-ai/dsh-tools@0.1.1-rc.2
配置¶
在插件的 cordis.patch.yml 中設置以下字段：
baseURL：目標服務器的地址，包含 API 前綴（如/v1），例如http://127.0.0.1:8080/v1。apiKey：認證密鑰。發送爲Authorization: Bearer，建議使用環境變量DSH_COMPAT_PROBE_API_KEY而非直接寫入配置。allowRemote：是否允許探測非迴環地址。默認爲false，必須顯式設爲true才能探測其他主機。model：fixture 請求中使用的模型 ID。timeoutMs：每個請求的超時時間（毫秒），默認爲 3000。
探測卡¶
工具返回一個對象，包含以下字段：
reachable：是否收到任何 HTTP 響應。models_ok：GET {baseURL}/models是否返回 2xx 狀態碼。stream_sse：stream: true是否返回 Server-Sent Events（text/event-stream或data:幀）。stream_ignored_json：stream: true是否被忽略，返回了一個非流式的 JSON 完成對象。honors_max_tokens：服務器是否接受max_tokens參數。honors_max_completion_tokens：服務器是否接受max_completion_tokens參數。http_status：第一個非 2xx 狀態碼，或最後一個成功狀態碼，或null（無連接）。error_code：錯誤代碼（UNREACHABLE,HTTP_ERROR），僅在失敗時存在。
注意事項¶
- 安全默認值：默認僅探測迴環地址（
localhost,127.0.0.1,::1）。拒絕非迴環目標直到顯式允許。迴環判斷基於寫入的地址，而非解析結果。 - 非測試工具：不是 Ollama、負載測試器或 GPU 基準測試工具。
- 非客戶端：不是託管 OpenAI 或 Anthropic 的客戶端。
- 無權重/進程：不包含 GGUF 權重或下載功能，不啓動
llama-server或任何其他進程。
結語¶
該工具專注於協議驗證與兼容性確認，而非性能測試。它通過結構化數據回答“服務器實際上能做什麼”，幫助開發者避免運行時錯誤。相關資源請參考目錄頁與 GitHub 倉庫。
