Preface¶

DeepSeek Harness (referred to as DSH for short) is an agent runtime framework open-sourced by DeepSeek AI. Its core philosophy is “Everything is a Plugin”: model adapters, sessions, tools, approval workflows, persistence layers, and web UIs are all combined through a Cordis plugin tree. The official repository is currently in developer preview, and the documentation explicitly warns of breaking changes. When conducting long-term secondary development under this development rhythm, the common pain point is not the lack of source code access, but the overwhelming context: product boundaries, module ownership, extension points, and quality constraints are scattered across upstream docs/, generated directories, and source code comments. Feeding the entire repository into Codex or Claude Code risks misinterpretation, as well as treating documented declarations as already implemented behaviors.

dsh-specs was created to solve this exact problem. It does not provide new runtime tools, but instead organizes the product, architecture, runtime workflows, extension points, and quality constraints from a fixed upstream commit into a specification library optimized for on-demand reading by intelligent coding tools. Below is an explanation of what it is, which documents it covers, how to install it, and the evidentiary boundaries that must be upheld before implementation, cross-checked against the community catalog page, repository README, AGENTS.md, source lock file, and the upstream official repository.

What is This?¶

The repository title of dsh-specs is “DSH Intelligent Development Specification Library”, maintained by showjiangnan under the MIT license (the copyright notice retains the upstream DeepSeek attribution). The community plugin catalog categorizes it under “Tools and Capabilities”. The current GitHub repository star count is 8 (the catalog page still shows 6, refer to the repository page for the accurate number). The version number in package.json is 0.1.0.

It serves two types of work:
- Long-term secondary development based on DSH
- Developing new plugins, capability providers, and integration services for DSH

The repository clearly defines its scope: it does not contain DSH product source code, and cannot be used to build or run DSH independently. The documentation is a specification snapshot extracted and verified from a fixed commit in the upstream source repository. Before starting implementation, coding tools must still cross-check code, tests, and configurations in the matching source code checkout.

The current source baseline is recorded in source-lock.json and Source and Synchronization:

Two key distinctions must be made: DeepSeek Harness itself is maintained by DeepSeek AI; deepseek-harness-plugin.com is an independent community plugin catalog with no official affiliation to DeepSeek or Magic Square, and it should not be treated as an official app store.

Core Features¶

Minimum Onboarding Path for Coding Tools¶

The repository defines a fixed reading order for “what to read first” to avoid overwhelming users with the full documentation set at once. It is recommended to place the specification library and the source code repository in the same workspace:

Workspace/
├── deepseek-harness/   # DSH source code
└── dsh-specs/          # This specification library

Then instruct the coding tool to read in the following order:
1. AGENTS.md: Reading, evidentiary, and maintenance rules for this repository
2. docs/开发/智能编码工具接管指南.zh.md: Scope of task control context
3. ARCHITECTURE.md: System-level quick entry point
4. docs/文档导航.zh.md: Navigate to product, frontend, backend, quality, or specific subsystems

Claude Code reads the same agent instructions via the root-level CLAUDE.md file (the content of this file is a pointer to AGENTS.md); tools that support AGENTS.md can establish context directly from the root directory.

The original first instruction provided to Codex or Claude Code in the repository is:

First read dsh-specs/AGENTS.md and dsh-specs/docs/开发/智能编码工具接管指南.zh.md.
The current task is: <task>.
Use dsh-specs as the navigation and constraint framework, with the current deepseek-harness source code and tests as the implementation facts;
Distinguish between verified facts, documented declarations, and inferences, and reference specific files and symbols.

Document Map by Domain¶

Document files use Chinese semantic names; files without the .zh suffix store English content, .zh.md stores Simplified Chinese, and a supporting .i18n.yaml file records the content hash when the two language versions were last confirmed to be consistent.

AGENTS.md also stipulates that each fact must belong to exactly one document; other pages should only retain summaries and links. Do not mix tutorials, reference directories, plans, and decision justifications on the same page.

Evidentiary Boundaries Between Specifications and Source Code¶

This is the most critical constraint of this repository, and it is also written into AGENTS.md and Source and Synchronization:
- The specification is fixed to the aforementioned public upstream commit, providing direction, terminology, ownership, and constraints, but does not replace the target checkout
- Source code, tests, configurations, generators, and full decision history still belong to the upstream repository; content not included in this repository is referenced using GitHub links fixed to that commit
- For the current baseline: source code and checked-in configurations define implemented behaviors, tests define executed cases, generated directories provide lists derived from source code, and the current state documentation explains how these facts combine
- If a different upstream commit is used for actual development, differences must be listed as pending validation items, and this repository’s documentation must not be treated as a higher factual source than the current code
- Builds, tests, type checks, generated freshness validation (whether generated results still match the source code), and runtime verification must be completed in the upstream source code checkout; the green documentation checks in this repository cannot replace these validations

Three Key Seams to Locate During Plugin Development¶

The onboarding guide frames capability seams as a complete connection of “abstract service, concrete implementation, and consuming code”. When adding a new plugin or capability provider, three roles should be identified first:
- Service Definition: Defines the capability interface
- Service Provider: Implements the capability
- Consumer: Uses the capability

Public service methods and events should be reused; do not directly import concrete providers, and do not modify the agent loop. For each plugin, the guide requires determining: the Cordis plugin entry point and validated configuration; the services and events it depends on or contributes; registration, deregistration, and failure behaviors; trust boundaries for model/tool JSON, files, processes, queues, and remote calls; whether model-visible data is recorded as session events; and package tests, runnable examples, keyless snapshots, and documentation used to validate post-combination behavior.

ARCHITECTURE.md summarizes the runtime as: the CLI superimposes bundles (installable configuration layers) based on profiles (named runtime combinations), and Cordis then loads these configurations into a plugin tree. New capabilities should typically hook into existing services or events.

Offline Validation for the Documentation Itself¶

The repository’s validator only uses Node.js standard libraries and does not require installing dependencies:

npm run docs:check
git diff --check

It checks Chinese semantic paths, Markdown local links and anchors, bilingual paired structures, paired hashes, and text endings. The corresponding script in package.json is node scripts/校验文档.mjs.

Installation and Activation¶

The installation command provided on the community catalog page, to be run in the DeepSeek Harness terminal:

dsh plugin add github:showjiangnan/dsh-specs

For reproducible installations, the catalog page notes that the commit hash can be pinned:

dsh plugin add github:showjiangnan/dsh-specs#commit

Replace #commit with the actual Git commit hash.

An important clarification: this repository is a documentation engineering project. The root directory contains AGENTS.md, ARCHITECTURE.md, docs/, source-lock.json, and validation scripts, but no common plugin.json manifest file. The README describes its usage as placing the specification library next to the source code for reading by tools like Codex and Claude Code, rather than adding a new tool set to a running DSH process. The catalog page still provides the dsh plugin add command above, but does not provide additional runtime capability descriptions. If the goal is specification navigation during secondary development, the approach closest to the repository’s original intent is to clone it into the workspace and have the coding tool start from AGENTS.md.

Typical Usage Examples¶

For the following types of tasks, the onboarding guide provides “primary context” and “source code evidence to check”. The specification library is only responsible for navigation; evidence still resides in deepseek-harness.

A reproducible onboarding workflow:
1. Check out the upstream source code matching the snapshot, or at minimum record the commit hash of the current checkout
2. Place dsh-specs in the same workspace
3. Send the first instruction from the previous section to the coding tool, replacing <task> with a specific goal, e.g. “Add a new tool plugin for DSH”
4. The tool follows the onboarding guide to access docs/开发/ and relevant subsystems, then cross-check symbols and tests in the source code
5. Implementation and validation are only carried out in deepseek-harness; at most run npm run docs:check in dsh-specs

The repository also warns: do not preload the entire generated directory. The entry documents clarify factual ownership; detailed reference materials should only be added to the context once the task has identified the relevant service, event, type, tool, or configuration field.

Applicable Scenarios and Cautions¶

Situations where dsh-specs is suitable for use are roughly:
- Conducting continuous secondary development on DSH source code, requiring a modularized specification entry point
- Writing plugins, capability providers, or integration services, needing to clarify the seams between Service Definition / Provider / Consumer
- Using coding tools like Codex or Claude Code, hoping they load minimal context on a per-task basis rather than scanning the entire repository

It is not appropriate to treat it as:
- A runnable DSH distribution or installation package that replaces source code checkouts
- A “latest documentation” that automatically updates with the upstream default branch
- A higher factual source than the current code

Several constraints written into the repository or catalog page must be followed:
1. Plugins run with the permissions of the current DSH process and may execute code during installation. Before installing, check the source code repository and license; for reproducible installations, pin the commit hash.
2. The snapshot will not automatically follow the upstream default branch. The upstream is still in developer preview, and the official README explicitly notes breaking compatibility changes. If the source code commit differs from 47f943859bef60e4160492346772ded9b24f765a, first record the differences as unknown items.
3. Generated pages must have the generator run in a matching upstream checkout before being synchronized to this repository; manual edits of generated content in dsh-specs are prohibited.
4. This repository does not install runtime dependencies, and does not claim to replace upstream builds, tests, type checks, generated freshness validation, or VitePress documentation gatekeeping.

Summary¶

dsh-specs compiles the DSH product, architecture, extension points, and quality constraints from a fixed upstream commit into a specification library optimized for on-demand reading by intelligent coding tools. It does not contain source code, and cannot run DSH on its own; its value lies in codifying rules for “which page to read first, which facts belong where, and where evidence resides in the source code”. For anyone conducting long-term secondary development on DSH or writing plugins, it can be placed in the same workspace as deepseek-harness, starting from AGENTS.md and the onboarding guide, then using the current source code and tests as the basis for implementation.

Catalog Page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-specs/

GitHub: https://github.com/showjiangnan/dsh-specs