dsh-connect-modelscope-token-plan 0.4.0 → 0.6.1

package/cordis.patch.yml

@@ -24,10 +24,25 @@
         # 删除——留着它们只会让人以为面板能算「还剩几次」，而它算不出。
         # 本地计数的独家价值在分布 / 趋势 / 429 事件流，不在「离上限多远」。
         # ------------------------------------------------------------------
-        # 本地趋势保留天数（插件私有状态文件里的天桶数量，与上游无关）。
+        # 趋势图显示天数（面板标题「近 N 天」与图上柱数）——面板里可改看多长。
         trendDays: 14
+        # 本地趋势**保留**天数（插件私有状态文件里的天桶数量，与上游无关）。
+        # 独立于 trendDays：显示只决定「画多少」，保留决定「留多少」。留得比画得多，
+        # 面板才可能让你把窗口调到更远。显示窗口恒被硬夹在保留之内。
+        retentionDays: 90
         # 429/错误事件环形缓冲的上限（面板只展示最近的）。上界 1000，硬夹。
         maxEvents: 50
+        # 单模型「额度耗尽」推断窗口（分钟）。官方只有账户级魔粒余额、没有
+        # per-model 额度端点，所以「哪个模型刚才在限频」从本插件的 429 事件流
+        # 推断（纯函数见 src/host/usage-store.ts 的 exhaustedModelIds）：某模型
+        # 最近在这个窗口内出现过 kind=quota 的事件（重分类后的口径——被误判成
+        # QUOTA 的 rpm 限频已在此之前纠正为 rate_limit，不算证据），选择器就不再
+        # 提供它、面板 roster 灰显；事件移出窗口即恢复。**恢复不可观测是已知
+        # 代价**：成功的调用不发事件，额度若在窗口内恢复（按天重置恰好如此），
+        # 模型最多灰显满一个窗口——方向保守（不提供注定 429 的模型），且灰显
+        # 带着原因。下界 5 分钟（再短规则形同虚设），上界 1440（一天，额度按天
+        # 重置，更长的窗口没有对应的恢复语义）。硬夹。
+        exhaustionWindowMinutes: 60
         # Host 侧对 /v1/models 的缓存秒数；面板脚注直接引用此值。上界 600。
         cacheSeconds: 60
         # 面板轮询间隔，由 Host 下发、面板跟随。上界 3600（1 小时）。
@@ -43,11 +58,12 @@
         # tab 的「接入为 DSH 模型」开关可随时翻转，面板保存值优先于这里的默认。
         # 注册后魔搭模型进入 DSH 模型选择器。
         #
-        # 计数范围：注册开关打开后，DSH 的魔搭对话经本插件的适配器出去，每一次
-        # 调用与每一条 429/错误事件都由 src/host/usage-observer.ts 在流的出口
-        # 记进同一个 usage-store——所以面板「额度」tab 的本地计数覆盖**全部 DSH
-        # 魔搭调用**，不只反映面板自身的探针。直连魔搭的其它客户端仍不计入
-        # （本插件看不见它们），消耗总量以官方魔粒余额为准。
+        # 计数范围：注册开关打开后，本客户端（本 profile）的魔搭对话经本插件的
+        # 适配器出去，每一次调用与每一条 429/错误事件都由 src/host/usage-observer.ts
+        # 在流的出口记进同一个 usage-store。口径是**本客户端**：桌面端与 Web 端是
+        # 两个 profile，各记各的账、互不可见（`npm run doctor` 并排列出各 profile），
+        # 别把它当跨端总量。直连魔搭的其它客户端同样不计入（本插件看不见它们），
+        # 消耗总量以官方魔粒余额为准。
         #
         # 偏差方向是**按流计次**：重试不在流内部发生，而是流被消费完后由
         # agent/request-error 瀑布决定重发，因而每次重试各记一次（按「魔搭按
@@ -55,6 +71,25 @@
         # 与 README「诚实声明」。
         registerProvider: false
         # ------------------------------------------------------------------
+        # 逐模型的单次输出上限覆盖（模型 id → tokens）。空对象 = 目录说了算。
+        #
+        # **为什么必须有它**：本插件对输出上限的策略是「目录声明了才声明」，而魔搭
+        # `/v1/models` **从不返回**这个字段（实测每条只有 id / object / owned_by /
+        # created，见 docs/REFERENCES.md）。两条合起来 = **每一个**模型的 descriptor
+        # 都不带 maxTokens，harness 于是用它的 `defaultMaxTokens ?? 32768` 兜底：
+        # 32768 既不是魔搭声明的数，也不是实测过的数，它只是 harness 的缺省值。
+        # 目录给不出真值时，只有操作者知道某个模型实测能吐多少——没有这个字段，
+        # 那份知识无处可写（写进目录缓存会被下一轮轮询覆盖）。
+        #
+        # 优先级 `覆盖 > 目录声明 > 不声明`。键是**精确模型 id**，不做子串匹配——
+        # 上限是请求参数，宽松的键会顺手改掉一批没被点名的模型（键写 flash 会命中
+        # 七八条）；值必须是正整数（0 = 未声明；非法值丢弃而不是夹取）。
+        # 面板模型清单行会用「最大输出」徽章显示生效值，来源是覆盖还是目录一目了然。
+        #
+        # 例（把下面这行整行复制出去、去掉 `#` 即可）：
+        # maxTokensOverrides: { "deepseek-ai/DeepSeek-V4.1-Flash": 65536 }
+        maxTokensOverrides: {}
+        # ------------------------------------------------------------------
         # 给 agent 注册出图工具（`modelscope_draw_image`）。**与上面的
         # registerProvider 是两条独立开关**：那个管「魔搭作为 chat provider」，
         # 这个管「agent 能不能出图」。默认同样关（opt-in）。
@@ -77,13 +112,14 @@
         # 没有任何 text-to-image。官方示例里的 Qwen/Qwen-Image-2.1-Turbo 与
         # black-forest-labs/FLUX.1-Kontext-dev **都不在目录内**，后者实测 FAILED。
         drawModelId: ""
-        # 单次出图总预算（毫秒），含提交与全部轮询。上界 900000（15 分钟）。
-        # 别调小：实测最慢一次 859s 才成功，而超时放弃**不等于**任务死亡
-        # （上游会继续跑），把预算压到 5 分钟曾实测击穿。
+        # 单次出图总预算（毫秒），含提交与全部轮询。上界 1800000（30 分钟），
+        # 严格高于这个默认值——它**不是**上限。别调小：实测最慢一次 859s 才成功，
+        # 而超时放弃**不等于**任务死亡（上游会继续跑），把预算压到 5 分钟曾实测击穿。
         drawTimeoutMs: 900000
         # 单次出图**工具调用**愿意等的时间（毫秒）。与上面那条是两件事：那是
         # 「这张图值不值得继续等」的总放弃线，这是「一轮对话被占住多久」。
         # 等不到就返回 pending + jobId，agent 带 jobId 再调用即可续查。
+        # 实际取值夹在 10s 与上面那条 drawTimeoutMs 之间（等待超过总放弃线没有意义）。
         drawWaitMs: 90000
         # 追加可信 Host 名（默认 localhost / 127.0.0.1 / ::1，只增不替）。
         # allowedHosts: []

package/lib/host-config.js

@@ -375,9 +375,12 @@ function enabledCountOf(list, rosterIds) {
 * 1. `compat.supportsDeveloperRole: false`——pi-ai 缺省会**自动探测**这个标志，
 *    对非标准 provider 一律猜 `true`，于是每条请求都用 `developer` 角色，魔搭这个
 *    多模型代理不认识，会 400 或 403。qoder 路由证明必须显式写 false。
-* 2. `maxTokens` 只在目录**声明了**上限时声明——harness 对未声明的 maxTokens
-*    用 `defaultMaxTokens ?? 32768` 兜底，所以「不声明」是「平台没说」的诚实处理，
-*    别猜数字填。
+* 2. `maxTokens` 由 `maxTokensFor` 一处决定，优先级 **`覆盖 > 目录声明 > 不声明`**：
+*    目录没声明时不猜数字（harness 会用它的 `defaultMaxTokens ?? 32768` 兜底，那是
+*    harness 的默认值，不是平台说的），但操作者可以在 `maxTokensOverrides` 里显式
+*    填实测值。**本插件的目录（魔搭 `/v1/models`）从不返回这个字段**，所以「目录
+*    说了算」在现实里等于「永远是 32768」——这条退路不是锦上添花，它是唯一出口。
+*    完整回退顺序写在 `maxTokensFor` 上，此处不重复。
 * 3. `reasoning: false` + **不设** `thinkingLevelMap`——魔搭 API-Inference 是
 *    多模型代理，是否吃 `reasoning_effort` 取决于背后那个具体模型，本插件无法
 *    离线得知每个 id 的档位表（sensenova 那份是拿真令牌逐模型探测才钉出来的）。
@@ -482,6 +485,22 @@ const KNOWN_VISION_IDS = Object.freeze(/* @__PURE__ */ new Set([
 	"stepfun-ai/Step-3.7-Flash"
 ]));
 /**
+* 已知能**纯文生图**的目录内模型 id（2026-10-16 真机复核）。
+*
+* 为什么需要手工策展：api-inference 目录里至今**没有**平台声明的 `text-to-image`
+* 条目，只有 2 条 `image-to-image`——而两者行为**不同**：
+* `Qwen/Qwen-Image-Edit` 不带 `image_url` 纯文生图可用（本轮实测：提交成功、两次
+* 15min 排队超时后于 9.7min 出图）；`MusePublic/Qwen-Image-Edit` 纯文生图被上游
+* 直接拒绝（提交阶段 HTTP 4xx：`image_url is required for model: …`）。
+* 能力枚举把两者都归为 `image-to-image`，区分不了这个差异，所以这里用实测知识兜底：
+* 目录里没有 `text-to-image` 可挑时，默认偏向这个已知能用的 id，而不是「目录第一个」
+* （真实目录顺序 `MusePublic/…` 在前，照旧逻辑纯文生图必挂）。
+*
+* 与 `KNOWN_VISION_IDS` 放在一起：所有「哪些模型能做什么」的策展知识集中一处，
+* 不会漂。
+*/
+const KNOWN_T2I_MODEL_ID = "Qwen/Qwen-Image-Edit";
+/**
 * 把原始 `/v1/models` data 条目变成归一目录条目。
 *
 * 只做投影与回退，不做判断：`id` 必取，`name` 回退 id，`vision`/`contextWindow`/
@@ -669,9 +688,11 @@ function contextWindowSourceOf(entry) {
 /**
 * 读目录声明的单次输出上限，0 = 未声明。
 *
-* 这个数**只用于展示/投影**。descriptor 只在 >0 时声明 `maxTokens`（见模块头注
-* 第 2 条），所以它从不变成请求参数——它说的是平台至多能吐多少，让用户明白为什么
-* 长回答仍会以 `finish_reason: length` 停住。
+* 这个数**是请求参数**，不是纯展示值：`toPiDescriptor` 在它 >0 时声明为
+* `maxTokens`（见模块头注第 2 条）。**但 `0` 有真实的代价**——魔搭目录从不返回
+* 这个字段，所以它对本插件的每一个模型都是 0，harness 于是用 `defaultMaxTokens ??
+* 32768` 兜底。「目录没说」在这里不等于「平台没限制」，只等于**我们不知道**；把它
+* 当「不设上限」读会错得很远。操作者知道时用 `maxTokensFor` 的覆盖参数补上。
 * @param {object} entry - 一条归一目录条目。
 * @returns {number} 声明的上限，未声明为 0。
 */
@@ -687,6 +708,50 @@ function maxOutputLengthOf(entry) {
 	return 0;
 }
 /**
+* 该条目**实际生效**的输出上限：`覆盖 > 目录声明 > 不声明(0)`——全插件唯一的
+* 回退顺序，写在这里就只写一遍。
+*
+* 为什么覆盖必须排在目录**之前**（而不是「目录优先、覆盖只补空缺」）：目录说的是
+* 「这个平台声称能吐多少」，覆盖说的是「我实测过这个模型能吐多少」。两者冲突时后者
+* 是更新的事实——目录是我们**抓来的**（`/v1/models`，会随上游改动、也可能常年不
+* 更新），覆盖是操作者**写的**。魔搭这条路上目录连这个字段都不返回，所以顺序在
+* 多数情况下没有争议；把它写死仍然重要，因为「谁赢」这件事只能有一个答案。
+*
+* 返回 0 的含义与 `maxOutputLengthOf` 完全一致：**不声明** `maxTokens`，让 harness
+* 用它的兜底值——不是「上限为 0」。`0` 因此不是一个可以配置的上限（
+* `resolveMaxTokensOverrides` 会把 0 丢掉）。
+* @param {object} entry - 一条归一目录条目。
+* @param {object|null} [overrides] - 归一后的 id → 上限映射（`ResolvedSettings`）。
+* @returns {number} 生效上限，未声明为 0。
+*/
+function maxTokensFor(entry, overrides) {
+	const declared = maxOutputLengthOf(entry);
+	if (overrides === void 0 || overrides === null) return declared;
+	const id = str(entry?.id, "");
+	if (id === "") return declared;
+	const override = overrides[id];
+	return typeof override === "number" && Number.isInteger(override) && override > 0 ? override : declared;
+}
+/**
+* 这个条目的输出上限数字从真值链哪一级来——与 {@link maxTokensFor} 配对的来源标记，
+* 形状与 {@link contextWindowSourceOf} 刻意保持同一套词汇。
+*
+* 只有两级，因为这里**没有策展表**：窗口有 `context-catalog.ts` 那份实测策展表，
+* 输出上限没有（魔搭从不声明它，策展一张「猜每个模型能吐多少」的表没有依据）。
+* `catalog` 的含义因此是「覆盖没命中」——包括目录没声明、值就是 0 的情况，面板据此
+* 不画徽章。
+* @param {object} entry - 一条归一目录条目。
+* @param {object|null} [overrides] - 归一后的 id → 上限映射。
+* @returns {"catalog"|"override"} 来源标记。
+*/
+function maxTokensSourceOf(entry, overrides) {
+	if (overrides === void 0 || overrides === null) return "catalog";
+	const id = str(entry?.id, "");
+	if (id === "") return "catalog";
+	const override = overrides[id];
+	return typeof override === "number" && Number.isInteger(override) && override > 0 ? "override" : "catalog";
+}
+/**
 * 把一条目录条目映射成适配器交给 pi-ai 的 model descriptor。
 *
 * vision 用的是与快照/roster 完全相同的判定（`isVisionModel`），所以模型选择器
@@ -695,14 +760,17 @@ function maxOutputLengthOf(entry) {
 * @param {object} [options] - 装配参数。
 * @param {string} [options.providerId] - 该 descriptor 所属的 provider id。
 * @param {string} [options.baseUrl] - OpenAI 兼容源站。
+* @param {object} [options.maxTokensOverrides] - 逐模型输出上限覆盖（id → tokens），
+*   经 `maxTokensFor` 决定 `maxTokens`。缺省 = 目录说了算（对本插件的目录即「不声
+*   明」）。
 * @returns {object} pi-ai descriptor。
 */
 function toPiDescriptor(entry, options = {}) {
-	const { providerId = LLM_PROVIDER_ID, baseUrl } = options;
+	const { providerId = LLM_PROVIDER_ID, baseUrl, maxTokensOverrides } = 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);
+	const effectiveMaxTokens = maxTokensFor(entry, maxTokensOverrides);
 	return {
 		id,
 		name: str(entry.name, id),
@@ -713,7 +781,7 @@ function toPiDescriptor(entry, options = {}) {
 		reasoning: false,
 		cost: { ...NO_COST },
 		contextWindow: contextWindowOf(entry),
-		...maxOutputLength > 0 ? { maxTokens: maxOutputLength } : {},
+		...effectiveMaxTokens > 0 ? { maxTokens: effectiveMaxTokens } : {},
 		compat: {
 			maxTokensField: "max_tokens",
 			supportsDeveloperRole: false
@@ -794,11 +862,11 @@ function buildRosterRows(entries, project) {
 * `rosterWithAvailability` 仍显示它们，灰显加原因，但 picker 不提供注定 429 的
 * 请求；两处口径不同是故意的，别统一。
 * @param {object[]} entries - 归一目录条目。
-* @param {object} options - `{ providerId, baseUrl, enabledIds, unavailableModelIds }`。
+* @param {object} options - `{ providerId, baseUrl, enabledIds, unavailableModelIds, maxTokensOverrides }`。
 * @returns {object[]} pi-ai descriptor，按首见顺序。
 */
 function buildDescriptors(entries, options = {}) {
-	const { providerId = LLM_PROVIDER_ID, baseUrl, enabledIds = [], unavailableModelIds = [] } = options;
+	const { providerId = LLM_PROVIDER_ID, baseUrl, enabledIds = [], unavailableModelIds = [], maxTokensOverrides } = options;
 	const filtered = filterByEnabled(entries, enabledIds).filter((entry) => isChatModel(entry));
 	const blocked = new Set(Array.isArray(unavailableModelIds) ? unavailableModelIds : []);
 	const seen = /* @__PURE__ */ new Map();
@@ -818,7 +886,8 @@ function buildDescriptors(entries, options = {}) {
 			id
 		}, {
 			providerId,
-			...baseUrl !== void 0 ? { baseUrl } : {}
+			...baseUrl !== void 0 ? { baseUrl } : {},
+			...maxTokensOverrides !== void 0 ? { maxTokensOverrides } : {}
 		});
 	}
 	return out;
@@ -899,6 +968,85 @@ function textToImageModelIds(entries) {
 	return idsOf(entries, (entry) => resolveModelCapability(entry) === "text-to-image");
 }
 /**
+* 一份目录里的出图候选，按首见顺序去重，带能力档与纯文生图标记。
+*
+* 与 {@link imageGenModelIds} 同一份判定（只认平台声明的出图能力），只是把
+* `reference` 需要的两个附加位一起投出来——面板的每一行徽章与「当前使用」都从
+* 这里派生，不各自再判一次。
+* @param {unknown} entries - 归一目录条目。
+* @returns {DrawCandidate[]} 出图候选。
+*/
+function drawCandidates(entries) {
+	const position = /* @__PURE__ */ new Map();
+	const out = [];
+	for (const entry of Array.isArray(entries) ? entries : []) {
+		if (entry === null || typeof entry !== "object" || Array.isArray(entry)) continue;
+		const e = entry;
+		if (!isImageGenModel(e)) continue;
+		const id = str(e.id, "");
+		if (id === "") continue;
+		const capability = resolveModelCapability(e);
+		const row = {
+			id,
+			capability: capability === "text-to-image" ? "text-to-image" : capability === "image-to-image" ? "image-to-image" : "other",
+			textToImage: capability === "text-to-image" || id === "Qwen/Qwen-Image-Edit"
+		};
+		const seen = position.get(id);
+		if (seen === void 0) {
+			position.set(id, out.length);
+			out.push(row);
+		} else out[seen] = row;
+	}
+	return out;
+}
+/**
+* 从目录里挑一个出图模型，并说明**为什么是它**。
+*
+* 优先级（高 → 低），与 `draw-runtime.ts` 的 `pickDrawModel` 同一份：
+* 1. `requested` —— 工具调用里显式给的 model（这里不投理由，调用方场景）；
+* 2. `preferred` —— 面板保存 / 配置 `drawModelId`；用户点了谁就是谁，不校验在不在目录；
+* 3. 平台声明为 `text-to-image` 的条目（将来目录补上真文生图模型时自动优先）；
+* 4. 已知能纯文生图的 `KNOWN_T2I_MODEL_ID`（今天目录的坑位）；
+* 5. 目录里第一个出图模型。
+*
+* `requested` 会以 `preferred` 的理由返回——它同样是「有人指定了」，面板不需要
+* 为一次工具调用区分这两者。
+* @param {unknown} entries - 归一目录条目。
+* @param {string} [requested] - 工具调用显式指定的 id。
+* @param {string} [preferred] - 面板/配置的默认 id。
+* @returns {DrawModelChoice} 选中的 id 与理由。
+*/
+function resolveDrawModelChoice(entries, requested, preferred) {
+	const want = str(requested, "");
+	if (want !== "") return {
+		id: want,
+		source: "preferred"
+	};
+	const preferredId = str(preferred, "");
+	if (preferredId !== "") return {
+		id: preferredId,
+		source: "preferred"
+	};
+	const ids = imageGenModelIds(entries);
+	if (ids.length === 0) return {
+		id: null,
+		source: null
+	};
+	const t2i = textToImageModelIds(entries);
+	if (t2i.length > 0) return {
+		id: t2i[0] ?? null,
+		source: "declared-text-to-image"
+	};
+	if (ids.includes("Qwen/Qwen-Image-Edit")) return {
+		id: KNOWN_T2I_MODEL_ID,
+		source: "known-text-to-image"
+	};
+	return {
+		id: ids[0] ?? null,
+		source: "catalog-first"
+	};
+}
+/**
 * 带额度可用性的面板 roster。
 *
 * 与 {@link rosterOf} 一样每 chat 模型 id 一行，但每行还带该模型额度池是否耗尽。
@@ -906,9 +1054,14 @@ function textToImageModelIds(entries) {
 * 面板保留它们在清单里、灰显，让用户看得见「为什么模型从选择器里不见了」。
 * @param {object[]} entries - 归一目录条目。
 * @param {string[]} unavailableIds - 额度耗尽的模型 id；空数组 = 全部可用。
-* @returns {{id: string, name: string, vision: boolean, capability: ModelCapability, available: boolean, quotaExhausted: boolean, contextWindow: number, maxOutputLength: number}[]}
+* @param {object} [maxTokensOverrides] - 逐模型输出上限覆盖（id → tokens）。**位置参数
+*   而非 options 对象**：本函数的既有调用面就是两个位置参数，第三个在三个调用点都是
+*   一次机械追加；改成对象会动三处签名与它们各自的测试假件，收益只是好看。窗口那边
+*   （`contextSource`）**不**走这个参数——它在 fetchModels 归一时就被打标了，两条路
+*   的机制不同，这里不假装统一。
+* @returns {{id: string, name: string, vision: boolean, capability: ModelCapability, available: boolean, quotaExhausted: boolean, contextWindow: number, contextSource: "catalog"|"override"|"curated", maxOutputLength: number, maxOutputSource: "catalog"|"override"}[]}
 */
-function rosterWithAvailability(entries, unavailableIds) {
+function rosterWithAvailability(entries, unavailableIds, maxTokensOverrides) {
 	const blocked = new Set(Array.isArray(unavailableIds) ? unavailableIds : []);
 	return buildRosterRows(entries, (entry, id) => ({
 		id,
@@ -919,7 +1072,8 @@ function rosterWithAvailability(entries, unavailableIds) {
 		quotaExhausted: blocked.has(id),
 		contextWindow: contextWindowOf(entry),
 		contextSource: contextWindowSourceOf(entry),
-		maxOutputLength: maxOutputLengthOf(entry)
+		maxOutputLength: maxTokensFor(entry, maxTokensOverrides),
+		maxOutputSource: maxTokensSourceOf(entry, maxTokensOverrides)
 	}));
 }
 
@@ -949,7 +1103,7 @@ const inject = ["webServer"];
 * 产物反而引入第二份真源；这里用常量、由 test/config.test.mjs 钉住与
 * package.json 一致。
 */
-const PLUGIN_VERSION = "0.4.0";
+const PLUGIN_VERSION = "0.6.1";
 /**
 * 默认值。刻意不含额度常数——理由见本文件头。
 * 面板头条是官方魔粒余额，次数口径的推算已在面板收敛时删除，这里若留着
@@ -960,8 +1114,23 @@ const CONFIG_DEFAULTS = Object.freeze({
 	apiBase: "https://api-inference.modelscope.cn/v1",
 	/** 站点源站，只用于面板外链（访问令牌页 / 文档）。 */
 	siteBase: "https://modelscope.cn",
-	/** 本地趋势保留天数（usage-store 天桶数量；超出即修剪）。 */
+	/**
+	* 趋势图**显示**天数（面板标题「近 N 天」与图上柱数）——默认值，用户可在面板里
+	* 改看多长。
+	*
+	* **与 retentionDays 是两件事**（2026-10-17 拆开）：这个数只决定「画多少」，
+	* 不再决定「留多少」。曾经一个 trendDays 同时是保留窗口，于是「想多看几天」等于
+	* 「改保留策略」，改小还会把历史当场剪掉——拆开正是为了消除这层耦合。
+	*/
 	trendDays: 14,
+	/**
+	* 本地趋势**保留**天数（usage-store 天桶的修剪窗口；超出即删）。
+	*
+	* 取 90：够回看一个季度，而每个天桶只是两个整数——留 90 天的磁盘代价可忽略。
+	* 显示窗口恒被夹在它之内（见 resolveSettings），所以「画得比留得多」这个会把
+	* 已剪的日子画成 0（与「那天真的没调用」在面板上无法区分）的组合不会出现。
+	*/
+	retentionDays: 90,
 	/** Host 侧对 /v1/models 的缓存秒数。 */
 	cacheSeconds: 60,
 	/** 面板轮询间隔——由 Host 下发、面板跟随，两端不各自假设。 */
@@ -970,9 +1139,55 @@ const CONFIG_DEFAULTS = Object.freeze({
 	inferenceTimeoutMs: 3e4,
 	/** 事件流保留条数（429/错误事件的环形上限）。 */
 	maxEvents: 50,
+	/**
+	* 单模型「额度耗尽」的推断窗口（分钟）。
+	*
+	* 官方只给**账户级**魔粒余额，没有 per-model 额度端点，所以「哪个模型刚才在
+	* 限频」只能从本插件的 429 事件流推断（规则是纯函数 `exhaustedModelIds`，
+	* usage-store.ts）：某模型最近在这个窗口内出现过 `kind:"quota"` 事件
+	* （重分类后的 code，见 llm-error-fix），picker 就不再提供它、面板 roster
+	* 灰显；事件移出窗口即恢复提供。
+	*
+	* 取 60 分钟：覆盖一次「耗尽 → 用户看到 → 换模型」的合理观察期，又不至于让
+	* 一次深夜的耗尽事件把模型关一整天。**恢复不可观测是这条规则已知的代价**：
+	* 成功的流不发事件，所以额度若在窗口内恢复（按天重置恰好在窗口内发生），
+	* 模型最多灰显满一个窗口——方向是保守的（宁可少提供一会，不提供注定 429
+	* 的模型），且面板灰显上写着原因，不是静默消失。
+	*/
+	exhaustionWindowMinutes: 60,
 	/** provider 注册的 patch 默认值（面板保存值优先于它）。 */
 	registerProvider: false,
 	/**
+	* 逐模型的单次输出上限覆盖（模型 id → tokens），空对象 = 目录说了算。
+	*
+	* **为什么需要它**：本插件对输出上限的原始策略是「目录声明了才声明」
+	* （llm-models.ts 模块头注第 2 条），而魔搭 `/v1/models` **从不返回**这个字段
+	* （docs/REFERENCES.md 实测：每条只有 `id`/`object`/`owned_by`/`created`）。
+	* 两条合起来的结果是**每一个**模型的 descriptor 都不带 `maxTokens`，harness 于是
+	* 走它的 `defaultMaxTokens ?? 32768` 兜底——32768 不是魔搭声明的数，也不是任何
+	* 实测过的数，它只是 harness 的默认值。
+	*
+	* 目录给不出真值时，操作者是唯一的信息源：他知道某个模型实测能吐 64k。没有这个
+	* 字段，这份知识**无处可写**——写进目录缓存会被下一轮轮询覆盖。于是他只能看着
+	* 输出在 32768 处被截断，而手上明明有答案。
+	*
+	* **语义与优先级**：`覆盖 > 目录声明 > 不声明`。目录声明了时覆盖仍然赢（这是
+	* 「覆盖」二字的全部含义）；目录没声明时覆盖就是唯一的真值来源。空对象（默认）
+	* ＝ 完全维持旧行为，不改变任何已有部署的输出。
+	*
+	* **键是精确 id，不做子串匹配**——与 sensenova 那种「按名字包含」的倍率旋钮
+	* 刻意不同：上限是**请求参数**，一个宽松的键会顺手改掉一批没被点名的模型
+	* （键写 `flash` 会命中七八条）。只认整串相等。
+	*
+	* **值必须是正整数**：0 有保留含义（`maxOutputLengthOf` 里 0 = 未声明），所以
+	* 非法值一律**丢弃**（非整数 / NaN / Infinity / 字符串数字 / 0 / 负数），不是夹取
+	* ——夹取等于替用户声明一个他没说过的上限。
+	*
+	* 读取点只有一处：`llm-models.ts` 的 `maxTokensFor`。descriptor 构建与面板 roster
+	* **都**调它，所以面板显示的数字与线上真正发的 `max_tokens` 不可能不一致。
+	*/
+	maxTokensOverrides: {},
+	/**
 	* 出图工具的 patch 默认值（面板保存值优先于它）。
 	*
 	* **与 `registerProvider` 是两个独立开关**：前者是「把魔搭当 chat provider」，
@@ -995,6 +1210,10 @@ const CONFIG_DEFAULTS = Object.freeze({
 	* 取 15 分钟：覆盖已观测到的最慢一次（537s）并留一倍余量。**注意超时放弃不等于
 	* 任务死亡**——上游任务会继续跑（且记录最终会被回收，见 docs/SPIKE-image-gen.md
 	* §坑 5）。宁可多等，不要把一张已经在生成的图扔掉。
+	*
+	* 「15 分钟够不够」我们**没有把握**（上面的实测还在恶化），所以夹取的上界
+	* `DRAW_TIMEOUT_MAX_MS` 取 30 分钟，严格高于本默认值——觉得不够就往上调，
+	* 别把它当上限用。
 	*/
 	drawTimeoutMs: 9e5,
 	/**
@@ -1023,6 +1242,20 @@ function clampInt(raw, def, min, max = Infinity) {
 	return Math.min(max, Math.max(min, Math.floor(num(raw, def))));
 }
 /**
+* `drawTimeoutMs` 的**上界**——必须严格大于它的默认值。
+*
+* 这个上界曾经与默认值同为 900_000，于是该字段只能调小、不能调大。而「15 分钟
+* 够不够」恰恰是本文件自己承认**没有把握**的问题：上面的注释记着同模型连测
+* 61s→261s→**537s** 的单调恶化、5 分钟预算被实测击穿，docs/SPIKE-image-gen.md
+* 还记着一次 900s 预算的 e2e 在 905s 放弃。把一个**已知可能不够用**的数值同时
+* 写成默认值与硬上限，等于在用户最需要「多等一会儿」的时刻把旋钮焊死——而且
+* 焊死在一个已被实测证伪的数上。
+*
+* 取 30 分钟：仍是有界的（不会让一次工具调用无限期挂着），但比默认值高出一倍，
+* 慢档用户有可调空间。它同时是 `drawWaitMs` 的上界来源（见 resolveSettings）。
+*/
+const DRAW_TIMEOUT_MAX_MS = 18e5;
+/**
 * 端点必须是合法的 http(s) 绝对地址；不是就在**挂载时**抛（resolveSettings
 * 捕获后转成 configError 经快照呈现），而不是等到第一次轮询才变成莫名其妙的
 * 网络失败。
@@ -1037,6 +1270,32 @@ function assertHttpUrl(value, field) {
 	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error(`${field} must be an http(s) URL, got ${parsed.protocol}`);
 }
 /**
+* 归一「逐模型输出上限覆盖」。
+*
+* 三个刻意的选择，都与姊妹插件的同类函数不同：
+*
+* 1. **键精确相等**，不做子串匹配。上限是请求参数，宽松匹配会改掉一批没被点名的
+*    模型；倍率那种「按名字包含」的旋钮可以宽松，因为它只影响画图。
+* 2. **值必须是正整数**，非法值**丢弃**而不是夹取。0 在 `maxOutputLengthOf` 里已经
+*    表示「未声明」，把 `-5` 夹成 1 等于替用户声明了一个他没说过的上限；丢弃则
+*    退回目录/兜底，方向是保守的。
+* 3. **非对象一律回落到默认空对象**，不抛错——坏配置不能让 apply 抛出去（本文件的
+*    既有纪律，见 resolveSettings 的 catch 分支）。
+* @param {unknown} raw - patch 行里的原始值（加载器送来的未校验输入）。
+* @returns {Record<string, number>} id → 上限，只含合法项。
+*/
+function resolveMaxTokensOverrides(raw) {
+	if (raw === void 0 || raw === null) return CONFIG_DEFAULTS.maxTokensOverrides;
+	if (typeof raw !== "object" || Array.isArray(raw)) return { ...CONFIG_DEFAULTS.maxTokensOverrides };
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) {
+		if (key === "") continue;
+		if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) continue;
+		out[key] = value;
+	}
+	return out;
+}
+/**
 * 把 patch 行的原始配置解析成有效设置。
 *
 * 坏行不许从这里抛出去——apply 在挂载期跑，抛错等于整机插件消失。问题以
@@ -1049,20 +1308,25 @@ function resolveSettings(config) {
 		const siteBase = str(source.siteBase, CONFIG_DEFAULTS.siteBase).replace(/\/+$/, "");
 		assertHttpUrl(apiBase, "apiBase");
 		assertHttpUrl(siteBase, "siteBase");
+		const drawTimeoutMs = clampInt(source.drawTimeoutMs, CONFIG_DEFAULTS.drawTimeoutMs, 3e4, DRAW_TIMEOUT_MAX_MS);
+		const retentionDays = clampInt(source.retentionDays, CONFIG_DEFAULTS.retentionDays, 1, 365);
 		return {
 			settings: {
 				apiBase,
 				siteBase,
-				trendDays: clampInt(source.trendDays, CONFIG_DEFAULTS.trendDays, 1, 365),
+				trendDays: clampInt(source.trendDays, CONFIG_DEFAULTS.trendDays, 1, retentionDays),
+				retentionDays,
 				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),
+				exhaustionWindowMinutes: clampInt(source.exhaustionWindowMinutes, CONFIG_DEFAULTS.exhaustionWindowMinutes, 5, 1440),
 				registerProvider: source.registerProvider === true,
+				maxTokensOverrides: resolveMaxTokensOverrides(source.maxTokensOverrides),
 				drawEnabled: source.drawEnabled === true,
 				drawModelId: str(source.drawModelId, CONFIG_DEFAULTS.drawModelId),
-				drawTimeoutMs: clampInt(source.drawTimeoutMs, CONFIG_DEFAULTS.drawTimeoutMs, 3e4, 9e5),
-				drawWaitMs: clampInt(source.drawWaitMs, CONFIG_DEFAULTS.drawWaitMs, 1e4, 9e5),
+				drawTimeoutMs,
+				drawWaitMs: clampInt(source.drawWaitMs, CONFIG_DEFAULTS.drawWaitMs, 1e4, drawTimeoutMs),
 				allowedHosts: resolveAllowedHosts(source)
 			},
 			configError: null
@@ -1073,11 +1337,14 @@ function resolveSettings(config) {
 				apiBase: CONFIG_DEFAULTS.apiBase,
 				siteBase: CONFIG_DEFAULTS.siteBase,
 				trendDays: CONFIG_DEFAULTS.trendDays,
+				retentionDays: CONFIG_DEFAULTS.retentionDays,
 				cacheSeconds: CONFIG_DEFAULTS.cacheSeconds,
 				pollSeconds: CONFIG_DEFAULTS.pollSeconds,
 				inferenceTimeoutMs: CONFIG_DEFAULTS.inferenceTimeoutMs,
 				maxEvents: CONFIG_DEFAULTS.maxEvents,
+				exhaustionWindowMinutes: CONFIG_DEFAULTS.exhaustionWindowMinutes,
 				registerProvider: false,
+				maxTokensOverrides: CONFIG_DEFAULTS.maxTokensOverrides,
 				drawEnabled: false,
 				drawModelId: CONFIG_DEFAULTS.drawModelId,
 				drawTimeoutMs: CONFIG_DEFAULTS.drawTimeoutMs,
@@ -1148,4 +1415,4 @@ function isAdmitted(request, allowedHosts) {
 }
 
 //#endregion
-export { obj as C, str as D, redactSecrets as E, verbatim as O, errMsg as S, pluginError as T, CODE as _, resolveSettings as a, reclassifyStream as b, LLM_PROVIDER_ID as c, isVisionModel as d, normalizeEntry as f, parseAllowedList as g, enabledCountOf as h, name as i, buildDescriptors as l, textToImageModelIds 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, imageGenModelIds as u, hasHardQuotaWordingIn as v, optional as w, degrade as x, looksLikeRateLimit as y };
+export { errMsg as C, redactSecrets as D, pluginError as E, str as O, degrade as S, optional as T, parseAllowedList as _, resolveSettings as a, looksLikeRateLimit as b, LLM_PROVIDER_ID as c, imageGenModelIds as d, isVisionModel as f, enabledCountOf as g, rosterWithAvailability as h, name as i, verbatim as k, buildDescriptors as l, resolveDrawModelChoice as m, inject as n, LLM_API_KEY_NAME as o, normalizeEntry as p, isAdmitted as r, LLM_DISPLAY_NAME as s, PLUGIN_VERSION as t, drawCandidates as u, CODE as v, obj as w, reclassifyStream as x, hasHardQuotaWordingIn as y };