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

package/lib/index.js

@@ -4045,6 +4045,35 @@ function createUsageAggregator(persistence, options = {}) {
 	};
 }
 //#endregion
+//#region lib/types/route-keys.js
+/**
+* 宿主 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）。 */
+function routeKeyRefCandidates(route) {
+	return [`${route.replaceAll("-", "_").toUpperCase()}_API_KEY`, ...{
+		"kimi-coding": ["KIMI_API_KEY"],
+		"opencode-go": ["OPENCODE_API_KEY"]
+	}[route] ?? []];
+}
+/** 依次解析候选 ref，返回第一个解析出非空值的 ref 与值；全部落空返回 undefined。 */
+async function firstResolvedRef(refs, resolveRef) {
+	for (const ref of refs) {
+		const value = await resolveRef(ref);
+		if (value !== void 0) return {
+			ref,
+			value
+		};
+	}
+}
+//#endregion
 //#region lib/types/resilience.js
 /**
 * 上游网络请求的稳定性工具：有限重试（指数退避）与每平台熔断冷却门。
@@ -4650,32 +4679,51 @@ const QUERIERS = [
 ];
 /**
 * 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).
 */
 async function queryBalances(ctx, providers) {
-	const byName = /* @__PURE__ */ new Map();
-	for (const { route, querier, displayName } of QUERIERS) {
+	const resolveRef = async (name) => {
+		try {
+			const hit = await ctx.credentials.resolve(credentialRef(name));
+			return hit?.value !== void 0 && hit.value !== "" ? hit.value : void 0;
+		} catch {
+			return;
+		}
+	};
+	const resolved = await Promise.all(QUERIERS.map(async ({ route, querier, displayName }) => {
 		const env = providers[route]?.apiKeyEnv;
-		const configured = typeof env === "string" && env !== "";
-		const existing = byName.get(displayName);
-		if (existing !== void 0 && existing.env !== void 0) continue;
-		byName.set(displayName, {
+		const explicit = typeof env === "string" && env !== "" ? env : void 0;
+		const hit = await firstResolvedRef([...explicit !== void 0 ? [explicit] : [], ...routeKeyRefCandidates(route)], resolveRef);
+		return {
 			displayName,
 			querier,
-			env: configured ? env : void 0
+			ref: hit?.ref ?? explicit,
+			configured: explicit !== void 0 || hit !== void 0
+		};
+	}));
+	const byName = /* @__PURE__ */ new Map();
+	for (const item of resolved) {
+		const existing = byName.get(item.displayName);
+		if (existing !== void 0 && existing.ref !== void 0) continue;
+		byName.set(item.displayName, {
+			displayName: item.displayName,
+			querier: item.querier,
+			ref: item.configured ? item.ref : void 0
 		});
 	}
-	return await Promise.all([...byName.values()].map(({ querier, displayName, env }) => {
-		if (env === void 0) return Promise.resolve({
+	return await Promise.all([...byName.values()].map(({ displayName, querier, ref }) => {
+		if (ref === void 0) return Promise.resolve({
 			provider: displayName,
 			displayName,
 			error: "unconfigured"
 		});
-		return querier(ctx, env);
+		return querier(ctx, ref);
 	}));
 }
 /**
@@ -4913,8 +4961,9 @@ async function queryCustomBalances(ctx, configs) {
 * 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. 声明不能覆盖内置读法：只在内置表答不上来时它才轮到。
@@ -5052,10 +5101,21 @@ function compileDeclaredEndpoint(decl) {
 */
 async function queryDeclaredEndpoints(ctx, providers, declarations) {
 	const byOrigin = /* @__PURE__ */ new Map();
-	for (const entry of Object.values(providers)) {
+	for (const [route, entry] of Object.entries(providers)) {
 		const origin = entry.baseURL === void 0 ? void 0 : normalizeDeclaredOrigin(entry.baseURL);
-		if (origin !== void 0 && !byOrigin.has(origin)) byOrigin.set(origin, entry);
+		if (origin !== void 0 && !byOrigin.has(origin)) byOrigin.set(origin, {
+			route,
+			...entry.apiKeyEnv !== void 0 ? { apiKeyEnv: entry.apiKeyEnv } : {}
+		});
 	}
+	const resolveRef = async (name) => {
+		try {
+			const hit = await ctx.credentials.resolve(credentialRef(name));
+			return hit?.value !== void 0 && hit.value !== "" ? hit.value : void 0;
+		} catch {
+			return;
+		}
+	};
 	return await Promise.all(declarations.map(async (decl) => {
 		const displayName = typeof decl.displayName === "string" && decl.displayName !== "" ? decl.displayName : "已声明";
 		const provider = `declared:${displayName}`;
@@ -5083,8 +5143,8 @@ async function queryDeclaredEndpoints(ctx, providers, declarations) {
 			declared: true,
 			error: "unreachable"
 		};
-		const hit = await ctx.credentials.resolve(credentialRef(matched.apiKeyEnv ?? ""));
-		if (hit === void 0 || hit.value === "") return {
+		const hit = await firstResolvedRef([...matched.apiKeyEnv !== void 0 ? [matched.apiKeyEnv] : [], ...routeKeyRefCandidates(matched.route)], resolveRef);
+		if (hit === void 0) return {
 			provider,
 			displayName,
 			declared: true,
@@ -5712,7 +5772,11 @@ function swallowed(reason, error) {
 * 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.
 */
 /** 每平台熔断门：某个订阅适配器连续可重试失败（网络 / 5xx / 429）达阈值后
 *  短路由不可用，避免 30 秒轮询对已故障的上游反复打满超时。鉴权失败（unauthorized）
@@ -5761,6 +5825,88 @@ const EMPTY_SUBSCRIPTION_KEYS = {
 	tencentCloudApi: "",
 	zaiRegion: "global"
 };
+/** 订阅 provider id（llm-pi-ai 设置键）→ SubscriptionKeys 字段的映射。 */
+const SUBSCRIPTION_KEY_SOURCES = [
+	{
+		provider: "kimi-coding",
+		key: "kimiApiKey"
+	},
+	{
+		provider: "zai-coding-cn",
+		key: "zaiCnApiKey"
+	},
+	{
+		provider: "zai-coding",
+		key: "zaiApiKey"
+	},
+	{
+		provider: "opencode",
+		key: "opencodeApiKey"
+	},
+	{
+		provider: "opencode-go",
+		key: "opencodeApiKey"
+	},
+	{
+		provider: "minimax",
+		key: "minmaxApiKey"
+	},
+	{
+		provider: "minimax-token-plan",
+		key: "minmaxApiKey"
+	},
+	{
+		provider: "minimax-token-plan-cn",
+		key: "minmaxApiKey"
+	},
+	{
+		provider: "minimax-cn",
+		key: "minmaxApiKey"
+	},
+	{
+		provider: "openrouter",
+		key: "openrouterApiKey"
+	},
+	{
+		provider: "commandcode",
+		key: "commandcodeApiKey"
+	},
+	{
+		provider: "tencent-token-plan",
+		key: "tencentCloudApi"
+	}
+];
+/**
+* key 解析的可测核心（无文件 I/O）：先显式 `apiKeyEnv`（旧口径，优先），key 仍缺
+* 时按约定 ref 名解析（新版宿主的存放形态，见 route-keys.ts）。`keyConfigured`
+* 回报每条路由的 key 是否解析成功，供识别层作为第三配置信号（refResolved）。
+* @param providers - llm-pi-ai 的 providers 视图。
+* @param resolveRef - 凭据 seam：ref 名 → 非空 key 值；未配置/失败返回 undefined。
+*/
+async function resolveSubscriptionAccess(providers, resolveRef) {
+	const keys = { ...EMPTY_SUBSCRIPTION_KEYS };
+	const keyConfigured = /* @__PURE__ */ new Set();
+	for (const { provider, key } of SUBSCRIPTION_KEY_SOURCES) {
+		const env = providers[provider]?.apiKeyEnv;
+		if (typeof env === "string" && env !== "") {
+			const value = await resolveRef(env);
+			if (value !== void 0) {
+				keys[key] = value;
+				keyConfigured.add(provider);
+				continue;
+			}
+		}
+		const hit = await firstResolvedRef(routeKeyRefCandidates(provider), resolveRef);
+		if (hit !== void 0) {
+			keys[key] = hit.value;
+			keyConfigured.add(provider);
+		}
+	}
+	return {
+		keys,
+		keyConfigured
+	};
+}
 /** 订阅类 provider 的显示名（未命中的回退为 id 本身）。 */
 const SUBSCRIPTION_DISPLAY_NAMES = {
 	"kimi-coding": "Kimi For Coding",
@@ -5814,14 +5960,15 @@ const SUBSCRIPTION_ADAPTERS = {
 /** 有额度适配器的 provider id 集合（识别用）。 */
 const ADAPTER_PROVIDER_IDS = new Set(Object.keys(SUBSCRIPTION_ADAPTERS));
 /**
-* 从 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.
 */
 function identifySubscriptionPlans(providers) {
 	const out = [];
 	for (const [id, config] of Object.entries(providers ?? {})) {
-		if (typeof config?.apiKeyEnv !== "string" || config.apiKeyEnv === "") continue;
+		if (!(typeof config?.apiKeyEnv === "string" && config.apiKeyEnv !== "" || config?.hasModels === true || config?.refResolved === true)) continue;
 		if (!isSubscriptionProviderId(id)) continue;
 		out.push({
 			provider: id,
@@ -6552,9 +6699,10 @@ async function collectSubscriptions(keys, plans = [], timeoutMs = DEFAULT_TIMEOU
 *
 * 适用场景：用户把某条 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）；
@@ -6744,7 +6892,7 @@ async function readRelayByKind(baseURL, apiKey, kind) {
 /**
 * 查询单个中转站路由的额度。先试 Sub2API，再试 New API；任一读出额度即返回。
 * @param ctx - host context carrying the credentials seam.
-* @param route - 待探测的路由（baseURL + apiKeyEnv）。
+* @param route - 待探测的路由（baseURL + 凭据 ref 候选）。
 * @returns 该路由的一行额度结果（status 标记成败）。
 */
 async function queryRelayQuota(ctx, route) {
@@ -6753,32 +6901,32 @@ async function queryRelayQuota(ctx, route) {
 		origin: originOf(route.baseURL),
 		displayName: route.displayName ?? route.route
 	};
-	const gateKey = `${route.baseURL}::${route.apiKeyEnv}`;
+	const gateKey = `${route.baseURL}::${route.route}`;
 	if (!relayGate.check(gateKey)) return {
 		...base,
 		kind: "unknown",
 		status: "unavailable"
 	};
-	let hit;
-	try {
-		hit = await ctx.credentials.resolve(credentialRef(route.apiKeyEnv));
-	} catch {
-		return {
-			...base,
-			kind: "unknown",
-			status: "not-configured"
-		};
-	}
-	if (hit === void 0 || hit.value === "") return {
+	const resolveRef = async (name) => {
+		try {
+			const hit = await ctx.credentials.resolve(credentialRef(name));
+			return hit?.value !== void 0 && hit.value !== "" ? hit.value : void 0;
+		} catch {
+			return;
+		}
+	};
+	const hit = await firstResolvedRef(route.apiKeyRefs, resolveRef);
+	if (hit === void 0) return {
 		...base,
 		kind: "unknown",
 		status: "not-configured"
 	};
+	const apiKey = hit.value;
 	const cached = fingerprintCache.get(base.origin);
 	const knownKind = cached !== void 0 && Date.now() - cached.at < FINGERPRINT_TTL_MS ? cached.kind : void 0;
 	try {
 		if (knownKind === "sub2api" || knownKind === "new-api") {
-			const parsed = await readRelayByKind(route.baseURL, hit.value, knownKind);
+			const parsed = await readRelayByKind(route.baseURL, apiKey, knownKind);
 			if (parsed !== null) {
 				relayGate.success(gateKey);
 				return {
@@ -6796,7 +6944,7 @@ async function queryRelayQuota(ctx, route) {
 				status: "invalid-response"
 			};
 		}
-		const sub2 = await fetchRelayJson(endpointOf(route.baseURL, "/v1/usage"), hit.value);
+		const sub2 = await fetchRelayJson(endpointOf(route.baseURL, "/v1/usage"), apiKey);
 		if (sub2.ok) {
 			const parsed = parseSub2ApiUsage(sub2.data);
 			if (parsed !== null) {
@@ -6820,7 +6968,7 @@ async function queryRelayQuota(ctx, route) {
 				status: "invalid-response"
 			};
 		}
-		const na = await fetchRelayJson(endpointOf(route.baseURL, "/api/status"), hit.value);
+		const na = await fetchRelayJson(endpointOf(route.baseURL, "/api/status"), apiKey);
 		if (na.ok) {
 			const parsed = parseNewApiStatus(na.data);
 			if (parsed !== null) {
@@ -6862,7 +7010,7 @@ async function queryRelayQuota(ctx, route) {
 /**
 * 批量查询多个中转站路由的额度（每个独立成败，互不影响）。
 * @param ctx - host context carrying the credentials seam.
-* @param routes - 配了 baseURL 且 apiKeyEnv 有值的路由列表。
+* @param routes - 配了 baseURL 且 key 候选可得（显式引用存在或约定 ref 解析出值）的路由列表。
 * @returns 每个路由一行的额度结果。
 */
 async function queryRelayQuotas(ctx, routes) {
@@ -7584,61 +7732,6 @@ const inject = [
 	"credentials",
 	"settings"
 ];
-/**
-* 订阅 provider id（llm-pi-ai 设置键）→ billing 适配器 key 的映射。
-* 复用 dsh 既有的 llm-pi-ai provider 配置（apiKeyEnv 引用），不引入新配置面。
-*/
-/** key 只取字符串凭据字段：zaiRegion 是区域枚举，由下方区域逻辑单独赋值。 */
-const SUBSCRIPTION_KEY_SOURCES = [
-	{
-		provider: "kimi-coding",
-		key: "kimiApiKey"
-	},
-	{
-		provider: "zai-coding-cn",
-		key: "zaiCnApiKey"
-	},
-	{
-		provider: "zai-coding",
-		key: "zaiApiKey"
-	},
-	{
-		provider: "opencode",
-		key: "opencodeApiKey"
-	},
-	{
-		provider: "opencode-go",
-		key: "opencodeApiKey"
-	},
-	{
-		provider: "minimax",
-		key: "minmaxApiKey"
-	},
-	{
-		provider: "minimax-token-plan",
-		key: "minmaxApiKey"
-	},
-	{
-		provider: "minimax-token-plan-cn",
-		key: "minmaxApiKey"
-	},
-	{
-		provider: "minimax-cn",
-		key: "minmaxApiKey"
-	},
-	{
-		provider: "openrouter",
-		key: "openrouterApiKey"
-	},
-	{
-		provider: "commandcode",
-		key: "commandcodeApiKey"
-	},
-	{
-		provider: "tencent-token-plan",
-		key: "tencentCloudApi"
-	}
-];
 /** 读 llm-pi-ai 设置的 `providers` 字典（`<route> → { apiKeyEnv?, baseURL?, displayName? }`）。
 *  余额与订阅查询复用同一份来源：部署为某个 provider 配一次，多 surface 共享。
 * @param settings - the settings service (reads the llm-pi-ai namespace).
@@ -7651,10 +7744,12 @@ async function readPiAiProviders(settings) {
 		for (const [route, entry] of Object.entries(providers ?? {})) {
 			if (entry === null || typeof entry !== "object") continue;
 			const { apiKeyEnv, baseURL, displayName } = entry;
+			const models = entry.models;
 			out[route] = {
 				...typeof apiKeyEnv === "string" ? { apiKeyEnv } : {},
 				...typeof baseURL === "string" ? { baseURL } : {},
-				...typeof displayName === "string" ? { displayName } : {}
+				...typeof displayName === "string" ? { displayName } : {},
+				...Array.isArray(models) && models.length > 0 ? { hasModels: true } : {}
 			};
 		}
 		return out;
@@ -7761,51 +7856,47 @@ function buildWorkspaceTitleResolver(ctx) {
 	};
 }
 /**
-* 解析订阅适配器需要的 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).
+* 凭据 seam 的宽容解析：ref 名 → 非空值；失败/缺失返回 undefined（多 surface 共用，
+* 失败按结构化静默记录）。
 */
-async function resolveSubscriptionKeys(settings, credentials) {
-	const keys = { ...EMPTY_SUBSCRIPTION_KEYS };
-	let providers;
-	try {
-		providers = (settings.describe({ redactSecrets: true }).find((descriptor) => descriptor.ns === "llm-pi-ai")?.value)?.providers;
-	} catch {
-		return {
-			keys,
-			identified: []
-		};
-	}
-	for (const { provider, key } of SUBSCRIPTION_KEY_SOURCES) {
-		const env = providers?.[provider]?.apiKeyEnv;
-		if (typeof env !== "string" || env === "") continue;
+function refResolver(credentials) {
+	return async (name) => {
 		try {
-			const resolved = await credentials.resolve(credentialRef(env));
-			if (resolved?.value !== void 0 && resolved.value !== "") keys[key] = resolved.value;
+			const resolved = await credentials.resolve(credentialRef(name));
+			return resolved?.value !== void 0 && resolved.value !== "" ? resolved.value : void 0;
 		} catch (error) {
 			swallowed("credential-resolve-failed", error);
+			return;
 		}
-	}
-	if (providers?.["zai-coding-cn"]?.apiKeyEnv !== void 0 && keys.zaiCnApiKey !== "") keys.zaiRegion = "bigmodel-cn";
+	};
+}
+/**
+* 解析订阅适配器需要的 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).
+*/
+async function resolveSubscriptionKeys(settings, credentials) {
+	const providers = await readPiAiProviders(settings);
+	const { keys, keyConfigured } = await resolveSubscriptionAccess(providers, refResolver(credentials));
+	if (keys.zaiCnApiKey !== "") keys.zaiRegion = "bigmodel-cn";
 	if (keys.opencodeApiKey === "") keys.opencodeApiKey = await readOpenCodeToken();
 	keys.anthropicApiKey = await readClaudeOAuthToken();
-	if (keys.anthropicApiKey !== "") {
-		const identified = identifySubscriptionPlans(providers);
-		if (!identified.some((plan) => plan.provider === "anthropic")) identified.push({
-			provider: "anthropic",
-			displayName: "Claude (Anthropic)",
-			adapter: true
-		});
-		return {
-			keys,
-			identified
-		};
-	}
+	const identified = identifySubscriptionPlans(Object.fromEntries(Object.entries(providers).map(([route, entry]) => [route, {
+		...entry.apiKeyEnv !== void 0 ? { apiKeyEnv: entry.apiKeyEnv } : {},
+		...entry.hasModels === true ? { hasModels: true } : {},
+		...keyConfigured.has(route) ? { refResolved: true } : {}
+	}])));
+	if (keys.anthropicApiKey !== "" && !identified.some((plan) => plan.provider === "anthropic")) identified.push({
+		provider: "anthropic",
+		displayName: "Claude (Anthropic)",
+		adapter: true
+	});
 	return {
 		keys,
-		identified: identifySubscriptionPlans(providers)
+		identified
 	};
 }
 /** 读本机 OpenCode 客户端的凭据 token；取不到返回空串（安静退回）。 */
@@ -8341,14 +8432,18 @@ function apply(ctx, config = {}) {
 	};
 	const refreshRelay = async () => {
 		const providers = await readPiAiProviders(ctx.settings);
+		const resolve = refResolver(ctx.credentials);
 		const routes = [];
 		for (const [route, entry] of Object.entries(providers)) {
-			if (entry.baseURL === void 0 || entry.apiKeyEnv === void 0) continue;
+			if (entry.baseURL === void 0) continue;
 			if (isOfficialBaseUrl(entry.baseURL)) continue;
+			const apiKeyRefs = [.../* @__PURE__ */ new Set([...entry.apiKeyEnv !== void 0 ? [entry.apiKeyEnv] : [], ...routeKeyRefCandidates(route)])];
+			const hit = await firstResolvedRef(apiKeyRefs, resolve);
+			if (entry.apiKeyEnv === void 0 && hit === void 0) continue;
 			routes.push({
 				route,
 				baseURL: entry.baseURL,
-				apiKeyEnv: entry.apiKeyEnv,
+				apiKeyRefs,
 				...entry.displayName === void 0 ? {} : { displayName: entry.displayName }
 			});
 		}

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/client/budget-store.d.ts

@@ -33,6 +33,10 @@ export type BudgetPrefsActions = {
     setModelBudget: (d: BudgetPrefsState, key: string, value: number) => void;
     markModelTierAlerted: (d: BudgetPrefsState, marks: readonly string[], day: string) => void;
 };
+/** 读取兜底：v1.5.x 老持久化状态缺 `modelBudgets` 键（模块级常量，引用稳定不触发重渲染）。 */
+export declare const EMPTY_MODEL_BUDGETS: Readonly<Record<string, number>>;
+/** 读取兜底：v1.5.x 老持久化状态缺 `modelTierAlertDays` 键（同上）。 */
+export declare const EMPTY_MODEL_TIER_ALERT_DAYS: Readonly<Record<string, string>>;
 /**
  * Declare the budget-preferences store handle.
  * @returns the store handle for the register call's store seat.

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

@@ -41,12 +41,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 +77,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[]>;