Skip to content

[PR] docs: document the compaction gate for custom agent presets - #3568

Closed
ygpking wants to merge 2 commits into
ranxianglei:masterfrom
ygpking:docs/custom-preset-compaction-gate
Closed

ygpking wants to merge 2 commits into
ranxianglei:masterfrom
ygpking:docs/custom-preset-compaction-gate

Conversation

@ygpking

@ygpking ygpking commented Oct 17, 2026 •

Copy link
Copy Markdown

这次改了什么

只改文档:在 CONFIGURATION.zh-CN.md / CONFIGURATION.md 的 dsh.allowDshCompaction 附近补一节「自定义 agent preset 的压缩闸门」,把 #3354 覆盖不到的那一类 preset 写清楚,附一台真实设备的实测数据。

为什么需要

src/agent/dsh-compaction-disable.ts:35 的闸门名单是硬编码的:

const DSH_WEB_PRESET_IDS = ["preset-standard", "preset-ptc", "preset-minimal", "preset-cordis"] as const;

dsh.bundle.patch.yml 也只给这四行加 inject: [biliBasicCompactionPolicy]。而 dsh 允许用第三方 bundle 声明自己的 agent preset——这种 preset 的 compaction-basic 行不在名单里,没有 inject 闸门,加载期 overlay 与它的解析顺序就没有保证,于是 dsh 原生压缩可能保持 armed,压缩请求被 #1729 在线上逐条拒收(422 dsh_compaction_refused),而用户在 UI 上什么都看不到。

实测(可作为该症状的定量参考)

一台 Android 16 / arm64 / proot 的手机(dsh 2.0.0-rc.2 + bili 0.1.197,98 个会话,其中 70 个跑自定义 preset):

  • 5,090 次压缩请求全部 422,单会话最高 3,254 次;
  • 上下文因此钉在窗口上限,单会话均值入站 16.67 MiB/步(其余会话 0.36–0.99 MiB),23 小时合计 57.7 GiB;
  • 被拒的 compaction replay 又触发 dsh压缩与bili压缩冲突 #2490 的 planning floor,输出预算被 clamp 113 次(如 10033 → 4220),单步被砍成多步,请求数再翻倍。

也就是说:这不是"日志里有几条 422",而是单会话 97% 的入站流量。

文档给出的两条出路

  1. 给该 preset 补一行闸门(cordis.patch.yml):
- id: <你的 preset id>
  inject: [biliBasicCompactionPolicy]
  1. 或按 fix(dsh): profile 层 patch 其实可以关掉 web profile 的原生自动压缩(#1772 结论修正)+ 一个会静默清空整个 preset 的写法坑 #2474 全量快照覆盖该 preset 的 compaction-basic 行(config 是整体替换,默认项要一起写)。

另外说明:dsh native 安装(bili plugin install dsh)下 launcher 的 overlay patch 整段跳过(src/launcher.ts:5161 的 if (!dshNativeInstalled())),所以闸门必须落在 profile 自己的 patch 层——这一点现在只在启动 warning 里说,文档里没提。

后续(不在本 PR 内)

真正的修法是让闸门名单不再硬编码:安装期扫描 profile 的 patch 层(含 dsh.profile.bundles 声明的那几个 bundle 各自的 cordis.patch.yml),把其中的 name: '@deepseek-ai/dsh-agent-preset' 条目 id 一并写进闸门行。这需要在 plugin-install 路径做文件发现,我没有你们的测试环境(容器里连不上 npm,跑不了 pnpm test),所以没有盲写代码进这个 PR。

ranxianglei#3354 的闸门名单只有四个内置 preset;由第三方 bundle 声明的 agent preset 不在名单里,也没有
inject 闸门,加载期 overlay 与它的解析顺序没有保证,dsh 原生压缩保持 armed,压缩请求被 ranxianglei#1729
逐条拒收(422)而 UI 无感。补中英两版文档:症状、两条自救路(补 inject 闸门 / ranxianglei#2474 全量快照)、
以及 dsh native 安装下 launcher overlay 被跳过这一层原因。附一台真机的实测代价。
@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

查重: 不重复。检索 open+closed issue/PR(关键词 custom preset / 3354):仅本 PR 命中「custom preset」,#3354 本体已由已关闭的 PR #3451 落地(load-time overlay + 闸门行),本 PR 是对其文档盲区(第三方 bundle preset 不在闸门名单)的补充,无并行在途工作。

初审状态:PR 里的事实性论断我已逐条对 master 源码核验——DSH_WEB_PRESET_IDS 四内置名单(src/agent/dsh-compaction-disable.ts:35)、inject 闸门的服务名与格式(compactionDisablePatchRows())、native install 下 writeDshAcpPatch 被跳过(src/launcher.ts:5161)、启动警告文案(src/launcher.ts:5176)、422 dsh_compaction_refused(src/server/dsh-compaction-guard.ts:287)、checkpoint 不可逆语义(CONFIGURATION.md BILI_ALLOW_DSH_COMPACTION 条目)——全部属实。真机代价数据无法本地复现,但机制链与既有文档记载一致。

发现两处文档质量问题(非事实错误):①新段落插在顶层配置键参考区(compactionOptIn 与 compat 之间),而该区域每节都是「Type/Default/Status/Description」键条目,prose 节放这里破坏结构——仓库已有同主题章节(CONFIGURATION.md「Turning dsh native auto-compaction OFF in a web profile (#1772/#3354)」),新内容应紧邻它;②yaml 注释里的路径写法(未闭合的反引号 + /.dsh/… 前导斜杠)不符合仓库 $DSH_HOME/profiles/<name>/cordis.patch.yml 惯例。两处我直接在 PR 分支上补 commit 修掉,随后按八问给完整 review 结论。

…web-profile section; normalize patch path in yaml example

Reviewer alignment for ranxianglei#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 ranxianglei#1206 block under "Plugin Mode (native tools)", directly beside the
  existing ranxianglei#3354/ranxianglei#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/<name>/cordis.patch.yml (cf. the ranxianglei#2474 recipe).
Both EN and ZH files moved symmetrically.
@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

Review 结论(结构化八问)

  1. 是什么问题:See how to integrate the plugin that automatically disables dsh compression. | 自动关闭 dsh 压缩的插件看如何集成 #3354 的加载期闸门只覆盖四个内置 Web preset;第三方 bundle 声明的 agent preset 不在名单、不带 inject 闸门,dsh 原生压缩保持 armed,所有压缩请求被 nudge 死锁无检测:同一 session 交替收到两种结构互斥的请求流(巨型单消息 ↔ 多轮)时不告警 #1729 线侧闸门拒收(422 dsh_compaction_refused),UI 无感——用户既不知道发生了什么,也不知道怎么修。本 PR 补这个文档盲区。
  2. 什么原因导致的:文档缺口而非代码缺陷。See how to integrate the plugin that automatically disables dsh compression. | 自动关闭 dsh 压缩的插件看如何集成 #3354 落地时文档只写了内置名单的覆盖与 fix(dsh): profile 层 patch 其实可以关掉 web profile 的原生自动压缩(#1772 结论修正)+ 一个会静默清空整个 preset 的写法坑 #2474 fallback,没写「preset 在闸门之外」时的表现与自救路径。底层机制是 preset 注册顺序 vs overlay 注册顺序:未挂闸门的 preset 可能在 bili 的 internal/config 中间件注册前就解析完成(src/agent/dsh-compaction-disable.ts 头部注释所述 fail-safe 语义)。
  3. 影响范围与严重程度:特定条件下的问题——dsh web profile + 以独立 bundle 安装第三方助手 preset + bili 承载压缩的用户面。功能不坏(线侧闸门保证 checkpoint 无法落地,会话照常工作),但有实测代价:入站均值 16.67 MiB/步 vs 有闸门的 0.36–0.99 MiB、输出预算被 dsh压缩与bili压缩冲突 #2490 planning floor clamp 113 次、步数约翻倍。
  4. 怎么修复的:纯文档——中英两节:症状、两条自救路(补一行 inject: [biliBasicCompactionPolicy] 闸门 / fix(dsh): profile 层 patch 其实可以关掉 web profile 的原生自动压缩(#1772 结论修正)+ 一个会静默清空整个 preset 的写法坑 #2474 全量快照覆盖)、native install 下 launcher overlay 被跳过这一层原因、真机代价数据。我另做了一处对齐重构(commit 26161f092,已推到本分支):原插入位置在顶层配置键参考区(compactionOptIn 与 compat 之间,该区域每节都是 Type/Default/Status/Description 键条目),prose 节放那里破坏结构——现移至「Plugin Mode (native tools)」下、紧邻既有 See how to integrate the plugin that automatically disables dsh compression. | 自动关闭 dsh 压缩的插件看如何集成 #3354/fix(dsh): profile 层 patch 其实可以关掉 web profile 的原生自动压缩(#1772 结论修正)+ 一个会静默清空整个 preset 的写法坑 #2474 web-profile 章节之后;yaml 示例注释的未闭合反引号与 /.dsh/… 路径改为仓库惯例 $DSH_HOME/profiles/<profile>/cordis.patch.yml(同文件 fix(dsh): profile 层 patch 其实可以关掉 web profile 的原生自动压缩(#1772 结论修正)+ 一个会静默清空整个 preset 的写法坑 #2474 recipe 的写法)。内容其余逐字保留,中英对称移动。
  5. 是否有回归问题:无代码改动、无行为变更。审过的既有行为:相邻键条目(compactionOptIn/compat)未受扰;新节内容与既有「Turning dsh native auto-compaction OFF in a web profile (dsh.bundle.patch.yml 禁用自动压缩在 web profile 下静默失效 #1772/See how to integrate the plugin that automatically disables dsh compression. | 自动关闭 dsh 压缩的插件看如何集成 #3354)」章节及 BILI_ALLOW_DSH_COMPACTION 条目逐一对照无冲突。事实断言全部对 master 源码核验通过:DSH_WEB_PRESET_IDS 四内置名单(src/agent/dsh-compaction-disable.ts:35)、服务名与 patch 行格式(:31、:43-45)、native install 跳过逻辑(src/launcher.ts:5161-5162)、启动警告文案(src/launcher.ts:5176)、422 拒收码(src/server/dsh-compaction-guard.ts:287)、checkpoint 不可逆语义(CONFIGURATION.md BILI_ALLOW_DSH_COMPACTION 条目)。真机数字无法本地复现,机制链与既有文档记载一致,予以采信。
  6. 是否破坏缓存:不涉及(纯文档)。
  7. 是否改了设计方向:不涉及。
  8. 是否引入了新的配置:不涉及(dsh.allowDshCompaction 与 profile patch 层均为既有机制,本节只做记载)。

判定:可合。docs-only,无配置面/线协议/持久化格式触碰;对齐 commit 已在分支上(a1d3650b6..26161f092),等 CI 在新 head 上绿后合入即可。

@ranxianglei

Copy link
Copy Markdown
Owner

(ai: zhipuai-lb/glm-5.3)

孤儿票清理:提交两周未更新、无 issue 关联,且相关领域已有后续修复落地。为避免重复劳动关闭;如果你想继续推进,请 reopen 并补一个关联 issue(Fixes #N),我们会优先审查。感谢贡献!

@ranxianglei ranxianglei changed the title docs: document the compaction gate for custom agent presets [PR] docs: document the compaction gate for custom agent presets Oct 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants