Billwu18/dsh-cache-hit-monitor

Cache Hit Monitor

Live prompt-cache telemetry for the current session, drawn as an instrument panel in the DSH right sidebar.

English · 中文说明

---

What it does

The plugin adds one tab to the DSH right sidebar. It reads the tokenUsage and contextPressure session projections the Host already publishes and shows them as four flat instrument faces:

The tab opens by itself once per page load, so the panel is on screen without hunting through the tab guide. It closes like any other tab.

How the hit rate is calculated

hit rate = cache read / (cache read + cache write + uncached input)

Output tokens are deliberately excluded. Generated tokens are never cacheable, so counting them would flatter the number — a long generation would make a cold prompt look warm.

The reactor core in detail

One cell is one request that settled while the panel was mounted, ordered newest-first from the top left. The board is one whole number of rows at all times, and it is never taller than the history it actually holds, so a young session shows a short row rather than a large empty lattice.

• Ink — the request's hit rate, on a single-hue intensity ramp.
• Diameter — sqrt(request tokens / heaviest request on the board), which keeps small requests visible next to a cold burst.
• Fade — older cells dim toward the bottom of the board.

Each cell carries a title with its exact read / write / uncached / output split, so the picture can be audited rather than trusted.

---

Install

From GitHub

dsh plugin --profile web add github:Billwu18/dsh-cache-hit-monitor

Or install it through the Plugin Manager in the Web UI.

Manual, for development

git clone https://github.com/Billwu18/dsh-cache-hit-monitor
dsh plugin --profile web add /absolute/path/to/dsh-cache-hit-monitor

Then reload the page. The Host re-reads plugin artifacts by modification time, so edits to client.js are picked up by a refresh — no dsh web restart.

Requirements

• DSH >=0.1.7-rc.1 <0.2.0-0
• Node >=20 (only for the test harnesses; the plugin itself runs in the browser)
• React 18 or newer, which the DSH Web UI provides

No dependencies, no build step, no install scripts.

---

Reading the instrument

• A filled red dot next to the title means at least one request has settled in this session; an empty ring means nothing has been recorded yet.
• The register bank shows session totals, not per-request values. Its lamps are proportional to the largest bucket on screen.
• The core legend (0 % → 100 %) is the ink ramp, so a cell's brightness can be read back as a number.
• ROWS 4 / 6 / 9 sets the maximum board height in rows. The width is chosen by the sidebar itself: the panel measures how many columns fit and the board grows into whole rows, so the same history fills more rows in a narrow sidebar than in a wide one.
• CLR clears the recorded history for the current session. It does not touch any Host-side data.

---

How it works

The Host half is deliberately inert (index.js exports an empty apply). It exists so the bundle has a Loader row and can be enabled, disabled and inspected like any other plugin.

Everything the panel shows is already computed on the Host: @deepseek-ai/dsh-token-meter folds the durable session log into the tokenUsage and contextPressure projections. The Client half reads them from its slot props via useProjection and renders.

The client bundle is a single file (client.js) in the DSH browser-module format. It uses only React and standard browser APIs:

• The board measures its own column count from the live layout with getComputedStyle plus a ResizeObserver, and re-renders once before paint. If the measurement is unavailable the board simply grows with the data instead of being capped.
• The clock for the "age" readout lives in its own component and ticks at the resolution it prints (1 s / 5 s / 30 s), so an idle panel is not reconciling the whole board once a second.
• Recorded history lives in a bounded module-level cache keyed by session, so it survives the remount that a tab switch causes. The tab is also registered with keepMounted: true, which prevents that remount in the first place.

Privacy

The panel reads local session projections. It makes no network requests, sends no telemetry, and stores nothing outside the browser tab. Clearing history touches only in-memory state.

---

Compatibility

---

Development

No dependencies are required to work on this plugin — the tests run on plain Node against the real client.js.

node test/run-all.mjs     # all four suites
node test/preview.mjs     # writes HTML that can be screenshotted

Repository layout

dsh-cache-hit-monitor/
├── client.js              the entire browser half (React, DSH module format)
├── index.js               the host half (intentionally inert)
├── cordis.patch.yml       the Loader row that installs the plugin
├── package.json           manifest: dsh.bundle + dsh.client
├── icon.svg               plugin card artwork
├── screenshots.json       storefront screenshots, relative to this file
├── locale/
│   ├── en.json            plugin card title and description
│   └── zh.json
├── assets/                screenshots referenced by the READMEs
└── test/
    ├── run-all.mjs        runs every suite below
    ├── preview.mjs        renders the panel to standalone HTML
    ├── wiring.test.mjs    bundle identity, effects, tab and slot registration
    ├── render.test.mjs    the rendered tree: shapes, counts, no NaN, key coverage
    ├── persist.test.mjs   history and depth survive a remount
    └── robust.test.mjs    adversarial inputs and locale coverage

How the tests work

There is no DOM and no test framework. Each harness stubs window.__ModuleLoader__ to capture the bundle, stubs react, applies the real apply(ctx) against a stub context, then drives the registered component with a small renderer.

That is enough to assert real behaviour: which services the plugin injects, what it registers into which slot, how many cells and lamps the tree contains, that history survives a remount, and that no reachable input produces a thrown exception or leaks undefined/NaN into a style string.

---

License

MIT © 2026 Billwu18