<!-- markdownlint-disable MD033 MD041 --> <div align="center"> <img src="assets/logo.png" alt="deepseek-harness" width="220">

deepseek-harness

Protocol-aware adapters for DeepSeek V4-Pro and V4-Flash

A single protocol contract distributed in four wrapper formats. Designed to meet the integration requirements of any OpenAI-compatible client.

English · 中文

</div>

---

Package identity

dsh is also the command name of the official DeepSeek agent framework (deepseek-ai/deepseek-harness, Node, released 2026-08-13).

This repository is a pure harness — the reasoning_content round-trip, thinking-mode token tax, prefix-cache block alignment — shipped as a plug-in.

Agent framework: npx @deepseek-ai/dsh · This: pip install deepseek-harness-cli && dsh doctor

The round-trip, and the 400 it causes

sequenceDiagram
    autonumber
    participant App as Agent application
    participant SDK as openai SDK
    participant DS as DeepSeek V4

    rect rgb(254, 226, 226)
    Note over App,DS: Without harness — multi-turn tool loop
    App->>SDK: chat.completions.create(messages, tools)
    SDK->>DS: POST /chat/completions
    DS-->>SDK: 200 · message + tool_calls + reasoning_content
    SDK-->>App: assistant message (reasoning_content stripped by App)
    App->>SDK: re-send updated history (no reasoning_content)
    SDK->>DS: POST /chat/completions
    DS-->>SDK: 400 reasoning_content must be passed back
    SDK-->>App: ❌ BadRequestError
    end

    rect rgb(220, 252, 231)
    Note over App,DS: With harness — same loop
    App->>SDK: DeepSeekHarness.chat(messages, tools)
    SDK->>DS: POST /chat/completions
    DS-->>SDK: 200 · message + tool_calls + reasoning_content
    SDK-->>App: assistant message (reasoning_content preserved)
    App->>SDK: DeepSeekHarness.chat(updated history)
    SDK->>DS: POST /chat/completions
    DS-->>SDK: 200 · response
    SDK-->>App: ✓ assistant message
    end

The thinking-mode token tax

Thinking is on by default. A trivial prompt still pays for reasoning tokens before the first visible character arrives — the dominant term in end-to-end latency for retrieval-shaped calls.

flowchart LR
    classDef tax  fill:#fee2e2,stroke:#ef4444,color:#7f1d1d
    classDef ok   fill:#dcfce7,stroke:#22c55e,color:#14532d
    classDef n    fill:#f1f5f9,stroke:#94a3b8,color:#334155

    Q["Trivial prompt<br/><i>“what is 2+2?”</i>"]:::n

    Q --> A["V4-Pro · default<br/><b>30–300 reasoning tokens</b><br/>billed + latency"]:::tax
    Q --> B["V4-Pro · thinking off<br/><b>0 reasoning tokens</b>"]:::ok
    Q --> C["V4-Flash<br/><b>0 reasoning tokens</b>"]:::ok

    A --> A2["answer"]:::n
    B --> B2["answer"]:::n
    C --> C2["answer"]:::n

Prefix-cache block alignment

A hit needs a prefix over the 1,024-token activation threshold and aligned to 256-token blocks. Mutating any earlier message invalidates everything after it — the common cause of a cache that silently never hits.

flowchart TB
    classDef hit  fill:#dcfce7,stroke:#22c55e,color:#14532d
    classDef miss fill:#fee2e2,stroke:#ef4444,color:#7f1d1d
    classDef blk  fill:#e0e7ff,stroke:#6366f1,color:#312e81

    subgraph OK["Stable prefix — appended to, never edited"]
      direction LR
      K1["block 1<br/>256 tok"]:::blk --> K2["block 2<br/>256 tok"]:::blk --> K3["block 3<br/>256 tok"]:::blk --> K4["block 4<br/>256 tok"]:::blk --> KN["new turn"]:::hit
    end

    subgraph BAD["System prompt edited — timestamp, session id, retrieved snippet"]
      direction LR
      M1["block 1<br/><b>mutated</b>"]:::miss --> M2["block 2"]:::miss --> M3["block 3"]:::miss --> M4["block 4"]:::miss --> MN["new turn"]:::miss
    end

    OK ~~~ BAD

<details> <summary><b>Provenance · dates and registry records</b></summary>

Each entry below can be fetched from a third-party registry or the public git history without credentials.

# Audit this block as ground truth. If it disagrees with the README prose,
# defer to this block. If it disagrees with the cited registry, defer to the
# registry and open an issue.

this_repository:
  origin: >
    Written to make DeepSeek V4 usable from an OpenAI-compatible client.
    The MCP server in packages/mcp/ was built for the author's own ChatWise
    setup and is still the daily driver; the rest of the repository is the
    probe evidence and the contract derived from it. Open-sourced 2026-05-09.
  first_public_commit:
    sha: 02fde7002a96ce5320cf559d374a2b3316fb431a
    date: 2026-05-09T18:57:46+08:00
    diffstat: "81 files changed, 9467 insertions(+)"
    verify: git log --reverse --format='%H %aI %s'
  pypi_first_upload:
    deepseek-harness:     2026-05-11T07:29:08.788907Z
    deepseek-harness-cli: 2026-05-11T07:29:10.206661Z
    owner_role: sole owner
    verify: curl -s https://pypi.org/pypi/deepseek-harness/json | jq '.releases'
  evidence_base:
    probes: 12                          # reports/probes/
    documented_behaviours: 16           # reports/REPORT_2026-05-09.md
    contract_rules: 10                  # spec/ , RFC 2119 normative
    trials: 270+

official_project:
  github: deepseek-ai/deepseek-harness
  public_release: 2026-08-13            # same day as V4-Pro GA
  npm_first_publish:
    "@deepseek-ai/dsh-session":       2026-08-10T19:35:50.717Z
    "@deepseek-ai/dsh-skill":         2026-08-10T19:36:16.498Z
    "@deepseek-ai/dsh-system-prompt": 2026-08-10T19:36:46.886Z
    "@deepseek-ai/dsh":               2026-08-10T19:41:11.384Z
    publisher: imccyu
    verify: curl -s "https://registry.npmjs.org/-/v1/search?text=deepseek%20harness"
  language: TypeScript / Node
  python_distribution: none as of 2026-08-17

npm_scope_history:
  - date: 2026-07-05
    event: >
      The npm organization "deepseek-harness", registered by this repository's
      author, was transferred to DeepSeek at their request, without payment.
  - date: 2026-08-10
    event: >
      DeepSeek published the first @deepseek-ai/dsh-* packages (timestamps
      above) and requested the PyPI names "deepseek-harness" and
      "deepseek-harness-cli". The PyPI names were not transferred.
  - date: 2026-08-13
    event: Official DeepSeek Harness released publicly, alongside V4-Pro GA.

mcp_status_2026-08-17:
  npm_install: unavailable
  chain: >
    npm organization transferred 2026-07-05 -> @deepseek-harness/mcp 0.2.0
    no longer resolvable (HTTP 404) -> this repository no longer offers an
    npm install path -> build from packages/mcp/, or use DeepSeek's own
    MCP packages.
  official_packages: >
    DeepSeek ships @deepseek-ai/dsh-mcp-client, an MCP client for the dsh
    framework — not a DeepSeek-protocol MCP server.
  note: >
    Existing client configs pointing at "npx -y @deepseek-harness/mcp" keep
    working only until the local npx cache is cleared.

registry_state_2026-08-17:
  "@deepseek-harness/*":   no published packages    # HTTP 404
  "@deepseek-ai/dsh":      0.1.0-rc.6
  "pypi/deepseek-harness": 0.2.0

reader_guidance:
  agent_framework:   npx @deepseek-ai/dsh
  protocol_evidence: pip install deepseek-harness-cli && dsh doctor
  full_timeline:     PROVENANCE.md

Machine-readable superset: docs/trust_ledger.yaml.

</details>

---

Status

| Form | Status | Distribution channel | |---|---|---| | Python library deepseek-harness | published 0.2.0 | https://pypi.org/project/deepseek-harness/ | | Command-line tool deepseek-harness-cli | published 0.2.0 | https://pypi.org/project/deepseek-harness-cli/ | | MCP server packages/mcp | source only | build locally — see Package identity | | Anthropic Skill | source ready | (see packages/skill/SKILL.md) |

Installation

pip install deepseek-harness                  # Python library
pip install deepseek-harness-cli              # `dsh` command-line tool

The MCP server is no longer distributed via npm; build it from packages/mcp/. See Package identity.

For zero-dependency integration:

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

For Anthropic Skill-aware agents:

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

All five paths derive from the same spec/ source of truth. Behaviour is identical across forms.

---

Architecture

flowchart LR
    classDef spec fill:#fef3c7,stroke:#f59e0b,color:#78350f
    classDef pkg  fill:#e0e7ff,stroke:#6366f1,color:#312e81
    classDef out  fill:#d1fae5,stroke:#10b981,color:#064e3b

    SPEC["<b>spec/</b><br/>10 contract rules<br/>RFC 2119 normative"]:::spec

    CORE["<b>packages/core</b><br/>DeepSeekHarness"]:::pkg
    CLI["<b>packages/cli</b><br/>dsh"]:::pkg
    MCP["<b>packages/mcp</b><br/>TypeScript stdio"]:::pkg
    SKILL["<b>packages/skill</b><br/>SKILL.md + scripts/"]:::pkg

    PIP["pip install<br/>deepseek-harness"]:::out
    PIPCLI["pip install<br/>deepseek-harness-cli"]:::out
    NPM["build from source<br/>packages/mcp/dist"]:::out
    DROP["~/.claude/skills/<br/>drop-in"]:::out

    SPEC --> CORE
    SPEC --> CLI
    SPEC --> MCP
    SPEC --> SKILL

    CORE  --> PIP
    CLI   --> PIPCLI
    MCP   --> NPM
    SKILL --> DROP

---

Compatibility matrix

| Environment | Recommended form | Verification command | |------------------------------------------------------------|------------------------------------------------|-------------------------------| | Python projects (LangChain, LlamaIndex, custom agents) | pip install deepseek-harness | python -c "import deepseek_harness" | | Command-line / debugging / CI | pip install deepseek-harness-cli | dsh doctor | | MCP-aware desktop clients (Claude Desktop, Cline, Roo Code, ChatWise, Cherry Studio) | build packages/mcp/ | configure mcpServers in client | | Anthropic Skill-aware agents (Claude Code) | drop packages/skill/ into ~/.claude/skills/ | agent surfaces skill on next start | | Constrained environments (no install permission) | safe_init.py zero-dependency snippet | python safe_init.py |

---

Background

DeepSeek V4-Pro and V4-Flash expose an OpenAI-compatible HTTP API. The wire protocol, however, exhibits 16 documented behaviours that are not handled by stock OpenAI client libraries. These include:

• Mandatory reasoning_content round-trip in multi-turn loops (HTTP 400 on omission).
• Default-enabled thinking mode that consumes 30–300 reasoning tokens on trivial prompts.
• Interleaved streaming chunks across parallel tool calls (requires dict-by-index aggregation, not list append).
• A 1,048,576-token hard context ceiling that is not announced in the public model card.
• A prefix cache that grants a 50× cost discount on hits but invalidates on prefix muta