Preface¶

DeepSeek Harness (dsh) is an Agent runtime open-sourced by DeepSeek. The first line of the official repository reads: everything is a plugin — both model adapters, tool registries, session logs, and even the Agent loop itself are plugins, assembled by Cordis. It is currently in the developer preview stage, and the official README notes that there will be breaking compatibility changes.

The official documentation is suitable for lookup: if you want to know an event name or how to start a certain profile, you can search the repository and documentation site. However, many people who encounter this architecture for the first time lack systematic learning: how do Cordis’s five core concepts translate into code? What is the difference between the headless and web profiles? How to run the turn/step/tool loop without connecting a real model?

Community maintainer yanhua1010 created a Chinese tutorial repository dsh-harness-tutorial: a VitePress site that explains principles and source code, 8 demos that hands-on with the real dsh package, and finally a hand-written educational version of mini-harness (React frontend + Node.js TypeScript backend). This article is organized after cross-checking the community directory page, GitHub repository README, and tutorial text.

What is this¶

dsh-harness-tutorial is a progressive Chinese tutorial for computer science undergraduates and engineers who want to read the dsh source code, maintained by yanhua1010, licensed under MIT (the LICENSE file has a copyright year of 2026). The GitHub repository had 46 stars as of 2026-08-17; the community directory page marked 39 stars when it was收录. The main language is TypeScript.

It does not solve the problem of “adding a new tool to a running Agent”, but breaks down “everything is a plugin” into actionable lessons:
- First build a mental model: Harness, Cordis, seams, turn/step
- Then对照 real repository packages to study the implementation line by line
- Then use 8 verified demos to run through the mechanism
- Finally implement a honest, simplified educational Agent from scratch

It is收录 in the “Tools and Capabilities” category of the community site DeepSeek Harness Plugin Library, with the收录 date of 2026-08-15. Please note that this directory is an independent community site, not officially affiliated with DeepSeek / FunFinder, and is not an official app store.

There is also a boundary to clarify first. The package.json in the repository root is for the VitePress tutorial site (private: true, scripts are docs:dev / docs:build), and does not declare dsh.bundle. The usage given in the README is to clone the repository and run the site, demos, and tutorial project with npm, rather than treating it as a runtime capability plugin attached to an existing profile. The directory page still provides the dsh plugin add command, which will be recorded as-is below; for actual learning, please refer to the repository README.

There is another repository ht426/deepseek-harness-tutorial on GitHub, also a Chinese tutorial, but it is a separate resource and should not be confused with yanhua1010/dsh-harness-tutorial introduced in this article.

Course Structure¶

The tutorial site divides the content into four sections, corresponding to four directories in the repository.

Principles Section (docs/guide/, 8 chapters)¶

Following the route on the tutorial homepage, this section aims to build a mental model rather than an API checklist:

The tutorial text quotes the original meaning of the official architecture documentation: every part of the product is a plugin, so every part can be replaced from the configuration. Coupling between functions occurs at runtime registration, rather than import in the source code.

Source Code Breakdown Section (docs/source/, 6 chapters)¶

This section breaks down the real repository package by package: repository map, Cordis kernel, session, agent, llm, tools. The tutorial’s own positioning is to explain “why this design is chosen” and “what problem each step solves”, rather than listing APIs. If you need exact types or event signatures, you should still return to deepseek-ai/deepseek-harness.

Practical Demo Section (demos/, 8 demos)¶

All 8 demos are based on real npm packages, with locked versions:
- DeepSeek Harness: @deepseek-ai/dsh@0.1.0-rc.6 (and the same version of dsh-llm, dsh-tools)
- Cordis: @deepseek-ai/cordis@4.0.1

demos/README.md states: Starting from Demo 4, the Mock adapter is used, no network requests are sent, and no API Key is required.

The tutorial marks Demo 5 as a watershed: the first time the real dsh agent loop runs, just with the model replaced by a self-written Mock plugin. Demos 5–8 use --patch overlays to attach local plugins to dsh --profile headless, and use their respective DSH_HOME to isolate session directories.

Educational Project (final-project/)¶

Write it again after reading. docs/project/overview.md states: the core library is about 900 lines of TypeScript, with zero runtime dependencies; then it is paired with a Node backend of Express + SSE, and a React frontend with chat and real-time event panels. The tutorial homepage totals about 1500 lines of the entire teaching implementation.

It retains the skeleton: three plugin forms, reversible effect, four event dispatch types, LLM seam, turn/step, four tool gates. What is cut is production-level complexity, such as fiber/HMR, schemasteery configuration validation, JSONL/SQLite persistence, sandbox and approval interface, sub-agent. The tutorial requires that each cut item explain “why real dsh needs it”.

Installation and Activation¶

The installation command given on the community directory page is as follows, run in the DeepSeek Harness terminal:

dsh plugin add github:yanhua1010/dsh-harness-tutorial

For reproducible installation, the directory page recommends pinning the commit hash. The latest commit of the current main branch is 2a29d03a83859f79e0c93d66fad2d5b405780b0b (2026-08-13):

dsh plugin add github:yanhua1010/dsh-harness-tutorial#2a29d03a83859f79e0c93d66fad2d5b405780b0b

The directory page also reminds: the plugin runs with the permissions of the current dsh process, and may execute code during installation; you should check the source code repository and license before installing.

As mentioned earlier, this repository is designed to be read and run as a tutorial, not installed as a capability plugin. The quick start from the repository README is as follows.

First clone:

git clone https://github.com/yanhua1010/dsh-harness-tutorial.git
cd dsh-harness-tutorial

Environment requirements from the tutorial homepage and README:
- Node.js ≥ 20.19 (22+ recommended)
- Use npm as the package manager, the tutorial does not require pnpm
- DeepSeek API Key is optional: all demos can be run with the Mock adapter, only the “connect to real model” section requires it

If you just want to read without running the site locally, you can directly open the GitHub Pages:
https://yanhua1010.github.io/dsh-harness-tutorial/

Typical Usage¶

The commands below are all from the repository README and demos/README.md, and can be reproduced as-is.

1. Open the tutorial site locally¶

npm install
npm run docs:dev

The development server address is http://localhost:5173/dsh-harness-tutorial/ (the repository uses the base path for GitHub Pages, and the local one also uses the same prefix). It is recommended to read in the order of “Principles Section → Source Code Breakdown → Demos → Tutorial Project”. The demo pages also mark the corresponding relationship with the principle chapters, for example, Demos 1–3 correspond to docs/guide/02-cordis-core.md.

2. Run Demos 1–4 (standalone scripts)¶

cd demos
npm install
npm run demo:1
npm run demo:2
npm run demo:3
npm run demo:4

These four scripts in demos/package.json call tsx to execute main.ts under each demo directory respectively. Demos 1–3 only depend on Cordis; Demo 4 introduces the dsh-llm package, using the Mock adapter to demonstrate the StreamChunk protocol.

3. Run Demo 5 with headless overlay¶

Demos 5–8 are no longer standalone tsx scripts, but patch local plugins into the real dsh process. Take Demo 5 as an example:

cd demos/05-headless-mock
DSH_HOME="$PWD/.dsh-home" npx dsh --profile headless --patch mock.patch.yml "你好，介绍一下你自己"
node read-session.mjs

There are two key points, both written in the demo preparation page:
- DSH_HOME must point to the demo’s own .dsh-home to avoid sessions and settings conflicting with other local profiles
- The local plugin path in the patch is ../../../plugins/xxx.ts, because the Loader’s baseUrl is $DSH_HOME/profiles/headless/

Demo 6 verifies the tool loop, Demo 7 can use the environment variable DSH_DEMO_DENY_ECHO=1 to take the rejection path, Demo 8 uses the custom profile demo8, and uses --dump-config to observe the combined configuration tree:

cd demos/08-profile
DSH_HOME="$PWD/.dsh-home" npx dsh --profile demo8 "你好，自定义 profile"
DSH_HOME="$PWD/.dsh-home" npx dsh --profile demo8 --dump-config | tail -12

The tutorial notes: headless has clean output and a one-time lifecycle, which is more suitable for observation; after learning Demo 8, you can replace --profile headless with --profile web to go through the same Mock链路 in the browser.

4. Start the educational mini-harness¶

cd final-project
npm install
npm run demo

npm run demo is a smoke test for the core library. To see the end-to-end effect with an interface, open two terminals:

npm run dev:server    # Backend http://127.0.0.1:4317
npm run dev:web       # Frontend http://localhost:5174

The project overview shows an excerpt of npm run demo: after the Mock adapter and echo tool are registered, a task will print turn/start → step/start → tool/call → tool/result → then open a second step for subsequent model calls → turn/end. This is the tool loop that you will write by hand in the tutorial version.

Applicable Scenarios and Notes¶

Who it is suitable for, the tutorial homepage writes specifically:
- Computer science undergraduates who have written TypeScript/JavaScript, understand HTTP and JSON, have heard of Function Calling, but have not seen the internal structure of an Agent framework
- Engineers who want to read the DeepSeek Harness source code: the official documentation is mainly for lookup, and this tutorial is mainly for learning, the two can be used together
- People who want to build their own Agent system and need a honest simplified implementation of about a thousand lines of code

It is not suitable to treat it as a production plugin that “installs and immediately adds a tool”. The root package is a tutorial site; to add a tool to a running dsh, you should write a bundle with dsh.bundle, or directly refer to the official plugin publishing documentation.

Pay attention to these things before use:
1. Version locking and preview stage. The tutorial is written based on 0.1.0-rc.6, and the demo dependencies have been pinned, you can run through it by following along. DeepSeek Harness is still marked as developer preview, the architectural ideas are relatively stable, and the API details shall be subject to the latest version of the official documentation.
2. Permissions and licenses. Whether using dsh plugin add or npx dsh, the code runs with the permissions of the current process. You should read the repository source code and MIT license before installing or running.
3. Windows environment variables. The demo preparation page gives POSIX syntax; in PowerShell, use $env:DSH_HOME = "$PWD\.dsh-home", and adjust the path separators according to PowerShell.
4. Common runtime issues. When npx dsh cannot find the package, confirm that you have run npm install under demos/; headless is a one-time process, just re-run the command after modifying the plugin.
5. Community directory is not an official store. The plugin library is maintained by the community, and the收录 entries and GitHub star counts may be out of sync.

Summary¶

dsh-harness-tutorial breaks down DeepSeek Harness’s “everything is a plugin” into a actionable Chinese path: 8 chapters of principles, 6 chapters of source code comparison, 8 demos locked to 0.1.0-rc.6, plus a runnable educational version of mini-harness. The official documentation continues to be used for looking up interfaces, and this tutorial is used to build mechanism understanding and hands-on experience.

Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-harness-tutorial/

GitHub: https://github.com/yanhua1010/dsh-harness-tutorial

Online reading: https://yanhua1010.github.io/dsh-harness-tutorial/