# dsh-ui-web

> 在 DSH Web 会话状态行显示实时输入输出 token 估算与生成吞吐速率，响应流式输出时持续更新。

## Metadata

- Author: [@CAPTAIN1275](https://github.com/CAPTAIN1275)
- Repo: <https://github.com/CAPTAIN1275/dsh-ui-web.git>
- GitHub: [CAPTAIN1275/dsh-ui-web](https://github.com/CAPTAIN1275/dsh-ui-web)
- Stars: 34
- Language: TypeScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Topics: `dsh-plugin`, `dsh-plugin-market`, `dsh-plugins`
- Forks: 2
- Open Issues: 0
- Last push: 2026-08-16T18:08:27.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

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

## Wiki

## 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
| Dependency | Minimum Version | Description |
|---|---|---|
| DSH Web | 0.1.0-rc.6 | All 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) |
| React | 18.2.0 | Both client card and TPS row use React components |
| Platform | Cross-platform (macOS / Windows / Linux) | Runtime is OS-agnostic, but `dsh.client.platform="web"`, only renders in Web host |
| Native Modules | None | All logic completed in TypeScript and React, no node-gyp dependencies |

## Installation
```bash
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):

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

## Configuration Options
| Configuration | Type | Description | Default |
|---|---|---|---|
| `enabled` | Boolean | Master switch, disables token estimation and throughput tracking, but still registers projection skeleton | `true` |
| `charsPerToken` | Number | Approximate number of text characters per token; Chinese has higher density, can adjust to around 1.5 | `4` |
| `blockOverhead` | Non-negative integer | Fixed framework token count for each content block (text/tool call/tool result) | `4` |
| `roleOverhead` | Non-negative integer | Fixed framework token count per message or assistant response | `4` |

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

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-ui-web](https://deepseek-plugin.org/plugins/CAPTAIN1275/dsh-ui-web/packages/dsh-live-stats)
Wiki generated by AI (model: `MiniMax-M2.5`)