deepseek-harness/docs/cookbook/adding-a-package.md

Cookbook: adding a workspace package

English | 中文

The file-by-file checklist for a new @deepseek-ai/dsh-<name> package. (Verified by the bash and adapter packages; if it drifts, fix it here.)

1. Create the package

packages/<group>/<pkg>/
  package.json     # copy from packages/core/tools, adjust name/description/deps
  tsconfig.json    # extends ../../../tsconfig.base.json, rootDir src,
                   # outDir lib/types, references: ../../../vendor/cosmokit,
                   # ../../../vendor/cordis (+ ../../../vendor/schemastery if
                   # you use Config, + ../../<group>/<dep> for each dsh dep)
  src/index.ts     # service default export or plugin (name/inject/apply/Config)
  tests/<x>.spec.ts
  README.md        # service API, events, extension points, design notes,
                   # + gated Model Experience context blocks or short sentence
                   # + the gated "Known Limitations and Deferred Work" section
                   # (or a whitelist entry in scripts/verify-package-readme-limitations.ts)

Choose an existing group when one matches the package's role (core, llm, bash, compact, subagent, todo, session-persistence, ui, util, or support). A new group is allowed, but it is a pure container: no package.json, no source files, and packages still sit exactly one level below it.

package.json invariants (enforced by pnpm run constraints / scripts/check-workspace-constraints.ts): private: true, a version matching the root package.json, type: module, main: "lib/index.js", types: "lib/types/index.d.ts", exports["."].types: "./lib/types/index.d.ts", exports["."].default: "./lib/index.js", cordis in BOTH peerDependencies and devDependencies (same range). Mirror every dsh peer dependency in devDependencies. schemastery goes in dependencies (it is a runtime validator), matching agent-loop. The files list is precise: lib/index.js, lib/types/**/*.d.ts, lib/types/**/*.d.ts.map, and src; do not publish lib/types JS or JS-map intermediates or stale root declaration files. CLI app packages with a package bin include lib/bin.js immediately after lib/index.js in files.

In-package relative imports use explicit .ts specifiers in source (for example, export * from './types.ts'). The compiler rewrites those to .js in emitted JS and leaves explicit .ts specifiers in declarations, which standard NodeNext/Node16 TypeScript consumers resolve to the sibling .d.ts files.

2. Register it in the root configs

File	Change
tsconfig.base.json	no edit for an existing group; for a new group, add a ./packages/<group>/*/src candidate to the @deepseek-ai/dsh-* wildcard
tsconfig.json	add { "path": "./packages/<group>/<pkg>" } to references
tsconfig.build.json	add { "path": "./packages/<group>/<pkg>" } to references
knip.json	only if the package has non-*.spec.ts entries (e.g. *.e2e.ts → add a per-workspace override like packages/llm/llm-deepseek)

Covered automatically by globs or package-manifest discovery — no edits needed: root package.json workspaces, scripts/publint-all.ts, tsdown.config.ts, vitest.config.ts, eslint.config.mjs, scripts/check-workspace-constraints.ts.

3. Decide the package topology

For a swappable capability, split interface / implementation / consumer into separate packages (see docs/architecture.md § "Capability seams" — the bash trio is the template). A single-purpose plugin stays one package.

4. Write the package README

Keep package-specific service API, config, events, extension points, and design notes first. The limitations section records durable consumer gaps and non-obvious maintainer constraints owned by this package; ordinary cleanup stays in its source TODO or RFC. An indirect Model Experience sentence may name the consumer that surfaces this package's contribution, but it does not restate that consumer's implementation. End a package README with this canonical sequence:

## Model Experience

### Request surface and condition

**What the model sees**: An exact data-dependent shape, an anchored generated-catalog link, or an introduction to the verbatim literal below.

**Token effect**: Fixed, conditional, retained, replaced, capped, or zero-direct token effect.

#### Verbatim text for this context surface, when needed

```markdown
Stable system-prompt prose of any length, or another long non-generated literal, copied exactly from source.
```

## Known Limitations and Deferred Work

- **Consumer-visible gap** — exact boundary, consequence, or maintainer constraint.

Fill Model Experience from the implementation. Use one H3 per direct, conditional, capped, lifetime, or auxiliary-model surface, with the two fields shown above. Quote stable text owned by the package: system-prompt prose goes in a titled H4 plus markdown fence, other short literals stay inline with named placeholders, and other long literals use the same nested form. Summarize only data-dependent or provider-owned text. A tool-schema surface links its anchored section in the generated tool catalog and states only deltas absent there. Keep prompt and schema surfaces separate when scoping can hide one without the other. The prose standard governs completeness and ownership; the verifier enforces the mechanical shape.

A package with no context effect or one consumer-owned path uses the audited None, as or Indirectly, through sentence in SENTENCE_MODEL_EXPERIENCE; a model-agnostic generic package may instead join NO_MODEL_EXPERIENCE_SECTION. Do not expand either case into a description of another package's work. The limitations allowlist is independent. The Model Experience RFC records the rationale.

5. Verify

pnpm install        # registers the workspace
pnpm run doc-sync
pnpm run constraints && pnpm run typecheck && pnpm run lint
pnpm run test:coverage  # 100% per-file over src (types.ts exempt)
pnpm run build && pnpm run hygiene

Test expectations: every registry/registration needs an HMR-safety test (register from a child fiber, dispose it, assert cleanup). Excessive tests are welcome — see docs/testing.md.