@kenz1117/dsh-ui-usage-billing 0.9.16 → 0.9.18

package/lib/index.js

@@ -1057,11 +1057,58 @@ function hourStamp(time) {
 	const pad = (n) => String(n).padStart(2, "0");
 	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}`;
 }
+/**
+* 宿主进程的 IANA 时区名与 UTC 偏移，供面板标注「天按哪个时区切分」。
+* `getTimezoneOffset` 是 UTC 以西的分钟数，符号与日常写法相反，故取反。
+* @returns `{ name, offset }`，如 `{ name: "Asia/Shanghai", offset: "UTC+08:00" }`。
+*/
+function hostTimeZone(now = /* @__PURE__ */ new Date()) {
+	const minutes = -now.getTimezoneOffset();
+	const sign = minutes < 0 ? "-" : "+";
+	const abs = Math.abs(minutes);
+	const hh = String(Math.floor(abs / 60)).padStart(2, "0");
+	const mm = String(abs % 60).padStart(2, "0");
+	let name;
+	try {
+		name = Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+	} catch {
+		name = "UTC";
+	}
+	return {
+		name,
+		offset: `UTC${sign}${hh}:${mm}`
+	};
+}
 /** 工作区名：取 cwd 的末级目录名；无 cwd 时返回 {@link UNKNOWN_WORKSPACE_NAME}。 */
 function workspaceNameOf(cwd) {
 	if (cwd === void 0 || cwd === "") return "—";
 	return cwd.split(/[\\/]/).filter(Boolean).at(-1) ?? "—";
 }
+/**
+* 账本迁移注册表。当前账本 schema（version 1）尚无字段变更需求，故为空表；
+* 机制已就绪，schema 变更时在此登记幂等迁移，见 {@link LedgerMigration}。
+*/
+const LEDGER_MIGRATIONS = [];
+/**
+* 在加载边界对账本文档应用未执行的迁移，并记录已应用 id 供写回。
+* @param document - 从持久化读出的原始账本文档。
+* @param migrations - 待执行的迁移注册表；缺省用模块级 {@link LEDGER_MIGRATIONS}。
+* @returns 是否发生了需要重新落盘的修改。
+*/
+function runLedgerMigrations(document, migrations = LEDGER_MIGRATIONS) {
+	const applied = new Set(document.appliedMigrations ?? []);
+	let changed = false;
+	for (const migration of migrations) {
+		if (applied.has(migration.id)) continue;
+		if (migration.apply(document)) changed = true;
+		applied.add(migration.id);
+	}
+	if (applied.size > 0 && (document.appliedMigrations === void 0 || document.appliedMigrations.length !== applied.size || document.appliedMigrations.some((id) => !applied.has(id)))) {
+		document.appliedMigrations = [...applied];
+		changed = true;
+	}
+	return changed;
+}
 /** Serialize Map/Set-heavy fold state into a JSON-safe ledger entry. */
 function serializeFold(fold) {
 	return {
@@ -1168,6 +1215,11 @@ function turnState(turns, turn) {
 * @returns the per-session fold (cached by the incremental aggregator).
 */
 function foldSession(events, subscriptionProviders, officialProviderIds, routes = {}) {
+	let seedBoundary = -1;
+	for (const event of events) if (event.type === "session/end-seed" && typeof event.seq === "number" && Number.isFinite(event.seq)) seedBoundary = Math.max(seedBoundary, event.seq);
+	if (seedBoundary >= 0) {
+		if (!events.some((event) => typeof event.seq === "number" && Number.isFinite(event.seq) && event.seq > seedBoundary)) seedBoundary = -1;
+	}
 	const fold = {
 		total: emptyUsage(),
 		byModel: /* @__PURE__ */ new Map(),
@@ -1194,6 +1246,7 @@ function foldSession(events, subscriptionProviders, officialProviderIds, routes
 	const steps = /* @__PURE__ */ new Map();
 	let lastOpenStepKey;
 	for (const event of events) {
+		if (seedBoundary >= 0 && typeof event.seq === "number" && Number.isFinite(event.seq) && event.seq < seedBoundary) continue;
 		fold.lastActive = Math.max(fold.lastActive, event.time);
 		if (event.type === "session/title") {
 			const title = event.data.title;
@@ -1395,6 +1448,9 @@ function createUsageAggregator(persistence, options = {}) {
 		ledgerLoaded = true;
 		try {
 			const stored = await options.ledger.load();
+			if (stored !== null && typeof stored === "object" && stored.sessions !== void 0) {
+				if (runLedgerMigrations(stored)) ledgerNeedsSave = true;
+			}
 			for (const entry of ledgerSessionsOf(stored)) ledger.set(entry.id, entry);
 		} catch (error) {
 			console.warn("[usage-billing] failed to load durable usage ledger; rebuilding from current sessions:", error);
@@ -1625,6 +1681,7 @@ function createUsageAggregator(persistence, options = {}) {
 			version: 3,
 			updatedAt: now,
 			source: "session-logs",
+			timezone: hostTimeZone(),
 			total,
 			byModel: toRecord(byModel),
 			byDay: toRecord(byDay),
@@ -1739,7 +1796,7 @@ function createCooldownGate(options = {}) {
 * provider's key once and every surface reuses it.
 */
 /** Abort a balance fetch when the upstream hangs beyond this budget. */
-const FETCH_TIMEOUT_MS$2 = 8e3;
+const FETCH_TIMEOUT_MS$3 = 8e3;
 /**
 * 每平台熔断门：单个 provider 连续可重试失败（网络波动 / 5xx / 429）达阈值后
 * 短路一段真实时间，避免 30 秒轮询在已不可用的上游上反复打满超时。
@@ -1767,7 +1824,7 @@ const XAI_CREDITS_URL = "https://api.x.ai/v1/billing/credits";
 /** 智谱 GLM（大模型国内域）官方余额接口（open.bigmodel.cn/api/paas/v4/balance）。 */
 const ZHIPU_BALANCE_URL = "https://open.bigmodel.cn/api/paas/v4/balance";
 /** 数字归一化：接口返回的余额是字符串（如 `"110.00"`），统一转 number。 */
-function toNumber(value) {
+function toNumber$1(value) {
 	if (typeof value === "number" && Number.isFinite(value)) return value;
 	if (typeof value === "string") {
 		const parsed = Number(value);
@@ -1800,7 +1857,7 @@ async function queryBearerBalance(ctx, url, apiKeyEnv, provider, displayName, pa
 	};
 	const doRequest = async () => {
 		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS$2);
+		const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS$3);
 		try {
 			const response = await fetch(url, {
 				headers: {
@@ -1860,9 +1917,9 @@ function queryDeepSeek(ctx, apiKeyEnv) {
 		const doc = data;
 		const info = (Array.isArray(doc.balance_infos) ? doc.balance_infos : [])[0];
 		const currency = typeof info?.currency === "string" ? info.currency : void 0;
-		const totalBalance = toNumber(info?.total_balance);
-		const grantedBalance = toNumber(info?.granted_balance);
-		const toppedUpBalance = toNumber(info?.topped_up_balance);
+		const totalBalance = toNumber$1(info?.total_balance);
+		const grantedBalance = toNumber$1(info?.granted_balance);
+		const toppedUpBalance = toNumber$1(info?.topped_up_balance);
 		const isAvailable = typeof doc.is_available === "boolean" ? doc.is_available : void 0;
 		return {
 			provider: "deepseek",
@@ -1884,9 +1941,9 @@ function queryDeepSeek(ctx, apiKeyEnv) {
 function queryMoonshot(ctx, apiKeyEnv) {
 	return queryBearerBalance(ctx, MOONSHOT_BALANCE_URL, apiKeyEnv, "月之暗面", "月之暗面", (data) => {
 		const doc = data;
-		const totalBalance = toNumber(doc.data?.available_balance);
-		const grantedBalance = toNumber(doc.data?.voucher_balance);
-		const toppedUpBalance = toNumber(doc.data?.cash_balance);
+		const totalBalance = toNumber$1(doc.data?.available_balance);
+		const grantedBalance = toNumber$1(doc.data?.voucher_balance);
+		const toppedUpBalance = toNumber$1(doc.data?.cash_balance);
 		return {
 			provider: "月之暗面",
 			displayName: "月之暗面",
@@ -1906,9 +1963,9 @@ function queryMoonshot(ctx, apiKeyEnv) {
 function queryStepFun(ctx, apiKeyEnv) {
 	return queryBearerBalance(ctx, STEPFUN_BALANCE_URL, apiKeyEnv, "阶跃星辰", "阶跃星辰", (data) => {
 		const doc = data;
-		const totalBalance = toNumber(doc.balance);
-		const toppedUpBalance = toNumber(doc.total_cash_balance);
-		const grantedBalance = toNumber(doc.total_voucher_balance);
+		const totalBalance = toNumber$1(doc.balance);
+		const toppedUpBalance = toNumber$1(doc.total_cash_balance);
+		const grantedBalance = toNumber$1(doc.total_voucher_balance);
 		return {
 			provider: "阶跃星辰",
 			displayName: "阶跃星辰",
@@ -1929,7 +1986,7 @@ function querySiliconFlow(ctx, apiKeyEnv) {
 	return queryBearerBalance(ctx, SILICONFLOW_BALANCE_URL, apiKeyEnv, "硅基流动", "硅基流动", (data) => {
 		const doc = data;
 		const inner = doc.data ?? doc;
-		const totalBalance = toNumber(inner.balance ?? inner.balance_cny);
+		const totalBalance = toNumber$1(inner.balance ?? inner.balance_cny);
 		return {
 			provider: "硅基流动",
 			displayName: "硅基流动",
@@ -1946,7 +2003,7 @@ function querySiliconFlow(ctx, apiKeyEnv) {
 */
 function queryXai(ctx, apiKeyEnv) {
 	return queryBearerBalance(ctx, XAI_CREDITS_URL, apiKeyEnv, "xAI", "xAI", (data) => {
-		const cents = toNumber(data.total?.val);
+		const cents = toNumber$1(data.total?.val);
 		const totalBalance = cents === void 0 ? void 0 : Math.abs(cents) / 100;
 		return {
 			provider: "xAI",
@@ -1968,7 +2025,7 @@ function queryXai(ctx, apiKeyEnv) {
 function queryZhipu(ctx, apiKeyEnv) {
 	return queryBearerBalance(ctx, ZHIPU_BALANCE_URL, apiKeyEnv, "智谱 AI", "智谱 AI", (data) => {
 		const doc = data;
-		const totalBalance = toNumber(doc.balance?.available) ?? toNumber(doc.balance?.total);
+		const totalBalance = toNumber$1(doc.balance?.available) ?? toNumber$1(doc.balance?.total);
 		return {
 			provider: "智谱 AI",
 			displayName: "智谱 AI",
@@ -2055,13 +2112,13 @@ function evalExtract(rule, data) {
 		if (paths.length === 0) return void 0;
 		let total;
 		for (const path of paths) {
-			const value = toNumber(getPath(data, path));
+			const value = toNumber$1(getPath(data, path));
 			if (value === void 0) return void 0;
 			total = total === void 0 ? value : rule.op === "add" ? total + value : total - value;
 		}
 		return total;
 	}
-	const base = typeof rule.path === "string" ? toNumber(getPath(data, rule.path)) : void 0;
+	const base = typeof rule.path === "string" ? toNumber$1(getPath(data, rule.path)) : void 0;
 	if (base === void 0) return void 0;
 	if (rule.op === "divide") {
 		const by = rule.by;
@@ -2115,7 +2172,7 @@ async function queryCustomBalances(ctx, configs) {
 		};
 		const doRequest = async () => {
 			const controller = new AbortController();
-			const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS$2);
+			const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS$3);
 			try {
 				const response = await fetch(config.url, {
 					method: config.method ?? "GET",
@@ -2170,6 +2227,383 @@ async function queryCustomBalances(ctx, configs) {
 	}));
 }
 //#endregion
+//#region lib/types/declarative.js
+/**
+* 声明端点（declarative endpoints）：让用户为内置表没有的供应商自声明余额/额度接口，
+* 不用等插件发版。用户提供「数字在哪儿」的取值路径，而非「怎么取」——没有表达式、
+* 没有任何东西被求值，`fields` / `windows` 里写的只是响应 JSON 的点路径，唯一操作是
+* 逐层下钻。
+*
+* ## 为什么把安全边界写在代码里而不是建议里
+*
+* 这个功能让**配置文件**决定一个携带用户 API key 的请求发往哪里。风险全在此，靠
+* 「提醒用户小心」一点都没用：
+*
+* 1. `origin` 只是查找键：请求 URL 由**匹配到的 provider 的 origin** 构造，绝不由
+*    声明的 origin 自己决定。匹配不到任何已配置的 provider 就不发请求。
+* 2. `path` 必须单斜杠绝对路径：`//evil.example/x` 是协议相对 URL，`new URL()` 会
+*    把它解析到别的主机；构造后还会再校验一次 origin。
+* 3. 只发 GET，无请求体，无自定义 method / headers。
+* 4. 凭据仍从匹配 provider 自己的 `apiKeyEnv` 取，经同一凭据 seam 解析；声明不能
+*    指定任何凭据。
+* 5. 跨源重定向直接失败，不跟随——那是绕过第 1 条最省事的办法。
+* 6. 响应体有大小上限与共享超时，坏 / 恶意端点拖不住面板。
+* 7. 声明不能覆盖内置读法：只在内置表答不上来时它才轮到。
+*
+* 这类行会标 `declared`，因为数字来自用户自己写的路径——取错是配置问题，界面要让
+* 这一点看得出来；全部字段都没取到时给 `reason`，而不是留一张和「上游没返回」无从
+* 区分的空卡。
+*/
+/** Abort a declared fetch when the upstream hangs beyond this budget. */
+const FETCH_TIMEOUT_MS$2 = 8e3;
+/** 响应体上限（字节）：坏 / 恶意端点不能拖住面板或耗尽内存。 */
+const MAX_BODY_BYTES = 1e6;
+/** 声明端点查询的熔断门：按（匹配 provider origin + path）独立熔断，各端点互不干扰。 */
+const declaredGate = createCooldownGate({
+	failures: 3,
+	cooldownMs: 6e4
+});
+/** 会触及原型链的路径段：一律拒绝（读结果不是文档自带字段）。 */
+const FORBIDDEN_SEGMENTS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/**
+* 归一化 baseURL 为可比的 origin：`scheme://host[:port]`，剥掉 scheme 的默认端口，
+* host 转小写，忽略路径。无法解析返回 undefined。
+* @param baseURL - provider 的端点地址，或声明里的 origin。
+*/
+function normalizeDeclaredOrigin(baseURL) {
+	if (typeof baseURL !== "string" || baseURL.trim() === "") return void 0;
+	let url;
+	try {
+		url = new URL(baseURL.trim());
+	} catch {
+		return;
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") return void 0;
+	const defaultPort = url.protocol === "https:" ? "443" : "80";
+	const port = url.port === "" || url.port === defaultPort ? "" : `:${url.port}`;
+	return `${url.protocol}//${url.hostname.toLowerCase()}${port}`;
+}
+/**
+* 沿点路径走进已解析的响应体。
+* 任何失败都是同一个答案 `undefined`——路径不匹配是这份响应没有那个字段，是卡片
+* 本来就渲染得了的事实，不是错误，而且不该让已解析成功的字段被牵连。
+* @param body - 已解析的响应 JSON。
+* @param path - 点路径（如 `data.balance`）。
+* @returns 路径处的值，或 undefined（路径缺失 / 中途不是对象 / 命中原型链）。
+*/
+function readDeclaredPath(body, path) {
+	if (typeof path !== "string" || path === "") return void 0;
+	let cursor = body;
+	for (const segment of path.split(".")) {
+		if (cursor === null || typeof cursor !== "object") return void 0;
+		if (FORBIDDEN_SEGMENTS.has(segment)) return void 0;
+		cursor = cursor[segment];
+	}
+	return cursor;
+}
+/** 数字常以字符串抵达（如 `"110.00"`），统一转 number；非有限数返回 undefined。 */
+function toNumber(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+}
+/** 百分比收敛到 0–100。 */
+function clampPercent$2(value) {
+	return Math.round(Math.max(0, Math.min(100, value)) * 10) / 10;
+}
+/** 解出一个窗口的已用百分比：usedPercent 路径 > usedRatio 路径 > used/limit 组合。 */
+function windowUsedPercent(body, input) {
+	const ratio = typeof input.usedPercent === "string" ? toNumber(readDeclaredPath(body, input.usedPercent)) : void 0;
+	if (ratio !== void 0) return clampPercent$2(ratio);
+	const usageRatio = typeof input.usedRatio === "string" ? toNumber(readDeclaredPath(body, input.usedRatio)) : void 0;
+	if (usageRatio !== void 0) return clampPercent$2(usageRatio * 100);
+	const used = typeof input.used === "string" ? toNumber(readDeclaredPath(body, input.used)) : void 0;
+	const total = typeof input.limit === "string" ? toNumber(readDeclaredPath(body, input.limit)) : void 0;
+	if (used !== void 0 && total !== void 0 && total > 0) return clampPercent$2(used / total * 100);
+	return null;
+}
+/**
+* 解出一个窗口的重置时刻：resetsAt 路径 > resetInSeconds 路径（now + 秒）推算。
+* @param body - 已解析的响应 JSON。
+* @param input - 窗口配置。
+* @param nowMs - 当前时刻（epoch ms）。
+* @returns ISO 时刻字符串，或 undefined。
+*/
+function windowResetsAt(body, input, nowMs) {
+	if (typeof input.resetsAt === "string") {
+		const value = readDeclaredPath(body, input.resetsAt);
+		if (typeof value === "string" && value !== "") return value;
+	}
+	if (typeof input.resetInSeconds === "string") {
+		const seconds = toNumber(readDeclaredPath(body, input.resetInSeconds));
+		if (seconds !== void 0 && Number.isFinite(seconds) && seconds >= 0) return new Date(nowMs + seconds * 1e3).toISOString();
+	}
+}
+/** 把一条声明窗口配置解析成面板可渲染的滚动窗口；取不到已用百分比则不产出。 */
+function resolveDeclaredWindow(body, input, nowMs) {
+	const used = windowUsedPercent(body, input);
+	if (used === null) return null;
+	const remaining = clampPercent$2(Math.max(0, 100 - used));
+	const resetsAt = windowResetsAt(body, input, nowMs);
+	const remainingAmount = typeof input.used === "string" && typeof input.limit === "string" ? (() => {
+		const u = toNumber(readDeclaredPath(body, input.used));
+		const t = toNumber(readDeclaredPath(body, input.limit));
+		return u !== void 0 && t !== void 0 ? t - u : void 0;
+	})() : void 0;
+	return {
+		kind: input.kind ?? "weekly",
+		usedPercent: used,
+		remainingPercent: remaining,
+		...resetsAt === void 0 ? {} : { resetsAt },
+		...remainingAmount === void 0 ? {} : { remaining: remainingAmount }
+	};
+}
+/**
+* 校验并编译一条声明端点：能否安全地给出一条查询方案。
+* 返回方案的 `read` 用匹配到 provider 的 origin 构造 URL；路径不合规（非单斜杠绝对）
+* 返回 undefined，该账户保持「unsupported」，这是真话，也是它没声明之前的样子。
+*/
+function compileDeclaredEndpoint(decl) {
+	const path = decl?.path;
+	if (typeof path !== "string" || !path.startsWith("/") || path.startsWith("//")) return void 0;
+	return path;
+}
+/**
+* 查询一组声明端点的余额/额度。每个声明独立成败，互不影响。
+* @param ctx - host context carrying the credentials seam.
+* @param providers - llm-pi-ai providers dict（`<route> → { baseURL?, apiKeyEnv? }`）。
+* @param declarations - 声明端点配置列表。
+* @returns 每个匹配到 provider 的声明一行结果；无匹配的声明不上报（不产生请求）。
+*/
+async function queryDeclaredEndpoints(ctx, providers, declarations) {
+	const byOrigin = /* @__PURE__ */ new Map();
+	for (const entry of Object.values(providers)) {
+		const origin = entry.baseURL === void 0 ? void 0 : normalizeDeclaredOrigin(entry.baseURL);
+		if (origin !== void 0 && !byOrigin.has(origin)) byOrigin.set(origin, entry);
+	}
+	return await Promise.all(declarations.map(async (decl) => {
+		const displayName = typeof decl.displayName === "string" && decl.displayName !== "" ? decl.displayName : "已声明";
+		const provider = `declared:${displayName}`;
+		const requestPath = compileDeclaredEndpoint(decl);
+		if (requestPath === void 0) return {
+			provider,
+			displayName,
+			declared: true,
+			error: "invalid",
+			reason: "path 必须单斜杠绝对路径"
+		};
+		const declOrigin = normalizeDeclaredOrigin(decl.origin);
+		const matched = declOrigin === void 0 ? void 0 : byOrigin.get(declOrigin);
+		if (matched === void 0) return {
+			provider,
+			displayName,
+			declared: true,
+			error: "unconfigured",
+			reason: "未匹配到同源 provider（需先在 llm-pi-ai 配好 baseURL）"
+		};
+		const gateKey = `${declOrigin}${requestPath}`;
+		if (!declaredGate.check(gateKey)) return {
+			provider,
+			displayName,
+			declared: true,
+			error: "unreachable"
+		};
+		const hit = await ctx.credentials.resolve(credentialRef(matched.apiKeyEnv ?? ""));
+		if (hit === void 0 || hit.value === "") return {
+			provider,
+			displayName,
+			declared: true,
+			error: "unconfigured"
+		};
+		const url = new URL(requestPath, declOrigin);
+		if (url.origin !== declOrigin) return {
+			provider,
+			displayName,
+			declared: true,
+			error: "invalid",
+			reason: "跨源路径被拒绝"
+		};
+		try {
+			const body = await fetchDeclaredBody(url, decl.raw === true, hit.value);
+			const fields = decl.fields ?? {};
+			const total = typeof fields.total === "string" ? toNumber(readDeclaredPath(body, fields.total)) : void 0;
+			const granted = typeof fields.granted === "string" ? toNumber(readDeclaredPath(body, fields.granted)) : void 0;
+			const used = typeof fields.used === "string" ? toNumber(readDeclaredPath(body, fields.used)) : void 0;
+			const currency = typeof fields.currency === "string" ? readDeclaredPath(body, fields.currency) : void 0;
+			const plan = typeof fields.plan === "string" ? readDeclaredPath(body, fields.plan) : void 0;
+			const windows = (decl.windows ?? []).map((w) => resolveDeclaredWindow(body, w, Date.now())).filter((w) => w !== null);
+			declaredGate.success(gateKey);
+			const nothingResolved = total === void 0 && granted === void 0 && used === void 0 && windows.length === 0;
+			return {
+				provider,
+				displayName,
+				declared: true,
+				...total !== void 0 ? { totalBalance: total } : {},
+				...granted !== void 0 ? { grantedBalance: granted } : {},
+				...typeof currency === "string" && currency !== "" ? { currency } : {},
+				...typeof plan === "string" && plan !== "" ? { plan } : {},
+				...windows.length === 0 ? {} : { windows },
+				...nothingResolved ? {
+					error: "invalid",
+					reason: "声明路径未命中任何字段"
+				} : {}
+			};
+		} catch {
+			declaredGate.fail(gateKey);
+			return {
+				provider,
+				displayName,
+				declared: true,
+				error: "unreachable"
+			};
+		}
+	}));
+}
+/**
+* 带边界约束的 GET 请求：只 GET、跨源重定向直接失败、响应体上限、共享超时。
+* 401/403 → unauthorized（调用方判定）；其余非 2xx / 超限抛错（走 unreachable）。
+*/
+async function fetchDeclaredBody(url, raw, apiKey) {
+	const doRequest = async () => {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS$2);
+		try {
+			const response = await fetch(url.toString(), {
+				method: "GET",
+				headers: {
+					accept: "application/json",
+					...raw ? {} : { authorization: `Bearer ${apiKey}` }
+				},
+				signal: controller.signal,
+				redirect: "manual"
+			});
+			if (response.type === "opaqueredirect" || response.status >= 300 && response.status < 400) throw new HttpStatusError("redirect", 302);
+			if (response.status === 401 || response.status === 403) throw new HttpStatusError("unauthorized", response.status);
+			if (!response.ok) throw new HttpStatusError("http-error", response.status);
+			const text = await response.text();
+			if (text.length > MAX_BODY_BYTES) throw new HttpStatusError("body-too-large", 413);
+			return JSON.parse(text);
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+	return await withRetry(doRequest, {
+		retries: 1,
+		baseDelayMs: 250,
+		maxDelayMs: 2e3
+	});
+}
+/** HTTP 状态错误：携带 statusCode，供调用方区分 unauthorized / 其它。 */
+var HttpStatusError = class extends Error {
+	statusCode;
+	kind;
+	constructor(kind, statusCode) {
+		super(`${kind}:${String(statusCode)}`);
+		this.kind = kind;
+		this.statusCode = statusCode;
+	}
+};
+//#endregion
+//#region lib/types/reconcile.js
+/**
+* 余额差交叉校验（reconcile）：用官方账户余额当日变动反推消费，与本地账本
+* 的当日官方费用比对。若二者偏差超阈值，提示用户核对价格表或近期账单——
+* 这是让计费数据可信的兜底机制，也是对账的稳定锚点。
+*
+* 只对官方直连渠道（DeepSeek 官方）对账：订阅 / Coding Plan / 第三方中转的
+* 消费不动官方余额，强行用余额差替代今日费用会把订阅用户全天的消费归零。
+* 充值、授信、币种变化都会让旧基准失去可比性，此时重置基准而非告警。
+*
+* 纯函数：输入上一基准与本次余额查询结果，输出新基准与对账事件，可独立单测。
+*/
+/** 余额差对账阈值下限（元）：消费低于该值时不值得提示，避免小金额波动刷屏。 */
+const MIN_DRIFT_ABS = .3;
+/** 余额差相对容忍度：偏差超过较大一方的该比例才判漂移。 */
+const DRIFT_RELATIVE = .15;
+/**
+* 归一化一个余额快照中的数值；非有限/缺失返回 0（对账只用其差值，0 安全）。
+* @param value - 待归一化的数值。
+*/
+function num(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+/**
+* 由本次余额查询与上一基准推出一份新的基准快照（用于下一次对账）。
+* @param ref - 上一基准片段（date / currency / at）。
+* @param balance - 本次余额查询结果。
+* @param nowMs - 当前时刻。
+*/
+function snapOf(ref, balance, nowMs) {
+	return {
+		date: ref.date,
+		total: num(balance.totalBalance),
+		granted: num(balance.grantedBalance),
+		topped: num(balance.toppedUpBalance),
+		currency: typeof balance.currency === "string" ? balance.currency : ref.currency,
+		at: nowMs
+	};
+}
+/**
+* 对账：用官方余额当日变动反推消费，与本地账本当日官方费用比对。
+* @param prevRef - 上一基准（可为 null，表示首次/基准缺失）。
+* @param balance - 本次余额查询结果。
+* @param todayOfficialCost - 本地账本当日的官方渠道费用（CNY）。
+* @param dayKey - 本地日期键（YYYY-MM-DD）。
+* @param nowMs - 当前时刻（epoch ms）。
+* @returns 新基准与对账事件；余额不可用（无 totalBalance）时返回 `{ ref: prevRef, event: null }`。
+*/
+function reconcileBalanceDelta(prevRef, balance, todayOfficialCost, dayKey, nowMs) {
+	const total = balance.totalBalance;
+	if (typeof total !== "number" || !Number.isFinite(total)) return {
+		ref: prevRef,
+		event: null
+	};
+	const snap = snapOf({
+		date: dayKey,
+		currency: prevRef?.currency ?? ""
+	}, balance, nowMs);
+	if (prevRef === null || prevRef.date !== dayKey) return {
+		ref: snap,
+		event: { kind: "baseline" }
+	};
+	if (prevRef.currency !== snap.currency) return {
+		ref: snap,
+		event: { kind: "structure-reset" }
+	};
+	if (snap.granted > prevRef.granted + .009 || snap.topped > prevRef.topped + .009) return {
+		ref: snap,
+		event: { kind: "structure-reset" }
+	};
+	const spent = prevRef.total - snap.total;
+	if (spent <= .009) return {
+		ref: prevRef,
+		event: { kind: "flat" }
+	};
+	const cost = num(todayOfficialCost);
+	if (Math.abs(spent - cost) > Math.max(MIN_DRIFT_ABS, DRIFT_RELATIVE * Math.max(spent, cost))) return {
+		ref: prevRef,
+		event: {
+			kind: "drift",
+			spent,
+			todayOfficialCost: cost
+		}
+	};
+	return {
+		ref: prevRef,
+		event: {
+			kind: "ok",
+			spent,
+			todayOfficialCost: cost
+		}
+	};
+}
+//#endregion
 //#region lib/types/pricing-fetch.js
 /**
 * One-shot live pricing refresh for the billing dashboard.
@@ -2813,7 +3247,8 @@ async function collectOpenCodeGo(keys, config, timeoutMs) {
 		provider: config.provider,
 		displayName: "OpenCode Go",
 		status: "not-configured",
-		windows: []
+		windows: [],
+		hint: "未配置 key；可在 llm-pi-ai 里给 opencode(opencode-go) 配 apiKeyEnv，或让本机 OpenCode 凭据（~/.local/share/opencode/auth.json）可用"
 	};
 	try {
 		const windows = parseOpenCodeGoApi(await requestJson(`${base}/zen/go/v1/usage`, { headers: {
@@ -2951,7 +3386,8 @@ async function collectOpenRouter(keys, config, timeoutMs) {
 		provider: config.provider,
 		displayName: "OpenRouter",
 		status: "not-configured",
-		windows: []
+		windows: [],
+		hint: "未配置 key；OpenRouter 的额度接口只认 Management Key，用推理 key 会 401"
 	};
 	try {
 		const windows = parseOpenRouterCredits(await requestJson(`${base}/api/v1/credits`, { headers: {
@@ -2965,11 +3401,13 @@ async function collectOpenRouter(keys, config, timeoutMs) {
 			windows
 		};
 	} catch (error) {
+		const status = statusOf$1(error);
 		return {
 			provider: config.provider,
 			displayName: "OpenRouter",
-			status: statusOf$1(error),
-			windows: []
+			status,
+			windows: [],
+			...status === "unauthorized" ? { hint: "OpenRouter 额度接口只认 Management Key；你配的 key 返回了 401，请换成管理密钥（在 openrouter.ai/settings/keys 创建）" } : {}
 		};
 	}
 }
@@ -3156,6 +3594,32 @@ function originOf(baseURL) {
 		return baseURL;
 	}
 }
+/**
+* 已知官方（非中转站）端点 host 判定：这些域是厂商自己的官方 API，卖的是
+* 官方按量余额而非中转站按 key 的额度，探测其 `/v1/usage`、`/api/status`
+* 子路径只会得到 404/非中转站格式，因而面板应排除它们，避免误判为
+* 「未识别」。中转站面板只列真正的第三方中转程序。
+*/
+const OFFICIAL_HOSTS = new Set([
+	"api.deepseek.com",
+	"api.openai.com",
+	"open.bigmodel.cn",
+	"api.moonshot.cn",
+	"api.siliconflow.cn",
+	"api.stepfun.com",
+	"api.x.ai",
+	"api.anthropic.com",
+	"generativelanguage.googleapis.com"
+]);
+/**
+* 判断一个 baseURL 是否指向已知官方端点（而非第三方中转站）。
+* @param baseURL - llm-pi-ai provider 路由的端点地址。
+* @returns 官方端点返回 true（中转站面板应排除）。
+*/
+function isOfficialBaseUrl(baseURL) {
+	const host = originOf(baseURL).replace(/^https?:\/\//, "");
+	return host !== baseURL && OFFICIAL_HOSTS.has(host);
+}
 /** 构造端点 URL：`/v1/usage` 与 `/api/status` 都以 baseURL 为宿主解析。 */
 function endpointOf(baseURL, path) {
 	return new URL(path, baseURL).toString();
@@ -3540,11 +4004,25 @@ async function resolveSubscriptionKeys(settings, credentials) {
 		} catch {}
 	}
 	if (providers?.["zai-coding-cn"]?.apiKeyEnv !== void 0 && keys.zaiApiKey !== "") keys.zaiRegion = "bigmodel-cn";
+	if (keys.opencodeApiKey === "") keys.opencodeApiKey = await readOpenCodeToken();
 	return {
 		keys,
 		identified: identifySubscriptionPlans(providers)
 	};
 }
+/** 读本机 OpenCode 客户端的凭据 token；取不到返回空串（安静退回）。 */
+async function readOpenCodeToken() {
+	try {
+		const auth = JSON.parse(await readFile(join(homedir(), ".local", "share", "opencode", "auth.json"), "utf8"));
+		if (typeof auth === "string" && auth !== "") return auth;
+		if (auth !== null && typeof auth === "object") {
+			const record = auth;
+			const token = record.token ?? record.key ?? record.apiKey;
+			if (typeof token === "string" && token !== "") return token;
+		}
+	} catch {}
+	return "";
+}
 /**
 * Host plugin body: serve real aggregated usage to the browser dashboard.
 * @param ctx - host context carrying webServer and sessionPersistence.
@@ -3553,8 +4031,26 @@ async function resolveSubscriptionKeys(settings, credentials) {
 function apply(ctx, config = {}) {
 	let usageSettingsScope;
 	const cwd = process.cwd();
-	const snapshotPath = join(homedir(), ".dsh/.dsh-usage-stats.json");
+	const snapshotPath = config.snapshotPath ?? join(homedir(), ".dsh/.dsh-usage-stats.json");
 	const ledgerStore = createFileUsageLedgerStore(config.ledgerPath ?? join(homedir(), ".dsh/.dsh-usage-ledger.json"));
+	const reconcilePath = config.reconcilePath ?? join(homedir(), ".dsh/.dsh-usage-reconcile.json");
+	let reconcileRef = null;
+	(async () => {
+		try {
+			const ref = JSON.parse(await readFile(reconcilePath, "utf8")).ref;
+			if (ref !== null && typeof ref === "object") {
+				const candidate = ref;
+				if (typeof candidate.date === "string" && typeof candidate.total === "number" && typeof candidate.granted === "number" && typeof candidate.topped === "number" && typeof candidate.currency === "string") reconcileRef = candidate;
+			}
+		} catch {}
+	})();
+	const persistReconcileRef = () => {
+		if (reconcileRef === null) return;
+		writeFileAtomic(reconcilePath, JSON.stringify({ ref: reconcileRef }), {
+			mode: 384,
+			dirMode: 448
+		}).catch(() => {});
+	};
 	const workspaceTitleResolver = buildWorkspaceTitleResolver(ctx);
 	const aggregator = createUsageAggregator(ctx.sessionPersistence, {
 		...config.subscriptionProviders === void 0 ? {} : { subscriptionProviders: config.subscriptionProviders },
@@ -3785,12 +4281,42 @@ function apply(ctx, config = {}) {
 		handler: async (req, res) => {
 			if (!guardLoopback(req, res)) return;
 			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
-			const providers = { ...await readPiAiProviders(ctx.settings) };
+			const piProviders = await readPiAiProviders(ctx.settings);
+			const providers = { ...piProviders };
 			if (providers["deepseek"] === void 0) providers["deepseek"] = { apiKeyEnv: config.balanceApiKeyEnv ?? DEFAULT_BALANCE_API_KEY_ENV };
 			const balances = await queryBalances(ctx, providers);
 			const custom = await queryCustomBalances(ctx, config.customBalances ?? []);
-			for (const row of [...balances, ...custom]) if (row.error === "unauthorized") warnAuthOnce("balance", row.provider, row.displayName);
-			res.end(JSON.stringify({ balances: [...balances, ...custom] }));
+			const declared = await queryDeclaredEndpoints(ctx, piProviders, config.declaredEndpoints ?? []);
+			for (const row of [
+				...balances,
+				...custom,
+				...declared
+			]) if (row.error === "unauthorized") warnAuthOnce("balance", row.provider, row.displayName);
+			const official = balances.find((row) => row.provider === "deepseek");
+			let reconcile;
+			if (official !== void 0 && official.totalBalance !== void 0) {
+				const now = Date.now();
+				const today = dayStamp(now);
+				let todayOfficialCost = 0;
+				try {
+					todayOfficialCost = (await aggregator.aggregate()).byDay[today]?.officialCost ?? 0;
+				} catch {}
+				const result = reconcileBalanceDelta(reconcileRef, official, todayOfficialCost, today, now);
+				reconcileRef = result.ref;
+				if (result.event !== null && result.event.kind !== "flat") reconcile = {
+					...result.event,
+					provider: official.displayName
+				};
+				if (result.ref !== null) persistReconcileRef();
+			}
+			res.end(JSON.stringify({
+				balances: [
+					...balances,
+					...custom,
+					...declared
+				],
+				...reconcile === void 0 ? {} : { reconcile }
+			}));
 		}
 	}), "usage-billing: balance route");
 	ctx.effect(() => ctx.webServer.register({
@@ -3878,6 +4404,7 @@ function apply(ctx, config = {}) {
 		const routes = [];
 		for (const [route, entry] of Object.entries(providers)) {
 			if (entry.baseURL === void 0 || entry.apiKeyEnv === void 0) continue;
+			if (isOfficialBaseUrl(entry.baseURL)) continue;
 			routes.push({
 				route,
 				baseURL: entry.baseURL,