The DSH official docs, in the right order

DeepSeek Harness’s official documentation lives in the repository’s docs/ directory: 171 documents, 97% with an official Simplified Chinese twin (add .zh.md next to the English file, e.g. architecture.zh.md). The problem was never a lack of docs — it is that nobody tells you which five to read first. This guide organizes them into two reading paths and flags the three places newcomers most often get stuck.

One warning before you read: the project is in developer preview, and the README plus SAFETY.md state breaking changes are expected. Any third-party mirror can lag upstream — check the commit date before trusting a page.

The user path: you just want to run DSH

Four documents, in this order:

1. README — one-line start with npx @deepseek-ai/dsh web.
2. SAFETY.md — the safety notice the official side asks you to read first.
3. Use the Web UI — the interface and daily operation.
4. Configure models — newcomer trap #1. Credentials, providers and model aliases intertwine, and a misconfiguration presents as “it boots but nothing happens.” Keep the Plugin Config Catalog at hand afterwards; it is the dictionary for configuration keys.

The developer path: writing plugins or touching the source

1. Architecture — the everything-is-a-plugin design.
2. Cordis primer — services, events and fibers in one pass.
3. The Cordis tutorial, chapters 1–7 — hands-on, no API key needed. Chapters 2 and 3 are newcomer trap #2: inject dependency declaration and effect cleanup. The official postmortem 0001 is a live incident caused by an export default dropping inject — read it right after chapter 3 and the lesson sticks.
4. The DSH plugin development series — from first plugin to packaging and publishing.
5. The Cookbook — 11 authoritative walkthroughs: tools, settings cards, model adapters.

The cordis.yml composition and overlay mechanism is newcomer trap #3: read tutorial chapter 6 (composition and HMR) together with the development guide.

The dictionary (do not read in order)

docs/subsystems/ holds 51 subsystem deep-dives — sandbox, approval, sessions, skills, webhooks, slots. They are a dictionary, not a course: look up the subsystem you are touching. Two navigational documents are worth bookmarking: the documentation graph index and the glossary.

The five documents without a Chinese twin (verified 2026-09-17)

docs/AGENTS.md (the documentation standard), cordis-api/inherited.md, and three translation-governance files under i18n/. The other 166 all have official Chinese versions.

On third-party mirrors and version drift

Community mirror sites republish the official docs as multilingual web pages (dshfind’s docs section, for example, with compliant MIT attribution). Two things to know: the Chinese versions exist in the upstream repository itself — the mirror’s “Chinese” is not its own translation — and mirrors pin a fixed commit: when we checked, one major mirror was about a month behind upstream and missing several newer subsystem documents. For current behavior, the repository is always the source of truth.

FAQ

Do the official docs have a Chinese version?

Yes, as a first-class mechanism: 1,646 .zh.md files in the repository, covering 97% of docs/. Insert .zh before the .md of the English path. No official Japanese or Korean versions exist.

Which three traps should I avoid first?

Model configuration (read the providers doc together with the config catalog), inject declarations and effect cleanup (Cordis tutorial chapters 2–3 plus postmortem 0001), and the cordis.yml composition mechanism (tutorial chapter 6). These are also the most frequent failure points in the official postmortems and Discussions.

What if the docs disagree with actual behavior?

The project ships weekly and breaking changes are normal. Check the repository’s release records against the commit date of the document you are reading, and treat the repository — never a mirror — as canonical.