前言¶

DeepSeek V4-Pro 和 V4-Flash 對外提供 OpenAI 兼容的 HTTP API。很多智能體、LangChain 項目、桌面客戶端因此只改 base_url，就按標準 openai SDK 去調。倉庫 README 寫明：線上協議仍有 16 項標準客戶端不會處理的行爲。比較常見的幾條是：多輪工具循環裏漏掉 reasoning_content 會直接 HTTP 400；思考模式默認開啓，簡單提示也會多消耗 30–300 個推理 token；並行 tool_call 的流式增量按 tc.index 交錯，不能按列表追加。

社區插件目錄把 HenryZ838978 維護的 deepseek-harness 收進「界面增強」。它實際做的不是換皮膚或改側邊欄，而是一層協議感知適配：把這 16 項行爲寫成契約，再用同一份 spec/ 分發成 Python 庫、命令行、MCP 服務器和 SKILL.md。需要先分清名字：DeepSeek 官方的 DeepSeek Harness（dsh）是「一切皆插件」的智能體運行時；本文介紹的是社區維護的同名適配層，不是官方運行時本身。社區目錄是獨立站點，與 DeepSeek / 幻方沒有官方從屬關係。

本文按目錄詳情頁、GitHub README、packages/skill/SKILL.md 和 PyPI 頁面交叉覈對後整理：它解決什麼問題、四種形態怎麼裝、以及官方給出的可復現用法。

這是什麼¶

deepseek-harness 是面向 DeepSeek V4-Pro / V4-Flash 的協議感知適配層，維護者是 GitHub 用戶 HenryZ838978（Henry Zhang），許可證 MIT，當前公開發布版本爲 0.2.0（PyPI 上傳時間爲 2026-05-11）。社區目錄收錄日期爲 2026-08-15，分類爲界面增強；目錄頁星標爲 40，GitHub 倉庫覈實當天約爲 40 餘星。

它要解決的問題可以概括成一句：OpenAI 兼容客戶端能連上 DeepSeek 的 HTTP 接口，但不等於能安全走完多輪工具循環、流式並行調用和前綴緩存。倉庫把每條行爲對應到可復現探針，再抽成 10 條 RFC 2119 風格的規範規則，默認由 DeepSeekHarness 強制執行。

同一套契約目前有四種對外形態，外加一份零依賴腳本：

形態	分發	版本狀態
Python 庫 `deepseek-harness`	`pip install deepseek-harness`	已發佈 0.2.0
命令行 `deepseek-harness-cli`	`pip install deepseek-harness-cli`	已發佈 0.2.0，入口爲 `dsh`
MCP 服務器 `@deepseek-harness/mcp`	`npx -y @deepseek-harness/mcp`	已發佈 0.2.0
Anthropic Skill	複製 `packages/skill/` 到 `~/.claude/skills/`	源碼可用
`safe_init.py`	單文件，約 200 行，依賴 `openai` SDK	無安裝權限時使用

倉庫還附了 12 個探針、270 餘次試驗記錄，以及 2026-05-09 的審計報告。Python 包裝了 openai.OpenAI，要求 Python >= 3.9。

核心功能¶

先擋住會直接報錯的協議差異¶

README 用「無 harness / 有 harness」對照了一條最容易踩的路徑：多輪工具循環裏，應用把助手消息裏的 reasoning_content 剝掉再回傳，下一次請求會收到：

HTTP 400: The reasoning_content in the thinking mode must be passed back to the API.

probe_2 在 V4-Pro 和 V4-Flash 上均爲 3/3 復現。走 DeepSeekHarness.chat() 時，這條字段會被保留，同一循環可以繼續。

另外幾條對接入方同樣具體：

V4-Pro / Flash 默認 thinking=enabled。不顯式關掉時，簡單提示也會消耗推理 token。契約規則 C1 是默認關閉思考，需要推理時再打開。
流式響應裏大約會夾 3 個 choices 爲空的 chunk。直接 chunk.choices[0] 會崩。規則 C6 要求先判斷空再索引。
並行工具調用的 delta 按 tc.index 交錯（probe_7：Pro 30 個 chunk、Flash 38 個 chunk）。必須用字典按 index 聚合，不能 list.append。
硬上下文上限是 2^20 = 1,048,576 token，公開模型卡未寫這一條。probe_6b 復現了帶字節計數的 400。發送前要校驗 prompt_tokens + max_tokens ≤ 1,048,576。
不要把帶工具的請求打到 /beta：該端點會把 v4-pro 靜默映射成舊的 deepseek-reasoner。

V3 時期社區討論過的「工具調用泄漏到 content」（約 11%）和 strict: true 破壞 JSON，在 V4 的探針裏分別是 0/50、0/32。倉庫自己標明：這是 2026-05-09 在官方端點上的觀察，V3 相關 issue 仍可能開着，換模型版本要複測，不能當成永久消失。

10 條契約默認全部打開¶

spec/ 從上述發現抽出 10 條規範（C1–C10）。Harness 默認全部強制；構造 DeepSeekHarness 時可以用開關逐條關掉，方便對照排查。和接入最相關的幾條是：

C1 / C2：默認關思考；工具循環內必須回傳 reasoning_content。新用戶輪次到來後可以剝掉該字段，以免撐大前綴緩存鍵。
C3：每次請求都設 max_tokens，默認 4096。probe_9 在對抗提示上測到約 26 KB / 84 秒、7941 個 SSE chunk；下游 Electron 客戶端可能撞上 V8 字符串上限。
C4 / C5：並行 tool_call 按 index 聚合；流式正文用 list buffer 再 "".join()，不要反覆字符串拼接。
C7 / C8：發送前檢查 1,048,576 上限；不要往緩存前綴裏塞當前日期這類易變內容。
C9 / C10：工具調用走 https://api.deepseek.com，不用 /beta；V4 上 strict: true 可啓用，但仍建議事後用 schema 校驗 JSON。

前綴緩存按塊對齊¶

DeepSeek 的前綴緩存命中可把輸入成本降到未命中的約五十分之一。倉庫文檔給出的對照是 V4-Flash 輸入：未命中 $0.14/M，命中 $0.0028/M。probe_5 觀察到緩存按 256 token 分塊，激活閾值約 1024 token；前綴中段改一個字符時，前 512 個已緩存 token 仍可能保留。

probe_10 在五輪對話上看到命中率從 0 升到 0.56、0.72、0.78、0.95。要保住命中，就不要在 system 前綴裏注入易變字段，也不要頻繁裁剪、摘要歷史。返回的 usage 裏，DeepSeek 原生字段 prompt_cache_hit_tokens 和 OpenAI 形態的 prompt_tokens_details.cached_tokens 會同時出現，客戶端兩邊都要讀。

安裝與啓用¶

社區目錄給出的 DeepSeek Harness 插件安裝命令如下，在 DeepSeek Harness 終端裏運行：

dsh plugin add github:HenryZ838978/deepseek-harness

需要可復現安裝時，按目錄頁說明固定 commit 哈希：

dsh plugin add github:HenryZ838978/deepseek-harness#commit

把 commit 換成實際哈希。目錄頁同時寫明：插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。安裝前應檢查源碼倉庫和許可證。

倉庫 README 把日常使用按環境拆成五條路徑，行爲來自同一份 spec/：

pip install deepseek-harness                  # Python 庫
pip install deepseek-harness-cli              # 本項目的 dsh 命令行
npx -y @deepseek-harness/mcp                  # MCP 服務器（stdio）

無安裝權限時，可以只拉單文件：

curl -sL https://raw.githubusercontent.com/HenryZ838978/deepseek-harness/main/packages/skill/scripts/safe_init.py -o safe_init.py

給 Claude Code 等識別 SKILL.md 的智能體：

git clone https://github.com/HenryZ838978/deepseek-harness && \
cp -r deepseek-harness/packages/skill ~/.claude/skills/deepseek-harness

驗證方式也寫在兼容性表裏：Python 側 python -c "import deepseek_harness"；命令行側 dsh doctor；MCP 側在客戶端配置 mcpServers。

這裏有一個同名衝突：官方 DeepSeek Harness 的 CLI 叫 dsh，本項目 pip install deepseek-harness-cli 之後的入口也叫 dsh。 同一環境裏兩條 PATH 會搶命令。在已經安裝官方 dsh 的機器上，優先用目錄頁的 dsh plugin add，或只用 pip install deepseek-harness 的 Python API / npx MCP，不要輕易再裝一份同名 CLI。

典型用法¶

下面例子均來自倉庫 README 或 SKILL.md，可以按原樣復現。調用前需要有效的 DEEPSEEK_API_KEY。

1. Python 庫：默認關閉思考並打印緩存命中¶

from deepseek_harness import DeepSeekHarness, estimate_cache_hit

client = DeepSeekHarness(disable_thinking_by_default=True)
response = client.chat(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=4096,
)
print(response["message"]["content"])
print(f"cost: ${response['usage']['estimated_cost_usd']:.6f}")
print(f"cache hit ratio: {response['usage']['cache_hit_rate']:.0%}")

estimate_cache_hit 可以在不發請求的情況下估前綴命中，適合先檢查消息歷史會不會把緩存打穿。

2. 命令行：體檢、對話、離線審計¶

pip install deepseek-harness-cli
export DEEPSEEK_API_KEY=sk-...

dsh doctor                       # 檢查環境，並做一次單 token 實呼
dsh chat                         # 交互 REPL，默認打開全部守衛
dsh chat -r                      # 打開思考模式
dsh validate path/to/msgs.json   # 離線契約檢查，不消耗配額
dsh estimate path/to/msgs.json   # 離線緩存命中估計
dsh probe probe_2 --n 3          # 按名稱跑探針

README 把 dsh doctor 的預期寫成：狀態表爲綠色，實呼費用約 $0.000002。

3. MCP：接到桌面客戶端¶

Claude Desktop、Cline、Roo Code、ChatWise、Cherry Studio 這類識別 MCP 的客戶端，把下面片段寫進各自的 MCP 配置：

{
  "mcpServers": {
    "deepseek-harness": {
      "command": "npx",
      "args": ["-y", "@deepseek-harness/mcp"],
      "env": { "DEEPSEEK_API_KEY": "sk-..." }
    }
  }
}

服務器暴露四個工具：deepseek_chat、deepseek_chat_stream、validate_message_history、estimate_cache_hit。後兩個只做契約校驗，不消耗 API 配額。MCP 包要求 Node.js >= 18，傳輸爲 stdio。

4. 用探針確認協議還在¶

倉庫給了兩組對照命令。第一組用原裝 OpenAI 客戶端復現協議錯誤；第二組走 harness：

# 1. 用原裝客戶端復現 reasoning_content 400
python reports/probes/probe_2_reasoning_lifecycle.py --n 3
# 預期：phase-B 三次試驗都返回 BadRequestError，
# 原文包含 "The reasoning_content in the thinking mode must be passed back to the API."

# 2. 同一場景交給 harness
dsh doctor

如果第一組不再報錯，說明上游可能改了協議，應回頭更新 spec/，而不是繼續假定舊契約。

適用場景與注意事項¶

適合這些人和場景：

用 Python（LangChain、LlamaIndex、自研智能體）接 DeepSeek V4，需要多輪工具循環而不是單次補全
在 CI 或終端裏調試協議問題，需要 dsh doctor / dsh validate / dsh probe
把 DeepSeek 接到 Claude Desktop、Cline、Roo Code、ChatWise、Cherry Studio 等 MCP 客戶端
在 Claude Code 裏希望助手自動帶上這 10 條契約和 safe_init.py

使用時注意下面幾條，都來自目錄頁或倉庫自己的披露，不是額外發揮：

插件以當前 dsh 進程權限運行。 安裝可能執行代碼。裝之前看源碼和 MIT 許可證；要可復現就固定 commit。
探針只打過官方端點 https://api.deepseek.com。 倉庫寫明：vLLM、SGLang、OpenRouter 以及 Anthropic 形態中繼可能不同，這是已知缺口。
統計結論不要讀成「永不發生」。 例如「0/50 泄漏」的含義是：2026-05-09、單把 API Key、連續 50 次試驗未出現，不是嚴格的不存在證明。Finding 13（V8 字符串過長）只部分復現：V4 推理長度有界（對抗提示上觀察到最大約 26 KB），harness 仍用 max_tokens 做防護。
命令行入口與官方 dsh 同名。 見上一節。不要在同一 PATH 裏混裝兩套 CLI 後再靠記憶調用。
目錄分類是界面增強，能力是協議適配。 相關指南鏈到了側邊欄和主題文檔，那是目錄的分類導航，不能據此把它當成皮膚插件。
需要有效的 DeepSeek API Key。 示例裏的 sk-... 只是佔位，不要把密鑰寫進倉庫或客戶端配置的明文備份。

小結¶

deepseek-harness 把 DeepSeek V4-Pro / V4-Flash 上已記錄的 16 項協議行爲收成 spec/，再以 Python 庫、CLI、MCP、SKILL.md 四種形態發出去。對已經在用 OpenAI 兼容客戶端接 DeepSeek 的人來說，它主要擋住的是：漏回傳 reasoning_content 導致的 400、默認思考燒 token、交錯的並行 tool_call，以及 1,048,576 的硬上限。社區目錄提供 dsh plugin add github:HenryZ838978/deepseek-harness；日常接入以倉庫 README 的 pip / npx / Skill 路徑爲準。

目錄頁與源碼：

社區目錄：https://deepseek-harness-plugin.com/zh-CN/plugins/deepseek-harness-henryz838978/
GitHub：https://github.com/HenryZ838978/deepseek-harness
PyPI 庫：https://pypi.org/project/deepseek-harness/
審計報告：https://github.com/HenryZ838978/deepseek-harness/blob/main/reports/REPORT_2026-05-09.md
官方 DeepSeek Harness（同名運行時，便於對照）：https://github.com/deepseek-ai/deepseek-harness

用 deepseek-harness 給 OpenAI 客戶端補上 DeepSeek V4 協議適配

前言¶

這是什麼¶

核心功能¶

先擋住會直接報錯的協議差異¶

10 條契約默認全部打開¶

前綴緩存按塊對齊¶

安裝與啓用¶

典型用法¶

1. Python 庫：默認關閉思考並打印緩存命中¶

2. 命令行：體檢、對話、離線審計¶

3. MCP：接到桌面客戶端¶

4. 用探針確認協議還在¶

適用場景與注意事項¶

小結¶

精选优惠券

用 deepseek-harness 給 OpenAI 客戶端補上 DeepSeek V4 協議適配

前言¶

這是什麼¶

核心功能¶

先擋住會直接報錯的協議差異¶

10 條契約默認全部打開¶

前綴緩存按塊對齊¶

安裝與啓用¶

典型用法¶

1. Python 庫：默認關閉思考並打印緩存命中¶

2. 命令行：體檢、對話、離線審計¶

3. MCP：接到桌面客戶端¶

4. 用探針確認協議還在¶

適用場景與注意事項¶

小結¶

精选优惠券

相關文章