dsh-connect-modelscope-token-plan 0.6.5 → 0.7.0

package/lib/index.js

@@ -1540,8 +1540,8 @@ function createCoalescedFetch(options = {}) {
 * 最大值：个别网关把窗口抄大（如 openrouter 抄 1M）不代表魔搭侧真开那么宽。
 *
 * 维护纪律：
-* 1. 只收**当前魔搭目录里真实存在**的 id（2026-10-16 实拉 `/v1/models` 全集
-*    37 个中筛出 19 个）；目录下架的条目应随手删除，表不是历史档案。
+* 1. 只收**当前魔搭目录里真实存在**的 id（2026-10-23 实拉 `/v1/models` 全集
+*    37 个中筛出 21 个）；目录下架的条目应随手删除，表不是历史档案。
 * 2. 每条注明来源 host 与核对日期；有多个数据源时写主流值并留离群说明。
 * 3. 覆盖优先级由 `curatedWindowOf` 的调用方（inference-client 打标）保证：
 *    目录声明过窗口的条目不进打标，策展表永不推翻平台声明。
@@ -1555,14 +1555,14 @@ function createCoalescedFetch(options = {}) {
 * 而使用者无从判断一个值是三个月前还是三年前核的。快照侧据此在表过期时给一条
 * shapeWarning（见 {@link curatedCatalogStale}）。
 */
-const CURATED_AS_OF = "2026-10-16";
+const CURATED_AS_OF = "2026-10-23";
 /**
 * 策展表距上次核对已经过去多少天；日期解析不了返回 `null`。
 * @param {Date} [now] - 时钟源（测试注入）。
 * @returns {number|null} 天数（向下取整），或 null。
 */
 function curatedCatalogAgeDays(now = /* @__PURE__ */ new Date()) {
-	const asOf = Date.parse("2026-10-16T00:00:00Z");
+	const asOf = Date.parse("2026-10-23T00:00:00Z");
 	if (Number.isNaN(asOf)) return null;
 	const delta = now.getTime() - asOf;
 	return delta < 0 ? 0 : Math.floor(delta / 864e5);
@@ -1586,6 +1586,7 @@ const CURATED_CONTEXT_WINDOWS = {
 	"deepseek-ai/DeepSeek-V4-Pro": 1048576,
 	"deepseek-ai/DeepSeek-V4-Pro-0813": 1048576,
 	"deepseek-ai/DeepSeek-V4.1-Flash": 1048576,
+	"deepseek-ai/DeepSeek-V4.1-Flash-1017": 1048576,
 	"meituan-longcat/LongCat-Flash-Lite": 256e3,
 	"MiniMax/MiniMax-M1-80k": 1e6,
 	"MiniMax/MiniMax-M3": 1048576,
@@ -1599,6 +1600,7 @@ const CURATED_CONTEXT_WINDOWS = {
 	"Qwen/Qwen3.8-Flash-Next": 262144,
 	"stepfun-ai/Step-3.5-Flash": 262144,
 	"stepfun-ai/Step-3.7-Flash": 262144,
+	"stepfun-ai/Step-5-Preview": 1e6,
 	"ZhipuAI/GLM-4.7-Flash": 2e5,
 	"ZhipuAI/GLM-5.2": 1e6
 };
@@ -2026,7 +2028,7 @@ function createInferenceClient({ settings, tokenStore, deps = {}, logger }) {
 * 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$2 = {
+const EMPTY_PAYLOAD$3 = {
 	enabled: null,
 	enabledIds: null,
 	contextWindow: null,
@@ -2255,7 +2257,7 @@ function createFileProviderStore(options = {}) {
 	* `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$2;
+	const readPayload = async () => await read() ?? EMPTY_PAYLOAD$3;
 	/**
 	* Read one payload, then hand it to {@link writePayload} — the read-modify-
 	* write that keeps the switch and the list from clobbering each other.
@@ -2479,7 +2481,7 @@ function createFileProviderStore(options = {}) {
 const DRAW_STORE_VERSION = 1;
 /** 本 build 读得懂的版本集合（升级时把新号加进来，旧号保持可读）。 */
 const KNOWN_DRAW_VERSIONS = Object.freeze([1]);
-const EMPTY_PAYLOAD$1 = {
+const EMPTY_PAYLOAD$2 = {
 	enabled: null,
 	modelId: null,
 	version: null
@@ -2578,7 +2580,7 @@ function createFileDrawStore(options = {}) {
 	* 读当前 payload。
 	* @returns {Promise<DrawPayload>}
 	*/
-	const readPayload = async () => await cache.read() ?? EMPTY_PAYLOAD$1;
+	const readPayload = async () => await cache.read() ?? EMPTY_PAYLOAD$2;
 	/**
 	* 读-改-写一份补丁，**整段排队**。
 	*
@@ -2836,7 +2838,7 @@ function switchSource(panel) {
 const USAGE_PREFS_VERSION = 1;
 /** 本 build 读得懂的版本集合（升级时把新号加进来，旧号保持可读）。 */
 const KNOWN_USAGE_PREFS_VERSIONS = Object.freeze([1]);
-const EMPTY_PAYLOAD = {
+const EMPTY_PAYLOAD$1 = {
 	windowDays: null,
 	version: null
 };
@@ -2955,7 +2957,7 @@ function createFileUsagePrefsStore(options = {}) {
 	* 读当前 payload。
 	* @returns {Promise<UsagePrefsPayload>}
 	*/
-	const readPayload = async () => await cache.read() ?? EMPTY_PAYLOAD;
+	const readPayload = async () => await cache.read() ?? EMPTY_PAYLOAD$1;
 	/**
 	* 读-改-写，**整段排队**。
 	*
@@ -3014,6 +3016,258 @@ function createFileUsagePrefsStore(options = {}) {
 	};
 }
 
+//#endregion
+//#region src/host/roster-seen-store.ts
+/**
+* 「本机第一次见到这个模型是什么时候」——胶囊那句「· N 新模型」的唯一事实源。
+*
+* ## 它回答什么，不回答什么
+*
+* 只记**首见时间戳**：每个 id 第一次出现在本机拉到的目录里的那一刻。由此派生的
+* 那句话必须说成「本机首次见到的模型」，**不能**说成「网关新增」——上游的
+* `/v1/models` 不提供「上架时间」，本插件没有任何字段能证实某个模型是这周才上
+* 的。能证实的只有「本机从哪天开始看见它」，那就只说这一句。
+*
+* 也**不**记录活动/促销变化（限免、错峰、签到）：那些是实时读数，面板的余额块与
+* 胶囊 popover 已经直接画上游给的现值，再造一本「促销 diff 账」就是同一事实两本
+* 账，两本迟早说两套话（ADR-017 的口径）。
+*
+* ## 一次调用同时 diff 与落盘
+*
+* {@link RosterSeenStore.note} 不能拆成「先 diff 缓存、稍后再写」：那样两个并发
+* 的收敛轮可能都基于同一份旧 map 判断，后写的那次会把先写的那批模型再宣布一遍。
+* 读、算、写在一个调用里完成。
+*
+* ## 首次写入是**播种**，不是宣布
+*
+* 升级到带本文件的构建时，磁盘上没有历史——此时**知道**目录里有这些模型，但
+* **不知道**其中哪些是新的。把整个目录宣布成「刚上架」正是本文件要避免的谎，
+* 所以播种那一轮把每个 id 都盖成「已过期」的戳（`now - 窗口`），`newIds` 返回
+* 空。这个自愈是刻意的：某个 id 要先离开目录再回来，才配得到一个真实的首见戳。
+*
+* ## 200 个 id 以上是**形状漂移**，不是「保留最新 200」
+*
+* 按「保留最新」淘汰一个仍在目录里的 id，会让它下一轮看起来像没见过 → 重新盖戳
+* → 再被宣布一次；而被淘汰的集合每轮轮换，于是「新模型」计数会**震荡并变大**
+* （实测 250 个 id 对 200 上限：50 → 100 → …）。会自己发明新模型的历史文件比
+* 没有历史文件更糟，所以超限一律读作形状漂移：**不写、不宣布**，旧 map 原样
+* 保留，标记在异常期间消失，目录回到合理规模后自愈。
+*
+* ## 分段与 legacy
+*
+* 落点与 provider / draw / usage-prefs 同一套分段规则：
+* `$DSH_HOME/state/<profile>/<plugin>/roster-seen.json`（无 profile 时落共享目录）。
+* **不搬**：本文件晚于 profile 分段引入，共享目录里不存在它的旧布局可继承——
+* 与 usage-prefs-store 的「legacy 继承」相反，这里没有 legacy 缝，也不该长出一条。
+*
+* 完整性三件套与其余 store 同源（全部上收在 `state-store.ts`，本文件只做调用方，
+* 论述见 `draw-store.ts` 头注）：写串行化（{@link createStateWriteQueue}）、写守卫
+* （{@link guardStateWrite}，ADR-006）、读侧说明（{@link stateVersionNote}）。
+*
+* doctor 覆盖：{@link describeRosterSeenPayload} 给只读速览，`doctor.ts` 据此把
+* roster-seen.json 的「损坏 / 未知版本」报进症状表。
+*
+* @module dsh-connect-modelscope-token-plan/roster-seen-store
+*/
+/** 本 store 落盘 payload 的版本。 */
+const ROSTER_SEEN_VERSION = 1;
+/** 本 build 读得懂的版本集合（升级时把新号加进来，旧号保持可读）。 */
+const KNOWN_ROSTER_SEEN_VERSIONS = Object.freeze([1]);
+/**
+* 「新」的时效窗口：首见戳落在这个窗口内就算新。
+*
+* 7 天是有意的尺度——它要盖住「用户几天没开面板、回来时发现多了两个模型」这个
+* 真实场景，又不能长到让一次批量上架在半个月后还挂着标记。窗口在这里是**常量**
+* 而不是配置：一个能被调成 365 天的「新模型」标记等于没有语义。
+*/
+const ROSTER_SEEN_NEW_WINDOW_MS = 6048e5;
+/**
+* 目录规模上限。超过即视为形状漂移（不是淘汰队列，理由见模块头注）。
+*
+* 取值与姊妹插件的同类实现一致：真实目录在数百个模型以内，200 给「这一侧目录
+* 突然返回了整站列表」这类事故留出足够间距。
+*/
+const ROSTER_SEEN_MAX_IDS = 200;
+const EMPTY_PAYLOAD = {
+	seen: {},
+	version: null
+};
+/**
+* 本 build 读不读得懂这个版本。
+*
+* 与其余 store 的 `isKnown*Version` 同形：**白名单**判据，不与
+* {@link ROSTER_SEEN_VERSION} 比较——升级后旧号仍要可读。读侧、报告侧问的都是
+* 这一个函数。
+* @param {unknown} version - 盘上读到的值（可能根本不是数字）。
+* @returns {boolean}
+*/
+function isKnownRosterSeenVersion(version) {
+	return typeof version === "number" && KNOWN_ROSTER_SEEN_VERSIONS.includes(version);
+}
+/**
+* 归一一张首见表：只留「id 是非空字符串、戳是有限正数」的项。
+*
+* 丢掉而不是修补坏项是有意的：一个戳为 0 或负数的项会让 `now - stamp` 变成
+* 几十年，那个 id 于是永远算「新」；宁可让它下次出现时重新盖一个真实戳。
+* @param {unknown} raw - 盘上读到的 `seen` 值。
+* @returns {RosterSeen} 归一后的表（可能是空对象）。
+*/
+function normalizeRosterSeen(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {};
+	const out = {};
+	for (const [id, stamp] of Object.entries(raw)) {
+		if (id === "") continue;
+		if (typeof stamp !== "number" || !Number.isFinite(stamp) || stamp <= 0) continue;
+		out[id] = stamp;
+	}
+	return out;
+}
+/** 本 store 的目录（与 provider / draw / usage-prefs 同一套分段规则）。 */
+function rosterSeenDir(profile, dir) {
+	if (typeof dir === "string" && dir !== "") return dir;
+	return profile ? profileStateDir(name, profile) : stateDir(name);
+}
+/**
+* 从一张首见表里挑出「还算新」的 id，按首见时间升序（最老的在前）。
+*
+* 升序是有意的：调用方只展示前几个名字（胶囊 tooltip / popover 的预算），先看到
+* 的应该是**最早**变成新的那几个——它们离过期最近，也是读者最可能已经见过、
+* 需要被告知「其实才刚出现」的那批。
+* @param {RosterSeen} seen - 归一后的首见表。
+* @param {number} nowMs - 当前时刻。
+* @returns {string[]} 窗口内的 id 列表。
+*/
+function freshIdsOf(seen, nowMs) {
+	return Object.entries(seen).filter(([, first]) => nowMs - first < ROSTER_SEEN_NEW_WINDOW_MS).sort((left, right) => left[1] - right[1]).map(([id]) => id);
+}
+/**
+* 文件支撑的首见表。
+* @param {StoreOptions} [options] - `{ dir, profile, ttlMs, logger }`。
+* @returns {object} store 句柄。
+*/
+function createFileRosterSeenStore(options = {}) {
+	const { dir, profile = null, ttlMs = STATE_READ_TTL_MS, logger } = options;
+	const stateDir = rosterSeenDir(profile, dir);
+	const filePath = join(stateDir, "roster-seen.json");
+	/**
+	* 写一份 payload 并落盘。
+	*
+	* ADR-006 写守卫（{@link guardStateWrite}）先问盘：版本不认或文件读不出 →
+	* 返回拒绝理由（已 degrade 记录），不落笔。
+	* @param {object} body - 要持久化的 JSON 体。
+	* @returns {Promise<string|null>} 拒绝原因，或 `null` = 已写入。
+	*/
+	const writePayload = async (body) => {
+		const refusal = await guardStateWrite(filePath, KNOWN_ROSTER_SEEN_VERSIONS, {
+			label: "roster-seen-state",
+			logger
+		});
+		if (refusal !== null) return refusal;
+		await ensureStateDir(stateDir);
+		await writeStateFile(filePath, JSON.stringify(body, null, 2), { temporary: temporaryOf(stateDir, "roster-seen.json") });
+		return null;
+	};
+	/** 写串行化：读-改-写必须排队（详见{@link createStateWriteQueue}）。 */
+	const writeQueue = createStateWriteQueue();
+	/**
+	* 解析一份路径上的 payload；认不出的版本读作「空表」但**记住**版本号——读侧
+	* 宽容、versionNote 负责把宽容说出口（写侧守卫已挡住覆盖，两半合起来才是
+	* ADR-006）。
+	*/
+	const parseAt = async (path) => {
+		const source = obj(await readStateJson(path));
+		const version = typeof source.version === "number" ? source.version : null;
+		if (!isKnownRosterSeenVersion(version)) return {
+			seen: {},
+			version
+		};
+		return {
+			seen: normalizeRosterSeen(source.seen),
+			version
+		};
+	};
+	const cache = createStateReadCache(() => parseAt(filePath), { ttlMs });
+	/** 读当前 payload。 */
+	const readPayload = async () => await cache.read() ?? EMPTY_PAYLOAD;
+	return {
+		/**
+		* 记下这一轮的完整目录，并回答「其中哪些还在新窗口内」。
+		*
+		* 一次调用同时 diff 与落盘（理由见模块头注）。首轮写入是**播种**：把每个 id
+		* 盖成已过期的戳、返回空 `newIds`。
+		* @param {readonly string[]} ids - 上游这一轮列出的**完整**目录 id。
+		* @param {number} [nowMs] - 时钟（测试注入）。
+		* @returns {Promise<{newIds: string[]}>} 窗口内的 id，升序；播种那轮为空。
+		*/
+		async note(ids, nowMs = Date.now()) {
+			const list = Array.isArray(ids) ? ids.filter((id) => typeof id === "string" && id !== "") : [];
+			const unique = [...new Set(list)];
+			if (unique.length === 0) return { newIds: [] };
+			const now = Number.isFinite(nowMs) ? nowMs : Date.now();
+			return writeQueue.enqueue(async () => {
+				const current = await parseAt(filePath);
+				if (current.version !== null && !isKnownRosterSeenVersion(current.version)) return { newIds: [] };
+				const previous = current.seen;
+				const seeded = current.version === null;
+				const next = {};
+				for (const id of unique) {
+					const first = previous[id];
+					next[id] = typeof first === "number" && first > 0 ? Math.min(first, now) : seeded ? now - ROSTER_SEEN_NEW_WINDOW_MS : now;
+				}
+				if (Object.keys(next).length > 200) return { newIds: [] };
+				if (seeded || Object.keys(previous).length !== Object.keys(next).length || Object.keys(next).some((id) => previous[id] !== next[id])) {
+					const refusal = await writePayload({
+						version: 1,
+						seen: next,
+						updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+					});
+					if (refusal !== null) throw new Error(refusal);
+					cache.remember({
+						seen: next,
+						version: 1
+					});
+				}
+				return { newIds: seeded ? [] : freshIdsOf(next, now) };
+			});
+		},
+		/**
+		* 只读：此刻还算「新」的 id（升序）。
+		*
+		* **不写盘**：快照与 provider 路由都是读路径，写只发生在收敛器的 `note`。
+		* 读路径若顺手补戳，一次面板轮询就能把「谁是新模型」这件事改写掉。
+		* @param {number} [nowMs] - 时钟（测试注入）。
+		* @returns {Promise<string[]>}
+		*/
+		async fresh(nowMs = Date.now()) {
+			return freshIdsOf((await readPayload()).seen, Number.isFinite(nowMs) ? nowMs : Date.now());
+		},
+		/** 这张表有没有写过（区分「播种」与「真的没有新模型」）。 */
+		async isSet() {
+			return (await readPayload()).version !== null;
+		},
+		/**
+		* 盘上带着本构建读不懂的版本时的一句说明，否则 `null`。
+		*
+		* 读侧宽容（未知版本读作空表）的另一半：快照聚合把它转进 `shapeWarnings`，
+		* doctor 报同一份文件。没有它，「首见表被忽略」在面板上就是「没有新模型」。
+		* @returns {Promise<string|null>}
+		*/
+		async versionNote() {
+			const version = (await readPayload()).version;
+			if (version === null || isKnownRosterSeenVersion(version)) return null;
+			return stateVersionNote({
+				label: "roster-seen-state",
+				file: filePath,
+				version,
+				known: KNOWN_ROSTER_SEEN_VERSIONS,
+				consequence: "the first-sighting history is being answered as empty, so the pill shows no new-model marker."
+			});
+		},
+		/** 落盘路径（诊断与测试用）。 */
+		filePath
+	};
+}
+
 //#endregion
 //#region src/host/draw.ts
 /**
@@ -3948,11 +4202,10 @@ function sleep(ms, signal) {
 /** 当前缺席原因（`null` = 未登记 / 已清掉）。 */
 let note = null;
 /**
-* 本次挂载是否真的把工具注册上了。
+* 此刻工具是否真的在 registry 里。
 *
-* 与 `note` 的区别见文件头：`note` 是「注册尝试过且失败的原因」，这一位是「注册
-* 成功与否」。开关在挂载后才翻开的场景，两者都是「没有缺席原因 + 没注册上」，
-* 只有这一位能把它认出来。
+* 与 `note` 的区别见文件头：`note` 是「为什么没成」，这一位是「此刻在不在」。
+* 开关翻转会当场重算这一位，所以它是动态读数，不是「本次挂载」的存档。
 */
 let mounted = false;
 /**
@@ -3998,22 +4251,33 @@ function resetDrawToolNote() {
 //#endregion
 //#region src/host/draw-register.ts
 /**
-* 出图工具的挂载副作用：读开关 → 解析目录 → 注册 agent 工具。
+* 出图工具的挂载副作用：读开关 → 解析目录 → 注册 agent 工具；开关翻转时**现挂现卸**。
 *
 * 与 `provider-publish.ts` 的分工：那个管「魔搭作为 chat provider 的注册」，本文件
 * 管「给 agent 一个出图工具」。两者是**独立的开关**——回答的是不同问题，合并没有
 * 好处（用户可能想用工具出图但不想把魔搭塞进模型选择器，反之亦然）。
 *
-* 承重约束：**peer 的 tools registry 没有 unregister**。所以
-*  - 注册只在挂载时尝试**一次**，不在任何轮询/路由里重复调用；
-*  - 开关在挂载后翻转，要到下次 Host 启动才生效（面板文案必须说这句，否则用户
-*    会以为开关坏了）；
+* 承重契约：peer 的 tools.register 返回 disposer（`() => void` 注销句柄，见
+* `@deepseek-ai/dsh-tools` 的 `ToolsService.register`）。所以
+*  - 开关翻转可以在**本次 Host 生命周期内**生效：`sync()` 读一次开关，要开就注册、
+*    要关就调 disposer 摘掉，不需要等下次启动；
+*  - 句柄必须**存住**：丢掉它 = 插件卸载后注册残留（僵尸工具），而 registry 对重名
+*    insert 会抛错，下一次挂载直接失败（错误文本形如 `tool "<name>" is already
+*    registered`）。旧版把返回的 `unknown` 直接丢弃，正是这条缺口的来源；
 *  - 目录变化**不需要**重注册：工具在**调用时**才读目录（`getEntries` 是个函数），
 *    所以一次目录刷新会自然被下一次出图看到。
 *
-* 失败一律降级为「工具缺席」，绝不炸掉插件：tools 服务缺失、peer 加载失败、
-* registry 拒收——三种都由 `draw-tool-state.ts` 记下原因供面板显示。本文件不吞
-* 错误（那会让「工具为什么不在」无从诊断），只把它们翻译成可展示的原因码。
+* 并发：`sync()` 串行排队（`chain`），每次执行时**现读**开关，所以快速连点开关
+* 最终收敛到最后一次保存的值；重复 sync 幂等（已注册就跳过——真去重复注册会撞
+* registry 的重名保护，把它当正常分支会把「开关开着」误报成缺席）。
+*
+* 失败一律降级为「工具缺席」，绝不炸掉插件：tools 服务缺失、peer 加载失败、registry
+* 拒收——三种都由 `draw-tool-state.ts` 记下原因供面板显示。另有一种**非缺席**的
+* 降级：registry 收下了却**没返回 disposer**（旧 Host / 旧 peer）。工具能用但关不
+* 掉，记 `not-removable` 让面板说实话——否则用户关掉开关、面板显示「已关闭」而
+* 工具还在。
+*
+* 本文件不吞错误（那会让「工具为什么不在」无从诊断），只把它们翻译成可展示的原因码。
 *
 * peer-dependent：`@deepseek-ai/dsh-tools` 由 `deps.loadToolsModule` 惰性注入。
 *
@@ -4031,9 +4295,8 @@ function resetDrawToolNote() {
 /**
 * 解析一个可选服务，允许它稍后才注册。
 *
-* 承 sensenova 同名函数的纪律：**重试的是读，不是注册**——工具不能注销，重复注册
-* 比缺席更糟。这里只做有限次立即读取，不做长退避（服务要么已注册，要么这次挂载
-* 就没有）。
+* 承 sensenova 同名函数的纪律：**重试的是读，不是写**。这里只做有限次立即读取，
+* 不做长退避（服务要么已注册，要么这次就没有）。
 * @param {object} ctx - Host 上下文。
 * @param {string} service - 服务名。
 * @param {() => boolean} isDisposed - 卸载闸。
@@ -4049,67 +4312,142 @@ async function resolveService(ctx, service, isDisposed) {
 	return null;
 }
 /**
-* 读一次开关，决定是否注册出图工具。
+* 建一个出图工具挂载控制器（不产生副作用，`sync()` 才读开关/注册）。
 * @param {object} ctx - Host 上下文。
-* @param {object} wiring - `{ settings, configError, tokenStore, inference, providerStore, publisher, logger }`。
+* @param {object} wiring - `{ settings, configError, tokenStore, inference, drawStore, publisher, logger }`。
 * @param {object} deps - 测试缝（`loadToolsModule`、`drawFetch`、`pollIntervalMs`）。
-* @returns {Promise<void>}
+* @returns {DrawToolMount} 控制器。
 */
-async function registerDrawTool(ctx, wiring, deps = {}) {
+function createDrawToolMount(ctx, wiring, deps = {}) {
 	const { settings, configError, tokenStore, inference, drawStore, publisher, logger } = wiring;
 	const loggerFor = logger ?? ctx.logger;
-	setDrawToolNote(null);
-	setDrawToolMounted(false);
-	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;
+	/** 当前已注册工具的注销句柄；`null` = 没挂上（或已摘掉）。 */
+	let disposeTool = null;
+	/** peer 的 `defineTool` 只解析一次：成功后就缓存，失败留到下次 sync 重试。 */
+	let defineTool = null;
+	/** 卸载闸：`dispose()` 之后任何在途/后续 sync 都不再注册。 */
+	let closed = false;
+	/** 串行链：保证「读开关 → 挂/卸」不会被两次 sync 交错执行。 */
+	let chain = Promise.resolve();
+	const isDisposed = () => closed || publisher?.isDisposed?.() === true;
+	/**
+	* 摘掉已注册的工具（幂等）。
+	*
+	* 先清注册位再调 disposer：即使 disposer 抛了，面板也不该继续显示「已注册」。
+	* @returns {void}
+	*/
+	function unmount() {
+		const dispose = disposeTool;
+		disposeTool = null;
+		setDrawToolMounted(false);
+		if (dispose !== null) try {
+			dispose();
+		} catch (error) {
+			loggerFor?.warn?.(`${name}: draw tool dispose failed (${redactSecrets(errMsg(error))})`);
 		}
-		let defineTool = null;
+		setDrawToolNote(null);
+	}
+	/**
+	* 解析 peer 的 `defineTool`（成功后缓存）。
+	* @returns {Promise<Function|null>} `defineTool` 或 `null`（失败已记原因）。
+	*/
+	async function loadDefineTool() {
+		if (defineTool !== null) return defineTool;
 		try {
 			const mod = await Promise.resolve(deps.loadToolsModule ? deps.loadToolsModule() : import("@deepseek-ai/dsh-tools"));
-			defineTool = mod?.defineTool ?? mod?.default?.defineTool ?? null;
+			const found = mod?.defineTool ?? mod?.default?.defineTool ?? null;
+			if (typeof found === "function") {
+				defineTool = found;
+				return found;
+			}
 		} catch (error) {
-			setDrawToolNote("peer-load-failed");
 			loggerFor?.warn?.(`${name}: draw tool peer module failed to load (${redactSecrets(errMsg(error))}) — the tool is absent`);
-			return;
 		}
-		if (typeof defineTool !== "function") {
-			setDrawToolNote("peer-load-failed");
-			return;
+		return null;
+	}
+	/**
+	* 一次收敛：读开关，要开就注册、要关就注销。
+	* @returns {Promise<void>}
+	*/
+	async function apply() {
+		if (closed) return;
+		try {
+			if (configError !== null) return;
+			const panelValue = drawStore ? await drawStore.enabled().catch(() => null) : null;
+			if (resolveSwitchEnabled(panelValue, settings.drawEnabled === true) !== true) {
+				unmount();
+				return;
+			}
+			if (disposeTool !== null) {
+				setDrawToolNote(null);
+				setDrawToolMounted(true);
+				return;
+			}
+			const tools = await resolveService(ctx, "tools", isDisposed);
+			if (tools === null || typeof tools.register !== "function") {
+				setDrawToolNote("no-tools-service");
+				setDrawToolMounted(false);
+				return;
+			}
+			const found = await loadDefineTool();
+			if (found === null) {
+				setDrawToolNote("peer-load-failed");
+				setDrawToolMounted(false);
+				return;
+			}
+			const drawFetch = deps.drawFetch ?? ((url, options) => fetch(url, options));
+			const dispose = tools.register(defineDrawTool({
+				defineTool: found,
+				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,
+					drawWaitMs: settings.drawWaitMs
+				},
+				...wiring.drawJobs !== void 0 ? { jobs: wiring.drawJobs } : {},
+				...deps.pollIntervalMs !== void 0 ? { pollIntervalMs: deps.pollIntervalMs } : {},
+				isDisposed
+			}));
+			if (typeof dispose === "function") {
+				disposeTool = dispose;
+				setDrawToolNote(null);
+				setDrawToolMounted(true);
+			} else {
+				disposeTool = null;
+				setDrawToolNote("not-removable");
+				setDrawToolMounted(true);
+				loggerFor?.warn?.(`${name}: draw tool registered without a disposer — turning the switch off cannot unmount it on this host`);
+			}
+		} catch (error) {
+			setDrawToolNote("registry-refused");
+			setDrawToolMounted(false);
+			loggerFor?.warn?.(`${name}: draw tool registration refused (${redactSecrets(errMsg(error))}) — the tool is absent`);
 		}
-		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,
-				drawWaitMs: settings.drawWaitMs
-			},
-			...wiring.drawJobs !== void 0 ? { jobs: wiring.drawJobs } : {},
-			...deps.pollIntervalMs !== void 0 ? { pollIntervalMs: deps.pollIntervalMs } : {},
-			isDisposed
-		}));
-		setDrawToolMounted(true);
-	} catch (error) {
-		setDrawToolNote("registry-refused");
-		loggerFor?.warn?.(`${name}: draw tool registration refused (${redactSecrets(errMsg(error))}) — the tool is absent`);
 	}
+	return {
+		sync() {
+			chain = chain.then(apply).catch((error) => {
+				loggerFor?.warn?.(`${name}: draw tool sync failed (${redactSecrets(errMsg(error))})`);
+			});
+			return chain;
+		},
+		dispose() {
+			closed = true;
+			unmount();
+		},
+		mounted() {
+			return drawToolMounted();
+		}
+	};
 }
 
 //#endregion
@@ -4920,7 +5258,7 @@ function syncSignaturesAfterPublish(state) {
 * @returns {{reconcile: () => Promise<void>; health: () => {{ lastError: unknown }} }}
 */
 function createProviderReconciler(deps) {
-	const { settings, providerStore, inference, publisher, usageEvents, logger } = deps;
+	const { settings, providerStore, inference, publisher, usageEvents, logger, rosterSeenStore } = deps;
 	/**
 	* 把一次 store 读取收成「值或 null」——**同步抛与异步拒收都降级**。
 	*
@@ -5003,6 +5341,11 @@ function createProviderReconciler(deps) {
 			return;
 		}
 		const entries = Array.isArray(catalog?.entries) ? catalog.entries : [];
+		if (rosterSeenStore !== void 0) try {
+			await rosterSeenStore.note(entries.map((entry) => String(entry?.id ?? "")));
+		} catch (error) {
+			logger?.warn?.(`${name}: roster first-sighting write failed (${redactSecrets(errMsg(error))}) — the new-model marker may miss this pass`);
+		}
 		const enabledIds = resolveEnabledIds(after.enabledIds, publisher.state.enabledIds);
 		const unavailable = await readUnavailable();
 		try {
@@ -5116,7 +5459,7 @@ async function soft(promise) {
 }
 /** 聚合快照 body。wiring 子集见 routes/snapshot.ts 的 Pick。 */
 async function buildSnapshotBody(wiring) {
-	const { settings, tokenStore, usageStore, inference, providerStore, drawStore, usagePrefsStore, publisher } = wiring;
+	const { settings, tokenStore, usageStore, inference, providerStore, drawStore, usagePrefsStore, rosterSeenStore, publisher } = wiring;
 	const panelWindow = await usagePrefsStore.windowDays().catch(() => null);
 	const windowDays = resolveWindowDays(panelWindow, settings.trendDays, settings.retentionDays);
 	const [tokenState, daily, perModel, trend, events, providerNote] = await Promise.all([
@@ -5149,6 +5492,8 @@ async function buildSnapshotBody(wiring) {
 	if (drawNote.ok && drawNote.value !== null) shapeWarnings.push(drawNote.value);
 	const windowNote = await soft((async () => usagePrefsStore.versionNote())());
 	if (windowNote.ok && windowNote.value !== null) shapeWarnings.push(windowNote.value);
+	const rosterNote = await soft((async () => rosterSeenStore.versionNote())());
+	if (rosterNote.ok && rosterNote.value !== null) shapeWarnings.push(rosterNote.value);
 	if (curatedCatalogStale()) {
 		const age = curatedCatalogAgeDays();
 		shapeWarnings.push(`context-catalog: curated windows were last verified on ${CURATED_AS_OF}` + (age === null ? "" : ` (${age} days ago)`) + " — re-check them against the current catalogue");
@@ -5164,6 +5509,7 @@ async function buildSnapshotBody(wiring) {
 		const enabledCount = enabledCountOf(allowedList, roster.map((row) => row.id));
 		const contextWindow = await providerStore.contextWindow().catch(() => null);
 		const catalogNote = models.ok ? null : `模型目录读不到：${models.error}`;
+		const newModelIds = await rosterSeenStore.fresh().catch(() => []);
 		return {
 			enabled,
 			source,
@@ -5175,6 +5521,7 @@ async function buildSnapshotBody(wiring) {
 			allowed: allowedList.mode,
 			enabledIds,
 			contextWindow,
+			newModelIds,
 			roster
 		};
 	})());
@@ -5410,7 +5757,8 @@ function withOrigin(handler, allowedHosts) {
 */
 /**
 * 注册快照路由。wiring 子集：settings / configError / tokenStore /
-* usageStore / inference / providerStore / publisher / logger。
+* usageStore / inference / providerStore / drawStore / usagePrefsStore /
+* rosterSeenStore / publisher / logger。
 * @returns {Function} off() 注销回调。
 */
 function registerSnapshotRoute(ctx, wiring) {
@@ -5699,7 +6047,7 @@ async function readEnabledIds(store, published) {
 * @returns {Function} 依次调用三个 `off()` 的注销回调。
 */
 function registerProviderRoute(ctx, wiring) {
-	const { settings, providerStore, publisher, reconcile, inference, logger } = wiring;
+	const { settings, providerStore, publisher, reconcile, inference, rosterSeenStore, logger } = wiring;
 	/**
 	* 组装一份 §9 响应形状。GET 与成功后的 POST 共用，所以两个方向不可能对「当前
 	* 状态是什么」说两套话。
@@ -5727,6 +6075,7 @@ function registerProviderRoute(ctx, wiring) {
 		const roster = rosterWithAvailability(entries, publisher.state.unavailableIds ?? [], settings.maxTokensOverrides);
 		const allowedList = parseAllowedList(enabledIds);
 		const modelCount = roster.length;
+		const newModelIds = rosterSeenStore === void 0 ? [] : await optional(rosterSeenStore.fresh(), []);
 		return {
 			ok: true,
 			enabled: resolveSwitchEnabled(panelSwitch, settings.registerProvider),
@@ -5739,6 +6088,7 @@ function registerProviderRoute(ctx, wiring) {
 			allowed: allowedList.mode,
 			enabledIds,
 			contextWindow,
+			newModelIds,
 			roster,
 			...catalogError !== null ? { catalogError } : {},
 			...extra
@@ -5882,12 +6232,11 @@ function registerProviderRoute(ctx, wiring) {
 * 「给 agent 一个出图工具」。两者的开关、状态文件、候选集合都不同，合并会让
 * 「关掉出图」波及 provider 的注册时序（详见 draw-store.ts 的头注）。
 *
-* 一处**与 provider 路由不同**的地方必须说清：provider 开关翻转会**立即**重注册
-* （publish 是活的重建），而出图工具的开关翻转**要等下次 Host 启动**——peer 的
-* tools registry 没有 unregister，工具一旦注册就摘不下来（完整论述见
-* draw-register.ts 文件头注）。所以本路由保存成功后
-* 不改挂载状态，只在响应里给出 `mountPending`，让面板能说清这件事，而不是让用户
-* 以为开关坏了。
+* 开关翻转**当场生效**：保存成功后本路由 await 挂载控制器的 `syncDraw()`（注册
+* 或注销），再把**收敛之后**的真实状态写进响应。所以面板拿到的不是「已保存、等
+* 重启」，而是「已挂上」或「挂载失败的原因」。`syncDraw` 由装配层注入（`index.ts`
+* 把同一个控制器交给路由与挂载），本路由不自己建——否则「注册」与「注销」会各持
+* 一份状态。
 *
 * peer-free：不 import 任何 Host peer。
 * @module dsh-connect-modelscope-token-plan/routes/draw
@@ -5926,7 +6275,7 @@ async function readEntries(inference) {
 * @returns {Function} 注销回调。
 */
 function registerDrawRoute(ctx, wiring) {
-	const { settings, drawStore, inference, logger } = wiring;
+	const { settings, drawStore, inference, syncDraw, logger } = wiring;
 	/**
 	* 组装响应。GET 与写成功后的响应共用，两个方向不可能对「当前状态」说两套话。
 	* @param {object} [extra] - 追加/覆盖字段。
@@ -5952,15 +6301,15 @@ function registerDrawRoute(ctx, wiring) {
 			effectiveSource: choice.source,
 			absentReason: drawToolNote(),
 			/**
-			* 开关的保存**不会**改变本次挂载的工具。
+			* 开关为开、但工具此刻还没挂上（正在收敛，或收敛失败）。
 			*
-			* 工具无法注销（peer 的 tools registry 没有 unregister），所以开关翻转只在
-			* 下次 Host 启动时生效。面板据此显示一句说明——否则用户会以为开关坏了。
-			* 判据：开关为开且**本次挂载没注册上**。
+			* 现在开关翻转是**当场**收敛的（见上面的 `syncDraw`），所以正常保存后这一位
+			* 就是 false。它仍然有用：GET 与进程刚启动、还没跑到第一次 sync 时仍可能为
+			* true，面板靠它区分「暂时没挂」与「挂上了」。
 			*
-			* 注意判据不是「有缺席原因」：缺席原因非 null 表示注册尝试过且失败，而挂载
-			* 那一刻开关是关的（用户之后才翻开）时 absentReason 为 null、却同样没注册
-			* 上——后者才是最需要这句提示的场景。见 `draw-tool-state.ts` 文件头。
+			* 注意判据不是「有缺席原因」：缺席原因非 null 表示收敛已尝试且失败（面板会
+			* 优先显示那个原因），而「还没跑完」时 absentReason 为 null。见
+			* `draw-tool-state.ts` 文件头。
 			*/
 			mountPending: resolveSwitchEnabled(panelSwitch, settings.drawEnabled) === true && drawToolMounted() !== true,
 			preferredInCatalog: preferredModelId === null ? null : catalog.ok ? candidates.some((row) => row.id === preferredModelId) : null,
@@ -6010,6 +6359,7 @@ function registerDrawRoute(ctx, wiring) {
 			try {
 				if (hasEnabled) await drawStore.saveEnabled(body.enabled);
 				if (body.modelId !== void 0) await drawStore.saveModelId(body.modelId);
+				if (hasEnabled) await syncDraw?.();
 			} catch (error) {
 				respondError(response, error);
 				return;
@@ -6031,6 +6381,7 @@ function registerDrawRoute(ctx, wiring) {
 			}));
 			try {
 				await drawStore.reset();
+				await syncDraw?.();
 			} catch (error) {
 				respondError(response, error);
 				return;
@@ -6213,7 +6564,7 @@ function registerRoutes(ctx, wiring) {
 *
 *   **出图工具**
 *   - `draw.ts`               协议纯逻辑半边（peer-free）
-*   - `draw-register.ts`      工具注册（挂载时一次性，不可撤销）
+*   - `draw-register.ts`      工具挂载控制器（开关翻转现挂现卸）
 *   - `draw-runtime.ts`       运行时（两段式：提交 → 轮询）
 *   - `draw-jobs.ts`          作业表（本次挂载内有效）
 *   - `draw-tool-state.ts`    缺席原因 + 本次挂载注册位（内存）
@@ -6272,6 +6623,10 @@ function apply(ctx, config = {}, deps = {}) {
 		profile,
 		logger: ctx.logger
 	});
+	const rosterSeenStore = createFileRosterSeenStore({
+		profile,
+		logger: ctx.logger
+	});
 	const publisher = createProviderPublisher({
 		settings,
 		panelSwitch: () => providerStore.enabled(),
@@ -6294,6 +6649,7 @@ function apply(ctx, config = {}, deps = {}) {
 		inference,
 		publisher,
 		usageEvents: () => usageStore.events(),
+		rosterSeenStore,
 		logger: ctx.logger
 	});
 	const wiring = {
@@ -6306,16 +6662,21 @@ function apply(ctx, config = {}, deps = {}) {
 		drawStore,
 		drawJobs,
 		usagePrefsStore,
+		rosterSeenStore,
 		publisher,
 		reconcile,
 		logger: ctx.logger
 	};
-	const offs = registerRoutes(ctx, wiring);
+	const drawMount = createDrawToolMount(ctx, wiring, deps);
+	const offs = registerRoutes(ctx, {
+		...wiring,
+		syncDraw: () => drawMount.sync()
+	});
 	ctx.effect(() => {
 		reconcile().catch((error) => {
 			ctx.logger?.warn?.(`${name}: mount reconcile failed (${redactSecrets(errMsg(error))})`);
 		});
-		registerDrawTool(ctx, wiring, deps);
+		drawMount.sync();
 		const timer = setInterval(() => {
 			reconcile().catch((error) => {
 				ctx.logger?.warn?.(`${name}: scheduled reconcile failed (${redactSecrets(errMsg(error))})`);
@@ -6323,6 +6684,7 @@ function apply(ctx, config = {}, deps = {}) {
 		}, settings.pollSeconds * 1e3);
 		return () => {
 			clearInterval(timer);
+			drawMount.dispose();
 			resetDrawToolNote();
 			drawJobs.dispose();
 			publisher.dispose();