前言¶

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. 用探针确认协议还在¶

适用场景与注意事项¶

小结¶

精选优惠券

相关文章