dsh-router-core 0.4.2 → 0.4.3

package/lib/index.js

@@ -2687,11 +2687,10 @@ function projectImageDimensions(width, height, maxPixels) {
 * base64）。图片字节经 `resolveAttachments` 读取；读不到时回退为稳定的占位文本，
 * **绝不静默丢图**（丢图 = 模型看到一条没有图的消息却毫无提示）。
 *
-* 工具结果双模型兼容：0.1.5/0.1.6 里 tool result 是 user 消息里的 'tool-result' 块
-* （旧路径）；0.1.7+ 改成了独立 role:'tool' 消息、toolCallId 挂消息级（新分支）。
-* 两者在 wire 上统一序列化为 role:'tool'，产物一致。见主循环里的 role==='tool' 分支。
+* 工具结果只有一种形态：独立 `role:'tool'` 消息、toolCallId 挂消息级，wire 上原样
+* 发 `role:'tool'`。见主循环里的 `role === 'tool'` 分支。
 */
-/** tool-result 里图片挂到 user 消息时用的说明文字（与官方适配器一致）。 */
+/** tool 消息里的图片挂到 user 消息时用的说明文字（与官方适配器一致）。 */
 const TOOL_RESULT_IMAGE_TEXT = "Tool result images";
 /**
 * 流空闲超时：上游连上后这么久没吐**任何**字节就判失败（抛 TIMEOUT，可重试）。
@@ -2706,7 +2705,7 @@ const STREAM_IDLE_TIMEOUT_MS = 3e5;
 async function wireMessages(options, system, attachments, log) {
 	const out = [];
 	/**
-	* 攒着「tool-result 里带出来的图片」，等这一串 tool 消息**发完**再合并成一条
+	* 攒着「tool 消息里带出来的图片」，等这一串 tool 消息**发完**再合并成一条
 	* user 消息补在后面。
 	*
 	* 为什么必须跨消息攒、而不是各消息各发一条：harness 把**每个 tool 结果放
@@ -2774,26 +2773,12 @@ async function wireMessages(options, system, attachments, log) {
 			pendingToolImages.push(...imageParts);
 			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, log);
-		if (ownParts.length > 0 || toolResults.length === 0) {
-			flushToolImages();
-			out.push({
-				role: "user",
-				content: compactUserContent(ownParts)
-			});
-		}
-		for (const result of toolResults) {
-			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({
-				role: "tool",
-				tool_call_id: result.toolCallId,
-				content: text
-			});
-			pendingToolImages.push(...imageParts);
-		}
+		const userParts = await contentParts(message.content, attachments, options.signal, log);
+		flushToolImages();
+		out.push({
+			role: "user",
+			content: compactUserContent(userParts)
+		});
 	}
 	flushToolImages();
 	return out;
@@ -2811,7 +2796,7 @@ function compactUserContent(parts) {
 	return texts.join("");
 }
 /**
-* 一块 DSH user/tool-result 内容序列化成 OpenAI content parts（text + image_url）。
+* 一条 DSH 消息的内容块序列化成 OpenAI content parts（text + image_url）。
 * 纯文本时返回空数组（上层走紧凑字符串路径）。图片转 base64 data URI；
 * attachments 缺失或读取失败时回退稳定占位文本（绝不静默丢图）。
 */
@@ -2831,7 +2816,6 @@ async function contentParts(blocks, attachments, signal, log) {
 			parts.push(...await imageParts(ref, attachments, signal, log));
 			continue;
 		}
-		if (block.type === "tool-result") parts.push(...await contentParts(block.content, attachments, signal, log));
 	}
 	return parts;
 }
@@ -4614,37 +4598,46 @@ function loopbackBaseURL(readPort, path = "/v1") {
 //#endregion
 //#region src/host-version.ts
 /**
-* 宿主 DSH 版本探测 —— **0.1.5 / 0.1.7 兼容分叉的唯一判据来源**。
+* 宿主 DSH 版本探测 —— 现在只剩两件事：**报版本**（日志 + `/router/api/health`）与
+* **守版本地板**。
+*
+* ## 为什么不再有兼容分叉
 *
-* 原先三处兼容都靠「能力检测」（看方法/属性在不在），语义上是同一个问题
-* ——「这是 0.1.7 还是更老」——却各检各的、还容易误判（插件自己 node_modules
-* 里的依赖版本与宿主实际加载的版本并不一致：实测插件解析到 schemastery 3.18.4，
-* profile 里却是 3.18.3、全局是 3.18.2）。所以统一改成**读宿主版本号**判定：
+* 原来这里有三处 `>= 0.1.7` 的分叉（设置卡片注册路径、「最近命中」徽章座位、adapter
+* 的工具结果消息形态），彼此独立判断、还容易误判。本插件现已按 **0.2.0 单面**编写，
+* 三处的旧分支全部删除：
 *
-*   1. 「最近命中」徽章：composer.dock 在 0.1.5 渲染位置不对 → >= 0.1.7 才挂。
-*   2. 设置命名空间：0.1.5 用 `settings.installSection` 注册；0.1.7 改由导出的
-*      Config 驱动（无此方法）→ 按版本走对应注册路径。
-*   3. adapter 的 tool-result 消息形态：0.1.5/0.1.6 = user 里的 'tool-result'
-*      块；0.1.7+ = 独立 role:'tool' 消息。
+*   1. 设置卡片：0.1.5 走 `settings.installSection`，0.1.7+ 走导出的 volatile Config。
+*      0.2.0 只有后者 → installSection 分支删除。
+*   2. 「最近命中」徽章：0.1.5 渲染在 InputBar 之后的独立块（位置不对），0.1.7+ 才在
+*      composer 底部操作行。0.2.0 起无条件挂载，不再问支持位。
+*   3. adapter 工具结果形态：旧的「user 内嵌 tool-result 块」0.1.7 起退役；0.2.0 的
+*      v3→v4 会话迁移还主动拒绝该包装，所以它到不了 adapter → 分支删除。
+*
+* ## 为什么仍要读版本
+*
+* 因为**跑在老宿主上必须出声**。删掉分叉不等于「老宿主也能跑」：0.1.x 上本插件会
+* 静默走错路径（卡片不出、徽章错位、工具结果丢失），而用户看到的现象与「插件坏了」
+* 无法区分。所以这里只保留一个判据 `isHostSupported`（>= 0.2.0），仅用于 apply 时
+* 打一条醒目的警告 —— 不是兼容，是可诊断。
 *
 * 读法：宿主把 profile 目录挂在 `ctx.baseUrl`（见 data-dir.ts）。本插件跑在宿主
 * 进程内，`require.resolve('@deepseek-ai/dsh/package.json', { paths: [profile] })`
-* 会沿 profile 的 node_modules 向上解析到全局安装根（实测命中 bun 全局目录）。
-* 拿不到就回落直接拼路径，再不行就返回 undefined（按「不支持/老版本」处理，不抛）。
+* 会沿 profile 的 node_modules 向上解析到全局安装根。拿不到就回落直接拼路径，再不行
+* 返回 undefined（按「无法确认」处理，不抛）。
 *
-* 注意：**只能在 `apply(ctx)` 里用**（那时才有 baseUrl）。模块顶层（如 Config 导出）
-* 解析到的是插件自己的依赖，不能代表宿主——那处保留能力检测，见 index.ts 注释。
+* 注意：**只能在 `apply(ctx)` 里用**（那时才有 baseUrl）。模块顶层解析到的是插件自己
+* 的依赖，不能代表宿主。
 */
-/** 各兼容分叉的版本门槛。 */
-/** composer.dock 徽章 / 独立 role:'tool' 消息形态：0.1.7 起。 */
-const V0_1_7 = [
+/** 版本地板：低于此版本的宿主本插件不再兼容（0.1.5/0.1.6/0.1.7 全部落此下）。 */
+const V0_2_0 = [
 	0,
-	1,
-	7
+	2,
+	0
 ];
 /**
 * 解析并比较 semver（只取前导数字段，预发布标识忽略）。
-* `0.1.7-alpha.2` → [0,1,7]，`0.1.5-rc.3` → [0,1,5]。
+* `0.2.0-rc.1` → [0,2,0]，`0.1.7-alpha.2` → [0,1,7]。
 * 返回负数/0/正数，语义同 `<`/`==`/`>`。
 */
 function compareVersion(a, b) {
@@ -4655,7 +4648,7 @@ function compareVersion(a, b) {
 	}
 	return 0;
 }
-/** `0.1.7-alpha.2` → [0,1,7]；解析失败返回 null。 */
+/** `0.2.0-rc.1` → [0,2,0]；解析失败返回 null。 */
 function parseVersion(raw) {
 	const m = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(raw.trim());
 	if (m === null) return null;
@@ -4668,7 +4661,7 @@ function parseVersion(raw) {
 /**
 * 探测 profile 里安装的 DSH 宿主版本。
 * @param baseUrl 宿主注入的 profile 锚点（`ctx.baseUrl`）
-* @returns 形如 `0.1.7-alpha.2`；读不到返回 undefined（调用方按「不支持」处理）
+* @returns 形如 `0.2.0-rc.1`；读不到返回 undefined
 */
 function detectHostVersion(baseUrl) {
 	const profile = profileDirOf(baseUrl);
@@ -4682,26 +4675,19 @@ function detectHostVersion(baseUrl) {
 		if (typeof parsed.version === "string" && parsed.version !== "") return parsed.version;
 	} catch {}
 }
-/** 宿主版本是否 >= 门槛。读不到版本 → false（按老版本处理）。 */
-function atLeast(baseUrl, min) {
+/**
+* 宿主是否在本插件支持的地板之上（>= 0.2.0）。
+*
+* **只用于报警，不用于分流** —— 低于地板时插件照常加载，但要在日志里说清「这台宿主
+* 不再兼容、会出现什么症状」，把静默的错变成可查的错。读不到版本 → false（当作
+* 「无法确认」，同样值得说一句）。
+*/
+function isHostSupported(baseUrl) {
 	const v = detectHostVersion(baseUrl);
 	if (v === void 0) return false;
 	const parsed = parseVersion(v);
 	if (parsed === null) return false;
-	return compareVersion(parsed, min) >= 0;
-}
-/**
-* 宿主是否 >= 0.1.7。三处兼容分叉共用这一个判据：
-*   - 「最近命中」徽章（composer.dock 位置正确）
-*   - 设置命名空间（Config 驱动而非 installSection）
-*   - adapter 的独立 role:'tool' 消息形态
-*/
-function isHost017Plus(baseUrl) {
-	return atLeast(baseUrl, V0_1_7);
-}
-/** 「最近命中」徽章是否可用（= 宿主 >= 0.1.7）。 */
-function supportsLastHitDock(baseUrl) {
-	return isHost017Plus(baseUrl);
+	return compareVersion(parsed, V0_2_0) >= 0;
 }
 //#endregion
 //#region src/ext/store.ts
@@ -4823,26 +4809,23 @@ const name = "dsh-router-core";
 /** Services required before mounting: the webserver (routes) + llm (设置-模型). */
 const inject = ["webServer", "llm"];
 /**
-* `Config` 导出：让 Router 卡片进 0.1.7 的设置镜像。
+* `Config` 导出：让 Router 卡片进设置-模型的镜像（0.2.0 的收录链是「插件导出的
+* Config + 配置树行 id」）。
 *
-* **这处刻意保留能力检测，不用宿主版本号** —— 与另两处兼容点（installSection /
-* adapter 消息形态）不同。原因（已实测）：这是**模块顶层导出**，loader 一 import
-* 就求值；而 schemastery 是本插件的**普通依赖**（`^3.18.4`，见 package.json），
-* 解析到的是**插件自己 node_modules 里那一份**，跟宿主实际加载的版本无关
-* （实测：插件解析到 3.18.4，而 profile 里是 3.18.3、全局是 3.18.2）。既然这里
-* 拿不到宿主版本，就只剩「这份 Schema 实例到底有没有 `.volatile`」这个真问题 ——
-* 能力检测恰好就是**对**的判据。
+* **这处保留能力检测，不看宿主版本号** —— 因为它是**模块顶层导出**，loader 一 import
+* 就求值，那时还没有 `ctx.baseUrl`；而 schemastery 是本插件的**普通依赖**，解析到的
+* 是插件自己 node_modules 里那一份，跟宿主实际加载的版本无关。既然这里拿不到宿主
+* 版本，就只剩「这份 Schema 实例到底有没有 `.volatile`」这个真问题 —— 能力检测
+* 恰好就是**对**的判据。
 *
-* 定位说明（非兼容分叉）：`.volatile()` 是 schemastery 3.18.4 才有的原型方法；
-* 老版本上直写 `Schema.object({}).volatile()` 会 `.volatile` 为 undefined →
-* 抛 TypeError → **整个插件加载失败**（不只是卡片，是 dsh-router 完全挂掉）。
-*   - 有 volatile：走 volatile，空 object 不被 volatileForm 过滤 → 卡片进镜像；
-*   - 无 volatile：回落普通空 schema，不抛；此时宿主必是 0.1.5，本就靠
-*     installSection 出卡片（见下方按版本分流的注册），这个 Config 无副作用。
+* 为什么要 `.volatile()`：空 object 会被 volatileForm 过滤掉，顶层标 volatile 才能让
+* 卡片进镜像。`.volatile()` 是 schemastery 3.18.4 才有的原型方法，直写
+* `Schema.object({}).volatile()` 在没有它的版本上会抛 TypeError → **整个插件加载
+* 失败**。所以：无 volatile 就回落普通空 schema（不抛，代价是卡片不出现，并有日志）。
 */
 const emptySchema = Schema.object({});
 /**
-* 0.1.7 的设置镜像只认「插件导出的 Config + 配置树行 id」这条收录链，且空 object
+* 设置镜像只认「插件导出的 Config + 配置树行 id」这条收录链，且空 object
 * 会被 volatileForm 过滤掉 —— 顶层 `.volatile()` 才能让 Router 卡片出现在设置-模型。
 * Router 的真配置在自己的 state.json（路由系统面板），这里故意不暴露任何字段。
 */
@@ -4880,9 +4863,9 @@ function apply(rawContext) {
 	const stateFile = join(dataDir, "state.json");
 	log(`data dir: ${dataDir}`);
 	const hostVersion = detectHostVersion(ctx.baseUrl);
-	const host017Plus = isHost017Plus(ctx.baseUrl);
-	const lastHitDock = supportsLastHitDock(ctx.baseUrl);
-	log(`host version: ${hostVersion ?? "未知"} (>=0.1.7: ${host017Plus ? "yes" : "no"}, last-hit dock: ${lastHitDock ? "on" : "off"})`);
+	const hostSupported = isHostSupported(ctx.baseUrl);
+	log(`host version: ${hostVersion ?? "未知"} (>=0.2.0: ${hostSupported ? "yes" : "no"})`);
+	if (!hostSupported) ctx.logger.warn(`[dsh-router] 宿主版本 ${hostVersion ?? "未知"} 低于本插件支持的 0.2.0 —— 插件仍会加载，但设置卡片、「最近命中」徽章与工具结果转发会走错路径。请把宿主升到 0.2.0 及以上。`);
 	const store = new SupplierConfigStore(stateFile);
 	const credentials = new CredentialStore(join(dataDir, "auths"));
 	const router = new Router(stateFile, store, log);
@@ -5050,7 +5033,7 @@ function apply(rawContext) {
 		writeJson(res, 200, {
 			ok: true,
 			hostVersion: hostVersion ?? "",
-			lastHitDock,
+			lastHitDock: true,
 			suppliers: suppliers.map((s) => {
 				const loaded = loadedSuppliers.find((l) => l.supplier.id === s.id);
 				return {
@@ -5264,6 +5247,39 @@ function apply(rawContext) {
 			requireApiKey: keys.requireApiKey
 		});
 	});
+	/**
+	* 把 `router.ext` 表映射成面板要的 `ExtInfo[]`。**GET 与 PATCH 共用**。
+	*
+	* ⚠️ 2026-09-30：op 成功时我复制了一份这段映射来就地回表 —— 两份必然漂移
+	*   （改一处只生效一半，本仓反复栽的坑）⇒ 抽成函数，一处定义两处调用。
+	*/
+	function extInfos(table, isEnabled) {
+		return Object.values(table).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 } : {},
+				...e.icon !== void 0 ? { icon: e.icon } : {},
+				enabled: isEnabled(e.id),
+				ready: st?.ready === true,
+				...raw.source === "builtin" ? { source: "builtin" } : {},
+				...Array.isArray(e.controls) && e.controls.length > 0 ? { controls: e.controls.filter((c) => !!c && typeof c.id === "string" && c.id !== "" && typeof c.title === "string").map((c) => ({
+					id: c.id,
+					title: c.title,
+					on: c.on === true,
+					...c.detail !== void 0 ? { detail: c.detail } : {},
+					...typeof c.body === "string" ? { body: c.body } : {},
+					...c.editable === true ? { editable: true } : {},
+					custom: c.custom === true,
+					overridden: c.overridden === true
+				})) } : {},
+				...st?.detail !== void 0 ? { detail: st.detail } : {}
+			};
+		}).filter((e) => e !== void 0);
+	}
 	route(`${ROUTER_API_BASE}/ext`, async (req, res) => {
 		if (req.method === "PATCH") {
 			let body;
@@ -5276,6 +5292,7 @@ function apply(rawContext) {
 				});
 				return;
 			}
+			let addedId = null;
 			const ext = typeof body.id === "string" ? exts[body.id] : void 0;
 			if (!ext) {
 				writeJson(res, 404, {
@@ -5284,6 +5301,152 @@ function apply(rawContext) {
 				});
 				return;
 			}
+			if (body.op !== void 0) {
+				const op = body.op;
+				if (op === "reorder") {
+					if (!Array.isArray(body.ids)) {
+						writeJson(res, 400, {
+							ok: false,
+							error: "ids must be an array"
+						});
+						return;
+					}
+					if (typeof ext.setControlOrder !== "function" || !ext.setControlOrder(body.ids)) {
+						writeJson(res, 400, {
+							ok: false,
+							error: "排序保存失败"
+						});
+						return;
+					}
+				} else if (op === "remove" || op === "reset") {
+					if (typeof body.controlId !== "string" || body.controlId === "") {
+						writeJson(res, 400, {
+							ok: false,
+							error: "controlId must be a non-empty string"
+						});
+						return;
+					}
+					const fn = op === "remove" ? ext.removeCustomControl : ext.resetControlText;
+					if (typeof fn !== "function" || !fn.call(ext, body.controlId)) {
+						writeJson(res, 400, {
+							ok: false,
+							error: op === "remove" ? "只能删除自定义准则（内置条目请用开关关掉）" : "只能还原内置准则，且它得先被改过"
+						});
+						return;
+					}
+				} else if (op === "add") {
+					if (typeof ext.addCustomControl !== "function") {
+						writeJson(res, 400, {
+							ok: false,
+							error: "extension does not support custom controls"
+						});
+						return;
+					}
+					addedId = ext.addCustomControl(typeof body.title === "string" ? body.title : "", typeof body.body === "string" ? body.body : "");
+					if (addedId === null) {
+						writeJson(res, 400, {
+							ok: false,
+							error: "标题与内容都不能为空"
+						});
+						return;
+					}
+				} else {
+					writeJson(res, 400, {
+						ok: false,
+						error: `unknown op: ${String(op)}`
+					});
+					return;
+				}
+				writeJson(res, 200, addedId === null ? {
+					ok: true,
+					enhancers: extInfos(exts, (id) => extStore.isEnabled(id))
+				} : {
+					ok: true,
+					id: addedId,
+					enhancers: extInfos(exts, (id) => extStore.isEnabled(id))
+				});
+				return;
+			}
+			if (body.title !== void 0 || body.body !== void 0) {
+				if (typeof body.controlId !== "string" || body.controlId === "") {
+					writeJson(res, 400, {
+						ok: false,
+						error: "controlId must be a non-empty string"
+					});
+					return;
+				}
+				if (typeof body.title !== "undefined" && typeof body.title !== "string") {
+					writeJson(res, 400, {
+						ok: false,
+						error: "title must be a string"
+					});
+					return;
+				}
+				if (typeof body.body !== "undefined" && typeof body.body !== "string") {
+					writeJson(res, 400, {
+						ok: false,
+						error: "body must be a string"
+					});
+					return;
+				}
+				if (typeof ext.setControlText !== "function") {
+					writeJson(res, 400, {
+						ok: false,
+						error: "extension controls are not editable"
+					});
+					return;
+				}
+				const patch = {};
+				if (typeof body.title === "string") patch.title = body.title;
+				if (typeof body.body === "string") patch.body = body.body;
+				if (!ext.setControlText(body.controlId, patch)) {
+					writeJson(res, 400, {
+						ok: false,
+						error: "unknown controlId"
+					});
+					return;
+				}
+				writeJson(res, 200, {
+					ok: true,
+					enhancers: extInfos(exts, (id) => extStore.isEnabled(id))
+				});
+				return;
+			}
+			if (body.controlId !== void 0) {
+				if (typeof body.controlId !== "string" || body.controlId === "") {
+					writeJson(res, 400, {
+						ok: false,
+						error: "controlId must be a non-empty string"
+					});
+					return;
+				}
+				if (typeof body.on !== "boolean") {
+					writeJson(res, 400, {
+						ok: false,
+						error: "on must be a boolean"
+					});
+					return;
+				}
+				if (typeof ext.setControl !== "function") {
+					writeJson(res, 400, {
+						ok: false,
+						error: "extension has no controls"
+					});
+					return;
+				}
+				if (!ext.setControl(body.controlId, body.on)) {
+					writeJson(res, 400, {
+						ok: false,
+						error: "unknown controlId"
+					});
+					return;
+				}
+				writeJson(res, 200, {
+					ok: true,
+					enhancers: extInfos(exts, (id) => extStore.isEnabled(id))
+				});
+				return;
+			}
 			if (typeof body.enabled !== "boolean") {
 				writeJson(res, 400, {
 					ok: false,
@@ -5305,21 +5468,7 @@ function apply(rawContext) {
 		}
 		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 } : {},
-					...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)
+			enhancers: extInfos(exts, (id) => extStore.isEnabled(id))
 		});
 	});
 	/** 解析并校验周期参数（不接受任意字符串）。 */
@@ -5382,24 +5531,7 @@ function apply(rawContext) {
 		disposers.push(ctx.llm.registerModelDiscovery(settingsNs, async () => {
 			return (await router.combos()).map((c) => ({ id: c.name }));
 		}));
-		const routerSettingsSchema = Schema.object({});
-		if (isHost017Plus(ctx.baseUrl)) log(`settings section driven by exported Config (${settingsNs})`);
-		else ctx.inject(["settings"], (sctx) => {
-			const settings = sctx.settings;
-			if (settings === void 0) {
-				log("settings service absent — skip Router settings-section registration");
-				return;
-			}
-			if (settings.installSection === void 0) {
-				log(`settings.installSection absent despite 0.1.5 host (${settingsNs})`);
-				return;
-			}
-			settings.installSection(rawContext, settingsNs, routerSettingsSchema, {}, {
-				setSource: () => {},
-				onChange: () => {}
-			});
-			log(`Router settings section registered (${settingsNs})`);
-		});
+		log(`settings section driven by exported Config (${settingsNs})`);
 		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 {

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

@@ -61,11 +61,124 @@ export interface RouterExt {
      * 再在下面列一遍就是同一个东西显示两处。
      */
     readonly source?: 'builtin';
+    /**
+     * 扩展自带的**子开关**（可选；不声明 = 只有总开关）。
+     *
+     * 为什么需要：有些扩展的「开/关」不是一件事而是**几件独立的事** —— 例如分层
+     * 提示词有 14 个准则分类，每条都该能单独关。硬塞进一个总开关 = 要么全给、
+     * 要么全不给。
+     *
+     * ⚠️ **与总开关的关系**：子开关是**叠加**在总开关之上的，总开关关 ⇒ 全部子开关
+     *   一起失效（但**不清零**用户的子开关选择）。详情页在总开关关时把它们显示为
+     *   禁用而不是隐藏 —— 隐藏会让用户以为它们不存在。
+     *
+     * ⚠️ **值存哪**：核心**不认识**这些子开关的语义，只负责搬运。落盘一律走
+     *   `ExtStoreService.writeData`（`data` 抽屉），由扩展自己读回。核心不替扩展
+     *   存一份 —— 那样会变成两份可能漂移的真相。
+     */
+    /**
+     * 扩展自报的**子开关**列表。
+     *
+     * ⚠️ **实现方应当每次读都重算**（getter），而不是在构造时算好一个数组快照：
+     *   核心每次 `GET /ext` 都读它，面板也靠它刷新。若它是快照，改完文本再刷新
+     *   面板拿到的仍是**旧值** —— 用户会看到"保存了、又变回去了"
+     *   （实测踩过：2026-09-29 第一版用 `CATEGORIES.map(...)`，编辑生效但列表
+     *   不跟着变，而注释里还写着"现算不缓存"——**注释与事实不符**，比没写更坏）。
+     */
+    readonly controls?: ExtControl[];
+    /**
+     * 改一个子开关（面板调用；可选 —— 没有 `controls` 就不需要）。
+     *
+     * ⚠️ **为什么由扩展自己写、核心不代劳**：子开关的落盘形状归扩展所有
+     *   （本仓是 `data.categories[id]`），核心一旦代写就得认识那个形状 ——
+     *   换个扩展就是换个形状，核心会变成「认识所有扩展的私有数据格式」的地方。
+     *   核心只负责：把 `{ controlId, on }` 递进来，并把**成功/失败**如实回给面板。
+     *
+     * @param controlId - 要改的子开关 id。
+     * @param on - 目标状态。
+     * @returns 落盘结果。返回 false 时核心回 400，且**不写盘**。
+     */
+    setControl?(controlId: string, on: boolean): boolean;
+    /**
+     * 改一个子开关的**文本**（标题 / 正文），可选 —— 不实现就是不可编辑。
+     *
+     * ⚠️ **与 `setControl` 分开而不是合并**：开关是**布尔**、文本是**字符串**，
+     *   合成一个方法就得在里面判类型，面板那边也要问"这次改的是哪个" ——
+     *   那是两个独立动作、两种失败原因（未知 id / 空标题）。
+     *
+     * ⚠️ 落盘形状仍归扩展（本仓是 `data.text[id]`，与开关的 `data.categories[id]`
+     *   **分开两个键**）：开关是"开不开"，文本是"写成什么样"，混在一个键里
+     *   改标题会顺手碰到开关状态。
+     *
+     * @param controlId - 要改的子开关 id。
+     * @param patch - 要覆盖的字段；**未出现的字段保持原样**（部分更新）。
+     * @returns 落盘结果。返回 false 时核心回 400，且**不写盘**。
+     */
+    setControlText?(controlId: string, patch: {
+        title?: string;
+        body?: string;
+    }): boolean;
+    /**
+     * 改**展示顺序**（拖动）。落盘一串 id；扩展负责过滤自己不认识的 id。
+     *
+     * ⚠️ 与前三者都不同：它改的是**列表本身**，不是某一条的内容。
+     */
+    setControlOrder?(ids: string[]): boolean;
+    /**
+     * 新增一条**自建**条目，返回新 id（由扩展生成，避免前端编 id 撞内置）。
+     * @returns 新 id；失败（如空标题/空正文）返回 null。
+     */
+    addCustomControl?(title: string, body: string): string | null;
+    /**
+     * 删一条 —— **扩展应当只允许删自建条目**（内置的删除手段是关开关）。
+     * @returns 落盘结果；false 时核心回 400 且不写盘。
+     */
+    removeCustomControl?(controlId: string): boolean;
+    /**
+     * 还原一条的文本（丢掉覆盖，回到扩展自带的内容）。
+     * 自建条目**没有"自带内容"**可回退，扩展应当对它返回 false。
+     */
+    resetControlText?(controlId: string): boolean;
     /** 当前运行时状态（ready + 不就绪时的说明）。 */
     getState(): ExtState;
     /** 卸载清理（表删除时由 dsh-router 调用，可选）。 */
     dispose?(): void;
 }
+/**
+ * 一个可独立开关的子项（如准则的某一条）。
+ *
+ * ⚠️ `id` 是**持久化键**（落进 `data` 抽屉），**改名会让用户已保存的选择丢失**。
+ */
+export interface ExtControl {
+    /** 稳定 id（持久化键）。 */
+    readonly id: string;
+    /** 面板显示名。 */
+    readonly title: string;
+    /** 当前是否开启（扩展自算：默认值 + 用户已存的选择）。 */
+    readonly on: boolean;
+    /** 一句话说明这一条管什么（面板副行，可选）。 */
+    readonly detail?: string;
+    /**
+     * 这一条的**原文**（可选）—— 面板点开即可读到。
+     *
+     * 为什么值得加：不给出原文的话，用户是在**盲切** —— 只看到「结构」「交付」
+     * 这样的名字，不知道它到底写了什么，也无从判断该不该关掉这一条。给出原文
+     * ⇒「看内容 → 决定开关」这个动作才成立。
+     */
+    readonly body?: string;
+    /**
+     * 这一条的**文本可被编辑**（可选；缺省 = 只读）。
+     *
+     * ⚠️ 为什么要显式声明而不是「有 `setControlText` 就可编辑」：扩展实现了写入
+     *   能力但某些条目**刻意锁住**（例如标题是分类 id 的可读形式，改了会和
+     *   `data` 里的键失去对应关系）。由扩展逐条说了算。
+     */
+    readonly editable?: boolean;
+    /** 自建条目（可删除）。缺省 = 内置（不可删除，只有开关与还原）。 */
+    readonly custom?: boolean;
+    /** 文本被用户改过（决定「还原」按钮是否可点）。 */
+    readonly overridden?: boolean;
+}
 /** 面板/API 用的一条扩展器信息 = 核心存的开关 + 插件报的运行时事实。 */
 export interface ExtInfo {
     id: string;