@kenz1117/dsh-ui-usage-billing 1.6.2 → 1.6.4

package/lib/types/balance.d.ts

@@ -24,8 +24,10 @@ import type { CustomBalanceConfig, CustomBalanceExtract, ProviderBalance } from
 export declare function pickTokenDanceBalanceCny(data: unknown): number | undefined;
 /**
  * Query every configured provider's account balance. A provider is queried only
- * when its llm-pi-ai route has an `apiKeyEnv`; absent routes answer
- * `unconfigured` so the dashboard shows a stable state instead of dropping the row.
+ * when its llm-pi-ai route has a key: an explicit `apiKeyEnv`, or — on hosts
+ * whose settings UI stores route keys as credentials refs — the route's
+ * conventional ref (route-keys.ts). Absent routes answer `unconfigured` so the
+ * dashboard shows a stable state instead of dropping the row.
  * @param ctx - host context carrying the credentials seam.
  * @param providers - the llm-pi-ai providers dict (`<route> → { apiKeyEnv? }`).
  * @returns the balance rows (one per provider).

package/lib/types/config.d.ts

@@ -4,7 +4,15 @@
  * 引用（作为 Deps 类型签名），把它单独放这里让 route 文件能从 src/ 根 import。
  * 仍由 src/index.ts 的 apply(ctx, config) 消费：路由层只通过 Deps 拿到它，
  * 不直接构造。
+ *
+ * ⚠️ Config 运行时 schema 必须经 src/index.ts re-export（issue #98）：宿主
+ * dsh-settings@0.2.1-rc.2 的 settings.update 写回要求本插件条目在 loader fiber
+ * 上有 `Config` schema（`entry.fiber.runtime.Config` 且带 toJSON），缺失时抛
+ * `No configurable plugin entry`——v1.6.0 拆分时把 schema 退化成纯类型，「注入
+ * 用量查询」开关随之失效（#80 方案的回归）。schemastery 非 strict object 会
+ * merge 未声明键，其余 config 字段（statsPath / routeAliases 等）不受影响。
  */
+import z from '@deepseek-ai/schemastery';
 import type { CustomBalanceConfig, DeclaredEndpointConfig, SubscriptionPlanConfig } from './pricing-shared.ts';
 /** 宿主 0.1.7+ 经 Config schema 解析后，volatile 字段在 config 中的稳定引用形态
  *  （cosmokit `Volatile<T>` 的最小结构镜像，避免为类型引入直接依赖）。 */
@@ -12,6 +20,19 @@ export interface VolatileToggle {
     /** @returns 当前生效的布尔快照（设置写入后原位更新，无需重载插件）。 */
     get(): boolean;
 }
+/**
+ * 宿主侧条目 config schema（#80 / #98）：宿主 0.1.7+ 的设置系统据此把
+ * `enableUsageStatsTool` 投影为 volatile 引用（设置写入即时反映 + 写回走
+ * settings.update）。**必须**经 src/index.ts re-export 给 loader——宿主从插件
+ * 运行时模块的 `Config` 导出发现它；只声明类型等于没有。schemastery 非 strict
+ * 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. */

package/lib/types/declarative.d.ts

@@ -14,8 +14,9 @@
  * 2. `path` 必须单斜杠绝对路径：`//evil.example/x` 是协议相对 URL，`new URL()` 会
  *    把它解析到别的主机；构造后还会再校验一次 origin。
  * 3. 只发 GET，无请求体，无自定义 method / headers。
- * 4. 凭据仍从匹配 provider 自己的 `apiKeyEnv` 取，经同一凭据 seam 解析；声明不能
- *    指定任何凭据。
+ * 4. 凭据仍只从匹配 provider 自己的凭据取：显式 `apiKeyEnv` 优先，缺省按路由
+ *    约定 ref（新版宿主的存放形态，见 route-keys.ts）经同一凭据 seam 解析；声明
+ *    不能指定任何凭据。
  * 5. 跨源重定向直接失败，不跟随——那是绕过第 1 条最省事的办法。
  * 6. 响应体有大小上限与共享超时，坏 / 恶意端点拖不住面板。
  * 7. 声明不能覆盖内置读法：只在内置表答不上来时它才轮到。

package/lib/types/index.d.ts

@@ -28,6 +28,7 @@ interface SettingsReader {
     }[];
 }
 export type { UsageBillingConfig } from './config.ts';
+export { Config } 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.
@@ -41,12 +42,14 @@ export declare const inject: string[];
  * @param settings - the settings service (reads the llm-pi-ai namespace).
  * @returns the providers dict; empty when the namespace is unreadable.
  */
-/** 一个 llm-pi-ai provider 路由的读取视图：只取三块——apiKeyEnv（凭据引用）、
- *  baseURL（中转站零配置发现的来源）、displayName（站点显示名）。 */
+/** 一个 llm-pi-ai provider 路由的读取视图：apiKeyEnv（凭据引用）、baseURL（中转站
+ *  零配置发现）、displayName（站点显示名）、hasModels（新版宿主设置页保存的
+ *  models 列表——订阅识别的第二配置信号）。 */
 export interface PiAiProviderRoute {
     apiKeyEnv?: string;
     baseURL?: string;
     displayName?: string;
+    hasModels?: boolean;
 }
 /** 同步读取 provider 路由的 baseURL 视图（中转站零配置发现来源）。
  *  `settings.describe` 是同步调用，聚合器每次折叠取最新站点映射，无需缓存/过期。
@@ -75,9 +78,10 @@ export declare function readRegisteredProviderIds(get: ((name: string) => unknow
     reason?: string;
 };
 /**
-  * 解析订阅适配器需要的 API Key：从 llm-pi-ai 设置的 `providers.<id>.apiKeyEnv`
- * 读引用（如 kimi-coding → KIMI_CODING_API_KEY），再经凭据 seam 解析成实际值。
- * 同时识别出用户配置了 key 的订阅套餐（供面板只显示已识别的）。
+ * 解析订阅适配器需要的 API Key：经典形态从 llm-pi-ai 设置的 `providers.<id>.apiKeyEnv`
+ * 读引用（如 kimi-coding → KIMI_CODING_API_KEY）；新版宿主设置页把 key 直接存成
+ * 凭据 refs（路由约定名 `<ROUTE>_API_KEY`，pi-ai 目录 ambient 名补充），显式引用
+ * 解析不到时按约定名找回。同时识别出已配置的订阅套餐（供面板只显示已识别的）。
  * @param settings - the settings service (reads the llm-pi-ai namespace).
  * @param credentials - the credentials service (resolves the env refs).
  */

package/lib/types/relay.d.ts

@@ -3,9 +3,10 @@
  *
  * 适用场景：用户把某条 llm-pi-ai provider 路由的 `baseURL` 指向第三方中转站
  * （New API / One API / VoAPI / Sub2API 等）。这类站点不卖官方余额，卖的是
- * 按 key 的额度（used/total）或多个滚动窗口。本模块对**配了 baseURL 且有
- * apiKeyEnv** 的路由逐个探测两个已知端点，能解析出额度就返回；解析不出的
- * 静默标记 unavailable，绝不臆造金额（与 balance/subscriptions 一致的姿态）。
+ * 按 key 的额度（used/total）或多个滚动窗口。本模块对**配了 baseURL 且 key 可得**
+ * （显式 `apiKeyEnv`，或新版宿主存进凭据 refs 的路由约定名，见 route-keys.ts）
+ * 的路由逐个探测两个已知端点，能解析出额度就返回；解析不出的静默标记
+ * unavailable，绝不臆造金额（与 balance/subscriptions 一致的姿态）。
  *
  * 探测顺序：先 Sub2API `/v1/usage`（标准化程度高），再 New API `/api/status`；
  * 404 = 不是该套程序，继续试下一种；401/403 = 是但 key 不对（unauthorized）；
@@ -13,14 +14,14 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { RelayQuota, SubscriptionWindow } from './pricing-shared.ts';
-/** 一个待探测的中转站路由（来自 llm-pi-ai providers 的 baseURL + apiKeyEnv）。 */
+/** 一个待探测的中转站路由（来自 llm-pi-ai providers 的 baseURL + key 候选 ref）。 */
 export interface RelayRoute {
     /** llm-pi-ai providers 路由名（key）。 */
     route: string;
     /** 该路由配置的端点地址（origin 来源）。 */
     baseURL: string;
-    /** 该路由解析到的 apiKeyEnv 引用。 */
-    apiKeyEnv: string;
+    /** 该路由的凭据 ref 候选（按优先序：显式 apiKeyEnv 在首，路由约定名补后）。 */
+    apiKeyRefs: readonly string[];
     /** 站点显示名；缺省用路由名。 */
     displayName?: string;
 }
@@ -53,14 +54,14 @@ export declare function isOfficialBaseUrl(baseURL: string): boolean;
 /**
  * 查询单个中转站路由的额度。先试 Sub2API，再试 New API；任一读出额度即返回。
  * @param ctx - host context carrying the credentials seam.
- * @param route - 待探测的路由（baseURL + apiKeyEnv）。
+ * @param route - 待探测的路由（baseURL + 凭据 ref 候选）。
  * @returns 该路由的一行额度结果（status 标记成败）。
  */
 export declare function queryRelayQuota(ctx: Context, route: RelayRoute): Promise<RelayQuota>;
 /**
  * 批量查询多个中转站路由的额度（每个独立成败，互不影响）。
  * @param ctx - host context carrying the credentials seam.
- * @param routes - 配了 baseURL 且 apiKeyEnv 有值的路由列表。
+ * @param routes - 配了 baseURL 且 key 候选可得（显式引用存在或约定 ref 解析出值）的路由列表。
  * @returns 每个路由一行的额度结果。
  */
 export declare function queryRelayQuotas(ctx: Context, routes: readonly RelayRoute[]): Promise<readonly RelayQuota[]>;

package/lib/types/route-keys.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 宿主 llm-pi-ai 新代际的路由 key 约定（订阅额度 / 余额 / 中转站 / 声明端点共用）。
+ *
+ * 新版宿主设置页把路由 key 直接存成凭据 refs（命名 = 路由 id 大写下划线 +
+ * `_API_KEY`），providers 配置里只剩 models 列表；chat 认证走 pi-ai 目录路由的
+ * ambient 发现，不再需要显式 `apiKeyEnv`。插件侧所有「按路由取 key」的读取口
+ * 共用本模块的候选名推导与顺序解析——显式引用优先，约定名补后。
+ */
+/** 候选 ref 名：路由 id 约定名（`<ROUTE 大写下划线>_API_KEY`）优先，其后补宿主
+ *  pi-ai 目录的 ambient env 名（仅当与约定名不同——目录把 kimi-coding 指到
+ *  KIMI_API_KEY、opencode-go 与 opencode 同用 OPENCODE_API_KEY）。 */
+export declare function routeKeyRefCandidates(route: string): readonly string[];
+/** 宽容的凭据解析口：ref 名 → 非空值；未配置 / 解析失败返回 undefined。 */
+export type RefResolver = (name: string) => Promise<string | undefined>;
+/** 依次解析候选 ref，返回第一个解析出非空值的 ref 与值；全部落空返回 undefined。 */
+export declare function firstResolvedRef(refs: readonly string[], resolveRef: RefResolver): Promise<{
+    ref: string;
+    value: string;
+} | undefined>;
+//# sourceMappingURL=route-keys.d.ts.map

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

@@ -3,6 +3,8 @@
  *
  * usage_stats 工具开关：插件自带的读/写接口（不依赖宿主浏览器设置白名单）。
  * GET 返回当前是否注入；POST 写设置命名空间（重启应用后工具注入随新值生效）。
+ * 写回失败回 503 + 宿主错误文案（issue #98：此前 200 + 笼统 invalid，开关无声
+ * 弹回且无任何诊断线索）；body 非 JSON 回 400。
  *
  * 双世代宿主（issue #19 + #28 + v1.4.19）的接线在装配器里完成：
  * - 旧宿主 ≤0.1.6 走 `settings.register` 命名空间 scope。

package/lib/types/subscriptions.d.ts

@@ -9,7 +9,11 @@
  * 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.
+ * settings namespace resolved through the credentials seam: the classic
+ * `apiKeyEnv` refs, or — on hosts whose settings UI stores route keys as
+ * credentials refs named after the route (`<ROUTE>_API_KEY`, catalog ambient
+ * names as fallback) — the conventional refs, matched against the same
+ * subscription-class route ids.
  */
 import type { SubscriptionPlanConfig, SubscriptionQuota, SubscriptionWindow } from './pricing-shared.ts';
 /** 订阅适配器需要的凭据（来自 llm-pi-ai 设置命名空间）。 */
@@ -46,6 +50,17 @@ export interface SubscriptionKeys {
 export declare function parseOpenCodeAuthDocument(document: unknown): string;
 /** 空凭据：全部未配置时的初始值。 */
 export declare const EMPTY_SUBSCRIPTION_KEYS: SubscriptionKeys;
+/**
+ * key 解析的可测核心（无文件 I/O）：先显式 `apiKeyEnv`（旧口径，优先），key 仍缺
+ * 时按约定 ref 名解析（新版宿主的存放形态，见 route-keys.ts）。`keyConfigured`
+ * 回报每条路由的 key 是否解析成功，供识别层作为第三配置信号（refResolved）。
+ * @param providers - llm-pi-ai 的 providers 视图。
+ * @param resolveRef - 凭据 seam：ref 名 → 非空 key 值；未配置/失败返回 undefined。
+ */
+export declare function resolveSubscriptionAccess(providers: Readonly<Record<string, SubscriptionRouteConfigView | undefined>>, resolveRef: (name: string) => Promise<string | undefined>): Promise<{
+    keys: SubscriptionKeys;
+    keyConfigured: ReadonlySet<string>;
+}>;
 /** 已识别的一个订阅套餐（用户在 llm-pi-ai 里配置了 key 的订阅类 provider）。 */
 export interface IdentifiedSubscriptionPlan {
     /** llm-pi-ai 的 provider id（如 kimi-coding、xiaomi-token-plan-cn）。 */
@@ -57,16 +72,28 @@ export interface IdentifiedSubscriptionPlan {
     /** 适配器区域覆盖：两个 Z.ai 路由各自固定区域，互不跟随 keys.zaiRegion。 */
     region?: 'global' | 'bigmodel-cn';
 }
+/**
+ * 一条 llm-pi-ai 路由的订阅识别视图：三个「已配置」信号任一为真即识别。
+ * 新版宿主（内置目录 + ambient 发现）把路由 key 存进凭据 refs，providers 配置里
+ * 只剩 models 列表——`apiKeyEnv` 不再是唯一的配置信号。
+ */
+export interface SubscriptionRouteConfigView {
+    /** 显式凭据引用（旧口径）。 */
+    apiKeyEnv?: string;
+    /** 路由声明了非空 models 列表（新版设置页保存的配置形态）。 */
+    hasModels?: boolean;
+    /** 路由约定 ref（`<ROUTE>_API_KEY` / 目录 ambient 名）解析出了非空 key。 */
+    refResolved?: boolean;
+}
 /** 是否是订阅类 provider id（如 kimi-coding、xiaomi-token-plan-cn）。 */
 export declare function isSubscriptionProviderId(providerId: string): boolean;
 /**
- * 从 llm-pi-ai 设置里识别订阅套餐：带订阅类 id 且配置了 apiKeyEnv 的 provider。
+ * 从 llm-pi-ai 设置里识别订阅套餐：带订阅类 id 且任一配置信号成立的 provider
+ * （显式 apiKeyEnv / models 已配置 / 约定 ref 解析出了 key）。
  * @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[];
+export declare function identifySubscriptionPlans(providers: Record<string, SubscriptionRouteConfigView | undefined> | undefined): IdentifiedSubscriptionPlan[];
 /**
  * 解析 MiniMax Token Plan `/v1/token_plan/remains` 响应。取 general(或 MiniMax-M*)
  * 一行抽出 5h/7d 窗口(total_count 常为 0,以 remaining_percent 为准),不按模型拆条。

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.2",
+  "version": "1.6.4",
   "keywords": [
     "deepseek-harness",
     "deepseek",