DeepSeek Harness Handbook
English · 简体中文 · 日本語 · 한국어 · Español
Listed in Awesome DeepSeek Harness, the community-maintained DSH ecosystem directory.
Also mapped in SandBase's Awesome Agent Runtime, alongside runtime, sandbox, and tool-protocol infrastructure.
The agent-first, English-canonical field guide to understanding, running, debugging, and extending DeepSeek Harness, with reviewed Simplified Chinese coverage and multilingual foundations. — Community-maintained and open-source.
If this handbook saves you a debugging cycle, star the repository. That signal helps more Agent builders find source-backed DeepSeek Harness guidance.
Cite or link the handbook
If you publish a DeepSeek Harness tutorial, benchmark, plugin, or integration, link to the canonical handbook URL so readers can follow the source-backed runbooks and current release notes:
SandBase. DeepSeek Harness Handbook: source-backed Agent runtime guides.
https://github.com/sandbaseai/deepseek-harness-handbook
The handbook is community-maintained and independent of DeepSeek AI. Please link to the exact guide or release when you make a version-sensitive claim.
173 canonical guides · 202 localized documents · 79 curated Awesome resources · rc.2 + alpha.1 source-pinned analysis
Unlike a command catalog, this handbook follows the complete Agent boundary: model routing, tools, approval, sandboxing, durable Sessions, plugins, MCP, ACP, and operator-visible failure recovery. Version-sensitive pages identify the source revision they were checked against.
Choose one path and get to evidence quickly:
Explore the Agent ecosystem
The curated Awesome resource map now covers 79 source-linked starting points, including checkpoint/rewind, side Sessions, child-Agent visibility, browser and Office surfaces, plugin discovery and health checks, database analysis, adversarial workflow review, Agent evolution, mobile access, and provider fallback controls. Each entry is an Agent-oriented discovery lead, not a compatibility or security endorsement; inspect permissions, credentials, and rollback paths before installation.
For scale context, the pinned upstream catalog snapshot contains 271 hub repositories, 1,000 public dsh-plugin topic repositories, and 471 manual additions. This handbook deliberately curates a smaller, source-linked subset so every entry has an explicit Agent boundary to inspect.
For Chinese-language peer discussion, see the upstream community’s Feishu group discussion for the current invite and context. It is community-run and not official DeepSeek support; do not share credentials, private Session logs, or sensitive workspace data.
Newly source-verified
| Problem |
What the guide proves |
| Understand Harness versus framework |
Separate model, provider, framework, and runtime responsibilities so tool, context, and long-running Agent claims are tested at the right boundary. |
A continuable child exposes only report |
Separate parent/child tool views, preset composition order, toolFilter, and cold-resume evidence before treating model prose as a tool result. |
| Read-only Windows PowerShell succeeds with noisy stderr |
Separate command output from ConstrainedLanguage preamble diagnostics and preserve the ACL sandbox while validating a narrow fix. |
| Firefox shows a blank Web client while Chrome works |
Separate browser bootstrap, cached assets, origin/WebSocket, and extension boundaries before touching provider credentials or durable Sessions. |
| An alpha.1 auth token cannot be obtained or entered |
Keep acquisition, UI entry, credential storage, token scope, and outbound authorization as separate contracts with redacted evidence. |
A settings section recurses on removeChild |
Route NotFoundError through DOM ownership and render-generation evidence instead of misclassifying it as a proven MutationObserver CPU loop. |
| Long ChatView sessions grow WebContent memory |
Separate renderer DOM retention from Host memory, preserve Sessions, and measure a virtualization boundary before using reload as containment. |
| Choose from the DSH ecosystem by capability |
Use four bounded Agent starter paths and multilingual maps to choose skills, memory, routing, UI, file, research, and governance resources from the public Awesome catalog. |
| Custom providers can hide multi-protocol models |
Separate live model discovery from provider-default filtering, then pin each model's protocol and verify the actual request endpoint. |
| Recover a client Cordis inspect query stuck Pending |
Separate a page refusal from Host settlement, preserve first-valid-page routing, and make every inspect wait bounded. |
| Evaluate cross-Session memory without leaking scope or losing the store |
A local JSON file is not a local-only data path once recall becomes a model-visible tool result; require scoped identity, atomic writes, corruption quarantine, retrieval budgets, and explicit privacy copy. |
| Edit model capabilities without mistaking declarations for proof |
Image, reasoning, capacity, and gateway fields declare a route contract; verify the real endpoint and keep headers out of whole-namespace presets. |
| Diagnose a terminal command still shown after 40 minutes |
Standard alpha.1 foreground Bash cannot explain that timer by default; route background jobs, persistent terminals, live processes, and stale presentation before retrying. |
| Repair count-balanced but ID-invalid tool history |
Equal call/result counts do not prove valid pairing; use an ordered identity ledger and keep request stripping observable as containment. |
| Stop empty continuation chunks from erasing a valid tool ID and name |
rc.2 and tagged alpha.1 both accept explicit empty identity updates; retain the first valid identity, reject never-identified calls before policy, and keep invalid records out of Session replay. |
| Recover when one corrupt Session prevents Web startup |
A Windows plugin tree failed to load can wrap one bad Zstandard header; isolate the artifact before changing the launcher, profile, or every healthy Session. |
Classify macOS sandbox-exec ENOENT |
Host executable lookup can succeed while the Harness sandbox provider cannot start; preserve fail-closed behavior and prove the provider boundary before changing authority. |
Keep a single ~ literal in Markdown |
alpha.1 calls both GFM parsers without disabling single-tilde strikethrough; verify source and served bundle across streaming, finalized, and plain-text projections. |
| Evaluate a bounded Ralph failure successor |
Discussion #109's recovery proposal can remain fail-closed: default off, fresh child only, shared budgets, observable failure state, no-change circuit breaking, and no retry for infrastructure failures. |
| Keep HTTP(S) URLs out of filesystem tools |
Discussion #4862's Windows reproduction is a capability-boundary failure: reject URI-like input before local path resolution, preserve the original value, and route network retrieval to a web/fetch tool. |
| Fold compaction and retry usage without losing cost evidence |
Discussion #1886 separates duplicate chunk/message observations from independent retry attempts and makes compaction/summary.usage visible in cumulative accounting. |
Each entry above names its pinned official source revision—currently rc.2 b150a551… or alpha.1 cd5ef814…—records what is observed, source-verified, inferred, or proposed, and includes acceptance gates rather than a copy-paste-only happy path.
If the handbook resolves a real question, star it on GitHub. That signal helps the next Agent builder find a source-backed answer instead of another unverified command list. If a claim differs from the runtime you operate, open an evidence report with the exact DSH version and first failing boundary.
Browse the visual field guides · Explore the Awesome resource map · Download its JSON index · Read the Show & Tell · Help validate the index · Request a source-backed runbook · Subscribe to new guides · Read the changelog
DeepSeek Harness is more than a model wrapper. It is a composable agent runtime that connects model providers, tools, approval, sandboxing, durable sessions, subagents, and user interfaces through a plugin graph. This independent handbook explains those systems from the perspective of people building and operating agents.
The project is maintained by SandBase. It is not an official DeepSeek AI project.
[!IMPORTANT]
DeepSeek Harness is in developer preview and may introduce compatibility-breaking changes. Pages in this handbook name their verification date and link to primary sources. Pin the revision you deploy.
This repository is documentation, not a DeepSeek Harness plugin. Do not run dsh plugin add github:sandbaseai/deepseek-harness-handbook; the handbook has no dsh.bundle activation contract. Read the guides from GitHub or the visual field site instead.
Start with your goal
Choose the smallest path that matches the job. The full task index remains available below without occupying the repository's first screen.
| Goal |
Fastest useful path |
| Install or run DeepSeek Harness for the first time |
Five-minute quickstart |
| UI looks reset after changing launch commands |
Install identity and DSH_HOME guide |
npx installs but dsh web burns CPU without a port |
Post-install Web startup boundary |
| ACP inline images fail in the Python SDK |
ACP inline-image contract |
| Web renderer drops dollar signs from prose |
Literal dollar rendering |
| Every request fails during plugin inventory preparation |
Request extension boundary |
| A follow-up accepted during a running turn never starts |
Queued follow-up wake-latch recovery |
| A renamed workspace breaks tools and sandbox roots |
Recover a stale session cwd |
| Evaluate a Codex-style Web client without replacing the Host |
Client extension boundary |
| OpenRouter rejects concurrent requests with an in-flight budget cap |
Retry the provider-attested cooldown |
| A resumed Agent intermittently loses a registered tool |
Resumed tool-view boundary |
| Evaluate nested follow-up Sessions safely |
Nested follow-up evaluation |
| Sessions corrupt under concurrent writers or recovery |
Session write-integrity invariants |
| Session cold-open is dominated by zstd frames |
Session framing performance |
| Diagnose a failing install |
Interactive Install Doctor |
| Route an Agent, model, tool, Session, or UI failure |
Interactive Failure Router |
| Check what is shipped, inferred, or proposed |
Current field status |
| Configure a model, gateway, image route, or reasoning level |
Model provider guide |
| Build and package a plugin |
First plugin lab |
| Connect MCP tools |
MCP integration guide |
| Connect SandBase Harness as a real MCP runtime |
SandBase Harness bridge guide |
| Understand Sessions, Skills, and long-term memory |
Memory architecture |
| Audit permissions, credentials, or a community plugin |
Security guides |
Browse the complete task-specific index
Every current task route
一份由社区维护、面向 Agent 的 DeepSeek Harness 手册：包含 173 篇有出处的指南，涵盖 Agent 运行时的运行、调试和扩展，另附一份精选的 79 条生态地图。以英文为权威版本，另有 202 篇本地化文档，其中包括经过审校的简体中文。