From 1beb38554e62bf6c83b4b163c135b69c0f4ac38b Mon Sep 17 00:00:00 2001 From: NI0317 Date: Fri, 31 Jul 2026 15:19:59 +0800 Subject: [PATCH] fix(review): align runtime-context diagnostics and docs --- .../feature/2026-07-06-sandbox.i18n.yaml | 4 ++-- .../implemented/feature/2026-07-06-sandbox.md | 2 +- .../feature/2026-07-06-sandbox.zh.md | 2 +- docs/architecture.i18n.yaml | 4 ++-- docs/architecture.md | 4 ++-- docs/architecture.zh.md | 4 ++-- docs/cordis-catalog/services.md | 2 +- packages/bash/bash-sandbox/README.i18n.yaml | 4 ++-- packages/bash/bash-sandbox/README.md | 2 +- packages/bash/bash-sandbox/README.zh.md | 2 +- packages/core/agent-loop/src/agent.ts | 1 + packages/core/system-prompt/src/index.ts | 22 +++++++++++-------- .../system-prompt/tests/system-prompt.spec.ts | 9 ++++++++ packages/pty/pty-local/src/index.ts | 1 + 14 files changed, 39 insertions(+), 24 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml index b062a57391..d5727d9c4b 100644 --- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-06-sandbox.md -2026-07-06-sandbox.md: f53516f97d45426bc4693b43a7135dd565a468a3 -2026-07-06-sandbox.zh.md: 6c92d9d80cf67a5e501f15572cbbe680babb863b +2026-07-06-sandbox.md: 4355ab57374f77f1733fff39e2fb4ccadcedaf6b +2026-07-06-sandbox.zh.md: 02c5337555b7466c2bac7fc4774cdd2c945178ae diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md index f53516f97d..4355ab5737 100644 --- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md +++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md @@ -72,7 +72,7 @@ Backend profiles share the mode contract but differ in necessary host grants. La `dsh-bash-sandbox` extends `LocalBashExecutor` and hands `ctx.sandbox` the exact `['bash', '-c', command]` argv it is about to spawn. A denial is an orthogonal result fact, conservatively classified from the active runner's stderr dialect. A runner failure outranks denial: foreground execution throws `SANDBOX_UNAVAILABLE`; a settled `BashProcess` stamps `sandbox.runnerFailed`, and the bash producer renders it through generic `task_output`. -The model sees the current effective file policy in the owner-derived `sandbox:policy` request section, while the static tool description explains the denial marker (`[sandbox: file access denied under mode]`), encourages attempting commands that may be denied, and forbids retrying around a denial; when the escalation fields are advertised, a denied result additionally carries the escalation hint itself, so the sanctioned same-turn retry is prompted at the decision point rather than depending on the model recalling the description (§ Escalation). [The current-policy decision](2026-07-30-current-sandbox-policy-context.md) owns the section's rationale and boundaries. +The model sees the current effective file policy in the owner-derived `sandbox:policy` runtime context, while the static tool description explains the denial marker (`[sandbox: file access denied under mode]`), encourages attempting commands that may be denied, and forbids retrying around a denial; when the escalation fields are advertised, a denied result additionally carries the escalation hint itself, so the sanctioned same-turn retry is prompted at the decision point rather than depending on the model recalling the description (§ Escalation). [The current-policy decision](2026-07-30-current-sandbox-policy-context.md) owns the context's rationale and boundaries. #### Escalation: one approved wider retry after a denial diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md index 6c92d9d80c..02c5337555 100644 --- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md +++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md @@ -72,7 +72,7 @@ Landlock launcher 源码和包工作区位于 `native/landlock-run`，与 harnes `dsh-bash-sandbox` 扩展 `LocalBashExecutor`，并把即将 spawn 的确切 `['bash', '-c', command]` argv 交给 `ctx.sandbox`。拒绝是与其他结果正交的事实，依据当前 runner 的 stderr 方言保守分类。Runner 失败优先于拒绝：前台执行抛出 `SANDBOX_UNAVAILABLE`；结算后的 `BashProcess` 会盖章 `sandbox.runnerFailed`，bash 生产者再通过通用 `task_output` 渲染它。 -模型会在归属方派生的 `sandbox:policy` 请求段落中看到当前有效的文件策略；静态工具描述则解释拒绝标记（`[sandbox: file access denied under mode]`），鼓励尝试可能被拒绝的命令，并禁止绕过拒绝重试。当升级字段被公布时，被拒绝的结果还会携带升级提示本身，使被认可的同轮次重试在决策点获得提示，而非依赖模型回忆描述（§ 升级机制）。[当前策略决策](2026-07-30-current-sandbox-policy-context.md)负责该段落的理由与边界。 +模型会在归属方派生的 `sandbox:policy` 运行时上下文中看到当前有效的文件策略；静态工具描述则解释拒绝标记（`[sandbox: file access denied under mode]`），鼓励尝试可能被拒绝的命令，并禁止绕过拒绝重试。当升级字段被公布时，被拒绝的结果还会携带升级提示本身，使被认可的同轮次重试在决策点获得提示，而非依赖模型回忆描述（§ 升级机制）。[当前策略决策](2026-07-30-current-sandbox-policy-context.md)负责该上下文的理由与边界。 #### 升级机制：拒绝后一次经批准的更宽重试 diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index 2b07607b39..6d31636819 100644 --- a/docs/architecture.i18n.yaml +++ b/docs/architecture.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/architecture.md -architecture.md: 461a1eee94be28ced65e320286bab98773f78337 -architecture.zh.md: 9dd3b4aed1b3bb0af14f7c53b7c8d51dfd75cd99 +architecture.md: f03f8709ff99406f29e2348ec971abef99e8b64a +architecture.zh.md: bd668e9e6c2f7d22d368b8a42937f7ab0d9b2371 diff --git a/docs/architecture.md b/docs/architecture.md index 461a1eee94..f03f8709ff 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -16,7 +16,7 @@ Harnesses are [Cordis](cordis-primer.md) contexts; packages contribute services, |---|---|---| | — | [`dsh-scope`](../packages/core/scope/README.md) | scoped-context registrations and shared layer storage (library) | | `ctx.sessions` | `dsh-session` | in-memory event-sourced sessions | -| `ctx.systemPrompt` | `dsh-system-prompt` | ordered prompt sections, tool schemas, and variables | +| `ctx.systemPrompt` | `dsh-system-prompt` | ordered stable system sections, cache-safe dynamic contexts, tool schemas, and variables | | `ctx.tools` | `dsh-tools` | tool registry and [execution pipeline](tool-execution-pipeline.md) | | `ctx.agents` | `dsh-agent` | live agents, delegated creation, `agent/*` events, process-local initiator scope | | `ctx.agentLoop` | `dsh-agent-loop` | concrete `Agent` driver | @@ -118,7 +118,7 @@ idle inject: do not open a turn or run the model ``` -Each step assembles ordered prompt sections, tool schemas, and variables; unknown references fail the turn. `dsh-system-prompt` owns identity and persona; the loop supplies `provider`, `model`, and `cwd` ([prompt ownership](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)). +Each step assembles ordered stable system sections, cache-safe dynamic contexts, tool schemas, and variables; unknown references fail the turn. `dsh-system-prompt` owns identity and persona; the loop supplies `provider`, `model`, and `cwd` ([prompt ownership](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)). Admission-time and active-turn `inject()` stage for the next step; post-tool `additionalContexts` settles after results. Steering shares that staging boundary and requests another step. Idle `inject()` appends immediately without changing turn numbers; persistence drains eagerly. diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index 9dd3b4aed1..bd668e9e6c 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -16,7 +16,7 @@ |---|---|---| | — | [`dsh-scope`](../packages/core/scope/README.md) | 作用域上下文注册项与共享层存储（库） | | `ctx.sessions` | `dsh-session` | 内存中的事件溯源会话 | -| `ctx.systemPrompt` | `dsh-system-prompt` | 有序提示词片段、工具 schema 和变量 | +| `ctx.systemPrompt` | `dsh-system-prompt` | 有序的稳定系统提示词片段、缓存安全的动态上下文、工具 schema 和变量 | | `ctx.tools` | `dsh-tools` | 工具注册表和[执行流水线](tool-execution-pipeline.md) | | `ctx.agents` | `dsh-agent` | 活跃 agent、委托创建、`agent/*` 事件、进程内发起方作用域 | | `ctx.agentLoop` | `dsh-agent-loop` | 实体 `Agent` 驱动器 | @@ -118,7 +118,7 @@ idle inject: do not open a turn or run the model ``` -每个步骤都会组装有序提示词片段、工具 schema 和变量；未知引用会使该轮次失败。`dsh-system-prompt` 负责身份和角色设定；循环提供 `provider`、`model` 和 `cwd`（[提示词归属](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)）。 +每个步骤都会组装有序的稳定系统提示词片段、缓存安全的动态上下文、工具 schema 和变量；未知引用会使该轮次失败。`dsh-system-prompt` 负责身份和角色设定；循环提供 `provider`、`model` 和 `cwd`（[提示词归属](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)）。 接纳期间和活跃轮次内的 `inject()` 会为下一步骤暂存；工具执行后的 `additionalContexts` 会在结果记录完毕后落定。steering 与其共用这一暂存边界，并请求再执行一个步骤。空闲状态下的 `inject()` 会立即追加，且不改变轮次编号；持久化层会尽快排空。 diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 4e8bb09ec8..d8cc864aab 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -2050,7 +2050,7 @@ async assemble(context: AssembleContext = {}): Promise Types: [AssembleContext](../core-data-structures/system-prompt.md) · [PromptContext](../core-data-structures/system-prompt.md) · [PromptSection](../core-data-structures/system-prompt.md) · [ToolProviderResult](../core-data-structures/system-prompt.md) -Source: [`packages/core/system-prompt/src/index.ts:294`](../../packages/core/system-prompt/src/index.ts) +Source: [`packages/core/system-prompt/src/index.ts:298`](../../packages/core/system-prompt/src/index.ts) ## `ctx.tasks` — `TaskService` (abstract seam) diff --git a/packages/bash/bash-sandbox/README.i18n.yaml b/packages/bash/bash-sandbox/README.i18n.yaml index 0c294c57be..640eb1810f 100644 --- a/packages/bash/bash-sandbox/README.i18n.yaml +++ b/packages/bash/bash-sandbox/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/bash/bash-sandbox/README.md -README.md: e9b040e7af55192e8afb9abf8bb4b99358ef8342 -README.zh.md: f3956111f31ad85331caa47b1755667b096d2969 +README.md: 035a8ad2401ca608d264049d454359eda7b2b9a7 +README.zh.md: cee27a9baaa539ba07eb1d730ea9bef2004fbeeb diff --git a/packages/bash/bash-sandbox/README.md b/packages/bash/bash-sandbox/README.md index e9b040e7af..035a8ad240 100644 --- a/packages/bash/bash-sandbox/README.md +++ b/packages/bash/bash-sandbox/README.md @@ -52,7 +52,7 @@ Small fixed schema increment on requests where `bash` is visible, plus the curre #### KV Cache effect -Prefix-stable while the executor and standing policy are unchanged. Changing the policy updates the owner-rendered section; changing executor capabilities also alters the `bash` schema. +A standing-policy change appends a complete owner-rendered context snapshot after retained history, preserving the existing system/history prefix byte-for-byte. Changing executor capabilities alters the `bash` schema. ### Bash tool result, indirectly diff --git a/packages/bash/bash-sandbox/README.zh.md b/packages/bash/bash-sandbox/README.zh.md index f3956111f3..cee27a9baa 100644 --- a/packages/bash/bash-sandbox/README.zh.md +++ b/packages/bash/bash-sandbox/README.zh.md @@ -52,7 +52,7 @@ #### KV Cache 影响 -执行器与常驻策略不变时，前缀保持稳定。更改策略会更新归属方渲染的段落；更改执行器能力也会改变 `bash` schema。 +常驻策略变化会在保留的历史之后追加一份由归属方渲染的完整上下文快照，并使既有 system/history 前缀保持逐字节不变。更改执行器能力会改变 `bash` schema。 ### 间接的 Bash 工具结果 diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index a2e3c8c156..82309aa6bb 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -56,6 +56,7 @@ type StepOutcome = | { kind: 'request-failed'; error: RequestError; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined } const RUNTIME_CONTEXT_SOURCE = '@deepseek-ai/dsh-system-prompt' +/** Clearing marker kept distinct from every prefixed {@link renderContextSnapshot} result. */ const CLEARED_RUNTIME_CONTEXT = 'Current runtime context: none. Earlier runtime-context snapshots no longer apply.' /** Whether one user message is owned by runtime-context materialization. */ diff --git a/packages/core/system-prompt/src/index.ts b/packages/core/system-prompt/src/index.ts index e96490b02a..2e07fcfff2 100644 --- a/packages/core/system-prompt/src/index.ts +++ b/packages/core/system-prompt/src/index.ts @@ -194,7 +194,7 @@ export interface Config { */ export function renderPrompt(assembly: PromptAssembly): string { return assembly.sections - .map(section => interpolate(section, assembly.variables)) + .map(section => interpolate(section, assembly.variables, 'section')) .filter(text => text.length > 0) .join('\n\n') } @@ -209,16 +209,20 @@ export function renderPrompt(assembly: PromptAssembly): string { */ export function renderContextSnapshot(assembly: PromptAssembly): string { const body = assembly.contexts - .map(context => interpolate(context, assembly.variables)) + .map(context => interpolate(context, assembly.variables, 'context')) .filter(text => text.length > 0) .join('\n\n') if (body.length === 0) return '' return `Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\n${body}` } -/** Interpolate one section's `{{variable}}` references (see {@link renderPrompt}). */ -function interpolate(section: AssembledSection, variables: Record): string { - const text = section.text +/** Interpolate one section or context and attribute diagnostics to its owning input. */ +function interpolate( + input: AssembledSection | AssembledContext, + variables: Record, + kind: 'section' | 'context', +): string { + const text = input.text let result = '' let last = 0 for (let open = text.indexOf('{{'); open >= 0; open = text.indexOf('{{', last)) { @@ -226,7 +230,7 @@ function interpolate(section: AssembledSection, variables: Record= 0) { - throw new Error(`malformed prompt variable reference at "${text.slice(open, open + 16)}…" in section "${section.name}" (references are complete simple {{name}} groups)`) + 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 @@ -235,16 +239,16 @@ function interpolate(section: AssembledSection, variables: Record 0 ? known.join(', ') : '(none)'}`) + 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 === undefined) { - throw new Error(`prompt variable "{{${name}}}" has no value for this assembly (section "${section.name}")`) + 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 diff --git a/packages/core/system-prompt/tests/system-prompt.spec.ts b/packages/core/system-prompt/tests/system-prompt.spec.ts index e5bfb5138b..834c17c341 100644 --- a/packages/core/system-prompt/tests/system-prompt.spec.ts +++ b/packages/core/system-prompt/tests/system-prompt.spec.ts @@ -309,6 +309,15 @@ describe('SystemPrompt', () => { .toBe('Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nMode: read-only.') }) + it('attributes context interpolation failures to the contributing context', () => { + expect(() => renderContextSnapshot({ + sections: [], + contexts: [{ name: 'policy', text: 'Mode: {{missing}}.' }], + tools: [], + variables: {}, + })).toThrow('unknown prompt variable "{{missing}}" in context "policy"; registered variables: (none)') + }) + it('emits system-prompt/change when a tool provider is registered and disposed', async () => { const ctx = new Context() await ctx.plugin(SystemPrompt) diff --git a/packages/pty/pty-local/src/index.ts b/packages/pty/pty-local/src/index.ts index d471e3cbfe..e59d53446a 100644 --- a/packages/pty/pty-local/src/index.ts +++ b/packages/pty/pty-local/src/index.ts @@ -74,6 +74,7 @@ function childEnvironment(spec: PtyBackendSpawnSpec): NodeJS.ProcessEnv { function spawnArgv(ctx: Context, config: ResolvedConfig, policy: SandboxExecutionPolicy): string[] { const argv = [config.shellPath, ...config.shellArgs] if (policy.mode === 'danger-full-access') return argv + // Re-state the discriminant because object spread does not preserve its narrowed type. return ctx.sandbox.confine(argv, { ...policy, mode: policy.mode }).argv }