dsh-native-deepseek-balance

Readme

<div align="center">

# DSH Native DeepSeek Balance

**Official DeepSeek API cash balance with a private DSH-local usage dashboard**

[![CI](https://github.com/WSL043/dsh-native-deepseek-balance/actions/workflows/ci.yml/badge.svg)](https://github.com/WSL043/dsh-native-deepseek-balance/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/dsh-native-deepseek-balance?logo=npm&label=npm)](https://www.npmjs.com/package/dsh-native-deepseek-balance)
[![total npm downloads](https://img.shields.io/npm/dt/dsh-native-deepseek-balance?logo=npm&label=total%20downloads)](https://www.npmjs.com/package/dsh-native-deepseek-balance)
[![MIT](https://img.shields.io/badge/license-MIT-111111.svg)](LICENSE)
[![Stars](https://img.shields.io/github/stars/WSL043/dsh-native-deepseek-balance?style=flat&logo=github&label=stars)](https://github.com/WSL043/dsh-native-deepseek-balance/stargazers)

[Install](#install) · [Privacy](#privacy-and-network-access) · [简体中文](README.zh-CN.md)

</div>

<p align="center">
  <img src="https://raw.githubusercontent.com/WSL043/dsh-native-deepseek-balance/main/docs/assets/balance-composer-en.png" width="900" alt="DeepSeek API cash balance pill and detail panel in the DeepSeek Harness composer">
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/WSL043/dsh-native-deepseek-balance/main/docs/assets/balance-usage-en.png" width="720" alt="DeepSeek API cash balance with local request and token usage charts in DeepSeek Harness Settings">
  <br><sub>Captured from an installed official DeepSeek Harness build. Balance and sample session data are isolated for documentation; the chart is not account-wide DeepSeek billing.</sub>
</p>

## What it does

- Shows one quiet 28 px balance pill beside the composer controls only while the active model uses the DeepSeek provider; Codex and other providers remain untouched.
- Opens a compact detail panel and provides a dedicated **Settings → DeepSeek** page.
- Shows one selected CNY or USD balance at a time, including total, granted, and topped-up cash balance.
- Lets you choose exactly one display currency, CNY or USD, shared by the dashboard and composer pill without adding another credential.
- Opens DeepSeek's official account balance page for top-up from either balance surface; the plugin never handles a payment itself.
- Adds a dedicated usage dashboard with API calls, Token totals, cache hit rate, switchable daily Token/request charts, and model distribution.
- Breaks Token usage into uncached input, output, cache read, and cache write values reported by the provider.
- Pauses automatic refresh in hidden tabs, catches up when visible, and shows when the data was last updated.
- Keeps the last successful value during a temporary failure and labels it as stale; an unknown balance is never shown as zero.

DeepSeek's public API reports current account cash balance, not per-model quota. DSH session events report the usage of calls made through DSH. The dashboard keeps those sources visibly separate: it does not present local DSH activity as account-wide DeepSeek usage or invent an official spending history.

## Install

PowerShell helper—it still delegates to DSH's official plugin command:

```powershell
irm 'https://github.com/WSL043/dsh-native-deepseek-balance/releases/latest/download/install.ps1' | iex
```

Or use the official command directly:

```sh
dsh plugin --profile web add dsh-native-deepseek-balance
```

Restart DSH after installation. The plugin reuses the DeepSeek API key configured in **Settings → Models**.

Update or uninstall:

```sh
dsh plugin --profile web update dsh-native-deepseek-balance
dsh plugin --profile web remove dsh-native-deepseek-balance
```

For an Agent, use the packaged [installation and verification guide](AGENTS.md).

## Privacy and network access

For balance, the DSH host calls only DeepSeek's documented
[`GET https://api.deepseek.com/user/balance`](https://api-docs.deepseek.com/api/get-user-balance)
endpoint. The API key remains in the host credential service; the browser receives only validated currency and balance fields. Provider error bodies, credentials, and account identifiers are never returned to the UI. Successful balance responses are cached in memory for 30 seconds and are never written to disk.

Usage charts are derived from the normal DSH session logs already stored in the selected profile. The plugin creates no second telemetry database and sends no analytics request.

The plugin registers no model-facing tool, adds nothing to the system prompt or conversation history, and consumes no model tokens.

## Compatibility

Supports the latest DeepSeek Harness release recorded in the package metadata. [DSH-Portable](https://github.com/WSL043/DSH-Portable) uses the same standard `dsh plugin` command and treats this as an optional plugin.

This community project is not affiliated with or endorsed by DeepSeek.

[Report a bug](https://github.com/WSL043/dsh-native-deepseek-balance/issues/new?template=bug-report.yml) · [Request a feature](https://github.com/WSL043/dsh-native-deepseek-balance/issues/new?template=feature-request.yml) · [Security](SECURITY.md) · [MIT](LICENSE)