dsh-context-compression-improved 0.5.1 → 0.5.3

package/CHANGELOG.zh.md

@@ -1,77 +1,131 @@
-# 更新日志（fork 新增条目）
-
-> 完整历史（含上游 0.1.0 及更早版本）见 [CHANGELOG.md](CHANGELOG.md)。本文件只翻译本 fork 的新增条目。 · [English](CHANGELOG.md) · [日本語](CHANGELOG.ja.md) · [한국어](CHANGELOG.ko.md)
-
-## 0.5.1 - 2026-09-20
-
-### Fixed
-
-- 同一 identity 的并发 preset-overlay 组装在 Windows 上不再失败：发布改为按目标路径串行，
-  且当原子 rename 仍然竞争失败时，会先确认目标文件已带有本 staging 文件的
-  `{mtimeMs, size}` standing key 才判定发布成功。Windows 的 `MoveFileEx` 会把这种竞争
-  失败报成 `EPERM`/`EBUSY`，而 POSIX `rename` 只是覆盖目标——这曾导致并发启动会话时
-  `standingKeyFor()` 抛错。目标不匹配时仍会明确失败，静默复用世代依旧被禁止。
-- 一并修复了长期掩盖该问题及其它预存红灯的发布门禁与测试：packed smoke 中陈旧的标识符与
-  已退役的审计 reason、过期的客户端 inject 断言，以及仅 Windows 触发的 spawn 陷阱
-  （`git` 与多行 `node -e` 脚本经 `cmd.exe` 转发会被改写参数）。
-
-## 0.5.0 - 2026-09-20
-
-### Added
-
-- 建议型相关度 advisor（仅统计与建议，默认关闭）：每个 turn 边界以 fire-and-forget 方式
-  运行一次 pass——从最近的 `todo/write` 事件总结尾部任务语义（无 todolist 时回退到最近
-  用户文本）、对历史 tool-result 候选做"内容+注释语义 ↔ 当前任务"的增量相关度打分、并
-  计算前缀腐化度（prefix-decay，按 characterPressure 加权的相关度均值取反）。低相关的
-  旧段标记为 `recertified`，仅作为后续 history 激进化的建议输入——本轮没有任何决策路径
-  消费它，且 advisor 输出绝不抑制、延迟或改写任何本应落地的 reduction（有专项不变量测试
-  钉死）。经 `presetOptions.advisor*` settings 键配置（`advisorMode` `''|'host'|'direct'`，
-  默认 `''`；direct 通道复用 estimator 端点；`SideChannel` 新增可选 overrides 参数，
-  共享传输层而不共享配置）。可观测性：新增 `advisor-outcome` 审计记录（content-free，
-  每阶段一条：summary / scoring / decay）与只读 HTTP 路由
-  `GET .../advisor-report?sessionId=`（部署级 opt-in 开关 `advisorReportRoute`，与 review
-  路由同骨架）。本轮刻意不提供客户端 UI。
-
-## 0.4.0 - 2026-09-20
-
-### Fixed
-
-- 插件不再依赖路由 model id：全部规划闸门改按字符基准决策（Unicode code points，
-  经 `characterPressure` / `pressureCost`），不再以 exact tokenizer 计数为前提，
-  因此未内建 tokenizer 的路由（线上 `deepseek-flash`）重新能落地改写而不是静默跳过。
-  token 阈值键名与数值全部保留（按既有 4.0 字符/token 约定换算，冻结 profile 基线零改动）；
-  token 数值降级为遥测，由 rewrite 审计记录新增的 `measurementBasis` 字段如实区分
-  （`exact-tokenizer` 与 `characters`，派生时写 `tokenizerId: 'characters'` /
-  `tokenizerRevision: 'chars-per-token-4.0'`）。回滚：确认无后续改动依赖本提交后再执行
-  `git revert 7a1972a` 整体恢复旧闸门。
-
-### Changed
-
-- runtime 包并入 selector 包：一次安装即可获得完整栈，仓库根目录即为安装面
-  （`name`、`main`、`types`、`exports`（含 `./pruner`、`./invariant`）、`dependencies`、`dsh`），
-  工具链、脚本与 CI 一并收敛为单包。已真机验证的 estimator-catalog 路由注册（双前缀、受保护的
-  双通道激活、按请求解析服务、可检索的生命周期日志）重放到本线，并新增宿主侧守门；`ab2175a`
-  降级为 `z.any()` 的 settings schema 已还原，每日 Custom 默认值重新下发。
-- 在本分支适配官方 DeepSeek Harness `v0.1.5-rc.2`。全部 `@deepseek-ai/dsh-*` 开发依赖与 e2e 官方宿主清单从 `0.1.1-rc.2` 升至 `0.1.5-rc.2`（cordis `4.0.2`、schemastery `3.18.2`），含新的拆分包（`dsh-session-projection`、`dsh-session-persistence`、`dsh-atomic-write`、`dsh-home-paths`、`dsh-sandbox` 等）与 `dsh-client-store` 客户端栈。
-- Surface 替换操作改用 v3 的 `startSeq`/`endSeq` 形状与品牌化 `SessionSeq`；`compaction/prune` 清单保留持久化的 `start`/`end` 字段。surface node 事件改为按 seq 查找而非数组下标。
-- 客户端 bundle 不再引用已移除的 `@deepseek-ai/dsh-client-runtime`：settings 类型改自 `@deepseek-ai/dsh-client-ui-settings`，会话 hooks 合并自 `@deepseek-ai/dsh-client-ui-session`。两份 package manifest 与 `dsh.plugin.json` 声明 `engines.dsh >=0.1.5-alpha.1 <0.2.0-0`。
-- Harness 0.1.5 不再向浏览器暴露会话 `agentPreset`，客户端无法再识别 Minimal 会话；选择器保持可选，旧的不可用横幅不再出现。
-- 测试套件按 0.1.5 语义更新：cordis 插件启动需要 `.await()`，Token Meter 需要预先挂载 `SessionProjectionRegistry`，assistant 事件携带 `stream: []`，settings 命名空间为普通字符串。
-
-### 修复
-
-- 估计器卡片在 Harness 宿主通道上不再要求 API Key。选择宿主通道后只显示实时供应商/模型下拉框，并标出当前真正生效的路由（显式覆盖优先，否则跟随会话默认模型）；既不显示密钥输入框，也不再有第二个手填模型输入——端点地址、模型文本框与只写密钥均只属于直连端点通道。
-- `presetOptions` 改为按路径写入。此前整段写入会替换整个分节，导致再改动估计器的任何一个字段（供应商、模型、端点）都会删掉 `estimatorMode` 及其余全部覆盖值——估计器被静默关回关闭状态，而面板却报告保存成功。现在每个字段只写自己，`undefined` 只清除指名的那一个字段，且 confirm-on-write 校验的是同一组字段而非仅校验通道。
-- 新增回归覆盖：`packages/selector/tests/preset-options-write.client.spec.ts`（按路径写入、保留同级字段、显式清除、空改动不写、未提交写入的报错）与 `packages/selector/tests/estimator-channel.client.spec.tsx`（各通道字段、目录下拉框、手填回退）。
-
-
-### 新增
-
-- 正交的代码骨架压缩门（`codeSkeleton.enabled`，默认关闭）：超大源码类工具结果首次曝光时，可保留导入与声明的骨架——省略函数体并保留错误行——失败时回退到原头部裁剪。这道门独立于所有 Profile，且以精确 tokenizer 测量为前提。
-- 选择器设置区内新增该门的开关，附简体中文与英文文案。
-- 新增段的浏览器/运行时解码对齐测试、`saveCodeSkeleton` 的 confirm-on-write 契约测试，以及全文档 parity 矩阵扩展。
-
-### 变更
-
-- 新增 ESLint 平铺配置基线（`pnpm lint`，CI 同步强制）与 `pnpm test:watch` TDD 环路；清理死导入，并修复 lint 基线暴露的两处错误处理路径。
-- 本仓库现为 `WilliamShi666/dsh-context-compression-selector` 的改进版 fork；文档提供英、简中、日、韩四种语言。
+# 更新日志（fork 新增条目）
+
+> 完整历史（含上游 0.1.0 及更早版本）见 [CHANGELOG.md](CHANGELOG.md)。本文件只翻译本 fork 的新增条目。 · [English](CHANGELOG.md) · [日本語](CHANGELOG.ja.md) · [한국어](CHANGELOG.ko.md)
+
+## 0.5.3 - 2026-09-20
+
+### Fixed
+
+- Bundle patch 不再设置已退役的 review 路由开关。`reviewQueueRoute` 在 review gate 退役时已从插件的
+  Config schema 删除，却仍留在 `packages/selector/cordis.patch.yml` 中，等于宣告了一条永远注册不了的
+  路由。宿主对未知配置键宽容（插件加载与服务均正常，已在真机验证），故属**陈旧配置**而非故障；但任何
+  严格校验插件配置的宿主都会失败。
+- 生成产物钉死为 LF（`packages/selector/lib/** text eol=lf`）。此前在 `core.autocrlf=true` 下，每次
+  检出都会把已提交的 `lib/**` 改写成 CRLF，于是任何分支切换或合并都会让整个产物目录以"仅行尾差异"
+  显示为已修改。该状态从未被提交过，但它让每棵树看起来都是脏的，并且会掩盖真实的产物变更。
+
+### Added
+
+- Bundle patch 的**阴性对照**契约钉桩：patch 中一旦设置退役配置键即失败（按"键赋值行"判定，注释里
+  仍可点名该键），并要求在线的 `estimatorCatalogRoute` 开关保持接线。
+
+### Tests
+
+- 客户端座位契约补充了老宿主降级钉桩：未声明该 seat 的宿主会在槽边界拒绝注册，`apply()` 必须吞掉该
+  拒绝并告警，而不是把全部设置入口一起弄丢。
+
+## 0.5.2 - 2026-09-20
+
+### Changed
+
+- **退役**人工审查管线（review gate，beta）。其语义由"建议"取代：收益模型仍按"整批一次
+  mutation"定价，但它算出的分带（`profitable` / `high-impact` / `slow-payback` /
+  `unpriceable` / `not-worth-it`）现在只作为 `reduction-advice` 审计记录发布，并在 advisor
+  报告路由上留一份快照——绝不扣留、延迟或改写任何 reduction。该 gate 与本功能自身的要求
+  （缩减不阻断自动处理）相矛盾，且在出厂默认下（`reviewMode` 开 + 4000 token 高影响阈值
+  对 8192 token 的 fresh 门槛）会把整批 fresh 100% 改道进人审，等于让选择开启它的用户失去
+  自动路径。建议阈值改为模块常量（α `0.1`、高影响 `4000` token）：没有任何路径依据它们
+  行动，因此不再作为配置项。
+- 随 gate 一并移除：审查队列及其 `storageDomain` 适配器、进程级注册表、
+  `review-queue` / `review-decide` 两条 HTTP 路由与 `reviewQueueRoute` 部署开关、
+  `shell.overlay` 客户端浮窗、`reviewMode` / `reviewTimeoutTurns` /
+  `cacheHitDiscountAlpha` / `reviewHighImpactTokens` 四个 settings 键，以及
+  `review-outcome` 审计类型。这四个键在**两个解码器**中仍被接受但被忽略——既有配置文档
+  （线上即带 `reviewMode: false`）照常加载、设置卡照常渲染——且永不进入已解析的 policy。
+  只读路由 `GET .../advisor-report` 额外提供 `lastAdvice`。
+
+### Added
+
+- 退役的回归钉桩：一条宿主集成测试用**当年会全量改道的那套配置**（`reviewMode: true`、
+  `reviewHighImpactTokens: 1`）断言 fresh 批次**照常落地**并附带 `high-impact` 建议记录；
+  另一条弃用契约测试在运行时解析器与浏览器解码器两侧钉死"接受但忽略"。
+
+### Rollback
+
+- 回退到仍带 gate 的最后一个版本：`npm dist-tag add
+  dsh-context-compression-improved@0.5.1 dsh-0.1.5 --registry https://registry.npmjs.org/`，
+  然后 `dsh plugin --profile web add dsh-context-compression-improved@0.5.1`。
+
+## 0.5.1 - 2026-09-20
+
+### Fixed
+
+- 同一 identity 的并发 preset-overlay 组装在 Windows 上不再失败：发布改为按目标路径串行，
+  且当原子 rename 仍然竞争失败时，会先确认目标文件已带有本 staging 文件的
+  `{mtimeMs, size}` standing key 才判定发布成功。Windows 的 `MoveFileEx` 会把这种竞争
+  失败报成 `EPERM`/`EBUSY`，而 POSIX `rename` 只是覆盖目标——这曾导致并发启动会话时
+  `standingKeyFor()` 抛错。目标不匹配时仍会明确失败，静默复用世代依旧被禁止。
+- 一并修复了长期掩盖该问题及其它预存红灯的发布门禁与测试：packed smoke 中陈旧的标识符与
+  已退役的审计 reason、过期的客户端 inject 断言，以及仅 Windows 触发的 spawn 陷阱
+  （`git` 与多行 `node -e` 脚本经 `cmd.exe` 转发会被改写参数）。
+
+## 0.5.0 - 2026-09-20
+
+### Added
+
+- 建议型相关度 advisor（仅统计与建议，默认关闭）：每个 turn 边界以 fire-and-forget 方式
+  运行一次 pass——从最近的 `todo/write` 事件总结尾部任务语义（无 todolist 时回退到最近
+  用户文本）、对历史 tool-result 候选做"内容+注释语义 ↔ 当前任务"的增量相关度打分、并
+  计算前缀腐化度（prefix-decay，按 characterPressure 加权的相关度均值取反）。低相关的
+  旧段标记为 `recertified`，仅作为后续 history 激进化的建议输入——本轮没有任何决策路径
+  消费它，且 advisor 输出绝不抑制、延迟或改写任何本应落地的 reduction（有专项不变量测试
+  钉死）。经 `presetOptions.advisor*` settings 键配置（`advisorMode` `''|'host'|'direct'`，
+  默认 `''`；direct 通道复用 estimator 端点；`SideChannel` 新增可选 overrides 参数，
+  共享传输层而不共享配置）。可观测性：新增 `advisor-outcome` 审计记录（content-free，
+  每阶段一条：summary / scoring / decay）与只读 HTTP 路由
+  `GET .../advisor-report?sessionId=`（部署级 opt-in 开关 `advisorReportRoute`，与 review
+  路由同骨架）。本轮刻意不提供客户端 UI。
+
+## 0.4.0 - 2026-09-20
+
+### Fixed
+
+- 插件不再依赖路由 model id：全部规划闸门改按字符基准决策（Unicode code points，
+  经 `characterPressure` / `pressureCost`），不再以 exact tokenizer 计数为前提，
+  因此未内建 tokenizer 的路由（线上 `deepseek-flash`）重新能落地改写而不是静默跳过。
+  token 阈值键名与数值全部保留（按既有 4.0 字符/token 约定换算，冻结 profile 基线零改动）；
+  token 数值降级为遥测，由 rewrite 审计记录新增的 `measurementBasis` 字段如实区分
+  （`exact-tokenizer` 与 `characters`，派生时写 `tokenizerId: 'characters'` /
+  `tokenizerRevision: 'chars-per-token-4.0'`）。回滚：确认无后续改动依赖本提交后再执行
+  `git revert 7a1972a` 整体恢复旧闸门。
+
+### Changed
+
+- runtime 包并入 selector 包：一次安装即可获得完整栈，仓库根目录即为安装面
+  （`name`、`main`、`types`、`exports`（含 `./pruner`、`./invariant`）、`dependencies`、`dsh`），
+  工具链、脚本与 CI 一并收敛为单包。已真机验证的 estimator-catalog 路由注册（双前缀、受保护的
+  双通道激活、按请求解析服务、可检索的生命周期日志）重放到本线，并新增宿主侧守门；`ab2175a`
+  降级为 `z.any()` 的 settings schema 已还原，每日 Custom 默认值重新下发。
+- 在本分支适配官方 DeepSeek Harness `v0.1.5-rc.2`。全部 `@deepseek-ai/dsh-*` 开发依赖与 e2e 官方宿主清单从 `0.1.1-rc.2` 升至 `0.1.5-rc.2`（cordis `4.0.2`、schemastery `3.18.2`），含新的拆分包（`dsh-session-projection`、`dsh-session-persistence`、`dsh-atomic-write`、`dsh-home-paths`、`dsh-sandbox` 等）与 `dsh-client-store` 客户端栈。
+- Surface 替换操作改用 v3 的 `startSeq`/`endSeq` 形状与品牌化 `SessionSeq`；`compaction/prune` 清单保留持久化的 `start`/`end` 字段。surface node 事件改为按 seq 查找而非数组下标。
+- 客户端 bundle 不再引用已移除的 `@deepseek-ai/dsh-client-runtime`：settings 类型改自 `@deepseek-ai/dsh-client-ui-settings`，会话 hooks 合并自 `@deepseek-ai/dsh-client-ui-session`。两份 package manifest 与 `dsh.plugin.json` 声明 `engines.dsh >=0.1.5-alpha.1 <0.2.0-0`。
+- Harness 0.1.5 不再向浏览器暴露会话 `agentPreset`，客户端无法再识别 Minimal 会话；选择器保持可选，旧的不可用横幅不再出现。
+- 测试套件按 0.1.5 语义更新：cordis 插件启动需要 `.await()`，Token Meter 需要预先挂载 `SessionProjectionRegistry`，assistant 事件携带 `stream: []`，settings 命名空间为普通字符串。
+
+### 修复
+
+- 估计器卡片在 Harness 宿主通道上不再要求 API Key。选择宿主通道后只显示实时供应商/模型下拉框，并标出当前真正生效的路由（显式覆盖优先，否则跟随会话默认模型）；既不显示密钥输入框，也不再有第二个手填模型输入——端点地址、模型文本框与只写密钥均只属于直连端点通道。
+- `presetOptions` 改为按路径写入。此前整段写入会替换整个分节，导致再改动估计器的任何一个字段（供应商、模型、端点）都会删掉 `estimatorMode` 及其余全部覆盖值——估计器被静默关回关闭状态，而面板却报告保存成功。现在每个字段只写自己，`undefined` 只清除指名的那一个字段，且 confirm-on-write 校验的是同一组字段而非仅校验通道。
+- 新增回归覆盖：`packages/selector/tests/preset-options-write.client.spec.ts`（按路径写入、保留同级字段、显式清除、空改动不写、未提交写入的报错）与 `packages/selector/tests/estimator-channel.client.spec.tsx`（各通道字段、目录下拉框、手填回退）。
+
+
+### 新增
+
+- 正交的代码骨架压缩门（`codeSkeleton.enabled`，默认关闭）：超大源码类工具结果首次曝光时，可保留导入与声明的骨架——省略函数体并保留错误行——失败时回退到原头部裁剪。这道门独立于所有 Profile，且以精确 tokenizer 测量为前提。
+- 选择器设置区内新增该门的开关，附简体中文与英文文案。
+- 新增段的浏览器/运行时解码对齐测试、`saveCodeSkeleton` 的 confirm-on-write 契约测试，以及全文档 parity 矩阵扩展。
+
+### 变更
+
+- 新增 ESLint 平铺配置基线（`pnpm lint`，CI 同步强制）与 `pnpm test:watch` TDD 环路；清理死导入，并修复 lint 基线暴露的两处错误处理路径。
+- 本仓库现为 `WilliamShi666/dsh-context-compression-selector` 的改进版 fork；文档提供英、简中、日、韩四种语言。

package/docs/installation.md

@@ -1,103 +1,103 @@
-# 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 published to npm as
-`dsh-context-compression-improved` under the `dsh-0.1.5` dist-tag; the package name
-intentionally stays upstream's. The runtime that used to be a second package is now part of
-it, so one install brings the whole stack.
-
-## 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 model route. Lossy compression — including the code-skeleton gate — decides on the character basis, so no bundled-tokenizer route requirement remains; when a bundled tokenizer exists its exact counts are recorded as telemetry, and 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. Optional: the advisory relevance advisor
-
-The plugin can keep statistics about how relevant the session's history still is — advisory only, it never decides or blocks anything. It is off by default; turn it on by editing the `presetOptions` section of the context-compression settings (settings JSON, no UI card this round):
-
-```json
-"presetOptions": {
-  "advisorMode": "host",
-  "advisorRefreshTurns": 8,
-  "advisorScoreThreshold": 0.35,
-  "advisorSampleLimit": 16,
-  "advisorMinTokens": 250,
-  "advisorTimeoutMs": 8000
-}
-```
-
-`advisorMode: "host"` calls the harness `llm` service; `"direct"` reuses the estimator's
-`estimatorBaseUrl` / `estimatorApiKey` / `estimatorModel` endpoint. At every turn boundary
-the advisor (1) summarizes the current task from the most recent `todo/write` event,
-(2) incrementally scores historical tool results for content-and-comment relevance, and
-(3) records a prefix-decay figure. Results surface as `advisor-outcome` audit records and,
-with the deployment flag `advisorReportRoute: true`, a read-only
-`GET .../advisor-report?sessionId=` HTTP route. What the advisor reports can never
-suppress, delay, or rewrite any reduction that would land.
-
-## 6. 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 (decisions run on the character basis; no exact-tokenizer route requirement), 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.
+# 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 published to npm as
+`dsh-context-compression-improved` under the `dsh-0.1.5` dist-tag; the package name
+intentionally stays upstream's. The runtime that used to be a second package is now part of
+it, so one install brings the whole stack.
+
+## 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 model route. Lossy compression — including the code-skeleton gate — decides on the character basis, so no bundled-tokenizer route requirement remains; when a bundled tokenizer exists its exact counts are recorded as telemetry, and 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. Optional: the advisory relevance advisor
+
+The plugin can keep statistics about how relevant the session's history still is — advisory only, it never decides or blocks anything. It is off by default; turn it on by editing the `presetOptions` section of the context-compression settings (settings JSON, no UI card this round):
+
+```json
+"presetOptions": {
+  "advisorMode": "host",
+  "advisorRefreshTurns": 8,
+  "advisorScoreThreshold": 0.35,
+  "advisorSampleLimit": 16,
+  "advisorMinTokens": 250,
+  "advisorTimeoutMs": 8000
+}
+```
+
+`advisorMode: "host"` calls the harness `llm` service; `"direct"` reuses the estimator's
+`estimatorBaseUrl` / `estimatorApiKey` / `estimatorModel` endpoint. At every turn boundary
+the advisor (1) summarizes the current task from the most recent `todo/write` event,
+(2) incrementally scores historical tool results for content-and-comment relevance, and
+(3) records a prefix-decay figure. Results surface as `advisor-outcome` audit records and,
+with the deployment flag `advisorReportRoute: true`, a read-only
+`GET .../advisor-report?sessionId=` HTTP route. What the advisor reports can never
+suppress, delay, or rewrite any reduction that would land.
+
+## 6. 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 (decisions run on the character basis; no exact-tokenizer route requirement), 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

@@ -1,100 +1,100 @@
-# 安装 dsh-context-compression-improved
-
-> [English](installation.md) · [中文](installation.zh.md) · [日本語](installation.ja.md) · [한국어](installation.ko.md)
-
-本教程从源码安装 fork。fork 亦已发布到 npm，dist-tag 为 `dsh-0.1.5`；包名有意与上游保持一致：
-`dsh-context-compression-improved`（单一包 —— 原先独立发布的 runtime 包已并入其中）。
-
-## 前置条件
-
-- 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 模型路由。有损压缩——包括代码骨架门——按字符基准决策，不再要求内建精确 tokenizer；存在内建 tokenizer 时其 exact 计数仅作遥测记录，其他路由 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. 可选：建议型相关度 advisor
-
-插件可以对"会话历史还有多相关"做统计——仅建议性质，不做任何决策、也不阻断任何流程。默认关闭；本轮没有设置卡片，请直接编辑上下文压缩设置中的 `presetOptions` 段（settings JSON）：
-
-```json
-"presetOptions": {
-  "advisorMode": "host",
-  "advisorRefreshTurns": 8,
-  "advisorScoreThreshold": 0.35,
-  "advisorSampleLimit": 16,
-  "advisorMinTokens": 250,
-  "advisorTimeoutMs": 8000
-}
-```
-
-`advisorMode: "host"` 走 harness `llm` 服务；`"direct"` 复用 estimator 的
-`estimatorBaseUrl` / `estimatorApiKey` / `estimatorModel` 端点。每个 turn 边界，advisor
-会：(1) 从最近的 `todo/write` 事件总结当前任务语义；(2) 对历史 tool result 做"内容+注释
-语义 ↔ 当前任务"的增量相关度打分；(3) 记录前缀腐化度（prefix-decay）。结果以
-`advisor-outcome` 审计记录呈现；部署配置打开 `advisorReportRoute: true` 后，还可经只读
-HTTP 路由 `GET .../advisor-report?sessionId=` 读取。advisor 报告的任何内容都不会抑制、
-延迟或改写任何本应落地的 reduction。
-
-## 6. 更新或卸载
-
-```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 的升级，请先移除旧版本再安装。
+# 安装 dsh-context-compression-improved
+
+> [English](installation.md) · [中文](installation.zh.md) · [日本語](installation.ja.md) · [한국어](installation.ko.md)
+
+本教程从源码安装 fork。fork 亦已发布到 npm，dist-tag 为 `dsh-0.1.5`；包名有意与上游保持一致：
+`dsh-context-compression-improved`（单一包 —— 原先独立发布的 runtime 包已并入其中）。
+
+## 前置条件
+
+- 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 模型路由。有损压缩——包括代码骨架门——按字符基准决策，不再要求内建精确 tokenizer；存在内建 tokenizer 时其 exact 计数仅作遥测记录，其他路由 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. 可选：建议型相关度 advisor
+
+插件可以对"会话历史还有多相关"做统计——仅建议性质，不做任何决策、也不阻断任何流程。默认关闭；本轮没有设置卡片，请直接编辑上下文压缩设置中的 `presetOptions` 段（settings JSON）：
+
+```json
+"presetOptions": {
+  "advisorMode": "host",
+  "advisorRefreshTurns": 8,
+  "advisorScoreThreshold": 0.35,
+  "advisorSampleLimit": 16,
+  "advisorMinTokens": 250,
+  "advisorTimeoutMs": 8000
+}
+```
+
+`advisorMode: "host"` 走 harness `llm` 服务；`"direct"` 复用 estimator 的
+`estimatorBaseUrl` / `estimatorApiKey` / `estimatorModel` 端点。每个 turn 边界，advisor
+会：(1) 从最近的 `todo/write` 事件总结当前任务语义；(2) 对历史 tool result 做"内容+注释
+语义 ↔ 当前任务"的增量相关度打分；(3) 记录前缀腐化度（prefix-decay）。结果以
+`advisor-outcome` 审计记录呈现；部署配置打开 `advisorReportRoute: true` 后，还可经只读
+HTTP 路由 `GET .../advisor-report?sessionId=` 读取。advisor 报告的任何内容都不会抑制、
+延迟或改写任何本应落地的 reduction。
+
+## 6. 更新或卸载
+
+```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 的升级，请先移除旧版本再安装。