@virzz/dsh-plugin-deepseek-balance 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 virzz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# @virzz/dsh-plugin-deepseek-balance
+
+A [DSH](https://github.com/deepseek-ai/deepseek-harness) plugin that shows the DeepSeek
+official account balance as a row in the sidebar footer, above **Settings**.
+
+```
+◆  Cordis Plugin                    0 running
+▤  DeepSeek 余额              $1058.69 · ¥-0.01
+⚙  设置
+```
+
+## Shape
+
+| Half | File | What it does |
+| --- | --- | --- |
+| Host | `lib/index.js` | Owns one resident `node` child, decodes the JSON lines it prints, serves the newest snapshot on `GET /deepseek-balance` |
+| Client | `lib/client.js` | Registers a row in `sidebar.footer.action` and re-reads that route every 15s |
+
+The child polls `https://api.deepseek.com/user/balance` with Node's own global `fetch` and
+prints one JSON line per attempt:
+
+```json
+{"ok":true,"available":true,"balances":[{"currency":"USD","total":"1058.69","granted":"0.00","toppedUp":"1058.69"}],"fetchedAt":1789030816379}
+```
+
+Design notes:
+
+- **No shell, no curl.** `argv` is an explicit `node -e`, resolved through
+  `subprocess.resolveExecutable`, so nothing depends on the launching shell's `PATH`.
+- **One process.** The child is spawned once per plugin lifetime and restarted only after it
+  exits (5s backoff); it is terminated with the owning fiber.
+- **The key stays on the host.** `DEEPSEEK_API_KEY` is resolved through the `credentials`
+  service and passed to the child in its environment — never on the command line, never to
+  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.
+
+## Install
+
+Published to npmjs on every release:
+
+```sh
+npm install @virzz/dsh-plugin-deepseek-balance
+```
+
+Also mirrored to the GitHub npm registry:
+
+```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:
+
+```sh
+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
+- insert:
+    - id: deepseek-balance
+      name: '@virzz/dsh-plugin-deepseek-balance'
+```
+
+`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
+`lib/client.js` must equal the package name — the workflow checks that before publishing.
+
+## Why the client half overrides one slot anchor
+
+`sidebar.footer.action` renders as a flex **row**, and its only shipped occupant — the
+Cordis panel row — is `flex: none; width: 100%`, so a second entry in that row collapses to
+zero width. The slot anchor itself renders with `display: contents`, which is what makes the
+one-line fix safe:
+
+```css
+[data-slot="sidebar.footer.action"] { display: flex !important; flex-direction: column; }
+```
+
+The anchor becomes a real box, the two entries stack, and no shipped rule or row is touched.
+The row itself reuses the shipped footer row's metrics (42px, 12px radius, right-aligned
+status text in `--dsw-alias-label-tertiary`) so it reads as part of the sidebar foot; in the
+56px rail it collapses to a 36px circle showing the primary currency symbol.
+
+## Publish
+
+`.github/workflows/publish.yml` runs on a published release, on a `v*` tag push, or by hand
+via **Run workflow**. It has three jobs: a `check` gate, then one publish job per registry.
+
+| Registry | Credential | Notes |
+| --- | --- | --- |
+| npmjs | **OIDC trusted publishing** — no token at all | the job carries `id-token: write` and the npm CLI exchanges that for a short-lived publish credential; provenance is generated automatically because the repo is public |
+| GitHub Packages | the workflow's own `GITHUB_TOKEN` | needs `packages: write`; nothing to configure |
+
+They are separate jobs on purpose: the two use different credentials, and one being
+unconfigured never blocks the other. `publishConfig.registry` is deliberately **not** set —
+it would override each job's `--registry`, and the `check` job fails if it comes back.
+
+### Trusted publishing setup
+
+Trusted publishing needs npm CLI >= 11.5.1 on Node >= 22.14, so the jobs run Node 24 and the
+npmjs job upgrades npm before publishing. On npmjs.com, at
+**Packages → @virzz/dsh-plugin-deepseek-balance → Settings → Trusted publishing**, add a
+GitHub Actions publisher with these exact, case-sensitive values:
+
+| Field | Value |
+| --- | --- |
+| Organization or user | `virzz` |
+| Repository | `dsh-plugin-deepseek-balance` |
+| Workflow filename | `publish.yml` |
+| Allowed actions | `npm publish` |
+
+**First publish is the exception.** A package that does not exist yet has no settings page to
+attach a trusted publisher to, so version `1.0.0` has to be published once the ordinary way —
+either `npm login && npm publish --access public` from a checkout, or run the workflow with a
+temporary `NPM_TOKEN` secret. Configure the trusted publisher immediately afterwards; every
+later release then publishes with no token, and you can set the package to
+*Require two-factor authentication and disallow tokens*.
+
+Bump `version` before releasing: both registries reject a duplicate version.
+
+## Test
+
+`test/host-smoke.mjs` drives `apply()` with a fake Cordis context whose subprocess provider
+is a real `node:child_process`, then reads the registered route — covering spawn, stdout
+lines, snapshot, and route JSON without a DSH process:
+
+```sh
+DEEPSEEK_API_KEY=... node test/host-smoke.mjs
+```

package/lib/client.js

@@ -0,0 +1,217 @@
+window.__ModuleLoader__.load({
+	id: "@virzz/dsh-plugin-deepseek-balance",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		const React = require("react");
+
+		/** Read route served by the host half. Must match ROUTE_PATH in lib/index.js. */
+		const ROUTE = "/deepseek-balance";
+		/** How often the row re-reads the host's cached snapshot (the child collects every 60s). */
+		const REFRESH_MS = 15000;
+		/** Currency glyphs; anything else renders as its ISO code. */
+		const SYMBOLS = { CNY: "¥", USD: "$", EUR: "€", GBP: "£", JPY: "¥" };
+
+		/**
+		 * The sidebar foot is a flex ROW whose only shipped occupant (the Cordis panel row) is
+		 * `flex: none; width: 100%`, so a second entry there collapses to zero width. The slot
+		 * anchor itself renders with `display: contents`, which is exactly what lets this rule
+		 * give the two entries a column of their own without touching the shipped rows.
+		 */
+		const CSS = [
+			'[data-slot="sidebar.footer.action"]{display:flex !important;flex-direction:column;gap:2px;width:100%;min-width:0}',
+			".dsb-row{box-sizing:border-box;width:100%;height:42px;color:var(--dsw-alias-label-primary);text-align:left;cursor:pointer;background:0 0;border:none;border-radius:12px;align-items:center;gap:8px;margin:8px 0 0;padding:0 10px 0 8px;font-family:inherit;font-size:14px;line-height:22px;display:flex;overflow:hidden}",
+			".dsb-row:hover{background:var(--dsw-alias-interactive-bg-hover)}",
+			".dsb-row:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:-2px}",
+			".dsb-icon{flex:none;place-items:center;width:16px;height:16px;display:inline-flex;color:var(--dsw-alias-label-secondary)}",
+			".dsb-label{text-overflow:ellipsis;white-space:nowrap;min-width:0;overflow:hidden}",
+			".dsb-value{color:var(--dsw-alias-label-tertiary);font-variant-numeric:tabular-nums;white-space:nowrap;flex:none;margin-left:auto;font-size:12px;line-height:16px}",
+			'.dsb-row[data-tone="error"] .dsb-value{color:var(--dsw-alias-state-error-primary)}',
+			'.dsb-row[data-busy="true"] .dsb-value{opacity:.7}',
+			".dsb-row.dsb-rail{width:36px;height:36px;margin:0;padding:0;justify-content:center;gap:0;border-radius:50%}",
+			".dsb-row.dsb-rail .dsb-label,.dsb-row.dsb-rail .dsb-value{display:none}",
+			".dsb-railGlyph{color:var(--dsw-alias-label-secondary);font-size:13px;line-height:1}",
+		].join("");
+
+		function symbolOf(currency) {
+			const code = typeof currency === "string" ? currency.toUpperCase() : "";
+			if (code === "") return "";
+			if (Object.prototype.hasOwnProperty.call(SYMBOLS, code)) return SYMBOLS[code];
+			return code + " ";
+		}
+
+		function amountOf(entry) {
+			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) {
+			for (let index = 0; index < balances.length; index += 1) {
+				const value = Number(balances[index].total);
+				if (Number.isFinite(value) && value !== 0) return balances[index];
+			}
+			return balances.length > 0 ? balances[0] : undefined;
+		}
+
+		function timeText(ms) {
+			if (typeof ms !== "number" || ms <= 0) return "";
+			try {
+				return new Date(ms).toLocaleTimeString();
+			} catch {
+				return "";
+			}
+		}
+
+		/** A wallet glyph, sized to sit beside the shipped footer rows' marks. */
+		function walletGlyph() {
+			return React.createElement("svg", {
+				width: 16,
+				height: 16,
+				viewBox: "0 0 16 16",
+				fill: "none",
+				"aria-hidden": true,
+			}, [
+				React.createElement("rect", {
+					key: "body",
+					x: 1.75,
+					y: 3.75,
+					width: 12.5,
+					height: 8.5,
+					rx: 2.25,
+					stroke: "currentColor",
+					strokeWidth: 1.5,
+				}),
+				React.createElement("circle", { key: "stud", cx: 11.25, cy: 8, r: 1.25, fill: "currentColor" }),
+			]);
+		}
+
+		/** The sidebar-foot row: it reads the host snapshot and renders the newest figures. */
+		function BalanceRow(props) {
+			const wide = props === null || props === undefined || props.wide !== false;
+			const [state, setState] = React.useState({
+				phase: "loading",
+				code: "",
+				error: "",
+				available: true,
+				balances: [],
+				fetchedAt: 0,
+			});
+
+			const load = () => {
+				fetch(ROUTE, { headers: { accept: "application/json" } })
+					.then((response) => response.json().then((data) => ({ status: response.status, data })))
+					.then(({ status, data }) => {
+						const isObject = data !== null && typeof data === "object";
+						if (status !== 200 || !isObject || data.ok !== true) {
+							const code = isObject && typeof data.code === "string" ? data.code : "http-" + String(status);
+							const message = isObject && typeof data.error === "string" ? data.error : "读取失败";
+							setState({ phase: "error", code, error: message, available: false, balances: [], fetchedAt: 0 });
+							return;
+						}
+						setState({
+							phase: "ok",
+							code: "",
+							error: "",
+							available: data.available === true,
+							balances: Array.isArray(data.balances) ? data.balances : [],
+							fetchedAt: typeof data.fetchedAt === "number" ? data.fetchedAt : 0,
+						});
+					})
+					.catch((error) => {
+						const message = error !== null && error !== undefined && typeof error.message === "string" ? error.message : String(error);
+						setState({ phase: "error", code: "network", error: message, available: false, balances: [], fetchedAt: 0 });
+					});
+			};
+
+			React.useEffect(() => {
+				load();
+				const id = setInterval(load, REFRESH_MS);
+				return () => clearInterval(id);
+			}, []);
+
+			const balances = state.balances;
+			let tone = "loading";
+			let label = "DeepSeek 余额";
+			let value = "…";
+			let detail = "DeepSeek 余额：正在读取宿主采集进程…";
+
+			if (state.phase === "ok") {
+				tone = state.available ? "ok" : "error";
+				value = balances.slice(0, 2).map(amountOf).join(" · ");
+				const lines = ["DeepSeek 余额（常驻 node 采集）"];
+				for (let index = 0; index < balances.length; index += 1) {
+					const entry = balances[index];
+					lines.push(entry.currency + " " + entry.total + "（赠金 " + entry.granted + " · 充值 " + entry.toppedUp + "）");
+				}
+				if (state.available !== true) lines.push("该账户当前不可调用");
+				const updated = timeText(state.fetchedAt);
+				if (updated !== "") lines.push("采集于 " + updated);
+				lines.push("node 每 60 秒采集一次 · 界面每 15 秒读取缓存 · 点击立即读取");
+				detail = lines.join("\n");
+			} else if (state.phase === "error") {
+				tone = "error";
+				value = state.code === "missing-key" ? "未配置密钥" : "不可用";
+				detail = "DeepSeek 余额获取失败\n" + state.error + "\n点击重试 · 每 15 秒自动重试";
+			}
+
+			if (wide !== true) {
+				const primary = primaryOf(balances);
+				const glyph = state.phase === "ok" ? symbolOf(primary === undefined ? "" : primary.currency) : state.phase === "error" ? "!" : "…";
+				return React.createElement("button", {
+					type: "button",
+					className: "dsb-row dsb-rail",
+					"data-tone": tone,
+					"data-busy": state.phase === "loading" ? "true" : "false",
+					title: detail,
+					"aria-label": label + " " + value,
+					onClick: load,
+				}, React.createElement("span", { className: "dsb-railGlyph" }, glyph));
+			}
+
+			return React.createElement("button", {
+				type: "button",
+				className: "dsb-row",
+				"data-tone": tone,
+				"data-busy": state.phase === "loading" ? "true" : "false",
+				title: detail,
+				"aria-label": label + " " + value,
+				onClick: load,
+			}, [
+				React.createElement("span", { key: "icon", className: "dsb-icon" }, walletGlyph()),
+				React.createElement("span", { key: "label", className: "dsb-label" }, label),
+				React.createElement("span", { key: "value", className: "dsb-value" }, value),
+			]);
+		}
+
+		/** The slot registry is the only client service this half reads. */
+		const inject = ["slots"];
+
+		/**
+		 * Client plugin body: own the stylesheet and the sidebar-foot row.
+		 *
+		 * @param ctx - client root context.
+		 */
+		function apply(ctx) {
+			ctx.effect(() => {
+				const tag = document.createElement("style");
+				tag.dataset.plugin = "dsh-plugin-deepseek-balance";
+				tag.textContent = CSS;
+				document.head.appendChild(tag);
+				return () => {
+					tag.remove();
+				};
+			}, "deepseek-balance: styles");
+			ctx.slots.inject("sidebar.footer.action", () => ctx.slots.register({
+				name: "sidebar.footer.action",
+				id: "deepseek-balance",
+				order: 40,
+				label: "DeepSeek 余额",
+			}, BalanceRow));
+		}
+
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -0,0 +1,263 @@
+/**
+ * DeepSeek balance pill — host half.
+ *
+ * One resident `node` child polls the DeepSeek balance API with Node's own global `fetch`
+ * and prints one JSON line per attempt on stdout; this half only decodes those lines and
+ * serves the newest snapshot to the browser half over a local read route.
+ *
+ * No shell and no curl are involved: `argv` is an explicit `node -e`, and the API key
+ * reaches the child through its environment, never through the command line. The key never
+ * leaves this process either — the read route returns only the balance figures.
+ *
+ * @module dsh-plugin-deepseek-balance
+ */
+
+/** Polling cadence of the resident child. */
+const COLLECT_MS = 60000
+
+/** Read route the browser half polls. Must match ROUTE in lib/client.js. */
+const ROUTE_PATH = '/deepseek-balance'
+
+/**
+ * The one long-lived child program. It polls the balance API itself and prints one JSON
+ * line per attempt, which is the whole contract with this half: `{ ok: true, available,
+ * balances, fetchedAt }` or `{ ok: false, code, error }`.
+ *
+ * All inner quotes are single, so this literal needs no escaping.
+ */
+const POLLER = "const KEY = process.env.DEEPSEEK_API_KEY; const URL_BALANCE = 'https://api.deepseek.com/user/balance'; function emit(value) { console.log(JSON.stringify(value)) } async function tick() { try { const response = await fetch(URL_BALANCE, { headers: { Authorization: 'Bearer ' + KEY, Accept: 'application/json' } }); const body = await response.text(); if (!response.ok) { emit({ ok: false, code: 'http-' + response.status, error: 'HTTP ' + response.status + ': ' + body.slice(0, 200) }); return } const payload = JSON.parse(body); const raw = Array.isArray(payload.balance_infos) ? payload.balance_infos : []; const balances = []; for (const entry of raw) { if (entry === null || typeof entry !== 'object') continue; balances.push({ currency: String(entry.currency || ''), total: String(entry.total_balance || ''), granted: String(entry.granted_balance || ''), toppedUp: String(entry.topped_up_balance || '') }) } if (balances.length === 0) { emit({ ok: false, code: 'bad-response', error: '响应中没有余额信息' }); return } emit({ ok: true, available: payload.is_available === true, balances: balances, fetchedAt: Date.now() }) } catch (error) { emit({ ok: false, code: 'request-failed', error: String((error && error.message) || error) }) } } tick(); setInterval(tick, EVERY_MS_PLACEHOLDER)"
+
+/** One-line description of any thrown value. */
+function describe(error) {
+  if (error === null || error === undefined) return '未知错误'
+  if (typeof error === 'string') return error
+  if (typeof error.message === 'string') return error.message
+  return String(error)
+}
+
+/**
+ * The shell implementation's own default working directory, so the child inherits a real
+ * cwd without this plugin guessing a path.
+ *
+ * @param ctx - host context.
+ * @returns an existing directory path.
+ */
+function workingDirectory(ctx) {
+  try {
+    const shell = ctx.get('shell')
+    if (shell !== undefined && typeof shell.resolve === 'function') {
+      const spec = shell.resolve({ command: 'true' })
+      if (spec !== null && typeof spec === 'object' && typeof spec.workdir === 'string' && spec.workdir !== '') {
+        return spec.workdir
+      }
+    }
+  } catch {
+    // Fall through to the neutral root.
+  }
+  return '/'
+}
+
+/**
+ * Own the resident collector: one child, restarted only after it exits.
+ *
+ * @param ctx - host context.
+ * @returns the lifecycle hooks the plugin effect drives.
+ */
+function createCollector(ctx) {
+  const program = POLLER.replace('EVERY_MS_PLACEHOLDER', String(COLLECT_MS))
+  const state = {
+    latest: undefined,
+    failure: undefined,
+    buffer: '',
+    stderr: '',
+    disposed: false,
+    handle: undefined,
+    restart: undefined,
+  }
+
+  /** The wire shape the browser half renders. */
+  function snapshot() {
+    if (state.latest !== undefined) {
+      const value = state.latest
+      if (value.ok === true) {
+        return {
+          ok: true,
+          available: value.available === true,
+          balances: Array.isArray(value.balances) ? value.balances : [],
+          fetchedAt: typeof value.fetchedAt === 'number' ? value.fetchedAt : 0,
+        }
+      }
+      return {
+        ok: false,
+        code: typeof value.code === 'string' ? value.code : 'failed',
+        error: typeof value.error === 'string' ? value.error : '未知错误',
+      }
+    }
+    if (state.failure !== undefined) return { ok: false, code: state.failure.code, error: state.failure.error }
+    return { ok: false, code: 'starting', error: '正在启动 node 采集进程…' }
+  }
+
+  function onStdout(chunk) {
+    state.buffer += chunk.toString('utf8')
+    let index = state.buffer.indexOf('\n')
+    while (index >= 0) {
+      const line = state.buffer.slice(0, index).trim()
+      state.buffer = state.buffer.slice(index + 1)
+      if (line !== '') {
+        try {
+          const value = JSON.parse(line)
+          if (value !== null && typeof value === 'object') {
+            state.latest = value
+            state.failure = undefined
+          }
+        } catch {
+          // A partial or foreign line is ignored; the next one carries the payload.
+        }
+      }
+      index = state.buffer.indexOf('\n')
+    }
+    if (state.buffer.length > 65536) state.buffer = state.buffer.slice(-4096)
+  }
+
+  /**
+   * Resolve the node executable in the provider's own execution world, so the child never
+   * depends on the launching shell's PATH. A provider that cannot answer falls back to the
+   * bare name, which spawn resolves exactly as before.
+   */
+  async function nodeCommand(subprocess) {
+    try {
+      const resolved = await subprocess.resolveExecutable('node')
+      if (typeof resolved === 'string' && resolved !== '') return resolved
+    } catch {
+      // No resolver answer: let spawn resolve the bare name.
+    }
+    return 'node'
+  }
+
+  async function start() {
+    if (state.disposed === true) return
+    try {
+      const subprocess = ctx.get('subprocess')
+      const credentials = ctx.get('credentials')
+      if (subprocess === undefined || credentials === undefined) {
+        // Belt and braces: `inject` normally guarantees these, but a row that activates
+        // before them still recovers instead of latching a failure for its whole lifetime.
+        state.failure = {
+          code: 'unavailable',
+          error: '等待 ' + (subprocess === undefined ? 'subprocess' : 'credentials') + ' 服务，5 秒后重试',
+        }
+        state.restart = ctx.timeout(() => { start() }, 5000)
+        return
+      }
+      const resolved = await credentials.resolve('DEEPSEEK_API_KEY')
+      if (state.disposed === true) return
+      if (resolved === undefined || typeof resolved.value !== 'string' || resolved.value === '') {
+        state.failure = { code: 'missing-key', error: '未配置 DEEPSEEK_API_KEY' }
+        return
+      }
+
+      const command = await nodeCommand(subprocess)
+      if (state.disposed === true) return
+
+      let handle
+      try {
+        handle = subprocess.spawn({
+          argv: [command, '-e', program],
+          cwd: workingDirectory(ctx),
+          stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' },
+          graceMs: 3000,
+          env: { DEEPSEEK_API_KEY: resolved.value },
+        })
+      } catch (error) {
+        state.failure = { code: 'spawn-failed', error: '启动 node 失败：' + describe(error) }
+        return
+      }
+
+      state.handle = handle
+      handle.stdout?.on('data', onStdout)
+      handle.stderr?.on('data', (chunk) => {
+        state.stderr = (state.stderr + chunk.toString('utf8')).slice(-600)
+      })
+      handle.done.then(() => {
+        if (state.disposed === true) return
+        const tail = state.stderr.trim()
+        state.failure = {
+          code: 'poller-exited',
+          error: 'node 采集进程已退出，5 秒后重启' + (tail === '' ? '' : '：' + tail.slice(0, 300)),
+        }
+        state.restart = ctx.timeout(() => { start() }, 5000)
+      }, (error) => {
+        if (state.disposed === true) return
+        state.failure = { code: 'poller-failed', error: 'node 采集进程失败：' + describe(error) }
+        state.restart = ctx.timeout(() => { start() }, 5000)
+      })
+    } catch (error) {
+      state.failure = { code: 'unavailable', error: '启动采集进程出错：' + describe(error) }
+    }
+  }
+
+  function stop() {
+    state.disposed = true
+    if (state.restart !== undefined) state.restart()
+    try {
+      state.handle?.terminate()
+    } catch {
+      // The child is already gone; nothing to terminate.
+    }
+  }
+
+  return { start, stop, snapshot }
+}
+
+export const name = 'deepseek-balance'
+
+/**
+ * Hard dependencies, declared so `apply` cannot run before they exist. `subprocess` and
+ * `credentials` are provided by other rows and are not guaranteed to be up when this row
+ * activates; reading them only through `ctx.get` at activation time can observe them absent
+ * and latch a failure that never clears. `shell` stays optional — it only supplies a default
+ * working directory — and `timer` backs the restart backoff.
+ */
+export const inject = ['timer', 'subprocess', 'credentials']
+
+/**
+ * Plugin body: own the resident collector and publish its snapshot on one exact read route.
+ *
+ * @param ctx - host root context.
+ */
+export function apply(ctx) {
+  const collector = createCollector(ctx)
+
+  ctx.effect(() => {
+    collector.start()
+    return collector.stop
+  }, 'deepseek-balance: resident collector')
+
+  const registerRoute = (carrier) => {
+    // Read the service through the context rather than through an injected property:
+    // `webServer` is deliberately not a hard dependency of this plugin.
+    const webServer = carrier.get('webServer')
+    if (webServer === undefined) return
+    carrier.effect(() => webServer.register({
+      kind: 'exact',
+      path: ROUTE_PATH,
+      handler(req, res) {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+          res.writeHead(405, { allow: 'GET, HEAD' })
+          res.end()
+          return
+        }
+        const body = JSON.stringify(collector.snapshot())
+        res.writeHead(200, {
+          'content-type': 'application/json; charset=utf-8',
+          'content-length': Buffer.byteLength(body),
+          'cache-control': 'no-store',
+        })
+        res.end(req.method === 'HEAD' ? undefined : body)
+      },
+    }), 'deepseek-balance: read route')
+  }
+
+  if (ctx.get('webServer') === undefined) ctx.inject(['webServer'], registerRoute)
+  else registerRoute(ctx)
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@virzz/dsh-plugin-deepseek-balance",
+  "version": "1.0.0",
+  "description": "DeepSeek official account balance as a DSH sidebar status row, collected by one resident node process",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "platform": "web",
+      "inject": []
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "deepseek",
+    "cordis",
+    "plugin",
+    "balance"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/virzz/dsh-plugin-deepseek-balance.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}