dsh-router-core 0.3.21 → 0.4.1

package/src/client/index.tsx

@@ -10,8 +10,14 @@
  */
 import { mountRouterWorkspace } from './workspace-mount.tsx'
 import { RouterSettingsSection } from './settings-section.tsx'
+import { RouterComponentsSection } from './RouterComponentsSection.tsx'
+import { ExtTestPanel } from './ExtTestPanel.tsx'
+import { registerExtPanel } from './ext-panels.ts'
+import { EXT_TEST_ID } from '../ext-test/plugin.ts'
 import { registerSettingsNavIcon } from './settings-nav-icon.ts'
 import { rewriteRouterModelHint } from './model-hint-copy.ts'
+import { LastHitDock } from './LastHitDock.tsx'
+import { ROUTER_API_BASE } from '../shared.ts'
 import './router.css'
 
 /**
@@ -37,6 +43,42 @@ interface Ctx {
   effect: (fn: () => (() => void) | void, label?: string) => void
 }
 
+/**
+ * 挂载输入框底部的「最近命中」徽章：注册到官方 `conversation.composer.dock`
+ * （kind: list, scope: session —— 即宿主 composer 卡片底部操作行
+ * `.uV2eYG_dock` 里、原生上下文环旁边的位置）。
+ * scope 为 session 时宿主给组件注入 `sessionId`，据此按**当前会话**取命中。
+ *
+ * **仅宿主 >= 0.1.7 才挂**：composer.dock 这个座位在 0.1.5 也在，但渲染在
+ * InputBar 之后的独立块（位置不对），只有 0.1.7 才放进底部操作行。座位名相同
+ * 没法靠契约区分，故先问核心 `/router/api/health` 的 `lastHitDock` 支持位。
+ * @returns 清理函数；不支持或宿主无 slots 时为空操作
+ */
+function mountLastHitDock(ctx: Ctx, supported: boolean): () => void {
+  const slots = ctx.slots
+  if (slots === undefined || !supported) return () => {}
+  return slots.inject('conversation.composer.dock', () => slots.register({
+    name: 'conversation.composer.dock',
+    id: 'dsh-router-last-hit',
+    order: 10,
+  }, LastHitDock))
+}
+
+/**
+ * 问核心是否支持「最近命中」徽章（宿主 >= 0.1.7）。
+ * 网络/解析失败一律当**不支持**——宁可不显示，也不在 0.1.5 上摆错位置。
+ */
+async function fetchLastHitDockSupport(): Promise<boolean> {
+  try {
+    const res = await fetch(`${ROUTER_API_BASE}/health`)
+    if (!res.ok) return false
+    const body = (await res.json()) as { lastHitDock?: unknown }
+    return body.lastHitDock === true
+  } catch {
+    return false
+  }
+}
+
 /** 挂载「设置 → 路由」页；拿不到 slots 时返回 undefined 表示跳过。 */
 function mountSettingsSection(ctx: Ctx): (() => void) | undefined {
   const slots = ctx.slots
@@ -55,7 +97,46 @@ function mountSettingsSection(ctx: Ctx): (() => void) | undefined {
   }, RouterSettingsSection))
 }
 
+/**
+ * 官方插件页（设置 → 插件）里 dsh-router-core 详情页的「路由组件」一节。
+ *
+ * 为什么走 `plugins.detail.section` 而不是官方那个「包含的组件」：后者的行由
+ * 宿主从**本 bundle 自己的 cordis.patch.yml** 算出来，跨 bundle 没有注入通道，
+ * 而子插件（codebuddy / ext-rtk …）必须保持各自独立安装。官方给的位置就是这一
+ * 个槽位（渲染在原生行列表之后）。槽位不存在的老宿主上 `inject` 不会触发，
+ * 自动不挂——不引入硬 client inject。
+ */
+function mountComponentsSection(ctx: Ctx): (() => void) | undefined {
+  const slots = ctx.slots
+  if (slots === undefined) return undefined
+  return slots.inject('plugins.detail.section', () => slots.register({
+    name: 'plugins.detail.section',
+    id: 'dsh-router-components',
+    order: 10,
+  }, RouterComponentsSection))
+}
+
+/**
+ * 给「插件自检」扩展登记它的详情面板。
+ *
+ * 面板的**唯一入口**是设置 → 路由 → 扩展 → 点开那张卡片（`ExtDetail` 查注册表拿到
+ * 本组件）。**刻意不给插件页那一行再挂一个详情页**：那一行的宿主行开关已经能开/关
+ * 它了，再点进去看同一块面板就是同一个东西有两个入口 —— 与「内置扩展不在自绘节里
+ * 重复列」是同一条理由。
+ */
+function registerExtTestPanel(ctx: Ctx): void {
+  const dispose = registerExtPanel(EXT_TEST_ID, ExtTestPanel)
+  ctx.effect(() => dispose, 'dsh-router: ext test panel registry')
+}
+
 export function apply(ctx: Ctx): void {
+  // 「最近命中」徽章：走官方 conversation.composer.dock（scope: session → 组件
+  // props 注入 sessionId，按当前会话取命中）。**仅宿主 >= 0.1.7 才挂**——
+  // composer.dock 在 0.1.5 渲染位置不对，先问核心拿支持位，避免摆错位置。
+  // 查询是异步的，拿到结果（无论成败）再决定注册与否。
+  void fetchLastHitDockSupport().then((supported) => {
+    ctx.effect(() => mountLastHitDock(ctx, supported), 'dsh-router: last-hit dock')
+  })
   const disposeSettings = mountSettingsSection(ctx)
   if (disposeSettings === undefined) {
     // 老宿主（无 slots）：回退到侧边栏入口 + 中心栏面板
@@ -64,6 +145,11 @@ export function apply(ctx: Ctx): void {
     return
   }
   ctx.effect(() => disposeSettings, 'dsh-router: settings section')
+  const disposeComponents = mountComponentsSection(ctx)
+  if (disposeComponents !== undefined) {
+    ctx.effect(() => disposeComponents, 'dsh-router: plugin page components')
+  }
+  registerExtTestPanel(ctx)
   // 换掉宿主的默认齿轮（契约没有 icon 字段，只能注册后认领自己的行）
   ctx.effect(() => registerSettingsNavIcon(SECTION_LABEL), 'dsh-router: settings nav icon')
   // 设置-模型 里 Router 卡片的那句死路提示 → 正确说法（同样只能认领后就地改写）

package/src/client/last-hit-store.ts

@@ -0,0 +1,89 @@
+/**
+ * 「最近命中」的会话级数据源。
+ *
+ * 为什么要有这层：徽章组件可能因宿主重渲染而卸载/重建，但**轮询不该跟着重建**
+ * （每个会话一个轮询器，多会话各自独立；组件只订阅结果）。这里做两件事：
+ *   - 按 sessionId 维护「最近一次命中」的最新值 + 订阅者集合；
+ *   - 每个会话一个定时器，只在有订阅者时开、无订阅者时停。
+ *
+ * 数据源：核心 `/router/api/last-hit?session=`（轻端点，不打 status）。
+ */
+
+const DIGEST_API = '/router/api/last-hit'
+/** 刷新间隔：命中信息跟着请求走，轮询取一个不打扰的频率。 */
+const POLL_MS = 3000
+
+/** 一次命中的快照（后端 `/last-hit` 的 `hit` 字段，只声明用到的）。 */
+export interface LastHit {
+  supplier: string
+  model: string
+  requested: string
+  uid: string
+  account?: string
+  credits?: number
+  ok: boolean
+}
+
+interface Entry {
+  value: LastHit | null
+  listeners: Set<(v: LastHit | null) => void>
+  timer: number | null
+}
+
+const entries = new Map<string, Entry>()
+
+function entryOf(key: string): Entry {
+  let e = entries.get(key)
+  if (e === undefined) {
+    e = { value: null, listeners: new Set(), timer: null }
+    entries.set(key, e)
+  }
+  return e
+}
+
+function emit(e: Entry): void {
+  for (const fn of e.listeners) fn(e.value)
+}
+
+async function refresh(key: string): Promise<void> {
+  const e = entryOf(key)
+  try {
+    // key 为空（宿主未注入 sessionId）时不带 session 参数 → 后端回退全局最近。
+    const qs = key === '' ? '' : `?session=${encodeURIComponent(key)}`
+    const res = await fetch(`${DIGEST_API}${qs}`, { cache: 'no-store' })
+    const data = await res.json() as { ok: boolean; hit?: LastHit | null }
+    const next = data.ok && data.hit ? data.hit : null
+    e.value = next
+  } catch {
+    // 网络抖动不该清空徽章（保留上次值）
+  }
+  emit(e)
+}
+
+/** 读该会话当前的最近命中（同步快照）。 */
+export function getLastHit(sessionId?: string): LastHit | null {
+  return entryOf(sessionId ?? '').value
+}
+
+/**
+ * 订阅该会话的最近命中。首次订阅即启动轮询，最后一个退订时停。
+ * @param sessionId 宿主会话身份（可能为 undefined，此时键为空串 = 全局）
+ * @param listener 值变化回调
+ * @returns 退订函数
+ */
+export function subscribeLastHit(sessionId: string | undefined, listener: (v: LastHit | null) => void): () => void {
+  const key = sessionId ?? ''
+  const e = entryOf(key)
+  e.listeners.add(listener)
+  if (e.timer === null) {
+    void refresh(key)
+    e.timer = window.setInterval(() => void refresh(key), POLL_MS)
+  }
+  return () => {
+    e.listeners.delete(listener)
+    if (e.listeners.size === 0 && e.timer !== null) {
+      window.clearInterval(e.timer)
+      e.timer = null
+    }
+  }
+}

package/src/client/model-choice.test.ts

@@ -0,0 +1,41 @@
+/**
+ * 「只列可用模型」这条判据的测试。
+ *
+ * 为什么要有：错了不会抛异常、不会白屏，只是下拉里多了几个用户明明关掉的模型 ——
+ * 挑中一个去测，测通了也不代表配置是对的，而用户看不出自己挑错了。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { modelChoice } from './model-choice.ts'
+
+test('只列用户没停用的模型（端点给的是全部模型）', () => {
+  const c = modelChoice([
+    { id: 'a', enabled: true },
+    { id: 'b', enabled: false },
+    { id: 'c', enabled: true },
+    { id: 'd', enabled: false },
+  ])
+  assert.deepEqual(c.ids, ['a', 'c'])
+  assert.equal(c.empty, undefined)
+})
+
+test('保持端点给的顺序（端点已按优先级排好，重排会毁掉它）', () => {
+  const c = modelChoice([{ id: 'z', enabled: true }, { id: 'a', enabled: true }])
+  assert.deepEqual(c.ids, ['z', 'a'])
+})
+
+test('缺 enabled 按「未停用」读 —— 不凭空把模型藏起来', () => {
+  const c = modelChoice([{ id: 'a' }, { id: 'b', enabled: false }])
+  assert.deepEqual(c.ids, ['a'])
+})
+
+test('一个模型都没有 vs 全被停用：两种空得指去不同的地方', () => {
+  assert.equal(modelChoice([]).empty, 'none', '没模型 → 该去拉取')
+  assert.equal(modelChoice([{ id: 'a', enabled: false }]).empty, 'all-disabled', '有模型但全关 → 该去开启')
+})
+
+test('全停用时 ids 为空，不会把停用的模型漏进下拉', () => {
+  const c = modelChoice([{ id: 'a', enabled: false }, { id: 'b', enabled: false }])
+  assert.deepEqual(c.ids, [])
+  assert.equal(c.empty, 'all-disabled')
+})

package/src/client/model-choice.ts

@@ -0,0 +1,37 @@
+/**
+ * 自检面板的「模型」下拉该列哪些 —— 纯函数，不碰 React。
+ *
+ * 为什么不能把端点返回的模型全列出来：那个端点给的是**全部**模型（含用户在
+ * 供应商详情里停用的）。实测某供应商 30 个模型里只有 3 个是启用的 —— 把 30 个都
+ * 塞进下拉，用户会挑到一个自己明明关掉的模型去测，测通了也不代表配置是对的。
+ * 所以只列**可用**的（用户没停用的），与路由实际会用的那批保持一致。
+ *
+ * 顺带把「没有可选模型」拆成两种，因为**用户该做的事不一样**：
+ *   - `none`（一个模型都没有）→ 该去供应商详情拉取模型；
+ *   - `all-disabled`（有模型但全被停用）→ 该去供应商详情把它们打开，
+ *     去拉取是白跑一趟。
+ * 两种共用一句「没有模型」就是把用户往错的方向指。
+ *
+ * `enabled` 缺省按**未停用**读（`!== false`）：这个字段是用户的配置，缺失时不该
+ * 凭空把模型藏起来。
+ */
+
+/** `/suppliers/:id/models` 里的一条模型。 */
+export interface ModelRow {
+  id: string
+  enabled?: boolean
+}
+
+export interface ModelChoice {
+  /** 可用模型的 id，按端点返回的顺序（不重排 —— 端点已经按优先级排过了）。 */
+  ids: string[]
+  /** 没有可选模型时的原因；`undefined` = 有得选。 */
+  empty?: 'none' | 'all-disabled'
+}
+
+/** 从端点答复里挑出可用的模型，并说明「空的」到底是哪一种空。 */
+export function modelChoice(models: readonly ModelRow[]): ModelChoice {
+  const ids = models.filter((m) => m.enabled !== false).map((m) => m.id)
+  if (ids.length > 0) return { ids }
+  return { ids, empty: models.length === 0 ? 'none' : 'all-disabled' }
+}

package/src/client/model-hint-copy.test.ts

@@ -10,8 +10,8 @@ import assert from 'node:assert/strict'
 import { routerHintRewrite, ROUTER_MODEL_HINT_COPY } from './model-hint-copy.ts'
 
 test('认出宿主提示（中/英两种文案 + 命名空间指纹）', () => {
-  const zh = '其余字段在 settings.yaml 中，请直接编辑对应段。 (llm-dsh-router)'
-  const en = 'Other fields live in settings.yaml; edit that section directly. (llm-dsh-router)'
+  const zh = '其余字段在 settings.yaml 中，请直接编辑对应段。 (dsh-router)'
+  const en = 'Other fields live in settings.yaml; edit that section directly. (dsh-router)'
   assert.equal(routerHintRewrite(zh), ROUTER_MODEL_HINT_COPY)
   assert.equal(routerHintRewrite(en), ROUTER_MODEL_HINT_COPY)
 })
@@ -21,6 +21,11 @@ test('别的 provider 的同类提示不动（指纹只属于 Router）', () =>
   assert.equal(routerHintRewrite(deepseek), undefined)
 })
 
+test('旧命名空间指纹不再认领 —— 0.1.7 起宿主渲染的是行 id', () => {
+  const legacy = '其余字段在 settings.yaml 中，请直接编辑对应段。 (llm-dsh-router)'
+  assert.equal(routerHintRewrite(legacy), undefined)
+})
+
 test('已是目标文案时早退 —— 观察器不自激', () => {
   assert.equal(routerHintRewrite(ROUTER_MODEL_HINT_COPY), undefined)
 })

package/src/client/model-hint-copy.ts

@@ -3,7 +3,7 @@
  *
  * 为什么不能直接改源头：Router 的卡片走宿主的 "unknown" 布局（宿主只认得
  * llm-deepseek / llm-pi-ai 两套表单），那句
- *   「其余字段在 settings.yaml 中，请直接编辑对应段。 (llm-dsh-router)」
+ *   「其余字段在 settings.yaml 中，请直接编辑对应段。 (dsh-router)」
  * 属于宿主 `settings.models` 的 locale 字典，而字典注册对同一个 (ns, locale)
  * 只允许一个占位者（重复注册直接抛），插件覆写不了，契约也没给可覆写字段。
  * 所以沿用本插件既有的认领手法（同 settings-nav-icon.ts）：按文案指纹认出宿主
@@ -16,7 +16,7 @@
  */
 
 /** 指纹：语言无关（不受中英文切换影响），且只出现在 Router 卡片上。 */
-const FINGERPRINT = '(llm-dsh-router)'
+const FINGERPRINT = '(dsh-router)'
 
 /** 正确说法：对齐 README「组合即模型」。 */
 export const ROUTER_MODEL_HINT_COPY = '组合即模型 · 建好的组合会自动出现在 DSH 模型目录中，选中组合名即可直接使用。'

package/src/client/router-components.test.ts

@@ -0,0 +1,114 @@
+/**
+ * 「路由组件」分组判据测试 —— 锁住三条会静默出错的规则。
+ *
+ * 1. `source` 判据取反：只有 external 是独立安装的 bundle，其余归本地组。
+ * 2. 缺 `source` 的供应商不许被静默丢掉，也不许被误报成独立插件。
+ * 3. 只有 ext 那组 `togglable` —— 供应商在这一页没有可写的开关。
+ *
+ * 这三条错了都不会抛异常，只会显示成「少了一组 / 多了个开关」，所以必须有闸门。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { groupRouterComponents, isEmptyComponents, EMPTY_COMPONENTS } from './router-components.ts'
+import type { RouterExtResponse, RouterHealthResponse } from '../shared.ts'
+
+const health = (suppliers: NonNullable<RouterHealthResponse['suppliers']>): RouterHealthResponse => ({ ok: true, suppliers })
+const noExt: RouterExtResponse = { ok: true, enhancers: [] }
+
+test('内置供应商一个都不进这一节（它们是原生「包含的组件」里的行）', () => {
+  const out = groupRouterComponents(health([
+    { id: 'opencode', name: 'OpenCode', source: 'builtin' },
+    { id: 'openrouter', name: 'OpenRouter', source: 'builtin' },
+    { id: 'nvidia', name: 'NVIDIA NIM', source: 'builtin' },
+  ]), noExt)
+  // 重复显示两处 = 用户看到同一个东西两次，且有一处没有开关。
+  assert.deepEqual(out.external, [])
+  assert.deepEqual(out.ext, [])
+})
+
+test('外部供应商插件进「供应商」组（各是独立 bundle，这一页有开关）', () => {
+  const out = groupRouterComponents(health([
+    { id: 'codebuddy', name: 'CodeBuddy', source: 'external' },
+    { id: 'traework', name: 'TRAE SOLO', source: 'external' },
+  ]), noExt)
+  assert.deepEqual(out.external.map((r) => r.key), ['supplier:codebuddy', 'supplier:traework'])
+  assert.equal(out.external.every((r) => r.togglable), true, '供应商在这一页有开关（写 PATCH /suppliers/:id/enabled）')
+})
+
+test('缺 source 的供应商不显示，也不被误报成独立插件', () => {
+  const out = groupRouterComponents(health([{ id: 'mystery', name: 'Mystery' }]), noExt)
+  assert.deepEqual(out.external, [])
+})
+
+test('user 目录投放的供应商也不进这一节（它的对应物是行的覆盖或外部插件）', () => {
+  const out = groupRouterComponents(health([{ id: 'mine', name: 'My Supplier', source: 'user' }]), noExt)
+  assert.deepEqual(out.external, [])
+})
+
+test('扩展插件进 ext 组且唯一可开关；状态按「宁可关着」读', () => {
+  const out = groupRouterComponents(health([]), {
+    ok: true,
+    enhancers: [
+      { id: 'rtk', name: 'RTK', enabled: true, ready: true },
+      { id: 'jev', name: 'JEV' },
+    ],
+  })
+  assert.equal(out.ext.length, 2)
+  assert.equal(out.ext.every((r) => r.togglable), true)
+  assert.deepEqual(out.ext.map((r) => r.enabled), [true, false])
+  assert.deepEqual(out.ext.map((r) => r.ready), [true, false])
+})
+
+test('图标与说明只在该有的时候带上（不塞 undefined 键）', () => {
+  const out = groupRouterComponents(health([{ id: 'loomy', name: 'Loomy', icon: 'data:image/png;base64,x', source: 'external' }]), {
+    ok: true,
+    enhancers: [{ id: 'rtk', name: 'RTK', detail: '本机未装 rtk' }],
+  })
+  const supplier = out.external.at(0)
+  const extRow = out.ext.at(0)
+  assert.ok(supplier !== undefined && extRow !== undefined)
+  assert.equal('icon' in supplier, true)
+  assert.equal('detail' in extRow, true)
+  assert.equal('icon' in extRow, false)
+})
+
+test('两个端点都没有内容时不渲染这一节（不留空标题）', () => {
+  assert.equal(isEmptyComponents(EMPTY_COMPONENTS), true)
+  assert.equal(isEmptyComponents(groupRouterComponents({ ok: true }, { ok: true })), true)
+  assert.equal(isEmptyComponents(groupRouterComponents({ ok: true }, { ok: true, enhancers: [{ id: 'rtk', name: 'RTK' }] })), false)
+})
+
+test('端点报错/缺字段时分组仍是空组，不抛（形状恒定）', () => {
+  const out = groupRouterComponents({ ok: false, error: 'boom' }, { ok: false, error: 'boom' })
+  assert.deepEqual(out, EMPTY_COMPONENTS)
+})
+
+test('供应商的开关状态：缺 enabled 按开着读，关掉的仍列出来（关掉后要能再开）', () => {
+  const out = groupRouterComponents(health([
+    { id: 'codebuddy', name: 'CodeBuddy', source: 'external' },
+    { id: 'traework', name: 'TRAE SOLO', source: 'external', enabled: false },
+  ]), noExt)
+  assert.deepEqual(out.external.map((r) => r.key), ['supplier:codebuddy', 'supplier:traework'],
+    '关掉的供应商不能从列表消失 —— 消失了就再没有可点的开关把它开回来')
+  assert.deepEqual(out.external.map((r) => r.enabled), [true, false])
+})
+
+test('供应商行没有 ready（那是扩展的运行时事实）—— 缺失不得让它变成点不开', () => {
+  const out = groupRouterComponents(health([{ id: 'codebuddy', name: 'CodeBuddy', source: 'external' }]), noExt)
+  const row = out.external.at(0)
+  assert.ok(row !== undefined)
+  assert.equal('ready' in row, false, '供应商不报就绪，别塞一个 undefined 键进去')
+  assert.equal(row.togglable, true)
+})
+
+test('内置扩展不进这一节（它已经是原生「包含的组件」里的一行）', () => {
+  const out = groupRouterComponents({ ok: true }, {
+    ok: true,
+    enhancers: [
+      { id: 'test', name: '插件自检', source: 'builtin' },
+      { id: 'rtk', name: 'RTK' },
+    ],
+  })
+  // 重复显示两处 = 用户看到同一个东西两次，且有一处没有开关。
+  assert.deepEqual(out.ext.map((r) => r.key), ['ext:rtk'])
+})

package/src/client/router-components.ts

@@ -0,0 +1,104 @@
+/**
+ * 官方插件页「路由组件」一节的分组 —— 纯函数，不碰 React。
+ *
+ * 为什么抽出来：这一节唯一有分支的地方就是「一条供应商/扩展归哪组、能不能
+ * 就地开关」（见下两条判据）。留在组件里就只能靠真页面点出来验，抽出来单测，
+ * 判据改错当场变红。
+ *
+ * 数据源是核心**已经在提供**的两个端点，本模块不新增任何 API：
+ *   - `/health` 的 `suppliers[]` 带 `source`（builtin / user / external）
+ *   - `/ext` 的 `enhancers[]` 是核心合并完开关与运行时事实的扩展表
+ */
+import type { RouterExtResponse, RouterHealthResponse } from '../shared.ts'
+
+/** `/health` 里的一条供应商摘要（就地取型，不另抄一份形状）。 */
+export type RouterSupplierSummary = NonNullable<RouterHealthResponse['suppliers']>[number]
+
+/** 一行组件（两组共用同一种形状，渲染时才分叉）。 */
+export interface RouterComponentRow {
+  /** 组内唯一键：`supplier:<id>` / `ext:<id>`。 */
+  key: string
+  name: string
+  icon?: string
+  /** ext 报的就绪状态说明（如「本机未装 rtk」）。 */
+  detail?: string
+  enabled?: boolean
+  ready?: boolean
+  /**
+   * 能否就地开关。**两组都能**：扩展走 `PATCH /router/api/ext`（核心持久化到
+   * `<dataDir>/ext.json`），供应商走 `PATCH /router/api/suppliers/:id/enabled`
+   * （落到 `supplier-config.json`）。两组都是核心持久化的用户开关，核心都据此
+   * 真的停止路由 —— 不是一个只把卡片藏起来的假开关。
+   */
+  togglable: boolean
+}
+
+/**
+ * 这一节要列的两组。
+ *
+ * **为什么没有「内置与本地供应商」组**：内置供应商是 dsh-router-core 自己 patch
+ * 里的**行**（`cordis.patch.yml` insert 了三个子路径模块），已经在宿主的原生
+ * 「包含的组件」里，带着宿主管的开关。在这里再列一遍就是同一个东西显示两处。
+ */
+export interface RouterComponents {
+  /** 独立安装的供应商插件（各是独立 bundle，启停在它们自己的插件页）。 */
+  external: RouterComponentRow[]
+  /** 扩展插件（`router.ext`，开关归核心）。 */
+  ext: RouterComponentRow[]
+}
+
+/** 空组：加载前与加载失败都用它，保证形状恒定。 */
+export const EMPTY_COMPONENTS: RouterComponents = { external: [], ext: [] }
+
+/** 一条外部供应商摘要 → 只读行。 */
+function supplierRow(s: RouterSupplierSummary): RouterComponentRow {
+  return {
+    key: `supplier:${s.id}`,
+    name: s.name,
+    // 缺 `enabled` 按开着读（老核心没这个字段）。关掉的供应商**仍列出来** ——
+    // 面板「扩展」页的形状是「关掉就不出现」，但供应商关掉后如果也消失，这里就
+    // 少了一个可点的开关、再也开不回来。两组刻意不同。
+    enabled: s.enabled !== false,
+    togglable: true,
+    ...(s.icon === undefined ? {} : { icon: s.icon }),
+  }
+}
+
+/**
+ * 把两个端点的答复分成两组。
+ *
+ * 供应商这边只收 `source === 'external'`（独立安装的供应商插件）。`builtin`
+ * 的那三个已经作为**原生行**在宿主的「包含的组件」里显示了（core 自己 patch
+ * insert 的子路径模块，开关是宿主管的那个行开关），`user` 的是用户目录里投放的
+ * js —— 两者都不该在这里出现第二次。`source` 缺失按「不是 external」处理：
+ * 不显示总比把内置的错标成独立插件强。
+ *
+ * 两组都在这一页开关，指向核心的同两个端点（`PATCH /suppliers/:id/enabled` 与
+ * `PATCH /ext`），所以「在哪开关」是一致的：**设置 → 插件 → dsh-router-core**。
+ * 供应商的开关关掉是真的不参与路由（见 Router 的活跃集合），不是只隐藏卡片。
+ */
+export function groupRouterComponents(health: RouterHealthResponse, ext: RouterExtResponse): RouterComponents {
+  const external = (health.suppliers ?? [])
+    .filter((s) => s.source === 'external')
+    .map(supplierRow)
+  // 只列**独立安装**的扩展（`source !== 'builtin'`）。随核心分发的内置扩展已经在
+  // 宿主原生的「包含的组件」里占一行、自带宿主管的开关，在这里再列一遍就是同一个
+  // 东西显示两处 —— 与内置供应商的处理完全一样。
+  const extRows = (ext.enhancers ?? []).filter((e) => e.source !== 'builtin').map((e): RouterComponentRow => ({
+    key: `ext:${e.id}`,
+    name: e.name,
+    // 缺字段一律按「关 / 未就绪」读：没拿到的事实不当真，宁可显示成关着
+    // 让用户自己去开，也不要谎报在跑（`ready` 是运行时事实，猜不得）。
+    enabled: e.enabled === true,
+    ready: e.ready === true,
+    togglable: true,
+    ...(e.icon === undefined ? {} : { icon: e.icon }),
+    ...(e.detail === undefined ? {} : { detail: e.detail }),
+  }))
+  return { external, ext: extRows }
+}
+
+/** 两组加起来一个都没有 → 这一节不渲染（不留空标题）。 */
+export function isEmptyComponents(components: RouterComponents): boolean {
+  return components.external.length === 0 && components.ext.length === 0
+}