deepseek-harness-handbook README

The project's README from github.com/sandbaseai/deepseek-harness-handbook. As one markdown file: README.md.

DeepSeek Harness Handbook

English · 简体中文 · 日本語 · 한국어 · Español

GitHub stars Latest release Content check License: Apache-2.0

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.

DeepSeek Harness Handbook — source-backed operator guides, Install Doctor, and Failure Router

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.

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:

Run Evaluate Debug or build
Five-minute quickstart Agent Harness Scorecard Interactive Failure Router
CLI and headless map Agent runtime map Profile repair and reset
API cost boundary Current field status MCP guide

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

I want to… Start here
Explain why ask_user_question aborted before I answered ask_user_question abort and deadline guide
Stop an Agent alternating between unknown edit and str_replace_editor calls Unknown edit-tool assembly diagnosis
Reach Settings sections clipped below a long plugin navigation Settings navigation overflow repair
Organize Sessions without turning a sidebar label into a filesystem root Session Collections and no-Workspace design
Design two real Session panes without crossing data or interaction identity Multi-Session presentation contract
Customize the Web UI without patching files inside an npx installation Persistent Client plugin guide
Generate strict Typert artifacts for a plugin developed outside the monorepo Out-of-tree Typert generation guide
Diagnose manual /compact ending with DeepSeek request aborted by caller Manual compaction cancellation runbook
Fix ERR_PNPM_UNEXPECTED_STORE during a plugin update pnpm store-identity recovery
Fix AbortSignal.any is not a function even though Node looks current Runtime identity and offline recovery runbook
Recover Web stuck on Loading plugins in a pnpm source checkout pnpm symlink boot guide
Separate Responses API full-history traffic, retry attempts, and SSE leaks [Responses overload runbook](https://sandbaseai.github.io/deepseek-harness-handbook/responses-overload-retry.html

deepseek-harness-handbook (sandbaseai/deepseek-harness-handbook)

Searching Database…

234 ·GitHub
Deepseek-harness-handbook
What is this?A community-maintained, agent-first handbook for DeepSeek Harness: 173 source-backed guides on running, debugging, and extending the agent runtime, plus a curated 79-entry ecosystem map. English is canonical, with 202 localized documents including reviewed Simplified Chinese.
Is this a plugin I add to DeepSeek Harness, or plain documentation?Pure documentation, not a plugin — there is nothing to install. The README explicitly warns against running dsh plugin add on this repository because it has no dsh.bundle activation contract; you read it on GitHub or the visual field site.
How do I start with it?Pick the path that fits your goal: a five-minute quickstart for first runs, the Agent Harness Scorecard to evaluate, or the Interactive Failure Router to debug, plus a full task-specific index. Everything reads directly on GitHub or the visual field guides site.
Any gotchas before I rely on it?It is independent community documentation, not official DeepSeek support, and DSH itself is a developer preview with compatibility-breaking changes — pages carry verification dates, so pin the revision you deploy. Ecosystem entries are discovery leads, not security endorsements.
Is it written for agent developers or for DeepSeek end users?For people building and operating agents — the runtime is explained from the builder's and operator's perspective, not for end users just chatting with a model.
What is DeepSeek Harness, the runtime this handbook covers?A composable agent runtime that connects model providers, tools, approval, sandboxing, durable sessions, subagents, and user interfaces through a plugin graph. The handbook's core claim is that it is more than a model wrapper.
What does 'the complete Agent boundary' include?Model routing, tools, approval, sandboxing, durable Sessions, plugins, MCP, ACP, and operator-visible failure recovery — so claims about tools, context, or long-running agents get tested at the right boundary: model, provider, framework, or runtime.
How source-backed are the guides?Each entry names the pinned official source revision it was checked against — currently rc.2 (b150a551...) or alpha.1 (cd5ef814...) — and labels claims as observed, source-verified, inferred, or proposed, with acceptance gates instead of copy-paste happy paths.
What kinds of problems do the troubleshooting runbooks solve?Concrete field failures: a Firefox-only blank Web client, successful PowerShell commands buried in ConstrainedLanguage stderr noise, one corrupt Session blocking Web startup, macOS sandbox-exec ENOENT, and growing WebContent memory in long ChatView sessions.
What are similar projects?awesome-deepseek-harness, Awesome-DeepSeek-Harness-Plugins, awesome-deepseek-harness, Blue-Whale-Harness, Proteus, awesome-dsh-plugin, deepseek-harness-orange-book, awesome-harness-engineering
Which topics is it in?troubleshooting, agent-runtime, acp, plugins, agent-harness, debugging, dsh, evaluation, sandbox, deepseek-harness, multilingual, deepseek
Creator
sandbaseai
Size
6.5 MB
Stars
234
Updated
CommitAug 31Releasev0.5.438Aug 29
Age
2mo
Commits · 90 Days