dsh source notes
DeepSeek Harness · source deep dive

Everything is a Plugin
how that tagline is honoured across 215k lines of TypeScript

227 packages, ~50 package groups, 2,693 vendored lines of Cordis. 12 chapters, reordered into the sequence in which you actually come to understand an agent harness — every claim on a file:line.

Start with chapter 1 GitHub repo
baseline 0.1.1-rc.2 commit b150a551 12 chapters · 12 diagrams

A chapter-by-chapter source reading of DeepSeek Harness (dsh) — 227 packages, ~215k lines of TypeScript — reordered into the sequence in which a newcomer actually comes to understand an agent harness. Every claim lands on a file:line.

Read online: https://dragonchencl.github.io/dsh-notes/ (redeployed by GitHub Actions on every push to main)

Heads-up on language: the 12 chapters themselves are written in Chinese. This page is the English entry point — what the book covers, how it is organized, and where to start. Chapter titles below link to the Chinese text; code, symbol names, file:line references and the SVG diagrams are language-neutral and readable on their own.

Baseline version 0.1.1-rc.2 ｜ commit b150a551 ｜ 2026-08 dsh is in developer preview and upstream states there will be breaking changes. On a newer checkout line numbers may drift, but symbol names and structural conclusions should still hold.

What this book is about

dsh's tagline is "Everything is a Plugin". That is not marketing copy — even the agent loop that drives the whole product is itself a plugin:

// packages/core/agent-loop/src/index.ts:296
export class AgentLoop extends Service implements AgentFactory {
  static inject = ['agents', 'sessions', 'llm', 'tools', 'systemPrompt']

The session log, prompt assembly, the tool registry, model invocation — from the loop's point of view all of these are "services somebody else provides". Drop this package from the config and the product has no loop; swap in another package implementing the same interface and the product's loop has been replaced.

The question the book answers is: how is that tagline actually honoured across 200k+ lines of code, and which of those design decisions are worth stealing for your own project.

Table of contents

Part 1 · Foundations

Ch Title In one line
1 Overview: Everything is a Plugin What dsh is, how one turn flows, why the three event families must stay separate
2 The Cordis substrate: Context, Service, Fiber, Effect Four primitives in 2,693 vendored lines, and the exact semantics of five dispatch modes
3 Startup assembly: profiles, bundles and patch layers There is no default config file — only an empty array plus patch layers

Part 2 · The main line

Ch Title In one line
4 Agent and agent loop: turn, step, inbox The one piece of concrete loop logic in the whole harness, read line by line
5 Session log: append-only events and surface projection Why messages[] is only a derived view, and how replace coexists with append-only
6 Prompt assembly: sections, context, variables, tool schemas 30-odd anonymous contributors, a different result per agent
7 The tool system: registry and a five-stage pipeline Four waterfalls, a monotonic guard, out-of-order dispatch with in-order commit

Part 3 · Capabilities and governance

Ch Title In one line
8 Capability seams: the Definition / Provider / Consumer triangle 34 replaceable capabilities; two providers move the whole execution world remote
9 Sandbox and approvals: modes, approval, same-turn escalation A closed three-value vocabulary, fail-closed approval, the one retry that is honoured after a denial
10 Context compaction: measure, prune, summarize, spill Four reduction layers ordered cheapest-first; the summary call replays the prefix to keep the cache warm

Part 4 · Orchestration and the outside world

Ch Title In one line
11 Orchestration: subagents, workflows, background jobs, goals Four independent families; a competitor's agent can be just another provider
12 External interfaces and self-modification Five channels, four positionings; a DNS-rebinding fence; the model editing the runtime it is running on

All 12 chapters are complete.

How each chapter is written

The same four movements every time: what it is → how it works → why it was built this way → what you can take away.

  • Every code reference carries packages/.../file.ts:line so you can verify it against your own checkout;
  • Every chapter ships an SVG architecture or flow diagram under assets/;
  • Each chapter ends with a table of every source location it cited.

Suggested reading paths

Your goal Route
Understand how an agent actually runs 4 → 5 → 7
Write a plugin for dsh 2 → 3 → 8, then the chapter covering the extension point you need
Borrow the architecture for your own product 1 → 2 → 8 → 10 (the transferable methodology)
Read it all In order — vocabulary built early is reused throughout

Run it first

Strongly recommended before reading any source: several design decisions only click after you have edited one line of cordis.patch.yml yourself.

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

# The two most useful commands while reading the source
pnpm dsh --profile web --dump-config   # print the fully assembled plugin tree without starting
pnpm run doc-sync                      # regenerate the relationship graphs in the official docs

Relationship to the official docs

dsh's docs/ are good, and nearly every page ships a Chinese version (*.zh.md), plus 46 subsystem pages and several script-generated graphs (composition.md, capability-seams.md, event-producer-consumer.md, tool-execution-pipeline.md).

So these notes deliberately do not translate. They do the three things the official docs do not:

  1. Reorder — the official docs are organized by subsystem (good for lookup); this book is organized by learning path (good for reading);
  2. Go down to the implementation — the official docs state contracts; this book reads the key functions passage by passage, including the "why is this condition checked twice" details;
  3. Name the trade-offs — every design gets its cost stated, not just its benefit.

You will get the most out of it with docs/architecture.md and docs/glossary.md open beside you.

With thanks to the linux.do community for their support.

Disclaimer

  • This repository is third-party study notes, unaffiliated with DeepSeek and not representing any official position;
  • dsh is distributed under its own license — the upstream repository is authoritative; this repository contains only note text, diagrams and short quoted snippets;
  • Found a factual error? Issues and PRs welcome — please include the file:line.

License

Note text and diagrams are licensed under CC BY 4.0; quoted dsh source snippets remain the copyright of their authors.