dsh-connect-modelscope-token-plan 0.2.0 → 0.3.0

package/lib/index.js

@@ -1,6 +1,6 @@
-import { C as redactSecrets, S as pluginError, T as verbatim, a as resolveSettings, b as obj, c as LLM_PROVIDER_ID, d as normalizeEntry, f as resolveAllowedList, g as looksLikeRateLimit, h as hasHardQuotaWordingIn, i as name, n as inject, p as rosterWithAvailability, r as isAdmitted, s as LLM_DISPLAY_NAME, t as PLUGIN_VERSION, u as isVisionModel, v as degrade, w as str, x as optional, y as errMsg } from "./host-config-C4bWNPWU.js";
+import { C as optional, D as verbatim, E as str, S as obj, T as redactSecrets$1, _ as hasHardQuotaWordingIn, a as resolveSettings, b as degrade, c as LLM_PROVIDER_ID, d as isVisionModel, f as normalizeEntry, h as textToImageModelIds, i as name, m as rosterWithAvailability, n as inject, p as resolveAllowedList, r as isAdmitted, s as LLM_DISPLAY_NAME, t as PLUGIN_VERSION, u as imageGenModelIds, v as looksLikeRateLimit, w as pluginError, x as errMsg } from "./host-config.js";
 import { join } from "node:path";
-import { mkdir, open, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 
@@ -64,11 +64,29 @@ function isPlausibleToken(value) {
 * @param {object|Function|null} [options.credentials] - `ctx.credentials` 服务
 *   或其 resolver；**每次使用时解析**（服务可能在本插件挂载之后才注册，
 *   一次性查找会把错误的 "ephemeral" 断言冻进后续每个轮询）。
-* @param {object} [options.env] - 环境源；默认 `process.env`。
+* @param {object} [options.env] - 环境源；**默认 `process.env`**。
+*   测试经 `apply()` 的 `deps.env` 注入 `{}` 以隔离宿主环境——本文件时不能假设
+*   「没有传就是要用真环境」以外的语义，但调用方可以（详见 types.ts 的 env 缝）。
+*
+*   `| undefined` 不是冗余：`tsconfig` 开了 `exactOptionalPropertyTypes`，
+*   「可选」不允许被显式赋值为 `undefined`，而 `apply()` 是原样转发 `deps.env`
+*   （产品侧不传时它就是 `undefined`）。不写这一半，转发点编译不过。
 */
 function createTokenStore({ credentials = null, env = process.env } = {}) {
 	/** 无凭据服务的 Host 的内存兜底。 */
 	const memory = /* @__PURE__ */ new Map();
+	/**
+	* 最后一次零额度探针的结论（`TokenStatus.valid` / `checkedAt` 的唯一生产者）。
+	*
+	* 只活在本进程：重启即回到「未检查过」，那是诚实答案——`valid: null` 的语义本来
+	* 就是「没检查过」，不是「检查过但没结论」。
+	*
+	* **只在令牌换手时清**（`save` / `forget`）：上一次的结论只对**那一把**令牌成立。
+	* 换令牌后留着旧结论，等于让一个关于别的值的判断继续替新令牌说话——正是
+	* `ephemeral` 那条修正反对的「不是判出来的、是碰巧对的」。env 在 DSH 启动时读
+	* 一次，进程内不会换手，所以这两个入口是全部。
+	*/
+	let lastCheck = null;
 	const resolveService = () => {
 		return (typeof credentials === "function" ? credentials() : credentials) ?? null;
 	};
@@ -95,6 +113,7 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 				await service.set(TOKEN_REF, value);
 				memory.set(TOKEN_REF, value);
 			} else memory.set(TOKEN_REF, value);
+			lastCheck = null;
 		},
 		/**
 		* 忘掉面板保存的令牌。env 回退**不动**——清面板引用不能删操作者的 .env。
@@ -107,10 +126,26 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 		*/
 		async forget() {
 			memory.delete(TOKEN_REF);
+			lastCheck = null;
 			const service = resolveService();
 			if (service !== null && typeof service.unset === "function") await service.unset(TOKEN_REF);
 		},
 		/**
+		* 记录一次**零额度探针**的结论（probe 路由是唯一调用方）。
+		*
+		* 只接已经判出来的结论：`true`（200/400，令牌好）或 `false`（401/403，令牌坏）。
+		* 429 / 上游错误 / 配置错误**不调用**——那些回答的是「上游现在忙不忙」或
+		* 「这次请求成没成」，不是「这把令牌好不好」，把它们记进 `valid` 就是把限频
+		* 说成令牌坏（正是 429 分诊那条修正反对的误判）。不调用即留着上一次的结论，
+		* 那是已知的最好答案。
+		*/
+		noteValidity(valid) {
+			lastCheck = {
+				valid,
+				checkedAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+		},
+		/**
 		* 解析当前令牌与来源。返回类型显式注解：这是快照 TokenStatus.source
 		* 联合类型的上游，靠推断会把字面量联合拓宽成 string。
 		* @returns {Promise<{value: string, source: ("credentials"|"memory"|"env"|null)}>}
@@ -144,9 +179,11 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 		},
 		/**
 		* 无秘密的状态描述（快照与面板消费）。
-		* `valid` 恒为 null：本模块不做有效性断言（零额度探针在 probe 路由，
-		* 语义已于 2026-10-04 真机回填——判定 401/403 = 令牌坏、200/400 = 令牌好；
-		* SPIKE.md §结论 5）。
+		*
+		* `valid` / `checkedAt` 来自 `noteValidity`（零额度探针的结论），**本模块自己
+		* 不做有效性断言**——判定规则在 probe 路由（401/403 = 令牌坏、200/400 = 令牌好，
+		* 2026-10-04 真机回填；SPIKE.md §结论 5）。没探过就是 `null`，那不是「无效」，
+		* 是「没检查过」。
 		*
 		* `ephemeral` 答的是「**手里这个值**重启会不会丢」，不是「有没有凭据服务」
 		* ——wire 的定义是前者。曾经只按「服务缺席」置位，于是两种都说谎：没有服务
@@ -159,8 +196,8 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 			return {
 				present: source !== null,
 				source: source === null ? "none" : source,
-				valid: null,
-				checkedAt: null,
+				valid: lastCheck === null ? null : lastCheck.valid,
+				checkedAt: lastCheck === null ? null : lastCheck.checkedAt,
 				ephemeral: source === "memory"
 			};
 		}
@@ -170,16 +207,14 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 //#endregion
 //#region src/host/state-store.ts
 /**
-* 状态文件公共原语 —— 把本插件的各 store（usage-store）从
-* 各自手写的同一段"版本载荷 + temp 文件 + rename 原子 + 0600 + 损坏即忽略"
-* 收敛到这里（家规：peer-free、离线可测）。。
-*
-* 第二步收敛的是**读缓存**：provider / draw 早有 1s TTL，而 catalog 完全没有
-* （进程内永不失效）——同一个「两个进程共享一个 state 目录」的问题修了两个、
-* 漏了第三个。现在统一走 {@link createStateReadCache}，一个 TTL 三个调用方。
+* 状态文件公共原语。**TL;DR**：本文件只做三件事——`dshHome`/`stateDir`（定位
+* 状态目录）、`profileSegment`（按 profile 分段路径）、以及 {@link createStateReadCache}
+* （统一读缓存）。其余一切遵守下方「行为约定」。
 *
-* peer-free 与四个 store 同纪律：不 import 任何 Host peer，纯 `node:fs`，
-* 离线可测（store.test.mjs 直接注入 dir 构造即可）。
+* 把本插件各 store（usage-store / provider / draw）各自手写的同一段
+* "版本载荷 + temp 文件 + rename 原子 + 0600 + 损坏即忽略" 收敛到这里。
+* 家规：peer-free（不 import 任何 Host peer，纯 `node:fs`）、离线可测
+* （store.test.mjs 直接注入 dir 构造即可）。
 *
 * 行为约定（与本插件 store 的约定逐一对齐）：
 *   - 目录：`$DSH_HOME/state/<name>`——与 Host 自己的目录并列，而不是在
@@ -187,29 +222,32 @@ function createTokenStore({ credentials = null, env = process.env } = {}) {
 *   - 写：临时文件（0600，owner-only）→ `rename` 原子落位。**失败抛错**，
 *     是否吞错是各 store 的语义（usage-store 面对只读 Home 选择吞、
 *     provider 面板开关交给调用方的错误路径），原语不做决定。
-*   - 临时名：进程 + 时间戳 + 随机 UUID 后缀。固定临时名会让两个 Host 进程的
-*     写落到同一路径、互相 `rename` 掉对方写了一半的文件；同一进程同一毫秒的
-*     两次异步写也会撞名（`writeFile` 截断覆盖后一次 `rename` 静默丢写），
-*     随机后缀让每个 temp 路径唯一，`rename` 原子性借此成立（见 `temporaryOf`）。
-*     此前的写法曾只有进程 + 时间戳，同毫秒并发写会静默丢一条。
+*   - 临时名：进程 + 时间戳 + 随机 UUID 后缀。随机后缀让每个 temp 路径唯一，
+*     `rename` 原子性借此成立（见 `temporaryOf`）。
 *   - 读：缺失、不可读、非 JSON 一律返回 `null`——"损坏即忽略"的方向。是否
 *     缓存、缓存多久由 {@link createStateReadCache} 决定，不是每个 store 各自的
 *     即兴实现。
 *
+* ## 演变记录（历史，非契约）
+* 1. 第一步收敛的是上述「版本载荷 + 临时文件 + 原子落位」；临时名此前只有
+*    进程 + 时间戳，同毫秒并发写会静默丢一条，故加随机后缀。
+* 2. 第二步收敛的是**读缓存**：provider / draw 早有 1s TTL，而 catalog 完全
+*    没有（进程内永不失效）——同一个「两个进程共享一个 state 目录」的问题修了
+*    两个、漏了第三个。现在统一走 {@link createStateReadCache}，一个 TTL 三个调用方。
+*
 * @module dsh-connect-modelscope-token-plan/state-store
 */
 /**
-* The DSH home: `$DSH_HOME` when the operator exported one, else `~/.dsh`.
-* @returns {string} the home directory.
+* DSH 主目录：操作者导出了 `DSH_HOME` 就用它，否则回落到 `~/.dsh`。
+* @returns {string} 主目录。
 */
 function dshHome() {
 	return str(process.env.DSH_HOME, join(homedir(), ".dsh"));
 }
 /**
-* Where this plugin keeps state: `$DSH_HOME/state/<name>`.
-* @param {string} name - the plugin's own state directory name
-*   (`host-config.ts`'s `name`).
-* @returns {string} the directory.
+* 本插件存放状态的位置：`$DSH_HOME/state/<name>`。
+* @param {string} name - 插件自己的状态目录名（即 `host-config.ts` 的 `name`）。
+* @returns {string} 目录路径。
 */
 function stateDir(name) {
 	return join(dshHome(), "state", name);
@@ -229,9 +267,9 @@ function stateDir(name) {
 const PROFILE_SEGMENT_MAX = 64;
 const PROFILE_SEGMENT_RE = /^(?!\.)[A-Za-z0-9._-]+$/;
 /**
-* Is this string safe to use as ONE path segment?
-* @param {unknown} value - candidate profile name.
-* @returns {boolean} true when it survives {@link PROFILE_SEGMENT_RE}.
+* 该字符串能否安全地作为**一个**路径段使用？
+* @param {unknown} value - 候选 profile 名。
+* @returns {boolean} 通过 {@link PROFILE_SEGMENT_RE} 即为 true。
 */
 function isProfileSegment(value) {
 	if (typeof value !== "string") return false;
@@ -263,8 +301,8 @@ function isProfileSegment(value) {
 *
 * 取到 = 调用方据此分段；取不到 = **退回当前的全局路径**，行为零漂移。
 *
-* @param {object} [ctx] - the Cordis context the Host handed `apply()`.
-* @returns {string|null} the profile name, or `null` when unavailable/unsafe.
+* @param {object} [ctx] - Host 交给 `apply()` 的 Cordis context。
+* @returns {string|null} profile 名，取不到或不安全时为 `null`。
 */
 function profileSegment(ctx) {
 	if (ctx === null || typeof ctx !== "object") return null;
@@ -510,22 +548,46 @@ async function readStateJson(file) {
 	}
 }
 /**
-* Read the persisted `version` field of one state file, or `null` when it is
-* absent, unreadable, non-JSON, or carries no numeric `version`.
+* Read the persisted `version` field of one state file.
 *
 * This is the ADR-006 write-side guard's probe: a writer must know what it is
-* about to overwrite. "No version" is the same as "no record" (nothing to
-* protect), while a NUMERIC version this build does not recognise means the
-* file was written by a NEWER build and must not be clobbered.
+* about to overwrite. Three outcomes, and the difference between the first two
+* is load-bearing:
+*
+*   - `null` — ABSENT (ENOENT), non-JSON, or carrying no numeric `version`.
+*     Nothing here the guard could protect, so a write belongs: a corrupt file
+*     must stay replaceable, or an operator would be stuck with it forever.
+*   - a number — the version on disk. One this build does not recognise was
+*     written by a NEWER build and must not be clobbered.
+*   - **throws** — the path EXISTS but could not be read (EACCES/EBUSY/EIO, or a
+*     directory sitting at the path). The guard must read that as "there is
+*     something here and I cannot see it", never as "nothing stored": collapsing
+*     it into `null` made the anti-clobber guard fail OPEN, so the very
+*     downgrade it exists to prevent came through that seam.
 *
 * Kept apart from `readStateJson` on purpose: the guard needs the version even
-* when the rest of the payload is unparseable, and it must not depend on any
-* store's parse semantics.
+* when the rest of the payload is unparseable, it must not depend on any store's
+* parse semantics, and it must NOT inherit the read path's deliberate "anything
+* unrecognised reads as not set" permissiveness — that permissiveness is right
+* for a reader and wrong for a writer.
 * @param {string} file - the state file path.
-* @returns {Promise<number|null>} the persisted version, or `null`.
+* @returns {Promise<number|null>} the persisted version, or `null` when absent/unusable.
+* @throws when the path exists but cannot be read — callers must refuse to write.
 */
 async function readStateVersion(file) {
-	const raw = await readStateJson(file);
+	let text;
+	try {
+		text = await readFile(file, "utf8");
+	} catch (error) {
+		if (error?.code === "ENOENT") return null;
+		throw error;
+	}
+	let raw;
+	try {
+		raw = JSON.parse(text);
+	} catch {
+		return null;
+	}
 	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
 	const version = raw.version;
 	return typeof version === "number" ? version : null;
@@ -556,7 +618,10 @@ function isKnownStateVersion(version, known) {
 *
 * @module dsh-connect-modelscope-token-plan/codes
 */
-/** 面板按它分流的稳定码表。 */
+/**
+* 面板按它分流的稳定码表 —— Client 的 `GUIDANCE_BY_CODE` 以这份表的键为契约，
+* 新增/改名必须同步 Client，否则内部错误没有引导文案（见下 `INTERNAL_ERROR`）。
+*/
 const CODE = Object.freeze({
 	CONFIG_ERROR: "config_error",
 	NETWORK_ERROR: "network_error",
@@ -573,19 +638,27 @@ const CODE = Object.freeze({
 	* 「每个键必须在 CODE 里」），最需要人看的内部错误反而没有引导文案。
 	* 正式收进码表，两端从此同一份真源。
 	*/
-	INTERNAL_ERROR: "internal_error"
+	INTERNAL_ERROR: "internal_error",
+	/**
+	* Client 自产码：Host 响应无法解读成快照（非 JSON / 缺 ok 字段）时，
+	* 面板用它走引导文案，而不是把裸英文串（"unexpected payload"）上屏。
+	*
+	* 本表是 `GUIDANCE_BY_CODE` 的键集真源（panel.test §2 钉「每个键必须在
+	* CODE 里」、§3c 钉「每个码必须有引导」）——新增 client 码必须同时进
+	* 这张表，两侧才同步。
+	*/
+	PAYLOAD_ERROR: "payload_error"
 });
 /**
 * 把上游 HTTP 状态归类成稳定码。
 *
 * 401/403 → AUTH_ERROR（换令牌能修，绝不自动重试——魔搭没有锁号问题，
 * 但重试一个坏令牌只会刷屏）；429 由调用方先走 {@link classifyRateLimit}
-* 分诊，这里只兜底；5xx → UPSTREAM_ERROR；其余 → NETWORK_ERROR。
+* 分诊，这里只兜底；其余 4xx/5xx → UPSTREAM_ERROR；低于 400 → NETWORK_ERROR。
 */
 function classifyStatus(status) {
 	if (status === 401 || status === 403) return CODE.AUTH_ERROR;
 	if (status === 429) return CODE.RATE_LIMITED;
-	if (status >= 500) return CODE.UPSTREAM_ERROR;
 	if (status >= 400) return CODE.UPSTREAM_ERROR;
 	return CODE.NETWORK_ERROR;
 }
@@ -684,6 +757,19 @@ function parseRetryAfterMs(headers, message) {
 function localDateKey(now) {
 	return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
 }
+/**
+* 路径在不在（任何 fs 错误都读作「不在」——存在性问的是能不能 `ls` 到它。
+* EACCES 让 `stat` 失败时，真相其实是「在，只是看不见」，而对下面的判据来说
+* 那同样不能被当成「没有记录」）。
+*/
+async function pathExists(file) {
+	try {
+		await stat(file);
+		return true;
+	} catch {
+		return false;
+	}
+}
 const STATE_VERSION = 1;
 const KNOWN_VERSIONS = [STATE_VERSION];
 /** 解析并校验磁盘载荷；形状不对读作 null（损坏即忽略），并标记异常。 */
@@ -790,7 +876,16 @@ function createFileUsageStore({ name, profile = null, trendDays = 14, maxEvents
 	* @returns `true` = 磁盘版本比本构建新（写必须拒绝）；`false` = 可以写。
 	*/
 	const diskVersionBlocksWrites = async () => {
-		const onDisk = await readStateVersion(file);
+		let onDisk;
+		try {
+			onDisk = await readStateVersion(file);
+		} catch (error) {
+			const note = `usage-state: usage.json exists but cannot be read (${redactSecrets$1(errMsg(error))})`;
+			if (!readOnly) logger?.warn?.(`${name}: ${note} — recording disabled to avoid clobbering`);
+			anomaly = note;
+			readOnly = true;
+			return true;
+		}
 		if (onDisk !== null && !isKnownStateVersion(onDisk, KNOWN_VERSIONS)) {
 			const note = `usage-state: on-disk version ${onDisk} is newer than this build knows`;
 			if (!readOnly) logger?.warn?.(`${name}: ${note} — recording disabled to avoid clobbering`);
@@ -823,7 +918,7 @@ function createFileUsageStore({ name, profile = null, trendDays = 14, maxEvents
 	const enqueue = (mutate) => {
 		const run = writeChain.then(async () => {
 			if (await diskVersionBlocksWrites()) return;
-			const payload = (loaded ? current : await cache.read() ?? null) ?? {
+			const payload = await readThrough() ?? (loaded ? current : null) ?? {
 				version: STATE_VERSION,
 				days: {},
 				models: {},
@@ -891,16 +986,47 @@ function createFileUsageStore({ name, profile = null, trendDays = 14, maxEvents
 				}, ...payload.events].slice(0, maxEvents);
 			});
 		},
-		/** 今天（本地时区）的账户级计数；没有任何记录时是 0，不是 null。 */
+		/**
+		* 今天（本地时区）的账户级计数。
+		*
+		* 三种答案，三种含义，**不可合并**（wire.ts DailyUsage 的语义基线）：
+		*   - `0` —— 确实一次都没有（没记录，或今天还没有桶）；这是可信的日常值；
+		*   - `null` —— **读不到**：文件在，但本构建看不懂它（损坏 / 形状不对 / 更新
+		*     构建写的版本 / 存在却不可读）。面板渲染「—」；
+		*   - 数字 —— 今日次数。
+		*
+		* 判据是「文件在不在」而不是「载荷读没读出来」：**文件不存在**才是真实的 0
+		* （这台 Host 从未经本插件调用过，不是数据丢失），而**文件在却读成空**代表
+		* 我们失去了那部分信息——把它报成 0 会让操作者以为今天没调用过，真相是他
+		* 不知道。
+		*
+		* 这是 2026-10-16 补上的一块拼图：`routes.test.mjs` 早有一条
+		* 「本地计数读不到 → null，绝不是 0」的断言，但它只能用一个**会抛错的桩**
+		* 造出那条路径（注释原话：「挂载的真实 store 造不出『读的时候抛』」）——
+		* 真实 store 把所有读失败都吞成了空载荷。于是 null 那份语义在 wire.ts、
+		* `cards.ts`、`snapshot-aggregate.ts` 里写了三遍，却从未在本机真的产出过。
+		*
+		* @returns {{dateKey: string, calls: number|null, tokens: number|null}}
+		*/
 		async daily() {
-			const day = (await cache.read())?.days[localDateKey(now())] ?? null;
+			const payload = await cache.read();
+			const dateKey = localDateKey(now());
+			if (payload === null) {
+				const stored = await pathExists(file);
+				return {
+					dateKey,
+					calls: stored ? null : 0,
+					tokens: stored ? null : 0
+				};
+			}
+			const day = payload.days[dateKey] ?? null;
 			return day === null ? {
-				dateKey: localDateKey(now()),
+				dateKey,
 				calls: 0,
 				tokens: 0
 			} : {
 				...day,
-				dateKey: localDateKey(now())
+				dateKey
 			};
 		},
 		/** 今天的单模型计数（只含有记录的模型，dayCalls/dayTokens 口径，均跨日清零）。 */
@@ -1005,6 +1131,13 @@ const MAX_CACHE_AGE_MS = 36e5;
 * flight's answer would be served to the account that just signed in.
 * Hanging the counters off the map makes every instance over that map share
 * one generation state, so the guard holds no matter how the caller builds it.
+*
+* `seq` is the ONE monotonic source both bumps draw from (see
+* {@link clearCoalescedFetch}): `global` is a high-water mark that only a global
+* clear moves, and `keys` holds one absolute number per individually-cleared
+* key. `keys` is therefore bounded by the number of distinct keys cleared since
+* the last global clear — not swept, because a per-key number must outlive any
+* in-flight flight born under it, while a later global clear wipes them all.
 */
 const GENERATIONS = /* @__PURE__ */ new WeakMap();
 /** The (created-on-demand) generation state belonging to one cache map. */
@@ -1013,6 +1146,7 @@ function generationsOf(cache) {
 	if (state === void 0) {
 		state = {
 			global: 0,
+			seq: 0,
 			keys: /* @__PURE__ */ new Map()
 		};
 		GENERATIONS.set(cache, state);
@@ -1034,14 +1168,15 @@ function generationsOf(cache) {
 */
 function clearCoalescedFetch(cache, inflight, key) {
 	const gens = generationsOf(cache);
+	gens.seq += 1;
 	if (key === void 0) {
-		gens.global += 1;
+		gens.global = gens.seq;
 		cache.clear();
 		inflight.clear();
 		gens.keys.clear();
 		return;
 	}
-	gens.keys.set(key, (gens.keys.get(key) ?? gens.global) + 1);
+	gens.keys.set(key, gens.seq);
 	cache.delete(key);
 	inflight.delete(key);
 }
@@ -1116,6 +1251,66 @@ function createCoalescedFetch(options = {}) {
 	};
 }
 
+//#endregion
+//#region src/host/context-catalog.ts
+/**
+* 内置上下文窗口策展表——魔搭目录不声明窗口时的第三方真值来源。
+*
+* 魔搭 `/v1/models`（及模型详情端点）只回基础标识字段（id/object/owned_by/
+* created + Tasks 标签），没有窗口字段；未声明窗口的条目会一路落到
+* `FALLBACK_CONTEXT_WINDOW`（128k）。这张表在「用户全局档位」之外补第三级
+* 真值：目录声明 > 用户覆盖 > **策展表** > 兜底。
+*
+* 数据来自 models.dev 聚合（github.com/anomalyco/models.dev，MIT；api.json
+* 构建产物）。魔搭 provider 自身在 api.json 只有 7 个不在当前目录的旧模型，
+* 所以每条真值取的是**同 id 模型在各厂自家 host 下的主流 limit.context**——
+* 跨 host 抄写的开量窗口是模型出厂规格，不是各网关的部署配额，取多数而非
+* 最大值：个别网关把窗口抄大（如 openrouter 抄 1M）不代表魔搭侧真开那么宽。
+*
+* 维护纪律：
+* 1. 只收**当前魔搭目录里真实存在**的 id（2026-10-16 实拉 `/v1/models` 全集
+*    37 个中筛出 19 个）；目录下架的条目应随手删除，表不是历史档案。
+* 2. 每条注明来源 host 与核对日期；有多个数据源时写主流值并留离群说明。
+* 3. 覆盖优先级由 `curatedWindowOf` 的调用方（inference-client 打标）保证：
+*    目录声明过窗口的条目不进打标，策展表永不推翻平台声明。
+* 4. 生图/语音模型（Qwen-Image-Edit、ACE-Step 等）无对话上下文，不收。
+*/
+/** id → 标称上下文窗口（tokens）。键必须与魔搭目录 id 逐字一致。 */
+const CURATED_CONTEXT_WINDOWS = {
+	"deepseek-ai/DeepSeek-V4-Flash-0731": 1048576,
+	"deepseek-ai/DeepSeek-V4-Pro": 1048576,
+	"deepseek-ai/DeepSeek-V4-Pro-0813": 1048576,
+	"deepseek-ai/DeepSeek-V4.1-Flash": 1048576,
+	"meituan-longcat/LongCat-Flash-Lite": 256e3,
+	"MiniMax/MiniMax-M1-80k": 1e6,
+	"MiniMax/MiniMax-M3": 1048576,
+	"nex-agi/Nex-N2.5-mini": 262144,
+	"nex-agi/Nex-N2.5-Pro": 262144,
+	"Qwen/Qwen3.5-122B-A10B": 262144,
+	"Qwen/Qwen3.5-27B": 262144,
+	"Qwen/Qwen3.5-35B-A3B": 262144,
+	"Qwen/Qwen3.5-397B-A17B": 262144,
+	"Qwen/Qwen3.8-27B": 262144,
+	"Qwen/Qwen3.8-Flash-Next": 262144,
+	"stepfun-ai/Step-3.5-Flash": 262144,
+	"stepfun-ai/Step-3.7-Flash": 262144,
+	"ZhipuAI/GLM-4.7-Flash": 2e5,
+	"ZhipuAI/GLM-5.2": 1e6
+};
+/**
+* 查策展窗口：命中返回正数，未命中返回 null（调用方继续走兜底）。
+*
+* 只认逐字 id——不做大小写/前后缀模糊匹配，宁可查不到落兜底，也不把
+* 相近 id 的窗口张冠李戴。值合法性再挡一道（表内只应出现正数）。
+* @param {string} id - 模型 id（魔搭目录原样拼写）。
+* @returns {number|null} 标称窗口，未收录为 null。
+*/
+function curatedWindowOf(id) {
+	if (typeof id !== "string" || id === "") return null;
+	const value = CURATED_CONTEXT_WINDOWS[id];
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
+}
+
 //#endregion
 //#region src/host/inference-client.ts
 /**
@@ -1177,7 +1372,7 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 			});
 		} catch (error) {
 			if (error instanceof Error && error.name === "AbortError") throw pluginError(CODE.TIMEOUT_ERROR, "modelscope request timed out");
-			throw pluginError(CODE.NETWORK_ERROR, redactSecrets(errMsg(error)));
+			throw pluginError(CODE.NETWORK_ERROR, redactSecrets$1(errMsg(error)));
 		} finally {
 			clearTimeout(timer);
 		}
@@ -1245,15 +1440,34 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 		* cacheSeconds。返回归一后的目录条目（entries，M4 用来建 descriptor）与
 		* 派生的 id 列表（ids，旧消费方继续可用）——两条路线读同一份条目，不会漂移；
 		* 形状漂移抛 UPSTREAM_ERROR 并带 detail。
+		*
+		* `contextOverride`（tokens）是面板保存的全局上下文窗口覆盖：非 null 时在
+		* 归一**之前**改写每条原始条目——删掉目录可能携带窗口的四个原始拼写键、写上
+		* `contextWindow`。这是唯一能可靠生效的注入点：`normalizeEntry` 按
+		* `context_length/context_window/contextWindow/max_context_tokens` 顺序读
+		* 首个正数，任何只改归一后字段的窄打标都会被 `...source` 展开里的旧键回读
+		* 污染。删四键再写宽形状键，不依赖键序，目录声明与覆盖不可能同时在场。
+		* descriptor、roster、catalogSignature 都从这份归一条目派生，一处打标全链
+		* 路生效；签名含窗口值，覆盖变化自动触发重新注册。
+		*
+		* 覆盖值**参与缓存键**：coalesced 缓存里存的条目已是打标后的形状，若仍用
+		* 字面量 `"models"` 键，保存覆盖后的一个 TTL 内会读到未打标的旧条目（面板
+		* 显示变了、注册却没变）。带指纹后不同覆盖值各自缓存，互不串味。
+		*
+		* 窗口三级真值链（fetchModels 内单点判定）：目录声明 > 用户覆盖 >
+		* **策展表**（context-catalog，models.dev 交叉真值，零网络依赖）> 兜底
+		* 128k。目录声明过的条目任何下层都不碰；策展表只在用户没设覆盖时兜在
+		* 兜底之前——它是「更聪明的 128k」，不是新权威。
+		* @param {number|null} [contextOverride] - 全局窗口覆盖（tokens），null = 跟随目录。
 		*/
-		async fetchModels() {
+		async fetchModels(contextOverride) {
 			const url = settings.apiBase + "/models";
-			return await read("models", async () => {
+			return await read(`models:${contextOverride ?? "catalog"}`, async () => {
 				const response = await fetchWithTimeout(url, { method: "GET" });
 				if (!response.ok) {
 					const message = await readErrorMessage(response);
 					const code = classifyStatus(response.status);
-					throw pluginError(code, redactSecrets("model catalog failed with HTTP " + String(response.status) + (message === "" ? "" : ": " + message)));
+					throw pluginError(code, redactSecrets$1("model catalog failed with HTTP " + String(response.status) + (message === "" ? "" : ": " + message)));
 				}
 				const json = await response.json().catch(() => null);
 				if (json === null || typeof json !== "object" || json.object !== "list" || !Array.isArray(json.data)) throw pluginError(CODE.UPSTREAM_ERROR, "model catalog shape drifted (expected {object:'list', data:[...]})");
@@ -1265,10 +1479,34 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 				const entries = raws.map((raw) => {
 					const id = str(raw.id, "");
 					const tags = tagsById.get(id) ?? [];
-					return normalizeEntry({
+					const source = {
 						...raw,
 						tasks: tags.length > 0 ? tags : void 0
-					});
+					};
+					const CONTEXT_KEYS = [
+						"context_length",
+						"context_window",
+						"contextWindow",
+						"max_context_tokens"
+					];
+					if (!CONTEXT_KEYS.some((key) => {
+						const value = source[key];
+						return typeof value === "number" && Number.isFinite(value) && value > 0;
+					})) {
+						if (contextOverride != null) {
+							for (const key of CONTEXT_KEYS) delete source[key];
+							source.contextWindow = contextOverride;
+							source.__contextSource = "override";
+						} else {
+							const curated = curatedWindowOf(id);
+							if (curated !== null) {
+								for (const key of CONTEXT_KEYS) delete source[key];
+								source.contextWindow = curated;
+								source.__contextSource = "curated";
+							}
+						}
+					}
+					return normalizeEntry(source);
 				}).filter((entry) => entry.id !== "");
 				return {
 					entries,
@@ -1298,7 +1536,7 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 				if (!response.ok) {
 					const message = await readErrorMessage(response);
 					const code = classifyStatus(response.status);
-					throw pluginError(code, redactSecrets("magicube balance failed with HTTP " + String(response.status) + (message === "" ? "" : ": " + message)));
+					throw pluginError(code, redactSecrets$1("magicube balance failed with HTTP " + String(response.status) + (message === "" ? "" : ": " + message)));
 				}
 				const json = await response.json().catch(() => null);
 				const data = json !== null && typeof json === "object" ? json.data : null;
@@ -1314,8 +1552,9 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 			}, settings.cacheSeconds * 1e3);
 		},
 		/**
-		* 一次 probe 调用：故意缺 messages 的请求，预期 401（令牌坏）先于 400
-		* （请求坏）返回，**零额度**鉴权探针（语义已真机回填，SPIKE.md）。
+		* 一次 probe 调用：故意缺 messages 的请求（**零额度**鉴权探针，语义已真机
+		* 回填，SPIKE.md）。魔搭**不先校验 messages**——缺 messages 返回 200（空壳）
+		* 而非 400，故判定规则是 401/403 = 令牌坏、200/400 = 令牌好、429 = 限频中。
 		*
 		* 失败抛 pluginError；调用方（probe 路由）负责把它记进事件流。
 		*/
@@ -1339,14 +1578,14 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 			const elapsedMs = Date.now() - startedAt;
 			if (response.status === 401 || response.status === 403) {
 				const message = await readErrorMessage(response);
-				throw pluginError(CODE.AUTH_ERROR, redactSecrets(message === "" ? "token rejected (HTTP 401/403)" : message));
+				throw pluginError(CODE.AUTH_ERROR, redactSecrets$1(message === "" ? "token rejected (HTTP 401/403)" : message));
 			}
 			if (response.status === 429) {
 				const message = await readErrorMessage(response);
 				const retryAfterMs = parseRetryAfterMs(response.headers, message);
 				const triage = classifyRateLimit(message);
 				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);
+				throw pluginError(triage === "quota" ? CODE.QUOTA_EXCEEDED : CODE.RATE_LIMITED, redactSecrets$1(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)");
 			response.body?.cancel();
@@ -1389,16 +1628,32 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 * Integrity follows `state-store.ts`: a versioned payload, a temp file plus an
 * atomic rename (two Host processes can share the directory), owner-only
 * modes, and "anything unrecognised reads as not set" — a corrupted or
-* downgraded file costs one re-toggle, never a crash.
+* downgraded file costs one re-toggle, never a crash. The write side refuses
+* to overwrite a version this build cannot read (ADR-006); the read side stays
+* permissive but REPORTS the disagreement via `versionNote()`, because for the
+* allow-list "unreadable" and "never saved" would otherwise collapse to the
+* same answer — and that answer is "offer every model".
 *
 * The allow-list's empty-vs-absent distinction is the one this module guards:
 * an EMPTY list means "no filter, offer every model", while `HIDE_ALL_MODELS`
 * (`llm-models.ts`) is the caller-side sentinel for "offer nothing". Neither
 * spelling is stored here as `null` — absence of a saved list reads as "no
-* filter", which is the only safe default for a fresh install.
+* filter", which is the only safe default for a fresh install. A foreign file
+* reads the same way, which is precisely why `versionNote()` exists.
 *
 * @module dsh-connect-modelscope-token-plan/provider-store
 */
+/**
+* The "nothing stored" payload. Every absent / unreadable / foreign read
+* collapses here, so the three call sites that produce it stay in step instead
+* of each spelling out the same three `null`s.
+*/
+const EMPTY_PAYLOAD$1 = {
+	enabled: null,
+	enabledIds: null,
+	contextWindow: null,
+	version: null
+};
 /** Shape version, bumped when the persisted form changes incompatibly. */
 const PROVIDER_VERSION = 1;
 /**
@@ -1406,12 +1661,36 @@ const PROVIDER_VERSION = 1;
 * historical ones. Bumping {@link PROVIDER_VERSION} means adding the new number
 * here too — otherwise this build would refuse its own newest files.
 *
-* This is the ADR-006 write-side guard's whitelist: an on-disk version not in
-* this list was written by a NEWER build, and must not be clobbered (see
-* {@link writePayload}).
+* This list is asked in THREE places:
+*   - the write side ({@link writePayload}, ADR-006): an on-disk version not in
+*     this list was written by a NEWER build and must not be clobbered. That
+*     caller asks `isKnownStateVersion(existing, ...)` rather than
+*     {@link isKnownProviderVersion} on purpose — it must also admit `null`
+*     ("no file at all"), which is the one situation where a write belongs.
+*   - the READ side ({@link parseAt}) and the report ({@link versionNote} /
+*     {@link describeProviderPayload}), which ask {@link isKnownProviderVersion}.
+* Keeping the read side and the report on one predicate is what makes them
+* unable to disagree about what a foreign version means.
 */
 const KNOWN_PROVIDER_VERSIONS = [1];
 /**
+* Whether this build can read a file declaring `version`.
+*
+* THE single answer to that question. Note it is deliberately NOT
+* `version === PROVIDER_VERSION`: the whitelist includes shapes this build can
+* read but no longer writes, so comparing against the write version would make a
+* version bump unreadable-of-its-own-files. The original bug behind this function
+* was exactly that split — `parseAt` compared against the write version while the
+* report asked the whitelist, so a bumped build read its own v1 files as "not
+* set" while its report said "nothing to say": the silent collapse the read side
+* exists to kill, resurrected by the upgrade procedure.
+* @param {unknown} version - the value read off disk (may not be a number at all).
+* @returns {boolean}
+*/
+function isKnownProviderVersion(version) {
+	return typeof version === "number" && KNOWN_PROVIDER_VERSIONS.includes(version);
+}
+/**
 * The directory this plugin's state lives in — per-profile when the Host names
 * one, shared otherwise. Unlike the THROTTLE, which is deliberately shared
 * across profiles, this answers "does THIS profile want the provider registered"
@@ -1431,6 +1710,18 @@ function normalizeEnabled(raw) {
 	return typeof raw === "boolean" ? raw : null;
 }
 /**
+* Normalize a context-window value: a positive finite number, or `null`
+* ("follow the catalog"). Anything else — strings, zero, negative, NaN,
+* Infinity — reads as no override, mirroring how {@link normalizeEnabled}
+* answers "nothing usable" instead of inventing a default.
+* @param {unknown} raw - the persisted or posted value.
+* @returns {number|null} the window in tokens, or `null` when nothing usable.
+*/
+function normalizeContextWindow(raw) {
+	if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) return null;
+	return raw;
+}
+/**
 * Normalize a persisted allow-list: an array of non-empty strings, de-duplicated
 * and order-preserved. Anything else reads as "no saved list".
 *
@@ -1454,6 +1745,33 @@ function normalizeEnabledIds(raw) {
 	return out;
 }
 /**
+* Resolve the allow-list to publish/display, from the persisted value and the
+* list this process last published.
+*
+* THE single answer to "which list wins", so that every consumer asks it the
+* same way: a READABLE persisted list wins — including an EMPTY one, because
+* this module's contract defines `[]` as "no filter, offer every model" — and
+* the in-memory list is consulted only when the persisted side could not be read
+* at all (the caller's `.catch` turns a rejection into `null`).
+*
+* The three call sites used to spell this out separately, and two of them had
+* drifted: `snapshot-aggregate.ts` and `routes/provider.ts` honoured an empty
+* persisted list, while `index.ts` treated it as "no answer" and republished the
+* remembered list. So after the operator deleted `provider.json` (the reset
+* `versionNote` itself recommends) the panel reported `allowed: "all"` — its
+* `enabledCount` counting every model — while the poller kept registering the
+* OLD restriction: the panel and the Host disagreeing about what is served,
+* which is precisely what the publish queue and the idle guards exist to
+* prevent. One copy now, asked by all three.
+* @param {unknown} stored - the persisted list, or `null` when unreadable.
+* @param {unknown} remembered - `publisher.state.enabledIds` (last published).
+* @returns {string[]} the list to use.
+*/
+function resolveEnabledIds(stored, remembered) {
+	if (Array.isArray(stored)) return stored;
+	return Array.isArray(remembered) ? remembered : [];
+}
+/**
 * The file-backed provider switch + allow-list.
 * @param {object} [options]
 * @param {string} [options.dir] - override the state directory (tests).
@@ -1483,7 +1801,14 @@ function createFileProviderStore(options = {}) {
 	*   decides whether to surface the refusal to a user.
 	*/
 	const writePayload = async (body) => {
-		const existing = await readStateVersion(filePath);
+		let existing;
+		try {
+			existing = await readStateVersion(filePath);
+		} catch (error) {
+			const reason = `provider: refusing to overwrite provider.json (cannot read it: ${redactSecrets$1(errMsg(error))})`;
+			degrade(reason, null, logger, null);
+			return reason;
+		}
 		if (!isKnownStateVersion(existing, KNOWN_PROVIDER_VERSIONS)) {
 			const reason = `provider: refusing to overwrite provider.json holding version ${existing} (this build knows ${KNOWN_PROVIDER_VERSIONS.join("/")})`;
 			degrade(reason, null, logger, null);
@@ -1495,22 +1820,73 @@ function createFileProviderStore(options = {}) {
 		return null;
 	};
 	const legacyFile = dir === void 0 && profile ? join(stateDir(name), "provider.json") : null;
-	/** Read ONE payload off the disk, shape-checked. */
-	const parsePayload = async () => {
-		const raw = await readStateJson(filePath);
-		const source = obj(raw);
-		if (source.version !== 1) return {
+	/**
+	* Read ONE payload off the disk, shape-checked.
+	*
+	* "Can this build read it" is asked through {@link isKnownProviderVersion} —
+	* the same predicate the report and the write guard use. Comparing against
+	* {@link PROVIDER_VERSION} instead would say "cannot read" about the OLDEST
+	* shapes this build still knows, which is exactly wrong when it is bumped:
+	* the header's upgrade rule adds the new number to {@link KNOWN_PROVIDER_VERSIONS},
+	* so a v1 file must stay readable while v2 is written. Getting that wrong
+	* makes this reader disagree with {@link versionNote} — reads "not set" while
+	* the note says "nothing to say", which is the silent collapse this module
+	* exists to kill. That split once existed in production code for one release.
+	*
+	* A version this build cannot read reads as EMPTY, but REMEMBERS which version
+	* it was. The ADR-006 guard already refuses to overwrite such a file, so the
+	* read side has to be able to say "there is an answer in there, it just is
+	* not one we can see" — collapsing it to "never saved" is what made a saved
+	* allow-list look like a deliberate "offer every model". See {@link versionNote}.
+	*/
+	const parseAt = async (file) => {
+		const source = obj(await readStateJson(file));
+		const version = typeof source.version === "number" ? source.version : null;
+		if (!isKnownProviderVersion(version)) return {
 			enabled: null,
-			enabledIds: null
+			enabledIds: null,
+			contextWindow: null,
+			version
 		};
 		return {
 			enabled: normalizeEnabled(source.enabled),
-			enabledIds: normalizeEnabledIds(source.enabledIds)
+			enabledIds: normalizeEnabledIds(source.enabledIds),
+			contextWindow: normalizeContextWindow(source.contextWindow),
+			version
 		};
 	};
+	/** Read the profile's own file, shape-checked. */
+	const parsePayload = async () => parseAt(filePath);
+	/** Read one payload off an explicit path (the legacy shared file). */
+	const parsePayloadFrom = async (file) => parseAt(file);
+	let writeChain = Promise.resolve(null);
+	const cache = createStateReadCache(async () => {
+		const own = await parsePayload();
+		if (own.enabled !== null || own.enabledIds !== null || legacyFile === null) return own;
+		if (own.version !== null) return own;
+		const legacy = await parsePayloadFrom(legacyFile);
+		if (legacy.enabled === null && legacy.enabledIds === null) return own;
+		const inherited = {
+			version: 1,
+			...legacy.enabled === null ? {} : { enabled: legacy.enabled },
+			...legacy.enabledIds === null ? {} : { enabledIds: legacy.enabledIds },
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await writeChain.then(() => writePayload(inherited).then(() => void 0, () => void 0), () => writePayload(inherited).then(() => void 0, () => void 0));
+		return legacy;
+	}, { ttlMs });
+	const read = () => cache.read();
+	/**
+	* The payload the callers actually read. The short-TTL cache's `read()` is
+	* typed `Promise<T | null>` because it doubles as "never read" signalling for
+	* the §23 legacy adoption; a provider payload is always an object, so the
+	* `null` branch collapses here, in one place, rather than at every caller.
+	* @returns {Promise<ProviderPayload>} the payload; the empty payload when nothing is stored.
+	*/
+	const readPayload = async () => await read() ?? EMPTY_PAYLOAD$1;
 	/**
-	* Read one payload, then hand it to `write` — the read-modify-write that keeps
-	* the switch and the list from clobbering each other.
+	* Read one payload, then hand it to {@link writePayload} — the read-modify-
+	* write that keeps the switch and the list from clobbering each other.
 	*
 	* Three-state keys, and they are SYMMETRIC between `enabled` and `enabledIds`:
 	* a key the caller omits (`undefined`) keeps whatever is on disk, an explicit
@@ -1519,26 +1895,28 @@ function createFileProviderStore(options = {}) {
 	* value is stored as given. An earlier `mergeEnabled` flag applied the
 	* "keep what is on disk" rule to `enabled` unconditionally, which silently
 	* discarded the very value a switch save was asked to store.
-	* @param {object} patch - `{ enabled?, enabledIds? }` to persist.
-	* @returns {Promise<string|null>} the write refusal reason, or `null`.
-	*/
-	/**
-	* 读-改-写**整段排队**：两个并发patch 不能互相覆盖。
-	*
-	* 这个 store 以前完全没有写串行化（对比 `usage-store.ts` 的 `writeChain`），于是
-	* 面板开关POST 与 roster POST —— 两个独立请求，外加 `index.ts` 轮询同时在调
-	* `enabledIds()` —— 会各自读到同一个 `current`，后写的赢。实测：先存清单，再并发
-	* `save(true)` + `saveEnabledIds([...])`，其中一次保存被**整个丢掉**（用户勾了
-	* 模型又开了开关，两次点击只活下来一次）。
 	*
-	* 文件头说「两个字段必须作为一个载荷读写，否则开关会覆盖清单」——设计意图是对的，
-	* 但那只防住了「**不同字段**互相覆盖」；缺了串行化，**同字段**与「两次都基于同一
-	* 快照」的互相覆盖照样发生。链的形状与 `usage-store` 一致，且必须把
-	* `writePayload` 的版本拒绝语义一起搬进临界区（否则拒绝判断会落在锁外）。
+	* 读-改-写**整段排队**：两个并发 patch 不能互相覆盖。这个 store 以前完全没有
+	* 写串行化（对比 `usage-store.ts` 的 `writeChain`），于是面板开关 POST 与
+	* roster POST —— 两个独立请求，外加 `index.ts` 轮询同时在调 `enabledIds()` ——
+	* 会各自读到同一个 `current`，后写的赢。实测：先存清单，再并发 `save(true)` +
+	* `saveEnabledIds([...])`，其中一次保存被**整个丢掉**（用户勾了模型又开了开关，
+	* 两次点击只活下来一次）。文件头说「两个字段必须作为一个载荷读写，否则开关会
+	* 覆盖清单」——设计意图是对的，但那只防住了「**不同字段**互相覆盖」；缺了串行化，
+	* **同字段**与「两次都基于同一快照」的互相覆盖照样发生。链的形状与
+	* `usage-store` 一致，且必须把 `writePayload` 的版本拒绝语义一起搬进临界区
+	* （否则拒绝判断会落在锁外）。
 	*
 	* 链吞掉自己的失败继续走：一次只读 Home 上的写失败不该毒化后续所有保存。
+	*
+	* 写成功的同时更新读缓存，调用方不再各自回读一遍：缓存里永远是刚写下去的那份，
+	* 而 `patchPayload` 的 `current` 来自磁盘（`parsePayload`，不走缓存），所以合并
+	* 结果不会带进过期值。此前的写法是写完再 `readPayload()` 读回另一半——那条回读
+	* 走的是 TTL 缓存，拿到的是**写入前**的值，并发时会把一个较新的缓存项顶成旧值。
+	*
+	* @param {object} patch - `{ enabled?, enabledIds?, contextWindow? }` to persist.
+	* @returns {Promise<string|null>} the write refusal reason, or `null`.
 	*/
-	let writeChain = Promise.resolve(null);
 	const patchPayload = (patch) => {
 		const run = writeChain.then(async () => {
 			const current = await parsePayload();
@@ -1548,51 +1926,21 @@ function createFileProviderStore(options = {}) {
 			if (enabled !== null) body.enabled = enabled;
 			const enabledIds = patch.enabledIds === void 0 ? current.enabledIds : patch.enabledIds;
 			if (enabledIds !== null) body.enabledIds = enabledIds;
+			const contextWindow = patch.contextWindow === void 0 ? current.contextWindow : patch.contextWindow;
+			if (contextWindow !== null) body.contextWindow = contextWindow;
 			body.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-			return writePayload(body);
+			const refusal = await writePayload(body);
+			if (refusal === null) cache.remember({
+				enabled,
+				enabledIds,
+				contextWindow,
+				version: 1
+			});
+			return refusal;
 		});
 		writeChain = run.catch(() => null);
 		return run;
 	};
-	const cache = createStateReadCache(async () => {
-		const own = await parsePayload();
-		if (own.enabled !== null || own.enabledIds !== null || legacyFile === null) return own;
-		const legacy = await parsePayloadFrom(legacyFile);
-		if (legacy.enabled === null && legacy.enabledIds === null) return own;
-		const inherited = {
-			version: 1,
-			...legacy.enabled === null ? {} : { enabled: legacy.enabled },
-			...legacy.enabledIds === null ? {} : { enabledIds: legacy.enabledIds },
-			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-		};
-		await writeChain.then(() => writePayload(inherited).then(() => void 0, () => void 0), () => writePayload(inherited).then(() => void 0, () => void 0));
-		return legacy;
-	}, { ttlMs });
-	const read = () => cache.read();
-	/**
-	* The payload the callers actually read. The short-TTL cache's `read()` is
-	* typed `Promise<T | null>` because it doubles as "never read" signalling for
-	* the §23 legacy adoption; a provider payload is always an object, so the
-	* `null` branch collapses here, in one place, rather than at every caller.
-	* @returns {Promise<ProviderPayload>} the payload; `{enabled:null,enabledIds:null}` when nothing is stored.
-	*/
-	const readPayload = async () => await read() ?? {
-		enabled: null,
-		enabledIds: null
-	};
-	/** Read one payload off an explicit path (the legacy shared file). */
-	const parsePayloadFrom = async (file) => {
-		const raw = await readStateJson(file);
-		const source = obj(raw);
-		if (source.version !== 1) return {
-			enabled: null,
-			enabledIds: null
-		};
-		return {
-			enabled: normalizeEnabled(source.enabled),
-			enabledIds: normalizeEnabledIds(source.enabledIds)
-		};
-	};
 	return {
 		/**
 		* The saved switch value.
@@ -1610,6 +1958,16 @@ function createFileProviderStore(options = {}) {
 			return (await readPayload()).enabledIds ?? [];
 		},
 		/**
+		* The saved context-window override (tokens), or `null` = follow the
+		* catalog. `null` is a real answer here, not absence: the override is
+		* optional by design, and the caller (snapshot / stamping) decides what
+		* "follow the catalog" means.
+		* @returns {Promise<number|null>}
+		*/
+		async contextWindow() {
+			return (await readPayload()).contextWindow;
+		},
+		/**
 		* Whether the panel has ever saved a value here.
 		* @returns {Promise<boolean>}
 		*/
@@ -1618,6 +1976,27 @@ function createFileProviderStore(options = {}) {
 			return payload.enabled !== null || payload.enabledIds !== null;
 		},
 		/**
+		* A human-readable note when the file holds a version this build cannot
+		* read, or `null` when there is nothing to say.
+		*
+		* The READ side is permissive on purpose: a foreign file reads as "not set",
+		* so the panel keeps working instead of failing the whole snapshot. The cost
+		* is that it cannot tell "never saved" from "saved but unreadable" — and
+		* for the allow-list those two read differently in the dangerous direction
+		* (an empty list means "offer every model"). Writes are already protected by
+		* the ADR-006 guard in {@link writePayload}; this note is the read side's
+		* half of the same promise. The snapshot aggregate pushes it into
+		* `shapeWarnings`, and `doctor.ts` reports the same file, so the operator
+		* sees the disagreement instead of a switch that looks merely unset.
+		*
+		* @returns {Promise<string|null>}
+		*/
+		async versionNote() {
+			const version = (await readPayload()).version;
+			if (version === null || isKnownProviderVersion(version)) return null;
+			return `provider-state: provider.json holds version ${version}, which this build cannot read (this build knows ${KNOWN_PROVIDER_VERSIONS.join("/")}); the saved switch and allow-list are being answered as "not set", so the allow-list reads as "no filter, offer every model" while the switch falls back to the config default. Upgrade this build to see the saved values, or delete the file to reset them.`;
+		},
+		/**
 		* Persist a switch value. The write is atomic (temp file + rename) so a
 		* concurrent reader never sees a partial payload, and it PRESERVES the
 		* saved allow-list.
@@ -1629,10 +2008,6 @@ function createFileProviderStore(options = {}) {
 			if (enabled === null) throw new TypeError("provider switch expects a boolean");
 			const refusal = await patchPayload({ enabled });
 			if (refusal !== null) throw new Error(refusal);
-			cache.remember({
-				enabled,
-				enabledIds: (await readPayload()).enabledIds ?? []
-			});
 		},
 		/**
 		* Persist the model allow-list, preserving the saved switch.
@@ -1644,108 +2019,1091 @@ function createFileProviderStore(options = {}) {
 			if (list === null) throw new TypeError("provider allow-list expects an array of strings");
 			const refusal = await patchPayload({ enabledIds: list });
 			if (refusal !== null) throw new Error(refusal);
-			cache.remember({
-				enabled: (await readPayload()).enabled ?? null,
-				enabledIds: list
-			});
+		},
+		/**
+		* Persist the context-window override, preserving the saved switch and
+		* allow-list. `null` clears the override back to "follow the catalog".
+		* @param {number|null} value - the window in tokens, or `null` to clear.
+		* @returns {Promise<void>}
+		*/
+		async saveContextWindow(value) {
+			const window = normalizeContextWindow(value);
+			if (value !== null && window === null) throw new TypeError("provider context window expects a positive finite number");
+			const refusal = await patchPayload({ contextWindow: window });
+			if (refusal !== null) throw new Error(refusal);
 		},
 		/**
 		* Forget the panel-saved values: the config default and "no filter" rule
-		* again.
+		* again. The context override is forgotten WITH them — the reset button
+		* means "back to the way this plugin ships", and the override is panel
+		* state in exactly the same sense.
 		* @returns {Promise<void>}
 		*/
 		async forget() {
 			const refusal = await patchPayload({
 				enabled: null,
-				enabledIds: null
+				enabledIds: null,
+				contextWindow: null
 			});
 			if (refusal !== null) throw new Error(refusal);
-			cache.remember({
-				enabled: null,
-				enabledIds: null
-			});
 		}
 	};
 }
 
 //#endregion
-//#region src/host/switch-precedence.ts
+//#region src/host/draw-store.ts
 /**
-* The single adjudicator for "panel-saved value vs config default" across
-* every opt-in switch.
+* 出图工具的开关与模型偏好——本插件**自己的**状态文件，与 provider 那条开关分开。
 *
-* Historically the rule was hand-copied at three call sites (the provider
-* route, the models route, the draw route) in two look-alike dialects:
+* 为什么不是第二个字段塞进 `provider.json`：两者回答的是不同问题。
+* `provider.json` 说「这个 profile 要不要把魔搭作为 **chat provider** 提供」；
+* 本文件说「要不要给 agent 一个**出图工具**」。用户完全可能只要其一（用工具出图但
+* 不污染模型选择器，或反之）。合成一个 payload 会让「关掉出图」连带改掉 provider
+* 清单的写入时序——provider-store 的注释已说明为什么它的两个字段必须同生共死，
+* 而那组理由**不适用于**这两个开关（它们之间没有 atomicity 要求）。
 *
-*   - the boolean switch: `(panel ?? config) === true` plus
-*     `panel === null ? "config" : "panel"`;
-*   - the model preference: `panel ?? config` plus the same source probe.
+* 落点与 `provider-store.ts` 一致：`$DSH_HOME/state/<plugin>/draw.json`（无 profile
+* 时）或 `$DSH_HOME/state/<profile>/<plugin>/draw.json`。profile 分段的意思是
+* 「这个 profile 要不要暴露出图工具」，两个 profile 不能互相覆盖。
 *
-* A fourth dialect existed where no config default exists at all (a switch that
-* is purely panel-owned — a profile without a saved value falls to `off` with no
-* fallback), which is exactly the shape this module does NOT serve: that one has
-* no config default to adjudicate against, so it is the caller's plain read.
+* 优先级与所有 opt-in 开关同一份裁决（`switch-precedence.ts`）：面板保存值赢，
+* 否则 `cordis.patch.yml` 的 `drawEnabled` 默认值说了算。
 *
-* This module is peer-free and deliberately tiny: the whole point is that a
-* switch can never again invent its own precedence dialect, and the source
-* label (`panel` / `config`) always rides with the answer so the panel can
-* say which side is in charge. `test/switch-precedence.test.mjs` pins the
-* dialect so a new caller copying the shape is the odd one out.
+* 完整性沿用 `state-store.ts`：版本化 payload、临时文件 + 原子改名 + fsync、属主
+* 可读、「认不出的内容一律读作没设过」。写入侧拒绝覆盖本版本读不懂的版本（ADR-006）。
 *
-* 注：本模块自带的 `test/switch-precedence.test.mjs` 钉死纯函数行为；部分旧注释里
-* 提到的 `test/peer-contract.test.mjs`（钉死真 peer 的 classifyPiAiError /
-* resolveRetryPolicy 协议）依赖未 vendored 进本仓库的运行时 peer，不在 `npm test`
-* 离线门禁内。
+* @module dsh-connect-modelscope-token-plan/draw-store
+*/
+/** 本 store 落盘 payload 的版本。 */
+const DRAW_STORE_VERSION = 1;
+/** 本 build 读得懂的版本集合（升级时把新号加进来，旧号保持可读）。 */
+const KNOWN_DRAW_VERSIONS = Object.freeze([1]);
+const EMPTY_PAYLOAD = {
+	enabled: null,
+	modelId: null,
+	version: null
+};
+/** 本 build 读不读得懂这个版本。 */
+function isKnownDrawVersion(version) {
+	return isKnownStateVersion(version, KNOWN_DRAW_VERSIONS);
+}
+/**
+* 归一一个保存的模型偏好：非空字符串，或 `null`（= 自动挑——具体挑谁由
+* `draw-runtime.ts` 的 `pickDrawModel` 优先级决定，不是简单取目录第一个）。
 *
-* @module dsh-connect-modelscope-token-plan/switch-precedence
+* 不校验「这个 id 是否真存在」——目录会变，存一个暂时不在目录里的 id 是合法的
+* （用户可能先配好、等模型上线）。调用侧解析不出来时退回自动。
+* @param {unknown} value - 原始值。
+* @returns {string|null} 归一后的 id 或 `null`。
 */
+function normalizeDrawModelId(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed === "" ? null : trimmed;
+}
 /**
-* Resolve the effective boolean switch: a panel-saved value always wins,
-* otherwise the config default rules.
-* @param {boolean|null} panel - the panel-saved value (`null` = never saved).
-* @param {boolean} config - the patch-declared default.
-* @returns {boolean} the effective switch.
+* 归一保存的开关值：只有真正的 boolean 才算数，其余读作「没设过」。
+* @param {unknown} value - 原始值。
+* @returns {boolean|null} 归一后的开关。
 */
-function resolveSwitchEnabled(panel, config) {
-	return (panel ?? config) === true;
+function normalizeDrawEnabled(value) {
+	return typeof value === "boolean" ? value : null;
+}
+/** 本 store 的目录（与 provider-store 同一套分段规则）。 */
+function drawStoreDir(profile, dir) {
+	if (typeof dir === "string" && dir !== "") return dir;
+	return profile ? profileStateDir(name, profile) : stateDir(name);
 }
 /**
-* Where the effective value came from — the panel when it saved one, the
-* config otherwise. Rides with every resolved answer so the panel can name
-* the side in charge.
-* @param {boolean|string|null} panel - the panel-saved value.
-* @returns {"panel"|"config"}
+* 文件支撑的出图开关 + 模型偏好。
+* @param {StoreOptions} [options] - `{ dir, profile, ttlMs, logger }`。
+* @returns {object} store 句柄。
 */
-function switchSource(panel) {
-	return panel === null ? "config" : "panel";
+function createFileDrawStore(options = {}) {
+	const { dir, profile = null, ttlMs = STATE_READ_TTL_MS, logger } = options;
+	const stateDir = drawStoreDir(profile, dir);
+	const filePath = join(stateDir, "draw.json");
+	/** 解析一份 payload；认不出的版本读作「没设过」但**记住**版本号。 */
+	const parsePayload = async () => {
+		const source = obj(await readStateJson(filePath));
+		const version = typeof source.version === "number" ? source.version : null;
+		if (!isKnownDrawVersion(version)) return {
+			enabled: null,
+			modelId: null,
+			version
+		};
+		return {
+			enabled: normalizeDrawEnabled(source.enabled),
+			modelId: normalizeDrawModelId(source.modelId),
+			version
+		};
+	};
+	const cache = createStateReadCache(parsePayload, { ttlMs });
+	/**
+	* 读当前 payload。
+	* @returns {Promise<DrawPayload>}
+	*/
+	const current = async () => await cache.read() ?? EMPTY_PAYLOAD;
+	/**
+	* 写一份补丁并落盘。
+	* @param {{enabled?: boolean|null, modelId?: string|null}} patch - 要改的字段。
+	* @returns {Promise<string|null>} 拒绝原因（`null` = 已写入）。
+	*/
+	const patchPayload = async (patch) => {
+		const before = await current();
+		const enabled = patch.enabled === void 0 ? before.enabled : patch.enabled;
+		const modelId = patch.modelId === void 0 ? before.modelId : patch.modelId;
+		try {
+			await ensureStateDir(stateDir);
+			const body = { version: 1 };
+			if (enabled !== null) body.enabled = enabled;
+			if (modelId !== null) body.modelId = modelId;
+			body.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+			await writeStateFile(filePath, JSON.stringify(body, null, 2), { temporary: temporaryOf(stateDir, "draw.json") });
+			cache.remember({
+				enabled,
+				modelId,
+				version: 1
+			});
+			return null;
+		} catch (error) {
+			return degrade("draw store write failed", error, logger, "draw store write failed");
+		}
+	};
+	return {
+		/** 面板保存的出图开关；`null` = 回退 patch 默认值。 */
+		async enabled() {
+			return (await current()).enabled;
+		},
+		/** 面板保存的模型偏好；`null` = 自动。 */
+		async modelId() {
+			return (await current()).modelId;
+		},
+		/** 这个 profile 是否被显式配置过。 */
+		async isConfigured() {
+			const payload = await current();
+			return payload.enabled !== null || payload.modelId !== null;
+		},
+		/** 保存开关。 */
+		async saveEnabled(enabled) {
+			if (typeof enabled !== "boolean") throw new TypeError("draw switch expects a boolean");
+			return patchPayload({ enabled });
+		},
+		/** 保存模型偏好（`null` = 清掉，回到自动）。 */
+		async saveModelId(modelId) {
+			if (modelId !== null && (typeof modelId !== "string" || modelId.trim() === "")) throw new TypeError("draw model expects a non-empty string or null");
+			return patchPayload({ modelId });
+		},
+		/** 清掉两个字段（回到「没配过」）。 */
+		async reset() {
+			return patchPayload({
+				enabled: null,
+				modelId: null
+			});
+		},
+		/** 落盘路径（诊断与测试用）。 */
+		filePath
+	};
 }
 
 //#endregion
-//#region src/host/publish-core.ts
+//#region src/host/draw.ts
 /**
-* The shared bones of a provider publisher — the parts that MUST NOT differ
-* between upstreams, factored out so they cannot drift.
+* 魔搭出图（`/v1/images/generations`）的**纯逻辑半边**——协议形状的解析与判定。
 *
-* The publisher (`provider-publish.ts` for the ModelScope provider) runs the
-* same control plane: a publish queue, a `disposed` gate, and a single-point
-* pair registration that doubles as the rollback path. Those three are
-* load-bearing and pinned by tests — and the rollback is the worst place to
-* discover a divergence, because it only runs once something has already failed.
-* When they were written twice, keeping them in sync relied on comments in one
-* file pointing at the other; here there is one copy.
+* 为什么是这个形状：魔搭的生图是**异步两段式**（提交得 `task_id`，轮询才出图），
+* 与姊妹插件 `dsh-connect-sensenova-token-plan/src/host/draw.ts` 的**同步单发**
+* （`drawOnce` 一次 fetch 即 `parseDrawResponse` 取 `data[0].url`）形状不兼容，
+* **不能照抄**。可复用的只有外壳（endpoint 拼接、冷却门、失败文案），核心必须新写。
+* 协议依据全部来自 `docs/SPIKE-image-gen.md` 的真机实测，非文档转述。
 *
-* What is deliberately NOT shared: the publish GATE and the state shape. The
-* ModelScope side decides from "switch on?" plus a persisted catalog and an
-* allow-list, and restores `entries`/`enabledIds`/quota ids on a rollback;
-* another provider's publisher decides from "switch on?" plus "is there a
-* credential?" and restores its roster. That difference is real domain
-* difference, and folding it into one parameterized state machine would make a
-* publish unreadable — every reader would have to read the configuration to
-* know what one does.
+* 本模块**只做纯函数**：endpoint 构造、请求体构造、响应解析、状态判定、失败分诊。
+* 它**不发起任何请求、不碰凭据、不注册工具**——那半边（fetch 注入、Host 工具注册）
+* 与 `llm-adapter.ts` 一样 peer-dependent，测试覆盖同样是零（docs/ROADMAP.md Backlog）。
+* 刻意 peer-free：纯函数部分能进离线 `npm test` 门禁，`test/draw.test.mjs` 钉住形状。
 *
-* Peer-free: touches no runtime peer.
+* 三条承重结论（全部实测，推翻了几条广泛流传的错误写法）：
 *
-* @module dsh-connect-modelscope-token-plan/publish-core
+* 1. **轮询必须带 `X-ModelScope-Task-Type: image_generation`**，否则上游一律返回
+*    `task not found` + `task_status: FAILED`——**那是假失败**，任务实际正常。
+*    缺这个头的实现会在第一次轮询就误判失败并放弃一张已经能出的图。
+* 2. **提交响应的 `task_status` 不可信**：实测每次提交都回 `SUCCEED`，包括最终确实
+*    `FAILED` 的那次。所以提交只认 `task_id`，**成功与否只看轮询终态**。
+* 3. **`FAILED` 没有可分诊的形状**：`errors.code` 实测为 `0`、`errors.message` 为
+*    空串，没有顶层 `message`。任何「从错误里读出原因」的承诺都是编造——本模块的
+*    `describeDrawFailure` 因此**明确承认原因不可知**，只报可确定的形态差异。
+*
+* @module dsh-connect-modelscope-token-plan/draw
+*/
+/**
+* 出图请求的截止时间（墙钟毫秒）。
+*
+* **15 分钟**：实测同一模型的耗时在 61s–537s 之间大幅波动（免费池排队），
+* 且**超时放弃不等于任务死亡**——上游任务会继续跑完（记录之后还会被回收，
+* 见 docs/SPIKE-image-gen.md §坑 5）。宁可多等，不要扔掉一张已在生成的图。
+*/
+const DRAW_TIMEOUT_MS = 9e5;
+/**
+* 两次轮询之间的间隔（毫秒）。
+*
+* 取 15s 的**真正理由**是「够用且不浪费」：实测最慢一次 537s，15s 间隔意味着
+* 最多几十次查询，代价可忽略；而更密（社区示例的 5s）没有观测收益。
+*
+* ⚠️ 早先曾写「更密的轮询拖慢任务」，**该归因已推翻**——后续对照显示同一模型、
+* 同样 15s 轮询的耗时是 61s → 261s → 537s 单调恶化，是**上游排队时长在波动**。
+* 那次构成「证据」的 5s vs 30s 对照，控制变量没做，不足以支撑因果。
+* 详见 docs/SPIKE-image-gen.md §坑 4（含撤回记录）。
+*/
+const DRAW_POLL_INTERVAL_MS = 15e3;
+/** 轮询的总截止时间；与 `DRAW_TIMEOUT_MS` 同量级但独立可调（诊断时可放宽）。 */
+const DRAW_POLL_DEADLINE_MS = DRAW_TIMEOUT_MS;
+/**
+* 轮询必须携带的头名与取值。
+*
+* 漏掉它 → 上游返回 `task not found` + `FAILED`，而任务其实在正常跑。这是本协议
+* 最贵的单点知识，也是第一份外部资料缺失的那一块。
+*/
+const TASK_TYPE_HEADER = "X-ModelScope-Task-Type";
+const TASK_TYPE_IMAGE_GENERATION = "image_generation";
+/**
+* 一次出图请求由几个 HTTP 请求组成：一次提交 + N 次轮询。
+* 只作为文档性常量，供工具描述与测试引用。
+*/
+const DRAW_PHASE = Object.freeze({
+	submit: "submit",
+	poll: "poll"
+});
+/**
+* 读一个响应的 `task_status`，取不到返回 `null`。
+*
+* 刻意**不猜**：字段缺失或类型不对都返回 `null`，由 `isTerminalStatus` 把它当作
+* 「非终态」继续等——这样一次形状漂移最多变成多轮轮询，不会变成误报失败。
+* @param {unknown} data - 已解析的 JSON。
+* @returns {DrawTaskStatus|null} 规范化状态，取不到为 `null`。
+*/
+function readTaskStatus(data) {
+	if (data === null || typeof data !== "object") return null;
+	const raw = data.task_status;
+	if (typeof raw !== "string") return null;
+	const upper = raw.trim().toUpperCase();
+	if (upper === "PENDING" || upper === "RUNNING" || upper === "SUCCEED" || upper === "FAILED") return upper;
+	return null;
+}
+/**
+* 一个状态是不是终态。
+*
+* **只有** `SUCCEED` / `FAILED` 是终态；`null`（读不到）与一切未知值都**不是**。
+* 「未知值继续等」是刻意的：把上游新增的状态误判成失败会丢掉一张已经能出的图，
+* 而误判成进行中最多多等几轮（受 `DRAW_POLL_DEADLINE_MS` 兜底）。
+* @param {DrawTaskStatus|null} status - 规范化状态。
+* @returns {boolean} 是否终态。
+*/
+function isTerminalStatus(status) {
+	return status === "SUCCEED" || status === "FAILED";
+}
+/**
+* 从提交响应里取 `task_id`。
+*
+* 提交响应里那个 `task_status: "SUCCEED"` **一律忽略**（见模块头第 2 条：它与终态
+* 无关）。本函数只认 `task_id`，所以一个「提交即失败」的上游只要给了 id 就仍会被
+* 轮询，而不给 id 会被当作提交失败——这两种都符合实测。
+* @param {unknown} data - 已解析的提交响应。
+* @returns {string|null} 任务 id，取不到为 `null`。
+*/
+function readTaskId(data) {
+	if (data === null || typeof data !== "object") return null;
+	const raw = data.task_id;
+	return typeof raw === "string" && raw.trim() !== "" ? raw.trim() : null;
+}
+/**
+* 从终态响应里取出成品图的 URL 列表。
+*
+* 实测形状是顶层 `output_images: string[]`。**刻意不读** `data[0].url`（OpenAI
+* 同步形状）与 `output.image_url`（外部资料误传的形状）——两者在魔搭上都不存在。
+* @param {unknown} data - 已解析的轮询响应。
+* @returns {string[]} 可用的图片 URL（保持上游顺序，已去空）。
+*/
+function readOutputImages(data) {
+	if (data === null || typeof data !== "object") return [];
+	const raw = data.output_images;
+	if (!Array.isArray(raw)) return [];
+	const out = [];
+	for (const item of raw) if (typeof item === "string" && item.trim() !== "") out.push(item.trim());
+	return out;
+}
+/**
+* 构造出图请求体。
+*
+* 只发上游**确认消费**的字段：`model` / `prompt` / `image_url` / `size` / `steps` /
+* `guidance` / `seed` / `negative_prompt` 均被实测接受（SPIKE 实测 #9）；`loras`
+* 也被确认消费（无效 LoRA id 在提交阶段直接 500，实测 #18）。**不发** `ref_image`
+* ——那是别家平台的写法，魔搭上不存在（SPIKE §对照）。
+*
+* `image_url` **一律发数组**，哪怕只有一张：官方示例的形状是数组（多图编辑要用），
+* 实测单张以数组发也通（#17）、以裸字符串发亦通（#8）。取数组是因为它的超集更贴近
+* 上游本意，也省掉一个分支。
+*
+* `n` 刻意**不作为请求字段**：实测目录里的出图模型都是单出模型，`n` 的支持度未
+* 逐项验证，传一个上游不认的参数比不传更危险。调用方要几张就发几次。
+* @param {object} options - 请求参数。
+* @param {string} options.model - 模型 id。
+* @param {string} options.prompt - 提示词。
+* @param {string|string[]} [options.imageUrl] - 输入图 URL，**字符串或数组均可**，
+*   内部一律归一为数组（官方形状；多图编辑要用数组）。
+* @param {string} [options.size] - `"宽x高"`，如 `"1024x1024"`（64 对齐）。
+* @param {number} [options.steps] - 采样步数。
+* @param {number} [options.guidance] - 引导系数。
+* @param {number} [options.seed] - 随机种子。
+* @param {string} [options.negativePrompt] - 负向提示词。
+* @param {string|Record<string, number>} [options.loras] - LoRA 配置：单个 repo id，
+*   或 `{id: weight}` 映射（官方：最多 6 个，权重和须为 1.0）。
+* @returns {object} 请求体。
+*/
+function buildDrawBody(options) {
+	const body = {
+		model: strOrEmpty(options.model),
+		prompt: strOrEmpty(options.prompt)
+	};
+	const imageUrl = normalizeImageUrlList(options.imageUrl);
+	if (imageUrl.length > 0) body.image_url = imageUrl;
+	const size = strOrEmpty(options.size);
+	if (size !== "") body.size = size;
+	if (Number.isFinite(options.steps)) body.steps = options.steps;
+	if (Number.isFinite(options.guidance)) body.guidance = options.guidance;
+	if (Number.isFinite(options.seed)) body.seed = options.seed;
+	const negativePrompt = strOrEmpty(options.negativePrompt);
+	if (negativePrompt !== "") body.negative_prompt = negativePrompt;
+	const loras = options.loras;
+	if (typeof loras === "string" && loras.trim() !== "") body.loras = loras.trim();
+	else if (loras !== null && typeof loras === "object") {
+		const entries = Object.entries(loras).filter(([id, weight]) => id.trim() !== "" && Number.isFinite(weight));
+		if (entries.length > 0) body.loras = Object.fromEntries(entries);
+	}
+	return body;
+}
+/**
+* 把「一张或多张输入图」归一成 URL 数组。
+*
+* 单张给字符串上游也吃（实测 #8），但官方示例与多图编辑都用数组（#17 实测通），
+* 故一律归一为数组。逐项过滤空串，**保持调用方给定的顺序**——多图编辑里顺序即语义
+* （官方示例：「图一中的狗，去追图二中的飞盘」）。
+* @param {unknown} value - 单个 URL、URL 数组，或缺省。
+* @returns {string[]} 归一后的 URL 数组（可为空）。
+*/
+function normalizeImageUrlList(value) {
+	const raw = Array.isArray(value) ? value : [value];
+	const out = [];
+	for (const item of raw) if (typeof item === "string" && item.trim() !== "") out.push(item.trim());
+	return out;
+}
+/**
+* 从任意配置里读出「可用作输入图」的 URL。
+*
+* 承接 agent 工具的 `image_url` 参数。**只接受 http(s) 与 data URL**——其它形态
+* （本地路径）上游取不到，转发过去只会换回一个原因不可知的 `FAILED`。实测尚未
+* 验证 data URL 是否被上游接受（SPIKE 待办），但**转发它不会更糟**，而拦掉它会让
+* 本地图片彻底不可用；故放行并在档案里留待验证。
+* @param {unknown} value - 原始参数。
+* @returns {string|null} 规范化后的 URL，不可用时为 `null`。
+*/
+function normalizeImageUrlInput(value) {
+	const raw = typeof value === "string" ? value.trim() : "";
+	if (raw === "") return null;
+	if (/^https?:\/\//i.test(raw)) return raw;
+	if (/^data:image\/[a-z0-9.+-]+;base64,/i.test(raw)) return raw;
+	return null;
+}
+/**
+* 把一次失败转成 agent 与面板都能读的一句话。
+*
+* **关于魔搭 `FAILED` 的诚实边界**：实测唯一的失败样本是
+* `{"errors":{"code":0,"message":""}, "task_status":"FAILED"}`——**原因不可知**。
+* 所以这里只报「可确定的形态事实」（HTTP 码 / 轮询未出终态 / 明确的原因文本），
+* **不从空错误里编造原因**，并在原因确实拿不到时明说「上游未给出原因」。这是本仓库
+* README「诚实声明」的要求。
+*
+* 凭据永不入消息：body 文本可能回显 `ms-` 令牌，过 `redactSecrets` 后再截断。
+* @param {object} failure - 失败信息。
+* @param {number} [failure.status] - HTTP 状态码（提交/轮询的传输层失败）。
+* @param {string} [failure.bodyText] - 上游 body 原文。
+* @param {string} [failure.taskStatus] - 轮询读到的状态。
+* @param {string} [failure.cause] - 已知原因（超时 / 没有可用图片 / 拿不到 task_id 等）。
+* @returns {string} 一行说明。
+*/
+function describeDrawFailure(failure) {
+	const text = redactSecrets(typeof failure.bodyText === "string" ? failure.bodyText : "").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 === 404) return `出图失败：HTTP 404 —— 端点或模型不存在（检查 apiBase 与模型 id）${tail}`;
+	if (status === 429) return `出图失败：HTTP 429 —— 上游限流，请稍后重试${tail}`;
+	if (status >= 500) return `出图失败：HTTP ${status} —— 上游服务异常，稍后重试${tail}`;
+	const cause = strOrEmpty(failure.cause);
+	if (cause !== "") return `出图失败：${cause}${tail}`;
+	const taskStatus = strOrEmpty(failure.taskStatus);
+	if (taskStatus === "FAILED") return "出图失败：上游任务 FAILED，但未给出失败原因（实测 errors.code=0、message 为空），换模型或稍后重试";
+	if (taskStatus !== "") return `出图失败：任务停在 ${taskStatus}（非终态），已超过截止时间`;
+	return `出图失败：上游未给出可诊断的失败信息${tail}`;
+}
+/**
+* 冷却门：一次失败后的一段时间内拒绝再试。
+*
+* 借 sensenova 那份的形状（它也从 `dsh-draw-router` 抄来）：出图慢且贵，一次失败
+* 后立刻重试既容易撞限流又浪费等待窗口。纯闭包，无依赖，可离线测。
+* @param {number} cooldownMs - 冷却窗口（毫秒）。
+* @returns {{fail: () => void, remainingMs: () => number, clear: () => void}} 冷却门。
+*/
+function createDrawCooldown(cooldownMs) {
+	const window = Math.max(0, Math.floor(cooldownMs));
+	let until = 0;
+	return {
+		/** 记一次失败，从此刻起进入冷却。 */
+		fail() {
+			until = Date.now() + window;
+		},
+		/** 剩余冷却毫秒；0 表示可以发起。 */
+		remainingMs() {
+			return Math.max(0, until - Date.now());
+		},
+		/** 清掉冷却（例如面板里手动排障后）。 */
+		clear() {
+			until = 0;
+		}
+	};
+}
+/** 读一个字符串，否则空串（本地化的小工具，避免为 3 行代码再引 util 的依赖面）。 */
+function strOrEmpty(value) {
+	return typeof value === "string" ? value.trim() : "";
+}
+/** 凭据脱敏：出图失败消息可能带上游回显的 body，令牌不能随它进日志或面板。 */
+function redactSecrets(text) {
+	return 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-[A-Za-z0-9-]{16,}/g, "ms-[REDACTED]");
+}
+
+//#endregion
+//#region src/host/draw-runtime.ts
+/**
+* 出图的 **peer-dependent 半边**：真正发起请求、驱动异步两段式、注册成 agent 工具。
+*
+* 与 `llm-adapter.ts` 同一个处境——import Host 发行的 peer（`@deepseek-ai/dsh-tools`
+* 的 `defineTool` 由调用方惰性注入），**不能由离线单测套件导入**。纯逻辑全部住在
+* `draw.ts`（已由 `test/draw.test.mjs` 覆盖 39 组），本文件只做「接线 + I/O」：
+* 轮询循环、fetch、工具定义。改错本文件**不会让任何门禁变红**。
+*
+* 与姊妹插件的关键差异（形状不兼容，不能照抄）：
+* `sensenova` 的出图是**同步单发**——一次 `fetch` 拿 `data[0].url` 就结束。魔搭是
+* **异步两段式**：提交拿 `task_id`，再轮询到终态取 `output_images[0]`。所以这里多
+* 一个 `pollTask` 循环，且它必须带 `X-ModelScope-Task-Type`（漏了 = 假失败）。
+*
+* 三条承重纪律：
+* 1. 提交响应的 `task_status` **一律忽略**（实测恒为 SUCCEED，连最终 FAILED 的那次
+*    也是），成功与否只看轮询终态。`readTaskId` 已把这条钉在纯逻辑层。
+* 2. 轮询间隔 15s（`DRAW_POLL_INTERVAL_MS`），**不是**社区常见的 5s——实测更密的
+*    轮询只与更慢相关。
+* 3. 失败原因实测可能**不可知**（`errors.code:0` + 空 message）。`describeDrawFailure`
+*    因此明说「未给出原因」，本文件也**不从空错误里编造**。
+*
+* @module dsh-connect-modelscope-token-plan/draw-runtime
+*/
+/** agent 工具名。带插件前缀，避免与 `dsh-draw-router` 的 `draw_image` 撞名。 */
+const DRAW_TOOL_NAME = "modelscope_draw_image";
+/**
+* 已知能**纯文生图**的目录内模型 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/…` 在前，照旧逻辑纯文生图必挂）。
+*/
+const KNOWN_T2I_MODEL_ID = "Qwen/Qwen-Image-Edit";
+/** 一次失败的冷却窗：出图慢，失败后立刻重试既易撞限流又白等。 */
+const DRAW_FAILURE_COOLDOWN_MS = 6e4;
+/**
+* 把 OpenAI 兼容 base 拼成出图端点。
+*
+* `…/v1` → `…/v1/images/generations`；已带该后缀则原样；更深路径回卷到 `/v1`。
+* 与 sensenova 的同名函数同源（那是受控复制：endpoint 拼接与上游是谁无关）。
+* @param {string} apiBase - 配置里的 apiBase。
+* @returns {string} 完整端点。
+*/
+function buildGenerationsEndpoint(apiBase) {
+	const trimmed = str(apiBase, "").replace(/\/+$/, "");
+	if (/\/images\/generations$/.test(trimmed)) return trimmed;
+	if (/\/v1$/.test(trimmed)) return `${trimmed}/images/generations`;
+	if (/\/v1\//.test(trimmed)) return trimmed.replace(/\/v1\/.*$/, "/v1/images/generations");
+	return `${trimmed}/v1/images/generations`;
+}
+/**
+* 拼轮询端点。task_id 上游是 UUID（实测失败态出现过短 id），一律走 path。
+* @param {string} apiBase - 配置里的 apiBase。
+* @param {string} taskId - 任务 id。
+* @returns {string} 完整端点。
+*/
+function buildTasksEndpoint(apiBase, taskId) {
+	return `${buildGenerationsEndpoint(apiBase).replace(/\/images\/generations$/, "")}/tasks/${encodeURIComponent(taskId)}`;
+}
+/**
+* 一个响应体到底是不是「终态」——读不到就当还没好，继续等。
+*
+* 与 `isTerminalStatus` 的分工：那个管状态语义，这个管「响应本身能不能读」。
+* 上游偶发返回非 JSON（CDN 错误页）时，当作暂时性抖动继续等，而不是判失败——
+* 实测过一个 task 在正常轮询下始终 SUCCEED，没有理由把一次解析失败升级成终局。
+* @param {unknown} data - 已解析的 JSON。
+* @returns {boolean} 是否终态。
+*/
+function isTerminalPayload(data) {
+	return isTerminalStatus(readTaskStatus(data));
+}
+/**
+* 真正跑一次出图：提交 + 轮询到终态。
+*
+* 两段都必须带各自必需的头：提交带 `X-ModelScope-Async-Mode`（实测可省但官方示例
+* 都带，带上无害），轮询带 `X-ModelScope-Task-Type`（**必需**，漏了必假失败）。
+* @param {object} options - 调用参数。
+* @param {DrawFetch} options.fetchImpl - 注入的 fetch。
+* @param {string} options.apiBase - apiBase。
+* @param {string} options.apiKey - 访问令牌（绝不出现在返回文本里）。
+* @param {string} options.model - 模型 id。
+* @param {string} options.prompt - 提示词。
+* @param {string|string[]} [options.imageUrl] - 输入图（图生图 / 多图编辑）。
+* @param {string} [options.size] - `"宽x高"`。
+* @param {number} [options.steps] - 采样步数。
+* @param {number} [options.guidance] - 引导系数。
+* @param {number} [options.seed] - 种子。
+* @param {string} [options.negativePrompt] - 负向提示词。
+* @param {number} [options.pollDeadlineMs] - 轮询截止。
+* @param {number} [options.pollIntervalMs] - 轮询间隔（测试可缩短）。
+* @returns {Promise<DrawOutcome>} 出图结果。
+* @throws {Error} 提交失败、任务 FAILED、或超时——消息已过 `describeDrawFailure`。
+*/
+async function runDrawOnce({ fetchImpl, apiBase, apiKey, model, prompt, imageUrl, size, steps, guidance, seed, negativePrompt, pollDeadlineMs = DRAW_POLL_DEADLINE_MS, pollIntervalMs = DRAW_POLL_INTERVAL_MS }) {
+	const headers = {
+		Authorization: `Bearer ${apiKey}`,
+		"Content-Type": "application/json"
+	};
+	const body = buildDrawBody({
+		model,
+		prompt,
+		...imageUrl !== void 0 ? { imageUrl } : {},
+		...size !== void 0 ? { size } : {},
+		...steps !== void 0 ? { steps } : {},
+		...guidance !== void 0 ? { guidance } : {},
+		...seed !== void 0 ? { seed } : {},
+		...negativePrompt !== void 0 ? { negativePrompt } : {}
+	});
+	let submitted;
+	try {
+		submitted = await fetchImpl(buildGenerationsEndpoint(apiBase), {
+			method: "POST",
+			headers: {
+				...headers,
+				"X-ModelScope-Async-Mode": "true"
+			},
+			body: JSON.stringify(body)
+		});
+	} catch (error) {
+		throw new Error(describeDrawFailure({ cause: `提交请求失败：${error instanceof Error ? error.message : String(error)}` }));
+	}
+	const submitText = await safeText(submitted);
+	if (!submitted.ok) throw new Error(describeDrawFailure({
+		status: submitted.status,
+		bodyText: submitText
+	}));
+	const taskId = readTaskId(await safeJson(submitted, submitText));
+	if (taskId === null) throw new Error(describeDrawFailure({
+		bodyText: submitText,
+		cause: "提交响应里没有 task_id"
+	}));
+	const deadline = Date.now() + Math.max(1e3, Math.floor(pollDeadlineMs));
+	const interval = Math.max(1, Math.floor(pollIntervalMs));
+	let polls = 0;
+	let lastStatus;
+	for (;;) {
+		if (Date.now() >= deadline) throw new Error(describeDrawFailure({ cause: `超过截止时间（${Math.round(pollDeadlineMs / 1e3)}s，${polls} 次轮询）仍未拿到结果。上游任务（${taskId}）**可能仍在生成**——实测排队时长在 1–15 分钟间大幅波动，与请求本身无关。稍后可重试；注意超时后原任务的结果不保证还能取回` }));
+		await sleep(interval);
+		polls++;
+		let polled;
+		try {
+			polled = await fetchImpl(buildTasksEndpoint(apiBase, taskId), {
+				method: "GET",
+				headers: {
+					...headers,
+					[TASK_TYPE_HEADER]: TASK_TYPE_IMAGE_GENERATION
+				}
+			});
+		} catch {
+			continue;
+		}
+		const pollText = await safeText(polled);
+		if (!polled.ok) throw new Error(describeDrawFailure({
+			...polled.status !== void 0 ? { status: polled.status } : {},
+			...pollText !== "" ? { bodyText: pollText } : {},
+			...lastStatus !== void 0 ? { taskStatus: lastStatus } : {}
+		}));
+		const data = await safeJson(polled, pollText);
+		const status = readTaskStatus(data);
+		if (status !== null) lastStatus = status;
+		if (!isTerminalPayload(data)) continue;
+		if (status === "FAILED") throw new Error(describeDrawFailure({
+			taskStatus: "FAILED",
+			bodyText: pollText
+		}));
+		const images = readOutputImages(data);
+		if (images.length === 0) throw new Error(describeDrawFailure({
+			taskStatus: "SUCCEED",
+			bodyText: pollText,
+			cause: "任务报 SUCCEED 但没有可用图片"
+		}));
+		return {
+			model,
+			images,
+			taskId,
+			polls
+		};
+	}
+}
+/**
+* 从目录里挑一个出图模型。
+*
+* 优先级（高 → 低）：
+* 1. **工具显式请求**——即使不在目录里也放行（手工覆盖，上游会自己报错）；
+* 2. **首选模型**（面板保存的模型偏好，或配置 `drawModelId`）——用户点了谁就是
+*    谁，同样不校验在不在目录（用户可能先配好、等模型上线）。此前这个偏好只在
+*    `pickDrawModel` 返回 null 时才生效，目录非空时等于死配置——面板显示的
+*    preferredModel 与实际挑中的模型会说两套话；
+* 3. 目录里**平台声明**为 `text-to-image` 的条目（`textToImageModelIds`，将来目录
+*    补上真文生图模型时自动优先生效）；
+* 4. **已知能纯文生图**的模型（`KNOWN_T2I_MODEL_ID`）——今天目录的坑位，见该
+*    常量的注释：真实目录里它是第二个，照旧取「第一个」会挑中纯文生图必挂的
+*    `MusePublic/…`；
+* 5. 目录里第一个出图模型（`isImageGenModel` 的严格方向：只认明确声明，缺字段
+*    不算）。
+*
+* 目录为空且既无显式请求也无首选模型 → `null`，由调用方给出可操作的错误，
+* 而不是发一个注定失败的请求。
+* @param {unknown} entries - 归一目录条目。
+* @param {string} [requested] - 工具调用里显式给的 model。
+* @param {string} [preferred] - 首选模型 id（面板偏好或配置 `drawModelId`）。
+* @returns {string|null} 选中的 id。
+*/
+function pickDrawModel(entries, requested, preferred) {
+	const want = str(requested, "");
+	if (want !== "") return want;
+	const preferredId = str(preferred, "");
+	if (preferredId !== "") return preferredId;
+	const ids = imageGenModelIds(entries);
+	if (ids.length === 0) return null;
+	const t2i = textToImageModelIds(entries);
+	if (t2i.length > 0) return t2i[0] ?? null;
+	if (ids.includes("Qwen/Qwen-Image-Edit")) return KNOWN_T2I_MODEL_ID;
+	return ids[0] ?? null;
+}
+/**
+* 目录里可用于出图的模型 id（工具结果里回显，方便 agent 与用户看到实际候选）。
+* @param {unknown} entries - 归一目录条目。
+* @returns {string[]} id 列表。
+*/
+function drawModelIds(entries) {
+	return imageGenModelIds(entries);
+}
+/**
+* 装配 agent 工具定义。
+*
+* 工具只做「参数归一 → 跑一次 → 组装结果文本」，所有判定都委托给 `draw.ts` 的纯函数。
+* @param {object} options - 装配参数。
+* @param {(definition: object) => unknown} options.defineTool - peer 的工厂。
+* @param {DrawFetch} options.fetchImpl - 注入的 fetch。
+* @param {() => Promise<string>} options.resolveApiKey - 每次调用现读令牌。
+* @param {() => unknown|Promise<unknown>} [options.getEntries] - 目录条目读取器。
+* @param {object} [options.settings] - `{ apiBase, drawModelId, drawTimeoutMs }`。
+* @param {ReturnType<typeof createDrawCooldown>} [options.cooldown] - 冷却门。
+* @param {() => boolean} [options.isDisposed] - 卸载闸。
+* @returns {unknown} 已定义的 agent 工具。
+*/
+function defineDrawTool({ defineTool, fetchImpl, resolveApiKey, getEntries, settings, getPreferredModelId, cooldown = createDrawCooldown(DRAW_FAILURE_COOLDOWN_MS), isDisposed = () => false }) {
+	const timeoutMs = Math.max(3e4, Math.floor(Number(settings?.drawTimeoutMs) > 0 ? Number(settings?.drawTimeoutMs) : DRAW_TIMEOUT_MS));
+	const apiBase = str(settings?.apiBase, "https://api-inference.modelscope.cn/v1");
+	return defineTool({
+		name: DRAW_TOOL_NAME,
+		description: "Generate or edit an image with the ModelScope (魔搭) API-Inference token. Text-to-image by default; pass `imageUrl` to edit an existing image (image-to-image), or an array of URLs for multi-image editing. Omit `model` to use the catalogue's image model. This call is ASYNCHRONOUS upstream: the model queues first, so latency varies from ~1 minute to 15+ minutes depending on the free pool; it polls until the task reaches a terminal state. Available image model ids are reported in the result.",
+		parameters: {
+			prompt: {
+				type: "string",
+				required: true,
+				description: "Image prompt; describe the target image (for edits, describe the intended change)"
+			},
+			model: {
+				type: "string",
+				description: "ModelScope image model id; defaults to the catalogue's image model"
+			},
+			imageUrl: {
+				type: "string",
+				description: "Input image URL for editing (public http(s) or data:image/...;base64). For multi-image editing pass several URLs separated by newlines — order is significant."
+			},
+			size: {
+				type: "string",
+				description: "Image size as WIDTHxHEIGHT, e.g. 1024x1024 (64-aligned)"
+			},
+			steps: {
+				type: "number",
+				description: "Sampling steps (platform range 1-100)"
+			},
+			guidance: {
+				type: "number",
+				description: "Prompt guidance scale (platform range 1.5-20)"
+			},
+			seed: {
+				type: "number",
+				description: "Random seed"
+			},
+			negativePrompt: {
+				type: "string",
+				description: "Negative prompt"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					source: { type: "string" },
+					model: { type: "string" },
+					url: { type: "string" },
+					prompt: { type: "string" },
+					hint: { type: "string" }
+				}
+			},
+			render: (_args, result) => [{
+				type: "text",
+				text: result?.hint || "图片已生成"
+			}]
+		},
+		timeoutMs: timeoutMs + 1e4,
+		async execute(params) {
+			if (isDisposed()) throw new Error("modelscope draw tool is no longer mounted");
+			const prompt = str(params?.prompt, "");
+			if (prompt === "") throw new Error("prompt is required");
+			const remaining = cooldown.remainingMs();
+			if (remaining > 0) throw new Error(`draw cooldown: 上一次出图失败，${Math.ceil(remaining / 1e3)}s 后再试`);
+			const apiKey = await resolveApiKey();
+			if (typeof apiKey !== "string" || apiKey.trim() === "") throw new Error("MODELSCOPE_API_KEY 未配置：在面板粘贴 ms- 访问令牌，或设置该环境变量");
+			let picked = [];
+			try {
+				picked = await getEntries?.() ?? [];
+			} catch {
+				picked = [];
+			}
+			const entries = Array.isArray(picked) ? picked : [];
+			const configuredPreferred = str(settings?.drawModelId, "");
+			const panelPreferred = typeof getPreferredModelId === "function" ? await getPreferredModelId().catch(() => null) : null;
+			const preferred = typeof panelPreferred === "string" && panelPreferred.trim() !== "" ? panelPreferred : configuredPreferred;
+			const model = pickDrawModel(entries, str(params?.model, ""), preferred);
+			if (model === null) throw new Error("目录里没有出图模型（image-to-image / text-to-image 条目为空）：确认令牌已配置、面板已至少轮询一次，且套餐含该模型");
+			const rawImages = splitImageUrls(params?.imageUrl);
+			const images = [];
+			for (const raw of rawImages) {
+				const normalized = normalizeImageUrlInput(raw);
+				if (normalized === null) throw new Error(`imageUrl 不可用：${raw.slice(0, 80)} —— 只接受公网 http(s) 链接或 data:image/...;base64 内联数据（本地文件上游取不到，请先上传）`);
+				images.push(normalized);
+			}
+			try {
+				const size = str(params?.size, "");
+				const steps = toPositiveInt(params?.steps);
+				const guidance = toPositiveNumber(params?.guidance);
+				const seed = toNonNegativeInt(params?.seed);
+				const negativePrompt = str(params?.negativePrompt, "");
+				const outcome = await runDrawOnce({
+					fetchImpl,
+					apiBase,
+					apiKey,
+					model,
+					prompt,
+					...images.length > 0 ? { imageUrl: images } : {},
+					...size !== "" ? { size } : {},
+					...steps !== void 0 ? { steps } : {},
+					...guidance !== void 0 ? { guidance } : {},
+					...seed !== void 0 ? { seed } : {},
+					...negativePrompt !== "" ? { negativePrompt } : {},
+					pollDeadlineMs: timeoutMs
+				});
+				const available = drawModelIds(entries);
+				const urls = outcome.images.join("\n");
+				return {
+					source: "modelscope",
+					model: outcome.model,
+					url: outcome.images[0] ?? "",
+					prompt,
+					hint: `图片已生成（上游异步任务，${outcome.polls} 次轮询，task ${outcome.taskId}）\n模型: ${outcome.model}\n${urls}` + (available.length > 0 ? `\n可用出图模型: ${available.join(", ")}` : "")
+				};
+			} catch (error) {
+				cooldown.fail();
+				throw error;
+			}
+		}
+	});
+}
+/**
+* 把工具参数里的输入图拆成列表。
+*
+* 官方支持多图（数组形状），而 agent 工具的参数类型是标量，所以约定**用换行分隔**
+* 多张。同时容忍调用方直接传数组（内部调用与测试会这么用）。
+* @param {unknown} value - 原始参数。
+* @returns {string[]} 拆好的 URL（未归一，调用方逐项过闸）。
+*/
+function splitImageUrls(value) {
+	if (Array.isArray(value)) return value.map((v) => String(v)).filter((v) => v.trim() !== "");
+	const raw = str(value, "");
+	if (raw === "") return [];
+	return raw.split(/\r?\n/).map((v) => v.trim()).filter((v) => v !== "");
+}
+/** 读正整数，非法返回 undefined（不下发无意义参数）。 */
+function toPositiveInt(value) {
+	const n = Number(value);
+	return Number.isFinite(n) && n > 0 ? Math.floor(n) : void 0;
+}
+/** 读非负整数（seed 可为 0）。 */
+function toNonNegativeInt(value) {
+	const n = Number(value);
+	return Number.isFinite(n) && n >= 0 ? Math.floor(n) : void 0;
+}
+/** 读正浮点（guidance 可为小数）。 */
+function toPositiveNumber(value) {
+	const n = Number(value);
+	return Number.isFinite(n) && n > 0 ? n : void 0;
+}
+/** 读 body 文本，读不到给空串（错误分诊不能因为读 body 失败而失败）。 */
+async function safeText(response) {
+	try {
+		return await response.text();
+	} catch {
+		return "";
+	}
+}
+/** 解析 JSON；读不到就返回 `null`，由调用方按「非终态/无 id」处理。 */
+async function safeJson(response, text) {
+	try {
+		return await response.json();
+	} catch {
+		try {
+			return text === "" ? null : JSON.parse(text);
+		} catch {
+			return null;
+		}
+	}
+}
+/** 可注入的 sleep（测试可覆写；这里只提供默认实现）。 */
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+//#endregion
+//#region src/host/draw-tool-state.ts
+/** 当前缺席原因（`null` = 未登记 / 已清掉）。 */
+let note = null;
+/**
+* 记下缺席原因（`null` 清空）。
+* @param {DrawToolAbsentReason|null} reason - 原因码。
+* @returns {void}
+*/
+function setDrawToolNote(reason) {
+	note = reason;
+}
+/**
+* 读当前缺席原因。
+* @returns {DrawToolAbsentReason|null} 原因码。
+*/
+function drawToolNote() {
+	return note;
+}
+/**
+* 清空（卸载时调用：下一个 Host 生命周期从干净的「未登记」开始）。
+* @returns {void}
+*/
+function resetDrawToolNote() {
+	note = null;
+}
+
+//#endregion
+//#region src/host/switch-precedence.ts
+/**
+* 所有 opt-in 开关共用的唯一裁决：「面板保存值 vs 配置默认值」。
+*
+* 规则只有一条：**面板保存值赢，否则配置默认值说了算**。来源标签（`panel` /
+* `config`）随答案一起返回，面板才能说出是谁在管。规则收在一处，是为了让开关
+* 再也无法各自发明一套优先级方言；`test/switch-precedence.test.mjs` 钉死这个
+* 方言，照抄形状的新调用方会被它标成异类。
+*
+* 不服务「纯面板拥有、无配置默认值」的开关——那种没有可裁决的配置默认值，
+* 调用方直接读即可。peer-free，纯函数。
+*
+* @module dsh-connect-modelscope-token-plan/switch-precedence
+*/
+/**
+* Resolve the effective boolean switch: a panel-saved value always wins,
+* otherwise the config default rules.
+* @param {boolean|null} panel - the panel-saved value (`null` = never saved).
+* @param {boolean} config - the patch-declared default.
+* @returns {boolean} the effective switch.
+*/
+function resolveSwitchEnabled(panel, config) {
+	return (panel ?? config) === true;
+}
+/**
+* Resolve the effective string preference (e.g. a draw-model id): a
+* panel-saved value wins, otherwise the config default rules.
+* @param {string|null} panel - the panel-saved value (`null` = never saved).
+* @param {string|undefined} config - the patch-declared default.
+* @returns {string|undefined} the effective preference.
+*/
+function resolveSwitchValue(panel, config) {
+	return panel ?? config;
+}
+/**
+* Where the effective value came from — the panel when it saved one, the
+* config otherwise. Rides with every resolved answer so the panel can name
+* the side in charge.
+* @param {boolean|string|null} panel - the panel-saved value.
+* @returns {"panel"|"config"}
+*/
+function switchSource(panel) {
+	return panel === null ? "config" : "panel";
+}
+
+//#endregion
+//#region src/host/draw-register.ts
+/**
+* 出图工具的挂载副作用：读开关 → 解析目录 → 注册 agent 工具。
+*
+* 与 `provider-publish.ts` 的分工：那个管「魔搭作为 chat provider 的注册」，本文件
+* 管「给 agent 一个出图工具」。两者是**独立的开关**——回答的是不同问题，合并没有
+* 好处（用户可能想用工具出图但不想把魔搭塞进模型选择器，反之亦然）。
+*
+* 承重约束：**peer 的 tools registry 没有 unregister**。所以
+*  - 注册只在挂载时尝试**一次**，不在任何轮询/路由里重复调用；
+*  - 开关在挂载后翻转，要到下次 Host 启动才生效（面板文案必须说这句，否则用户
+*    会以为开关坏了）；
+*  - 目录变化**不需要**重注册：工具在**调用时**才读目录（`getEntries` 是个函数），
+*    所以一次目录刷新会自然被下一次出图看到。
+*
+* 失败一律降级为「工具缺席」，绝不炸掉插件：tools 服务缺失、peer 加载失败、
+* registry 拒收——三种都由 `draw-tool-state.ts` 记下原因供面板显示。本文件不吞
+* 错误（那会让「工具为什么不在」无从诊断），只把它们翻译成可展示的原因码。
+*
+* peer-dependent：`@deepseek-ai/dsh-tools` 由 `deps.loadToolsModule` 惰性注入，
+* 因此本文件与 `llm-adapter.ts` 一样**不能被离线测试导入**，也没有测试覆盖
+* （docs/ROADMAP.md Backlog 记着这条缺口）。
+*
+* @module dsh-connect-modelscope-token-plan/draw-register
+*/
+/**
+* 解析一个可选服务，允许它稍后才注册。
+*
+* 承 sensenova 同名函数的纪律：**重试的是读，不是注册**——工具不能注销，重复注册
+* 比缺席更糟。这里只做有限次立即读取，不做长退避（服务要么已注册，要么这次挂载
+* 就没有）。
+* @param {object} ctx - Host 上下文。
+* @param {string} service - 服务名。
+* @param {() => boolean} isDisposed - 卸载闸。
+* @returns {Promise<object|null>} 服务实例或 `null`。
+*/
+async function resolveService(ctx, service, isDisposed) {
+	for (let attempt = 0; attempt < 3; attempt++) {
+		if (isDisposed()) return null;
+		const found = ctx.get?.(service);
+		if (found !== null && found !== void 0) return found;
+		if (attempt < 2) await new Promise((resolve) => setTimeout(resolve, 50));
+	}
+	return null;
+}
+/**
+* 读一次开关，决定是否注册出图工具。
+* @param {object} ctx - Host 上下文。
+* @param {object} wiring - `{ settings, configError, tokenStore, inference, providerStore, publisher, logger }`。
+* @param {object} deps - 测试缝（`loadToolsModule`、`drawFetch`）。
+* @returns {Promise<void>}
+*/
+async function registerDrawTool(ctx, wiring, deps = {}) {
+	const { settings, configError, tokenStore, inference, drawStore, publisher, logger } = wiring;
+	const loggerFor = logger ?? ctx.logger;
+	setDrawToolNote(null);
+	try {
+		if (configError !== null) return;
+		const panelValue = drawStore ? await drawStore.enabled().catch(() => null) : null;
+		if (resolveSwitchEnabled(panelValue, settings.drawEnabled === true) !== true) return;
+		const isDisposed = () => publisher?.isDisposed?.() === true;
+		const tools = await resolveService(ctx, "tools", isDisposed);
+		if (tools === null || typeof tools.register !== "function") {
+			setDrawToolNote("no-tools-service");
+			return;
+		}
+		let defineTool = null;
+		try {
+			const mod = await Promise.resolve(deps.loadToolsModule ? deps.loadToolsModule() : import("@deepseek-ai/dsh-tools"));
+			defineTool = mod?.defineTool ?? mod?.default?.defineTool ?? null;
+		} catch (error) {
+			setDrawToolNote("peer-load-failed");
+			loggerFor?.warn?.(`${name}: draw tool peer module failed to load (${redactSecrets$1(errMsg(error))}) — the tool is absent`);
+			return;
+		}
+		if (typeof defineTool !== "function") {
+			setDrawToolNote("peer-load-failed");
+			return;
+		}
+		const drawFetch = deps.drawFetch ?? ((url, options) => fetch(url, options));
+		tools.register(defineDrawTool({
+			defineTool,
+			fetchImpl: drawFetch,
+			resolveApiKey: async () => (await tokenStore.resolve()).value,
+			getEntries: async () => {
+				return (await inference.fetchModels().catch(() => null))?.entries ?? [];
+			},
+			getPreferredModelId: async () => {
+				const panelValue = drawStore ? await drawStore.modelId().catch(() => null) : null;
+				return resolveSwitchValue(panelValue, settings.drawModelId === "" ? void 0 : settings.drawModelId) ?? null;
+			},
+			settings: {
+				apiBase: settings.apiBase,
+				drawModelId: settings.drawModelId,
+				drawTimeoutMs: settings.drawTimeoutMs
+			},
+			isDisposed
+		}));
+	} catch (error) {
+		setDrawToolNote("registry-refused");
+		loggerFor?.warn?.(`${name}: draw tool registration refused (${redactSecrets$1(errMsg(error))}) — the tool is absent`);
+	}
+}
+
+//#endregion
+//#region src/host/publish-core.ts
+/**
+* The shared bones of a provider publisher — the parts that MUST NOT differ
+* between upstreams, factored out so they cannot drift.
+*
+* The publisher (`provider-publish.ts` for the ModelScope provider) runs the
+* same control plane: a publish queue, a `disposed` gate, and a single-point
+* pair registration that doubles as the rollback path. Those three are
+* load-bearing and pinned by tests — and the rollback is the worst place to
+* discover a divergence, because it only runs once something has already failed.
+* When they were written twice, keeping them in sync relied on comments in one
+* file pointing at the other; here there is one copy.
+*
+* What is deliberately NOT shared: the publish GATE and the state shape. The
+* ModelScope side decides from "switch on?" plus a persisted catalog and an
+* allow-list, and restores `entries`/`enabledIds`/quota ids on a rollback;
+* another provider's publisher decides from "switch on?" plus "is there a
+* credential?" and restores its roster. That difference is real domain
+* difference, and folding it into one parameterized state machine would make a
+* publish unreadable — every reader would have to read the configuration to
+* know what one does.
+*
+* Peer-free: touches no runtime peer.
+*
+* @module dsh-connect-modelscope-token-plan/publish-core
 */
 /** The event a successful (re)registration emits so readers refresh. */
 const ADAPTERS_UPDATED_EVENT = "llm/adapters-updated";
@@ -1857,6 +3215,15 @@ function registerProviderPair(llm, built, target, { providerId, displayName }) {
 *
 * The module is loaded once and the factory is read off it once, so a Host
 * whose peers resolve slowly pays that cost one time, not per publish.
+*
+* Only the SUCCESS is memoized. The memoized value used to be the promise
+* itself, which pinned a rejection in the slot for the life of the process:
+* after one failed `import()` every later publish rethrew the same error and
+* the provider could never register again — even after the operator fixed the
+* missing peer, which is exactly the remedy this file's own
+* `describeBuildFailure` prints for `ERR_MODULE_NOT_FOUND`. A recoverable
+* install problem cost a Host restart. Clearing the slot on failure keeps
+* "loaded once" for the happy path and gives the next publish a real retry.
 * @param {() => Promise<object>} loadModule - resolves the adapter module.
 * @param {string} exportName - the factory export to read off the module.
 * @returns {() => Promise<Function>} the memoized factory resolver.
@@ -1864,7 +3231,10 @@ function registerProviderPair(llm, built, target, { providerId, displayName }) {
 function createAdapterFactoryResolver(loadModule, exportName) {
 	let adapterFactoryPromise;
 	return async () => {
-		if (adapterFactoryPromise === void 0) adapterFactoryPromise = Promise.resolve(loadModule()).then((mod) => mod?.[exportName]);
+		if (adapterFactoryPromise === void 0) adapterFactoryPromise = Promise.resolve(loadModule()).then((mod) => mod?.[exportName]).catch((error) => {
+			adapterFactoryPromise = void 0;
+			throw error;
+		});
 		return adapterFactoryPromise;
 	};
 }
@@ -1895,7 +3265,7 @@ function describeBuildFailure(error) {
 	const annotated = error;
 	const why = errMsg(error);
 	return {
-		note: redactSecrets(why),
+		note: redactSecrets$1(why),
 		hint: annotated?.code === "ERR_MODULE_NOT_FOUND" ? " — the llm peer packages ship with the Host; install this plugin where they resolve (or link them into its own node_modules)" : "",
 		error
 	};
@@ -1917,6 +3287,13 @@ function warnBuildFailure(logger, label, described) {
 * fact about the Host — not about the provider — so it is one copy: a Host
 * with no `llm` service gets no registration and a stated reason, never a
 * half-built one.
+*
+* The absence routes through {@link unregister}, not a hand-rolled
+* `release(); registered = false`: `state.built` must go down with it. A
+* stale `built` survives into the NEXT publish as its rollback target, so a
+* later failed publish would re-register an adapter whose release has already
+* been called — a rollback path running against a dead pair, which is the
+* worst possible moment to discover the divergence.
 * @param {object} job
 * @param {object} job.state - the publisher state.
 * @param {(service: string) => object|null} job.getLlm - the service resolver.
@@ -1927,9 +3304,11 @@ function resolveRegistrationService({ state, getLlm, release }) {
 	const llm = getLlm("llm");
 	state.llmAvailable = llm !== null && typeof llm.registerAdapter === "function";
 	if (!state.llmAvailable) {
-		release();
-		state.registered = false;
-		state.error = NO_LLM_SERVICE_ERROR;
+		unregister({
+			state,
+			release,
+			error: NO_LLM_SERVICE_ERROR
+		});
 		return null;
 	}
 	return llm;
@@ -1992,16 +3371,14 @@ function swapRegistration({ llm, built, previousBuilt, state, release, registerP
 		release();
 		state.built = null;
 		onRollback?.();
-		state.error = redactSecrets(errMsg(error));
-		if (previousBuilt !== null) try {
-			registerPair(llm, previousBuilt, state);
-			state.built = previousBuilt;
-			state.registered = true;
-		} catch {
-			state.built = null;
-			state.registered = false;
-		}
-		else state.registered = false;
+		state.error = redactSecrets$1(errMsg(error));
+		restorePreviousPair({
+			llm,
+			previousBuilt,
+			state,
+			registerPair,
+			release
+		});
 		return {
 			ok: false,
 			error
@@ -2014,6 +3391,30 @@ function swapRegistration({ llm, built, previousBuilt, state, release, registerP
 	return { ok: true };
 }
 /**
+* 注册失败后恢复先前在服务的 provider 对（如果有）。
+*
+* 从 {@link swapRegistration} 提取，把 catch 块里的嵌套从 4 层降到 2 层——
+* 原实现里 `registerPair(llm, previousBuilt, ...)` 住在 try 内、try 住在
+* catch 内，读起来要数四层缩进才能确认它在做什么。行为完全不变：先摘掉
+* 新对（`release()` 已在调用方做过），再尝试挂回旧对；旧对也注册不上就
+* 诚实地标 `registered: false`。
+*/
+function restorePreviousPair({ llm, previousBuilt, state, registerPair, release }) {
+	if (previousBuilt === null) {
+		state.registered = false;
+		return;
+	}
+	try {
+		registerPair(llm, previousBuilt, state);
+		state.built = previousBuilt;
+		state.registered = true;
+	} catch {
+		release();
+		state.built = null;
+		state.registered = false;
+	}
+}
+/**
 * Emit the adapter-update event, tolerating a Host that has no `emit` and a
 * Host whose `emit` refuses.
 *
@@ -2086,7 +3487,7 @@ function createProviderPublisher(deps = {}) {
 	const { settings, panelSwitch, loadAdapterModule, getLlm, resolveApiKey, usage, emit, logger } = deps;
 	const effectiveSettings = settings ?? {};
 	const effectivePanelSwitch = panelSwitch ?? (async () => null);
-	const effectiveLoadAdapterModule = loadAdapterModule ?? (() => import("./llm-adapter-DnaNNORe.js"));
+	const effectiveLoadAdapterModule = loadAdapterModule ?? (() => import("./llm-adapter.js"));
 	const effectiveGetLlm = getLlm ?? (() => null);
 	const effectiveResolveApiKey = resolveApiKey ?? (async () => "");
 	const effectiveLogger = logger ?? { warn: () => {} };
@@ -2134,6 +3535,15 @@ function createProviderPublisher(deps = {}) {
 		displayName: LLM_DISPLAY_NAME
 	});
 	/**
+	* 空转守卫的公共判据：目录 offer 与额度耗尽集合是否都没变。
+	*
+	* 两处空转守卫（开关关着 / 开关开着）共用这个签名比对——公式与轮询同源
+	* （由 {@link syncSignaturesAfterPublish} 内部调用导出的 {@link catalogSignature}
+	* 与 {@link quotaSignatureOf}），不会漂移。提取成函数避免两处各写一遍。
+	* @returns {boolean} true = offer 没变，可以跳过这次 publish。
+	*/
+	const offerUnchanged = () => state.signature === catalogSignature(state.entries, state.enabledIds) && state.quotaSignature === quotaSignatureOf(state.unavailableIds);
+	/**
 	* 为一个目录/允许清单快照（重）构建并注册 provider。
 	*
 	* 重建并重注册而非原地改：`PiAiAdapter` 内部 memoize profiles 快照，只有新的注册
@@ -2158,7 +3568,7 @@ function createProviderPublisher(deps = {}) {
 		state.unavailableIds = Array.isArray(unavailableModelIds) ? unavailableModelIds : [];
 		const panelValue = await effectivePanelSwitch().catch(() => null);
 		if (!resolveSwitchEnabled(panelValue, effectiveSettings.registerProvider === true)) {
-			if (state.registered === false && state.error === null && state.signature === catalogSignature(state.entries, state.enabledIds) && state.quotaSignature === quotaSignatureOf(state.unavailableIds)) return {
+			if (state.registered === false && state.error === null && offerUnchanged()) return {
 				ok: true,
 				skipped: true
 			};
@@ -2202,7 +3612,7 @@ function createProviderPublisher(deps = {}) {
 				error: described.error
 			};
 		}
-		if (state.registered === true && state.error === null && state.signature === catalogSignature(state.entries, state.enabledIds) && state.quotaSignature === quotaSignatureOf(state.unavailableIds)) return {
+		if (state.registered === true && state.error === null && offerUnchanged()) return {
 			ok: true,
 			skipped: true
 		};
@@ -2210,6 +3620,7 @@ function createProviderPublisher(deps = {}) {
 			ok: false,
 			skipped: true
 		};
+		const requestedSignature = catalogSignature(state.entries, state.enabledIds);
 		const result = swapRegistration({
 			llm,
 			built,
@@ -2225,6 +3636,7 @@ function createProviderPublisher(deps = {}) {
 			}
 		});
 		syncSignaturesAfterPublish(state);
+		if (result.ok === false && state.registered === true && state.signature === requestedSignature) state.error = null;
 		return result;
 	};
 	/**
@@ -2305,7 +3717,9 @@ function syncSignaturesAfterPublish(state) {
 //#region src/host/routes/paths.ts
 /**
 * 路由字面量。浏览器 bundle（src/client/const.ts）无法从 host-config 导入，
-* 两边各写一份字面量——由 test/config.test.mjs 钉住相等，改名时先红再改。
+* 两边各写一份字面量——由 test/panel.test.mjs 的 §6/§6b 钉住两端解析出的完整
+* 路径集合双向相等，改名时先红再改。（原注释指向 test/config.test.mjs，但那套
+* 钉的是 CONFIG_DEFAULTS ↔ cordis.patch.yml，不含路由字面量。）
 * @module dsh-connect-modelscope-token-plan/routes/paths
 */
 const SNAPSHOT_PATH = "/api/dsh-connect-modelscope-token-plan/snapshot";
@@ -2314,6 +3728,7 @@ const TOKEN_PATH = "/api/dsh-connect-modelscope-token-plan/token";
 const TOKEN_FORGET_PATH = "/api/dsh-connect-modelscope-token-plan/token/forget";
 const PROBE_PATH = "/api/dsh-connect-modelscope-token-plan/probe";
 const PROVIDER_PATH = "/api/dsh-connect-modelscope-token-plan/provider";
+const DRAW_PATH = "/api/dsh-connect-modelscope-token-plan/draw";
 
 //#endregion
 //#region src/host/snapshot-aggregate.ts
@@ -2352,7 +3767,7 @@ async function soft(promise) {
 		const code = error.code;
 		return {
 			ok: false,
-			error: redactSecrets(errMsg(error)),
+			error: redactSecrets$1(errMsg(error)),
 			code: typeof code === "string" ? code : CODE.INTERNAL_ERROR
 		};
 	}
@@ -2372,43 +3787,47 @@ function providerDegraded(error) {
 		enabledCount: 0,
 		allowed: "all",
 		enabledIds: [],
+		contextWindow: null,
 		roster: []
 	};
 }
 /** 聚合快照 body。wiring 子集见 routes/snapshot.ts 的 Pick。 */
 async function buildSnapshotBody(wiring) {
-	const { settings, tokenStore, usageStore, inference, providerStore, publisher } = wiring;
-	const [tokenState, daily, perModel, trend, events] = await Promise.all([
+	const { settings, tokenStore, usageStore, inference, providerStore, drawStore, publisher } = wiring;
+	const [tokenState, daily, perModel, trend, events, providerNote] = await Promise.all([
 		soft(tokenStore.state()),
 		soft(usageStore.daily()),
 		soft(usageStore.perModelToday()),
 		soft(usageStore.trend(settings.trendDays)),
-		soft(usageStore.events())
+		soft(usageStore.events()),
+		soft(providerStore.versionNote())
 	]);
 	const shapeWarnings = [];
 	const usageAnomaly = usageStore.anomaly();
 	if (usageAnomaly !== null) shapeWarnings.push(usageAnomaly);
-	for (const path of [
-		tokenState,
-		daily,
-		perModel,
-		trend,
-		events
-	]) if (!path.ok) shapeWarnings.push(`usage-source failed (${path.code}): ${path.error}`);
-	const tokenPresent = tokenState.ok ? tokenState.value.present : false;
-	const balance = await soft(inference.fetchBalance());
-	const models = await soft(inference.fetchModels());
+	for (const [label, path] of [
+		["token", tokenState],
+		["daily", daily],
+		["per-model", perModel],
+		["trend", trend],
+		["events", events]
+	]) if (!path.ok) shapeWarnings.push(`${label} source failed (${path.code}): ${path.error}`);
+	const tokenKnownAbsent = tokenState.ok && tokenState.value.present === false;
+	const contextOverride = await providerStore.contextWindow().catch(() => null);
+	const [balance, models] = await Promise.all([soft(inference.fetchBalance()), soft(inference.fetchModels(contextOverride))]);
 	const modelIds = models.ok ? models.value.ids : [];
 	const modelEntries = models.ok ? models.value.entries : [];
 	if (!models.ok && models.code !== "network_error") shapeWarnings.push(`models: ${models.error}`);
-	if (tokenPresent && !balance.ok && balance.code !== "network_error") shapeWarnings.push(`balance: ${balance.error}`);
+	if (!tokenKnownAbsent && !balance.ok && balance.code !== "network_error") shapeWarnings.push(`balance: ${balance.error}`);
+	if (providerNote.ok && providerNote.value !== null) shapeWarnings.push(providerNote.value);
 	const provider = await soft((async () => {
 		const panel = await providerStore.enabled().catch(() => null);
 		const enabled = resolveSwitchEnabled(panel, settings.registerProvider);
 		const source = switchSource(panel);
 		const roster = rosterWithAvailability(modelEntries, []);
 		const stored = await providerStore.enabledIds().catch(() => null);
-		const enabledIds = Array.isArray(stored) ? stored : Array.isArray(publisher.state.enabledIds) ? publisher.state.enabledIds : [];
+		const enabledIds = resolveEnabledIds(stored, publisher.state.enabledIds);
+		const contextWindow = await providerStore.contextWindow().catch(() => null);
 		const allowed = resolveAllowedList(enabledIds);
 		const allowSet = new Set(enabledIds);
 		const enabledCount = allowed === "all" ? roster.length : allowed === "list" ? roster.filter((row) => allowSet.has(row.id)).length : 0;
@@ -2422,10 +3841,27 @@ async function buildSnapshotBody(wiring) {
 			enabledCount,
 			allowed,
 			enabledIds,
+			contextWindow,
 			roster
 		};
 	})());
-	const usedLocal = daily.ok ? daily.value.calls : 0;
+	const draw = await soft((async () => {
+		const panel = await drawStore.enabled().catch(() => null);
+		const panelModel = await drawStore.modelId().catch(() => null);
+		const candidateIds = imageGenModelIds(modelEntries);
+		return {
+			enabled: resolveSwitchEnabled(panel, settings.drawEnabled),
+			source: switchSource(panel),
+			candidateIds,
+			candidateCount: candidateIds.length,
+			preferredModel: resolveSwitchValue(panelModel, settings.drawModelId === "" ? void 0 : settings.drawModelId) ?? null,
+			preferredSource: switchSource(panelModel),
+			absentReason: drawToolNote(),
+			mountPending: resolveSwitchEnabled(panel, settings.drawEnabled) === true && drawToolNote() !== null,
+			toolName: "modelscope_draw_image"
+		};
+	})());
+	const usedLocal = daily.ok ? daily.value.calls : null;
 	return {
 		ok: true,
 		name,
@@ -2433,12 +3869,16 @@ async function buildSnapshotBody(wiring) {
 		now: (/* @__PURE__ */ new Date()).toISOString(),
 		pollSeconds: settings.pollSeconds,
 		cacheSeconds: settings.cacheSeconds,
-		token: tokenState.ok ? tokenState.value : {
+		token: tokenState.ok ? {
+			...tokenState.value,
+			readError: null
+		} : {
 			present: false,
 			source: "none",
 			valid: null,
 			checkedAt: null,
-			ephemeral: true
+			ephemeral: true,
+			readError: tokenState.error
 		},
 		balance: balance.ok ? {
 			available: balance.value.available,
@@ -2451,7 +3891,7 @@ async function buildSnapshotBody(wiring) {
 			total: null,
 			frozen: null,
 			fetchedAt: null,
-			error: tokenPresent ? balance.error : null
+			error: tokenKnownAbsent ? null : balance.error
 		},
 		quota: {
 			daily: { usedLocal },
@@ -2470,6 +3910,7 @@ async function buildSnapshotBody(wiring) {
 			error: models.ok ? null : models.error
 		},
 		provider: provider.ok ? provider.value : providerDegraded(provider.error),
+		...draw.ok ? { draw: draw.value } : {},
 		shapeWarnings,
 		quotaError: null
 	};
@@ -2567,9 +4008,25 @@ function refuseMethod(response) {
 * 日志或响应）。redactSecrets 幂等，双重应用无害。
 */
 function redactedError(error) {
-	const text = redactSecrets(errMsg(error));
+	const text = redactSecrets$1(errMsg(error));
 	return text.trim() === "" ? "request failed" : text;
 }
+/**
+* 写盘/操作失败的统一响应：HTTP 恒 200、成败看 body（与快照路由同一语义，
+* 一次写失败不许顺着渲染树炸穿）。**用户显式操作的失败必须上屏**，所以
+* 调用方不吞、这里只负责脱敏后的标准形状。provider 开关/清单/reset 与
+* token save/forget 五处 catch 曾各写一遍这个 writeJson——集中成一份，
+* 措辞与形状不会漂移。
+* @param {object} response - webServer 的响应对象。
+* @param {unknown} error - catch 到的任意值（未必是 Error）。
+* @returns {void}
+*/
+function respondError(response, error) {
+	writeJson(response, 200, {
+		ok: false,
+		error: redactedError(error)
+	}, { "cache-control": "no-store" });
+}
 /** 读并校验 JSON body，失败时写 400 并返回 null（调用方的停手信号）。 */
 async function readJsonBodyOr400(request, response, limit = MAX_JSON_BODY_BYTES) {
 	const body = await readJsonBody(request, limit);
@@ -2702,7 +4159,14 @@ function registerModelsRoute(ctx, wiring) {
 * 简化（SPIKE.md §结论 3）。
 * @module dsh-connect-modelscope-token-plan/routes/token
 */
-/** 注册令牌路由（POST /token 保存，POST /token/forget 忘掉）。 */
+/**
+* 注册令牌路由（POST /token 保存，POST /token/forget 忘掉）。
+*
+* 返回类型是本族唯一的一个**数组**：token 注册两条路由（save + forget），其余
+* 路由族各只注册一条、返回单个 off()。标注在**这里**而不是在 routes.ts 里对
+* 调用结果做 `as Array<() => void>` 断言——断言放在消费端等于把「这两条返回的是
+* 注销回调而不是 handler」这个约定藏起来，标注在产地才是声明。
+*/
 function registerTokenRoute(ctx, wiring) {
 	const { settings, tokenStore } = wiring;
 	const save = withOrigin(async (request, response) => {
@@ -2727,10 +4191,7 @@ function registerTokenRoute(ctx, wiring) {
 				...await tokenStore.state()
 			}, { "cache-control": "no-store" });
 		} catch (error) {
-			writeJson(response, 200, {
-				ok: false,
-				error: redactedError(error)
-			}, { "cache-control": "no-store" });
+			respondError(response, error);
 		}
 	}, settings.allowedHosts);
 	const forget = withOrigin(async (request, response) => {
@@ -2745,10 +4206,7 @@ function registerTokenRoute(ctx, wiring) {
 				...await tokenStore.state()
 			}, { "cache-control": "no-store" });
 		} catch (error) {
-			writeJson(response, 200, {
-				ok: false,
-				error: redactedError(error)
-			}, { "cache-control": "no-store" });
+			respondError(response, error);
 		}
 	}, settings.allowedHosts);
 	return [ctx.webServer.register({
@@ -2807,13 +4265,15 @@ function registerProbeRoute(ctx, wiring) {
 			}
 			try {
 				const result = await inference.probe({ modelId });
+				wiring.tokenStore.noteValidity(true);
 				writeJson(response, 200, {
 					...result,
-					tokenState: await wiring.tokenStore.state()
+					tokenState: await wiring.tokenStore.state().catch(() => null)
 				}, { "cache-control": "no-store" });
 			} catch (error) {
 				const code = error.code;
 				const message = redactedError(error);
+				if (code === CODE.AUTH_ERROR) wiring.tokenStore.noteValidity(false);
 				const eventKind = code === CODE.QUOTA_EXCEEDED ? "quota" : code === CODE.RATE_LIMITED ? "rate_limit" : "error";
 				await usageStore.recordEvent({
 					modelId,
@@ -2837,13 +4297,15 @@ function registerProbeRoute(ctx, wiring) {
 //#endregion
 //#region src/host/routes/provider.ts
 /**
-* provider 注册路由：开关读/写、允许清单保存、回退默认。
+* provider 注册路由：开关读/写、允许清单保存、上下文窗口覆盖、回退默认。
 *
-* 三件事（§9）：
-*   - GET  `PROVIDER_PATH`        读当前开关 + 目录 + 允许清单 + 注册状态（无副作用）；
-*   - POST `PROVIDER_PATH`        body `{enabled?: boolean}` → 保存面板开关并重注册；
-*   - POST `PROVIDER_PATH/roster` body `{enabledIds?: string[]}` → 保存允许清单并重注册；
-*   - POST `PROVIDER_PATH/reset`  忘掉面板开关与允许清单，回到 patch 默认。
+* 四件事（§9）：
+*   - GET  `PROVIDER_PATH`           读当前开关 + 目录 + 允许清单 + 注册状态（无副作用）；
+*   - POST `PROVIDER_PATH`           body `{enabled?: boolean}` → 保存面板开关并重注册；
+*   - POST `PROVIDER_PATH/roster`    body `{enabledIds?: string[]}` → 保存允许清单并重注册；
+*   - POST `PROVIDER_PATH/context`   body `{contextWindow: number|null}` → 保存全局上下文
+*     窗口覆盖并重注册（null = 跟随目录）；
+*   - POST `PROVIDER_PATH/reset`     忘掉面板开关、允许清单与窗口覆盖，回到 patch 默认。
 *
 * `withOrigin` 围栏与 `refuseMethod` 照现有路由；写开关/清单失败**必须传播**
 * （`ok:false` + error），不静默吞——这是用户的显式操作，面板必须看见它没生效。
@@ -2853,9 +4315,16 @@ function registerProbeRoute(ctx, wiring) {
 */
 /**
 * 读目录条目，读不到按空目录降级（GET 不能因目录失败把整个面板状态打掉）。
+*
+* 读目录前先取**当前窗口覆盖**传给 `fetchModels`：条目在归一前打上覆盖标记，
+* descriptor / roster / catalogSignature 都从这份条目派生。每个写路由（开关、
+* 清单、窗口、reset）都经这里取条目再 publish，所以任何一次重注册都带着最新
+* 覆盖——否则先存窗口、再存清单会把未打标的目录重新注册上去，覆盖静默失效到
+* 下一轮轮询。
 */
-async function readEntries(inference) {
-	const catalog = await inference.fetchModels().catch((error) => {
+async function readEntries$1(inference, providerStore) {
+	const contextWindow = await optional(providerStore?.contextWindow?.(), null);
+	const catalog = await inference.fetchModels(contextWindow).catch((error) => {
 		return {
 			entries: [],
 			__error: error
@@ -2865,11 +4334,12 @@ async function readEntries(inference) {
 }
 /**
 * 读「当前」允许清单：优先持久化的，否则 publisher 最近 publish 的那份。
+*
+* 判据是**共用**的 resolveEnabledIds（provider-store）——本文件与面板聚合、
+* index.ts 的轮询必须对「空清单」给同一个答案，否则三个界面各说一套。
 */
 async function readEnabledIds(store, published) {
-	const stored = await optional(store.enabledIds?.(), null);
-	if (Array.isArray(stored)) return stored;
-	return Array.isArray(published) ? published : [];
+	return resolveEnabledIds(await optional(store.enabledIds?.(), null), published);
 }
 /**
 * `allowed` 的分类：委托给 `llm-models.ts` 的单一口径
@@ -2902,7 +4372,8 @@ function registerProviderRoute(ctx, wiring) {
 	const snapshot = async (extra = {}) => {
 		const panelSwitch = await optional(providerStore.enabled());
 		const enabledIds = await readEnabledIds(providerStore, publisher.state.enabledIds);
-		const entries = await readEntries(inference);
+		const contextWindow = await optional(providerStore.contextWindow?.(), null);
+		const entries = await readEntries$1(inference, providerStore);
 		const roster = rosterWithAvailability(entries, []);
 		const allowed = allowedOf(enabledIds);
 		const modelCount = roster.length;
@@ -2918,6 +4389,7 @@ function registerProviderRoute(ctx, wiring) {
 			enabledCount: allowed === "all" ? modelCount : allowed === "none" ? 0 : roster.filter((row) => allowSet.has(row.id)).length,
 			allowed,
 			enabledIds,
+			contextWindow,
 			roster,
 			...extra
 		};
@@ -2947,13 +4419,10 @@ function registerProviderRoute(ctx, wiring) {
 			}
 			try {
 				await providerStore.save(body.enabled);
-				const entries = await readEntries(inference);
+				const entries = await readEntries$1(inference, providerStore);
 				await publisher.publish(entries, await readEnabledIds(providerStore, publisher.state.enabledIds), []);
 			} catch (error) {
-				writeJson(response, 200, {
-					ok: false,
-					error: redactedError(error)
-				}, { "cache-control": "no-store" });
+				respondError(response, error);
 				return;
 			}
 			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
@@ -2979,15 +4448,40 @@ function registerProviderRoute(ctx, wiring) {
 			const ids = body.enabledIds.filter((id) => typeof id === "string" && id !== "");
 			try {
 				await providerStore.saveEnabledIds?.(ids);
-				const entries = await readEntries(inference);
+				const entries = await readEntries$1(inference, providerStore);
 				await publisher.publish(entries, ids, []);
 			} catch (error) {
-				writeJson(response, 200, {
+				respondError(response, error);
+				return;
+			}
+			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+		}, settings.allowedHosts)
+	}));
+	offs.push(ctx.webServer.register({
+		kind: "exact",
+		path: `${PROVIDER_PATH}/context`,
+		handler: withOrigin(async (request, response) => {
+			if ((request.method === void 0 ? "POST" : request.method) !== "POST") {
+				refuseMethod(response);
+				return;
+			}
+			const body = await readJsonBodyOr400(request, response);
+			if (body === null) return;
+			if (body.contextWindow !== null && (typeof body.contextWindow !== "number" || !Number.isFinite(body.contextWindow) || body.contextWindow <= 0)) {
+				writeJson(response, 400, {
 					ok: false,
-					error: redactedError(error)
+					error: "expected { contextWindow: number | null }"
 				}, { "cache-control": "no-store" });
 				return;
 			}
+			try {
+				await providerStore.saveContextWindow?.(body.contextWindow);
+				const entries = await readEntries$1(inference, providerStore);
+				await publisher.publish(entries, await readEnabledIds(providerStore, publisher.state.enabledIds), []);
+			} catch (error) {
+				respondError(response, error);
+				return;
+			}
 			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
 		}, settings.allowedHosts)
 	}));
@@ -3006,15 +4500,182 @@ function registerProviderRoute(ctx, wiring) {
 			try {
 				await providerStore.forget();
 				await providerStore.saveEnabledIds?.([]);
-				const entries = await readEntries(inference);
+				const entries = await readEntries$1(inference, providerStore);
 				await publisher.publish(entries, [], []);
 			} catch (error) {
-				writeJson(response, 200, {
+				respondError(response, error);
+				return;
+			}
+			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+		}, settings.allowedHosts)
+	}));
+	return () => {
+		for (const off of offs) try {
+			off();
+		} catch (error) {
+			logger?.warn?.(`provider route unregister failed: ${redactedError(error)}`);
+		}
+	};
+}
+
+//#endregion
+//#region src/host/routes/draw.ts
+/**
+* 出图工具路由：开关读/写、模型偏好保存、回到默认。
+*
+* 三条路径：
+*   - GET  `DRAW_PATH`        读开关 + 出图候选模型 + 工具挂载状态（无副作用）；
+*   - POST `DRAW_PATH`        body `{enabled?: boolean, modelId?: string|null}` → 保存；
+*   - POST `DRAW_PATH/reset`  忘掉面板值，回到 patch 默认。
+*
+* **与 provider 路由刻意分开**：provider 管「魔搭作为 chat provider」，本路由管
+* 「给 agent 一个出图工具」。两者的开关、状态文件、候选集合都不同，合并会让
+* 「关掉出图」波及 provider 的注册时序（详见 draw-store.ts 的头注）。
+*
+* 一处**与 provider 路由不同**的地方必须说清：provider 开关翻转会**立即**重注册
+* （publish 是活的重建），而出图工具的开关翻转**要等下次 Host 启动**——peer 的
+* tools registry 没有 unregister，工具一旦注册就摘不下来。所以本路由保存成功后
+* 不改挂载状态，只在响应里给出 `mountPending`，让面板能说清这件事，而不是让用户
+* 以为开关坏了。
+*
+* peer-free：不 import 任何 Host peer。
+* @module dsh-connect-modelscope-token-plan/routes/draw
+*/
+/**
+* 读目录条目，读不到按空目录降级。
+*
+* 与 provider 路由同一条纪律：GET 不能因为一次目录失败就把整个面板状态打掉——
+* 出图候选为空只影响「能不能挑模型」，不影响开关的显示。
+* @param {object} inference - inference client。
+* @returns {Promise<unknown[]>} 归一目录条目。
+*/
+async function readEntries(inference) {
+	const catalog = await inference.fetchModels().catch(() => ({ entries: [] }));
+	return Array.isArray(catalog?.entries) ? catalog.entries : [];
+}
+/**
+* 注册出图路由（两条路径）。
+* @param ctx - host 根上下文（只用 `ctx.webServer`）。
+* @param {DrawRouteWiring} wiring - 本路由读到的子集。
+* @returns {Function} 注销回调。
+*/
+function registerDrawRoute(ctx, wiring) {
+	const { settings, drawStore, inference, logger } = wiring;
+	/**
+	* 组装响应。GET 与写成功后的响应共用，两个方向不可能对「当前状态」说两套话。
+	* @param {object} [extra] - 追加/覆盖字段。
+	* @returns {Promise<object>} 响应体。
+	*/
+	const snapshot = async (extra = {}) => {
+		const panelSwitch = await optional(drawStore.enabled());
+		const panelModelId = await optional(drawStore.modelId());
+		const entries = await readEntries(inference);
+		const candidateIds = imageGenModelIds(entries);
+		const effectiveModelId = resolveSwitchValue(panelModelId, settings.drawModelId === "" ? void 0 : settings.drawModelId) ?? null;
+		return {
+			ok: true,
+			enabled: resolveSwitchEnabled(panelSwitch, settings.drawEnabled),
+			source: switchSource(panelSwitch),
+			candidateIds,
+			candidateCount: candidateIds.length,
+			preferredModel: effectiveModelId,
+			preferredSource: switchSource(panelModelId),
+			absentReason: drawToolNote(),
+			/**
+			* 开关的保存**不会**改变本次挂载的工具。
+			*
+			* 工具无法注销（peer 的 tools registry 没有 unregister），所以开关翻转只在
+			* 下次 Host 启动时生效。面板据此显示一句说明——否则用户会以为开关坏了。
+			* 判据：开关为开且本次挂载尚未注册成功（或缺席原因未知）。
+			*/
+			mountPending: resolveSwitchEnabled(panelSwitch, settings.drawEnabled) === true && drawToolNote() !== null,
+			toolName: "modelscope_draw_image",
+			...extra
+		};
+	};
+	const offs = [];
+	offs.push(ctx.webServer.register({
+		kind: "exact",
+		path: DRAW_PATH,
+		handler: withOrigin(async (request, response) => {
+			const method = request.method === void 0 ? "GET" : request.method;
+			if (method === "GET") {
+				writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+				return;
+			}
+			if (method !== "POST") {
+				refuseMethod(response);
+				return;
+			}
+			const body = await readJsonBodyOr400(request, response);
+			if (body === null) return;
+			const hasEnabled = typeof body.enabled === "boolean";
+			const hasModel = body.modelId === null || typeof body.modelId === "string";
+			if (!hasEnabled && !hasModel) {
+				writeJson(response, 400, {
 					ok: false,
-					error: redactedError(error)
+					error: "expected { enabled?: boolean, modelId?: string|null }"
+				}, { "cache-control": "no-store" });
+				return;
+			}
+			if (body.enabled !== void 0 && !hasEnabled) {
+				writeJson(response, 400, {
+					ok: false,
+					error: "enabled must be a boolean"
 				}, { "cache-control": "no-store" });
 				return;
 			}
+			if (body.modelId !== void 0 && !hasModel) {
+				writeJson(response, 400, {
+					ok: false,
+					error: "modelId must be a string or null"
+				}, { "cache-control": "no-store" });
+				return;
+			}
+			try {
+				if (hasEnabled) {
+					const refusal = await drawStore.saveEnabled(body.enabled);
+					if (refusal !== null) {
+						respondError(response, new Error(refusal));
+						return;
+					}
+				}
+				if (body.modelId !== void 0) {
+					const refusal = await drawStore.saveModelId(body.modelId);
+					if (refusal !== null) {
+						respondError(response, new Error(refusal));
+						return;
+					}
+				}
+			} catch (error) {
+				respondError(response, error);
+				return;
+			}
+			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
+		}, settings.allowedHosts)
+	}));
+	offs.push(ctx.webServer.register({
+		kind: "exact",
+		path: `${DRAW_PATH}/reset`,
+		handler: withOrigin(async (request, response) => {
+			if ((request.method === void 0 ? "POST" : request.method) !== "POST") {
+				refuseMethod(response);
+				return;
+			}
+			await readJsonBody(request, MAX_JSON_BODY_BYTES).catch(() => ({
+				ok: false,
+				error: "ignored"
+			}));
+			try {
+				const refusal = await drawStore.reset();
+				if (refusal !== null) {
+					respondError(response, new Error(refusal));
+					return;
+				}
+			} catch (error) {
+				respondError(response, error);
+				return;
+			}
 			writeJson(response, 200, await snapshot(), { "cache-control": "no-store" });
 		}, settings.allowedHosts)
 	}));
@@ -3022,7 +4683,7 @@ function registerProviderRoute(ctx, wiring) {
 		for (const off of offs) try {
 			off();
 		} catch (error) {
-			logger?.warn?.(`provider route unregister failed: ${redactedError(error)}`);
+			logger?.warn?.(`draw route unregister failed: ${redactedError(error)}`);
 		}
 	};
 }
@@ -3042,7 +4703,8 @@ function registerRoutes(ctx, wiring) {
 		registerModelsRoute(ctx, wiring),
 		...registerTokenRoute(ctx, wiring),
 		registerProbeRoute(ctx, wiring),
-		registerProviderRoute(ctx, wiring)
+		registerProviderRoute(ctx, wiring),
+		registerDrawRoute(ctx, wiring)
 	];
 }
 
@@ -3051,8 +4713,12 @@ function registerRoutes(ctx, wiring) {
 /**
 * dsh-connect-modelscope-token-plan — Host 半边（thin router）。
 *
-* 读魔搭 API-Inference 的**本地用量**（上游没有余额接口，见 docs/SPIKE.md）
-* 并经一条只读 /api 路由喂给 Client 面板。重活都在专注的兄弟模块里，本文件
+* 读魔搭 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 信任围栏
@@ -3072,11 +4738,16 @@ function registerRoutes(ctx, wiring) {
 * @param ctx - Host 根上下文。
 * @param config - 行的原始 patch 配置（无 schema，未校验；坏配置以
 *   configError 经快照呈现，而不是在挂载时炸掉整台插件）。
-* @param deps - 测试缝（fetchImpl）。真实 Loader 不传。
+* @param deps - 测试缝（`HostDeps`：fetchImpl / getLlm / emit / credentials / env
+*   与出图那两条）。真实 Loader 不传；**每个缝不传时都必须落回 ctx 或全局默认**，
+*   产品行为零漂移。声明与接线由 `test/deps-wiring.test.mjs` 双向扫描守着。
 */
 function apply(ctx, config = {}, deps = {}) {
 	const { settings, configError } = resolveSettings(config);
-	const tokenStore = createTokenStore({ credentials: () => ctx.get("credentials") ?? null });
+	const tokenStore = createTokenStore({
+		credentials: deps.credentials !== void 0 ? deps.credentials : () => ctx.get("credentials") ?? null,
+		env: deps.env
+	});
 	const profile = profileSegment(ctx);
 	const usageStore = createFileUsageStore({
 		name,
@@ -3095,10 +4766,14 @@ function apply(ctx, config = {}, deps = {}) {
 		profile,
 		logger: ctx.logger
 	});
+	const drawStore = createFileDrawStore({
+		profile,
+		logger: ctx.logger
+	});
 	const publisher = createProviderPublisher({
 		settings,
 		panelSwitch: () => providerStore.enabled(),
-		getLlm: (service) => ctx.get?.(service) ?? null,
+		getLlm: deps.getLlm ?? ((service) => ctx.get?.(service) ?? null),
 		resolveApiKey: async () => (await tokenStore.resolve()).value,
 		usage: {
 			recordCall: (input) => usageStore.recordCall({
@@ -3107,24 +4782,52 @@ function apply(ctx, config = {}, deps = {}) {
 			}).catch(() => {}),
 			recordEvent: (input) => usageStore.recordEvent(input).catch(() => {})
 		},
-		emit: (event) => ctx.emit?.(event),
+		emit: deps.emit ?? ((event) => ctx.emit?.(event)),
+		...deps.loadAdapterModule ? { loadAdapterModule: deps.loadAdapterModule } : {},
 		logger: ctx.logger
 	});
 	/**
-	* 一次目录轮询：拉目录 + 读落盘允许清单，再 publish 当前 offer。
+	* 当前允许清单：落盘优先，读不到回退内存最近一次 publish 的清单。
+	*
+	* 判据与另外两个消费者（`snapshot-aggregate.ts` 的面板块、`routes/provider.ts`
+	* 的 GET）**共用** {@link resolveEnabledIds}——空清单是「不过滤，提供全部模型」，
+	* 那是 provider-store 的契约，不是「没有答案」。本函数曾经自己写成
+	* `stored.length > 0` 才算数，于是**可读的空清单**（操作者按 versionNote 的建议
+	* 删掉 provider.json，或清单被保存为空）会让面板说 all、轮询却继续按内存里的旧
+	* 清单注册：面板与 Host 对「正在提供什么」各说一套。只有读**抛错**（`.catch`
+	* → null）才回退内存。
+	* @returns {Promise<string[]>}
+	*/
+	const currentEnabledIds = async () => resolveEnabledIds(await providerStore.enabledIds().catch(() => null), publisher.state.enabledIds);
+	/**
+	* 一次目录轮询：拉目录，再 publish 当前 offer。
+	*
+	* **窗口覆盖必须参与**：catalogSignature 含窗口值，轮询若用未打标条目 publish，
+	* 用户保存覆盖后的每次轮询都会因「签名不同」把注册摘下重挂（覆盖每 pollSeconds
+	* 静默回退一次、适配器每轮重建）。所以 fetch **前**先读落盘覆盖传给 fetchModels，
+	* 与 `currentEnabledIds` 同一模式。
 	*
-	* 允许清单必须走 `providerStore.enabledIds()`——清单是**落盘**的（provider-store
-	* 按 profile 分段持久化），重启后内存里的 `publisher.state.enabledIds` 早已清空，
-	* 若从它读，用户勾选的清单会随重启静默丢失（见 fix A）。
+	* fetch **后**再读一次：目录拉取可能耗时数百毫秒，期间用户可能保存了新覆盖——
+	* 保存路由已经用新值 publish 过，此时用旧标条目 publish 反而把注册**倒退**一个
+	* 周期；这种窗口内跳过本轮即可（下一轮轮询自然带新值）。清单沿用 fetch 后读的
+	* 老顺序（捕获 fetch 期间的编辑），两条时序理由同源。
 	* @returns {Promise<void>}
 	*/
 	const runPoll = async () => {
+		const contextWindow = await providerStore.contextWindow().catch(() => null);
+		let catalog = null;
 		try {
-			const catalog = await inference.fetchModels();
-			const stored = await providerStore.enabledIds().catch(() => null);
-			const enabledIds = Array.isArray(stored) && stored.length > 0 ? stored : Array.isArray(publisher.state.enabledIds) ? publisher.state.enabledIds : [];
-			await publisher.publish(catalog.entries, enabledIds, []);
-		} catch {}
+			catalog = await inference.fetchModels(contextWindow);
+		} catch (error) {
+			ctx.logger?.warn?.(`${name}: catalog fetch failed (${redactSecrets$1(errMsg(error))}) — the next poll retries; the panel keeps its degraded models block`);
+			return;
+		}
+		if (await providerStore.contextWindow().catch(() => null) !== contextWindow) return;
+		try {
+			await publisher.publish(catalog.entries, await currentEnabledIds(), []);
+		} catch (error) {
+			ctx.logger?.warn?.(`${name}: publish failed (${redactSecrets$1(errMsg(error))}) — the catalog is current, only the provider registration did not land`);
+		}
 	};
 	const wiring = {
 		settings,
@@ -3133,23 +4836,26 @@ function apply(ctx, config = {}, deps = {}) {
 		usageStore,
 		inference,
 		providerStore,
+		drawStore,
 		publisher,
 		logger: ctx.logger
 	};
 	const offs = registerRoutes(ctx, wiring);
 	ctx.effect(() => {
 		runPoll();
+		registerDrawTool(ctx, wiring, deps);
 		const timer = setInterval(() => {
 			runPoll();
 		}, settings.pollSeconds * 1e3);
 		return () => {
 			clearInterval(timer);
+			resetDrawToolNote();
 			publisher.dispose();
 			publisher.release();
 			for (const off of offs) try {
 				off?.();
 			} catch (error) {
-				ctx.logger?.warn?.(`${name}: route unregister failed: ${redactSecrets(errMsg(error))}`);
+				ctx.logger?.warn?.(`${name}: route unregister failed: ${redactSecrets$1(errMsg(error))}`);
 			}
 		};
 	}, `${name}: routes`);