dsh-model-params 0.1.5 → 0.1.7

package/README.md

@@ -2,10 +2,12 @@
 
 ## English
 
-**Current release: 0.1.5** — models.dev parameter assistant inside the official DeepSeek Harness Models settings page. This release adds a documented install path: `dsh plugin --profile web add dsh-model-params`.
+**Current release: 0.1.6** — Portable settings transport: the plugin now resolves the official pi-ai settings scope on both the `settingsScope` (≤ 0.1.5) and `configForms` (≥ 0.1.7-rc.1) hosts, so the provider card keeps working across the rename.
 
 For every configured `llm-pi-ai` provider card (custom OpenAI-compatible gateways such as the ones you add under Settings → Models), a `models.dev 参数` control fetches the official models.dev records for the provider's configured model ids and proposes the metadata pi-ai needs: context window, max output tokens, and reasoning-effort levels. One click writes the merged `models` array back to that provider profile through the official revision-aware Settings API.
 
+On hosts that declare the root-scope `settings.section` list seat, that same card is also registered as a first-class settings page — identity `YOTK · Model Params`, id `yotk-model-params`, order `63` — additive beside the Models-page extension and never an activation gate. The page needs nothing selected elsewhere: it reads the `llm-pi-ai` providers you have configured through the same settings scope, addresses the first one (with a picker whenever several exist), and states plainly when the namespace is loading, unserved, or has no provider yet.
+
 Safety boundaries:
 
 - The control never auto-writes. You open the panel, review the per-model diff, then click **应用并写入该 provider** — it writes only that provider's `models` array in the `llm-pi-ai` namespace.
@@ -20,6 +22,8 @@ models.dev model ids may collide across catalog providers; the matcher prefers t
 
 面向 DeepSeek Harness Web 官方 **设置 → 模型** 页的 models.dev 参数助手。每个已配置的 `llm-pi-ai` provider 卡片内提供 `models.dev 参数` 入口：按该 provider 的模型 id 在 models.dev 官方目录中匹配，预览上下文窗口 / max 输出 / 推理档位，确认后一次性写回该 provider 的 `models` 配置（官方 revision-aware Settings API，仅写 `llm-pi-ai` 命名空间下当前 provider 的数组）。
 
+在声明根级 `settings.section` 列表座的宿主上，同一张卡片还会注册为设置页的一级入口 —— 标识 `YOTK · Model Params`、id `yotk-model-params`、order `63` —— 与「设置 → 模型」页的扩展并存，且从不成为激活门槛。该页不依赖别处选中的 provider：它通过同一设置作用域读取已配置的 `llm-pi-ai` provider，默认处理第一个（配置多个时可在页内切换），并在命名空间仍在读取、宿主未提供或尚未配置 provider 时明确说明。
+
 - 默认仅补缺失参数；勾选「覆盖已有值」才替换差异值。
 - 窗口顶部可启用一个所有 provider 共用的 models.dev 请求代理并编辑地址；它只影响下一次参数查询，不改变任何 LLM provider 的 `baseURL`。
 - Host 只负责拉取并缓存 models.dev 目录（6 小时，支持公共代理或 `HTTPS_PROXY` 回退），不接触任何 LLM 配置与凭据。
@@ -31,7 +35,7 @@ models.dev model ids may collide across catalog providers; the matcher prefers t
 dsh plugin --profile web add dsh-model-params
 ```
 
-Restart the existing DSH Web process afterwards: the Host scans the browser plugin roster at startup, so the provider-card control appears only after that restart. Then open **Settings → Models** and look for `models.dev 参数` on a configured provider card.
+Restart the existing DSH Web process afterwards: the Host scans the browser plugin roster at startup, so the provider-card control appears only after that restart. Then open **Settings → Models** and look for `models.dev 参数` on a configured provider card. Where the host also exposes the settings page seat, the same control is one click deep in **Settings** as **YOTK · Model Params**.
 
 Local development, from this package directory:
 

package/lib/client.js

@@ -3,12 +3,18 @@
 // Renders a compact "models.dev 参数" affordance inside every official
 // llm-pi-ai provider card on the Models settings page
 // (settings.models.provider-card, keyed by the pi-ai settings namespace).
-// It reads the current provider profile from the official llm-pi-ai Settings
-// scope, asks the Host for the matching models.dev records, previews the
-// proposed context / max-output / reasoning-effort values per model, and —
-// only on an explicit "应用" click — writes the merged models array back
-// through the revision-aware official Settings API. Default policy fills
-// missing parameters only; "覆盖已有值" also replaces differing ones.
+// The same card is ALSO registered on the root-scope `settings.section` list
+// seat (id `yotk-model-params`), which makes it a first-class settings page of
+// its own on hosts that declare that seat. That seat's owner share is
+// `{ close }` alone, so the page is handed no provider: it resolves one of the
+// routes the llm-pi-ai namespace itself declares, from the same scope and
+// never through a second read path.
+// Either way it reads the current provider profile from the official llm-pi-ai
+// Settings scope, asks the Host for the matching models.dev records, previews the
+// proposed context / max-output / reasoning-effort values per model, and — only
+// on an explicit "应用" click — writes the merged models array back through the
+// revision-aware official Settings API. Default policy fills missing parameters
+// only; "覆盖已有值" also replaces differing ones.
 // The plugin never auto-writes, never touches other providers/namespaces,
 // and never sends credentials anywhere.
 
@@ -22,6 +28,30 @@ window.__ModuleLoader__.load({
 
     const PI_NS = 'llm-pi-ai'
     const API = '/api/model-params/lookup'
+
+    // ── settings-scope portability (DSH 0.1.5 ↔ 0.1.7-rc.1) ──────────────────
+    //
+    // This plugin owns no settings namespace: it extends the OFFICIAL pi-ai
+    // Models page and writes that provider's own `llm-pi-ai` section. The two
+    // supported hosts expose the same scope CONTRACT under different names:
+    //
+    //   ≤ 0.1.5  settingsScope.bind({ namespace })  → SettingsScope<T>
+    //   ≥ 0.1.7  configForms.get(entryId)           → ConfigForm<T>
+    //
+    // Both return getSnapshot()/subscribe()/set()/unset()/mutate() over the same
+    // { status, value, base, user, revision, writable, mode } snapshot, so the
+    // resolved object is used unchanged by the provider card. On 0.1.7-rc.1 a
+    // form's namespace IS the profile entry id, and the pi-ai LLM entry is
+    // mounted as `llm-pi-ai`, so the same key resolves on either host.
+    // `ctx.get` (never a direct property read) keeps the lookup safe when only
+    // one service is mounted: an uninjected property read throws.
+    function resolveSettingsScopeFrom(ctx, namespace) {
+      const binder = ctx.get('settingsScope')
+      if (binder && typeof binder.bind === 'function') return binder.bind({ namespace })
+      const forms = ctx.get('configForms')
+      if (forms && typeof forms.get === 'function') return forms.get(namespace)
+      return undefined
+    }
     const FETCH_TIMEOUT_MS = 20000
     const CSS_ID = 'dsh-model-params/style'
     const LEVELS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']
@@ -40,6 +70,8 @@ window.__ModuleLoader__.load({
        '.dpmProxy{display:flex;flex-direction:column;gap:6px;padding:7px 8px;border:1px solid var(--dsw-alias-border-l2);border-radius:8px;background:var(--dsw-alias-bg-layer-2)}',
        '.dpmProxy label{display:flex;align-items:center;gap:6px;color:var(--dsw-alias-label-secondary);cursor:pointer}',
        '.dpmProxy input[type=text]{width:100%;box-sizing:border-box;border:1px solid var(--dsw-alias-border-l2);border-radius:6px;padding:4px 6px;background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);font:inherit;font-size:11px}',
+      '.dpmRoute{display:flex;align-items:center;gap:6px;color:var(--dsw-alias-label-secondary)}',
+      '.dpmRoute select{font:inherit;font-size:11px;max-width:100%;border:1px solid var(--dsw-alias-border-l2);border-radius:6px;padding:3px 6px;background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary)}',
       '.dpmHint{color:var(--dsw-alias-label-tertiary);margin:0;font-size:11px;line-height:1.5}',
       '.dpmErr{color:var(--dsw-alias-state-error-primary);margin:0;font-size:11px;word-break:break-all}',
       '.dpmList{display:flex;flex-direction:column;gap:6px}',
@@ -71,6 +103,48 @@ window.__ModuleLoader__.load({
     const clean = (value) => typeof value === 'string' && value.trim() ? value.trim() : undefined
     const intersectLevels = (values) => (values || []).filter((value) => LEVELS.includes(value))
 
+    // ── the section page's own provider (the `settings.section` seat) ─────────
+    //
+    // The root-scope section seat's owner share is `{ close }` ALONE
+    // (SettingsSectionOwnerProps), so that page is handed NO provider while its
+    // Models-page sibling receives one per card. It therefore resolves its
+    // provider from the ONE settings transport this package already reads: the
+    // `llm-pi-ai` section itself, whose `providers` dict IS keyed by provider
+    // route (PiAiProviderProfile). Every route this page addresses is one the
+    // namespace really declares — never a synthesized id, never a second read or
+    // write path — and the profile supplies the real display name when it has one.
+    function piAiValue(snapshot) {
+      return snapshot && snapshot.status === 'ready' && snapshot.value && typeof snapshot.value === 'object' ? snapshot.value : undefined
+    }
+    function piAiRoutes(snapshot) {
+      const value = piAiValue(snapshot)
+      const providers = value && value.providers && typeof value.providers === 'object' && !Array.isArray(value.providers) ? value.providers : undefined
+      return providers ? Object.keys(providers).filter((route) => typeof route === 'string' && route.length > 0) : []
+    }
+    function piAiProfile(snapshot, route) {
+      const value = piAiValue(snapshot)
+      const profile = value && value.providers && typeof value.providers === 'object' ? value.providers[route] : undefined
+      return profile && typeof profile === 'object' ? profile : undefined
+    }
+    function piAiModels(snapshot, route) {
+      const profile = piAiProfile(snapshot, route)
+      return profile && Array.isArray(profile.models) ? profile.models : []
+    }
+    function piAiDisplayName(snapshot, route) {
+      const profile = piAiProfile(snapshot, route)
+      return (profile && clean(profile.displayName)) || route
+    }
+    // What the page says when it has no card to draw. A namespace still loading, a
+    // namespace this host does not serve, and a namespace with no provider
+    // configured are three different facts, and none may look like a blank page.
+    function sectionPageHint(snapshot, scope) {
+      if (!scope) return '设置传输不可用：本机未挂载 settingsScope / configForms，无法读写 llm-pi-ai 配置。'
+      const status = snapshot && snapshot.status
+      if (status === 'loading') return '正在读取 llm-pi-ai 设置…'
+      if (status !== 'ready') return '当前 Host 未提供 llm-pi-ai 设置，无法读写模型参数。'
+      return 'llm-pi-ai 命名空间下还没有已配置的 provider；请先在 设置 → 模型 中添加一个自定义 provider。'
+    }
+
     function paramLine(label, value) {
       if (value === undefined || value === null || value === '') return null
       return e('span', { key: label }, label + ': ' + value)
@@ -79,11 +153,23 @@ window.__ModuleLoader__.load({
     function ModelParamsExtension(props) {
       const row = props.provider
       const entry = row && row.entry && typeof row.entry === 'object' ? row.entry : row
-      const route = entry && (entry.provider || row && row.provider)
-      const settingsNs = entry && entry.settingsNs
+      // The provider the Models page hands this card through the seat's own owner
+      // props. The section seat hands NONE (`{ close }` is its whole owner share),
+      // so there this card IS the page and picks its own provider from the routes
+      // the namespace declares — see the resolvers above.
+      const seatRoute = entry && (entry.provider || row && row.provider)
       const api = props.api
       const scope = props.scope
-      const [open, setOpen] = React.useState(false)
+      // The panel starts COLLAPSED on the Models-page provider card, which renders
+      // one control per provider beside the others; it starts EXPANDED wherever the
+      // card is the whole page (`settings.section` passes `defaultOpen: true`), so
+      // the single-card seat opens with its content already visible. The trigger
+      // button below keeps folding it either way.
+      const [open, setOpen] = React.useState(props.defaultOpen === true)
+      // Which real route this card addresses on the page seat. Ignored while a
+      // provider arrives from the host, because a provider CARD is bound to the
+      // row it extends and must never follow a module-level selection.
+      const [picked, setPicked] = React.useState('')
       const [busy, setBusy] = React.useState(false)
       const [failed, setFailed] = React.useState('')
       const [saved, setSaved] = React.useState('')
@@ -94,7 +180,22 @@ window.__ModuleLoader__.load({
          proxyState.listeners.add(rerender)
          return () => proxyState.listeners.delete(rerender)
        }, [])
-      const [result, setResult] = React.useState(null) // { matched: [], unmatched: [] }
+       const [, refreshScope] = React.useState(0)
+       // The page's only reason to re-render beyond its own clicks: the namespace
+       // may still be loading at first paint, and a provider added in 设置 → 模型
+       // must appear here without a reload. ONE subscription on the same transport,
+       // disposed with the card.
+       React.useEffect(() => {
+         if (!scope || typeof scope.subscribe !== 'function') return undefined
+         const unsubscribe = scope.subscribe(() => refreshScope((value) => value + 1))
+         return () => { if (typeof unsubscribe === 'function') unsubscribe() }
+       }, [scope])
+      // A lookup answer is stamped with the route it was requested for: this card
+      // can change its addressed provider (the page seat's chooser, or the
+      // namespace dropping the picked route) while a request is in flight, and the
+      // previous provider's matches must never be previewed beside this one's
+      // models.
+      const [rawResult, setRawResult] = React.useState(null) // { route, matched: [], unmatched: [] }
       const ref = React.useRef(null)
 
       React.useEffect(() => {
@@ -109,29 +210,47 @@ window.__ModuleLoader__.load({
         }
       }, [open])
 
-      if (!route || settingsNs !== PI_NS) return null
-
       const snap = scope && typeof scope.getSnapshot === 'function' ? scope.getSnapshot() : { status: 'unavailable' }
-      const value = snap.status === 'ready' && snap.value && typeof snap.value === 'object' ? snap.value : {}
-      const profile = value.providers && value.providers[route] && typeof value.providers[route] === 'object' ? value.providers[route] : null
-      const models = Array.isArray(profile && profile.models) ? profile.models : []
+      // Two seats, ONE card. Where the host supplies a provider, this is the
+      // per-provider control it always was. Where none arrives (the
+      // `settings.section` page), this card is the page: it addresses the first
+      // route the llm-pi-ai namespace declares, or the one the user picked from the
+      // namespace's real route list.
+      const sectionSeat = !seatRoute
+      const routes = sectionSeat ? piAiRoutes(snap) : []
+      const route = sectionSeat ? (routes.includes(picked) ? picked : routes[0]) : seatRoute
+      const settingsNs = sectionSeat ? PI_NS : entry && entry.settingsNs
+      if (!route || settingsNs !== PI_NS) {
+        // A provider CARD whose namespace is not ours renders nothing (the seat
+        // dispatches by settingsNs, so this is defensive). The page seat owns the
+        // whole surface instead, so it always explains what it cannot draw rather
+        // than showing an empty page.
+        if (!sectionSeat) return null
+        return e('div', { className: 'dpmWrap' }, e('p', { className: 'dpmHint' }, sectionPageHint(snap, scope)))
+      }
+
+      const models = piAiModels(snap, route)
+      // Only this route's answer is this route's preview.
+      const result = rawResult && rawResult.route === route ? rawResult : null
       const writable = snap.status === 'ready' && snap.writable === true && !!api && !!api.settings
 
-      async function load() {
-        if (!models.length || busy) return
+      async function load(routeOverride) {
+        const targetRoute = routeOverride || route
+        const targetModels = routeOverride ? piAiModels(snap, routeOverride) : models
+        if (!targetModels.length || busy) return
         setBusy(true)
         setFailed('')
         setSaved('')
-        setResult(null)
+        setRawResult(null)
         const controller = new AbortController()
         const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
         try {
-          const ids = models.map((model) => model.id).filter(Boolean)
+          const ids = targetModels.map((model) => model.id).filter(Boolean)
           const query = '?ids=' + encodeURIComponent(ids.join(',')) + (proxyState.enabled ? '&proxy=' + encodeURIComponent((proxyState.url.trim() || PROXY_DEFAULT)) : '')
            const response = await fetch(API + query, { cache: 'no-store', signal: controller.signal })
           const data = await response.json()
           if (!data || data.ok !== true) throw new Error((data && data.error) || 'lookup failed')
-          setResult({ matched: data.matched || [], unmatched: data.unmatched || [] })
+          setRawResult({ route: targetRoute, matched: data.matched || [], unmatched: data.unmatched || [] })
         } catch (error) {
           setFailed(String((error && error.name === 'AbortError') ? '请求超时' : (error && error.message) || error))
         } finally {
@@ -197,7 +316,7 @@ window.__ModuleLoader__.load({
           }
           setSaved('已写入 provider "' + route + '" 的模型参数。')
            setOpen(false)
-          setResult(null)
+          setRawResult(null)
         } catch (error) {
           setFailed(String((error && error.message) || error))
         } finally {
@@ -205,7 +324,10 @@ window.__ModuleLoader__.load({
         }
       }
 
-      const displayName = entry && entry.displayName ? entry.displayName : route
+      // The Models page joins the official directory, so its `displayName` is the
+      // richest one. The page seat has only the namespace's own profile, which may
+      // declare one; otherwise the route itself is the honest label.
+      const displayName = (entry && entry.displayName) || piAiDisplayName(snap, route)
       const hasModels = models.length > 0
       const summary = result && result.matched ? result.matched.length + '/' + models.length + ' 匹配' : ''
 
@@ -214,6 +336,24 @@ window.__ModuleLoader__.load({
           busy ? '查询中…' : ('models.dev 参数' + (summary ? ' · ' + summary : ''))),
         open && e('div', { className: 'dpmPanel', role: 'dialog', 'aria-label': displayName + ' models.dev 参数' },
           e('h4', null, displayName + ' · models.dev 官方参数'),
+          // A namespace may declare SEVERAL llm-pi-ai providers. This page holds ONE
+          // card, so it offers the namespace's real routes instead of silently
+          // addressing whichever one is declared first; a single-route namespace gets
+          // no chooser at all, because there is nothing to choose.
+          routes.length > 1 && e('label', { className: 'dpmRoute' }, 'provider',
+            e('select', {
+              value: route,
+              'aria-label': '选择要处理的 llm-pi-ai provider',
+              onChange: (event) => {
+                const next = event.target.value
+                setPicked(next)
+                setRawResult(null)
+                setSaved('')
+                setFailed('')
+                void load(next)
+              },
+            }, routes.map((item) => e('option', { key: item, value: item }, piAiDisplayName(snap, item)))),
+          ),
            e('div', { className: 'dpmProxy' },
              e('label', null,
                e('input', { type: 'checkbox', checked: proxyState.enabled, onChange: (ev) => { proxyState.enabled = ev.target.checked; notifyProxy() } }),
@@ -274,15 +414,89 @@ window.__ModuleLoader__.load({
       const api = remote && remote.settings
         ? { settings: { mutate: (payload) => remote.settings.mutate(payload.ns, payload.ops, payload.expectedRevision).then((result) => ({ result })) } }
         : undefined
-      const scope = ctx.settingsScope.bind({ namespace: PI_NS })
-      return ctx.slots.inject('settings.models.provider-card', () => ctx.slots.register(
-        { name: 'settings.models.provider-card', key: PI_NS },
-        (props) => e(ModelParamsExtension, { ...props, api, scope }),
-      ))
+      // Version-portable scope on the official pi-ai namespace. Both transport
+      // names are awaited WITHOUT gating activation, and whichever this host
+      // mounts resolves; see resolveSettingsScopeFrom.
+      let scope
+      let cardRegistered = false
+      // Slot-registration disposers, released from apply's own disposer on stop /
+      // update / HMR so no seat entry outlives the plugin.
+      const disposeSlots = []
+      // The provider card MUST register from inside a context that has the
+      // settings transport, i.e. from the `ctx.inject([...], cb)` callback and on
+      // the CHILD context it hands us. Registering
+      // `settings.models.provider-card` from the bare apply context puts the
+      // entry where the Models page's ledger never sees it, so the extension
+      // never renders even though `register` returned normally. (dshmarket, an
+      // out-of-repo bundle that does render its card, uses this nested shape.)
+      const registerCard = (sctx) => {
+        if (cardRegistered) return
+        const resolved = resolveSettingsScopeFrom(sctx, PI_NS)
+        if (resolved === undefined) return
+        scope = resolved
+        cardRegistered = true
+        disposeSlots.push(sctx.slots.inject('settings.models.provider-card', () => sctx.slots.register(
+          { name: 'settings.models.provider-card', key: PI_NS },
+          (props) => e(ModelParamsExtension, { ...props, api, scope }),
+        )))
+      }
+      // The first wait fires only when settingsScope exists; the second covers a
+      // host that renamed the transport, and its guard keeps the card from
+      // registering twice when both names exist.
+      ctx.inject(['settingsScope'], registerCard)
+      ctx.inject(['configForms'], (sctx) => { if (!cardRegistered) registerCard(sctx) })
+
+      // ── additive seat: the `settings.section` page ─────────────────────────
+      //
+      // 0.1.7-rc.2 also declares the root-scope LIST slot `settings.section`
+      // ("one settings page per list entry"), which puts this card one click deep
+      // inside 设置 as a first-class page of its own. It is purely ADDITIVE: the
+      // provider-card extension above stays the Models-page affordance, and both
+      // render the SAME `ModelParamsExtension` through the SAME resolved transport
+      // — no second settings UI and no second read/write path. This package owns
+      // no bundle row, so there is no `plugins.row.config` occupant to mirror:
+      // its card is the official Models-page extension.
+      //
+      // That seat's owner share is `{ close }` alone, so this page is handed NO
+      // provider. It addresses one of the routes the llm-pi-ai namespace itself
+      // declares — read from the SAME resolved scope, so no second read path and no
+      // synthesized route — and explains a loading, unavailable or provider-less
+      // namespace instead of rendering a blank page. The page passes no `provider`
+      // prop, which is exactly how the card knows it is the whole page.
+      //
+      // The wait on `slots` is NON-GATING (the seat is host-version dependent: a
+      // host that does not declare it simply never fires the inner `slots.inject`,
+      // so this registration can never gate the plugin), the callback RETURNS the
+      // registration disposer, and that disposer is pushed onto disposeSlots so
+      // the entry is owned by the registering fiber and released with the rest on
+      // stop / update / HMR.
+      const registerSettingsSection = (sctx) => {
+        disposeSlots.push(sctx.slots.inject('settings.section', () => sctx.slots.register({
+          name: 'settings.section',
+          id: 'yotk-model-params',
+          order: 63,
+          label: () => 'YOTK · Model Params',
+        }, function ModelParamsSettingsSection() {
+          // The seat owner shares `close` and nothing else; this card needs
+          // neither it nor the host-owned optional `form` prop, because values
+          // keep flowing through the one resolved transport — so the page is the
+          // same card component the provider-card seat renders, with the panel
+          // expanded: one card alone on the page. The trigger button still folds
+          // it back up.
+          return e(ModelParamsExtension, { api, scope, defaultOpen: true })
+        })))
+      }
+      ctx.inject(['slots'], registerSettingsSection)
+
+      return () => { for (const dispose of disposeSlots) { try { dispose() } catch (_) {} } }
     }
 
     exports.name = 'dsh-model-params'
-    exports.inject = ['slots', 'settingsScope', 'remote', 'remote.settings']
+    // 'settingsScope' and 'configForms' are alternatives, not both-required:
+    // cordis resolves each inject name as its own gate, so activation succeeds on
+    // whichever settings transport the host mounts (0.1.5 vs 0.1.7-rc.1). The
+    // dotted remote names stay declared — dropping them fails the loader fiber.
+    exports.inject = ['slots', 'remote', 'remote.settings']
     exports.apply = apply
     return module.exports
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-model-params",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "EN: models.dev parameter assistant for the official DeepSeek Harness Models page: per-provider one-click context / max-output / reasoning-effort fill. ZH: 官方模型设置页的 models.dev 参数助手：按 provider 一键补全上下文、max 输出与推理档位。",
   "type": "module",
   "main": "lib/index.js",