DeepSeek Harness
DeepSeek Harness Source Code: Architecture and Execution Flow
Trace DeepSeek Harness from profile composition to a model step, using the repository architecture guide and package maps as a reading plan.
What you will learn
- Read apps, packages, docs, and examples as separate architectural layers.
- Profile layers compose into a Cordis entry tree before the app activates services.
- Steps, turns, and event domains provide the vocabulary for tracing execution.
Before you start
- Basic HTTP and API knowledge
Leave with a concrete implementation checklist and a testable starting point.
Key takeaways
- Read apps, packages, docs, and examples as separate architectural layers.
- Profile layers compose into a Cordis entry tree before the app activates services.
- Steps, turns, and event domains provide the vocabulary for tracing execution.
Read the repository in layers
Start with `apps` for runnable surfaces, `packages` for reusable services, `docs` for contracts, and `examples` for compositions. The package map distinguishes the core API spine, LLM adapters, tools, sessions, host, client, bundles, and SDK layers.
This directory map is more useful than opening files at random: it tells you which package owns a capability and which package merely consumes its service definition. Keep the official architecture guide open while tracing imports.
Boot and composition flow
At boot, a profile contributes ordered bundles, then profile and home patch files, followed by any command-line overlay. The app-boot package composes those layers over an empty entry list, mounts the Cordis include tree, and audits that enabled entries loaded and activated.
The `dsh --profile web --dump-config` command is a practical inspection point because it shows the tree your machine will actually boot. A patch replaces a matched row's whole config, so an override must restate fields it keeps.
Turn, step, and extension points
The architecture guide distinguishes a step from a turn: a step is one model request plus its tool calls; a turn spans the input claim until no work remains. Session events are durable facts, agent events describe live work, and capability events attach policies and adapters without importing the loop.
For a source-reading exercise, trace one event from producer to consumer, then identify the service definition, provider, and model-facing consumer. This gives you a testable extension path instead of a vague claim that the system is modular.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Trace this first | A service definition and its provider/consumer | A random implementation file without its composition |
| Use events when | The fact is durable or needs an extension point | A local helper has no lifecycle or observer contract |
Implementation steps
- 1
Begin with docs/architecture.md and packages/README.md.
- 2
Pick one capability such as tools or sessions and locate its service key.
- 3
Inspect the profile bundle order and dump the composed config.
- 4
Trace one event from producer to consumer and write a focused test or diagram.
Copy-ready example
# Inspect the composed tree before changing a package
dsh --profile web --dump-config
# Source build checkpoints
pnpm run typecheck
pnpm run buildFrequently asked questions
Where should I start source analysis?
Start with docs/architecture.md, then packages/README.md and the relevant subsystem README. The repository explicitly recommends understanding Cordis before changing packages.
What is the difference between a step and a turn?
A step is one model request plus its tools. A turn includes the lifecycle from claiming input through completing all owed work.
Sources
- DeepSeek Harness architectureSource checked 2026-08-27
- DeepSeek Harness packages mapSource checked 2026-08-27
- DeepSeek Harness app-boot packageSource checked 2026-08-27