@kenz1117/dsh-ui-usage-billing 1.6.7 → 1.7.0

package/lib/types/client/live-cost.d.ts

@@ -21,6 +21,7 @@
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import type { LiveCostBarPrefs } from './usage-billing-settings.ts';
 import type { UsageBillingKey } from './locales.ts';
+import type { UseProjection } from '@deepseek-ai/dsh-api-session-controller/client';
 /** The usage-stats shape the composer bar needs (a thin slice, not the whole doc). */
 export interface LiveStats {
     bySession?: readonly {
@@ -116,6 +117,12 @@ export declare function isBlankPhase(session: SessionPhaseSlice): boolean;
 export interface LiveCostBarProps {
     /** Current Session identity supplied by the session-scope standard kit. */
     sessionId: SessionId;
+    /**
+     * Host projection reader (session-scope standard kit). Present only on hosts
+     * that serve session projections; absent → no context dimension (the
+     * dashboard hides that card entirely rather than showing zeros).
+     */
+    useProjection?: UseProjection;
     /** The owning seat's locale seat (bound to the billing NS). */
     t: (key: UsageBillingKey) => string;
     /** Which host seat this instance occupies; it renders only when the position pref matches. */
@@ -128,7 +135,7 @@ export interface LiveCostBarProps {
  * @param props - framework session identity, locale, the seat occupied, and
  * (input.dock only) the owner session snapshot.
  */
-export declare function LiveCostBar({ sessionId, t, seat, session }: LiveCostBarProps): React.ReactNode;
+export declare function LiveCostBar({ sessionId, t, seat, session, useProjection }: LiveCostBarProps): React.ReactNode;
 /** Props of the tool-row chip: session identity and locale only (its seat is fixed to input.right). */
 export type LiveCostChipProps = Pick<LiveCostBarProps, 'sessionId' | 't'>;
 /**

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

@@ -1,5 +1,5 @@
 /** Locale dictionaries for the usage billing surface. */
-export type UsageBillingKey = 'title' | 'cost' | 'todayCost' | 'monthCost' | 'yearCost' | 'monthProjected' | 'liveTurn' | 'liveSession' | 'liveSessionSub' | 'calls' | 'cacheHitRate' | 'tokens' | 'inputTokens' | 'outputTokens' | 'avgCost' | 'kpiRange' | 'avgRangeToday' | 'avgRange7d' | 'avgRangeWeek' | 'avgRangeMonth' | 'avgRangeAll' | 'trend' | 'trend7d' | 'trend30d' | 'trendMetric' | 'trendMetricCost' | 'trendMetricTokens' | 'pricingSearch' | 'bandPinHint' | 'trendEmpty' | 'trendTotal' | 'roundsUnit' | 'healthModelsLive' | 'healthVendorsDown' | 'healthVendorsUnavailable' | 'budget' | 'budgetRemain' | 'budgetAmount' | 'budgetSummary' | 'sessions' | 'sessionTitle' | 'lastActive' | 'sessionOverflow' | 'budgetTierBody' | 'models' | 'providerBilling' | 'channelUnknown' | 'directTag' | 'relayTag' | 'unknownTag' | 'unknownChannelHint' | 'planCountUnit' | 'actual' | 'pricing' | 'input' | 'output' | 'cacheHit' | 'peak' | 'offPeak' | 'flat' | 'band' | 'close' | 'footer' | 'footerCredit' | 'lastUpdated' | 'noData' | 'todayRate' | 'rateLive' | 'rateBuiltin' | 'pricingSyncedAt' | 'pricingSyncNow' | 'pricingSyncing' | 'promoBadge' | 'promoUntil' | 'promoOpenEnded' | 'pricingTip' | 'pricingUnit' | 'pricingNotes' | 'ubPeak' | 'ubOff' | 'ubStd' | 'peakBand' | 'pricingSource' | 'noteCache' | 'noteBand' | 'noteSource' | 'balance' | 'recharge' | 'rechargeHint' | 'balanceUnconfigured' | 'balanceUnauthorized' | 'balanceUnreachable' | 'uncatalogued' | 'estimatedPricing' | 'balanceDays' | 'balanceLowBody' | 'reconcileDrift' | 'reconcileDismiss' | 'subscriptionNotConfigured' | 'subscriptionUnauthorized' | 'subscriptionUnavailable' | 'subscriptionInvalid' | 'subscriptionRateLimited' | 'subscriptionSession' | 'subscriptionWeekly' | 'subscriptionMonthly' | 'subscriptionBilling' | 'subscriptionRemaining' | 'subscriptionExhausted' | 'subscriptionReset' | 'subscriptionNoApi' | 'floatWindow' | 'floatModeCombined' | 'floatModeSubscription' | 'floatMode' | 'floatTargets' | 'floatWindowHint' | 'floatPrimaryToday' | 'floatPrimaryWeek' | 'floatPrimaryMonth' | 'floatNoTargets' | 'floatNoTargetsHint' | 'cardDisplay' | 'cardDisplayHint' | 'cardMetric' | 'cardMetricMoney' | 'cardMetricTokens' | 'cardSpan' | 'cardSpanDay' | 'cardSpanWeek' | 'cardSpanMonth' | 'cardDeltaBadge' | 'cardDeltaShow' | 'cardDeltaHide' | 'triggerMonthTokens' | 'triggerTodayTokens' | 'triggerWeekTokens' | 'subscriptionsStale' | 'staleLedgerNotice' | 'unreadableNotice' | 'unreadableFormatNotice' | 'unreadableNoLedgerNotice' | 'tokenCacheWrite' | 'toolRank' | 'toolName' | 'userPrices' | 'userPricesHint' | 'userPriceSave' | 'userPriceModel' | 'userPriceSource' | 'userPriceSourceHint' | 'userPriceOffPeak' | 'userPriceNormal' | 'userPriceCurrency' | 'userPriceAdd' | 'userPriceRemoveSelected' | 'userPriceSelect' | 'sessionStaleBadge' | 'sessionUntitled' | 'sessionSubCost' | 'sessionSubCalls' | 'sessionSubRow' | 'heatmapLess' | 'heatmapMore' | 'currency' | 'currencyCny' | 'currencyUsd' | 'currencyEur' | 'language' | 'heatmap' | 'rounds' | 'roundsHint' | 'anomaly' | 'model' | 'thModel' | 'thInputMiss' | 'thInputHit' | 'costAbbr' | 'tabOverview' | 'tabTrends' | 'tabProviders' | 'tabPricing' | 'tabSettings' | 'budgetHint' | 'peakAlertHint' | 'peakAlertDescPeak' | 'peakAlertDescOff' | 'peakAlertDescPeakZhipu' | 'peakAlertDescOffZhipu' | 'export' | 'exportCsvDay' | 'exportCsvSession' | 'exportJson' | 'peakShare' | 'peakSharePerCall' | 'offPeakSavings' | 'perfMax' | 'weekCost' | 'roleCost' | 'roleUser' | 'roleAssistant' | 'roleTool' | 'roleHint' | 'tierPeak' | 'tierOff' | 'tierToPeak' | 'tierToOff' | 'tierAlertEnterPeak' | 'tierAlertEnterOff' | 'tierAlertEnterPeakZhipu' | 'tierAlertEnterOffZhipu' | 'peakAlertTitlePeak' | 'peakAlertTitleOff' | 'peakAlert' | 'peakAlertLeadMin' | 'peakAlertPos' | 'peakAlertMode' | 'peakAlertPosCorner' | 'peakAlertPosCenter' | 'peakAlertModePeak' | 'peakAlertModeOff' | 'peakAlertModeBoth' | 'peakAlertWebNotify' | 'peakAlertPreview' | 'planTypeCode' | 'planTypeToken' | 'subscriptionFeePerMonth' | 'triggerToday' | 'triggerMonth' | 'subscriptionTag' | 'cellEstimateHint' | 'free' | 'perfSamples' | 'perfTtft' | 'perfP50' | 'perfP90' | 'perfTps' | 'perfLatency' | 'perfEstimated' | 'perfEmpty' | 'perfTpsUnit' | 'perfTitle' | 'perfHint' | 'perfAll' | 'perfChartEmpty' | 'heatmapYear' | 'heatmapHalf' | 'heatmapMonth' | 'metricCost' | 'metricTokens' | 'heatmapTotal' | 'activeDays' | 'streakDays' | 'subscriptionAutoDetect' | 'pluginAuthor' | 'pluginRepository' | 'pluginNpm' | 'pluginLicense' | 'tabToken' | 'tokenExport' | 'tokenExportCsv' | 'tokenReasoningShare' | 'tokenReasoningShort' | 'tokenIo' | 'tokenPeak' | 'densityLabel' | 'densityHint' | 'densityCompact' | 'densityDefault' | 'densityComfortable' | 'motionLabel' | 'motionHint' | 'motionOff' | 'motionSubtle' | 'motionRich' | 'settingsNavDisplayPref' | 'settingsNavBudget' | 'settingsNavAlert' | 'settingsNavDisplay' | 'settingsNavAdvanced' | 'settingsNavAbout' | 'settingsSearchPlaceholder' | 'settingsSearchEmpty' | 'sessionsViewAll' | 'sessionViewerSearch' | 'modelBudgetTitle' | 'modelBudgetHint' | 'modelBudgetBody' | 'modelBudgetPlaceholder' | 'moreWorksTitle' | 'adEngramName' | 'adEngramDesc' | 'adRainbowName' | 'adRainbowDesc' | 'kpiDescCacheHit' | 'kpiDescTokens' | 'kpiDescAvgCost' | 'kpiDescCalls' | 'kpiDescReasoning' | 'kpiDescIo' | 'kpiDescPeak' | 'healthDotLive' | 'healthDotFailed' | 'healthDotUnknown' | 'settingsSectionDisplay' | 'emptyHint' | 'tokenDaily' | 'tokenByModel' | 'tokenMiss' | 'tokenHit' | 'tokenOutput' | 'tokenViewStructure' | 'tokenViewModel' | 'tokenHitShort' | 'tokenMissShort' | 'tokenTotal' | 'tokenShare' | 'usageStatsTool' | 'usageStatsToolHint' | 'balanceGranted' | 'balanceTopped' | 'balanceDaily' | 'balanceDaysLong' | 'balanceDaysUnit' | 'popTodayModel' | 'popNoConsumption' | 'popTitle' | 'popDirectLead' | 'popSubLead' | 'unpricedHint' | 'searchEstimateHint' | 'siteListDisplay' | 'siteListDisplayHint' | 'liveCostBar' | 'liveCostBarHint' | 'liveCostBarPosition' | 'liveCostBarPosBelow' | 'liveCostBarPosAbove' | 'liveCostBarPosToolbar' | 'exportCsvSite' | 'panelRelayQuota' | 'relayBalance' | 'relayNoQuota' | 'relayWindowUsed' | 'relayKindNewApi' | 'relayKindSub2Api' | 'relayKindUnknown' | 'expandAll' | 'collapseAll' | 'todayOnly' | 'todayNoConsumption';
+export type UsageBillingKey = 'title' | 'cost' | 'todayCost' | 'monthCost' | 'yearCost' | 'monthProjected' | 'liveTurn' | 'liveSession' | 'liveSessionSub' | 'calls' | 'cacheHitRate' | 'tokens' | 'inputTokens' | 'outputTokens' | 'avgCost' | 'kpiRange' | 'avgRangeToday' | 'avgRange7d' | 'avgRangeWeek' | 'avgRangeMonth' | 'avgRangeAll' | 'trend' | 'trend7d' | 'trend30d' | 'trendMetric' | 'trendMetricCost' | 'trendMetricTokens' | 'pricingSearch' | 'bandPinHint' | 'trendEmpty' | 'trendTotal' | 'roundsUnit' | 'healthModelsLive' | 'healthVendorsDown' | 'healthVendorsUnavailable' | 'budget' | 'budgetRemain' | 'budgetAmount' | 'budgetSummary' | 'sessions' | 'sessionTitle' | 'lastActive' | 'sessionOverflow' | 'budgetTierBody' | 'models' | 'providerBilling' | 'channelUnknown' | 'directTag' | 'relayTag' | 'unknownTag' | 'unknownChannelHint' | 'planCountUnit' | 'actual' | 'pricing' | 'input' | 'output' | 'cacheHit' | 'peak' | 'offPeak' | 'flat' | 'band' | 'close' | 'footer' | 'footerCredit' | 'lastUpdated' | 'noData' | 'todayRate' | 'rateLive' | 'rateBuiltin' | 'pricingSyncedAt' | 'pricingSyncNow' | 'pricingSyncing' | 'promoBadge' | 'promoUntil' | 'promoOpenEnded' | 'pricingTip' | 'pricingUnit' | 'pricingNotes' | 'ubPeak' | 'ubOff' | 'ubStd' | 'peakBand' | 'pricingSource' | 'noteCache' | 'noteBand' | 'noteSource' | 'balance' | 'recharge' | 'rechargeHint' | 'balanceUnconfigured' | 'balanceUnauthorized' | 'balanceUnreachable' | 'uncatalogued' | 'estimatedPricing' | 'balanceDays' | 'balanceLowBody' | 'reconcileDrift' | 'reconcileDismiss' | 'subscriptionNotConfigured' | 'subscriptionUnauthorized' | 'subscriptionUnavailable' | 'subscriptionInvalid' | 'subscriptionRateLimited' | 'subscriptionSession' | 'subscriptionWeekly' | 'subscriptionMonthly' | 'subscriptionBilling' | 'subscriptionRemaining' | 'subscriptionExhausted' | 'subscriptionReset' | 'subscriptionNoApi' | 'floatWindow' | 'floatModeCombined' | 'floatModeSubscription' | 'floatMode' | 'floatTargets' | 'floatWindowHint' | 'floatPrimaryToday' | 'floatPrimaryWeek' | 'floatPrimaryMonth' | 'floatNoTargets' | 'floatNoTargetsHint' | 'cardDisplay' | 'cardDisplayHint' | 'cardMetric' | 'cardMetricMoney' | 'cardMetricTokens' | 'cardSpan' | 'cardSpanDay' | 'cardSpanWeek' | 'cardSpanMonth' | 'cardDeltaBadge' | 'cardDeltaShow' | 'cardDeltaHide' | 'triggerMonthTokens' | 'triggerTodayTokens' | 'triggerWeekTokens' | 'subscriptionsStale' | 'balanceStaleNotice' | 'staleLedgerNotice' | 'staleSnapshotNotice' | 'unreadableNotice' | 'unreadableFormatNotice' | 'unreadableNoLedgerNotice' | 'tokenCacheWrite' | 'toolRank' | 'toolName' | 'userPrices' | 'userPricesHint' | 'userPriceSave' | 'userPriceModel' | 'userPriceSource' | 'userPriceSourceHint' | 'userPriceOffPeak' | 'userPriceNormal' | 'userPriceCurrency' | 'userPriceAdd' | 'userPriceRemoveSelected' | 'userPriceSelect' | 'sessionStaleBadge' | 'sessionUntitled' | 'sessionSubCost' | 'sessionSubCalls' | 'sessionSubRow' | 'heatmapLess' | 'heatmapMore' | 'currency' | 'currencyCny' | 'currencyUsd' | 'currencyEur' | 'language' | 'heatmap' | 'rounds' | 'roundsHint' | 'anomaly' | 'model' | 'thModel' | 'thInputMiss' | 'thInputHit' | 'costAbbr' | 'tabOverview' | 'tabTrends' | 'tabProviders' | 'tabPricing' | 'tabSettings' | 'budgetHint' | 'peakAlertHint' | 'peakAlertDescPeak' | 'peakAlertDescOff' | 'peakAlertDescPeakZhipu' | 'peakAlertDescOffZhipu' | 'export' | 'exportCsvDay' | 'exportCsvSession' | 'exportJson' | 'peakShare' | 'peakSharePerCall' | 'offPeakSavings' | 'perfMax' | 'weekCost' | 'roleCost' | 'roleUser' | 'roleAssistant' | 'roleTool' | 'roleHint' | 'tierPeak' | 'tierOff' | 'tierToPeak' | 'tierToOff' | 'tierAlertEnterPeak' | 'tierAlertEnterOff' | 'tierAlertEnterPeakZhipu' | 'tierAlertEnterOffZhipu' | 'peakAlertTitlePeak' | 'peakAlertTitleOff' | 'peakAlert' | 'peakAlertLeadMin' | 'peakAlertPos' | 'peakAlertMode' | 'peakAlertPosCorner' | 'peakAlertPosCenter' | 'peakAlertModePeak' | 'peakAlertModeOff' | 'peakAlertModeBoth' | 'peakAlertWebNotify' | 'peakAlertPreview' | 'planTypeCode' | 'planTypeToken' | 'subscriptionFeePerMonth' | 'triggerToday' | 'triggerMonth' | 'subscriptionTag' | 'cellEstimateHint' | 'free' | 'perfSamples' | 'perfTtft' | 'perfP50' | 'perfP90' | 'perfTps' | 'perfLatency' | 'perfEstimated' | 'perfEmpty' | 'perfTpsUnit' | 'perfTitle' | 'perfHint' | 'perfAll' | 'perfChartEmpty' | 'heatmapYear' | 'heatmapHalf' | 'heatmapMonth' | 'metricCost' | 'metricTokens' | 'heatmapTotal' | 'activeDays' | 'streakDays' | 'subscriptionAutoDetect' | 'pluginAuthor' | 'pluginRepository' | 'pluginNpm' | 'pluginLicense' | 'tabToken' | 'tokenExport' | 'tokenExportCsv' | 'tokenReasoningShare' | 'tokenReasoningShort' | 'tokenIo' | 'tokenPeak' | 'densityLabel' | 'densityHint' | 'densityCompact' | 'densityDefault' | 'densityComfortable' | 'motionLabel' | 'motionHint' | 'motionOff' | 'motionSubtle' | 'motionRich' | 'settingsNavDisplayPref' | 'settingsNavBudget' | 'settingsNavAlert' | 'settingsNavDisplay' | 'settingsNavAdvanced' | 'settingsNavAbout' | 'settingsSearchPlaceholder' | 'settingsSearchEmpty' | 'sessionsViewAll' | 'sessionViewerSearch' | 'modelBudgetTitle' | 'modelBudgetHint' | 'modelBudgetBody' | 'modelBudgetPlaceholder' | 'moreWorksTitle' | 'adEngramName' | 'adEngramDesc' | 'adRainbowName' | 'adRainbowDesc' | 'kpiDescCacheHit' | 'kpiDescTokens' | 'kpiDescAvgCost' | 'kpiDescCalls' | 'kpiDescReasoning' | 'kpiDescIo' | 'kpiDescPeak' | 'healthDotLive' | 'healthDotFailed' | 'healthDotUnknown' | 'settingsSectionDisplay' | 'emptyHint' | 'tokenDaily' | 'tokenByModel' | 'tokenMiss' | 'tokenHit' | 'tokenOutput' | 'tokenViewStructure' | 'tokenViewModel' | 'tokenHitShort' | 'tokenMissShort' | 'tokenTotal' | 'tokenShare' | 'usageStatsTool' | 'usageStatsToolHint' | 'balanceGranted' | 'balanceTopped' | 'balanceDaily' | 'balanceDaysLong' | 'balanceDaysUnit' | 'popTodayModel' | 'popNoConsumption' | 'popTitle' | 'popDirectLead' | 'popSubLead' | 'unpricedHint' | 'searchEstimateHint' | 'siteListDisplay' | 'siteListDisplayHint' | 'liveCostBar' | 'liveCostBarHint' | 'liveCostBarPosition' | 'liveCostBarPosBelow' | 'liveCostBarPosAbove' | 'liveCostBarPosToolbar' | 'exportCsvSite' | 'panelRelayQuota' | 'relayBalance' | 'relayNoQuota' | 'relayWindowUsed' | 'relayKindNewApi' | 'relayKindSub2Api' | 'relayKindUnknown' | 'expandAll' | 'collapseAll' | 'todayOnly' | 'todayNoConsumption' | 'commandUsageLabel' | 'commandUsageDescription' | 'sessionOpen' | 'sessionOpenFailed' | 'sessionOpenUnavailable' | 'contextOccupancy' | 'contextWindow' | 'contextSystem' | 'contextTools' | 'contextMessages' | 'contextNoData' | 'tabContext' | 'tabAgents' | 'contextNextRequest' | 'contextLastRequest' | 'contextComposition' | 'contextCompositionHint' | 'agentsSummary' | 'agentsCount' | 'agentsDelegations' | 'agentsRoots' | 'agentsMostExpensive' | 'agentsChainTotal' | 'agentsNoData' | 'agentsSubagent' | 'agentsRoot';
 export declare const NS = "usageBilling";
 export declare const zh: Record<UsageBillingKey, string>;
 export declare const en: Record<UsageBillingKey, string>;

package/lib/types/client/session-navigation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 会话跳转（跨插件导航）：把面板里的会话行接到宿主的会话选择通道。
+ *
+ * 宿主有**两代**通道（实测自 deepseek-harness 源码，非推测）：
+ * - 0.1.6-alpha.2+：`ctx.uiWorkspace.openSession(SessionId)`
+ *   （@deepseek-ai/dsh-client-ui-workspace，packages/client/ui-workspace/src/client/navigation.ts:36）
+ * - 0.1.2-alpha.1 ~ 0.1.6-alpha.1：`ctx.sessions.open(SessionId)`
+ *   （@deepseek-ai/dsh-api-session-controller，packages/api/session-controller/src/client/contract/sessions.ts:44
+ *    —— 注释写明「id 必须在列表中，不存在则 fail loud」）
+ * master 已移除 `sessions.open`，故运行时按「新 → 旧」探测，两条都不可用时降级为不可跳转。
+ *
+ * 取服务一律走 `ctx.get()`（cordis 的免 inject 服务读取），**不进 inject 列表**：
+ * 老宿主没有 uiWorkspace 服务，把它声明成注入依赖会挂起等它、卡住整个 web 启动
+ * （本仓 apply.ts 对 remote.llm 的注释记过这个坑：issue #28 的同源教训）。
+ *
+ * 老宿主的 `sessions.open` 对未知 id 会 fail loud——本插件的会话行来自**持久化会话
+ * 日志**，可能不在宿主当前会话列表里（删过、别的 profile、只读快照），故调用必须
+ * 包 try/catch 并把失败如实回报给 UI，不得让点击抛错。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** 跳转结果：opened=已跳转；unavailable=宿主无通道（老到没有）；failed=通道报错。 */
+export type SessionNavigationResult = 'opened' | 'unavailable' | 'failed';
+/** 会话跳转器：面板用它把「点会话行」接到宿主导航。 */
+export interface SessionNavigator {
+    /** 当前宿主是否具备跳转能力（运行时探测，服务可能后到）。 */
+    available(): boolean;
+    /** 打开指定会话；返回结果供 UI 决定是否提示。 */
+    open(sessionId: string): SessionNavigationResult;
+}
+/**
+ * 构造会话跳转器。
+ * @param ctx - 客户端根 context（服务读取走 ctx.get，不声明注入依赖）。
+ * @returns 跳转器。
+ */
+export declare function createSessionNavigator(ctx: Context): SessionNavigator;
+//# sourceMappingURL=session-navigation.d.ts.map

package/lib/types/client/usage-command.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `/usage` 对话内命令：把计费仪表盘拉进对话流。
+ *
+ * 宿主能力（@deepseek-ai/dsh-client-ui-commands，`ctx.commandUi`）：
+ * - `register(contribution)` 注册一个**客户端自有**的斜杠命令，与宿主命令目录按
+ *   名字合并；同名撞宿主命令会 fail loud（绝不遮蔽宿主命令）——故命令名取
+ *   `usage`，宿主目录里没有同名命令。
+ * - `contribution.ui` 用 `{ kind: 'action', run(session) }`：行为完全在客户端，
+ *   不回传宿主命令执行器。
+ * - `label` / `description` 是**函数**：菜单每次打开都重新读取，切换语言立即生效，
+ *   无需重新注册。
+ *
+ * 取服务走 `ctx.get('commandUi')`（cordis 免 inject 读取）：老宿主没有该服务时
+ * **不注册命令**，面板功能完全不受影响——这是「服务缺席即降级、不得因此收窄兼容
+ * 矩阵」的落点（宿主自己的 ui-permission-presets 也是 `ctx.get('commandUi')`）。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** 命令名（斜杠后不带斜杠）：与宿主命令目录合并的键。 */
+export declare const USAGE_COMMAND_NAME = "usage";
+/** 注册参数。 */
+export interface UsageCommandOptions {
+    /** 打开计费仪表盘（复用面板已注册的打开回调）。 */
+    openDashboard: () => void;
+    /** 菜单行标题（每次候选合成时读取，语言切换即时生效）。 */
+    label: () => string;
+    /** 菜单行描述。 */
+    description: () => string;
+}
+/**
+ * 注册 `/usage` 命令。
+ *
+ * @param ctx - 客户端根 context。
+ * @param options - 打开回调与文案。
+ * @returns 是否注册成功（宿主无 commandUi 服务时返回 false，属正常降级）。
+ */
+export declare function registerUsageCommand(ctx: Context, options: UsageCommandOptions): boolean;
+//# sourceMappingURL=usage-command.d.ts.map

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

@@ -78,6 +78,12 @@ export interface BalanceResponse {
     balances: readonly ProviderBalance[];
     /** 官方余额差对账提示（对账开启且当日有余额消费时下发）。 */
     reconcile?: ReconcileNotice;
+    /**
+     * 本次余额来自上一次成功的查询（服务端刷新超预算，issue #104）：
+     * 上游查询被拖住时不再把响应长期挂起，改为回旧值并标记，客户端据此提示
+     * 「余额数据来自上次查询」。
+     */
+    stale?: boolean;
 }
 /** 官方余额差对账提示（drift 时携带供 UI 展示的已用/本地费用）。 */
 export interface ReconcileNotice {

package/lib/types/routes/balance.d.ts

@@ -5,8 +5,9 @@
  * TokenHub 等）+ 用户自定义余额 + 声明端点 + 余额差对账。5 分钟缓存（避免
  * 每 30s 后台轮询打上游），in-flight 去重（并发请求共享同一次进行中的刷新）。
  *
- * 路由文件只关心 HTTP 缓存逻辑：5 分钟过期判定 + 失败时仍发旧缓存（不挂起
- * 已 writeHead 的响应）。上游查询（queryBalances / queryCustomBalances /
+ * 路由文件只关心 HTTP 缓存逻辑：5 分钟过期判定 + 刷新预算（超预算回旧
+ * 缓存并标 stale，不把响应挂在长查询上）+ 失败时仍发旧缓存（不挂起已
+ * writeHead 的响应）。上游查询（queryBalances / queryCustomBalances /
  * queryDeclaredEndpoints / reconcileBalanceDelta）在装配器里跑，路由只通过
  * `cached()` 与 `refreshOnce()` 拿到结果。
  */
@@ -17,6 +18,11 @@ import type { ReconcileEvent } from '../reconcile.ts';
 export interface BalanceDoc {
     balances: readonly ProviderBalance[];
     reconcile?: ReconcileEvent;
+    /**
+     * 本次余额来自上一次成功的查询（刷新超预算，见 {@link BalanceDeps.responseBudgetMs}）。
+     * 客户端据此提示「余额数据来自上次查询」，别把旧值当最新读。
+     */
+    stale?: boolean;
 }
 interface CachedBalance {
     doc: BalanceDoc;
@@ -31,6 +37,16 @@ export interface BalanceDeps {
     refreshOnce: () => Promise<void>;
     /** 5 分钟缓存间隔（毫秒）。 */
     cacheMs: number;
+    /**
+     * 刷新的总等待预算（毫秒）：超预算立刻回上一次成功的余额。
+     *
+     * 存在的理由（issue #104）：浏览器对同源最多 6 条并发连接，而余额响应被
+     * 上游查询（最坏 8s 超时 × 重试）拖住时，这条连接会被长期占住；多标签页
+     * 各挂一条即占满连接池，宿主自己的资源请求排队——用户看到的是「整个 DSH
+     * 界面卡死」。预算到期后刷新在后台继续（in-flight 去重共享同一次刷新），
+     * 下一轮轮询即可拿到新值。
+     */
+    responseBudgetMs: number;
 }
 export declare function registerBalanceRoute(ctx: Context, deps: BalanceDeps): void;
 export {};

package/lib/types/routes/relay-quotas.d.ts

@@ -21,6 +21,14 @@ export interface RelayQuotasDeps {
     refreshOnce: () => Promise<void>;
     /** 5 分钟缓存间隔（毫秒）。 */
     cacheMs: number;
+    /**
+     * 刷新的总等待预算（毫秒）：超预算立刻回上一次成功的额度（stale 标记）。
+     *
+     * 与 balance 路由同因（issue #104）：中转站不可达时（8s 超时 × 重试）响应
+     * 会被长期挂住，占着浏览器的同源连接（每源 6 条）——多标签页各挂一条即让
+     * 宿主自己的资源请求排队，界面整体卡死。
+     */
+    responseBudgetMs: number;
 }
 export declare function registerRelayQuotasRoute(ctx: Context, deps: RelayQuotasDeps): void;
 export {};

package/lib/types/routes/subscriptions.d.ts

@@ -22,6 +22,14 @@ export interface SubscriptionsDeps {
     refreshOnce: () => Promise<void>;
     /** 5 分钟缓存间隔（毫秒）。 */
     cacheMs: number;
+    /**
+     * 刷新的总等待预算（毫秒）：超预算立刻回上一次成功的额度（stale 标记）。
+     *
+     * 与 balance 路由同因（issue #104）：上游额度接口不可达时（8s 超时 × 重试）
+     * 响应会被长期挂住，占着浏览器的同源连接（每源 6 条）——多标签页各挂一条
+     * 即让宿主自己的资源请求排队，界面整体卡死。
+     */
+    responseBudgetMs: number;
 }
 export declare function registerSubscriptionsRoute(ctx: Context, deps: SubscriptionsDeps): void;
 export {};

package/lib/types/routes/usage-stats.d.ts

@@ -37,6 +37,13 @@ export interface UsageStatsDeps {
     packageVersion: string;
     /** 等待预算（毫秒）：聚合在此预算内完成就回实时数据，超预算立即回最近快照。 */
     responseBudgetMs: number;
+    /**
+     * 最近一次**已完成**的聚合文档（只读，不触发新折叠）。
+     *
+     * 超预算时的第一回落：它比磁盘快照新（磁盘快照受落盘节流影响，最多落后数分钟；
+     * 内存文档只落后一个聚合周期）。从未完成过一次聚合时 undefined，继续回落磁盘快照。
+     */
+    lastDoc?: () => Record<string, unknown> | undefined;
 }
 /** 校验一份聚合文档；返回漂移原因（null = 形状正常）。纯只读，不改 doc。 */
 export declare function usageStatsShapeError(doc: unknown): string | null;

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": "1.6.7",
+  "version": "1.7.0",
   "keywords": [
     "deepseek-harness",
     "deepseek",
@@ -81,7 +81,8 @@
         "0.2.1-alpha.4": "compatible",
         "0.2.1-alpha.5": "compatible",
         "0.2.1-rc.1": "compatible",
-        "0.2.1-rc.2": "compatible"
+        "0.2.1-rc.2": "compatible",
+        "0.2.1-rc.3": "compatible"
       }
     }
   },
@@ -90,6 +91,7 @@
     "bundle": "tsdown",
     "watch": "tsdown --watch",
     "lint": "node scripts/lint.mjs && node scripts/check-clientbundle-sync.mjs",
+    "size": "node scripts/check-bundle-size.mjs",
     "test": "vitest run",
     "test:e2e": "playwright test",
     "test:e2e:install": "playwright install chromium"
@@ -110,6 +112,9 @@
     "@deepseek-ai/dsh-client-ui-primitives": "*",
     "@deepseek-ai/dsh-client-ui-sidebar": "*",
     "@deepseek-ai/dsh-client-ui-slots": "*",
+    "@deepseek-ai/dsh-client-ui-commands": "*",
+    "@deepseek-ai/dsh-client-ui-workspace": "*",
+    "@deepseek-ai/dsh-token-meter": "*",
     "@deepseek-ai/dsh-credentials": "*",
     "@deepseek-ai/dsh-home-paths": "*",
     "@deepseek-ai/dsh-host-webserver": "*",
@@ -129,36 +134,39 @@
     "@deepseek-ai/cordis": "*",
     "@deepseek-ai/cordis-plugin-include": "^1.0.7",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.5",
-    "@deepseek-ai/dsh-agent": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-api-gateway": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-api-remotes": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-api-session-controller": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-atomic-write": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-locale": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-store": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-sidebar": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-credentials": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-home-paths": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-host-webserver": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-agent": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-api-gateway": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-api-remotes": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-api-session-controller": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-atomic-write": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-locale": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-store": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-commands": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-workspace": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-sidebar": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-credentials": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-home-paths": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-host-webserver": "0.2.1-rc.3",
     "@deepseek-ai/dsh-invariants": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-ptc-runtime": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-sandbox": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-scope": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-session": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-session-persistence": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-settings": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-user-approval": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-util-code-language": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-util-workspace-path": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-ptc-runtime": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-sandbox": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-scope": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-session": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-session-persistence": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-settings": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-token-meter": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-user-approval": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-util-code-language": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-util-workspace-path": "0.2.1-rc.3",
     "@deepseek-ai/schemastery": "^3.18.4",
     "@playwright/test": "^1.64.1",
     "@shikijs/langs": "^4.3.1",