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

package/lib/index.js

@@ -1,4 +1,4 @@
-import { C as errMsg, D as redactSecrets, E as pluginError, O as str, S as degrade, T as optional, _ as parseAllowedList, a as resolveSettings, b as looksLikeRateLimit, c as LLM_PROVIDER_ID, d as imageGenModelIds, f as isVisionModel, g as enabledCountOf, h as rosterWithAvailability, i as name, k as verbatim, m as resolveDrawModelChoice, n as inject, p as normalizeEntry, r as isAdmitted, s as LLM_DISPLAY_NAME, t as PLUGIN_VERSION, u as drawCandidates, w as obj, y as hasHardQuotaWordingIn } from "./host-config.js";
+import { A as verbatim, C as degrade, D as pluginError, E as optional, O as redactSecrets, T as obj, _ as enabledCountOf, a as name, b as hasHardQuotaWordingIn, c as LLM_DISPLAY_NAME, d as drawCandidates, f as imageGenModelIds, g as rosterWithAvailability, h as resolveDrawModelChoice, i as isAdmitted, k as str, l as LLM_PROVIDER_ID, m as normalizeEntry, n as PLUGIN_VERSION, o as resolveSettings, p as isVisionModel, r as inject, t as DRAW_TIMEOUT_MAX_MS, v as parseAllowedList, w as errMsg, x as looksLikeRateLimit } from "./host-config.js";
 import { basename, join } from "node:path";
 import { mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
@@ -130,7 +130,13 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 	};
 	return {
 		/**
-		* 把面板输入的令牌存成引用；原样存（不 trim），空白值视为没输入。
+		* 把面板输入的令牌存成引用；**两端空白先 trim**，空白值视为没输入。
+		*
+		* **为什么 trim 而不是原样存**：校验用的是 `value.trim()`，落库却曾是原值——
+		* 校验与落库必须是**同一个值**，否则「通过校验的值」与「发出去的值」不是一个东西。
+		* 实测（2026-10-19）：`save("  ms-3f2a…  ")` 会把带着前后空格的串存进凭据服务，
+		* 而它拼出的请求头是 `Bearer   ms-…  `——用户粘进一个空格就换来一个语焉不详的
+		* 401，面板却显示「已保存」。只 trim 两端，令牌中间的形状（分段连字符）不动。
 		*
 		* **形状校验**：只接受 `ms-` + 至少 16 位十六进制（可含连字符分段）。这不是
 		* 洁癖——`redactSecrets` 的脱敏闸是**正则**，只能遮它认识的形状；一个
@@ -143,9 +149,9 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 		* 真机请求换来一个语焉不详的 401。
 		*/
 		async save(token) {
-			const value = verbatim(token, "");
-			if (typeof value !== "string" || value.trim() === "") throw new Error("a ModelScope token is required");
-			if (!isPlausibleToken(value.trim())) throw new Error("that does not look like a ModelScope access token (expected ms- followed by at least 16 hex digits); if you are sure the token is correct, this plugin's shape check may be out of date");
+			const value = verbatim(token, "").trim();
+			if (value === "") throw new Error("a ModelScope token is required");
+			if (!isPlausibleToken(value)) throw new Error("that does not look like a ModelScope access token (expected ms- followed by at least 16 hex digits); if you are sure the token is correct, this plugin's shape check may be out of date");
 			const service = resolveService();
 			if (service !== null && typeof service.set === "function") {
 				await service.set(TOKEN_REF, value);
@@ -424,17 +430,6 @@ function temporaryOf(dir, base, now = Date.now) {
 	return join(dir, `${base}.${process.pid}.${now()}.${randomUUID()}.tmp`);
 }
 /**
-* Write one state file atomically: a 0600 temporary file, then a rename.
-*
-* The payload string is written with a trailing newline, exactly as every
-* store wrote before this module existed. Failures PROPAGATE — the callers
-* decide whether a read-only Home breaks their flow.
-* @param {string} file - the final file path.
-* @param {string} payload - the serialized body (JSON text).
-* @param {{temporary: string}} options - the temp path to write first.
-* @returns {Promise<void>}
-*/
-/**
 * 写一个状态文件：一个 0600 临时文件，然后 rename。
 *
 * 载荷串以换行结尾，与本模块存在前每个 store 的写法一致。失败**向上传播** ——
@@ -1743,6 +1738,24 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 		}
 		return Array.from(new Set(tasks));
 	};
+	/**
+	* 令牌的稳定指纹（FNV-1a，32 位 hex）——只用作余额缓存的键。
+	*
+	* **不用 `token.slice(-6)` 那种末位截断**：两个不同令牌末 6 位相同的概率在
+	* 1/16^7 量级，虽低但非零，而代价是一个 TTL（cacheSeconds，默认 60s）内把
+	* A 的身份的余额当 B 的返回——缓存键的正确性不该交给运气。指纹不需要保密、
+	* 不进日志（脱敏正则的形状与它无关），完整的哈希零成本。
+	* @param {string} token - 访问令牌。
+	* @returns {string} 8 位 hex 指纹。
+	*/
+	function tokenFingerprint(token) {
+		let hash = 2166136261;
+		for (let i = 0; i < token.length; i++) {
+			hash ^= token.charCodeAt(i);
+			hash = Math.imul(hash, 16777619);
+		}
+		return (hash >>> 0).toString(16).padStart(8, "0");
+	}
 	return {
 		/**
 		* 模型目录：GET apiBase/models，免认证、零额度，coalesced 缓存
@@ -1836,13 +1849,14 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 		/**
 		* 官方「魔粒」余额：GET siteBase/openapi/v1/magicubes/balance（Bearer
 		* 令牌；2026-10-04 实测可用，匿名 401，SPIKE.md §魔粒）。coalesced 缓存
-		* cacheSeconds，缓存键带令牌指纹——换令牌 ≤1 个 TTL 内必然读到新身份。
+		* cacheSeconds，缓存键带令牌指纹（FNV-1a 完整哈希，不是末位截断——
+		* 换令牌 ≤1 个 TTL 内必然读到新身份，且不同令牌不会因同后缀串味）。
 		*/
 		async fetchBalance() {
 			const { value: token } = await tokenStore.resolve();
 			if (token === "") throw pluginError(CODE.AUTH_ERROR, "no ModelScope token configured — set MODELSCOPE_API_KEY or save one in the panel");
 			const url = settings.siteBase + "/openapi/v1/magicubes/balance";
-			const key = "balance#" + token.slice(-6);
+			const key = "balance#" + tokenFingerprint(token);
 			return await read(key, async () => {
 				const response = await fetchWithTimeout(url, {
 					method: "GET",
@@ -1905,7 +1919,10 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 				const extra = retryAfterMs !== null && retryAfterMs !== void 0 ? { retryAfterMs } : {};
 				throw pluginError(triage === "quota" ? CODE.QUOTA_EXCEEDED : CODE.RATE_LIMITED, redactSecrets(message === "" ? "modelscope returned 429 (probe on " + modelId + ")" : message), extra);
 			}
-			if (response.status >= 500) throw pluginError(CODE.UPSTREAM_ERROR, "modelscope returned HTTP " + String(response.status) + " (validity probe)");
+			if (response.status >= 500) {
+				discardBody(response);
+				throw pluginError(CODE.UPSTREAM_ERROR, "modelscope returned HTTP " + String(response.status) + " (validity probe)");
+			}
 			response.body?.cancel();
 			return {
 				ok: true,
@@ -2615,6 +2632,76 @@ function createFileDrawStore(options = {}) {
 	};
 }
 
+//#endregion
+//#region src/host/draw-jobs.ts
+/**
+* 建一张出图作业表。
+* @param {DrawJobsOptions} [options] - 容量与保护窗参数。
+* @returns {DrawJobs} 作业表。
+*/
+function createDrawJobs(options = {}) {
+	const maxJobs = Math.max(1, Math.floor(options.maxJobs ?? 64));
+	const resumeWindowMs = Math.max(1, Math.floor(options.resumeWindowMs ?? 9e5));
+	const hardMaxJobs = Math.max(maxJobs, Math.floor(options.hardMaxJobs ?? maxJobs * 2));
+	/** @type {Map<string, DrawJob>} 插入顺序即淘汰顺序（Map 保序）。 */
+	const jobs = /* @__PURE__ */ new Map();
+	/**
+	* 超容时的两级淘汰（判据见文件头「生命周期」）：
+	*   软上限只淘汰已过续查保护窗的（越过总放弃线，续查只换来「超过总预算」）；
+	*   硬上限保底——全是保护窗内的作业也绝不无界。
+	* @param {number} now - 当前墙钟毫秒（`create` 的 `now` 缝传进来，测试可造旧作业）。
+	*/
+	const evictIfNeeded = (now) => {
+		if (jobs.size <= maxJobs) return;
+		for (const [id, job] of jobs) {
+			if (jobs.size <= maxJobs) return;
+			if (now - job.submittedAt >= resumeWindowMs) jobs.delete(id);
+		}
+		while (jobs.size > hardMaxJobs) {
+			const oldest = jobs.keys().next();
+			if (oldest.done === true) return;
+			jobs.delete(oldest.value);
+		}
+	};
+	return {
+		create({ taskId, model, prompt, now }) {
+			const jobId = taskId;
+			const at = typeof now === "number" && Number.isFinite(now) ? now : Date.now();
+			const job = {
+				jobId,
+				taskId,
+				model,
+				prompt,
+				submittedAt: at,
+				polls: 0
+			};
+			const previous = jobs.get(jobId);
+			if (previous !== void 0) job.polls = previous.polls;
+			jobs.set(jobId, job);
+			evictIfNeeded(at);
+			return { ...job };
+		},
+		get(jobId) {
+			const found = jobs.get(jobId);
+			return found === void 0 ? null : { ...found };
+		},
+		notePolls(jobId, polls) {
+			const found = jobs.get(jobId);
+			if (found === void 0) return;
+			found.polls += Math.max(0, Math.floor(polls));
+		},
+		drop(jobId) {
+			jobs.delete(jobId);
+		},
+		dispose() {
+			jobs.clear();
+		},
+		size() {
+			return jobs.size;
+		}
+	};
+}
+
 //#endregion
 //#region src/host/switch-precedence.ts
 /**
@@ -2917,9 +3004,11 @@ function createFileUsagePrefsStore(options = {}) {
 *    缺这个头的实现会在第一次轮询就误判失败并放弃一张已经能出的图。
 * 2. **提交响应的 `task_status` 不可信**：实测每次提交都回 `SUCCEED`，包括最终确实
 *    `FAILED` 的那次。所以提交只认 `task_id`，**成功与否只看轮询终态**。
-* 3. **`FAILED` 没有可分诊的形状**：`errors.code` 实测为 `0`、`errors.message` 为
-*    空串，没有顶层 `message`。任何「从错误里读出原因」的承诺都是编造——本模块的
-*    `describeDrawFailure` 因此**明确承认原因不可知**，只报可确定的形态差异。
+* 3. **`FAILED` 常常没有可分诊的形状**：实测样本 `errors.code` 为 `0`、
+*    `errors.message` 为空串、没有顶层 `message`。所以不能承诺「一定读得出原因」——
+*    本模块的 `describeDrawFailure` 只报**这个 body 里确实写着**的东西：读得到
+*    `errors.message` 就报它，读不到就明说原因不可知（2026-10-19 修补：旧写法把
+*    「实测样本为空」当成了「永远为空」，非空原因会被一并报成「未给出原因」）。
 *
 * 关于两个小工具（`str` / `redactSecrets`）：它们曾以**本地私有副本**的形式活在
 * 本文件里，理由是「避免为 3 行代码引 util 的依赖面」。那条理由不成立——util.ts
@@ -3120,13 +3209,31 @@ function normalizeImageUrlInput(value) {
 	return null;
 }
 /**
+* 从上游 body 里取第一句**可引用的原因**：`errors.message`，退回顶层 `message`。
+*
+* 取的是**未截断**的原文——`describeDrawFailure` 的 tail 会截到 300 字符，截断后的
+* JSON 解析不出来。解析不出来（非 JSON / 字段为空 / 字段不是字符串）一律返回 `""`：
+* 这里**不猜**，没有原因就说没有原因。
+*/
+function upstreamMessageOf(raw) {
+	if (raw === "") return "";
+	try {
+		const parsed = JSON.parse(raw);
+		for (const candidate of [parsed?.errors?.message, parsed?.message]) if (typeof candidate === "string" && candidate.trim() !== "") return candidate.trim();
+	} catch {}
+	return "";
+}
+/**
 * 把一次失败转成 agent 与面板都能读的一句话。
 *
-* **关于魔搭 `FAILED` 的诚实边界**：实测唯一的失败样本是
-* `{"errors":{"code":0,"message":""}, "task_status":"FAILED"}`——**原因不可知**。
-* 所以这里只报「可确定的形态事实」（HTTP 码 / 轮询未出终态 / 明确的原因文本），
-* **不从空错误里编造原因**，并在原因确实拿不到时明说「上游未给出原因」。这是本仓库
-* README「诚实声明」的要求。
+* **关于魔搭 `FAILED` 的诚实边界**：实测见过的失败样本是
+* `{"errors":{"code":0,"message":""}, "task_status":"FAILED"}`——那一份**原因不可知**。
+* 但样本量是 1，不是恒定形态：上游也可能给出非空的 `errors.message`
+* （2026-10-19 锐评实测 `sensitive content detected`、
+* `image_url is required for model MusePublic/Qwen-Image-Edit` 这类原因会被旧写法
+* 一并报成「未给出失败原因」，且 body 被丢掉，2/2 误报）。所以判据是**逐个 body 判**：
+* 有原因就报原因，确实没有才明说「上游未给出原因」；任何情况下都不从空错误里编造
+* 原因，两种情况**都附脱敏后的 body**。这是本仓库 README「诚实声明」的要求。
 *
 * 凭据永不入消息：body 文本可能回显 `ms-` 令牌，过 `redactSecrets` 后再截断。
 * @param {object} failure - 失败信息。
@@ -3137,17 +3244,22 @@ function normalizeImageUrlInput(value) {
 * @returns {string} 一行说明。
 */
 function describeDrawFailure(failure) {
-	const text = redactSecrets(typeof failure.bodyText === "string" ? failure.bodyText : "").slice(0, 300);
+	const raw = typeof failure.bodyText === "string" ? failure.bodyText : "";
+	const text = redactSecrets(raw).slice(0, 300);
 	const status = Number.isFinite(failure.status) ? Number(failure.status) : 0;
 	const tail = text === "" ? "" : `; body: ${text}`;
-	if (status === 401 || status === 403) return `出图失败：HTTP ${status} —— 访问令牌无效、无权访问该模型，或账号未完成邮箱验证/实名（后者是实测遇到过的真实拦截）。请在面板确认令牌与账号状态${tail}`;
+	if (status === 401 || status === 403) return `出图失败：HTTP ${status} —— ${/邮箱|实名|email[^\n]{0,40}verif|verif\w*[^\n]{0,40}email|complete\s+your\s+profile/i.test(text) ? "访问令牌无效、无权访问该模型，或账号未完成邮箱验证/实名（上游 body 提到了账号态）" : "访问令牌无效或无权访问该模型（上游未指明具体原因）"}。请在面板确认令牌与账号状态${tail}`;
 	if (status === 404) return `出图失败：HTTP 404 —— 端点或模型不存在（检查 apiBase 与模型 id）${tail}`;
 	if (status === 429) return `出图失败：HTTP 429 —— 上游限流，请稍后重试${tail}`;
 	if (status >= 500) return `出图失败：HTTP ${status} —— 上游服务异常，稍后重试${tail}`;
 	const cause = str(failure.cause, "");
-	if (cause !== "") return `出图失败：${cause}${tail}`;
+	if (cause !== "") return `出图失败：${redactSecrets(cause)}${tail}`;
 	const taskStatus = str(failure.taskStatus, "");
-	if (taskStatus === "FAILED") return "出图失败：上游任务 FAILED，但未给出失败原因（实测 errors.code=0、message 为空），换模型或稍后重试";
+	if (taskStatus === "FAILED") {
+		const upstream = upstreamMessageOf(raw);
+		if (upstream !== "") return `出图失败：上游任务 FAILED —— ${redactSecrets(upstream)}${tail}`;
+		return `出图失败：上游任务 FAILED，但未给出失败原因（上游 errors.message 为空），换模型或稍后重试${tail}`;
+	}
 	if (taskStatus !== "") return `出图失败：任务停在 ${taskStatus}（非终态），已超过截止时间`;
 	return `出图失败：上游未给出可诊断的失败信息${tail}`;
 }
@@ -3178,62 +3290,6 @@ function createDrawCooldown(cooldownMs) {
 	};
 }
 
-//#endregion
-//#region src/host/draw-jobs.ts
-/**
-* 建一张出图作业表。
-* @param {DrawJobsOptions} [options] - 容量上限。
-* @returns {DrawJobs} 作业表。
-*/
-function createDrawJobs(options = {}) {
-	const maxJobs = Math.max(1, Math.floor(options.maxJobs ?? 64));
-	/** @type {Map<string, DrawJob>} 插入顺序即淘汰顺序（Map 保序）。 */
-	const jobs = /* @__PURE__ */ new Map();
-	const evictIfNeeded = () => {
-		while (jobs.size > maxJobs) {
-			const oldest = jobs.keys().next();
-			if (oldest.done === true) return;
-			jobs.delete(oldest.value);
-		}
-	};
-	return {
-		create({ taskId, model, prompt, now }) {
-			const jobId = taskId;
-			const job = {
-				jobId,
-				taskId,
-				model,
-				prompt,
-				submittedAt: typeof now === "number" && Number.isFinite(now) ? now : Date.now(),
-				polls: 0
-			};
-			const previous = jobs.get(jobId);
-			if (previous !== void 0) job.polls = previous.polls;
-			jobs.set(jobId, job);
-			evictIfNeeded();
-			return { ...job };
-		},
-		get(jobId) {
-			const found = jobs.get(jobId);
-			return found === void 0 ? null : { ...found };
-		},
-		notePolls(jobId, polls) {
-			const found = jobs.get(jobId);
-			if (found === void 0) return;
-			found.polls += Math.max(0, Math.floor(polls));
-		},
-		drop(jobId) {
-			jobs.delete(jobId);
-		},
-		dispose() {
-			jobs.clear();
-		},
-		size() {
-			return jobs.size;
-		}
-	};
-}
-
 //#endregion
 //#region src/host/draw-runtime.ts
 /**
@@ -3263,6 +3319,9 @@ function createDrawJobs(options = {}) {
 *    轮询只与更慢相关。
 * 3. 失败原因实测可能**不可知**（`errors.code:0` + 空 message）。`describeDrawFailure`
 *    因此明说「未给出原因」，本文件也**不从空错误里编造**。
+* 4. 轮询的 5xx / 429 / 408 是**瞬态**不是终局（{@link isTransientPollStatus}）：
+*    同一个物理故障不因表现为 TCP 抛错还是 5xx 响应就两种判法；只有 4xx 是
+*    终局证据。瞬态持续时由 deadline 收口成 pending，续查把手不丢。
 *
 * @module dsh-connect-modelscope-token-plan/draw-runtime
 */
@@ -3271,6 +3330,13 @@ const DRAW_TOOL_NAME = "modelscope_draw_image";
 /** 一次失败的冷却窗：出图慢，失败后立刻重试既易撞限流又白等。 */
 const DRAW_FAILURE_COOLDOWN_MS = 6e4;
 /**
+* 工具级硬护栏比单次等待预算多出的余量。
+*
+* 它保证**等待循环先返回**：护栏若与等待预算同值，正常路径会以 peer 的超时错误
+* 结束，而不是带 `jobId` 的 `pending`——那会把续查这条唯一的把手换成一个死胡同。
+*/
+const DRAW_TOOL_TIMEOUT_MARGIN_MS = 1e4;
+/**
 * 把 OpenAI 兼容 base 拼成出图端点。
 *
 * `…/v1` → `…/v1/images/generations`；已带该后缀则原样；更深路径回卷到 `/v1`。
@@ -3363,8 +3429,10 @@ async function submitDrawTask({ fetchImpl, apiBase, apiKey, model, prompt, image
 * 抛错是「这件事做不成了」，`pending` 是「还没成，可以再查」。同一段循环因此
 * 同时服务于两种调用形状（一次性跑完 / 分段续查），不写两份。
 *
-* 轮询带 `X-ModelScope-Task-Type`（**必需**，漏了必假失败）；传输层抖动与非
-* JSON 响应体都**不升级为终局**，继续等下一轮。
+* 轮询带 `X-ModelScope-Task-Type`（**必需**，漏了必假失败）。三类情形**不升级
+* 为终局**，在本次预算内继续等下一轮：① 传输层抛错（ECONNRESET / DNS）；
+* ② 非 JSON / 200 垃圾响应体（CDN 错误页）；③ **瞬态 HTTP 状态码**（5xx /
+* 429 / 408，见 {@link isTransientPollStatus}）。只有 4xx 是终局证据。
 * @param {object} options - 等待参数。
 * @param {DrawFetch} options.fetchImpl - 注入的 fetch。
 * @param {string} options.apiBase - apiBase。
@@ -3372,9 +3440,12 @@ async function submitDrawTask({ fetchImpl, apiBase, apiKey, model, prompt, image
 * @param {string} options.taskId - 上游任务 id。
 * @param {number} [options.waitMs] - 本次调用的等待预算。
 * @param {number} [options.pollIntervalMs] - 轮询间隔（测试可缩短）。
+* @param {() => boolean} [options.shouldStop] - 每轮轮询前问一次「还要不要继续」
+*   （撤下闸）。`signal` 只能表达**已经**中止，问不出「刚刚被撤下」——等待循环是
+*   本模块唯一的循环，撤下只有在这里能被周期性看见。
 * @returns {Promise<DrawAwait>} 三种结局之一。
 */
-async function awaitDrawTask({ fetchImpl, apiBase, apiKey, taskId, waitMs = DRAW_WAIT_BUDGET_MS, pollIntervalMs = DRAW_POLL_INTERVAL_MS, signal }) {
+async function awaitDrawTask({ fetchImpl, apiBase, apiKey, taskId, waitMs = DRAW_WAIT_BUDGET_MS, pollIntervalMs = DRAW_POLL_INTERVAL_MS, signal, shouldStop }) {
 	const headers = {
 		Authorization: `Bearer ${apiKey}`,
 		"Content-Type": "application/json"
@@ -3388,6 +3459,10 @@ async function awaitDrawTask({ fetchImpl, apiBase, apiKey, taskId, waitMs = DRAW
 			kind: "pending",
 			polls
 		};
+		if (shouldStop?.() === true) return {
+			kind: "pending",
+			polls
+		};
 		try {
 			await sleep(interval, signal);
 		} catch {
@@ -3404,20 +3479,29 @@ async function awaitDrawTask({ fetchImpl, apiBase, apiKey, taskId, waitMs = DRAW
 				headers: {
 					...headers,
 					[TASK_TYPE_HEADER]: TASK_TYPE_IMAGE_GENERATION
-				}
+				},
+				...signal !== void 0 ? { signal } : {}
 			});
 		} catch {
+			if (signal?.aborted === true) return {
+				kind: "pending",
+				polls
+			};
 			continue;
 		}
 		const pollText = await safeText(polled);
-		if (!polled.ok) return {
-			kind: "failed",
-			message: describeDrawFailure({
-				...polled.status !== void 0 ? { status: polled.status } : {},
-				...pollText !== "" ? { bodyText: pollText } : {},
-				...lastStatus !== void 0 ? { taskStatus: lastStatus } : {}
-			})
-		};
+		if (!polled.ok) {
+			if (isTransientPollStatus(polled.status)) continue;
+			const previous = lastStatus !== void 0 ? `（上一轮读到 ${lastStatus}）` : "";
+			return {
+				kind: "failed",
+				message: describeDrawFailure({
+					...polled.status !== void 0 ? { status: polled.status } : {},
+					...pollText !== "" ? { bodyText: pollText } : {},
+					cause: `轮询请求失败：HTTP ${polled.status ?? "未知"}，本轮未读到任务状态${previous}`
+				})
+			};
+		}
 		const data = await safeJson(polled, pollText);
 		const status = readTaskStatus(data);
 		if (status !== null) lastStatus = status;
@@ -3516,21 +3600,34 @@ function drawModelIds(entries) {
 * @returns {unknown} 已定义的 agent 工具。
 */
 function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, settings, getPreferredModelId, cooldown = createDrawCooldown(DRAW_FAILURE_COOLDOWN_MS), jobs = createDrawJobs(), pollIntervalMs = DRAW_POLL_INTERVAL_MS, isDisposed = () => false }) {
-	/** 总放弃线：从提交算起，跨多次调用累计。 */
-	const timeoutMs = Math.max(3e4, Math.floor(Number(settings?.drawTimeoutMs) > 0 ? Number(settings?.drawTimeoutMs) : DRAW_TIMEOUT_MS));
+	/**
+	* 总放弃线：从提交算起，跨多次调用累计。
+	*
+	* 上下界与 `host-config.resolveSettings` 同源，这里再夹一次是为了让本函数的
+	* 不变式**自足**：`waitMs + margin <= timeoutMs <= DRAW_TIMEOUT_MAX_MS`（见下面
+	* `waitMs` 与工具定义里的 `timeoutMs`）。直接调用本函数（不经配置层）时也成立。
+	*/
+	const timeoutMs = Math.min(DRAW_TIMEOUT_MAX_MS, Math.max(3e4, Math.floor(Number(settings?.drawTimeoutMs) > 0 ? Number(settings?.drawTimeoutMs) : DRAW_TIMEOUT_MS)));
 	/**
 	* 单次调用愿意等的时间。
 	*
-	* 只夹**上界**（不该超过总放弃线，超过它的等待没有意义）；下界交给
-	* `host-config` 的 `drawWaitMs` clamp——同一个数在两处各夹一次，上限/下限就会
-	* 各说一套话（`drawTimeoutMs` 的 clamp 早已是本仓库的教训）。
+	* 上界是 `timeoutMs - margin`，**不是** `timeoutMs`：工具的硬护栏取
+	* `waitMs + margin`，若允许两者相等，护栏就会越过 `DRAW_TIMEOUT_MAX_MS`
+	* （配置允许 `drawWaitMs == drawTimeoutMs`，上限 1_800_000 → 护栏 1_810_000），
+	* 且「等待循环先返回」从结构保证退化成「用户不会把两个值设成相等」的运气。
+	* 下界交给 `host-config` 的 `drawWaitMs` clamp——同一个数在两处各夹一次，上限/
+	* 下限就会各说一套话（`drawTimeoutMs` 的 clamp 早已是本仓库的教训）。
 	*/
-	const waitMs = Math.min(timeoutMs, Math.max(1, Math.floor(Number(settings?.drawWaitMs) > 0 ? Number(settings?.drawWaitMs) : DRAW_WAIT_BUDGET_MS)));
+	const waitMs = Math.min(Math.max(1, timeoutMs - DRAW_TOOL_TIMEOUT_MARGIN_MS), Math.max(1, Math.floor(Number(settings?.drawWaitMs) > 0 ? Number(settings?.drawWaitMs) : DRAW_WAIT_BUDGET_MS)));
 	const apiBase = str(settings?.apiBase, "https://api-inference.modelscope.cn/v1");
 	const abortController = new AbortController();
 	const abortIfDisposed = () => {
 		if (isDisposed()) abortController.abort();
 	};
+	const shouldStop = () => {
+		abortIfDisposed();
+		return isDisposed();
+	};
 	/**
 	* 等一个作业，把 {@link awaitDrawTask} 的三种结局翻译成工具结果或错误。
 	*
@@ -3551,7 +3648,8 @@ function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, sett
 			taskId: job.taskId,
 			waitMs,
 			pollIntervalMs,
-			signal: abortController.signal
+			signal: abortController.signal,
+			shouldStop
 		});
 		if (awaited.kind === "failed") {
 			jobs.drop(job.jobId);
@@ -3574,6 +3672,7 @@ function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, sett
 		}
 		const elapsedMs = Date.now() - job.submittedAt;
 		if (elapsedMs >= timeoutMs) throw new Error(describeDrawFailure({ cause: `超过总预算（${Math.round(timeoutMs / 1e3)}s，${polls} 次轮询）仍未拿到结果。上游任务（${job.taskId}）可能仍在生成——实测排队时长在 1–15 分钟间大幅波动，与请求本身无关；注意放弃后原任务的结果不保证还能取回` }));
+		const resumeHint = jobs.get(job.jobId) !== null ? `稍后带 jobId ${job.jobId} 再调用本工具即可继续查询（只查询、不会重复出图；作业表只在本次挂载内有效，重启 DSH 或重挂插件后要重新提交）` : "本次挂载已撤下（插件被卸载/重载），作业表已清空——这一轮之后**不能**再带 jobId 续查；上游任务可能仍在生成，但结果不保证还能取回，重新出图请去掉 jobId 再调用";
 		return {
 			source: "modelscope",
 			status: "pending",
@@ -3581,7 +3680,7 @@ function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, sett
 			model: job.model,
 			url: "",
 			prompt: job.prompt,
-			hint: `仍在生成中（已等 ${Math.round(elapsedMs / 1e3)}s，${polls} 次轮询，task ${job.taskId}）：上游排队通常 1–15 分钟。稍后带 jobId ${job.jobId} 再调用本工具即可继续查询（只查询、不会重复出图）`
+			hint: `仍在生成中（已等 ${Math.round(elapsedMs / 1e3)}s，${polls} 次轮询，task ${job.taskId}）：上游排队通常 1–15 分钟。${resumeHint}`
 		};
 	};
 	return defineTool({
@@ -3645,7 +3744,7 @@ function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, sett
 				text: result?.hint || "图片已生成"
 			}]
 		},
-		timeoutMs: waitMs + 1e4,
+		timeoutMs: waitMs + DRAW_TOOL_TIMEOUT_MARGIN_MS,
 		async execute(params) {
 			if (abortController.signal.aborted || isDisposed()) throw new Error("modelscope draw tool is no longer mounted");
 			const apiKey = await resolveApiKey();
@@ -3745,6 +3844,24 @@ function toPositiveNumber(value) {
 	const n = Number(value);
 	return Number.isFinite(n) && n > 0 ? n : void 0;
 }
+/**
+* 轮询响应里的**瞬态** HTTP 状态码：不判作业死刑，本次等待预算内继续等下一轮。
+*
+* 判据是「同一个物理故障不因表现形态而异」：传输层抛错（ECONNRESET / DNS
+* 解析失败）早就走的是「继续等下一轮」，而同一种 CDN 边缘抖动、上游短暂过载
+* 以 **5xx/429 响应**的形态出现时，旧写法直接判失败、作业出表、进 60s 冷却
+* ——agent 想续查只能重新提交一张图。上游排队窗口实测 1–15 分钟
+* （docs/SPIKE-image-gen.md），那个窗口内的边缘 5xx 是常态噪声，不是终局。
+*
+* 4xx 保持终局：401/403 = 令牌或权限真的没了，404/400 = 任务或端点真的没了
+* ——这些等下去也不会变。deadline 负责收口：瞬态一直持续时耗尽预算后返回
+* `pending`，两段式的续查把手（jobId）不丢。
+* @param {number} status - 轮询响应的 HTTP 状态码。
+* @returns {boolean} 是否按瞬态继续等。
+*/
+function isTransientPollStatus(status) {
+	return status === 408 || status === 429 || status >= 500;
+}
 /** 读 body 文本，读不到给空串（错误分诊不能因为读 body 失败而失败）。 */
 async function safeText(response) {
 	try {
@@ -3899,7 +4016,7 @@ async function resolveService(ctx, service, isDisposed) {
 * 读一次开关，决定是否注册出图工具。
 * @param {object} ctx - Host 上下文。
 * @param {object} wiring - `{ settings, configError, tokenStore, inference, providerStore, publisher, logger }`。
-* @param {object} deps - 测试缝（`loadToolsModule`、`drawFetch`）。
+* @param {object} deps - 测试缝（`loadToolsModule`、`drawFetch`、`pollIntervalMs`）。
 * @returns {Promise<void>}
 */
 async function registerDrawTool(ctx, wiring, deps = {}) {
@@ -3948,6 +4065,8 @@ async function registerDrawTool(ctx, wiring, deps = {}) {
 				drawTimeoutMs: settings.drawTimeoutMs,
 				drawWaitMs: settings.drawWaitMs
 			},
+			...wiring.drawJobs !== void 0 ? { jobs: wiring.drawJobs } : {},
+			...deps.pollIntervalMs !== void 0 ? { pollIntervalMs: deps.pollIntervalMs } : {},
 			isDisposed
 		}));
 		setDrawToolMounted(true);
@@ -5008,12 +5127,13 @@ async function buildSnapshotBody(wiring) {
 		const allowedList = parseAllowedList(enabledIds);
 		const enabledCount = enabledCountOf(allowedList, roster.map((row) => row.id));
 		const contextWindow = await providerStore.contextWindow().catch(() => null);
+		const catalogNote = models.ok ? null : `模型目录读不到：${models.error}`;
 		return {
 			enabled,
 			source,
 			llmAvailable: publisher.state.llmAvailable === true,
 			registered: publisher.state.registered === true,
-			error: typeof publisher.state.error === "string" ? publisher.state.error : null,
+			error: typeof publisher.state.error === "string" ? publisher.state.error : catalogNote,
 			modelCount: roster.length,
 			enabledCount,
 			allowed: allowedList.mode,
@@ -6003,25 +6123,73 @@ function registerRoutes(ctx, wiring) {
 //#endregion
 //#region src/host/index.ts
 /**
-* dsh-connect-modelscope-token-plan — Host 半边（thin router）。
-*
-* 读魔搭 API-Inference 的**本地用量**，并把它与官方魔粒余额一起经一条只读 /api
-* 路由喂给 Client 面板。口径分工：推理响应**不携带**额度头（SPIKE.md §结论 1），但
-* 官方另有魔粒余额端点（`GET {siteBase}/openapi/v1/magicubes/balance`，SPIKE.md
-* 文首后记，2026-10-04 实测可用），面板头条读的是它；本文件下的兄弟模块只负责本地
-* 计数那一半（按模型分布 / 本地趋势 / 429 事件流），回答官方余额答不了的问题。
-* 重活都在专注的兄弟模块里，本文件
-* 只保留 Cordis 入口（name/inject/apply）、wiring 装配与卸载副作用：
-*
-*   - `host-config.ts`        配置契约 + isAdmitted 信任围栏
-*   - `routes.ts`             四条路由的门面（snapshot/models/token/probe）
-*   - `ms-auth.ts`            访问令牌存取（静态钥匙，无登录流）
-*   - `inference-client.ts`   模型目录（零额度）+ probe 调用（带分诊）
-*   - `usage-store.ts`        本地计数：天桶/单模型/事件流（原子写、版本守卫）
-*   - `snapshot-aggregate.ts` 快照聚合（软失败）
-*   - `state-store.ts`        状态文件原子原语
+* dsh-connect-modelscope-token-plan — Host 半边（装配入口）。
+*
+* 本插件的定位是**额度 + provider + 出图 + 上下文窗口策展**的多功能集成（见
+* AGENTS.md「定位变更」），不再是「只做额度信息」的那一版。口径分工：推理响应
+* **不携带**额度头（SPIKE.md §结论 1），但官方另有魔粒余额端点
+* （`GET {siteBase}/openapi/v1/magicubes/balance`，SPIKE.md 文首后记，2026-10-04
+* 实测可用），面板头条读的是它；本文件下的兄弟模块只负责本地计数那一半（按模型
+* 分布 / 本地趋势 / 429 事件流），回答官方余额答不了的问题。
+*
+* 重活都在专注的兄弟模块里，本文件只保留 Cordis 入口（name/inject/apply）、
+* wiring 装配与卸载副作用。兄弟模块按域分组：
+*
+*   **配置与凭据**
+*   - `host-config.ts`        配置契约 + isAdmitted 信任围栏 + 夹取常量
+*   - `switch-precedence.ts`  开关优先级：面板值 > patch 默认
+*   - `ms-auth.ts`            访问令牌存取（静态钥匙，无登录流；唯一凭据出口）
+*
+*   **路由（7 条，`routes.ts` 是门面，`routes/` 下各域一份）**
+*   - `routes/snapshot.ts`    面板轮询的唯一只读路由
+*   - `routes/models.ts`      模型目录
+*   - `routes/token.ts`       令牌保存/忘掉/验证
+*   - `routes/probe.ts`       零额度鉴权探针
+*   - `routes/provider.ts`    provider 开关/清单/窗口/重置
+*   - `routes/draw.ts`        出图开关/模型/重置
+*   - `routes/usage-prefs.ts` 趋势显示窗口
+*   - `routes/http.ts`        CORS / JSON / 错误脱敏的公共辅助
+*   - `routes/paths.ts`       路由路径常量
+*
+*   **数据层（`state-store.ts` 是共用原语）**
+*   - `state-store.ts`        原子写/版本守卫/读缓存/写队列（四个 store 共用）
+*   - `usage-store.ts`        本地计数：天桶/单模型/事件流
+*   - `provider-store.ts`     开关 + 允许清单 + 窗口覆盖的持久化
+*   - `draw-store.ts`         出图开关 + 模型偏好
+*   - `usage-prefs-store.ts`  趋势显示窗口偏好 + `resolveWindowDays` 夹取
+*   - `inference-client.ts`   HTTP 出口：模型目录 + 魔粒余额 + 探针
+*   - `coalesced-fetch.ts`    有界并发缓存（目录/余额/标签共用）
+*   - `context-catalog.ts`    内置上下文窗口策展表（models.dev 交叉真值）
+*
+*   **Provider 注册**
+*   - `llm-models.ts`         目录 → descriptor 映射（peer-free）
+*   - `llm-adapter.ts` / `llm-adapter-core.ts`  适配器装配（core 为三族共享）
+*   - `provider-publish.ts`   发布状态机：队列/disposed 闸/回滚
+*   - `provider-reconcile.ts` desired-state 收敛器（轮询 + 路由统一触发）
+*   - `publish-core.ts`       三族共享的发布原语
+*
+*   **观测与纠正**
+*   - `usage-observer.ts`     真实对话 → 本地计数/事件（观察流出口）
+*   - `llm-error-fix.ts`      429 误判纠正（QUOTA → RATE_LIMIT）
+*   - `llm-retry.ts`          重试策略（按 code 决定退避）
 *   - `codes.ts`              错误分类单一真源
-*   - `usage-observer.ts`     真实对话 → 本地计数/事件（观察流出口，见该文件头）
+*
+*   **出图工具**
+*   - `draw.ts`               协议纯逻辑半边（peer-free）
+*   - `draw-register.ts`      工具注册（挂载时一次性，不可撤销）
+*   - `draw-runtime.ts`       运行时（两段式：提交 → 轮询）
+*   - `draw-jobs.ts`          作业表（本次挂载内有效）
+*   - `draw-tool-state.ts`    缺席原因 + 本次挂载注册位（内存）
+*
+*   **聚合与工具**
+*   - `snapshot-aggregate.ts` 快照聚合（软失败，绝不白屏）
+*   - `doctor.ts`             只读盘点工具
+*   - `util.ts`               通用工具（脱敏/错误消息/类型守卫）
+*   - `types.ts`              Host 侧类型定义
+*
+* 完整的「文件 → 一句话职责 → 关键导出」表在 AGENTS.md 的代码地图里，由
+* test/docs.test.mjs §14 门禁守着（每个 src/*.ts 都必须登记）。本注释只做入口
+* 处的分组索引——**新增兄弟模块时两处都要改**，别让这里再落后一轮。
 *
 * @module dsh-connect-modelscope-token-plan
 */
@@ -6062,6 +6230,7 @@ function apply(ctx, config = {}, deps = {}) {
 		profile,
 		logger: ctx.logger
 	});
+	const drawJobs = createDrawJobs({ resumeWindowMs: settings.drawTimeoutMs });
 	const usagePrefsStore = createFileUsagePrefsStore({
 		profile,
 		logger: ctx.logger
@@ -6098,6 +6267,7 @@ function apply(ctx, config = {}, deps = {}) {
 		inference,
 		providerStore,
 		drawStore,
+		drawJobs,
 		usagePrefsStore,
 		publisher,
 		reconcile,
@@ -6117,6 +6287,7 @@ function apply(ctx, config = {}, deps = {}) {
 		return () => {
 			clearInterval(timer);
 			resetDrawToolNote();
+			drawJobs.dispose();
 			publisher.dispose();
 			publisher.release();
 			for (const off of offs) try {