@feiyang666/dsh-usage-plugin 1.9.0 → 1.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +2 -2
- package/README.md +103 -117
- package/README.zh.md +258 -0
- package/package.json +2 -2
- package/README.en.md +0 -272
package/CHANGELOG.md
CHANGED
|
@@ -8,9 +8,9 @@
|
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## v1.9.1 (2026-08-16)
|
|
12
12
|
|
|
13
|
-
-
|
|
13
|
+
- **文档**: README 改为英文优先（`README.md` 英文 + 新增 `README.zh.md` 中文）；补充「npm 包名已更换」醒目通知（旧包名 `@feiyang666/deepseekharnessdesktop` → 新包名 `@feiyang666/dsh-usage-plugin`），并移除发布教程等无关内容；修正 tarball 测试命令为新包名文件名。
|
|
14
14
|
|
|
15
15
|
---
|
|
16
16
|
|
package/README.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
# DeepSeek Harness
|
|
3
|
+
# DeepSeek Harness Usage & Cost Tracker (dsh-usage-plugin)
|
|
4
4
|
|
|
5
|
-
[
|
|
5
|
+
**English** · [简体中文](./README.zh.md)
|
|
6
6
|
|
|
7
7
|
[GitHub](https://github.com/feiyang-dev/dsh-usage-plugin) · [npm](https://www.npmjs.com/package/@feiyang666/dsh-usage-plugin) · MIT License
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
**A community plugin for DeepSeek Harness** — records token usage and cost for every model call, with peak/off-peak billing, balance query, a calendar heatmap, and CSV / JSON / PNG export.
|
|
10
10
|
|
|
11
11
|
|
|
12
12
|
|
|
@@ -16,129 +16,129 @@
|
|
|
16
16
|
|
|
17
17
|
---
|
|
18
18
|
|
|
19
|
-
> ## 🔔
|
|
19
|
+
> ## 🔔 Important Notice (2026-08-16): npm package renamed
|
|
20
20
|
>
|
|
21
|
-
>
|
|
21
|
+
> The **npm package has been renamed from `@feiyang666/deepseekharnessdesktop` to `@feiyang666/dsh-usage-plugin`** (matching the GitHub repo `feiyang-dev/dsh-usage-plugin`).
|
|
22
22
|
>
|
|
23
|
-
> -
|
|
24
|
-
> -
|
|
25
|
-
> -
|
|
23
|
+
> - Use the new package name for install / upgrade: `dsh plugin --profile web add @feiyang666/dsh-usage-plugin`
|
|
24
|
+
> - The old package `@feiyang666/deepseekharnessdesktop` remains published for a while, but it is **no longer maintained and will not receive updates** — please migrate soon.
|
|
25
|
+
> - The desktop client ([`DeepSeek Harness Desktop`](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop)) supports both package names and will auto-detect old-name installs with a **one-click update** to the new name.
|
|
26
26
|
|
|
27
27
|
---
|
|
28
28
|
|
|
29
|
-
##
|
|
29
|
+
## Overview
|
|
30
30
|
|
|
31
|
-
dsh-usage-plugin
|
|
31
|
+
dsh-usage-plugin is a **usage & cost tracker** plugin in the DeepSeek Harness ecosystem (a DSH plugin shipped as a Host + Client two-in-one package). After installation, **"Usage & Cost"** and **"Balance Query"** tabs appear in the Web UI, right after "Conversation" and "Trace":
|
|
32
32
|
|
|
33
|
-
>
|
|
33
|
+
> Supports **Windows / macOS / Linux**: paths are handled per platform (`node:path`), and the folder picker / "reveal in file manager" use each OS's native mechanism (macOS: `osascript` / `open`; Linux: `zenity` / `xdg-open`). Balance query and export do not depend on Windows-only commands.
|
|
34
34
|
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
-
|
|
42
|
-
-
|
|
43
|
-
-
|
|
35
|
+
- **Usage & Cost**: records each model call's token usage and cache hits (input miss / cache hit / cache write / output / reasoning / finish reason), and computes cost using DeepSeek's peak/valley or base pricing (peak hours are automatically priced by Beijing time 09:00–12:00 and 14:00–18:00). Model names come from the actual request parameters, so non-DeepSeek models are shown truthfully instead of "unknown model"; models without an official price are counted as 0. The overview shows a by-model table plus a by-API-provider × model drill-down (each provider grouped with every model's calls and peak/off-peak cost split) and a grand total row.
|
|
36
|
+
- **Usage Calendar**: a monthly daily-usage heatmap (colored by cost or call count), hover for details including the peak/off-peak cost split, click a day for its call list and peak/off-peak totals, plus a per-day statistics table with peak cost / off-peak cost / total columns and monthly rollups.
|
|
37
|
+
- **Cache Hit List**: newest-first, fully scrollable, with quick filters (Today / 7 days / 30 days / All) and custom date ranges; the summary line and footer total split peak vs off-peak consumption with a grand cost total. The list is paginated (100 rows per page), so it stays smooth even with large data volumes.
|
|
38
|
+
- **Price Table**: the official DeepSeek API price table — base and peak/valley unit prices shown side by side (peak vs off-peak), editable in-panel and persisted to `pricing.json`, with a reset-to-default option.
|
|
39
|
+
- **Balance Query**: queries your DeepSeek account balance using the configured `DEEPSEEK_API_KEY`.
|
|
40
|
+
- **Export**: CSV / JSON / **PNG long image** (newest-first, up to the latest 2000 records, warns if exceeded; the PNG report includes peak/off-peak cost columns), to any directory (native picker), auto-opens the folder after export.
|
|
41
|
+
- **Import**: merge-imports JSON / CSV files, deduplicated by time.
|
|
42
|
+
- **Persistence**: records are written live to `<session workspace>/dsh-usage/usage-records.json` and restored on restart (cap 100000 records).
|
|
43
|
+
- **UI adaptation**: panel typography scales with the app's display-size setting (em-relative fonts); table wrapping and spacing are tuned so large display sizes stay readable.
|
|
44
44
|
|
|
45
45
|
---
|
|
46
46
|
|
|
47
|
-
##
|
|
47
|
+
## Screenshots
|
|
48
48
|
|
|
49
|
-
###
|
|
50
|
-
|
|
51
51
|
|
|
52
|
-
###
|
|
53
|
-
|
|
54
54
|
|
|
55
|
-
##
|
|
55
|
+
## Recommended Installation
|
|
56
56
|
|
|
57
|
-
>
|
|
57
|
+
> Either method works and is equivalent. **We recommend the desktop app** — fully graphical, no command line needed.
|
|
58
58
|
|
|
59
|
-
###
|
|
59
|
+
### Option 1 (recommended): One-click via the desktop app
|
|
60
60
|
|
|
61
|
-
|
|
61
|
+
Install [DeepSeek Harness Desktop](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop), open it, then go to **"Install Plugins" → Recommended → Usage & Cost Tracker → Install** and click **"Restart Service Now"** to activate.
|
|
62
62
|
|
|
63
|
-
###
|
|
63
|
+
### Option 2: Command line
|
|
64
64
|
|
|
65
65
|
```bash
|
|
66
|
-
#
|
|
66
|
+
# Prerequisite: install dsh (npm install -g @deepseek-ai/dsh)
|
|
67
67
|
dsh plugin --profile web add @feiyang666/dsh-usage-plugin
|
|
68
68
|
```
|
|
69
69
|
|
|
70
|
-
|
|
70
|
+
Or install to another profile:
|
|
71
71
|
|
|
72
72
|
```bash
|
|
73
73
|
dsh plugin --profile web add @feiyang666/dsh-usage-plugin
|
|
74
74
|
dsh plugin --profile headless add @feiyang666/dsh-usage-plugin
|
|
75
75
|
```
|
|
76
76
|
|
|
77
|
-
|
|
77
|
+
Restart the dsh web service after installation. Detailed manual install / wiring / uninstall / troubleshooting follows below.
|
|
78
78
|
|
|
79
79
|
---
|
|
80
80
|
|
|
81
|
-
##
|
|
81
|
+
## What's in the package
|
|
82
82
|
|
|
83
|
-
|
|
83
|
+
One npm package = a **host half** (Node-side Cordis plugin: recording, billing, balance query, export — see `lib/index.js`) + a **client half** (browser-side panel — see `lib/client.js`, which talks to the host via `/usage/api`).
|
|
84
84
|
|
|
85
|
-
|
|
85
|
+
The package integrates with DSH through two declarations:
|
|
86
86
|
|
|
87
|
-
|
|
|
87
|
+
| Declaration | Purpose |
|
|
88
88
|
| --- | --- |
|
|
89
|
-
| `dsh.bundle.patch
|
|
90
|
-
| `dsh.client` + `exports["./client"]` |
|
|
89
|
+
| `dsh.bundle.patch` (`cordis.patch.yml`) | Lets DSH recognize it as a **standard bundle plugin package**: `dsh plugin --profile <name> add <package>` installs and wires it in one command, no manual config editing |
|
|
90
|
+
| `dsh.client` + `exports["./client"]` | Lets the web client auto-load the browser panel at `/plugins/<package>/client.js` |
|
|
91
91
|
|
|
92
|
-
|
|
92
|
+
So for users, **installation is one command** — no YAML editing, no manual file copying.
|
|
93
93
|
|
|
94
94
|
---
|
|
95
95
|
|
|
96
|
-
##
|
|
96
|
+
## Installation (for users)
|
|
97
97
|
|
|
98
|
-
### 0.
|
|
98
|
+
### 0. Prerequisites
|
|
99
99
|
|
|
100
|
-
-
|
|
101
|
-
-
|
|
102
|
-
-
|
|
100
|
+
- DeepSeek Harness installed (`npm install -g @deepseek-ai/dsh`, or a desktop app built on it, or `npx @deepseek-ai/dsh web`).
|
|
101
|
+
- Option A (recommended) needs **pnpm**: `npm install -g pnpm` (or `corepack enable`).
|
|
102
|
+
- Make sure `dsh` is on PATH (for the desktop app, run in its bundled terminal).
|
|
103
103
|
|
|
104
|
-
### 1.
|
|
104
|
+
### 1. Method A (recommended): one command
|
|
105
105
|
|
|
106
106
|
```bash
|
|
107
107
|
dsh plugin --profile web add @feiyang666/dsh-usage-plugin
|
|
108
108
|
```
|
|
109
109
|
|
|
110
|
-
|
|
110
|
+
This does three things (all automatic):
|
|
111
111
|
|
|
112
|
-
1.
|
|
113
|
-
2.
|
|
114
|
-
3.
|
|
112
|
+
1. Installs the package via pnpm into `~/.dsh/profiles/web` (auto-initializes the profile on first use);
|
|
113
|
+
2. Detects the package's `dsh.bundle` declaration and writes the package name into the profile's `dsh.profile.bundles` layer list;
|
|
114
|
+
3. After restart, DSH reads the package's `cordis.patch.yml` and mounts the plugin row into the app tree — **no manual config editing**.
|
|
115
115
|
|
|
116
|
-
|
|
116
|
+
Same for other profiles (replace `web` with your profile name, e.g. `dsh plugin --profile headless add ...`; `dsh web` equals `dsh --profile web`).
|
|
117
117
|
|
|
118
|
-
>
|
|
118
|
+
> Test a local tarball: `dsh plugin --profile web add C:\path\to\feiyang666-dsh-usage-plugin-1.9.0.tgz`
|
|
119
119
|
|
|
120
|
-
### 2.
|
|
120
|
+
### 2. Method B: manual install (no pnpm / no `dsh plugin`)
|
|
121
121
|
|
|
122
|
-
|
|
122
|
+
Only for when you have no pnpm or want full manual control. **Do not `npm install` directly at `~/.dsh/profiles`** (that dir has no package.json; npm would treat the whole node_modules as residue and wipe it).
|
|
123
123
|
|
|
124
|
-
**B1.
|
|
124
|
+
**B1. Use pnpm but not `dsh plugin`:**
|
|
125
125
|
|
|
126
126
|
```bash
|
|
127
127
|
cd ~/.dsh/profiles/web
|
|
128
128
|
pnpm add @feiyang666/dsh-usage-plugin
|
|
129
|
-
#
|
|
129
|
+
# then manually append the plugin row to web/cordis.patch.yml (see B3) and restart
|
|
130
130
|
```
|
|
131
131
|
|
|
132
|
-
**B2.
|
|
132
|
+
**B2. Or use npm:** add a minimal package.json to the profile first, then install:
|
|
133
133
|
|
|
134
134
|
```bash
|
|
135
135
|
cd ~/.dsh/profiles/web
|
|
136
|
-
#
|
|
136
|
+
# if no package.json exists there yet (only after `dsh plugin` init):
|
|
137
137
|
# echo '{"name":"dsh-profile-web","private":true,"dependencies":{}}' > package.json
|
|
138
138
|
npm install @feiyang666/dsh-usage-plugin
|
|
139
139
|
```
|
|
140
140
|
|
|
141
|
-
**B3.
|
|
141
|
+
**B3. Wire it up (once, idempotent):** append to `~/.dsh/profiles/web/cordis.patch.yml`:
|
|
142
142
|
|
|
143
143
|
```yaml
|
|
144
144
|
- insert:
|
|
@@ -153,107 +153,93 @@ npm install @feiyang666/dsh-usage-plugin
|
|
|
153
153
|
- agents
|
|
154
154
|
```
|
|
155
155
|
|
|
156
|
-
|
|
156
|
+
Or just run the package's built-in wiring script (auto-finds the profile and appends, idempotent):
|
|
157
157
|
|
|
158
158
|
```bash
|
|
159
159
|
node node_modules/@feiyang666/dsh-usage-plugin/scripts/wire.js
|
|
160
160
|
```
|
|
161
161
|
|
|
162
|
-
> ⚠️
|
|
162
|
+
> ⚠️ The `inject` list is **required**: it makes Cordis wait until `fs` / `webServer` / `subprocess` / `credentials` / `sandboxPolicy` / `agents` are ready before activating the plugin. Without it the `/usage/api` route never registers and the panel fails with `Unexpected end of JSON input`.
|
|
163
163
|
|
|
164
|
-
### 3.
|
|
164
|
+
### 3. Method C: desktop app
|
|
165
165
|
|
|
166
|
-
|
|
166
|
+
The desktop app (e.g. [DeepSeek Harness Desktop](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop)) uses the same `~/.dsh/profiles` underneath. Run Method A's command in any terminal, restart the app, and the plugin activates automatically (the app starts the same `dsh web`).
|
|
167
167
|
|
|
168
|
-
### 4.
|
|
168
|
+
### 4. Restart and verify
|
|
169
169
|
|
|
170
|
-
|
|
170
|
+
Restart the DeepSeek Harness web app (command line: kill the old process and re-run `dsh web`; desktop: fully quit and reopen). Then:
|
|
171
171
|
|
|
172
|
-
-
|
|
173
|
-
-
|
|
174
|
-
-
|
|
172
|
+
- Refresh http://127.0.0.1:3080 — after "Conversation" and "Trace", you should see **"Usage & Cost"** and **"Balance Query"** tabs; there are entries in Settings too.
|
|
173
|
+
- The "Usage & Cost" panel contains **Overview / Usage Calendar / Cache Hit List / Price Table** subtabs.
|
|
174
|
+
- Send a message and the "Usage & Cost" panel should show this call's token / cost record.
|
|
175
175
|
|
|
176
|
-
### 5.
|
|
176
|
+
### 5. Configuration (for balance query)
|
|
177
177
|
|
|
178
|
-
|
|
178
|
+
"Balance Query" uses the configured `DEEPSEEK_API_KEY`: set the API Key in **Settings → Models** (same key used for chats), then open the "Balance Query" tab and click "Query Balance".
|
|
179
179
|
|
|
180
180
|
---
|
|
181
181
|
|
|
182
|
-
##
|
|
182
|
+
## Uninstall
|
|
183
183
|
|
|
184
184
|
```bash
|
|
185
185
|
dsh plugin --profile web remove @feiyang666/dsh-usage-plugin
|
|
186
186
|
```
|
|
187
187
|
|
|
188
|
-
|
|
188
|
+
(Equivalent to pnpm remove; `dsh plugin` auto-removes the package name from the `dsh.profile.bundles` layer list.) Restart the app afterward.
|
|
189
189
|
|
|
190
|
-
|
|
190
|
+
For manual installs (Method B), do it in reverse: remove the `usage-plugin` row from `cordis.patch.yml`, then `pnpm remove` / `npm uninstall` the package, and restart.
|
|
191
191
|
|
|
192
|
-
>
|
|
192
|
+
> Upgrading from a 1.0.x manual-wiring install to 1.1.x: first remove the old `usage-plugin` row from `cordis.patch.yml` (or follow the uninstall flow), then reinstall via Method A to avoid mounting the plugin twice.
|
|
193
193
|
|
|
194
194
|
---
|
|
195
195
|
|
|
196
|
-
##
|
|
196
|
+
## Data & locations
|
|
197
197
|
|
|
198
|
-
-
|
|
199
|
-
-
|
|
200
|
-
-
|
|
201
|
-
-
|
|
202
|
-
-
|
|
198
|
+
- Records: `<session workspace>/dsh-usage/usage-records.json`
|
|
199
|
+
- Price config (edited & saved in the panel): `<session workspace>/dsh-usage/pricing.json`
|
|
200
|
+
- Default export dir: `<session workspace>/dsh-usage/{csv,json,images}/`
|
|
201
|
+
- Custom export dir: set in the panel's "Export target directory" or click "Choose directory…"
|
|
202
|
+
- Startup diagnostics (if the plugin fails to activate): `dsh-usage-boot.log` in the session workspace
|
|
203
203
|
|
|
204
204
|
---
|
|
205
205
|
|
|
206
|
-
##
|
|
206
|
+
## FAQ
|
|
207
207
|
|
|
208
|
-
|
|
|
208
|
+
| Symptom | Cause / Fix |
|
|
209
209
|
| --- | --- |
|
|
210
|
-
|
|
|
211
|
-
|
|
|
212
|
-
|
|
|
213
|
-
|
|
|
214
|
-
| `dsh plugin`
|
|
215
|
-
|
|
|
216
|
-
|
|
|
210
|
+
| Panel reports `Unexpected end of JSON input` | The plugin row is missing the `inject` list, so the route isn't registered. Add the inject list per Method B3 and restart |
|
|
211
|
+
| Panel blank / no top tab | Plugin not activated. Check `dsh-usage-boot.log`; confirm the `cordis.patch.yml` row exists with the correct `name` |
|
|
212
|
+
| Balance query fails with "DEEPSEEK_API_KEY not configured" | Set the API Key in Settings → Models |
|
|
213
|
+
| Balance query network error | Ensure `api.deepseek.com` is reachable (configure a proxy if needed) |
|
|
214
|
+
| `dsh plugin` reports pnpm not found | Install pnpm: `npm install -g pnpm` |
|
|
215
|
+
| Install can't reach the npm registry | Set a mirror: `npm config set registry https://registry.npmmirror.com` (or `pnpm config set registry ...`) and retry |
|
|
216
|
+
| After uninstall, still reports `Cannot find package '@feiyang666/...'` | A package reference remains in the profile. Remove the corresponding row from `cordis.patch.yml` and the package name from `dsh.profile.bundles`, then restart |
|
|
217
217
|
|
|
218
218
|
---
|
|
219
219
|
|
|
220
|
-
##
|
|
220
|
+
## Related Projects
|
|
221
221
|
|
|
222
|
-
|
|
223
|
-
npm login # 用你自己的 npm 账号
|
|
224
|
-
npm run check # 发布前自检（prepublishOnly 也会自动跑）
|
|
225
|
-
npm pack # 检查 tarball 内容
|
|
226
|
-
npm publish --access public # 作用域包必须 --access public
|
|
227
|
-
```
|
|
228
|
-
|
|
229
|
-
> 发布到公共 npm 会公开源码，请确认包内无敏感信息（API Key 等只在运行时由用户配置）。
|
|
230
|
-
> 本机网络若连不上 `registry.npmjs.org`，发布前用 `npm config set registry https://registry.npmjs.org`（包内 `.npmrc` 已预置该 registry）。
|
|
231
|
-
|
|
232
|
-
---
|
|
233
|
-
|
|
234
|
-
## 相关项目
|
|
235
|
-
|
|
236
|
-
| 项目 | 说明 | 安装方式 |
|
|
222
|
+
| Project | Description | Installation |
|
|
237
223
|
| --- | --- | --- |
|
|
238
|
-
| [DeepSeek Harness
|
|
239
|
-
| [
|
|
240
|
-
| [DeepSeek-Harness](https://github.com/deepseek-ai/DeepSeek-Harness) |
|
|
224
|
+
| [DeepSeek Harness Desktop](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop) | Windows desktop console: install/start/stop/restart the dsh web service with one click, built-in plugin management — **install this plugin from its Recommended section** | Download the desktop app and click a few buttons |
|
|
225
|
+
| [Data Vault (dsh-vault)](https://github.com/feiyang-dev/dsh-vault) | Auto backup / wipe detection / one-click restore — protects chat history and workspace data | One-click from the desktop app, or `dsh plugin add @feiyang666/dsh-vault` |
|
|
226
|
+
| [DeepSeek-Harness](https://github.com/deepseek-ai/DeepSeek-Harness) | Official CLI / Web service | Quick start below |
|
|
241
227
|
|
|
242
|
-
###
|
|
228
|
+
### Running DeepSeek Harness
|
|
243
229
|
|
|
244
|
-
|
|
230
|
+
**Quick start (via npm)**
|
|
245
231
|
|
|
246
|
-
|
|
232
|
+
Install Node.js, then run:
|
|
247
233
|
|
|
248
234
|
```bash
|
|
249
235
|
npx @deepseek-ai/dsh web
|
|
250
236
|
```
|
|
251
237
|
|
|
252
|
-
|
|
238
|
+
This command starts the Web UI at the default address http://127.0.0.1:3080. See the [Web UI Guide](https://github.com/deepseek-ai/DeepSeek-Harness) for details.
|
|
253
239
|
|
|
254
|
-
|
|
240
|
+
**Run from source**
|
|
255
241
|
|
|
256
|
-
|
|
242
|
+
To run from the repository source:
|
|
257
243
|
|
|
258
244
|
```bash
|
|
259
245
|
git clone https://github.com/deepseek-ai/deepseek-harness.git
|
|
@@ -263,10 +249,10 @@ pnpm run build
|
|
|
263
249
|
pnpm dsh web
|
|
264
250
|
```
|
|
265
251
|
|
|
266
|
-
##
|
|
252
|
+
## Acknowledgements
|
|
267
253
|
|
|
268
|
-
- **[@liu3734](https://github.com/liu3734)
|
|
254
|
+
- **[@liu3734](https://github.com/liu3734)**: reported and diagnosed the Windows-only path handling / spawn issues on macOS (POSIX) and proposed the cross-platform fix ([#1](https://github.com/feiyang-dev/dsh-usage-plugin/issues/1)).
|
|
269
255
|
|
|
270
|
-
##
|
|
256
|
+
## License
|
|
271
257
|
|
|
272
258
|
MIT © dsh-usage-plugin
|
package/README.zh.md
ADDED
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# DeepSeek Harness 用量与消耗插件（dsh-usage-plugin）
|
|
4
|
+
|
|
5
|
+
[English](./README.md) | **简体中文**
|
|
6
|
+
|
|
7
|
+
[GitHub](https://github.com/feiyang-dev/dsh-usage-plugin) · [npm](https://www.npmjs.com/package/@feiyang666/dsh-usage-plugin) · MIT License
|
|
8
|
+
|
|
9
|
+
**由开发者制作的 DeepSeek Harness 插件** —— 记录每一次模型调用的 token 用量与消耗，支持峰谷计费、余额查询、日历热力图与 CSV / JSON / PNG 导出。
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
</div>
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
> ## 🔔 重要通知（2026-08-16）：npm 包名已更换
|
|
20
|
+
>
|
|
21
|
+
> 本插件的 **npm 包名已由 `@feiyang666/deepseekharnessdesktop` 更名为 `@feiyang666/dsh-usage-plugin`**（与 GitHub 仓库名 `feiyang-dev/dsh-usage-plugin` 保持一致）。
|
|
22
|
+
>
|
|
23
|
+
> - 安装 / 升级请使用新包名：`dsh plugin --profile web add @feiyang666/dsh-usage-plugin`
|
|
24
|
+
> - 旧包名 `@feiyang666/deepseekharnessdesktop` 仍会保留一段时间，但**不再维护、不会更新**，请尽快迁移
|
|
25
|
+
> - 桌面端（[`DeepSeek Harness 桌面版`](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop)）已兼容两种包名，旧包名安装的会自动识别并支持「一键更新」迁移到新包名
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## 简介
|
|
30
|
+
|
|
31
|
+
dsh-usage-plugin 是 DeepSeek Harness 生态的**用量与消耗统计插件**（DSH plugin，Host + Client 双面一体包）。装好后在 WebUI 顶部「对话」「轨迹」之后会出现 **「用量与消耗」** 与 **「剩余余额查询」** 两个 tab：
|
|
32
|
+
|
|
33
|
+
> 支持 **Windows / macOS / Linux**：路径按当前平台处理（`node:path`），目录选择与「打开所在目录」均调用系统原生方式（macOS 用 `osascript` / `open`，Linux 用 `zenity` / `xdg-open`），余额查询与导出不依赖 Windows 专用命令。
|
|
34
|
+
|
|
35
|
+
- **用量与消耗**：记录每次模型调用的 token 用量与缓存命中（输入·未命中 / 缓存命中 / 缓存写入 / 输出 / 推理 / 结束原因），按 DeepSeek 峰谷/基础价格计算消耗（高峰时段自动按北京时间 9:00–12:00、14:00–18:00 计价）。模型名以请求参数为准如实显示（非 DeepSeek 模型不再显示为「未知模型」，无官方价格的模型消耗按 0 统计）。概览含「按模型」表与「按 API 服务商 × 模型」明细表（每个服务商一组，组内列出各模型的调用与高峰/空闲分列消耗），底部有总费用合计。
|
|
36
|
+
- **用量日历**：按月查看每日用量热力图（按消耗或调用数着色），悬停查看详情（含高峰 / 空闲消耗拆分）、点击某天查看当日调用明细与高峰/空闲消耗统计，附本月每日统计表（高峰消耗 / 空闲消耗 / 总消耗分列）与月度汇总。
|
|
37
|
+
- **缓存命中列表**：最新记录排在最前，支持 今天 / 近7天 / 近30天 / 全部 快捷筛选与自定义起止日期区间，汇总行与表尾合计区分高峰消耗 / 空闲消耗 / 总费用合计；列表分页渲染（每页 100 条），记录量大也不卡顿。
|
|
38
|
+
- **价格表**：**DeepSeek 官方 API 价格表**，展示基础价与峰谷价（高峰/空闲）单价表，高峰价与空闲价分列展示，支持在面板内直接编辑价格并持久化（数据目录 `pricing.json`），也可一键恢复默认。
|
|
39
|
+
- **剩余余额查询**：用当前配置的 `DEEPSEEK_API_KEY` 查询 DeepSeek 账户余额。
|
|
40
|
+
- **导出**：CSV / JSON / **PNG 长图**（按最新在前展示，最多含最近 2000 条，超出会提示；PNG 报告含高峰 / 空闲消耗分列统计），可导出到任意目录（原生目录选择器），导出后自动打开所在目录。
|
|
41
|
+
- **导入**：选择文件（JSON / CSV）合并导入，按时间去重。
|
|
42
|
+
- **持久化**：记录实时落盘到 `<会话工作区>/dsh-usage/usage-records.json`，重启自动恢复（上限 100000 条，尽量多存）。
|
|
43
|
+
- **界面适配**：面板字号跟随应用「显示大小」设置自动缩放（em 相对字号），面板宽度以视口封顶、宽表格在容器内横向滑动（max-content + overflow-x），任何窗口大小下所有列与合计都完整可见，不会裁掉右侧内容。
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## 界面预览
|
|
48
|
+
|
|
49
|
+
### 用量与消耗
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
### 剩余余额查询
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
## 推荐安装方式
|
|
56
|
+
|
|
57
|
+
> 两个方法任选其一，效果等价。**推荐使用桌面端**，全程图形化、无需命令行。
|
|
58
|
+
|
|
59
|
+
### 方式一（推荐）：桌面端一键安装
|
|
60
|
+
|
|
61
|
+
安装 [DeepSeek Harness 桌面版](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop)，打开后点击 **「安装插件」→ 推荐插件 → 用量与消耗插件 → 一键安装**，完成后点 **「立即重启服务」** 即可生效。
|
|
62
|
+
|
|
63
|
+
### 方式二：命令行安装
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
# 前提：已安装 dsh（npm install -g @deepseek-ai/dsh）
|
|
67
|
+
dsh plugin --profile web add @feiyang666/dsh-usage-plugin
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
也可对其它 profile 安装：
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
dsh plugin --profile web add @feiyang666/dsh-usage-plugin
|
|
74
|
+
dsh plugin --profile headless add @feiyang666/dsh-usage-plugin
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
装完重启 dsh web 服务即可。详细的手动安装 / 接线 / 卸载 / 排障说明见下方。
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## 这个包是什么
|
|
82
|
+
|
|
83
|
+
一个 npm 包 = **host 半**（Node 侧 Cordis 插件，负责记录、计费、余额查询、导出，见 `lib/index.js`）+ **client 半**（浏览器侧面板，见 `lib/client.js`，通过 `/usage/api` 与 host 通信）。
|
|
84
|
+
|
|
85
|
+
包通过两处声明接入 DSH：
|
|
86
|
+
|
|
87
|
+
| 声明 | 作用 |
|
|
88
|
+
| --- | --- |
|
|
89
|
+
| `dsh.bundle.patch`（`cordis.patch.yml`） | 让 DSH 把它识别为**标准 bundle 插件包**：`dsh plugin --profile <名> add <包名>` 一条命令即可安装并自动接线，无需手改任何配置文件 |
|
|
90
|
+
| `dsh.client` + `exports["./client"]` | 让 web 客户端在 `/plugins/<包名>/client.js` 自动加载浏览器面板 |
|
|
91
|
+
|
|
92
|
+
所以对使用者来说，**安装就是一条命令**，不用碰 YAML、不用手动复制文件。
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## 安装（给使用者）
|
|
97
|
+
|
|
98
|
+
### 0. 前提条件
|
|
99
|
+
|
|
100
|
+
- 已安装 DeepSeek Harness（`npm install -g @deepseek-ai/dsh` 全局安装，或使用基于它的桌面应用 / `npx @deepseek-ai/dsh web`）。
|
|
101
|
+
- 安装方式 A（推荐）需要 **pnpm**：`npm install -g pnpm`（或 `corepack enable`）。
|
|
102
|
+
- 确保 `dsh` 命令在 PATH 里（桌面应用自带环境则在其终端中执行）。
|
|
103
|
+
|
|
104
|
+
### 1. 方法 A（推荐）：一条命令安装
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
dsh plugin --profile web add @feiyang666/dsh-usage-plugin
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
这条命令会做三件事（全部自动）：
|
|
111
|
+
|
|
112
|
+
1. 在 `~/.dsh/profiles/web` 里通过 pnpm 安装本包（首次使用会自动初始化该 profile）；
|
|
113
|
+
2. 检测到包的 `dsh.bundle` 声明，自动把包名写进 profile 的 `dsh.profile.bundles` 层列表；
|
|
114
|
+
3. 重启后，DSH 启动时会自动读取包内的 `cordis.patch.yml`，把插件行挂进应用树——**不需要**手动编辑任何配置文件。
|
|
115
|
+
|
|
116
|
+
其它 profile 同理，把 `web` 换成你的 profile 名即可（如 `dsh plugin --profile headless add ...`；`dsh web` 等价于 `dsh --profile web`）。
|
|
117
|
+
|
|
118
|
+
> 想用本地 tarball 测试：`dsh plugin --profile web add C:\path\to\feiyang666-dsh-usage-plugin-1.9.0.tgz`
|
|
119
|
+
|
|
120
|
+
### 2. 方法 B：手动安装（不使用 pnpm / 无 `dsh plugin`）
|
|
121
|
+
|
|
122
|
+
只在没有 pnpm 或需要完全手工控制时才用。请**不要在 `~/.dsh/profiles` 根目录直接 `npm install`**（该目录没有 package.json，npm 会把整个 node_modules 当残留清掉）。
|
|
123
|
+
|
|
124
|
+
**B1. 用 pnpm 但不用 `dsh plugin`：**
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
cd ~/.dsh/profiles/web
|
|
128
|
+
pnpm add @feiyang666/dsh-usage-plugin
|
|
129
|
+
# 然后手动把插件行加进 web/cordis.patch.yml（见 B3），再重启
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
**B2. 或用 npm：** 在 profile 目录先补一个最小 package.json 再装：
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
cd ~/.dsh/profiles/web
|
|
136
|
+
# 若该目录还没有 package.json（用 dsh plugin 初始化过才会有）：
|
|
137
|
+
# echo '{"name":"dsh-profile-web","private":true,"dependencies":{}}' > package.json
|
|
138
|
+
npm install @feiyang666/dsh-usage-plugin
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
**B3. 接线（只需做一次，幂等）：** 在 `~/.dsh/profiles/web/cordis.patch.yml` 末尾追加：
|
|
142
|
+
|
|
143
|
+
```yaml
|
|
144
|
+
- insert:
|
|
145
|
+
- id: usage-plugin
|
|
146
|
+
name: '@feiyang666/dsh-usage-plugin'
|
|
147
|
+
inject:
|
|
148
|
+
- fs
|
|
149
|
+
- webServer
|
|
150
|
+
- subprocess
|
|
151
|
+
- credentials
|
|
152
|
+
- sandboxPolicy
|
|
153
|
+
- agents
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
也可以直接跑包内的接线脚本（自动找 profile 并追加，幂等）：
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
node node_modules/@feiyang666/dsh-usage-plugin/scripts/wire.js
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
> ⚠️ 行上的 `inject` 列表**不能省略**：它让 Cordis 等到 `fs` / `webServer` / `subprocess` / `credentials` / `sandboxPolicy` / `agents` 服务就绪后再激活插件。缺了它，`/usage/api` 路由不会注册，面板会报 `Unexpected end of JSON input`。
|
|
163
|
+
|
|
164
|
+
### 3. 方法 C：桌面应用
|
|
165
|
+
|
|
166
|
+
桌面版（如 [DeepSeek Harness 桌面版](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop)）底层就是同一个 `~/.dsh/profiles`。在任意终端执行方法 A 的命令即可，装完重启应用；应用内启动的是同一个 `dsh web`，插件自动生效。
|
|
167
|
+
|
|
168
|
+
### 4. 重启并验证
|
|
169
|
+
|
|
170
|
+
重启 DeepSeek Harness 的 web 应用（命令行：结束旧进程后重新运行 `dsh web`；桌面应用：完全退出后重新打开）。然后：
|
|
171
|
+
|
|
172
|
+
- 刷新 http://127.0.0.1:3080 ，顶部「对话」「轨迹」之后会出现 **「用量与消耗」** 和 **「剩余余额查询」** 两个 tab；设置里也有对应入口。
|
|
173
|
+
- 「用量与消耗」面板内含 **概览 / 用量日历 / 缓存命中列表 / 价格表** 四个子页签。
|
|
174
|
+
- 发一条消息后，「用量与消耗」面板应出现本次调用的 token / 消耗记录。
|
|
175
|
+
|
|
176
|
+
### 5. 配置（余额查询需要）
|
|
177
|
+
|
|
178
|
+
「剩余余额查询」使用当前配置的 `DEEPSEEK_API_KEY`：在 **设置 → 模型** 中配置 API Key（与跑对话用的同一个 key），然后打开「剩余余额查询」tab 点「查询余额」。
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## 卸载
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
dsh plugin --profile web remove @feiyang666/dsh-usage-plugin
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
（等价于 pnpm remove；`dsh plugin` 会自动把包名从 `dsh.profile.bundles` 层列表里移除。）然后重启应用即可。
|
|
189
|
+
|
|
190
|
+
手工安装的（方法 B），反向操作：删除 `cordis.patch.yml` 里的 `usage-plugin` 行，再 `pnpm remove` / `npm uninstall` 该包，重启。
|
|
191
|
+
|
|
192
|
+
> 从 1.0.x 手工接线版升级到 1.1.x 时：先删掉旧 `cordis.patch.yml` 里的 `usage-plugin` 行（或整体按卸载流程走一遍），再按方法 A 重装，避免同一插件被挂载两次。
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## 数据与位置
|
|
197
|
+
|
|
198
|
+
- 数据文件：`<会话工作区>/dsh-usage/usage-records.json`
|
|
199
|
+
- 价格配置（面板内编辑后保存）：`<会话工作区>/dsh-usage/pricing.json`
|
|
200
|
+
- 导出目录（默认）：`<会话工作区>/dsh-usage/{csv,json,images}/`
|
|
201
|
+
- 自定义导出目录：在面板「导出目标目录」里填写或点「选择目录…」
|
|
202
|
+
- 启动诊断日志（若插件激活失败）：会话工作区下的 `dsh-usage-boot.log`
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## 常见问题
|
|
207
|
+
|
|
208
|
+
| 现象 | 原因 / 处理 |
|
|
209
|
+
| --- | --- |
|
|
210
|
+
| 面板报 `Unexpected end of JSON input` | 插件行缺少 `inject` 列表，路由未注册。按方法 B3 补上 inject 后重启 |
|
|
211
|
+
| 面板一直空白 / 顶部无 tab | 插件未激活。看会话工作区 `dsh-usage-boot.log`；确认 `cordis.patch.yml` 里的行存在且 `name` 正确 |
|
|
212
|
+
| 余额查询失败「未配置 DEEPSEEK_API_KEY」 | 在 设置 → 模型 里配置 API Key |
|
|
213
|
+
| 余额查询失败网络错误 | 确认能访问 `api.deepseek.com`（国内网络请配置代理） |
|
|
214
|
+
| `dsh plugin` 报 pnpm not found | 安装 pnpm：`npm install -g pnpm` |
|
|
215
|
+
| 安装时连不上 npm 官方源 | 配置镜像：`npm config set registry https://registry.npmmirror.com`（或对 pnpm 设 `pnpm config set registry ...`）后再执行安装命令 |
|
|
216
|
+
| 卸载后仍报 `Cannot find package '@feiyang666/...'` | profile 里残留了包引用。删掉 `cordis.patch.yml` 中对应行与 `dsh.profile.bundles` 里的包名，重启 |
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
## 相关项目
|
|
221
|
+
|
|
222
|
+
| 项目 | 说明 | 安装方式 |
|
|
223
|
+
| --- | --- | --- |
|
|
224
|
+
| [DeepSeek Harness 桌面版](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop) | Windows 桌面控制台：一键安装/启动/停止/重启 dsh web 服务，内置插件管理，**推荐插件区一键安装本插件** | 下载桌面版，点几下即可 |
|
|
225
|
+
| [数据保险箱（dsh-vault）](https://github.com/feiyang-dev/dsh-vault) | 自动备份 / 清空检测 / 一键恢复，保护聊天记录与工作区数据 | 桌面端一键安装，或 `dsh plugin add @feiyang666/dsh-vault` |
|
|
226
|
+
| [DeepSeek-Harness](https://github.com/deepseek-ai/DeepSeek-Harness) | 官方 CLI / Web 服务 | 见下方「运行 DeepSeek Harness」 |
|
|
227
|
+
|
|
228
|
+
### 运行 DeepSeek Harness
|
|
229
|
+
|
|
230
|
+
**快速安装（通过 npm）**
|
|
231
|
+
|
|
232
|
+
安装 Node.js，然后运行：
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
npx @deepseek-ai/dsh web
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
该命令会启动 Web UI，默认地址为 http://127.0.0.1:3080。详见 [Web UI 指南](https://github.com/deepseek-ai/DeepSeek-Harness)。
|
|
239
|
+
|
|
240
|
+
**从源码运行**
|
|
241
|
+
|
|
242
|
+
如需从仓库源码运行：
|
|
243
|
+
|
|
244
|
+
```bash
|
|
245
|
+
git clone https://github.com/deepseek-ai/deepseek-harness.git
|
|
246
|
+
cd deepseek-harness
|
|
247
|
+
pnpm install
|
|
248
|
+
pnpm run build
|
|
249
|
+
pnpm dsh web
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
## 致谢
|
|
253
|
+
|
|
254
|
+
- **[@liu3734](https://github.com/liu3734)**：报告并定位 macOS（POSIX）下路径处理与 spawn 的 Windows 专用问题，提出跨平台修复方案（[#1](https://github.com/feiyang-dev/dsh-usage-plugin/issues/1)）。
|
|
255
|
+
|
|
256
|
+
## 许可
|
|
257
|
+
|
|
258
|
+
MIT © dsh-usage-plugin
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@feiyang666/dsh-usage-plugin",
|
|
3
|
-
"version": "1.9.
|
|
3
|
+
"version": "1.9.1",
|
|
4
4
|
"description": "DeepSeek Harness usage & cost tracker plugin: per-call token/cache-hit stats, peak/off-peak billing, DeepSeek balance query, CSV/JSON/PNG export with custom destination, and persistent local storage. Ships a host half plus a web client half in one npm package; installs into a DSH profile as a dsh.bundle with one command (dsh plugin --profile web add @feiyang666/dsh-usage-plugin).",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"deepseek",
|
|
@@ -54,7 +54,7 @@
|
|
|
54
54
|
"scripts",
|
|
55
55
|
"cordis.patch.yml",
|
|
56
56
|
"README.md",
|
|
57
|
-
"README.
|
|
57
|
+
"README.zh.md",
|
|
58
58
|
"CHANGELOG.md"
|
|
59
59
|
],
|
|
60
60
|
"scripts": {
|
package/README.en.md
DELETED
|
@@ -1,272 +0,0 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
# DeepSeek Harness Usage & Cost Tracker (dsh-usage-plugin)
|
|
4
|
-
|
|
5
|
-
[简体中文](./README.md) · **English**
|
|
6
|
-
|
|
7
|
-
[GitHub](https://github.com/feiyang-dev/dsh-usage-plugin) · [npm](https://www.npmjs.com/package/@feiyang666/dsh-usage-plugin) · MIT License
|
|
8
|
-
|
|
9
|
-
**A community plugin for DeepSeek Harness** — records token usage and cost for every model call, with peak/off-peak billing, balance query, a calendar heatmap, and CSV / JSON / PNG export.
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
</div>
|
|
16
|
-
|
|
17
|
-
---
|
|
18
|
-
|
|
19
|
-
> ## 🔔 Important Notice (2026-08-16): npm package renamed
|
|
20
|
-
>
|
|
21
|
-
> The **npm package has been renamed from `@feiyang666/deepseekharnessdesktop` to `@feiyang666/dsh-usage-plugin`** (matching the GitHub repo `feiyang-dev/dsh-usage-plugin`).
|
|
22
|
-
>
|
|
23
|
-
> - Use the new package name for install / upgrade: `dsh plugin --profile web add @feiyang666/dsh-usage-plugin`
|
|
24
|
-
> - The old package `@feiyang666/deepseekharnessdesktop` remains published for a while, but it is **no longer maintained and will not receive updates** — please migrate soon.
|
|
25
|
-
> - The desktop client (`DeepSeek Harness Desktop`) supports both package names and will auto-detect old-name installs with a **one-click update** to the new name.
|
|
26
|
-
|
|
27
|
-
---
|
|
28
|
-
|
|
29
|
-
## Overview
|
|
30
|
-
|
|
31
|
-
dsh-usage-plugin is a **usage & cost tracker** plugin in the DeepSeek Harness ecosystem (a DSH plugin shipped as a Host + Client two-in-one package). After installation, **"Usage & Cost"** and **"Balance Query"** tabs appear in the Web UI, right after "Conversation" and "Trace":
|
|
32
|
-
|
|
33
|
-
> Supports **Windows / macOS / Linux**: paths are handled per platform (`node:path`), and the folder picker / "reveal in file manager" use each OS's native mechanism (macOS: `osascript` / `open`; Linux: `zenity` / `xdg-open`). Balance query and export do not depend on Windows-only commands.
|
|
34
|
-
|
|
35
|
-
- **Usage & Cost**: records each model call's token usage and cache hits (input miss / cache hit / cache write / output / reasoning / finish reason), and computes cost using DeepSeek's peak/valley or base pricing (peak hours are automatically priced by Beijing time 09:00–12:00 and 14:00–18:00). Model names come from the actual request parameters, so non-DeepSeek models are shown truthfully instead of "unknown model"; models without an official price are counted as 0. The overview shows a by-model table plus a by-API-provider × model drill-down (each provider grouped with every model's calls and peak/off-peak cost split) and a grand total row.
|
|
36
|
-
- **Usage Calendar**: a monthly daily-usage heatmap (colored by cost or call count), hover for details including the peak/off-peak cost split, click a day for its call list and peak/off-peak totals, plus a per-day statistics table with peak cost / off-peak cost / total columns and monthly rollups.
|
|
37
|
-
- **Cache Hit List**: newest-first, fully scrollable, with quick filters (Today / 7 days / 30 days / All) and custom date ranges; the summary line and footer total split peak vs off-peak consumption with a grand cost total. The list is paginated (100 rows per page), so it stays smooth even with large data volumes.
|
|
38
|
-
- **Price Table**: the official DeepSeek API price table — base and peak/valley unit prices shown side by side (peak vs off-peak), editable in-panel and persisted to `pricing.json`, with a reset-to-default option.
|
|
39
|
-
- **Balance Query**: queries your DeepSeek account balance using the configured `DEEPSEEK_API_KEY`.
|
|
40
|
-
- **Export**: CSV / JSON / **PNG long image** (newest-first, up to the latest 2000 records, warns if exceeded; the PNG report includes peak/off-peak cost columns), to any directory (native picker), auto-opens the folder after export.
|
|
41
|
-
- **Import**: merge-imports JSON / CSV files, deduplicated by time.
|
|
42
|
-
- **Persistence**: records are written live to `<session workspace>/dsh-usage/usage-records.json` and restored on restart (cap 100000 records).
|
|
43
|
-
- **UI adaptation**: panel typography scales with the app's display-size setting (em-relative fonts); table wrapping and spacing are tuned so large display sizes stay readable.
|
|
44
|
-
|
|
45
|
-
---
|
|
46
|
-
|
|
47
|
-
## Screenshots
|
|
48
|
-
|
|
49
|
-
### Usage & Consumption
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
### Balance Query
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
## Recommended Installation
|
|
56
|
-
|
|
57
|
-
> Either method works and is equivalent. **We recommend the desktop app** — fully graphical, no command line needed.
|
|
58
|
-
|
|
59
|
-
### Option 1 (recommended): One-click via the desktop app
|
|
60
|
-
|
|
61
|
-
Install [DeepSeek Harness Desktop](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop), open it, then go to **"Install Plugins" → Recommended → Usage & Cost Tracker → Install** and click **"Restart Service Now"** to activate.
|
|
62
|
-
|
|
63
|
-
### Option 2: Command line
|
|
64
|
-
|
|
65
|
-
```bash
|
|
66
|
-
# Prerequisite: install dsh (npm install -g @deepseek-ai/dsh)
|
|
67
|
-
dsh plugin --profile web add @feiyang666/dsh-usage-plugin
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
Or install to another profile:
|
|
71
|
-
|
|
72
|
-
```bash
|
|
73
|
-
dsh plugin --profile web add @feiyang666/dsh-usage-plugin
|
|
74
|
-
dsh plugin --profile headless add @feiyang666/dsh-usage-plugin
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
Restart the dsh web service after installation. Detailed manual install / wiring / uninstall / troubleshooting follows below.
|
|
78
|
-
|
|
79
|
-
---
|
|
80
|
-
|
|
81
|
-
## What's in the package
|
|
82
|
-
|
|
83
|
-
One npm package = a **host half** (Node-side Cordis plugin: recording, billing, balance query, export — see `lib/index.js`) + a **client half** (browser-side panel — see `lib/client.js`, which talks to the host via `/usage/api`).
|
|
84
|
-
|
|
85
|
-
The package integrates with DSH through two declarations:
|
|
86
|
-
|
|
87
|
-
| Declaration | Purpose |
|
|
88
|
-
| --- | --- |
|
|
89
|
-
| `dsh.bundle.patch` (`cordis.patch.yml`) | Lets DSH recognize it as a **standard bundle plugin package**: `dsh plugin --profile <name> add <package>` installs and wires it in one command, no manual config editing |
|
|
90
|
-
| `dsh.client` + `exports["./client"]` | Lets the web client auto-load the browser panel at `/plugins/<package>/client.js` |
|
|
91
|
-
|
|
92
|
-
So for users, **installation is one command** — no YAML editing, no manual file copying.
|
|
93
|
-
|
|
94
|
-
---
|
|
95
|
-
|
|
96
|
-
## Installation (for users)
|
|
97
|
-
|
|
98
|
-
### 0. Prerequisites
|
|
99
|
-
|
|
100
|
-
- DeepSeek Harness installed (`npm install -g @deepseek-ai/dsh`, or a desktop app built on it, or `npx @deepseek-ai/dsh web`).
|
|
101
|
-
- Option A (recommended) needs **pnpm**: `npm install -g pnpm` (or `corepack enable`).
|
|
102
|
-
- Make sure `dsh` is on PATH (for the desktop app, run in its bundled terminal).
|
|
103
|
-
|
|
104
|
-
### 1. Method A (recommended): one command
|
|
105
|
-
|
|
106
|
-
```bash
|
|
107
|
-
dsh plugin --profile web add @feiyang666/dsh-usage-plugin
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
This does three things (all automatic):
|
|
111
|
-
|
|
112
|
-
1. Installs the package via pnpm into `~/.dsh/profiles/web` (auto-initializes the profile on first use);
|
|
113
|
-
2. Detects the package's `dsh.bundle` declaration and writes the package name into the profile's `dsh.profile.bundles` layer list;
|
|
114
|
-
3. After restart, DSH reads the package's `cordis.patch.yml` and mounts the plugin row into the app tree — **no manual config editing**.
|
|
115
|
-
|
|
116
|
-
Same for other profiles (replace `web` with your profile name, e.g. `dsh plugin --profile headless add ...`; `dsh web` equals `dsh --profile web`).
|
|
117
|
-
|
|
118
|
-
> Test a local tarball: `dsh plugin --profile web add C:\path\to\feiyang666-deepseekharnessdesktop-1.1.0.tgz`
|
|
119
|
-
|
|
120
|
-
### 2. Method B: manual install (no pnpm / no `dsh plugin`)
|
|
121
|
-
|
|
122
|
-
Only for when you have no pnpm or want full manual control. **Do not `npm install` directly at `~/.dsh/profiles`** (that dir has no package.json; npm would treat the whole node_modules as residue and wipe it).
|
|
123
|
-
|
|
124
|
-
**B1. Use pnpm but not `dsh plugin`:**
|
|
125
|
-
|
|
126
|
-
```bash
|
|
127
|
-
cd ~/.dsh/profiles/web
|
|
128
|
-
pnpm add @feiyang666/dsh-usage-plugin
|
|
129
|
-
# then manually append the plugin row to web/cordis.patch.yml (see B3) and restart
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
**B2. Or use npm:** add a minimal package.json to the profile first, then install:
|
|
133
|
-
|
|
134
|
-
```bash
|
|
135
|
-
cd ~/.dsh/profiles/web
|
|
136
|
-
# if no package.json exists there yet (only after `dsh plugin` init):
|
|
137
|
-
# echo '{"name":"dsh-profile-web","private":true,"dependencies":{}}' > package.json
|
|
138
|
-
npm install @feiyang666/dsh-usage-plugin
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
**B3. Wire it up (once, idempotent):** append to `~/.dsh/profiles/web/cordis.patch.yml`:
|
|
142
|
-
|
|
143
|
-
```yaml
|
|
144
|
-
- insert:
|
|
145
|
-
- id: usage-plugin
|
|
146
|
-
name: '@feiyang666/dsh-usage-plugin'
|
|
147
|
-
inject:
|
|
148
|
-
- fs
|
|
149
|
-
- webServer
|
|
150
|
-
- subprocess
|
|
151
|
-
- credentials
|
|
152
|
-
- sandboxPolicy
|
|
153
|
-
- agents
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
Or just run the package's built-in wiring script (auto-finds the profile and appends, idempotent):
|
|
157
|
-
|
|
158
|
-
```bash
|
|
159
|
-
node node_modules/@feiyang666/dsh-usage-plugin/scripts/wire.js
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
> ⚠️ The `inject` list is **required**: it makes Cordis wait until `fs` / `webServer` / `subprocess` / `credentials` / `sandboxPolicy` / `agents` are ready before activating the plugin. Without it the `/usage/api` route never registers and the panel fails with `Unexpected end of JSON input`.
|
|
163
|
-
|
|
164
|
-
### 3. Method C: desktop app
|
|
165
|
-
|
|
166
|
-
The desktop app (e.g. [DeepSeek Harness Desktop](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop)) uses the same `~/.dsh/profiles` underneath. Run Method A's command in any terminal, restart the app, and the plugin activates automatically (the app starts the same `dsh web`).
|
|
167
|
-
|
|
168
|
-
### 4. Restart and verify
|
|
169
|
-
|
|
170
|
-
Restart the DeepSeek Harness web app (command line: kill the old process and re-run `dsh web`; desktop: fully quit and reopen). Then:
|
|
171
|
-
|
|
172
|
-
- Refresh http://127.0.0.1:3080 — after "Conversation" and "Trace", you should see **"Usage & Cost"** and **"Balance Query"** tabs; there are entries in Settings too.
|
|
173
|
-
- The "Usage & Cost" panel contains **Overview / Usage Calendar / Cache Hit List / Price Table** subtabs.
|
|
174
|
-
- Send a message and the "Usage & Cost" panel should show this call's token / cost record.
|
|
175
|
-
|
|
176
|
-
### 5. Configuration (for balance query)
|
|
177
|
-
|
|
178
|
-
"Balance Query" uses the configured `DEEPSEEK_API_KEY`: set the API Key in **Settings → Models** (same key used for chats), then open the "Balance Query" tab and click "Query Balance".
|
|
179
|
-
|
|
180
|
-
---
|
|
181
|
-
|
|
182
|
-
## Uninstall
|
|
183
|
-
|
|
184
|
-
```bash
|
|
185
|
-
dsh plugin --profile web remove @feiyang666/dsh-usage-plugin
|
|
186
|
-
```
|
|
187
|
-
|
|
188
|
-
(Equivalent to pnpm remove; `dsh plugin` auto-removes the package name from the `dsh.profile.bundles` layer list.) Restart the app afterward.
|
|
189
|
-
|
|
190
|
-
For manual installs (Method B), do it in reverse: remove the `usage-plugin` row from `cordis.patch.yml`, then `pnpm remove` / `npm uninstall` the package, and restart.
|
|
191
|
-
|
|
192
|
-
> Upgrading from a 1.0.x manual-wiring install to 1.1.x: first remove the old `usage-plugin` row from `cordis.patch.yml` (or follow the uninstall flow), then reinstall via Method A to avoid mounting the plugin twice.
|
|
193
|
-
|
|
194
|
-
---
|
|
195
|
-
|
|
196
|
-
## Data & locations
|
|
197
|
-
|
|
198
|
-
- Records: `<session workspace>/dsh-usage/usage-records.json`
|
|
199
|
-
- Price config (edited & saved in the panel): `<session workspace>/dsh-usage/pricing.json`
|
|
200
|
-
- Default export dir: `<session workspace>/dsh-usage/{csv,json,images}/`
|
|
201
|
-
- Custom export dir: set in the panel's "Export target directory" or click "Choose directory…"
|
|
202
|
-
- Startup diagnostics (if the plugin fails to activate): `dsh-usage-boot.log` in the session workspace
|
|
203
|
-
|
|
204
|
-
---
|
|
205
|
-
|
|
206
|
-
## FAQ
|
|
207
|
-
|
|
208
|
-
| Symptom | Cause / Fix |
|
|
209
|
-
| --- | --- |
|
|
210
|
-
| Panel reports `Unexpected end of JSON input` | The plugin row is missing the `inject` list, so the route isn't registered. Add the inject list per Method B3 and restart |
|
|
211
|
-
| Panel blank / no top tab | Plugin not activated. Check `dsh-usage-boot.log`; confirm the `cordis.patch.yml` row exists with the correct `name` |
|
|
212
|
-
| Balance query fails with "DEEPSEEK_API_KEY not configured" | Set the API Key in Settings → Models |
|
|
213
|
-
| Balance query network error | Ensure `api.deepseek.com` is reachable (configure a proxy if needed) |
|
|
214
|
-
| `dsh plugin` reports pnpm not found | Install pnpm: `npm install -g pnpm` |
|
|
215
|
-
| Install can't reach the npm registry | Set a mirror: `npm config set registry https://registry.npmmirror.com` (or `pnpm config set registry ...`) and retry |
|
|
216
|
-
| After uninstall, still reports `Cannot find package '@feiyang666/...'` | A package reference remains in the profile. Remove the corresponding row from `cordis.patch.yml` and the package name from `dsh.profile.bundles`, then restart |
|
|
217
|
-
|
|
218
|
-
---
|
|
219
|
-
|
|
220
|
-
## Publish to npm (for maintainers)
|
|
221
|
-
|
|
222
|
-
```bash
|
|
223
|
-
npm login # use your own npm account
|
|
224
|
-
npm run check # pre-publish self-check (also runs via prepublishOnly)
|
|
225
|
-
npm pack # inspect the tarball contents
|
|
226
|
-
npm publish --access public # scoped packages must use --access public
|
|
227
|
-
```
|
|
228
|
-
|
|
229
|
-
> Publishing to public npm makes the source public — make sure no sensitive info is in the package (API keys are user-configured at runtime only).
|
|
230
|
-
> If your network can't reach `registry.npmjs.org`, run `npm config set registry https://registry.npmjs.org` before publishing (the package's `.npmrc` presets this registry).
|
|
231
|
-
|
|
232
|
-
---
|
|
233
|
-
|
|
234
|
-
## Related Projects
|
|
235
|
-
|
|
236
|
-
| Project | Description | Installation |
|
|
237
|
-
| --- | --- | --- |
|
|
238
|
-
| [DeepSeek Harness Desktop](https://github.com/feiyang-dev/DeepSeek-Harness-Desktop) | Windows desktop console: install/start/stop/restart the dsh web service with one click, built-in plugin management — **install this plugin from its Recommended section** | Download the desktop app and click a few buttons |
|
|
239
|
-
| [Data Vault (dsh-vault)](https://github.com/feiyang-dev/dsh-vault) | Auto backup / wipe detection / one-click restore — protects chat history and workspace data | One-click from the desktop app, or `dsh plugin add @feiyang666/dsh-vault` |
|
|
240
|
-
| [DeepSeek-Harness](https://github.com/deepseek-ai/DeepSeek-Harness) | Official CLI / Web service | Quick start below |
|
|
241
|
-
|
|
242
|
-
### Running DeepSeek Harness
|
|
243
|
-
|
|
244
|
-
**Quick start (via npm)**
|
|
245
|
-
|
|
246
|
-
Install Node.js, then run:
|
|
247
|
-
|
|
248
|
-
```bash
|
|
249
|
-
npx @deepseek-ai/dsh web
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
This command starts the Web UI at the default address http://127.0.0.1:3080. See the [Web UI Guide](https://github.com/deepseek-ai/DeepSeek-Harness) for details.
|
|
253
|
-
|
|
254
|
-
**Run from source**
|
|
255
|
-
|
|
256
|
-
To run from the repository source:
|
|
257
|
-
|
|
258
|
-
```bash
|
|
259
|
-
git clone https://github.com/deepseek-ai/deepseek-harness.git
|
|
260
|
-
cd deepseek-harness
|
|
261
|
-
pnpm install
|
|
262
|
-
pnpm run build
|
|
263
|
-
pnpm dsh web
|
|
264
|
-
```
|
|
265
|
-
|
|
266
|
-
## Acknowledgements
|
|
267
|
-
|
|
268
|
-
- **[@liu3734](https://github.com/liu3734)**: reported and diagnosed the Windows-only path handling / spawn issues on macOS (POSIX) and proposed the cross-platform fix ([#1](https://github.com/feiyang-dev/dsh-usage-plugin/issues/1)).
|
|
269
|
-
|
|
270
|
-
## License
|
|
271
|
-
|
|
272
|
-
MIT © dsh-usage-plugin
|