高保真压缩 helibeiqi/dsh-compaction-pro

dsh-compaction-pro

DeepSeek Harness 的高保真上下文压缩后端 —— dsh-compaction-basic 的无损升级替换。
保留官方全部压力/保留/token 计量策略，只把“摘要质量”这一环换掉。

topic:dsh-plugin

它解决什么问题

长会话里 dsh 会触发上下文压缩（compaction），把早期对话压成一个 checkpoint。官方后端 dsh-compaction-basic 的摘要提示词是英文通用模板，有两个痛点：

1. 丢精确值：数字、文件路径、命令串、错误串、标识符常被“整理”或改写 —— 对量化/编程 Agent 是致命的（一个版本号、一个股票代码、一条命令被改掉，下游就错了）。
2. 只出英文：中文用户的会话被压成英文摘要，回读割裂。

dsh-compaction-pro 只改 summarize() 这一环（官方文档明确标注的唯一子类钩子），其余策略全部继承官方实现。

与官方 dsh-compaction-basic 对比

| 维度 | dsh-compaction-basic（官方唯一实现） | dsh-compaction-pro |
| 摘要提示词 | 英文通用模板 | 高保真模板：强制保留精确数值/路径/命令/标识符 |
| 语言 | 强制英文输出 | 跟随会话语言（中文会话→中文摘要，代码/标识符逐字保留） |
| 决策还原 | 仅“关键决策” | 决策 + 理由 + 被否决的替代方案（贴合真实推理方式） |
| 大区段处理 | 单次摘要，易在 maxTokens 处被截断 | 可选递归分块：先压每块、再合并，长会话不丢信息 |
| 工具结果 | 笼统保留 | 单列「关键工具输出」段（返回结构/重要返回值/文件片段） |
| 自定义 | 无 | customInstruction 可整段替换提示词 |
| 策略/保留/计量 | 官方实现 | 完全一致（继承自 BasicCompactionEngine） |

一句话：官方做“压得动”，pro 做“压不歪”。

快速开始

方式 A：本地开发（无需构建、无需发布）

dsh 的 loader 直接加载 .ts 源文件（内部 transpile；官方 dev 用 node --import tsx）。
把下面这段加进你的 ~/.dsh/cordis.patch.yml（升级安全，重启自动重挂）：

若你的 dsh 构建只认已编译 JS，先 npm run build 再把 name 指向 lib/index.js 即可，其余不变。

- id: compaction-pro
name: 'C:/Users//dsh-plugins/dsh-compaction-pro/src/index.ts'
config:
faithful: true
recursive: true
summaryLanguage: auto
thresholdRatio: 0.8
retainRatio: 0.16
maxTokens: 8192

⚠️ 必做（否则 dsh 启动即崩）：本插件与内置 dsh-compaction-basic 都注册同一个 ctx.compaction 服务，二者不能同时启用。cordis 会在启动时抛 "ctx.compaction already provided" 类错误。请在同一个 cordis.patch.yml 里显式禁用 basic（下面两步放一起即可）：

1) 禁用内置后端
- id: compaction-basic
disabled: true
2) 注册 pro 后端
- id: compaction-pro
name: 'C:/Users//dsh-plugins/dsh-compaction-pro/src/index.ts'
config:
faithful: true
recursive: true
summaryLanguage: auto
thresholdRatio: 0.8
retainRatio: 0.16
maxTokens: 8192

方式 B：从 npm 安装（推荐）

dsh plugin --profile web add dsh-compaction-pro

安装后，仍需在 ~/.dsh/profiles/web/cordis.patch.yml 里禁用内置 dsh-compaction-basic（见上方「⚠️ 必做」说明），否则两个 ctx.compaction 后端冲突、dsh 启动即崩。本插件已在 apply() 里打印启动自检横幅提示该冲突。

配置项

| 配置 | 类型 | 默认 | 含义 |
| faithful | boolean | true | 强制保留精确数值/路径/命令/标识符，绝不改写 |
| summaryLanguage | 'en' \| 'zh' \| 'auto' | 'auto' | 摘要语言；auto 跟随会话语言 |
| recursive | boolean | true | 大区段先分块压、再合并，避免截断丢信息 |
| chunkMessages | number | 40 | recursive 开启时每个分块的消息数 |
| customInstruction | string | — | 整段替换内置摘要提示词 |
| thresholdRatio | number | 0.8 | 上下文窗口的压缩触发比例（继承自官方） |
| retainRatio | number | 0.16 | 保留近期尾部的比例（继承自官方） |
| maxTokens | number | 8192 | 摘要生成上限（继承自官方） |
| summarizationProvider / summarizationModel | string | '' | 留空则复用会话路由模型，否则钉死摘要模型 |

工作原理

BasicCompactionEngine (官方：压力/保留/token 计量 + 事务)
▲ extends
ProCompactionEngine (本插件：只重写 summarize() 钩子)
▲ 重写
proSummarize()
├─ 复用会话自身 system/tools/消息前缀 → ctx.llm.stream({ purpose: 'compaction' }) │ （前缀缓存复用，不失效 provider 热缓存） ├─ 追加高保真提示词（faithful + 双语 + 决策/理由 + 工具输出） └─ recursive：区段过大时先分块压、再合并

- 注册为 ctx.compaction，取代内置后端；所有调用方（compactIfNeeded / compactNow / /compact 命令）无感切换。
- 摘要走 ctx.llm.stream() 直连，可在 llm/stream 处统一拦截；abort/资源释放会中止进行中的摘要。

开发 & 构建

npm install # 安装 typescript / tsx（peer 由 dsh 运行时提供）
npm run typecheck # 类型检查（无产物）
npm run build # 产出 lib/（发布用）

本地联调：编辑 src/.ts 后重启 dsh 即可（loader 直跑 .ts）。

⚠️ 开发陷阱（已踩，省你时间）

这些坑在官方文档里不会写，是实际对着已发布包类型定义踩出来的：

1. dsh-compaction-basic/src/summarizer 子路径在已发布包里是死链接。
官方 README 暗示可以从 …/src/summarizer 拿 SummarizationInput / SummaryResult，但已发布的 npm 包只含 lib/ + lib/types/，没有 src/；而且根入口 @deepseek-ai/dsh-compaction-basic 不 re-export 这两个类型。
所以消费者无论类型检查还是运行时都拿不到它们。本插件的解法：在 src/types.ts 里逐字镜像这两个类型（只依赖 dsh-llm 里确实导出的 ContentBlock/Message/ToolSchema/TokenUsage），完全绕开死子路径。

2. schemastery v3 没有静态 literal / union 工厂。
z.literal('x')、z.union([...]) 会报 Property 'literal' does not exist。
字符串枚举改用 z.string() 并在注释里写明取值集合；object/number/string/ boolean/array 才是可用的静态工厂。

3. 类型检查要对着真实 dsh 运行时类型做。
@deepseek-ai/ 装在 dsh 自己的 node_modules 里。最稳的做法是把 dsh 运行时的 @deepseek-ai 作用域整坨拷进本插件的 node_modules/@deepseek-ai（约 28MB），再普通 tsc 解析即可，不必折腾 paths / baseUrl 的 Windows 绝对路径坑。

4. 相对导入用 .ts 扩展名 + allowImportingTsExtensions。
import { x } from './foo.ts'，配合 tsconfig 的 allowImportingTsExtensions: true
与 noEmit: true（发布构建时再切到 .js 扩展名）。

当前验证状态

- ✅ 类型检查通过：对着真实 dsh 运行时类型（@deepseek-ai/dsh-compaction-basic 的 BasicCompactionEngine、protected summarize() 钩子签名、z.object 配置形态）零报错。
这证明了继承关系、override 签名、配置 schema 形状都正确。
- ✅ 运行时验证通过（2026-08-17）：在真实 dsh web 实例（profile web，端口 8787）干净启动、零错误日志；dsh --profile web --dump-config 确认 compaction-pro 作为唯一 ctx.compaction 提供方生效、compaction-basic 已被禁用；浏览器实测 /compact 命令可发现并触发。
- ⚠️ 尚未端到端验证：摘要 LLM 的实际输出质量（faithful / 双语 / 递归分块）需要在配好 API Key 的真实会话里跑一次 /compact 才能确认。插件本身已确认正确加载与接管，这一步不影响"它作为后端生效"的结论。

测试

本插件带一套 vitest 单元测试，覆盖纯逻辑层（指令构建、配置解析、摘要编排），并通过 mock 拦截 @deepseek-ai/dsh-llm，无需真实 cordis 运行时或 API Key 即可离线运行：

npm install # 含 .npmrc：legacy-peer-deps，跳过重型 cordis 依赖
npm test # vitest run —— 覆盖 buildInstruction / partialInstruction /
mergeInstruction / resolveProConfig / proSummarize 全部分支

测试重点验证了修复过的真实缺陷：当 summarizationProvider / summarizationModel 未配置（文档默认"复用会话路由模型"）时，必须回落到路由模型而非崩溃。
CI 在每次 push / PR 到 main 时自动运行 npm test（见 .github/workflows/ci.yml）。

兼容性

- 测试版本：dsh v0.1.0-rc.6（DeepSeek Harness 开发者预览期）。
- API 稳定性警告：dsh 处于早期、官方明确会有 兼容性破坏性变更。本插件通过继承 BasicCompactionEngine 并复用其内部实现细节（src/types.ts 镜像了官方未导出的 SummarizationInput / SummaryResult，构造函数需剥离 pro-only 配置键）。上游一旦改动这两个内部契约，本插件可能静默失效或崩溃——届时请升级到对应的 dsh-compaction-pro 版本。README 的「开发陷阱」一节列出了全部已知耦合点，升级 dsh 后请优先核对。

许可证

MIT © dsh-compaction-pro contributors

标签：deepseek-harness · dsh-plugin · compaction · context · summarization