@kenz1117/dsh-ui-usage-billing 1.5.1 → 1.6.1

package/lib/types/guard.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 共享 loopback 守卫（v1.5.2 抽自 src/index.ts）。
+ *
+ * 端点只供本机浏览器用，局域网/远端请求一律拒绝，避免面板数据（含中转站
+ * origin 与余额）外泄。三层防御：peer socket（最可信）+ Host 头精确字面量
+ * （防 `127.0.0.1.evil.com` 这类 DNS rebinding 域名）+ trustedHosts 白名单
+ * （反向代理场景的精确主机名放行）。Origin 头独立校验（写操作用）。
+ *
+ * 设计要点：精确字面量匹配（`startsWith('127.')` 会被 `127.0.0.1.evil.com`
+ * 穿透，必须正则）。IPv6 字面量带方括号（`[::1]:3080`）单独剥离。
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Peer 地址是否为回环（本地）。回环防护：本插件的端点只供本机浏览器用，
+ *  局域网/远端请求一律拒绝，避免面板数据（含中转站 origin 与余额）外泄。 */
+export declare function isLoopbackPeer(req: IncomingMessage): boolean;
+/** 校验 Host 头是本机回环（精确 127.0.0.0/8 / ::1 / localhost 或空，供 curl 不带 Host 的极简请求）。
+ *  拒绝 `127.0.0.1.attacker.com` 这类以 `127.` 开头但解析到外部的 DNS rebinding 域名：
+ *  只用 `startsWith('127.')` 会被它穿透，必须精确匹配回环 IP 的字面量。 */
+/**
+ * Host 头/名单条目的主机名部分：IPv6 字面量带方括号（`[::1]:3080`），整体去括号；
+ * 裸 IPv6（多个冒号、无方括号）整体是字面量；其余按首个冒号去端口。统一小写。
+ * （此前一律 `split(':')[0]`：`[::1]:3080` 截成 `[`，IPv6 回环请求被误拒，
+ * trustedHosts 也配不进去——fail-closed 无安全暴露，但本机 IPv6 场景功能失效。）
+ */
+export declare function hostNameOf(host: string): string;
+/**
+ * 信任主机名归一化：去空白、去端口、转小写，丢弃空项（IPv6 经 {@link hostNameOf}
+ * 去方括号）。与请求侧 Host 头解析同口径，因此匹配忽略大小写与端口。
+ * @param hosts - 配置里的原始名单。
+ * @returns 归一化后的主机名集合（空集 = 与历史版本行为一致）。
+ */
+export declare function normalizeTrustedHosts(hosts: readonly string[] | undefined): ReadonlySet<string>;
+/** 校验 Host 头是本机回环（精确 127.0.0.0/8 / ::1 / localhost 或空，供 curl 不带 Host 的极简请求）。
+ *  拒绝 `127.0.0.1.attacker.com` 这类以 `127.` 开头但解析到外部的 DNS rebinding 域名：
+ *  只用 `startsWith('127.')` 会被它穿透，必须精确匹配回环 IP 的字面量。 */
+export declare function isLoopbackHost(req: IncomingMessage, trustedHosts?: ReadonlySet<string>): boolean;
+/** 校验 Origin 头是否回环（写操作用，防止跨站表单/fetch 改写设置）。Origin 缺失
+ *  （curl 或同源 fetch 不带）视为放行，交给下方的 Content-Type 校验兜底；Origin 存在
+ *  但主机非回环则拒绝——跨站脚本发起的写请求必带攻击者域名的 Origin。 */
+export declare function isLoopbackOrigin(origin: string | undefined): boolean;
+/**
+ * 回环防护守卫：仅接受回环 GET 请求（peer socket 地址 + Host 头同时校验）。
+ * 不满足时返回 403 并结束响应；调用方在 handler 顶部调用，返回 false 即已拒绝。
+ * @param req - 当前请求。
+ * @param res - 当前响应。
+ * @returns 是否放行；false = 已拒绝并结束响应。
+ */
+export declare function guardLoopback(req: IncomingMessage, res: ServerResponse, trustedHosts?: ReadonlySet<string>): boolean;
+//# sourceMappingURL=guard.d.ts.map

package/lib/types/index.d.ts

@@ -12,13 +12,12 @@
  * file is served as a fallback, and a missing file answers `{ error }` so the
  * dashboard shows zeros, never fabricated samples.
  */
-import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Context } from '@deepseek-ai/cordis';
 import type { CredentialProvider } from '@deepseek-ai/dsh-credentials';
-import z from '@deepseek-ai/schemastery';
 import { type UsageLedgerStore, type UsagePersistence } from './aggregate.ts';
-import type { CustomBalanceConfig, DeclaredEndpointConfig, SubscriptionPlanConfig } from './pricing-shared.ts';
+import type { UsageBillingConfig } from './config.ts';
 import { type IdentifiedSubscriptionPlan, type SubscriptionKeys } from './subscriptions.ts';
+export { guardLoopback, isLoopbackOrigin, isLoopbackHost, isLoopbackPeer, hostNameOf, normalizeTrustedHosts } from './guard.ts';
 /** 设置服务的读取面：两代宿主运行时都提供 describe（条目键为 profile entry id）。 */
 interface SettingsReader {
     describe(options?: {
@@ -28,102 +27,7 @@ interface SettingsReader {
         value: unknown;
     }[];
 }
-/**
- * 信任主机名归一化：去空白、去端口、转小写，丢弃空项（IPv6 经 {@link hostNameOf}
- * 去方括号）。与请求侧 Host 头解析同口径，因此匹配忽略大小写与端口。
- * @param hosts - 配置里的原始名单。
- * @returns 归一化后的主机名集合（空集 = 与历史版本行为一致）。
- */
-export declare function normalizeTrustedHosts(hosts: readonly string[] | undefined): ReadonlySet<string>;
-/**
- * 回环防护守卫：仅接受回环 GET 请求（peer socket 地址 + Host 头同时校验）。
- * 不满足时返回 403 并结束响应；调用方在 handler 顶部调用，返回 false 即已拒绝。
- * @param req - 当前请求。
- * @param res - 当前响应。
- * @returns 是否放行；false = 已拒绝并结束响应。
- */
-export declare function guardLoopback(req: IncomingMessage, res: ServerResponse, trustedHosts?: ReadonlySet<string>): boolean;
-/** 宿主 0.1.7+ 经 Config schema 解析后，volatile 字段在 config 中的稳定引用形态
- *  （cosmokit `Volatile<T>` 的最小结构镜像，避免为类型引入直接依赖）。 */
-export interface VolatileToggle {
-    /** @returns 当前生效的布尔快照（设置写入后原位更新，无需重载插件）。 */
-    get(): boolean;
-}
-/**
- * Loader 挂载时对条目 config 做校验的 Config 声明：`enableUsageStatsTool` 标记
- * volatile，宿主 0.1.7+ 设置系统据此把它投影为可实时编辑的开关（describe/update）。
- * schemastery 非严格 object 透传未声明键，其余 config 字段不受影响；未导出 Config
- * 的旧宿主直接把原始 config 交给 apply，普通布尔形态由读取端兼容。
- */
-export declare const Config: z<Schemastery.ObjectS<NoInfer<{
-    enableUsageStatsTool: z<boolean, boolean, "volatile-defined">;
-}>>, Schemastery.ObjectT<NoInfer<{
-    enableUsageStatsTool: z<boolean, boolean, "volatile-defined">;
-}>>, "plain">;
-/** Plugin configuration. */
-export interface UsageBillingConfig {
-    /** Absolute path to a `.dsh-usage-stats.json` fallback file. */
-    statsPath?: string;
-    /** 统计快照的持久化路径；默认 `<harness home>/.dsh-usage-stats.json`
-     *  （harness home = `DSH_HOME` 环境变量或 `~/.dsh`，见 resolveDshHome）。
-     *  测试注入临时目录以隔离真实家目录（聚合失败回退与快照落盘都走此路径）。 */
-    snapshotPath?: string;
-    /** 独立持久用量账本的绝对路径；默认 `<harness home>/.dsh-usage-ledger.json`。
-     *  账本与会话日志解耦，因此永久删除会话不会抹掉已经观测到的用量。 */
-    ledgerPath?: string;
-    /** 余额差对账基准的持久化路径；默认 `<harness home>/.dsh-usage-reconcile.json`。 */
-    reconcilePath?: 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 下发，仪表盘显示预算进度条。 */
-    monthlyBudget?: number;
-    /** 余额不足告警阈值（人民币元）：余额低于此值时仪表盘每天提醒一次；
-        不设置则客户端按默认阈值（50 元）兜底。 */
-    lowBalanceThreshold?: number;
-    /** 自定义 Provider 余额查询（任意 HTTP 端点 + extract 规则，适配 NewApi/LiteLLM 等）。 */
-    customBalances?: readonly CustomBalanceConfig[];
-    /**
-     * 声明端点（declarative endpoints）：为内置表没有的供应商自声明余额/额度接口。
-     * 绑定到某条已配置 provider 的同源地址，`fields` / `windows` 写响应里的取值路径；
-     * 安全边界（origin 绑定、单斜杠 path、只 GET、跨源重定向失败、凭据取自 apiKeyEnv）
-     * 写死在 declarative.ts。缺省空。
-     */
-    declaredEndpoints?: readonly DeclaredEndpointConfig[];
-    /**
-     * 允许通过 Host 头校验的额外主机名（反向代理场景）；缺省空，行为与历史版本完全一致。
-     * 仅在 peer socket 已通过回环校验后才参考：socket 校验仍为强制且不受本字段影响，
-     * 本名单只放宽「纵深防御」的第二层。匹配为**精确主机名**，忽略大小写与端口；
-     * 不支持后缀 / 通配符，因此 `evil.com` 永远无法满足 `trusted.com`。
-     * 例：`['llm.example.com']`。
-     */
-    trustedHosts?: string[];
-    /** `usage_stats` 工具注入开关（默认 false：不注入）。宿主 0.1.7+ 经 Config
-     *  解析后是 volatile 引用（设置写入即时反映），直连 apply（测试）是普通布尔；
-     *  读取统一走 readUsageStatsToggle。该工具占用每次请求的上下文，coding 场景多在仪表盘查看。 */
-    enableUsageStatsTool?: boolean | VolatileToggle;
-    /**
-     * 联网搜索请求（`web/deepseek-search-llm-request`，日志只有请求、无用量事件）
-     * 的单次费用估算（人民币元）。这类调用直连官方 api.deepseek.com，开放平台照常
-     * 计费但本地日志无 usage，按次估值计入今日/本月费用；默认 0.02 元/次，设 0 关闭。
-     */
-    searchCallEstimateCny?: number;
-    /**
-     * 历史路由别名（旧 provider 路由名 → 当前路由名）：改过名/删除过的路由，其
-     * 历史用量原会落「未知路由」桶且站点/订阅/官方判定全部失效；配置别名后按
-     * 目标路由归位。例：`{ "deepseek-official": "tencent", "tencent-cloud": "tencent" }`。
-     */
-    routeAliases?: Record<string, string>;
-    /**
-     * 用户自定义模型别名（真实日志 model id → 计费目录键）：目录外的新模型无需
-     * 等发版，配置一条别名即完成识别与计价（值必须是 MODEL_CATALOG 的既有 key，
-     * 如 `{ "hy4-preview": "hunyuan" }`）。聚合折叠与客户端渲染共用同一映射。
-     */
-    modelKeyAliases?: Record<string, string>;
-}
+export type { UsageBillingConfig } from './config.ts';
 /**
  * Create the atomic file-backed durable-ledger store. The previous complete file
  * is retained as `.bak`; a malformed/missing main file falls back to that backup.
@@ -199,5 +103,4 @@ export declare function adaptSessionPersistence(raw: unknown): UsagePersistence;
  * @param config - optional statsPath override.
  */
 export declare function apply(ctx: Context, config?: UsageBillingConfig): void;
-export {};
 //# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,37 @@
+/**
+ * 路由：GET /api/billing/balance
+ *
+ * 多平台余额（DeepSeek / Kimi / StepFun / SiliconFlow / xAI / 智谱 / 腾讯云
+ * TokenHub 等）+ 用户自定义余额 + 声明端点 + 余额差对账。5 分钟缓存（避免
+ * 每 30s 后台轮询打上游），in-flight 去重（并发请求共享同一次进行中的刷新）。
+ *
+ * 路由文件只关心 HTTP 缓存逻辑：5 分钟过期判定 + 失败时仍发旧缓存（不挂起
+ * 已 writeHead 的响应）。上游查询（queryBalances / queryCustomBalances /
+ * queryDeclaredEndpoints / reconcileBalanceDelta）在装配器里跑，路由只通过
+ * `cached()` 与 `refreshOnce()` 拿到结果。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ProviderBalance } from '../pricing-shared.ts';
+import type { ReconcileEvent } from '../reconcile.ts';
+/** 余额响应体形状（来自装配器 `balanceCache.doc`）。 */
+export interface BalanceDoc {
+    balances: readonly ProviderBalance[];
+    reconcile?: ReconcileEvent;
+}
+interface CachedBalance {
+    doc: BalanceDoc;
+    at: number;
+}
+/** 路由依赖。 */
+export interface BalanceDeps {
+    trustedHosts: ReadonlySet<string>;
+    /** 装配器内缓存 + 时间戳（`Date.now()`）。 */
+    cached: () => CachedBalance;
+    /** in-flight 去重的刷新入口。 */
+    refreshOnce: () => Promise<void>;
+    /** 5 分钟缓存间隔（毫秒）。 */
+    cacheMs: number;
+}
+export declare function registerBalanceRoute(ctx: Context, deps: BalanceDeps): void;
+export {};
+//# sourceMappingURL=balance.d.ts.map

package/lib/types/routes/notify-claim.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 路由：POST /api/billing/notify-claim
+ *
+ * 跨实例提醒认领（issue #44）：多实例（CLI + 桌面等）合法共存，各自轮询
+ * 会重复弹通知。两级去重——进程内 Set 挡同进程的并发/重渲染（trigger 与仪表盘
+ * 是两个组件实例，effect 同周期并发时本地 store 标记读到的还是旧值）；跨进程走
+ * 认领端点（先到先得），另一实例刚发过则跳过。端点不可达（旧版本/网络故障）
+ * 时放行，退化为原有 per-客户端去重。通知构造失败（平台限制）静默。
+ *
+ * 路由文件职责：handler + 模块级 `notifyClaims` 单例（与 `loadNotifications`
+ * 共享内存状态——先到先得认领）。文件持久化（`writeFileAtomic`）由 index.ts 装配
+ * 器通过 `claimsPath` 注入；handler 拿到路径后自行管理读写。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** 路由依赖：装配器注入，无需直接读 ctx。 */
+export interface NotifyClaimDeps {
+    /** 反向代理白名单（来自 `config.trustedHosts` 经 normalizeTrustedHosts 归一化）。 */
+    trustedHosts: ReadonlySet<string>;
+    /** 认领表文件路径：`<snapshotPath>.notify-claims.json`。 */
+    claimsPath: string;
+}
+/** 注册路由到 cordis webServer effect；handler 闭包外只读 deps。 */
+export declare function registerNotifyClaimRoute(ctx: Context, deps: NotifyClaimDeps): void;
+//# sourceMappingURL=notify-claim.d.ts.map

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

@@ -0,0 +1,26 @@
+/**
+ * 路由：GET /api/billing/pricing + POST /api/billing/pricing/refresh
+ *
+ * 实时定价（汇率 + OpenRouter 模型价 + models.dev 目录外补充）的 GET/POST 同
+ * concern，合一个文件：
+ * - GET 由前端 30s 轮询 + 弹窗初始拉取触发，返回完整价目表文档（live + 内置
+ *   目录 + 别名表 + syncedAt）。
+ * - POST 是费率条「立即同步」按钮触发，强制服务端重新拉取一次；写操作额外
+ *   校验 Origin 与 Content-Type。
+ *
+ * 路由文件只关心 HTTP 层：响应体序列化与缓存（pricingBodyCache）由 index.ts
+ * 装配器通过 `body()` 闭包注入；服务端重拉逻辑（refreshPricing + 价格目录代际
+ * 变化触发 reprice）也在装配器里，路由只通过 `refresh()` 触发。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** 路由依赖：装配器注入。 */
+export interface PricingDeps {
+    trustedHosts: ReadonlySet<string>;
+    /** 装配器内缓存的序列化响应体（含 live + 内置目录 + 别名 + syncedAt）。 */
+    body: () => string;
+    /** 触发服务端重新拉取 models.dev / 汇率。 */
+    refresh: () => Promise<void>;
+}
+/** 一次性注册两条同 concern 路由。 */
+export declare function registerPricingRoutes(ctx: Context, deps: PricingDeps): void;
+//# sourceMappingURL=pricing.d.ts.map

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

@@ -0,0 +1,27 @@
+/**
+ * 路由：GET /api/billing/relay-quotas
+ *
+ * 中转站额度（New API / Sub2API 余额 + 滚动窗口）。5 分钟缓存 + in-flight
+ * 去重。诊断（每条路由的 origin / kind）随响应下发，供「我的中转站为什么不显
+ * 示」自查。
+ *
+ * 路由文件只关心 HTTP 缓存 + 诊断序列化。上游查询（queryRelayQuotas +
+ * 路由筛选 + isOfficialBaseUrl 排除）在装配器里跑。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { RelayQuota } from '../pricing-shared.ts';
+interface CachedRelay {
+    quotas: readonly RelayQuota[];
+    at: number;
+}
+/** 路由依赖。 */
+export interface RelayQuotasDeps {
+    trustedHosts: ReadonlySet<string>;
+    cached: () => CachedRelay;
+    refreshOnce: () => Promise<void>;
+    /** 5 分钟缓存间隔（毫秒）。 */
+    cacheMs: number;
+}
+export declare function registerRelayQuotasRoute(ctx: Context, deps: RelayQuotasDeps): void;
+export {};
+//# sourceMappingURL=relay-quotas.d.ts.map

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

@@ -0,0 +1,28 @@
+/**
+ * 路由：GET /api/billing/subscriptions
+ *
+ * 订阅套餐额度（Kimi / Z.ai Coding / OpenCode / MiniMax / OpenRouter / Claude /
+ * CommandCode / 腾讯云 TokenHub 等）。5 分钟缓存 + in-flight 去重（与 balance
+ * 同模式——并发请求共享同一次进行中的刷新）。
+ *
+ * 路由文件只关心 HTTP 缓存逻辑：超时或未命中时触发 refreshOnce，失败时仍用
+ * 旧缓存（不挂起已 writeHead 的响应）。上游查询（collectSubscriptions +
+ * resolveSubscriptionKeys + 适配器 + 套餐知识库）在装配器里跑。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SubscriptionQuota } from '../pricing-shared.ts';
+interface CachedQuotas {
+    quotas: readonly SubscriptionQuota[];
+    at: number;
+}
+/** 路由依赖。 */
+export interface SubscriptionsDeps {
+    trustedHosts: ReadonlySet<string>;
+    cached: () => CachedQuotas;
+    refreshOnce: () => Promise<void>;
+    /** 5 分钟缓存间隔（毫秒）。 */
+    cacheMs: number;
+}
+export declare function registerSubscriptionsRoute(ctx: Context, deps: SubscriptionsDeps): void;
+export {};
+//# sourceMappingURL=subscriptions.d.ts.map

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

@@ -0,0 +1,44 @@
+/**
+ * 路由：GET /api/billing/usage-stats
+ *
+ * 实时用量聚合文档（byDay / byModel / bySession / bySite / byTurn / perf 等）。
+ * stale-while-revalidate：聚合是全量扫描（重度用户上万条会话的冷启动折叠以
+ * 分钟计），HTTP 请求绝不全程等它——只给 RESPONSE_BUDGET_MS 的等待预算，超
+ * 预算立即回最近一次快照；后台折叠完成后快照随之刷新（挂在聚合 promise 上，
+ * 与响应路径解耦）。宿主是单进程，慢响应期间事件循环被折叠占住，会话/模型
+ * 列表 RPC 会一起饿死（用户反馈的启动卡顿）。
+ *
+ * 路由文件只关心 HTTP 拼装：
+ * - decorate（注入 PACKAGE_VERSION / 预算 / 阈值）
+ * - 聚合预算（Promise.race + setTimeout.unref）
+ * - 响应体缓存（`statsBodyCache`：装饰 + 序列化结果按 doc 引用 + config 字段
+ *   缓存，30s 轮询期间复用）
+ * - 失败路径（聚合失败 → 读快照候选 → 仍无则 `{ error }`）
+ *
+ * 聚合器（`aggregator.aggregate()` / `sessionUsageOf()`）+ 快照读写 + 配置在
+ * 装配器里跑，路由只通过 Deps 拿到回调。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { UsageAggregator } from '../aggregate.ts';
+import type { UsageBillingConfig } from '../config.ts';
+/** 路由依赖。 */
+export interface UsageStatsDeps {
+    trustedHosts: ReadonlySet<string>;
+    /** 聚合器（仅用 .aggregate() 与 .sessionUsageOf()）。 */
+    aggregator: Pick<UsageAggregator, 'aggregate' | 'sessionUsageOf'>;
+    config: UsageBillingConfig;
+    /** 快照候选路径列表（主文件 + 约定路径 + config.snapshotPath）。 */
+    candidates: readonly string[];
+    /** 聚合成功后异步落盘节流（30s 内多次触发只写一次）。 */
+    persistSnapshot: (doc: Record<string, unknown>) => void;
+    /** 读一个快照候选：主文件优先，主文件损坏时回退 `.bak`，都失败返回 null。 */
+    readSnapshot: (candidate: string) => Promise<Record<string, unknown> | null>;
+    /** 插件版本（来自 package.json）。 */
+    packageVersion: string;
+    /** 等待预算（毫秒）：聚合在此预算内完成就回实时数据，超预算立即回最近快照。 */
+    responseBudgetMs: number;
+}
+/** 校验一份聚合文档；返回漂移原因（null = 形状正常）。纯只读，不改 doc。 */
+export declare function usageStatsShapeError(doc: unknown): string | null;
+export declare function registerUsageStatsRoute(ctx: Context, deps: UsageStatsDeps): void;
+//# sourceMappingURL=usage-stats.d.ts.map

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

@@ -0,0 +1,27 @@
+/**
+ * 路由：GET/POST /api/billing/usage-tool
+ *
+ * usage_stats 工具开关：插件自带的读/写接口（不依赖宿主浏览器设置白名单）。
+ * GET 返回当前是否注入；POST 写设置命名空间（重启应用后工具注入随新值生效）。
+ *
+ * 双世代宿主（issue #19 + #28 + v1.4.19）的接线在装配器里完成：
+ * - 旧宿主 ≤0.1.6 走 `settings.register` 命名空间 scope。
+ * - 宿主 0.1.7+ 注册面已移除，走 volatile config 投影。
+ * 装配器提供 `read` / `write` 闭包，路由文件不感知双世代——`read()` 已内部分支
+ * （scope 存在时读 scope，否则读 volatile + config base），`write(next)` 同理。
+ * 工具注入由装配器的 `syncUsageTool` 驱动：写回后路由通过 `syncTool()` 显式调用一次
+ * （幂等），覆盖「写回成功但引用未即时可见」的组合（测试替身不提交）。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** 路由依赖。 */
+export interface UsageToolDeps {
+    trustedHosts: ReadonlySet<string>;
+    /** 当前 enableUsageStatsTool 值（装配器内已做双世代分支）。 */
+    read: () => boolean;
+    /** 写回 + 立即同步工具注册（幂等）。 */
+    write: (next: boolean) => Promise<void>;
+    /** 写回后显式调用一次的工具注册同步（幂等）。 */
+    syncTool: () => void;
+}
+export declare function registerUsageToolRoute(ctx: Context, deps: UsageToolDeps): void;
+//# sourceMappingURL=usage-tool.d.ts.map

package/lib/types/silent.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 静默吞错的结构化记录（S-6）：「缺失=未配置」类 catch 的统一出口。
+ *
+ * 本仓 78 处 server 端 catch 多数是有意的静默（文件缺失=首次运行、凭据未
+ * 配置=跳过该 provider），此前唯一载体是注释——用户报「X 不工作」时只能靠
+ * 猜。本工具把这些静默升级为**节流的结构化日志**：同 reason 5 分钟最多一条
+ * info，宿主日志可 grep `swallowed:`，诊断时看得到「哪个环节吞了什么」，
+ * 而又不把已知常态刷成告警噪音。
+ *
+ * 不取代 console.warn——已知异常需要用户行动的（账本损坏、刷新失败）继续
+ * warn；这里只收「确认无害的静默」。节流状态导出重置仅供测试。
+ */
+/**
+ * 记录一次有意的静默吞错。
+ * @param reason - 稳定的短横线 reason 键（如 `reconcile-ref-missing`），节流以此为粒度。
+ * @param error - 可选的原始异常（Error 打 message，其他值原样）。
+ */
+export declare function swallowed(reason: string, error?: unknown): void;
+/** 清空节流状态（仅供测试：模块级 Map 会跨用例泄漏）。 */
+export declare function resetSwallowedForTest(): void;
+//# sourceMappingURL=silent.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": "1.5.1",
+  "version": "1.6.1",
   "keywords": [
     "deepseek-harness",
     "deepseek",
@@ -78,6 +78,9 @@
         "0.2.1-alpha.1": "compatible",
         "0.2.1-alpha.2": "compatible",
         "0.2.1-alpha.3": "compatible",
+        "0.2.1-alpha.4": "compatible",
+        "0.2.1-alpha.5": "compatible",
+        "0.2.1-rc.1": "compatible",
         "0.2.1-rc.2": "compatible"
       }
     }
@@ -86,7 +89,10 @@
     "build": "tsc -b tsconfig.json && tsdown",
     "bundle": "tsdown",
     "watch": "tsdown --watch",
-    "test": "vitest run"
+    "lint": "node scripts/lint.mjs && node scripts/check-clientbundle-sync.mjs",
+    "test": "vitest run",
+    "test:e2e": "playwright test",
+    "test:e2e:install": "playwright install chromium"
   },
   "license": "MIT",
   "engines": {
@@ -105,8 +111,8 @@
     "@deepseek-ai/dsh-client-ui-sidebar": "*",
     "@deepseek-ai/dsh-client-ui-slots": "*",
     "@deepseek-ai/dsh-credentials": "*",
-    "@deepseek-ai/dsh-host-webserver": "*",
     "@deepseek-ai/dsh-home-paths": "*",
+    "@deepseek-ai/dsh-host-webserver": "*",
     "@deepseek-ai/dsh-invariants": "*",
     "@deepseek-ai/dsh-llm": "*",
     "@deepseek-ai/dsh-session": "*",
@@ -123,11 +129,11 @@
     "@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-agent": "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",
@@ -136,10 +142,9 @@
     "@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-host-webserver": "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-invariants": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-util-code-language": "0.2.1-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",
@@ -152,17 +157,19 @@
     "@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/schemastery": "^3.18.4",
+    "@playwright/test": "^1.64.1",
     "@shikijs/langs": "^4.3.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.1.0",
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "^19.2.7",
-    "immer": "^10.1.1",
     "anser": "^2.3.5",
     "diff": "^9.0.0",
+    "immer": "^10.1.1",
     "jsdom": "^26.1.0",
     "katex": "^0.16.47",
     "lightningcss": "^1.32.0",