Introduction¶

When developing DSH plugins, a common requirement arises: I want to know how many tokens each local session consumes per day, and also take a look at the remaining DeepSeek balance. This data is scattered in local session logs, so usually, you have to open the terminal, browse through files, and write scripts to piece together a daily summary.

dsh-usage-monitor is designed for this pain point: it does not replace any statistical commands; it only parses session logs into a daily summary and adds a balance card. Below is an introduction to its features, installation methods, data flow, and limitations.

What is it¶

• Maintainer: Alvin-Sun6612
• Repository: https://github.com/Alvin-Sun6612/dsh-usage-monitor
• Directory Page: https://www.skillhub.cn/plugins/Alvin-Sun6612/dsh-usage-monitor
• Positioning: DSH (DeepSeek Harness) client plugin, opening a “Usage & Balance” panel in the sidebar

It solves two things:

1. Count local session token usage by day, with four windows: Today, Last 7 days, Last 30 days, and Total.
2. Display the DeepSeek account balance, but you need to paste the API Key into the panel yourself.

Core Features¶

Below are the capabilities verified in the README, listed item by item.

1. Usage Windows: Today / Last 7 days / Last 30 days / Total. Each window provides total tokens, number of calls, and cache hit rate.
2. Today Details: Uncached input, cache hit, and output.
3. Last 30 days bar chart with hover to see daily values.
4. Balance card: Requires a DeepSeek API Key; paste it into the panel. The Key is stored locally.
5. Panel name and description provide both Chinese and English locales.

Regarding the balance, the README explicitly states a constraint that is easy to trip over: the balance endpoint /user/balance only recognizes the API Key (sk-...). If you are only logged into DeepSeek via DSH without a Key, the panel will display “API Key not configured”. The usage statistics themselves do not require a Key.

Installation and Enablement¶

The README provides three installation paths; choose based on your scenario. The installation commands are copied verbatim from the README without manual concatenation.

Method 1: Local Directory (for Development)¶

powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
# or specify profile: -Profile web

After installation, you need to restart DSH for the “Usage & Balance” entry to appear in the sidebar. This path assumes you have pulled the repository locally and is suitable for the stage of modifying the source code.

Method 2: Install tgz from Release¶

This is the recommended path indicated in the README; it does not require git or npm:

# Install Release attachment directly (Recommended)
dsh plugin --profile desktop add "https://github.com/Alvin-Sun6612/dsh-usage-monitor/releases/download/v0.1.0/dsh-usage-monitor-0.1.0.tgz"

# When you have a tgz file locally
dsh plugin --profile desktop add .\dsh-usage-monitor-0.1.0.tgz

# Can also use GitHub direct install when repository has git (pnpm uses git, requires allowBuilds authorization)
dsh plugin --profile desktop add github:Alvin-Sun6612/dsh-usage-monitor

After installation, you also need to restart DSH. The uninstall command:

dsh plugin --profile desktop remove dsh-usage-monitor

Note that the profile is fixed to desktop. If you cannot see the entry after installation, the README suggests checking if dsh.profile.bundles in ~/.dsh/profiles/desktop/package.json contains dsh-usage-monitor.

What it reads and sends¶

This part determines the extent to which you are willing to trust it. The README provides a table; the key points are recorded below.

When the port is occupied, you can change the port at the bottom of the panel (the browser remembers the setting), or directly write it in ~/.dsh/dsh-usage-monitor.json:

{"port": 46851}

Typical Usage¶

Host Half Verification¶

The README provides a standalone self-test path. index.js is the Host half, responsible for parsing zstd logs, proxying the balance, and starting the local HTTP service; it does not depend on the DSH runtime and can run directly:

node index.js
# http://127.0.0.1:46850/health
# http://127.0.0.1:46850/summary?days=30
# http://127.0.0.1:46850/balance

• /health: Whether the service is alive.
• /summary?days=30: Usage summary.
• /balance: Balance, returns “not configured” status if no Key is set.

/summary return structure (excerpt from README):

{
  "sessions": 22, "scanned": 22, "parsed": 22, "scanMs": 465,
  "today":  { "requests": 525, "totalTokens": 43301332, "cacheHitRate": 0.982 },
  "last7":  { "...": "same structure as above" },
  "last30": { "...": "same structure as above" },
  "allTime":{ "...": "same structure as above" },
  "series": [{ "date": "2026-11-05", "totalTokens": 43301332 }]
}

Browser Half Contract Tests¶

After modifying the panel logic, the README suggests running a 19-item contract test to cover the rendering and interaction of the Browser half:

node test/smoke.mjs

Version and Release¶

The version in package.json is 0.1.0, and the license is MIT. The README also provides several release paths; here I will only remind you of two points: you need to npm login before npm publish, and repository must exist in package.json; if publishing a tgz directly, use pnpm pack, which produces dsh-usage-monitor-0.1.0.tgz.

Directory Structure¶

dsh-usage-monitor/
├─ package.json          # dsh.bundle + dsh.client declarations, exports four items
├─ cordis.patch.yml      # Bundle patch: insert id=usage-monitor
├─ index.js              # Host half: parses zstd session logs + balance proxy + local HTTP service
├─ client.js             # Browser half: sidebar panel (no build, React.createElement)
├─ locale/{zh,en}.json   # Panel name and description
├─ icon.svg / icon.png   # Icons
├─ install.ps1           # One-click install (UTF-8 BOM)
└─ test/smoke.mjs        # Contract test: node test/smoke.mjs

The two parts are separated: index.js runs in the local process, client.js runs in the browser sidebar, connected by the local read-only HTTP service 127.0.0.1:46850. When you want to modify functionality, client.js is the panel side, and index.js is the data side.

Customization and Publishing¶

If you want to rename it or swap in your own functionality, the README provides four steps: modify package.json (keep dsh.bundle.patch); align the id and name in cordis.patch.yml with the package name; in client.js, it is recommended to change NS, PANEL_ID, PORT_KEY, and the CSS prefix dsh-um-* together to avoid conflicts with other plugins; meta.title / meta.description in locale/*.json are the market card copy.

When publishing to the DSH Plugin Market (dshmarket), the README conclusion is very clear: Do not submit a PR to the dsh-market repository, and do not manually modify README / plugins.json / index.json, as they are generated by CI. The only action is to submit a new file data/plugins/Alvin-Sun6612__dsh-usage-monitor.yml to https://github.com/awesome-dsh-plugin/awesome-dsh-plugin, using category: usage. The market entry for this plugin is already prepared and located at data/plugins/Alvin-Sun6612__dsh-usage-monitor.yml in the repository.

One of the prerequisites is to push the directory contents to the root of your own GitHub repository, wait for the repository to be created for 1 day, and add the dsh-plugin topic. After merging, the market will be automatically rebuilt, and it can usually be found within a day.

FAQ¶

The following are the faults and solutions listed in the README; I have selected the four most common ones.

There is also an environmental pitfall: PowerShell 5.1 requires adding -Encoding UTF8 to read files, and .ps1 files must be saved as UTF-8 with BOM.

Applicable Scenarios and Notes¶

Suitable for these people and scenarios:

• Want to see local token trends by day and by window, rather than just the instantaneous numbers of single calls.
• Want to keep an eye on the DeepSeek balance conveniently without opening a browser to log into the console.
• Need to make DSH plugins and want a minimal reference structure for a Host half + Browser half.

Points to note:

1. The plugin runs with the permissions of the current DSH process. Before installing, you should read the source code and LICENSE (MIT) to confirm that the permissions to access ~/.dsh/sessions/ and ~/.dsh/dsh-usage-monitor.json are acceptable to you.
2. Usage statistics are local in scope, covering only session logs under ~/.dsh/sessions/; it does not provide a global view across multiple machines or workspaces.
3. Balance is the result of the plugin forwarding api.deepseek.com/user/balance; the Key is only stored locally, and the panel does not echo it.
4. The default port of the local service is fixed at 46850; you only need to change it if it is occupied.

Conclusion¶

The value of dsh-usage-monitor lies in bringing “usage statistics” and “balance” into the sidebar—two operational-level tasks—separating the Host half (runs offline) from the Browser half (does the display), with a clean separation of responsibilities. The directory page is at https://www.skillhub.cn/plugins/Alvin-Sun6612/dsh-usage-monitor, and the source code is at https://github.com/Alvin-Sun6612/dsh-usage-monitor.