dsh-usage-dashboard

dsh-usage-dashboard

English | 中文

A usage dashboard for DeepSeek Harness web deployments, shipped as a first-class composition plugin (one host half, one trusted browser half). It replaces the sidebar's built-in usage dialog with a durable, deployment-wide usage ledger that fixes the built-in dashboard's four structural problems:

1. No manual expansion. The built-in dashboard folds only the sessions the browser has loaded. This plugin backfills every persisted session straight from the session logs at activation, then folds every committed event live — nothing needs to be opened first.
2. Deleting a conversation never reduces the totals. The ledger lives in its own storage domain (usage_dashboard in the harness storage root), completely separate from the session logs and their projection caches.
3. Backup and migration. The dialog exports the whole ledger as one JSON document and imports it again — importing into a fresh deployment restores the full history, and re-importing the same backup never double counts.
4. Exact numbers — no more, no less. The fold mirrors the harness's own tokenUsage / sessionStats projection semantics field-for-field (verified against the harness folds over randomized event sequences): same-step usage samples replace instead of adding, fork/subagent seed prefixes are skipped so an ancestor's history is counted exactly once, and every write is cross-checked against the live tokenUsage projection with a loud mismatch log.

It also records the models used by subagents (each subagent is its own session, attributed to its parent), and draws the usage trend per day — stacked input/output bars plus a cumulative line, with 7-day / 30-day / all windows.

Why a composition plugin (and no approval dialog)

The earlier releases installed the dashboard as a dynamic Cordis package per session (via the autoload/ loader). Dynamic browser halves are gated by the harness's client-code activation policy, so every harness start showed a Cordis approval dialog for usage-dashboard in every session. This release mounts the same host ledger and the same sidebar dialog as ordinary composition rows in the web profile patch: the browser half is part of the trusted page composition, so no dynamic plugin is defined, nothing is approved, and no dialog ever appears. The ledger data itself is unchanged and carries over seamlessly.

Requirements

A DeepSeek Harness web-profile deployment that mounts storage-domain, session-persistence, and webServer (the standard web bundle does). The plugin reads only public services — it changes no harness code.

Installation (per deployment)

1. Build the deployable package (or use a release's prebuilt lib/):

   node scripts/build.mjs   # emits lib/index.js (host) + lib/client.js (browser bundle)
   

2. Copy the package into the profile's packages directory:

   cp -r . "$DSH_HOME/profiles/<profile>/packages/dsh-usage-dashboard"
   

3. Add the dependency to <profile>/package.json and link it:

   "dependencies": { "dsh-usage-dashboard": "file:./packages/dsh-usage-dashboard" }
   

   then run pnpm install in the profile directory.

4. Append to <profile>/cordis.patch.yml:

   # Usage dashboard: durable cross-session ledger (host) + trusted sidebar
   # dashboard (browser). No dynamic-plugin approval is involved.
   - insert:
       - id: usage-dashboard
         name: dsh-usage-dashboard
   # Keep only the most feature-complete dashboard: disable the shipped
   # projection-only footer action (same sidebar cell).
   - id: ui-dashboard
     disabled: true
   

5. Restart the harness. The sidebar now shows a single 用量 action backed by the durable ledger, for every session, with no approval prompts.

What the dialog shows

• Stat cards — total / input / output tokens, cache-hit share, cache read/write, session count, turns, steps, LLM and tool wall time, decode throughput.
• Usage trend (per day) — stacked input/output bars with a cumulative line, legend, dashed gridlines, sparse date ticks, and window selection.
• Model usage — per-model totals including the models subagents billed, with distinct-session counts.
• Session table — per-session tokens, newest billed model, turns/steps, with a 子代理 badge for subagent sessions.
• Backup & migration — export (copy the JSON document to a file) and import (paste a backup and merge it).

Data semantics

• Each ledger record is keyed by sessionId@createdAt and carries the folded state (per-day and per-model token buckets, turns/steps/timings, newest billed model) plus a seq watermark. Records only ever advance: writes are serialized per key and a lower-watermark snapshot can never regress a stored record.
• A session's own suffix starts at its header's seedLength: fork and subagent children count exactly what they themselves billed, and the inherited prefix stays attributed to the ancestor — the totals are the true billed usage with no double counting anywhere in a fork tree.
• Live sessions fold through session/event listeners registered with { global: true } (at the host root this is the default view anyway; the flag keeps the code scope-independent). Activation heals every stored tail, materializes live cells, and the report additionally backfills any session the ledger has never seen, so the report is complete even for sessions created while the plugin was stopped.
• The backup document is { format: 'dsh-usage-dashboard-backup', version: 1, exportedAt, records }. Import validates every record and merges by key: a record is adopted only when its seq is higher than the stored one, so repeated imports are idempotent.
• The browser half fetches /usage-dashboard/report, /usage-dashboard/export, and /usage-dashboard/import (same-origin webServer routes registered by the host half) — the dynamic runner's harness.handle/host.call channel does not exist for composition rows.

Known limitations

• Backup travels as text. Export renders the JSON document in a textarea (copy it to a file); import accepts the same JSON pasted back.
• Day buckets use the host's local calendar. Totals never depend on the bucket; only the trend chart's grouping does.
• Sessions whose logs were deleted before the plugin ever ran cannot be reconstructed — there is nothing left to fold. Everything present in the store is counted.
• Per-session titles are joined from the live session list when available; sessions no longer in the list (e.g. deleted) show a short id.

Repository layout

• src/host.js — the canonical host-half module (ledger, heal/backfill, report/export/import webServer routes).
• src/client.js — the canonical browser-half module (sidebar action and dialog; React is provided by the bundle wrapper).
• scripts/build.mjs — generates lib/index.js and lib/client.js from the sources (the browser bundle is a window.__ModuleLoader__.load({ id, factory }) handoff).
• package.json — the deployable package manifest (dsh.client declares the web browser half; exports["./client"] points at the bundle).