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

package/lib/types/aggregate.d.ts

@@ -111,6 +111,15 @@ export declare function foldUsage(acc: ModelUsage, usage: TokenUsage, key: strin
 export declare function dayStamp(time: number): string;
 /** Local-time hour stamp `YYYY-MM-DDTHH` — the performance series bucket key. */
 export declare function hourStamp(time: number): string;
+/**
+ * 宿主进程的 IANA 时区名与 UTC 偏移，供面板标注「天按哪个时区切分」。
+ * `getTimezoneOffset` 是 UTC 以西的分钟数，符号与日常写法相反，故取反。
+ * @returns `{ name, offset }`，如 `{ name: "Asia/Shanghai", offset: "UTC+08:00" }`。
+ */
+export declare function hostTimeZone(now?: Date): {
+    name: string;
+    offset: string;
+};
 /** cwd 未知时工作区聚合的占位名（UI 显示 em dash，保持语言无关）。 */
 export declare const UNKNOWN_WORKSPACE_NAME = "\u2014";
 /** 工作区名：取 cwd 的末级目录名；无 cwd 时返回 {@link UNKNOWN_WORKSPACE_NAME}。 */
@@ -127,6 +136,11 @@ export interface UsageStatsDocument {
     version: number;
     updatedAt: number;
     source: 'session-logs';
+    /** 宿主进程时区（IANA 名 + UTC 偏移）：天按此切分，面板据此标注。 */
+    timezone?: {
+        name: string;
+        offset: string;
+    };
     total: ModelUsage;
     byModel: Record<string, ModelUsage>;
     byDay: Record<string, ModelUsage>;
@@ -325,7 +339,31 @@ export interface UsageLedgerDocument {
     version: 1;
     updatedAt: number;
     sessions: UsageLedgerSession[];
+    /** 已应用的一次性配置迁移 id 列表（随文档落盘；缺省 = 尚未跑过任何迁移）。 */
+    appliedMigrations?: string[];
 }
+/**
+ * 一次性账本迁移：id 唯一，apply 在加载边界对原始文档执行，已应用过的跳过。
+ * 未来账本/schema 字段变更（重命名、拆桶、语义调整）时，在此追加一条迁移并
+ * bump {@link UsageLedgerDocument.version}；引擎保证幂等，重启不会重复执行。
+ */
+export interface LedgerMigration {
+    id: string;
+    /** 对原始文档执行就地变更；返回是否产生了需要落盘的实际修改。 */
+    apply(document: UsageLedgerDocument): boolean;
+}
+/**
+ * 账本迁移注册表。当前账本 schema（version 1）尚无字段变更需求，故为空表；
+ * 机制已就绪，schema 变更时在此登记幂等迁移，见 {@link LedgerMigration}。
+ */
+export declare const LEDGER_MIGRATIONS: readonly LedgerMigration[];
+/**
+ * 在加载边界对账本文档应用未执行的迁移，并记录已应用 id 供写回。
+ * @param document - 从持久化读出的原始账本文档。
+ * @param migrations - 待执行的迁移注册表；缺省用模块级 {@link LEDGER_MIGRATIONS}。
+ * @returns 是否发生了需要重新落盘的修改。
+ */
+export declare function runLedgerMigrations(document: UsageLedgerDocument, migrations?: readonly LedgerMigration[]): boolean;
 /** Storage seam for the durable ledger; the host supplies an atomic file implementation. */
 export interface UsageLedgerStore {
     load(): Promise<unknown | undefined>;
@@ -350,6 +388,7 @@ export declare function foldSession(events: readonly {
     type: string;
     time: number;
     data: never;
+    seq?: number;
 }[], subscriptionProviders: ReadonlySet<string>, officialProviderIds?: ReadonlySet<string>, routes?: Readonly<Record<string, ProviderRouteView>>): SessionFold;
 /**
  * 增量聚合器：按会话缓存折叠结果，用日志文件的 mtime+size 作失效键——

package/lib/types/client/TrendChart.d.ts

@@ -26,18 +26,24 @@ export interface TrendPoint {
     cost: number;
     /** API calls that day (total across models). */
     calls: number;
+    /** Total tokens that day (input+output+cache); used by the `tokens` metric. */
+    tokens?: number;
     /** Per-model cost that day (stats key → CNY); absent entries plot zero. */
     byModel?: Readonly<Record<string, number>>;
 }
+/** Metric rendered by the chart columns: daily cost (stacked by model) or total tokens. */
+export type TrendMetric = 'cost' | 'tokens';
 /**
- * Render the daily stacked cost bars plus the total-calls line.
+ * Render the daily bars plus the total-calls line.
  * @param props.data - sorted daily rows (ascending date).
- * @param props.models - the model legend, in bar order.
+ * @param props.models - the model legend, in bar order (used by the `cost` metric).
  * @param props.currency - display currency for the cost labels.
+ * @param props.metric - `cost` (stacked per-model CNY, default) or `tokens` (single-color total tokens).
  */
-export declare function TrendChart({ data, models, currency }: {
+export declare function TrendChart({ data, models, currency, metric }: {
     data: readonly TrendPoint[];
     models?: readonly TrendSeriesModel[];
     currency?: CostCurrency;
+    metric?: TrendMetric;
 }): React.ReactNode;
 //# sourceMappingURL=TrendChart.d.ts.map

package/lib/types/client/UsageBilling.d.ts

@@ -14,6 +14,7 @@ import type { SidebarFooterActionOwnerProps } from '@deepseek-ai/dsh-client-ui-s
 import { type ClientPerf } from './PerfPanel.tsx';
 import type { createBillingBudgetStore } from './budget-store.ts';
 import { type CatalogModel } from './pricing.ts';
+import type { ReconcileNotice } from '../pricing-shared.ts';
 import { NS, type UsageBillingKey } from './locales.ts';
 /** Model-connectivity health reported by the host model directory probe. */
 export interface ModelHealth {
@@ -35,8 +36,8 @@ export interface ModelHealth {
 /** 仪表盘分区 Tab id。 */
 export type DashboardTab = 'overview' | 'token' | 'trends' | 'providers' | 'pricing' | 'settings';
 /**
- * Tab 定义（顺序即渲染顺序）：概览=主数字/KPI/热力图，趋势=趋势图/每轮费用，
- * 明细=厂商计费与订阅，统计=工作区/会话明细，费率=模型单价表，设置=预算与峰谷提醒。
+ * Tab 定义（顺序即渲染顺序）：概览=主数字/KPI/热力图，账单=厂商计费与订阅，
+ * 用量=Token 用量，趋势=趋势图/每轮费用，费率=模型单价表，设置=预算与峰谷提醒。
  * 导出供测试断言 tab 与文案 key 对齐、decor 锚点落在正确分区。
  */
 export declare const DASHBOARD_TABS: readonly {
@@ -121,6 +122,11 @@ interface SessionBillingRow {
 export interface UsageStats {
     /** 服务端聚合时间戳（毫秒）；旧快照可能缺失。 */
     updatedAt?: number;
+    /** 宿主进程时区（IANA 名 + UTC 偏移）：天按此切分，副标题据此标注；旧快照可能缺失。 */
+    timezone?: {
+        name: string;
+        offset: string;
+    };
     /** 月度预算（人民币元）：宿主 Config 注入；未配置时不渲染预算条。 */
     budget?: number;
     /** 余额不足告警阈值（人民币元）：宿主 Config 注入；未配置时客户端用默认值。 */
@@ -215,6 +221,11 @@ export interface UsageStats {
     /** 插件版本号（服务端读自包 package.json；旧快照缺失）。 */
     pluginVersion?: string;
 }
+/**
+ * 拉取官方余额差对账提示（drift 时非空），供余额面板展示；失败返回 undefined。
+ * @returns the reconcile notice, or undefined on any failure / no drift.
+ */
+export declare function fetchReconcile(): Promise<ReconcileNotice | undefined>;
 /** 组件注入面：探活 + 计费指标写入（billing 自身写入，主题插件经服务读取）。 */
 export interface UsageBillingInjected {
     checkModels: () => Promise<ModelHealth>;

package/lib/types/client/locales.d.ts

@@ -1,5 +1,5 @@
 /** Locale dictionaries for the usage billing surface. */
-export type UsageBillingKey = 'billing.title' | 'billing.subtitle' | 'billing.cost' | 'billing.todayCost' | 'billing.monthCost' | 'billing.yearCost' | 'billing.monthProjected' | 'billing.liveTurn' | 'billing.liveSession' | 'billing.totalCost' | 'billing.calls' | 'billing.cacheHitRate' | 'billing.tokens' | 'billing.inputTokens' | 'billing.outputTokens' | 'billing.avgCost' | 'billing.trend' | 'billing.trend7d' | 'billing.trend30d' | 'billing.trendEmpty' | 'billing.budget' | 'billing.sessions' | 'billing.project' | 'billing.lastActive' | 'billing.sessionOverflow' | 'billing.budgetTierBody' | 'billing.models' | 'billing.providerBilling' | 'billing.estimated' | 'billing.actual' | 'billing.pricing' | 'billing.showPricing' | 'billing.hidePricing' | 'billing.pricePerM' | 'billing.input' | 'billing.output' | 'billing.cacheHit' | 'billing.peak' | 'billing.offPeak' | 'billing.flat' | 'billing.peakHours' | 'billing.band' | 'billing.openDashboard' | 'billing.close' | 'billing.lastUpdated' | 'billing.noData' | 'billing.todayRate' | 'billing.rateLive' | 'billing.rateBuiltin' | 'billing.pricingTip' | 'billing.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable' | 'billing.uncatalogued' | 'billing.estimatedPricing' | 'billing.balanceDays' | 'billing.balanceLowBody' | 'billing.subscriptions' | 'billing.subscriptionNotConfigured' | 'billing.subscriptionUnauthorized' | 'billing.subscriptionUnavailable' | 'billing.subscriptionInvalid' | 'billing.subscriptionRateLimited' | 'billing.subscriptionSession' | 'billing.subscriptionWeekly' | 'billing.subscriptionMonthly' | 'billing.subscriptionBilling' | 'billing.subscriptionRemaining' | 'billing.subscriptionExhausted' | 'billing.subscriptionReset' | 'billing.subscriptionNoApi' | 'billing.floatWindow' | 'billing.floatModeCombined' | 'billing.floatModeSubscription' | 'billing.floatWindowHint' | 'billing.floatNoTargets' | 'billing.floatNoTargetsHint' | 'billing.floatPrev' | 'billing.floatNext' | 'billing.heatmapLess' | 'billing.heatmapMore' | 'billing.currency' | 'billing.currencyCny' | 'billing.currencyUsd' | 'billing.heatmap' | 'billing.rounds' | 'billing.anomaly' | 'billing.workspaces' | 'billing.plan' | 'billing.remaining' | 'billing.unknownModel' | 'billing.model' | 'billing.currentRound' | 'billing.costAbbr' | 'billing.tabOverview' | 'billing.tabTrends' | 'billing.tabProviders' | 'billing.tabDetails' | 'billing.tabPricing' | 'billing.tabSettings' | 'billing.settingsHead' | 'billing.settingsHint' | 'billing.budgetHint' | 'billing.peakAlertHint' | 'billing.peakAlertDescPeak' | 'billing.peakAlertDescOff' | 'billing.export' | 'billing.exportCsvDay' | 'billing.exportCsvSession' | 'billing.exportJson' | 'billing.peakShare' | 'billing.peakShareHint' | 'billing.weekCost' | 'billing.roleCost' | 'billing.roleUser' | 'billing.roleAssistant' | 'billing.roleTool' | 'billing.roleHint' | 'billing.tierPeak' | 'billing.tierOff' | 'billing.tierToPeak' | 'billing.tierToOff' | 'billing.tierAlertEnterPeak' | 'billing.tierAlertEnterOff' | 'billing.peakAlertTitlePeak' | 'billing.peakAlertTitleOff' | 'billing.peakAlert' | 'billing.peakAlertLeadMin' | 'billing.peakAlertPosCorner' | 'billing.peakAlertPosCenter' | 'billing.peakAlertModePeak' | 'billing.peakAlertModeOff' | 'billing.peakAlertModeBoth' | 'billing.peakAlertWebNotify' | 'billing.peakAlertPreview' | 'billing.planTypeCode' | 'billing.planTypeToken' | 'billing.subscriptionFeePerMonth' | 'billing.triggerToday' | 'billing.triggerMonth' | 'billing.subscriptionIncluded' | 'billing.free' | 'billing.official' | 'billing.thirdParty' | 'billing.officialCost' | 'billing.thirdPartyCost' | 'billing.perfSamples' | 'billing.perfTtft' | 'billing.perfP50' | 'billing.perfP90' | 'billing.perfTps' | 'billing.perfLatency' | 'billing.perfEstimated' | 'billing.perfEmpty' | 'billing.perfTpsUnit' | 'billing.perfTitle' | 'billing.perfHint' | 'billing.heatmapYear' | 'billing.heatmapMonth' | 'billing.activeDays' | 'billing.streakDays' | 'billing.subscriptionAutoDetect' | 'billing.pluginInfo' | 'billing.pluginName' | 'billing.pluginDescription' | 'billing.pluginVersion' | 'billing.pluginAuthor' | 'billing.pluginRepository' | 'billing.pluginNpm' | 'billing.pluginLicense' | 'billing.tabToken' | 'billing.tokenExport' | 'billing.tokenExportCsv' | 'billing.tokenCacheHitRate' | 'billing.tokenReasoningShare' | 'billing.tokenReasoningShort' | 'billing.tokenIo' | 'billing.tokenPeak' | 'billing.tokenDaily' | 'billing.tokenByModel' | 'billing.tokenMiss' | 'billing.tokenHit' | 'billing.tokenOutput' | 'billing.tokenTotal' | 'billing.tokenShare' | 'billing.usageStatsTool' | 'billing.usageStatsToolHint' | 'billing.balanceGranted' | 'billing.balanceTopped' | 'billing.balanceDaily' | 'billing.balanceDaysLong' | 'billing.balanceDaysUnit' | 'billing.popTodayModel' | 'billing.popNoConsumption' | 'billing.popQuotaAlert' | 'billing.popRiskNone' | 'billing.popTitle' | 'billing.popDirectLead' | 'billing.popSubLead' | 'billing.popBalanceNormal' | 'billing.popBalanceLow' | 'billing.popQuotaNormal' | 'billing.popQuotaLow' | 'billing.alertBalanceLow' | 'billing.alertQuotaLow' | 'billing.unpricedHint' | 'billing.exportCsvSite' | 'billing.panelRelay' | 'billing.relaySite' | 'billing.relayDirect' | 'billing.relayUnknown' | 'billing.panelRelayQuota' | 'billing.relayBalance' | 'billing.relayNoQuota' | 'billing.relayWindowUsed' | 'billing.relayKindNewApi' | 'billing.relayKindSub2Api' | 'billing.relayKindUnknown' | 'billing.relayCalls';
+export type UsageBillingKey = 'billing.title' | 'billing.subtitle' | 'billing.cost' | 'billing.todayCost' | 'billing.monthCost' | 'billing.yearCost' | 'billing.monthProjected' | 'billing.liveTurn' | 'billing.liveSession' | 'billing.totalCost' | 'billing.calls' | 'billing.cacheHitRate' | 'billing.tokens' | 'billing.inputTokens' | 'billing.outputTokens' | 'billing.avgCost' | 'billing.trend' | 'billing.trend7d' | 'billing.trend30d' | 'billing.trendMetric' | 'billing.trendMetricCost' | 'billing.trendMetricTokens' | 'billing.trendEmpty' | 'billing.budget' | 'billing.sessions' | 'billing.project' | 'billing.lastActive' | 'billing.sessionOverflow' | 'billing.budgetTierBody' | 'billing.models' | 'billing.providerBilling' | 'billing.estimated' | 'billing.actual' | 'billing.pricing' | 'billing.showPricing' | 'billing.hidePricing' | 'billing.pricePerM' | 'billing.input' | 'billing.output' | 'billing.cacheHit' | 'billing.peak' | 'billing.offPeak' | 'billing.flat' | 'billing.peakHours' | 'billing.band' | 'billing.openDashboard' | 'billing.close' | 'billing.lastUpdated' | 'billing.noData' | 'billing.todayRate' | 'billing.rateLive' | 'billing.rateBuiltin' | 'billing.pricingTip' | 'billing.balance' | 'billing.balanceUnconfigured' | 'billing.balanceUnauthorized' | 'billing.balanceUnreachable' | 'billing.uncatalogued' | 'billing.estimatedPricing' | 'billing.balanceDays' | 'billing.balanceLowBody' | 'billing.reconcileDrift' | 'billing.reconcileDismiss' | 'billing.subscriptions' | 'billing.subscriptionNotConfigured' | 'billing.subscriptionUnauthorized' | 'billing.subscriptionUnavailable' | 'billing.subscriptionInvalid' | 'billing.subscriptionRateLimited' | 'billing.subscriptionSession' | 'billing.subscriptionWeekly' | 'billing.subscriptionMonthly' | 'billing.subscriptionBilling' | 'billing.subscriptionRemaining' | 'billing.subscriptionExhausted' | 'billing.subscriptionReset' | 'billing.subscriptionNoApi' | 'billing.floatWindow' | 'billing.floatModeCombined' | 'billing.floatModeSubscription' | 'billing.floatWindowHint' | 'billing.floatNoTargets' | 'billing.floatNoTargetsHint' | 'billing.floatPrev' | 'billing.floatNext' | 'billing.subscriptionsStale' | 'billing.heatmapLess' | 'billing.heatmapMore' | 'billing.currency' | 'billing.currencyCny' | 'billing.currencyUsd' | 'billing.heatmap' | 'billing.rounds' | 'billing.anomaly' | 'billing.workspaces' | 'billing.plan' | 'billing.remaining' | 'billing.unknownModel' | 'billing.model' | 'billing.currentRound' | 'billing.costAbbr' | 'billing.tabOverview' | 'billing.tabTrends' | 'billing.tabProviders' | 'billing.tabDetails' | 'billing.tabPricing' | 'billing.tabSettings' | 'billing.settingsHead' | 'billing.settingsHint' | 'billing.budgetHint' | 'billing.peakAlertHint' | 'billing.peakAlertDescPeak' | 'billing.peakAlertDescOff' | 'billing.export' | 'billing.exportCsvDay' | 'billing.exportCsvSession' | 'billing.exportJson' | 'billing.peakShare' | 'billing.peakShareHint' | 'billing.weekCost' | 'billing.roleCost' | 'billing.roleUser' | 'billing.roleAssistant' | 'billing.roleTool' | 'billing.roleHint' | 'billing.tierPeak' | 'billing.tierOff' | 'billing.tierToPeak' | 'billing.tierToOff' | 'billing.tierAlertEnterPeak' | 'billing.tierAlertEnterOff' | 'billing.peakAlertTitlePeak' | 'billing.peakAlertTitleOff' | 'billing.peakAlert' | 'billing.peakAlertLeadMin' | 'billing.peakAlertPosCorner' | 'billing.peakAlertPosCenter' | 'billing.peakAlertModePeak' | 'billing.peakAlertModeOff' | 'billing.peakAlertModeBoth' | 'billing.peakAlertWebNotify' | 'billing.peakAlertPreview' | 'billing.planTypeCode' | 'billing.planTypeToken' | 'billing.subscriptionFeePerMonth' | 'billing.triggerToday' | 'billing.triggerMonth' | 'billing.subscriptionIncluded' | 'billing.free' | 'billing.official' | 'billing.thirdParty' | 'billing.officialCost' | 'billing.thirdPartyCost' | 'billing.perfSamples' | 'billing.perfTtft' | 'billing.perfP50' | 'billing.perfP90' | 'billing.perfTps' | 'billing.perfLatency' | 'billing.perfEstimated' | 'billing.perfEmpty' | 'billing.perfTpsUnit' | 'billing.perfTitle' | 'billing.perfHint' | 'billing.heatmapYear' | 'billing.heatmapMonth' | 'billing.activeDays' | 'billing.streakDays' | 'billing.subscriptionAutoDetect' | 'billing.pluginInfo' | 'billing.pluginName' | 'billing.pluginDescription' | 'billing.pluginVersion' | 'billing.pluginAuthor' | 'billing.pluginRepository' | 'billing.pluginNpm' | 'billing.pluginLicense' | 'billing.tabToken' | 'billing.tokenExport' | 'billing.tokenExportCsv' | 'billing.tokenCacheHitRate' | 'billing.tokenReasoningShare' | 'billing.tokenReasoningShort' | 'billing.tokenIo' | 'billing.tokenPeak' | 'billing.tokenDaily' | 'billing.tokenByModel' | 'billing.tokenMiss' | 'billing.tokenHit' | 'billing.tokenOutput' | 'billing.tokenTotal' | 'billing.tokenShare' | 'billing.usageStatsTool' | 'billing.usageStatsToolHint' | 'billing.balanceGranted' | 'billing.balanceTopped' | 'billing.balanceDaily' | 'billing.balanceDaysLong' | 'billing.balanceDaysUnit' | 'billing.popTodayModel' | 'billing.popNoConsumption' | 'billing.popQuotaAlert' | 'billing.popRiskNone' | 'billing.popTitle' | 'billing.popDirectLead' | 'billing.popSubLead' | 'billing.popBalanceNormal' | 'billing.popBalanceLow' | 'billing.popQuotaNormal' | 'billing.popQuotaLow' | 'billing.alertBalanceLow' | 'billing.alertQuotaLow' | 'billing.unpricedHint' | 'billing.exportCsvSite' | 'billing.panelRelay' | 'billing.relaySite' | 'billing.relayDirect' | 'billing.relayUnknown' | 'billing.panelRelayQuota' | 'billing.relayBalance' | 'billing.relayNoQuota' | 'billing.relayWindowUsed' | 'billing.relayKindNewApi' | 'billing.relayKindSub2Api' | 'billing.relayKindUnknown' | 'billing.relayCalls';
 export declare const NS = "usageBilling";
 export declare const zh: Record<UsageBillingKey, string>;
 export declare const en: Record<UsageBillingKey, string>;

package/lib/types/declarative.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 声明端点（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`，而不是留一张和「上游没返回」无从
+ * 区分的空卡。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { DeclaredEndpointConfig, ProviderBalance } from './pricing-shared.ts';
+/**
+ * 归一化 baseURL 为可比的 origin：`scheme://host[:port]`，剥掉 scheme 的默认端口，
+ * host 转小写，忽略路径。无法解析返回 undefined。
+ * @param baseURL - provider 的端点地址，或声明里的 origin。
+ */
+export declare function normalizeDeclaredOrigin(baseURL: string): string | undefined;
+/**
+ * 沿点路径走进已解析的响应体。
+ * 任何失败都是同一个答案 `undefined`——路径不匹配是这份响应没有那个字段，是卡片
+ * 本来就渲染得了的事实，不是错误，而且不该让已解析成功的字段被牵连。
+ * @param body - 已解析的响应 JSON。
+ * @param path - 点路径（如 `data.balance`）。
+ * @returns 路径处的值，或 undefined（路径缺失 / 中途不是对象 / 命中原型链）。
+ */
+export declare function readDeclaredPath(body: unknown, path: string): unknown;
+/**
+ * 查询一组声明端点的余额/额度。每个声明独立成败，互不影响。
+ * @param ctx - host context carrying the credentials seam.
+ * @param providers - llm-pi-ai providers dict（`<route> → { baseURL?, apiKeyEnv? }`）。
+ * @param declarations - 声明端点配置列表。
+ * @returns 每个匹配到 provider 的声明一行结果；无匹配的声明不上报（不产生请求）。
+ */
+export declare function queryDeclaredEndpoints(ctx: Context, providers: Readonly<Record<string, {
+    baseURL?: string;
+    apiKeyEnv?: string;
+}>>, declarations: readonly DeclaredEndpointConfig[]): Promise<readonly ProviderBalance[]>;
+//# sourceMappingURL=declarative.d.ts.map

package/lib/types/index.d.ts

@@ -14,7 +14,7 @@ import type { Context } from '@deepseek-ai/cordis';
 import type { CredentialProvider } from '@deepseek-ai/dsh-credentials';
 import { type SettingsProvider } from '@deepseek-ai/dsh-settings';
 import { type UsageLedgerStore } from './aggregate.ts';
-import type { CustomBalanceConfig, SubscriptionPlanConfig } from './pricing-shared.ts';
+import type { CustomBalanceConfig, DeclaredEndpointConfig, SubscriptionPlanConfig } from './pricing-shared.ts';
 import { type IdentifiedSubscriptionPlan, type SubscriptionKeys } from './subscriptions.ts';
 /**
  * 回环防护守卫：仅接受回环 GET 请求（peer socket 地址 + Host 头同时校验）。
@@ -28,9 +28,14 @@ export declare function guardLoopback(req: IncomingMessage, res: ServerResponse)
 export interface UsageBillingConfig {
     /** Absolute path to a `.dsh-usage-stats.json` fallback file. */
     statsPath?: string;
+    /** 统计快照的持久化路径；默认 `~/.dsh/.dsh-usage-stats.json`。
+     *  测试注入临时目录以隔离真实家目录（聚合失败回退与快照落盘都走此路径）。 */
+    snapshotPath?: string;
     /** 独立持久用量账本的绝对路径；默认 `~/.dsh/.dsh-usage-ledger.json`。
      *  账本与会话日志解耦，因此永久删除会话不会抹掉已经观测到的用量。 */
     ledgerPath?: string;
+    /** 余额差对账基准的持久化路径；默认 `~/.dsh/.dsh-usage-reconcile.json`。 */
+    reconcilePath?: string;
     /** 订阅制（coding / token / agent plan）provider id 列表；默认 kimi-coding、xiaomi-token-plan-cn。 */
     subscriptionProviders?: string[];
     /** 订阅套餐额度适配器（kimi / zai / opencode-go）；默认全部内置。 */
@@ -44,6 +49,13 @@ export interface UsageBillingConfig {
     lowBalanceThreshold?: number;
     /** 自定义 Provider 余额查询（任意 HTTP 端点 + extract 规则，适配 NewApi/LiteLLM 等）。 */
     customBalances?: readonly CustomBalanceConfig[];
+    /**
+     * 声明端点（declarative endpoints）：为内置表没有的供应商自声明余额/额度接口。
+     * 绑定到某条已配置 provider 的同源地址，`fields` / `windows` 写响应里的取值路径；
+     * 安全边界（origin 绑定、单斜杠 path、只 GET、跨源重定向失败、凭据取自 apiKeyEnv）
+     * 写死在 declarative.ts。缺省空。
+     */
+    declaredEndpoints?: readonly DeclaredEndpointConfig[];
     /** `usage_stats` 工具注入的组合 base（默认 false：不注入）；与设置命名空间同字段，
      *  作为用户设置（设置 Tab 开关）的组合兜底。该工具占用每次请求的上下文，coding 场景多在仪表盘查看。 */
     enableUsageStatsTool?: boolean;

package/lib/types/pricing-shared.d.ts

@@ -60,10 +60,32 @@ export interface ProviderBalance {
     isAvailable?: boolean;
     /** 未配置/鉴权失败/网络不可达等失败原因；缺省 = 查询成功。 */
     error?: BalanceError;
+    /** 声明端点（declaredEndpoint）出数：数字来自用户配置的取值路径，界面据此标注。 */
+    declared?: boolean;
+    /** 声明端点未解析出字段 / 安全边界拒绝时的原因文本（配置问题，而非上游故障）。 */
+    reason?: string;
+    /** 声明端点给出的滚动额度窗口（与订阅面板同款）。 */
+    windows?: readonly SubscriptionWindow[];
+    /** 订阅套餐名（声明端点读出的 plan 字段）。 */
+    plan?: string;
 }
 /** Response of `/api/billing/balance` consumed by the dashboard. */
 export interface BalanceResponse {
     balances: readonly ProviderBalance[];
+    /** 官方余额差对账提示（对账开启且当日有余额消费时下发）。 */
+    reconcile?: ReconcileNotice;
+}
+/** 官方余额差对账提示（drift 时携带供 UI 展示的已用/本地费用）。 */
+export interface ReconcileNotice {
+    kind: 'baseline' | 'structure-reset' | 'flat' | 'ok' | 'drift';
+    /** 余额提供商显示名（如 DeepSeek）；仅 `ok`/`drift`。 */
+    provider?: string;
+    /** 余额币种（CNY / USD）。 */
+    currency?: string;
+    /** 按余额差反推的当日消费；仅 `ok`/`drift`。 */
+    spent?: number;
+    /** 本地账本当日的官方渠道费用（CNY）；仅 `ok`/`drift`。 */
+    todayOfficialCost?: number;
 }
 /** Quota query result status; the dashboard maps each to a row state. */
 export type SubscriptionStatus = 'ok' | 'not-configured' | 'unauthorized' | 'rate-limited' | 'unavailable' | 'invalid-response';
@@ -98,6 +120,8 @@ export interface SubscriptionQuota {
     planType?: 'code' | 'token';
     /** 订阅月费（人民币元；code 计划用，计入「本月预计」）。 */
     subscriptionAmount?: number;
+    /** 面向用户的配置提示（如 OpenRouter 额度接口只认 Management Key）。 */
+    hint?: string;
 }
 /** Response of `/api/billing/subscriptions`. */
 export interface SubscriptionResponse {
@@ -178,4 +202,64 @@ export interface CustomBalanceConfig {
         remaining: CustomBalanceExtract;
     };
 }
+/** 声明端点的一个滚动窗口输入：`kind`/`minutes` 是字面值，其余是响应里的取值路径。 */
+export interface DeclaredWindowConfig {
+    /** 窗口周期：session / weekly / monthly / billing。 */
+    kind?: SubscriptionWindow['kind'];
+    /** 窗口分钟周期（用于按 resetInSeconds 推算周期；缺省不推）。 */
+    minutes?: number;
+    /** 已用百分比（0–100，取值路径）。 */
+    usedPercent?: string;
+    /** 已用比例（0–1，取值路径）。 */
+    usedRatio?: string;
+    /** 剩余百分比（取值路径）。 */
+    remainingPercent?: string;
+    /** 已用量（取值路径）。 */
+    used?: string;
+    /** 总量（取值路径）。 */
+    limit?: string;
+    /** 重置时刻（ISO 字符串，取值路径）。 */
+    resetsAt?: string;
+    /** 距重置剩余秒数（取值路径）。 */
+    resetInSeconds?: string;
+}
+/** 声明端点的字段取值路径：值里写的是响应 JSON 里的点路径，不是表达式。 */
+export interface DeclaredEndpointFields {
+    /** 余额总量（取值路径）。 */
+    total?: string;
+    /** 赠金余额（取值路径）。 */
+    granted?: string;
+    /** 已用（取值路径）。 */
+    used?: string;
+    /** 币种（取值路径）。 */
+    currency?: string;
+    /** 套餐名（取值路径）。 */
+    plan?: string;
+}
+/**
+ * 一个声明端点配置（插件 config 的 `declaredEndpoints` 条目）。用户为内置表
+ * 没有的供应商自声明余额/额度接口。
+ *
+ * 安全边界写死在代码里，不靠自觉（详见 declarative.ts）：
+ * - `origin` 只是查找键，请求必须发往某条**已配置** provider 的同源地址；
+ * - `path` 必须单斜杠绝对路径（`//host/x` 是协议相对 URL，会解析到别的主机）；
+ * - 只发 GET、无请求体、无自定义 method/headers；
+ * - 凭据仍从匹配 provider 自己的 `apiKeyEnv` 取，声明不能指定凭据；
+ * - 跨源重定向直接失败；响应体有大小上限与超时；
+ * - 不能覆盖内置读法，只在内置表答不上来时轮到它。
+ */
+export interface DeclaredEndpointConfig {
+    /** 查找键：必须匹配某条已配置 provider 的 baseURL 同源地址。 */
+    origin: string;
+    /** 显示名；缺省用 `已声明`。 */
+    displayName?: string;
+    /** 余额端点（单斜杠绝对路径，基于匹配 provider 的 origin 构造）。 */
+    path: string;
+    /** 裸密钥模式：true 时不加 `Bearer ` 前缀（某些控制台接口要裸 key）。 */
+    raw?: boolean;
+    /** 字段取值路径。 */
+    fields?: DeclaredEndpointFields;
+    /** 滚动额度窗口列表。 */
+    windows?: readonly DeclaredWindowConfig[];
+}
 //# sourceMappingURL=pricing-shared.d.ts.map

package/lib/types/reconcile.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 余额差交叉校验（reconcile）：用官方账户余额当日变动反推消费，与本地账本
+ * 的当日官方费用比对。若二者偏差超阈值，提示用户核对价格表或近期账单——
+ * 这是让计费数据可信的兜底机制，也是对账的稳定锚点。
+ *
+ * 只对官方直连渠道（DeepSeek 官方）对账：订阅 / Coding Plan / 第三方中转的
+ * 消费不动官方余额，强行用余额差替代今日费用会把订阅用户全天的消费归零。
+ * 充值、授信、币种变化都会让旧基准失去可比性，此时重置基准而非告警。
+ *
+ * 纯函数：输入上一基准与本次余额查询结果，输出新基准与对账事件，可独立单测。
+ */
+/** 对账基准快照：上次余额查询时的官方账户状态，用于反推当日消费。 */
+export interface BalanceRef {
+    /** 本地日期键（YYYY-MM-DD）。 */
+    date: string;
+    /** 当日总余额。 */
+    total: number;
+    /** 未过期赠金。 */
+    granted: number;
+    /** 充值余额。 */
+    topped: number;
+    /** 余额币种（CNY / USD）。 */
+    currency: string;
+    /** 打基准时刻（epoch ms）。 */
+    at: number;
+}
+/** 一次对账的结果类别。 */
+export type ReconcileKind = 'baseline' | 'structure-reset' | 'flat' | 'ok' | 'drift';
+/** 对账事件：`ok`/`drift`/`flat` 携带有意义的结果，`baseline`/`structure-reset` 仅为无消费的基准刷新。 */
+export interface ReconcileEvent {
+    kind: ReconcileKind;
+    /** 余额提供商显示名（如 DeepSeek）；仅 `ok`/`drift`。 */
+    provider?: string;
+    /** 按余额差反推的当日消费（CNY/USD 按余额币种）；仅 `ok`/`drift`。 */
+    spent?: number;
+    /** 本地账本当日的官方渠道费用；仅 `ok`/`drift`。 */
+    todayOfficialCost?: number;
+}
+/** 余额查询结果的最小视图（对账只关心这三个分项与币种）。 */
+interface BalanceSnapshot {
+    totalBalance?: number;
+    grantedBalance?: number;
+    toppedUpBalance?: number;
+    currency?: string;
+}
+/**
+ * 对账：用官方余额当日变动反推消费，与本地账本当日官方费用比对。
+ * @param prevRef - 上一基准（可为 null，表示首次/基准缺失）。
+ * @param balance - 本次余额查询结果。
+ * @param todayOfficialCost - 本地账本当日的官方渠道费用（CNY）。
+ * @param dayKey - 本地日期键（YYYY-MM-DD）。
+ * @param nowMs - 当前时刻（epoch ms）。
+ * @returns 新基准与对账事件；余额不可用（无 totalBalance）时返回 `{ ref: prevRef, event: null }`。
+ */
+export declare function reconcileBalanceDelta(prevRef: BalanceRef | null, balance: BalanceSnapshot, todayOfficialCost: number, dayKey: string, nowMs: number): {
+    ref: BalanceRef | null;
+    event: ReconcileEvent | null;
+};
+export {};
+//# sourceMappingURL=reconcile.d.ts.map

package/lib/types/relay.d.ts

@@ -44,6 +44,12 @@ export declare function parseSub2ApiUsage(data: unknown): {
 export declare function parseNewApiStatus(data: unknown): {
     windows?: readonly SubscriptionWindow[];
 } | null;
+/**
+ * 判断一个 baseURL 是否指向已知官方端点（而非第三方中转站）。
+ * @param baseURL - llm-pi-ai provider 路由的端点地址。
+ * @returns 官方端点返回 true（中转站面板应排除）。
+ */
+export declare function isOfficialBaseUrl(baseURL: string): boolean;
 /**
  * 查询单个中转站路由的额度。先试 Sub2API，再试 New API；任一读出额度即返回。
  * @param ctx - host context carrying the credentials seam.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kenz1117/dsh-ui-usage-billing",
   "description": "Usage billing dashboard for DeepSeek Harness: sidebar cost metrics plus a full dashboard modal, priced from a current multi-provider catalog with real usage aggregated from session logs.",
-  "version": "0.9.16",
+  "version": "0.9.18",
   "publishConfig": {
     "access": "public"
   },