@kenz1117/dsh-ui-usage-billing 0.3.0 → 0.4.0

package/lib/types/aggregate.d.ts

@@ -11,12 +11,8 @@
  */
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence';
 import type { TokenUsage } from '@deepseek-ai/dsh-llm';
-/**
- * Real provider model ids map to their billing-catalog keys. Unknown ids stay
- * as-is and price zero (they are not in the catalog; subscription-plan routes
- * like kimi-coding / token plans fall here and therefore cost nothing).
- */
-export declare const MODEL_KEY_ALIASES: Readonly<Record<string, string>>;
+import { MODEL_KEY_ALIASES } from './client/pricing.ts';
+export { MODEL_KEY_ALIASES };
 /**
  * 走订阅套餐（coding / token plan / opencode 订阅）的 provider id：这些通道的
  * 调用按套餐计费，不再按 token 计费，因此即使模型 id 与计费表撞名也一律豁免。
@@ -51,10 +47,15 @@ export declare function emptyUsage(): ModelUsage;
  * @param usage - the provider-reported usage of one call.
  * @param key - the billing-catalog key this call belongs to.
  * @param subscription - whether the call went through a subscription plan; such calls never cost money.
+ * @param timeMs - the call's wall-clock time (epoch ms); drives peak/off-peak pricing.
  */
-export declare function foldUsage(acc: ModelUsage, usage: TokenUsage, key: string, subscription: boolean): void;
+export declare function foldUsage(acc: ModelUsage, usage: TokenUsage, key: string, subscription: boolean, timeMs: number): void;
 /** Local-time date stamp (the host runs in the user's timezone). */
 export declare function dayStamp(time: number): string;
+/** cwd 未知时工作区聚合的占位名（UI 显示 em dash，保持语言无关）。 */
+export declare const UNKNOWN_WORKSPACE_NAME = "\u2014";
+/** 工作区名：取 cwd 的末级目录名；无 cwd 时返回 {@link UNKNOWN_WORKSPACE_NAME}。 */
+export declare function workspaceNameOf(cwd: string | undefined): string;
 /**
  * The persistence surface the aggregate reads: enough of
  * `SessionPersistence` to list sessions and read each log once; `locate`
@@ -74,6 +75,10 @@ export interface UsageStatsDocument {
     byDayModels: Record<string, Record<string, ModelUsage>>;
     /** 会话明细：按费用倒序，封顶 {@link SESSION_ROW_LIMIT} 行；旧快照可能缺失。 */
     bySession: SessionUsageRow[];
+    /** 每轮费用明细：按起始时间倒序，封顶 {@link TURN_ROW_LIMIT} 行；旧快照可能缺失。 */
+    byTurn?: TurnUsageRow[];
+    /** 工作区聚合：按 cwd 末级目录归并，按费用倒序；旧快照可能缺失。 */
+    byWorkspace?: WorkspaceUsageRow[];
 }
 /** 会话明细行：仪表盘「会话明细」面板的数据源。 */
 export interface SessionUsageRow {
@@ -88,8 +93,42 @@ export interface SessionUsageRow {
     /** 最后一个事件的时间戳（毫秒）。 */
     lastActive: number;
 }
+/** 每轮费用明细行：仪表盘「每轮费用」图的数据源。 */
+export interface TurnUsageRow {
+    /** 会话 id（字符串形式）：不同会话的轮次号相互独立，展示时需区分。 */
+    sessionId: string;
+    /** 会话内轮次号。 */
+    turn: number;
+    /** 归因模型 key（计费目录键；未收录原样保留）。 */
+    model: string;
+    input: number;
+    output: number;
+    cacheHit: number;
+    cacheMiss: number;
+    /** 该轮成本（人民币元，按调用时刻精确判高峰/空闲档）。 */
+    cost: number;
+    /** 轮起始时刻（毫秒）。 */
+    startedAt: number;
+    /** 轮结束时刻（毫秒）；未结束轮缺失。 */
+    endedAt?: number;
+}
+/** 会话内折叠的每轮行（不含 sessionId，合并时补齐）。 */
+type SessionTurnRow = Omit<TurnUsageRow, 'sessionId'>;
+/** 工作区聚合行：按会话 cwd 的末级目录归并。 */
+export interface WorkspaceUsageRow {
+    /** 目录末级名；cwd 未知的会话归入「未命名」。 */
+    name: string;
+    calls: number;
+    cost: number;
+    input: number;
+    output: number;
+    /** 该工作区最近一次活跃时刻（毫秒）。 */
+    lastActive: number;
+}
 /** 会话明细行的响应封顶：控制 payload 体积，重度用户的完整长尾不逐行下发。 */
 export declare const SESSION_ROW_LIMIT = 100;
+/** 每轮费用行的响应封顶：同样控制 payload 体积。 */
+export declare const TURN_ROW_LIMIT = 200;
 /** 聚合文档的短 TTL（毫秒）：合并密集轮询，TTL 内直接复用上次的合并结果。 */
 export declare const AGGREGATE_TTL_MS = 5000;
 /** One persisted session's folded usage plus drill-down metadata. */
@@ -100,6 +139,8 @@ interface SessionFold {
     byDayModels: Map<string, Map<string, ModelUsage>>;
     /** 每个模型 key 在本会话内走订阅通道的调用数（合并时跨会话累加判定 plan）。 */
     planCalls: Map<string, number>;
+    /** 每轮费用明细（按轮次号升序，不含 sessionId）；sessionId 在合并时补齐。 */
+    turns: SessionTurnRow[];
     /** 日志里最新的 session/title 文本（无标题事件时 undefined）。 */
     title?: string;
     /** 最后一个事件的时间戳（毫秒）；空日志为 0。 */
@@ -107,7 +148,8 @@ interface SessionFold {
 }
 /**
  * Fold one session's events into a {@link SessionFold}. 每个 LLM 调用归属到
- * 其前置 request/header 记录的模型；同时提取最新会话标题与最后活跃时间。
+ * 其前置 request/header 记录的模型；同时提取最新会话标题、最后活跃时间，
+ * 并按轮次折叠每轮费用明细（turn/start → turn/end；调用按 (turn) 归组）。
  * @param events - the session's persisted events in log order.
  * @param subscriptionProviders - provider ids billed through subscription plans.
  * @returns the per-session fold (cached by the incremental aggregator).
@@ -140,5 +182,4 @@ export declare function createUsageAggregator(persistence: UsagePersistence, opt
  * @returns the usage-stats document (same shape the dashboard expects).
  */
 export declare function aggregateUsage(persistence: UsagePersistence, options?: AggregateOptions): Promise<UsageStatsDocument>;
-export {};
 //# sourceMappingURL=aggregate.d.ts.map

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

@@ -37,6 +37,21 @@ export declare function getRateInfo(): {
 };
 /** Default share of traffic assumed to fall in the peak band (0..1). */
 export declare const DEFAULT_PEAK_SHARE = 0.5;
+/** 计费时段档位：高峰 / 空闲（官方 DeepSeek 刊例价：高峰 = 空闲 × 2）。 */
+export type PriceTierId = 'peak' | 'offPeak';
+/** 成本显示币种：人民币（国内模型直价）/ 美元（国外模型直价或换算显示）。 */
+export type CostCurrency = 'cny' | 'usd';
+/**
+ * 高峰时段判定（北京时间，UTC+8，无夏令时）：09:00–12:00、14:00–18:00。
+ * @param beijingHour - 北京时间的小时数（0–23）。
+ */
+export declare function isPeakHour(beijingHour: number): boolean;
+/**
+ * 由时刻（epoch 毫秒）推断计费时段；时刻未知/非法时按高峰计（保守：未知
+ * 时刻不低估成本，与社区 dsh-usage-chart 的 tierAt 语义一致）。
+ * @param timeMs - Unix epoch 毫秒；null/undefined/NaN 视为未知。
+ */
+export declare function tierAt(timeMs: number | null | undefined): PriceTierId;
 /** Usage buckets consumed by one model (counts in raw tokens). */
 export interface TokenUsageBuckets {
     /** Uncached input tokens. */
@@ -97,6 +112,13 @@ export interface ModelEntry {
  * from 2026-08-17, and Gemini's Flex tier discounts spare-capacity traffic.
  */
 export declare const MODEL_CATALOG: readonly ModelEntry[];
+/**
+ * 真实 provider model id → 计费目录键（`MODEL_CATALOG[].key`）的映射。未知 id
+ * 原样保留并落回 `other`（未知模型不估算费用）。聚合层（aggregate.ts）在折叠时
+ * 用同一张表把日志里的 model id 归并为目录键，客户端渲染（`modelOf`）也按它
+ * 解析，两侧共用一份映射，避免同一模型两侧不一致导致「未收录」。
+ */
+export declare const MODEL_KEY_ALIASES: Readonly<Record<string, string>>;
 /** Lookup a model by its stats key; falls back to the generic `other` entry. */
 export declare function modelOf(key: string): ModelEntry;
 /** Resolve a price-table row by its CSS variable name (theme token or fallback color). */
@@ -117,8 +139,25 @@ export declare function resolveToken(name: string): string;
  * @returns the estimated cost in CNY.
  */
 export declare function computeCost(entry: ModelEntry, buckets: TokenUsageBuckets, peakShare?: number): number;
-/** Format a CNY amount with adaptive precision. */
-export declare function formatMoney(cny: number): string;
+/**
+ * 按调用时刻精确判定高峰/空闲档并计价（P0-1：替代固定比例混合）。时刻未知
+ * （null/NaN，理论不发生在真实事件流）时回退 {@link DEFAULT_PEAK_SHARE} 混合，
+ * 保持旧语义不低估。平档模型（无 offPeak）两个时段同价。
+ * @param entry - the catalog entry whose prices apply.
+ * @param buckets - token usage counts.
+ * @param timeMs - the call's wall-clock time (epoch ms); null falls back to the peak-share mix.
+ * @param peakShare - fallback mix used only when `timeMs` is missing.
+ * @returns the estimated cost in the entry's native currency.
+ */
+export declare function computeCostAt(entry: ModelEntry, buckets: TokenUsageBuckets, timeMs: number | null | undefined, peakShare?: number): number;
+/** 人民币 → 美元（显示换算用）：1 USD = {@link USD_TO_CNY} CNY。 */
+export declare function cnyToUsd(cny: number): number;
+/**
+ * Format an amount with adaptive precision and the given currency symbol.
+ * @param amount - the amount (CNY by default; pass `usd` for dollar display).
+ * @param currency - display currency; default `cny`.
+ */
+export declare function formatMoney(amount: number, currency?: CostCurrency): string;
 /**
  * Format a per-1M-token price in its native currency (free when the rate is
  * zero): CNY for domestic models, USD for overseas ones.

package/lib/types/index.d.ts

@@ -10,12 +10,17 @@
  * fabricated samples.
  */
 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 IdentifiedSubscriptionPlan, type SubscriptionKeys, type SubscriptionPlanConfig } from './subscriptions.ts';
 /** Plugin configuration. */
 export interface UsageBillingConfig {
     /** Absolute path to a `.dsh-usage-stats.json` fallback file. */
     statsPath?: string;
     /** 订阅制（coding / token / agent plan）provider id 列表；默认 kimi-coding、xiaomi-token-plan-cn。 */
     subscriptionProviders?: string[];
+    /** 订阅套餐额度适配器（kimi / zai / opencode-go）；默认全部内置。 */
+    subscriptionPlans?: readonly SubscriptionPlanConfig[];
     /** 余额查询用的 DeepSeek 凭据引用（环境变量名）；默认 DEEPSEEK_API_KEY。 */
     balanceApiKeyEnv?: string;
     /** 月度预算（人民币元）；设置后随 usage-stats 下发，仪表盘显示预算进度条。 */
@@ -24,8 +29,19 @@ export interface UsageBillingConfig {
         不设置则客户端按默认阈值（50 元）兜底。 */
     lowBalanceThreshold?: number;
 }
-/** Required services: the web server and the persisted session log store. */
+/** Required services: the web server, the persisted session log store, and user settings. */
 export declare const inject: string[];
+/**
+ * 解析订阅适配器需要的 API Key：从 llm-pi-ai 设置的 `providers.<id>.apiKeyEnv`
+ * 读引用（如 kimi-coding → KIMI_CODING_API_KEY），再经凭据 seam 解析成实际值。
+ * 同时识别出用户配置了 key 的订阅套餐（供面板只显示已识别的）。
+ * @param settings - the settings service (reads the llm-pi-ai namespace).
+ * @param credentials - the credentials service (resolves the env refs).
+ */
+export declare function resolveSubscriptionKeys(settings: SettingsProvider, credentials: CredentialProvider): Promise<{
+    keys: SubscriptionKeys;
+    identified: IdentifiedSubscriptionPlan[];
+}>;
 /**
  * Host plugin body: serve real aggregated usage to the browser dashboard.
  * @param ctx - host context carrying webServer and sessionPersistence.

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

@@ -47,4 +47,43 @@ export interface ProviderBalance {
 export interface BalanceResponse {
     balances: readonly ProviderBalance[];
 }
+/** Quota query result status; the dashboard maps each to a row state. */
+export type SubscriptionStatus = 'ok' | 'not-configured' | 'unauthorized' | 'rate-limited' | 'unavailable' | 'invalid-response';
+/** One quota window (session / weekly / monthly / billing). */
+export interface SubscriptionWindow {
+    kind: 'session' | 'weekly' | 'monthly' | 'billing';
+    /** Used share in percent (0–100, one decimal). */
+    usedPercent: number;
+    /** Remaining share in percent (0–100, one decimal). */
+    remainingPercent: number;
+    /** ISO reset time; absent when the provider reports none. */
+    resetsAt?: string;
+    /** Absolute remaining amount; present when the provider reports one. */
+    remaining?: number;
+}
+/** One provider's subscription plan quota row. */
+export interface SubscriptionQuota {
+    /** Adapter id: `kimi` / `zai` / `opencode-go`. */
+    provider: string;
+    /** Human display name (e.g. Kimi For Coding). */
+    displayName: string;
+    /** Plan label; absent when the provider did not name one. */
+    plan?: string;
+    status: SubscriptionStatus;
+    /** Quota windows, newest-window first; empty when the query failed. */
+    windows: readonly SubscriptionWindow[];
+}
+/** Response of `/api/billing/subscriptions`. */
+export interface SubscriptionResponse {
+    quotas: readonly SubscriptionQuota[];
+}
+/** Config for one subscription adapter (validated in apply). */
+export interface SubscriptionPlanConfig {
+    /** Adapter id: `kimi` / `zai` / `opencode-go`. */
+    provider: string;
+    /** API base URL override; defaults to the provider's public endpoint. */
+    baseUrl?: string;
+    /** Z.ai region override; defaults to the settings-namespace `zaiRegion`. */
+    region?: 'global' | 'bigmodel-cn';
+}
 //# sourceMappingURL=pricing-shared.d.ts.map

package/lib/types/subscriptions.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Subscription-plan quota polling (node half): how much of each coding/token
+ * plan is left. The billing dashboard already exempts subscription providers
+ * from per-token cost; this module surfaces the REMAINING quota so the user
+ * sees plan headroom instead of a blank row.
+ *
+ * The panel shows only the plans the user actually configured: adapters with
+ * a known quota API (Kimi, Z.ai, OpenCode Go) query the remaining amount;
+ * other subscription providers the harness recognizes (volcengine / baidu /
+ * qwen / xiaomi token plans, agent plans…) are identified and listed with a
+ * "no quota API" marker rather than hidden. API keys come from the `llm-pi-ai`
+ * settings namespace (`apiKeyEnv` refs) resolved through the credentials seam.
+ */
+import type { SubscriptionPlanConfig, SubscriptionQuota } from './pricing-shared.ts';
+/** 订阅适配器需要的凭据（来自 llm-pi-ai 设置命名空间）。 */
+export interface SubscriptionKeys {
+    /** Kimi For Coding API key。 */
+    kimiApiKey: string;
+    /** Z.ai API key。 */
+    zaiApiKey: string;
+    /** OpenCode Go API key。 */
+    opencodeApiKey: string;
+    /** Z.ai 区域（global / bigmodel-cn）。 */
+    zaiRegion: 'global' | 'bigmodel-cn';
+}
+/** 空凭据：全部未配置时的初始值。 */
+export declare const EMPTY_SUBSCRIPTION_KEYS: SubscriptionKeys;
+/** 已识别的一个订阅套餐（用户在 llm-pi-ai 里配置了 key 的订阅类 provider）。 */
+export interface IdentifiedSubscriptionPlan {
+    /** llm-pi-ai 的 provider id（如 kimi-coding、xiaomi-token-plan-cn）。 */
+    provider: string;
+    /** 显示名（映射表命中则用映射，否则用 id）。 */
+    displayName: string;
+    /** 是否有额度查询适配器。 */
+    adapter: boolean;
+    /** 适配器区域覆盖（zai-coding-cn → bigmodel-cn）。 */
+    region?: 'global' | 'bigmodel-cn';
+}
+/** 是否是订阅类 provider id（如 kimi-coding、xiaomi-token-plan-cn）。 */
+export declare function isSubscriptionProviderId(providerId: string): boolean;
+/**
+ * 从 llm-pi-ai 设置里识别订阅套餐：带订阅类 id 且配置了 apiKeyEnv 的 provider。
+ * @param providers - the `providers` map of the llm-pi-ai settings namespace.
+ * @returns identified plans in configuration order.
+ */
+export declare function identifySubscriptionPlans(providers: Record<string, {
+    apiKeyEnv?: string;
+} | undefined> | undefined): IdentifiedSubscriptionPlan[];
+/**
+ * Collect quota for the given plans concurrently (adapter-backed plans only;
+ * identified plans without an adapter are surfaced by the caller as "no
+ * quota API" rows).
+ * @param keys - the API keys from the llm-pi-ai settings namespace.
+ * @param plans - adapter-backed plans to poll; empty by default.
+ * @param timeoutMs - per-request timeout; defaults to 15s.
+ * @returns the quotas in plan order (unknown providers degrade to `unavailable`).
+ */
+export declare function collectSubscriptions(keys: SubscriptionKeys, plans?: readonly SubscriptionPlanConfig[], timeoutMs?: number): Promise<readonly SubscriptionQuota[]>;
+//# sourceMappingURL=subscriptions.d.ts.map

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.3.0",
+  "version": "0.4.0",
   "publishConfig": {
     "access": "public"
   },
@@ -61,6 +61,8 @@
     "@deepseek-ai/dsh-llm": "*",
     "@deepseek-ai/dsh-session": "*",
     "@deepseek-ai/dsh-session-persistence": "*",
+    "@deepseek-ai/dsh-settings": "*",
+    "@deepseek-ai/schemastery": "*",
     "@deepseek-ai/cordis": "*",
     "react": "^18.2.0"
   },
@@ -74,6 +76,7 @@
     "@deepseek-ai/dsh-client-ui-conversation": "*",
     "@deepseek-ai/dsh-client-ui-primitives": "*",
     "@deepseek-ai/dsh-client-ui-slots": "*",
+    "@deepseek-ai/dsh-client-web-react": "*",
     "@deepseek-ai/dsh-invariants": "*",
     "@testing-library/react": "^16.1.0",
     "@types/react": "~18.3.1",