Reading Guide and Research Map
How to navigate the completed study and its evidence indexes
Developer Preview source archaeology · pinned baseline
Not a feature list, but a verifiable map of system semantics
DeepSeek Harness looks like a coding-agent product. The more interesting subject is its attempt to decompose an Agent product into a network of composable, disposable, and replayable capabilities. This report starts from real entry points, mutations, failure branches, and persistence boundaries to explain how it actually runs.
Completion snapshot
All 36 chapters are verified at the pinned baseline. Chapter 35 indexes 1,094 evidence records across 533 distinct catalog paths and 48 curated terms. Chapters 00–34 contain 1,350 evidence occurrences spanning 1,092 unique catalog IDs: 99.8% catalog reach and 100.0% catalog-path reach. These are navigation metrics, not claims of architectural completeness or proof quality.
The website remains the navigable edition with an English default and a same-chapter Chinese switch. The repository also ships complete single-file Markdown editions: English and 简体中文.
What this dissection must answer
Runtime
How does the plugin tree start? Who drives Agents, turns, steps, model requests, and tool batches? At exactly which points are events appended?
Context
How do the system prompt, tool schemas, dynamic context, message history, Skills, and compaction summaries jointly determine what the model sees?
Durability
What does an internal session actually store? What do JSONL, SQLite, projection caches, checkpoints, forks, resume, and replay each guarantee?
Execution and governance
Which interception layers does a tool cross between schema and execution? How do parallelism, approval, monotonic guards, sandboxes, file observation, and timeouts compose?
Orchestration
How do multi-Agent providers, continuation, background jobs, workflow workers, and the Ralph loop share underlying primitives?
Tradeoffs
What does “everything is a plugin” actually solve, and what cognitive, configuration, validation, and compatibility costs does it create?
Start with three invariants
Model adapters, the tool registry, the session log, and the agent loop all mount as plugins on a shared Cordis context. The repository explicitly says there is no privileged core that extensions must patch. ARCH-PLUGIN-CORE
Anything that truly enters a model request must be reconstructable from the session log. The log therefore serves not only UI rendering, but also model context, recovery, forking, telemetry, and replay as a shared source of truth. ARCH-LOG
The effective “core” of DeepSeek Harness is not one immutable loop class. It is a set of harder-to-replace invariants: scope, event ordering, reversible registration, logging of model-visible input, and closure among capability definitions, providers, and consumers. Plugins are replaceable; these composition semantics are the de facto architectural constitution.
Suggested reading paths
- First pass: Design Philosophy → Turn/Step/Loop → Prompt Assembly → Session Events → Tool Pipeline.
- Agent-platform focus: Persistence → Checkpoints → Compaction → Plan/Goal/Todo → Multi-Agent → Workflow.
- Secure-execution focus: Tool Primitives → Permission and Approval → Sandbox/FS → Shell/Terminal/Jobs → Security Model.
- Engineering-quality focus: Observability and Replay → API/SDK/ACP → Tests and Invariants → Tradeoffs.
- Reverse lookup: Glossary and Evidence Catalog → evidence ID, package, path, documented symbol, durable event, live event, or host service.
How to interpret chapter status
| Status | Meaning | Safe to cite as a conclusion? |
|---|---|---|
| Queued | The scope is mapped, but the body may still be only a question list. | No |
| In progress | Some source facts and deductions exist, but the coverage audit is incomplete. | Only local facts with pinned evidence |
| Verified | Entry points, control flow, state, failures, persistence, and key tests have passed targeted or exhaustive review. | Yes, with the pinned baseline attached |
My Learning Notes
Autosaved only in this browser. Nothing is uploaded or committed. Export Markdown whenever you want to keep a copy.