dsh-router-core 0.4.0 → 0.4.2

package/src/router/supplier-switch.test.ts

@@ -0,0 +1,220 @@
+/**
+ * 供应商开关测试 —— 锁住「关掉 = 真的不参与路由」，而且是**全部入口**都拦。
+ *
+ * 为什么要有这个文件：这个开关的唯一实现是 `Router` 里的活跃集合
+ * （`active` = 装载清单里开关为开的那一份）。而路由有 15 处读供应商清单，
+ * 少收一处就出现「面板显示已关闭、请求照样打过去」——那是最坏的一种：开关说了
+ * 假话，用户以为断了流量其实在烧额度。所以这里逐个入口钉住：
+ *
+ *   1. 组合腿（`supplierId,modelId` 形态）
+ *   2. 直调（`alias/model` 形态）
+ *   3. 模型目录 / 别名前缀（关掉的不能留下「前缀存在但必然 503」的死前缀）
+ *   4. status() 仍带出关掉的（否则关掉后就没法再开，开关失去对象）
+ *   5. 关掉不能连带卸载（`removeSupplier` 是插件卸载用的另一码事）
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import type { ServerResponse } from 'node:http'
+import { Router } from './index.ts'
+import type { ModelInfo } from './types.ts'
+import { AccountPool } from './account-pool.ts'
+import { SupplierConfigStore } from '../supplier-config.ts'
+import type { AccountPool as Pool } from './account-pool.ts'
+import type { ChatOnceResult, SupplierAccountNow, SupplierStatusNow } from '../suppliers/contract.ts'
+
+interface Spy {
+  calls: number
+  seen: string[]
+  s: {
+    id: string
+    name: string
+    priority: number
+    pool: Pool
+    status: () => SupplierStatusNow
+    listModels: () => Promise<ModelInfo[]>
+    modelsWithEnabled: () => Promise<Array<ModelInfo & { enabled: boolean }>>
+    customModelIds: () => string[]
+    getAlias: () => string
+    accounts: () => SupplierAccountNow[]
+    chatOnce: (uid: string, lv: string, req: { rawBody: string }) => Promise<ChatOnceResult>
+    dispose: () => void
+  }
+}
+
+/** 带探针的供应商：只服务自己的模型，记录被问过什么。 */
+function spy(id: string, modelId: string, alias = id): Spy {
+  const calls = { n: 0 }
+  const seen: string[] = []
+  return {
+    get calls() { return calls.n },
+    seen,
+    s: {
+      id, name: id, priority: 0, pool: new AccountPool(),
+      status: () => ({ id, name: id, accounts: [{ uid: `${id}-u1`, credits: 0, state: 'ok' }] }),
+      listModels: async () => [{ id: modelId }],
+      modelsWithEnabled: async () => [{ id: modelId, enabled: true }],
+      customModelIds: () => [`${id}-custom`],
+      getAlias: () => alias,
+      accounts: () => [{ uid: `${id}-u1`, credits: 0, state: 'ok' }],
+      chatOnce: async (_uid, _lv, req) => {
+        calls.n += 1
+        const m = (JSON.parse(req.rawBody) as { model?: string }).model ?? ''
+        seen.push(m)
+        const base = m.startsWith(`${alias}/`) ? m.slice(alias.length + 1) : m
+        if (base !== modelId) return { ok: false, state: 'no_such_model', message: `unknown model ${m}` }
+        return { ok: true, status: 200, body: '{"ok":1}' }
+      },
+      dispose: () => {},
+    },
+  }
+}
+
+function add(router: Router, s: unknown): void {
+  router.add(s as Parameters<Router['add']>[0])
+}
+
+function fakeRes(): ServerResponse {
+  return {
+    writeHead: (): unknown => undefined,
+    end: (): unknown => undefined,
+    write: (): boolean => true,
+    once: (): unknown => undefined,
+    removeListener: (): unknown => undefined,
+    destroy: (): unknown => undefined,
+  } as unknown as ServerResponse
+}
+
+function reqWith(model: string) {
+  return { model, stream: false, rawBody: JSON.stringify({ model, messages: [] }) }
+}
+
+/** 路由器 + 共享 store（开关要能从 store 落盘/读回，所以显式传同一个实例）。 */
+function rig() {
+  const store = new SupplierConfigStore('')
+  return { router: new Router('', store, () => {}), store }
+}
+
+test('关掉的供应商：组合腿不会打到它（唯一的路由入口之一）', async () => {
+  const { router, store } = rig()
+  const a = spy('supA', 'a-model')
+  const b = spy('supB', 'b-model')
+  add(router, a.s); add(router, b.s)
+  assert.equal(router.createCombo('c', ['supA,a-model', 'supB,b-model']).ok, true)
+
+  store.setEnabled('supA', false)
+  await router.chatCompletions(reqWith('c'), fakeRes())
+
+  assert.equal(a.calls, 0, '已关闭的供应商不该被组合腿问到')
+  assert.equal(b.calls, 1, '开着的供应商照常服务')
+})
+
+test('关掉的供应商：alias 直调也进不去（第二条入口）', async () => {
+  const { router, store } = rig()
+  const a = spy('supA', 'a-model', 'aaa')
+  add(router, a.s)
+
+  store.setEnabled('supA', false)
+  await router.chatCompletions(reqWith('aaa/a-model'), fakeRes())
+
+  assert.equal(a.calls, 0, '已关闭的供应商不该被直调命中')
+  assert.equal(router.supplierByAlias('aaa'), undefined, '别名反查也不该命中')
+})
+
+test('关掉再打开，路由立刻恢复（开关不是卸载）', async () => {
+  const { router, store } = rig()
+  const a = spy('supA', 'a-model', 'aaa')
+  add(router, a.s)
+
+  store.setEnabled('supA', false)
+  assert.equal(a.calls, 0)
+  store.setEnabled('supA', true)
+  await router.chatCompletions(reqWith('aaa/a-model'), fakeRes())
+  assert.equal(a.calls, 1, '重新打开后应当照常服务')
+})
+
+test('关掉的供应商仍出现在 status()（关掉后要能再开）且带 enabled=false', () => {
+  const { router, store } = rig()
+  add(router, spy('supA', 'a-model').s)
+  store.setEnabled('supA', false)
+
+  const { suppliers } = router.status()
+  assert.equal(suppliers.length, 1, '关掉不等于卸载，列表里还得有它')
+  assert.equal(suppliers[0]?.enabled, false)
+  assert.equal(router.isEnabled('supA'), false)
+})
+
+test('关掉的供应商不留死前缀、不进模型目录（否则是「存在但必然 503」）', async () => {
+  const { router, store } = rig()
+  add(router, spy('supA', 'a-model', 'aaa').s)
+  store.setEnabled('supA', false)
+
+  assert.deepEqual(router.aliases(), [], '关掉的供应商不该再提供模型前缀')
+  assert.deepEqual(await router.modelsOf('supA'), [], '关掉的供应商不该还能拉模型')
+  const models = await router.listModels()
+  assert.equal(
+    models.some((m) => m.id.includes('supA-custom')),
+    false,
+    '关掉的供应商的自定义模型不该进模型目录',
+  )
+})
+
+test('没记录过的供应商默认开着（升级不把全灭变成全开）', () => {
+  const { router } = rig()
+  add(router, spy('supA', 'a-model').s)
+  assert.equal(router.isEnabled('supA'), true)
+})
+
+// ---- 指定连接自检（插件自检面板的连接测试用它） ----
+// 面板「供应商」详情里的「测试」按钮走账号池（任选可用号、失败自动换号）；
+// 面板的连接测试可以**钉死一个连接**，用来诊断单个链接到底通不通。关键性质：
+// 指定了连接就**不回退**到别的号，否则「测这个连接」测出来的是另一个号的结果。
+
+test('指定连接：只试这一个连接', async () => {
+  const { router } = rig()
+  const a = spy('supA', 'a-model')
+  a.s.accounts = () => [
+    { uid: 'u1', credits: 0, state: 'ok' },
+    { uid: 'u2', credits: 0, state: 'ok' },
+  ]
+  a.s.status = () => ({ id: 'supA', name: 'supA', accounts: a.s.accounts() })
+  add(router, a.s)
+
+  const r = await router.testModel('supA', 'a-model', 'u1')
+  assert.equal(r.ok, true)
+  assert.equal(a.calls, 1, '只该试一次')
+})
+
+test('指定连接失败时不回退到别的号（否则诊断结论是假的）', async () => {
+  const { router } = rig()
+  const a = spy('supA', 'a-model')
+  a.s.accounts = () => [
+    { uid: 'u1', credits: 0, state: 'ok' },
+    { uid: 'u2', credits: 0, state: 'ok' },
+  ]
+  a.s.status = () => ({ id: 'supA', name: 'supA', accounts: a.s.accounts() })
+  // 自己记账：spy 的 calls 计数封在原 chatOnce 里，换掉实现就得自己数。
+  const seen: string[] = []
+  a.s.chatOnce = async (uid) => {
+    seen.push(uid)
+    return { ok: false, state: 'transport', message: `link ${uid} down` }
+  }
+  add(router, a.s)
+
+  const r = await router.testModel('supA', 'a-model', 'u1')
+  assert.equal(r.ok, false)
+  assert.deepEqual(seen, ['u1'], '失败也不该换号重试')
+  assert.match(r.error ?? '', /u1/, '错误信息要点名是哪个连接挂了')
+})
+
+test('指定不存在的连接：明确报「连接不存在」，而不是静默测了别的号', async () => {
+  const { router } = rig()
+  const a = spy('supA', 'a-model')
+  a.s.accounts = () => [{ uid: 'u1', credits: 0, state: 'ok' }]
+  a.s.status = () => ({ id: 'supA', name: 'supA', accounts: a.s.accounts() })
+  add(router, a.s)
+
+  const r = await router.testModel('supA', 'a-model', 'gone')
+  assert.equal(r.ok, false)
+  assert.equal(a.calls, 0, '一个号都不该被试')
+  assert.match(r.error ?? '', /不存在/)
+})

package/src/shared.ts

@@ -79,6 +79,11 @@ export interface RouterHealthResponse {
     capabilities?: string[]
     /** 来源：内置 / 用户目录 / 外部插件。 */
     source?: 'builtin' | 'user' | 'external'
+    /**
+     * 供应商开关（是否参与路由）。**关掉的仍出现在这个列表里** —— 否则关掉之后
+     * 就没有可指的对象、再也开不回来。缺省按开启读（老版本核心没有这个字段）。
+     */
+    enabled?: boolean
   }>
   error?: string
 }
@@ -152,6 +157,13 @@ export interface RouterExtItem {
   ready?: boolean
   /** 一句话状态说明（如「本机未装 rtk」）。 */
   detail?: string
+  /**
+   * 来源：随核心分发的内置扩展标 `builtin`，独立安装的不标（= plugin）。
+   *
+   * 插件页那个自绘的「路由组件」节据此**只列独立安装的**：内置的已经在原生
+   * 「包含的组件」里占一行了，两处都列就是同一个东西显示两遍（与内置供应商同理）。
+   */
+  source?: 'builtin'
 }
 
 /** `/router/api/ext` response（扩展插件列表 + 开关）。 */

package/src/supplier-config.ts

@@ -23,6 +23,14 @@ import { dirname, join } from 'node:path'
 export const CREDITS_UNKNOWN = -1
 
 export interface SupplierConfig {
+  /**
+   * 这个供应商是否参与路由（用户开关，与扩展开关同构）。
+   *
+   * **缺省 true** —— 没记录过就是开着。关掉 = 核心不把它接进路由（`Router` 的
+   * 活跃集合），请求不会落到它、模型列表/组合里也不再出现它，而它自己仍留在
+   * `/health` 与面板里（不然关掉之后就找不回来、开关也失去了开关的对象）。
+   */
+  enabled: boolean
   alias: string
   disabled: string[]
   custom: string[]
@@ -87,7 +95,7 @@ export class SupplierConfigStore {
   get(supplierId: string): SupplierConfig {
     let cfg = this.bySupplier.get(supplierId)
     if (!cfg) {
-      cfg = { alias: '', disabled: [], custom: [], poolOrder: [], credits: {}, accountNames: {} }
+      cfg = { enabled: true, alias: '', disabled: [], custom: [], poolOrder: [], credits: {}, accountNames: {} }
       this.bySupplier.set(supplierId, cfg)
     }
     return cfg
@@ -110,6 +118,26 @@ export class SupplierConfigStore {
     return { ok: true }
   }
 
+  // ---- 供应商开关（用户对核心面板的操作，归核心持久化，与 ext.json 同一层） ----
+
+  /** 这个供应商是否参与路由（未记录过 = 开）。 */
+  isEnabled(supplierId: string): boolean {
+    return this.get(supplierId).enabled
+  }
+
+  /**
+   * 置供应商开关。**不写盘**时值不变也要返回，让调用方知道是否需要重连路由。
+   * @returns 值确实变了
+   */
+  setEnabled(supplierId: string, enabled: boolean): boolean {
+    if (supplierId === '') return false
+    const cfg = this.get(supplierId)
+    if (cfg.enabled === enabled) return false
+    cfg.enabled = enabled
+    this.saveLocked()
+    return true
+  }
+
   setModelEnabled(supplierId: string, modelId: string, enabled: boolean): void {
     const cfg = this.get(supplierId)
     cfg.disabled = enabled
@@ -208,6 +236,8 @@ export class SupplierConfigStore {
     }
     for (const [id, c] of Object.entries(f.suppliers ?? {})) {
       this.bySupplier.set(id, {
+        // 老配置没有这个字段（写盘早于本开关）→ 视为开着，不让升级把全灭变成全开
+        enabled: typeof c.enabled === 'boolean' ? c.enabled : true,
         alias: typeof c.alias === 'string' ? c.alias : '',
         disabled: Array.isArray(c.disabled) ? c.disabled.filter((m) => typeof m === 'string') : [],
         custom: Array.isArray(c.custom) ? c.custom.filter((m) => typeof m === 'string') : [],
@@ -223,6 +253,7 @@ export class SupplierConfigStore {
     const f: ConfigFile = { suppliers: {} }
     for (const [id, cfg] of this.bySupplier) {
       f.suppliers[id] = {
+        enabled: cfg.enabled,
         alias: cfg.alias,
         disabled: [...cfg.disabled],
         custom: [...cfg.custom],

package/src/suppliers/contract.ts

@@ -9,6 +9,7 @@
  * 用户自定义供应商 js 放到 `~/.dsh/profiles/web/suppliers/*.js`，重启后自动加载。
  * 内置供应商与用户 js 同构（差异化能力驱动）。
  */
+import type { Context } from '@deepseek-ai/cordis'
 import type { ChatRequest, ModelInfo, SupplierAccount } from '../router/types.ts'
 import type { SupplierConfigStore } from '../supplier-config.ts'
 import type { CredentialStore } from '../credential-store.ts'
@@ -40,8 +41,16 @@ export interface SupplierEnv {
   onLateFailure?: (uid: string, model: string, state: AccountState, message: string) => void
 }
 
-/** 通用供应商工厂：一个 js 模块 export 它（或 default export 它），loader 调用得到实例。 */
-export type SupplierFactory = (env: SupplierEnv) => SupplierModule
+/**
+ * 通用供应商工厂：一个 js 模块 export 它（或 default export 它），loader 调用得到实例。
+ *
+ * `source` 是**可选标签**，声明这个供应商是从哪儿来的。核心用它把 `/health` 的
+ * `source` 报准（面板按它分「内置 / 插件」两组，面板和插件页都看这个值）。
+ * 不声明 = `external`（独立安装的供应商插件的现状，一个字段都不用改）。
+ */
+export type SupplierFactory = ((env: SupplierEnv) => SupplierModule) & {
+  source?: 'builtin'
+}
 
 /**
  * 账户此刻的状态 —— 插件**解读**上游信号后的语义状态。
@@ -170,3 +179,46 @@ export interface SupplierModule {
 
 /** 供应商账号（复用 router 类型，供 loader 包装）。 */
 export type { SupplierAccount }
+
+/**
+ * `router.suppliers` 共享聚合表的取值：一个供应商工厂。
+ *
+ * 核心 provide 空表；**谁都可以往里 append** —— 内置供应商（core 自己的插件行）
+ * 与独立安装的供应商插件走的是同一条通道、同一套契约，核心那边不区分内外，
+ * 只看工厂上的 `source` 标签。
+ */
+export type SupplierRegistry = Record<string, SupplierFactory>
+
+/**
+ * 读当前 `router.suppliers` 表（同一 live 对象，可追加）——供应商行用它登记自己。
+ *
+ * 读法与 `ext/contract.ts` 的 `currentExts` 同一套（cordis 的 ctx 是 Proxy，
+ * 未声明的服务直接 get 会抛，所以走 `get()` 兜底）。
+ */
+export function currentSuppliers(ctx: unknown): SupplierRegistry | undefined {
+  const c = ctx as {
+    get?: (key: string) => unknown
+    router?: { suppliers?: SupplierRegistry }
+  }
+  return (c.get?.('router.suppliers') ?? c.router?.suppliers) as SupplierRegistry | undefined
+}
+
+/**
+ * 把一个供应商工厂登记进 `router.suppliers`，并通知核心去装载它。
+ *
+ * 为什么自己 emit `internal/service`：核心靠这个事件发现「表里多了供应商」
+ * （同 `router.ext` 的做法）。**幂等** —— 同一个 id 已经在表里就直接返回，
+ * 不会把别人的登记顶掉（内置行与用户目录 js 同名时由核心按优先级裁决，
+ * 这里不越权覆盖）。
+ */
+export function registerSupplierRow(ctx: Context, id: string, factory: SupplierFactory): void {
+  ctx.inject(['router.suppliers'], (sctx) => {
+    const table = currentSuppliers(sctx)
+    if (table === undefined) return
+    if (table[id] !== undefined) return
+    table[id] = factory
+    // 核心只 provide 空表、**不监听表的变更**（表里放的是工厂，实例化要它的
+    // env），所以新增条目必须自己喊一声，否则核心只在启动时扫过一遍。
+    ctx.emit('internal/service', 'router.suppliers', table)
+  })
+}

package/src/suppliers/loader.test.ts

@@ -9,10 +9,10 @@
  */
 import test from 'node:test'
 import assert from 'node:assert/strict'
-import { mkdtempSync } from 'node:fs'
+import { mkdtempSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { wrapModule } from './loader.ts'
+import { loadSuppliers, supplierWins, wrapModule } from './loader.ts'
 import { SupplierConfigStore } from '../supplier-config.ts'
 import type { CredentialStore } from '../credential-store.ts'
 import type { SupplierEnv, SupplierModule, SupplierAccountNow, ChatOnceResult } from './contract.ts'
@@ -181,3 +181,37 @@ test('onLateFailure 空 uid（无账号供应商）→ 不记，不炸', () => {
   assert.doesNotThrow(() => e.onLateFailure?.('', 'm1', 'quota', 'boom'))
   assert.deepEqual(loaded.supplier.status().accounts.map((a) => a.cooling), [false, false])
 })
+
+// ---- 同 id 冲突的优先级：用户目录 js > 内置行 > 外部插件供应商 ----
+// 规则错了不抛异常，只会让用户的覆盖悄悄失效，所以必须有闸门。
+
+test('优先级：用户目录的 js 压过内置行（内置改行之后不能反过来）', () => {
+  assert.equal(supplierWins('user', 'builtin'), true)
+  assert.equal(supplierWins('user', 'external'), true)
+})
+
+test('优先级：内置行压过外部插件供应商，同级不顶替', () => {
+  assert.equal(supplierWins('builtin', 'external'), true)
+  assert.equal(supplierWins('builtin', 'builtin'), false)
+  assert.equal(supplierWins('external', 'builtin'), false)
+  assert.equal(supplierWins('external', 'external'), false)
+  assert.equal(supplierWins('user', 'user'), false)
+})
+
+test('用户目录只加载 *.js，且同 id 后者覆盖前者（按文件名序）', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'sup-dir-'))
+  writeFileSync(join(dir, 'a-first.js'), 'export const id = "dup"\nexport const name = "First"\nexport const accounts = () => []\n')
+  writeFileSync(join(dir, 'b-second.js'), 'export const id = "dup"\nexport const name = "Second"\nexport const accounts = () => []\n')
+  writeFileSync(join(dir, 'notes.txt'), '不是 js，不该被加载')
+  const { suppliers, errors } = await loadSuppliers({
+    userDir: dir,
+    dataDir: dir,
+    store: new SupplierConfigStore(join(dir, 'cfg.json')),
+    credentials: {} as CredentialStore,
+    log: () => {},
+  })
+  assert.deepEqual(errors, [])
+  assert.deepEqual(suppliers.map((s) => s.supplier.id), ['dup'])
+  assert.equal(suppliers[0]?.supplier.name, 'Second')
+  assert.equal(suppliers[0]?.source, 'user')
+})

package/src/suppliers/loader.ts

@@ -1,10 +1,16 @@
 /**
- * 供应商 loader —— 扫描 suppliers 目录下的 *.js，动态 import，按契约包装成
+ * 供应商 loader —— 扫描 **用户目录**下的 *.js，动态 import，按契约包装成
  * 内部 Supplier，并暴露"能力检测"(capabilities)供通用路由/前端按能力渲染。
  *
- * 加载来源（两处，profile 优先）：
- *   1. 内置：<plugin>/lib/suppliers/*.js（随插件分发）
- *   2. 用户：~/.dsh/profiles/web/suppliers/*.js（用户自定义）
+ * 加载来源（两处）：
+ *   1. 用户：`~/.dsh/profiles/<profile>/suppliers/*.js`（自定义供应商）
+ *   2. 内置：**插件页「包含的组件」里的行** —— core 自己的 cordis.patch.yml
+ *      insert 了三个子路径模块，经 `router.suppliers` 表进来，与独立安装的
+ *      供应商插件同一条通道，核心不区分内外，只看工厂上的 `source` 标签。
+ *
+ * 内置曾经也是「扫 `<plugin>/lib/suppliers/*.js`」（本文件早先的 builtinDir）。
+ * 改成行之后那条路径已删：扫目录拿不到行的身份（插件页的开关/显示名/说明），
+ * 而且关一个内置供应商要手改配置才生效 —— 行才有宿主管的开关。
  */
 import { readdirSync } from 'node:fs'
 import { join, dirname, basename } from 'node:path'
@@ -196,10 +202,23 @@ function scanDir(dir: string): string[] {
   }
 }
 
+/**
+ * 同 id 冲突时的优先级：**用户目录 js > 内置行 > 外部插件供应商**。
+ *
+ * 为什么用户目录最高：用户放一个同 id 的 js 就是想替换它，这是「扫目录时代」
+ * 就有的语义（见本文件早先的 `loadSuppliers`：内置被用户版覆盖），内置改成行
+ * 之后不能悄悄反过来。
+ *
+ * 纯函数 + 有测试：这条规则错了不会抛异常，只会让用户的覆盖悄悄失效。
+ */
+const SUPPLIER_RANK: Record<LoadedSupplier['source'], number> = { user: 2, builtin: 1, external: 0 }
+
+export function supplierWins(incoming: LoadedSupplier['source'], existing: LoadedSupplier['source']): boolean {
+  return SUPPLIER_RANK[incoming] > SUPPLIER_RANK[existing]
+}
+
 export interface LoadSuppliersOptions {
-  /** 内置供应商目录（<plugin>/lib/suppliers）。 */
-  builtinDir: string
-  /** 用户供应商目录（~/.dsh/profiles/web/suppliers）。 */
+  /** 用户供应商目录（~/.dsh/profiles/<profile>/suppliers）。 */
   userDir: string
   /** 数据目录。 */
   dataDir: string
@@ -210,7 +229,10 @@ export interface LoadSuppliersOptions {
   log: (msg: string) => void
 }
 
-/** 加载全部供应商（内置 + 用户，用户覆盖内置同 id）。 */
+/**
+ * 加载用户目录下的供应商。同一个 id 出现多个文件时**后者覆盖前者**（按文件名序），
+ * 与内置共存的裁决交给核心（`registerLoaded` 的优先级：用户目录 js > 行）。
+ */
 export async function loadSuppliers(opts: LoadSuppliersOptions): Promise<{
   suppliers: LoadedSupplier[]
   errors: SupplierLoadError[]
@@ -219,18 +241,11 @@ export async function loadSuppliers(opts: LoadSuppliersOptions): Promise<{
   const byId = new Map<string, LoadedSupplier>()
   const errors: SupplierLoadError[] = []
 
-  const files = [
-    ...scanDir(opts.builtinDir).map((f) => ({ f, builtin: true })),
-    ...scanDir(opts.userDir).map((f) => ({ f, builtin: false })),
-  ]
-  for (const { f, builtin } of files) {
+  for (const f of scanDir(opts.userDir).sort()) {
     try {
-      const loaded = await loadOne(f, env, builtin ? 'builtin' : 'user')
-      // 用户目录覆盖内置
-      const existing = byId.get(loaded.supplier.id)
-      if (existing && builtin) continue // 内置已被用户版覆盖
+      const loaded = await loadOne(f, env, 'user')
       byId.set(loaded.supplier.id, loaded)
-      opts.log(`supplier ${loaded.supplier.id} loaded (${builtin ? 'builtin' : 'user'}) from ${basename(f)}`)
+      opts.log(`supplier ${loaded.supplier.id} loaded (user) from ${basename(f)}`)
     } catch (err) {
       errors.push({ id: basename(f, '.js'), file: f, error: (err as Error).message })
       opts.log(`supplier load failed ${basename(f)}: ${(err as Error).message}`)

package/src/suppliers/nvidia/index.ts

@@ -0,0 +1,27 @@
+/**
+ * NVIDIA NIM 的 **cordis 行** —— 官方插件页（设置 → 插件 → dsh-router-core）详情页
+ * 「包含的组件」里的那一行。
+ *
+ * 为什么多一层壳：`plugin.ts` 已经把 `name` 用作**面板显示名**（供应商契约的
+ * 字段，所有供应商插件都这么写），而 cordis 的插件身份也要一个 `name`，两者
+ * 抢同一个名字。所以行 = 这一层壳（cordis 身份 + 登记），实现 = `plugin.ts`。
+ *
+ * 这一行只做一件事：把供应商工厂登记进核心的 `router.suppliers` 表。**通道和
+ * 契约与独立安装的供应商插件完全一样**（core 不区分内外，只看工厂上的
+ * `source: 'builtin'` 标签），因此这一行在插件页能拿到宿主管的开关：关掉它 =
+ *  loader 不 import 这个模块 = 供应商压根没注册 = 路由不会落到它。
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { registerSupplierRow, type SupplierEnv, type SupplierFactory } from '../contract.ts'
+import factory, { id } from './plugin.ts'
+
+/** cordis 插件身份（配置树里这一行的技术名；显示名走同目录的 locale）。 */
+export const name = 'dsh-router-supplier-nvidia'
+
+/** 登记本供应商。幂等：同一个 id 已在表里就直接返回，不顶掉别人的登记。 */
+export function apply(ctx: Context): void {
+  // `source: 'builtin'` 让 /health 如实报出「内置」，面板的「内置 / 插件」
+  // 两组才不会把随核心分发的供应商误标成插件提供的。
+  const row: SupplierFactory = Object.assign((env: SupplierEnv) => factory(env), { source: 'builtin' as const })
+  registerSupplierRow(ctx, id, row)
+}

package/src/suppliers/nvidia/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "NVIDIA NIM",
+    "description": "NVIDIA 官方推理通道，API key 制"
+  }
+}

package/src/suppliers/nvidia/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "NVIDIA NIM",
+    "description": "NVIDIA 官方推理通道，API key 制"
+  }
+}

package/src/suppliers/nvidia/row.json

@@ -0,0 +1,5 @@
+{
+  "name": "dsh-router-core-supplier-nvidia",
+  "type": "module",
+  "description": "NVIDIA 官方推理通道，API key 制（随 dsh-router 核心分发）"
+}

package/src/suppliers/opencode/index.ts

@@ -0,0 +1,27 @@
+/**
+ * OpenCode 的 **cordis 行** —— 官方插件页（设置 → 插件 → dsh-router-core）详情页
+ * 「包含的组件」里的那一行。
+ *
+ * 为什么多一层壳：`plugin.ts` 已经把 `name` 用作**面板显示名**（供应商契约的
+ * 字段，所有供应商插件都这么写），而 cordis 的插件身份也要一个 `name`，两者
+ * 抢同一个名字。所以行 = 这一层壳（cordis 身份 + 登记），实现 = `plugin.ts`。
+ *
+ * 这一行只做一件事：把供应商工厂登记进核心的 `router.suppliers` 表。**通道和
+ * 契约与独立安装的供应商插件完全一样**（core 不区分内外，只看工厂上的
+ * `source: 'builtin'` 标签），因此这一行在插件页能拿到宿主管的开关：关掉它 =
+ *  loader 不 import 这个模块 = 供应商压根没注册 = 路由不会落到它。
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { registerSupplierRow, type SupplierEnv, type SupplierFactory } from '../contract.ts'
+import factory, { id } from './plugin.ts'
+
+/** cordis 插件身份（配置树里这一行的技术名；显示名走同目录的 locale）。 */
+export const name = 'dsh-router-supplier-opencode'
+
+/** 登记本供应商。幂等：同一个 id 已在表里就直接返回，不顶掉别人的登记。 */
+export function apply(ctx: Context): void {
+  // `source: 'builtin'` 让 /health 如实报出「内置」，面板的「内置 / 插件」
+  // 两组才不会把随核心分发的供应商误标成插件提供的。
+  const row: SupplierFactory = Object.assign((env: SupplierEnv) => factory(env), { source: 'builtin' as const })
+  registerSupplierRow(ctx, id, row)
+}

package/src/suppliers/opencode/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "OpenCode",
+    "description": "Zen 免费档（无需账号）"
+  }
+}

package/src/suppliers/opencode/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "OpenCode",
+    "description": "Zen 免费档（无需账号）"
+  }
+}

package/src/suppliers/opencode/row.json

@@ -0,0 +1,5 @@
+{
+  "name": "dsh-router-core-supplier-opencode",
+  "type": "module",
+  "description": "Zen 免费档（无需账号）（随 dsh-router 核心分发）"
+}

package/src/suppliers/openrouter/index.ts

@@ -0,0 +1,27 @@
+/**
+ * OpenRouter 的 **cordis 行** —— 官方插件页（设置 → 插件 → dsh-router-core）详情页
+ * 「包含的组件」里的那一行。
+ *
+ * 为什么多一层壳：`plugin.ts` 已经把 `name` 用作**面板显示名**（供应商契约的
+ * 字段，所有供应商插件都这么写），而 cordis 的插件身份也要一个 `name`，两者
+ * 抢同一个名字。所以行 = 这一层壳（cordis 身份 + 登记），实现 = `plugin.ts`。
+ *
+ * 这一行只做一件事：把供应商工厂登记进核心的 `router.suppliers` 表。**通道和
+ * 契约与独立安装的供应商插件完全一样**（core 不区分内外，只看工厂上的
+ * `source: 'builtin'` 标签），因此这一行在插件页能拿到宿主管的开关：关掉它 =
+ *  loader 不 import 这个模块 = 供应商压根没注册 = 路由不会落到它。
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { registerSupplierRow, type SupplierEnv, type SupplierFactory } from '../contract.ts'
+import factory, { id } from './plugin.ts'
+
+/** cordis 插件身份（配置树里这一行的技术名；显示名走同目录的 locale）。 */
+export const name = 'dsh-router-supplier-openrouter'
+
+/** 登记本供应商。幂等：同一个 id 已在表里就直接返回，不顶掉别人的登记。 */
+export function apply(ctx: Context): void {
+  // `source: 'builtin'` 让 /health 如实报出「内置」，面板的「内置 / 插件」
+  // 两组才不会把随核心分发的供应商误标成插件提供的。
+  const row: SupplierFactory = Object.assign((env: SupplierEnv) => factory(env), { source: 'builtin' as const })
+  registerSupplierRow(ctx, id, row)
+}

package/src/suppliers/openrouter/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "OpenRouter",
+    "description": "OpenRouter 聚合通道，API key 制"
+  }
+}