82 lines
6.2 KiB
Markdown
82 lines
6.2 KiB
Markdown
# Cookbook: adding a workspace package
|
|
|
|
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,
|
|
# + the gated Model Experience table or short sentence
|
|
# + the gated "Known Limitations and Deferred Work" section
|
|
# (or a whitelist entry in scripts/verify-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`, `version: 0.0.1`, `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. End a package README with this canonical sequence:
|
|
|
|
````markdown
|
|
## Model Experience
|
|
|
|
| Context surface | What the model sees | Token effect |
|
|
|---|---|---|
|
|
| Request surface and condition | Short verbatim text, an exact data-dependent shape, or a link to the long literal below | Fixed, conditional, retained, replaced, capped, or zero-direct token effect |
|
|
|
|
### Verbatim model-visible text
|
|
|
|
#### Descriptive title matching the table row
|
|
|
|
```text
|
|
Long stable prompt or schema description, copied exactly from source.
|
|
```
|
|
|
|
## Known Limitations and Deferred Work
|
|
|
|
- **Consumer-visible gap** — exact boundary or deliberately deferred work.
|
|
````
|
|
|
|
Fill Model Experience from the implementation. Direct, multi-surface, conditional, capped, or lifetime effects use the table; name each request contribution and token-growth condition. Quote short stable model-visible source literals verbatim in inline code, using named placeholders such as `<mode>` only for interpolated values. Put a long stable prompt or schema description under the optional exact `### Verbatim model-visible text` heading: give each literal an H4 title and its own `text` fence, then link it from the table instead of putting long prose in a cell. Summarize only data-dependent payloads, provider-owned text, or schemas too large to reproduce, and identify their exact shape and renderer. Do not infer prompt visibility from tool-schema visibility because independently registered guidance can remain after a scoped tool restriction.
|
|
|
|
An audited package with no context effect or one simple consumer-owned path joins [`SENTENCE_MODEL_EXPERIENCE`](../../scripts/verify-package-readme-model-experience.ts) and replaces the table with one line beginning `None, as ` or `Indirectly, through `. Every package outside that allowlist must keep the exact table; the verifier also gates the optional verbatim appendix's heading, H4-plus-`text`-fence shape, and placement after the table. A package with genuinely no limitations joins the separate allowlist in [`verify-readme-limitations.ts`](../../scripts/verify-readme-limitations.ts) and ends after Model Experience. The [Model Experience RFC](../rfc/implemented/process/2026-07-12-package-model-experience-contract.md) records the rationale.
|
|
|
|
## 5. Verify
|
|
|
|
```sh
|
|
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](../testing.md).
|