dsh-handbook: a community-written manual for DeepSeek Harness, read against its own alpha warning

The gap dsh-handbook claims to fill, and who that gap belongs to

DeepSeek Harness is described in this repository as an agent runtime open-sourced by DeepSeek on 2026-08-13, built on an everything-is-a-plugin model. The handbook's own framing of the problem is narrow and specific: the official material is architecture-oriented, and there is no path from zero to a working setup. That is a real category of gap. Architecture documents explain how a system is put together; they rarely tell you which command to type first, what a profile file is for, or what a plugin mount actually changes. The handbook positions itself as the second document, and it is aimed at four reader types it names explicitly: people meeting dsh for the first time, developers who want a clonable plugin template, people comparing agent runtimes for a selection decision, and people tuning inference settings or cost. The Chinese-first choice is deliberate and stated, with English mirror files for some chapters. If you do not read Chinese and the English file for the chapter you need is missing, the handbook is only partly available to you, and the README does not claim full English parity.

How the material is organised: five stages, fifteen chapters, one ecosystem report

The table of contents is staged rather than topic-indexed. Stage one covers what a harness is and a five-minute quickstart. Stage two covers profiles and the plugin system, then walks through writing a first plugin with code, tests and what the README calls real-machine verification. Stage three covers application scenarios and performance tuning, including a section on cache hit rate. Stage four covers the ecosystem, the tools and context system, and MCP with subagents and workflows. Stage five holds complex worked cases, a future-outlook chapter, a limitations chapter, and then security and sandboxing plus cache and cost. Chapter 15 is a separate ecosystem report that the README says cross-checks data from 1804 plugin repositories against 780 discussion threads. That report is the most unusual part of the repository: it is observational rather than instructional, and it makes claims about where the ecosystem is thin, such as a stated supply gap in the sandbox category. Treat those counts as the author's own survey with a described method, not as an independent measurement. The structure is sensible for a tutorial. It is less sensible as a reference, because a reader who wants the sandbox permission model has to know it lives in chapter 13 rather than in a lookup table.

Getting dsh running: the commands the handbook actually gives

The quickstart is two commands. The first is npx -y @deepseek-ai/dsh web, which starts a web interface the README says is reachable at http://127.0.0.1:3080. The second is dsh --profile headless "你好，请用一句话介绍自己", a one-shot invocation the handbook recommends for scripts and CI. Node.js 22 or newer is listed as a requirement. The profile flag is the mechanism worth understanding before you copy anything: the handbook describes a profile as a bundle stack plus a patch layer, expressed through package.json and cordis.patch.yml. Mounting a plugin is described as two edits, adding a dependency and adding an insert line. That is a small surface, and it is the reason the plugin chapter can stay short. The handbook also documents a three-level reasoning setting, low, high and max, with high as the default, and states that thinking consumes about 90 percent of tool-chain time. There is a caveat printed next to it that matters more than the setting itself: low is described as the level on the gateway the handbook measured, while the DeepSeek official adapter uses off, high and max. If you copy low from the quickstart while running the official adapter, you are copying a value that does not exist in your configuration. That single note is the most practically valuable sentence in the README.

The accuracy problem: documenting a runtime that is still at alpha

The repository carries a warning block above its own quickstart. It states that the GitHub version of dsh is v0.1.3-alpha.1, that this is a pre-release tag, that npm carries a 0.1.2-rc.1 line, and that production use should be evaluated carefully. A handbook for a pre-release runtime has a structural accuracy problem, and this one is honest about it rather than hiding it. Chapter 12 is titled known shortcomings and boundaries and is described as an honest rc-version chapter covering instability, an early ecosystem and cross-platform weaknesses. The ecosystem report names Windows as the first pain point, citing Chinese path handling, koffi, port and subprocess issues, and says the data and the discussion threads agree. The report also describes a family of serialization bugs around unknown tool, omitted reasoning and discarded run_code, which it calls the main battleground of the rc period. Those are the kinds of defects that make a tutorial's example output stale within weeks. The handbook's mitigation is a feedback pipeline document with 19 trackable items, which is a process, not a guarantee. The version badge in the README and the handbook's own chapter numbering will drift apart from the runtime unless the author keeps pace, and nothing in the material shows how that is enforced.

Where the handbook is the wrong tool, and what to use instead

If your question is what dsh's request lifecycle actually does at a given extension point, the handbook is the wrong first stop. It is a teaching document, and its own comparison table says the official material takes the architecture view while the handbook takes the beginner view. The upstream AGENTS.md and architecture.md files are the primary source for how the runtime is put together, and the handbook points at them. The same applies to version-specific behaviour: the handbook's measured numbers, such as the stated 97 percent cache hit rate and the case timings it reports (a data-cleaning pipeline at 186 seconds, a five-bug fix at 94 seconds), come from its own environment and its own adapter. They are not portable constants, and the README does not present them as such. For a selection decision, the handbook offers a capability matrix against Claude Code, Codex, OpenCode, Gemini and Kimi, and its own summary of the trade-off is that deep customisation and ecosystem point to dsh while out-of-the-box use points to Claude Code. That is a reasonable shape for a comparison, but it is the handbook's own table, and the reader should treat a vendor-adjacent tutorial's comparison as an argument rather than a measurement.

Licence, maintenance and the cost of keeping up

The README badge identifies the licence as CC-BY-NC-SA-4.0, which is a content licence rather than a software licence. For a handbook that means the text and the PDF carry a non-commercial restriction and a share-alike condition on derivatives, which is a different proposition from the MIT licence the README attributes to dsh itself. If you were considering translating, excerpting or bundling this material into training content or a paid product, the non-commercial term is the clause to read first. This is a description of what the licence identifier says, not legal advice. On maintenance, the repository shows a release cadence of v1.6.0, v1.7.0 and v1.8.0 across 2026-08-13 and 2026-08-14, with v1.8.0 described as the 15-chapter complete edition and the last push dated 2026-09-07. Rapid handbook releases during a runtime's rc period are a signal of active maintenance and also a signal of churn: three handbook versions in roughly a day suggests the text was still settling. The upgrade cost for a reader is low, since the artefacts are HTML and PDF, but the verification cost is not, because each new runtime release can invalidate a chapter. Budget for re-reading chapter 12 and chapter 13 whenever you move dsh versions, since those are the chapters most exposed to pre-release behaviour.

Editorial conclusion

Adopt dsh-handbook if you are new to dsh, read Chinese or can work with the English mirror files, and want a sequenced path that the upstream architecture documents do not provide; the quickstart command, the profile and plugin chapters, and the limitations chapter are the parts worth your first hour. Do not adopt it as a reference for production dsh behaviour, because the repository itself warns that dsh is at v0.1.3-alpha.1 while npm carries a 0.1.2-rc.1 line, and any chapter can be invalidated by a runtime release. Before relying on a chapter, open the docs/02-quickstart.md note on reasoning levels and compare it against the adapter you actually run, then check the release tag you installed against the version the chapter was written for.

Official sources

1. Electricitysheep/dsh-handbook on GitHub
2. Issues
3. Project website
4. README
5. Releases