@lynn123411/dsh-llm-agentrouter 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 aqiu817
+Copyright (c) 2026 lynn123411 (alpha.5 compatibility fork: settings/slots API migration, package rename)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @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。
+
+## 特性
+
+- **单路由多模型**：Claude Opus 5、GPT-5.6-sol 等走同一 `agentrouter` 路由，`reasoningEffort` 档位与兼容开关按实测探针手写声明，模型列表不翻倍。
+- **端点一键切换**：设置卡片两个大选项（国内端点 / 国际端点，附带真实 host 展示），点击即写即生效，无需重启；API Key 只存 `$DSH_HOME/.credentials.yaml` 的 `AGENTROUTER_API_KEY` 引用。
+- **请求围栏**：重写 relay 要求的 `User-Agent`（适配器强制署名下沉到 `fetch` 层替换），哨兵 host（`.internal` 不可解析）兜底防裸奔，402 配额耗尽的 JSON 错误体改写为可读提示。
+- **alpha.5 兼容**：宿主改用 `ctx.settings.installSection` + `ctx.inject(['settings'])`，客户端卡片改挂 `settings.plugins.tab`；沿用 `llm-agentrouter` 设置命名空间，老配置无缝继承。
+
+## 安装
+
+```bash
+dsh plugin --profile web add @lynn123411/dsh-llm-agentrouter
+```

package/cordis.patch.yml

@@ -0,0 +1,147 @@
+# dsh-llm-agentrouter bundle patch — the AgentRouter relay as ONE provider route
+# whose endpoint is a runtime choice, plus the fence that makes both possible.
+#
+# Applied after the dsh-base / dsh-web-app bundle layers, so the `llm-pi-ai`
+# row below overrides the dormant zero-route entry dsh-base mounts.
+#
+# WHY ONE ROUTE AND NOT TWO
+# The relay serves the same three models at a domestic and an international
+# endpoint; only the origin differs. Declaring a route per endpoint put every
+# model in the picker twice and made "which endpoint" a choice the user had to
+# re-make on every model switch. It is not a model property — it is one
+# deployment-wide setting, so it lives in this plugin's own settings section and
+# the picker shows one AgentRouter group.
+#
+# WHY THE BASE URL IS A SENTINEL
+# `baseURL` is resolved once per request by the adapter, but it cannot read this
+# plugin's endpoint choice — the two live in different namespaces. So the route
+# addresses a host that deliberately does not exist, and the fence rewrites it
+# to the chosen endpoint on the way out (`.internal` is reserved for exactly
+# this, so an unfenced request fails to resolve instead of reaching anything
+# real). The fence has to be in the request path regardless: the relay
+# authenticates its client by User-Agent, and the adapter strips profile headers
+# colliding with its mandatory attribution. See lib/index.js.
+#
+# CREDENTIALS
+# `apiKeyEnv` is a credential *reference* resolved per request; the secret lives
+# in $DSH_HOME/.credentials.yaml (or the environment), never in this file. Do
+# NOT move a key into `headers`: that dict is returned verbatim by the adapter's
+# `describe()` and rendered by the Models settings page. One reference serves
+# both endpoints because it is one relay account.
+#
+# MODEL CATALOG
+# pi-ai's installed catalog describes all three models, but under their vendor
+# providers (`anthropic`, `openai`) and other protocols — Opus via
+# anthropic-messages, gpt-5.6-sol via openai-responses. A hand-declared route
+# inherits nothing, so capacities, reasoning levels, and compat switches are
+# restated here from that catalog, adjusted for Chat Completions.
+#
+# `reasoningEfforts` keys are the levels the picker offers; each value is the
+# wire spelling sent as `reasoning_effort`. All three models were probed against
+# the live relay: every level below answered 200. `off:` (declared, no value)
+# offers Off and sends nothing, which is what an OpenAI-shaped endpoint wants.
+# WHY THE PICKER SAYS NOTHING ABOUT THE ENDPOINT
+# The model picker renders no child slots, so a plugin cannot inject anything
+# into that menu; per group it shows only `displayName`, and per model only the
+# name and an adapter-supplied description a hand-declared pi-ai route has no
+# field for. The group title is therefore the only reachable surface — and it is
+# a name, not a notice, so it stays a name. The endpoint is explained where it is
+# changed: 设置 → 插件 → AgentRouter 中转站.
+- id: llm-pi-ai
+  name: '@deepseek-ai/dsh-llm-pi-ai'
+  config:
+    providers:
+      agentrouter:
+        displayName: AgentRouter
+        apiKeyEnv: AGENTROUTER_API_KEY
+        api: openai-completions
+        # Rewritten per request by llm-agentrouter to the selected endpoint.
+        baseURL: https://relay.agentrouter.internal/v1
+        defaultInput:
+          - text
+        # The relay is not an endpoint pi-ai can recognize, so its detection
+        # would address it as OpenAI itself: `developer` system role and
+        # `max_completion_tokens`. Probes show it accepts plain `system`,
+        # `max_tokens`, top-level `reasoning_effort`, and `strict` tools.
+        compat:
+          thinkingFormat: openai
+          supportsReasoningEffort: true
+          supportsDeveloperRole: false
+          maxTokensField: max_tokens
+          supportsStore: false
+          supportsStrictMode: true
+          supportsUsageInStreaming: true
+        models:
+          - id: claude-opus-5
+            name: Claude Opus 5
+            contextWindow: 1000000
+            maxTokens: 128000
+            reasoningEfforts: &opus-efforts
+              off:
+              low: low
+              medium: medium
+              high: high
+              xhigh: xhigh
+              max: max
+          - id: claude-opus-4-8
+            name: Claude Opus 4.8
+            contextWindow: 1000000
+            maxTokens: 128000
+            reasoningEfforts: *opus-efforts
+          - id: gpt-5.6-sol
+            name: GPT 5.6 Sol
+            contextWindow: 272000
+            maxTokens: 128000
+            reasoningEfforts:
+              off:
+              minimal: minimal
+              low: low
+              medium: medium
+              high: high
+              xhigh: xhigh
+              max: max
+          # Tiers mirror what the first-party `deepseek-official` route offers for
+          # DeepSeek-V4-Flash — off / low / high / max — rather than the relay's
+          # full enum. The relay does accept `minimal`, `medium`, and `xhigh` for
+          # this model, but the levels a model is *offered* under should match the
+          # vendor's own selection; add them here if that ever changes.
+          #
+          # `off` carries the wire value `none` instead of being left empty, and
+          # that is not cosmetic: omitting `reasoning_effort` entirely still
+          # returns `reasoning_content` with a nonzero `reasoning_tokens`, so an
+          # empty `off:` would offer a switch that does nothing. `none` is the
+          # only spelling that actually stops the thinking, and it is the relay's
+          # own word — `off` is rejected with a 400 naming the accepted enum.
+          - id: deepseek-v4-flash
+            name: DeepSeek V4 Flash
+            contextWindow: 1000000
+            maxTokens: 256000
+            reasoningEfforts:
+              off: none
+              low: low
+              high: high
+              max: max
+          # This model declares no `off` at all, and that is the honest shape
+          # rather than an omission: every level outside low / high / max — `none`,
+          # `minimal`, `medium`, `xhigh` — is refused with 400 «该模型始终思考，不
+          # 支持关闭思考；请使用 low、high 或 max。». It always thinks. Leaving `off`
+          # out withholds the level, so the picker never offers a switch the
+          # upstream would reject.
+          #
+          # `maxTokens` is the ceiling the relay states for this model: a larger
+          # value comes back as «max_tokens参数非法：限制数值范围[1,131072]».
+          - id: glm-5.3
+            name: GLM 5.3
+            contextWindow: 1000000
+            maxTokens: 131072
+            reasoningEfforts:
+              low: low
+              high: high
+              max: max
+
+# The endpoint switch and the User-Agent fence. Both are one plugin because both
+# are one rewrite of one outbound request, and splitting them would mean two
+# wrappers over the same global for the same hostname.
+- insert:
+    - id: llm-agentrouter
+      name: '@lynn123411/dsh-llm-agentrouter'

package/lib/client.js

@@ -0,0 +1,256 @@
+window.__ModuleLoader__.load({
+	id: "@lynn123411/dsh-llm-agentrouter",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let jsx = require("react/jsx-runtime");
+		let react = require("react");
+
+		//#region styles
+		/*
+		 * Written by hand rather than emitted from a CSS module: the `clientBundle`
+		 * tsdown preset that produces those hashed class names is not published, so
+		 * this bundle owns a prefixed class set and injects it once. Every colour is
+		 * a shell design token, so the card follows the active theme.
+		 */
+		const CSS = [
+			".dshAr_card{display:flex;flex-direction:column;gap:10px}",
+			".dshAr_lead{margin:0;color:var(--dsw-alias-label-tertiary);font-size:13px;line-height:20px}",
+			".dshAr_choices{display:flex;gap:10px;margin:0;padding:0;border:0;flex-wrap:wrap}",
+			".dshAr_choice{flex:1 1 200px;min-width:0;display:flex;gap:9px;align-items:flex-start;padding:11px 13px;border:1px solid var(--dsw-alias-border-l2);border-radius:10px;background:var(--dsw-alias-bg-layer-3);cursor:pointer}",
+			".dshAr_choice:hover{background:var(--dsw-alias-interactive-bg-hover)}",
+			".dshAr_choice[data-selected=true]{border-color:var(--dsw-alias-state-business-primary);box-shadow:0 0 0 1px var(--dsw-alias-state-business-primary) inset}",
+			".dshAr_choice[data-disabled=true]{cursor:default;opacity:.55}",
+			".dshAr_choice input{margin:3px 0 0}",
+			".dshAr_choiceText{display:flex;flex-direction:column;gap:2px;min-width:0}",
+			".dshAr_choiceTitle{color:var(--dsw-alias-label-primary);font-size:14px;font-weight:600;line-height:20px}",
+			".dshAr_choiceHost{overflow-wrap:anywhere;color:var(--dsw-alias-label-tertiary);font-family:var(--ds-font-family-code);font-size:12px;line-height:17px}",
+			".dshAr_choiceHint{color:var(--dsw-alias-label-tertiary);font-size:12px;line-height:17px}",
+			".dshAr_status{margin:0;min-height:18px;color:var(--dsw-alias-label-tertiary);font-size:12px;line-height:18px}",
+			".dshAr_status[data-kind=error]{color:var(--dsw-alias-state-error-primary)}",
+		].join("");
+		const CSS_TAG_ID = "dsh-llm-agentrouter/EndpointCard.css";
+		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(CSS_TAG_ID) + "]") === null) {
+			const tag = document.createElement("style");
+			tag.setAttribute("data-plugin-css", CSS_TAG_ID);
+			tag.textContent = CSS;
+			document.head.append(tag);
+		}
+		//#endregion
+
+		//#region locales
+		/** Simplified Chinese dictionary and key source of truth. */
+		const zh = {
+			title: "AgentRouter 中转站",
+			description: "选择请求发往的端点。切换后立即生效，无需重启；模型列表不受影响。",
+			cn: "国内端点",
+			cnHint: "如您区域处于中国大陆则更适用于该端点",
+			intl: "国际端点",
+			intlHint: "请确保您的网络环境支持访问该端点后切换",
+			loading: "正在读取设置…",
+			unavailable: "此浏览器无法读取该设置。",
+			readOnly: "当前部署不允许写入设置。",
+			saving: "正在保存…",
+			saved: "已切换到%s。",
+			failed: "保存失败，设置未更改。",
+		};
+		/** English dictionary checked against the Chinese key set. */
+		const en = {
+			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",
+			cnHint: "Better suited if you are in mainland China",
+			intl: "International endpoint",
+			intlHint: "Make sure your network can reach this endpoint before switching",
+			loading: "Reading settings…",
+			unavailable: "This browser cannot read these settings.",
+			readOnly: "This deployment does not accept settings writes.",
+			saving: "Saving…",
+			saved: "Switched to %s.",
+			failed: "The save failed; the setting is unchanged.",
+		};
+		//#endregion
+
+		//#region endpoint card
+		/** The endpoint keys this card offers, in display order. */
+		const ENDPOINTS = ["cn", "intl"];
+		/** Field this card writes inside its namespace. */
+		const FIELD = "endpoint";
+
+		/**
+		 * Read the endpoint from a resolved section, falling back to the default the
+		 * schema documents when the section is not readable yet.
+		 * @param {unknown} value - the scope snapshot's resolved value.
+		 * @returns {string} an endpoint key.
+		 */
+		function endpointOf(value) {
+			const endpoint = typeof value === "object" && value !== null ? value.endpoint : undefined;
+			return ENDPOINTS.includes(endpoint) ? endpoint : "cn";
+		}
+
+		/**
+		 * Read the host table from a resolved section so each choice can show the
+		 * origin it actually means.
+		 * @param {unknown} value - the scope snapshot's resolved value.
+		 * @returns {Record<string, string>} host per endpoint key.
+		 */
+		function hostsOf(value) {
+			const hosts = typeof value === "object" && value !== null ? value.endpoints : undefined;
+			return typeof hosts === "object" && hosts !== null ? hosts : {};
+		}
+
+		/**
+		 * The relay endpoint card: one radio group over this plugin's own settings
+		 * namespace.
+		 *
+		 * A choice writes immediately rather than staging behind a Save button. The
+		 * namespace has exactly one user-facing field and the write is reversible in
+		 * one click, so a staged form would add a step without protecting anything —
+		 * and `scope.set` already fences the write with the revision it read.
+		 *
+		 * @param {object} props - the injected scope face plus the bound translator.
+		 * @returns {JSX.Element} the card.
+		 */
+		function EndpointCard({ scope, t }) {
+			const snapshot = react.useSyncExternalStore(
+				react.useCallback((listener) => scope.subscribe(listener), [scope]),
+				() => scope.getSnapshot(),
+			);
+			const [pending, setPending] = react.useState(null);
+			const [failed, setFailed] = react.useState(false);
+			const groupName = react.useId();
+
+			const selected = endpointOf(snapshot.value);
+			const hosts = hostsOf(snapshot.value);
+			const disabled = snapshot.status !== "ready" || !snapshot.writable || pending !== null;
+
+			const choose = (endpoint) => {
+				if (endpoint === selected || disabled) return;
+				setPending(endpoint);
+				setFailed(false);
+				Promise.resolve()
+					.then(() => scope.set(FIELD, endpoint))
+					.then(
+						() => {
+							setPending(null);
+						},
+						() => {
+							setPending(null);
+							setFailed(true);
+						},
+					);
+			};
+
+			const status = () => {
+				if (snapshot.status === "loading") return { kind: "info", text: t("loading") };
+				if (snapshot.status === "unavailable") return { kind: "error", text: t("unavailable") };
+				if (failed) return { kind: "error", text: t("failed") };
+				if (pending !== null) return { kind: "info", text: t("saving") };
+				if (!snapshot.writable) return { kind: "info", text: t("readOnly") };
+				return { kind: "info", text: "" };
+			};
+			const shown = status();
+
+			return jsx.jsxs("section", {
+				className: "dshAr_card",
+				"data-plugin-card": "llm-agentrouter",
+				"aria-busy": snapshot.status === "loading" || pending !== null,
+				children: [
+					jsx.jsx("h3", { children: t("title") }),
+					jsx.jsx("p", { className: "dshAr_lead", children: t("description") }),
+					jsx.jsxs("fieldset", {
+						className: "dshAr_choices",
+						children: [
+							jsx.jsx("legend", { hidden: true, children: t("title") }),
+							...ENDPOINTS.map((endpoint) => {
+								const active = (pending ?? selected) === endpoint;
+								return jsx.jsxs(
+									"label",
+									{
+										className: "dshAr_choice",
+										"data-endpoint": endpoint,
+										"data-selected": active ? "true" : undefined,
+										"data-disabled": disabled ? "true" : undefined,
+										children: [
+											jsx.jsx("input", {
+												type: "radio",
+												name: groupName,
+												value: endpoint,
+												checked: active,
+												disabled: disabled && !active,
+												onChange: () => choose(endpoint),
+											}),
+											jsx.jsxs("span", {
+												className: "dshAr_choiceText",
+												children: [
+													jsx.jsx("span", { className: "dshAr_choiceTitle", children: t(endpoint) }),
+													jsx.jsx("span", {
+														className: "dshAr_choiceHost",
+														children: hosts[endpoint] ?? "",
+													}),
+													jsx.jsx("span", { className: "dshAr_choiceHint", children: t(endpoint + "Hint") }),
+												],
+											}),
+										],
+									},
+									endpoint,
+								);
+							}),
+						],
+					}),
+					jsx.jsx("p", {
+						className: "dshAr_status",
+						"data-kind": shown.kind,
+						role: shown.kind === "error" ? "alert" : "status",
+						children: shown.text,
+					}),
+				],
+			});
+		}
+		//#endregion
+
+		//#region plugin
+		/** Dictionary namespace owned by this plugin. */
+		const NS = "settings.agentrouter";
+		/**
+		 * Settings namespace the Host half registers. Spelled rather than imported:
+		 * a browser bundle must not depend on a Host package, so both halves state
+		 * the same literal (the Host's is `AGENTROUTER_SETTINGS_NAMESPACE`).
+		 */
+		const SETTINGS_NS = "llm-agentrouter";
+		/** Services this plugin needs from the browser runtime. */
+		const inject = ["slots", "locale", "settingsScope"];
+
+		/**
+		 * Register the endpoint card into the plugin configuration tab.
+		 * @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", () =>
+				ctx.slots.register(
+					{
+						name: "settings.plugins.tab",
+						id: SETTINGS_NS,
+						order: 30,
+						label: () => t("title"),
+						locale: NS,
+						inject: () => ({ scope, t }),
+					},
+					EndpointCard,
+				),
+			);
+		}
+		//#endregion
+
+		exports.NS = NS;
+		exports.SETTINGS_NS = SETTINGS_NS;
+		exports.EndpointCard = EndpointCard;
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -0,0 +1,304 @@
+import z from '@deepseek-ai/schemastery'
+
+/**
+ * dsh-llm-agentrouter — the runtime half of the bundle of the same name.
+ *
+ * The bundle's `cordis.patch.yml` declares ONE relay route on the pi-ai adapter
+ * (`llm-pi-ai`); everything a request needs — protocol, model catalog, reasoning
+ * levels — is configuration there, not code.
+ *
+ * This plugin owns the two things that configuration cannot express, both of
+ * which are rewrites of the same outbound request:
+ *
+ * 1. **The User-Agent.** The relay authenticates its *client* by `User-Agent`,
+ *    accepting only the exact value it requires, and `dsh-llm-pi-ai`
+ *    deliberately strips any profile header colliding with
+ *    its own attribution before appending
+ *    `user-agent: deepseek-harness/<version>`. Attribution is mandatory by
+ *    design ("a white-label deployment may replace it, but not suppress it"), so
+ *    the substitution has to happen below the adapter — at the `fetch` the
+ *    provider SDK resolves from the global scope when it builds its client.
+ *
+ * 2. **The endpoint.** The relay serves the same models at a domestic and an
+ *    international origin. That is one deployment-wide preference, not a model
+ *    property, so it is a single setting here rather than a route per endpoint —
+ *    which would list every model twice in the picker. The adapter cannot read
+ *    this namespace, so the route's `baseURL` names a deliberately unresolvable
+ *    sentinel host and the fence substitutes the chosen origin on the way out.
+ *
+ * The fence is therefore deliberately narrow: it rewrites one header and, for
+ * the sentinel alone, one origin; every other request goes to the previous
+ * `fetch` untouched. It is installed through `ctx.effect()`, so stopping or
+ * reloading the plugin restores the `fetch` it replaced.
+ *
+ * @module dsh-llm-agentrouter
+ */
+
+/** Stable Cordis plugin name. */
+const name = 'llm-agentrouter'
+
+/**
+ * Settings namespace this plugin owns.
+ *
+ * It is also the key the browser half registers its card under, so the two
+ * halves meet here without either importing the other.
+ */
+const AGENTROUTER_SETTINGS_NAMESPACE = 'llm-agentrouter'
+
+const Config = z.object({
+  /**
+   * Which relay origin outbound requests are sent to. The whole point of the
+   * plugin's settings card: one choice, applied to every model on the route.
+   */
+  endpoint: z
+    .union([z.const('cn'), z.const('intl')])
+    .default('cn')
+    .description('relay endpoint requests are sent to: cn (domestic) or intl (international)'),
+  /**
+   * Host per endpoint key. Configuration rather than a constant so a moved
+   * origin is a settings edit, not a release.
+   */
+  endpoints: z
+    .dict(z.string())
+    .default({ cn: 'ps.air-outer.com', intl: 'agentrouter.org' })
+    .description('host for each endpoint key'),
+  /**
+   * The host the route's `baseURL` names. Requests to it are rewritten to the
+   * selected endpoint; it must stay unresolvable so an unfenced request fails
+   * loudly instead of reaching some real server (`.internal` is reserved).
+   */
+  sentinel: z
+    .string()
+    .default('relay.agentrouter.internal')
+    .description('placeholder host in the route baseURL that the fence replaces with the selected endpoint'),
+  /**
+   * The exact User-Agent the relay accepts. It is the whole authentication of
+   * the client (the API key authenticates the account), so it is configuration
+   * rather than a constant: the relay may require a different value later.
+   */
+  userAgent: z
+    .string()
+    .default('claude-cli/2.1.161 (external, cli)')
+    .description('User-Agent value sent to the relay in place of the harness attribution'),
+  /** Report the installed fence once on activation. */
+  announce: z.boolean().default(true),
+  /**
+   * Hint appended to a 402 quota error from the relay. The relay answers
+   * Claude / GPT budget-pool exhaustion with HTTP 402 and a JSON error body
+   * mislabelled as an event stream; the fence keeps that original message and
+   * appends this plain-language explanation. Empty string disables it.
+   */
+  quotaHint: z
+    .string()
+    .default('Claude / GPT 本批额度已用完，请等待下一批投放。')
+    .description('text appended to relay 402 quota errors'),
+})
+
+/**
+ * Resolve a `fetch` argument to its URL without consuming a request body.
+ * @param {unknown} input - the first `fetch` argument.
+ * @returns {URL | undefined} the parsed URL, or undefined when it is not one.
+ */
+function urlOf(input) {
+  try {
+    if (typeof input === 'string') return new URL(input)
+    if (input instanceof URL) return input
+    if (typeof input === 'object' && input !== null && typeof input.url === 'string') return new URL(input.url)
+  } catch {
+    return undefined
+  }
+  return undefined
+}
+
+/**
+ * The hosts one resolved section wants rewritten, and how.
+ *
+ * Derived per request from the live section so a settings change takes effect on
+ * the next call with no reload. Endpoint hosts are included as themselves: a
+ * request already addressed to a real relay origin still needs the User-Agent.
+ *
+ * @param {ReturnType<typeof Config>} config - the resolved section.
+ * @returns {Map<string, string>} lowercase source host to destination host.
+ */
+function routingTable(config) {
+  const table = new Map()
+  const selected = config.endpoints[config.endpoint]
+  const sentinel = config.sentinel.trim().toLowerCase()
+  if (sentinel.length > 0 && typeof selected === 'string' && selected.trim().length > 0) {
+    table.set(sentinel, selected.trim())
+  }
+  for (const host of Object.values(config.endpoints)) {
+    if (typeof host !== 'string') continue
+    const trimmed = host.trim()
+    if (trimmed.length > 0) table.set(trimmed.toLowerCase(), trimmed)
+  }
+  return table
+}
+
+/**
+ * Wrap one `fetch` so relay requests carry the relay User-Agent, and sentinel
+ * requests additionally go to the selected endpoint.
+ *
+ * The wrapper never reads or rebuilds a body as a rule: for the shape every
+ * provider SDK in this harness uses (url plus an init object) it copies
+ * `init` and replaces only its headers. A bare `Request` is re-created with
+ * `duplex: 'half'` so a streamed body survives the clone.
+ *
+ * The one exception is a relay 402 quota-exhaustion response: the body is a
+ * small JSON error body mislabelled as `text/event-stream`, which provider
+ * SDKs otherwise surface as an opaque transport failure. The fence reads that
+ * body, keeps the original error message, appends the configured hint, and
+ * rebuilds it as `application/json`. Every other response is left untouched.
+ *
+ * @param {typeof fetch} native - the fetch this wrapper delegates to.
+ * @param {() => ReturnType<typeof Config>} current - reads the live section.
+ * @returns {typeof fetch} the wrapping fetch.
+ */
+function fenceFetch(native, current) {
+  return function agentRouterFetch(input, init) {
+    const url = urlOf(input)
+    if (url === undefined) return native(input, init)
+
+    const config = current()
+    const destination = routingTable(config).get(url.host.toLowerCase())
+    if (destination === undefined) return native(input, init)
+
+    const isRequest = typeof Request === 'function' && input instanceof Request
+    const headers = new Headers(init?.headers ?? (isRequest ? input.headers : undefined))
+    headers.set('user-agent', config.userAgent)
+
+    // Same host means the sentinel was not involved: rewrite the header only,
+    // and leave the caller's own URL object or Request identity alone.
+    let pending
+    if (destination.toLowerCase() === url.host.toLowerCase()) {
+      if (isRequest && init === undefined) pending = native(new Request(input, { headers, duplex: 'half' }))
+      else pending = native(input, { ...init, headers })
+    } else {
+      const target = new URL(url)
+      target.host = destination
+      if (isRequest) pending = native(new Request(target, { ...(init ?? {}), ...requestInitOf(input), headers, duplex: 'half' }))
+      else pending = native(target, { ...init, headers })
+    }
+
+    // The one response this wrapper rewrites: the relay answers Claude / GPT
+    // budget-pool exhaustion with HTTP 402 and a JSON error body mislabelled
+    // as an event stream, which provider SDKs otherwise surface as an opaque
+    // transport failure. Annotate those with the configured hint; every other
+    // response passes through untouched.
+    return config.quotaHint === '' ? pending : annotateQuotaError(pending, config.quotaHint)
+  }
+}
+
+/**
+ * The relay answers Claude / GPT budget-pool exhaustion with HTTP 402 and a
+ * JSON error body mislabelled as 'text/event-stream'; left alone, provider
+ * SDKs surface it as an opaque transport failure rather than the API error it
+ * is. This rebuilds such a response as 'application/json', keeping the
+ * original error message and appending the hint. Every other response passes
+ * through untouched.
+ *
+ * @param {Promise<Response>} pending - the relay fetch promise.
+ * @param {string} hint - text appended to the original error message; empty
+ *   disables the rewrite (the caller should not call this then).
+ * @returns {Promise<Response>} the (possibly rebuilt) response.
+ */
+function annotateQuotaError(pending, hint) {
+  return pending.then((response) => {
+    if (response.status !== 402) return response
+    const type = (response.headers.get('content-type') ?? '').toLowerCase()
+    if (!type.includes('event-stream') && !type.includes('json')) return response
+    return response.text().then((text) => {
+      let parsed
+      let message
+      try {
+        parsed = JSON.parse(text)
+        message = parsed?.error?.message
+      } catch {
+        message = undefined
+      }
+      const headers = new Headers(response.headers)
+      if (typeof message !== 'string' || message.length === 0) {
+        // Not a JSON error body; hand the bytes back unchanged.
+        return new Response(text, { status: response.status, statusText: response.statusText, headers })
+      }
+      headers.set('content-type', 'application/json')
+      // Only annotate quota-exhaustion errors; other 402s pass through with
+      // the original body so the provider SDK builds its own error message.
+      if (/\b(?:quota|budget)\b/i.test(message)) {
+        parsed.error.message = message + '\n' + hint
+      }
+      return new Response(JSON.stringify(parsed), { status: response.status, statusText: response.statusText, headers })
+    })
+  })
+}
+
+/**
+ * The fields of a `Request` that must survive re-addressing it.
+ *
+ * `new Request(url, request)` is not available — the second argument must be an
+ * init — so the parts a relay call depends on are copied explicitly. The body is
+ * passed by reference, never read.
+ *
+ * @param {Request} request - the request being re-addressed.
+ * @returns {RequestInit} an init carrying its method, body, and transfer flags.
+ */
+function requestInitOf(request) {
+  return {
+    method: request.method,
+    ...(request.body === null || request.method === 'GET' || request.method === 'HEAD' ? {} : { body: request.body }),
+    ...(request.signal === undefined ? {} : { signal: request.signal }),
+    credentials: request.credentials,
+    redirect: request.redirect,
+    referrer: request.referrer,
+    integrity: request.integrity,
+    keepalive: request.keepalive,
+    mode: request.mode,
+  }
+}
+
+/**
+ * Install the relay fence and expose its endpoint choice as a settings section.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the plugin's context.
+ * @param {ReturnType<typeof Config>} config - resolved entry configuration.
+ */
+function apply(ctx, config) {
+  // The section is the authority while a settings service exists; the composed
+  // entry is the fallback, so the fence works identically with no settings
+  // plane at all (headless, or before the service mounts).
+  let current = () => config
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.installSection(ctx, AGENTROUTER_SETTINGS_NAMESPACE, Config, config, {
+      setSource: (source) => {
+        current = source
+      },
+      onChange: () => {},
+    })
+  })
+
+  ctx.effect(() => {
+    const previous = globalThis.fetch
+    if (typeof previous !== 'function') {
+      ctx.logger.warn('llm-agentrouter: no global fetch to fence; relay requests will be unroutable and rejected')
+      return () => {}
+    }
+    const fenced = fenceFetch(previous, () => current())
+    globalThis.fetch = fenced
+    return () => {
+      // Restore only what this plugin installed: a later wrapper layered on top
+      // owns the global now, and clobbering it would drop that one's rewrite.
+      if (globalThis.fetch === fenced) globalThis.fetch = previous
+    }
+  })
+
+  if (config.announce) {
+    const table = routingTable(config)
+    ctx.logger.info(
+      'llm-agentrouter: endpoint %c (%c), sending %c',
+      config.endpoint,
+      table.get(config.sentinel.trim().toLowerCase()) ?? 'unrouted',
+      config.userAgent,
+    )
+  }
+}
+
+export { AGENTROUTER_SETTINGS_NAMESPACE, Config, apply, name }

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@lynn123411/dsh-llm-agentrouter",
+  "version": "0.2.0",
+  "description": "AgentRouter 中转聚合：一条 pi-ai 路由承载多模型 + 国内/国际端点一键切换（设置卡片）+ 出站请求 User-Agent/403-配额改写围栏。aqiu817/dsh-llm-agentrouter 的 alpha.5 兼容分叉。",
+  "keywords": [
+    "deepseek-harness",
+    "dsh-plugin",
+    "cordis",
+    "llm",
+    "agentrouter"
+  ],
+  "homepage": "https://github.com/tttnny/my-dsh#readme",
+  "bugs": "https://github.com/tttnny/my-dsh/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tttnny/my-dsh.git",
+    "directory": "plugins/dsh-llm-agentrouter"
+  },
+  "license": "MIT",
+  "author": "lynn123411",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "js-yaml": "^5.4.1",
+    "react": "18.3.1",
+    "react-test-renderer": "18.3.1"
+  }
+}