@lynn123411/dsh-llm-agentrouter 0.2.2 → 0.2.3

package/README.md

@@ -1,13 +1,14 @@
 # @lynn123411/dsh-llm-agentrouter
 
-AgentRouter 中转聚合插件：把同一家中转的多个模型收拢为一条 pi-ai 路由（模型选择器只出现一个 AgentRouter 分组），国内 / 国际端点在「设置 - 插件 - AgentRouter 中转站」一键切换、下一请求即生效，外加出站请求的 User-Agent 改写与 402 配额耗尽提示围栏。分叉自 `aqiu817/dsh-llm-agentrouter`，适配 DSH `0.1.2-alpha.5` 起的新 settings/slots API，已在 `0.1.5-rc.1` 逐项实证兼容。
+AgentRouter 中转聚合插件：把同一家中转的多个模型收拢为一条 pi-ai 路由（模型选择器只出现一个 AgentRouter 分组），国内 / 国际端点在「设置 - API中转 - AgentRouter 中转站」一键切换、下一请求即生效，外加出站请求的 User-Agent 改写与 402 配额耗尽提示围栏。分叉自 `aqiu817/dsh-llm-agentrouter`，适配 DSH `0.1.2-alpha.5` 起的新 settings/slots API，已在 `0.1.5-rc.1` 逐项实证兼容。
 
 ## 特性
 
 - **单路由多模型**：Claude Opus 5、GPT-5.6-sol 等走同一 `agentrouter` 路由，`reasoningEffort` 档位与兼容开关按实测探针手写声明，模型列表不翻倍。
 - **端点一键切换**：设置卡片两个大选项（国内端点 / 国际端点，附带真实 host 展示），点击即写即生效，无需重启；API Key 只存 `$DSH_HOME/.credentials.yaml` 的 `AGENTROUTER_API_KEY` 引用。
+- **共享「API中转」设置页**：本插件的端点卡片与 `dsh-a6api` 的面板挂在同一个设置页里（`settings.section` id `relay` 的页内两个 tab，参与者可增删）。内核不允许一页被多个插件共同声明，因此每个参与者各持一份运行时逻辑一致的页壳，**先加载者当选页面宿主**、其余只注册卡片；当选者被卸载后下次启动自动改选。做法与约束见仓库 `docs/rules/shared-settings-page.md`。
 - **请求围栏**：重写 relay 要求的 `User-Agent`（适配器强制署名下沉到 `fetch` 层替换），哨兵 host（`.internal` 不可解析）兜底防裸奔，402 配额耗尽的 JSON 错误体改写为可读提示。
-- **alpha.5 兼容**：宿主改用 `ctx.settings.installSection` + `ctx.inject(['settings'])`，客户端卡片改挂 `settings.plugins.tab`；沿用 `llm-agentrouter` 设置命名空间，老配置无缝继承。
+- **alpha.5 兼容**：宿主沿用 `ctx.settings.installSection` + `ctx.inject(['settings'])`，客户端卡片改挂共享设置页的子 slot；沿用 `llm-agentrouter` 设置命名空间，老配置无缝继承。
 
 ## 安装
 

package/lib/client.js

@@ -42,6 +42,7 @@ window.__ModuleLoader__.load({
 		//#region locales
 		/** Simplified Chinese dictionary and key source of truth. */
 		const zh = {
+			pageNav: "API中转",
 			title: "AgentRouter 中转站",
 			description: "选择请求发往的端点。切换后立即生效，无需重启；模型列表不受影响。",
 			cn: "国内端点",
@@ -57,6 +58,7 @@ window.__ModuleLoader__.load({
 		};
 		/** English dictionary checked against the Chinese key set. */
 		const en = {
+			pageNav: "API relay",
 			title: "AgentRouter relay",
 			description: "Which endpoint requests are sent to. A switch applies to the next request; the model list is unaffected.",
 			cn: "Domestic endpoint",
@@ -210,6 +212,217 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 
+		//#region shared relay settings page shell
+		/**
+		 * The shared 「API中转」 settings page.
+		 *
+		 * Several plugins contribute their configuration to ONE settings page, but the
+		 * kernel cannot declare that page jointly: `settings.section` is a list slot
+		 * that rejects a duplicate `id` at the same priority ("already has an entry
+		 * with id"), and a child slot may be declared exactly once ("slot … is already
+		 * declared"). Composing several cards into one page therefore takes one
+		 * declarer, so every participating plugin carries this same shell and the
+		 * FIRST one to activate claims the page; the others register their card into
+		 * RELAY_ITEM_SLOT and wait for the winner's declaration through
+		 * `slots.inject`. Uninstalling the winner promotes another participant on the
+		 * next boot, so no participant is a fixed owner.
+		 *
+		 * The page renders ONE TAB PER REGISTERED CARD: the tab roster comes from the
+		 * child slot's own registrations (id + `label` + `order`, the same shape the
+		 * kernel's own Plugins page uses for its tabs), and each panel dispatches
+		 * through `renderSlot(RELAY_ITEM_SLOT, {}, { only: id })`. Every panel stays
+		 * mounted but hidden, so a card's local state survives a tab switch.
+		 *
+		 * Keep the runtime body of this region identical to the one in
+		 * `dsh-a6api`'s `src/client/relay-settings-page.js`. Participants own their own
+		 * card component, locale dictionaries, settings namespace and Host half — only
+		 * the page shell is shared, because cross-plugin value imports are forbidden by
+		 * the client bundle purity gate. It needs nothing but `react` on purpose, so
+		 * every participant's build configuration compiles it unchanged.
+		 */
+		/** Page id claimed by the first participating plugin to activate. */
+		const RELAY_PAGE_ID = "relay";
+		/** Sidebar position of the shared page; own plugins start at 110. */
+		const RELAY_PAGE_ORDER = 120;
+		/** The page's one child slot: every participant's card registers here. */
+		const RELAY_ITEM_SLOT = "relay.settings.item";
+		/**
+		 * Tab chrome mirrors the kernel's own settings tabs (`.tabs` / `.tab` in
+		 * `ui-settings-plugins`): tertiary label, 13px, 22px gutter. The marker is the
+		 * ACTIVE TAB'S OWN bottom border and the bar draws no rail of its own — a
+		 * shared underline reads as "every tab is selected".
+		 */
+		const TABLIST_STYLE = {
+			display: "flex",
+			alignItems: "flex-end",
+			gap: "22px",
+			marginTop: "2px",
+			marginBottom: "16px",
+		};
+		const TAB_STYLE = {
+			appearance: "none",
+			background: "transparent",
+			// No border on ANY tab: the marker below is the active tab's own element, so
+			// an inactive tab has nothing that could render a line.
+			border: "none",
+			position: "relative",
+			padding: "7px 1px 11px",
+			cursor: "pointer",
+			font: "inherit",
+			fontSize: "13px",
+			lineHeight: "20px",
+			color: "var(--dsw-alias-label-tertiary, inherit)",
+		};
+		const TAB_ACTIVE_STYLE = Object.assign({}, TAB_STYLE, {
+			color: "var(--dsw-alias-label-primary, inherit)",
+		});
+		/** The kernel's own tab marker: a 2px rounded bar under the active label. */
+		const TAB_MARKER_STYLE = {
+			position: "absolute",
+			left: 0,
+			right: 0,
+			bottom: 0,
+			height: "2px",
+			borderRadius: "2px 2px 0 0",
+			background: "var(--dsw-alias-label-primary, currentColor)",
+		};
+		/**
+		 * Panels stay mounted (hidden) so each card keeps its local state. `display:
+		 * none` is written explicitly because a card's own styles commonly set
+		 * `display: flex` while the section's stylesheet loads after this one.
+		 */
+		const PANEL_STYLE = { margin: 0 };
+		const PANEL_HIDDEN_STYLE = { margin: 0, display: "none" };
+		/** A registration label is a plain string or a thunk re-read per projection. */
+		function readLabel(label) {
+			if (typeof label === "function") return label();
+			return typeof label === "string" ? label : "";
+		}
+		/**
+		 * Build the live tab roster over the child slot's registrations. `locale` is
+		 * read through `ctx.get`: a participant needs it only to re-read localized
+		 * labels on a language switch, and reaching an undeclared service as
+		 * `ctx.locale` would trip the kernel's inject guard. Every participant passes a
+		 * bound translator as its `label` thunk, so the label re-reads the active
+		 * language on each projection.
+		 *
+		 * @param {object} ctx - browser context carrying the slot registry.
+		 * @returns {object} the tab store consumed by the page component.
+		 */
+		function createRelayTabs(ctx) {
+			const locale = ctx.get("locale");
+			let version = -1;
+			let revision = -1;
+			let tabs = [];
+			return {
+				getSnapshot: () => {
+					const nextVersion = ctx.slots.getVersion(RELAY_ITEM_SLOT);
+					const nextRevision = locale === undefined ? 0 : locale.getSnapshot().revision;
+					if (nextVersion === version && nextRevision === revision) return tabs;
+					version = nextVersion;
+					revision = nextRevision;
+					tabs = ctx.slots.entries(RELAY_ITEM_SLOT)
+						.map((entry) => ({
+							id: entry.options.id ?? "",
+							order: entry.options.order ?? 0,
+							label: readLabel(entry.options.label),
+						}))
+						.sort((left, right) => left.order - right.order);
+					return tabs;
+				},
+				subscribe: (listener) => {
+					const offSlots = ctx.slots.subscribe(RELAY_ITEM_SLOT, listener);
+					const offLocale = locale === undefined ? undefined : locale.subscribe(listener);
+					return () => {
+						offSlots();
+						if (offLocale !== undefined) offLocale();
+					};
+				},
+			};
+		}
+		/**
+		 * Page body: one tab per registered card, plus the selected card's panel.
+		 * The shell supplies the section's own seats and `renderSlot` bound to the
+		 * child slot declared at registration time.
+		 *
+		 * @param {object} props - the injected render seat plus the tab roster.
+		 * @returns {JSX.Element|null} the page body.
+		 */
+		function RelaySettingsSection({ renderSlot, relayTabs }) {
+			const tabs = react.useSyncExternalStore(
+				relayTabs.subscribe,
+				relayTabs.getSnapshot,
+				relayTabs.getSnapshot,
+			);
+			const [requested, setRequested] = react.useState(null);
+			const selected = requested !== null && tabs.some((tab) => tab.id === requested)
+				? requested
+				: (tabs.length > 0 ? tabs[0].id : null);
+			if (selected === null) return null;
+			return react.createElement(
+				"div",
+				null,
+				react.createElement(
+					"div",
+					{ role: "tablist", style: TABLIST_STYLE },
+					tabs.map((tab) => react.createElement(
+						"button",
+						{
+							key: tab.id,
+							type: "button",
+							role: "tab",
+							"aria-selected": tab.id === selected,
+							style: tab.id === selected ? TAB_ACTIVE_STYLE : TAB_STYLE,
+							onClick: () => { setRequested(tab.id); },
+						},
+						tab.label,
+						tab.id === selected ? react.createElement("span", { style: TAB_MARKER_STYLE, "aria-hidden": true }) : null,
+					)),
+				),
+				tabs.map((tab) => react.createElement(
+					"div",
+					{
+						key: tab.id,
+						role: "tabpanel",
+						hidden: tab.id !== selected,
+						style: tab.id === selected ? PANEL_STYLE : PANEL_HIDDEN_STYLE,
+					},
+					renderSlot(RELAY_ITEM_SLOT, {}, { only: tab.id }),
+				)),
+			);
+		}
+		/** Whether a participant already holds the shared page. */
+		function relayPageClaimed(ctx) {
+			return ctx.slots.entries("settings.section").some((entry) => entry.options.id === RELAY_PAGE_ID);
+		}
+		/**
+		 * Claim the shared page when no participant holds it yet. Call inside
+		 * `ctx.slots.inject('settings.section', …)`: injection order decides the
+		 * winner, and the losers stay silent instead of colliding with the kernel's
+		 * duplicate-id and duplicate-declaration guards.
+		 *
+		 * @param {object} ctx - browser context carrying the slot registry.
+		 * @param {Function} label - page label of the claiming participant, re-read by
+		 * the shell on every projection so a language switch reaches the sidebar too.
+		 * @returns {Function} the page registration's disposer, or a no-op when
+		 * another participant already holds the page.
+		 */
+		function claimRelaySettingsPage(ctx, label) {
+			if (relayPageClaimed(ctx)) return () => {};
+			const relayTabs = createRelayTabs(ctx);
+			const children = {};
+			children[RELAY_ITEM_SLOT] = { kind: "list", scope: "root" };
+			return ctx.slots.register({
+				name: "settings.section",
+				id: RELAY_PAGE_ID,
+				order: RELAY_PAGE_ORDER,
+				label,
+				inject: () => ({ relayTabs }),
+				children,
+			}, RelaySettingsSection);
+		}
+		//#endregion
+
 		//#region plugin
 		/** Dictionary namespace owned by this plugin. */
 		const NS = "settings.agentrouter";
@@ -223,19 +436,28 @@ window.__ModuleLoader__.load({
 		const inject = ["slots", "locale", "settingsScope"];
 
 		/**
-		 * Register the endpoint card into the plugin configuration tab.
+		 * Register the endpoint card inside the shared 「API中转」 page, which this
+		 * plugin carries the shell for and claims when it activates first.
 		 * @param {object} ctx - the browser plugin context.
 		 */
 		function apply(ctx) {
 			ctx.effect(() => ctx.locale.register(NS, { zh, en }), "llm-agentrouter: dictionaries");
 			const t = ctx.locale.bind(NS);
 			const scope = ctx.settingsScope.bind({ namespace: SETTINGS_NS });
-			ctx.slots.inject("settings.plugins.tab", () =>
+			// The page is shared with dsh-a6api and the kernel cannot declare one page
+			// twice, so whichever participant activates first claims it and the other
+			// only contributes a card (see the shell region above).
+			ctx.slots.inject("settings.section", () =>
+				claimRelaySettingsPage(ctx, () => t("pageNav")));
+			ctx.slots.inject(RELAY_ITEM_SLOT, () =>
 				ctx.slots.register(
 					{
-						name: "settings.plugins.tab",
+						name: RELAY_ITEM_SLOT,
+						// id = the Host settings namespace; the shared page filters its
+						// panels by this id, so it must be the plugin's own key.
 						id: SETTINGS_NS,
-						order: 30,
+						order: 20,
+						// Rendered as the card's tab title inside the shared page.
 						label: () => t("title"),
 						locale: NS,
 						inject: () => ({ scope, t }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lynn123411/dsh-llm-agentrouter",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "AgentRouter 中转聚合：一条 pi-ai 路由承载多模型 + 国内/国际端点一键切换（设置卡片）+ 出站请求 User-Agent/402-配额改写围栏。aqiu817/dsh-llm-agentrouter 分叉，适配 0.1.2-alpha.5 起新 settings/slots API，已在 0.1.5-rc.1 逐项实证兼容。",
   "keywords": [
     "deepseek-harness",