<!-- 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, 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 · 中文

</div>

---

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:

| probe | what it tells you the Node stack won't | |---|---| | P1-reasoner-skip | Runs an A/B (bare prompt vs. +CoT-hint) and reports whether deepseek-reasoner skips its reasoning stream on your prompt shape. Historical baseline was bare 60% / hinted 0%; on V4.1 Flash the skip is no longer reachable (see HISTORY 2026-09-10), so this now doubles as a regression detector. | | P2-bom | You have a plugin package.json with a UTF-8 BOM — dsh plugin add will crash on it (#2798). Offline scan. | | P3-serve | Your dsh web fence silently rejects the data layer under a non-loopback Origin (#2573). | | P4-spill | Your tmp directory is unwritable — the subprocess spill path will exit 1 (spillAll() has no try/catch around openSync/writeSync). | | P5-seqgap | Your session log — or an Agent Teams log — already has a concurrent-writer seq gap (#2571). Two failure modes: silent truncation, or permanent corrupt on the next turn/end. | | P6-subagent-env-scrub | Any env var whose name contains KEY/TOKEN/SECRET/PASSWORD is silently stripped from Claude Code / Codex subagent children by SENSITIVE_ENV_PATTERN — including AWS_ACCESS_KEY_ID and friends you didn't mean as credentials. | | P7-subagent-codex-preflight | Your profile references the Codex subagent provider but @openai/codex is not installed — plugin load crashes at boot with ERR_MODULE_NOT_FOUND. | | P8-multimodal-preflight | Your composition names a vision model but no attachment provider is mounted — the user's image-bearing turn commits half a session log entry (image without reply). | | P9-files-quota-scope | Your local Files API upload index has records that another dsh install using the same API key can silently delete via reclaimOldestOwned — next image request breaks the prefix cache. | | P10-jsonl-repair-race | Your session logs carry a torn tail that a pre-0.1.5 jsonl backend would truncate on next write-open with no staleness re-check, while a second process appending in that window loses its committed event silently. Fixed upstream in 0.1.5-alpha.1 by the cross-process flock(2) write lease (session-persistence-jsonl/src/lease.ts); the probe reports torn tails as a "your harness is old" signal rather than an open defect. | | P11-plugin-inventory-manifest | Your profile's package.json — the one dsh generated — has a name and no version, and the default-on dsh_plugin_packages request field throws on exactly that shape when a local plugin (name: ./plugin.js) resolves to it. Every request in that profile then fails REQUEST_EXTENSION before HTTP, after the user turn was already written. |

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
    cla