dsh-router-core 0.3.12 → 0.3.14

package/lib/index.js

@@ -1,7 +1,8 @@
 import { basename, dirname, join, resolve } from "node:path";
+import Schema from "@deepseek-ai/schemastery";
 import { mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
 import { EMPTY_RESPONSE_CODE, LlmAdapter, LlmError, ReasoningEffortId, ToolCallId, attributionHeaders } from "@deepseek-ai/dsh-llm";
-import { randomBytes } from "node:crypto";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
 import { homedir } from "node:os";
@@ -9,6 +10,84 @@ import { homedir } from "node:os";
 /** Same-origin API base the client panel fetches (host half serves it). */
 const ROUTER_API_BASE = "/router/api";
 //#endregion
+//#region src/router/prefix-affinity.ts
+/**
+* 前缀指纹 —— 把一次请求的**消息前缀**压成一个短字符串，用于「同一个会话
+* 粘在同一个账号上」。
+*
+* ## 为什么要这个
+*
+* 上游 prompt cache 是 **per-account × per-conversation** 的命名空间。块轮询
+* 保证的是「单会话内连续驻留」，但多个会话被轮到同一个号时，各自十几万的大
+* 前缀会在该号的缓存里**互相驱逐**（实测 3 会话并发 → 命中 3.8%，单会话独占
+* → 82.5%，见 docs/pool-sticky-block.md §2.1）。
+*
+* 破法是让每个会话固定落到一个号：前缀指纹 → 选号。指纹相同的请求（= 同一
+* 会话的连续请求，前缀逐轮增长但开头不变）落在同一个号，各自有独立的缓存
+* 空间。
+*
+* ## 为什么按「前几条消息」而不是整个 body
+*
+* - 整个 body 每次都不一样（会话越跑越长）→ 指纹漂移 → 同一会话换号，正好
+*   是要避免的事。
+* - 请求体前 N 字节也不行：system prompt 动辄几 KB，同源会话（同一个 agent）
+*   在这 N 字节里完全一样，多个会话会撞到同一个号。
+* - 条数取 **2**（system + 首条用户消息）是刻意的：这两个槽位在会话整个
+*   生命周期里**永不变化**（新消息只往后追加），所以从第 1 个请求起指纹
+*   就稳定。取 3 条会在第一条 assistant 回复落进槽位 2 时变一次指纹 →
+*   会话开局多付一次全量重算。而「system + 首条消息逐字相同」的会话，
+*   缓存前缀本来就相同，共享一个号的缓存是收益不是冲突。
+*
+* 天花板：若某个客户端的前 3 条消息在所有会话里都逐字相同（无状态短请求），
+* 指纹会退化成一个值 → 全部压到一个号。此时退化行为 = fallback，可接受；
+* 真要区分得等 DSH 透传会话 id（不为此改契约）。
+*/
+/** 取前几条消息：system + 首条用户消息。会话里这两个槽位永不变化 → 指纹从第 1 个请求起稳定。 */
+const FP_MSGS = 2;
+/** 每条消息取前多少字符。缓存前缀的区分度集中在开头，全量哈希只增成本。 */
+const FP_CHARS = 512;
+/**
+* 消息 content 可能是字符串，也可能是多模态分片数组
+* （`[{ type: 'text', text: '...' }]`）。只取文本部分：图片是 base64，
+* 既大又不参与前缀匹配的语义（同一张图每轮都是同一串）。
+*/
+function textOf(content) {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	let s = "";
+	for (const part of content) {
+		if (typeof part === "string") {
+			s += part;
+			continue;
+		}
+		if (part !== null && typeof part === "object") {
+			const t = part.text;
+			if (typeof t === "string") s += t;
+		}
+	}
+	return s;
+}
+/**
+* 算请求的前缀指纹。
+* @param messages OpenAI 请求体的 `messages` 字段（未校验，来自外部输入）
+* @returns 指纹字符串；**空串 = 算不出来（无亲和，回退到块轮询）**
+*/
+function prefixFingerprint(messages) {
+	if (!Array.isArray(messages) || messages.length === 0) return "";
+	let buf = "";
+	const n = Math.min(messages.length, FP_MSGS);
+	for (let i = 0; i < n; i++) {
+		const m = messages[i];
+		if (m === null || typeof m !== "object") continue;
+		const { role, content } = m;
+		const text = textOf(content);
+		if (typeof role !== "string" && text === "") continue;
+		buf += `${typeof role === "string" ? role : ""}\u0000${text.slice(0, FP_CHARS)}\u0001`;
+	}
+	if (buf === "") return "";
+	return createHash("sha1").update(buf).digest("base64url").slice(0, 12);
+}
+//#endregion
 //#region src/router/account-pool.ts
 const MINUTE = 6e4;
 /**
@@ -85,6 +164,14 @@ const BLOCK_MIN = 16;
 const BLOCK_MAX = 48;
 /** 块轮询：判定「缓存无效」后的跳过时长。 */
 const BLOCK_DEMOTE_MS = 10 * MINUTE;
+/**
+* 前缀亲和：指纹 → 号 的绑定记忆上限。
+*
+* 会话指纹是无限集合（每个新会话一个），不封顶就是内存泄漏。超过了就丢掉
+* **最久没用**的那条：活跃会话的指纹每请求都在刷新，不会被误删。
+* 单号池（<= 几十个会话）绰绰有余。
+*/
+const AFFINITY_MAX = 512;
 /** 指数退避：等级 1 = BACKOFF_BASE_MS，每级翻倍，封顶 BACKOFF_MAX_MS。 */
 function backoffMs(level) {
 	return Math.min(BACKOFF_BASE_MS * 2 ** Math.max(0, level - 1), BACKOFF_MAX_MS);
@@ -99,10 +186,14 @@ var AccountPool = class {
 	/** uid → 连接级禁用 / 手动暂停。 */
 	byUid = /* @__PURE__ */ new Map();
 	rrCursor = 0;
-	/** (supplier, model) → 块轮询驻留状态。 */
+	/** (supplier, model) → 当前驻留的号（只有**无亲和**的回退路径用它）。 */
 	blocks = /* @__PURE__ */ new Map();
+	/** (supplier, model, uid) → 该号的缓存质量样本（降权判据，跨驻留累计）。 */
+	samples = /* @__PURE__ */ new Map();
 	/** (supplier, model, uid) → 缓存无效降权。 */
 	demoted = /* @__PURE__ */ new Map();
+	/** (supplier, model) → Map<前缀指纹, uid>：前缀亲和的选号记忆（LRU 封顶）。 */
+	affinity = /* @__PURE__ */ new Map();
 	constructor(supplierId = "") {
 		this.supplierId = supplierId;
 	}
@@ -169,22 +260,28 @@ var AccountPool = class {
 	/**
 	* 按策略为「某个模型」选一个健康账号。
 	*
-	* round-robin 走**块轮询**：一次轮转内连续服务若干请求，而不是每请求换号。
-	* 设计见 docs/pool-sticky-block.md。要点：
-	*  - 留守 = `计数 < N OR 命中率 < M`(OR,用户拍板):
-	*    命中率达标（缓存热了）→ 换号保均衡；计数到 N → 换号止损。
-	*    单号最多连续服务 N 次，不会因命中率低而死守到 N_max（打架场景关键）。
-	*  - 切号因子的思路：命中率是**留守**条件不是切号条件。反接会正反馈死锁
-	*    （切→cold miss→命中率 0%→触发切号→…），见文档 §3。
-	*  - `N_max` 绝对兜底：命中率永远不达标的号不能无限驻留（防死锁 + 防均衡归零）。
+	* round-robin = **前缀亲和定号 + 块统计只用来判定缓存无效**：
+	*
+	*  1. 算请求的前缀指纹（messages 前几条），查绑定表 → 命中且该号健康 → 用它。
+	*     这是第一优先：同一个会话的连续请求**永远落回同一个号**，前缀在该号的
+	*     缓存里只写一份。块轮询治不了跨会话驱逐（多会话大前缀在同一号互踩，
+	*     实测 3 会话 3.8% vs 单会话 82.5%），亲和才是根治。
+	*  2. 新指纹（或绑定的号不健康）→ 按游标挑一个号并**记下绑定**，之后就固定。
+	*     新会话用游标分发，所以不同会话天然散到不同号上（均衡）。
+	*  3. 块统计不再驱动轮转（亲和已经保证驻留，再轮转只会把会话踢出已热前缀），
+	*     只保留 `BLOCK_MAX` 次不达标 → 降权该号（缓存无效，可恢复）。
+	*
+	* 亲和失效（拿不到 messages / 指纹算不出）时**回退到块轮询**，行为与之前一致。
+	* 设计见 docs/pool-sticky-block.md §8。
 	*
 	* @param accounts 插件报告的「现在状态」（顺序即插件的自然顺序）
 	* @param poolOrder 用户在面板拖出来的顺序（核心管）
-	* @param strategy fallback 取第一个健康 / round-robin 块轮转健康号
+	* @param strategy fallback 取第一个健康 / round-robin 前缀亲和
 	* @param modelId 当前要路由的模型（决定查哪个 (model, uid) 冷却单元）
+	* @param messages 请求体的 messages（可选；给了才能算前缀指纹）
 	* @returns 选中的 uid；无健康账号返回 undefined
 	*/
-	pick(accounts, poolOrder, strategy, modelId) {
+	pick(accounts, poolOrder, strategy, modelId, messages) {
 		const now = Date.now();
 		const byUid = new Map(accounts.map((a) => [a.uid, a]));
 		const healthy = [...poolOrder.filter((uid) => byUid.has(uid)), ...accounts.map((a) => a.uid).filter((uid) => !poolOrder.includes(uid))].filter((uid) => this.healthy(uid, modelId, now));
@@ -192,24 +289,39 @@ var AccountPool = class {
 		if (strategy !== "round-robin") return healthy[0];
 		const usable = healthy.filter((uid) => !this.isDemoted(uid, modelId, now));
 		const pool = usable.length > 0 ? usable : healthy;
+		const fp = messages === void 0 ? "" : prefixFingerprint(messages);
+		if (fp !== "" && pool.includes(this.affinity.get(this.blockKey(modelId))?.get(fp) ?? "")) return this.affinity.get(this.blockKey(modelId)).get(fp);
 		const block = this.blocks.get(this.blockKey(modelId));
-		if (block !== void 0 && pool.includes(block.uid) && this.blockKeeps(block)) return block.uid;
-		const uid = pool[(block === void 0 ? this.rrCursor : Math.max(0, pool.indexOf(block.uid) + 1)) % pool.length];
+		if (fp === "" && block !== void 0 && pool.includes(block) && this.blockKeeps(modelId, block)) return block;
+		const uid = pool[(block === void 0 ? this.rrCursor : Math.max(0, pool.indexOf(block) + 1)) % pool.length];
 		this.rrCursor = (pool.indexOf(uid) + 1) % pool.length;
-		this.blocks.set(this.blockKey(modelId), {
-			uid,
-			served: 0,
-			hits: 0
-		});
+		this.blocks.set(this.blockKey(modelId), uid);
+		if (fp !== "") this.bind(modelId, fp, uid);
+		else this.samples.delete(this.key(modelId, uid));
 		return uid;
 	}
+	/** 记下「前缀指纹 → 号」的绑定（LRU：超上限丢最久未用的）。 */
+	bind(modelId, fp, uid) {
+		const k = this.blockKey(modelId);
+		let m = this.affinity.get(k);
+		if (m === void 0) {
+			m = /* @__PURE__ */ new Map();
+			this.affinity.set(k, m);
+		}
+		m.delete(fp);
+		m.set(fp, uid);
+		if (m.size > AFFINITY_MAX) {
+			const oldest = m.keys().next().value;
+			if (oldest !== void 0) m.delete(oldest);
+		}
+	}
 	/** 该号在本模型上是否被判定「缓存无效」（降权中）。 */
 	isDemoted(uid, modelId, now) {
 		const e = this.demoted.get(this.key(modelId, uid));
 		return e !== void 0 && e.until > now;
 	}
 	/**
-	* 块是否还应驻留在当前号上。
+	* 驻留是否还应留在当前号上（**只用于无亲和的回退路径**）。
 	*
 	* OR 语义（用户拍板）：`留守 = 计数 < N OR 命中率 < M`。
 	* 单一账号内部：一个号先被轮到（冷启动/热），然后
@@ -219,33 +331,39 @@ var AccountPool = class {
 	*
 	* 关键：命中率是**留守**条件不是切号执行器（反接会正反馈死锁，
 	* 见文档 §3）。换号由「命中达标 OR 份额用够」触发，都不是「命中率低」。
-	*
-	* 每个号各自守着「这个会话在自己账号上的那段前缀」，轮流热；
-	* 命中率 = 块的命中占比。单会话下每个号块都从冷到热各付一次,
-	* 收益来自块内连续驻留(缺了它就跟每请求轮询一样)。
 	*/
-	blockKeeps(block) {
-		if (block.served >= BLOCK_MAX) return false;
-		const ratio = block.served === 0 ? 0 : block.hits / block.served;
-		return block.served < BLOCK_MIN || ratio < BLOCK_HIT_RATIO;
+	blockKeeps(modelId, uid) {
+		const s = this.samples.get(this.key(modelId, uid));
+		const served = s?.served ?? 0;
+		if (served >= BLOCK_MAX) return false;
+		const ratio = served === 0 ? 0 : (s?.hits ?? 0) / served;
+		return served < BLOCK_MIN || ratio < BLOCK_HIT_RATIO;
 	}
 	/**
-	* 记录一次成功请求的缓存命中情况（块轮询的反馈信号）。
+	* 记录一次成功请求的缓存命中情况（降权判据的反馈信号）。
 	*
-	* 只有**成功**请求才计入：失败没产生缓存，计入会污染命中率并导致错切。
+	* 只有**成功**请求才计入：失败没产生缓存，计入会污染命中率并导致错降权。
+	* 统计按 (model, uid) 记，**不管这个号是不是「当前驻留」**——亲和开启后
+	* 多个会话各绑各的号交错服务，按驻留记会漏掉大部分真实反馈。
 	* @param uid 实际服务的号
 	* @param modelId 模型（块粒度）
 	* @param cachedTokens 上游报的命中 token 数；0 = 全量重算
 	*/
 	noteCache(uid, modelId, cachedTokens) {
-		const k = this.blockKey(modelId);
-		const block = this.blocks.get(k);
-		if (block === void 0 || block.uid !== uid) return;
-		block.served += 1;
-		if (cachedTokens > 0) block.hits += 1;
-		if (block.served >= BLOCK_MAX && block.hits / block.served < BLOCK_HIT_RATIO) this.demoted.set(this.key(modelId, uid), { until: Date.now() + BLOCK_DEMOTE_MS });
+		const k = this.key(modelId, uid);
+		const s = this.samples.get(k) ?? {
+			served: 0,
+			hits: 0
+		};
+		s.served += 1;
+		if (cachedTokens > 0) s.hits += 1;
+		this.samples.set(k, s);
+		if (s.served >= BLOCK_MAX && s.hits / s.served < BLOCK_HIT_RATIO) {
+			this.demoted.set(k, { until: Date.now() + BLOCK_DEMOTE_MS });
+			this.samples.delete(k);
+		}
 	}
-	/** 故障切走时作废当前块：换号后前缀归属变了，块计数不能沿用。 */
+	/** 故障切走时作废当前驻留：换号后前缀归属变了，驻留计数不能沿用。 */
 	dropBlock(modelId) {
 		this.blocks.delete(this.blockKey(modelId));
 	}
@@ -1237,6 +1355,17 @@ const TRANSIENT_SETTLE_MS = 2e3;
 function isTransient(state) {
 	return state === "transport" || state === "unavailable";
 }
+/**
+* 从请求体里取 `messages`（前缀亲和的指纹输入）。解析失败/字段缺失返回
+* undefined —— 亲和拿不到输入就自动回退到块轮询，不影响路由本身。
+*/
+function reqMessages(rawBody) {
+	try {
+		return JSON.parse(rawBody).messages;
+	} catch {
+		return;
+	}
+}
 /** 丢弃响应的假 ServerResponse（测试模型用：记录状态+内容，用于判定成败）。 */
 function sinkRes() {
 	let status = 200;
@@ -2075,9 +2204,10 @@ var Router = class {
 			}
 			return await writeChatResult(res, r, req.stream, probe, probe?.startedAt ?? 0);
 		}
+		const messages = reqMessages(req.rawBody);
 		const tried = /* @__PURE__ */ new Set();
 		for (;;) {
-			const uid = pool.pick(s.accounts().filter((a) => !tried.has(a.uid)), cfg.poolOrder, cfg.poolStrategy, req.model);
+			const uid = pool.pick(s.accounts().filter((a) => !tried.has(a.uid)), cfg.poolOrder, cfg.poolStrategy, req.model, messages);
 			if (uid === void 0) return false;
 			tried.add(uid);
 			const r = await s.chatOnce(uid, req.lv ?? "auto", req);
@@ -2169,18 +2299,31 @@ var Router = class {
 * 模型目录 = 组合（自动带出，不可改）。对话转发到本插件 /v1/chat/completions，
 * 由现有路由按组合策略命中供应商模型。
 *
-* 纯文本流：组合为文本模型，本 adapter 不处理图片附件。
+* 图文流：adapter 声明图片 modal（`inputModalities` 含 `image`），把 user 消息里的
+* `image` 块序列化成 OpenAI 标准的 `image_url` base64 part，经 /v1 原样透传给
+* 命中的上游供应商。最终能否看图取决于**命中的那个上游模型**——组合里是异构
+* 供应商，可能在网关端声明了图片能力、某条上游却只收文本（此时由上游自行拒收）。
+* 图片字节从 `ctx.attachments` 读取（读不到的按稳定占位文本降级，绝不静默丢图）。
 */
 /**
-* 把 DSH 消息序列化成 openai 兼容 wire 消息（纯文本 + tool）。
+* 把 DSH 消息序列化成 openai 兼容 wire 消息（文本 + 图片 + tool）。
 *
-* `system` 必须由调用方从 `options.system` 传进来：agent-loop 把系统提示词
-* 放在 **options.system 这个独立槽位**，不放进 messages（见 dsh-llm
-* types.d.ts 的 `system?: string` —— 注释原话 "adapters map to the
-* provider's system slot"）。不读这个槽位，模型每一轮都拿不到身份/规则/
-* 工具用法约束，且**不会报错**，只是行为悄悄降级。
+* `system` 必须由调用方从 `options.system` 传进来：one-shot 调用方把系统提示词
+* 放在 **options.system 这个独立槽位**，不放进 messages。不读这个槽位，
+* one-shot 调用方（如 compaction / session-title）的模型每一轮都拿不到身份/
+* 规则/工具用法约束，且**不会报错**，只是行为悄悄降级。
+*
+* 0.1.5 起 loop-built 请求反过来：`options.system` 为 undefined，系统提示词作为
+* **messages 里的 system-role 消息**下发（dsh-agent-loop 的 SystemProjection，
+* 可出现在任意位置以支持提示词热更新）。两条路径都必须支持 —— 与官方
+* dsh-llm-deepseek 一致（serializeRequest 前置 options.system，再按位置序列化
+* messages 里的 system 消息）。
+*
+* 图片：`image` 块被序列化成 OpenAI `content` 数组里的 `image_url` part（data URI
+* base64）。图片字节经 `resolveAttachments` 读取；读不到时回退为稳定的占位文本，
+* **绝不静默丢图**（丢图 = 模型看到一条没有图的消息却毫无提示）。
 */
-function wireMessages(options, system) {
+async function wireMessages(options, system, attachments) {
 	const out = [];
 	if (typeof system === "string" && system !== "") out.push({
 		role: "system",
@@ -2213,12 +2356,24 @@ function wireMessages(options, system) {
 			});
 			continue;
 		}
-		const text = flattenText(message.content);
 		const toolResults = message.content.filter((b) => b.type === "tool-result");
-		if (text.length > 0 || toolResults.length === 0) out.push({
-			role: "user",
-			content: text
-		});
+		if (hasImageBlock(message.content)) {
+			const parts = await contentParts(message.content, attachments, options.signal);
+			if (parts.length > 0) out.push({
+				role: "user",
+				content: parts
+			});
+			else if (toolResults.length === 0) out.push({
+				role: "user",
+				content: ""
+			});
+		} else {
+			const text = flattenText(message.content);
+			if (text.length > 0 || toolResults.length === 0) out.push({
+				role: "user",
+				content: text
+			});
+		}
 		for (const result of toolResults) out.push({
 			role: "tool",
 			tool_call_id: result.toolCallId,
@@ -2227,9 +2382,73 @@ function wireMessages(options, system) {
 	}
 	return out;
 }
-/** 组装 wire 请求体。 */
-function wireRequest(options) {
-	const messages = wireMessages(options, options.system);
+/**
+* 一块 DSH user/tool-result 内容序列化成 OpenAI content parts（text + image_url）。
+* 纯文本时返回空数组（上层走紧凑字符串路径）。图片转 base64 data URI；
+* attachments 缺失或读取失败时回退稳定占位文本（绝不静默丢图）。
+*/
+async function contentParts(blocks, attachments, signal) {
+	const parts = [];
+	for (const block of blocks) {
+		if (block.type === "text") {
+			const text = block.text ?? "";
+			if (text.length > 0) parts.push({
+				type: "text",
+				text
+			});
+			continue;
+		}
+		if (block.type === "image") {
+			const ref = block.attachment;
+			parts.push(...await imageParts(ref, attachments, signal));
+			continue;
+		}
+		if (block.type === "tool-result") parts.push(...await contentParts(block.content, attachments, signal));
+	}
+	return parts;
+}
+/** 一张图片 → 一个 OpenAI image_url part（或读不到附件时的占位文本）。 */
+async function imageParts(ref, attachments, signal) {
+	if (attachments === void 0) return [{
+		type: "text",
+		text: imagePlaceholder(ref.attachmentId)
+	}];
+	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);
+		return [{
+			type: "image_url",
+			image_url: { url: `data:${img.mediaType};base64,${bytesToBase64(img.data)}` }
+		}];
+	} catch {
+		return [{
+			type: "text",
+			text: imagePlaceholder(ref.attachmentId)
+		}];
+	}
+}
+/** Uint8Array → base64（browser + node 双环境安全，不依赖 Buffer 全局）。 */
+function bytesToBase64(bytes) {
+	let bin = "";
+	const chunk = 32768;
+	for (let i = 0; i < bytes.length; i += chunk) bin += String.fromCharCode(...bytes.subarray(i, i + chunk));
+	return btoa(bin);
+}
+/** 读不到图片字节时的稳定占位文本。 */
+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);
 	const body = {
 		model: options.model,
 		messages,
@@ -2276,6 +2495,14 @@ function applyReasoning(body, effort) {
 function flattenText(blocks) {
 	return blocks.filter((b) => b.type === "text").map((b) => b.text ?? "").join("");
 }
+/** 内容块里（含递归进 tool-result）是否存在 image 块。决定走数组 content 还是字符串。 */
+function hasImageBlock(blocks) {
+	for (const b of blocks) {
+		if (b.type === "image") return true;
+		if (b.type === "tool-result" && hasImageBlock(b.content)) return true;
+	}
+	return false;
+}
 /** openai SSE payload → DSH StreamChunk 流。导出以便单测锁死 usage 契约。 */
 /**
 * 把上游 SSE 的 `data:` 载荷流翻译成 DSH 的 StreamChunk 事件流。
@@ -2506,13 +2733,15 @@ const ROUTER_REASONING_EFFORTS = [
 		name: "Max"
 	}
 ];
-var RouterAdapter = class extends LlmAdapter {
+var RouterAdapter = class RouterAdapter extends LlmAdapter {
 	baseURL;
 	source;
-	constructor(baseURL, source) {
+	resolveAttachments;
+	constructor(baseURL, source, resolveAttachments) {
 		super();
 		this.baseURL = baseURL;
 		this.source = source;
+		this.resolveAttachments = resolveAttachments ?? (() => void 0);
 	}
 	providerInfo(provider) {
 		return {
@@ -2535,12 +2764,22 @@ var RouterAdapter = class extends LlmAdapter {
 		}
 		return out;
 	}
+	/**
+	* 声明图文：`inputModalities` 必须同时含 `text` 与 `image`。
+	* - 含 `image`：runtime/subagent 的模态门禁放行（不再抛
+	*   `MODEL_DOES_NOT_SUPPORT_IMAGES` = 界面「当前模型不支持图片」），
+	*   `projectImagesForTextModel` 也不会把图片块投影成占位文本。
+	* - 组合背后是异构供应商，**统一声明图片能力**；真正能否看图取决于命中
+	*   的某个上游模型（供应商各模型 capability 不同，网关端不能一刀切拦截）。
+	*/
+	static INPUT_MODALITIES = ["text", "image"];
 	async resolveModel(_provider, model) {
 		const found = (await this.source.comboModels()).find((m) => m.id === model || m.name === model);
 		return {
 			provider: "router",
 			id: model,
 			name: found?.name ?? found?.id ?? model,
+			inputModalities: RouterAdapter.INPUT_MODALITIES,
 			...found?.contextWindow !== void 0 ? { context: { contextWindow: found.contextWindow } } : {},
 			reasoning: {
 				efforts: ROUTER_REASONING_EFFORTS,
@@ -2549,7 +2788,7 @@ var RouterAdapter = class extends LlmAdapter {
 		};
 	}
 	async *stream(options) {
-		const body = wireRequest(options);
+		const body = await wireRequest(options, this.resolveAttachments());
 		const controller = new AbortController();
 		const onAbort = () => controller.abort();
 		options.signal?.addEventListener("abort", onAbort, { once: true });
@@ -4017,13 +4256,26 @@ function apply(rawContext) {
 			disposers.push(ctx.llm.registerModelDiscovery(LLM_NS, async () => {
 				return (await router.combos()).map((c) => ({ id: c.name }));
 			}));
+			const routerSettingsSchema = Schema.object({});
+			ctx.inject(["settings"], (sctx) => {
+				const settings = sctx.settings;
+				if (settings === void 0) {
+					log("settings service absent — skip Router settings-section registration");
+					return;
+				}
+				settings.installSection(rawContext, LLM_NS, routerSettingsSchema, {}, {
+					setSource: () => {},
+					onChange: () => {}
+				});
+				log(`Router settings section registered (${LLM_NS})`);
+			});
 			disposers.push(ctx.llm.registerAdapter(["router"], new RouterAdapter("http://localhost:3080/v1", { comboModels: async () => (await router.combos()).map((c) => {
 				const w = router.comboContextWindow(c);
 				return {
 					id: c.name,
 					...w !== void 0 ? { contextWindow: w } : {}
 				};
-			}) })));
+			}) }, () => ctx.get("attachments"))));
 			log("llm provider (Router) + discovery + adapter registered ok");
 			(async () => {
 				for (const c of await router.combos()) for (const ref of c.models) {
@@ -4051,11 +4303,20 @@ function apply(rawContext) {
 		} catch (err) {
 			registeredProviders = `error: ${err.message}`;
 		}
+		let settingsNamespaces = "n/a";
+		try {
+			const settings = ctx.get("settings");
+			settingsNamespaces = settings?.describe === void 0 ? "no settings service" : settings.describe({ redactSecrets: true }).map((d) => d.ns);
+		} catch (err) {
+			settingsNamespaces = `error: ${err.message}`;
+		}
 		writeJson(res, 200, {
 			ok: true,
 			llmAvailable: ctx.llm !== void 0,
 			directory,
-			registeredProviders
+			registeredProviders,
+			settingsNamespaces,
+			routerNamespaceRegistered: Array.isArray(settingsNamespaces) && settingsNamespaces.includes("llm-dsh-router")
 		});
 	});
 	ctx.effect(() => () => {

package/lib/types/llm/adapter.d.ts

@@ -4,9 +4,34 @@
  * 模型目录 = 组合（自动带出，不可改）。对话转发到本插件 /v1/chat/completions，
  * 由现有路由按组合策略命中供应商模型。
  *
- * 纯文本流：组合为文本模型，本 adapter 不处理图片附件。
+ * 图文流：adapter 声明图片 modal（`inputModalities` 含 `image`），把 user 消息里的
+ * `image` 块序列化成 OpenAI 标准的 `image_url` base64 part，经 /v1 原样透传给
+ * 命中的上游供应商。最终能否看图取决于**命中的那个上游模型**——组合里是异构
+ * 供应商，可能在网关端声明了图片能力、某条上游却只收文本（此时由上游自行拒收）。
+ * 图片字节从 `ctx.attachments` 读取（读不到的按稳定占位文本降级，绝不静默丢图）。
  */
 import { LlmAdapter, type GenerateOptions, type LlmModelInfo, type LlmResolvedModelInfo, type StreamChunk } from '@deepseek-ai/dsh-llm';
+/**
+ * dsh-attachment 的最小本地切面：adapter 只依赖「读一张图片的请求版本」
+ * 这一行为，不引入对 dsh-attachment 包编译期/运行期的依赖（它是宿主注入的
+ * devDependency）。本地声明与原包 `AttachmentStore.readImageRequest` 形状一致，
+ * 宿主注入真实 store 时天然满足。
+ */
+export interface RouterAttachmentStore {
+    readImageRequest(ref: {
+        attachmentId: string;
+        mediaType: string;
+        bytes: number;
+        width: number;
+        height: number;
+    }, policy: {
+        maxPixels: number;
+        maxBytes: number;
+    }, signal?: AbortSignal): Promise<{
+        mediaType: string;
+        data: Uint8Array;
+    }>;
+}
 /** 模型目录来源：组合。 */
 export interface RouterAdapterSource {
     /**
@@ -32,12 +57,22 @@ export declare function translateSse(payloads: AsyncIterable<string> | Iterable<
 export declare class RouterAdapter extends LlmAdapter {
     private readonly baseURL;
     private readonly source;
-    constructor(baseURL: string, source: RouterAdapterSource);
+    private readonly resolveAttachments;
+    constructor(baseURL: string, source: RouterAdapterSource, resolveAttachments?: () => RouterAttachmentStore | undefined);
     providerInfo(provider: string): {
         id: string;
         name: string;
     };
     listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
+    /**
+     * 声明图文：`inputModalities` 必须同时含 `text` 与 `image`。
+     * - 含 `image`：runtime/subagent 的模态门禁放行（不再抛
+     *   `MODEL_DOES_NOT_SUPPORT_IMAGES` = 界面「当前模型不支持图片」），
+     *   `projectImagesForTextModel` 也不会把图片块投影成占位文本。
+     * - 组合背后是异构供应商，**统一声明图片能力**；真正能否看图取决于命中
+     *   的某个上游模型（供应商各模型 capability 不同，网关端不能一刀切拦截）。
+     */
+    private static readonly INPUT_MODALITIES;
     resolveModel(_provider: string, model: string): Promise<LlmResolvedModelInfo>;
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
 }