dsh-router-core 0.4.0 → 0.4.2

package/lib/index.js

@@ -561,6 +561,7 @@ var SupplierConfigStore = class {
 		let cfg = this.bySupplier.get(supplierId);
 		if (!cfg) {
 			cfg = {
+				enabled: true,
 				alias: "",
 				disabled: [],
 				custom: [],
@@ -588,6 +589,22 @@ var SupplierConfigStore = class {
 		this.saveLocked();
 		return { ok: true };
 	}
+	/** 这个供应商是否参与路由（未记录过 = 开）。 */
+	isEnabled(supplierId) {
+		return this.get(supplierId).enabled;
+	}
+	/**
+	* 置供应商开关。**不写盘**时值不变也要返回，让调用方知道是否需要重连路由。
+	* @returns 值确实变了
+	*/
+	setEnabled(supplierId, enabled) {
+		if (supplierId === "") return false;
+		const cfg = this.get(supplierId);
+		if (cfg.enabled === enabled) return false;
+		cfg.enabled = enabled;
+		this.saveLocked();
+		return true;
+	}
 	setModelEnabled(supplierId, modelId, enabled) {
 		const cfg = this.get(supplierId);
 		cfg.disabled = enabled ? cfg.disabled.filter((m) => m !== modelId) : [.../* @__PURE__ */ new Set([...cfg.disabled, modelId])];
@@ -666,6 +683,7 @@ var SupplierConfigStore = class {
 			return;
 		}
 		for (const [id, c] of Object.entries(f.suppliers ?? {})) this.bySupplier.set(id, {
+			enabled: typeof c.enabled === "boolean" ? c.enabled : true,
 			alias: typeof c.alias === "string" ? c.alias : "",
 			disabled: Array.isArray(c.disabled) ? c.disabled.filter((m) => typeof m === "string") : [],
 			custom: Array.isArray(c.custom) ? c.custom.filter((m) => typeof m === "string") : [],
@@ -678,6 +696,7 @@ var SupplierConfigStore = class {
 		if (this.fp === "") return;
 		const f = { suppliers: {} };
 		for (const [id, cfg] of this.bySupplier) f.suppliers[id] = {
+			enabled: cfg.enabled,
 			alias: cfg.alias,
 			disabled: [...cfg.disabled],
 			custom: [...cfg.custom],
@@ -1453,6 +1472,99 @@ function isTransient(state) {
 	return state === "transport" || state === "unavailable";
 }
 /**
+* **每条降级腿的首字节预算**：从进入这条腿起，多久内上游必须吐出第一个字节。
+*
+* 为什么必须有（2026-09-24 夜里 money 组合实测）：上游（codebuddy 系）额度用完 /
+* 过载时，连接照常建立、HTTP 200 响应头照常回来，**body 却一个字节都不吐**。
+* 这既不是成功也不是失败，于是
+*   - `chatOnce` 的 120s 只守「连接+响应头」，`fetch` 一返回就撤表 → 守不到 body
+*   - 核心写响应的路径也没有任何计时器 → 组合链卡在这一条腿上不动
+*   - 客户端（dsh-router 自己的 adapter）有 300s 流空闲超时，但那是「整条请求」
+*     的兜底，与降级无关
+* 实测用户干等 200 多秒手动暂停：ttfb 84s / 122s / 151s / 244s / 246s / 250s /
+* 254s / 255s，8 次全部 `ok: true`——**全都最终成功了**，只是晚了四分钟。同一批
+* 账号因为「没失败」也不冷却，下一次请求继续挑它（cb-8 连吃 248s + 155s）。
+*
+* 60s 的来历（本机 500 条真实请求的 ttfb 分布）：p50 4.1s / p95 14.9s，
+* 最大的**非停滞**值 47.7s，停滞簇从 84.5s 起 —— 60s 正落在两簇之间的空档，
+* 砍得动停滞、砍不到真实慢请求。首个字节之后**不再计时**：长生成可以跑很久。
+*
+* 为什么按「腿」而不是按「账号」计：停滞是上游级的（同一供应商的所有号一起
+* 挂）。按账号计的话，codebuddy 有 11 个号，一次请求能 11×60s = 11 分钟才轮到
+* 下一个模型；按腿计，最坏 3 条腿 × 60s ≈ 3 分钟，且期间一定会走到下一个模型。
+*/
+const FIRST_BYTE_BUDGET_MS = 6e4;
+/**
+* 给上游流套一层**首字节截止**：截止前一个字节都没来，就把这条流判失败
+* （error 出去，调用方看到「一个字节都没写」→ 换号/换模型）。
+* 第一个字节到手后立刻撤表，之后多久都不管。
+*
+* 为什么套在核心而不是插件：首字节迟迟不来时，**只有核心**能做「还没提交响应
+* → 换一条腿」的决定（插件在 `fetch` 拿到响应头那一刻就把流交出去了，
+* 谁也没法再改结果）。核心也是所有供应商唯一的收口点，套一次全都受益。
+*/
+function withFirstByteDeadline(stream, ms) {
+	const reader = stream.getReader();
+	let first = true;
+	/** 消费方已取消：这之后任何 ctrl.* 都会抛（流已死），必须全部跳过。 */
+	let cancelled = false;
+	/**
+	* 上游 reader 只解绑一次。wrapper 替核心持有了这个 reader，所以**必须由
+	* wrapper 负责收尾**：上游正常读完 / 上游自己 error / 被取消时都解锁，
+	* 否则流永久锁着，上层想 cancel 会抛 `Invalid state: ReadableStream is locked`
+	* （disconnect-leak 那条判据守的就是这个；历史上由 aggregateSSE 的 finally 解锁，
+	* 现在读的是 wrapper，解绑责任跟着搬过来）。
+	*/
+	let released = false;
+	const release = () => {
+		if (released) return;
+		released = true;
+		try {
+			reader.releaseLock();
+		} catch {}
+	};
+	/** 取消要传到底下的上游（cancel 本身会顺带解锁）。 */
+	const cancelUpstream = (reason) => {
+		if (released) return Promise.resolve();
+		released = true;
+		return reader.cancel(reason).then(() => {}, () => {});
+	};
+	return new ReadableStream({
+		async pull(ctrl) {
+			let expired = false;
+			const timer = first ? setTimeout(() => {
+				expired = true;
+				cancelUpstream(/* @__PURE__ */ new Error("first byte timeout"));
+				try {
+					ctrl.error(/* @__PURE__ */ new Error(`no first byte within ${ms}ms`));
+				} catch {}
+			}, ms) : void 0;
+			try {
+				const { done, value } = await reader.read();
+				if (expired || cancelled) return;
+				if (done) {
+					release();
+					ctrl.close();
+					return;
+				}
+				first = false;
+				ctrl.enqueue(value);
+			} catch (e) {
+				release();
+				if (!expired && !cancelled) try {
+					ctrl.error(e);
+				} catch {}
+			} finally {
+				if (timer !== void 0) clearTimeout(timer);
+			}
+		},
+		cancel: (reason) => {
+			cancelled = true;
+			return cancelUpstream(reason);
+		}
+	});
+}
+/**
 * 从请求体里取 `messages`（前缀亲和的指纹输入）。解析失败/字段缺失返回
 * undefined —— 亲和拿不到输入就自动回退到块轮询，不影响路由本身。
 */
@@ -1723,8 +1835,11 @@ function fixFrame(frame) {
 *
 * 天花板：一旦写出第一个字节就绑死（HTTP 语义），中途断流只能截断，
 * 不能回退。要彻底解决得在写头前缓冲判定，代价是首字节延迟——未做。
+*
+* @param firstByteTimeoutMs 上游多久内必须吐出第一个字节（见 FIRST_BYTE_BUDGET_MS）。
+*   超时按「一个字节都没写」返回 false，调用方照常换号/换模型。
 */
-async function writeChatResult(res, r, wantsStream, probe, startedAt = 0) {
+async function writeChatResult(res, r, wantsStream, probe, startedAt = 0, firstByteTimeoutMs = FIRST_BYTE_BUDGET_MS) {
 	if (!r.ok) return false;
 	if (!("stream" in r)) {
 		if (probe !== void 0) probe.tokens = usageFromJsonBody(r.body);
@@ -1735,12 +1850,13 @@ async function writeChatResult(res, r, wantsStream, probe, startedAt = 0) {
 		res.end(r.body);
 		return true;
 	}
+	const src = withFirstByteDeadline(r.stream, firstByteTimeoutMs);
 	if (!wantsStream) {
 		let body;
 		try {
-			body = await aggregateSSE(r.stream);
+			body = await aggregateSSE(src);
 		} catch {
-			await r.stream.cancel().catch(() => {});
+			await src.cancel().catch(() => {});
 			return false;
 		}
 		if (probe !== void 0) probe.tokens = usageFromJsonBody(body);
@@ -1751,7 +1867,7 @@ async function writeChatResult(res, r, wantsStream, probe, startedAt = 0) {
 		res.end(body);
 		return true;
 	}
-	const tapped = probe === void 0 ? void 0 : tapStreamUsage(r.stream, startedAt);
+	const tapped = probe === void 0 ? void 0 : tapStreamUsage(src, startedAt);
 	let wroteAny = false;
 	/** 响应已死（客户端断开/res 已销毁）：等 drain 的写入要立刻放弃，别吊死。 */
 	let dead = false;
@@ -1815,7 +1931,7 @@ async function writeChatResult(res, r, wantsStream, probe, startedAt = 0) {
 		abort.abort();
 	};
 	res.once("close", onClose);
-	const norm = normalizeSSEStream(tapped?.stream ?? r.stream);
+	const norm = normalizeSSEStream(tapped?.stream ?? src);
 	try {
 		await norm.stream.pipeTo(new WritableStream({ write: writeChunk }), { signal: abort.signal });
 	} catch {} finally {
@@ -1846,6 +1962,12 @@ function extractUpstreamError(body) {
 }
 /** 路由器。 */
 var Router = class {
+	/**
+	* **已装载**的全部供应商（含被开关关掉的）。关掉的仍留在列表里 —— 否则用户关掉
+	* 之后它在 `/health`、面板、插件页里一起消失，开关就没有可指的对象、也没法再开。
+	*
+	* 真正参与路由的只有 `active` 那一份。
+	*/
 	suppliers = [];
 	combosFp = "";
 	customCombos = [];
@@ -1860,12 +1982,15 @@ var Router = class {
 	modelsInflight = /* @__PURE__ */ new Map();
 	/** 请求日志出口（面板/宿主 logger）。 */
 	log;
+	/** 每条降级腿的首字节预算（ms）。只给测试一个入口，生产恒为 FIRST_BYTE_BUDGET_MS。 */
+	firstByteBudgetMs;
 	/** 用量统计（概览看板）。 */
 	usage;
-	constructor(stateFile = "", store, log) {
+	constructor(stateFile = "", store, log, opts) {
 		this.combosFp = stateFile ? join(dirname(stateFile), "combos.json") : "";
 		this.store = store ?? new SupplierConfigStore(stateFile);
 		this.log = log ?? (() => {});
+		this.firstByteBudgetMs = opts?.firstByteBudgetMs ?? FIRST_BYTE_BUDGET_MS;
 		this.usage = new UsageStore(stateFile);
 		this.loadCombos();
 	}
@@ -1889,7 +2014,7 @@ var Router = class {
 					if (slash <= 0) return m;
 					const alias = m.slice(0, slash);
 					const modelId = m.slice(slash + 1);
-					const s = this.suppliers.find((x) => x.getAlias() === alias);
+					const s = this.active.find((x) => x.getAlias() === alias);
 					return s === void 0 ? modelId : `${s.id},${modelId}`;
 				});
 				return {
@@ -1916,6 +2041,20 @@ var Router = class {
 		this.suppliers.sort((a, b) => a.priority - b.priority);
 		this.store.sync(this.suppliers.map((s) => s.id));
 	}
+	/**
+	* **参与路由的供应商** —— 装载清单里开关为开的那一份，按 priority 排好。
+	*
+	* 这是「供应商开关」唯一的收口点：请求分发、别名反查、模型列表、组合、面板状态
+	* 全部读它。关掉一个供应商 = 它从这里消失，而不是在每个调用点各写一遍判断 ——
+	* 后者一定会漏（本次实测路由有 15 处读 `this.suppliers`）。
+	*/
+	get active() {
+		return this.suppliers.filter((s) => this.store.isEnabled(s.id));
+	}
+	/** 某供应商当前是否参与路由（面板与 API 用）。 */
+	isEnabled(supplierId) {
+		return this.store.isEnabled(supplierId);
+	}
 	/** 移除供应商（外部插件卸载时注销）。 */
 	removeSupplier(id) {
 		const i = this.suppliers.findIndex((s) => s.id === id);
@@ -1925,13 +2064,20 @@ var Router = class {
 		s?.dispose();
 		return true;
 	}
-	/** 返回全部供应商状态（面板用）。 */
+	/**
+	* 返回全部供应商状态（面板用）。**含被开关关掉的** —— 面板要能显示它们
+	* （「已关闭」），否则用户在面板上就再也看不到自己装过的供应商。
+	* 开关状态由 `enabled` 字段带出，调用方自己决定要不要只留开着的。
+	*/
 	status() {
-		return { suppliers: this.suppliers.map((s) => s.status()) };
+		return { suppliers: this.suppliers.map((s) => ({
+			...s.status(),
+			enabled: this.store.isEnabled(s.id)
+		})) };
 	}
-	/** 供应商前缀信息（组合模型全名 = alias/id，展示时动态拼接）。 */
+	/** 供应商前缀信息（组合模型全名 = alias/id，展示时动态拼接）。只含开着的。 */
 	aliases() {
-		return this.suppliers.map((s) => ({
+		return this.active.map((s) => ({
 			id: s.id,
 			name: s.name,
 			alias: s.getAlias()
@@ -1949,7 +2095,7 @@ var Router = class {
 			seen.add(c.name);
 			out.push({ id: c.name });
 		}
-		for (const s of this.suppliers) try {
+		for (const s of this.active) try {
 			const ids = s.customModelIds?.();
 			for (const id of ids ?? []) if (!seen.has(id)) {
 				seen.add(id);
@@ -2008,7 +2154,7 @@ var Router = class {
 		return min;
 	}
 	async modelsOf(supplierId, force = false) {
-		const s = this.suppliers.find((x) => x.id === supplierId);
+		const s = this.active.find((x) => x.id === supplierId);
 		if (s === void 0) return [];
 		const hit = this.modelsCache.get(supplierId);
 		const fresh = hit !== void 0 && Date.now() - hit.fetchedAt < MODELS_TTL_MS;
@@ -2072,7 +2218,7 @@ var Router = class {
 	/** 可用模型（按供应商分组，仅启用），面板加模型用。
 	*  各供应商**并行**拉取——串行会把每个上游的延迟累加起来。 */
 	async supplierModels() {
-		return (await Promise.all(this.suppliers.map(async (s) => {
+		return (await Promise.all(this.active.map(async (s) => {
 			try {
 				const models = (await this.modelsOf(s.id)).filter((m) => m.enabled);
 				return {
@@ -2107,7 +2253,7 @@ var Router = class {
 			if (slash <= 0) return m;
 			const alias = m.slice(0, slash);
 			const modelId = m.slice(slash + 1);
-			const s = this.suppliers.find((x) => x.getAlias() === alias);
+			const s = this.active.find((x) => x.getAlias() === alias);
 			return s === void 0 ? modelId : `${s.id},${modelId}`;
 		});
 	}
@@ -2233,7 +2379,7 @@ var Router = class {
 				const model = combo.models[i];
 				if (model === void 0) continue;
 				const trace = { attempts: 0 };
-				if (await this.chatWithModel(req, res, model, probe, trace)) {
+				if (await this.chatWithModel(req, res, model, probe, trace, Date.now() + this.firstByteBudgetMs)) {
 					settle(true);
 					return;
 				}
@@ -2279,8 +2425,11 @@ var Router = class {
 	* @param outTrace 可选出参：把这次调用的追踪信息带回去（组合据此判断
 	*   要不要「喘口气」再降级）。裸 id 遍历路径不填（多供应商混在一起，
 	*   失败状态没有单一归属）。
+	* @param firstByteDeadlineAt 这条腿的首字节截止时刻（绝对 ms）。同一条腿内的
+	*   多个账号共享它——停滞是上游级的，按号各给一份会 11×60s 才轮到下一个模型。
+	*   缺省 = 此刻起一份全新预算（直接调用路径只有这一条腿）。
 	*/
-	async chatWithModel(req, res, model, probe, outTrace) {
+	async chatWithModel(req, res, model, probe, outTrace, firstByteDeadlineAt = Date.now() + this.firstByteBudgetMs) {
 		const comma = model.indexOf(",");
 		const supplierId = comma > 0 ? model.slice(0, comma) : void 0;
 		const modelId = comma > 0 ? model.slice(comma + 1) : model;
@@ -2300,14 +2449,15 @@ var Router = class {
 			this.logChat(req.model, msg, 0);
 			return false;
 		}
-		const s = this.suppliers.find((x) => x.id === supplierId);
+		const s = this.active.find((x) => x.id === supplierId);
 		if (s === void 0) {
-			this.logChat(req.model, `supplier ${JSON.stringify(supplierId)} 不存在`, 0);
+			const reason = this.suppliers.some((x) => x.id === supplierId) ? `supplier ${JSON.stringify(supplierId)} 已关闭` : `supplier ${JSON.stringify(supplierId)} 不存在`;
+			this.logChat(req.model, reason, 0);
 			return false;
 		}
 		const t0 = Date.now();
 		const trace = { attempts: 0 };
-		const served = await this.chatWithSupplier(s, clone, res, trace, probe);
+		const served = await this.chatWithSupplier(s, clone, res, trace, probe, firstByteDeadlineAt);
 		if (outTrace !== void 0) {
 			outTrace.attempts = trace.attempts;
 			outTrace.lastError = trace.lastError;
@@ -2318,7 +2468,7 @@ var Router = class {
 	}
 	/** 按别名找供应商（对外模型全名 = alias/model）。别名唯一，故最多命中一个。 */
 	supplierByAlias(alias) {
-		return this.suppliers.find((s) => s.getAlias() === alias);
+		return this.active.find((s) => s.getAlias() === alias);
 	}
 	/**
 	* 单个供应商内遍历账号（核心策略）：选号 → 调 chatOnce → 按返回的
@@ -2328,8 +2478,16 @@ var Router = class {
 	* 还能换号重试；一旦写出第一个字节就绑死（HTTP 语义，9router 同样如此），
 	* 之后出错不再换号——要彻底能回退就得在写头前缓冲判定，代价是首字节
 	* 延迟，目前未做。
+	*
+	* @param firstByteDeadlineAt 这条腿的首字节截止时刻（见 chatWithModel）。
+	*   预算耗尽后不再调任何号：剩下的号大概率同样停滞（上游级故障），
+	*   挨个等下去只会把 60s 乘以号数，组合永远轮不到下一个模型。
+	*/
+	/**
+	* @param onlyUid - 只试这一个连接，**不做账号池回退**。给面板「指定连接」那档用
+	*   （诊断单个链接到底通不通）；正常请求与普通模型测试都不传，走账号池。
 	*/
-	async chatWithSupplier(s, req, res, trace, probe) {
+	async chatWithSupplier(s, req, res, trace, probe, firstByteDeadlineAt = Date.now() + this.firstByteBudgetMs, onlyUid) {
 		const pool = s.pool;
 		const cfg = this.store.get(s.id);
 		if (s.accounts !== void 0 && s.accounts().length === 0) {
@@ -2346,14 +2504,27 @@ var Router = class {
 				probe.model = `${s.getAlias()}/${stripAlias(req.model, s.getAlias())}`;
 				probe.uid = "";
 			}
-			return await writeChatResult(res, r, req.stream, probe, probe?.startedAt ?? 0);
+			return await writeChatResult(res, r, req.stream, probe, probe?.startedAt ?? 0, firstByteDeadlineAt - Date.now());
 		}
 		const messages = reqMessages(req.rawBody);
 		const tried = /* @__PURE__ */ new Set();
 		let pickWhy = "";
 		for (;;) {
-			const uid = pool.pick(s.accounts().filter((a) => !tried.has(a.uid)), cfg.poolOrder, req.model, messages, req.session);
-			if (uid === void 0) return false;
+			const uid = onlyUid !== void 0 ? s.accounts().some((a) => a.uid === onlyUid) && !tried.has(onlyUid) ? onlyUid : void 0 : pool.pick(s.accounts().filter((a) => !tried.has(a.uid)), cfg.poolOrder, req.model, messages, req.session);
+			if (uid === void 0) {
+				if (onlyUid !== void 0 && trace !== void 0) {
+					trace.lastState = "unknown";
+					trace.lastError = `连接 ${JSON.stringify(onlyUid)} 不存在（可能已被删除）`;
+				}
+				return false;
+			}
+			if (firstByteDeadlineAt - Date.now() <= 0) {
+				if (trace !== void 0) {
+					trace.lastState = "transport";
+					trace.lastError = "first-byte budget exhausted";
+				}
+				return false;
+			}
 			pickWhy = pool.lastWhy;
 			tried.add(uid);
 			const r = await s.chatOnce(uid, req.lv ?? "auto", req);
@@ -2384,7 +2555,7 @@ var Router = class {
 				probe.model = `${s.getAlias()}/${stripAlias(req.model, s.getAlias())}`;
 				probe.uid = uid;
 			}
-			if (await writeChatResult(res, r, req.stream, probe, probe?.startedAt ?? 0)) {
+			if (await writeChatResult(res, r, req.stream, probe, probe?.startedAt ?? 0, firstByteDeadlineAt - Date.now())) {
 				pool.noteCache(uid, req.model, probe?.tokens?.cachedTokens ?? 0, req.session);
 				return true;
 			}
@@ -2396,11 +2567,17 @@ var Router = class {
 			}
 		}
 	}
-	/** 测试某供应商的某模型是否可用。
-	*  走真实的账号遍历 + chatOnce 路径：账号池回退/冷却由核心实现，自动生效；
-	*  响应丢弃到 sink，限定单一供应商（不跨供应商回退）。 */
-	async testModel(supplierId, model) {
-		const s = this.suppliers.find((x) => x.id === supplierId);
+	/**
+	* 测试某供应商的某模型是否可用。
+	*
+	* 走真实的账号遍历 + chatOnce 路径：账号池回退/冷却由核心实现，自动生效；
+	* 响应丢弃到 sink，限定单一供应商（不跨供应商回退）。
+	*
+	* @param onlyUid - 限定只测这一个连接（诊断单个链接），**不做账号池回退**。
+	*   不传 = 与面板「测试」按钮完全同一条路径（池内任选可用号，失败自动换号）。
+	*/
+	async testModel(supplierId, model, onlyUid) {
+		const s = this.active.find((x) => x.id === supplierId);
 		if (s === void 0) return {
 			ok: false,
 			error: `unknown supplier ${JSON.stringify(supplierId)}`
@@ -2422,7 +2599,7 @@ var Router = class {
 		let served = false;
 		const trace = { attempts: 0 };
 		try {
-			served = await this.chatWithSupplier(s, req, sink, trace);
+			served = await this.chatWithSupplier(s, req, sink, trace, void 0, Date.now() + this.firstByteBudgetMs, onlyUid);
 		} catch (err) {
 			return {
 				ok: false,
@@ -2455,8 +2632,43 @@ var Router = class {
 * `image` 块序列化成 OpenAI 标准的 `image_url` base64 part，经 /v1 原样透传给
 * 命中的上游供应商。最终能否看图取决于**命中的那个上游模型**——组合里是异构
 * 供应商，可能在网关端声明了图片能力、某条上游却只收文本（此时由上游自行拒收）。
-* 图片字节从 `ctx.attachments` 读取（读不到的按稳定占位文本降级，绝不静默丢图）。
+* 图片字节从 `ctx.attachments` 读取。读不到时按稳定占位文本降级（不让整条消息失败），
+* 但**必须留痕**：降级原因走 adapter 的 `log` 出口打到宿主 logger。曾经这里是
+* 一个空 `catch {}`，字段改名导致的读图失败静默了跨两个内测版本（issue #8）。
 */
+/** 送上游的请求图的像素预算（宽 × 高），沿用 0.1.5 时代 `maxPixels` 的意图。 */
+const MAX_REQUEST_PIXELS = 64e4;
+/** 送上游的请求图的字节上限。 */
+const MAX_REQUEST_BYTES = 1048576;
+/**
+* 把源图尺寸投影到「总像素 ≤ maxPixels」的请求目标（等比、只缩不放）。
+*
+* 为什么需要它：宿主 0.1.6 起要的是 `ImageRequestTarget`（width/height/maxBytes），
+* 而「别把一张 12MP 手机照原样塞进对话」这个意图原本靠 `maxPixels` 表达。
+* 宿主自己**只按 target 的长边**缩放、短边由它推，所以我们要做的只是给出一组
+* 落在预算内的正整数；短边取 floor 即可（它只参与校验与缓存键，不决定出图尺寸）。
+*
+* 没有直接复用官方的 `requestImageDimensions`（`@deepseek-ai/dsh-attachment` 有导出）：
+* 本文件刻意不依赖那个包（见 `RouterAttachmentStore` 的说明 —— 它是宿主注入的
+* devDependency，引入它等于给插件加一条编译期/运行期依赖）。这 8 行是纯函数、
+* 有测试钉住；真要换成官方实现时，语义等价。
+*/
+function projectImageDimensions(width, height, maxPixels) {
+	const pixels = width * height;
+	if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) return {
+		width,
+		height
+	};
+	if (pixels <= maxPixels) return {
+		width,
+		height
+	};
+	const scale = Math.sqrt(maxPixels / pixels);
+	return {
+		width: Math.max(1, Math.floor(width * scale)),
+		height: Math.max(1, Math.floor(height * scale))
+	};
+}
 /**
 * 把 DSH 消息序列化成 openai 兼容 wire 消息（文本 + 图片 + tool）。
 *
@@ -2491,7 +2703,7 @@ const TOOL_RESULT_IMAGE_TEXT = "Tool result images";
 * 只守空闲、不封总时长：长生成只要持续吐块就不该被打断。
 */
 const STREAM_IDLE_TIMEOUT_MS = 3e5;
-async function wireMessages(options, system, attachments) {
+async function wireMessages(options, system, attachments, log) {
 	const out = [];
 	/**
 	* 攒着「tool-result 里带出来的图片」，等这一串 tool 消息**发完**再合并成一条
@@ -2551,7 +2763,7 @@ async function wireMessages(options, system, attachments) {
 		}
 		if (message.role === "tool") {
 			const toolCallId = message.toolCallId;
-			const parts = await contentParts(message.content, attachments, options.signal);
+			const parts = await contentParts(message.content, attachments, options.signal, log);
 			const imageParts = parts.filter((p) => p.type !== "text");
 			const text = parts.filter((p) => p.type === "text").map((p) => p.text ?? "").join("");
 			out.push({
@@ -2563,7 +2775,7 @@ async function wireMessages(options, system, attachments) {
 			continue;
 		}
 		const toolResults = message.content.filter((b) => b.type === "tool-result");
-		const ownParts = await contentParts(message.content.filter((b) => b.type !== "tool-result"), attachments, options.signal);
+		const ownParts = await contentParts(message.content.filter((b) => b.type !== "tool-result"), attachments, options.signal, log);
 		if (ownParts.length > 0 || toolResults.length === 0) {
 			flushToolImages();
 			out.push({
@@ -2572,7 +2784,7 @@ async function wireMessages(options, system, attachments) {
 			});
 		}
 		for (const result of toolResults) {
-			const parts = await contentParts(result.content, attachments, options.signal);
+			const parts = await contentParts(result.content, attachments, options.signal, log);
 			const imageParts = parts.filter((p) => p.type !== "text");
 			const text = parts.filter((p) => p.type === "text").map((p) => p.text ?? "").join("");
 			out.push({
@@ -2603,7 +2815,7 @@ function compactUserContent(parts) {
 * 纯文本时返回空数组（上层走紧凑字符串路径）。图片转 base64 data URI；
 * attachments 缺失或读取失败时回退稳定占位文本（绝不静默丢图）。
 */
-async function contentParts(blocks, attachments, signal) {
+async function contentParts(blocks, attachments, signal, log) {
 	const parts = [];
 	for (const block of blocks) {
 		if (block.type === "text") {
@@ -2616,35 +2828,41 @@ async function contentParts(blocks, attachments, signal) {
 		}
 		if (block.type === "image") {
 			const ref = block.attachment;
-			parts.push(...await imageParts(ref, attachments, signal));
+			parts.push(...await imageParts(ref, attachments, signal, log));
 			continue;
 		}
-		if (block.type === "tool-result") parts.push(...await contentParts(block.content, attachments, signal));
+		if (block.type === "tool-result") parts.push(...await contentParts(block.content, attachments, signal, log));
 	}
 	return parts;
 }
 /** 一张图片 → 一个 OpenAI image_url part（或读不到附件时的占位文本）。 */
-async function imageParts(ref, attachments, signal) {
-	if (attachments === void 0) return [{
-		type: "text",
-		text: imagePlaceholder(ref.attachmentId)
-	}];
+async function imageParts(ref, attachments, signal, log) {
+	if (attachments === void 0) {
+		log?.("图片附件 store 不可用（ctx.attachments 未注入），该图降级为占位文本");
+		return [{
+			type: "text",
+			text: imagePlaceholder(ref.attachmentId)
+		}];
+	}
+	const ref0 = {
+		attachmentId: ref.attachmentId,
+		mediaType: ref.mediaType,
+		bytes: ref.bytes,
+		width: ref.width,
+		height: ref.height
+	};
+	const target = {
+		...projectImageDimensions(ref.width, ref.height, MAX_REQUEST_PIXELS),
+		maxBytes: MAX_REQUEST_BYTES
+	};
 	try {
-		const img = await attachments.readImageRequest({
-			attachmentId: ref.attachmentId,
-			mediaType: ref.mediaType,
-			bytes: ref.bytes,
-			width: ref.width,
-			height: ref.height
-		}, {
-			maxPixels: 64e4,
-			maxBytes: 1048576
-		}, signal);
+		const img = await attachments.readImageRequest(ref0, target, signal);
 		return [{
 			type: "image_url",
 			image_url: { url: `data:${img.mediaType};base64,${bytesToBase64(img.data)}` }
 		}];
-	} catch {
+	} catch (err) {
+		log?.(`读取图片 ${ref.attachmentId} 失败，已降级为占位文本：${err.message}`);
 		return [{
 			type: "text",
 			text: imagePlaceholder(ref.attachmentId)
@@ -2663,8 +2881,8 @@ function imagePlaceholder(attachmentId) {
 	return `[image omitted because the attached bytes could not be read; attachment ${attachmentId}]`;
 }
 /** 组装 wire 请求体。图片序列化需要读 attachments，故为异步。 */
-async function wireRequest(options, attachments) {
-	const messages = await wireMessages(options, options.system, attachments);
+async function wireRequest(options, attachments, log) {
+	const messages = await wireMessages(options, options.system, attachments, log);
 	const body = {
 		model: options.model,
 		messages,
@@ -2942,21 +3160,31 @@ const ROUTER_REASONING_EFFORTS = [
 	}
 ];
 var RouterAdapter = class RouterAdapter extends LlmAdapter {
+	/**
+	* 网关端点。**函数形态 = 每次请求现算**：端口要等宿主 listen 完才有值的场景
+	* 必须传函数（写死 3080 在桌面端等非 3080 宿主上全线 `fetch failed`，
+	* issue #9），见 `host-base-url.ts`。
+	*/
 	baseURL;
 	source;
 	resolveAttachments;
 	/** 流空闲超时（ms）：上游这么久不吐字节就判 TIMEOUT。 */
 	idleTimeoutMs;
+	/** 降级/失败诊断的出口（宿主接 ctx.logger.warn）。缺省丢弃 —— 仅为测试可注入。 */
+	log;
 	/**
 	* @param idleTimeoutMs 流空闲超时；缺省用生产值（300s，对齐 pi-ai）。
 	*   可注入只为测试能压到几百毫秒，生产不传。
+	* @param log 降级诊断出口。图片读不到时会降级成占位文本，原因走这里 ——
+	*   曾经那条路径是个空 `catch`，出问题跨版本都没人发现（issue #8）。
 	*/
-	constructor(baseURL, source, resolveAttachments, idleTimeoutMs = STREAM_IDLE_TIMEOUT_MS) {
+	constructor(baseURL, source, resolveAttachments, idleTimeoutMs = STREAM_IDLE_TIMEOUT_MS, log) {
 		super();
 		this.baseURL = baseURL;
 		this.source = source;
 		this.resolveAttachments = resolveAttachments ?? (() => void 0);
 		this.idleTimeoutMs = idleTimeoutMs;
+		this.log = log;
 	}
 	providerInfo(provider) {
 		return {
@@ -3003,13 +3231,14 @@ var RouterAdapter = class RouterAdapter extends LlmAdapter {
 		};
 	}
 	async *stream(options) {
-		const body = await wireRequest(options, this.resolveAttachments());
+		const body = await wireRequest(options, this.resolveAttachments(), this.log);
 		const controller = new AbortController();
 		const onAbort = () => controller.abort();
 		options.signal?.addEventListener("abort", onAbort, { once: true });
 		let resp;
 		try {
-			resp = await fetch(`${this.baseURL}/chat/completions`, {
+			const base = typeof this.baseURL === "function" ? this.baseURL() : this.baseURL;
+			resp = await fetch(`${base}/chat/completions`, {
 				method: "POST",
 				headers: {
 					...attributionHeaders(),
@@ -3243,12 +3472,18 @@ var KeysStore = class {
 //#endregion
 //#region src/suppliers/loader.ts
 /**
-* 供应商 loader —— 扫描 suppliers 目录下的 *.js，动态 import，按契约包装成
+* 供应商 loader —— 扫描 **用户目录**下的 *.js，动态 import，按契约包装成
 * 内部 Supplier，并暴露"能力检测"(capabilities)供通用路由/前端按能力渲染。
 *
-* 加载来源（两处，profile 优先）：
-*   1. 内置：<plugin>/lib/suppliers/*.js（随插件分发）
-*   2. 用户：~/.dsh/profiles/web/suppliers/*.js（用户自定义）
+* 加载来源（两处）：
+*   1. 用户：`~/.dsh/profiles/<profile>/suppliers/*.js`（自定义供应商）
+*   2. 内置：**插件页「包含的组件」里的行** —— core 自己的 cordis.patch.yml
+*      insert 了三个子路径模块，经 `router.suppliers` 表进来，与独立安装的
+*      供应商插件同一条通道，核心不区分内外，只看工厂上的 `source` 标签。
+*
+* 内置曾经也是「扫 `<plugin>/lib/suppliers/*.js`」（本文件早先的 builtinDir）。
+* 改成行之后那条路径已删：扫目录拿不到行的身份（插件页的开关/显示名/说明），
+* 而且关一个内置供应商要手改配置才生效 —— 行才有宿主管的开关。
 */
 function isFn(v) {
 	return typeof v === "function";
@@ -3384,7 +3619,27 @@ function scanDir(dir) {
 		return [];
 	}
 }
-/** 加载全部供应商（内置 + 用户，用户覆盖内置同 id）。 */
+/**
+* 同 id 冲突时的优先级：**用户目录 js > 内置行 > 外部插件供应商**。
+*
+* 为什么用户目录最高：用户放一个同 id 的 js 就是想替换它，这是「扫目录时代」
+* 就有的语义（见本文件早先的 `loadSuppliers`：内置被用户版覆盖），内置改成行
+* 之后不能悄悄反过来。
+*
+* 纯函数 + 有测试：这条规则错了不会抛异常，只会让用户的覆盖悄悄失效。
+*/
+const SUPPLIER_RANK = {
+	user: 2,
+	builtin: 1,
+	external: 0
+};
+function supplierWins(incoming, existing) {
+	return SUPPLIER_RANK[incoming] > SUPPLIER_RANK[existing];
+}
+/**
+* 加载用户目录下的供应商。同一个 id 出现多个文件时**后者覆盖前者**（按文件名序），
+* 与内置共存的裁决交给核心（`registerLoaded` 的优先级：用户目录 js > 行）。
+*/
 async function loadSuppliers(opts) {
 	const env = {
 		dataDir: opts.dataDir,
@@ -3394,18 +3649,10 @@ async function loadSuppliers(opts) {
 	};
 	const byId = /* @__PURE__ */ new Map();
 	const errors = [];
-	const files = [...scanDir(opts.builtinDir).map((f) => ({
-		f,
-		builtin: true
-	})), ...scanDir(opts.userDir).map((f) => ({
-		f,
-		builtin: false
-	}))];
-	for (const { f, builtin } of files) try {
-		const loaded = await loadOne(f, env, builtin ? "builtin" : "user");
-		if (byId.get(loaded.supplier.id) && builtin) continue;
+	for (const f of scanDir(opts.userDir).sort()) try {
+		const loaded = await loadOne(f, env, "user");
 		byId.set(loaded.supplier.id, loaded);
-		opts.log(`supplier ${loaded.supplier.id} loaded (${builtin ? "builtin" : "user"}) from ${basename(f)}`);
+		opts.log(`supplier ${loaded.supplier.id} loaded (user) from ${basename(f)}`);
 	} catch (err) {
 		errors.push({
 			id: basename(f, ".js"),
@@ -3420,6 +3667,355 @@ async function loadSuppliers(opts) {
 	};
 }
 //#endregion
+//#region src/suppliers/probe.ts
+/**
+* 契约成员清单（体检的唯一事实来源）。
+*
+* `required: false` = 差异化能力，按存在性暴露端点/UI；`probe: 'skip'` 的理由都写在这里，
+* 面板会把 `skipReason` 原样显示 —— 用户能知道「有这个能力，只是体检不替你调」。
+*/
+const SUPPLIER_CONTRACT_MEMBERS = [
+	{
+		key: "id",
+		label: "供应商 id",
+		required: true,
+		probe: "safe"
+	},
+	{
+		key: "name",
+		label: "显示名",
+		required: true,
+		probe: "safe"
+	},
+	{
+		key: "priority",
+		label: "优先级",
+		required: false,
+		probe: "safe"
+	},
+	{
+		key: "icon",
+		label: "图标",
+		required: false,
+		probe: "safe"
+	},
+	{
+		key: "apiKeyHint",
+		label: "API key 提示文案",
+		required: false,
+		probe: "safe"
+	},
+	{
+		key: "status",
+		label: "账号状态",
+		required: true,
+		probe: "safe"
+	},
+	{
+		key: "listModels",
+		label: "模型列表",
+		required: true,
+		probe: "safe"
+	},
+	{
+		key: "chatOnce",
+		label: "调用上游",
+		required: true,
+		probe: "skip",
+		skipReason: "会真的发一次请求（消耗额度）。用上面的「跑一次访问测试」单独测，或在供应商详情里测模型。"
+	},
+	{
+		key: "checkinNow",
+		label: "签到",
+		required: false,
+		probe: "skip",
+		skipReason: "会替这个连接真的去签到。"
+	}
+];
+/** 读原始模块实例（`wrapModule` 挂在 wrapper 上）。 */
+function rawModule(loaded) {
+	return loaded.supplier.__module ?? {};
+}
+/** 读出账号状态列表（只读，不改任何东西）。 */
+function accountStates(status) {
+	if (typeof status !== "object" || status === null) return [];
+	const accounts = status.accounts;
+	if (!Array.isArray(accounts)) return [];
+	return accounts.flatMap((a) => {
+		const uid = a?.uid;
+		if (typeof uid !== "string") return [];
+		return [{
+			uid,
+			state: typeof a.state === "string" ? a.state : "ok",
+			cooling: a.cooling === true
+		}];
+	});
+}
+/** 第一个连接 uid（`checkinNow` 之类要真实连接时用）。 */
+function firstAccountUid(m) {
+	return accountStates(m.status())[0]?.uid;
+}
+/** 账号状态分布：`正常 2、冷却 1`、`session_dead 1` 这样。 */
+function accountTally(accounts) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const a of accounts) {
+		const key = a.cooling ? "冷却" : a.state === "ok" ? "正常" : a.state;
+		counts.set(key, (counts.get(key) ?? 0) + 1);
+	}
+	return [...counts].map(([k, n]) => `${k} ${n}`).join("、");
+}
+/**
+* 摘要：把返回值压成一行**对排查有用**的文本。
+*
+* 原先只说「返回 number」「返回 data:image/svg+xml,%3Csvg…」——等于没说话：
+* 体检的意义就是让人一眼看出「priority 是几」「图标给了没有」。
+*/
+function describe(value) {
+	if (value === void 0) return "未提供（可选）";
+	if (value === null) return "返回 null";
+	if (Array.isArray(value)) return `${value.length} 项`;
+	if (typeof value === "string") {
+		if (value.startsWith("data:")) return `已提供（内联 ${value.slice(5, value.indexOf("/") || 12)}）`;
+		if (value === "") return "返回空串";
+		return value.length > 48 ? `返回 ${value.slice(0, 48)}…` : `返回 ${value}`;
+	}
+	if (typeof value === "number" || typeof value === "boolean") return `返回 ${value}`;
+	if (typeof value === "object") {
+		const o = value;
+		if (typeof o.ok === "boolean") return o.ok === false ? `ok:false ${String(o.error ?? o.message ?? "")}`.trim() : "ok:true";
+		return Object.keys(o).slice(0, 4).join(", ") || "空对象";
+	}
+	return `返回 ${typeof value}`;
+}
+/** 异步取一个值并压成摘要（同步抛错也要接住）。 */
+async function probeValue(call) {
+	try {
+		return {
+			ok: true,
+			detail: describe(await call())
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			detail: err.message
+		};
+	}
+}
+/**
+*（这里原本有一份「永不实跑」名单：`dispose` / `addApiKey`。
+*   两者都已移出体检清单，名单随之作废 —— 留着空机制比删掉更糟：
+*   它看起来像个可配置的开关，其实没有任何成员会命中。
+*   「为什么要移」见 PROBE_EXCLUDED_MEMBERS。）
+*/
+/** 深度档用来「不碰真实状态就跑通代码路径」的探针输入。 */
+const PROBE_UID = "__probe_no_such_uid__";
+const PROBE_CALLBACK = "https://invalid.example/__probe__";
+/**
+* 体检一个已装载的供应商。
+*
+* 只跑 `probe: 'safe'` 的成员；`skip` 的只报存在性。绝不代替用户调有副作用的成员。
+*
+* @param models - 该供应商当前的模型启用状态（由调用方用 `router.modelsOf` 取，
+*   走核心缓存不额外打上游）。取不到就传 undefined —— 报告里会如实写「拿不到」，
+*   不能拿 0 冒充「一个模型都没有」。
+*/
+async function probeSupplier(loaded, input = {}) {
+	const m = rawModule(loaded);
+	const members = [];
+	for (const member of SUPPLIER_CONTRACT_MEMBERS) {
+		const present = member.key in m ? m[member.key] !== void 0 : false;
+		const base = {
+			key: member.key,
+			label: member.label,
+			required: member.required,
+			present,
+			executed: present ? "ran" : "no"
+		};
+		if (!present) {
+			members.push({
+				...base,
+				state: member.required ? "fail" : "absent",
+				...member.required ? { detail: "必填成员缺失，插件不完整" } : {}
+			});
+			continue;
+		}
+		const outcome = member.probe === "safe" ? await runSafeProbe(member.key, m, input) : await runProbedMember(member.key, m, input);
+		members.push({
+			...base,
+			state: outcome.ok ? "ok" : outcome.detail.startsWith("无法验证") ? "unverified" : "fail",
+			detail: outcome.detail
+		});
+	}
+	const bulkResult = await runBulkRoundTrip(input);
+	input.models;
+	const summary = {
+		total: members.length,
+		implemented: members.filter((x) => x.present).length,
+		ok: members.filter((x) => x.state === "ok").length,
+		fail: members.filter((x) => x.state === "fail").length,
+		absent: members.filter((x) => x.state === "absent").length,
+		unverified: members.filter((x) => x.state === "unverified").length
+	};
+	const listModels = members.find((x) => x.key === "listModels");
+	return {
+		supplier: loaded.supplier.id,
+		name: loaded.supplier.name,
+		members,
+		core: await coreReport(input, listModels?.state === "ok", bulkResult),
+		summary: {
+			...summary,
+			ran: members.filter((x) => x.executed === "ran" && x.present).length,
+			bulk: bulkResult.ran ? bulkResult.ok === true ? "ok" : "fail" : "unverified"
+		}
+	};
+}
+/**
+* 实跑「有副作用但可以安全试」的成员：要么用**无害探针输入**跑通代码路径，要么用
+* **连接池里的真实连接**真跑一次（前提由使用者保证：池里已放好可用 token）。
+*/
+async function runProbedMember(key, m, input) {
+	try {
+		switch (key) {
+			case "chatOnce": {
+				if (input.runChatOnce === void 0) return {
+					ok: false,
+					detail: "无法验证：没有发起真实调用的入口"
+				};
+				const model = input.models?.find((x) => x.enabled)?.id ?? input.models?.[0]?.id;
+				if (model === void 0) return {
+					ok: false,
+					detail: "无法验证：没有已启用的模型（先启用至少一个）"
+				};
+				const r = await input.runChatOnce(model);
+				return {
+					ok: r.ok,
+					detail: `真实调用 ${model}：${r.ok ? "通了" : `失败（${r.detail}）`}`
+				};
+			}
+			case "checkinNow": {
+				const uid = firstAccountUid(m);
+				if (uid === void 0) return {
+					ok: false,
+					detail: "无法验证：连接池里没有可用连接（先加一个 token）"
+				};
+				const v = await m.checkinNow?.(uid);
+				return {
+					ok: v?.ok !== false,
+					detail: `对连接 ${uid} 真实签到：${describe(v)}`
+				};
+			}
+			case "generateLoginUrl": return {
+				ok: true,
+				detail: describe(await m.generateLoginUrl?.())
+			};
+			case "completeLogin": return {
+				ok: true,
+				detail: `无效回调实跑：${describe(await m.completeLogin?.(PROBE_CALLBACK))}（没抛错即通过）`
+			};
+			case "removeLink": {
+				const v = await m.removeLink?.(PROBE_UID);
+				return {
+					ok: v !== false,
+					detail: `不存在的连接实跑：${describe(v)}`
+				};
+			}
+			default: return {
+				ok: true,
+				detail: "未纳入自动实跑"
+			};
+		}
+	} catch (err) {
+		return {
+			ok: false,
+			detail: `实跑抛错（这本身就是一条问题）：${err.message}`
+		};
+	}
+}
+/** 核心代劳的能力区：模型启用/禁用状态 + 那几个改配置的操作（只报可用性）。 */
+/** 核心区：模型启用状态 + 「全部启用/禁用」实跑结果。 */
+async function coreReport(input, modelsProbed, bulk) {
+	const models = input.models;
+	const enabled = models?.filter((m) => m.enabled).length;
+	const disabled = models === void 0 ? void 0 : models.length - (enabled ?? 0);
+	return {
+		models: {
+			total: models?.length ?? null,
+			enabled: enabled ?? 0,
+			disabled: disabled ?? 0,
+			...models === void 0 ? { note: modelsProbed ? "拿不到模型列表" : "listModels 不可用，无法读启用状态" } : {}
+		},
+		operations: [{
+			key: "models.bulk",
+			label: "模型全部启用 / 全部禁用",
+			ran: bulk.ran,
+			...bulk.ok === void 0 ? {} : { ok: bulk.ok },
+			detail: bulk.detail
+		}]
+	};
+}
+/**
+* 实跑「全部禁用 → 看列表 → 全部启用」。
+*
+* 违规的插件会在这里露馅：它把已禁用的模型从 `listModels` 里过滤掉了，于是全部禁用
+* 之后核心**看不到任何一个模型** —— 用户点「全部启用」也就再也点不回来了
+* （路由里没有可用的模型 id 可传）。
+*/
+async function runBulkRoundTrip(input) {
+	if (input.runBulkToggleRoundTrip === void 0) return {
+		ran: false,
+		detail: "没有模型可禁用"
+	};
+	try {
+		const r = await input.runBulkToggleRoundTrip();
+		return {
+			ran: true,
+			ok: r.ok,
+			detail: r.detail
+		};
+	} catch (err) {
+		return {
+			ran: true,
+			ok: false,
+			detail: `实跑抛错：${err.message}`
+		};
+	}
+}
+/** 无副作用成员的实跑。**每个 case 都必须没有副作用** —— 新增成员时照此办理。 */
+async function runSafeProbe(key, m, input) {
+	switch (key) {
+		case "id":
+		case "name":
+		case "priority":
+		case "icon":
+		case "apiKeyHint": {
+			const value = m[key];
+			if (value === void 0) return {
+				ok: true,
+				detail: "未提供（可选）"
+			};
+			return {
+				ok: true,
+				detail: describe(value)
+			};
+		}
+		case "status": {
+			const r = await probeValue(() => m.status());
+			if (!r.ok) return r;
+			const accounts = accountStates(m.status());
+			return {
+				ok: true,
+				detail: accounts.length === 0 ? "无账号（无账号直连型供应商）" : `${accounts.length} 个账号：${accountTally(accounts)}`
+			};
+		}
+		case "listModels": return await probeValue(() => m.listModels());
+		case "pollLogin": return await probeValue(() => m.pollLogin?.());
+		default: return {
+			ok: true,
+			detail: "未纳入自动探测"
+		};
+	}
+}
+//#endregion
 //#region src/suppliers/registry.ts
 function writeJson$1(res, status, body) {
 	const payload = JSON.stringify(body);
@@ -3496,6 +4092,106 @@ function supplierRoutes(base, loaded, store, router) {
 			});
 		}
 	});
+	routes.push({
+		kind: "exact",
+		path: `${p}/enabled`,
+		handler: async (req, res) => {
+			let body;
+			try {
+				body = JSON.parse(await readBody$1(req));
+			} catch {
+				writeJson$1(res, 400, {
+					ok: false,
+					error: "invalid JSON body"
+				});
+				return;
+			}
+			if (typeof body.enabled !== "boolean") {
+				writeJson$1(res, 400, {
+					ok: false,
+					error: "enabled must be a boolean"
+				});
+				return;
+			}
+			store.setEnabled(s.id, body.enabled);
+			router.invalidateModels(s.id);
+			writeJson$1(res, 200, {
+				ok: true,
+				id: s.id,
+				enabled: router.isEnabled(s.id)
+			});
+		}
+	});
+	routes.push({
+		kind: "exact",
+		path: `${p}/probe`,
+		handler: async (req, res) => {
+			if (req.method !== "POST") {
+				writeJson$1(res, 405, {
+					ok: false,
+					error: "probe requires POST"
+				});
+				return;
+			}
+			try {
+				let pick = {};
+				const raw = (await readBody$1(req)).trim();
+				if (raw !== "") {
+					const body = JSON.parse(raw);
+					pick = {
+						...typeof body.model === "string" ? { model: body.model } : {},
+						...typeof body.uid === "string" ? { uid: body.uid } : {}
+					};
+				}
+				writeJson$1(res, 200, {
+					ok: true,
+					report: await probeSupplier(loaded, {
+						models: await router.modelsOf(s.id).catch(() => void 0),
+						runBulkToggleRoundTrip: async () => {
+							const original = [...store.get(s.id).disabled];
+							const ids = (await router.modelsOf(s.id)).map((mm) => mm.id);
+							if (ids.length === 0) return {
+								ok: true,
+								detail: "该供应商没有模型，跳过"
+							};
+							try {
+								store.setAllModelsEnabled(s.id, false, ids);
+								router.invalidateModels(s.id);
+								const after = await router.modelsOf(s.id, true);
+								const hidden = after.filter((mm) => !mm.enabled).length;
+								const missing = ids.length - after.length;
+								if (hidden !== ids.length || missing !== 0) return {
+									ok: false,
+									detail: `全部禁用后只剩 ${after.length}/${ids.length} 个 —— 插件在 listModels 里藏了已禁用的模型（启用状态由核心合并）`
+								};
+								return {
+									ok: true,
+									detail: `全部禁用后 ${after.length} 个都在，再启用可恢复`
+								};
+							} finally {
+								store.setAllModelsEnabled(s.id, true, ids);
+								for (const id of original) store.setAllModelsEnabled(s.id, false, [id]);
+								router.invalidateModels(s.id);
+								await router.modelsOf(s.id, true);
+							}
+						},
+						runChatOnce: async (model) => {
+							const r = await router.testModel(s.id, model, pick.uid);
+							return {
+								ok: r.ok,
+								detail: r.ok ? "通了" : r.error ?? "上游没给原因"
+							};
+						}
+					})
+				});
+			} catch (err) {
+				writeJson$1(res, 500, {
+					ok: false,
+					error: err.message
+				});
+			}
+		}
+	});
 	routes.push({
 		kind: "exact",
 		path: `${p}/alias`,
@@ -3629,7 +4325,8 @@ function supplierRoutes(base, loaded, store, router) {
 		path: `${p}/models/test`,
 		handler: async (req, res) => {
 			const body = JSON.parse(await readBody$1(req));
-			const result = await router.testModel(s.id, body.id ?? "");
+			const onlyUid = typeof body.uid === "string" && body.uid !== "" ? body.uid : void 0;
+			const result = await router.testModel(s.id, body.id ?? "", onlyUid);
 			writeJson$1(res, result.ok ? 200 : 400, result);
 		}
 	});
@@ -3874,6 +4571,47 @@ function dshHome() {
 	return resolve(value);
 }
 //#endregion
+//#region src/host-base-url.ts
+/**
+* 网关端点地址（`http://127.0.0.1:<宿主端口>/v1`）的解析。
+*
+* ## 为什么端口不能写死
+*
+* dsh-router **自己不开端口**：`/v1/*` 是注册在**宿主** web server 上的路由
+* （见 `index.ts` 的 `ctx.webServer.register`）。所以端点地址里的端口由启动通道
+* 决定，而不是插件决定 —— `dsh web` 默认 3080，桌面端官方通道、以及配置
+* `port: 0`（让 OS 分配）时都**不是** 3080。之前 adapter 把
+* `http://localhost:3080/v1` 写死在构造参数里，于是非 3080 的宿主上 Router
+* 的每一轮对话都是 `dsh-router upstream call failed: fetch failed`（issue #9）。
+*
+* ## 为什么返回函数而不是字符串
+*
+* `webServer.port` 是**监听之后**才有值的 getter（listen 前是 `undefined`），
+* 且宿主重启/换端口后它会变。所以这里返回函数、**每次请求现算**，不在注册时
+* 算一次 —— 注册发生在启动早期，那时算只会把「拿不到端口」固化成常量。
+*
+* ## 拿不到端口时为什么抛，而不是回退 3080
+*
+* 回退等于把同一个 bug 换种写法：端口读不到时宿主的路由也没在服务，回退到 3080
+* 只会重新得到一句无从查证的 `fetch failed`。这里抛明确的话，让它出现在
+* `LlmError` 消息里（adapter 在 fetch 同一个 try 里调它），报错自带原因。
+*/
+/** 回环地址：宿主即使监听 `0.0.0.0`（LAN 模式），走 127.0.0.1 也通。 */
+const LOOPBACK_HOST = "127.0.0.1";
+/**
+* 造一个「每次调用现读宿主端口」的端点解析器。
+*
+* @param readPort 读宿主监听端口（`webServer.port`）。取不到时抛错而不是猜。
+* @param path 端点路径前缀，默认 `/v1`。
+*/
+function loopbackBaseURL(readPort, path = "/v1") {
+	return () => {
+		const port = readPort();
+		if (port === void 0) throw new Error("dsh-router: 宿主 webServer 端口未就绪（webServer.port 读不到），无法定位 /v1 端点");
+		return `http://${LOOPBACK_HOST}:${String(port)}${path}`;
+	};
+}
+//#endregion
 //#region src/host-version.ts
 /**
 * 宿主 DSH 版本探测 —— **0.1.5 / 0.1.7 兼容分叉的唯一判据来源**。
@@ -4183,6 +4921,15 @@ function apply(rawContext) {
 	const extStore = new ExtStore(stateFile);
 	ctx.provide("router.extStore", extStore);
 	const registerLoaded = (loaded) => {
+		const existing = loadedSuppliers.find((l) => l.supplier.id === loaded.supplier.id);
+		if (existing !== void 0) {
+			if (!supplierWins(loaded.source, existing.source)) {
+				log(`supplier ${loaded.supplier.id} (${loaded.source}) skipped: ${existing.source} already registered`);
+				return;
+			}
+			log(`supplier ${loaded.supplier.id}: ${existing.source} replaced by ${loaded.source}`);
+			unregisterSupplier(loaded.supplier.id);
+		}
 		loadedSuppliers.push(loaded);
 		router.add(loaded.supplier);
 		registerSupplierRoutes(loaded);
@@ -4193,22 +4940,24 @@ function apply(rawContext) {
 		for (const [sid, factory] of Object.entries(suppliers)) {
 			if (externalSupplierIds.includes(sid)) continue;
 			try {
-				const loaded = wrapModule(factory({
+				const module = factory({
 					dataDir,
 					log,
 					store,
 					credentials
-				}), {
+				});
+				const kind = factory.source === "builtin" ? "builtin" : "external";
+				const loaded = wrapModule(module, {
 					dataDir,
 					log,
 					store,
 					credentials
-				}, `service router.suppliers.${sid}`);
+				}, `service router.suppliers.${sid}`, kind);
 				registerLoaded(loaded);
 				externalSupplierIds.push(loaded.supplier.id);
-				log(`external supplier loaded: ${sid}`);
+				log(`${kind} supplier loaded: ${sid}`);
 			} catch (err) {
-				ctx.logger.warn(`[dsh-router] external supplier ${sid} load failed: ${err.message}`);
+				ctx.logger.warn(`[dsh-router] supplier ${sid} load failed: ${err.message}`);
 			}
 		}
 	};
@@ -4227,10 +4976,8 @@ function apply(rawContext) {
 	});
 	(async () => {
 		try {
-			const userDir = join(profileDirOf(ctx.baseUrl), "suppliers");
 			const { suppliers, errors } = await loadSuppliers({
-				builtinDir: join(import.meta.dirname, "suppliers"),
-				userDir,
+				userDir: join(profileDirOf(ctx.baseUrl), "suppliers"),
 				dataDir,
 				store,
 				credentials,
@@ -4312,7 +5059,8 @@ function apply(rawContext) {
 					icon: loaded?.supplier.icon,
 					apiKeyHint: loaded?.supplier.apiKeyHint,
 					capabilities: loaded ? [...loaded.capabilities] : [],
-					source: loaded?.source ?? "external"
+					source: loaded?.source ?? "external",
+					enabled: s.enabled
 				};
 			})
 		});
@@ -4568,6 +5316,7 @@ function apply(rawContext) {
 					...e.icon !== void 0 ? { icon: e.icon } : {},
 					enabled: extStore.isEnabled(e.id),
 					ready: st?.ready === true,
+					...raw.source === "builtin" ? { source: "builtin" } : {},
 					...st?.detail !== void 0 ? { detail: st.detail } : {}
 				};
 			}).filter((e) => e !== void 0)
@@ -4651,13 +5400,13 @@ function apply(rawContext) {
 			});
 			log(`Router settings section registered (${settingsNs})`);
 		});
-		disposers.push(ctx.llm.registerAdapter(["router"], new RouterAdapter("http://localhost:3080/v1", { comboModels: async () => (await router.combos()).map((c) => {
+		disposers.push(ctx.llm.registerAdapter(["router"], new RouterAdapter(loopbackBaseURL(() => ctx.webServer?.port), { comboModels: async () => (await router.combos()).map((c) => {
 			const w = router.comboContextWindow(c);
 			return {
 				id: c.name,
 				...w !== void 0 ? { contextWindow: w } : {}
 			};
-		}) }, () => ctx.get("attachments"))));
+		}) }, () => ctx.get("attachments"), void 0, (msg) => ctx.logger.warn(`[dsh-router] ${msg}`))));
 		log("llm provider (Router) + discovery + adapter registered ok");
 		(async () => {
 			for (const c of await router.combos()) for (const ref of c.models) {