@wannanbigpig/dsh-usage-stats 0.1.2 → 0.1.4

package/README.md

@@ -133,7 +133,7 @@ DEEPSEEK_API_KEY: sk-your-key-here
 
 ### 用量提醒与限额（设置 → 用量与计费）
 
-「设置 → 用量与计费」页面承载限额配置（已从查询弹窗迁出，弹窗保持只读）。可**按 Key（或全局）**配置：
+「设置 → 用量与计费」页面承载限额配置（已从查询弹窗迁出，弹窗保持只读）。可**按 Key（或全局）**配置；**仅配置一个 API Key 时，「目标 API Key」选择器自动隐藏**，直接配置全局规则即可（单 Key 下全局规则就是生效规则）：
 
 - **启用限额**：开关。
 - **每日消费限额**（CNY）：今日估算消费达到限额 × `alertPercent`（默认 80%）→ 黄色预警；达到限额 × `criticalPercent`（默认 90%）→ 红色已超限（仅提醒与告警，不拦截）；两个比例都可在设置页调整。
@@ -143,7 +143,7 @@ DEEPSEEK_API_KEY: sk-your-key-here
 
 限额保存在 `~/.dsh/storages/usage-limits.json`，当前 schema 为 v2。旧 v1 文件会安全迁移：保留提醒规则，但不会自动继承旧 `stopOnExceed` / `minBalance` 为硬停止；用户需在设置页重新确认开启。v2 会拒绝未知配置字段。**规则解析采用全局兜底**：某个 Key 未设置数值（或仅有空壳规则）时，沿用全局限额；Key 设置了数值则覆盖全局、未设置的字段继续继承全局，因此全局限额始终是底线，不会被空壳 Key 规则静默绕过。拦截采用 **fail-open** 策略：限额检查本身出错时放行调用，绝不因插件故障阻塞模型。
 
-状态统一为 `normal / warning / exceeded / blocked / stale / unavailable`。侧栏状态点与设置页读取同一个 `/limits` 状态源；告警只在状态跨越或冷却到期时触发，恢复正常时生成一次恢复事件，避免每次轮询或模型请求重复提醒。
+状态统一为 `normal / warning / exceeded / blocked / stale / unavailable / unpriced`（`unpriced`：当日用量含未定价模型，消费金额不可靠，日限额不参与拦截且 fail-open；硬停止消息会点名真实触发原因——达到 100% 每日限额或余额跌破保障线，而非 90% 预警文案）。侧栏状态点与设置页读取同一个 `/limits` 状态源；告警只在状态跨越或冷却到期时触发，恢复正常时生成一次恢复事件，避免每次轮询或模型请求重复提醒。
 
 默认单价（CNY / 1M tokens，严格对应 DeepSeek 官方中文价格页，2026-08）：
 

package/lib/client.js

@@ -673,7 +673,7 @@ window.__ModuleLoader__.load({
 			}
 
 			function limitStatusLabelKey(status) {
-				return ["normal", "warning", "exceeded", "blocked", "stale", "unavailable"].includes(status)
+				return ["normal", "warning", "exceeded", "blocked", "stale", "unavailable", "unpriced"].includes(status)
 					? `limits.status.${status}`
 					: "limits.status.normal";
 			}
@@ -1095,13 +1095,18 @@ window.__ModuleLoader__.load({
 			const [limits, setLimits] = react.useState(null);
 			const limitsRef = react.useRef(null);
 			const [statusMap, setStatusMap] = react.useState({});
+			const isSingleKey = (keys || []).length <= 1;
 			const [activeKey, setActiveKey] = react.useState(() => {
+				if (isSingleKey) return "__global__";
 				const stored = safeGetStorage("dsh_usage_limits_active_key");
 				if (stored !== null && stored !== "") return stored;
 				return selectedKey ?? "__global__";
 			});
 			const [saving, setSaving] = react.useState(false);
 			const [error, setError] = react.useState(null);
+			// 限额文档未加载完成前禁用表单：GET 失败时 limits 恒为 null，若仍可保存会
+			// 以空文档为基底 POST，整体覆盖并清空服务器上的全部限额配置。
+			const [loaded, setLoaded] = react.useState(false);
 			const pendingRef = react.useRef(null);
 			const debounceTimerRef = react.useRef(null);
 			const savingRef = react.useRef(false);
@@ -1122,6 +1127,7 @@ window.__ModuleLoader__.load({
 						limitsRef.current = payload.limits;
 						setLimits(payload.limits);
 						setStatusMap(payload.status || {});
+						setLoaded(true);
 					}
 				} catch (err) {
 					setError(err instanceof Error ? err.message : String(err));
@@ -1134,6 +1140,10 @@ window.__ModuleLoader__.load({
 
 			// Sync activeKey when selectedKey becomes available (if not explicitly chosen in storage)
 			react.useEffect(() => {
+				if (isSingleKey) {
+					setActiveKey("__global__");
+					return;
+				}
 				if (selectedKey !== null && selectedKey !== undefined && selectedKey !== "") {
 					const stored = safeGetStorage("dsh_usage_limits_active_key");
 					if (stored) {
@@ -1142,7 +1152,7 @@ window.__ModuleLoader__.load({
 					}
 					setActiveKey(selectedKey);
 				}
-			}, [selectedKey]);
+			}, [selectedKey, isSingleKey]);
 
 			// Update form fields when activeKey or limits payload change
 			react.useEffect(() => {
@@ -1160,6 +1170,7 @@ window.__ModuleLoader__.load({
 			}, [activeKey, limits]);
 
 			const handleKeySelect = (newKey) => {
+				if (isSingleKey) return;
 				// Do not strand an unsaved batch on the previous key's form.
 				if (pendingRef.current !== null && !savingRef.current) flushSave();
 				setActiveKey(newKey);
@@ -1196,6 +1207,7 @@ window.__ModuleLoader__.load({
 			};
 
 			const handleSave = async (overrideRule, immediate = false) => {
+				if (!loaded) return;
 				// Debounce + latest-value compensation: every change replaces the
 				// pending batch with a full rule snapshot, so the flush always sends
 				// the newest values even while a previous request is still in flight.
@@ -1304,10 +1316,9 @@ window.__ModuleLoader__.load({
 							})
 						]
 					}),
-					react_jsx_runtime.jsx("p", { className: S.note, children: translate("limits.desc") }),
 					error && react_jsx_runtime.jsx("div", { className: S.error, children: error }),
-					// Key selection
-					react_jsx_runtime.jsxs("label", {
+					// Key selection — hidden when only one key is configured (the global rule IS the key rule).
+					keys.length > 1 && react_jsx_runtime.jsxs("label", {
 						className: S.pickerRow,
 						children: [
 							react_jsx_runtime.jsxs("span", {
@@ -1369,6 +1380,7 @@ window.__ModuleLoader__.load({
 										react_jsx_runtime.jsx("input", {
 											type: "checkbox",
 											checked: enabled,
+											disabled: !loaded,
 											onChange: (e) => {
 												const nextVal = e.target.checked;
 												setEnabled(nextVal);
@@ -1390,6 +1402,7 @@ window.__ModuleLoader__.load({
 										react_jsx_runtime.jsx("input", {
 											type: "checkbox",
 											checked: stopOnExceed,
+											disabled: !loaded,
 											onChange: (e) => {
 												const nextVal = e.target.checked;
 												setStopOnExceed(nextVal);
@@ -2122,14 +2135,20 @@ window.__ModuleLoader__.load({
 									className: S.sidebarText,
 									children: [
 										react_jsx_runtime.jsx("span", { className: S.sidebarLabel, children: t("panel.badge") }),
-								react_jsx_runtime.jsxs("span", {
+									react_jsx_runtime.jsxs("span", {
 									className: S.sidebarSummary,
 									title: summaryText,
 									children: [
-										summary.balanceStatus !== "muted" ? react_jsx_runtime.jsx("span", { className: S.statusDot, "data-tone": summary.balanceStatus }) : null,
-										summary.todayStatus !== "muted" ? react_jsx_runtime.jsx("span", { className: S.statusDot, "data-tone": summary.todayStatus }) : null,
-										summaryText
-									]
+										react_jsx_runtime.jsxs("span", { className: S.statusItem, children: [
+											summary.balanceStatus !== "muted" ? react_jsx_runtime.jsx("span", { className: S.statusDot, "data-tone": summary.balanceStatus }) : null,
+											`余额 ${summary.balance}`
+										] }),
+										" · ",
+										react_jsx_runtime.jsxs("span", { className: S.statusItem, children: [
+											summary.todayStatus !== "muted" ? react_jsx_runtime.jsx("span", { className: S.statusDot, "data-tone": summary.todayStatus }) : null,
+											`今日 ${summary.today}`
+										] })
+								]
 								})
 									]
 								})
@@ -2202,7 +2221,6 @@ window.__ModuleLoader__.load({
 			"chart.inputWithCache": "输入（含缓存）",
 			"chart.peakNote": "高峰：北京时间 09-12 / 14-18，费用×2",
 			"limits.title": "用量提醒与限额设置",
-			"limits.desc": "按指定 API Key 或全局设置每日消费限额与预警比例；硬停止默认关闭，仅在主动开启后阻止新调用。",
 			"limits.apiKey": "目标 API Key",
 			"limits.global": "全局默认 (全部 Key)",
 			"limits.enable": "启用用量提醒",
@@ -2226,6 +2244,7 @@ window.__ModuleLoader__.load({
 			"limits.status.blocked": "已停止新调用",
 			"limits.status.stale": "余额数据已过期",
 			"limits.status.unavailable": "余额暂不可用",
+			"limits.status.unpriced": "费用不可靠（含未定价模型）",
 			"limits.status.unlimited": "未限制",
 			"limits.progress": "今日已消费 {spent} / 限额 {limit} ({percent}%)",
 			"limits.save": "保存设置",
@@ -2302,7 +2321,6 @@ window.__ModuleLoader__.load({
 			"chart.inputWithCache": "Input (incl. cache)",
 			"chart.peakNote": "Peak: Beijing 09-12 / 14-18, ×2 price",
 			"limits.title": "Usage Alerts & Quota Limits",
-			"limits.desc": "Configure daily spend limits and alert thresholds per API key or globally. Hard stop is off by default and only blocks new calls after you opt in.",
 			"limits.apiKey": "Target API Key",
 			"limits.global": "Global Default (All Keys)",
 			"limits.enable": "Enable Usage Alerts",
@@ -2326,6 +2344,7 @@ window.__ModuleLoader__.load({
 			"limits.status.blocked": "New Calls Blocked",
 			"limits.status.stale": "Balance Data Stale",
 			"limits.status.unavailable": "Balance Unavailable",
+			"limits.status.unpriced": "Cost Unreliable (Unpriced Models)",
 			"limits.status.unlimited": "No Limit",
 			"limits.progress": "Spent today {spent} / Limit {limit} ({percent}%)",
 			"limits.save": "Save Settings",

package/lib/index.js

@@ -361,6 +361,10 @@ function parseLedger(raw) {
 		appendLedger(ledger, {
 			id: entry.id,
 			occurredAt: entry.occurredAt,
+			// completedAt 是账本按完成时间归小时/判峰谷的基准；缺省回退发起时间
+			// （与 ledger.js 的 attribution 契约一致），否则 loadCache 按 completedAt
+			// 过滤会把账本在每次重启后整体清空。
+			completedAt: entry.completedAt ?? entry.occurredAt,
 			provider: entry.provider,
 			model: entry.model,
 			usage: entry.usage,
@@ -524,7 +528,7 @@ async function saveCache(ctx, cache) {
 	}
 }
 
-/** Single-flight guard: concurrent requests share one aggregation run. */
+/** Single-flight guard for READ-side aggregation: concurrent renders share one run. */
 function withLock(run) {
 	if (inflight !== null) return inflight;
 	inflight = run().finally(() => {
@@ -532,6 +536,20 @@ function withLock(run) {
 	});
 	return inflight;
 }
+
+/**
+ * Serialized WRITE queue for ledger persistence: every call executes in
+ * order and none is dropped. A single-flight guard would silently discard
+ * the second concurrent completion (parallel tool calls are common) and
+ * undercount billing; sharing the read lock also made collectUsage return
+ * a ledger entry instead of the usage payload.
+ */
+let writeChain = Promise.resolve();
+function serializeWrite(run) {
+	const result = writeChain.then(run);
+	writeChain = result.then(() => void 0, () => void 0);
+	return result;
+}
 //#endregion
 
 /**
@@ -894,7 +912,10 @@ function todayKeyLocal() {
 /** Build the per-key status map once, shared by evaluateStatus/evaluateAll. */
 async function evaluateStatuses({ ctx, config, balanceService, limits, usage, today, deps }) {
 	const dayEntry = (usage.days ?? []).find((d) => d.date === today);
-	const globalTodayCost = dayEntry?.cost ?? 0;
+	// 当日任一模型未定价（未知模型 id / 缺 model）→ day.cost 为 null：消费金额
+	// 不可靠，绝不能静默当成 0 消费（否则日限额/硬停止整日失效）。
+	const costReliable = dayEntry === void 0 || dayEntry.cost !== null;
+	const globalTodayCost = dayEntry === void 0 ? 0 : (dayEntry.cost ?? 0);
 	const { perKey } = todayCostPerKey(usage.days, today, config);
 	const keys = [...new Set([...config.keys, ...Object.keys(limits.keys)])];
 	// First pass: collect the refs whose cached balance is stale or missing.
@@ -928,6 +949,7 @@ async function evaluateStatuses({ ctx, config, balanceService, limits, usage, to
 			keyRef: ref,
 			limits,
 			todayCost: todayCostFor(ref, perKey, globalTodayCost, config),
+			todayCostReliable: costReliable,
 			balance: account?.balance ?? null,
 			balanceStatus: account?.status,
 			balanceFetchedAt: account?.fetchedAt,
@@ -958,7 +980,9 @@ function resolveLimitRule(allLimits, keyRef) {
 	// inherit the global for any field left unset (null), so the global stays
 	// the floor and a key can only tighten — never silently opt out.
 	return {
-		enabled: keyRule.enabled,
+		// Key 只能收紧、不能静默退出：全局开启时，Key 的 enabled:false 不得
+		// 关掉整个限额（与 stopOnExceed 的 OR 语义一致）。
+		enabled: keyRule.enabled === true || global.enabled === true,
 		period: keyRule.period ?? global.period ?? "daily",
 		dailyCostLimit: keyRule.dailyCostLimit ?? global.dailyCostLimit ?? null,
 		monthlyCostLimit: keyRule.monthlyCostLimit ?? global.monthlyCostLimit ?? null,
@@ -971,7 +995,7 @@ function resolveLimitRule(allLimits, keyRef) {
 	};
 }
 
-function evaluateKeyQuota({ keyRef, limits, todayCost = 0, balance = null, balanceStatus, balanceFetchedAt, now = Date.now(), balanceMaxAgeMs = Infinity }) {
+function evaluateKeyQuota({ keyRef, limits, todayCost = 0, todayCostReliable = true, balance = null, balanceStatus, balanceFetchedAt, now = Date.now(), balanceMaxAgeMs = Infinity }) {
 	const allLimits = limits ?? defaultLimits();
 	const rule = resolveLimitRule(allLimits, keyRef);
 	const numericCost = Number(todayCost) || 0;
@@ -1028,8 +1052,9 @@ function evaluateKeyQuota({ keyRef, limits, todayCost = 0, balance = null, balan
 	let reason = null;
 	let message = "";
 
-	// Check daily cost limit
-	if (rule.dailyCostLimit !== null && rule.dailyCostLimit > 0) {
+	// Check daily cost limit (skipped when today's cost is unreliable: any
+	// unpriced model makes the amount unknowable — never treat it as zero).
+	if (todayCostReliable !== false && rule.dailyCostLimit !== null && rule.dailyCostLimit > 0) {
 		if (numericCost >= rule.dailyCostLimit * (rule.criticalPercent / 100)) {
 			exceeded = true;
 			reason = "daily_cost";
@@ -1046,15 +1071,33 @@ function evaluateKeyQuota({ keyRef, limits, todayCost = 0, balance = null, balan
 		message = `余额 (${numericBalance.toFixed(2)}) 已低于警戒线 (${rule.minBalance.toFixed(2)})`;
 	}
 
+	const unpriced = todayCostReliable === false;
+	if (unpriced && reason === null) {
+		reason = "unpriced";
+		message = "今日用量包含未定价模型，消费金额不可靠，日限额暂不参与拦截";
+	}
 	const spendStatus = rule.dailyCostLimit !== null && rule.dailyCostLimit > 0
-		? (exceeded ? "exceeded" : (warning ? "warning" : "normal"))
+		? (exceeded ? "exceeded" : (warning ? "warning" : (unpriced ? "muted" : "normal")))
 		: "muted";
-	const hardLimitReached = balanceExceeded || (rule.dailyCostLimit !== null && rule.dailyCostLimit > 0 && numericCost >= rule.dailyCostLimit);
-	const status = exceeded && rule.stopOnExceed && hardLimitReached
-		? "blocked"
+	const costLimitReached = rule.dailyCostLimit !== null && rule.dailyCostLimit > 0 && numericCost >= rule.dailyCostLimit;
+	const hardLimitReached = balanceExceeded || costLimitReached;
+	const blocked = exceeded && rule.stopOnExceed && hardLimitReached;
+	// 硬停止消息必须点明真实触发原因（达到 100% 限额或余额跌破保障线），
+	// 不能沿用 90% 预警文案——否则用户会误以为在 90% 就被拦截。
+	if (blocked) {
+		if (balanceExceeded) {
+			reason = "min_balance";
+			message = `余额 (${numericBalance.toFixed(2)}) 已低于最低余额保障线 (${rule.minBalance.toFixed(2)})，已停止新调用`;
+		} else if (costLimitReached) {
+			reason = "daily_cost";
+			message = `今日消费 (${numericCost.toFixed(2)}) 已达到每日限额 (${rule.dailyCostLimit.toFixed(2)})，已停止新调用`;
+		}
+	}
+	const status = blocked ? "blocked"
 		: exceeded ? "exceeded"
 			: warning ? "warning"
-				: stale ? "stale"
+				: unpriced ? "unpriced"
+					: stale ? "stale"
 					: unavailable ? "unavailable"
 						: balanceAlertStatus === "warning" || balanceAlertStatus === "exceeded" ? balanceAlertStatus : "normal";
 	if (reason === null && stale) {
@@ -1147,7 +1190,7 @@ const DEFAULT_MAX_LEDGER_ENTRIES = 5000;
  * @param deps - optional { maxLedgerEntries }; the two-arg call stays valid.
  */
 async function recordLedgerEntry(ctx, entry, deps = {}) {
-	return withLock(async () => {
+	return serializeWrite(async () => {
 		const cache = await loadCache();
 		appendLedger(cache.ledger, entry);
 		const maxEntries = Number.isFinite(Number(deps?.maxLedgerEntries)) && Number(deps.maxLedgerEntries) > 0
@@ -1183,7 +1226,14 @@ function createLimitsService({ ctx, config, balanceService, deps = {} }) {
 	}
 
 	async function updateLimits(raw) {
-		const validated = validateLimits(raw);
+		// 空/畸形 body（null、{}、无 global/keys）会把配置静默重置为默认值并
+		// 持久化，清空全部限额规则——客户端总是在加载完成后发送完整文档，
+		// 因此拒绝这类载荷是安全的。
+		const body = raw === null || typeof raw !== "object" || Array.isArray(raw) ? null : raw;
+		if (body === null || (typeof body.global !== "object" && typeof body.keys !== "object")) {
+			throw new TypeError("limits payload must carry a global rule or a keys map");
+		}
+		const validated = validateLimits(body);
 		await (deps.saveLimits ?? saveLimits)(ctx, validated);
 		memoryLimits = validated;
 		return validated;
@@ -1241,6 +1291,10 @@ async function handleLimits(ctx, config, limitsService, req, res) {
 		}
 	} catch (error) {
 		ctx.logger.warn(`usage-stats: limits request failed: ${String(error)}`);
+		if (error instanceof TypeError) {
+			json(res, 400, { ok: false, error: "invalid-payload", message: error.message });
+			return;
+		}
 		json(res, 500, { ok: false, error: "internal", message: error instanceof Error ? error.message : String(error) });
 	}
 }
@@ -1379,6 +1433,7 @@ export {
 	roundCost,
 	defaultLimitRule,
 	defaultLimits,
+	parseLedger,
 	validateLimitRule,
 	validateLimits,
 	evaluateKeyQuota,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wannanbigpig/dsh-usage-stats",
   "description": "DeepSeek 官方余额、Token 用量、月历热图与离线 tokenizer，内置在 Harness 侧栏",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/wannanbigpig/dsh-usage-stats.git"