# dsh-context-compression-improved

> [dsh-context-compression-selector](https://github.com/WilliamShi666/dsh-context-compression-selector) 的改进版 fork——面向 DeepSeek Harness 的可审计工具结果上下文压缩选择器，新增正交的**代码骨架压缩门*。

[English](README.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Italiano](README.it.md) · [Русский](README.ru.md) · [Español](README.es.md) · [更新日志](CHANGELOG.zh.md) · [安装教程](docs/installation.zh.md)

> [!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](https://github.com/WilliamShi666/dsh-context-compression-selector#model-support-and-safety)。

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

<!-- host-compat:begin — generated by scripts/sync-hosts.mjs from scripts/hosts.mjs; DO NOT EDIT -->
- **支持的 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）
<!-- host-compat:end -->

## 它是什么

长时运行的 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 触发水位，并开关代码骨架压缩。开关即改即存，刷新后显示已保存状态。

![Context Compression Selector 设置界面](docs/assets/context-compression-selector-settings.png)

## 监控界面

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

![压缩监控面板](assets/board.png)

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

![上下文趋势图](assets/context.png)

## 统计口径与持久化

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

- **存量（当前生效）**——当前上下文面上仍在生效的净节省，随压缩内容进出面而涨落；
- **累计（按 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，分线代码路径由运行时自行选择）；内部包名有意保持与上游一致：

```sh
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——完整步骤（含验证与卸载）见[安装教程](docs/installation.zh.md)。

## 开发

```sh
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](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](https://github.com/WilliamShi666/dsh-context-compression-selector)，作者 WilliamShi666（MIT）。
- fork 新增内容（代码骨架门、工具链、多语文档）：drscrewdriver。
- MIT——见 [LICENSE](LICENSE)（保留上游版权声明）；内置 tokenizer 来源见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。