deepseek-harness

Protocol-aware adapters for DeepSeek V4-Pro, V4-Flash, and V4-Flash-Vision-Exp

A single protocol contract distributed in four wrapper formats. Designed to meet the integration requirements of any OpenAI-compatible client. Multimodal (vision) contract per spec/07 since 2026-08-22.

English · 中文

Project identity. Independently authored and maintained by Henry Zhang (@HenryZ838978). Repository first commit 2026-05-09; PyPI packages deepseek-harness and deepseek-harness-cli first published 2026-05-11 — three months before deepseek-ai/deepseek-harness (Node, 0.1.0-rc.6, 2026-08-13). Not a fork or distribution of the official Node agent framework.

• What broke in each official rc release, one line per row: HISTORY.md
• Full dated timeline: Provenance

Installed the Node harness? Run this first.

flowchart LR
    classDef fail  fill:#fee2e2,stroke:#ef4444,color:#7f1d1d,font-weight:bold
    classDef sym   fill:#fef3c7,stroke:#f59e0b,color:#78350f
    classDef fix   fill:#dcfce7,stroke:#22c55e,color:#14532d,font-weight:bold

    F1["Short prompt on<br/>deepseek-reasoner"]:::fail
    F2["Plugin package.json<br/>saved with UTF-8 BOM"]:::fail
    F3["dsh web hit via<br/>non-loopback hostname"]:::fail
    F4["tmp dir<br/>unwritable"]:::fail
    F5["Two dsh processes<br/>on one workspace"]:::fail
    F6["MY_SERVICE_KEY<br/>set in env"]:::fail
    F7["Codex provider row<br/>without @openai/codex"]:::fail
    F8["Vision model, no<br/>attachment-local plugin"]:::fail
    F9["Two dsh installs<br/>sharing one API key"]:::fail
    F10["Crash left a torn<br/>tail in a session log"]:::fail
    F11["A <code>./plugin.js</code> line<br/>in the profile patch"]:::fail

    S1["Thinking-mode history<br/><i>looks incomplete</i>"]:::sym
    S2["<code>dsh plugin add</code><br/>crashes on JSON.parse"]:::sym
    S3["Page hangs on<br/>'Select a workspace'<br/><i>no console error</i>"]:::sym
    S4["Whole harness<br/><code>exit 1</code> mid-turn"]:::sym
    S5["Session won't load,<br/>or loads with<br/><i>silently fewer events</i>"]:::sym
    S6["Subagent CLI<br/><i>silently sees a hole</i><br/>where your var was"]:::sym
    S7["Profile load<br/><code>ERR_MODULE_NOT_FOUND</code><br/>takes down dsh boot"]:::sym
    S8["Image message sent,<br/>no reply, session shows<br/>orphan turn"]:::sym
    S9["<code>unknown file_id</code>,<br/>image re-upload,<br/>prefix cache misses"]:::sym
    S10["Repair warns, truncates,<br/><i>a second process's event<br/>vanishes with it</i>"]:::sym
    S11["Every request fails<br/><code>extension preparation failed</code>,<br/><i>no HTTP ever sent</i>"]:::sym

    D1["<b>P1-reasoner-skip</b><br/>bare 60% · +hint 0% · Δ+60%"]:::fix
    D2["<b>P2-bom</b><br/>1/N manifests → BOM"]:::fix
    D3["<b>P3-serve</b><br/>mux 403 under evil Origin"]:::fix
    D4["<b>P4-spill</b><br/>EACCES on /tmp probe"]:::fix
    D5["<b>P5-seqgap</b><br/>seq gap at line N, awaiting turn/end"]:::fix
    D6["<b>P6-subagent-env-scrub</b><br/>N user vars will be stripped"]:::fix
    D7["<b>P7-subagent-codex-preflight</b><br/>@openai/codex missing"]:::fix
    D8["<b>P8-multimodal-preflight</b><br/>vision model + no attachment"]:::fix
    D9["<b>P9-files-quota-scope</b><br/>N records across M scopes"]:::fix
    D10["<b>P10-jsonl-repair-race</b><br/>N logs carry a torn tail"]:::fix
    D11["<b>P11-plugin-inventory-manifest</b><br/>N entries resolve to dsh's own manifest"]:::fix

    F1 --> S1 --> D1
    F2 --> S2 --> D2
    F3 --> S3 --> D3
    F4 --> S4 --> D4
    F5 --> S5 --> D5
    F6 --> S6 --> D6
    F7 --> S7 --> D7
    F8 --> S8 --> D8
    F9 --> S9 --> D9
    F10 --> S10 --> D10
    F11 --> S11 --> D11

    subgraph L1["failure mode"]
      F1
      F2
      F3
      F4
      F5
      F6
      F7
      F8
      F9
      F10
      F11
    end
    subgraph L2["what you see"]
      S1
      S2
      S3
      S4
      S5
      S6
      S7
      S8
      S9
      S10
      S11
    end
    subgraph L3["dsh doctor --node · one line"]
      D1
      D2
      D3
      D4
      D5
      D6
      D7
      D8
      D9
      D10
      D11
    end

pip install deepseek-harness-cli
export DEEPSEEK_API_KEY=sk-...
dsh doctor --node

Eleven probes for @deepseek-ai/dsh (the official Node runtime) — each reports something its own tooling does not:

Each finding is a WARN or FAIL with a concrete fix. The doctor is not a competitor to the official runtime — it's a witness. Wraps around the same dsh name because the Node stack advertises "everything is a plugin"; this is one.

Not the same tool as @simon-world/dsh-toolkit doctor (Node-side, checks Node version / koffi pin / ports / ASCII paths / sandbox). The two are complementary: theirs answers "will it install and start", ours answers "what will silently bite you after it does".

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

Dated timeline of who published what and when: see Provenance at the bottom.

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

# 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

Status

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

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 mutation.

The goal of this repository is to characterize each behaviour with a reproducible probe, codify the resulting contract in spec/, and ship reference implementations of that contract in the four most common distribution formats.

Cache discount in practice

Cache hit progression observed across a five-turn conversation (probe_10 / S1 on V4-Pro). Each turn appends to the same prefix; cache miss decreases monotonically until the prefix exceeds the 1,024-token activation threshold and the 256-token block boundaries align.

xychart-beta
    title "Cache hit ratio over five conversation turns (probe_10/S1, V4-Pro)"
    x-axis "Turn" [0, 1, 2, 3, 4]
    y-axis "Cache hit ratio" 0 --> 1
    bar [0, 0.56, 0.72, 0.78, 0.95]

At the equilibrium hit ratio of 95%, input cost is reduced by a factor of approximately 50 relative to a cache-miss workload ($0.0028/M vs $0.14/M for V4-Flash input pricing).

Findings summary

A summary of all 16 documented findings, each linked to the probe that produced it.

The full numerical detail is in reports/REPORT_2026-05-09.md. The paper-style write-up with reproducibility instructions is in docs/technical_report.md.

Contract specification

Ten normative rules derived from the findings above. Each rule maps to a section of spec/.

| ID | Rule | Spec section | |-----|--