dsh-connect-modelscope-token-plan 0.5.0 → 0.6.2

package/client.js

@@ -136,7 +136,7 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 	var zh, en;
 	var init_i18n = __esmMin((() => {
 		zh = {
-			"panel.title": "魔搭接入 · 额度面板",
+			"panel.title": "魔搭模型接入",
 			"panel.refresh": "刷新",
 			"panel.updated": "更新于 {time}",
 			"panel.loading": "加载中…",
@@ -212,6 +212,9 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 			"provider.contextDefault": "不覆盖（默认）",
 			"provider.contextHint": "目录未声明窗口时套用此值（会盖过内置策展表）；保存后立即重新注册",
 			"provider.contextCuratedTitle": "窗口来自内置策展表（models.dev 交叉真值），平台未亲口声明；带 * 标记",
+			"provider.maxOutput": "最大输出",
+			"provider.maxOutputOverrideTitle": "最大输出：来自 maxTokensOverrides 里你写的值（盖过目录声明）",
+			"provider.maxOutputHint": "魔搭目录不返回输出上限，未覆盖的模型按 harness 默认（32768）截断；要更大就在 maxTokensOverrides 里逐模型写实测值（面板徽章用「最大输出」显示生效值）",
 			"section.draw": "出图工具",
 			"draw.enable": "开启后，agent 可在对话里用 modelscope_draw_image 生成或编辑图片",
 			"draw.on": "已开启",
@@ -242,13 +245,20 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 			"draw.absent.peerLoad": "开关已开，但 tools 模块加载失败，出图工具缺席（Host 问题，非配置）。",
 			"draw.absent.registry": "开关已开，但工具注册被 Host 拒绝，出图工具缺席（Host 问题，非配置）。",
 			"draw.absent.unknown": "开关已开，但出图工具未挂载，原因未知。",
+			"draw.preferredGone": "已保存的默认模型 {model} 已不在当前目录（下架或改名）——出图会用它失败，请在下面重选。",
 			"trend.none": "还没有本地调用记录。",
+			"trend.unreadable": "本地计数读不到，趋势图无法显示（不是 0 次）。",
 			"trend.legend": "柱长相对区间内最大值，仅本地口径。",
+			"trend.metric": "趋势指标",
+			"trend.metricCalls": "调用次数",
+			"trend.metricTokens": "token 数",
+			"trend.legendTokens": "按 token 数相对区间内最大值画柱，仅本地口径；失败调用没有用量记录，与「该日无数据」一样显示为 0。",
 			"trend.window": "显示天数",
 			"trend.windowDefault": "默认（跟随配置）",
 			"trend.windowDays": "{days} 天",
 			"trend.windowHint": "只决定画多少天；能回看多久另有一个保留窗口（留得比画得多才画得出更远）。",
 			"events.none": "暂无事件。",
+			"events.unreadable": "本地计数读不到，事件流无法显示（不是没有事件）。",
 			"events.quota": "额度",
 			"events.rate_limit": "限频",
 			"events.error": "错误",
@@ -278,7 +288,7 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 			"composer.stale": "上次数据"
 		};
 		en = {
-			"panel.title": "ModelScope Access · Quota",
+			"panel.title": "ModelScope Model Access",
 			"panel.refresh": "Refresh",
 			"panel.updated": "Updated {time}",
 			"panel.loading": "Loading…",
@@ -354,6 +364,9 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 			"provider.contextDefault": "No override (default)",
 			"provider.contextHint": "Applied when the catalog declares no window (it overrides the built-in curated table); re-registers immediately",
 			"provider.contextCuratedTitle": "Window from the built-in curated table (models.dev cross-check), not declared by the platform; marked with *",
+			"provider.maxOutput": "Max output",
+			"provider.maxOutputOverrideTitle": "Max output: the value you wrote in maxTokensOverrides (it wins over the catalogue)",
+			"provider.maxOutputHint": "The ModelScope catalogue returns no output ceiling, so models without an override are cut off at the harness default (32768); write per-model measured values in maxTokensOverrides for more (the badge shows the effective value)",
 			"section.draw": "Draw tool",
 			"draw.enable": "Once on, the agent can generate or edit images with modelscope_draw_image",
 			"draw.on": "On",
@@ -384,13 +397,20 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 			"draw.absent.peerLoad": "The switch is on, but the tools module failed to load; the draw tool is absent (a Host fault, not config).",
 			"draw.absent.registry": "The switch is on, but the Host refused the tool registration; the draw tool is absent (a Host fault, not config).",
 			"draw.absent.unknown": "The switch is on, but the draw tool is not mounted; the reason is unknown.",
+			"draw.preferredGone": "The saved default model {model} is no longer in the catalogue (delisted or renamed) — drawing with it will fail. Pick another one below.",
 			"trend.none": "No local call records yet.",
+			"trend.unreadable": "Local counts could not be read; the trend chart is unavailable (this is not zero calls).",
 			"trend.legend": "Bar lengths are relative to the maximum in the range (local scope only).",
+			"trend.metric": "Trend metric",
+			"trend.metricCalls": "Calls",
+			"trend.metricTokens": "Tokens",
+			"trend.legendTokens": "Bar lengths are relative to the largest token count in the range (local scope only). Failed calls record no usage, and days with no data also read as 0.",
 			"trend.window": "Days shown",
 			"trend.windowDefault": "Default (follow config)",
 			"trend.windowDays": "{days} days",
 			"trend.windowHint": "Only sets how many days are drawn; how far back history is kept is a separate retention window.",
 			"events.none": "No events.",
+			"events.unreadable": "Local counters unreadable; event stream cannot be shown (not \"no events\").",
 			"events.quota": "Quota",
 			"events.rate_limit": "Rate limit",
 			"events.error": "Error",
@@ -455,6 +475,36 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 		if (number >= 1e4) return Math.round(number).toLocaleString();
 		return String(Math.round(number * 100) / 100);
 	}
+	/**
+	* 大数字的紧凑文本：`< 1000` 原样，`< 1e6` 用 `k`，`≥ 1e6` 用 `m`（各留 1~2 位小数，
+	* 去尾零）。**只给 token 这类会自然到百万级的读数用**——调用次数一天几十上百，千分位
+	* 逗号反而更好读，那条路径继续走 `count()`。
+	*
+	* 单位用小写 k/m：视觉上与 SI 前缀一致，也避开「兆」的歧义（`M` 在中文语境里常被读成
+	* 万亿）。负值与 NaN 分别返回 `-1.2k` 与 `NaN`——不做掩饰，异常值该在面板上现形。
+	*
+	* **与 `const.ts` 的 `formatWindow()` 刻意不同，不是漏统一**：那个印的是**上下文窗口
+	* 规格**（`128K` / `256K` / `1M`，按上游与市场的叫法、K=1024 口径），回答「大概能放
+	* 多少上下文」；这里印的是**实测用量读数**（`1.2k` / `3.4m`，十进制、小写），回答
+	* 「实际用了多少」。同一数字在两处印法不同，是因为它们量纲不同（规格 vs 读数）。
+	*/
+	function compactCount(value) {
+		if (typeof value !== "number" || !Number.isFinite(value)) return String(value);
+		const trim = (number) => String(Number(number.toFixed(number >= 100 ? 0 : number >= 10 ? 1 : 2)));
+		const sign = value < 0 ? "-" : "";
+		const abs = Math.abs(value);
+		if (abs < 1e3) return `${sign}${trim(abs)}`;
+		const tiers = [
+			[1e3, "k"],
+			[1e6, "m"],
+			[1e9, "b"]
+		];
+		for (const [i, [divisor, unit]] of tiers.entries()) {
+			const shown = trim(abs / divisor);
+			if (i === tiers.length - 1 || Number(shown) < 1e3) return `${sign}${shown}${unit}`;
+		}
+		return `${sign}${trim(abs)}b`;
+	}
 	/** 填 `{key}` 模板：vars 的每个键对应模板里的同名占位符。 */
 	function format(template, vars) {
 		let text = template;
@@ -760,6 +810,28 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 				fontSize: 11,
 				color: "var(--dsw-alias-label-secondary)"
 			},
+			trendMetricBar: {
+				display: "flex",
+				gap: 2,
+				marginBottom: 6,
+				alignItems: "center"
+			},
+			trendMetricBtn: {
+				appearance: "none",
+				background: "none",
+				border: "none",
+				borderBottom: "1px solid transparent",
+				padding: "2px 8px",
+				fontSize: 11,
+				color: "var(--dsw-alias-label-secondary)",
+				cursor: "pointer",
+				outlineOffset: -2
+			},
+			trendMetricBtnActive: {
+				color: "var(--dsw-alias-label-primary)",
+				fontWeight: 600,
+				borderBottom: `1px solid ${BRAND}`
+			},
 			muted: { color: "var(--dsw-alias-label-secondary)" },
 			error: { color: "var(--dsw-alias-state-error-primary)" },
 			empty: {
@@ -1021,13 +1093,15 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 			};
 			case "quota": return {
 				daily: { usedLocal: null },
-				perModel: [],
+				perModel: null,
 				countingNote: "local-counting"
 			};
-			case "events": return [];
+			case "events": return null;
 			case "trend": return {
 				days: 0,
-				buckets: []
+				windowDays: null,
+				maxDays: 0,
+				buckets: null
 			};
 			case "models": return {
 				available: false,
@@ -1101,6 +1175,8 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 			const id = String(row.id ?? "");
 			const w = row.contextWindow;
 			const contextSource = row.contextSource === "override" || row.contextSource === "curated" ? row.contextSource : "catalog";
+			const maxOutputSource = row.maxOutputSource === "override" ? "override" : "catalog";
+			const out = row.maxOutputLength;
 			return {
 				id,
 				name: typeof row.name === "string" && row.name !== "" ? row.name : id,
@@ -1108,7 +1184,9 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 				available: row.available !== false,
 				quotaExhausted: row.quotaExhausted === true,
 				contextSource,
-				...typeof w === "number" && Number.isFinite(w) && w > 0 ? { contextWindow: w } : {}
+				maxOutputSource,
+				...typeof w === "number" && Number.isFinite(w) && w > 0 ? { contextWindow: w } : {},
+				...typeof out === "number" && Number.isFinite(out) && out > 0 ? { maxOutputLength: out } : {}
 			};
 		}).filter((entry) => entry.id !== "") : [];
 		return {
@@ -1169,6 +1247,7 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 			..."effectiveSource" in d ? { effectiveSource } : {},
 			absentReason,
 			mountPending: d.mountPending === true,
+			preferredInCatalog: d.preferredInCatalog === true ? true : d.preferredInCatalog === false ? false : null,
 			toolName: typeof d.toolName === "string" && d.toolName !== "" ? d.toolName : "modelscope_draw_image"
 		};
 	}
@@ -1228,6 +1307,7 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 			effectiveSource: null,
 			absentReason: null,
 			mountPending: false,
+			preferredInCatalog: null,
 			toolName: "modelscope_draw_image"
 		});
 		GUIDANCE_BY_CODE = Object.freeze({
@@ -1453,17 +1533,19 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 	function LocalDailyCard({ snapshot, tt }) {
 		const quota = snapshot.quota;
 		const daily = quota?.daily ?? { usedLocal: null };
-		const perModel = Array.isArray(quota?.perModel) ? quota.perModel : [];
+		const perModel = quota?.perModel;
+		const perModelRows = Array.isArray(perModel) ? perModel : perModel === null ? null : [];
 		const unknownUsed = !(typeof daily.usedLocal === "number" && Number.isFinite(daily.usedLocal));
 		const usedText = unknownUsed ? "—" : count(daily.usedLocal);
+		const perModelUnknown = perModelRows === null;
 		return h("div", { style: S.card }, h("div", { style: S.poolName }, format(tt("quota.headline"), {
 			calls: usedText,
-			models: count(perModel.length)
-		})), unknownUsed ? h("div", { style: {
+			models: perModelUnknown ? "—" : count(perModelRows.length)
+		})), unknownUsed || perModelUnknown ? h("div", { style: {
 			...S.formNote,
 			color: "var(--dsw-alias-state-warn-primary)"
-		} }, tt("quota.unavailable")) : null, h(ModelUsageTable, {
-			rows: perModel,
+		} }, tt("quota.unavailable")) : null, perModelUnknown ? null : h(ModelUsageTable, {
+			rows: perModelRows,
 			tt
 		}), h("div", { style: S.trendLegend }, tt("quota.note")));
 	}
@@ -1479,7 +1561,7 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 			}, h("div", { style: S.trendRowHead }, h("span", {
 				style: S.trendModel,
 				title: row.modelId
-			}, row.modelId), h("span", { style: S.trendCredits }, format(tt("quota.rowCalls"), { calls: count(row.calls) }) + (row.tokens !== null ? ` · ${format(tt("quota.rowTokens"), { tokens: count(row.tokens) })}` : ""))), pct >= 1 ? h("div", {
+			}, row.modelId), h("span", { style: S.trendCredits }, format(tt("quota.rowCalls"), { calls: count(row.calls) }) + (row.tokens !== null ? ` · ${format(tt("quota.rowTokens"), { tokens: compactCount(row.tokens) })}` : ""))), pct >= 1 ? h("div", {
 				style: S.trendBar,
 				role: "progressbar",
 				"aria-valuenow": Math.round(pct),
@@ -1526,33 +1608,63 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 		}
 		return out;
 	}
-	/** 近 N 天本地调用趋势（天桶；缺桶 = 该日 0 次，真实零）——**竖向柱状图**。 */
+	/**
+	* 近 N 天本地调用趋势（天桶；缺桶 = 该日 0 次，真实零）——**竖向柱状图**。
+	*
+	* token 与调用次数共用同一根柱子但**各自归一化**（`max` 按当前指标现算）：两者量级
+	* 差三四个数量级，若共用一把尺，次数柱会被 token 柱压成贴地的一条线——那图就撒谎了。
+	* 一次只画一个指标（不放双柱），窄容器里双柱既挤又难读，且对比还得再解释一遍。
+	*
+	* 切换态活在组件内的 useState：它是纯显示偏好，不落盘——与「显示天数」不同，那个
+	* 会改变 Host 的取数窗口（真要持久化就该走 usage-prefs，别混进这里）。
+	*/
 	function TrendBars({ buckets, tt }) {
+		const [metric, setMetric] = useState("calls");
+		if (buckets === null) return h("div", { style: S.trendLegend }, tt("trend.unreadable"));
 		if (!Array.isArray(buckets) || buckets.length === 0) return h("div", { style: S.trendLegend }, tt("trend.none"));
 		const rows = buckets.map((bucket) => ({
 			dateKey: bucket.dateKey,
-			calls: Number.isFinite(bucket.calls) ? Math.max(0, bucket.calls) : 0
+			calls: Number.isFinite(bucket.calls) ? Math.max(0, bucket.calls) : 0,
+			tokens: Number.isFinite(bucket.tokens) ? Math.max(0, bucket.tokens) : 0
 		}));
-		const max = Math.max(0, ...rows.map((row) => row.calls));
-		return h("div", null, h("div", { style: S.trendChartBars }, rows.map((row) => {
-			const pct = max > 0 ? row.calls / max * 100 : 0;
+		const tokenMode = metric === "tokens";
+		const values = rows.map((row) => tokenMode ? row.tokens : row.calls);
+		const max = Math.max(0, ...values);
+		/** 读数文本：次数走 count（千分位），token 走 compactCount（`1.2k` / `3.4m`）。 */
+		const readout = (value) => tokenMode ? compactCount(value) : count(value);
+		return h("div", null, h("div", {
+			style: S.trendMetricBar,
+			role: "group",
+			"aria-label": tt("trend.metric")
+		}, ...[["calls", "trend.metricCalls"], ["tokens", "trend.metricTokens"]].map(([key, labelKey]) => h("button", {
+			key,
+			type: "button",
+			"aria-pressed": metric === key,
+			style: metric === key ? {
+				...S.trendMetricBtn,
+				...S.trendMetricBtnActive
+			} : S.trendMetricBtn,
+			onClick: () => setMetric(key)
+		}, tt(labelKey)))), h("div", { style: S.trendChartBars }, rows.map((row, index) => {
+			const value = values[index] ?? 0;
+			const pct = max > 0 ? value / max * 100 : 0;
 			return h("div", {
 				key: row.dateKey,
 				style: S.trendChartBar,
-				title: `${row.dateKey}: ${count(row.calls)}`
-			}, row.calls > 0 ? h("span", {
+				title: `${row.dateKey}: ${readout(value)}`
+			}, value > 0 ? h("span", {
 				style: {
 					...S.trendChartValue,
 					bottom: `calc(${pct}% + 3px)`
 				},
 				"aria-hidden": "true"
-			}, count(row.calls)) : null, h("div", {
+			}, readout(value)) : null, h("div", {
 				style: {
 					...S.trendChartFill,
 					height: `${pct}%`
 				},
 				role: "progressbar",
-				"aria-label": `${row.dateKey} ${count(row.calls)}`,
+				"aria-label": `${row.dateKey} ${readout(value)}`,
 				"aria-valuenow": Math.round(pct),
 				"aria-valuemin": 0,
 				"aria-valuemax": 100
@@ -1564,7 +1676,7 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 				title: key,
 				style: { whiteSpace: "nowrap" }
 			}, shortDateKey(key));
-		})), h("div", { style: S.trendLegend }, tt("trend.legend")));
+		})), h("div", { style: S.trendLegend }, tt(tokenMode ? "trend.legendTokens" : "trend.legend")));
 	}
 	/**
 	* 趋势显示窗口选择器：默认（跟随 `trendDays` 配置）/ 7 / 14 / 30 / 90 天。
@@ -1622,8 +1734,9 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 			role: "alert"
 		}, error) : null);
 	}
-	/** 事件流（429/错误），Newest-first。 */
+	/** 事件流（429/错误），Newest-first。`events` 为 null = 读不到，渲染「—」（读不到 ≠ 0）。 */
 	function EventsList({ events, tt }) {
+		if (events === null) return h("div", { style: S.trendLegend }, tt("events.unreadable"));
 		if (!Array.isArray(events) || events.length === 0) return h("div", { style: S.trendLegend }, tt("events.none"));
 		return h("div", null, events.map((event, index) => h("div", {
 			key: `${event.at}-${index}`,
@@ -1889,7 +2002,10 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 					color: "var(--dsw-alias-label-secondary)"
 				} : S.modelBadge,
 				title: row.contextSource === "curated" ? tt("provider.contextCuratedTitle") : tt("provider.contextWindow")
-			}, row.contextSource === "curated" ? formatWindow(row.contextWindow) + " *" : formatWindow(row.contextWindow)) : null, row.quotaExhausted === true ? h("span", { style: {
+			}, row.contextSource === "curated" ? formatWindow(row.contextWindow) + " *" : formatWindow(row.contextWindow)) : null, typeof row.maxOutputLength === "number" ? h("span", {
+				style: S.modelBadge,
+				title: row.maxOutputSource === "override" ? tt("provider.maxOutputOverrideTitle") : tt("provider.maxOutput")
+			}, formatWindow(row.maxOutputLength)) : null, row.quotaExhausted === true ? h("span", { style: {
 				...S.modelBadge,
 				color: "var(--dsw-alias-state-error-primary)"
 			} }, tt("provider.quotaExhausted")) : null, h("a", {
@@ -1957,7 +2073,7 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 			style: S.primary,
 			disabled: busy,
 			onClick: () => onSaveList(draft.slice())
-		}, tt("provider.saveList"))), visibleRows.length === 0 ? h("div", { style: {
+		}, tt("provider.saveList"))), h("div", { style: S.advancedHint }, tt("provider.maxOutputHint")), visibleRows.length === 0 ? h("div", { style: {
 			...S.muted,
 			fontSize: 12,
 			padding: "10px 4px"
@@ -2074,7 +2190,7 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 			},
 			role: "status"
 		}, tt("draw.notMounted"));
-		const restartHint = enabled ? h("div", { style: {
+		const restartHint = enabled && status.mountPending === true ? h("div", { style: {
 			...S.formNote,
 			color: "var(--dsw-alias-state-warn-primary)"
 		} }, tt("draw.restartHint")) : null;
@@ -2082,6 +2198,13 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 			...S.formNote,
 			color: "var(--dsw-alias-state-warn-primary)"
 		} }, tt("draw.needsKey")) : null;
+		const preferredGoneHint = status.preferredModel !== null && status.preferredInCatalog === false ? h("div", {
+			style: {
+				...S.formNote,
+				color: "var(--dsw-alias-state-warn-primary)"
+			},
+			role: "status"
+		}, format(tt("draw.preferredGone"), { model: status.preferredModel })) : null;
 		const autoDescription = !hasEffectiveKey || status.preferredModel !== null ? null : effectiveModel === null || effectiveModel === "" ? h("div", { style: {
 			...S.muted,
 			fontSize: 11,
@@ -2199,7 +2322,7 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 		}, tt("draw.reset"))), error !== null ? h("div", {
 			style: S.formError,
 			role: "alert"
-		}, error) : null, restartHint, tokenHint);
+		}, error) : null, restartHint, tokenHint, preferredGoneHint);
 	}
 	var MAX_TICKS, TREND_WINDOW_TIERS, EVENT_KIND_KEY, DRAW_ABSENT_KEY;
 	var init_cards = __esmMin((() => {
@@ -2662,7 +2785,7 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 				onChange: (windowDays) => void saveTrendWindow(windowDays),
 				tt
 			}), h(TrendBars, {
-				buckets: snap.trend?.buckets ?? [],
+				buckets: snap.trend?.buckets ?? null,
 				tt
 			})), h(SectionCard, {
 				title: tt("section.events"),
@@ -2670,7 +2793,7 @@ var dsh_connect_modelscope_token_plan_client = (function() {
 				onToggle: () => toggleSection("events"),
 				tt
 			}, h(EventsList, {
-				events: snap.events ?? [],
+				events: snap.events ?? null,
 				tt
 			})));
 		};

package/cordis.patch.yml

@@ -32,6 +32,17 @@
         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 小时）。
@@ -47,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 瀑布决定重发，因而每次重试各记一次（按「魔搭按
@@ -59,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）。