dsh-context-compression-improved 0.1.1 → 0.2.0

package/.gitattributes

@@ -0,0 +1 @@
+packages/selector/assets/** -text

package/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+        with:
+          version: 11.7.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22.19.0
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm typecheck
+      - run: pnpm build
+      # scripts/ is compiled to the gitignored scripts-dist/, and nothing above this
+      # point builds it. Without this step verify:release and test:e2e:packed both
+      # die with MODULE_NOT_FOUND on a clean checkout — which is what kept this
+      # workflow red on every push to main while the same gates passed locally,
+      # where scripts-dist/ had been built by hand once.
+      - run: pnpm build:scripts
+      - run: pnpm test
+      - run: pnpm --filter dsh-context-compression-improved test
+      - run: pnpm test:built
+      - run: pnpm verify:release
+      - run: pnpm pack:dry-run
+      - run: pnpm test:e2e:packed
+      - run: pnpm audit --audit-level high

package/CHANGELOG.ja.md

@@ -0,0 +1,39 @@
+# 変更履歴（フォークの追加エントリー）
+
+> 完全な履歴（アップストリーム 0.1.0 以前を含む）は [CHANGELOG.md](CHANGELOG.md) を参照。このファイルはフォークの追加エントリーのみを翻訳したものです。 · [English](CHANGELOG.md) · [中文](CHANGELOG.zh.md) · [한국어](CHANGELOG.ko.md)
+
+## 0.1.1
+
+### 追加
+
+- `scripts/` の TypeScript ツールチェーン：`verify-release`、`packed-components-smoke`、`packed-install-e2e` が `.ts` ソースになり、`tsc` で `scripts-dist/` にコンパイルされます。リポジトリ内の最後の3つの非 TS ヽースファイルが排除されました。
+
+### 変更
+
+- `package.json` スクリプト `test:e2e:packed` と `verify:release` が `scripts-dist/` のコンパイル成果物を実行するようになりました。
+- エスティメーターカタログルート登録が硬化：`asWebServer` がサービス自体を返すように修正（D7 修正）、エステーター UI が非アクティブ時にセクション見出しを保持するように修正（U1 修正）。
+- フレームワークドキュメント修正：行レベル `inject: [webServer]` は負荷担うものではない（Y22）；DSH 全パッケージに `isolate()` なし。
+
+### 修正
+
+- エスティメーターカタログルートは `asWebServer` が `register` をサービスから切り離したため、最初から一度も登録されなかった（D7）。
+- 非 TokenPilot プロファイル時にエステーターセクションが警告なしに非表示になっていた（U1）。
+
+## Unreleased（未リリース）
+
+### 追加
+
+- 直交するコードスケルトン圧縮ゲート（`codeSkeleton.enabled`、デフォルトはオフ）：超大規模なソースコード系ツール結果の初回露出時に、インポートと宣言のスケルトンを保持できます（関数本体は省略、エラー行は保持）。失敗時は元の先頭トリミングへフォールバックします。ゲートはすべてのプロファイルから独立し、正確なトークナイザー計測を前提とします。
+- セレクター設定セクションにゲートのトグルを追加（簡体字中国語・英語のコピー付き）。
+- 新セクションのブラウザー/ランタイム デコード整合テスト、`saveCodeSkeleton` の confirm-on-write コントラクトテスト、およびドキュメント全体のパリティ行列拡張。
+
+### 変更
+
+- ESLint フラット設定ベースライン（`pnpm lint`、CI でも強制）と `pnpm test:watch` による TDD ループを追加。デッドインポートを整理し、lint ベースラインで浮かび上がった 2 つのエラー経路を強化しました。
+- 本リポジトリは `WilliamShi666/dsh-context-compression-selector` の改良フォークとして管理されます。ドキュメントは英語・簡体字中国語・日本語・韓国語で提供されます。
+
+### 修正
+
+- エスティメーターカードは Harness ホストチャネルで API キーを要求しなくなりました。ホストチャネルを選ぶと、ライブのプロバイダー/モデル ドロップダウンが表示され、実際に使われるルート（明示的な上書き、なければセッション既定モデル）を明示します。キー入力欄と 2 つ目の手入力モデル欄は表示されません — エンドポイント URL、モデルのテキスト欄、書き込み専用キーはダイレクト接続チャネルだけに属します。
+- `presetOptions` の書き込みが兄弟フィールドを保持するようになりました。`settingsScope.set('presetOptions', patch)` はセクション全体を置き換えるため、エスティメーターの 2 つ目のフィールド（プロバイダー、モデル、エンドポイント）に触れると `estimatorMode` と他のすべての上書きが削除され、パネルは保存成功と表示したままエスティメーターが静かにオフへ戻っていました。現在はパッチを保存済みセクションへマージし、`undefined` は指定したフィールドだけを消去し、変更なしのパッチは書き込まず、confirm-on-write はチャネル単独ではなく同じフィールド群を検証します。
+- 回帰カバレッジを追加：`packages/selector/tests/preset-options-write.client.spec.ts`（マージ書き込み、兄弟フィールドの保持、明示的な消去、変更なし時の無書き込み、未コミット書き込みの報告）と `packages/selector/tests/estimator-channel.client.spec.tsx`（チャネル別フィールド、カタログのドロップダウン、手入力フォールバック）。

package/CHANGELOG.ko.md

@@ -0,0 +1,39 @@
+# 변경 로그(포크 추가 항목)
+
+> 전체 히스토리(업스트림 0.1.0 이전 포함)는 [CHANGELOG.md](CHANGELOG.md)를 참고하세요. 이 파일은 포크의 추가 항목만 번역한 것입니다. · [English](CHANGELOG.md) · [中文](CHANGELOG.zh.md) · [日本語](CHANGELOG.ja.md)
+
+## 0.1.1
+
+### 추가
+
+- `scripts/`의 TypeScript 도구 체인: `verify-release`, `packed-components-smoke`, `packed-install-e2e`가 `.ts` 소스가 되어 `tsc`로 `scripts-dist/`에 컴파일됩니다. 저장소의 마지막 3개 비-TS 소스 파일이 제거되었습니다.
+
+### 변경
+
+- `package.json` 스크립트 `test:e2e:packed`와 `verify:release`가 `scripts-dist/`의 컴파일 결과물을 실행합니다.
+- 추정기 카탈로그 라우트 등록이 강화됨: `asWebServer`가 서비스 자체를 반환하도록 수정(D7 수정), 추정기 UI가 비활성 시 섹션 제목을 유지하도록 수정(U1 수정).
+- 프레임워크 문서 정정: 행 수준 `inject: [webServer]`는 부담을 지지 않음(Y22); DSH 모든 패키지에 `isolate()` 없음.
+
+### 수정
+
+- 추정기 카탈로그 라우트는 `asWebServer`가 `register`를 서비스에서 분리한导致로 처음부터 한 번도 등록되지 않았음(D7).
+- 비-TokenPilot 프로필에서 추정기 섹션이 경고 없이 사라졌음(U1).
+
+## Unreleased(미출시)
+
+### 추가
+
+- 직교하는 코드 스켈레톤 압축 게이트(`codeSkeleton.enabled`, 기본값 off): 매우 큰 소스코드 도구 결과가 처음 노출될 때 임포트와 선언부의 스켈레톤을 보존할 수 있습니다(함수 본문 생략, 에러 라인 유지). 실패 시 기존의 head 트리밍으로 폴백합니다. 게이트는 모든 프로파일과 독립적이며 정확한 토크나이저 측정이 전제입니다.
+- 셀렉터 설정 섹션에 게이트의 토글 추가(간체 중국어·영문 카피 포함).
+- 새 섹션의 브라우저/런타임 디코드 정합성 테스트, `saveCodeSkeleton`의 confirm-on-write 컨트랙트 테스트, 전체 문서 패리티 매트릭스 확장.
+
+### 변경
+
+- ESLint 플랫 설정 베이스라인(`pnpm lint`, CI에서도 강제)과 `pnpm test:watch` TDD 루프를 추가. 죽은 임포트를 정리하고, lint 베이스라인에서 드러난 두 오류 경로를 보강했습니다.
+- 이 저장소는 이제 `WilliamShi666/dsh-context-compression-selector`의 개선 포크로 관리됩니다. 문서는 영어·중국어(간체)·일본어·한국어로 제공됩니다.
+
+### 수정
+
+- 추정기 카드가 Harness 호스트 채널에서 더 이상 API 키를 요구하지 않습니다. 호스트 채널을 선택하면 라이브 프로바이더/모델 드롭다운이 표시되고 실제로 사용될 라우트(명시적 재정의, 없으면 세션 기본 모델)를 알려줍니다. 키 입력란과 두 번째 수동 모델 입력란은 렌더링되지 않습니다 — 엔드포인트 URL, 모델 텍스트 필드, 쓰기 전용 키는 직접 연결 채널에만 속합니다.
+- `presetOptions` 쓰기가 형제 필드를 보존합니다. `settingsScope.set('presetOptions', patch)`는 섹션 전체를 교체하므로 추정기의 두 번째 필드(프로바이더, 모델, 엔드포인트)를 건드리면 `estimatorMode`와 다른 모든 재정의가 삭제되어, 패널은 저장 성공을 보고하는데도 추정기가 조용히 꺼졌습니다. 이제 패치는 저장된 섹션 위에 병합되고, `undefined`는 지목한 필드만 지우며, 변경 없는 패치는 쓰지 않고, confirm-on-write는 채널 하나가 아니라 같은 필드 집합을 검증합니다.
+- 회귀 커버리지 추가: `packages/selector/tests/preset-options-write.client.spec.ts`(병합 쓰기, 형제 필드 보존, 명시적 삭제, 변경 없음 시 무쓰기, 미커밋 쓰기 보고)와 `packages/selector/tests/estimator-channel.client.spec.tsx`(채널별 필드, 카탈로그 드롭다운, 수동 폴백).

package/CHANGELOG.md

@@ -0,0 +1,135 @@
+# Changelog
+
+All notable changes use this file. The project follows semantic versioning after `0.1.0`.
+
+## 0.1.1
+
+### Added
+
+- TypeScript toolchain for `scripts/`: `verify-release`, `packed-components-smoke`, and `packed-install-e2e` are now `.ts` sources compiled to `scripts-dist/` via `tsc`, eliminating the last three non-TS source files in the repository.
+
+### Changed
+
+- `package.json` scripts `test:e2e:packed` and `verify:release` now run compiled outputs from `scripts-dist/`.
+- Estimator catalog route registration hardened: `asWebServer` returns the service itself (D7 fix), and the estimator UI preserves its section heading when inactive instead of hiding behind an invisible gate (U1 fix).
+- Framework documentation corrected: row-level `inject: [webServer]` is not load-bearing (Y22); `isolate()` does not exist in any DSH package.
+
+### Fixed
+
+- The estimator catalog route was never registered since day one because `asWebServer` detached `register` from its service (D7).
+- The estimator section silently disappeared when a non-TokenPilot profile was active, with no hint about why or how to enable it (U1).
+
+## Unreleased
+
+### Added
+
+- New `tokenpilot-inspired` profile: a TokenPilot-paper-inspired capability matrix layered on the Balanced thresholds, selected explicitly from the settings UI; every pre-existing profile keeps a byte-identical resolved policy (enforced by a captured-baseline golden test).
+- Byte-identical repeated tool-result dedup: an oversized repeat is replaced with a pointer to the first occurrence's append-only original event (`dedupe-pointer`), with a per-session SHA-256 index (2,048-entry insertion-order eviction, hash+seq metadata only).
+- No-net-savings guard: replacements whose text is not smaller than the original are rejected even when the exact tokenizer reports a token saving.
+- Recovery exemption: recovery-tool output is permanently exempt from every reduction pass via a unified per-session exemption set, preventing compress-restore oscillation.
+- Auto Compact summary locator: after `compaction/end`, the landed summary checkpoint gains an Exact Sources block (shadowed seq range, spill files, touched files) so summarized-away details stay recoverable; skipped when it would locate nothing concrete.
+- Read-state semantics: a historical read whose file was later mutated is `superseded` and takes the small whole-result placeholder; optional error/warn/info clustering of omitted lines is appended to historical placeholders.
+- Optional residual-utility estimator (three channels: off / Harness host model / direct OpenAI-compatible endpoint) with per-session exponential backoff, strict timeout, advisory-only verdicts consumed by the next pressure pass, and numeric-only `estimator-outcome` audits. The estimator card appears only while the new profile is selected; the API key is write-only in settings and never enters the frozen policy, audits, or logs.
+- New audit records: `summary-locator` and `estimator-outcome`; the rewrite record covers dedup via the `dedupe-pointer` reducer. Audit field allowlists are unchanged.
+- Simplified Chinese and English copy for the new profile and estimator card; unit and golden coverage under `packages/runtime/tests/tokenpilot/`.
+
+- Orthogonal code-skeleton compression gate (`codeSkeleton.enabled`, default off): the first exposure of an oversized fresh source-code tool result can keep an imports-and-declarations skeleton with bodies elided and error lines preserved, falling back to the original head pruning. The gate is independent of every profile and gated on exact tokenizer measurement.
+- Settings-UI toggle for the gate in the selector settings section, with Simplified Chinese and English copy.
+- Browser/runtime decode parity for the new section, confirm-on-write contract tests for `saveCodeSkeleton`, and a full-document parity matrix extension.
+
+### Changed
+
+- Added an ESLint flat-config baseline (`pnpm lint`, enforced in CI) and a `pnpm test:watch` TDD loop; removed dead imports and hardened two error paths surfaced by the lint baseline.
+- This repository is now maintained as an improved fork of `WilliamShi666/dsh-context-compression-selector`; documentation ships in English, Simplified Chinese, Japanese, and Korean.
+
+### Fixed
+
+- The estimator card no longer demands an API key on the Harness host channel. Selecting the host channel shows the live provider/model dropdowns, names the route that would actually run (explicit override, else the session default), and renders neither a key field nor a second manual model input: the base URL, the model text field, and the write-only key belong to the direct endpoint channel alone.
+- `presetOptions` writes preserve their siblings. `settingsScope.set('presetOptions', patch)` replaces the whole section, so touching any second estimator field (a provider, a model, an endpoint) deleted `estimatorMode` and every other override — silently switching the estimator back off while the panel still reported a successful save. The patch is now merged over the stored section, `undefined` clears exactly the field it names, an unchanged patch writes nothing, and the confirmation read compares the same fields instead of the channel alone.
+- New coverage: `packages/selector/tests/preset-options-write.client.spec.ts` (merged writes, sibling preservation, explicit clears, no-op patches, uncommitted-write reporting) and `packages/selector/tests/estimator-channel.client.spec.tsx` (per-channel fields, catalog dropdowns, manual fallback).
+
+## 0.1.0 - 2026-09-03
+
+### Added
+
+- Stable release of DeepSeek V4 Flash Vision tokenizer integration for `deepseek-v4-flash-vision-exp`, including exact text counting and bounded image-token estimates.
+- User-configurable model-driven Auto Compact threshold in the selector settings section.
+- Auto Compact threshold linkage for each standard profile's History / micro-compact watermarks and related compression parameters.
+
+### Changed
+
+- The threshold editor now uses one direct numeric input; the slider and fixed quick-value buttons were removed.
+- Runtime session-event access supports both the established Harness `events` accessor and the newer `snapshotEvents()` public API.
+
+## 0.1.0-beta.4 - 2026-09-02
+
+### Fixed
+
+- Support the official DeepSeek Harness `dsh-v0.1.2-alpha.5` public API while retaining compatibility with the existing `0.1.1-rc.2` peer range. The plugin now owns the two small immutable-value helpers that the newer Harness no longer exports, and uses the same public `context-compression` namespace literal accepted by both Settings implementations. No Harness core code is modified.
+
+## 0.1.0-beta.3 - 2026-09-01
+
+### Scope
+
+This is a staged release. Exact **text-class** token counting for `deepseek-v4-flash-vision-exp`, best-effort bounded **vision-class image** estimates, and the Auto Compact threshold/UI/audit work are delivered. Exact image measurement remains **BLOCKED upstream**: the current measurement seam exposes neither the adapter's projected request-image dimensions nor the absolute serialized position, so estimates cannot be promoted to `exact-tokenizer`.
+
+### Added
+
+- DeepSeek V4 Flash Vision support for `deepseek-v4-flash-vision-exp` via a separately bundled official tokenizer pinned at `deepseek-ai/DeepSeek-V4-Flash-Vision-Exp` revision `6821d6ad3681a4b137b066b76094fa82ebd0a380`. Text, reasoning, tool-call arguments, and pure-text tool results are counted exactly; image-bearing tool-result candidates stay fail-open.
+- Vision image-token arithmetic ported line-by-line from the official `inference/image_processor.py` (patch size 14, downsample 3, 384-token cap, min pixels 147456, 8:1 aspect clamp, and position-dependent alignment padding), validated against golden fixtures generated by executing the official Python implementation. Valid intrinsic dimensions now produce `tokenizer-estimate` at the midpoint of all four alignment residues with a 384-token per-image upper bound; malformed or unevaluable dimensions use a documented 256-token fallback. Mixed text/image surfaces aggregate exact text and estimated images without promoting them to exact.
+- `autoCompact.thresholdPercent` setting (default 80, integer 50–90, step 1) with one shared validation contract across the settings UI, the persisted schema, and the runtime resolver. The editor lives inside the context-compression selector settings section.
+- Standard-profile History linkage to the Auto Compact watermark: `A = floor(C × a)` rescales the History trigger, minimum reclaim, and recent-token tail; `D = floor(A × 0.875)` replaces the fixed 0.7 capacity-pressure ratio as the micro-compact last-chance gate; one batch must justify its cache break by pulling the complete request back below the deadline. Defaults at 80% reproduce the previous numbers exactly.
+- The preset overlay writes the saved threshold into the generated `compaction-basic` composition as `thresholdRatio` (with `retainRatio` pinned at 0.16) and, from the same read, into the plugin runtime's deployment config as `autoCompactThresholdPercent`, so one standing generation never runs Auto Compact and micro compact on two different thresholds. Any generation-identity change — threshold, source, or module paths, including equal-length ones — produces a new standing composition generation. Deterministic identity-derived stamps use an 8-hex whole-second window; equal-prefix identities can collide in that first window on a coarse filesystem, so the overlay observes the staging file's real `mtimeMs+size` key and escalates to later hash windows before the atomic rename. Content, permissions, and the final unique stamp are complete before publication; already-running sessions keep their frozen policy.
+- `policy-resolved` audits now record the Auto Compact coordination facts (threshold percent, `A`, `D`, parameter source — including `deployment-override`/`mixed` when deployment config replaces linked History watermarks), the routed provider/model, and the bundled tokenizer identity.
+- Persisted settings reject present-but-invalid sections (`profile: null`, `custom: null`, own-property `undefined`) before any schema default can absorb them; a malformed stored document freezes the session losslessly (`profile: off`, audited as `settingsInvalidFallback: lossless-off`) instead of silently enabling the lossy Balanced default. The browser decoder applies the same rule and canonicalizes legacy Custom v1/v2 documents to the same v3 document the runtime resolver produces.
+- The History planner returns a discriminated outcome, and `component-evaluation` audits distinguish the full skip taxonomy: `below-profile-trigger`, `below-micro-deadline`, `exact-tokenizer-unavailable`, `no-safe-candidates` (only recovery-tool output or already-cleared results), `protected-working-set` (everything inside the protected tail), `insufficient-reclaim` and `cannot-reach-deadline-target` (with the reached/required token numbers), `adaptive-cost-rejected`, and `recovery-tool-unavailable`.
+
+### Known limitations
+
+- Images never claim exact counts. The official expansion depends on the absolute prompt position (system prompt, chat-template framing, adapter image handles) and on the adapter's final request-image projection (including per-route `imagePixelBudget`/`imageDetail` overrides and byte-cap reprojection), none of which is exposed through the current measurement seam. Intrinsic/default estimates may therefore differ materially from provider accounting. Upstream capability requests remain projected request-image dimensions and the absolute serialized position exposed to token-meter extensions.
+- History skips the whole batch whenever any tool-result candidate lacks an exact count, including image-bearing candidates, even though sibling text candidates are individually exact.
+- Custom remains manual token mode; its History parameters do not follow the Auto Compact watermark.
+- A vision token breakdown UI is not shipped; image estimates and the intrinsic alignment diagnostic are available on the measured token view, while lossy rewrite proofs still require exact counts.
+
+### Deferred
+
+- Audit `modality` field and the tokenizer artifact SHA-256 inside audit records (the audits already carry the routed provider/model and tokenizer identity).
+- Publishing the (now complete) runtime skip-reason taxonomy as a user-facing documentation table.
+- Custom-profile display of the A/D watermarks and an above-D warning; Custom remains fully manual.
+- Vision token breakdown UI and promotion of image estimates to exact measurement.
+
+## 0.1.0-beta.2 - 2026-08-28
+
+### Fixed
+
+- Resolve the official DeepSeek V4 Flash tokenizer route so Fresh and Aggregate can evaluate tool results for the supported V4 models.
+- Run Cache Strict History at the real request boundary once its configured capacity-pressure condition is met; trigger the capacity condition at 70% routed-context utilization.
+- Disable Harness-native head/middle/tail tool-result pruning whenever a selector profile is active, leaving the selector as the sole tool-result compactor.
+
+### Changed
+
+- Protect the newest 10 agent tool calls and a 64,000-token tool-result tail window before History/microcompact rewrites older results.
+
+## 0.1.0-beta.1 - 2026-08-27
+
+### Added
+
+- One-install DeepSeek Harness Product Bundle backed by a separate exact-version runtime package.
+- Web profile selector with preset-stable settings and an explicit built-in Minimal exception.
+- Fresh, Aggregate, routine/capacity-aware History, Native tool-result pruning, and default-off Custom TailTrim.
+- Standard-event TailTrim protocol using `compaction/prune` plus recoverable `user/message` replacement.
+- Plugin-owned `context_compression_retrieve` recovery tool.
+- Structured, content-free policy, evaluation, rewrite, failure, and Native auto-compact audit records.
+- Pinned official DeepSeek V4 tokenizer assets with runtime SHA-256 validation and upstream license.
+- Public-API component E2E, preset/Minimal, and parent/fork/spawn cache-prefix regression tests.
+
+### Compatibility
+
+- Verified against DeepSeek Harness `dsh-v0.1.1-rc.2` public packages.
+- Exact tokenizer mapping is currently limited to `deepseek-v4-flash` and `deepseek-v4-pro`.
+
+### Known limitations
+
+- Adaptive ordinary History fails closed when public request-level route/cache evidence is incomplete; capacity pressure remains a separate safety override.
+- Cache-prefix tests prove native fork inheritance and identical serialized prefixes, not a provider-specific cache allocation or a guaranteed DeepSeek cache hit.
+- Settings snapshots and first-exposure decisions are process-local to the mounted runtime.

package/CHANGELOG.zh.md

@@ -0,0 +1,39 @@
+# 更新日志（fork 新增条目）
+
+> 完整历史（含上游 0.1.0 及更早版本）见 [CHANGELOG.md](CHANGELOG.md)。本文件只翻译本 fork 的新增条目。 · [English](CHANGELOG.md) · [日本語](CHANGELOG.ja.md) · [한국어](CHANGELOG.ko.md)
+
+## 0.1.1
+
+### 新增
+
+- `scripts/` 的 TypeScript 工具链：`verify-release`、`packed-components-smoke` 和 `packed-install-e2e` 现为 `.ts` 源文件，通过 `tsc` 编译至 `scripts-dist/`，消除仓库中最后三个非 TS 源文件。
+
+### 变更
+
+- `package.json` 脚本 `test:e2e:packed` 和 `verify:release` 现运行 `scripts-dist/` 中的编译产物。
+- 估计器目录路由注册加固：`asWebServer` 直接返回 service 本身（D7 修复），估计器 UI 在未激活时保留区块标题而非隐藏（U1 修复）。
+- 框架文档更正：行级 `inject: [webServer]` 非承载性（Y22）；DSH 中无 `isolate()` 实例。
+
+### 修复
+
+- 估计器目录路由自始至终从未注册，因 `asWebServer` 使 `register` 脱离 service（D7）。
+- 非 TokenPilot Profile 下估计器区块静默消失，无任何启用提示（U1）。
+
+## Unreleased（未发布）
+
+### 新增
+
+- 正交的代码骨架压缩门（`codeSkeleton.enabled`，默认关闭）：超大源码类工具结果首次曝光时，可保留导入与声明的骨架——省略函数体并保留错误行——失败时回退到原头部裁剪。这道门独立于所有 Profile，且以精确 tokenizer 测量为前提。
+- 选择器设置区内新增该门的开关，附简体中文与英文文案。
+- 新增段的浏览器/运行时解码对齐测试、`saveCodeSkeleton` 的 confirm-on-write 契约测试，以及全文档 parity 矩阵扩展。
+
+### 变更
+
+- 新增 ESLint 平铺配置基线（`pnpm lint`，CI 同步强制）与 `pnpm test:watch` TDD 环路；清理死导入，并修复 lint 基线暴露的两处错误处理路径。
+- 本仓库现为 `WilliamShi666/dsh-context-compression-selector` 的改进版 fork；文档提供英、简中、日、韩四种语言。
+
+### 修复
+
+- 估计器卡片在 Harness 宿主通道上不再要求 API Key。选择宿主通道后只显示实时供应商/模型下拉框，并标出当前真正生效的路由（显式覆盖优先，否则跟随会话默认模型）；既不显示密钥输入框，也不再有第二个手填模型输入——端点地址、模型文本框与只写密钥均只属于直连端点通道。
+- `presetOptions` 写入改为保留同级字段。`settingsScope.set('presetOptions', patch)` 会替换整个分节，导致再改动估计器的任何一个字段（供应商、模型、端点）都会删掉 `estimatorMode` 及其余全部覆盖值——估计器被静默关回关闭状态，而面板却报告保存成功。现在补丁会合并到已存分节之上，`undefined` 只清除指名的那一个字段，空改动不写盘，且 confirm-on-write 校验同一组字段而非仅校验通道。
+- 新增回归覆盖：`packages/selector/tests/preset-options-write.client.spec.ts`（合并写入、保留同级字段、显式清除、空改动不写、未提交写入的报错）与 `packages/selector/tests/estimator-channel.client.spec.tsx`（各通道字段、目录下拉框、手填回退）。

package/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing
+
+Thank you for helping improve this community plugin.
+
+1. Open an issue before large behavior or compatibility changes.
+2. Keep every production change inside this repository; do not require a DeepSeek Harness core patch.
+3. Add a failing regression first for compression, surface/recovery, preset, tokenizer, or cache-prefix behavior.
+4. Run:
+
+   ```sh
+   pnpm install --frozen-lockfile
+   pnpm test
+   pnpm typecheck
+   pnpm build
+   pnpm verify:release
+   pnpm pack:dry-run
+   ```
+
+5. Never commit API keys, `.env` files, real Session logs, prompts/tool results, user paths, generated tarballs, or NPM tokens.
+6. Read [`docs/repair-log.md`](docs/repair-log.md) before starting a new branch or version. It is the cross-version ledger of install/boot defects; a class recorded there must be re-checked on every new line instead of being rediscovered. Note in particular that `lib/` is committed, so a built chunk an entry imports must be committed in the same change — `pnpm verify:release` enforces it.
+
+Pull requests should explain the evidence for “triggered”, “enabled but skipped”, and fail-open behavior separately. A code path existing is not runtime proof. Changes to tokenizer/model compatibility require an official source, pinned revision, license, byte length, SHA-256, and negative tests.

package/README.ja.md

@@ -0,0 +1,104 @@
+# dsh-context-compression-improved
+
+> [dsh-context-compression-selector](https://github.com/WilliamShi666/dsh-context-compression-selector) の改良フォーク——DeepSeek Harness 向けの監査可能なツール結果コンテキスト圧縮セレクターに、直交する**コードスケルトン圧縮ゲート**を追加しました。
+
+[English](README.md) · [中文说明](README.zh.md) · [한국어](README.ko.md) · [変更履歴](CHANGELOG.ja.md) · [インストールガイド](docs/installation.ja.md)
+
+> [!NOTE]
+> **このフォークがアップストリーム 0.1.0 に追加したもの:**
+>
+> - 直交する**コードスケルトン圧縮ゲート**（`codeSkeleton.enabled`、デフォルトはオフ）：超大規模なソースコード系ツール結果の初回露出時に、通常の reducer に渡る前でインポートと宣言のスケルトンを保持できます（関数本体は省略、エラー行は保持）。
+> - 同じセレクター設定セクション内に、すべての圧縮プロファイルから独立したこのゲートのトグルを追加。
+> - CI に組み込まれた ESLint ベースライン、`test:watch` による TDD ループ、英語/簡体字中国語/日本語/韓国語のドキュメント。
+
+> [!IMPORTANT]
+> 本プロジェクトは **DeepSeek モデルのみ**をサポートします。可逆的な計測と非可逆圧縮は、同梱の DeepSeek 公式トークナイザー（`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) を参照してください。
+
+## これは何か
+
+長時間稼働するエージェントタスクは大量のツール出力を蓄積します。本コミュニティプラグインは、DeepSeek Harness のコアを改変することなく、選択可能で監査可能なツール結果コンテキスト圧縮ポリシーを提供します：
+
+- **Fresh**：モデルが受け取る前に、新たにサイズ超過したツール結果セグメントを事前圧縮します。
+- **Aggregate**：Fresh 圧縮後も予算を超える場合、再度圧縮します。
+- **History / micro-compact**：直近の作業コンテキストを保護しつつ、対象となる古いツール結果を置き換えます。
+- **TailTrim**：Custom のみで有効化できる任意のテール縮小パスです。
+- **Native**：Harness 方式の先頭/中間/末尾トリミングを明示的なプロファイルとして保持します。
+- **コードスケルトン（新規、直交ゲート）**——下記参照。
+
+すべての判断は記録されます：ステージ、reducer、トリガー理由、スキップ理由、そして取得可能な場合は正確なトークン数。
+
+## コードスケルトンゲート（新規）
+
+ゲートを有効にすると、超大規模な**ソースコード系の新規ツール結果**（例：大きな `read_file`）に対して、まずスケルトン圧縮を試みます：インポートと型/関数/クラス宣言を保持し、関数本体をマーカー付きで省略し、省略された本体の中のエラー行を保持します。スケルトンを生成できない、または検証できない場合は、元の先頭トリミングへフォールバックします——このゲートがコンテキストを悪化させることはありません。
+
+特徴：
+
+- **直交**：選択されたプロファイル（`balanced`、`savings`、`cache-strict`、`adaptive`、`custom`、`off`、`native`）から独立しています。すべてのプロファイルでゲートを利用できます。
+- **デフォルトはオフ**：`codeSkeleton: { enabled: false }`。明示的に有効化するまで動作しません。
+- **計測が前提**：正確な DeepSeek トークナイザーが必要で、利用不可の場合は fail-open します。
+- **セッション凍結**：他のセレクター設定と同様、変更は新しく観測されたセッションにのみ適用されます。
+- **厳格なパース**：`codeSkeleton` は正確に `{ enabled: boolean }` である必要があります。不正な値はランタイム側でスローされ、ブラウザー UI 側では読み取り不能として表示されます。
+
+### 出典、そしてこの数値は誰のものか
+
+スケルトン化のアプローチは **[Headroom](https://github.com/headroomlabs-ai/headroom)**
+（Apache-2.0）から借用しています。AI エージェント向けのコンテキスト圧縮レイヤーで、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 自身の
+圧縮器が Headroom 自身のベンチマークで測定した値です。本ゲートの機構はここに同源があります。
+本リポジトリは**独自のベンチマークを一切持たない**ため、**独自の削減率を主張しません**。
+数値が必要な場合は出典で確認してください。
+
+## 設定 UI
+
+同じ設定セクションで、圧縮プロファイルの選択、Auto Compact トリガーレベルの調整、コードスケルトン圧縮のトグルが行えます。トグルは変更時に即保存され、再読み込み時には保存済みの状態が表示されます。
+
+![Context Compression Selector 設定 UI](packages/selector/assets/screenshots/context-compression-selector-settings.png)
+
+## インストール
+
+ソースからビルドしてインストールします（本フォークはまだ npm に公開していません。内部パッケージ名は意図的にアップストリームのままです）：
+
+```sh
+git clone https://github.com/drscrewdriver/dsh-context-compression-improved.git
+cd dsh-context-compression-improved
+pnpm install --frozen-lockfile
+pnpm build
+```
+
+その後、セレクターパッケージを pack して Harness プロファイルに追加します——検証とアンインストールを含む完全な手順は[インストールガイド](docs/installation.ja.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)。
+
+## 互換性
+
+- 公開されているプラグインおよびプロファイル 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 とは提携・承認関係にありません。
+
+## クレジットとライセンス
+
+- アップストリームのプロジェクトと既存のすべての成果：[WilliamShi666/dsh-context-compression-selector](https://github.com/WilliamShi666/dsh-context-compression-selector)（作者 WilliamShi666、MIT）。
+- フォークによる追加（コードスケルトンゲート、ツールチェーン、多言語ドキュメント）：drscrewdriver。
+- コードスケルトン機構の出典：[Headroom](https://github.com/headroomlabs-ai/headroom)（Apache-2.0）——上記「出典、そしてこの数値は誰のものか」を参照。
+- MIT——[LICENSE](LICENSE)（アップストリームの著作権表示を保持）を参照。同梱トークナイザーの出所は [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

package/README.ko.md

@@ -0,0 +1,103 @@
+# dsh-context-compression-improved
+
+> [dsh-context-compression-selector](https://github.com/WilliamShi666/dsh-context-compression-selector)의 개선 포크——DeepSeek Harness용 감사 가능한 도구 결과 컨텍스트 압축 셀렉터에, 직교하는 **코드 스켈레톤 압축 게이트**를 추가했습니다.
+
+[English](README.md) · [中文说明](README.zh.md) · [日本語](README.ja.md) · [변경 로그](CHANGELOG.ko.md) · [설치 가이드](docs/installation.ko.md)
+
+> [!NOTE]
+> **이 포크가 업스트림 0.1.0에 추가한 것:**
+>
+> - 직교하는 **코드 스켈레톤 압축 게이트**(`codeSkeleton.enabled`, 기본값 off): 매우 큰 소스코드 도구 결과가 처음 노출될 때, 일반 리듀서로 넘어가기 전에 임포트와 선언부의 스켈레톤을 보존할 수 있습니다(함수 본문은 생략, 에러 라인은 유지).
+> - 동일한 셀렉터 설정 섹션에 모든 압축 프로파일과 독립적인 이 게이트의 토글을 추가.
+> - CI에 통합된 ESLint 베이스라인, `test:watch` TDD 루프, 영어/중국어(간체)/일본어/한국어 문서.
+
+> [!IMPORTANT]
+> 이 프로젝트는 **DeepSeek 모델만** 지원합니다. 손실 없는 측정과 손실 압축은 번들된 DeepSeek 공식 토크나이저(`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)를 참고하세요.
+
+## 이것은 무엇인가
+
+장시간 실행되는 에이전트 작업은 대량의 도구 출력을 축적합니다. 이 커뮤니티 플러그인은 DeepSeek Harness 코어를 수정하지 않고, 선택 가능하고 감사 가능한 도구 결과 컨텍스트 압축 정책을 제공합니다:
+
+- **Fresh**: 모델이 받기 전에 새로 커진 도구 결과 세그먼트를 사전 압축합니다.
+- **Aggregate**: Fresh 압축 후에도 예산을 초과하면 다시 압축합니다.
+- **History / micro-compact**: 최근 작업 컨텍스트를 보호하면서 대상이 되는 오래된 도구 결과를 교체합니다.
+- **TailTrim**: Custom에서만 활성화할 수 있는 선택적 테일 축소 경로입니다.
+- **Native**: Harness 방식의 head/중간/tail 트리밍을 하나의 명시적 프로파일로 유지합니다.
+- **코드 스켈레톤(신규, 직교 게이트)**——아래 참고.
+
+모든 결정은 기록됩니다: 단계, 리듀서, 트리거 이유, 건너뜀 이유, 그리고 가능한 경우 정확한 토큰 수.
+
+## 코드 스켈레톤 게이트(신규)
+
+게이트를 활성화하면 매우 큰 **소스코드 도구 결과**(예: 큰 `read_file`)에 대해 먼저 스켈레톤 축소를 시도합니다: 임포트와 타입/함수/클래스 선언을 유지하고, 함수 본문은 마커와 함께 생략하며, 생략된 본문 안의 에러 라인은 보존합니다. 스켈레톤을 생성하거나 검증할 수 없으면 원래의 head 트리밍으로 폴백합니다——이 게이트가 컨텍스트를 악화시킬 수는 없습니다.
+
+특성:
+
+- **직교**: 선택된 프로파일(`balanced`, `savings`, `cache-strict`, `adaptive`, `custom`, `off`, `native`)과 독립적입니다. 모든 프로파일이 이 게이트를 받습니다.
+- **기본값 off**: `codeSkeleton: { enabled: false }`이며, 직접 켜기 전까지는 동작하지 않습니다.
+- **측정이 선행**: 정확한 DeepSeek 토크나이저가 필요하며, 사용할 수 없으면 fail-open합니다.
+- **세션 고정**: 다른 셀렉터 설정과 마찬가지로 변경 사항은 새로 관찰된 세션에만 적용됩니다.
+- **엄격한 파싱**: `codeSkeleton`은 정확히 `{ enabled: boolean }`이어야 합니다. 잘못된 값은 런타임 쪽에서 예외를 던지고, 브라우저 UI에서는 읽을 수 없음으로 표시됩니다.
+
+### 출처, 그리고 이 수치는 누구의 것인가
+
+스켈레톤화 접근은 **[Headroom](https://github.com/headroomlabs-ai/headroom)**(Apache-2.0)에서
+차용했습니다. AI 에이전트용 컨텍스트 압축 계층으로, 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 자체
+압축기가 Headroom 자체 벤치마크에서 측정한 값입니다. 이 게이트의 메커니즘은 여기에 동원(同源)을
+둡니다. 이 저장소는 **자체 벤치마크가 전혀 없으므로 자체 감축률을 주장하지 않습니다.** 수치가
+필요하면 출처에서 확인하십시오.
+
+## 설정 UI
+
+동일한 설정 섹션에서 압축 프로파일 선택, Auto Compact 트리거 레벨 조정, 코드 스켈레톤 압축 토글을 모두 처리할 수 있습니다. 토글은 변경 시 즉시 저장되며, 다시 불러올 때 저장된 상태가 표시됩니다.
+
+![Context Compression Selector 설정 UI](packages/selector/assets/screenshots/context-compression-selector-settings.png)
+
+## 설치
+
+소스에서 빌드하여 설치합니다(이 포크는 아직 npm에 게시되지 않았습니다. 내부 패키지 이름은 의도적으로 업스트림과 동일하게 유지됩니다):
+
+```sh
+git clone https://github.com/drscrewdriver/dsh-context-compression-improved.git
+cd dsh-context-compression-improved
+pnpm install --frozen-lockfile
+pnpm build
+```
+
+이후 셀렉터 패키지를 pack 해서 Harness 프로파일에 추가합니다——검증과 제거를 포함한 전체 절차는 [설치 가이드](docs/installation.ko.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) 참고.
+
+## 호환성
+
+- 공개된 플러그인 및 프로파일 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과 제휴하거나 승인받지 않았습니다.
+
+## 크레딧과 라이선스
+
+- 업스트림 프로젝트와 기존의 모든 작업: [WilliamShi666/dsh-context-compression-selector](https://github.com/WilliamShi666/dsh-context-compression-selector), 작성자 WilliamShi666(MIT).
+- 포크에서 추가된 것(코드 스켈레톤 게이트, 툴체인, 다국어 문서): drscrewdriver.
+- 코드 스켈레톤 메커니즘 출처: [Headroom](https://github.com/headroomlabs-ai/headroom) (Apache-2.0) — 위의 "출처, 그리고 이 수치는 누구의 것인가"를 참조하십시오.
+- MIT——[LICENSE](LICENSE)(업스트림 저작권 표기 유지) 참고. 번들된 토크나이저의 출처는 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).