dsh-router-core 0.3.11 → 0.3.13

package/lib/index.js

@@ -1,7 +1,7 @@
 import { basename, dirname, join, resolve } from "node:path";
 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 +9,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;
 /**
@@ -77,6 +155,22 @@ const TRANSIENT_COOLDOWN_MS = 3e4;
 const BACKOFF_BASE_MS = 2e3;
 const BACKOFF_MAX_MS = 5 * MINUTE;
 const BACKOFF_MAX_LEVEL = 15;
+/** 块轮询：命中率达标就放行（`留守 = 计数<N OR 命中率<M`）。见 stickyBlock 说明。 */
+const BLOCK_HIT_RATIO = .85;
+/** 块轮询：最短驻留。新接到这个号的最少连续服务次数（防冷启动误切）。 */
+const BLOCK_MIN = 16;
+/** 块轮询：绝对兜底。轮次过多(max)无论命中率如何都让位，防死守 + 保均衡下限。 */
+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);
@@ -91,6 +185,14 @@ var AccountPool = class {
 	/** uid → 连接级禁用 / 手动暂停。 */
 	byUid = /* @__PURE__ */ new Map();
 	rrCursor = 0;
+	/** (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;
 	}
@@ -156,22 +258,118 @@ var AccountPool = class {
 	}
 	/**
 	* 按策略为「某个模型」选一个健康账号。
+	*
+	* 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));
 		if (healthy.length === 0) return void 0;
 		if (strategy !== "round-robin") return healthy[0];
-		const uid = healthy[this.rrCursor % healthy.length];
-		this.rrCursor = (this.rrCursor + 1) % healthy.length;
+		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 (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);
+		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`。
+	* 单一账号内部：一个号先被轮到（冷启动/热），然后
+	*   - 命中率**爬上去**（>= M，缓存热了）→ 让位，轮到下一个号（均衡）
+	*   - 命中率**没上去**（冷启动/短块）→ 留守，继续热（不急着跳）
+	*   - 轮次**实在太多**（计数 >= N_max）→ 也换（防死守 + 保均衡下限）
+	*
+	* 关键：命中率是**留守**条件不是切号执行器（反接会正反馈死锁，
+	* 见文档 §3）。换号由「命中达标 OR 份额用够」触发，都不是「命中率低」。
+	*/
+	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.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));
+	}
+	/** 块状态键：与冷却同粒度 (supplier, model)，不含 uid。 */
+	blockKey(modelId) {
+		return `${this.supplierId}${SEP}${modelId}`;
+	}
 	/** 记录一次失败：按状态处置（冷却/禁用/退避），落在「(模型, 连接)」这个冷却单元上。 */
 	noteFailure(uid, modelId, state, message) {
 		const rule = RULES[state];
@@ -1156,6 +1354,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;
@@ -1867,6 +2076,7 @@ var Router = class {
 				ok,
 				durationMs: Date.now() - probe.startedAt,
 				ttfbMs: probe.ttfbMs,
+				...ok && probe.uid !== "" ? { uid: probe.uid } : {},
 				...error === void 0 ? {} : { error }
 			}, usage);
 		};
@@ -1993,9 +2203,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);
@@ -2005,6 +2216,7 @@ var Router = class {
 					return false;
 				}
 				pool.noteFailure(uid, req.model, r.state, r.message);
+				pool.dropBlock(req.model);
 				if (trace !== void 0) {
 					trace.attempts += 1;
 					trace.lastState = r.state;
@@ -2019,7 +2231,10 @@ 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)) return true;
+			if (await writeChatResult(res, r, req.stream, probe, probe?.startedAt ?? 0)) {
+				pool.noteCache(uid, req.model, probe?.tokens?.cachedTokens ?? 0);
+				return true;
+			}
 			pool.noteFailure(uid, req.model, "transport", "stream failed before first byte");
 			if (trace !== void 0) {
 				trace.attempts += 1;
@@ -2088,11 +2303,16 @@ var Router = class {
 /**
 * 把 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 消息）。
 */
 function wireMessages(options, system) {
 	const out = [];
@@ -2420,7 +2640,7 @@ const ROUTER_REASONING_EFFORTS = [
 		name: "Max"
 	}
 ];
-var RouterAdapter = class extends LlmAdapter {
+var RouterAdapter = class RouterAdapter extends LlmAdapter {
 	baseURL;
 	source;
 	constructor(baseURL, source) {
@@ -2449,12 +2669,22 @@ var RouterAdapter = class extends LlmAdapter {
 		}
 		return out;
 	}
+	/**
+	* 只收文本。`resolveModel` 声明 `inputModalities: ['text']` 是**必须**的：
+	* 0.1.5 的 runtime 只在 `inputModalities` 存在且不含 `image` 时才把 image 块
+	* 投影成占位文本（见 dsh-llm adapterStream 的 projectImagesForTextModel）。
+	* 不声明 = "unknown" = 不投影，而 wireMessages 只读 text 块 → 图片**静默
+	* 丢失**，模型看到一条没有图片的用户消息却毫无提示。声明后由 runtime 统一
+	* 投影，我们仍只处理文本。
+	*/
+	static INPUT_MODALITIES = ["text"];
 	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,
@@ -3328,6 +3558,116 @@ function dshHome() {
 	return resolve(value);
 }
 //#endregion
+//#region src/ext/store.ts
+/**
+* 扩展存储 —— **开关状态与插件数据都归核心持久化**,插件不自己 file IO。
+*
+* 落盘 `<dataDir>/ext.json`,按扩展器 id 存:
+*   `{ "rtk": { "enabled": true, "data": { ...插件自己的东西... } } }`
+*
+* 为什么归核心:跟 `supplier-config.json` 一个道理——开关是用户对**核心面板**的操作,
+* 不该由扩展插件各自决定存哪、怎么存(否则每个插件长一份互相不一致的实现,核心也无
+* 从统一裁决「能不能开」)。插件变薄:只报自己是否可用(`ready`)+ 做事。
+*
+* `data` 槽是给插件的通用抽屉(2026-09 加):插件不再为了存一点状态而自己开数据目录,
+* 统一经 `router.extStore` service 读写,落盘位置仍由核心锚定(不跟 cwd 跑)。
+*
+* 写法与核心其他存储一致:先写 `.tmp` 再 `rename` 原子覆盖(避免写一半崩掉留坏文件),
+* 权限 600;持久化失败不阻断。
+*/
+/** 扩展开关 + 插件数据存储。 */
+var ExtStore = class {
+	fp = "";
+	byId = {};
+	constructor(stateFile) {
+		this.fp = stateFile ? join(dirname(stateFile), "ext.json") : "";
+		this.load();
+		this.migrateLegacy();
+	}
+	migrateLegacy() {
+		if (this.fp === "") return;
+		if (Object.keys(this.byId).length > 0) return;
+		const legacy = join(dirname(this.fp), "enhance.json");
+		let enabled = false;
+		try {
+			enabled = JSON.parse(readFileSync(legacy, "utf8")).enabled === true;
+		} catch {
+			return;
+		}
+		if (!enabled) return;
+		this.byId.rtk = {
+			enabled: true,
+			data: void 0
+		};
+		this.save();
+	}
+	load() {
+		if (this.fp === "") return;
+		let raw;
+		try {
+			raw = readFileSync(this.fp, "utf8");
+		} catch {
+			return;
+		}
+		try {
+			const f = JSON.parse(raw);
+			for (const [id, v] of Object.entries(f)) {
+				if (id === "" || v === null || typeof v !== "object") continue;
+				if (typeof v?.enabled !== "boolean") continue;
+				this.byId[id] = {
+					enabled: v.enabled,
+					data: v.data
+				};
+			}
+		} catch {}
+	}
+	save() {
+		if (this.fp === "") return;
+		try {
+			const dir = dirname(this.fp);
+			if (dir !== "" && dir !== ".") mkdirSync(dir, { recursive: true });
+			const out = {};
+			for (const [id, e] of Object.entries(this.byId)) out[id] = e.data === void 0 ? { enabled: e.enabled } : {
+				enabled: e.enabled,
+				data: e.data
+			};
+			const raw = JSON.stringify(out, null, 2);
+			const tmp = this.fp + ".tmp";
+			writeFileSync(tmp, raw, { mode: 384 });
+			renameSync(tmp, this.fp);
+		} catch {}
+	}
+	/** 是否开启(未记录过 = 默认关)。 */
+	isEnabled(id) {
+		return this.byId[id]?.enabled === true;
+	}
+	setEnabled(id, enabled) {
+		if (id === "") return;
+		const cur = this.byId[id];
+		if (cur?.enabled === enabled) return;
+		this.byId[id] = {
+			enabled,
+			data: cur?.data
+		};
+		this.save();
+	}
+	/** 读插件自己存的数据块(没存过 = undefined)。 */
+	readData(id) {
+		if (id === "") return void 0;
+		return this.byId[id]?.data;
+	}
+	/** 写插件自己的数据块(覆盖;与 enabled 同一文件落盘)。 */
+	writeData(id, value) {
+		if (id === "") return;
+		const cur = this.byId[id];
+		this.byId[id] = {
+			enabled: cur?.enabled === true,
+			data: value
+		};
+		this.save();
+	}
+};
+//#endregion
 //#region src/index.ts
 /**
 * Plugin identity for cordis.yml rows — 必须与 package.json 的 name 一致。
@@ -3401,6 +3741,10 @@ function apply(rawContext) {
 		log(`supplier unregistered: ${id}`);
 	};
 	ctx.provide("router.suppliers", {});
+	const exts = {};
+	ctx.provide("router.ext", exts);
+	const extStore = new ExtStore(stateFile);
+	ctx.provide("router.extStore", extStore);
 	const registerLoaded = (loaded) => {
 		loadedSuppliers.push(loaded);
 		router.add(loaded.supplier);
@@ -3703,6 +4047,62 @@ function apply(rawContext) {
 			requireApiKey: keys.requireApiKey
 		});
 	});
+	route(`${ROUTER_API_BASE}/ext`, async (req, res) => {
+		if (req.method === "PATCH") {
+			let body;
+			try {
+				body = JSON.parse(await readBody(req, 65536));
+			} catch {
+				writeJson(res, 400, {
+					ok: false,
+					error: "invalid JSON body"
+				});
+				return;
+			}
+			const ext = typeof body.id === "string" ? exts[body.id] : void 0;
+			if (!ext) {
+				writeJson(res, 404, {
+					ok: false,
+					error: "extension not found"
+				});
+				return;
+			}
+			if (typeof body.enabled !== "boolean") {
+				writeJson(res, 400, {
+					ok: false,
+					error: "enabled must be a boolean"
+				});
+				return;
+			}
+			if (body.enabled && typeof ext.getState === "function") {
+				const st = ext.getState();
+				if (st?.ready !== true) {
+					writeJson(res, 409, {
+						ok: false,
+						error: st?.detail ?? "extension not ready"
+					});
+					return;
+				}
+			}
+			extStore.setEnabled(ext.id, body.enabled);
+		}
+		writeJson(res, 200, {
+			ok: true,
+			enhancers: Object.values(exts).map((raw) => {
+				const e = raw;
+				if (!e || typeof e.id !== "string" || e.id === "") return void 0;
+				const st = typeof e.getState === "function" ? e.getState() : { ready: false };
+				return {
+					id: e.id,
+					name: e.name ?? e.id,
+					...e.description !== void 0 ? { description: e.description } : {},
+					enabled: extStore.isEnabled(e.id),
+					ready: st?.ready === true,
+					...st?.detail !== void 0 ? { detail: st.detail } : {}
+				};
+			}).filter((e) => e !== void 0)
+		});
+	});
 	/** 解析并校验周期参数（不接受任意字符串）。 */
 	const periodOf = (raw) => {
 		return raw === "24h" || raw === "7d" || raw === "30d" ? raw : "today";
@@ -3803,6 +4203,9 @@ function apply(rawContext) {
 		});
 	});
 	ctx.effect(() => () => {
+		for (const raw of Object.values(exts)) try {
+			raw?.dispose?.();
+		} catch {}
 		for (const dispose of disposers.splice(0)) dispose();
 		router.dispose();
 	}, "dsh-router: teardown");

package/lib/types/ext/contract.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 扩展 (Ext) 通用契约 —— dsh-router 的「扩展插件」扩展点（不是供应商）。
+ *
+ * 分工（2026-09 重构：核心只做管理，不做拦截）：
+ *   - **dsh-router 核心 = 管理面**：持有 `router.ext` 注册表（发现）、渲染面板与
+ *     `/router/api/ext`（展示）、代存开关与插件数据（`router.extStore` →
+ *     `<dataDir>/ext.json`）。核心**不挂 `tools/execute`、不裁决、不改写**。
+ *   - **扩展插件 = 执行面**：自己挂监听、自己问 `isEnabled`、自己按 ready 裁决、
+ *     自己短路执行。怎么改一条命令是插件的**私事**，不在本契约里。
+ *
+ * 为什么把拦截从核心挪走：
+ *   `tools/execute` 是任何插件都能自己挂的 around-dispatch waterfall（插件 ctx 不在
+ *   agent scope 下就能收到全部派发）。核心代挂只在一个消费者（rtk）时是纯亏损：为留
+ *   40 行委派逻辑，付了共享表 + inject 广播 + 契约两处同步的代价。核心归位成管理面
+ *   后，扩展插件与 dsh-router 只在**注册表 + 存储**两处耦合。
+ *
+ * ponytail: 天花板 —— 核心代挂原本顺带解决「多个扩展插件各自挂监听会互相踩 / 顺序
+ *   不可控」。这个保护现在没了；目前只有 rtk 一家消费，无所谓。**第二家 ext 出现时
+ *   要重新收敛顺序**（升级路径：核心暴露一个按顺序委派的共享工具方法，而不是收回拦截）。
+ *
+ * 契约要点：
+ *   - 扩展器只有**声明**（id / name / description）+ `getState()`；核心拿这些渲染面板。
+ *   - `getState()` 只报**运行时事实**（ready 是否可用、detail 说明），不报开关。
+ *   - **开关与数据归核心持久化**（`router.extStore` → `<dataDir>/ext.json`），插件不自己
+ *     file IO —— 落盘位置由核心锚定（不跟 cwd 跑），读写经核心，插件无状态。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** 扩展器唯一 id（注册键）。 */
+export type ExtId = string;
+/**
+ * 扩展器当前状态（**运行时事实**，由插件现算，不持久化）。
+ *
+ * 注意：`enabled` 不在这里 —— 开关状态归核心持久化（`<dataDir>/ext.json`），
+ * 插件只负责做事 + 报自己是否可用。核心把两者合并后再给面板用。
+ */
+export interface ExtState {
+    /** 运行时是否就绪（如 RTK 二进制是否可用）；false 时即使开启也不生效。 */
+    ready: boolean;
+    /** 不就绪时的一句话说明（如「本机未装 rtk」），面板红字显示。 */
+    detail?: string;
+}
+/**
+ * 注册到 `router.ext` 表的扩展器实现。核心（面板/API）只认这几个成员，
+ * 插件可以携带更多内部状态。
+ */
+export interface RouterExt {
+    /** 扩展器 id，也是 `router.ext` 表里的注册键。 */
+    readonly id: ExtId;
+    /** 面板显示名（如「RTK」）。 */
+    readonly name: string;
+    /** 面板副标题说明。 */
+    readonly description?: string;
+    /** 当前运行时状态（ready + 不就绪时的说明）。 */
+    getState(): ExtState;
+    /** 卸载清理（表删除时由 dsh-router 调用，可选）。 */
+    dispose?(): void;
+}
+/** 面板/API 用的一条扩展器信息 = 核心存的开关 + 插件报的运行时事实。 */
+export interface ExtInfo {
+    id: string;
+    name: string;
+    description?: string;
+    /** 核心持久化的开关（默认关）。 */
+    enabled: boolean;
+    /** 插件报的运行时就绪状态。 */
+    ready: boolean;
+    /** 不就绪时的说明（面板红字）。 */
+    detail?: string;
+}
+/** `router.ext` 共享聚合表：`{ [extId]: RouterExt }`（同一 live 对象可追加）。 */
+export interface RouterExtService {
+    [extId: string]: RouterExt;
+}
+/**
+ * 扩展的存储面（核心 provide，插件 inject）。
+ *
+ * 插件**不自己 file IO**：落盘位置由核心用 `dataDirOf(ctx.baseUrl)` 锚定（不跟
+ * process.cwd() 跑），读写都经核心，同一文件、同一次原子写。
+ *
+ * 落盘形状：`<dataDir>/ext.json` = `{ "<id>": { "enabled": boolean, "data": unknown } }`
+ */
+export interface ExtStoreService {
+    /** 是否开启（未记录过 = 默认关）。 */
+    isEnabled(id: string): boolean;
+    /** 置开关（面板/API 调）。 */
+    setEnabled(id: string, enabled: boolean): void;
+    /** 读插件自己的数据块（没有 = undefined）。 */
+    readData<T = unknown>(id: string): T | undefined;
+    /** 写插件自己的数据块（覆盖；与 enabled 同文件原子落盘）。 */
+    writeData(id: string, value: unknown): void;
+}
+/** 读取当前 router.ext 表（同一 live 对象，可追加）——扩展插件用它注册自己。 */
+export declare function currentExts(ctx: Context): RouterExtService | undefined;
+/** 读取扩展存储服务——扩展插件用它读开关、读写自己存的数据。 */
+export declare function currentExtStore(ctx: Context): ExtStoreService | undefined;

package/lib/types/ext/store.d.ts

@@ -0,0 +1,16 @@
+/** 扩展开关 + 插件数据存储。 */
+export declare class ExtStore {
+    private fp;
+    private byId;
+    constructor(stateFile: string);
+    private migrateLegacy;
+    private load;
+    private save;
+    /** 是否开启(未记录过 = 默认关)。 */
+    isEnabled(id: string): boolean;
+    setEnabled(id: string, enabled: boolean): void;
+    /** 读插件自己存的数据块(没存过 = undefined)。 */
+    readData<T = unknown>(id: string): T | undefined;
+    /** 写插件自己的数据块(覆盖;与 enabled 同一文件落盘)。 */
+    writeData(id: string, value: unknown): void;
+}