dsh-whale-usage

Readme

<div align="center">
  🌏 <a href="./README.zh.md">中文</a> · <b>English</b>
</div>

<div align="center">
  <b style="font-size: 1.15em;">A self-contained DeepSeek Harness (DSH) plugin: balances, today's usage &amp; app-usage in one bridge</b><br /><br />
  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" /></a>
  <a href="https://github.com/YpipaQ/dsh-whale-usage"><img alt="GitHub" src="https://img.shields.io/badge/GitHub-YpipaQ%2Fdsh--whale--usage-4d6bfe" /></a>
  <a href="https://github.com/YpipaQ/dsh-whale-usage/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YpipaQ/dsh-whale-usage" /></a>
  <a href="https://opensource.org/licenses/MIT"><img alt="DSH" src="https://img.shields.io/badge/DSH-0.1.0--rc%2B-4d6bfe" /></a>
</div>

# 🐳 dsh-whale-usage

> **Self-contained** DSH plugin that **merges two existing plugins into one**, and adds an
> **accounting / real-time-token / app-usage** configuration panel on the desktop whale widget.
>
> **Does not modify the original packages** — it absorbs their source logic at the bottom layer, so it is **immune to upstream updates**. After installing, you can maintain **two fewer plugins** (`dsh-whale-widget` and `dsh-usage-stats` may be uninstalled).

## ✨ What it is

| Absorbed source | Capabilities | Original author / repo |
|---|---|---|
| `dsh-whale-widget` | Bottom-right DeepSeek **balance whale widget** (balance, peak/off-peak pricing, random quotes &amp; sounds, **ledger / token** usage modes) | [zhu1090093659/dsh-web-ui](https://github.com/zhu1090093659/dsh-web-ui) |
| `dsh-usage-stats` | Per-DSH-session **app usage** data engine (token trends, model breakdown, activity) | [lanlandeli/dsh-usage-stats](https://github.com/lanlandeli/dsh-usage-stats) |

`dsh-whale-usage` is the bridge &amp; merge product: it **replaces** both plugins above with a single
self-contained one. © credits: [CREDITS.md](./CREDITS.md).

## 💡 Features

- **Whale widget** — kept as-is: balance, today's usage, peak/off-peak pricing, sounds, draggable.
- **Usage settings panel** — click the whale button at the bottom of the sidebar to open the "Little Whale · Usage" overlay and configure:
  - **Accounting (ledger)**: accumulate today's usage from the balance delta (auto-resets daily and appends to the history ledger).
  - **Real-time tokens**: compute today's usage from DeepSeek platform tokens in real time.
  - **App usage**: show local DSH session usage (today / last 7 days Tokens, sessions, messages, most-used model).

## 🖼️ Screenshots

<div align="center">
  <img src="./docs/screenshot-config.png" alt="Usage config panel" width="62%" />
</div>
<p align="center"><i>Usage config panel — usage mode / pricing / sounds / volume / peak times.</i></p>

<div align="center">
  <img src="./docs/screenshot-app-usage.png" alt="App usage dashboard" width="82%" />
</div>
<p align="center"><i>App-usage dashboard — tokens, sessions, messages, activity heatmap, top model.</i></p>

<div align="center">
  <img src="./docs/screenshot-peak-times.png" alt="Peak / off-peak time" width="62%" />
</div>
<p align="center"><i>Peak / off-peak pricing time periods (weekly).</i></p>

## 🚀 Install

> **Install as a normal package — do NOT link it via a junction.** A junction makes dependencies fail to resolve upward (e.g. `schemastery` / `react`) and desyncs the package name from `cordis.patch.yml`; both break DSH startup.

```sh
# Recommended — install from npm (published): https://www.npmjs.com/package/dsh-whale-usage
dsh plugin --profile web add dsh-whale-usage
# or: npm install dsh-whale-usage

# From source: this repo (or after cloning it on the target machine)
dsh plugin --profile web add <absolute path to this folder>

# Or install the built tarball
dsh plugin --profile web add <path>/dsh-whale-usage-0.1.4.tgz

# Or use the convenience scripts
bash scripts/install.sh                              # macOS / Linux / Git Bash
powershell -ExecutionPolicy Bypass -File scripts/install.ps1   # Windows
```

After installing, **restart DSH and hard-refresh the browser** (Cmd/Ctrl+Shift+R):

- the whale widget appears in the bottom-right corner;
- a "Little Whale · Usage" button appears at the bottom of the sidebar.

> Because this plugin **replaces** the original two, uninstall `dsh-whale-widget` and `dsh-usage-stats` only after confirming this plugin works:
> `dsh plugin --profile web remove dsh-whale-widget` · `dsh plugin --profile web remove dsh-usage-stats`

## ⚙️ Configuration

```yaml
config:
  indexConcurrency: 2      # usage engine concurrency for reading historical sessions
  cacheWriteDelayMs: 1000  # debounce before writing local stats
  apiPath: /usage-stats/v1 # app-usage API prefix
```

Data is stored locally:

- Whale accounting / config: `~/.dsh/.dshw-*.json`
- App-usage index: `$DSH_HOME/usage-stats`

## 🗂️ Repository structure

```
dsh-whale-usage/
├── lib/                # built plugin (host: index.js, usage-host.js, whale-host.js; client: client.js)
├── assets/             # whale images / sounds
├── cordis.patch.yml    # DSH bundle patch (plugin id dsh-whale-usage)
├── dsh.plugin.json     # DSH plugin manifest (id / version / main / client.main)
├── package.json        # npm package (name dsh-whale-usage, MIT)
├── LICENSE / CREDITS.md# MIT + upstream credits
├── README.md / README.zh.md
├── docs/               # dev notes (development.md) + screenshots
└── scripts/install.*   # one-click install scripts
```

## 🛠️ Development

See [`docs/development.md`](./docs/development.md) for architecture, building the tarball
(`npm pack`), and re-syncing upstream fixes (`lib/whale-host.js`, `lib/usage-host.js`).

## 📄 License & Credits

- **License**: [MIT](./LICENSE). The merged third-party source remains © its original authors — see [CREDITS.md](./CREDITS.md).
- This plugin is **self-contained**: it does not follow upstream automatically; re-sync fixes via `docs/development.md`.

---

*中文说明见 [`README.zh.md`](./README.zh.md)。*