From 555b664b08db05e1cf8eeebb7eb00960ddf785b7 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Fri, 18 Sep 2026 17:38:59 +0800 Subject: [PATCH] fix(compaction): reserve configurable 64K pressure headroom --- ...el-context-and-compaction-policy.i18n.yaml | 4 +- ...ted-model-context-and-compaction-policy.md | 6 +- ...-model-context-and-compaction-policy.zh.md | 6 +- .../profiles/headless/tests/compaction.e2e.ts | 1 + docs/config-catalog.i18n.yaml | 4 +- docs/config-catalog.md | 8 +- docs/config-catalog.zh.md | 8 +- .../compaction-basic/README.i18n.yaml | 4 +- .../compaction/compaction-basic/README.md | 13 +-- .../compaction/compaction-basic/README.zh.md | 13 +-- .../compaction/compaction-basic/src/config.ts | 29 +++++-- .../compaction/compaction-basic/src/index.ts | 3 + .../compaction/compaction-basic/src/types.ts | 9 +- .../tests/compaction-basic.spec.ts | 84 ++++++++++++++----- .../tests/compaction-loop-repro.spec.ts | 3 + .../tests/loader-composition.spec.ts | 7 ++ packages/llm/llm-deepseek/README.i18n.yaml | 4 +- packages/llm/llm-deepseek/README.md | 2 +- packages/llm/llm-deepseek/README.zh.md | 2 +- .../acp/image-compaction/cordis.snapshot.yml | 1 + snapshots/acp/image-compaction/cordis.yml | 1 + .../cordis.snapshot.yml | 5 +- .../compaction-output-reserve/cordis.yml | 1 + 23 files changed, 149 insertions(+), 69 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.i18n.yaml index a5b947001e..081f618b1a 100644 --- a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.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/architecture/2026-07-20-routed-model-context-and-compaction-policy.md -2026-07-20-routed-model-context-and-compaction-policy.md: 1e4abb3b97ceb5c3265da321ad6070b135b98a73 -2026-07-20-routed-model-context-and-compaction-policy.zh.md: 15db2343ee6c06c8f4ab24562362faeb1203077d +2026-07-20-routed-model-context-and-compaction-policy.md: d276354cb21f45eaec1c4e3202c7be1770745efb +2026-07-20-routed-model-context-and-compaction-policy.zh.md: b6e2a0b914f78e19675d80b86d8d962e8ba8c80f diff --git a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md index 1e4abb3b97..d276354cb2 100644 --- a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md +++ b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md @@ -26,17 +26,17 @@ The hand-rolled DeepSeek adapter accepts optional `contextWindow` on each config Compact-basic owns consumer policy. Top-level fields define defaults; `modelPolicies` contains partial overrides keyed by the exact `{ provider, model }` pair. Duplicate targets and unknown or invalid fields fail plugin load. `thresholdRatio` defaults to `0.8`, and retention defaults to `retainRatio: 0.16`; callers may use an absolute `retainTokens` instead, but the two retention forms are mutually exclusive. After inheritance, a ratio retention that is not below its threshold ratio also fails plugin load because no model capacity can make that policy valid. -For proactive pressure, compaction-basic reads the latest durable request route, resolves its adapter capacity and exact-target policy, and scales ratios into a `ResolvedCompactSpec`. Ratios scale the route's *message budget* — its context window minus the output tokens one request reserves — because a provider charges the prompt and that reservation to the same window. Scaling the whole window instead can place the threshold above the point where the provider refuses the request, so the provider can reject the request before proactive pressure qualifies. The reservation is the effective envelope's `maxTokens`, else the adapter's per-request output default. Compaction-basic performs this resolution on every check, so a provider or model switch in one session changes capacity and policy immediately. An absolute retained budget that is not below the scaled threshold fails when the target capacity first makes that comparison possible. +For proactive pressure, compaction-basic reads the latest durable route and resolves its adapter capacity `W`, request output reservation `O`, and exact-target policy. The trigger is `floor(min(W × thresholdRatio, W − O − headroomTokens))`, with default headroom of 65,536 tokens. The window fraction limits history growth while the second cap leaves extra room after a full output for compaction input and generation; it does not bound arbitrary tool-result growth. Retention scales `W − O` independently. `O` is the effective envelope’s `maxTokens`, else the adapter’s per-request default, else zero. Resolution runs on every check, so route or output-cap changes immediately affect policy. A nonpositive pressure budget or retention at least as large as the trigger fails when target capacity makes that comparison possible. The same exact-target override can select summarization provider/model, summarization output cap, convergence retries, and overflow retry cap. These are compaction concerns and never enter an LLM provider. ### Target-specific pressure failures preserve optional composition -An adapter that lacks capacity metadata remains a valid LLM route. Manual proactive pressure fails with a target-specific configuration error; the automatic listener warns once per exact route and continues with full history. The same per-route suppression applies when the output reservation leaves no message budget or resolved capacity exposes an invalid absolute retention budget, while unrelated operational failures remain independently visible. Canonical provider-confirmed overflow does not need capacity metadata: it bypasses the proactive threshold and normal retention budget, attempts one maximal balanced reduction, and preserves the original provider error unless replacement proves progress. +An adapter that lacks capacity metadata remains a valid LLM route. Manual proactive pressure fails with a target-specific configuration error; the automatic listener warns once per exact route and continues with full history. The same suppression applies when output plus headroom exhausts capacity or retention reaches the trigger, while unrelated operational failures remain independently visible. Canonical provider-confirmed overflow does not need capacity metadata: it bypasses the proactive threshold and normal retention budget, attempts one maximal balanced reduction, and preserves the original provider error unless replacement proves progress. ## Testing -Service tests cover detached context metadata, invalid adapter output, catalog independence, and default absence. Adapter tests cover DeepSeek exact/default/unlisted resolution, invalid capacities, and pi-ai exact descriptor resolution. Compact tests cover ratio scaling against the message budget left after the routed request's reservation (envelope cap and adapter-default fallback), exact provider/model overrides, load-time rejection of invalid merged ratios, runtime absolute-budget validation, same-model-id provider switches, target-specific warning suppression, and capacity-independent overflow recovery. The keyless `compaction-output-reserve` headless scenario records a nonzero request cap, proactive compaction before the next step, and the replacement history. Loader fixtures reject the removed token-meter capacity setting, and examples configure capacity on adapters. +Service tests cover detached context metadata, invalid adapter output, catalog independence, and default absence. Adapter tests cover DeepSeek exact/default/unlisted resolution, invalid capacities, and pi-ai exact descriptor resolution. Compact tests cover both trigger caps, default and overridden headroom, envelope output caps and adapter fallback, independent retention scaling, invalid budgets, exact-target overrides, provider switches, warning suppression, and capacity-independent overflow recovery. The keyless `compaction-output-reserve` headless scenario records a nonzero request cap, proactive compaction before the next step, and replacement history. Loader fixtures reject the removed token-meter capacity setting, and examples configure capacity on adapters. ## Alternatives considered diff --git a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md index 15db2343ee..b6e2a0b914 100644 --- a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md @@ -26,17 +26,17 @@ Status: implemented Compact-basic 拥有消费方策略。顶层字段定义默认值;`modelPolicies` 包含以精确 `{ provider, model }` 组合为键的部分覆盖。重复目标、未知字段或无效字段都会让插件加载失败。`thresholdRatio` 默认为 `0.8`,保留策略默认为 `retainRatio: 0.16`;调用方也可以改用绝对 `retainTokens`,但两种保留形式互斥。完成继承后,如果保留比例不小于阈值比例,插件也会加载失败,因为任何模型容量都无法让该策略有效。 -对于主动压力检查,compaction-basic 读取最新持久请求路由,解析其适配器容量与精确目标策略,再把比例缩放为 `ResolvedCompactSpec`。比例缩放的是该路由的**消息预算**——其上下文窗口减去单次请求预留的输出 token——因为提供方把提示词与这份预留计入同一个窗口。按整个窗口缩放可能使阈值落在提供方开始拒绝请求的位置之上,让提供方在主动压力满足条件之前就拒绝请求。这份预留取自生效信封的 `maxTokens`,否则取适配器按请求输出的默认值。Compaction-basic 每次检查都会重新解析,因此同一会话切换提供方或模型后,容量与策略会立即变化。若绝对保留预算不小于缩放后的阈值,系统会在目标容量首次允许比较两者时失败。 +对于主动压力检查,compaction-basic 读取最新持久路由,解析适配器容量 `W`、请求输出预留 `O` 和精确目标策略。触发阈值为 `floor(min(W × thresholdRatio, W − O − headroomTokens))`,默认余量为 65,536 tokens。窗口比例限制历史增长,第二项则在一次完整输出后为压缩输入与生成留出额外空间;它无法限制任意工具结果的增长。保留预算独立按 `W − O` 缩放。`O` 取自生效信封的 `maxTokens`,否则取适配器按请求的默认值,再回退到零。每次检查都会重新解析,因此路由或输出上限变化会立即影响策略。若压力预算非正,或保留预算不低于触发阈值,会在目标容量允许比较时失败。 同一精确目标覆盖还可以选择摘要提供方/模型、摘要输出上限、收敛重试次数与溢出重试上限。这些都属于压缩问题,不会进入任何 LLM 提供方。 ### 目标专用压力错误仍保留可选组合 -缺少容量元数据的适配器仍是有效 LLM 路由。手动主动压力检查会返回目标专用配置错误;自动监听器按精确路由只警告一次,并继续保留完整历史。当输出预留没有留下消息预算,或已解析容量暴露出无效的绝对保留预算时,系统也按路由抑制重复警告;其他运行故障仍会各自对外可见。提供方已经确认的规范化溢出不需要容量元数据:它绕过主动阈值与普通保留预算,尝试一次最大且平衡的缩减,并在替换无法证明进展时保留原始提供方错误。 +缺少容量元数据的适配器仍是有效 LLM 路由。手动主动压力检查会返回目标专用配置错误;自动监听器按精确路由只警告一次,并继续保留完整历史。当输出预留与余量耗尽容量,或保留预算达到触发阈值时,也会抑制重复警告;其他运行故障仍会各自对外可见。提供方已经确认的规范化溢出不需要容量元数据:它绕过主动阈值与普通保留预算,尝试一次最大且平衡的缩减,并在替换无法证明进展时保留原始提供方错误。 ## 测试 -服务测试覆盖与适配器内部状态分离的上下文元数据、无效适配器输出、目录独立性与默认缺失行为。适配器测试覆盖 DeepSeek 的精确容量、默认容量、未列出模型解析及无效容量,以及 pi-ai 的精确描述符解析。压缩测试覆盖按已路由请求预留之后的消息预算进行比例缩放(生效信封上限与适配器默认回退两条路径)、精确提供方/模型覆盖、加载期拒绝无效合并比例、运行时校验绝对预算、相同模型 id 的提供方切换、目标专用警告抑制与不依赖容量的溢出恢复。无需密钥的 `compaction-output-reserve` headless 场景记录非零请求上限、下一步之前的主动压缩和替换后的历史。Loader fixture(测试前置数据)会拒绝已经移除的 token-meter 容量设置,示例则在适配器上配置容量。 +服务测试覆盖与适配器内部状态分离的上下文元数据、无效适配器输出、目录独立性与默认缺失行为。适配器测试覆盖 DeepSeek 的精确容量、默认容量、未列出模型解析及无效容量,以及 pi-ai 的精确描述符解析。压缩测试覆盖两项阈值上限、默认和覆盖余量、信封输出上限与适配器回退、独立保留预算缩放、无效预算、精确目标覆盖、提供方切换、警告抑制和不依赖容量的溢出恢复。无需密钥的 `compaction-output-reserve` headless 场景记录非零请求上限、下一步之前的主动压缩和替换后的历史。Loader fixture(测试前置数据)会拒绝已经移除的 token-meter 容量设置,示例则在适配器上配置容量。 ## 考虑过的替代方案 diff --git a/apps/cli/tests/profiles/headless/tests/compaction.e2e.ts b/apps/cli/tests/profiles/headless/tests/compaction.e2e.ts index 7497e76e8e..8a7506bb91 100644 --- a/apps/cli/tests/profiles/headless/tests/compaction.e2e.ts +++ b/apps/cli/tests/profiles/headless/tests/compaction.e2e.ts @@ -40,6 +40,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('compaction: a long session compa modelMaxTokens: 7_000, compact: { thresholdRatio: 0.5, + headroomTokens: 4_000, retainTokens: 400, summarizationProvider: '', summarizationModel: '', diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index 859b69315b..8527ea13a7 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.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/config-catalog.md -config-catalog.md: 422383d1a102fc2139897d581a6897efbc1ade29 -config-catalog.zh.md: fe156ebd82ed58cd021542f1395fb08532e29960 +config-catalog.md: a99bfcdbbe588feac739ef4f9c8126714a838fa3 +config-catalog.zh.md: 2e50e9960920d153fdee779c3a3ea8a88ca5d567 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 422383d1a1..a99bfcdbbe 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -486,9 +486,11 @@ export interface BasicCompactionConfig extends CompactionPolicyConfig { /** Policy fields shared by the default policy and exact model overrides. */ export interface CompactionPolicyConfig { - /** Compact at this fraction of the model's message budget: context window minus reserved output tokens. Defaults to `0.8`. */ + /** Window fraction for pressure; capped at context window minus reserved output and `headroomTokens`. Defaults to `0.8`. */ thresholdRatio?: number - /** Recent context retained as a fraction of that same message budget. Defaults to `0.16`. */ + /** Additional pressure headroom beyond the routed output reservation. Non-negative integer; defaults to `65536`. */ + headroomTokens?: number + /** Recent context retained as a fraction of context window minus reserved output tokens. Defaults to `0.16`. */ retainRatio?: number /** Absolute recent-context budget; mutually exclusive with `retainRatio`. */ retainTokens?: number @@ -513,7 +515,7 @@ export interface ModelCompactPolicyConfig extends CompactionPolicyConfig { } ``` -Source: [`packages/compaction/compaction-basic/src/types.ts:38`](../packages/compaction/compaction-basic/src/types.ts) +Source: [`packages/compaction/compaction-basic/src/types.ts:40`](../packages/compaction/compaction-basic/src/types.ts) diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index fe156ebd82..2e50e99609 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -488,9 +488,11 @@ export interface BasicCompactionConfig extends CompactionPolicyConfig { /** Policy fields shared by the default policy and exact model overrides. */ export interface CompactionPolicyConfig { - /** Compact at this fraction of the model's message budget: context window minus reserved output tokens. Defaults to `0.8`. */ + /** Window fraction for pressure; capped at context window minus reserved output and `headroomTokens`. Defaults to `0.8`. */ thresholdRatio?: number - /** Recent context retained as a fraction of that same message budget. Defaults to `0.16`. */ + /** Additional pressure headroom beyond the routed output reservation. Non-negative integer; defaults to `65536`. */ + headroomTokens?: number + /** Recent context retained as a fraction of context window minus reserved output tokens. Defaults to `0.16`. */ retainRatio?: number /** Absolute recent-context budget; mutually exclusive with `retainRatio`. */ retainTokens?: number @@ -515,7 +517,7 @@ export interface ModelCompactPolicyConfig extends CompactionPolicyConfig { } ``` -来源:[`packages/compaction/compaction-basic/src/types.ts:38`](../packages/compaction/compaction-basic/src/types.ts) +来源:[`packages/compaction/compaction-basic/src/types.ts:40`](../packages/compaction/compaction-basic/src/types.ts) diff --git a/packages/compaction/compaction-basic/README.i18n.yaml b/packages/compaction/compaction-basic/README.i18n.yaml index 1d0c9664ee..0c3dca4b8e 100644 --- a/packages/compaction/compaction-basic/README.i18n.yaml +++ b/packages/compaction/compaction-basic/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/compaction/compaction-basic/README.md -README.md: 5b6f6c35447fa214f58f1fe8192be2031ef37658 -README.zh.md: 6c9effbae4dcd5d5b9e25db1b419918f28a65e85 +README.md: e2da58b0749ef82d8e7e3e514c9d0e573438c2ef +README.zh.md: de53683b15fe08d62e5fa1f1291d63bddc27e50e diff --git a/packages/compaction/compaction-basic/README.md b/packages/compaction/compaction-basic/README.md index 5b6f6c3544..e2da58b074 100644 --- a/packages/compaction/compaction-basic/README.md +++ b/packages/compaction/compaction-basic/README.md @@ -59,12 +59,13 @@ You can verify success by watching the conversation continue past the point wher ### Tuning when condensation starts -All settings are optional. The defaults start condensing at 80% of the routed model's message budget — its context window minus the output tokens one request reserves — and keep the newest 16% of that budget verbatim; the table below is the complete policy surface, and the generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-compaction-basic) is the exhaustive source. +All settings are optional. With context window `W`, effective request output cap `O`, and headroom `B`, the default trigger is `floor(min(W × 0.8, W − O − B))`, where `B = 65,536` tokens. Retention keeps the newest 16% of `W − O` verbatim. The table below lists every setting; the generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-compaction-basic) also includes their types. | Field | Default | Meaning | |---|---|---| -| `thresholdRatio` | `0.8` | Start condensing at `floor(messageBudget × ratio)`, where `messageBudget` is the routed context window minus the output tokens one request reserves. | -| `retainRatio` | `0.16` | Recent conversation kept verbatim as a fraction of that same message budget; mutually exclusive with `retainTokens`. | +| `thresholdRatio` | `0.8` | Window fraction used in `floor(min(W × thresholdRatio, W − O − headroomTokens))`. | +| `headroomTokens` | `65536` | Additional pressure headroom beyond the routed output reservation; a non-negative integer. | +| `retainRatio` | `0.16` | Recent conversation kept verbatim as a fraction of `W − O`; mutually exclusive with `retainTokens`. | | `retainTokens` | — | Absolute recent-conversation budget kept verbatim; mutually exclusive with `retainRatio` and must be below the resolved threshold. | | `summarizationProvider` | `''` | Set together with `summarizationModel`; an empty pair uses the latest routed request target, then the `AgentOptions` pair. | | `summarizationModel` | `''` | Set together with `summarizationProvider`; an empty pair uses the latest routed request target, then the `AgentOptions` pair. | @@ -74,7 +75,7 @@ All settings are optional. The defaults start condensing at 80% of the routed mo | `modelPolicies` | `[]` | Exact `{ provider, model, ...partialPolicy }` overrides for individual model routes. | | `auto` | `true` | Enable automatic condensation and overflow recovery; set `false` for manual-only operation. | -Misconfiguration fails fast: an unknown setting, a duplicate per-model override, both retention forms together, or a ratio retention that is not below the threshold all reject the plugin at load. An absolute `retainTokens` budget — top-level or per-model — that is not below its threshold fails when that model is first used, because the comparison needs the model's message budget. Proactive pressure requires the adapter model's `contextWindow` to exceed the effective request `maxTokens`. To compact earlier, lower `thresholdRatio` or an exact `modelPolicies` override; a reduced `contextWindow` must still leave room for messages after the output reservation. +Misconfiguration fails fast: unknown settings, duplicate per-model overrides, invalid token counts, both retention forms together, or a retention ratio at least as large as the threshold ratio reject the plugin at load. When the model is first used, `W − O − B` must be positive and the resolved retained budget must be below the trigger. Small-window deployments must configure headroom that fits their capacity; lower `thresholdRatio` to compact earlier. ### What happens when condensation runs @@ -111,7 +112,7 @@ The backend is built on four commitments: With `auto: true`, a serial `agent/pre-step` listener checks pressure before request derivation: it prices the latest durable routed request envelope through `ctx.tokenMeter`, and when pressure crosses the routed model's threshold it prunes, then summarizes the oldest balanced span while keeping a priced recent tail. Every selected range starts at the first surface node that is not a `system/message`, so a system prompt at surface node 0 is never shadowed; a later `system/message` appended by an in-history prompt update is ordinary history that the range may shadow, and the agent loop's projection then replaces node 0 with the current prompt when their text differs ([decision rule](../../core/agent-loop/README.md#understand-the-implementation)). The `agent/request-error` listener reacts to a provider-confirmed `CONTEXT_WINDOW_EXCEEDED`: it bypasses the normal threshold and retention policy, attempts one maximal balanced head reduction, and authorizes a retry only after the surface replacement generation advances. Cancellation stays authoritative throughout. -Pressure policy resolves capacity from the adapter that owns the durable route. Missing capacity, an output reservation at least as large as the window, or an absolute retention budget at least as large as the threshold makes the manual pressure path throw a target-specific configuration error. The automatic listener warns once for that exact target and skips proactive compaction until its configuration is corrected; provider-confirmed overflow recovery remains available. +Pressure policy resolves capacity from the adapter that owns the durable route. Missing capacity, output plus headroom exhausting the window, or a retained budget at least as large as the threshold makes the manual pressure path throw a target-specific configuration error. The automatic listener warns once for that exact target and skips proactive compaction until its configuration is corrected; provider-confirmed overflow recovery remains available. ### Summarization mechanics @@ -125,7 +126,7 @@ The transaction validates the surface span and the durable lock, appends `compac ### Config resolution -`resolveConfig` validates and detaches the defaults, `resolveTargetPolicy` merges an exact provider/model override over them, and `resolveCompactSpec` scales the merged policy into concrete token budgets using the adapter-owned context capacity minus the routed request’s reserved output tokens. Model discovery (`listModels()`) is never consulted for policy; only the durable route's capacity matters. +`resolveConfig` validates and detaches defaults, `resolveTargetPolicy` merges exact provider/model overrides, and `resolveCompactSpec` resolves the trigger and retained budget using adapter capacity and the routed request’s output reservation. The effective envelope’s `maxTokens` supplies that reservation, falling back to the adapter default and then zero. Model discovery (`listModels()`) is never consulted for policy; only the durable route's capacity matters. ### Source map diff --git a/packages/compaction/compaction-basic/README.zh.md b/packages/compaction/compaction-basic/README.zh.md index 6c9effbae4..de53683b15 100644 --- a/packages/compaction/compaction-basic/README.zh.md +++ b/packages/compaction/compaction-basic/README.zh.md @@ -59,12 +59,13 @@ kind: "package-reference" ### 调整压缩开始的时机 -所有设置都可选。默认在对话达到已路由模型消息预算的 80% 处开始压缩——消息预算即其上下文窗口减去单次请求预留的输出 token——并逐字保留该预算最新的 16%;下表是完整的策略面,生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-compaction-basic)是穷尽式真源。 +所有设置都可选。设上下文窗口为 `W`、生效请求输出上限为 `O`、余量为 `B`,默认触发阈值为 `floor(min(W × 0.8, W − O − B))`,其中 `B = 65,536` tokens。逐字保留的近期历史预算仍为 `W − O` 的 16%。下表列出全部设置;生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-compaction-basic)还包含字段类型。 | 字段 | 默认值 | 含义 | |---|---|---| -| `thresholdRatio` | `0.8` | 在 `floor(messageBudget × ratio)` 处开始压缩,其中 `messageBudget` 为已路由上下文窗口减去单次请求预留的输出 token。 | -| `retainRatio` | `0.16` | 以同一消息预算的一部分表示逐字保留的近期对话;与 `retainTokens` 互斥。 | +| `thresholdRatio` | `0.8` | 用于 `floor(min(W × thresholdRatio, W − O − headroomTokens))` 的窗口比例。 | +| `headroomTokens` | `65536` | 路由请求输出预留之外的额外压力余量;必须为非负整数。 | +| `retainRatio` | `0.16` | 以 `W − O` 的一部分表示逐字保留的近期对话;与 `retainTokens` 互斥。 | | `retainTokens` | — | 逐字保留的近期对话绝对预算;与 `retainRatio` 互斥,并且必须低于已解析阈值。 | | `summarizationProvider` | `''` | 与 `summarizationModel` 一起设置;空对使用最新已路由请求目标,再回退到 `AgentOptions` 对。 | | `summarizationModel` | `''` | 与 `summarizationProvider` 一起设置;空对使用最新已路由请求目标,再回退到 `AgentOptions` 对。 | @@ -74,7 +75,7 @@ kind: "package-reference" | `modelPolicies` | `[]` | 针对个别模型路由的精确 `{ provider, model, ...partialPolicy }` 覆盖。 | | `auto` | `true` | 启用自动压缩与溢出恢复;设为 `false` 则仅手动执行。 | -配置错误会快速失败:未知设置、重复的按模型覆盖、两种保留形式同时出现,或比例保留量不低于阈值,都会在加载时拒绝插件。任何绝对 `retainTokens` 预算——顶层或按模型——不低于其阈值时,都会在该模型首次使用时失败,因为该比较需要模型的消息预算。主动压力检查要求适配器模型的 `contextWindow` 大于生效请求的 `maxTokens`。要提早压缩,应降低 `thresholdRatio` 或精确的 `modelPolicies` 覆盖值;缩小后的 `contextWindow` 仍须在扣除输出预留后为消息留出空间。 +配置错误会快速失败:未知设置、重复的按模型覆盖、无效 token 数、两种保留形式同时出现,或保留比例不小于阈值比例,都会在加载时拒绝插件。模型首次使用时,`W − O − B` 必须为正,且解析出的保留预算必须低于触发阈值。小窗口部署必须配置适合其容量的余量;降低 `thresholdRatio` 可以提早压缩。 ### 压缩运行时会发生什么 @@ -111,7 +112,7 @@ kind: "package-reference" 当 `auto: true` 时,串行 `agent/pre-step` listener 会在请求派生前检查压力:它通过 `ctx.tokenMeter` 为最新持久路由请求 envelope 定价,当压力越过路由模型的阈值时,先剪枝,再在保留已定价近期尾部的同时摘要最旧的平衡范围。每个选定范围都从第一个不是 `system/message` 的 surface 节点开始,因此位于 surface 节点 0 的系统提示词永不会被遮蔽;由历史内提示词更新追加的后续 `system/message` 是普通历史,范围可以遮蔽它,agent loop(智能体循环)的投影随后会在二者文本不同时用当前提示词替换节点 0([决策规则](../../core/agent-loop/README.zh.md#understand-the-implementation))。`agent/request-error` listener 响应提供方确认的 `CONTEXT_WINDOW_EXCEEDED`:它绕过常规阈值与保留策略,尝试一次最大平衡头部缩减,并且只在表层替换 generation 前进后才授权重试。取消全程保持最终决定权。 -压力策略从拥有持久路由的适配器解析容量。容量缺失、输出预留不小于窗口,或绝对保留预算不小于阈值时,手动压力路径会抛出目标特定配置错误。自动 listener 会对该精确目标警告一次,并在配置修正前跳过主动压缩;提供方确认溢出后的恢复仍然可用。 +压力策略从拥有持久路由的适配器解析容量。容量缺失、输出预留与余量耗尽窗口,或保留预算不小于阈值时,手动压力路径会抛出目标特定配置错误。自动 listener 会对该精确目标警告一次,并在配置修正前跳过主动压缩;提供方确认溢出后的恢复仍然可用。 ### 摘要机制 @@ -125,7 +126,7 @@ kind: "package-reference" ### 配置解析 -`resolveConfig` 验证并分离默认值,`resolveTargetPolicy` 将精确的提供方/模型覆盖合并到默认值之上,`resolveCompactSpec` 使用适配器拥有的上下文容量减去路由请求预留的输出 token,将合并后的策略缩放为具体 token 预算。策略解析绝不咨询模型发现(`listModels()`);只有持久路由的容量才重要。 +`resolveConfig` 验证并分离默认值,`resolveTargetPolicy` 合并精确的提供方/模型覆盖,`resolveCompactSpec` 使用适配器容量与路由请求的输出预留解析触发阈值和保留预算。预留取自生效信封的 `maxTokens`,否则回退到适配器默认值,再回退到零。策略解析绝不咨询模型发现(`listModels()`);只有持久路由的容量才重要。 ### 源码地图 diff --git a/packages/compaction/compaction-basic/src/config.ts b/packages/compaction/compaction-basic/src/config.ts index 02967ecf82..f69e16a632 100644 --- a/packages/compaction/compaction-basic/src/config.ts +++ b/packages/compaction/compaction-basic/src/config.ts @@ -25,6 +25,7 @@ const DEFAULT_RETAIN_RATIO = 0.16 /** Fields shared by top-level defaults and exact-target overrides. */ const POLICY_CONFIG_KEYS = [ 'thresholdRatio', + 'headroomTokens', 'retainRatio', 'retainTokens', 'summarizationProvider', @@ -85,6 +86,7 @@ export function resolveConfig(config: BasicCompactionConfig = {}): ResolvedConfi return deepFreeze({ thresholdRatio, + headroomTokens: config.headroomTokens ?? 65_536, ...retention, summarizationProvider: config.summarizationProvider ?? '', summarizationModel: config.summarizationModel ?? '', @@ -115,6 +117,7 @@ export function resolveTargetPolicy( return deepFreeze({ target: { provider: target.provider, model: target.model }, thresholdRatio: override?.thresholdRatio ?? config.thresholdRatio, + headroomTokens: override?.headroomTokens ?? config.headroomTokens, ...resolveRetention(override ?? {}, inheritedRetention), summarizationProvider: override?.summarizationProvider ?? config.summarizationProvider, summarizationModel: override?.summarizationModel ?? config.summarizationModel, @@ -127,12 +130,9 @@ export function resolveTargetPolicy( /** * Scale one routed policy into concrete token budgets for its model capacity. * - * A routed request reserves output tokens that the provider charges to the same - * window as the prompt, so only the capacity left after that reservation is - * available to messages. Both budgets scale that message budget: scaling the - * whole window instead would place the pressure gate above the point where the - * provider starts rejecting the request, leaving proactive compaction - * unreachable. + * Pressure is capped by both the window fraction and the capacity remaining + * after the routed output reservation plus compaction headroom. Retention scales + * the message budget before headroom is deducted. * * @param policy - merged policy for the exact routed target. * @param contextWindow - positive adapter-owned capacity for that target. @@ -167,7 +167,20 @@ export function resolveCompactSpec( + "the adapter model's contextWindow above the effective request maxTokens", ) } - const thresholdTokens = Math.floor(messageBudgetTokens * policy.thresholdRatio) + const pressureBudgetTokens = messageBudgetTokens - policy.headroomTokens + if (pressureBudgetTokens <= 0) { + throw new TargetPressureConfigError( + targetKey, + `compaction-basic: ${targetKey} reserves ${reservedCompletionTokens} completion tokens ` + + `and ${policy.headroomTokens} headroom tokens of its ${contextWindow}-token context ` + + 'window, leaving no pressure budget; reduce the effective request maxTokens or ' + + 'compaction headroomTokens, or configure a larger adapter model contextWindow', + ) + } + const thresholdTokens = Math.floor(Math.min( + contextWindow * policy.thresholdRatio, + pressureBudgetTokens, + )) const retainTokens = policy.retainTokens === undefined ? Math.floor(messageBudgetTokens * policy.retainRatio) : policy.retainTokens @@ -255,12 +268,14 @@ function validatePolicy( name: string, ): void { const thresholdRatio = config.thresholdRatio + const headroomTokens = config.headroomTokens const retainRatio = config.retainRatio const retainTokens = config.retainTokens const maxTokens = config.maxTokens const compactionRetries = config.compactionRetries const maxOverflowRetries = config.maxOverflowRetries if (thresholdRatio !== undefined) assertRatio(`${name}.thresholdRatio`, thresholdRatio) + if (headroomTokens !== undefined) assertNonNegativeInteger(`${name}.headroomTokens`, headroomTokens) if (retainRatio !== undefined) assertRatio(`${name}.retainRatio`, retainRatio) if (retainTokens !== undefined) assertNonNegativeInteger(`${name}.retainTokens`, retainTokens) if (retainRatio !== undefined && retainTokens !== undefined) { diff --git a/packages/compaction/compaction-basic/src/index.ts b/packages/compaction/compaction-basic/src/index.ts index a6d8b21177..163cec3810 100644 --- a/packages/compaction/compaction-basic/src/index.ts +++ b/packages/compaction/compaction-basic/src/index.ts @@ -79,6 +79,7 @@ function conversationTarget( } const thresholdRatioSchema = z.number() +const headroomTokensSchema = z.number().step(1).min(0) const retainRatioSchema = z.number() const retainTokensSchema = z.number().step(1).min(0) const summarizationProviderSchema = z.string() @@ -91,6 +92,7 @@ const modelPolicy: z = z.object({ provider: z.string().required(), model: z.string().required(), thresholdRatio: thresholdRatioSchema, + headroomTokens: headroomTokensSchema, retainRatio: retainRatioSchema, retainTokens: retainTokensSchema, summarizationProvider: summarizationProviderSchema, @@ -113,6 +115,7 @@ export class BasicCompactionEngine extends CompactionEngine { static Config: z = z.object({ thresholdRatio: thresholdRatioSchema, + headroomTokens: headroomTokensSchema, retainRatio: retainRatioSchema, retainTokens: retainTokensSchema, summarizationProvider: summarizationProviderSchema, diff --git a/packages/compaction/compaction-basic/src/types.ts b/packages/compaction/compaction-basic/src/types.ts index 2d88f28d42..e72f69b607 100644 --- a/packages/compaction/compaction-basic/src/types.ts +++ b/packages/compaction/compaction-basic/src/types.ts @@ -8,9 +8,11 @@ import type { LlmCallConfig } from '@deepseek-ai/dsh-llm' /** Policy fields shared by the default policy and exact model overrides. */ export interface CompactionPolicyConfig { - /** Compact at this fraction of the model's message budget: context window minus reserved output tokens. Defaults to `0.8`. */ + /** Window fraction for pressure; capped at context window minus reserved output and `headroomTokens`. Defaults to `0.8`. */ thresholdRatio?: number - /** Recent context retained as a fraction of that same message budget. Defaults to `0.16`. */ + /** Additional pressure headroom beyond the routed output reservation. Non-negative integer; defaults to `65536`. */ + headroomTokens?: number + /** Recent context retained as a fraction of context window minus reserved output tokens. Defaults to `0.16`. */ retainRatio?: number /** Absolute recent-context budget; mutually exclusive with `retainRatio`. */ retainTokens?: number @@ -50,6 +52,7 @@ export type ResolvedRetention = /** Validated policy fields shared before and after exact-target matching. */ interface ResolvedPolicyFields { readonly thresholdRatio: number + readonly headroomTokens: number readonly summarizationProvider: string readonly summarizationModel: string readonly maxTokens: number @@ -69,7 +72,7 @@ export type ResolvedTargetPolicy = ResolvedPolicyFields & ResolvedRetention & { } /** One routed model's concrete pressure and retention budget. */ -export type ResolvedCompactSpec = Omit & { +export type ResolvedCompactSpec = Omit & { /** Adapter-declared full window; token budgets below exclude reserved output tokens. */ readonly contextWindow: number readonly thresholdTokens: number diff --git a/packages/compaction/compaction-basic/tests/compaction-basic.spec.ts b/packages/compaction/compaction-basic/tests/compaction-basic.spec.ts index 2dec47aab7..e47e802254 100644 --- a/packages/compaction/compaction-basic/tests/compaction-basic.spec.ts +++ b/packages/compaction/compaction-basic/tests/compaction-basic.spec.ts @@ -294,7 +294,7 @@ function service( config: BasicCompactionConfig = { auto: false }, ctx = createContext(), ): TestCompactionEngine { - return new TestCompactionEngine(ctx, config) + return new TestCompactionEngine(ctx, { headroomTokens: 0, ...config }) } async function compactIfNeeded( @@ -312,6 +312,7 @@ describe('compact configuration and defaults', () => { expect(resolved).toEqual({ thresholdRatio: 0.8, + headroomTokens: 65_536, retainRatio: 0.16, summarizationProvider: '', summarizationModel: '', @@ -345,12 +346,14 @@ describe('compact configuration and defaults', () => { it('merges exact provider/model policy overrides and scales ratios per model', () => { const config = resolveConfig({ + headroomTokens: 0, thresholdRatio: 0.8, retainRatio: 0.1, modelPolicies: [{ provider: 'small-provider', model: 'shared-id', thresholdRatio: 0.5, + headroomTokens: 600, retainTokens: 120, }], }) @@ -364,7 +367,7 @@ describe('compact configuration and defaults', () => { }) expect(resolveCompactSpec(small, 1_000)).toMatchObject({ - thresholdTokens: 500, + thresholdTokens: 400, retainTokens: 120, }) expect(resolveCompactSpec(otherProvider, 2_000)).toMatchObject({ @@ -373,6 +376,7 @@ describe('compact configuration and defaults', () => { }) const ratioOverride = resolveTargetPolicy(resolveConfig({ + headroomTokens: 0, retainTokens: 200, modelPolicies: [{ provider: 'ratio-provider', @@ -397,26 +401,37 @@ describe('compact configuration and defaults', () => { }) }) - it('scales both budgets by the message budget left after the reserved completion tokens', () => { - const policy = resolveTargetPolicy(resolveConfig({ - thresholdRatio: 0.8, - retainRatio: 0.16, - }), { provider: MODEL, model: MODEL }) + it.each([ + [1_048_576, 256_000, 727_040, 126_812], + [1_000_000, 0, 800_000, 160_000], + [1_000_000, 100_000, 800_000, 144_000], + [1_000_000, 134_464, 800_000, 138_485], + [1_000_000, 256_000, 678_464, 119_040], + ])('reserves 64K headroom in window %i with output cap %i', (window, output, threshold, retained) => { + const policy = resolveTargetPolicy(resolveConfig({}), { provider: MODEL, model: MODEL }) - // 1_048_576 - 256_000 = 792_576 available to messages: a 256_000-token - // reserve must not leave the gate (838_860 on the whole window) above the - // point where the provider rejects the request. - expect(resolveCompactSpec(policy, 1_048_576, 256_000)).toMatchObject({ - contextWindow: 1_048_576, - thresholdTokens: 634_060, - retainTokens: 126_812, + expect(resolveCompactSpec(policy, window, output)).toMatchObject({ + contextWindow: window, + thresholdTokens: threshold, + retainTokens: retained, }) + }) - // An undeclared reserve leaves the whole window available. - expect(resolveCompactSpec(policy, 1_000)).toMatchObject({ - thresholdTokens: 800, - retainTokens: 160, - }) + it('uses the window fraction when output is unspecified', () => { + const policy = resolveTargetPolicy(resolveConfig({}), { provider: MODEL, model: MODEL }) + expect(resolveCompactSpec(policy, 1_000_000).thresholdTokens).toBe(800_000) + }) + + it.each([500, 501])('rejects headroom %i that exhausts the remaining capacity', (headroomTokens) => { + const policy = resolveTargetPolicy(resolveConfig({ headroomTokens }), { provider: MODEL, model: MODEL }) + expect(() => resolveCompactSpec(policy, 1_000, 500)) + .toThrow(/headroom tokens.*leaving no pressure budget/) + }) + + it('rejects ratio retention that reaches the headroom-limited threshold', () => { + const policy = resolveTargetPolicy(resolveConfig({ headroomTokens: 420 }), { provider: MODEL, model: MODEL }) + expect(() => resolveCompactSpec(policy, 1_000, 500)) + .toThrow(/retainTokens \(80\) must be less than threshold tokens 80/) }) it('rejects a reserve that leaves no message budget or is not a count', () => { @@ -470,6 +485,10 @@ describe('compact configuration and defaults', () => { it('validates common values and pressure-policy invariants', () => { const bad = [ [{ maxTokens: 0 }, /maxTokens/], + [{ headroomTokens: -1 }, /headroomTokens.*non-negative integer/], + [{ headroomTokens: 0.5 }, /headroomTokens.*non-negative integer/], + [{ headroomTokens: '65536' }, /headroomTokens.*non-negative integer/], + [{ modelPolicies: [{ provider: MODEL, model: MODEL, headroomTokens: -1 }] }, /headroomTokens.*non-negative integer/], [{ compactionRetries: -1 }, /compactionRetries/], [{ maxOverflowRetries: -1 }, /maxOverflowRetries/], [{ auto: 'yes' }, /auto must be a boolean/], @@ -523,6 +542,7 @@ describe('compact configuration and defaults', () => { } const invalidPressure = resolveTargetPolicy(resolveConfig({ + headroomTokens: 0, thresholdRatio: 0.5, retainTokens: 500, }), { provider: MODEL, model: MODEL }) @@ -611,9 +631,8 @@ describe('pressure measurement and retention', () => { expect(measured).toBeLessThan(800) await expect(compactIfNeeded(compact, session)).resolves.toBeNull() - // The same pressure exceeds 80% of the budget left once the request - // reserves its output tokens: a gate scaled by the whole window would miss it. - const maxTokens = 1_000 - Math.floor(measured / 0.8) - 1 + // The output reservation lowers the threshold below the measured history. + const maxTokens = 1_000 - measured + 1 session.append('request/header', { header: { config: { provider: MODEL, model: MODEL, maxTokens } }, reason: 'change', @@ -633,7 +652,7 @@ describe('pressure measurement and retention', () => { id: model, name: model, context: { contextWindow: 1_000 }, - defaultMaxTokens: 1_000 - Math.floor(measured / 0.8) - 1, + defaultMaxTokens: 1_000 - measured + 1, })) await expect(compactIfNeeded(compact, session)).resolves.not.toBeNull() @@ -908,6 +927,7 @@ describe('optional model-free tool-result pruning', () => { const ctx = createContext(10_000) const prune = new ToolResultPruner(ctx, pruneConfig) const compact = new TestCompactionEngine(ctx, { + headroomTokens: 0, auto: false, thresholdRatio: 0.8, retainTokens: 100, @@ -925,6 +945,7 @@ describe('optional model-free tool-result pruning', () => { const ctx = createContext(1_000) void new ToolResultPruner(ctx, pruneConfig) const compact = new TestCompactionEngine(ctx, { + headroomTokens: 0, auto: false, thresholdRatio: 0.5, retainTokens: 50, @@ -942,6 +963,7 @@ describe('optional model-free tool-result pruning', () => { const ctx = createContext(2_000) void new ToolResultPruner(ctx, pruneConfig) const compact = new TestCompactionEngine(ctx, { + headroomTokens: 0, auto: false, thresholdRatio: 0.5, retainTokens: 50, @@ -957,6 +979,7 @@ describe('optional model-free tool-result pruning', () => { it('retains the original compaction-basic behavior without the optional plugin', async () => { const ctx = createContext(2_000) const compact = new TestCompactionEngine(ctx, { + headroomTokens: 0, auto: false, thresholdRatio: 0.5, retainTokens: 50, @@ -1653,6 +1676,7 @@ describe('automatic listener and loader composition', () => { it('compacts before a step above threshold using the durable routed model and remains idle below it', async () => { const ctx = createContext() const compact = new TestCompactionEngine(ctx, { + headroomTokens: 0, thresholdRatio: 0.5, retainTokens: 180, }) @@ -1669,6 +1693,7 @@ describe('automatic listener and loader composition', () => { it('skips pre-step pressure when the step signal is already aborted', async () => { const ctx = createContext() const compact = new TestCompactionEngine(ctx, { + headroomTokens: 0, thresholdRatio: 0.5, retainTokens: 180, }) @@ -1687,6 +1712,7 @@ describe('automatic listener and loader composition', () => { const warnings: string[] = [] ctx.logger.warn = ((message: string) => void warnings.push(message)) as typeof ctx.logger.warn const compact = new TestCompactionEngine(ctx, { + headroomTokens: 0, thresholdRatio: 0.5, retainTokens: 180, }) @@ -1708,6 +1734,7 @@ describe('automatic listener and loader composition', () => { name: model, })) void new TestCompactionEngine(ctx, { + headroomTokens: 0, thresholdRatio: 0.5, retainTokens: 180, }) @@ -1726,6 +1753,7 @@ describe('automatic listener and loader composition', () => { const warnings: string[] = [] ctx.logger.warn = ((message: string) => void warnings.push(message)) as typeof ctx.logger.warn void new TestCompactionEngine(ctx, { + headroomTokens: 0, thresholdRatio: 0.5, retainTokens: 500, }) @@ -1768,6 +1796,7 @@ describe('automatic listener and loader composition', () => { it('force-compacts below normal pressure for canonical overflow and retries only after replacement', async () => { const ctx = createContext(10_000) void new TestCompactionEngine(ctx, { + headroomTokens: 0, thresholdRatio: 1, retainTokens: 900, }) @@ -1792,6 +1821,7 @@ describe('automatic listener and loader composition', () => { tailChars: 10, }) const compact = new TestCompactionEngine(ctx, { + headroomTokens: 0, thresholdRatio: 1, retainTokens: 900, }) @@ -1811,6 +1841,7 @@ describe('automatic listener and loader composition', () => { tailChars: 10, }) const compact = new TestCompactionEngine(ctx, { + headroomTokens: 0, thresholdRatio: 1, retainTokens: 900, }) @@ -1832,6 +1863,7 @@ describe('automatic listener and loader composition', () => { tailChars: 10, }) const compact = new TestCompactionEngine(ctx, { + headroomTokens: 0, thresholdRatio: 1, retainTokens: 900, }) @@ -1855,6 +1887,7 @@ describe('automatic listener and loader composition', () => { tailChars: 10, }) const compact = new TestCompactionEngine(ctx, { + headroomTokens: 0, thresholdRatio: 1, retainTokens: 900, }) @@ -1869,6 +1902,7 @@ describe('automatic listener and loader composition', () => { it('preserves the newest whole tool-call/result pair during forced overflow compaction', async () => { const ctx = createContext() void new TestCompactionEngine(ctx, { + headroomTokens: 0, thresholdRatio: 1, retainTokens: 90, }) @@ -2006,6 +2040,7 @@ describe('automatic listener and loader composition', () => { it('applies the routed model override to the overflow retry cap', async () => { const ctx = createContext() const compact = new TestCompactionEngine(ctx, { + headroomTokens: 0, maxOverflowRetries: 2, modelPolicies: [{ provider: MODEL, @@ -2037,6 +2072,7 @@ describe('automatic listener and loader composition', () => { it('maxOverflowRetries:0 disables recovery without disabling post-step pressure', async () => { const ctx = createContext() void new TestCompactionEngine(ctx, { + headroomTokens: 0, maxOverflowRetries: 0, thresholdRatio: 0.5, retainTokens: 180, @@ -2052,6 +2088,7 @@ describe('automatic listener and loader composition', () => { it('auto:false installs neither automatic listener', async () => { const ctx = createContext() void new TestCompactionEngine(ctx, { + headroomTokens: 0, auto: false, thresholdRatio: 0.5, retainTokens: 180, @@ -2216,6 +2253,7 @@ describe('route-priced image pressure', () => { const session = imageConversation() const before = ctx.tokenMeter.measure(session) const compact = new TestCompactionEngine(ctx, { + headroomTokens: 0, auto: false, thresholdRatio: 0.8, retainTokens: 350, diff --git a/packages/compaction/compaction-basic/tests/compaction-loop-repro.spec.ts b/packages/compaction/compaction-basic/tests/compaction-loop-repro.spec.ts index decedf019e..b6c8ff7f86 100644 --- a/packages/compaction/compaction-basic/tests/compaction-loop-repro.spec.ts +++ b/packages/compaction/compaction-basic/tests/compaction-loop-repro.spec.ts @@ -165,6 +165,7 @@ async function harness(toolSteps: number): Promise<{ ctx: Context; compact: Repr // fires within the runaway turn after enough history can shrink. const compact = new ReproCompactionEngine(ctx, { auto: true, + headroomTokens: 0, thresholdRatio: 0.5, retainTokens: 50, maxTokens: 8192, @@ -396,6 +397,7 @@ describe('context-overflow recovery across the real loop and compaction-basic', ...await next(), provider: 'mock', model: 'mock', })) await ctx.plugin(BasicCompactionEngine, { + headroomTokens: 0, thresholdRatio: 1, retainTokens: 100, maxTokens: 64, @@ -472,6 +474,7 @@ describe('context-overflow recovery across the real loop and compaction-basic', await ctx.plugin(TokenMeter) ctx.llm.registerAdapter(['mock'], adapter) await ctx.plugin(BasicCompactionEngine, { + headroomTokens: 0, thresholdRatio: 1, retainTokens: 100, maxTokens: 64, diff --git a/packages/compaction/compaction-basic/tests/loader-composition.spec.ts b/packages/compaction/compaction-basic/tests/loader-composition.spec.ts index 1fc9d86bf9..89eaf0ae78 100644 --- a/packages/compaction/compaction-basic/tests/loader-composition.spec.ts +++ b/packages/compaction/compaction-basic/tests/loader-composition.spec.ts @@ -70,6 +70,11 @@ describe('real Loader composition', () => { "- name: '@deepseek-ai/dsh-compaction-basic'", ' config:', ' thresholdRatio: 0.5', + ' headroomTokens: 4000', + ' modelPolicies:', + ' - provider: mock', + ' model: small', + ' headroomTokens: 0', ' retainRatio: 0.125', ' auto: false', ]) @@ -82,6 +87,8 @@ describe('real Loader composition', () => { expect(loaded.get('compaction')).toBeInstanceOf(BasicCompactionEngine) expect((loaded.compaction as unknown as BasicCompactionEngine).config).toMatchObject({ thresholdRatio: 0.5, + headroomTokens: 4000, + modelPolicies: [{ provider: 'mock', model: 'small', headroomTokens: 0 }], retainRatio: 0.125, auto: false, }) diff --git a/packages/llm/llm-deepseek/README.i18n.yaml b/packages/llm/llm-deepseek/README.i18n.yaml index 76d2605857..3828ea8ca8 100644 --- a/packages/llm/llm-deepseek/README.i18n.yaml +++ b/packages/llm/llm-deepseek/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/llm/llm-deepseek/README.md -README.md: cdbb9c92d13bc42ae634579898e1e49a50df554b -README.zh.md: 0c224fbf823ba00e8c9f172e2b48fef2ed9edb2c +README.md: 2cc1f6696377de63b4f086fb23ecf82c8b17ebf4 +README.zh.md: ec38566505ae83f6198b7e2ae1cccca925602c21 diff --git a/packages/llm/llm-deepseek/README.md b/packages/llm/llm-deepseek/README.md index cdbb9c92d1..2cc1f66963 100644 --- a/packages/llm/llm-deepseek/README.md +++ b/packages/llm/llm-deepseek/README.md @@ -74,7 +74,7 @@ A request selects the route with `provider: deepseek-official`; the model id pas The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-llm-deepseek) is the exhaustive source for every accepted field and its JSDoc. -When [proactive compaction](../../compaction/compaction-basic/README.md#use-this-package) is enabled, `models[].contextWindow` (or `defaultContextWindow` when absent) must exceed the effective request `maxTokens` to leave a message budget. Requests without an explicit output cap use the model’s `maxTokens` or the adapter default. To compact earlier, lower the compaction policy’s `thresholdRatio` instead of shrinking the declared window below the output reservation. +When [proactive compaction](../../compaction/compaction-basic/README.md#use-this-package) is enabled, `models[].contextWindow` (or `defaultContextWindow` when absent) must exceed the effective request `maxTokens` plus the compaction policy’s `headroomTokens`. Requests without an explicit output cap use the model’s `maxTokens` or the adapter default. For small-window deployments, configure headroom within that capacity; lower `thresholdRatio` to compact earlier. ### Choose a protocol diff --git a/packages/llm/llm-deepseek/README.zh.md b/packages/llm/llm-deepseek/README.zh.md index 0c224fbf82..ec38566505 100644 --- a/packages/llm/llm-deepseek/README.zh.md +++ b/packages/llm/llm-deepseek/README.zh.md @@ -74,7 +74,7 @@ kind: "package-reference" 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-llm-deepseek)是每个受支持字段及其 JSDoc 的穷尽式真源。 -启用[主动压缩](../../compaction/compaction-basic/README.zh.md#use-this-package)时,`models[].contextWindow`(未声明时使用 `defaultContextWindow`)必须大于生效请求的 `maxTokens`,才能留出消息预算。请求未覆盖输出上限时,使用模型的 `maxTokens` 或适配器默认值。要提早压缩,应降低压缩策略的 `thresholdRatio`,而不是把声明的窗口缩到输出预留以下。 +启用[主动压缩](../../compaction/compaction-basic/README.zh.md#use-this-package)时,`models[].contextWindow`(未声明时使用 `defaultContextWindow`)必须大于生效请求的 `maxTokens` 与压缩策略 `headroomTokens` 之和。请求未覆盖输出上限时,使用模型的 `maxTokens` 或适配器默认值。小窗口部署应在容量范围内配置余量;降低 `thresholdRatio` 可以提早压缩。 ### 选择协议 diff --git a/snapshots/acp/image-compaction/cordis.snapshot.yml b/snapshots/acp/image-compaction/cordis.snapshot.yml index 213a65ac8b..fe086bc2a0 100644 --- a/snapshots/acp/image-compaction/cordis.snapshot.yml +++ b/snapshots/acp/image-compaction/cordis.snapshot.yml @@ -61,6 +61,7 @@ - id: compaction-basic name: '@deepseek-ai/dsh-compaction-basic' config: + headroomTokens: 0 retainTokens: 100 - insert: diff --git a/snapshots/acp/image-compaction/cordis.yml b/snapshots/acp/image-compaction/cordis.yml index ee11ff4f15..f9f00214b1 100644 --- a/snapshots/acp/image-compaction/cordis.yml +++ b/snapshots/acp/image-compaction/cordis.yml @@ -39,6 +39,7 @@ - id: compaction-basic name: '@deepseek-ai/dsh-compaction-basic' config: + headroomTokens: 0 retainTokens: 100 - insert: diff --git a/snapshots/session/compaction-output-reserve/cordis.snapshot.yml b/snapshots/session/compaction-output-reserve/cordis.snapshot.yml index 1d7a9a2290..919837f420 100644 --- a/snapshots/session/compaction-output-reserve/cordis.snapshot.yml +++ b/snapshots/session/compaction-output-reserve/cordis.snapshot.yml @@ -1,5 +1,5 @@ -# A 1,000-token output reservation moves the proactive threshold from 8,000 -# to 7,200 tokens, between the complete history and its condensed replacement. +# With 1,800 tokens of headroom, a 1,000-token output reservation lowers the +# trigger from 8,000 to 7,200, between the history and its condensed replacement. - id: llm-deepseek name: '@deepseek-ai/dsh-llm-deepseek' @@ -15,6 +15,7 @@ name: '@deepseek-ai/dsh-compaction-basic' config: thresholdRatio: 0.8 + headroomTokens: 1800 retainTokens: 20 maxTokens: 32 diff --git a/snapshots/session/compaction-output-reserve/cordis.yml b/snapshots/session/compaction-output-reserve/cordis.yml index 7f99379eaa..6b78a0b41b 100644 --- a/snapshots/session/compaction-output-reserve/cordis.yml +++ b/snapshots/session/compaction-output-reserve/cordis.yml @@ -10,5 +10,6 @@ - id: compaction-basic config: thresholdRatio: 0.8 + headroomTokens: 1800 retainTokens: 20 maxTokens: 32