billion-context 0.1.203 → 0.1.204

package/CONFIGURATION.md

@@ -120,6 +120,13 @@ This index is generated from `website/config-reference/*.yaml` — edit the seed
 | `dsh.authoredCompaction` | boolean | true (on, #3901 flip) | BILI_DSH_AUTHORED_COMPACTION | bili answers dsh compaction summarize calls locally with the folded snapshot instead of refusing (#3723/#3733). ON by default since the 0.1.203 dogfood window held; false (or env BILI_DSH_AUTHORED_COMPACTION=0) restores the #1729 refusal path. |
 | `resign` | scheme → { enabled?, passthrough?, credentialRef? } | {} (armed; built-in scheme sdk-hmac-sha256) | BILI_RESIGN, BILI_RESIGN_PASSTHROUGH, BILI_CODEARTS_REF, BILI_RESIGN_BENEFIT | Re-sign arm keyed by Authorization scheme: signed model requests tunnel with every egress body re-signed; unresignable requests are refused locally 403 unless passthrough opts that scheme into verbatim forwarding. |
 | `promptCache.routing` | "auto" \| "enabled" \| "disabled" | auto | ACP_PROMPT_CACHE_ROUTING | Prompt-cache routing posture for cache-aware lane selection. |
+| `cacheKeepalive.enabled` | boolean | false | BILI_CACHE_KEEPALIVE | Master switch for idle prompt-cache keepalive on the Anthropic wire (#3376): while a session goes idle, bili replays the last forwarded body with max_tokens=1 on a TTL-derived cadence so the upstream prefix cache stays warm; hits are verified via usage.cache_read_input_tokens; stops on miss/429/error-streak/duration cap. Also settable per provider route and per model. |
+| `cacheKeepalive.ttlFactor` | number | 0.9 | BILI_CACHE_KEEPALIVE_TTL_FACTOR | Cadence factor applied to the detected/assumed cache TTL tier (ping interval = tier x factor; 0.9 gives roughly one ping per 4.5 min on the 5-min tier and per 54 min on the 1-hour tier). Must be in (0, 1]. |
+| `cacheKeepalive.maxDurationMs` | number | 86400000 | BILI_CACHE_KEEPALIVE_MAX_DURATION_MS | Per-session keepalive lifetime cap, measured from the session's last real request (default 24 h); past it, keepalive disarms even while still hitting. |
+| `cacheKeepalive.maxConcurrentPings` | number | 4 | BILI_CACHE_KEEPALIVE_MAX_PINGS | Cap on simultaneously armed sessions; when exceeded, the longest-idle armed session is evicted first. |
+| `cacheKeepalive.assumeTtl` | "5m" \| "1h" | null (detect from body breakpoints) | BILI_CACHE_KEEPALIVE_ASSUME_TTL | Skip body breakpoint detection and derive the cadence from this tier directly - for relays that inject or rewrite cache_control TTL downstream of bili, leaving the forwarded body breakpoint-less or mis-tiered. |
+| `cacheKeepalive.armWithoutBreakpoints` | boolean | false | BILI_CACHE_KEEPALIVE_ARM_WITHOUT_BREAKPOINTS | Arm keepalive even when the forwarded body carries no cache_control breakpoint at all (off by default - without breakpoints there is no explicit break-pointed content to refresh; pair with assumeTtl/intervalMs when your relay manages breakpoints itself). |
+| `cacheKeepalive.intervalMs` | number | null (derive from TTL tier) | BILI_CACHE_KEEPALIVE_INTERVAL_MS | Absolute ping interval in milliseconds; wins over ttlFactor, assumeTtl and the detected tier. For fixed cadences that do not follow the upstream TTL policy. |
 | `native.attachExternal` | boolean | false | BILI_NATIVE_ATTACH_EXTERNAL | Let launcher-less native plugins attach to an external (lane'd, unarmed) daemon instead of spawning their own. |
 | `native.attachLanePriority` | string[] | [] (own lane → user zone → spawn) | — | Ordered list of FOREIGN lane names a lane may ride when no own-lane instance exists (#2905). Own lane always wins first; the user zone (manual bili start, the 8787 global) is ALWAYS last; unlisted lanes stay non-attachable. File-only, no env var. |
 | `native.attachPolicy` | "own-lane" \| "global-fallback" | own-lane | BILI_NATIVE_ATTACH_POLICY | Lane affinity for native-hook attach, and the gate on whether any cross-lane riding happens (#2877). own-lane (default): a LANEd hook rides ONLY a same-lane daemon and, with none available, spawns its own instead of falling back onto a lane-less / manually-started bili start daemon or another lane's daemon (that convergence pinned every agent to one daemon's version and double-wrote sessions); an armed lane-less daemon (a managed shared proxy, #1225) stays shareable under either policy. global-fallback restores the pre-#2877 behavior: same-lane first, then a compatible lane-less/user-zone daemon, and (with attachLanePriority) the listed foreign lanes. |
@@ -632,6 +639,18 @@ Top-level keys that control how the proxy listens and behaves globally.
 - **Status:** ACTIVE
 - **Description:** Routing for Responses-wire `prompt_cache_key` stamping. An explicit client-supplied `prompt_cache_key` always wins untouched; otherwise bili stamps its own stable conversation-derived key subject to the mode: `"enabled"` = always stamp, `"disabled"` = never stamp, `"auto"` (default) = stamp only when the upstream host is exactly `api.openai.com`. Overridden by `ACP_PROMPT_CACHE_ROUTING`.
 
+### `cacheKeepalive`
+
+- **Type:** `{ enabled?: boolean, ttlFactor?: number, maxDurationMs?: number, maxConcurrentPings?: number, assumeTtl?: "5m" | "1h", armWithoutBreakpoints?: boolean, intervalMs?: number }`
+- **Default:** `{}` (feature off)
+- **Status:** ACTIVE (#3376)
+- **Description:** Idle-period prompt-cache keepalive for the Anthropic wire (#3376). Anthropic prefix caches expire on a TTL (5 min or 1 h per breakpoint); while a session sits idle (lunch break, overnight), the next real request pays a full-price cold rebuild of the cached prefix. When enabled, bili snapshots each session's last successfully forwarded request body — the exact bytes that reached upstream, `cache_control` breakpoints included — and, while the session stays idle, replays it with `max_tokens=1` on a TTL-derived cadence; a cache-hit response refreshes the TTL at the cost of one minimal completion. Every ping is verified against the upstream's own `usage.cache_read_input_tokens`: a hit reschedules the next ping; zero read tokens means the prefix is already dead and keepalive stops.
+  - **Arming.** Only successful (2xx) Anthropic-wire POSTs arm/refresh a snapshot. Passthrough requests, re-sign lanes (the stored signature would cover stale bytes), non-string bodies, bodies over 64 MiB, and bodies without any `cache_control` breakpoint never arm unless overridden below. Snapshots are in-memory only: a restart clears them and the next real request re-arms.
+  - **Cadence.** `tier × ttlFactor`, where tier is `1h` when any breakpoint declares `ttl: "1h"`, else `5m`; default factor `0.9` → roughly one ping per 4.5 min / 54 min. Override with `assumeTtl` (skip body detection — for relays that inject or rewrite `cache_control` TTL downstream of bili) or absolute `intervalMs` (wins over everything); `armWithoutBreakpoints: true` arms even breakpoint-less bodies (pairs with `assumeTtl`).
+  - **Stopping.** A real request for the session cancels immediately (it refreshes the cache itself); a ping whose tick lands while the session has an in-flight request defers ~5 s; `cache_read_input_tokens = 0` → stop (`prefix-dead`); HTTP 429 → stop immediately; 3 consecutive other errors → stop; more than `maxDurationMs` (default 24 h) since the session's last real request → stop; `maxConcurrentPings` (default 4) caps simultaneously armed sessions, evicting the longest-idle first.
+  - **Cost & observability.** Pings bypass the proxy pipeline entirely, so they never enter the `/acp-cache` hit-rate ledger (synthetic traffic must not pollute health verdicts) and they create no cache-attribution samples — miss-attribution math runs on exactly the same request sequence as without keepalive. Each arm/ping/disarm logs a `[keepalive] …` line; `acp_status` reports one `CACHE KEEPALIVE: armed tier=… cadence=… · pings=N [· last-hit Mm ago]` line for an armed session (absent when unarmed); the web UI shows a per-session keepalive badge plus a detail line, and its raw JSON config editor accepts this section directly (validated server-side on save).
+  - **Per-provider & per-model override.** Every field can also be set under a provider route (`providers.<url>.cacheKeepalive`) and under a specific model of that route (`providers.<url>.models.<model>.cacheKeepalive`) — different models behind one upstream can run different tiers/cadences. Per field, precedence is: env var > model > route > global block > built-in default.
+
 ### `autoUpdate`
 
 - **Type:** `boolean`
@@ -1717,6 +1736,13 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes
 | `BILI_ALLOW_DSH_COMPACTION` | `dsh` | {} |
 | `BILI_ALLOW_PRIVATE_HTTP_PROVIDERS` | `network.allowPrivateHttpProviders` | false |
 | `BILI_AUTO_MODE_FORGE` | `autoModeForge.enabled` | true |
+| `BILI_CACHE_KEEPALIVE` | `cacheKeepalive.enabled` | false |
+| `BILI_CACHE_KEEPALIVE_ARM_WITHOUT_BREAKPOINTS` | `cacheKeepalive.armWithoutBreakpoints` | false |
+| `BILI_CACHE_KEEPALIVE_ASSUME_TTL` | `cacheKeepalive.assumeTtl` | null (detect from body breakpoints) |
+| `BILI_CACHE_KEEPALIVE_INTERVAL_MS` | `cacheKeepalive.intervalMs` | null (derive from TTL tier) |
+| `BILI_CACHE_KEEPALIVE_MAX_DURATION_MS` | `cacheKeepalive.maxDurationMs` | 86400000 |
+| `BILI_CACHE_KEEPALIVE_MAX_PINGS` | `cacheKeepalive.maxConcurrentPings` | 4 |
+| `BILI_CACHE_KEEPALIVE_TTL_FACTOR` | `cacheKeepalive.ttlFactor` | 0.9 |
 | `BILI_CA_FILE` | `network.caFile` | unset |
 | `BILI_CCR_RETRIEVAL_TTL_MS` | `ccrRetrievalTtlMs` | 600000 (0 disables retrieval) |
 | `BILI_CHAIN_CONTENT` | `chainContentDetection` | false |
@@ -1882,6 +1908,13 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes
 | `BILI_ALLOW_DSH_COMPACTION` | **REMOVED in #3666** (superseding #2028). The former switch let dsh's built-in auto-compaction run through bili by lifting the wire-level refusal (#1729); because a landed dsh checkpoint durably shadows the raw conversation history — irreversible, destroying the proxy's compression substrate — the escape hatch has been deleted outright: dsh native compaction calls are now intercepted unconditionally on every lane bili serves, on every build — refused (422) by default, or answered locally by bili itself when `BILI_DSH_AUTHORED_COMPACTION` is set (row below). Any leftover value — `"dsh": { "allowDshCompaction": true }`, a bare top-level `"allowDshCompaction"` in an older file, or the old env var — is ignored, with a one-time deprecation warning naming it. If you need dsh-side checkpoints out entirely, apply host-side suppression instead: the shipped bundle patch (`auto: false`) on non-web profiles, or the #3354 load-time overlay / #2474 full-snapshot override of preset-standard on web profiles. |
 | `BILI_DSH_AUTHORED_COMPACTION` | Set `1` to have bili itself ANSWER dsh's compaction summarize calls locally instead of refusing them (#3733). Prerequisites per call: the #1729 guard fires (marker-decisive; unconditional since #3651) and the session holds at least one ACTIVE fold block. The reply is forged with zero egress (the autoModeForge #2740 discipline): an identity header `<bili-snapshot v1 conv="…" seq="…" blocks="…" />` plus every active block's summary in the kernel render format — exactly the bytes the model already reads upstream, so client display, upstream context and server state agree for the first time, and dsh's checkpoint file shrinks (#3723's unbounded growth loop). Originals stay recoverable via CCR/export; the landed checkpoint is recognized on replay through the same #2432 rebase as a foreign one, but recorded as `dshAuthoredCheckpointLanded` (info, not warn). Env-only for the rollout window; read per-request, no restart needed. |
 | `BILI_NO_CACHE_CONTROL` | Set `1` to disable bili's Anthropic-lane `cache_control` breakpoint stamping (#1637, shipped in #1639). On by default: Anthropic-style upstreams cache only what is explicitly breakpointed (max 4 per request, counted across system + tools + message blocks combined), so bili marks the system block plus up to 3 cumulative message marks — a marked message stays marked (byte-stable prefix), marks die only by folding, and the last 3 stable messages carry the advancing frontier. Any client-set `cache_control` (message blocks, tools entries) suppresses bili's stamps entirely — client-managed caching wins. Marks persist with the session. This switch is the escape hatch for upstreams that reject the field or relays with their own breakpoint policy. Plain-proxy Anthropic lane only; OpenAI/Responses lanes cache implicitly and are never stamped. Config-file twin: [`compat.noCacheControl`](#compat) — the env var wins. |
+| `BILI_CACHE_KEEPALIVE` | Set `1` to turn ON idle prompt-cache keepalive for the Anthropic wire (#3376) — see [`cacheKeepalive`](#cachekeepalive) for the full mechanism, stop rules, and cost notes. File twin: `"cacheKeepalive": { "enabled": true }`; the env var wins. Default OFF. |
+| `BILI_CACHE_KEEPALIVE_TTL_FACTOR` | Cadence factor applied to the detected/assumed cache-TTL tier (default `0.9` → pings at ~4.5 min on the 5-min tier, ~54 min on the 1-hour tier). Must be in `(0, 1]`. File twin: `cacheKeepalive.ttlFactor`. |
+| `BILI_CACHE_KEEPALIVE_MAX_DURATION_MS` | Maximum keepalive lifetime per session, measured from its last REAL request (default `86400000` = 24 h); past it, an armed session disarms even while still hitting. File twin: `cacheKeepalive.maxDurationMs`. |
+| `BILI_CACHE_KEEPALIVE_MAX_PINGS` | Max simultaneously armed sessions (default `4`); overflow evicts the longest-idle session's keepalive. File twin: `cacheKeepalive.maxConcurrentPings`. |
+| `BILI_CACHE_KEEPALIVE_ASSUME_TTL` | `"5m"` or `"1h"`: skip the body's breakpoint detection and run the cadence from this tier instead — for relays/proxies that inject or rewrite `cache_control` TTL downstream of bili so the forwarded body shows no (or a wrong) breakpoint tier. File twin: `cacheKeepalive.assumeTtl`. |
+| `BILI_CACHE_KEEPALIVE_ARM_WITHOUT_BREAKPOINTS` | Set `1` to arm keepalive even when the forwarded body carries no `cache_control` breakpoints (default off — without breakpoints there is nothing explicitly breakpointed to refresh; pair with `assumeTtl`/`intervalMs` when your relay owns the breakpoints). File twin: `cacheKeepalive.armWithoutBreakpoints`. |
+| `BILI_CACHE_KEEPALIVE_INTERVAL_MS` | Absolute ping interval in ms; wins over `ttlFactor`, `assumeTtl`, and detected tier. Use for a fixed cadence regardless of the upstream's TTL policy. File twin: `cacheKeepalive.intervalMs`. |
 | `BILI_CHAIN_CONTENT` | Set `1` to turn ON the ACP-artifact / `<bili-chain …/>` checkpoint **body-content** detection of bili→bili chain awareness (#1086/#1421): when an inbound request carries compression artifacts (render tags / historical `acp_status`+`search_context` tool calls) or a digest-bearing checkpoint in its BODY but neither the `x-bili-hop` header nor local compression state for its session, bili records an advisory observation and/or applies first-processor-wins passthrough. **Default is OFF** (#1683 follow-up): by default ONLY the `x-bili-hop` header drives chain recognition, because scanning the request BODY can false-positive on CCR/file-introduced text and model-echoed tags that look like real markers. Enable it only for the narrow multi-bili relay case where an intermediate box strips `x-bili-hop` and you accept that false-positive risk. `"chainContentDetection": true` in the config file does the same; the env var wins. The `x-bili-hop` signal itself is unaffected by this switch. |
 | `BILI_CHAIN_STAMP` | Set `1` to turn ON egress emission of the **model-visible** `<bili-chain …/>` chain-integrity checkpoint carrier (#1683, default OFF): when enabled, every request THIS instance actually processes leaves with a digest-bearing stamp so a downstream bili applies first-processor-wins even when the `x-bili-hop` header was stripped in transit (#1421). The carrier lands in a slot the terminal model also reads (a trailing `user` message on OpenAI/Responses, a trailing text part on Anthropic/Google), so models treat it as phantom user input and burn tokens commenting on it — which is why it is off by default. Enable it only for the narrow multi-bili relay case where `x-bili-hop` is stripped by an intermediate box and the digest-verified body-stamp is the sole guard against double-processing. Independent of `BILI_CHAIN_CONTENT` (inbound body-detection is also default OFF) and of the `x-bili-hop` passthrough, which works either way. `"chainEgressStamp": true` in the config file does the same; the env var wins. |
 | `BILI_CHAIN_MAX_FUTURE_SKEW_MS` | Maximum future skew (ms) tolerated when validating a chain checkpoint's `issued-at` timestamp (#1395 step 2): a checkpoint stamped more than this far into the future is judged `stale` (replay / clock skew) even when its digest verifies. Default `120000` (2 min); non-numeric or non-positive values fall back to the default. Step 2 is shadow-only — these knobs tune verdict logging, never forwarding. |
@@ -2248,10 +2281,12 @@ Two compressors on one conversation double-compress and corrupt message refs, so
 
  #### Turning dsh native auto-compaction OFF in a web profile (#1772/#3354, automatic since #3354; #2474 recipe as fallback)
  
- **Automatic since #3354.** In a profile bundling `@deepseek-ai/dsh-web-app` the running compaction-basic instance lives inside an agent preset (`preset-standard.config.plugins`) where no patch layer can address the nested row by id (#1772) — the bundled `- id: compaction-basic` row lands on web-app's already-disabled host-plane row and changes nothing. bili now closes that gap at LOAD TIME: the `bili-native` bundle entry registers a cordis `internal/config` overlay (vendored from [deshark42/dsh-compaction-basic-disable](https://github.com/deshark42/dsh-compaction-basic-disable), MIT) that marks the preset's `compaction-basic` and `command-compact` rows `disabled: true`, and the preset gate rows in `dsh.bundle.patch.yml` / the launcher overlay make each Web preset wait for that overlay before it can register. Native auto-compaction is off in these profiles with no user action; ACP compression is unaffected.
+ **Automatic since #3354.** In a profile bundling `@deepseek-ai/dsh-web-app` the running compaction-basic instance lives inside an agent preset (`preset-standard.config.plugins`) where no patch layer can address the nested row by id (#1772) — the bundled `- id: compaction-basic` row lands on web-app's already-disabled host-plane row and changes nothing. bili now closes that gap at LOAD TIME: an always-on bundle entry `bili-compaction-gate` — a separate cordis entry beside `bili-native`, mounted by the same patch layers, so it stays alive when `bili-native` is disabled or kill-switched (#3662) — registers a cordis `internal/config` overlay (vendored from [deshark42/dsh-compaction-basic-disable](https://github.com/deshark42/dsh-compaction-basic-disable), MIT) that marks the preset's `compaction-basic` and `command-compact` rows `disabled: true` while bili owns the lane, and the preset gate rows in `dsh.bundle.patch.yml` / the launcher overlay make each Web preset wait for that overlay's service before it can register. Native auto-compaction is off in these profiles with no user action; ACP compression is unaffected.
  
  The overlay rides an INTERNAL dsh hook and is version-sensitive. If you still see a dsh compaction checkpoint land on a newer/older dsh build, use the fallback below.
  
+ **Disabling vs removing (#3662).** Disabling `bili-native` (dsh plugin manager or `disabled: true` in a patch layer) no longer bricks session creation: the gate service survives in the separate always-on `bili-compaction-gate` entry, so the presets fall back to STOCK native compaction instead of pending forever — compression off, dsh fully usable. Never disable `bili-compaction-gate` itself (that re-creates the brick); to fully uninstall remove `billion-context` from the profile's `dsh.profile.bundles` and restart. Pre-#3662 installs left bricked self-heal on upgrade; manually, append `- id: preset-standard` / `preset-ptc` / `preset-minimal` / `preset-cordis`, each with `inject: null`, to `$DSH_HOME/cordis.patch.yml` (home layer; default `~/.dsh/cordis.patch.yml`) — top-level keys replace wholesale, clearing the pending latch.
+ 
  **Fallback recipe (#2474)** (verified on dsh `0.2.1-alpha.1`, Windows 11, profile bundles including `@deepseek-ai/dsh-web-app`). A profile-layer patch can turn it off — presets are ordinary top-level rows inserted by the bundle layer, and the profile patch layer is applied after it. What does not work is addressing the nested row by id; what does work is overriding the preset row's `config` wholesale.
 
 ```bash

package/CONFIGURATION.zh-CN.md

@@ -120,6 +120,13 @@
 | `dsh.authoredCompaction` | boolean | true (on, #3901 flip) | BILI_DSH_AUTHORED_COMPACTION | bili 用折叠快照本地应答 dsh 压缩摘要请求而非拒绝（#3723/#3733）。0.1.203 狗粮窗口守住后默认开启；false（或环境变量 BILI_DSH_AUTHORED_COMPACTION=0）恢复 #1729 拒绝路径。 |
 | `resign` | scheme → { enabled?, passthrough?, credentialRef? } | {} (armed; built-in scheme sdk-hmac-sha256) | BILI_RESIGN, BILI_RESIGN_PASSTHROUGH, BILI_CODEARTS_REF, BILI_RESIGN_BENEFIT | 按 Authorization 方案键控的重签名臂：可重签名的模型请求全程重签转发；无法重签的请求本地 403 拒绝，除非该方案经 passthrough 选择原文透传。 |
 | `promptCache.routing` | "auto" \| "enabled" \| "disabled" | auto | ACP_PROMPT_CACHE_ROUTING | 面向缓存感知路由选择的提示词缓存路由姿态。 |
+| `cacheKeepalive.enabled` | boolean | false | BILI_CACHE_KEEPALIVE | Anthropic 线路空闲期提示缓存保活总开关（#3376）：会话空闲时按 TTL 推导的节奏以 max_tokens=1 重放最后一次转发的请求体，维持上游前缀缓存温热；以 usage.cache_read_input_tokens 验证命中，miss/429/连续错误/时长上限即停；支持逐 provider 路由与逐模型覆盖。 |
+| `cacheKeepalive.ttlFactor` | number | 0.9 | BILI_CACHE_KEEPALIVE_TTL_FACTOR | 作用于检测/假定缓存 TTL 档位的节奏因子（ping 间隔 = 档位 x 因子；0.9 → 5 分钟档约每 4.5 分钟、1 小时档约每 54 分钟一次）。取值须在 (0, 1]。 |
+| `cacheKeepalive.maxDurationMs` | number | 86400000 | BILI_CACHE_KEEPALIVE_MAX_DURATION_MS | 单会话保活时长上限，自其最后一次真实请求起算（默认 24 小时）；超过后即使仍在命中也会解除武装。 |
+| `cacheKeepalive.maxConcurrentPings` | number | 4 | BILI_CACHE_KEEPALIVE_MAX_PINGS | 同时武装的会话数上限；超限时先驱逐空闲最久的已武装会话。 |
+| `cacheKeepalive.assumeTtl` | "5m" \| "1h" | null (detect from body breakpoints) | BILI_CACHE_KEEPALIVE_ASSUME_TTL | 跳过 body 断点检测，直接按该档位推导节奏——面向会在 bili 下游注入或改写 cache_control TTL、导致转发 body 无断点（或档位不对）的中继/代理。 |
+| `cacheKeepalive.armWithoutBreakpoints` | boolean | false | BILI_CACHE_KEEPALIVE_ARM_WITHOUT_BREAKPOINTS | 转发 body 无任何 cache_control 断点时也武装保活（默认关——没有断点就没有显式打断点的内容可刷新；断点由你的中继自管时配合 assumeTtl/intervalMs 使用）。 |
+| `cacheKeepalive.intervalMs` | number | null (derive from TTL tier) | BILI_CACHE_KEEPALIVE_INTERVAL_MS | 绝对 ping 间隔（毫秒）；优先于 ttlFactor、assumeTtl 与检测档位。用于不随上游 TTL 策略变化的固定节奏。 |
 | `native.attachExternal` | boolean | false | BILI_NATIVE_ATTACH_EXTERNAL | 允许无启动器的原生插件挂到外部（车道化、未武装看门狗）守护进程，而不是自行派生。 |
 | `native.attachLanePriority` | string[] | [] (own lane → user zone → spawn) | — | 本 lane 没有自己的实例时可搭车的外部 lane 名字有序列表（#2905）。本 lane 永远第一；用户区（手动 bili start、8787 全局）永远最后；未列出的 lane 仍不可挂。仅配置文件，无 env。 |
 | `native.attachPolicy` | "own-lane" \| "global-fallback" | own-lane | BILI_NATIVE_ATTACH_POLICY | native hook 附着的 lane 亲和，也是是否发生跨 lane 搭车的总闸（#2877）。own-lane（默认）：lane 型 hook 只搭同 lane 的守护；没有时自行派生，而不是回落到无 lane / 手动启动的 bili start 守护或其他 lane 的守护（那种汇聚会把所有 agent 钉死在一台守护的版本上并双写会话）；已武装的无 lane 守护（受管共享代理，#1225）在两种策略下都可被搭车。global-fallback 恢复 #2877 之前的行为：先同 lane，再兼容的无 lane/用户区守护，以及（配 attachLanePriority）列出的外部 lane。 |
@@ -632,6 +639,18 @@
 - **状态：** ACTIVE
 - **说明：** Responses wire `prompt_cache_key` 盖章的路由策略。客户端显式提供的 `prompt_cache_key` 永远原样优先；否则 bili 按模式决定是否加盖自己从会话身份派生的稳定 key：`"enabled"` = 总是盖，`"disabled"` = 从不盖，`"auto"`（默认）= 仅当上游 host 恰好是 `api.openai.com` 时盖。可由 `ACP_PROMPT_CACHE_ROUTING` 覆盖。
 
+### `cacheKeepalive`
+
+- **类型：** `{ enabled?: boolean, ttlFactor?: number, maxDurationMs?: number, maxConcurrentPings?: number, assumeTtl?: "5m" | "1h", armWithoutBreakpoints?: boolean, intervalMs?: number }`
+- **默认值：** `{}`（功能关闭）
+- **状态：** ACTIVE（#3376）
+- **说明：** Anthropic 线路的空闲期提示缓存保活（#3376）。Anthropic 前缀缓存按 TTL 过期（每个断点 5 分钟或 1 小时）；会话空闲期间（午休、过夜）缓存失效，下一个真实请求就要为整个已缓存前缀付全价冷重建。启用后，bili 对每个会话快照其最后一次成功转发的请求体——到达上游的精确字节，含其中的 `cache_control` 断点——并在会话保持空闲时以 `max_tokens=1` 按 TTL 推导的节奏重放；命中缓存的响应只需一次最小补全即可刷新 TTL。每次 ping 以上游返回的 `usage.cache_read_input_tokens` 验证：命中则排定下一次；读数为 0 说明前缀已死，立即停止。
+  - **武装条件。** 只有成功的（2xx）Anthropic 线路 POST 才会武装/刷新快照。透传请求、重签名通道（存下的签名对应旧字节）、非字符串请求体、超过 64 MiB 的请求体、以及无任何 `cache_control` 断点的请求都不会武装（除非用下面的开关覆盖）。快照仅存内存：重启即清空，下一个真实请求重新武装。
+  - **节奏。** `档位 × ttlFactor`：body 中任一断点声明 `ttl: "1h"` 则档位为 `1h`，否则 `5m`；默认因子 `0.9` → 约 4.5 分钟 / 54 分钟一次。可用 `assumeTtl` 覆盖（跳过 body 检测——面向会在 bili 下游注入或改写 `cache_control` TTL 的中继），或用绝对值 `intervalMs`（优先级最高）；`armWithoutBreakpoints: true` 让无断点的 body 也武装（配合 `assumeTtl` 使用）。
+  - **停止条件。** 该会话出现真实请求立即取消（真实请求自己就会刷新缓存）；到点时该会话有在途请求则延迟约 5 秒再试；`cache_read_input_tokens = 0` → 停（`prefix-dead`）；HTTP 429 → 立即停；连续 3 次其他错误 → 停；距该会话最后一次真实请求超过 `maxDurationMs`（默认 24 小时）→ 停；`maxConcurrentPings`（默认 4）限制同时武装的会话数，超限时先驱逐空闲最久者。
+  - **成本与可观测性。** ping 完全绕过代理管线，因此不会进入 `/acp-cache` 命中率台账（合成流量不得污染健康判定），也不会产生任何缓存归因样本——miss 归因计算跑的请求序列与不开保活时完全一致。每次武装/ping/解除武装都记录 `[keepalive] …` 日志行；`acp_status` 对已武装会话输出一行 `CACHE KEEPALIVE: armed tier=… cadence=… · pings=N [· last-hit Mm ago]`（未武装时不出现）；Web UI 在会话列表显示保活徽标、详情页显示完整状态行，其原始 JSON 配置编辑器可直接写入本配置节（保存时服务端校验）。
+  - **逐 provider / 逐模型覆盖。** 所有字段也可写在 provider 路由下（`providers.<url>.cacheKeepalive`），或写在该路由的某个具体模型下（`providers.<url>.models.<model>.cacheKeepalive`）——同一上游后的不同模型可以跑不同的档位/节奏。逐字段优先级：环境变量 > 模型 > 路由 > 全局块 > 内置默认值。
+
 ### `autoUpdate`
 
 - **类型：** `boolean`
@@ -1716,6 +1735,13 @@ ACP 原生 agent（当前为 `pi` 扩展）会在每个进程内向代理上报
 | `BILI_ALLOW_DSH_COMPACTION` | `dsh` | {} |
 | `BILI_ALLOW_PRIVATE_HTTP_PROVIDERS` | `network.allowPrivateHttpProviders` | false |
 | `BILI_AUTO_MODE_FORGE` | `autoModeForge.enabled` | true |
+| `BILI_CACHE_KEEPALIVE` | `cacheKeepalive.enabled` | false |
+| `BILI_CACHE_KEEPALIVE_ARM_WITHOUT_BREAKPOINTS` | `cacheKeepalive.armWithoutBreakpoints` | false |
+| `BILI_CACHE_KEEPALIVE_ASSUME_TTL` | `cacheKeepalive.assumeTtl` | null (detect from body breakpoints) |
+| `BILI_CACHE_KEEPALIVE_INTERVAL_MS` | `cacheKeepalive.intervalMs` | null (derive from TTL tier) |
+| `BILI_CACHE_KEEPALIVE_MAX_DURATION_MS` | `cacheKeepalive.maxDurationMs` | 86400000 |
+| `BILI_CACHE_KEEPALIVE_MAX_PINGS` | `cacheKeepalive.maxConcurrentPings` | 4 |
+| `BILI_CACHE_KEEPALIVE_TTL_FACTOR` | `cacheKeepalive.ttlFactor` | 0.9 |
 | `BILI_CA_FILE` | `network.caFile` | unset |
 | `BILI_CCR_RETRIEVAL_TTL_MS` | `ccrRetrievalTtlMs` | 600000 (0 disables retrieval) |
 | `BILI_CHAIN_CONTENT` | `chainContentDetection` | false |
@@ -1877,6 +1903,13 @@ ACP 原生 agent（当前为 `pi` 扩展）会在每个进程内向代理上报
 | `BILI_ALLOW_DSH_COMPACTION` | **#3666 起移除**（取代 #2028）。原开关通过解除 wire 级拒绝（#1729）放行 dsh 内置自动压缩；由于落地的 dsh checkpoint 会永久覆盖原始会话历史——不可逆、摧毁代理的压缩基底——该逃生门已被整体删除：所有 bili 服务的线路上，dsh 原生压缩调用现在一律被无条件拦截，所有构建一致——默认拒绝（422），或在设置 `BILI_DSH_AUTHORED_COMPACTION`（下一行）时由 bili 本地应答。任何遗留取值——`"dsh": { "allowDshCompaction": true }`、旧文件里裸写在顶层的 `"allowDshCompaction"`、或旧环境变量——都会被忽略，并给出一条点名该键的一次性弃用警告。若要彻底避免 dsh 侧 checkpoint 落地，请改用宿主侧抑制：非 web profile 下随附 bundle patch（`auto: false`），web profile 下用 #3354 加载期 overlay 或 #2474 对 preset-standard 的完整快照覆盖。 |
 | `BILI_DSH_AUTHORED_COMPACTION` | 设为 `1` 让 bili **本地应答** dsh 的压缩摘要调用，而不是拒绝它们（#3733）。每次调用的前置条件：#1729 守卫触发（由标记决定；#3651 起无条件）、会话至少持有一个 ACTIVE 折叠块。应答零出口流量构造（autoModeForge #2740 纪律）：一行身份头 `<bili-snapshot v1 conv="…" seq="…" blocks="…" />` 加上每个活跃块的内核渲染格式摘要——与模型在上游已读到的字节完全一致，客户端显示、上游上下文与服务端状态首次吻合，dsh 的 checkpoint 文件随之缩小（终结 #3723 的无界增长环）。原始历史随时可经 CCR/导出恢复；落地的检查点在重放时经同一 #2432 rebase 识别（与外部 checkpoint 同路径），但记为 `dshAuthoredCheckpointLanded`（info 而非 warn）。灰度窗口期 env-only（无配置文件键）；每请求读取，无需重启。 |
 | `BILI_NO_CACHE_CONTROL` | 设为 `1` 关闭 bili 在 Anthropic 通道上的 `cache_control` 断点标注(#1637,随 #1639 落地)。默认开启:Anthropic 系上游只缓存被显式打断点的内容(每请求最多 4 个,按 system + tools + 消息块合并计数),因此 bili 会标注 system 块加上至多 3 个累积消息断点——被标注的消息保持标注(前缀字节稳定),断点只随折叠消亡,最近 3 条稳定消息承载推进前沿。客户端自设的任何 `cache_control`(消息块、tools 条目)都会完全抑制 bili 的标注——客户端自管缓存优先。断点随会话持久化。本开关是逃生阀:用于拒绝该字段的上游或有自己断点策略的中继。仅限 plain-proxy Anthropic 通道;OpenAI/Responses 通道隐式缓存,从不标注。配置文件对应项:[`compat.noCacheControl`](#compat) —— 环境变量优先。 |
+| `BILI_CACHE_KEEPALIVE` | 设为 `1` 开启 Anthropic 线路的空闲期提示缓存保活(#3376)——完整机制、停止规则与成本说明见 [`cacheKeepalive`](#cachekeepalive)。配置文件对应项:`"cacheKeepalive": { "enabled": true }`;环境变量优先。默认关闭。 |
+| `BILI_CACHE_KEEPALIVE_TTL_FACTOR` | 作用于检测/假定缓存 TTL 档位的节奏因子(默认 `0.9` → 5 分钟档约每 4.5 分钟一次,1 小时档约每 54 分钟一次)。取值须在 `(0, 1]`。配置文件对应项:`cacheKeepalive.ttlFactor`。 |
+| `BILI_CACHE_KEEPALIVE_MAX_DURATION_MS` | 单会话保活时长上限,自其最后一次真实请求起算(默认 `86400000` = 24 小时);超过后即使仍在命中也会解除武装。配置文件对应项:`cacheKeepalive.maxDurationMs`。 |
+| `BILI_CACHE_KEEPALIVE_MAX_PINGS` | 同时武装的会话数上限(默认 `4`);超限时先驱逐空闲最久的会话。配置文件对应项:`cacheKeepalive.maxConcurrentPings`。 |
+| `BILI_CACHE_KEEPALIVE_ASSUME_TTL` | `"5m"` 或 `"1h"`:跳过 body 断点检测,直接按该档位推导节奏——面向会在 bili 下游注入或改写 `cache_control` TTL、导致转发 body 无断点(或档位不对)的中继/代理。配置文件对应项:`cacheKeepalive.assumeTtl`。 |
+| `BILI_CACHE_KEEPALIVE_ARM_WITHOUT_BREAKPOINTS` | 设为 `1` 让转发 body 无任何 `cache_control` 断点时也武装保活(默认关——没有断点就没有显式打断点的内容可刷新;断点由你的中继自管时配合 `assumeTtl`/`intervalMs` 使用)。配置文件对应项:`cacheKeepalive.armWithoutBreakpoints`。 |
+| `BILI_CACHE_KEEPALIVE_INTERVAL_MS` | 绝对 ping 间隔(毫秒);优先于 `ttlFactor`、`assumeTtl` 与检测档位。用于不随上游 TTL 策略变化的固定节奏。配置文件对应项:`cacheKeepalive.intervalMs`。 |
 | `BILI_CHAIN_CONTENT` | 设为 `1` 开启 bili→bili 链感知的 ACP 产物 / `<bili-chain …/>` 检查点**正文内容**检测（#1086/#1421）：当入站请求的正文携带压缩产物（渲染标签 / 历史 `acp_status`+`search_context` 工具调用）或带摘要的检查点，但既无 `x-bili-hop` 头、本实例也无该会话的压缩状态时，bili 记录一次告警性观察和/或应用「首个处理器优先」透传。**默认关闭**（#1683 后续）：默认下只有 `x-bili-hop` 头驱动链识别，因为扫描请求正文可能把 CCR/文件引入的文本和模型回声标签误判为真实标记。仅在中间盒子剥掉 `x-bili-hop`、且你接受该误判风险的狭窄多 bili 中继场景下才启用。配置文件中设 `"chainContentDetection": true` 效果相同；环境变量优先。`x-bili-hop` 信号本身不受此开关影响。 |
 | `BILI_CHAIN_STAMP` | 设为 `1` 开启**模型可见**的 `<bili-chain …/>` 链完整性检查点载体的出站注入（#1683，默认关闭）：开启后，本实例实际处理的每个请求都携带一个带摘要的戳，使下游 bili 即使 `x-bili-hop` 头在传输中被剥离也能应用「首个处理器优先」（first-processor-wins）（#1421）。该载体落在终端模型同样会读取的位置（OpenAI/Responses 上是一条尾部 `user` 消息，Anthropic/Google 上是尾部文本 part），因此模型会把它当作幽灵用户输入并花 token 去评论它——这正是它默认关闭的原因。仅在多 bili 中继、且中间盒子剥掉 `x-bili-hop`、带摘要校验的 body-stamp 是防止双重处理的唯一手段这一狭窄场景下才启用。与 `BILI_CHAIN_CONTENT`（入站正文检测同样默认关闭）及 `x-bili-hop` 透传相互独立（后者无论如何都生效）。配置文件中设 `"chainEgressStamp": true` 效果相同；环境变量优先。 |
 | `BILI_CHAIN_MAX_FUTURE_SKEW_MS` | 校验链检查点 `issued-at` 时间戳时容忍的最大未来偏斜（毫秒）（#1395 step 2）：戳在比当前时间未来超过此值的检查点会被判为 `stale`（重放 / 时钟偏斜），即使其摘要校验通过。默认 `120000`（2 分钟）；非数字或非正值回退到默认值。Step 2 仅影子模式——这些旋钮只调判定日志，绝不影响转发。 |
@@ -2218,10 +2251,12 @@ bili plugin remove pi       # 撤销（原文件一次性备份为 *.bili-bak）
 
  #### 在 web profile 下关掉 dsh 原生自动压缩（#1772/#3354，#3354 起自动；#2474 配方为回退）
 
- **#3354 起自动完成。** 在 bundles 含 `@deepseek-ai/dsh-web-app` 的 profile 里，真正运行的 compaction-basic 实例位于 agent preset（`preset-standard.config.plugins`）内部，任何 patch 层都无法按 id 直寻那条嵌套行（#1772）—— 随包的 `- id: compaction-basic` 行落在 web-app 已禁用的宿主平面行上、什么都没改。bili 现在在**加载期**补上这一环：`bili-native` bundle 条目注册一个 cordis `internal/config` overlay（移植自 [deshark42/dsh-compaction-basic-disable](https://github.com/deshark42/dsh-compaction-basic-disable)，MIT），把 preset 里的 `compaction-basic` 与 `command-compact` 行标记为 `disabled: true`；`dsh.bundle.patch.yml` / 启动器 overlay 里的 preset 门控行让每个 Web preset 在注册前等待该 overlay。这些 profile 里原生自动压缩无需任何用户操作即关闭；ACP 压缩不受影响。
+ **#3354 起自动完成。** 在 bundles 含 `@deepseek-ai/dsh-web-app` 的 profile 里，真正运行的 compaction-basic 实例位于 agent preset（`preset-standard.config.plugins`）内部，任何 patch 层都无法按 id 直寻那条嵌套行（#1772）—— 随包的 `- id: compaction-basic` 行落在 web-app 已禁用的宿主平面行上、什么都没改。bili 现在在**加载期**补上这一环：一个**常驻**的 bundle 条目 `bili-compaction-gate`（与 `bili-native` 并列的独立 cordis 条目，由同一组 patch 层挂载，因此 `bili-native` 被禁用或 kill-switch 时它仍然存活，#3662）注册一个 cordis `internal/config` overlay（移植自 [deshark42/dsh-compaction-basic-disable](https://github.com/deshark42/dsh-compaction-basic-disable)，MIT），在 bili 持有该泳道期间把 preset 里的 `compaction-basic` 与 `command-compact` 行标记为 `disabled: true`；`dsh.bundle.patch.yml` / 启动器 overlay 里的 preset 门控行让每个 Web preset 在注册前等待该 overlay 的服务。这些 profile 里原生自动压缩无需任何用户操作即关闭；ACP 压缩不受影响。
 
  overlay 依赖 dsh 的内部钩子，对版本敏感。若在新/旧 dsh 构建上仍见到 dsh 压缩 checkpoint 落地，用下面的回退配方。
 
+ **禁用与移除的区别（#3662）。** 禁用 `bili-native`（dsh 插件管理器或 patch 层里的 `disabled: true`）不再会导致会话创建被「砖」：门控服务存活在独立的常驻条目 `bili-compaction-gate` 里，preset 回落到**原生**自动压缩而不是永久 pending —— 压缩关闭、dsh 完全可用。请勿禁用 `bili-compaction-gate` 本身（那会重新造成「砖」）；要彻底卸载，从 profile 的 `dsh.profile.bundles` 移除 `billion-context` 后重启。卡在 #3662 之前版本且已被禁用的安装，升级即自愈；手动解砖是在 `$DSH_HOME/cordis.patch.yml`（HOME 层；默认 `~/.dsh/cordis.patch.yml`）追加 `- id: preset-standard` / `preset-ptc` / `preset-minimal` / `preset-cordis`，各配 `inject: null` —— 顶层键为整体替换，清掉 pending 锁。
+
  **回退配方（#2474）**（已在 dsh `0.2.1-alpha.1`、Windows 11、bundles 含 `@deepseek-ai/dsh-web-app` 的 profile 上实测）。profile 层补丁可以关掉它 —— preset 是 bundle 层插入的普通顶层条目，而 profile 补丁层在其之后应用。不能用「按 id 定位嵌套行」的写法，可行的是**整体覆盖 preset 行的 `config`**。
 
 ```bash

package/dist/agent/dsh-compaction-gate.js

@@ -0,0 +1,3 @@
+import { createRequire as __biliCreateRequire } from 'node:module';
+const require = __biliCreateRequire(import.meta.url);
+var DSH_COMPACTION_BASIC_PACKAGE="@deepseek-ai/dsh-compaction-basic";var DSH_COMMAND_COMPACT_PACKAGE="@deepseek-ai/dsh-command-compact";var DSH_AGENT_PRESET_PACKAGE="@deepseek-ai/dsh-agent-preset";var BILI_COMPACTION_DISABLE_SERVICE="biliBasicCompactionPolicy";var DSH_COMPACTION_VERDICT_KEY="__BILI_DSH_COMPACTION_VERDICT__";function isDshCompactionActive(){return globalThis[DSH_COMPACTION_VERDICT_KEY]==="active"}var DSH_COMPACTION_GATE_TELEMETRY_KEY="__BILI_DSH_COMPACTION_GATE_TELEMETRY__";function noteGateCoverage(entryName,rows,isFactory){const store=globalThis;const current=store[DSH_COMPACTION_GATE_TELEMETRY_KEY];const telemetry=current??{covered:[],sawFactoryPreset:false};const existing=telemetry.covered.find(c=>c.entry===entryName);if(existing===void 0){telemetry.covered=[...telemetry.covered,{entry:entryName,rows}]}else if(rows>existing.rows){existing.rows=rows}if(isFactory)telemetry.sawFactoryPreset=true;store[DSH_COMPACTION_GATE_TELEMETRY_KEY]=telemetry}function countCompactionRows(rows){let n=0;for(const row of rows){if(row===null||typeof row!=="object")continue;const r=row;if(r.name===DSH_COMPACTION_BASIC_PACKAGE||r.name===DSH_COMMAND_COMPACT_PACKAGE)n+=1;else if(r.group&&Array.isArray(r.config))n+=countCompactionRows(r.config)}return n}function disableBasicCompaction(rows){return rows.map(row=>{if(row===null||typeof row!=="object")return row;const r=row;if(r.name===DSH_COMPACTION_BASIC_PACKAGE||r.name===DSH_COMMAND_COMPACT_PACKAGE){return{...r,disabled:true}}if(r.group&&Array.isArray(r.config)){return{...r,config:disableBasicCompaction(r.config)}}return row})}function registerCompactionDisable(ctx){if(typeof ctx.on==="function"){ctx.on("internal/config",function(_raw,next){const resolved=next();if(!isDshCompactionActive())return resolved;const config=resolved??{};if(!Array.isArray(config.plugins))return resolved;const compactionRows=countCompactionRows(config.plugins);if(compactionRows===0)return resolved;const rawName=this?.entry?.options?.name;const entryName=typeof rawName==="string"?rawName:"unnamed-entry";noteGateCoverage(entryName.slice(0,120),compactionRows,entryName===DSH_AGENT_PRESET_PACKAGE);return{...config,plugins:disableBasicCompaction(config.plugins)}},{global:true})}ctx.reflect?.provide?.(BILI_COMPACTION_DISABLE_SERVICE,Object.freeze({owner:"billion-context",issue:"#3354"}))}var name="bili-compaction-gate";var inject=[];function apply(ctx){registerCompactionDisable(ctx)}export{apply,inject,name};