Preface¶

DeepSeek V4-Pro and V4-Flash provide OpenAI-compatible HTTP APIs. As a result, many agents, LangChain projects, and desktop clients only need to modify the base_url to use the standard openai SDK for calls. The repository’s README notes that there are still 16 non-standard behaviors in the online protocol that standard clients do not handle by default. The most common ones include: directly returning an HTTP 400 if reasoning_content is omitted in a multi-turn tool loop; the thinking mode being enabled by default, which consumes 30–300 reasoning tokens even for simple prompts; and streaming incremental parallel tool_call chunks interleaved by tc.index, which cannot be appended to a list directly.

The community plugin directory included deepseek-harness, maintained by HenryZ838978, under the “Interface Enhancement” category. Contrary to its category label, it does not provide skin changes or sidebar modifications. Instead, it is a protocol-aware adaptation layer: it formalizes these 16 behaviors into a specification, then distributes the same spec/ assets as a Python library, command-line tool, MCP server, and SKILL.md. It is important to clarify the naming distinction: DeepSeek’s official DeepSeek Harness (dsh) is an “everything-as-plugin” agent runtime; the community-maintained adaptation layer introduced in this article shares the same name but is not the official runtime itself. The community directory is an independent site with no official affiliation to DeepSeek / Fangxin.

This article is collated by cross-referencing the directory details page, GitHub README, packages/skill/SKILL.md, and PyPI page: what problem it solves, how to install its four distribution forms, and the reproducible usage officially provided.

What Is It¶

deepseek-harness is a protocol-aware adaptation layer for DeepSeek V4-Pro / V4-Flash, maintained by GitHub user HenryZ838978 (Henry Zhang), licensed under MIT. The current publicly released version is 0.2.0 (uploaded to PyPI on 2026-05-11). The community directory included it on 2026-08-15, categorized under Interface Enhancement; the directory page had 40 stars, with approximately 40 stars on the day the GitHub repository was verified.

The problem it solves can be summarized in one sentence: While an OpenAI-compatible client can connect to DeepSeek’s HTTP interface, it does not guarantee safe completion of multi-turn tool loops, streaming parallel calls, and prefix caching. The repository maps each non-standard behavior to a reproducible probe, then distills them into 10 RFC 2119-style normative rules, which are enforced by default by DeepSeekHarness.

There are currently four distribution forms of this specification, plus a zero-dependency script:

The repository also includes 12 probes, over 270 test records, and an audit report dated 2026-05-09. The Python wrapper wraps openai.OpenAI, and requires Python >= 3.9.

Core Features¶

Block Protocol Differences That Cause Direct Errors¶

The README uses a “without harness / with harness” comparison to demonstrate one of the most commonly encountered pitfalls: in a multi-turn tool loop, an application strips the reasoning_content from the assistant message before passing it back, resulting in the next request receiving:

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

probe_2 reproduces this error 3/3 times on both V4-Pro and V4-Flash. When using DeepSeekHarness.chat(), this field is preserved, allowing the loop to continue normally.

Other concrete issues for integrators include:
- V4-Pro / Flash have thinking=enabled by default. If not explicitly disabled, even simple prompts will consume reasoning tokens. Normative rule C1 is to disable thinking by default, and enable it only when reasoning is needed.
- Streaming responses will contain approximately 3 chunks with empty choices. Directly accessing chunk.choices[0] will crash. Rule C6 requires checking for empty values before indexing.
- Parallel tool call deltas are interleaved by tc.index (probe_7: 30 chunks on Pro, 38 chunks on Flash). You must use a dictionary to aggregate by index instead of list.append.
- The hard context limit is 2^20 = 1,048,576 tokens, which is not documented in the public model card. probe_6b reproduces a 400 error with byte counting. You must validate that prompt_tokens + max_tokens ≤ 1,048,576 before sending requests.
- Do not send tool-enabled requests to /beta: this endpoint silently maps v4-pro to the older deepseek-reasoner model.

Community-discussed issues from the V3 era, such as “tool calls leaking into content” (approximately 11% of cases) and strict: true breaking JSON, had 0/50 and 0/32 reproduction rates in V4 probes respectively. The repository notes that these observations were made on official endpoints on 2026-05-09, and V3-related issues may still exist; you should retest when switching model versions and do not assume these issues are permanently resolved.

10 Normative Rules Enabled by Default¶

The spec/ directory distills the above findings into 10 normative rules (C1–C10). The harness enforces all of them by default; you can disable individual rules with switches when constructing DeepSeekHarness for comparative debugging. The most relevant rules for integrators include:
1. C1 / C2: Disable thinking by default; reasoning_content must be returned in tool loops. You can strip this field after a new user turn to avoid inflating the prefix cache key.
2. C3: Set max_tokens for every request, defaulting to 4096. probe_9 measured approximately 26 KB / 84 seconds and 7941 SSE chunks on adversarial prompts; downstream Electron clients may hit V8 string limits.
3. C4 / C5: Aggregate parallel tool calls by index; use a list buffer and "".join() for streaming text instead of repeated string concatenation.
4. C7 / C8: Check the 1,048,576 limit before sending requests; do not add volatile content like the current date to cache prefixes.
5. C9 / C10: Send tool calls to https://api.deepseek.com instead of /beta; strict: true is available on V4, but it is still recommended to validate JSON with a schema afterward.

Prefix Cache Alignment by Chunk¶

DeepSeek’s prefix cache hit rate can reduce input costs to approximately 1/50 of a miss. The repository documentation provides a comparison for V4-Flash inputs: a miss costs $0.14/M, while a hit costs $0.0028/M. probe_5 observed that the cache is split into 256-token chunks, with an activation threshold of approximately 1024 tokens; if one character in the middle of a prefix is changed, the first 512 cached tokens may still be retained.

probe_10 saw hit rates rise from 0 to 0.56, 0.72, 0.78, and 0.95 across five rounds of conversation. To preserve cache hits, do not inject volatile fields into the system prefix, and do not frequently truncate or summarize history. In the returned usage data, both DeepSeek’s native field prompt_cache_hit_tokens and OpenAI-style prompt_tokens_details.cached_tokens will appear, and clients should read both.

Installation and Activation¶

The installation command for the DeepSeek Harness plugin from the community directory is as follows, run in the DeepSeek Harness terminal:

dsh plugin add github:HenryZ838978/deepseek-harness

For reproducible installations, pin the commit hash per the directory page instructions:

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

Replace commit with the actual hash value. The directory page also notes that the plugin runs with the permissions of the current dsh process, and may execute code during installation. You should inspect the source repository and license before installing.

The repository README breaks down daily usage into five paths per environment, all using the same spec/ specification:

pip install deepseek-harness                  # Python library
pip install deepseek-harness-cli              # This project's dsh command line
npx -y @deepseek-harness/mcp                  # MCP server (stdio)

If you do not have installation permissions, you can pull only the single-file script:

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

For agents that recognize SKILL.md, such as Claude Code:

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

Verification methods are also listed in the compatibility table: for Python, run python -c "import deepseek_harness"; for the command line, run dsh doctor; for MCP, configure mcpServers in your client.

There is a naming conflict: the official DeepSeek Harness CLI is called dsh, and the entry point after pip install deepseek-harness-cli for this project is also dsh. The two PATH entries will conflict in the same environment. On machines where the official dsh is already installed, use the directory page’s dsh plugin add command first, or only use the Python API via pip install deepseek-harness or the npx MCP server, and avoid installing another conflicting CLI.

Typical Usage¶

All examples below are from the repository README or SKILL.md, and can be reproduced as-is. You need a valid DEEPSEEK_API_KEY before making calls.

1. Python Library: Disable Thinking by Default and Print Cache Hit Rate¶

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 can estimate prefix cache hits without sending a request, making it suitable for checking if message history will break cache hits.

2. Command Line: Health Check, Chat, Offline Audit¶

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

dsh doctor                       # Check environment and make a single token test call
dsh chat                         # Interactive REPL, enables all guards by default
dsh chat -r                      # Enable thinking mode
dsh validate path/to/msgs.json   # Offline specification check, no quota consumed
dsh estimate path/to/msgs.json   # Offline cache hit estimation
dsh probe probe_2 --n 3          # Run probe by name

The README states that the expected output of dsh doctor is a green status table, with a test call cost of approximately $0.000002.

3. MCP: Connect to Desktop Clients¶

For clients that support MCP, such as Claude Desktop, Cline, Roo Code, ChatWise, and Cherry Studio, add the following snippet to their MCP configuration:

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

The server exposes four tools: deepseek_chat, deepseek_chat_stream, validate_message_history, and estimate_cache_hit. The last two only perform specification checks and do not consume API quota. The MCP package requires Node.js >= 18, using stdio for transport.

4. Use Probes to Confirm Protocol Status¶

The repository provides two sets of comparison commands. The first set uses the stock OpenAI client to reproduce protocol errors; the second set uses the harness:

# 1. Use the stock OpenAI client to reproduce the reasoning_content 400 error
python reports/probes/probe_2_reasoning_lifecycle.py --n 3
# Expected: All three trials in phase-B return BadRequestError,
# with the message containing "The reasoning_content in the thinking mode must be passed back to the API."

# 2. Hand the same scenario to the harness
dsh doctor

If the first command no longer returns errors, it means the upstream protocol may have changed, and you should update the spec/ directory instead of assuming the old contract remains valid.

Applicable Scenarios and Notes¶

This tool is suitable for the following people and scenarios:
- Developers using Python (LangChain, LlamaIndex, custom agents) to integrate DeepSeek V4, requiring multi-turn tool loops rather than single-turn completions
- Debugging protocol issues in CI or terminals, needing dsh doctor / dsh validate / dsh probe
- Connecting DeepSeek to MCP-compatible clients such as Claude Desktop, Cline, Roo Code, ChatWise, and Cherry Studio
- Wanting Claude Code to automatically apply the 10 normative rules and safe_init.py

Please note the following points, all from the directory page or the repository’s own disclosures, not additional assumptions:
1. The plugin runs with the permissions of the current dsh process. It may execute code during installation. Inspect the source code and MIT license before installing; pin the commit hash for reproducible deployments.
2. Probes only tested the official endpoint https://api.deepseek.com. The repository notes that vLLM, SGLang, OpenRouter, and Anthropic-style relays may behave differently, which is a known limitation.
3. Do not interpret statistical results as “never occurs”. For example, “0/50 leaks” means no leaks were observed in 50 consecutive tests on 2026-05-09 with a single API key, not a rigorous proof of non-existence. Finding 13 (overlong V8 strings) was only partially reproducible: V4 inference length is bounded (observed maximum of ~26 KB on adversarial prompts), and the harness still uses max_tokens as a safeguard.
4. The command line entry point shares the same name as the official dsh. See the previous section. Do not install both CLIs in the same PATH and rely on memory to call the correct one.
5. The directory categorizes it as Interface Enhancement, but its core capability is protocol adaptation. The relevant links point to sidebar and theme documentation, which are just directory navigation, and you should not treat it as a skin plugin.
6. You need a valid DeepSeek API Key. The sk-... in the examples is just a placeholder; do not commit secrets to repositories or store them in plaintext client configuration backups.

Summary¶

deepseek-harness aggregates the 16 documented protocol behaviors of DeepSeek V4-Pro / V4-Flash into spec/, then distributes it in four forms: Python library, CLI, MCP server, and SKILL.md. For users already using OpenAI-compatible clients to connect to DeepSeek, it primarily blocks: 400 errors caused by missing reasoning_content回传, default thinking mode token consumption, interleaved parallel tool calls, and the 1,048,576 hard context limit. The community directory provides the installation command dsh plugin add github:HenryZ838978/deepseek-harness; daily integration should follow the pip / npx / Skill paths from the repository README.

Directory and source links:
- Community Directory: https://deepseek-harness-plugin.com/zh-CN/plugins/deepseek-harness-henryz838978/
- GitHub: https://github.com/HenryZ838978/deepseek-harness
- PyPI Library: https://pypi.org/project/deepseek-harness/
- Audit Report: https://github.com/HenryZ838978/deepseek-harness/blob/main/reports/REPORT_2026-05-09.md
- Official DeepSeek Harness (same-named runtime for comparison): https://github.com/deepseek-ai/deepseek-harness