@lyk308/dsh-token-dashboard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-token-dashboard contributors
+
+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,55 @@
+# dsh-token-dashboard
+
+[![awesome · DSH plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
+A DeepSeek Harness plugin that puts your **real-time account balance** and **token usage** on one dashboard. Local-first: reads your DSH session logs and the DeepSeek `/user/balance` API. No cloud account beyond your existing DeepSeek key.
+
+## Features
+
+- 💰 **Account balance** — live balance from the DeepSeek official `/user/balance` API (CNY/USD aware), with force-refresh.
+- 📊 **Token usage** — Today / This month / All-time cards, plus request count, cache hit rate, and session count.
+- 📈 **Usage distribution** — toggle between **by model** and **by workspace**, with a proportional share bar (top 8 + "other" aggregate). Percentages match the bar exactly.
+- 🗓 **Activity heatmap** — 30 / 90 / 180 day switch, green-shade intensity maps token usage.
+- 🤖 **Model breakdown** — a table of Req / Input / Cache / Output per model.
+
+## Installation
+
+This is a standard DSH bundle plugin, so install it with the official CLI:
+
+```bash
+dsh plugin --profile web add <path-or-git-url-to-this-repo>
+```
+
+If published to npm, you can also install by name:
+
+```bash
+dsh plugin --profile web add dsh-token-dashboard
+```
+
+After installing, **refresh the web UI**. The dashboard appears under **Settings → 用量看板** (Usage Dashboard).
+
+> Note: the plugin reads the DeepSeek API key from DSH's credentials service (`DEEPSEEK_API_KEY`). Without a valid key the balance card shows a hint instead of a number; token usage still works because it comes from local session logs.
+
+## Usage
+
+1. Open **Settings → 用量看板**.
+2. Refresh the server to load the latest data at any time.
+3. Switch between **by model / by workspace** and the **30 / 90 / 180-day** heatmap ranges.
+
+## Configuration
+
+The plugin mostly works with no configuration. The host half resolves sensible defaults in `lib/index.js`:
+- `sessionsRoot` — defaults to `$DSH_HOME/sessions`.
+- `balanceCacheMs` — balance cache TTL (default 300000 ms = 5 min).
+- `sweepIntervalMs` — stats refresh interval (default 60000 ms).
+
+## Development
+
+- `lib/index.js` — host half: session scanning (multi-frame zstd), token aggregation, balance proxy.
+- `lib/client.js` — client half: the settings.section UI.
+
+Edit `lib/client.js` → refresh the page to see changes. Edit `lib/index.js` → restart the DSH web profile.
+
+## License
+
+[MIT](./LICENSE)

package/README.zh.md

@@ -0,0 +1,55 @@
+# dsh-token-dashboard
+
+[![awesome · DSH plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
+一个 DeepSeek Harness 插件，把**实时账户余额**和 **Token 使用量**整合在一个看板上。本地优先：读取你的 DSH 会话日志 + DeepSeek 官方 `/user/balance` 接口，无需额外云端账号（沿用你已有的 DeepSeek key）。
+
+## 功能
+
+- 💰 **账户余额** — 通过 DeepSeek 官方 `/user/balance` 接口实时获取（自动识别 CNY/USD），支持强制刷新。
+- 📊 **Token 使用量** — 今日 / 本月 / 总计三卡，加请求数、缓存命中率、会话数。
+- 📈 **用量分布** — 在**按模型**和**按工作区**之间切换，带比例占比条（前 8 项 + 「其他」聚合），百分比与占比条完全一致。
+- 🗓 **活跃度热力图** — 30 / 90 / 180 天切换，绿色深浅映射 Token 用量。
+- 🤖 **按模型明细** — 每个模型的 Req / Input / Cache / Output 表格。
+
+## 安装
+
+这是一个标准 DSH bundle 插件，用官方 CLI 安装：
+
+```bash
+dsh plugin --profile web add <此仓库的路径或 git 地址>
+```
+
+如果发布到 npm，也可按包名安装：
+
+```bash
+dsh plugin --profile web add dsh-token-dashboard
+```
+
+安装后**刷新网页**即可。看板位于 **设置 → 用量看板**。
+
+> 说明：插件从 DSH 的凭据服务读取 DeepSeek API Key（`DEEPSEEK_API_KEY`）。没有有效 key 时余额卡片显示引导文案；Token 用量仍可正常统计（来自本地会话日志）。
+
+## 使用方法
+
+1. 打开 **设置 → 用量看板**。
+2. 随时刷新服务器加载最新数据。
+3. 切换 **按模型 / 按工作区**，以及 **30 / 90 / 180 天**热力图范围。
+
+## 配置
+
+插件基本无需配置即可使用，host 半在 `lib/index.js` 里解析合理默认值：
+- `sessionsRoot` — 默认为 `$DSH_HOME/sessions`。
+- `balanceCacheMs` — 余额缓存时长（默认 300000 毫秒 = 5 分钟）。
+- `sweepIntervalMs` — 统计刷新间隔（默认 60000 毫秒）。
+
+## 开发
+
+- `lib/index.js` — host 半：会话扫描（多帧 zstd）、Token 聚合、余额代理。
+- `lib/client.js` — client 半：settings.section 界面。
+
+改 `lib/client.js` → 刷新页面即可看到变化。改 `lib/index.js` → 重启 DSH web profile。
+
+## 许可证
+
+[MIT](./LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-token-dashboard bundle patch
+# 作为社区插件层被 dsh plugin add 安装时，本文件插入插件行（host 半 = 包默认导出；
+# client 半 = dsh.client 标记扫描，注册到 settings.section 槽位，避免与 footer.action 冲突）。
+# 注意：不在此处写 config / !!js 表达式，避免 patch 解析失败导致插件被 DSH 回退剔除。
+# 运行参数由 host 半（lib/index.js）自行解析默认值。
+- insert:
+    - id: token-dashboard
+      name: dsh-token-dashboard

package/lib/client.js

@@ -0,0 +1,345 @@
+/**
+ * dsh-token-dashboard — client half (Token Ledger style).
+ *
+ * Layout mirrors a token ledger: Balance card, Token-usage stat cards
+ * (Today / This month / All time + requests + cache rate), a grouped share bar
+ * (by model OR by workspace, toggleable), an Activity heatmap with a
+ * 30/90/180-day range switch, and a Models table (Req / Input / Cache /
+ * Output). Uses react/jsx-runtime jsx/jsxs correctly and never puts a raw null
+ * inside a children array. Wrapped in an ErrorBoundary.
+ */
+window.__ModuleLoader__.load({
+	id: "dsh-token-dashboard",
+	factory: (require) => {
+		const module = { exports: {} };
+		const exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+
+		const React = require("react");
+		const { useEffect, useState, useCallback, Component } = React;
+		const jsx = require("react/jsx-runtime").jsx;
+		const jsxs = require("react/jsx-runtime").jsxs;
+
+		// ---- CSS-ish tokens (follow DSH theme vars) ----
+		const CARD = {
+			border: "1px solid var(--dsw-alias-border-l1)",
+			borderRadius: "12px",
+			padding: "16px",
+			margin: "12px 0",
+			background: "var(--dsw-alias-bg-overlay, transparent)"
+		};
+		const SEC_TITLE = { fontSize: "13px", fontWeight: 600, color: "var(--dsw-alias-label-secondary)", marginBottom: "10px", letterSpacing: "0.02em" };
+		const NUM = { fontSize: "26px", fontWeight: 700, color: "var(--dsw-alias-label-primary)", lineHeight: 1.3 };
+		const LABEL = { fontSize: "12px", color: "var(--dsw-alias-label-tertiary)" };
+		const ROW = { display: "flex", alignItems: "center", justifyContent: "space-between", padding: "6px 0" };
+		const MONO = { fontVariantNumeric: "tabular-nums" };
+
+		function fmt(n) { return (n == null || isNaN(n)) ? "0" : Number(n).toLocaleString(); }
+		function fmtMoney(n) { return (n == null || isNaN(n)) ? "0.00" : Number(n).toFixed(2); }
+		function pct(v, max) { return max > 0 ? ((v / max) * 100) : 0; }
+
+		// A segmented control ("By model" / "By workspace" and the heatmap range).
+		function Seg({ options, value, onChange }) {
+			return jsxs("div", {
+				style: { display: "flex", gap: "4px", background: "var(--dsw-alias-interactive-bg-active, rgba(127,127,127,.14))", borderRadius: "8px", padding: "3px" },
+				children: options.map((o) => jsx("button", {
+					onClick: () => onChange(o.value),
+					style: {
+						flex: "1 1 auto", minWidth: "0", padding: "5px 14px", fontSize: "12px", borderRadius: "6px", cursor: "pointer",
+						border: "none", color: "var(--dsw-alias-label-primary)",
+						whiteSpace: "nowrap",
+						background: (o.value === value)
+							? "var(--dsw-alias-bg-overlay, rgba(255,255,255,.9))"
+							: "transparent",
+						fontWeight: (o.value === value) ? 600 : 400
+					},
+					children: o.label
+				}, o.value))
+			});
+		}
+
+		// Color scale for heatmap (green shades like the reference).
+		function heatColor(val, max) {
+			if (val <= 0) return "var(--dsw-alias-border-l1)";
+			const t = max > 0 ? (val / max) : 0;
+			const a = 0.25 + 0.75 * t;
+			return "rgba(76,175,80," + a.toFixed(2) + ")";
+		}
+
+		// A stable color per group entry; the "其他" (other) aggregate is grey so it
+		// reads as "everything else", distinct from the named top groups.
+		const GROUP_COLORS = ["#4caf50", "#2196f3", "#ff9800", "#9c27b0", "#00bcd4"];
+		function groupColor(key, i) {
+			if (key === "其他" || key === "other") return "var(--dsw-alias-label-tertiary, #9e9e9e)";
+			return GROUP_COLORS[i % GROUP_COLORS.length];
+		}
+
+		class Boundary extends Component {
+			constructor(props) { super(props); this.state = { error: null }; }
+			static getDerivedStateFromError(error) { return { error }; }
+			componentDidCatch(error, info) { console.error("[token-dashboard] render error:", error, info); }
+			render() {
+				if (this.state.error) {
+					return jsx("div", { style: { color: "var(--dsw-alias-danger, #e5484d)", fontSize: "12px", padding: "8px 0" }, children: "渲染出错：" + String(this.state.error?.message || this.state.error) });
+				}
+				return jsx("div", { children: this.props.children });
+			}
+		}
+
+		function TokenDashboardPanel() {
+			const [stats, setStats] = useState(null);
+			const [balance, setBalance] = useState(null);
+			const [error, setError] = useState(null);
+			const [loading, setLoading] = useState(true);
+			const [balanceLoading, setBalanceLoading] = useState(true);
+			const [groupBy, setGroupBy] = useState("model"); // "model" | "workspace"
+			const [range, setRange] = useState(90); // 30 | 90 | 180 days
+
+			const loadStats = useCallback(async () => {
+				try {
+					const res = await fetch("/api/token-dashboard/stats?refresh=1");
+					if (!res.ok) throw new Error("stats http " + res.status);
+					const data = await res.json();
+					if (data && data.status === "computing") { setTimeout(loadStats, 1200); return; }
+					setStats((data && typeof data === "object") ? data : {});
+					setLoading(false);
+				} catch (e2) { setError(String(e2)); setLoading(false); }
+			}, []);
+			const loadBalance = useCallback(async (force) => {
+				setBalanceLoading(true);
+				try {
+					const res = await fetch("/api/token-dashboard/balance" + (force ? "?force=1" : ""));
+					if (!res.ok) throw new Error("balance http " + res.status);
+					setBalance((await res.json()) || {});
+				} catch (e2) { setError(String(e2)); }
+				finally { setBalanceLoading(false); }
+			}, []);
+			useEffect(() => { loadStats(); loadBalance(false); }, [loadStats, loadBalance]);
+
+			if (!loading && stats) {
+				// ---- derived ----
+				const infos = balance?.data?.balance_infos || [];
+				let balInfo = infos.find((x) => x && x.currency === "CNY")
+					|| infos.find((x) => x && Number(x.total_balance ?? x.balance) > 0)
+					|| infos[0] || balance?.data || null;
+				const balValue = balInfo ? (balInfo.total_balance ?? balInfo.balance ?? null) : null;
+				const balCur = balInfo ? (balInfo.currency || "") : "";
+
+				const total = Number(stats.total) || 0;
+				const req = Number(stats.req) || Number(stats.events) || 0;
+				const today = Number(stats.today) || 0;
+				const thisMonth = Number(stats.thisMonth) || 0;
+				const cacheRate = (Number(stats.cacheHits) && total) ? (Number(stats.cacheHits) / total * 100).toFixed(1) : "0.0";
+
+				// grouped share data. Show top TOP_N entries by total, then fold the
+				// rest into a single "其他" (other) aggregate so the card never grows
+				// unbounded and tiny shares don't get lost in the bar.
+				const TOP_N = 8;
+				const groups = groupBy === "model" ? stats.byModel : stats.byWorkspace;
+				const allEntries = Object.keys(groups || {}).map((k) => ({ key: k, ...(typeof groups[k] === "object" ? groups[k] : { total: groups[k] }) }))
+					.sort((a, b) => b.total - a.total);
+				let groupEntries;
+				if (allEntries.length > TOP_N) {
+					const top = allEntries.slice(0, TOP_N);
+					// fold the remainder into a synthetic "其他" entry; keep broken-down
+					// counters for the bar/list (we only display total/req, but stay safe).
+					const rest = allEntries.slice(TOP_N);
+					const other = { key: "其他", req: 0, input: 0, output: 0, cacheRead: 0, reasoning: 0, total: 0 };
+					for (const r of rest) {
+						other.total += Number(r.total) || 0;
+						other.req += Number(r.req) || 0;
+						other.input += Number(r.input) || 0;
+						other.output += Number(r.output) || 0;
+						other.cacheRead += Number(r.cacheRead) || 0;
+						other.reasoning += Number(r.reasoning) || 0;
+					}
+					groupEntries = [...top, other];
+				} else {
+					groupEntries = allEntries;
+				}
+				// Percentages use the SUM of all group totals as the denominator, so the
+				// bar segments (flex-grow by total) and the printed % agree exactly and
+				// both reflect "share of all usage".
+				const groupSum = groupEntries.reduce((s, g) => s + (Number(g.total) || 0), 0);
+
+				// heatmap: build days from byDay within range
+				const byDay = stats.byDay || {};
+				const todayD = new Date();
+				const cells = [];
+				for (let i = range - 1; i >= 0; i--) {
+					const d = new Date(todayD); d.setDate(d.getDate() - i);
+					const key = d.toISOString().slice(0, 10);
+					cells.push({ key, val: Number(byDay[key]) || 0 });
+				}
+				const heatMax = Math.max(1, ...cells.map((c) => c.val));
+				// group cells into weeks for the grid (7 per week)
+				const weeks = [];
+				for (let i = 0; i < cells.length; i += 7) weeks.push(cells.slice(i, i + 7));
+
+				// models table rows
+				const modelRows = Object.keys(stats.byModel || {})
+					.map((m) => ({ key: m, ...stats.byModel[m] }))
+					.sort((a, b) => b.total - a.total);
+
+				// ---- render ----
+				const balanceInner = balanceLoading ? jsx("div", { style: { color: "var(--dsw-alias-label-secondary)" }, children: "加载中…" })
+					: (balance && balance.status === "ok")
+						? jsxs("div", { children: [
+							jsxs("div", { style: { display: "flex", alignItems: "baseline", gap: "6px" }, children: [
+								jsx("span", { style: { ...NUM, ...MONO }, children: (balCur === "CNY" ? "¥" : "$") + fmtMoney(balValue) }),
+								jsx("span", { style: LABEL, children: balCur })
+							] }),
+							jsxs("div", { style: { marginTop: "8px" }, children: [
+								jsx("button", { onClick: () => loadBalance(true), style: { cursor: "pointer", fontSize: "12px", padding: "4px 10px", borderRadius: "6px", border: "1px solid var(--dsw-alias-border-l1)", background: "transparent", color: "var(--dsw-alias-label-primary)" }, children: "强制刷新" }),
+								balance.cached ? jsx("span", { style: { fontSize: "11px", color: "var(--dsw-alias-label-tertiary)", marginLeft: "8px" }, children: "缓存" }) : null
+							] })
+						] })
+						: jsx("div", { style: { color: "var(--dsw-alias-label-secondary)" }, children: (balance?.message || "未配置或不可用") });
+
+				const statCards = [
+					{ label: "今日", val: today },
+					{ label: "本月", val: thisMonth },
+					{ label: "总计", val: total }
+				];
+				const statBar = jsxs("div", { style: { display: "grid", gridTemplateColumns: "repeat(3,1fr)", gap: "10px" }, children: statCards.map((s) =>
+					jsxs("div", { style: { background: "var(--dsw-alias-interactive-bg-active, rgba(127,127,127,.08))", borderRadius: "10px", padding: "12px" }, children: [
+						jsx("div", { style: LABEL, children: s.label }),
+						jsx("div", { style: { ...NUM, ...MONO, fontSize: "22px" }, children: fmt(s.val) })
+					] }, s.label)
+				) });
+
+				const shareBar = jsxs("div", { children: [
+					jsxs("div", { style: { display: "flex", height: "12px", borderRadius: "6px", overflow: "hidden", gap: "2px", backgroundColor: "var(--dsw-alias-border-l1)" }, children: groupEntries.map((g, i) =>
+						// flex-grow proportional to total: each segment takes its share of the
+						// full width. grow = g.total, shrink = 0, basis = 0 → segments split
+						// the row exactly by their token totals (no fixed/min width clobbering).
+						jsx("div", { style: { flex: g.total + " 0 0", background: groupColor(g.key, i) }, title: g.key + " " + fmt(g.total) }, g.key)
+					) }),
+					jsxs("div", { style: { display: "flex", flexDirection: "column", gap: "6px", marginTop: "10px" }, children: groupEntries.map((g, i) =>
+						jsxs("div", { style: ROW, children: [
+							jsxs("div", { style: { display: "flex", alignItems: "center", gap: "8px", minWidth: "0" }, children: [
+								jsx("div", { style: { width: "10px", height: "10px", borderRadius: "2px", flexShrink: "0", background: groupColor(g.key, i) } }),
+								jsx("span", { style: { overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap", maxWidth: "240px", color: "var(--dsw-alias-label-primary)", fontSize: "13px" }, children: g.key })
+							] }),
+							jsxs("div", { style: { display: "flex", gap: "14px", color: "var(--dsw-alias-label-secondary)", ...MONO, fontSize: "13px", flexShrink: "0" }, children: [
+								jsx("span", { children: fmt(g.total) }),
+								jsx("span", { style: { color: "var(--dsw-alias-label-tertiary)" }, children: pct(g.total, groupSum).toFixed(0) + "%" })
+							] })
+						] }, g.key)
+					) })
+				] });
+
+				// heatmap grid (weeks as columns is complex; render day cells in a wrap grid)
+				const heatGrid = jsxs("div", { style: { display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(14px, 1fr))", gap: "3px" }, children: cells.map((c) =>
+					jsx("div", { style: { width: "14px", height: "14px", borderRadius: "2px", background: heatColor(c.val, heatMax) }, title: c.key + ": " + fmt(c.val) }, c.key)
+				) });
+
+				const modelTable = jsxs("table", { style: { width: "100%", borderCollapse: "collapse", fontSize: "13px" }, children: [
+					jsxs("thead", { children: [jsxs("tr", { children: [
+						jsx("th", { style: thStyle, children: "模型" }), jsx("th", { style: thR, children: "Req" }),
+						jsx("th", { style: thR, children: "Input" }), jsx("th", { style: thR, children: "Cache" }),
+						jsx("th", { style: thR, children: "Output" })
+					] })] }),
+					jsxs("tbody", { children: modelRows.map((r) => jsxs("tr", { style: { borderTop: "1px solid var(--dsw-alias-border-l1)" }, children: [
+						jsx("td", { style: tdStyle, children: r.key }),
+						jsx("td", { style: tdR, children: r.req }),
+						jsx("td", { style: tdR, children: fmt(r.input) }),
+						jsx("td", { style: tdR, children: fmt(r.cacheRead) }),
+						jsx("td", { style: tdR, children: fmt(r.output) })
+					] }, r.key)) })
+				] });
+
+				return jsxs("div", { children: [
+					jsx("h3", { style: { fontSize: "18px", fontWeight: 700, color: "var(--dsw-alias-label-primary)", marginBottom: "4px" }, children: "用量看板" }),
+					(error) ? jsx("div", { style: { color: "var(--dsw-alias-danger, #e5484d)", fontSize: "12px", margin: "6px 0" }, children: "加载出错：" + error }) : null,
+
+					// Balance
+					jsxs("div", { style: CARD, children: [
+						jsx("div", { style: SEC_TITLE, children: "💰 账户余额（DeepSeek 官方）" }), balanceInner
+					] }),
+
+					// Token usage
+					jsxs("div", { style: CARD, children: [
+						jsx("div", { style: SEC_TITLE, children: "📊 Token 使用量" }),
+						statBar,
+						jsxs("div", { style: { ...ROW, marginTop: "10px" }, children: [
+							jsx("span", { children: "请求数" }), jsx("span", { ...MONO, children: fmt(req) })
+						] }),
+						jsxs("div", { style: ROW, children: [
+							jsx("span", { children: "缓存命中率" }), jsx("span", { ...MONO, children: cacheRate + "%" })
+						] }),
+						jsxs("div", { style: ROW, children: [
+							jsx("span", { children: "会话数" }), jsx("span", { ...MONO, children: Number(stats.sessions) || 0 })
+						] })
+					] }),
+
+					// Grouped share
+					jsxs("div", { style: CARD, children: [
+						jsxs("div", { style: { display: "flex", alignItems: "center", justifyContent: "space-between", gap: "8px", marginBottom: "10px" }, children: [
+							jsx("div", { style: SEC_TITLE, children: "📈 用量分布" }),
+							jsx(Seg, { options: [{ label: "按模型", value: "model" }, { label: "按工作区", value: "workspace" }], value: groupBy, onChange: setGroupBy })
+						] }),
+						shareBar
+					] }),
+
+					// Activity heatmap
+					jsxs("div", { style: CARD, children: [
+						jsxs("div", { style: { display: "flex", alignItems: "center", justifyContent: "space-between", marginBottom: "10px" }, children: [
+							jsx("div", { style: SEC_TITLE, children: "🗓 活跃度" }),
+							jsx(Seg, { options: [{ label: "30天", value: 30 }, { label: "90天", value: 90 }, { label: "180天", value: 180 }], value: range, onChange: setRange })
+						] }),
+						heatGrid
+					] }),
+
+					// Models table
+					jsxs("div", { style: CARD, children: [
+						jsx("div", { style: SEC_TITLE, children: "🤖 按模型" }),
+						modelTable
+					] })
+				] });
+			}
+
+			// loading / no data -> simple spinner-ish text
+			return jsxs("div", { children: [
+				jsx("h3", { style: { fontSize: "18px", fontWeight: 700, color: "var(--dsw-alias-label-primary)", marginBottom: "12px" }, children: "用量看板" }),
+				(error) ? jsx("div", { style: { color: "var(--dsw-alias-danger, #e5484d)", fontSize: "12px", margin: "6px 0" }, children: "加载出错：" + error }) : null,
+				jsx("div", { style: { color: "var(--dsw-alias-label-secondary)", padding: "8px 0" }, children: "加载中…" })
+			] });
+		}
+
+		const thStyle = { textAlign: "left", padding: "8px 6px", color: "var(--dsw-alias-label-tertiary)", fontWeight: 500, fontSize: "12px" };
+		const thR = { textAlign: "right", padding: "8px 6px", color: "var(--dsw-alias-label-tertiary)", fontWeight: 500, fontSize: "12px", ...MONO };
+		const tdStyle = { padding: "8px 6px", color: "var(--dsw-alias-label-primary)" };
+		const tdR = { textAlign: "right", padding: "8px 6px", color: "var(--dsw-alias-label-secondary)", ...MONO };
+
+		function apply(ctx) {
+			ctx.slots.inject("settings.section", () => ctx.slots.register(
+				{
+					name: "settings.section",
+					id: "token-dashboard",
+					order: 30,
+					label: () => {
+						try {
+							const bound = ctx.locale && typeof ctx.locale.bind === "function" && ctx.locale.bind("token-dashboard");
+							const v = bound && typeof bound === "function" ? bound("title") : null;
+							return (typeof v === "string" && v !== "title") ? v : "用量看板";
+						} catch {
+							return "用量看板";
+						}
+					},
+					inject: () => ({})
+				},
+				(props) => jsx(Boundary, { children: jsx(TokenDashboardPanel, props) })
+			));
+		}
+
+		exports.apply = apply;
+		exports.inject = ["slots", "locale"];
+		exports.TokenDashboardPanel = TokenDashboardPanel;
+		exports.Boundary = Boundary;
+		exports.fmt = fmt;
+		exports.fmtMoney = fmtMoney;
+
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -0,0 +1,361 @@
+/**
+ * dsh-token-dashboard — host half.
+ *
+ * Aggregates token usage from DSH persistent session logs (multi-frame zstd
+ * JSONL), and proxies DeepSeek `/user/balance` for the account balance card.
+ *
+ * Runtime contract (dsh bundle host plugin):
+ *   - default export = the Cordis plugin (a function `(ctx, config) => {...}`).
+ *   - `inject` = required services: `webServer` (route registration) and
+ *     `credentials` (DeepSeek API key resolution).
+ *
+ * The browser half rides `dsh.client` manifest; this file only owns the node
+ * half: session scan + aggregated statistics + balance proxy, exposed as a few
+ * JSON routes under `/api/token-dashboard/*`.
+ */
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { zstdDecompressSync, createZstdDecompress } from "node:zlib";
+import { createReadStream, createWriteStream } from "node:fs";
+import { once } from "node:events";
+
+const ZSTD_MAGIC = 0xfd2fb528; // bytes 28 b5 2f fd (little-endian)
+
+/**
+ * Split a zstd buffer into its constituent frames. DSH writes multi-frame zstd
+ * (one frame per chunk). We walk frame headers to find each frame boundary by
+ * scanning for the next magic; each slice is one complete zstd frame, which
+ * `zstdDecompressSync` decodes independently.
+ * @param {Buffer} buf
+ * @returns {{start:number,end:number}[]}
+ */
+function splitZstdFrames(buf) {
+	const frames = [];
+	let off = 0;
+	while (off < buf.length) {
+		if (buf.length - off < 4) break;
+		if (buf.readUInt32LE(off) !== ZSTD_MAGIC) break; // torn tail / non-frame
+		// frame header descriptor byte
+		const fhd = buf.readUInt8(off + 4);
+		let hdrLen = 5;
+		if (fhd & 0x01) hdrLen += 1; // window descriptor present
+		const didBits = (fhd >> 1) & 0x3;
+		hdrLen += [0, 1, 2, 4][didBits]; // dict id length
+		const fcs = fhd & 0x08;
+		if (fcs) {
+			const low = buf.readUInt8(off + hdrLen);
+			if (low === 0xff) {
+				// 8-byte content size (rare in DSH chunked logs); read and skip
+				hdrLen += 9;
+			} else {
+				hdrLen += 1;
+			}
+		}
+		// find next frame magic to bound this frame
+		let next = -1;
+		for (let i = off + hdrLen; i < buf.length - 3; i++) {
+			if (buf.readUInt32LE(i) === ZSTD_MAGIC) { next = i; break; }
+		}
+		const end = next === -1 ? buf.length : next;
+		frames.push({ start: off, end });
+		off = end;
+	}
+	return frames;
+}
+
+/**
+ * Decompress a (possibly multi-frame) zstd buffer to a UTF-8 string.
+ * @param {Buffer} buf
+ * @returns {string}
+ */
+function zstdDecompressToText(buf) {
+	// DSH writes MULTI-frame zstd (one frame per chunk). A naive single-shot
+	// `zstdDecompressSync(buf)` silently returns only the FIRST frame's bytes on
+	// Node, which is why we must always split into frames and decode each one.
+	const frames = splitZstdFrames(buf);
+	if (frames.length === 0) {
+		// fallback: maybe a genuine single-frame buffer whose magic walk failed
+		try {
+			const out = zstdDecompressSync(buf);
+			return out.toString("utf8");
+		} catch {
+			return "";
+		}
+	}
+	const parts = [];
+	for (const { start, end } of frames) {
+		try {
+			parts.push(zstdDecompressSync(buf.subarray(start, end)));
+		} catch {
+			// skip a corrupt frame; keep the rest of the log's data
+		}
+	}
+	if (parts.length === 0) return "";
+	return Buffer.concat(parts).toString("utf8");
+}
+
+/** Normalize a token-usage event into our source-neutral shape. */
+function usagesFromEvent(obj, acc, currentModel) {
+	if (!obj || typeof obj !== "object") return;
+	const data = obj.data;
+	if (!data) return;
+	const chunk = data.chunk;
+	if (!chunk) return;
+	const usage = chunk.usage;
+	if (!usage) return;
+	// Support both camelCase (DSH) and snake_case (OpenAI) keys.
+	const input = usage.inputTokens ?? usage.promptTokens ?? usage.prompt_tokens ?? 0;
+	const output = usage.outputTokens ?? usage.completionTokens ?? usage.completion_tokens ?? 0;
+	const cacheRead = usage.cacheReadTokens ?? usage.cachedTokens ?? usage.cached_tokens ?? 0;
+	const reasoning = usage.reasoningTokens ?? usage.reasoning_tokens ?? 0;
+	const sum = input + output + cacheRead + reasoning;
+	acc.total += sum;
+	acc.input += input;
+	acc.output += output;
+	acc.cacheRead += cacheRead;
+	acc.reasoning += reasoning;
+	acc.events += 1;
+	acc.req += 1;
+	acc.cacheHits += cacheRead;
+	// per-model attribution: prefer the model on the chunk/data, else the tracked current model.
+	// Store per-model BROKEN-DOWN counters so the UI can render Req/Input/Cache/Output/Total.
+	const model = chunk.model || data.model || obj.model || currentModel || "unknown";
+	if (model) {
+		let m = acc.byModel[model];
+		if (m === undefined) { m = acc.byModel[model] = { req: 0, input: 0, output: 0, cacheRead: 0, reasoning: 0, total: 0 }; }
+		m.req += 1;
+		m.input += input;
+		m.output += output;
+		m.cacheRead += cacheRead;
+		m.reasoning += reasoning;
+		m.total += sum;
+	}
+}
+
+/**
+ * Recursively walk the sessions root for `session.jsonl[.zstd]` files.
+ * @param {string} root
+ * @returns {string[]} absolute paths
+ */
+function findSessionLogs(root) {
+	const out = [];
+	if (!existsSync(root)) return out;
+	const walk = (dir) => {
+		let entries;
+		try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+		for (const e of entries) {
+			const p = join(dir, e.name);
+			if (e.isDirectory()) walk(p);
+			else if (/^session\.jsonl(\.zstd)?$/.test(e.name)) out.push(p);
+		}
+	};
+	walk(root);
+	return out;
+}
+
+/** Aggregate token stats across all session logs under `root`. */
+function aggregateTokens(root) {
+	const acc = {
+		total: 0, input: 0, output: 0, cacheRead: 0, reasoning: 0,
+		events: 0, req: 0, cacheHits: 0, sessions: 0, files: 0,
+		byModel: {}, byDay: {}, byWorkspace: {}
+	};
+	const files = findSessionLogs(root);
+	acc.files = files.length;
+	const now = new Date();
+	const todayKey = now.toISOString().slice(0, 10);
+	const monthKey = todayKey.slice(0, 7);
+	for (const file of files) {
+		let bytes;
+		try { bytes = readFileSync(file); } catch { continue; }
+		const text = file.endsWith(".zstd") ? zstdDecompressToText(bytes) : bytes.toString("utf8");
+		if (!text) continue;
+		acc.sessions += 1;
+		const lines = text.split("\n");
+		let ws = "unknown";
+		let currentModel = null;
+		for (const line of lines) {
+			if (!line) continue;
+			let o;
+			try { o = JSON.parse(line); } catch { continue; }
+			if (o.type === "session" && o.cwd) ws = o.cwd;
+			// Track the active model. DSH records it on:
+			//  - request/header: data.header.config.model  (authoritative)
+			//  - request/context: data.model
+			//  - assistant/message: data.usage.model
+			if (o.type === "request/header") {
+				const m = o.data?.header?.config?.model || o.data?.model || null;
+				if (m) currentModel = m;
+			} else if (o.type === "assistant/message") {
+				const m = o.data?.usage?.model || o.data?.model || null;
+				if (m) currentModel = m;
+			} else if (o.type === "request/context") {
+				const m = o.data?.model || null;
+				if (m) currentModel = m;
+			}
+			// Per-day + per-workspace accumulation must happen per event BEFORE the
+			// generic usagesFromEvent bump, so we mirror the same broken-down shape.
+			const usageBlock = o.data?.chunk?.usage;
+			if (usageBlock) {
+				const inTok = usageBlock.inputTokens ?? usageBlock.prompt_tokens ?? 0;
+				const outTok = usageBlock.outputTokens ?? usageBlock.completion_tokens ?? 0;
+				const cTok = usageBlock.cacheReadTokens ?? usageBlock.cachedTokens ?? 0;
+				const rTok = usageBlock.reasoningTokens ?? usageBlock.reasoning_tokens ?? 0;
+				const sum = inTok + outTok + cTok + rTok;
+				const t = o.time ?? o.createdAt;
+				const day = t ? new Date(t).toISOString().slice(0, 10) : null;
+				if (day !== null) {
+					acc.byDay[day] = (acc.byDay[day] || 0) + sum;
+					if (day === todayKey) acc.today = (acc.today || 0) + sum;
+					if (day.slice(0, 7) === monthKey) acc.thisMonth = (acc.thisMonth || 0) + sum;
+				}
+				// per-workspace broken-down counters
+				let w = acc.byWorkspace[ws];
+				if (w === undefined) { w = acc.byWorkspace[ws] = { req: 0, input: 0, output: 0, cacheRead: 0, reasoning: 0, total: 0 }; }
+				w.req += 1;
+				w.input += inTok;
+				w.output += outTok;
+				w.cacheRead += cTok;
+				w.reasoning += rTok;
+				w.total += sum;
+			}
+			usagesFromEvent(o, acc, currentModel);
+		}
+	}
+	return acc;
+}
+
+/**
+ * Proxy DeepSeek `/user/balance`.
+ * @param {string} apiKey
+ * @returns {Promise<object>}
+ */
+async function fetchBalance(apiKey) {
+	if (!apiKey) return { status: "unconfigured", message: "未配置 DeepSeek API Key" };
+	const res = await fetch("https://api.deepseek.com/user/balance", {
+		headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" }
+	});
+	if (!res.ok) return { status: "error", httpStatus: res.status, message: res.statusText };
+	const json = await res.json();
+	return { status: "ok", data: json };
+}
+
+/** A simple JSON response helper for the node:http handler. */
+function sendJson(res, status, payload) {
+	const body = JSON.stringify(payload);
+	res.writeHead(status, {
+		"Content-Type": "application/json; charset=utf-8",
+		"Cache-Control": "no-store"
+	});
+	res.end(body);
+}
+
+/**
+ * The Cordis plugin. `ctx` is the DSH context, `config` the merged config from
+ * the bundle patch row.
+ */
+export function apply(ctx, config) {
+	// sessionsRoot defaults to $DSH_HOME/sessions (config no longer forces it via
+	// the patch; the host half resolves its own default so the minimal patch
+	// `- insert: { id, name }` always parses and mounts).
+	const dshHome = process.env.DSH_HOME || join(process.env.USERPROFILE || process.env.HOME || ".", ".dsh");
+	const sessionsRoot = config?.sessionsRoot || join(dshHome, "sessions");
+	const balanceCacheMs = config?.balanceCacheMs ?? 300000;
+	const sweepIntervalMs = config?.sweepIntervalMs ?? 60000;
+	const logLevel = config?.logLevel ?? "info";
+
+	// ---- stats cache: keep a synchronous-but-heavy full scan OFF the request
+	// thread. Aggregate once every STATS_TTL_MS, serve cached results meanwhile.
+	// A sync scan of the whole sessions tree takes ~1.5s and would block the DSH
+	// event loop (freezing every concurrent request, SSE, and model call) if run
+	// inline in a handler — that is exactly the "everything goes slow / UI goes
+	// blank" symptom. Caching makes the request path O(1) and defers the costly
+	// scan to a background refresh that never blocks a response.
+	const STATS_TTL_MS = 60_000;
+	let statsCache = { at: 0, payload: null, computing: false };
+
+	function scheduleStatsRefresh() {
+		if (statsCache.computing) return; // already running; back off
+		statsCache.computing = true;
+		// Defer to the next tick so the current handler / event loop is not held.
+		setImmediate(() => {
+			try {
+				const s = aggregateTokens(sessionsRoot);
+				statsCache = { at: Date.now(), payload: s, computing: false };
+			} catch (error) {
+				ctx.logger.warn(error instanceof Error ? error : new Error(String(error)));
+				statsCache = { ...statsCache, computing: false };
+			}
+		});
+	}
+	// Warm the cache once on boot so the first open returns data immediately.
+	scheduleStatsRefresh();
+
+	// --- route: token stats (served from cache; never blocks the event loop) ---
+	ctx.webServer.register({
+		kind: "exact",
+		path: "/api/token-dashboard/stats",
+		handler: async (req, res) => {
+			try {
+				const url = new URL(req.url ?? "/", "http://x");
+				const force = url.searchParams.get("refresh") === "1";
+				if (force) scheduleStatsRefresh();
+				else if (!statsCache.computing && Date.now() - statsCache.at > STATS_TTL_MS) scheduleStatsRefresh();
+				const cached = statsCache.payload;
+				if (cached) {
+					sendJson(res, 200, { ...cached, cached: true });
+					return;
+				}
+				// No cache yet (first request after boot, scan still warming). Return
+				// immediately with a "computing" marker instead of blocking on the scan.
+				sendJson(res, 200, { status: "computing", cached: false });
+			} catch (error) {
+				ctx.logger.warn(error instanceof Error ? error : new Error(String(error)));
+				sendJson(res, 500, { status: "error", message: String(error) });
+			}
+		}
+	});
+
+	// --- route: balance (with cache + ?force=1) ---
+	let balanceCache = { at: 0, payload: null };
+	ctx.webServer.register({
+		kind: "exact",
+		path: "/api/token-dashboard/balance",
+		handler: async (req, res) => {
+			try {
+				const url = new URL(req.url ?? "/", "http://x");
+				const force = url.searchParams.get("force") === "1";
+				const now = Date.now();
+				if (!force && balanceCache.payload && now - balanceCache.at < balanceCacheMs) {
+					sendJson(res, 200, { ...balanceCache.payload, cached: true });
+					return;
+				}
+				// Resolve the DeepSeek API key from DSH credentials (service fetched
+				// lazily via ctx.get, mirroring dsh-llm-deepseek's own key path).
+				let apiKey;
+				try {
+					const credentials = ctx.get("credentials");
+					const hit = credentials?.resolve ? await credentials.resolve("DEEPSEEK_API_KEY") : null;
+					apiKey = typeof hit === "string" ? hit : (hit?.value ?? null);
+				} catch {
+					apiKey = null;
+				}
+				if (!apiKey) apiKey = process.env.DEEPSEEK_API_KEY || null;
+				const payload = await fetchBalance(apiKey);
+				balanceCache = { at: now, payload };
+				sendJson(res, 200, { ...payload, cached: false });
+			} catch (error) {
+				ctx.logger.warn(error instanceof Error ? error : new Error(String(error)));
+				sendJson(res, 500, { status: "error", message: String(error) });
+			}
+		}
+	});
+
+	ctx.logger.info(`[token-dashboard] mounted; sessionsRoot=${sessionsRoot}`);
+}
+
+export const inject = ["webServer"];
+export const name = "token-dashboard";
+
+// Re-export helpers for the standalone workspace self-test (not used by Cordis).
+export { aggregateTokens, zstdDecompressToText, findSessionLogs };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@lyk308/dsh-token-dashboard",
+  "version": "0.1.0",
+  "description": "DeepSeek Harness 实时看板：账户余额 + Token 使用量（按模型/工作区/缓存命中），本地读取会话日志 + DeepSeek /user/balance。",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-primitives"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "token",
+    "balance",
+    "usage",
+    "dashboard"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lyk308/dsh-token-dashboard.git"
+  },
+  "homepage": "https://github.com/lyk308/dsh-token-dashboard"
+}