DeepSeek Harness Cookbook: Add a New Package Step by Step
Adding a package is not “create another folder”; it is drawing a release and dependency boundary. The Cookbook splits the decision into whether to split, what to export, and where dependencies go (source). Reverse the order and you get “the package exists, but the profile cannot install it” or “it installs, but versions fight.”
DeepSeek Harness: When to split
The first criterion is “does this need its own release,” not “are there many files.” Any one of these justifies a package (source):
- Independent release cadence — the part needs its own version without the whole plugin.
- Independent dependency surface — it needs libraries the rest does not, and bundling them makes install heavy.
- Clear reuse boundary — several plugins share it and should not copy code.
If none holds, adding files to the existing package is cheaper. A package adds package.json, build config, version constraints, and another node in the profile graph.
Three bad reasons: many files, a prettier directory, or “we might reuse it later.” The first is organization, the other two are guesses.
Draw the dependency graph before splitting: who depends on whom, what the host provides, what the package brings. If you cannot draw it, the boundary is not clear enough.
DeepSeek Harness: Three package.json fields
Start with name, exports, and dsh. They decide what it is called, what it exposes, and what role it plays (source).
- name — stable, because profiles and graphs reference it; renaming later is expensive.
- exports — expose only what consumers need; do not export every internal file.
- dsh — declare the package role, such as a bundle patch location; without it, Harness may not know how to load the package.
exports is the easiest to over-widen. Exporting every subpath feels convenient and turns internals into a de facto public API; once someone imports them, you cannot change them freely.
Start with the root entry only. Add a subpath when a second consumer actually appears. A smaller export surface leaves more room to refactor.
The dsh field must match the package's job. A normal plugin, a bundle, and a client half declare different roles; a wrong value does not always error, but loading or mounting fails silently.
DeepSeek Harness: Keep exports minimal
Exports are a promise, not a convenience: every export is an interface you can no longer change casually. Three practices (source):
- Root exports public API only — types, registration functions, necessary constants.
- Internal modules stay unexported — relative imports inside the package should not appear in exports.
- Export the client half separately — use a clear
./cliententry, not a mixed root.
An over-wide surface produces “I changed one internal function and an external consumer broke.” The consumer is not at fault; the export made the internal a contract.
Design runtime and type exports together. Exporting only runtime values leaves TypeScript consumers unable to infer; exporting only types breaks runtime imports.
If a package has several entries, document each purpose and stability level. An undocumented entry is effectively internal.
DeepSeek Harness: Dependency placement
Wrong placement usually appears at runtime as two versions, not as a build error. Three categories (source):
| Dependency | Place | Test |
|---|---|---|
| Host-provided core package | peerDependencies | Must match the host; never bundle a copy |
| Runtime library | dependencies | The host does not provide it |
| Build, test, types | devDependencies | Development only |
Putting a core package in dependencies is the classic mistake. The plugin carries a second copy that conflicts with the host; the symptom can be “the service registered but cannot be found,” or “types compile, runtime does not.”
The reverse — putting a runtime library in devDependencies — works locally and fails after install. Ask whether the import runs on the user's machine. If yes, it cannot be dev-only.
Write a version range for peer dependencies. Too wide can install an incompatible host; too narrow blocks reasonable upgrades. Match the range the host actually supports.
DeepSeek Harness: Packages and bundles
A package is a code unit; a bundle is a loading unit. The Cookbook describes a bundle as the distribution format for Cordis config and mount code, with dsh.bundle pointing at a patch file (source).
This means:
- A new package does not require a new bundle — one bundle can mount several packages.
- The bundle decides what gets installed — profiles pull capabilities through bundles.
- The package decides how code is reused — boundaries and dependencies live there.
Mixing them produces “the package exists, but the profile never loads it.” Add it to a bundle patch or the profile dependency graph.
If you are adding one capability to an existing bundle, prefer adding it inside the current package rather than creating a package and a bundle. Each layer adds install and debugging steps.
DeepSeek Harness: Verify from import to install
Cover import, install, and registration. Four steps (source):
- Import — a test or example imports from the export surface; runtime and types resolve.
- Build — the package builds and every path in
exportsexists. - Install — the target profile or bundle contains it and
pnpm installreports no conflict. - Register — startup shows the service, tool, or settings the package contributes.
Passing only the first means “reusable code, not in the runtime”; passing the first three means “installed but not mounted.” All four complete the package.
The existing develop-workspace-package covers the directory and validation, and develop-plugin-bundle covers bundle structure; this article covers the split criteria, exports, and dependency placement. Ask “what breaks if I do not split” before adding a package; “more files” is not enough.
A package is a long-lived promise about releases and dependencies, so split for a reason you can name.
FAQ
Add a DeepSeek Harness package when the code needs its own release cadence, dependency surface, or reuse boundary. Splitting too early adds install and version cost; too late makes one package own several jobs.
exports defines which entry points consumers may import, while dsh declares the package's role in DeepSeek Harness, such as a bundle patch file. They are different jobs.
In DeepSeek Harness, put host-provided packages in peerDependencies to avoid duplicates and version conflicts; put libraries the plugin needs at runtime in dependencies; put build and test tools in devDependencies.
In DeepSeek Harness, check three things: the entry imports, the profile or bundle dependency graph contains it, and the runtime capability is registered. A successful pnpm install does not prove the profile loaded it.
Related Terms
- package boundary
- A package boundary is a DeepSeek Harness release and dependency unit; one package should have a single job, stable exports, and a clear dependency range.— DeepSeek Harness reference - Adding a package
- exports
- exports is the package.json field that declares which files and subpaths consumers may import from a DeepSeek Harness package.— DeepSeek Harness reference - Adding a package
- dsh field
- The dsh field declares a package's role in DeepSeek Harness, for example the patch file of a bundle.— DeepSeek Harness reference - Config catalog
- peerDependencies
- peerDependencies declares packages that the host must provide, preventing duplicate copies of a DeepSeek Harness core package.— DeepSeek Harness reference - Adding a package
Sources
- DeepSeek Harness reference - Adding a package· deepseek-harness
- DeepSeek Harness reference - Config catalog· deepseek-harness