前言¶

在 DSH 中處理 DeepSeek 工具調用時，有些失敗看起來像“模型抽風”，但根源可能在請求和響應的拼接上：工具結果已經傳回，請求仍可能報錯；流式輸出看起來正常，最後拼出的參數卻不是合法 JSON；同一段 history 在打開或關閉 thinking 後表現不同。

DeepSeek Protocol Doctor 是一個第三方 DSH 插件，用於離線檢查 DeepSeek 請求、工具循環、reasoning_content 和 SSE / JSONL 流。它只檢查給定的請求內容或錄製流，不調用模型，也不判斷回答質量。

這是什麼¶

DeepSeek Protocol Doctor 由 Whning0513 維護，採用 MIT 許可。它爲 DSH 增加兩個檢查工具：

• deepseek_protocol_check：檢查請求和消息歷史。
• deepseek_stream_check：檢查保存下來的 SSE / JSONL 流。

它也可以作爲 Agent Skill 使用。倉庫提供 skills/deepseek-protocol-doctor 目錄，DSH 可從 .agents/skills/、.dsh/skills/ 以及用戶目錄下的對應位置自動發現。Skill 只負責把排查步驟組織好，實際協議檢查仍調用同一套 dsv4-doctor。

能檢查哪些問題¶

下面列出的檢查項來自當前已覈實能力。工具主要面向工具調用協議、流式響應拼接和常見配置項。

• tool_call_id 缺失。
• 同一輪 tool call 未收齊就進入下一輪。
• reasoning_content 被客戶端丟掉。
• function.arguments 未拼完就被當成 JSON 解析。
• 多個流式 tool call 的 delta 交錯到達，客戶端按到達順序直接追加。
• strict schema 缺少 required 或 additionalProperties: false。
• max_tokens、thinking mode 和 /beta 路由中的相關配置。

每條問題會有固定 code，方便在 CI 中處理。輸出支持 text、JSON 和 SARIF。退出碼可用於區分 error 或 warning；warning 默認不攔 CI，需要更嚴格時加 --fail-on-warning。

安裝到 DSH¶

插件需要 Python 3.10+。如果 Python 安裝在別處，可以設置 DSV4_DOCTOR_PYTHON。

下面命令用於把插件安裝到 DSH 的某個 profile。命令中的 demo 是 profile 示例，需要替換爲實際 profile：

dsh plugin --profile demo add github:Whning0513/deepseek-protocol-doctor

安裝完成後，DSH 中會新增兩個工具。可以直接這樣調用：

用 deepseek_protocol_check 看看這個請求裏的工具調用哪裏不對：{ ... }

作爲 Agent Skill 使用¶

倉庫中的 skills/deepseek-protocol-doctor 是 DSH 可自動發現的 Skill 目錄。DSH 會從 .agents/skills/、.dsh/skills/ 以及用戶目錄下的對應位置發現它。

如果想把 Skill 放到當前項目的共享目錄，可以先執行：

mkdir -p .agents/skills
cp -R /path/to/deepseek-protocol-doctor/skills/deepseek-protocol-doctor .agents/skills/

這裏把 /path/to/deepseek-protocol-doctor 替換爲倉庫在本機的實際路徑即可。複製後，DSH 仍會通過同一套 dsv4-doctor 執行檢查。

命令行用法¶

在倉庫目錄裏可以先創建虛擬環境並安裝：

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .

安裝後可以運行示例數據：

dsv4-doctor check fixtures/valid_tool_loop.json
dsv4-doctor check fixtures/invalid_tool_loop.json
dsv4-doctor stream fixtures/stream_interleaved.jsonl

如果不安裝，也可以直接通過 Python 模塊運行：

PYTHONPATH=src python -m dsv4doctor check fixtures/valid_tool_loop.json

check 接受完整的 OpenAI-compatible 請求，也接受單獨的 messages 數組；stream 接受 SSE 和 JSONL。

如果需要機器可讀結果，可以輸出 JSON 或 SARIF：

dsv4-doctor check request.json --format json
dsv4-doctor check request.json --format sarif > result.sarif

適用場景與注意事項¶

這個插件適合 DSH / 智能體開發者在排障或 CI 中檢查請求結構、工具循環和流式拼接。它不是 benchmark，也不會判斷回答質量。

使用時需要注意：

• 這是第三方項目，不是 DeepSeek 官方組件。
• 它沒有內置 tokenizer，只做靜態的 max_tokens 檢查，不給出假裝精確的 token 數。
• OpenRouter、vLLM、SGLang 和其他兼容接口可能有自己的行爲，目前還沒有完整覆蓋。
• DSH 還在 developer preview；如果上游插件接口變化，這裏的包裝也需要跟着改。
• 工具不會替你補一段假的 reasoning_content。這個字段應該保存模型原始返回值。
• 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。

GitHub 倉庫：Whning0513/deepseek-protocol-doctor