@virzz/dsh-plugin-deepseek-balance 1.0.0 → 1.1.0

package/README.md

@@ -5,7 +5,7 @@ official account balance as a row in the sidebar footer, above **Settings**.
 
 ```
 ◆  Cordis Plugin                    0 running
-▤  DeepSeek 余额              $1058.69 · ¥-0.01
+▤  DeepSeek 余额                    $1058.69
 ⚙  设置
 ```
 
@@ -34,36 +34,120 @@ Design notes:
   the browser. The read route returns only balance figures.
 - **Two cadences.** The child collects every 60s; the row re-reads the host's cached
   snapshot every 15s, so no polling happens from the browser.
+- **Positive balances only.** A currency whose total is zero or negative says nothing useful
+  in a balance read-out, so it is left out of both the row and its tooltip. The tooltip
+  reports how many entries were hidden, and the row reads `0` when nothing is positive. The
+  host still returns every currency it receives — the rule is presentation, not data.
 
-## Install
+## Install into DSH
 
-Published to npmjs on every release:
+A DSH plugin is a package plus a row. The package has to be resolvable **from the profile
+that mounts it**, and the row has to name it — the browser half only reaches the page as part
+of that profile's client roster, which is composed at boot.
+
+### 1. Add the package to the profile
+
+```sh
+dsh plugin --profile web add @virzz/dsh-plugin-deepseek-balance
+```
+
+`dsh plugin` forwards everything after `--profile <name>` to pnpm **in the profile
+directory**, so this is an ordinary `pnpm add` in `$DSH_HOME/profiles/web` — which is exactly
+the `node_modules` tree the loader resolves row names from.
+
+To leave the shipped `web` profile untouched, derive your own from it and install there:
 
 ```sh
-npm install @virzz/dsh-plugin-deepseek-balance
+dsh --profile balance --from-default-profile web
+dsh plugin --profile balance add @virzz/dsh-plugin-deepseek-balance
 ```
 
-Also mirrored to the GitHub npm registry:
+The package is published to npmjs and to GitHub Packages. The command above resolves from
+npmjs by default; to install from GitHub Packages, point the scope at it first:
 
 ```sh
 npm config set @virzz:registry https://npm.pkg.github.com
-npm install @virzz/dsh-plugin-deepseek-balance
 ```
 
-To mount it in a DSH profile, the package must also be resolvable from that profile and named
-by a row. With pnpm available that is `dsh plugin --profile web add <spec>`; without pnpm a
-link plus one patch row is equivalent:
+<details>
+<summary>Without pnpm</summary>
+
+`dsh plugin add` does two things; both can be done by hand — put the package where the
+profile can resolve it, and name it in the profile's own patch layer.
 
 ```sh
-ln -s /path/to/dsh-plugin-deepseek-balance ~/.dsh/profiles/web/node_modules/@virzz/dsh-plugin-deepseek-balance
+mkdir -p ~/.dsh/profiles/web/node_modules/@virzz
+ln -s /path/to/dsh-plugin-deepseek-balance \
+      ~/.dsh/profiles/web/node_modules/@virzz/dsh-plugin-deepseek-balance
 ```
 
 ```yaml
-# ~/.dsh/profiles/web/cordis.patch.yml
+# ~/.dsh/profiles/web/cordis.patch.yml — applied after every bundle layer
 - insert:
     - id: deepseek-balance
       name: '@virzz/dsh-plugin-deepseek-balance'
 ```
+</details>
+
+### 2. Provide the DeepSeek API key
+
+The host half re-resolves the credential reference `DEEPSEEK_API_KEY` on every collector
+start. Either of these works:
+
+- **Settings → Models**, on the DeepSeek provider card — stored in `$DSH_HOME/.credentials.yaml`; or
+- export it where DSH boots: `export DEEPSEEK_API_KEY=sk-...`
+
+Nothing else needs it. The key never reaches the browser and never appears on a command
+line: the collector receives it in its environment, and the read route exposes balance
+figures only.
+
+### 3. Boot
+
+```sh
+dsh --profile web        # or: dsh web
+```
+
+The row appears in the sidebar footer, directly above **Settings**:
+
+```
+◆  Cordis Plugin                    0 running
+▤  DeepSeek 余额                    $1058.69
+⚙  设置
+```
+
+Hover it for the per-currency breakdown (total, granted, topped up) and the collection time;
+click it to re-read the host's cache immediately.
+
+### 4. Verify without opening the UI
+
+```sh
+dsh --profile web --dump-config | grep -A2 deepseek-balance   # is the row composed?
+curl -s http://127.0.0.1:8021/deepseek-balance                # does the host half answer?
+```
+
+The launcher prints its URL on boot; adjust the port if yours differs. A healthy answer:
+
+```json
+{"ok":true,"available":true,"balances":[{"currency":"USD","total":"1058.69","granted":"0.00","toppedUp":"1058.69"}],"fetchedAt":1789030816379}
+```
+
+### Troubleshooting
+
+| Symptom | What to check |
+| --- | --- |
+| Row reads `未配置密钥` | `DEEPSEEK_API_KEY` is not resolvable — set it in Settings → Models, or in the environment that boots DSH |
+| Row reads `不可用` | Hover it: the tooltip carries the exact cause (`http-401`, `request-failed`, `poller-exited`, …) |
+| Row reads `不可用`, tooltip says `subprocess 服务不可用` | The row activated before the subprocess service. It declares that as a hard dependency *and* retries every 5s, so it clears itself |
+| No row at all | The client roster is composed at boot — restart the profile. `--dump-config` above shows whether the row is composed at all |
+| Row only visible when the sidebar is expanded | Expected: in the 56px rail it collapses to a 36px circle showing the primary currency symbol |
+
+### Uninstall
+
+```sh
+dsh plugin --profile web remove @virzz/dsh-plugin-deepseek-balance
+```
+
+Or delete the row from `cordis.patch.yml` plus the `node_modules` entry, then restart.
 
 `dsh.client` in `package.json` puts `lib/client.js` into the browser roster that
 `@deepseek-ai/dsh-client-modules` composes into `window.__DSH_BOOT__`. The module id inside

package/lib/client.js

@@ -45,13 +45,18 @@ window.__ModuleLoader__.load({
 			return symbolOf(entry.currency) + entry.total;
 		}
 
-		/** The entry whose figure stands for the account: the first non-zero one, else the first. */
-		function primaryOf(balances) {
+		/**
+		 * The balances worth showing. A currency whose total is zero or negative carries no
+		 * information for a balance read-out, so it is left out of both the row and its
+		 * tooltip — and only counted, so the tooltip can say that something was hidden.
+		 */
+		function positiveOf(balances) {
+			const shown = [];
 			for (let index = 0; index < balances.length; index += 1) {
 				const value = Number(balances[index].total);
-				if (Number.isFinite(value) && value !== 0) return balances[index];
+				if (Number.isFinite(value) && value > 0) shown.push(balances[index]);
 			}
-			return balances.length > 0 ? balances[0] : undefined;
+			return shown;
 		}
 
 		function timeText(ms) {
@@ -131,6 +136,8 @@ window.__ModuleLoader__.load({
 			}, []);
 
 			const balances = state.balances;
+			const shown = positiveOf(balances);
+			const hidden = balances.length - shown.length;
 			let tone = "loading";
 			let label = "DeepSeek 余额";
 			let value = "…";
@@ -138,12 +145,14 @@ window.__ModuleLoader__.load({
 
 			if (state.phase === "ok") {
 				tone = state.available ? "ok" : "error";
-				value = balances.slice(0, 2).map(amountOf).join(" · ");
+				value = shown.length > 0 ? shown.slice(0, 2).map(amountOf).join(" · ") : "0";
 				const lines = ["DeepSeek 余额（常驻 node 采集）"];
-				for (let index = 0; index < balances.length; index += 1) {
-					const entry = balances[index];
+				for (let index = 0; index < shown.length; index += 1) {
+					const entry = shown[index];
 					lines.push(entry.currency + " " + entry.total + "（赠金 " + entry.granted + " · 充值 " + entry.toppedUp + "）");
 				}
+				if (shown.length === 0) lines.push("所有币种余额均不大于 0")
+				else if (hidden > 0) lines.push("已隐藏 " + hidden + " 项非正余额")
 				if (state.available !== true) lines.push("该账户当前不可调用");
 				const updated = timeText(state.fetchedAt);
 				if (updated !== "") lines.push("采集于 " + updated);
@@ -156,8 +165,10 @@ window.__ModuleLoader__.load({
 			}
 
 			if (wide !== true) {
-				const primary = primaryOf(balances);
-				const glyph = state.phase === "ok" ? symbolOf(primary === undefined ? "" : primary.currency) : state.phase === "error" ? "!" : "…";
+				const primary = shown.length > 0 ? shown[0] : undefined;
+				const glyph = state.phase === "ok"
+					? (primary === undefined ? "0" : symbolOf(primary.currency))
+					: state.phase === "error" ? "!" : "…";
 				return React.createElement("button", {
 					type: "button",
 					className: "dsb-row dsb-rail",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@virzz/dsh-plugin-deepseek-balance",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "DeepSeek official account balance as a DSH sidebar status row, collected by one resident node process",
   "type": "module",
   "main": "lib/index.js",