deepseek-harness/docs/core-data-structures/system-prompt.md

System Prompt Assembly

English | 中文

The system-prompt package owns the data exchanged between prompt contributors and one assembly call. The package README documents registration, ordering, scoping, and rendering behavior; this page pins the literal cross-package shapes that plugins implement or pass.

Source: packages/core/system-prompt/src/index.ts.

Assembly context

AssembleContext identifies the scope layer one assembly resolves and may carry the explicit control signal for that request. It is merge-extensible: dsh-agent adds the optional live agent field and modelRequest?: true marker. assembleContextFor(agent, signal) builds an agent-scoped inspection context; assembleRequestContextFor(agent, signal) marks a result that the caller will materialize into the next model request. A bare assembly has neither scope nor signal.

/** Merge-extensible context for one prompt assembly. */
interface AssembleContext {
  /**
   * Scope whose providers and waterfall listeners participate. When absent,
   * only global providers and subject-less listeners participate.
   */
  scope?: ScopeKey
  /** Explicit control signal for the turn that requested this assembly, when any. */
  signal?: AbortSignal
}

Tool-provider result

ToolProviderResult.schemas is the model-visible set for the current assembly. knownNames is the provider's pre-restriction name universe used to distinguish a configured-name typo from a known tool that is deliberately hidden in this scope.

/** Tool schemas visible in one assembly and their pre-restriction name set. */
interface ToolProviderResult {
  /** The schemas this provider contributes to THIS assembly. */
  readonly schemas: readonly ToolSchema[]
  /** The pre-restriction name universe for config validation (defaults to `schemas`' names). */
  readonly knownNames?: readonly string[]
}

Prompt sections

PromptSection is a readonly same-process registration contract. Its text may be static or resolved from the current assembly context.

/** One contributed section of the system prompt (registry input). */
interface PromptSection {
  /** Unique name — a duplicate registration throws (see {@link SystemPrompt.section}). */
  readonly name: string
  /**
   * Sections are concatenated in ascending order. Convention: `-100` is the
   * harness identity, `0` the deployment persona, tool guidance uses 100–199;
   * other negative orders also render before the persona.
   */
  readonly order: number
  /**
   * Static text or a provider evaluated at each assembly with that assembly's
   * {@link AssembleContext}. The text may reference `{{variable}}`s — they are
   * interpolated later, by {@link renderPrompt}.
   */
  readonly text: string | ((context: AssembleContext) => string)
}

Dynamic prompt context

PromptContext is the cache-safe counterpart to PromptSection. The assembly resolves and orders these contributions, while agent-loop logs their complete current snapshot after retained model history only when it changed or compaction removed it.

/**
 * One dynamic model-context contribution. Unlike a {@link PromptSection}, its
 * rendered text is materialized as a durable user-role snapshot at the request
 * tail, so changing runtime state preserves the stable system/history prefix.
 */
interface PromptContext {
  /** Unique name — a duplicate registration throws (see {@link SystemPrompt.context}). */
  readonly name: string
  /** Contexts are joined in ascending order, independently of system-section order. */
  readonly order: number
  /** Static text or a provider evaluated for each assembly. Empty text contributes nothing. */
  readonly text: string | ((context: AssembleContext) => string)
}