前言¶
DSH 的会话跑久了，历史前缀会撑大每次请求的 token 数。原生 Basic 压缩负责给人留一口气，但它不关心这次压缩到底走了没走缓存、也不关心这个模型的缓存价格。lloydzhou/dsh-smart-compaction 就是冲着这个缝来的：它把压缩执行和「经济策略」拆开，执行走缓存优先，策略层默认只做观察、不替用户做决定。
它属于「模型推理」分类，维护者是 lloydzhou。下面介绍这个插件做了什么、怎么装、怎么确认它真的在跑。
这是什么¶
一句话：一个可发布的 npm 包、一个 DSH 插件入口，内部分离压缩执行与自适应经济策略，不需要额外装第二个策略包，不修改 DSH 宿主。
它明确不做三件事：不保证缓存命中、不保证全局最低费用、不伪造模型的货币价格字段。
插件版本跟随 DSH 的三段版本线（0.2.1），RC 序号独立递增。README 里安装示例写的是 0.2.1-rc.1，仓库 package.json 的 version 字段当前是 0.2.1-rc.3；宿主兼容范围由 engines.dsh 单独声明，是 >=0.2.1-rc.3。README 与 package.json 的版本表述不完全一致，实际安装时以你要装的 RC 序号为准，并按目标宿主的兼容范围核对。
核心功能¶
缓存优先压缩¶
引擎以 cacheFirst（默认开）为开关。开着时，摘要请求尽量沿用已有的缓存后缀；关闭时回落到原生 BasicCompactionEngine，同时自适应策略失效。
摘要参数连续性¶
同一个会话、同一个 provider/model 下，原生摘要请求如果没有显式提供 reasoningEffort，插件会从最后一次已路由的 request header 补齐。不同路由之间不继承，已有参数不覆盖。它只修参数连续性，不证明 effort 一定影响缓存。相关讨论见 DSH #11816。
自适应经济策略¶
adaptive.mode 取 off / observe（默认）/ active。策略按每次决策读取，改完不用重启。
RC.3 / RC.5 的公开模型元数据里没有货币价格字段，插件不会假装能读出来。默认缺价时使用 DeepSeek V4.1 Flash 官方峰时 USD 参考价格，并在策略日志的 pricing 里标明来源、日期和参考型号，这不是当前路由的真实账单。referencePriceFallback: false 可以关掉这个兜底；缺价或币种不兼容时返回 missing-prices，固定策略和硬压力保护仍然有效。observe 始终不应用经济建议。
结构化日志¶
启用 cacheFirst 时（不论 adaptive 是否关闭），后端在 info 级别输出 cache-first-compaction/operation 和 cache-first-compaction/result，字段包括 sessionId、唯一 operationId、trigger、status、surfaceChanged，每次 summary attempt 还带持久化的 compactionId。它不写聊天上下文，不记录 prompt、摘要文本、工具输出或原始错误消息。
几个容易误读的点：
summaryAttempts是真正进入 stock summarize hook 的次数，含重试、失败、取消，不等于模型调用次数。llmStreamCalls/calls[]记录的是实际观测到的公开llm/stream调用，evidence字段区分来源。不能把 stream 调用直接当成已计费请求——公开 waterfall 在 adapter 查找、prepare 与真正 dispatch 之前就触发，只有裁剪/无摘要时才是modelCalls: 0、providerDispatch: none。usage.inputTokens是未缓存输入，DSH 三类输入计数互斥，完整计数时promptTokens = inputTokens + cacheReadTokens + cacheWriteTokens。缺失计数记为null而不是 0，失败且未报告 usage 的调用不会当作零消耗。knownUsageTotals只汇总已报告字段，不是完整总成本。
默认 adaptive.mode: observe 时，有请求 header 后会在自动压力检查中记录 adaptive-compaction/decision 结构化 info 日志。这些日志在运行该会话的 DSH 进程日志或日志导出器里找，不在聊天消息里，具体路径由宿主配置决定。
Chat UI 压缩卡片¶
外部 client bundle 复用公开的 conversation.chat.node 的 compaction 与 manual-compaction 渲染插槽，保留摘要和原有估算数量。折叠时是单行，在原文本后追加观测到的摘要流调用数和缓存比例；展开后先看决策与实际执行详情，再看原摘要。诊断采用实验性的 ignorable plugin records，不进模型上下文，最多保留最近 64 次有意义的操作。README 里写明尚未在运行中的 GUI 验证视觉效果，需要更新客户端并刷新后确认。
安装与启用¶
发布到 npm 之后的安装命令（web 与 desktop 两个 profile 装同一个包）：
dsh plugin --profile web add dsh-smart-compaction@0.2.1-rc.1
dsh plugin --profile desktop add dsh-smart-compaction@0.2.1-rc.1
本地开发用 pnpm link，需要注意链接包不会按普通规则从目标 node_modules 解析 peers，这是链接模式的通用提醒，不等于 DSH 解析失败。构建产物打成 tarball 后，由操作者明确执行：
npm ci
npm run build
npm run typecheck
npm test
npm pack
dsh plugin --profile web add ./dsh-smart-compaction-0.2.1-rc.1.tgz
环境要求：Node.js >=24.9.0，验证过的宿主是 DSH 0.2.1-rc.3 与 0.2.1-rc.5，Cordis 4.0.5，Schemastery 3.18.5。README 同时注明「尚未发布到 npm」，说明上述命令是发布流程落地后的形态。
启用与禁用¶
RC.3 / RC.5 会为运行中的 Agent 保留旧引擎版本，公开接口不支持非空会话直接换引擎。切换后必须重启 Web，再恢复原会话，不用新建、不改历史。正在执行的压缩也不要中途重启。
- 启用 bundle 或主开关：启动适配器从当前 standard 配置派生插件引擎。
- 禁用主条目
smart-compaction-integration：保留 bundle 的启动适配器，下次启动注册未经转换的原生 standard，旧 smart-compaction 别名也指向原生配置。 - 禁用整个 bundle：整层 patch 撤销，原宿主 standard 声明恢复。
前端用公开优先级 -10 覆盖原生优先级 0，保留原生注册。smart-compaction-preset-adapter 只是 bundle 的启动连接组件，不是第二个功能开关，不要单独禁用它。
设置表单¶
插件详情页（插件 → 智能压缩）有两个即时写入当前 profile 的设置，对应根条目 smart-compaction-integration 的 volatile 字段：cacheFirst（默认开）和 adaptiveMode（off / observe（默认）/ active）。表单要求 profile 中根条目 id 为 smart-compaction-integration。
两种开关组合的行为：
| cacheFirst | adaptive.mode | 行为 |
|---|---|---|
| true（默认） | observe（默认） | 缓存优先执行；只记录经济建议，不应用建议 |
| true | off | 固定配置的缓存优先执行，不安装策略观察器 |
| true | active | 缓存优先执行，启用有界经济策略 |
| false | off | 原生 BasicCompactionEngine，不安装策略观察器 |
| false | observe / active / 未填写 | 拒绝配置，必须显式设为 off |
典型用法¶
安装并重启宿主后，既有 standard 会话会使用动态派生的压缩配置，不需要另开会话。插件页面显示 agent-preset / Running 只说明 preset 声明已经注册，不证明当前会话真的用了这个引擎，要靠日志确认。
确认一次实际运行：
- 打开宿主 info 级别日志。
- 触发一次自动压力检查或手动
/compact。 - 在宿主进程日志里找
cache-first-compaction/operation与cache-first-compaction/result。 - 实际摘要成功时，宿主日志含
compaction (step pressure): shadowed ...或 overflow recovery；会话持久化日志里有compaction/start、compaction/summary、替换消息和compaction/end。仅工具裁剪用compaction/prune，不会凭空出现 summary 记录。
注意 decisionApplied: true 只表示 active 策略返回了决策，不证明已经压缩，更不代表省了钱。off 不生成策略日志，也没有 header 时不会产生策略检查。后端策略日志带 sessionId / operationId，可以和执行日志对上。
适用场景与注意事项¶
适合已经在用 standard preset、想搞清楚压缩到底有没有走缓存的 DSH 开发者。想先观察再决定，用默认的 cacheFirst: true + adaptiveMode: observe；要用固定缓存优先策略，设 off；要把有界经济建议真正接进决策，设 active。非 standard 的自定义 preset 仍需显式接入，插件不会强行劫持其他压缩实现。
几点要注意：
- 插件以当前 DSH 进程权限运行，安装前应检查源码与许可证（仓库声明 MIT）。
- 安装时可能同时报出该 profile 已有插件的版本冲突。按警告里的包名处理：旧 browser/computer-use、子代理或 usage-stats 的精确版本/范围冲突不属于本插件。优先升级或禁用不兼容插件，不建议直接授予版本豁免。
- 宿主运行库被声明为 peerDependencies，链接安装必须由宿主解析器共享这些库，否则可能出现两份 Session 导致公开插件记录函数的类身份校验失败。诊断失败会输出一次无敏感内容的 warning。
client.inject声明的是宿主提供的 UI/locale 服务依赖，只用于增强压缩展示，不是另一套压缩引擎。Desktop 实际界面启停尚未单独端到端验收。- 不要用
npm install当作激活手段——它只装文件，不激活 Cordis bundle。
结尾¶
这个插件的实际价值在于把「压缩有没有走缓存」和「缓存值多少钱」这两件事拆开，并给观察留出默认路径，而不是一上来就把经济决策塞进执行链路。想进一步核对安装与版本细节，见目录页和仓库：
- 目录页：https://www.skillhub.cn/plugins/lloydzhou/dsh-smart-compaction
- GitHub：https://github.com/lloydzhou/dsh-smart-compaction
