Skip to main content

dsh-ui-web/packages/dsh-live-stats

34Stars2Forks0Issues0Watchers

Displays real-time input/output token estimates and generation throughput rates in the DSH Web session status bar, continuously updating during streaming output responses.

Categories▣ UI Enhancements
Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki

ⓘ This plugin is a sub-package of the CAPTAIN1275/dsh-ui-web monorepo — stars and activity count the whole repository.

CAPTAIN1275CAPTAIN1275
·CAPTAIN1275/dsh-ui-web
Language
TypeScript
License
Apache-2.0
Branch
main
dsh-plugindsh-plugin-marketdsh-plugins

Install

cmdweb profile
$ dsh plugin --profile web add @captain1275/dsh-live-stats

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin CAPTAIN1275/dsh-ui-web/packages/dsh-live-stats for me: review the repository at https://github.com/CAPTAIN1275/dsh-ui-web first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-Line Description

Adds real-time input/output token estimation and generation throughput display to DSH Web's session status bar. When responding to streaming output, numbers update continuously with each chunk, and are replaced with precise values once the provider actually returns usage.

Core Features

  • Real-time input token estimation: Calculates input volume before streaming response starts based on character count plus block/message framework overhead, including system prompts and tool schemas
  • Real-time output token estimation: Accumulates from text-delta/reasoning-delta/tool-call-delta streaming chunks, refreshing the reading with each new chunk
  • Auto-replacement with precise values: When provider returns usage chunk or final message, immediately replaces the heuristic estimation from earlier steps with real values
  • Displays generation throughput TPS: Renders throughput rate in the session status bar as TPS 31.4 tok/s, calculated as active step's output tokens / wall-clock time
  • Persistent rate display: Once any step measures throughput, new steps use the last measured value before outputting their first chunk, or when encountering steps without rates; status bar doesn't flicker or disappear
  • Settings panel: Browser-side mounts a settings card in the Web UI plugin group, visually editing three estimation parameters and master switch, effective immediately without restart

Technical Implementation

  • Language: TypeScript (peer dependency React 18.2, dsh.client.platform="web")
  • Key Dependencies: @deepseek-ai/dsh-session-projection (projection host), schemastery (settings schema validation), zod (projection reading boundary schema), @deepseek-ai/dsh-token-meter (reading type source)
  • Architecture Pattern: Cordis bidirectional plugin. Host half registers a replayable session projection named liveTokenUsage (ctx.sessionProjections.register), freezing estimation parameters into a folded closure; client half mounts TPS row in conversation.composer.dock slot, settings card in web-ui.plugin.item slot
  • Entry Files: Host side src/index.ts (exports inject/Config/apply), client src/client/index.ts; pure function core in src/estimator.ts (character density estimation) and src/projection.ts (event folding + TPS derivation)

Use Cases

When running long tasks on DSH Web, seeing only the final token count feels uncertain. This plugin turns "how fast is the model generating" and "approximately how many tokens is this response" into real-time readings on the status bar. Ideal for heavy users who need immediate throughput and usage observation, and for engineers sensitive to KV cache costs to compare actual rates across different models/parameters.

Prerequisites & Compatibility

DependencyMinimum VersionDescription
DSH Web0.1.0-rc.6All peerDependencies pinned to ^0.1.0-rc.6 (including dsh-client-runtime, dsh-client-connection, dsh-client-ui-conversation, dsh-client-ui-settings, dsh-client-ui-slots, dsh-invariants, dsh-llm, dsh-session, dsh-session-projection, dsh-settings, dsh-token-meter)
React18.2.0Both client card and TPS row use React components
PlatformCross-platform (macOS / Windows / Linux)Runtime is OS-agnostic, but dsh.client.platform="web", only renders in Web host
Native ModulesNoneAll logic completed in TypeScript and React, no node-gyp dependencies

Installation

dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/dsh-live-stats

After installation, restart dsh web and the TPS group appears in the session status bar; it can also be added as a regular overlay line to ~/.dsh/config.yaml (saves and hot-reloads):

- insert:
    - id: live-stats
      name: '@captain1275/dsh-live-stats'
      config:
        charsPerToken: 4
        blockOverhead: 4
        roleOverhead: 4

Configuration Options

ConfigurationTypeDescriptionDefault
enabledBooleanMaster switch, disables token estimation and throughput tracking, but still registers projection skeletontrue
charsPerTokenNumberApproximate number of text characters per token; Chinese has higher density, can adjust to around 1.54
blockOverheadNon-negative integerFixed framework token count for each content block (text/tool call/tool result)4
roleOverheadNon-negative integerFixed framework token count per message or assistant response4

The three estimation parameters only take effect when charsPerToken is a positive finite number and blockOverhead and roleOverhead are non-negative integers; otherwise an error is thrown during the loading phase. After modifying from the settings panel, the host discards the old projection and refolds the session log with the new parameters, no restart of dsh web required.

FAQ

Q: Do I need to restart DSH Web after installation?

A: Yes. Projection registration happens in the host process; after installing or uninstalling, you must restart dsh web for it to take effect; browser hard refresh cannot replace host restart.

Q: Will it change the actual token count sent to the model?

A: No. The plugin doesn't inject prompt segments, doesn't register tools, doesn't emit session events, has zero impact on token count for each request to the model, and won't affect KV cache stability of system prompts.

Q: What should I fill in for charsPerToken?

A: The default 4 characters/token is sufficient for pure ASCII, but underestimates for Chinese. You can lower it to around 1.5 in the settings panel or ~/.dsh/config.yaml, then observe the deviation between ~ estimation and the provider's actual returned values to fine-tune.

Q: What does the ~ before the numbers in the status bar mean?

A: It indicates it's a heuristic estimation based on character count. Once the provider returns a usage chunk or final message with usage during streaming, the estimation is replaced in-place with the precise value; mid-process retries replace estimations from that step onward, aborted rounds remove their unsettled estimations.

Q: Do I need to clean up data after uninstalling?

A: The plugin itself doesn't persist any data; after uninstalling, the next time dsh web starts, it won't register the liveTokenUsage projection, and the session status bar automatically returns to the style without TPS group, no manual cache or data clearing required.

Q: Does it support TUI or desktop?

A: Not currently supported. The TPS row only renders in DSH Web's session status bar (composer dock); TUI, desktop, and mobile have no equivalent display locations.

Difficulty Level

Beginner — Install with one command, restart DSH Web to see results, all three estimation parameters have default values; only need to adjust when significant estimation deviation is observed.

Known Issues & Limitations

  • Heuristic estimation: Input/output totals marked with ~ are only character count approximations before provider usage arrives; precise cache hit statistics always come from DSH's built-in token usage projection, this plugin won't replace that authoritative path
  • Web only: TPS group renders in DSH Web's composer dock; TUI, desktop, and mobile have no equivalent display locations
  • Single active step: Each session only tracks one active step, status bar displays that session's view; concurrent sessions each have independent projections that don't interfere
  • Density assumption: charsPerToken=4 overestimates for pure ASCII, underestimates for Chinese; if estimation deviation is significant, this value can be fine-tuned according to deployment
  • Doesn't affect model experience: The plugin has zero intrusion into model's prompts/tools/event stream, only consumes persisted event stream for read-only rendering

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/CAPTAIN1275/dsh-ui-web/packages/dsh-live-stats)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory