DeepSeek Harness White Paper · dsh-handbook

• Three intuitions: dsh = the Lego base for Agents; harness = the engineering layer wrapped around the model; 2026 = the era of programmable Agents
• Core facts: MIT open-source · TypeScript · "everything is a plugin" · released 2026-08-13
• dsh vs 5 major Agents capability matrix (Claude Code / Codex / OpenCode / Gemini / Kimi): open-source ✅, model-agnostic ✅, official-grade plugin system (unique), custom UI ✅, headless CI ✅
• Selection decision: deep customization + ecosystem → dsh; out-of-the-box → Claude Code

• Launch with one command: npx -y @deepseek-ai/dsh web → http://127.0.0.1:3080

• Dual modes: web (chat UI) / headless (dsh --profile headless "任务", CI-friendly)

• Three reasoning tiers: low (fastest / simple tasks) · high (default) · max (strongest / complex reasoning) — performance-critical: thinking accounts for 90% of the toolchain time. > Note: low is a tier of the gateway tested in this whitepaper (pi-ai/opencode-go); the official DeepSeek adapter uses off (thinking disabled / fastest) / high / max (see the note in 02-quickstart 2.3)

• First plugin: mount the Git panel in 4 steps

• profile = bundle stack + your patch layer (package.json + cordis.patch.yml)
• Mounting a plugin requires only 2 changes (add dependency + add insert line)
• Host/client dual-half: one npm package = Node-side tools/services + browser-side UI
• 5 major extension points: agent/request waterfall, conversationEvents, ctx.slots, settings, ctx.provide
• 6 real pitfalls: rc.1 dependency breakage, missing plugin main, forgetting to await next(), unrecognizable types, ModuleLoader, port occupation

• Write a speed-boost plugin from scratch (full teardown): pure-function decision + agent/request waterfall injection
• Core technique: extract decision logic into pure functions (unit tests in milliseconds) → real-machine only verifies "whether injection happened"
• 3 dev disciplines: find the extension point first / extract logic into pure functions / never skip real-machine verification
• Real-machine log evidence: calls=[{name:"write"}] => reasoningEffort=low

• Git panel push/pull/fetch (PR #10): --force-with-lease safety red line + local bare-repo integration test + Playwright real-machine verification
• HTML draft preview (PR #11): srcdoc decision pure function under sandbox security constraints
• Speed-boost plugin example: downgrade reasoning per step in long toolchains

• Performance model: 90% of toolchain task time is model thinking (before each tool call)
• Tier strategy: simple turns low / everyday high / complex max — downgrading is the highest-leverage speedup
• 7 real pitfalls: including the eval trap where "simple task suddenly faster = cache hit"
• Three questions to check a scorecard: who ran it / what harness / how strict the validator

• Official entry points: repo / API docs / Discord / Discussions
• Current status: official team not accepting external PRs yet → building dsh-plugin ecosystem projects is the officially named contribution path
• Beginner path: use it → small PR → ship a plugin → write content

• 60+ official capability packages map: tools / context / conversation / sub-agents / MCP / workflow / security
• Built-in tools (measured): read/write/grep/glob/edit/bash/todo/skill
• Artifact tracking: tool returns locations → open artifacts at conversation end
• Context injection: layered system prompt + skills directory
• Auto compaction for long conversations + sandbox/permission/approval security layer

• MCP: connect external tool servers (community already has a token-tracking plugin)
• Sub-agents: parallel task delegation (large-repo research / long-task decomposition)
• Workflows: deterministic multi-step orchestration (pull → clean → report → validate)
• Four-stage beginner path: single Agent → +MCP → +sub-agents → +workflows

• Case A: data quality analysis → cleaning → visualization (186s, 52→35 rows to zero, chart.png, with tradeoff notes)
• Case B: 5-bug fix + 49 tests (94s, pytest 49 passed, covering divide-by-zero/negative/precision boundaries)
• Profile: multi-step toolchain auto-orchestration + judgment + traceable artifacts
• Privacy notice: all synthetic data / self-made code

• 30+ terms: harness/profile/bundle/cordis/extension points/waterfall/compaction…
• Command quick reference: dsh core / env / troubleshooting / plugin dev
• Benchmark: same-model 3-Agent measured (median of 3 runs)

• Tech/ecosystem/competition/opportunity/risk five-dimension forecast + timeline
• Opportunity: official ecosystem in early stage; building dsh-plugin projects is the entry bonus

• Instability: rc iterating fast, frequent breaking changes
• Early ecosystem: 60+ official packages but plugin ecosystem just starting
• Cross-platform gaps: Windows family pitfall records (incl. Node version red lines)

• Sandbox mechanism: process isolation (bwrap/Landlock/Seatbelt) + permission tiers + approval flows
• Community audit boundaries: node:vm not a security boundary, approval loops, workspace-write recursive delete, and other real escape surfaces
• Plugin security audit checklist: third-party audit methodology (#454)

• Cache mechanism: context caching + 97% measured hit rate (Flash discount 98% / Pro 99%+)
• Cost model: where tokens go + reasoning tier linkage + real task budgets
• Visualization: session log / balance plugin to see per-item cost

npx -y @deepseek-ai/dsh web          # 安装即启动 Web UI
dsh --profile headless "任务"        # 一次性任务（脚本/CI）

Reasoning tiers: low (fastest/simple turns) · high (default) · max (strongest/complex reasoning) — low is the tier measured in the gateway (pi-ai); the official adapter uses off/high/max

90% of toolchain task time is thinking — downgrading is the highest-leverage speedup Full card: docs/cheatsheet.md

# ① package.json 加依赖
"my-plugin": "link:C:\\path\\to\\my-plugin"
# ② cordis.patch.yml 加挂载
- insert:
    - id: my-plugin
      name: my-plugin

cd ~/.dsh/profiles/web && pnpm install && dsh web

Cloneable template (incl. pure function + waterfall + tests): examples/plugin-template/

agent-default-model:
  model: deepseek-v4-flash    # 或 deepseek-v4-pro
  reasoningEffort: high       # off（关闭思考/最快）/ high（默认）/ max（最强）

All fields (profile/cordis.patch.yml/common scenarios): docs/config-reference.md

1. Is dsh a model? No — it's a runtime; the model connects via the llm plugin
2. How is it different from Claude Code? Claude Code is a "complete car"; dsh is the "Lego base" (open-source, customizable)
3. Does it cost money? dsh is free and open-source; conversations are pay-per-use (cache discounts: Flash tier 98% / Pro tier 99%+, measured session cache hit rate 97%)
4. Plugin install 404? rc.1 dependency break — use dependency line >=0.1.2-rc.1 <0.2.0
5. Production-ready? rc phase has breaking changes; ecosystem use cases can start now

Full FAQ (six categories): docs/faq.md