drscrewdriver/dsh-context-compression-improved

dsh-context-compression-improved

dsh-context-compression-selector 的改进版 fork——面向 DeepSeek Harness 的可审计工具结果上下文压缩选择器，新增正交的*代码骨架压缩门。

English · 日本語 · 한국어 · Français · Deutsch · Italiano · Русский · Español · 更新日志 · 安装教程

[!NOTE] *本fork 在上游 0.1.0 之上新增：

• 正交的代码骨架压缩门（codeSkeleton.enabled，默认关闭）：超大源码类工具结果首次曝光时，可先保留导入与声明的骨架——省略函数体并保留错误行——再进入常规 reducer。
• 同一选择器设置区内新增该门的开关，独立于所有压缩 Profile。
• 接入 CI 的 ESLint 基线、test:watch TDD 环路，以及英/中日韩四语文档。

[!IMPORTANT] 本项目仅支持 DeepSeek 模型。无损测量与有损压缩依赖内置的 DeepSeek 官方 tokenizer（deepseek-v4-flash、deepseek-v4-pro、deepseek-v4-flash-vision-exp）。其余模型一律 fail-open 并保留原始工具结果。完整安全模型见上游 README。

[!TIP] 推荐接入方式：用 API key 以自定义 Responses API 连接 DeepSeek。 建议走自定义 OpenAI 兼容端点（/v1/responses）而不是官方账号的 Messages API 路由：前者不经过 Anthropic 风格的消息序列化，不会因为 message 格式而出现问题，可避开 tool_use/tool_result 配对校验限制（官方路由 resume-replay 时的 400 插件侧无法修复）；也便于按时间切换节点后接续会话。

• 支持的 DSH 宿主： 0.1.0-rc.2 0.1.0-rc.3 0.1.0-rc.6 0.1.0-rc.7 0.1.0-rc.8 0.1.1-rc.1 0.1.1-rc.2 0.1.2-rc.1 0.1.5-rc.1 0.1.5-rc.2 0.1.5-rc.3 0.1.7-rc.1 0.1.7-rc.2 0.2.0-rc.1 0.2.0-rc.2 0.2.1-rc.1 0.2.1-rc.2 0.2.1-rc.3 0.2.1-rc.4 0.2.1-rc.5（覆盖 0.1.0 / 0.1.1 / 0.1.2 / 0.1.5 / 0.1.7 / 0.2.0 / 0.2.1 七条线共 20 个 rc）

它是什么

长时运行的 agent 任务会积累大量工具输出。本社区插件在不修改 DeepSeek Harness 核心的前提下，提供可选、可审计的工具结果上下文压缩策略：

• Fresh：在模型收到之前，预压缩新近超限的工具结果段。
• Aggregate：当 Fresh 压缩后仍超出预算时再次预压缩。
• History / micro-compact：在保护近期工作上下文的前提下替换符合条件的旧工具结果。
• TailTrim：仅在 Custom 下可选的尾窗收缩路径。
• Native：把 Harness 原生头中尾裁剪保留为一个显式 Profile。
• 代码骨架（新增，正交门）——见下节。

每个决策都会留痕：阶段、reducer、触发原因、跳过原因，以及可得时的精确 token 数。

代码骨架门（新增）

开启后，超大源码类新工具结果（例如大型 read_file）会先尝试骨架化压缩：保留导入与类型/函数/类声明，省略函数体并加占位标记，被省略函数体内的错误行予以保留。若骨架无法生成或无法通过验证，则回退到原有的头部裁剪——这道门不会让上下文变得更差。

特性：

• 正交：独立于所选 Profile（balanced、savings、cache-strict、adaptive、custom、off、native），所有 Profile 都能拿到这道门。
• 默认关闭：codeSkeleton: { enabled: false }，需要显式开启。
• 测量前置：需要精确 DeepSeek tokenizer；不可用时 fail-open。
• 会话冻结：与所有选择器设置一致，修改只影响新观察的会话。
• 严格解析：codeSkeleton 必须恰好是 { enabled: boolean }；畸形输入在运行时侧抛错、浏览器侧显示不可读。

设置界面

在同一设置区内选择压缩 Profile、调整 Auto Compact 触发水位，并开关代码骨架压缩。开关即改即存，刷新后显示已保存状态。

监控界面

压缩运行时，插件提供节省量的实时视图：压缩监控悬浮面板——净节省/毛节省/抵消/上下文占用/缓存命中率/成本估算/回合末意图摘要状态，面板内可直接对当前会话恢复或停用——以及会话的上下文趋势图。

压缩会话的上下文趋势：逐步骤/轮次的 token 组成与耗时叠加，剪刀标记指示裁剪/折叠落点。

统计口径与持久化

节省统计分三个口径，语义不同、互不替代：

• 存量（当前生效）——当前上下文面上仍在生效的净节省，随压缩内容进出面而涨落；
• 累计（按 N 次 call）——每个请求边界对存量的采样求和，回答"历史上总共省了多少"，跨宿主重启保留；
• 省钱估计——累计按缓存命中/未命中分权折算官方牌价（仅 deepseek-official 官方路由可解，其余只显示 token 口径）。

统计经 SQLite 持久化（~/.dsh/storages/dsh-context-compression/stats.sqlite），跨宿主重启保留；驱动缺席或写失败时可见降级（面板标注，统计退回内存口径）。历史会话可从磁盘行为记录回填统计（宿主 sessionQuery 服务优先，缺席时只读解析会话日志，绝不写会话文件）。记录只含计数/序号/会话标识与组件枚举名，原文与自由文本绝不入库；删除该文件即可完全重置统计。

/ccip 命令提供面板实时控制：rows stock|total|money on|off（行开关）、mode compact|full、session <id|latest|off>（聚焦会话）、flush（强制落库）、backfill pause|resume|status（回填开关）。

安装

从源码构建并安装 —— 本 fork 亦已发布到 npm，包名为 dsh-context-compression-improved（单版本覆盖全部支持线：latest 携带 17 个 rc 的完整枚举 0.1.0-rc.2 → 0.2.1-rc.2，分线代码路径由运行时自行选择）；内部包名有意保持与上游一致：

git clone https://github.com/drscrewdriver/dsh-context-compression-improved.git
cd dsh-context-compression-improved
pnpm install --frozen-lockfile
pnpm build

随后打包 selector 包并安装到某个 Harness Profile——完整步骤（含验证与卸载）见安装教程。

开发

pnpm install --frozen-lockfile
pnpm lint          # ESLint 基线（CI 同步强制）
pnpm typecheck     # runtime + selector + tests tsc，含 bundle 步
pnpm test          # vitest 全量
pnpm test:watch    # TDD 环路：先写失败的回归用例，再让它通过
pnpm build
pnpm verify:release

贡献遵循上游纪律：先写失败的回归用例；所有生产改动收敛在本仓库内；对“已触发”“已启用但跳过”“fail-open”分别给出证据。见 CONTRIBUTING.md。

兼容性

• 基于官方 DeepSeek Harness 发布版构建并测试；peers 声明完整支持清单枚举（0.1.0-rc.2 → 0.2.1-rc.2 七条线），仅使用公开的插件与 Profile API。支持清单由 scripts/sync-hosts.mjs 从 scripts/hosts.mjs 生成到上方管理块。
• 需要 Node ^22.19.0 || >=24 与 pnpm 11.7.0。
• 插件只使用 Harness 公开扩展 API，不修改 Harness 核心代码。非官方社区项目，与 DeepSeek 无隶属或背书关系。

致谢与许可

• 上游项目与全部既有工作：WilliamShi666/dsh-context-compression-selector，作者 WilliamShi666（MIT）。
• fork 新增内容（代码骨架门、工具链、多语文档）：drscrewdriver。
• MIT——见 LICENSE（保留上游版权声明）；内置 tokenizer 来源见 THIRD_PARTY_NOTICES.md。