14 KiB
系统提示词组装
English | 中文
system-prompt 包负责管理提示词贡献者与一次组装调用之间交换的数据。该包的 README 记录注册、排序、作用域与渲染行为；本页记录各插件实现或传递的确切跨包类型。
源码：packages/core/system-prompt/src/index.ts。
组装上下文
AssembleContext 标识一次组装所解析的作用域层，并可携带该请求的显式控制信号。它可合并扩展：dsh-agent 添加可选字段 agent，用于携带当前的 agent（智能体）实例；assembleContextFor(agent, 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
}
工具提供方结果
ToolProviderResult.schemas 是当前组装中对模型可见的工具 schema 集合。knownNames 是提供方在限制前的名称全集，用于区分「配置名拼写错误」与「已知工具在此作用域中被有意隐藏」。
/** 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[]
}
提示词段落
导出的 PERSONA_PREFIX_SECTION（deployment:persona-prefix）与 PERSONA_SUFFIX_SECTION（deployment:persona-suffix）为全局配置和带作用域贡献所共享的段落命名。它们对应的 PromptSectionOrderName 项为 DEPLOYMENT_PERSONA_PREFIX 与 DEPLOYMENT_PERSONA_SUFFIX；包 README规定其位置与模板配置。
PromptSection 是一份只读的同进程注册约定。其文本可以是静态的，也可以从当前组装上下文动态解析。各段先按 order 升序排列，再按名称的代码单元顺序排列；仓库贡献方通过 getSectionOrder() 解析服务持有的具名分配。Runtime-context 贡献方通过 getContextOrder() 解析独立分配。协作式组装完成后，一个有效的 complete 段会成为唯一的提示词段落。agent loop（智能体循环）用 renderPrompt 渲染组装后的各段，并把文本作为 system/message surface 节点提交——首个步骤作为 surface 第 0 号节点追加，之后在渲染文本变化时原地替换，或者当已准备调用声明 systemPromptUpdate: 'in-history' 时，在序列延续期间把非空更新追加到已缓存历史之后——因此提示词作为派生历史中的消息而不是请求字段到达模型（决策；决策规则）。
/** 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. Equal orders use code-unit
* name order.
*/
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}, unless `interpolate` is false.
*/
readonly text: string | ((context: AssembleContext) => string)
/** Whether to interpolate prompt variables. Defaults to true; false preserves literal text. */
readonly interpolate?: boolean
/**
* Treat this contribution as the complete system prompt. Assembly still
* runs the cooperative waterfall so tools, contexts, and variables can be
* resolved, then restores this exact section as the sole prompt section.
* More than one effective complete section makes assembly fail.
*/
readonly complete?: boolean
}
动态提示词上下文
PromptContext 是与 PromptSection 对应的缓存安全结构。组装会解析这些贡献并排序；agent loop（智能体循环）仅在完整当前快照发生变化或被压缩（compaction）移除时，才会将其记录在保留的模型历史之后。
/** Dynamic model context materialized as a durable user-role snapshot. */
interface PromptContext {
/** Unique name — a duplicate registration throws (see {@link SystemPrompt.context}). */
readonly name: string
/** Contexts are joined in ascending order. */
readonly order: number
/** Static text or a provider evaluated at assembly and admission refresh. Empty text contributes nothing. */
readonly text: string | ((context: AssembleContext) => string)
/** Whether to interpolate prompt variables. Defaults to true; false preserves literal text. */
readonly interpolate?: boolean
/** Keep this operational context when optional runtime context is disabled. */
readonly required?: boolean
}
required: true 在可选运行时上下文被抑制时保留操作所需的贡献。interpolate: false 原样保留文本，包括看起来像变量的目录名。AssembledContext 将已求值文本及其插值选择传给渲染过程。
/** One resolved dynamic context contribution. */
interface AssembledContext {
/** The contributing context's unique name. */
name: string
/** The resolved text before variable interpolation. */
text: string
/** Whether to interpolate prompt variables. Defaults to true; false preserves literal text. */
interpolate?: boolean
}
Cordis API
Generated from source by scripts/gen-cordis-catalog.ts (verified fresh by pnpm run verify-cordis-catalog in doc-sync; regenerate with pnpm run gen-cordis-catalog) — the language sides differ only in locale-specific paired document paths. Signature blocks use a ts cordis-catalog fence and keep the original source JSDoc; dispatch modes are defined in the primer, and the framework-inherited ctx API lives in cordis-api/inherited.md.
ctx.systemPrompt — SystemPrompt
Registry service for the prompt inputs assembled before each model step.
/**
* Register an ordered prompt section in the calling context's scope. A scoped
* section shadows a global section with the same name; duplicates within one
* layer and non-finite orders throw. Registration and disposal emit
* `system-prompt/change`.
* @param section - the section to register.
* @returns the exact Cordis effect disposer.
*/
section(section: PromptSection): () => void
/**
* Resolve the centrally owned placement of a repository prompt section.
* @param name - stable section placement name.
* @returns the section's numeric sort order.
*/
getSectionOrder(name: PromptSectionOrderName): number
/**
* Resolve the centrally owned placement of a repository runtime context.
* @param name - stable context placement name.
* @returns the context's numeric sort order.
*/
getContextOrder(name: PromptContextOrderName): number
/**
* Register ordered dynamic context in the calling context's scope. Scoped
* entries shadow global entries with the same name.
* @param context - the context contribution to register.
* @returns the exact Cordis effect disposer.
*/
context(context: PromptContext): () => void
/**
* Suppress optional dynamic runtime-context contributions in the calling
* context's scope without changing the services that own or enforce those
* facts. Multiple suppressors remain independently disposable.
* @returns the exact Cordis effect disposer.
*/
suppressRuntimeContext(): () => void
/**
* Register a tool-schema provider in the calling context's scope. Global and
* matching scoped providers both contribute; returning the reserved
* {@link TOOL_ORDER_REST} name makes assembly fail.
* @param provider - evaluated for each assembly with its context.
* @returns the exact Cordis effect disposer.
*/
tools(provider: (context: AssembleContext) => ToolProviderResult): () => void
/**
* Register a prompt variable in the calling context's scope. Scoped values
* shadow globals; invalid or duplicate names throw. A provider may return
* `undefined`, but rendering a section that references that value then fails.
* @param name - the `[a-z][a-z0-9_]*` reference name.
* @param provider - evaluated for each assembly.
* @returns the exact Cordis effect disposer.
*/
variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void
/**
* Refresh accepted registered runtime facts for request admission. Contexts
* added only by the assembly waterfall retain their accepted values. Current
* suppression removes optional contexts, and missing required registrations
* are restored in registry order. Sections, tools, and interpolation variables
* retain their accepted values during this refresh.
* @param assembly - accepted assembly for this scope and step.
* @param context - the same scope and current plugin-defined assembly fields.
* @returns the accepted assembly with current runtime-context provider text.
*/
refreshContext<T extends PromptPreparation>(assembly: T, context: AssembleContext = {}): T
/**
* Prepare variables and runtime facts before accepting a step. No tool
* conditions or prompt sections are evaluated in this phase.
* @param context - calling scope and request cancellation.
* @returns prepared inputs after the preparation waterfall.
*/
async prepare(context: AssembleContext = {}): Promise<PromptPreparation>
/**
* Assemble prompt sections and tool declarations after request preparation.
* The presentation waterfall cannot replace provider-owned tools.
* @param context - calling scope, route-bound agent, and resolved tools.
* @param preparation - accepted variables and runtime facts; prepared here when omitted.
* @returns the complete assembly with ordered tool declarations.
*/
async assemble(context: AssembleContext = {}, preparation?: PromptPreparation): Promise<PromptAssembly>
Source: packages/core/system-prompt/src/index.ts
system-prompt/* events
system-prompt/assemble — waterfall
Presentation waterfall over assembled sections, contexts, and variables. Scope-filtered dispatch (@deepseek-ai/dsh-scope): scoped listeners receive only that scope's assemblies. The returned text is authoritative; tool declarations remain provider-owned. A supplied signal controls only this explicit assembly request and must not be retained to control later turns. A registered complete section is restored after this waterfall, so listeners cannot add to or replace that scope's system prompt.
/**
* Presentation waterfall over assembled sections, contexts, and variables.
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
* receive only that scope's assemblies. The returned text is authoritative; tool declarations remain provider-owned.
* A supplied signal controls only this explicit assembly request and must not
* be retained to control later turns. A registered complete section is
* restored after this waterfall, so listeners cannot add to or replace
* that scope's system prompt.
* @param assembly - the mutable assembly built from registered providers.
* @param context - the caller's per-assembly context.
* @mode waterfall
*/
'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptPresentation, context: AssembleContext, next: () => Promise<PromptPresentation>): Promise<PromptPresentation>
Types: Scoped
Source: packages/core/system-prompt/src/index.ts
system-prompt/change — emit
Emitted when any prompt provider changes. This registry notification is unfiltered because a global change affects every scope.
/**
* Emitted when any prompt provider changes. This registry notification is
* unfiltered because a global change affects every scope.
* @mode emit
*/
'system-prompt/change'(): void
Source: packages/core/system-prompt/src/index.ts
system-prompt/prepare — waterfall
Prepare variables and runtime context before step admission.
/**
* Prepare variables and runtime context before step admission.
* @param preparation - registered variables and context contributions.
* @param context - calling scope and cancellation.
* @mode waterfall
*/
'system-prompt/prepare'(this: Scoped<SystemPrompt>, preparation: PromptPreparation, context: AssembleContext, next: () => Promise<PromptPreparation>): Promise<PromptPreparation>
Types: Scoped