dsh-connect-modelscope-token-plan 0.1.0

package/lib/host-config-DBCiZOBW.js

@@ -0,0 +1,900 @@
+//#region src/host/util.ts
+/** 读一个有限的正数，否则回退值。 */
+function num(value, fallback) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+/** 读一个非空字符串，否则回退值。 */
+function str(value, fallback) {
+	return typeof value === "string" && value.trim() !== "" ? value.trim() : fallback;
+}
+/** 读一个普通对象，否则 `{}`。 */
+function obj(value) {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+/** catch 点统一的一行错误消息。 */
+function errMsg(value) {
+	return value instanceof Error ? value.message : String(value);
+}
+/** 原样读字符串（凭据专用：trim 是用户看不见的改动）。 */
+function verbatim(value, fallback) {
+	return typeof value === "string" ? value : fallback;
+}
+/**
+* 凭据形状字符串的脱敏闸：任何可能进日志/错误消息/面板响应的文本都先过这里。
+* 家规（AGENTS.md 红线 1）：凭据永不进日志。魔搭访问令牌的裸值形态
+* （`ms-` + UUID）与 `sk-` 推理键、Bearer/Basic 头、常见密钥键值对都在闸内。
+*/
+function redactSecrets(text) {
+	return (typeof text === "string" ? text : "").replace(/(["']?[Aa]uthorization["']?\s*[:=]\s*["']?)(?!Bearer\s)[^"',;\s]+/g, "$1[REDACTED]").replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi, "$1 [REDACTED]").replace(/\bms-[0-9a-f-]{16,}\b/gi, "ms-[REDACTED]").replace(/\bsk-[A-Za-z0-9._-]{8,}/g, "sk-[REDACTED]").replace(/(["']?(?:password|access_token|refresh_token|api[_-]?key|token)["']?\s*:\s*["'])[^"']+(?=["'])/gi, "$1[REDACTED]").replace(/\b(password|access_token|refresh_token|api[_-]?key|token)\s*=\s*[^&;\s]+/gi, "$1=[REDACTED]");
+}
+/**
+* 吞掉失败但留下痕迹。opt-in 模块按设计降级，但降级的理由必须落日志
+* （warn 而非 debug——debug 在默认 Host 上被滤掉等于零日志）。错误消息先
+* 脱敏。返回 fallback，两种静默 catch 形态都能用。
+*/
+function degrade(reason, error, logger, fallback) {
+	const detail = error == null ? "" : redactSecrets(errMsg(error));
+	logger?.warn?.(detail === "" ? `degraded: ${reason}` : `degraded: ${reason}: ${detail}`);
+	return fallback;
+}
+/**
+* Await 一个 OPTIONAL 的 store 调用：值缺失与 promise 拒绝都读作 fallback。
+* 注意守卫要套在**值**上（`Promise.resolve(value).catch(...)`）而不是调用结果上
+* ——`try { await value } catch` 漏掉「value 本身是 undefined」这条。
+*/
+function optional(value, fallback = null) {
+	return Promise.resolve(value).catch(() => fallback);
+}
+/** 带 code 的 Error：本插件所有失败的唯一构造点。 */
+function pluginError(code, message, extra = {}) {
+	const error = new Error(message);
+	error.code = code;
+	if (extra.retryAfterMs !== void 0) error.retryAfterMs = extra.retryAfterMs;
+	if (extra.detail !== void 0) error.detail = extra.detail;
+	return error;
+}
+
+//#endregion
+//#region src/host/llm-error-fix.ts
+/**
+* 429 误判纠正层 —— host 侧对 peer 分类器的安全覆盖。
+*
+* 根因（对照 peer 源码 `@deepseek-ai/dsh-llm-pi-ai` 的 `classifyPiAiError`
+* 与 `@deepseek-ai/dsh-llm` 的 `isQuotaExceededError`，二者均为**非行号锚**
+* 的稳定符号；其判定顺序与措辞命中面由 `test/peer-contract.test.mjs` 在
+* 真 peer 可达时钉死——该契约测试依赖未 vendored 进本仓库的运行时 peer，不在
+* `npm test` 离线门禁内，本模块自身的纠正判定由 `test/error-fix.test.mjs` 钉死）：
+*   `classifyPiAiError` **先**跑 `isQuotaExceededError`（命中面极宽：`out of
+*   ... budget`、`balance/credits exhausted` 等），**后**才跑纯限频分支
+*   （`\b429\b|rate.?limit`）。凡是魔搭 429 体里带上一两个 “budget/credits/
+*   limit” 字眼，就被前一行抢判成 `QUOTA`；于是 `llm-retry.ts` 的
+*   `retryableCodes()`（刻意排除 QUOTA）对这类 429 不重试，面板又把模型按
+*   `exhaustedModelIds` 静默下线，对用户呈现“额度耗尽”。
+*
+* 本模块在 host 侧把“看似限频却被误判为 QUOTA 的 429”纠正回 `RATE_LIMIT`，
+* 让退避重试真正生效；真配额耗尽（明确余额/积分耗尽的硬额度措辞）保留
+* `QUOTA`（那是共享 Token Plan 池的硬耗尽，重试只会延长冷却窗口，见
+* ROADMAP §1 纪律）。
+*
+* 设计约束（对应 AGENTS.md 红线与并行纪律）：
+*   - 不动 vendor peer：peer 不在此插件 git 内，也不可被改。
+*   - 零 peer 依赖：纯函数 + 稳定协议字符串；peer 缺席（干净 checkout）时
+*     模块仍加载、测试仍跑，不破坏 `npm test` 离线门禁。
+*   - 只重写 `finish` chunk 的 `failure.code`，保留原始 `message` 以便排查，
+*     不触碰任何正常数据流，幂等（已是 RATE_LIMIT / 非 QUOTA 原样放行）。
+*
+* 阅读顺序：本文件自上而下是「判据词表 → 两个纯判据 → 决策组合 → 流出口
+* 改写」。对外契约在底部（`reclassifyStream` / `reclassifyFinish`），想找它
+* 依赖了哪些判据，就从底部逆着依赖链往上读。
+*
+* @module dsh-connect-modelscope-token-plan/llm-error-fix
+*/
+/**
+* 与 peer 协议对齐的失败类（稳定字符串，不 import peer 也成立）。
+* `QUOTA` 来自 `@deepseek-ai/dsh-llm` 的 `QUOTA_EXCEEDED_CODE`，`RATE_LIMIT`
+* 来自 peer `classifyPiAiError` 的返回字面量。
+*/
+const CODE = Object.freeze({
+	/** 共享 Token Plan 池耗尽（peer 不重试，本层默认也不纠正）。 */
+	QUOTA: "QUOTA",
+	/**
+	* 账户级配额耗尽。peer 的 `classifyPiAiError` 目前不产生此类（它只返回
+	* `QUOTA_EXCEEDED_CODE`），列在此处纯为协议对齐与防御；本层不纠正它。
+	*/
+	ACCOUNT_QUOTA: "ACCOUNT_QUOTA",
+	/** 瞬时限频（peer retryPolicy 默认重试，本层把误判体拉回这里）。 */
+	RATE_LIMIT: "RATE_LIMIT"
+});
+/** 纯文本层面的限频信号（v1 启发用）。 */
+const RATE_SIGNAL = [
+	/\b429\b/,
+	/rate[_\s-]?limit/i,
+	/too many requests?/i,
+	/requests?\s+(?:per|rate|freq)/i,
+	/\b(?:rpm|tpm)\b/,
+	/throttl/i,
+	/请求过于频繁|限流|频率/
+];
+/**
+* 硬额度措辞：命中即相信是配额耗尽，不纠正（避免把真耗尽也拉去重试）。
+*
+* 最后两条是被 `codes.ts#classifyRateLimit` 的回归用例逼出来的：那张表的旧词表
+* 里有 `"daily"`，而这里没有，于是 `"You have reached your daily limit"`（真日额度
+* 耗尽）被共用后的新判据读成限频。两处现在共用这一份，缺口不会再各漂各的。
+*/
+const HARD_QUOTA_WORDING = [
+	/\b(?:balance|credits?)\s+(?:exhausted|depleted)\b/i,
+	/\bout[\s_-]+of[\s_-]+(?:credits?|budget)\b/i,
+	/额度\s*(?:已)?\s*(?:用尽|耗尽|不足)/,
+	/quota\s*(?:exceeded|exhausted|reached)/i,
+	/\b(?:daily|per[\s_-]?day|monthly|per[\s_-]?month)\b[^\n]{0,24}?\blimit\b/i,
+	/(?:每日|每月)\s*(?:调用)?\s*(?:上限|额度|配额)/
+];
+/** 结构化 type 分支认的「速率上限」信号：rpm/tpm/每分钟/限流/频率。 */
+const RATE_CAP_WORDING = /\brpm\b|\btpm\b|rate[_\s-]?limit|per[\s_-]?(?:min|minute|sec|second)|too many|限流|频率|请求过于频繁/i;
+/** 从错误文本里回捞魔搭结构化 `type` 字段（如 `"type":"quota_exceeded_error"`）。 */
+const STRUCTURED_TYPE = /"type"\s*:\s*"([^"]+)"/i;
+/**
+* 文本是否含硬额度措辞（真耗尽，不纠正）。
+*
+* 导出给 `codes.ts` 的 `classifyRateLimit`——那张表曾自己维护一份同组正则，
+* 于是「限频被误判成耗尽」和「耗尽被误判成限频」两个方向的漂移都可能发生。
+* 词表只有这一份，改它时 `test/error-fix.test.mjs` 与 `test/provider.test.mjs`
+* 会一起红。
+* @param message - 平台错误文本。
+* @returns `true` 表示命中硬额度措辞。
+*/
+function hasHardQuotaWordingIn(message) {
+	if (typeof message !== "string" || message.length === 0) return false;
+	return HARD_QUOTA_WORDING.some((re) => re.test(message));
+}
+/**
+* 一个 429 体是否“更可能是限频而非真配额耗尽”——纯文本启发（v1）。
+*
+* 判据：消息里出现显式限频信号（{@link RATE_SIGNAL} 任一），且**没有**命中
+* 硬额度措辞（{@link HARD_QUOTA_WORDING}）。
+*
+* 关键区分：“out of **rate** budget” / “rate limit budget” 是限频体，不在硬
+* 额度措辞里，所以仍判为限频——这正是误判的核心。
+* @param {string} message - 平台错误文本（可能含状态码与 JSON）。
+* @returns {boolean} true 表示应纠正为 RATE_LIMIT。
+*/
+function looksLikeRateLimit(message) {
+	if (typeof message !== "string" || message.length === 0) return false;
+	const m = message.toLowerCase();
+	if (!RATE_SIGNAL.some((re) => re.test(m))) return false;
+	return !hasHardQuotaWordingIn(message);
+}
+/**
+* 从错误文本里抽出魔搭结构化 `type` 字段。
+*
+* peer 把整条错误 JSON 拼进 `failure.message`，所以这里能从文本回捞结构信
+* 号，而不依赖 peer 是否单独透传了 `type`。抓不到返回 null。
+* @param {string} message
+* @returns {string|null}
+*/
+function extractStructuredType(message) {
+	if (typeof message !== "string" || message.length === 0) return null;
+	const match = STRUCTURED_TYPE.exec(message);
+	return match ? match[1] ?? null : null;
+}
+/**
+* 一个被 peer 判为 QUOTA 的失败，是否其实是限频、应纠正为 RATE_LIMIT。
+*
+* 这是修正 v1（纯文本启发）漏判的核心：`{"message":"rpm exhausted",
+* "type":"quota_exceeded_error","code":"8"}` 这种体——魔搭把**请求速率上限**
+* 复用 `quota_exceeded_error` 这个名字，纯文本里没有 “rate limit” 字样，v1 的
+* `looksLikeRateLimit` 既没命中限频信号也没命中硬额度，于是留在 QUOTA、不重试、
+* 直接失败。本函数改读结构化 `type`，逐层收窄：
+*
+*   1. `type` 含 `rate_limit` → 本就是限频（peer 多数已判 RATE_LIMIT，这里是防御）。
+*   2. `type` 含 `quota` 但仍带 {@link RATE_CAP_WORDING}（rpm/tpm/每分钟/限流…）
+*      → 是“被错命名为 quota 的速率上限”，纠正为 RATE_LIMIT。
+*   3. `type` 含 `quota` 且无任何速率信号（token/credit/balance 真耗尽）→ 保留 QUOTA。
+*   4. `type` 是其它非 quota 值 → 保守不纠正。
+*   5. 无结构化 `type` → 退回 v1 的 {@link looksLikeRateLimit}。
+*
+* 不纠正真配额耗尽：那是共享 Token Plan 池的硬耗尽，重试只会延长冷却窗口
+* （ROADMAP §1 纪律），所以宁可快失败。
+* @param {{code?: string, message?: string}} failure
+* @returns {boolean} true 表示应纠正为 RATE_LIMIT。
+*/
+function shouldReclassifyQuotaToRate(failure) {
+	if (!failure || failure.code !== CODE.QUOTA) return false;
+	const message = typeof failure.message === "string" ? failure.message : "";
+	const type = extractStructuredType(message);
+	if (type !== null) {
+		const t = type.toLowerCase();
+		if (/rate[_\s-]?limit/.test(t)) return true;
+		if (/quota/.test(t)) return RATE_CAP_WORDING.test(message);
+		return false;
+	}
+	return looksLikeRateLimit(message);
+}
+/**
+* 把单个流 chunk 里的失败码在误判时纠正。
+*
+* 非 finish、非 error 终止、非 QUOTA，或已判为限频的，一律原样返回（新对象
+* 仅在确有纠正时创建，保持调用方对引用相等的预期）。
+* @param {object} chunk - harness 流协议 chunk。
+* @returns {object} 原 chunk 或 code 被纠正后的新 chunk。
+*/
+function reclassifyFinish(chunk) {
+	if (!isErrorFinish(chunk)) return chunk;
+	const errorChunk = chunk;
+	const reason = errorChunk.reason;
+	const failure = reason?.failure;
+	if (failure === void 0 || !shouldReclassifyQuotaToRate(failure)) return chunk;
+	return {
+		...errorChunk,
+		reason: {
+			...reason,
+			failure: {
+				...failure,
+				code: CODE.RATE_LIMIT
+			}
+		}
+	};
+}
+/** 是否为「带 failure 的 error 型 finish chunk」——纠正层唯一关心的形状。 */
+function isErrorFinish(chunk) {
+	if (chunk === null || typeof chunk !== "object") return false;
+	const candidate = chunk;
+	return candidate.type === "finish" && candidate.reason !== null && typeof candidate.reason === "object" && candidate.reason.kind === "error" && candidate.reason.failure != null;
+}
+/**
+* 包裹一个 adapter 的 async iterator 流：对每个 finish chunk 做重判。
+* @param {AsyncIterableIterator<object>} source - 内层 adapter 的流。
+* @returns {AsyncGenerator<object>} 纠正后的流。
+*/
+async function* reclassifyStream(source) {
+	for await (const chunk of source) yield reclassifyFinish(chunk);
+}
+
+//#endregion
+//#region src/host/llm-models.ts
+/**
+* 目录条目 → pi-ai model descriptor 的映射层——魔搭 provider 注册的**纯函数半边**。
+*
+* 本模块刻意不 import 任何 Host peer（`@earendil-works/pi-ai`、
+* `@deepseek-ai/dsh-llm-pi-ai`）：它只产普通对象，所以这些映射决策可以在一个
+* 干净的 checkout 上离线测。peer 依赖的另一半（把这些 descriptor 交给
+* `createProvider`）在 `llm-adapter.ts`。
+*
+* 这里携带的三条决策是承重的，不是装饰：
+*
+* 1. `compat.supportsDeveloperRole: false`。pi-ai 在缺省时会**自动探测**这个
+*    标志，对非标准 provider 一律猜 `true`，于是每条请求都用 `developer`
+*    角色——魔搭这个多模型代理不认识，会 400 或 403。qoder 路由证明必须
+*    显式写 false。
+* 2. `maxTokens` 只在目录**声明了**上限时声明。harness 对未声明的 maxTokens
+*    用 `defaultMaxTokens ?? 32768` 兜底，所以「不声明」不是「没有上限」，而是
+*    「平台没说」的诚实处理；别猜数字填。
+* 3. `reasoning: false` + **不设** `thinkingLevelMap`。魔搭 API-Inference 是
+*    多模型代理，是否吃 `reasoning_effort` 取决于背后那个具体模型，本插件
+*    无法离线得知每个 id 的档位表（sensenova 那份是拿真令牌逐模型探测 200/400
+*    才钉出来的）。「宁可不选，不可错发」：发错档位会整条请求 400，比不发
+*    差得多。M4 之后的迭代（探测出档位表）再按模型开启。
+*
+* @module dsh-connect-modelscope-token-plan/llm-models
+*/
+/**
+* 本插件注册 provider 用的 id。
+*
+* **绝不能**是裸 `"modelscope"`：操作者可能已手写一条 `llm-pi-ai`
+* （apiKeyEnv `MODELSCOPE_API_KEY`、base `https://api-inference.modelscope.cn/v1`），
+* `registerAdapter` 对冲突 id 直接拒绝。自有 slug 形 id 不会撞。
+*/
+const LLM_PROVIDER_ID = "modelscope-token-plan";
+/** DSH 模型选择器里显示的 provider 名。 */
+const LLM_DISPLAY_NAME = "ModelScope Token Plan";
+/** pi-ai 展示的凭据名（静态令牌，形如 `ms-…`）。 */
+const LLM_API_KEY_NAME = "ModelScope token";
+/**
+* 代表「什么都不提供」的 id。
+*
+* 空的允许清单已经表示「不过滤」，所以还得有第二种写法表示「过滤结果为空」：
+* 一个永远不可能成为真实模型 id 的字符串，作为清单里唯一的项。`filterByEnabled`
+* 按一个匹配不到任何东西的 id 过滤，这就是用户要的 offer。裸 `[]` 不能同时表示
+* 「全部模型」与「没有模型」。
+*
+* provider 路由与快照用同一个字面量（浏览器 bundle 无法 import 本模块，所以
+* `client.js` 里还有一份）——两侧改名必须一起改，否则面板的「全部隐藏」会
+* 静默变成「全部提供」。
+*/
+const HIDE_ALL_MODELS = "__hide_all__";
+/**
+* 每 token 单价对额度制路由不可知，四处一律报零。
+*
+* ⚠️ 零是**哨兵**，不是「免费」。魔搭 Token Plan 是次数/额度池计费，按 token
+* 的美元单价在这条路上根本不存在——但模型照样烧额度。面板行显示 "$0.00" 说的是
+* 「按 token 单价未知」，永远不是「这模型不花钱」。注释就贴在这组值旁边，免得
+* 后来人「好心」改成真价，或更糟改成 `null`（pi-ai 会把它当未知成本行渲染，
+* 弄坏选择器的成本算术）。
+*/
+const NO_COST = Object.freeze({
+	input: 0,
+	output: 0,
+	cacheRead: 0,
+	cacheWrite: 0
+});
+/**
+* 目录没声明可用窗口时的兜底窗口。
+*
+* pi-ai 的 options 构建器会对 `model.contextWindow` 做算术，所以 undefined 被
+* 当 0 算而不是「未知」，会把 max-token 计算算坏；qoder 路由因此总是给正数。
+* 128k 是保守的通用默认；目录真的声明了窗口时，那个值永远赢。
+*/
+const FALLBACK_CONTEXT_WINDOW = 128e3;
+/** 判 vision 时优先读的结构化模态字段（平台拼写 + 常见别称）。 */
+const INPUT_MODALITY_KEYS = Object.freeze([
+	"input_modalities",
+	"modalities",
+	"inputTypes",
+	"modality",
+	"capabilities"
+]);
+/**
+* 无结构化字段时的名字启发。
+*
+* 多模态模型名里 `vl` 很常见，这条启发是社区惯例。漏判 = 模型收图时报
+* `UNSUPPORTED_CONTENT`，面板能看见，不算静默失败（所以方向偏「松」）。
+*/
+const VISION_NAME_PATTERN = /(vl|vision|qwen2?\.?\d*-?vl|glm.*v|internvl|llava|pixtral)/i;
+/**
+* 明确是图像**生成**模型的 id/名字才排除。
+*
+* 魔搭目录里这些是纯生图模型，打 `/chat/completions` 会 404。没标注的一律算
+* chat——缺失字段不等于不能用。
+*/
+const IMAGE_GEN_NAME_PATTERN = /(wanx|qwen-image|cogview|flux|stable-diffusion|sdxl|sd3|txt2img|text-to-image|draw|seedream|kolors|hunyuan-?image|imagen)/i;
+/**
+* 人工策展的「已知多模态（能吃图）模型」清单——详情端点**不可达时**的离线兜底。
+*
+* 为什么还需要：魔搭 `/v1/models` 实测每条只返回 `id`/`object`/`owned_by`/`created`，
+* 零模态字段（不像 sensenova 有 `type` 字段可判），名字启发也会漏掉
+* `DeepSeek-V4.1-Flash` 这类「名字不含 vl/vision 但能吃图」的模型。详见 `isVisionModel`：
+* 首选详情端点 `Tasks[].Name` 精确判定（image-text-to-text 即真），此清单只在详情拉取
+* 失败（网络 / 限频）时兜底，避免面板在离线时完全失去视觉标签。
+*
+* 这份清单是「我们已知」（模型卡 / 用户反馈），不是平台声明；与名字启发一样，**不假装
+* 上游返回过**。真机若某模型吃图却不在清单，最坏只是收 `UNSUPPORTED_CONTENT`，不静默
+* 失败。新增已确知的多模态模型时在此追加 id 即可。
+*
+* 已按详情端点 `Tasks[].Name == image-text-to-text` 逐条真机核实补全（2026-10-04，api-inference
+* 当前 35 条目录里共 14 条吃图模型，下面就是全部）。这样即使详情端点整段拉不到，面板也能
+* 保留准确的视觉标签，不用靠名字猜——`MiniMax-M3`/`Intern-S1`/`Qwen3.5-397B-A17B`/`Step-3.7-Flash`
+* 这类名字不含 vl/vision 的模型，光靠 `VISION_NAME_PATTERN` 会漏。
+*/
+const KNOWN_VISION_IDS = Object.freeze(/* @__PURE__ */ new Set([
+	"deepseek-ai/DeepSeek-V4.1-Flash",
+	"Qwen/Qwen3.8-Flash-Next",
+	"MiniMax/MiniMax-M3",
+	"OpenGVLab/InternVL3_5-241B-A28B",
+	"PaddlePaddle/ERNIE-4.5-VL-28B-A3B-PT",
+	"Qwen/Qwen3.5-122B-A10B",
+	"Qwen/Qwen3.5-27B",
+	"Qwen/Qwen3.5-35B-A3B",
+	"Qwen/Qwen3.5-397B-A17B",
+	"Qwen/Qwen3.8-27B",
+	"Shanghai_AI_Laboratory/Intern-S1",
+	"Shanghai_AI_Laboratory/Intern-S1-mini",
+	"Shanghai_AI_Laboratory/Intern-S2-Preview",
+	"stepfun-ai/Step-3.7-Flash"
+]));
+/**
+* 把原始 `/v1/models` data 条目变成归一目录条目。
+*
+* 只做投影与回退，不做判断：`id` 必取，`name` 回退 id，`vision`/`contextWindow`/
+* `maxOutputLength` 由下面的判断函数产出。`raw` 保留整条原始对象，且原始字段
+* 一并展开在条目上，所以 `context_length` 这类字段下游仍能直读——平台新增字段
+* 不需要改解析器。
+* @param {unknown} raw - `/v1/models` `data[]` 里的一条。
+* @returns {CatalogEntry} 归一后的条目。
+*/
+function normalizeEntry(raw) {
+	const source = raw !== null && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+	const id = str(source.id, "");
+	return {
+		...source,
+		id,
+		name: str(source.name, id),
+		capability: resolveModelCapability(source),
+		vision: isVisionModel(source),
+		contextWindow: contextWindowOf(source),
+		maxOutputLength: maxOutputLengthOf(source),
+		raw: source
+	};
+}
+/**
+* 读一条目录条目首个模态字段，取不到返回 undefined。
+*
+* 魔搭 `/v1/models` 是否声明 `input_modalities` 需真机核实；这里把平台拼写与
+* 常见别称一并列出，字符串/数组都能吃，平台换拼写不用改解析器。
+* @param {Record<string, unknown>} source - 一条目录条目。
+* @returns {string[]|undefined} 模态名列表，取不到为 undefined。
+*/
+function inputModalitiesOf(source) {
+	for (const key of INPUT_MODALITY_KEYS) {
+		const value = source[key];
+		if (Array.isArray(value)) return value.map((modality) => String(modality));
+		if (typeof value === "string" && value !== "") return value.split(/[,|]/).map((modality) => modality.trim()).filter((m) => m !== "");
+	}
+}
+/**
+* 读一条目录条目从详情端点带来的任务标签（image-text-to-text 等）。
+*
+* `fetchModels` 会对每个 id 并行请求 modelscope.cn/api/v1/models/{id}，把响应的
+* `Data.Tasks[].Name`（+ `widgets[].task` 兜底）收集后挂到 `entry.tasks`。取不到或
+* 非数组返回 undefined，调用方据此回退策展清单 + 名字启发。
+* @param {Record<string, unknown>} source - 一条目录条目。
+* @returns {string[]|undefined} 任务标签列表，取不到为 undefined。
+*/
+function tasksOf(source) {
+	const value = source.tasks;
+	if (Array.isArray(value)) {
+		const out = value.map((task) => String(task)).filter((task) => task !== "");
+		return out.length > 0 ? out : void 0;
+	}
+}
+/** 任务标签 → 能力。键为平台返回的小写任务名，词表见上方说明。 */
+const TASK_TO_CAPABILITY = Object.freeze({
+	"text-generation": "text",
+	"text2text-generation": "text",
+	"image-text-to-text": "vision-input",
+	"visual-question-answering": "vision-input",
+	"image-to-text": "image-to-text",
+	"image-caption": "image-to-text",
+	"image-to-image": "image-to-image",
+	"text-to-image-synthesis": "text-to-image",
+	"text-to-video-synthesis": "text-to-video"
+});
+/** 能力优先级：图像类信号比「纯文本」具体，多个标签时取最具体的一个。 */
+const CAPABILITY_RANK = Object.freeze({
+	unknown: 0,
+	text: 1,
+	"vision-input": 3,
+	"image-to-text": 3,
+	"image-to-image": 4,
+	"text-to-image": 5,
+	"text-to-video": 5
+});
+/** 从任务标签数组取能力；一个都不认识返回 undefined（调用方再走兜底）。 */
+function capabilityFromTasks(tasks) {
+	let best;
+	let bestRank = -1;
+	for (const task of tasks) {
+		const capability = TASK_TO_CAPABILITY[task.trim().toLowerCase()];
+		if (capability === void 0) continue;
+		if (CAPABILITY_RANK[capability] > bestRank) {
+			best = capability;
+			bestRank = CAPABILITY_RANK[capability];
+		}
+	}
+	return best;
+}
+/**
+* 解析一条目录条目的能力类型。
+*
+* 判定顺序（权威 → 兜底）：结构化模态字段 → 详情端点任务标签 → 策展清单 → 名字启发。
+* 前两级是平台声明，后两级是「我们已知 / 我们推断」，绝不混淆。
+* @param {object} entry - 一条归一目录条目。
+* @returns {ModelCapability} 能力类型。
+*/
+function resolveModelCapability(entry) {
+	const source = entry ?? {};
+	const modalities = inputModalitiesOf(source);
+	if (modalities !== void 0) return modalities.some((modality) => /image|vision/i.test(modality)) ? "vision-input" : "text";
+	const tasks = tasksOf(source);
+	if (tasks !== void 0) {
+		const capability = capabilityFromTasks(tasks);
+		if (capability !== void 0) return capability;
+		return "unknown";
+	}
+	const id = str(source.id, "");
+	if (id !== "" && KNOWN_VISION_IDS.has(id)) return "vision-input";
+	const idOrName = `${id} ${str(entry?.name, "")}`;
+	if (VISION_NAME_PATTERN.test(idOrName)) return "vision-input";
+	return "unknown";
+}
+/**
+* 一条目录条目能否吃图（vision）。
+*
+* 是 `resolveModelCapability` 的布尔投影：图进文出（`vision-input`）或图出文
+* （`image-to-text`/caption）算视觉模型；图出图（`image-to-image`）、文生图
+* （`text-to-image`）**不算**——它们不吃图，别混进 vision 开关。
+* 漏判 = 模型收图时报 `UNSUPPORTED_CONTENT`，面板能看见，不算静默失败。
+* @param {object} entry - 一条归一目录条目。
+* @returns {boolean} 是否吃图。
+*/
+function isVisionModel(entry) {
+	const capability = resolveModelCapability(entry);
+	return capability === "vision-input" || capability === "image-to-text";
+}
+/**
+* 一条目录条目能否作为 chat 模型寻址。
+*
+* **宽松方向**。只有明确是图像**生成**模型的 id/名字（`IMAGE_GEN_NAME_PATTERN`）
+* 或 `output_modalities` 只含 `image` 才排除：魔搭目录里这些是纯生图模型，打
+* `/chat/completions` 会 404。没标注的一律算 chat——缺失字段不等于不能用。
+* @param {object} entry - 一条归一目录条目。
+* @returns {boolean} 是否可用作 chat 模型。
+*/
+function isChatModel(entry) {
+	const out = (entry ?? {}).output_modalities;
+	if (Array.isArray(out) && out.length > 0) {
+		if (out.every((modality) => String(modality).toLowerCase() === "image")) return false;
+	}
+	const idOrName = `${str(entry?.id, "")} ${str(entry?.name, "")}`;
+	return !IMAGE_GEN_NAME_PATTERN.test(idOrName);
+}
+/**
+* 读目录声明的上下文窗口，取不到用兜底。
+*
+* 命中一个正数就用；否则 `FALLBACK_CONTEXT_WINDOW`——pi-ai 对 undefined 的
+* contextWindow 当 0 算，会坏掉 max-token 计算。与 `contextWindowOf` 同一份
+* 拼写策略：只认已知拼写，缺字段回退，不猜数字。
+* @param {object} entry - 一条归一目录条目。
+* @returns {number} 声明的窗口，或兜底值。
+*/
+function contextWindowOf(entry) {
+	for (const key of [
+		"context_length",
+		"context_window",
+		"contextWindow",
+		"max_context_tokens"
+	]) {
+		const value = Math.floor(num(entry?.[key], 0));
+		if (value > 0) return value;
+	}
+	return FALLBACK_CONTEXT_WINDOW;
+}
+/**
+* 读目录声明的单次输出上限，0 = 未声明。
+*
+* 这个数**只用于展示/投影**。descriptor 只在 >0 时声明 `maxTokens`（见模块头注
+* 第 2 条），所以它从不变成请求参数——它说的是平台至多能吐多少，让用户明白为什么
+* 长回答仍会以 `finish_reason: length` 停住。
+* @param {object} entry - 一条归一目录条目。
+* @returns {number} 声明的上限，未声明为 0。
+*/
+function maxOutputLengthOf(entry) {
+	for (const key of [
+		"max_output_length",
+		"maxOutputLength",
+		"max_output_tokens"
+	]) {
+		const value = Math.floor(num(entry?.[key], 0));
+		if (value > 0) return value;
+	}
+	return 0;
+}
+/**
+* 把一条目录条目映射成适配器交给 pi-ai 的 model descriptor。
+*
+* vision 用的是与快照/roster 完全相同的判定（`isVisionModel`），所以模型选择器
+* 不可能与面板的 vision 清单就「哪些模型能吃图」意见相反。
+* @param {object} entry - 一条归一目录条目（必须带 `id`）。
+* @param {object} [options] - 装配参数。
+* @param {string} [options.providerId] - 该 descriptor 所属的 provider id。
+* @param {string} [options.baseUrl] - OpenAI 兼容源站。
+* @returns {object} pi-ai descriptor。
+*/
+function toPiDescriptor(entry, options = {}) {
+	const { providerId = LLM_PROVIDER_ID, baseUrl } = options;
+	const id = str(entry?.id, "");
+	if (id === "") throw new Error("toPiDescriptor: catalog entry has no id");
+	const vision = isVisionModel(entry);
+	const maxOutputLength = maxOutputLengthOf(entry);
+	return {
+		id,
+		name: str(entry.name, id),
+		api: "openai-completions",
+		provider: providerId,
+		baseUrl,
+		input: vision ? ["text", "image"] : ["text"],
+		reasoning: false,
+		cost: { ...NO_COST },
+		contextWindow: contextWindowOf(entry),
+		...maxOutputLength > 0 ? { maxTokens: maxOutputLength } : {},
+		compat: {
+			maxTokensField: "max_tokens",
+			supportsDeveloperRole: false
+		}
+	};
+}
+/**
+* 允许清单的三态归一（§11 的 `allowed`）。
+*
+* 全插件只有这一处口径，快照（`snapshot-aggregate.ts`）与 provider 路由
+* （`routes/provider.ts`）都调它，杜绝两处各自写一套分类导致口径漂移：
+*
+*   - 空清单            → `"all"`（不过滤，提供全部模型）；
+*   - 含哨兵 `HIDE_ALL_MODELS` → `"none"`（什么都不提供）；
+*   - 其余非空清单      → `"list"`（严格白名单）。
+*
+* 空清单已经占用了「不过滤」，所以「什么都不提供」必须有第二种拼写——这正是
+* `HIDE_ALL_MODELS` 存在的原因。注意「含哨兵但还塞了别的 id」仍按 `"none"` 处理
+* （哨兵语义优先，与 `filterByEnabled` 的「匹配不到任何真实 id」完全一致）。
+* @param {string[]} enabledIds - 允许清单。
+* @returns {"all"|"none"|"list"}
+*/
+function resolveAllowedList(enabledIds) {
+	if (!Array.isArray(enabledIds) || enabledIds.length === 0) return "all";
+	if (enabledIds.includes("__hide_all__")) return "none";
+	return "list";
+}
+/**
+* 把目录缩到用户允许的模型子集。
+*
+* **空清单 = 不过滤**：新装没做过选择，仍应提供全部模型。一旦非空就是严格白
+* 名单；名单里点名了本目录没有的 id 也无害——它只是匹配不到东西。
+*
+* `HIDE_ALL_MODELS` 哨兵靠「匹配不到任何真实 id」表达「什么都不提供」，因为空
+* 清单已经被「不过滤」占用了。这里直接走 {@link resolveAllowedList} 的三态：
+* 含哨兵的清单属 `"none"`，过滤结果必然是空（哨兵不是真实 id），与
+* `isModelEnabled` 的口径一致（fix D）。
+* @param {object[]} entries - 归一目录条目。
+* @param {string[]} [enabledIds] - 允许清单；空/缺省关闭过滤。
+* @returns {object[]} 仍被提供的条目，按目录顺序。
+*/
+function filterByEnabled(entries, enabledIds) {
+	const list = Array.isArray(enabledIds) ? enabledIds : [];
+	if (list.length === 0) return Array.isArray(entries) ? entries : [];
+	const allow = new Set(list.map((id) => str(id, "")));
+	return (Array.isArray(entries) ? entries : []).filter((entry) => allow.has(str(entry?.id, "")));
+}
+/**
+* 为一份目录构建整份 descriptor 列表。
+*
+* 没有 id 的条目丢弃（线上没法寻址），重复 id 保留末次出现，与 `rosterOf` 的
+* 去重一致。`unavailableModelIds` 里的（额度耗尽的）模型丢弃——面板经
+* `rosterWithAvailability` 仍显示它们，灰显加原因，但 picker 不提供注定 429 的
+* 请求；两处口径不同是故意的，别统一。
+* @param {object[]} entries - 归一目录条目。
+* @param {object} options - `{ providerId, baseUrl, enabledIds, unavailableModelIds }`。
+* @returns {object[]} pi-ai descriptor，按首见顺序。
+*/
+function buildDescriptors(entries, options = {}) {
+	const { providerId = LLM_PROVIDER_ID, baseUrl, enabledIds = [], unavailableModelIds = [] } = options;
+	const filtered = filterByEnabled(entries, enabledIds).filter((entry) => isChatModel(entry));
+	const blocked = new Set(Array.isArray(unavailableModelIds) ? unavailableModelIds : []);
+	const seen = /* @__PURE__ */ new Map();
+	const out = [];
+	for (const entry of Array.isArray(filtered) ? filtered : []) {
+		if (entry === null || typeof entry !== "object" || Array.isArray(entry)) continue;
+		const catalogEntry = entry;
+		const id = str(catalogEntry.id, "");
+		if (id === "") continue;
+		if (blocked.has(id)) continue;
+		if (!seen.has(id)) {
+			seen.set(id, out.length);
+			out.push(void 0);
+		}
+		out[seen.get(id)] = toPiDescriptor({
+			...catalogEntry,
+			id
+		}, {
+			providerId,
+			...baseUrl !== void 0 ? { baseUrl } : {}
+		});
+	}
+	return out;
+}
+/**
+* 带额度可用性的面板 roster。
+*
+* 与 {@link rosterOf} 一样每 chat 模型 id 一行，但每行还带该模型额度池是否耗尽。
+* 与 **picker**（`buildDescriptors` 直接丢弃耗尽模型，避免发注定 429 的请求）不同，
+* 面板保留它们在清单里、灰显，让用户看得见「为什么模型从选择器里不见了」。
+* @param {object[]} entries - 归一目录条目。
+* @param {string[]} unavailableIds - 额度耗尽的模型 id；空数组 = 全部可用。
+* @returns {{id: string, name: string, vision: boolean, capability: ModelCapability, available: boolean, quotaExhausted: boolean, contextWindow: number, maxOutputLength: number}[]}
+*/
+function rosterWithAvailability(entries, unavailableIds) {
+	const blocked = new Set(Array.isArray(unavailableIds) ? unavailableIds : []);
+	const position = /* @__PURE__ */ new Map();
+	const out = [];
+	for (const entry of Array.isArray(entries) ? entries : []) {
+		if (!isChatModel(entry)) continue;
+		const id = str(entry?.id, "");
+		if (id === "") continue;
+		const row = {
+			id,
+			name: str(entry?.name, id),
+			vision: isVisionModel(entry),
+			capability: resolveModelCapability(entry),
+			available: !blocked.has(id),
+			quotaExhausted: blocked.has(id),
+			contextWindow: contextWindowOf(entry),
+			maxOutputLength: maxOutputLengthOf(entry)
+		};
+		if (position.has(id)) out[position.get(id)] = row;
+		else {
+			position.set(id, out.length);
+			out.push(row);
+		}
+	}
+	return out;
+}
+
+//#endregion
+//#region src/host/host-config.ts
+/**
+* 配置默认值。`CONFIG_DEFAULTS` 与 `cordis.patch.yml` 由 test/config.test.mjs
+* 双向钉住，代码与文档不会静默漂移。
+*
+* 这里**没有**额度常数（社区快照的「每日 N 次 / 单模型 N 次」）：官方改用
+* 「魔粒」计费后，面板头条是官方魔粒余额，次数口径的推算条已删除（见 README
+* 「三条事实」第2 条），而本插件的独家数据是分布 / 趋势 / 429 事件流——没有
+* 「上限」可与之相比。留着两个无人消费的常数只会在有人读配置时以为面板会拿它
+* 算「剩余次数」。真要加阈值提醒时，那应该是读官方余额的差值，不是这两个数。
+* @module dsh-connect-modelscope-token-plan/host-config
+*/
+/**
+* 本插件所有可寻址面的唯一 slug：/api 路由前缀、状态目录名、凭据记录命名
+* 空间都从它派生。改名必须连着用户已存的数据一起搬，不是改文本。
+* test/config.test.mjs 钉住 package.json#name 与 patch 行的 id/name 字面量。
+*/
+const name = "dsh-connect-modelscope-token-plan";
+/** Cordis 硬依赖：没有 webServer 本插件保持不活动。 */
+const inject = ["webServer"];
+/**
+* 快照里的插件版本。单一来源本可以是 package.json，但 lib 打包把它内联进
+* 产物反而引入第二份真源；这里用常量、由 test/config.test.mjs 钉住与
+* package.json 一致。
+*/
+const PLUGIN_VERSION = "0.1.0";
+/**
+* 默认值。刻意不含额度常数——理由见本文件头。
+* 面板头条是官方魔粒余额，次数口径的推算已在面板收敛时删除，这里若留着
+* dailyQuotaTotal 之类的社区快照，只会成为「看起来能算剩余次数」的假线索。
+*/
+const CONFIG_DEFAULTS = Object.freeze({
+	/** OpenAI 兼容推理源站（模型目录 + probe + provider 直连）。 */
+	apiBase: "https://api-inference.modelscope.cn/v1",
+	/** 站点源站，只用于面板外链（访问令牌页 / 文档）。 */
+	siteBase: "https://modelscope.cn",
+	/** 本地趋势保留天数（usage-store 天桶数量；超出即修剪）。 */
+	trendDays: 14,
+	/** Host 侧对 /v1/models 的缓存秒数。 */
+	cacheSeconds: 60,
+	/** 面板轮询间隔——由 Host 下发、面板跟随，两端不各自假设。 */
+	pollSeconds: 30,
+	/** 单次魔搭请求超时（毫秒）。 */
+	inferenceTimeoutMs: 3e4,
+	/** 事件流保留条数（429/错误事件的环形上限）。 */
+	maxEvents: 50,
+	/** provider 注册的 patch 默认值（面板保存值优先于它）。 */
+	registerProvider: false,
+	/** Host 应答的默认主机名；操作者的列表是「只增不替」。 */
+	admittedHosts: [
+		"localhost",
+		"127.0.0.1",
+		"[::1]",
+		"::1"
+	]
+});
+/** 把原始数值夹到有效整数（floor → 下限 → 上限；非正/非有限回退 def）。 */
+function clampInt(raw, def, min, max = Infinity) {
+	return Math.min(max, Math.max(min, Math.floor(num(raw, def))));
+}
+/**
+* 端点必须是合法的 http(s) 绝对地址；不是就在**挂载时**抛（resolveSettings
+* 捕获后转成 configError 经快照呈现），而不是等到第一次轮询才变成莫名其妙的
+* 网络失败。
+*/
+function assertHttpUrl(value, field) {
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		throw new Error(`${field} is not an absolute URL: ${JSON.stringify(value)}`);
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error(`${field} must be an http(s) URL, got ${parsed.protocol}`);
+}
+/**
+* 把 patch 行的原始配置解析成有效设置。
+*
+* 坏行不许从这里抛出去——apply 在挂载期跑，抛错等于整机插件消失。问题以
+* `configError` 返回，经快照路由呈现为一个能自我解释的面板。
+*/
+function resolveSettings(config) {
+	const source = obj(config);
+	try {
+		const apiBase = str(source.apiBase, CONFIG_DEFAULTS.apiBase).replace(/\/+$/, "");
+		const siteBase = str(source.siteBase, CONFIG_DEFAULTS.siteBase).replace(/\/+$/, "");
+		assertHttpUrl(apiBase, "apiBase");
+		assertHttpUrl(siteBase, "siteBase");
+		return {
+			settings: {
+				apiBase,
+				siteBase,
+				trendDays: clampInt(source.trendDays, CONFIG_DEFAULTS.trendDays, 1, 365),
+				cacheSeconds: clampInt(source.cacheSeconds, CONFIG_DEFAULTS.cacheSeconds, 5, 600),
+				pollSeconds: clampInt(source.pollSeconds, CONFIG_DEFAULTS.pollSeconds, 5, 3600),
+				inferenceTimeoutMs: clampInt(source.inferenceTimeoutMs, CONFIG_DEFAULTS.inferenceTimeoutMs, 1e3, 6e5),
+				maxEvents: clampInt(source.maxEvents, CONFIG_DEFAULTS.maxEvents, 1, 1e3),
+				registerProvider: source.registerProvider === true,
+				allowedHosts: resolveAllowedHosts(source)
+			},
+			configError: null
+		};
+	} catch (error) {
+		return {
+			settings: {
+				apiBase: CONFIG_DEFAULTS.apiBase,
+				siteBase: CONFIG_DEFAULTS.siteBase,
+				trendDays: CONFIG_DEFAULTS.trendDays,
+				cacheSeconds: CONFIG_DEFAULTS.cacheSeconds,
+				pollSeconds: CONFIG_DEFAULTS.pollSeconds,
+				inferenceTimeoutMs: CONFIG_DEFAULTS.inferenceTimeoutMs,
+				maxEvents: CONFIG_DEFAULTS.maxEvents,
+				registerProvider: false,
+				allowedHosts: new Set(CONFIG_DEFAULTS.admittedHosts)
+			},
+			configError: redactSecrets(errMsg(error))
+		};
+	}
+}
+/**
+* 收集本 Host 应答的主机名。操作者列表 **加** 到默认集上，绝不替换。
+*/
+function resolveAllowedHosts(source) {
+	const admitted = new Set(CONFIG_DEFAULTS.admittedHosts);
+	const extra = Array.isArray(source.allowedHosts) ? source.allowedHosts : [];
+	for (const entry of extra) {
+		const name = str(entry, "").trim().toLowerCase();
+		if (name !== "") admitted.add(name);
+	}
+	return admitted;
+}
+/**
+* 从 Host 头里剥端口；非法形状返回空串（被 {@link isAdmitted} 拒绝）。
+*
+* IPv6 字面量必须**整体**匹配 `[...]` 或 `[...]:port`：方括号闭合之后只允许空
+* 或 `:端口`，其余一律拒绝。曾经这里只「截断到第一个 `]` 就返回」，于是
+* `Host: [::1]evil.com` 读成 `[::1]` 并**通过**围栏——白名单是精确集合，前缀
+* 匹配等于把它放宽成「以白名单成员开头」。
+*/
+function hostName(host) {
+	if (host.startsWith("[")) {
+		const end = host.indexOf("]");
+		if (end < 0) return "";
+		const rest = host.slice(end + 1);
+		if (rest !== "" && !/^:\d{1,5}$/.test(rest)) return "";
+		return host.slice(0, end + 1);
+	}
+	if (host.includes("]")) return "";
+	const colons = host.split(":");
+	if (colons.length > 2) {
+		const penultimate = colons[colons.length - 2] ?? "";
+		const last = colons[colons.length - 1] ?? "";
+		if (/^\d+$/.test(penultimate) && /^\d+$/.test(last)) return host.slice(0, host.lastIndexOf(":"));
+		return host;
+	}
+	return colons.length > 1 ? host.slice(0, host.lastIndexOf(":")) : host;
+}
+/**
+* 路由的信任围栏。两攻击两事实：
+* 1. DNS rebinding——攻击页把域名 rebind 到 127.0.0.1，此时 Origin 与 Host
+*    互相一致，比较两者无意义；Host 头是浏览器唯一伪造不了的，对白名单查。
+* 2. 跨站伪造——Host 本来就合法，暴露它的是 Origin。
+* 所以：Host 必须在白名单内，且带 Origin 时必须与 Host 一致；无 Origin 的
+* 普通同源 GET 放行。围栏的边界是**浏览器**不是本机——本机进程两者都能伪造。
+*/
+function isAdmitted(request, allowedHosts) {
+	const host = str(request.headers?.host, "").toLowerCase();
+	if (host === "" || !allowedHosts.has(hostName(host))) return false;
+	const origin = request.headers?.origin;
+	if (typeof origin !== "string" || origin === "") return true;
+	if (origin === "null") return false;
+	try {
+		return new URL(origin).host === host;
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+export { redactSecrets as C, pluginError as S, verbatim as T, reclassifyStream as _, resolveSettings as a, obj as b, LLM_PROVIDER_ID as c, normalizeEntry as d, resolveAllowedList as f, looksLikeRateLimit as g, hasHardQuotaWordingIn as h, name as i, buildDescriptors as l, CODE as m, inject as n, LLM_API_KEY_NAME as o, rosterWithAvailability as p, isAdmitted as r, LLM_DISPLAY_NAME as s, PLUGIN_VERSION as t, isVisionModel as u, degrade as v, str as w, optional as x, errMsg as y };