@kuanfu0430/dsh-compaction-tune

Readme

# @kuanfu0430/dsh-compaction-tune

Adds a composer control for DeepSeek Harness automatic compaction: set a **percent (30–80)** or an **absolute token** threshold. The value is stored in `$DSH_HOME/settings.yaml` under `kuanfu-compaction-tune` and takes effect on the next agent step.

在 DeepSeek Harness 輸入框旁加入自動壓縮門檻控制：可設 **百分比（30–80）** 或 **絕對 token 數**。設定寫入 `$DSH_HOME/settings.yaml` 的 `kuanfu-compaction-tune` 分節，下一個 agent step 生效。

The planned listing for this repository is in [`docs/awesome-dsh-plugin.yml`](docs/awesome-dsh-plugin.yml). Submit it to [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) only after the repo is at least one day old and has 10 or more commits.

本倉預定上架條目見 [`docs/awesome-dsh-plugin.yml`](docs/awesome-dsh-plugin.yml)。請等倉庫滿一天且提交數 ≥ 10 再向 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 發 PR。

## What this is not / 這不是什麼

Official `@deepseek-ai/dsh-compaction-basic` already has a **static** `thresholdRatio` (default `0.8`) in plugin YAML. There is no in-conversation control for that field. This plugin is the live UI / settings-backed policy; it does not replace the compaction engine and does not register `/compact`.

官方 `@deepseek-ai/dsh-compaction-basic` 已有插件 YAML 裡的**靜態** `thresholdRatio`（預設 `0.8`），但沒有對話中可調的控制。本插件是即時 UI／settings 政策，不取代壓縮引擎，也不註冊 `/compact`。

## Install / 安裝

Tested on DeepSeek Harness `0.1.1-rc.2`. Not claimed compatible with `0.1.2-alpha` (conversation slots and the web token gate changed).

已在 DeepSeek Harness `0.1.1-rc.2` 驗證。不宣稱相容 `0.1.2-alpha`（會話 slot 與 Web token 閘門已變）。

```sh
dsh plugin --profile web add github:kuanfu0430/dsh-compaction-tune
```

Restart `dsh web`. The chip appears at `conversation.input.right` (composer, lower right).

重啟 `dsh web`。控件掛在 `conversation.input.right`（輸入框右下）。

The root `package.json` declares `dsh.bundle.patch` plus `cordis.patch.yml`, so `dsh plugin add` can install it. There is no build step.

根目錄 `package.json` 已宣告 `dsh.bundle.patch` 與 `cordis.patch.yml`，可直接用 `dsh plugin add` 安裝，無需編譯。

## Behaviour / 行為

- Percent mode defaults to 60%, range 30–80%.
- Token mode defaults to 128k, range 64k–832k, step 64k.
- Host-plane service `kuanfuCompactionPolicy.resolve(session)` returns frozen `{ mode, percent, tokens }`. Child sessions with `parentSession` set, `origin !== 'subagent'`, and `seedLength === 0` (for example a sidebar branch) get `null`; those sessions keep the backend 80% default.
- **Official backend** (`@deepseek-ai/dsh-compaction-basic`): when used tokens cross the effective threshold **below** the 80% safety cap, this plugin calls `compactIfNeeded(agent, 'context-overflow')`. The overflow trigger is required because the official pressure listener still gates on 80%. If the effective threshold is already at the 80% cap, this plugin does not fire and the official listener remains the only trigger.
- **Optional anchored backend** (`@kuanfu0430/dsh-compaction-anchored`): if that backend is loaded, this plugin does **not** register a second trigger. It only exposes the policy service for the anchored engine to read.
- Token thresholds above 80% of the current model window are capped in both the UI and the official fallback trigger.
- Host routes under `/compaction-tune/api/*` are limited to loopback / the profile trust fence. Responses contain settings, token/window metadata, backend identity, and compaction status — not message content or credentials.

## Limits / 限制

- Installing only this plugin does not add a compaction engine. The web profile already ships `compaction-basic`; without any `ctx.compaction`, the chip still saves settings but shows that no backend is available.
- Percent mode does nothing until the routed model’s context window can be resolved.
- Child sessions described above never inherit the main-chat threshold.
- The composer slot `conversation.input.right` is a 0.1.1-rc.2 contract. If a later DSH build removes that slot, the chip will not mount.

## Development / 開發

```sh
node --check index.js client.js
node ./test.mjs
```

## License

[MIT](./LICENSE)