@lynn123411/dsh-llm-agentrouter 0.3.1 → 0.4.1

package/README.md

@@ -4,12 +4,12 @@ AgentRouter 中转聚合插件：把同一家中转的多个模型收拢为一
 
 ## 特性
 
-- **单路由多模型**：Claude Opus 5、GPT-5.6-sol 等走同一 `agentrouter` 路由，`reasoningEffort` 档位与兼容开关按实测探针手写声明，模型列表不翻倍。
-- **模型列表可编辑**：设置卡片里直接列出这条路由的模型，`更新` 向中转站询问它现有的模型 ID（只补缺失的、不动已有条目），每个模型的 ID / 显示名 / 上下文窗口 / 最大输出 / 输入模态 / 各推理档位与线上取值都可改，保存后下一个请求即生效；新补入的模型默认 1048576 上下文、131072 输出、text+image、off..max 七档。改的就是路由自己的 `models`（与内核「设置 - 模型」页同一份数据），patch 里手写的那几条是「重置」的基线。
+- **单路由多模型**：Claude Opus 5、GPT-5.6-sol 等走同一 `agentrouter` 路由，`reasoningEfforts` 各档位与 `compat` 开关按实测探针手写声明，模型列表不翻倍。
+- **模型列表可编辑**：设置卡片里直接列出这条路由的模型，`更新` 向中转站询问它现有的模型 ID（只补缺失的、不动已有条目），每个模型的 ID / 显示名 / 上下文窗口 / 最大输出 / 输入模态 / 各推理档位与线上取值都可改，保存后下一个请求即生效；新补入的模型默认 1048576 上下文、131072 输出、text+image、off..max 七档。改的就是路由自己的 `models`——`llm-pi-ai` 这条 profile 插件配置里的 `providers.agentrouter.models`，内核「设置 - 模型」页对该路由注册的写入地址也正是这里，两边同一份数据；patch 里手写的那几条是「重置」的基线。
 - **端点一键切换**：设置卡片两个大选项（国内端点 / 国际端点，附带真实 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 错误体改写为可读提示。
-- **内核设置接入**：宿主用 `ctx.settings.installSection` 注册设置段（`ctx.inject(['settings'])`），客户端卡片挂在共享设置页的子 slot；设置命名空间为 `llm-agentrouter`。
+- **内核设置接入**：本插件 `Config` 里需要实时生效的字段都声明为 `.volatile()`，设置面据此派生表单、并把配置写回同一批引用（`ctx.inject(['settings'])` + `ctx.settings.configure({ auto: false })` 记下「本插件自带 UI」）；客户端卡片挂在共享设置页的子 slot，读写的是 `llm-agentrouter` 这条 profile 插件配置，条目 id 即设置命名空间。
 
 ## 安装
 

package/cordis.patch.yml

@@ -56,15 +56,15 @@
 # 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 中转站.
+# changed: 设置 → API中转 → AgentRouter 中转站.
 #
 # WHOLE-OBJECT OVERWRITE, NOT A DEEP MERGE — RE-CHECK ON EVERY dsh-base BUMP
 # The loader applies a patch entry as `target[key] = value`
-# (applyEntryPatches, 0.1.6-alpha.2), so the `config:` below REPLACES the
-# llm-pi-ai row's whole config object: nothing a default config carried survives,
-# at any depth. That is safe today only because dsh-base mounts
-# `- id: llm-pi-ai` with a `name:` and no `config:` at all
-# (dsh-base/cordis.patch.yml:114-115), so there is nothing to lose. If a future
+# (applyEntryPatches, @deepseek-ai/dsh-app-boot), so the `config:` below
+# REPLACES the llm-pi-ai row's whole config object: nothing a default config
+# carried survives, at any depth. That is safe today only because dsh-base
+# mounts `- id: llm-pi-ai` with a `name:` and no `config:` at all
+# (dsh-base/cordis.patch.yml:127-128), so there is nothing to lose. If a future
 # dsh-base gives that row a default config, this patch swallows it SILENTLY —
 # diff the shipped llm-pi-ai row against this file on every dsh-base bump and
 # fold whatever it adds into the `providers:` map below.

package/lib/client.js

@@ -185,9 +185,9 @@ window.__ModuleLoader__.load({
 		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.
+		 * Read the endpoint from a resolved entry, falling back to the default the
+		 * schema documents when the entry is not readable yet.
+		 * @param {unknown} value - the form snapshot's resolved value.
 		 * @returns {string} an endpoint key.
 		 */
 		function endpointOf(value) {
@@ -198,7 +198,7 @@ window.__ModuleLoader__.load({
 		/**
 		 * 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.
+		 * @param {unknown} value - the form snapshot's resolved value.
 		 * @returns {Record<string, string>} host per endpoint key.
 		 */
 		function hostsOf(value) {
@@ -207,23 +207,23 @@ window.__ModuleLoader__.load({
 		}
 
 		/**
-		 * The relay card: the endpoint radio group over this plugin's own settings
-		 * namespace, above the model list the route in `llm-pi-ai` actually serves.
+		 * The relay card: the endpoint radio group over this plugin's own profile
+		 * entry config, above the model list the route in `llm-pi-ai` actually serves.
 		 *
 		 * 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. The
-		 * two halves are independent: each reads and writes its own namespace, so a
-		 * deployment that exposes only one of them still renders the other.
+		 * and the form's own `set` already fences the write with the revision it read.
+		 * The two halves are independent: each reads and writes its own entry's form,
+		 * so a deployment that exposes only one of them still renders the other.
 		 *
-		 * @param {object} props - the injected scope faces plus the bound translator.
+		 * @param {object} props - the injected config forms plus the bound translator.
 		 * @returns {JSX.Element} the card.
 		 */
-		function EndpointCard({ scope, t, routeScope, operations }) {
+		function EndpointCard({ form, t, routeForm, operations }) {
 			const snapshot = react.useSyncExternalStore(
-				react.useCallback((listener) => scope.subscribe(listener), [scope]),
-				() => scope.getSnapshot(),
+				react.useCallback((listener) => form.subscribe(listener), [form]),
+				() => form.getSnapshot(),
 			);
 			const [pending, setPending] = react.useState(null);
 			const [failed, setFailed] = react.useState(false);
@@ -238,10 +238,14 @@ window.__ModuleLoader__.load({
 				setPending(endpoint);
 				setFailed(false);
 				Promise.resolve()
-					.then(() => scope.set(FIELD, endpoint))
+					.then(() => form.set(FIELD, endpoint))
 					.then(
-						() => {
+						// The form answers whether the Host accepted the write and runs its own
+						// recovery read; a refusal and a transport rejection are one outcome here:
+						// the choice did not land, so the card says so and leaves the section alone.
+						(accepted) => {
 							setPending(null);
+							if (!accepted) setFailed(true);
 						},
 						() => {
 							setPending(null);
@@ -313,7 +317,7 @@ window.__ModuleLoader__.load({
 						role: shown.kind === "error" ? "alert" : "status",
 						children: shown.text,
 					}),
-					routeScope === undefined ? null : jsx.jsx(ModelList, { routeScope, operations, t }),
+					routeForm === undefined ? null : jsx.jsx(ModelList, { routeForm, operations, t }),
 				],
 			});
 		}
@@ -321,12 +325,14 @@ window.__ModuleLoader__.load({
 
 		//#region model list
 		/**
-		 * The pi-ai settings namespace the relay route is declared in. This plugin's
-		 * model list is NOT its own preference: it is the `agentrouter` route's
-		 * `models` array, the same data the kernel's Models page edits, which is why
-		 * editing it is what changes the model picker. Spelled rather than imported,
-		 * for the same reason as SETTINGS_NS in the plugin region below: a browser
-		 * bundle must not depend on a Host package.
+		 * The profile entry id the relay route is declared in — `llm-pi-ai`'s own
+		 * patch row, which the adapter also registers as the settings namespace of
+		 * its configurable providers (`settingsPath: ["providers", route]`). This
+		 * plugin's model list is NOT its own preference: it is the `agentrouter`
+		 * route's `models` array, the same entry and the same path the kernel's
+		 * Models page edits, which is why editing it is what changes the model
+		 * picker. Spelled rather than imported, for the same reason as SETTINGS_NS in
+		 * the plugin region below: a browser bundle must not depend on a Host package.
 		 */
 		const PI_AI_SETTINGS_NS = "llm-pi-ai";
 		/** The route key inside that namespace this plugin owns. */
@@ -681,8 +687,8 @@ window.__ModuleLoader__.load({
 		}
 
 		/**
-		 * Store faces for a caller that injects no Host operations — an older Host,
-		 * or a test rendering this component directly.
+		 * Store faces for a caller that injects no Host operations — a test rendering
+		 * this component directly, or a registration whose optional Remote is absent.
 		 */
 		const NO_OPERATIONS_STORE = { subscribe: () => () => {}, snapshot: () => 0 };
 
@@ -691,24 +697,25 @@ window.__ModuleLoader__.load({
 		 * serves, the 更新 action that asks the relay what it currently offers, and
 		 * the write that puts the result back on the route.
 		 *
-		 * Reads come from the shared settings mirror through the scope bound to
-		 * `llm-pi-ai`, so the card and the kernel's Models page can never disagree
-		 * about the route. Writes go through the Remote call the operations were
-		 * built with, NOT through `scope.set`: the mirror's write path reports a
-		 * refusal by silently reloading, while this card has to show the Host's own
-		 * diagnostic — a stale revision, or a payload the adapter's schema refused.
+		 * Reads come from the shared config form of the `llm-pi-ai` profile entry, so
+		 * the card and the kernel's Models page can never disagree about the route.
+		 * Writes go through the Remote call the operations were built with, NOT
+		 * through the form's `mutate`: that path answers only whether the Host
+		 * accepted, while this card has to show the Host's own diagnostic — a stale
+		 * revision, or a payload the adapter's schema refused. The kernel's own
+		 * Models page writes the same namespace the same way.
 		 *
 		 * An edit lives in this component until 保存; 重置 drops the draft and, when
 		 * the user layer owns the list, removes that override so the composition's
 		 * hand-declared list serves again.
 		 *
-		 * @param {object} props - the route scope, the Host operations, and `t`.
+		 * @param {object} props - the route form, the Host operations, and `t`.
 		 * @returns {JSX.Element} the model list.
 		 */
-		function ModelList({ routeScope, operations, t }) {
+		function ModelList({ routeForm, operations, t }) {
 			const snapshot = react.useSyncExternalStore(
-				react.useCallback((listener) => routeScope.subscribe(listener), [routeScope]),
-				() => routeScope.getSnapshot(),
+				react.useCallback((listener) => routeForm.subscribe(listener), [routeForm]),
+				() => routeForm.getSnapshot(),
 			);
 			const ops = operations ?? {};
 			// The optional Remote faces mount after this plugin activates, so the
@@ -1134,27 +1141,30 @@ window.__ModuleLoader__.load({
 		/** 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`).
+		 * This plugin's profile entry id — its settings namespace, and the key its
+		 * config form is addressed by. 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"];
+		const inject = ["slots", "locale", "configForms"];
 
 		/**
 		 * Register the endpoint card inside the shared 「API中转」 page, which this
-		 * plugin carries the shell for and claims when it activates first.
+		 * plugin carries the shell for and claims when it activates first, and bind
+		 * the two config forms it reads (this plugin's own entry, and the adapter's
+		 * route) out of the shared configuration forms service.
 		 * @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 });
-			// The model list is not this plugin's own section: it is the `agentrouter`
-			// route inside the adapter's namespace, the same document the kernel's
-			// Models page edits, so the card derives from that namespace's mirror.
-			const routeScope = ctx.settingsScope.bind({ namespace: PI_AI_SETTINGS_NS });
+			const form = ctx.configForms.get(SETTINGS_NS);
+			// The model list is not this plugin's own entry: it is the `agentrouter`
+			// route inside the adapter's entry, the same document the kernel's Models
+			// page edits, so the card derives from that entry's shared config form.
+			const routeForm = ctx.configForms.get(PI_AI_SETTINGS_NS);
 			// Both Host faces are OPTIONAL reads: a deployment whose Client assembly
 			// mounts neither still shows the endpoint switch, and the model list
 			// degrades to read-only with the reason rendered instead of going blank.
@@ -1220,14 +1230,14 @@ window.__ModuleLoader__.load({
 				ctx.slots.register(
 					{
 						name: RELAY_ITEM_SLOT,
-						// id = the Host settings namespace; the shared page filters its
+						// id = this plugin's profile entry id; the shared page filters its
 						// panels by this id, so it must be the plugin's own key.
 						id: SETTINGS_NS,
 						order: 20,
 						// Rendered as the card's tab title inside the shared page.
 						label: () => t("title"),
 						locale: NS,
-						inject: () => ({ scope, t, routeScope, operations }),
+						inject: () => ({ form, t, routeForm, operations }),
 					},
 					EndpointCard,
 				),

package/lib/index.js

@@ -38,10 +38,11 @@ import z from '@deepseek-ai/schemastery'
 const name = 'llm-agentrouter'
 
 /**
- * Settings namespace this plugin owns.
+ * This plugin's profile entry id, which is also its settings namespace and the
+ * license key its configuration form is addressed by.
  *
- * It is also the key the browser half registers its card under, so the two
- * halves meet here without either importing the other.
+ * The id is declared by the bundle patch (`cordis.patch.yml`), and the browser
+ * half addresses the same literal without importing this module.
  */
 const AGENTROUTER_SETTINGS_NAMESPACE = 'llm-agentrouter'
 
@@ -53,6 +54,7 @@ const Config = z.object({
   endpoint: z
     .union([z.const('cn'), z.const('intl')])
     .default('cn')
+    .volatile()
     .description('relay endpoint requests are sent to: cn (domestic) or intl (international)'),
   /**
    * Host per endpoint key. Configuration rather than a constant so a moved
@@ -61,6 +63,7 @@ const Config = z.object({
   endpoints: z
     .dict(z.string())
     .default({ cn: 'ps.air-outer.com', intl: 'agentrouter.org' })
+    .volatile()
     .description('host for each endpoint key'),
   /**
    * The host the route's `baseURL` names. Requests to it are rewritten to the
@@ -70,6 +73,7 @@ const Config = z.object({
   sentinel: z
     .string()
     .default('relay.agentrouter.internal')
+    .volatile()
     .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
@@ -79,6 +83,7 @@ const Config = z.object({
   userAgent: z
     .string()
     .default('claude-cli/2.1.161 (external, cli)')
+    .volatile()
     .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),
@@ -91,9 +96,19 @@ const Config = z.object({
   quotaHint: z
     .string()
     .default('Claude / GPT 本批额度已用完，请等待下一批投放。')
+    .volatile()
     .description('text appended to relay 402 quota errors'),
 })
 
+/**
+ * Every field the fence reads carries `.volatile()` and is therefore a live
+ * reference rather than a snapshot: the settings plane writes the reference in
+ * place, the next request reads the new value, and no reload intervenes. That
+ * is also what makes these fields the ones the schema-derived config form
+ * shows and accepts writes to (`ctx.settings.describe`/`mutate`). `announce`
+ * is deliberately plain: it is read once, on activation.
+ */
+
 /**
  * Resolve a `fetch` argument to its URL without consuming a request body.
  * @param {unknown} input - the first `fetch` argument.
@@ -122,12 +137,13 @@ function urlOf(input) {
  */
 function routingTable(config) {
   const table = new Map()
-  const selected = config.endpoints[config.endpoint]
-  const sentinel = config.sentinel.trim().toLowerCase()
+  const endpoints = config.endpoints.get()
+  const selected = endpoints[config.endpoint.get()]
+  const sentinel = config.sentinel.get().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)) {
+  for (const host of Object.values(endpoints)) {
     if (typeof host !== 'string') continue
     const trimmed = host.trim()
     if (trimmed.length > 0) table.set(trimmed.toLowerCase(), trimmed)
@@ -151,21 +167,22 @@ function routingTable(config) {
  * 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.
+ * @param {ReturnType<typeof Config>} config - the entry configuration; every
+ *   field read here is a `.volatile()` reference, so the value is the one the
+ *   settings plane last wrote, not the one activation resolved.
  * @returns {typeof fetch} the wrapping fetch.
  */
-function fenceFetch(native, current) {
+function fenceFetch(native, config) {
   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)
+    headers.set('user-agent', config.userAgent.get())
 
     // Same host means the sentinel was not involved: rewrite the header only,
     // and leave the caller's own URL object or Request identity alone.
@@ -185,7 +202,8 @@ function fenceFetch(native, current) {
     // 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)
+    const hint = config.quotaHint.get()
+    return hint === '' ? pending : annotateQuotaError(pending, hint)
   }
 }
 
@@ -257,22 +275,18 @@ function requestInitOf(request) {
 }
 
 /**
- * Install the relay fence and expose its endpoint choice as a settings section.
+ * Install the relay fence and declare how this plugin's configuration is edited.
  * @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: () => {},
-    })
+  // The settings plane derives this plugin's form from the Config schema above
+  // and writes it back into the same `.volatile()` references the fence reads.
+  // `auto: false` because the endpoint card owns this plugin's UI (lib/client.js);
+  // the registration is optional, so a deployment with no settings service at all
+  // (headless, or before the service mounts) keeps the composed entry as-is.
+  ctx.inject(['settings'], (child) => {
+    child.effect(() => child.settings.configure({ auto: false }, ctx.fiber))
   })
 
   ctx.effect(() => {
@@ -281,7 +295,7 @@ function apply(ctx, config) {
       ctx.logger.warn('llm-agentrouter: no global fetch to fence; relay requests will be unroutable and rejected')
       return () => {}
     }
-    const fenced = fenceFetch(previous, () => current())
+    const fenced = fenceFetch(previous, config)
     globalThis.fetch = fenced
     return () => {
       // Restore only what this plugin installed: a later wrapper layered on top
@@ -294,9 +308,9 @@ function apply(ctx, config) {
     const table = routingTable(config)
     ctx.logger.info(
       'llm-agentrouter: endpoint %s (%s), sending %s',
-      config.endpoint,
-      table.get(config.sentinel.trim().toLowerCase()) ?? 'unrouted',
-      config.userAgent,
+      config.endpoint.get(),
+      table.get(config.sentinel.get().trim().toLowerCase()) ?? 'unrouted',
+      config.userAgent.get(),
     )
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lynn123411/dsh-llm-agentrouter",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "AgentRouter 中转聚合：一条 pi-ai 路由承载多模型（设置卡片内可从中转站拉取、逐个编辑模型与参数）+ 国内/国际端点一键切换 + 出站请求 User-Agent/402-配额改写围栏。模型列表写入内核「设置 - 模型」页所编辑的同一份 llm-pi-ai 路由数据。",
   "keywords": [
     "deepseek-harness",
@@ -52,13 +52,13 @@
   },
   "engines": {
     "node": ">=22",
-    "dsh": "0.1.6-alpha.2"
+    "dsh": ">=0.1.7-rc.2"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/schemastery": "^3.18.4"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.4"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {