@qlzt/dsh-system-prompt 0.0.0-stage → 0.2.1-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,88 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/core/system-prompt/README.md
+/:
+  en: 51d99b2500db958f
+  zh: 91f2b113ba7989fd
+/deepseek-ai-dsh-system-prompt:
+  en: e1cfb1611662e8ab
+  zh: 5476f22f8ffe923a
+/deepseek-ai-dsh-system-prompt/summary:
+  en: f5cce6867daddbab
+  zh: 4a1a47623c198207
+/deepseek-ai-dsh-system-prompt/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-system-prompt/use-this-package:
+  en: 7bea567207cd7e00
+  zh: ffc050b05f07ba7f
+/deepseek-ai-dsh-system-prompt/use-this-package/configure-the-prompt:
+  en: 87e28893e6cf58d7
+  zh: 06f476b38c4d2038
+/deepseek-ai-dsh-system-prompt/use-this-package/contribute-a-prompt-section:
+  en: 165fecb5329b00b6
+  zh: a7c595d1787916c9
+/deepseek-ai-dsh-system-prompt/use-this-package/contribute-a-prompt-variable:
+  en: b3e4c9b4ced59488
+  zh: d80c791e72bd5821
+/deepseek-ai-dsh-system-prompt/use-this-package/contribute-tool-schemas:
+  en: 009ef267dac2f270
+  zh: e79c24bff5cd836f
+/deepseek-ai-dsh-system-prompt/use-this-package/suppress-runtime-context:
+  en: a664608a3b37f8d7
+  zh: d6dd60772f4d72b8
+/deepseek-ai-dsh-system-prompt/understand-the-implementation:
+  en: ce7e776e9d516bdb
+  zh: 59d2751743db7795
+/deepseek-ai-dsh-system-prompt/understand-the-implementation/design-concept:
+  en: c91963b89a866fed
+  zh: ef9ef4940145778f
+/deepseek-ai-dsh-system-prompt/understand-the-implementation/source-map:
+  en: d9575bcb07a1145b
+  zh: 0f1a388780d055b1
+/deepseek-ai-dsh-system-prompt/understand-the-implementation/assembly-and-rendering:
+  en: 54977e6c431f851e
+  zh: ef60007054b97ff0
+/deepseek-ai-dsh-system-prompt/understand-the-implementation/scoping:
+  en: 1100ab1dfe961631
+  zh: c510275c893951b4
+/deepseek-ai-dsh-system-prompt/further-exploration:
+  en: 108d1b4cca466bc7
+  zh: e1275966f83c14f9
+/deepseek-ai-dsh-system-prompt/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-system-prompt/model-experience/system-prompt:
+  en: cf78b9dd5596495f
+  zh: bd44560f8c2435e8
+/deepseek-ai-dsh-system-prompt/model-experience/system-prompt/what-the-model-sees:
+  en: 0aaabee3a9883eea
+  zh: 13e6ead5b455fa30
+/deepseek-ai-dsh-system-prompt/model-experience/system-prompt/what-the-model-sees/harness-identity:
+  en: 40effd71cb503319
+  zh: 9969356237a4f398
+/deepseek-ai-dsh-system-prompt/model-experience/system-prompt/token-effect:
+  en: 29722e212137deaa
+  zh: 92cd0f1a16b10315
+/deepseek-ai-dsh-system-prompt/model-experience/system-prompt/kv-cache-effect:
+  en: ae980c28b57dc060
+  zh: 331eea5b204fa9ac
+/deepseek-ai-dsh-system-prompt/model-experience/tool-schemas:
+  en: 3039bc5e7a796b21
+  zh: 6b7a9eaf69c9ea53
+/deepseek-ai-dsh-system-prompt/model-experience/tool-schemas/what-the-model-sees:
+  en: a983ef220593cf73
+  zh: 28770612ffc1be60
+/deepseek-ai-dsh-system-prompt/model-experience/tool-schemas/token-effect:
+  en: f3a7d374c55e1720
+  zh: 0ee48af678cb875f
+/deepseek-ai-dsh-system-prompt/model-experience/tool-schemas/kv-cache-effect:
+  en: ebd329e360f0d143
+  zh: 9d67fe503a6a095a
+/deepseek-ai-dsh-system-prompt/known-limitations-and-deferred-work:
+  en: 23bb9f59ceb1620c
+  zh: be34f1770fa2e027
+/deepseek-ai-dsh-system-prompt/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,190 @@
-# Temporary Holding Version
+---
+description: "System-prompt assembly for users and maintainers adding prompt sections, variables, tool-schema sources, or configuring the model-facing prompt."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @deepseek-ai/dsh-system-prompt
+
+English | [中文](README.zh.md)
+
+## 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.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 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.
+
+<a id="configure-the-prompt"></a>
+### 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.
+
+```yaml
+- 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 optional 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](../../../docs/config-catalog.md#deepseek-aidsh-system-prompt) 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.
+
+```text
+ctx.systemPrompt.section({
+  name: 'tool:bash',
+  order: 100,
+  text: 'Prefer bash for file and process operations.',
+})
+```
+
+Set `interpolate: false` on a section or dynamic context to preserve its text literally, including `{{…}}` groups in generated tool documentation or directory names. Other contributions interpolate variables by default.
+
+`refreshContext(assembly, context)` refreshes registered runtime facts after pre-step and route preparation. It preserves accepted sections, tools, variables, and contexts contributed only by the assembly waterfall, applies current optional-context suppression, and restores missing required entries. Put changing facts in context providers; registered context text is read again before admission.
+
+### Contribute a prompt variable
+
+Variables are referenced from section or context text as `{{name}}` and resolved at each assembly; scoped variables shadow a same-named global for that agent. The loop supplies `provider` and `model`; plugins can register the facts they own. The working-directory service supplies directory text as literal user context.
+
+```text
+ctx.systemPrompt.variable('response_language', () => 'English')
+```
+
+Custom persona templates must not depend on a built-in `{{cwd}}` variable: the loop does not register it, so unresolved references fail prompt assembly before any model request. Remove the `Your working directory is {{cwd}}.` clause from home, profile, or invocation `personaSuffix` settings and preset `suffix` fields, preserving unrelated text. Omit or clear an otherwise empty suffix. The [working-directory service](../../session/working-directory/README.md) supplies the required current-directory context.
+
+### 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 optional dynamic context for the calling scope without disabling the owning services. Contributions marked `required` remain visible. Multiple suppressors compose; optional context returns when none remains.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains how the package realizes the behavior above; the observable contract is covered in [Use this package](#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`](src/index.ts) | Plugin entry: `SystemPrompt` service, config, assembly pipeline, `renderPrompt` |
+
+### 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 unless a section sets `interpolate: false`, 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.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+The package-level contract is enough for most consumers; read these when you need the surrounding domain.
+
+- [System-prompt subsystem](../../../docs/subsystems/system-prompt.md) — the exact cross-package types and generated service API.
+- [tools package](../tools/README.md) — the tool registry whose schemas flow into assembly.
+- [Prompt variables Agent Note](../../../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md) — who owns which prompt facts.
+- [First-party prompt order Agent Note](../../../.agents/notes/archived/architecture/2026-08-25-sparse-first-party-prompt-section-orders.md) — the sparse named order allocation.
+- [Core group map](../README.md) — how the core packages compose.
+
+-----
+
+<a id="model-experience"></a>
+## 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 optional contributions while required operational context remains.
+
+##### Harness identity
+
+```markdown
+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](../agent-loop/README.md#understand-the-implementation)). 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](../../../docs/tool-catalog.md#deepseek-aidsh-tools), 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.
+
+#### Token effect
+
+Schema tokens repeat on every request. Restricting a tool removes its entire schema cost for that agent but not a separate prompt section; reordering changes cache shape but not semantic content.
+
+#### KV Cache effect
+
+Prefix-stable while the visible schema set, rendering, and order are unchanged. Registration, restriction, or reordering may invalidate reuse from the first changed schema token.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when prompt assembly needs special care. They are current package constraints, not a task backlog.
+
+- **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 inline escape syntax in interpolated text** — use `interpolate: false` when a whole section must preserve literal braces.
+- **`toolOrder` misconfiguration surfaces at prompt assembly (the first turn), not at boot** — only shape violations throw at config load.
+
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,190 @@
+---
+description: "面向用户与维护者的系统提示词组装说明，用于添加提示词段、变量、工具 schema 来源或配置面向模型的提示词。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-system-prompt
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-system-prompt` 让 agent 在每个模型步骤收到一份有序系统提示词与可用工具 schema。需要添加提示词段、动态运行时事实、可复用变量或工具 schema，或者控制固定 harness 身份、部署 persona、运行时上下文和面向模型的工具顺序时，请使用本包。agent 作用域的贡献会遮蔽同名全局默认值，而不影响其他 agent。无效的完整提示词组合与未解析变量会使组装失败，不会向模型发送格式错误的提示词。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在任何运行 agent 的地方挂载 `dsh-system-prompt`：它提供 `ctx.systemPrompt`，即每个提示词贡献所落入的注册表。贡献带作用域——通过 `agent.ctx` 注册只影响该 agent，并遮蔽同名全局项。
+
+<a id="configure-the-prompt"></a>
+### 配置提示词
+
+配置拥有固定开场白、runtime 上下文、部署 persona 前缀与后缀与工具顺序；其余一切来自已注册的贡献。
+
+```yaml
+- name: '@deepseek-ai/dsh-system-prompt'
+  config:
+    includeHarnessIdentity: true
+    includeRuntimeContext: true
+    personaPrefix: 'You are the deployment assistant.'
+    toolOrder: ['<unlisted-tools>']
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `includeHarnessIdentity` | `true` | 是否包含顺序为 −1000 的第一方固定开场白 `You are an AI agent powered by DeepSeek Harness.`。仅当兼容性部署拥有完整系统提示词时设为 false。 |
+| `includeRuntimeContext` | `true` | 是否在组装中包含可选的有序动态 runtime 上下文 |
+| `personaPrefix` | `''` | 全局 persona 前缀模板，顺序为 `0`，位于第一方指导之前 |
+| `personaSuffix` | `''` | 全局 `deployment:persona-suffix` 模板，顺序为 `10200`，位于第一方指导之后 |
+| `toolOrder` | — | 显式面向模型工具顺序，含一个 `'<unlisted-tools>'` 其余项标记 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-system-prompt)是每个受支持字段的穷尽式真源。没有恰好一个其余项或存在重复项的 `toolOrder` 列表会在加载时失败；已列名称没有对应已注册工具会使每次 `assemble()` 被拒绝。
+
+### 贡献提示词段
+
+段携带静态或按上下文解析的文本与 `order`；它们先按顺序值升序拼接，顺序值相同时再按名称的代码单元顺序排列。仓库自带贡献方通过 `ctx.systemPrompt.getSectionOrder(name)` 解析集中分配的位置；runtime-context 贡献方使用 `getContextOrder(name)`。外部贡献可以使用任意有限的顺序值。`complete: true` 段会在组装后成为精确的完整提示词；有效的 complete 段超过一个时，组装会失败。
+
+```text
+ctx.systemPrompt.section({
+  name: 'tool:bash',
+  order: 100,
+  text: 'Prefer bash for file and process operations.',
+})
+```
+
+在段或动态上下文上设置 `interpolate: false` 可原样保留文本，包括生成的工具文档或目录名中的 `{{…}}` 组。其他贡献默认执行变量插值。
+
+`refreshContext(assembly, context)` 在 pre-step 与路由准备之后刷新已注册的运行时事实。它保留已接纳的段、工具、变量及仅由组装 waterfall 添加的上下文，应用当前的可选上下文抑制，并恢复缺失的必需条目。将变化的事实放在上下文 provider 中；已注册上下文的文本会在准入前再次读取。
+
+### 贡献提示词变量
+
+变量从段或上下文文本中以 `{{name}}` 引用，每次组装时解析；带作用域的变量会为该 agent 遮蔽同名全局变量。循环提供 `provider` 和 `model`；插件可注册自己拥有的事实。工作目录服务通过不执行插值的用户上下文提供目录文本。
+
+```text
+ctx.systemPrompt.variable('response_language', () => 'English')
+```
+
+自定义 persona 模板不得依赖内置 `{{cwd}}` 变量：循环不注册它，因此无法解析的引用会在任何模型请求之前使提示词组装失败。请从 home、profile 或单次调用的 `personaSuffix` 设置以及 preset 的 `suffix` 字段中移除 `Your working directory is {{cwd}}.` 语句，保留无关文本。后缀没有其他内容时，可省略或清空该字段。[工作目录服务](../../session/working-directory/README.zh.md) 提供必需的当前目录上下文。
+
+### 贡献工具 schema
+
+工具 schema 提供方在每次组装时求值，并贡献模型可见的 `ToolSchema` 集合；`ToolRuntime` 会自动注册自身，因此大多数工具在此无需手动接线。提供方返回限制后的可见集合，外加 `toolOrder` 使用的限制前名称全集。
+
+### 抑制运行时上下文
+
+`suppressRuntimeContext()` 移除调用作用域的可选动态上下文，但不禁用拥有这些事实的服务。标记为 `required` 的贡献仍然可见。多个抑制器独立组合；不再存在抑制器时，可选上下文恢复。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释该包如何实现上述行为；可观察约定已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+该包是一个注册表加一条协作式组装流水线。一次 `assemble()` 调用把全局层与所请求作用域的层合并，分离工具参数，先按数值再按名称规范化段顺序，运行按作用域筛选的 `system-prompt/assemble` waterfall，把有效的 complete 段恢复为唯一的提示词段，并实施任何当前生效的运行时上下文抑制器。段与动态上下文是独立的输入：段成为提示词文本，而上下文在循环下成为模型历史中带来源的 user 角色快照。工具 schema 按设计属于组装结果——「模型获知自己能做什么」是一个连贯整体，尽管适配器把 schema 作为独立 wire 字段传输。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：`SystemPrompt` 服务、配置、组装流水线、`renderPrompt` |
+
+### 组装与渲染
+
+组装分两阶段完成求值与渲染：`assemble()` 返回文本已求值但尚未插值的段、有序工具 schema，以及每个已注册变量按当前上下文求得的值；`renderPrompt()` 对未设置 `interpolate: false` 的段插值 `{{variable}}` 引用、删除空段并用空行连接——严格规则：未知引用、已注册但无值的引用或格式错误的完整组都会抛出，因为格式错误的提示词比明确失败更糟。`toolOrder` 在 waterfall 分发前规范化收集到的工具（注册顺序只是插件加载产物）；修改列表的 waterfall 监听器对其输出的确定性负责。
+
+### 作用域
+
+带作用域的段、变量与工具提供方会为单个 agent 遮蔽全局项，组装 waterfall 按作用域筛选分发。注册表变更通知（`system-prompt/change`）刻意不经过筛选，因为全局变更影响每个作用域。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+包级约定对大多数消费方已经足够；需要周边领域时再阅读以下页面。
+
+- [系统提示词子系统](../../../docs/subsystems/system-prompt.zh.md)——确切的跨包类型与生成的服务 API。
+- [tools 包](../tools/README.zh.md)——其 schema 流入组装的工具注册表。
+- [提示词变量 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.zh.md)——哪些提示词事实归谁所有。
+- [第一方提示词顺序 Agent Note](../../../.agents/notes/archived/architecture/2026-08-25-sparse-first-party-prompt-section-orders.md)——稀疏具名顺序分配。
+- [core 分组地图](../README.zh.md)——core 各包如何组合。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 系统提示词
+
+#### 模型看到什么
+
+第一方段落依次渲染 harness 身份、部署 persona 前缀（含模型名称介绍）、可复用指令（包括生成的工具 SDK 和结构化输出指导），最后是携带环境信息的后缀：harness 源码（`10000`）、Web 表层（`10100`）和部署 persona 后缀（`10200`）。外部段落的顺序与组装监听器仍决定其最终结果。`includeHarnessIdentity: false` 仅省略这个固定开场白。空段会消失；带作用域的段与变量可以为一个 agent 遮蔽全局项。`system-prompt/assemble` waterfall 决定交付的提示词与工具 schema，除非一个有效段声明自身为 complete——此时该确切段会成为完整的系统提示词，而 waterfall 得到的上下文、工具与变量保持不变。渲染后的提示词作为派生历史中的 system 角色消息——surface 第 0 号节点，或历史内更新之后最新的系统节点——到达模型；循环请求与 `request/header` 均不含单独的 `system` 字段。完整渲染结果为空时，循环通过有日志记录的空内容替换清除所有生效的系统节点，模型历史不再保留任何旧提示词。有序动态上下文与段分离，只在存在时才会成为带来源的 user 角色快照；`includeRuntimeContext: false` 或带作用域的抑制器会移除可选贡献；必需的操作上下文仍然保留。
+
+##### harness 身份
+
+```markdown
+You are an AI agent powered by DeepSeek Harness.
+```
+
+#### Token 影响
+
+启用时，身份是每次请求的固定成本。Persona 前缀、后缀与插件文本在每次请求中重复，成本随渲染内容增长。
+
+#### KV Cache 影响
+
+只要身份、persona、变量、段文本与顺序的渲染完全相同，前缀就保持稳定：渲染未变时系统节点保持不动，除非不支持该能力的路由或新请求序列必须归并保留的历史内提示词。没有 `systemPromptUpdate` 时，非空提示词文本通过有日志记录的逐节点替换归并到首个系统节点，因此头节点重写会从首个变化的 token 起失去前缀复用；当已准备调用声明 `systemPromptUpdate: 'in-history'` 时，agent loop（智能体循环）会在同一请求序列延续期间把变化后的非空提示词追加到已缓存历史之后，因此直到该历史末尾的前缀仍可复用（[决策规则](../agent-loop/README.zh.md#understand-the-implementation)）。模型、persona 前缀、工具与前置指令一致时，不同源码路径、本地 Web URL 或 persona 后缀值不会改变可复用的第一方前缀。persona 前缀变化可能改变靠前的前缀。任何变更都可能从第一个变化的 token 起使复用失效；不保证提供方共享缓存或实际命中率。
+
+### 工具 schema
+
+#### 模型看到什么
+
+对于已交付工具，模型会收到[生成工具 schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tools)中对每个 agent 可见的子集；限制与组装拦截完成后，按配置或字典序排列。扩展可以通过同一注册表贡献其他定义。段与 schema 提供方是独立的组装输入。限制不会移除段落注册：工具指导插件通过 `text({ scope })` 与 `ctx.tools.get(name, scope)` 返回空文本或选择适用片段。任意静态段落不会被自动改写。
+
+#### Token 影响
+
+schema token 在每次请求中重复。限制工具会为该 agent 移除其全部 schema 成本，但不会移除独立提示词段；重排序会改变缓存形状，但不改变语义内容。
+
+#### KV Cache 影响
+
+只要可见 schema 集合、渲染与顺序不变，前缀就保持稳定。注册、限制或重排序可能从第一个变化的 schema token 起使复用失效。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明提示词组装何时需要特别留意。它们是当前包约束，不是待办事项清单。
+
+- **部署方编写的提示词文本只来自配置／组合**：此插件拥有全局 persona 前缀与后缀默认值；创建方插件可以注册 agent 作用域的遮蔽项；其他段来自拥有相应事实的插件。不存在终端用户提示词编辑 API。
+- **插值文本不支持行内转义语法**：整段需要保留字面花括号时，使用 `interpolate: false`。
+- **`toolOrder` 配置错误在提示词组装（首轮）时出现，而不是启动时**：只有形状违规会在配置加载时抛出。
+
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,406 @@
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { AnonymousEntries, NamedEntries, ScopedLayers, scopeTarget } from "@qlzt/dsh-scope";
+//#region lib/types/index.js
+/**
+* Registry for ordered system sections, dynamic context, tool schemas, and prompt variables.
+*
+* @module @qlzt/dsh-system-prompt
+*/
+const SECTION_ORDERS = {
+	HARNESS_IDENTITY: -1e3,
+	DEPLOYMENT_PERSONA_PREFIX: 0,
+	PLAN_POLICY: 500,
+	TEAM_POLICY: 600,
+	PTC_ONLY: 800,
+	FILE_REFERENCE: 900,
+	TOOL_BASH: 1e3,
+	TOOL_PWSH: 1010,
+	TOOL_READ: 1100,
+	TOOL_WRITE: 1200,
+	TOOL_EDIT: 1300,
+	TOOL_GLOB: 1400,
+	TOOL_GREP: 1500,
+	TOOL_JOBS: 1600,
+	TOOL_PTY: 1700,
+	TOOL_WEB_SEARCH: 2e3,
+	TOOL_WEB_FETCH: 2100,
+	TOOL_LSP: 2200,
+	TOOL_SESSION_QUERY: 2300,
+	TOOL_GOAL: 2400,
+	TOOL_WORKFLOW: 2600,
+	TOOL_RALPH: 2700,
+	TOOL_SUBAGENT: 2800,
+	TOOL_REPORT: 2900,
+	TOOL_COMPUTER_USE: 3e3,
+	MCP_SERVERS: 3100,
+	TOOLS_SDK: 5e3,
+	DELIVERABLE_FILE_REFERENCES: 9e3,
+	STRUCTURED_OUTPUT: 9900,
+	HARNESS_SOURCE: 1e4,
+	WEB_SURFACE: 10100,
+	DEPLOYMENT_PERSONA_SUFFIX: 10200
+};
+const CONTEXT_ORDERS = {
+	WORKING_DIRECTORY: 100,
+	SANDBOX_POLICY: 110,
+	APPROVAL_POLICY: 115,
+	SUBAGENT_DELEGATION: 120
+};
+/**
+* The deployment persona prefix's section name. Exported because a
+* composition can replace this slot — an agent preset shadows the
+* deployment's persona with its own — and both sides naming the same section
+* is what makes the replacement work rather than duplicate.
+*/
+const PERSONA_PREFIX_SECTION = "deployment:persona-prefix";
+/** Deployment persona suffix section name shared by global and scoped contributions. */
+const PERSONA_SUFFIX_SECTION = "deployment:persona-suffix";
+/** Valid variable names: how they are written between the braces. */
+const VARIABLE_NAME = /^[a-z][a-z0-9_]*$/;
+/** A complete `{{...}}` reference group at the scan position (validated after). */
+const GROUP_AT = /^\{\{([^{}]*)\}\}/;
+/** Reserved {@link Config.toolOrder} marker for unlisted tools. */
+const TOOL_ORDER_REST = "<unlisted-tools>";
+/**
+* Validate duplicate names and the required {@link TOOL_ORDER_REST} marker.
+* Registered names are checked later because plugins have not loaded yet.
+*/
+function validateToolOrder(toolOrder) {
+	if (toolOrder === void 0) return void 0;
+	const seen = /* @__PURE__ */ new Set();
+	for (const name of toolOrder) {
+		if (seen.has(name)) throw new Error(`toolOrder lists "${name}" more than once`);
+		seen.add(name);
+	}
+	if (!seen.has("<unlisted-tools>")) throw new Error(`toolOrder must contain the "${TOOL_ORDER_REST}" rest entry (where unlisted tools are inserted)`);
+	return toolOrder;
+}
+/**
+* Apply configured tool order, inserting unlisted tools lexicographically at
+* {@link TOOL_ORDER_REST}. Unknown configured names fail; known but restricted
+* names may be absent.
+*/
+function orderTools(tools, toolOrder, knownNames) {
+	if (tools.find((tool) => tool.name === "<unlisted-tools>") !== void 0) throw new Error(`tool provider returned reserved tool name "${TOOL_ORDER_REST}" (reserved for toolOrder's rest entry)`);
+	if (toolOrder === void 0) return tools.sort(compareToolNames);
+	const unknown = toolOrder.filter((name) => name !== "<unlisted-tools>" && !knownNames.has(name));
+	if (unknown.length > 0) throw new Error(`toolOrder lists unregistered tool${unknown.length > 1 ? "s" : ""} ${unknown.map((name) => `"${name}"`).join(", ")}; known tools: ${[...knownNames].sort().join(", ") || "(none)"}`);
+	const listed = new Set(toolOrder);
+	const rest = tools.filter((tool) => !listed.has(tool.name)).sort(compareToolNames);
+	return toolOrder.flatMap((name) => name === "<unlisted-tools>" ? rest : tools.filter((tool) => tool.name === name));
+}
+/** Code-unit name comparison — locale-independent, so the order is identical on every machine. */
+function compareNames(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Order prompt sections by their explicit placement, then deterministically by name. */
+function comparePromptSections(a, b) {
+	return a.order - b.order || compareNames(a.name, b.name);
+}
+/** Order tool schemas lexicographically by name. */
+function compareToolNames(a, b) {
+	return compareNames(a.name, b.name);
+}
+/**
+* Interpolate strict `{{variable}}` references, drop empty sections, and join
+* the rest with blank lines. Sections with `interpolate: false` retain literal
+* text. Malformed, unknown, or undefined references in other sections throw;
+* a lone `{{` without any later `}}` is literal prose, and substituted values
+* are not scanned again.
+* @param assembly - the assembly whose sections and variables to render.
+* @returns the rendered prompt, or `''` when all sections are empty.
+*/
+function renderPrompt(assembly) {
+	return assembly.sections.map((section) => section.interpolate === false ? section.text : interpolate(section, assembly.variables, "section")).filter((text) => text.length > 0).join("\n\n");
+}
+/**
+* Render the complete dynamic context snapshot, preserving literal contributions.
+* @param assembly - the assembly whose contexts and variables to render.
+* @returns the current full snapshot, or `''` when no context is active.
+*/
+function renderContextSnapshot(assembly) {
+	return joinContextSections(renderContextSections(assembly));
+}
+/**
+* The model-facing snapshot text for an already-rendered section list.
+*
+* A caller that also needs the sections renders them once and joins here, so a
+* request does not interpolate every context twice.
+* @param sections - sections from {@link renderContextSections}.
+* @returns the current full snapshot, or `''` when no context is active.
+*/
+function joinContextSections(sections) {
+	const body = sections.map((section) => section.text).join("\n\n");
+	if (body.length === 0) return "";
+	return `Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\n${body}`;
+}
+/**
+* The same snapshot, kept as the named contributions it was assembled from.
+*
+* {@link renderContextSnapshot} joins these for the model; a consumer that
+* presents the snapshot uses them to attribute each part to the subsystem that
+* contributed it, without re-splitting the joined prose. Contributions with
+* `interpolate: false` preserve literal text instead of resolving prompt variables.
+* @param assembly - the assembly whose contexts and variables to render.
+* @returns one entry per contributing context that rendered to non-empty text.
+*/
+function renderContextSections(assembly) {
+	return assembly.contexts.map((context) => ({
+		name: context.name,
+		text: context.interpolate === false ? context.text : interpolate(context, assembly.variables, "context")
+	})).filter((section) => section.text.length > 0);
+}
+/** Interpolate one section or context and attribute diagnostics to its owning input. */
+function interpolate(input, variables, kind) {
+	const text = input.text;
+	let result = "";
+	let last = 0;
+	for (let open = text.indexOf("{{"); open >= 0; open = text.indexOf("{{", last)) {
+		const group = GROUP_AT.exec(text.slice(open));
+		if (group === null) {
+			if (text.indexOf("}}", open + 2) >= 0) throw new Error(`malformed prompt variable reference at "${text.slice(open, open + 16)}…" in ${kind} "${input.name}" (references are complete simple {{name}} groups)`);
+			result += text.slice(last, open + 2);
+			last = open + 2;
+			continue;
+		}
+		const name = group[0].slice(2, -2);
+		if (!VARIABLE_NAME.test(name)) throw new Error(`malformed prompt variable reference "{{${name}}}" in ${kind} "${input.name}" (variable names match ${String(VARIABLE_NAME)})`);
+		if (!Object.hasOwn(variables, name)) {
+			const known = Object.keys(variables);
+			throw new Error(`unknown prompt variable "{{${name}}}" in ${kind} "${input.name}"; registered variables: ${known.length > 0 ? known.join(", ") : "(none)"}`);
+		}
+		const value = variables[name];
+		if (value === void 0) throw new Error(`prompt variable "{{${name}}}" has no value for this assembly (${kind} "${input.name}")`);
+		result += text.slice(last, open) + value;
+		last = open + group[0].length;
+	}
+	return result + text.slice(last);
+}
+/** Resolve one registered runtime fact without assembling sections or tools. */
+function resolveContext(entry, context) {
+	return {
+		name: entry.name,
+		text: typeof entry.text === "function" ? entry.text(context) : entry.text,
+		...entry.interpolate !== void 0 ? { interpolate: entry.interpolate } : {}
+	};
+}
+/** All prompt registrations owned by one global or scoped layer. */
+var PromptLayer = class {
+	sections;
+	contexts;
+	runtimeContextSuppressors = new AnonymousEntries();
+	toolProviders = new AnonymousEntries();
+	variables;
+	/**
+	* Create one prompt layer with diagnostics specific to its ownership scope.
+	* @param scope - the scoped owner, or `undefined` for global registrations.
+	*/
+	constructor(scope) {
+		this.sections = new NamedEntries((name) => /* @__PURE__ */ new Error(scope === void 0 ? `prompt section "${name}" is already registered (for a per-agent override, register through that agent's \`agent.ctx\` instead)` : `prompt section "${name}" is already registered in this scope`));
+		this.contexts = new NamedEntries((name) => /* @__PURE__ */ new Error(scope === void 0 ? `prompt context "${name}" is already registered (for a per-agent override, register through that agent's \`agent.ctx\` instead)` : `prompt context "${name}" is already registered in this scope`));
+		this.variables = new NamedEntries((name) => /* @__PURE__ */ new Error(scope === void 0 ? `prompt variable "${name}" is already registered (for a per-agent value, register through that agent's \`agent.ctx\` instead)` : `prompt variable "${name}" is already registered in this scope`));
+	}
+	/** @returns whether this layer owns no prompt registrations. */
+	isEmpty() {
+		return this.sections.isEmpty() && this.contexts.isEmpty() && this.runtimeContextSuppressors.isEmpty() && this.toolProviders.isEmpty() && this.variables.isEmpty();
+	}
+};
+/** Registry service for the prompt inputs assembled before each model step. */
+var SystemPrompt = class extends Service {
+	static Config = z.object({
+		includeHarnessIdentity: z.boolean().default(true),
+		includeRuntimeContext: z.boolean().default(true),
+		personaPrefix: z.string().default(""),
+		personaSuffix: z.string().default(""),
+		toolOrder: z.array(z.string()).default(void 0)
+	});
+	layers = new ScopedLayers((scope) => new PromptLayer(scope), () => {
+		this.ctx.emit("system-prompt/change");
+	});
+	toolOrder;
+	constructor(ctx, config) {
+		super(ctx, "systemPrompt");
+		this.toolOrder = validateToolOrder(config.toolOrder);
+		if (config.includeHarnessIdentity ?? true) this.section({
+			name: "harness:identity",
+			order: this.getSectionOrder("HARNESS_IDENTITY"),
+			text: "You are an AI agent powered by DeepSeek Harness."
+		});
+		this.section({
+			name: PERSONA_PREFIX_SECTION,
+			order: this.getSectionOrder("DEPLOYMENT_PERSONA_PREFIX"),
+			text: config.personaPrefix ?? ""
+		});
+		this.section({
+			name: PERSONA_SUFFIX_SECTION,
+			order: this.getSectionOrder("DEPLOYMENT_PERSONA_SUFFIX"),
+			text: config.personaSuffix ?? ""
+		});
+		if (!(config.includeRuntimeContext ?? true)) this.suppressRuntimeContext();
+	}
+	/**
+	* 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) {
+		if (!Number.isFinite(section.order)) throw new TypeError(`prompt section "${section.name}" order must be a finite number`);
+		return this.layers.effect(this.ctx, (layer) => layer.sections.insert(section.name, section), { label: "systemPrompt.section()" });
+	}
+	/**
+	* 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) {
+		return SECTION_ORDERS[name];
+	}
+	/**
+	* 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) {
+		return CONTEXT_ORDERS[name];
+	}
+	/**
+	* 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) {
+		if (!Number.isFinite(context.order)) throw new TypeError(`prompt context "${context.name}" order must be a finite number`);
+		return this.layers.effect(this.ctx, (layer) => layer.contexts.insert(context.name, context), { label: "systemPrompt.context()" });
+	}
+	/**
+	* 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() {
+		return this.layers.effect(this.ctx, (layer) => layer.runtimeContextSuppressors.append(true), { label: "systemPrompt.suppressRuntimeContext()" });
+	}
+	/**
+	* 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) {
+		return this.layers.effect(this.ctx, (layer) => layer.toolProviders.append(provider), { label: "systemPrompt.tools()" });
+	}
+	/**
+	* 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, provider) {
+		if (!VARIABLE_NAME.test(name)) throw new Error(`invalid prompt variable name "${name}" (must match ${String(VARIABLE_NAME)})`);
+		return this.layers.effect(this.ctx, (layer) => layer.variables.insert(name, provider), { label: "systemPrompt.variable()" });
+	}
+	/**
+	* 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 the accepted assembly; their providers and waterfall do not rerun.
+	* @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(assembly, context = {}) {
+		const providers = this.layers.merge(context.scope, (layer) => layer.contexts);
+		const suppressed = !this.layers.global.runtimeContextSuppressors.isEmpty() || this.layers.chainLayers(context.scope).some((layer) => !layer.runtimeContextSuppressors.isEmpty());
+		const required = new Map([...providers].filter(([, entry]) => entry.required === true));
+		const contexts = [];
+		for (const accepted of assembly.contexts) {
+			const provider = providers.get(accepted.name);
+			required.delete(accepted.name);
+			if (suppressed && provider?.required !== true) continue;
+			contexts.push(provider === void 0 ? accepted : resolveContext(provider, context));
+		}
+		for (const provider of required.values()) {
+			const index = contexts.findIndex((entry) => {
+				const next = providers.get(entry.name);
+				return next !== void 0 && next.order > provider.order;
+			});
+			contexts.splice(index < 0 ? contexts.length : index, 0, resolveContext(provider, context));
+		}
+		return {
+			...assembly,
+			contexts
+		};
+	}
+	/**
+	* Assemble global and scoped providers, detach tool parameters, apply
+	* canonical ordering, then run the assembly waterfall. Scoped sections and
+	* variables shadow globals. The returned waterfall value is authoritative
+	* except that an effective complete section is restored afterwards as the
+	* sole prompt section.
+	* @param context - the optional scope and plugin-defined assembly fields.
+	* @returns the post-waterfall assembly with any complete prompt enforced.
+	*/
+	async assemble(context = {}) {
+		const scope = context.scope;
+		const scopeLayers = this.layers.chainLayers(scope);
+		const runtimeContextSuppressed = !this.layers.global.runtimeContextSuppressors.isEmpty() || scopeLayers.some((layer) => !layer.runtimeContextSuppressors.isEmpty());
+		const variables = {};
+		for (const [name, provider] of this.layers.global.variables.entries()) variables[name] = provider(context);
+		for (const layer of scopeLayers) for (const [name, provider] of layer.variables.entries()) variables[name] = provider(context);
+		const sectionByName = this.layers.merge(scope, (layer) => layer.sections);
+		const contextByName = this.layers.merge(scope, (layer) => layer.contexts);
+		const providers = [...this.layers.global.toolProviders.values(), ...scopeLayers.flatMap((layer) => [...layer.toolProviders.values()])];
+		const collected = [];
+		const knownNames = /* @__PURE__ */ new Set();
+		for (const provider of providers) {
+			const result = provider(context);
+			const schemas = result.schemas.map(({ name, description, parameters, deferLoading }) => ({
+				name,
+				description,
+				parameters: structuredClone(parameters),
+				...deferLoading === true ? { deferLoading } : {}
+			}));
+			const acceptedKnownNames = result.knownNames ?? schemas.map((tool) => tool.name);
+			collected.push(...schemas);
+			for (const name of acceptedKnownNames) knownNames.add(name);
+		}
+		const sectionDefinitions = [...sectionByName.values()].sort(comparePromptSections);
+		const completeSections = sectionDefinitions.filter((section) => section.complete === true);
+		if (completeSections.length > 1) throw new Error(`multiple complete prompt sections are active: ${completeSections.map((section) => JSON.stringify(section.name)).join(", ")}`);
+		let completeSection;
+		const assembly = {
+			sections: sectionDefinitions.map((section) => {
+				const assembled = {
+					name: section.name,
+					text: typeof section.text === "function" ? section.text(context) : section.text,
+					...section.interpolate !== void 0 ? { interpolate: section.interpolate } : {}
+				};
+				if (section.complete === true) completeSection = { ...assembled };
+				return assembled;
+			}),
+			contexts: [...contextByName.values()].filter((entry) => !runtimeContextSuppressed || entry.required === true).sort((a, b) => a.order - b.order).map((entry) => resolveContext(entry, context)),
+			tools: orderTools(collected, this.toolOrder, knownNames),
+			variables
+		};
+		const transformed = await this.ctx.waterfall(scopeTarget(this, scope), "system-prompt/assemble", assembly, context, () => Promise.resolve(assembly));
+		if (completeSection === void 0 && !runtimeContextSuppressed) return transformed;
+		const requiredContexts = new Set([...contextByName.values()].filter((entry) => entry.required === true).map((entry) => entry.name));
+		return {
+			...transformed,
+			sections: completeSection === void 0 ? transformed.sections : [completeSection],
+			contexts: runtimeContextSuppressed ? transformed.contexts.filter((entry) => requiredContexts.has(entry.name)) : transformed.contexts
+		};
+	}
+};
+//#endregion
+export { PERSONA_PREFIX_SECTION, PERSONA_SUFFIX_SECTION, SystemPrompt, SystemPrompt as default, TOOL_ORDER_REST, joinContextSections, renderContextSections, renderContextSnapshot, renderPrompt };

package/lib/types/index.d.ts

@@ -0,0 +1,314 @@
+/**
+ * Registry for ordered system sections, dynamic context, tool schemas, and prompt variables.
+ *
+ * @module @qlzt/dsh-system-prompt
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ScopeKey, Scoped } from '@qlzt/dsh-scope';
+import type { ContextSnapshotSection, ToolSchema } from '@qlzt/dsh-llm';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        systemPrompt: SystemPrompt;
+    }
+    interface Events {
+        /**
+         * Expert waterfall over the assembled sections, contexts, tools, and variables.
+         * Scope-filtered dispatch (`@qlzt/dsh-scope`): scoped listeners
+         * receive only that scope's assemblies. The returned value is authoritative.
+         * 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: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>;
+        /**
+         * Emitted when any prompt provider changes. This registry notification is
+         * unfiltered because a global change affects every scope.
+         * @mode emit
+         */
+        'system-prompt/change'(): void;
+    }
+}
+/** Merge-extensible context for one prompt assembly. */
+export 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;
+}
+/** One contributed section of the system prompt (registry input). */
+export 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;
+}
+/** Dynamic model context materialized as a durable user-role snapshot. */
+export 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;
+}
+/** One section of an assembly: {@link PromptSection} with its text resolved. */
+export interface AssembledSection {
+    /** The contributing section's unique name. */
+    name: string;
+    /** The resolved (but not yet interpolated) section text. */
+    text: string;
+    /** Whether to interpolate prompt variables. Defaults to true; false preserves literal text. */
+    interpolate?: boolean;
+}
+/** One resolved dynamic context contribution. */
+export 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;
+}
+/** Tool schemas visible in one assembly and their pre-restriction name set. */
+export 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[];
+}
+/**
+ * Merge-extensible assembled model input. Sections and contexts remain
+ * uninterpolated until rendered; tools are already in canonical order.
+ */
+export interface PromptAssembly {
+    sections: AssembledSection[];
+    contexts: AssembledContext[];
+    tools: ToolSchema[];
+    variables: Record<string, string | undefined>;
+}
+declare const SECTION_ORDERS: {
+    readonly HARNESS_IDENTITY: -1000;
+    readonly DEPLOYMENT_PERSONA_PREFIX: 0;
+    readonly PLAN_POLICY: 500;
+    readonly TEAM_POLICY: 600;
+    readonly PTC_ONLY: 800;
+    readonly FILE_REFERENCE: 900;
+    readonly TOOL_BASH: 1000;
+    readonly TOOL_PWSH: 1010;
+    readonly TOOL_READ: 1100;
+    readonly TOOL_WRITE: 1200;
+    readonly TOOL_EDIT: 1300;
+    readonly TOOL_GLOB: 1400;
+    readonly TOOL_GREP: 1500;
+    readonly TOOL_JOBS: 1600;
+    readonly TOOL_PTY: 1700;
+    readonly TOOL_WEB_SEARCH: 2000;
+    readonly TOOL_WEB_FETCH: 2100;
+    readonly TOOL_LSP: 2200;
+    readonly TOOL_SESSION_QUERY: 2300;
+    readonly TOOL_GOAL: 2400;
+    readonly TOOL_WORKFLOW: 2600;
+    readonly TOOL_RALPH: 2700;
+    readonly TOOL_SUBAGENT: 2800;
+    readonly TOOL_REPORT: 2900;
+    readonly TOOL_COMPUTER_USE: 3000;
+    readonly MCP_SERVERS: 3100;
+    readonly TOOLS_SDK: 5000;
+    readonly DELIVERABLE_FILE_REFERENCES: 9000;
+    readonly STRUCTURED_OUTPUT: 9900;
+    readonly HARNESS_SOURCE: 10000;
+    readonly WEB_SURFACE: 10100;
+    readonly DEPLOYMENT_PERSONA_SUFFIX: 10200;
+};
+/** Name of a centrally allocated prompt-section position. */
+export type PromptSectionOrderName = keyof typeof SECTION_ORDERS;
+declare const CONTEXT_ORDERS: {
+    readonly WORKING_DIRECTORY: 100;
+    readonly SANDBOX_POLICY: 110;
+    readonly APPROVAL_POLICY: 115;
+    readonly SUBAGENT_DELEGATION: 120;
+};
+/** Name of a centrally allocated runtime-context position. */
+export type PromptContextOrderName = keyof typeof CONTEXT_ORDERS;
+/**
+ * The deployment persona prefix's section name. Exported because a
+ * composition can replace this slot — an agent preset shadows the
+ * deployment's persona with its own — and both sides naming the same section
+ * is what makes the replacement work rather than duplicate.
+ */
+export declare const PERSONA_PREFIX_SECTION = "deployment:persona-prefix";
+/** Deployment persona suffix section name shared by global and scoped contributions. */
+export declare const PERSONA_SUFFIX_SECTION = "deployment:persona-suffix";
+/** Reserved {@link Config.toolOrder} marker for unlisted tools. */
+export declare const TOOL_ORDER_REST = "<unlisted-tools>";
+/** Plugin config: the deployment-authored fragment of the system prompt (see {@link Config.personaPrefix} for its contract). */
+export interface Config {
+    /** Include the fixed DeepSeek Harness identity before the deployment persona (default true). */
+    includeHarnessIdentity?: boolean;
+    /** Include optional runtime-context snapshots in model history (default true); required context remains. */
+    includeRuntimeContext?: boolean;
+    /**
+     * Deployment-wide persona prefix template before first-party guidance. A scoped section named
+     * `deployment:persona-prefix` shadows it; `{{variable}}` references are strict.
+     */
+    personaPrefix?: string;
+    /**
+     * Persona suffix template after first-party guidance. A scoped `deployment:persona-suffix`
+     * section shadows it; `{{variable}}` references are strict. Defaults to empty.
+     */
+    personaSuffix?: string;
+    /**
+     * Model-facing tool names in order, with {@link TOOL_ORDER_REST} exactly once.
+     * Invalid fields fail at load and unknown names fail at assembly; known names
+     * hidden in one scope may be absent there. Omitted means lexicographic order.
+     */
+    toolOrder?: string[];
+}
+/**
+ * Interpolate strict `{{variable}}` references, drop empty sections, and join
+ * the rest with blank lines. Sections with `interpolate: false` retain literal
+ * text. Malformed, unknown, or undefined references in other sections throw;
+ * a lone `{{` without any later `}}` is literal prose, and substituted values
+ * are not scanned again.
+ * @param assembly - the assembly whose sections and variables to render.
+ * @returns the rendered prompt, or `''` when all sections are empty.
+ */
+export declare function renderPrompt(assembly: PromptAssembly): string;
+/**
+ * Render the complete dynamic context snapshot, preserving literal contributions.
+ * @param assembly - the assembly whose contexts and variables to render.
+ * @returns the current full snapshot, or `''` when no context is active.
+ */
+export declare function renderContextSnapshot(assembly: PromptAssembly): string;
+/**
+ * The model-facing snapshot text for an already-rendered section list.
+ *
+ * A caller that also needs the sections renders them once and joins here, so a
+ * request does not interpolate every context twice.
+ * @param sections - sections from {@link renderContextSections}.
+ * @returns the current full snapshot, or `''` when no context is active.
+ */
+export declare function joinContextSections(sections: readonly ContextSnapshotSection[]): string;
+/**
+ * The same snapshot, kept as the named contributions it was assembled from.
+ *
+ * {@link renderContextSnapshot} joins these for the model; a consumer that
+ * presents the snapshot uses them to attribute each part to the subsystem that
+ * contributed it, without re-splitting the joined prose. Contributions with
+ * `interpolate: false` preserve literal text instead of resolving prompt variables.
+ * @param assembly - the assembly whose contexts and variables to render.
+ * @returns one entry per contributing context that rendered to non-empty text.
+ */
+export declare function renderContextSections(assembly: PromptAssembly): ContextSnapshotSection[];
+/** Registry service for the prompt inputs assembled before each model step. */
+export declare class SystemPrompt extends Service {
+    static Config: z<Config>;
+    private readonly layers;
+    private readonly toolOrder;
+    constructor(ctx: Context, config: Config);
+    /**
+     * 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 the accepted assembly; their providers and waterfall do not rerun.
+     * @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(assembly: PromptAssembly, context?: AssembleContext): PromptAssembly;
+    /**
+     * Assemble global and scoped providers, detach tool parameters, apply
+     * canonical ordering, then run the assembly waterfall. Scoped sections and
+     * variables shadow globals. The returned waterfall value is authoritative
+     * except that an effective complete section is restored afterwards as the
+     * sole prompt section.
+     * @param context - the optional scope and plugin-defined assembly fields.
+     * @returns the post-waterfall assembly with any complete prompt enforced.
+     */
+    assemble(context?: AssembleContext): Promise<PromptAssembly>;
+}
+export default SystemPrompt;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@qlzt/dsh-system-prompt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "System prompt assembly registry for the DeepSeek Harness",
+  "version": "0.2.1-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitee.com/zsping1989/deepseek-harness.git",
+    "directory": "packages/core/system-prompt"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qlzt/dsh-llm": "0.2.1-alpha.2",
+    "@qlzt/dsh-scope": "0.2.1-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.5-alpha.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-scope": "0.2.1-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
+  },
+  "dsh": {}
+}