dsh-context-compression-improved 0.1.1 → 0.2.1

package/README.md

@@ -1,26 +1,103 @@
 # dsh-context-compression-improved
 
-The installable Product Bundle for the unofficial community DeepSeek Harness context-compression selector.
+> An improved fork of [dsh-context-compression-selector](https://github.com/WilliamShi666/dsh-context-compression-selector) — an auditable tool-result context-compression selector for DeepSeek Harness — adding an orthogonal **code-skeleton compression gate**.
 
-**0.1.0 highlights:** DeepSeek V4 Flash Vision's official tokenizer is included; users can choose the model-driven Auto Compact threshold; standard profile watermarks and compression parameters follow that choice.
+[中文说明](README.zh.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Changelog](CHANGELOG.md) · [Installation guide](docs/installation.md)
+
+> [!NOTE]
+> **What this fork adds on top of upstream 0.1.0:**
+>
+> - An orthogonal **code-skeleton compression gate** (`codeSkeleton.enabled`, default off): the first exposure of an oversized fresh source-code tool result can keep a skeleton of imports and declarations — bodies elided, error lines kept — before the regular reducers run.
+> - A settings toggle for that gate in the same selector settings section, independent of every compression profile.
+> - An ESLint baseline wired into CI, a `test:watch` TDD loop, and documentation in English, Simplified Chinese, Japanese, and Korean.
+
+> [!IMPORTANT]
+> This project supports **DeepSeek models only**. Lossless measurement and lossy compression depend on the bundled official DeepSeek tokenizers (`deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-v4-flash-vision-exp`). Everything else fails open and keeps original tool results. See the [upstream README](https://github.com/WilliamShi666/dsh-context-compression-selector#model-support-and-safety) for the full safety model.
+
+## What it is
+
+Long-running agent tasks accumulate a large amount of tool output. This community plugin adds selectable, auditable policies for reducing that tool-result context without modifying DeepSeek Harness core:
+
+- **Fresh** pre-compresses a newly oversized tool-result segment before the model receives it.
+- **Aggregate** pre-compresses fresh material again when it still grows beyond its budget.
+- **History / micro-compact** replaces eligible old tool results while preserving recent working context.
+- **TailTrim** is an optional Custom-only tail reduction path.
+- **Native** preserves the Harness-style head/middle/tail trimming as one explicit profile.
+- **Code skeleton (new, orthogonal gate)** — see below.
+
+Every decision is recorded: stage, reducer, trigger, skip reason, and exact token counts where available.
+
+## Code skeleton gate (new)
+
+When the gate is enabled, an oversized **fresh source-code tool result** (for example a large `read_file`) first tries a skeleton reduction: imports and type/function/class declarations are kept, function bodies are elided with a marker, and error lines inside elided bodies are preserved. If the skeleton cannot be produced or verified, the result falls back to the original head pruning — the gate can never make context worse.
+
+Properties:
+
+- **Orthogonal**: independent of the selected profile (`balanced`, `savings`, `cache-strict`, `adaptive`, `custom`, `off`, `native`). All profiles get the gate.
+- **Off by default**: `codeSkeleton: { enabled: false }` until you turn it on.
+- **Measurement-gated**: requires the exact DeepSeek tokenizer; without it the plugin fails open.
+- **Session-frozen**: like all selector settings, changes affect newly observed sessions only.
+- **Strictly parsed**: `codeSkeleton` must be exactly `{ enabled: boolean }`; malformed values throw on the runtime side and show as unreadable in the browser UI.
+
+### Provenance, and whose numbers these are
+
+The skeletonization approach is borrowed from **[Headroom](https://github.com/headroomlabs-ai/headroom)**
+(Apache-2.0) — a context-compression layer for AI agents that routes JSON, source code and prose
+through separate compressors (`SmartCrusher` for JSON, `CodeCompressor` for code), with its
+skeleton transform living in `crates/headroom-core/src/transforms/live_zone.rs` and
+`smart_crusher/planning.rs`.
+
+**The reduction figures are Headroom's, not this plugin's.** Headroom's published claim, verbatim:
+
+> 20% fewer tokens for coding agents, **60–95% fewer tokens for JSON**, same answers.
+
+The headline — **up to 95% fewer tokens** — comes from that sentence: JSON payloads, measured by
+Headroom's own compressors on Headroom's own benchmarks. That is the same source this gate draws
+its mechanism from. This repository ships **no benchmark of its own**, so it claims **no reduction
+percentage of its own**; read the measurements at the source.
+
+## Settings UI
+
+Choose a compression profile, set the Auto Compact trigger level, and toggle code-skeleton compression in the same settings section. The toggle saves on change and shows the saved state on reload.
+
+![Context Compression Selector settings UI](packages/selector/assets/screenshots/context-compression-selector-settings.png)
+
+## Install
+
+Build and install from source (this fork is not yet published to npm; the internal package names intentionally stay upstream's):
 
 ```sh
-dsh plugin --profile web add dsh-context-compression-improved@latest
-dsh --profile web --dump-config
+git clone https://github.com/drscrewdriver/dsh-context-compression-improved.git
+cd dsh-context-compression-improved
+pnpm install --frozen-lockfile
+pnpm build
 ```
 
-This one command installs the Bundle and its pinned `@huggingface/tokenizers` dependency; there is no separate runtime package. The Bundle contributes Host settings, the Web UI, and a reversible preset overlay. All presets except the exact built-in `minimal` id receive the compression stack; switching non-Minimal presets preserves the saved selector settings. Minimal pauses plugin compression without deleting the setting.
+Then pack the selector package and add it to a Harness profile — the full walkthrough, including verification and uninstall steps, is in the [installation guide](docs/installation.md).
 
-## What it provides
+## Development
 
-It provides deterministic Fresh, Aggregate, History, Native tool-result, and Custom TailTrim compression; a plugin-owned `context_compression_retrieve` recovery tool; structured audit records; and a pinned offline DeepSeek V4 tokenizer. It uses only public DeepSeek Harness APIs and supports both `0.1.1-rc.2` and `0.1.2-alpha.5`; it does not patch Harness core.
+```sh
+pnpm install --frozen-lockfile
+pnpm lint          # ESLint baseline (also enforced in CI)
+pnpm typecheck     # runtime + selector + tests tsc, plus the bundle step
+pnpm test          # full vitest suite
+pnpm test:watch    # TDD loop: write the failing regression first, then make it pass
+pnpm build
+pnpm verify:release
+```
 
-Lossy rewrites require exact same-revision counts before and after replacement. Verified model ids are `deepseek-v4-flash`, `deepseek-v4-pro`, and `deepseek-v4-flash-vision-exp`. Vision text counting uses the separately pinned `deepseek-ai/DeepSeek-V4-Flash-Vision-Exp` tokenizer. Vision images use the official image-processor arithmetic validated against official golden fixtures and are reported as `tokenizer-estimate`: the four alignment residues over valid intrinsic dimensions are collapsed to their midpoint, with 384 tokens retained as the per-image upper bound; malformed or unevaluable dimensions use a fixed 256-token fallback. The estimate is not exact because the absolute prompt position and the adapter's final image projection are not publicly observable. Image-bearing tool-result candidates remain exact-ineligible and intact; unknown models, unavailable tokenizer assets, unsafe tool groups, and incomplete text measurements still fail open.
+Contributions follow the upstream discipline: add the failing regression first, keep every production change inside this repository, and explain “triggered”, “enabled but skipped”, and fail-open evidence separately. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-Audit log records use the prefix `context-compression audit ` and distinguish policy snapshots, skipped/disabled components, committed rewrites, fail-open errors, and observed core `compaction/summary` events. No audit record contains prompt or tool-result content.
+## Compatibility
 
-The first `policy-frozen` record carries the complete settings/deployment snapshot. It is emitted through the Harness logger, so its retention follows the configured log sink; standard prune/replacement Session events remain the durable proof of committed rewrites. This package does not hard-code a private path below `~/.dsh`.
+- Verified against DeepSeek Harness `dsh-v0.1.1-rc.2` using public plugin and profile APIs only; compatible with the official `dsh-v0.1.2-alpha.5` release.
+- Requires Node `^22.19.0 || >=24` and pnpm `11.7.0`.
+- The plugin uses only public Harness extension APIs and does not modify Harness core code. Unofficial community project, not affiliated with or endorsed by DeepSeek.
 
-Verified compatibility: DeepSeek Harness `dsh-v0.1.1-rc.2` and `dsh-v0.1.2-alpha.5`, Node `^22.19.0 || >=24`. No Harness core patch is required.
+## Credits and license
 
-See the [full README](https://github.com/WilliamShi666/dsh-context-compression-improved#readme) for profiles, defaults, audit evidence, Adaptive/cache limitations, upgrade/removal, and security guidance. Tokenizer provenance and checksums are in `assets/deepseek-v4/manifest.json` and `assets/deepseek-v4-vision-exp/manifest.json`, summarized in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). This package is not affiliated with or endorsed by DeepSeek.
+- Upstream project and all prior work: [WilliamShi666/dsh-context-compression-selector](https://github.com/WilliamShi666/dsh-context-compression-selector) by WilliamShi666 (MIT).
+- Fork additions (code-skeleton gate, tooling, localized docs): drscrewdriver.
+- Code-skeleton mechanism: [Headroom](https://github.com/headroomlabs-ai/headroom) (Apache-2.0) — see "Provenance, and whose numbers these are" above.
+- MIT — see [LICENSE](LICENSE) (upstream copyright notice retained) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for bundled tokenizer provenance.

package/README.zh.md

@@ -1,26 +1,101 @@
 # dsh-context-compression-improved
 
-这是可直接安装的非官方社区 DeepSeek Harness 上下文压缩选择器 Product Bundle。
+> [dsh-context-compression-selector](https://github.com/WilliamShi666/dsh-context-compression-selector) 的改进版 fork——面向 DeepSeek Harness 的可审计工具结果上下文压缩选择器，新增正交的**代码骨架压缩门**。
 
-**0.1.0 更新：**已加入 DeepSeek V4 Flash 视觉模型的官方 tokenizer；用户可选择模型驱动 Auto Compact 的触发阈值；标准 Profile 的水位与压缩参数会随该选择联动。
+[English](README.md) · [日本語](README.ja.md) · [한국어](README.ko.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)。
+
+## 它是什么
+
+长时运行的 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 }`；畸形输入在运行时侧抛错、浏览器侧显示不可读。
+
+### 出处，以及这些数字是谁的
+
+骨架化思路借鉴自 **[Headroom](https://github.com/headroomlabs-ai/headroom)**（Apache-2.0）——
+一个面向 AI Agent 的上下文压缩层，把 JSON、源码与散文分别交给不同压缩器（JSON 走
+`SmartCrusher`，代码走 `CodeCompressor`），其骨架化变换位于
+`crates/headroom-core/src/transforms/live_zone.rs` 与 `smart_crusher/planning.rs`。
+
+**降幅数字是 Headroom 的，不是本插件的。** Headroom 公开的官方口径原文如下：
+
+> 20% fewer tokens for coding agents, **60–95% fewer tokens for JSON**, same answers.
+
+其中 **最高降 95%** 即出自这一句：口径为 JSON 载荷，由 Headroom 自家压缩器在其自家基准上测得，
+也正是本门机制的同源出处。本仓库**不含任何自己的 benchmark**，因此**不自称任何降幅百分比**；
+要数字，请到源头读。
+
+## 设置界面
+
+在同一设置区内选择压缩 Profile、调整 Auto Compact 触发水位，并开关代码骨架压缩。开关即改即存，刷新后显示已保存状态。
+
+![Context Compression Selector 设置界面](packages/selector/assets/screenshots/context-compression-selector-settings.png)
+
+## 安装
+
+从源码构建并安装（本 fork 尚未发布 npm 包；内部包名有意保持与上游一致）：
 
 ```sh
-dsh plugin --profile web add dsh-context-compression-improved@latest
-dsh --profile web --dump-config
+git clone https://github.com/drscrewdriver/dsh-context-compression-improved.git
+cd dsh-context-compression-improved
+pnpm install --frozen-lockfile
+pnpm build
 ```
 
-这一条命令会安装 Bundle 及其固定版本的 `@huggingface/tokenizers` 依赖，不再需要单独的 runtime 包。Bundle 提供 Host 设置、Web UI 和可逆的 preset overlay。除 id 精确等于内置 `minimal` 的 preset 外，其他 preset 都会获得压缩能力；非 Minimal preset 之间切换时已保存设置保持不变。Minimal 只暂停插件压缩，不删除设置。
+随后打包 selector 包并安装到某个 Harness Profile——完整步骤（含验证与卸载）见[安装教程](docs/installation.zh.md)。
 
-## 本包能力
+## 开发
 
-本包提供确定性的 Fresh、Aggregate、History、Native 工具结果与 Custom TailTrim 压缩，插件自有的 `context_compression_retrieve` 恢复工具，结构化审计记录，以及固定版本的离线 DeepSeek V4 tokenizer。它只使用 DeepSeek Harness 的公开 API，兼容 `0.1.1-rc.2` 与 `0.1.2-alpha.5`，不修改 Harness 核心。
+```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
+```
 
-有损改写要求 replacement 前后取得同 revision 的 exact count。明确验证过的模型 id 为 `deepseek-v4-flash`、`deepseek-v4-pro` 与 `deepseek-v4-flash-vision-exp`。视觉模型的文本计数使用独立固定的 `deepseek-ai/DeepSeek-V4-Flash-Vision-Exp` tokenizer。图像 token 使用由官方 golden fixtures 逐项验证的官方图像处理算术，并以 `tokenizer-estimate` 上报：有效 intrinsic 尺寸的四种对齐位置取中值，每张图片保留 384 token 上限；尺寸畸形或无法计算时固定计为 256 token。由于绝对 prompt 位置与 adapter 最终图片投影不可公开观测，该数值不标记为 exact。含图片的工具结果候选仍不具备 exact 资格并保持原样；未知模型、tokenizer 资产不可用、不安全工具组或文本计量不完整时继续 fail-open。
+贡献遵循上游纪律：先写失败的回归用例；所有生产改动收敛在本仓库内；对“已触发”“已启用但跳过”“fail-open”分别给出证据。见 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
-审计日志以 `context-compression audit ` 开头，区分策略快照、组件关闭/跳过、已提交 rewrite、fail-open 错误和已观察到的核心 `compaction/summary`。审计记录不包含 prompt 或工具结果正文。
+## 兼容性
 
-首次 `policy-frozen` 会携带完整 settings/deployment 快照。它通过 Harness logger 输出，因此保留期限由部署的日志 sink 决定；标准 prune/replacement Session event 仍是已提交 rewrite 的持久证据。本包不会在 `~/.dsh` 下硬编码私有路径。
+- 仅使用公开的插件与 Profile API，针对 DeepSeek Harness `dsh-v0.1.1-rc.2` 验证；兼容官方 `dsh-v0.1.2-alpha.5` 版本。
+- 需要 Node `^22.19.0 || >=24` 与 pnpm `11.7.0`。
+- 插件只使用 Harness 公开扩展 API，不修改 Harness 核心代码。非官方社区项目，与 DeepSeek 无隶属或背书关系。
 
-已验证兼容：DeepSeek Harness `dsh-v0.1.1-rc.2` 与 `dsh-v0.1.2-alpha.5`，Node `^22.19.0 || >=24`。不需要修改 Harness 核心。
+## 致谢与许可
 
-Profile、默认值、审计证据、Adaptive/cache 限制、升级/卸载与安全说明见[完整 README](https://github.com/WilliamShi666/dsh-context-compression-improved#readme)。Tokenizer 来源与校验和在 `assets/deepseek-v4/manifest.json`、`assets/deepseek-v4-vision-exp/manifest.json`，并汇总于 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。本包与 DeepSeek 无隶属或背书关系。
+- 上游项目与全部既有工作：[WilliamShi666/dsh-context-compression-selector](https://github.com/WilliamShi666/dsh-context-compression-selector)，作者 WilliamShi666（MIT）。
+- fork 新增内容（代码骨架门、工具链、多语文档）：drscrewdriver。
+- 代码骨架机制来源：[Headroom](https://github.com/headroomlabs-ai/headroom)（Apache-2.0）——见上文「出处，以及这些数字是谁的」。
+- MIT——见 [LICENSE](LICENSE)（保留上游版权声明）；内置 tokenizer 来源见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security policy
+
+## Supported versions
+
+During the initial release, only the newest published Beta or stable version is supported. Compatibility is limited to the Harness versions listed in the README.
+
+## Reporting a vulnerability
+
+Please use GitHub's private **Report a vulnerability** flow for this repository. Do not open a public issue containing secrets, exploit details, private Session data, prompts, tool results, or user paths.
+
+Include the affected plugin version, Harness version, minimal reproduction, impact, and whether the issue can alter Session surface/recovery behavior. We will acknowledge a valid report as soon as practical, investigate privately, and publish a coordinated fix and advisory when appropriate.
+
+## Security posture
+
+- The Bundle does not require credentials of its own.
+- Compression and recovery are same-Session operations; audit records omit model-visible content.
+- Unknown models, tokenizer integrity failures, malformed policies, unsafe tool groups, and incomplete exact measurements fail open.
+- NPM tarballs use explicit file allowlists and do not ship source maps, user logs, Sessions, or local configuration.

package/THIRD_PARTY_NOTICES.md

@@ -1,38 +1,14 @@
 # Third-party notices
 
-Portions of this package are adapted from the MIT-licensed DeepSeek Harness, verified against `dsh-v0.1.1-rc.2` (`b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`).
+This community project contains code adapted from the MIT-licensed [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), verified against tag `dsh-v0.1.1-rc.2`, commit `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`.
 
-## DeepSeek Harness MIT notice
+The runtime package distributes tokenizer assets from these pinned official repositories, both under the MIT license:
 
-Copyright (c) 2026 DeepSeek
+- [deepseek-ai/DeepSeek-V4-Pro](https://huggingface.co/deepseek-ai/DeepSeek-V4-Pro) at revision `0e1a0e5e52aea73055f50fef6f2423db370265b6`, recorded in `packages/runtime/assets/deepseek-v4/manifest.json`.
+- [deepseek-ai/DeepSeek-V4-Flash-Vision-Exp](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-Vision-Exp) at revision `6821d6ad3681a4b137b066b76094fa82ebd0a380`, recorded in `packages/runtime/assets/deepseek-v4-vision-exp/manifest.json`. The vision model is served by this distinct tokenizer, never as an alias of the text tokenizer.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Exact file sizes and SHA-256 values are recorded in each directory's `manifest.json`; the upstream license text ships beside the assets.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The install-time production dependency closure also contains `@huggingface/tokenizers` (Apache-2.0), `js-yaml` (MIT), and its `argparse` dependency (Python-2.0). Each dependency ships its own license text in its NPM package.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
-This package also distributes `tokenizer.json` and `tokenizer_config.json` from these pinned official repositories, both under the MIT license:
-
-- `deepseek-ai/DeepSeek-V4-Pro` revision `0e1a0e5e52aea73055f50fef6f2423db370265b6` (serves `deepseek-v4-flash` and `deepseek-v4-pro`), in `assets/deepseek-v4/`.
-- `deepseek-ai/DeepSeek-V4-Flash-Vision-Exp` revision `6821d6ad3681a4b137b066b76094fa82ebd0a380` (serves `deepseek-v4-flash-vision-exp`), in `assets/deepseek-v4-vision-exp/`. This tokenizer is a distinct artifact, not an alias of the V4 Pro tokenizer.
-
-The exact provenance and SHA-256 values are in each directory's `manifest.json`; the upstream license text ships beside the assets. The vision image-token arithmetic is a port of the repository's `inference/image_processor.py` at the same pinned revision.
-
-This package depends on `@huggingface/tokenizers` 0.1.3 under Apache-2.0. Its NPM package carries the dependency license text.
-
-This package depends on `js-yaml` under MIT; its production dependency `argparse` is licensed under Python-2.0. Their NPM packages carry the dependency license texts.
-
-This is an unofficial community package and is not endorsed by DeepSeek.
+The names DeepSeek and DeepSeek Harness identify upstream projects only. They do not imply affiliation or endorsement.

package/docs/installation.ja.md

@@ -0,0 +1,76 @@
+# dsh-context-compression-improved をインストールする
+
+> [English](installation.md) · [中文](installation.zh.md) · [日本語](installation.ja.md) · [한국어](installation.ko.md)
+
+このガイドでは、ソースからフォークをインストールします。このフォークはアップストリームに対して名前が変更されており（`dsh-context-compression-selector` → `dsh-context-compression-improved`）、まだ npm に公開されていません。ソースおよびセッションログに現れる `dsh-context-compression-improved-runtime` は凍結された来歴ラベルであり、パッケージ依存ではありません。実行時の依存は `@huggingface/tokenizers` と `js-yaml` のみです。
+
+## 前提条件
+
+- Node `^22.19.0 || >=24` と pnpm `11.7.0`（`corepack enable` で `packageManager` の固定バージョンが使われます）。
+- `0.1.1-rc.2` peer 範囲に互換する DeepSeek Harness（公式 `dsh-v0.1.2-alpha.5` リリースに対して検証済み）。
+- DeepSeek V4 モデルルート（`deepseek-v4-flash`、`deepseek-v4-pro`、`deepseek-v4-flash-vision-exp`）。コードスケルトンゲートを含む非可逆圧縮には同梱の正確なトークナイザーが必要で、その他のルートは fail-open で元のツール結果を保持します。
+- Git。
+
+## 1. ソースからビルド
+
+```sh
+git clone https://github.com/drscrewdriver/dsh-context-compression-improved.git
+cd dsh-context-compression-improved
+pnpm install --frozen-lockfile
+pnpm build
+```
+
+`pnpm build` はすべてのパッケージの両方のライブラリ成果物をバンドルします（`tsdown`）。インストール前にフルスイートを実行したい場合は `pnpm test` を実行してください。
+
+## 2. Bundle エントリーパッケージを pack
+
+selector パッケージが唯一の Bundle エントリーで、ランタイムはその正確なバージョン依存として付いてきます：
+
+```sh
+cd packages/selector
+pnpm pack
+# → dsh-context-compression-improved-0.1.0.tgz
+cd ../..
+```
+
+`pnpm pack` は `prepack` フック経由でバンドルを実行するため、tarball は常にチェックアウト内容と一致します。
+
+## 3. Harness プロファイルに追加
+
+selector パッケージは Harness Bundle マニフェストフィールド `dsh.bundle.patch` を宣言しているため、`dsh plugin add` が標準のアウトオブツリー Bundle インストール経路になります：
+
+```sh
+dsh plugin --profile web add packages/selector/dsh-context-compression-improved-0.1.0.tgz
+dsh --profile web --dump-config
+```
+
+インストール後、対象プロファイルを再起動してください。設定ダンプに selector Bundle が有効として表示されるはずです。selector と runtime の 2 パッケージを別々にインストール・接続**しないでください**——runtime は自動的にインストールされます。
+
+## 4. コードスケルトンゲートを有効にする
+
+DeepSeek Harness の設定 → **Context compression selector** を開きます：
+
+1. 圧縮プロファイルを選択します（ゲートはすべてのプロファイルに対して直交します）。
+2. 必要に応じて Auto Compact トリガーレベルを調整します（50–90%、デフォルト 80%）。
+3. **Code skeleton compression** を **On** にします。トグルは変更時に保存されます。
+
+他のセレクター設定と同様、値はセッションが最初に観測した時点で凍結されます——ゲートは新しく観測されたセッションにのみ影響し、実行中のタスクには適用されません。
+
+## 5. 更新と削除
+
+```sh
+# 更新：pull、再ビルド、再 pack、新しい tarball を再追加
+git pull && pnpm install --frozen-lockfile && pnpm build
+cd packages/selector && pnpm pack && cd ../..
+dsh plugin --profile web add packages/selector/dsh-context-compression-improved-0.1.0.tgz
+
+# 削除
+dsh plugin --profile web remove dsh-context-compression-improved
+```
+
+## トラブルシューティング
+
+- **ダンプに Bundle が有効と表示されない**：プロファイルを再起動し、selector エントリーパッケージ（runtime ではなく）を追加したこと、Harness のバージョンが互換 peer 範囲内であることを確認してください。
+- **ツール結果が一切スケルトン圧縮されない**：ゲートはデフォルトでオフです。トグルを確認してください。圧縮は、正確なトークナイザーのモデルルート上の、新規かつ超大規模なソースコード系ツール結果にのみ適用され、すべてのスキップは理由付きで監査記録に残ります。
+- **トグルが読み取り不能と表示される**：保存済みの `codeSkeleton` セクションが厳格なブラウザーデコードに失敗しています（正確に `{ enabled: boolean }` である必要があります）。不正なセクションを削除すればデフォルトに戻ります。
+- **更新手順が失敗する**：プラグインは npm パッケージのセマンティクスに従います。お使いの Harness ビルドが tarball 間のアップグレードを拒否する場合は、まず古いバージョンを削除してください。

package/docs/installation.ko.md

@@ -0,0 +1,76 @@
+# dsh-context-compression-improved 설치하기
+
+> [English](installation.md) · [中文](installation.zh.md) · [日本語](installation.ja.md) · [한국어](installation.ko.md)
+
+이 가이드는 포크를 소스에서 설치하는 방법을 다룹니다. 이 포크는 업스트림에 대해 이름이 변경되었으며(`dsh-context-compression-selector` → `dsh-context-compression-improved`), 아직 npm에 게시되지 않았습니다. 소스와 세션 로그에 나타나는 `dsh-context-compression-improved-runtime`은 동결된 프로버넌스 라벨이며 패키지 의존성이 아닙니다. 런타임 의존성은 `@huggingface/tokenizers`와 `js-yaml`뿐입니다.
+
+## 사전 요구 사항
+
+- Node `^22.19.0 || >=24` 및 pnpm `11.7.0`(`corepack enable`은 `packageManager`의 고정 버전을 사용합니다).
+- `0.1.1-rc.2` peer 범위와 호환되는 DeepSeek Harness(공식 `dsh-v0.1.2-alpha.5` 릴리스에서 검증).
+- DeepSeek V4 모델 경로(`deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-v4-flash-vision-exp`). 코드 스켈레톤 게이트를 포함한 손실 압축은 번들된 정확한 토크나이저가 필요하며, 그 외의 경로는 fail-open으로 원본 도구 결과를 유지합니다.
+- Git.
+
+## 1. 소스에서 빌드
+
+```sh
+git clone https://github.com/drscrewdriver/dsh-context-compression-improved.git
+cd dsh-context-compression-improved
+pnpm install --frozen-lockfile
+pnpm build
+```
+
+`pnpm build`는 모든 패키지의 두 라이브러리 산출물을 번들합니다(`tsdown`). 설치 전에 전체 테스트 스위트를 실행하려면 `pnpm test`를 먼저 실행하세요.
+
+## 2. Bundle 엔트리 패키지를 pack
+
+셀렉터 패키지가 유일한 Bundle 엔트리이며, 런타임은 정확한 버전 의존성으로 함께 따라옵니다:
+
+```sh
+cd packages/selector
+pnpm pack
+# → dsh-context-compression-improved-0.1.0.tgz
+cd ../..
+```
+
+`pnpm pack`은 `prepack` 훅을 통해 번들을 실행하므로, tarball은 항상 체크아웃 내용과 일치합니다.
+
+## 3. Harness 프로파일에 추가
+
+셀렉터 패키지는 Harness Bundle 매니페스트 필드 `dsh.bundle.patch`를 선언하므로, `dsh plugin add`가 표준적인 out-of-tree Bundle 설치 경로입니다:
+
+```sh
+dsh plugin --profile web add packages/selector/dsh-context-compression-improved-0.1.0.tgz
+dsh --profile web --dump-config
+```
+
+설치 후 해당 프로파일을 재시작하세요. 설정 덤프에 셀렉터 Bundle이 활성 상태로 표시되어야 합니다. 셀렉터와 런타임 패키지를 따로 설치하거나 연결하지 **마세요** — 런타임은 자동으로 설치됩니다.
+
+## 4. 코드 스켈레톤 게이트 켜기
+
+DeepSeek Harness 설정 → **Context compression selector**를 엽니다:
+
+1. 압축 프로파일을 선택합니다(게이트는 모든 프로파일에 대해 직교합니다).
+2. 필요하면 Auto Compact 트리거 레벨을 조정합니다(50–90%, 기본값 80%).
+3. **Code skeleton compression**을 **On**으로 설정합니다. 토글은 변경 시 저장됩니다.
+
+다른 셀렉터 설정과 마찬가지로 값은 세션이 처음 관찰하는 시점에 고정됩니다 — 게이트는 새로 관찰된 세션에만 적용되며, 실행 중인 작업에는 적용되지 않습니다.
+
+## 5. 업데이트 및 제거
+
+```sh
+# 업데이트: pull, 재빌드, 재 pack, 새 tarball을 다시 추가
+git pull && pnpm install --frozen-lockfile && pnpm build
+cd packages/selector && pnpm pack && cd ../..
+dsh plugin --profile web add packages/selector/dsh-context-compression-improved-0.1.0.tgz
+
+# 제거
+dsh plugin --profile web remove dsh-context-compression-improved
+```
+
+## 문제 해결
+
+- **덤프에 Bundle이 활성으로 표시되지 않음**: 프로파일을 재시작하고, 셀렉터 엔트리 패키지(런타임이 아닌)를 추가했는지, Harness 버전이 호환 peer 범위 내인지 확인하세요.
+- **도구 결과가 한 번도 스켈레톤 압축되지 않음**: 게이트는 기본값이 off입니다. 토글을 확인하세요. 압축은 정확한 토크나이저 모델 경로에서 새로 들어온 초대형 소스코드 도구 결과에만 적용되며, 모든 건너뜀은 사유와 함께 감사 기록에 남습니다.
+- **토글이 읽을 수 없음으로 표시됨**: 저장된 `codeSkeleton` 섹션이 엄격한 브라우저 디코드에 실패했습니다(정확히 `{ enabled: boolean }`이어야 함). 잘못된 섹션을 제거하면 기본값으로 돌아갑니다.
+- **업데이트 단계 실패**: 플러그인은 npm 패키지 의미론을 따릅니다. 사용 중인 Harness 빌드가 tarball 간 업그레이드를 거부하면 먼저 이전 버전을 제거하세요.

package/docs/installation.md

@@ -0,0 +1,76 @@
+# Installing dsh-context-compression-improved
+
+> [English](installation.md) · [中文](installation.zh.md) · [日本語](installation.ja.md) · [한국어](installation.ko.md)
+
+This guide installs the fork from source. The fork is renamed relative to upstream (`dsh-context-compression-selector` → `dsh-context-compression-improved`) and is not yet published to npm. The literal `dsh-context-compression-improved-runtime` that appears in the source and in durable session logs is a frozen provenance label, not a package dependency — the runtime dependencies are `@huggingface/tokenizers` and `js-yaml`.
+
+## Prerequisites
+
+- Node `^22.19.0 || >=24` and pnpm `11.7.0` (`corepack enable` picks the pinned version from `packageManager`).
+- A DeepSeek Harness installation compatible with the `0.1.1-rc.2` peer range (verified against the official `dsh-v0.1.2-alpha.5` release).
+- A DeepSeek V4 model route (`deepseek-v4-flash`, `deepseek-v4-pro`, or `deepseek-v4-flash-vision-exp`). Lossy compression — including the code-skeleton gate — requires the exact bundled tokenizer; other routes fail open and keep original tool results.
+- Git.
+
+## 1. Build from source
+
+```sh
+git clone https://github.com/drscrewdriver/dsh-context-compression-improved.git
+cd dsh-context-compression-improved
+pnpm install --frozen-lockfile
+pnpm build
+```
+
+`pnpm build` bundles both library faces of every package (`tsdown`). Run `pnpm test` first if you want the full suite on your machine before installing.
+
+## 2. Pack the Bundle entry package
+
+The selector package is the single Bundle entry; the runtime comes along as its exact-version dependency:
+
+```sh
+cd packages/selector
+pnpm pack
+# → dsh-context-compression-improved-0.1.0.tgz
+cd ../..
+```
+
+`pnpm pack` runs the bundle through the `prepack` hook, so the tarball always matches your checkout.
+
+## 3. Add it to a Harness profile
+
+The selector package declares the Harness Bundle manifest field `dsh.bundle.patch`, so `dsh plugin add` is the standard out-of-tree Bundle installation path:
+
+```sh
+dsh plugin --profile web add packages/selector/dsh-context-compression-improved-0.1.0.tgz
+dsh --profile web --dump-config
+```
+
+Restart the selected profile after installation. The config dump should list the selector Bundle as active. Do **not** install or wire the selector and runtime packages separately — the runtime is installed automatically.
+
+## 4. Turn on the code-skeleton gate
+
+Open DeepSeek Harness settings → **Context compression selector**:
+
+1. Pick a compression profile (the gate is orthogonal to all of them).
+2. Optionally adjust the Auto Compact trigger level (50–90%, default 80%).
+3. Set **Code skeleton compression** to **On**. The toggle saves on change.
+
+Like all selector settings, the value is frozen when a session first observes it — the gate affects newly observed sessions, never a task that is already running.
+
+## 5. Update or remove
+
+```sh
+# update: pull, rebuild, repack, and add the new tarball again
+git pull && pnpm install --frozen-lockfile && pnpm build
+cd packages/selector && pnpm pack && cd ../..
+dsh plugin --profile web add packages/selector/dsh-context-compression-improved-0.1.0.tgz
+
+# remove
+dsh plugin --profile web remove dsh-context-compression-improved
+```
+
+## Troubleshooting
+
+- **Bundle not active in the dump**: restart the profile; confirm you added the selector entry package (not the runtime) and that the Harness version is in the compatible peer range.
+- **Tool results are never skeleton-compressed**: the gate is off by default; check the toggle. Compression only applies to fresh, oversized source-code tool results on exact-tokenizer model routes, and every skip is recorded with a reason in the audit trail.
+- **The toggle shows as unreadable**: the stored `codeSkeleton` section failed the strict browser decode (it must be exactly `{ enabled: boolean }`). Removing the malformed section restores defaults.
+- **Updating fails on the upgrade step**: the plugin follows npm package semantics; remove the old version first if a tarball-to-tarball upgrade is refused by your Harness build.

package/docs/installation.zh.md

@@ -0,0 +1,76 @@
+# 安装 dsh-context-compression-improved
+
+> [English](installation.md) · [中文](installation.zh.md) · [日本語](installation.ja.md) · [한국어](installation.ko.md)
+
+本教程从源码安装本 fork。本 fork 相对上游已重命名（`dsh-context-compression-selector` → `dsh-context-compression-improved`），且尚未发布 npm 包。源码与会话日志中出现的 `dsh-context-compression-improved-runtime` 是冻结的溯源标识，并非包依赖——运行时依赖只有 `@huggingface/tokenizers` 和 `js-yaml`。
+
+## 前置条件
+
+- Node `^22.19.0 || >=24` 与 pnpm `11.7.0`（`corepack enable` 会按 `packageManager` 字段使用固定版本）。
+- 兼容 `0.1.1-rc.2` peer 范围的 DeepSeek Harness（已针对官方 `dsh-v0.1.2-alpha.5` 验证）。
+- DeepSeek V4 模型路由（`deepseek-v4-flash`、`deepseek-v4-pro` 或 `deepseek-v4-flash-vision-exp`）。有损压缩——包括代码骨架门——依赖内置的精确 tokenizer；其他路由 fail-open 并保留原始工具结果。
+- Git。
+
+## 1. 从源码构建
+
+```sh
+git clone https://github.com/drscrewdriver/dsh-context-compression-improved.git
+cd dsh-context-compression-improved
+pnpm install --frozen-lockfile
+pnpm build
+```
+
+`pnpm build` 会打包所有包的两套产物（`tsdown`）。如需在安装前先跑全量测试，可执行 `pnpm test`。
+
+## 2. 打包 Bundle 入口包
+
+selector 包是唯一的 Bundle 入口；runtime 作为其精确版本依赖自动随行：
+
+```sh
+cd packages/selector
+pnpm pack
+# → dsh-context-compression-improved-0.1.0.tgz
+cd ../..
+```
+
+`pnpm pack` 会通过 `prepack` 钩子执行打包，因此 tarball 始终与你的检出内容一致。
+
+## 3. 安装到 Harness Profile
+
+selector 包声明了 Harness Bundle manifest 字段 `dsh.bundle.patch`，因此 `dsh plugin add` 是标准的树外 Bundle 安装方式：
+
+```sh
+dsh plugin --profile web add packages/selector/dsh-context-compression-improved-0.1.0.tgz
+dsh --profile web --dump-config
+```
+
+安装后重启对应 Profile。配置导出中应显示 selector Bundle 已激活。**不要**分别安装或手动连接 selector 与 runtime 两个包——runtime 会自动安装。
+
+## 4. 打开代码骨架门
+
+打开 DeepSeek Harness 设置 → **上下文压缩选择器**：
+
+1. 选择一个压缩 Profile（这道门与所有 Profile 正交）。
+2. 按需调整 Auto Compact 触发水位（50–90%，默认 80%）。
+3. 将**代码骨架压缩**设为**开**。开关即改即存。
+
+与所有选择器设置一致，取值在会话首次观察时冻结——这道门只影响新观察的会话，不会改变正在运行的任务。
+
+## 5. 更新或卸载
+
+```sh
+# 更新：拉取、重建、重新打包、再次添加新 tarball
+git pull && pnpm install --frozen-lockfile && pnpm build
+cd packages/selector && pnpm pack && cd ../..
+dsh plugin --profile web add packages/selector/dsh-context-compression-improved-0.1.0.tgz
+
+# 卸载
+dsh plugin --profile web remove dsh-context-compression-improved
+```
+
+## 故障排除
+
+- **配置导出中 Bundle 未激活**：重启 Profile；确认添加的是 selector 入口包（而非 runtime），且 Harness 版本在兼容的 peer 范围内。
+- **工具结果从未被骨架化压缩**：该门默认关闭，请检查开关。压缩只作用于精确 tokenizer 路由上新鲜、超大、源码类的工具结果，且每次跳过都会在审计记录中留有原因。
+- **开关显示为不可读**：已存的 `codeSkeleton` 段未通过严格的浏览器解码（必须恰好是 `{ enabled: boolean }`）。删除畸形段即可恢复默认。
+- **升级步骤失败**：插件遵循 npm 包语义；如果你的 Harness 构建拒绝 tarball 到 tarball 的升级，请先移除旧版本再安装。