{
    "format": "skillpro/v1",
    "skill_id": "henryz838978-deepseek-harness-packages-skill-skill-md",
    "name": "deepseek-harness",
    "version": "1.0.0",
    "description": "Use this skill whenever the user wants to call DeepSeek V4-Pro / V4-Flash (or its legacy aliases deepseek-chat / deepseek-reasoner), or you see code that imports `from openai import OpenAI` with `base_url=\"https://api.deepseek.com\"`. This skill teaches you the 10 protocol contract rules required to avoid the 16 documented bugs (reasoning_content lifecycle 400, tool-call leakage, max_tokens runaway → V8 string limit, parallel tool delta interleave, prefix-cache invalidation, /beta endpoint remap, etc.) and ships a single drop-in `safe_init.py` script you can copy into the user's project.",
    "category": [
        "内容创作"
    ],
    "trigger_words": [],
    "tags": [
        "api",
        "ai"
    ],
    "source": "DeepseekModel",
    "source_url": "https://deepseekmodel.com/skill?id=henryz838978-deepseek-harness-packages-skill-skill-md",
    "exported_at": "2026-09-17T07:52:12+08:00",
    "system_prompt": "name deepseek-harness description Use this skill whenever the user wants to call DeepSeek V4-Pro / V4-Flash (or its legacy aliases deepseek-chat / deepseek-reasoner), or you see code that imports `from openai import OpenAI` with `base_url=\"https://api.deepseek.com\"`. This skill teaches you the 10 protocol contract rules required to avoid the 16 documented bugs (reasoning_content lifecycle 400, tool-call leakage, max_tokens runaway → V8 string limit, parallel tool delta interleave, prefix-cache invalidation, /beta endpoint remap, etc.) and ships a single drop-in `safe_init.py` script you can copy into the user's project. when_to_use Any of these triggers should invoke this skill: • user mentions DeepSeek, deepseek-v4-pro, deepseek-v4-flash, deepseek-chat, deepseek-reasoner, or 深度求索 • code references `https://api.deepseek.com` or `https://api.deepseek.com/anthropic` or `/beta` • user complains about `400 reasoning_content`, `Invalid string length`, `RangeError`, hangs in chat clients, or \"weird tool call behaviour\" • user wants the cheapest possible LLM hosting that is also smart (V4-Flash $0.14/M input miss, $0.0028/M cached → 50× discount) license MIT version 0.2.0 author Henry Zhang (HenryZ838978) homepage https://github.com/HenryZ838978/deepseek-harness DeepSeek V4 Harness When you call DeepSeek V4-Pro or V4-Flash via the OpenAI-compatible API, you MUST follow the 10 contract rules below. Violating any one of them causes a documented production bug (the upstream issue and our reproduction probe are cited per rule). The 10 contract rules (ranked by blast radius) C1 · Disable thinking unless the task is genuinely reasoning-heavy deepseek-v4-pro defaults to thinking=enabled . Every call then burns 30-300 reasoning_tokens even on trivial prompts. client.chat.completions.create( model= \"deepseek-v4-pro\" , messages=messages, extra_body={ \"thinking\" : { \"type\" : \"disabled\" }}, # ← saves money on every non-reasoning call ) For TypeScript / openai-node, put thinking at the top level of the request, not inside extra_body (the JS SDK passes unknown top-level keys through): await openai. chat . completions . create ({ model : \"deepseek-v4-pro\" , messages, thinking : { type : \"disabled\" }, } as any ); C2 · In multi-turn loops, preserve reasoning_content on assistant messages If thinking IS enabled and you re-send a prior assistant message that has tool_calls , you must include the original reasoning_content field. Otherwise the next request returns: HTTP 400: The reasoning_content in the thinking mode must be passed back to the API. (Reproduced in reports/probes/probe_2_reasoning_lifecycle.py 3/3 trials on V4-Pro and V4-Flash, 2026-05-09.) msg = response.choices[ 0 ].message history.append({ \"role\" : \"assistant\" , \"content\" : msg.content, \"tool_calls\" : _serialize_tool_calls(msg.tool_calls), \"reasoning_content\" : getattr (msg, \"reasoning_content\" , None ), # ← REQUIRED }) When a NEW user turn arrives, you MAY strip reasoning_content from prior assistant messages — DeepSeek doesn't require it across user-turn boundaries, and keeping it bloats the prefix-cache key. C3 · Always set max_tokens (default 4096) Without an output cap, reasoning_content can stream 8000+ chunks ( probes/probe_9_reasoning_runaway.py measured 26 KB / 84 s on a self-doubt prompt) and downstream Electron clients (ChatWise, Cherry Studio) crash with RangeError: Invalid string length once their string buffer hits V8's 512 MB ceiling. C4 · Streaming: aggregate parallel tool_calls by tc.index , not list order DeepSeek interleaves chunks across parallel tool calls (probe_7 100% interleave on 3/3 V4-Pro and V4-Flash trials). Use a dict[int, slot] : tool_call_acc: dict [ int , dict ] = {} for chunk in stream: for tc in (chunk.choices[ 0 ].delta.tool_calls or []): slot = tool_call_acc.setdefault(tc.index, { \"id\" : None , \"name\" : None , \"arguments\" : \"\" }) if tc. id : slot[ \"id\" ] = tc. id if tc.function and tc.function.name: slot[ \"name\" ] = tc.function.name if tc.function and tc.function.arguments: slot[ \"arguments\" ] += tc.function.arguments C5 · Streaming: list buffer + \"\".join , NOT state += chunk DeepSeek streams 1-3 chars per reasoning chunk. state.text += chunk is O(n²) string allocation: buf = [] for chunk in stream: if c := (chunk.choices[ 0 ].delta.content or \"\" ): buf.append(c) final = \"\" .join(buf) C6 · Tolerate empty stream chunks DeepSeek emits ~3 chunks per response with choices == [] . Check truthiness before indexing: for chunk in stream: choices = chunk.choices or [] if not choices: if chunk.usage is not None : usage = chunk.usage continue ... C7 · Cap context length under 1,048,576 tokens The V4-Pro / V4-Flash hard ceiling is exactly 2^20 = 1,048,576 tokens (probe_6b validated). The server enforces len(messages_tokens) + max_tokens <= 1,048,576 and returns 400 if exceeded. C8 · Cache awareness — do NOT inject volatile content into the system prompt DeepSeek's prefix cache buckets in 256-token blocks and gives a 50× discount on hits. To maximise: Do NOT prune or summarise history aggressively (every prune = cache miss) Do NOT inject \"current date: 2026-05-09\" or similar into the cached prefix Do read both prompt_cache_hit_tokens (DeepSeek-native) AND prompt_tokens_details.cached_tokens (OpenAI-shape) — both are returned C9 · Avoid /beta endpoint when calling V4 with tools /beta silently remaps deepseek-v4-pro → legacy deepseek-reasoner , which rejects specific tool_choice={\"type\":\"function\",\"function\":{\"name\":\"...\"}} . Use https://api.deepseek.com for tool-using flows. C10 · strict: true is empirically OK on V4 (despite #1069 still being open) You MAY enable function.strict=true and additionalProperties=false on V4-Pro / V4-Flash — the historic JSON-corruption bug ( deepseek-ai/DeepSeek-V3#1069 ) was not reproducible in 32 trials on 2026-05-09. Still validate JSON post-hoc with jsonschema . Drop-in implementation If the user's environment allows installing third-party libraries, use any of: form install command Python lib pip install deepseek-harness from deepseek_harness import DeepSeekHarness Python CLI pip install deepseek-harness-cli dsh chat , dsh doctor , dsh validate MCP server npx -y @deepseek-harness/mcp wire into Claude/Cursor/Cline/ChatWise MCP config If they want zero deps beyond openai , copy scripts/safe_init.py (in this skill folder) into their project. It implements all 10 rules in 200 lines. Reproduction commands Every claim in this skill is backed by a runnable probe in reports/probes/ : # Reproduce the reasoning_content 400: python reports/probes/probe_2_reasoning_lifecycle.py --n 3 # Expected: 3/3 phase-B BadRequestError with the verbatim error message above. # Confirm tool-call leakage rate at 0% on official endpoint: python reports/probes/probe_3_tool_call_leakage.py --n 30 # Map cache prefix sensitivity: python reports/probes/probe_5_cache_prefix_sensitivity.py --n 8 See reports/REPORT_2026-05-09.md for the full 16-finding report.",
    "model_config": {
        "provider": "deepseek",
        "model": "deepseek-chat",
        "temperature": 0.7,
        "max_tokens": 4096,
        "top_p": 0.9
    },
    "examples": [
        {
            "input": "请用deepseek-harness帮我处理问题",
            "output": "好的，我是deepseek-harness。Use this skill whenever the user wants to call DeepSeek V4-Pro / V4-Flash (or its legacy aliases deepseek-chat / deepseek-reasoner), or you see code that imports `from openai import OpenAI` with `base_url=\"https://api.deepseek.com\"`. This skill teaches you the 10 protocol contract rules required to avoid the 16 documented bugs (reasoning_content lifecycle 400, tool-call leakage, max_tokens runaway → V8 string limit, parallel tool delta interleave, prefix-cache invalidation, /beta endpoint remap, etc.) and ships a single drop-in `safe_init.py` script you can copy into the user's project. 我会根据你的需求提供专业帮助。"
        },
        {
            "input": "介绍一下你的能力",
            "output": "我是deepseek-harness，专注于内容创作领域。Use this skill whenever the user wants to call DeepSeek V4-Pro / V4-Flash (or its legacy aliases deepseek-chat / deepseek-reasoner), or you see code that imports `from openai import OpenAI` with `base_url=\"https://api.deepseek.com\"`. This skill teaches you the 10 protocol contract rules required to avoid the 16 documented bugs (reasoning_content lifecycle 400, tool-call leakage, max_tokens runaway → V8 string limit, parallel tool delta interleave, prefix-cache invalidation, /beta endpoint remap, etc.) and ships a single drop-in `safe_init.py` script you can copy into the user's project."
        }
    ],
    "install_guide": {
        "coze": "在 Coze 平台创建 Bot -> 技能配置 -> 导入此 .skill 文件",
        "dify": "在 Dify 平台创建应用 -> 添加知识库 -> 导入此 .skill 配置",
        "claude": "将 system_prompt 字段内容复制到 Claude 自定义指令中",
        "custom": "将此 .skill 文件加载到你的 AI Agent 框架中，解析 system_prompt 和 model_config 即可使用"
    },
    "scripts": {
        "python": "# deepseek-harness - Python extension\n# Add custom Python logic here\ndef process(input_data):\n    return input_data\n",
        "javascript": "// deepseek-harness - JavaScript extension\n// Add custom JS logic here\nfunction process(inputData) {\n    return inputData;\n}\n"
    },
    "tools": {
        "mcp_servers": [],
        "api_endpoints": []
    },
    "dependencies": {
        "python": [],
        "node": []
    },
    "hooks": {
        "on_load": "echo \"Skill loaded: deepseek-harness\"",
        "on_call": "",
        "on_error": "echo \"Skill error: please check logs\""
    }
}