From a1d3650b600704cb8b61d11535a561921dfb0c36 Mon Sep 17 00:00:00 2001 From: ygpking <30524294+ygpking@users.noreply.github.com> Date: Sat, 17 Oct 2026 20:05:45 +0800 Subject: [PATCH 1/2] docs: document the compaction gate for custom agent presets MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #3354 的闸门名单只有四个内置 preset;由第三方 bundle 声明的 agent preset 不在名单里,也没有 inject 闸门,加载期 overlay 与它的解析顺序没有保证,dsh 原生压缩保持 armed,压缩请求被 #1729 逐条拒收(422)而 UI 无感。补中英两版文档:症状、两条自救路(补 inject 闸门 / #2474 全量快照)、 以及 dsh native 安装下 launcher overlay 被跳过这一层原因。附一台真机的实测代价。 --- CONFIGURATION.md | 23 +++++++++++++++++++++++ CONFIGURATION.zh-CN.md | 23 +++++++++++++++++++++++ 2 files changed, 46 insertions(+) diff --git a/CONFIGURATION.md b/CONFIGURATION.md index e91e6d2da7..864c095103 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -462,6 +462,29 @@ Top-level keys that control how the proxy listens and behaves globally. } ``` +### dsh native compaction and custom agent presets + +`#3354` stands dsh native basic compaction down at load time (rows marked `disabled: true`) and gates each preset entry on the `biliBasicCompactionPolicy` service so the overlay cannot lose the import race. The gate list is the built-in roster only: + +```ts +// src/agent/dsh-compaction-disable.ts +const DSH_WEB_PRESET_IDS = ["preset-standard", "preset-ptc", "preset-minimal", "preset-cordis"] as const; +``` + +A preset declared by a **third-party bundle** — any entry whose `name` is `'@deepseek-ai/dsh-agent-preset'` in some bundle's own `cordis.patch.yml`, which is how an assistant preset installed as its own bundle is declared — is not in that roster and carries no `inject: [biliBasicCompactionPolicy]`. Its rows can then resolve before bili's overlay is registered, so dsh native compaction stays armed and every compaction call is refused at the wire (`#1729`, `422 dsh_compaction_refused`) with nothing visible in the UI. Add the gate yourself: + +```yaml +# `/.dsh/profiles//cordis.patch.yml +- id: + inject: [biliBasicCompactionPolicy] +``` + +A full-snapshot override of that preset's `compaction-basic` row (`#2474`) also works; `config` is replaced wholesale there, so restate its defaults. Setting `dsh.allowDshCompaction` to `true` is the other way out, and the irreversible one: the checkpoint shadows the raw history. + +Under a **dsh native install** (`bili plugin install dsh`) the launcher's overlay patch is not written at all — `writeDshAcpPatch` is skipped when `dshNativeInstalled()` (`src/launcher.ts`) — so the gate has to live in the profile's own patch layer. The boot warning says that; this section says which layer, and why the roster cannot reach you. + +What it costs to leave a custom preset ungated — one Android/proot device, dsh 2.0.0-rc.2 + bili 0.1.197, 98 sessions of which 70 ran a custom preset: 5,090 compaction calls refused (3,254 of them in a single session). That session's inbound averaged **16.67 MiB per step** against 0.36–0.99 MiB for the gated ones — 57.7 GiB over 23 hours. The refused replay also fed the `#2490` planning floor, so the output budget was clamped 113 times (e.g. 10033 -> 4220) and the step count roughly doubled. Gating the preset (or opting in, as that device ultimately did) ended the storm. + ### `compat` - **Type:** `{ roles?: Record; dropFields?: string[]; streamErrorShape?: "protocol" | "completion"; noCacheControl?: boolean; keepResponseId?: boolean }` diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index f45422c0ca..3fa24c7118 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -462,6 +462,29 @@ } ``` +### dsh 原生压缩与自定义 agent preset + +`#3354` 在加载期把 dsh 的 native basic compaction 停掉(行标记 `disabled: true`),并给每个 preset 条目挂 `biliBasicCompactionPolicy` 服务作为闸门,保证 overlay 不输在导入顺序上。闸门名单只有内置的这几个: + +```ts +// src/agent/dsh-compaction-disable.ts +const DSH_WEB_PRESET_IDS = ["preset-standard", "preset-ptc", "preset-minimal", "preset-cordis"] as const; +``` + +由**第三方 bundle** 声明的 preset —— 某个 bundle 的 `cordis.patch.yml` 里 `name` 为 `'@deepseek-ai/dsh-agent-preset'` 的条目(把助手预设做成独立 bundle 安装就是这样)—— 不在这份名单里,也不会带 `inject: [biliBasicCompactionPolicy]`。于是它的行可能在 bili 的 overlay 注册之前就解析完成,dsh 原生压缩保持 armed,之后每次压缩都在线上被拒(`#1729`,`422 dsh_compaction_refused`),而 UI 上什么都看不到。自己补一行闸门: + +```yaml +# `/.dsh/profiles//cordis.patch.yml +- id: <你的 preset id> + inject: [biliBasicCompactionPolicy] +``` + +按 `#2474` 全量快照覆盖该 preset 的 `compaction-basic` 行同样可行;那里 `config` 是整体替换,默认项要一起写。把 `dsh.allowDshCompaction` 设为 `true` 是另一条出路,也是不可逆的那条:checkpoint 会盖掉原始历史。 + +**dsh native 安装**(`bili plugin install dsh`)下 launcher 的 overlay patch 根本不会写 —— `dshNativeInstalled()` 为真时 `writeDshAcpPatch` 整段跳过(`src/launcher.ts`)—— 所以闸门必须落在 profile 自己的 patch 层。启动 warning 说了这件事;这一节说清楚是哪一层,以及为什么名单覆盖不到你。 + +不给自定义 preset 加闸门的代价 —— 一台 Android/proot 设备,dsh 2.0.0-rc.2 + bili 0.1.197,98 个会话里 70 个跑自定义 preset:5,090 次压缩请求全部被拒(单会话占 3,254 次)。该会话入站均值 **16.67 MiB/步**,有闸门的会话是 0.36–0.99 MiB —— 23 小时共 57.7 GiB。被拒的 replay 又喂进 `#2490` 的 planning floor,输出预算被 clamp 113 次(如 10033 → 4220),步数大约翻倍。给 preset 补闸门(或像那台设备一样直接 opt-in)之后风暴就停了。 + ### `compat` - **类型:** `{ roles?: Record; dropFields?: string[]; streamErrorShape?: "protocol" | "completion"; noCacheControl?: boolean; keepResponseId?: boolean }` From 26161f092c333701560d239fa666c58a0f13d39b Mon Sep 17 00:00:00 2001 From: awork Date: Sat, 17 Oct 2026 20:26:18 +0800 Subject: [PATCH 2/2] docs: relocate custom-preset gate section beside the #3354 web-profile section; normalize patch path in yaml example Reviewer alignment for #3568 (content unchanged except the two fixes): - The new prose section sat between `compactionOptIn` and `compat` inside the top-level config-key reference area, where every entry follows the Type/Default/Status/Description key pattern. It now lives as an h3 after the #1206 block under "Plugin Mode (native tools)", directly beside the existing #3354/#2474 web-profile section it extends. - The yaml example comment carried an unclosed backtick and a non-repo path (`/.dsh/profiles/...`); it now uses the repo convention $DSH_HOME/profiles//cordis.patch.yml (cf. the #2474 recipe). Both EN and ZH files moved symmetrically. --- CONFIGURATION.md | 46 +++++++++++++++++++++--------------------- CONFIGURATION.zh-CN.md | 46 +++++++++++++++++++++--------------------- 2 files changed, 46 insertions(+), 46 deletions(-) diff --git a/CONFIGURATION.md b/CONFIGURATION.md index 864c095103..0467379235 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -462,29 +462,6 @@ Top-level keys that control how the proxy listens and behaves globally. } ``` -### dsh native compaction and custom agent presets - -`#3354` stands dsh native basic compaction down at load time (rows marked `disabled: true`) and gates each preset entry on the `biliBasicCompactionPolicy` service so the overlay cannot lose the import race. The gate list is the built-in roster only: - -```ts -// src/agent/dsh-compaction-disable.ts -const DSH_WEB_PRESET_IDS = ["preset-standard", "preset-ptc", "preset-minimal", "preset-cordis"] as const; -``` - -A preset declared by a **third-party bundle** — any entry whose `name` is `'@deepseek-ai/dsh-agent-preset'` in some bundle's own `cordis.patch.yml`, which is how an assistant preset installed as its own bundle is declared — is not in that roster and carries no `inject: [biliBasicCompactionPolicy]`. Its rows can then resolve before bili's overlay is registered, so dsh native compaction stays armed and every compaction call is refused at the wire (`#1729`, `422 dsh_compaction_refused`) with nothing visible in the UI. Add the gate yourself: - -```yaml -# `/.dsh/profiles//cordis.patch.yml -- id: - inject: [biliBasicCompactionPolicy] -``` - -A full-snapshot override of that preset's `compaction-basic` row (`#2474`) also works; `config` is replaced wholesale there, so restate its defaults. Setting `dsh.allowDshCompaction` to `true` is the other way out, and the irreversible one: the checkpoint shadows the raw history. - -Under a **dsh native install** (`bili plugin install dsh`) the launcher's overlay patch is not written at all — `writeDshAcpPatch` is skipped when `dshNativeInstalled()` (`src/launcher.ts`) — so the gate has to live in the profile's own patch layer. The boot warning says that; this section says which layer, and why the roster cannot reach you. - -What it costs to leave a custom preset ungated — one Android/proot device, dsh 2.0.0-rc.2 + bili 0.1.197, 98 sessions of which 70 ran a custom preset: 5,090 compaction calls refused (3,254 of them in a single session). That session's inbound averaged **16.67 MiB per step** against 0.36–0.99 MiB for the gated ones — 57.7 GiB over 23 hours. The refused replay also fed the `#2490` planning floor, so the output budget was clamped 113 times (e.g. 10033 -> 4220) and the step count roughly doubled. Gating the preset (or opting in, as that device ultimately did) ended the storm. - ### `compat` - **Type:** `{ roles?: Record; dropFields?: string[]; streamErrorShape?: "protocol" | "completion"; noCacheControl?: boolean; keepResponseId?: boolean }` @@ -2270,6 +2247,29 @@ Because a partial override fails without any diagnostic, always re-dump and comp - Under the opencode launcher/native mode a present `opencode-acp` is info-only by design (#920 absorbs it for legacy sessions); everywhere else it warns. - Disable: `BILI_CONFLICT_SCAN=0`. +### dsh native compaction and custom agent presets + +`#3354` stands dsh native basic compaction down at load time (rows marked `disabled: true`) and gates each preset entry on the `biliBasicCompactionPolicy` service so the overlay cannot lose the import race. The gate list is the built-in roster only: + +```ts +// src/agent/dsh-compaction-disable.ts +const DSH_WEB_PRESET_IDS = ["preset-standard", "preset-ptc", "preset-minimal", "preset-cordis"] as const; +``` + +A preset declared by a **third-party bundle** — any entry whose `name` is `'@deepseek-ai/dsh-agent-preset'` in some bundle's own `cordis.patch.yml`, which is how an assistant preset installed as its own bundle is declared — is not in that roster and carries no `inject: [biliBasicCompactionPolicy]`. Its rows can then resolve before bili's overlay is registered, so dsh native compaction stays armed and every compaction call is refused at the wire (`#1729`, `422 dsh_compaction_refused`) with nothing visible in the UI. Add the gate yourself: + +```yaml +# $DSH_HOME/profiles//cordis.patch.yml +- id: + inject: [biliBasicCompactionPolicy] +``` + +A full-snapshot override of that preset's `compaction-basic` row (`#2474`) also works; `config` is replaced wholesale there, so restate its defaults. Setting `dsh.allowDshCompaction` to `true` is the other way out, and the irreversible one: the checkpoint shadows the raw history. + +Under a **dsh native install** (`bili plugin install dsh`) the launcher's overlay patch is not written at all — `writeDshAcpPatch` is skipped when `dshNativeInstalled()` (`src/launcher.ts`) — so the gate has to live in the profile's own patch layer. The boot warning says that; this section says which layer, and why the roster cannot reach you. + +What it costs to leave a custom preset ungated — one Android/proot device, dsh 2.0.0-rc.2 + bili 0.1.197, 98 sessions of which 70 ran a custom preset: 5,090 compaction calls refused (3,254 of them in a single session). That session's inbound averaged **16.67 MiB per step** against 0.36–0.99 MiB for the gated ones — 57.7 GiB over 23 hours. The refused replay also fed the `#2490` planning floor, so the output budget was clamped 113 times (e.g. 10033 -> 4220) and the step count roughly doubled. Gating the preset (or opting in, as that device ultimately did) ended the storm. + --- ## Sessions & Migration diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index 3fa24c7118..6ae147b985 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -462,29 +462,6 @@ } ``` -### dsh 原生压缩与自定义 agent preset - -`#3354` 在加载期把 dsh 的 native basic compaction 停掉(行标记 `disabled: true`),并给每个 preset 条目挂 `biliBasicCompactionPolicy` 服务作为闸门,保证 overlay 不输在导入顺序上。闸门名单只有内置的这几个: - -```ts -// src/agent/dsh-compaction-disable.ts -const DSH_WEB_PRESET_IDS = ["preset-standard", "preset-ptc", "preset-minimal", "preset-cordis"] as const; -``` - -由**第三方 bundle** 声明的 preset —— 某个 bundle 的 `cordis.patch.yml` 里 `name` 为 `'@deepseek-ai/dsh-agent-preset'` 的条目(把助手预设做成独立 bundle 安装就是这样)—— 不在这份名单里,也不会带 `inject: [biliBasicCompactionPolicy]`。于是它的行可能在 bili 的 overlay 注册之前就解析完成,dsh 原生压缩保持 armed,之后每次压缩都在线上被拒(`#1729`,`422 dsh_compaction_refused`),而 UI 上什么都看不到。自己补一行闸门: - -```yaml -# `/.dsh/profiles//cordis.patch.yml -- id: <你的 preset id> - inject: [biliBasicCompactionPolicy] -``` - -按 `#2474` 全量快照覆盖该 preset 的 `compaction-basic` 行同样可行;那里 `config` 是整体替换,默认项要一起写。把 `dsh.allowDshCompaction` 设为 `true` 是另一条出路,也是不可逆的那条:checkpoint 会盖掉原始历史。 - -**dsh native 安装**(`bili plugin install dsh`)下 launcher 的 overlay patch 根本不会写 —— `dshNativeInstalled()` 为真时 `writeDshAcpPatch` 整段跳过(`src/launcher.ts`)—— 所以闸门必须落在 profile 自己的 patch 层。启动 warning 说了这件事;这一节说清楚是哪一层,以及为什么名单覆盖不到你。 - -不给自定义 preset 加闸门的代价 —— 一台 Android/proot 设备,dsh 2.0.0-rc.2 + bili 0.1.197,98 个会话里 70 个跑自定义 preset:5,090 次压缩请求全部被拒(单会话占 3,254 次)。该会话入站均值 **16.67 MiB/步**,有闸门的会话是 0.36–0.99 MiB —— 23 小时共 57.7 GiB。被拒的 replay 又喂进 `#2490` 的 planning floor,输出预算被 clamp 113 次(如 10033 → 4220),步数大约翻倍。给 preset 补闸门(或像那台设备一样直接 opt-in)之后风暴就停了。 - ### `compat` - **类型:** `{ roles?: Record; dropFields?: string[]; streamErrorShape?: "protocol" | "completion"; noCacheControl?: boolean; keepResponseId?: boolean }` @@ -2241,6 +2218,29 @@ dsh --profile --dump-config > /tmp/profile.yml - opencode launcher/native 模式下已存在的 `opencode-acp` 按设计只记 info(#920 有意吸收它处理 legacy 会话);其他场景一律告警。 - 关闭方式:`BILI_CONFLICT_SCAN=0`。 +### dsh 原生压缩与自定义 agent preset + +`#3354` 在加载期把 dsh 的 native basic compaction 停掉(行标记 `disabled: true`),并给每个 preset 条目挂 `biliBasicCompactionPolicy` 服务作为闸门,保证 overlay 不输在导入顺序上。闸门名单只有内置的这几个: + +```ts +// src/agent/dsh-compaction-disable.ts +const DSH_WEB_PRESET_IDS = ["preset-standard", "preset-ptc", "preset-minimal", "preset-cordis"] as const; +``` + +由**第三方 bundle** 声明的 preset —— 某个 bundle 的 `cordis.patch.yml` 里 `name` 为 `'@deepseek-ai/dsh-agent-preset'` 的条目(把助手预设做成独立 bundle 安装就是这样)—— 不在这份名单里,也不会带 `inject: [biliBasicCompactionPolicy]`。于是它的行可能在 bili 的 overlay 注册之前就解析完成,dsh 原生压缩保持 armed,之后每次压缩都在线上被拒(`#1729`,`422 dsh_compaction_refused`),而 UI 上什么都看不到。自己补一行闸门: + +```yaml +# $DSH_HOME/profiles//cordis.patch.yml +- id: <你的 preset id> + inject: [biliBasicCompactionPolicy] +``` + +按 `#2474` 全量快照覆盖该 preset 的 `compaction-basic` 行同样可行;那里 `config` 是整体替换,默认项要一起写。把 `dsh.allowDshCompaction` 设为 `true` 是另一条出路,也是不可逆的那条:checkpoint 会盖掉原始历史。 + +**dsh native 安装**(`bili plugin install dsh`)下 launcher 的 overlay patch 根本不会写 —— `dshNativeInstalled()` 为真时 `writeDshAcpPatch` 整段跳过(`src/launcher.ts`)—— 所以闸门必须落在 profile 自己的 patch 层。启动 warning 说了这件事;这一节说清楚是哪一层,以及为什么名单覆盖不到你。 + +不给自定义 preset 加闸门的代价 —— 一台 Android/proot 设备,dsh 2.0.0-rc.2 + bili 0.1.197,98 个会话里 70 个跑自定义 preset:5,090 次压缩请求全部被拒(单会话占 3,254 次)。该会话入站均值 **16.67 MiB/步**,有闸门的会话是 0.36–0.99 MiB —— 23 小时共 57.7 GiB。被拒的 replay 又喂进 `#2490` 的 planning floor,输出预算被 clamp 113 次(如 10033 → 4220),步数大约翻倍。给 preset 补闸门(或像那台设备一样直接 opt-in)之后风暴就停了。 + --- ## 会话与迁移