@deepseek-ai/dsh-system-prompt

September 11, 2026 · View on GitHub

English | 中文

Summary

dsh-system-prompt lets agents receive one ordered system prompt and the available tool schemas for each model step. Use it to add prompt sections, dynamic runtime facts, reusable variables, or tool schemas, or to control the fixed harness identity, deployment persona, runtime context, and model-facing tool order. Agent-scoped contributions override same-named global defaults without affecting other agents. Invalid complete-prompt combinations and unresolved variables fail assembly instead of sending a malformed prompt.

Use this package
Understand the implementation
Further Exploration
Model Experience
Known Limitations and Deferred Work
Dev Note

Use this package

Mount dsh-system-prompt wherever agents run: it provides ctx.systemPrompt, the registry every prompt contribution lands in. Contributions are scoped — registering through agent.ctx affects that agent alone and shadows a same-named global.

Configure the prompt

The config owns the fixed opener, runtime context, deployment persona prefix and suffix, and tool order; everything else comes from registered contributions.

- name: '@deepseek-ai/dsh-system-prompt'
  config:
    includeHarnessIdentity: true
    includeRuntimeContext: true
    personaPrefix: 'You are the deployment assistant.'
    toolOrder: ['<unlisted-tools>']

Field	Default	Meaning
`includeHarnessIdentity`	`true`	Include the fixed `You are an AI agent powered by DeepSeek Harness.` first-party opener at order −1000. Set false only when a compatibility deployment owns the complete system prompt.
`includeRuntimeContext`	`true`	Include ordered dynamic runtime context in assembly
`personaPrefix`	`''`	Global persona prefix template at order `0`, before first-party guidance
`personaSuffix`	`''`	Global `deployment:persona-suffix` template at order `10200`, after first-party guidance
`toolOrder`	—	Explicit model-facing tool order with one `'<unlisted-tools>'` rest entry

The generated configuration catalog is the exhaustive source for every accepted field. A toolOrder list without exactly one rest entry or with duplicates fails at load; a listed name with no registered tool rejects every assemble().

Contribute a prompt section

Sections carry static or context-resolved text with an order; they are concatenated in ascending order and equal orders use code-unit name order. Repository-owned contributors resolve centrally allocated positions through ctx.systemPrompt.getSectionOrder(name); runtime-context contributors use getContextOrder(name). External contributions may use any finite order. A complete: true section becomes the exact complete prompt after assembly; more than one effective complete section makes assembly fail.

ctx.systemPrompt.section({
  name: 'tool:bash',
  order: 100,
  text: 'Prefer bash for file and process operations.',
})

Contribute a prompt variable

Variables are referenced from section text as {{name}} and resolved at each assembly; scoped variables shadow a same-named global for that agent. The loop supplies model and cwd; any plugin can register the facts it owns.

ctx.systemPrompt.variable('cwd', ({ agent }) => agent?.session.header.cwd)

Contribute tool schemas

Tool-schema providers are evaluated per assembly and contribute the model-visible ToolSchema set; ToolRuntime registers itself automatically, so most tools need no manual wiring here. A provider returns the post-restriction visible set plus the pre-restriction name universe used by toolOrder.

Suppress runtime context

suppressRuntimeContext() removes every dynamic runtime-context contribution for the calling scope without disabling the services that own the underlying facts; multiple suppressors compose and the effect restores context when none remains.

Understand the implementation

Implementation internals — click to expand

This section explains how the package realizes the behavior above; the observable contract is covered in Use this package.

Design concept

The package is a registry plus a cooperative assembly pipeline. One assemble() call merges the global layer with the requested scope's layer, detaches tool parameters, canonicalizes section order by number and then name, runs the scope-filtered system-prompt/assemble waterfall, restores an effective complete section as the sole prompt section, and applies any active runtime-context suppressor. Sections and dynamic contexts are separate inputs: sections become prompt text, while contexts become sourced user-role snapshots in model history under the loop. Tool schemas are part of the assembly by design — "what the model is told it can do" is one coherent thing, even though adapters transmit schemas as a separate wire field.

Source map

File	Role
`src/index.ts`	Plugin entry: `SystemPrompt` service, config, assembly pipeline, `renderPrompt`
`src/invariant.ts`	Invariant companion

Assembly and rendering

Assembly resolves and renders in two stages: assemble() returns sections with resolved-but-uninterpolated text, the ordered tool schemas, and every registered variable resolved against the context, while renderPrompt() interpolates {{variable}} references, drops empty sections, and joins with blank lines — strictly, an unknown reference, a registered-but-valueless reference, or a malformed complete group throws, because a malformed prompt is worse than a loud failure. toolOrder canonicalizes the collected tools before the waterfall (registration order is a plugin-load artifact); a waterfall listener that mutates the list owns the determinism of what it emits.

Scoping

Scoped sections, variables, and tool providers shadow globals for one agent, and the assembly waterfall dispatches scope-filtered. Registry-change notifications (system-prompt/change) are deliberately unfiltered because a global change affects every scope.

Further Exploration

The package-level contract is enough for most consumers; read these when you need the surrounding domain.

System-prompt subsystem — the exact cross-package types and generated service API.
tools package — the tool registry whose schemas flow into assembly.
Prompt variables Agent Note — who owns which prompt facts.
First-party prompt order Agent Note — the sparse named order allocation.
Core group map — how the core packages compose.

Model Experience

System prompt

What the model sees

First-party sections render the harness identity, deployment persona prefix (including the model-name introduction), reusable instructions (including the generated tools SDK and structured-output guidance), then the environment-bearing suffix: harness source (10000), Web surface (10100), and deployment persona suffix (10200). External section orders and assembly listeners remain authoritative. includeHarnessIdentity: false omits only that fixed opener. Empty sections disappear; scoped sections and variables can shadow globals for one agent. The system-prompt/assemble waterfall determines the delivered prompt and tool schemas unless one effective section declares itself complete — that exact section then becomes the whole system prompt while the waterfall's contexts, tools, and variables remain. The rendered prompt reaches the model as a system-role message of derived history — surface node 0, or the latest system node after an in-history update — neither the loop request nor request/header carries a separate system field. If the complete rendering is empty, the loop clears every active system node through logged empty replacements, so no older prompt remains in model history. Ordered dynamic contexts are separate from sections and become sourced user-role snapshots only when present; includeRuntimeContext: false or a scoped suppressor removes them all.

Harness identity

You are an AI agent powered by DeepSeek Harness.

Token effect

Identity is a fixed per-request cost when enabled. Persona prefixes, suffixes, and plugin text are repeated per request and scale with their rendered content.

KV Cache effect

Prefix-stable while identity, persona, variables, section text, and order render identically: an unchanged rendering leaves the system nodes untouched unless an incapable route or a new request series must consolidate retained in-history prompts. Without systemPromptUpdate, non-empty prompt text is consolidated at the first system node through logged per-node replacements, so a head rewrite loses prefix reuse from its first changed token; when the prepared call declares systemPromptUpdate: 'in-history', the agent loop appends a non-empty changed prompt after the cached history inside a continuing request series, so the prefix through that history stays reusable (decision rule). With the same model, persona prefix, tools, and preceding instructions, different source paths, local Web URLs, or persona suffix values leave the reusable first-party prefix unchanged. Persona prefix changes can alter the early prefix. Any change may invalidate reuse from the first changed token; provider cache sharing and measured hit rates are not guaranteed.

Tool schemas

What the model sees

For shipped tools, the model receives the per-agent-visible subset of the generated tool schemas, ordered by configuration or lexicographically after restrictions and assembly interception. Extensions can contribute additional definitions through the same registry. Sections and schema providers are separate assembly inputs. A restriction does not remove a section registration: tool-guidance plugins use text({ scope }) and ctx.tools.get(name, scope) to return empty text or select applicable fragments. Arbitrary static sections are not automatically rewritten.

Deployment-authored prompt text is config/composition only — this plugin owns the global persona prefix and suffix defaults, creator plugins may register agent-scoped shadows, and other sections come from the plugin that owns the fact; there is no end-user prompt-editing API.
No escape syntax for literal {{…}} braces — every complete group is interpolated against registered variables; an escape is deferred until a real prompt needs one.
toolOrder misconfiguration surfaces at prompt assembly (the first turn), not at boot — only shape violations throw at config load.

Dev Note

Working context for maintainers — click to expand

None.