dsh-router-core 0.4.0 → 0.4.2

package/src/ext-test/ext-test.test.ts

@@ -0,0 +1,60 @@
+/**
+ * 插件自检扩展（`router.ext` 侧）测试 —— 锁住三件事：
+ *   1. 登记进 `router.ext` 表，带上可显示的身份（名字/说明/就绪）；
+ *   2. **幂等**：同一个 id 已在表里就不顶掉别人的登记；
+ *   3. 恒为就绪 —— 自检能力不依赖外部二进制，不该提前否决（真跑一次才知道）。
+ *
+ * 为什么测这个：扩展的「卡片出现与否」完全取决于它在不在这张表里，而表是核心
+ * provide 的**同一个 live 对象**。登记没发生的话，面板与插件页都看不到它，且不报错。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { createTestExt, EXT_TEST_ID } from './plugin.ts'
+import { apply, name as CORDIS_NAME } from './index.ts'
+import type { RouterExtService } from '../ext/contract.ts'
+
+test('扩展器带上面板要用的身份，且恒为就绪', () => {
+  const ext = createTestExt()
+  assert.equal(ext.id, EXT_TEST_ID)
+  assert.equal(ext.name, '插件自检')
+  assert.ok((ext.description ?? '').length > 0, '没有说明，插件页那一行就没有副标题')
+  assert.equal(ext.getState().ready, true, '自检不依赖本机二进制，不该报未就绪')
+})
+
+test('cordis 身份是行 id（与 patch 里声明的逐字相同，否则 loader 认不出）', () => {
+  assert.equal(CORDIS_NAME, 'dsh-router-ext-test')
+})
+
+/** 最小 ctx：inject 立刻回调、emit 记下来。 */
+function fakeCtx(table: RouterExtService): {
+  ctx: Parameters<typeof apply>[0]
+  events: string[]
+} {
+  const events: string[] = []
+  return {
+    events,
+    ctx: {
+      inject: (deps: string[], cb: (sctx: unknown) => void) => {
+        cb({ get: (key: string) => (key === 'router.ext' ? table : undefined) })
+      },
+      emit: (event: string) => { events.push(event) },
+    } as unknown as Parameters<typeof apply>[0],
+  }
+}
+
+test('apply 把扩展登记进 router.ext 表（这张表就是「卡片出现」的唯一依据）', () => {
+  const table: RouterExtService = {}
+  const { ctx, events } = fakeCtx(table)
+  apply(ctx)
+  assert.equal(table[EXT_TEST_ID]?.name, '插件自检')
+  assert.deepEqual(events, [], '核心持有同一个 live 对象且每次请求现读，不需要广播事件')
+})
+
+test('幂等：同一个 id 已在表里时不顶掉别人的登记', () => {
+  const table: RouterExtService = {}
+  const { ctx } = fakeCtx(table)
+  apply(ctx)
+  const first = table[EXT_TEST_ID]
+  apply(ctx)
+  assert.equal(table[EXT_TEST_ID], first, '重复登记不该换成一个新对象')
+})

package/src/ext-test/index.ts

@@ -0,0 +1,35 @@
+/**
+ * 插件自检扩展的 **cordis 行** —— 官方插件页（设置 → 插件 → dsh-router-core）详情页
+ * 原生「包含的组件」里的那一行。
+ *
+ * 壳存在的理由与内置供应商那三层一样：`plugin.ts` 已经把 `name` 用作**面板显示名**
+ * （扩展契约的字段，所有扩展都这么写），而 cordis 的插件身份也要一个 `name`，两者抢
+ * 同一个名字。所以行 = 这一层壳（cordis 身份 + 登记），实现 = `plugin.ts`。
+ *
+ * **默认关闭**（patch 里 `disabled: true`）：行关闭时 loader 根本不 import 这个模块，
+ * 扩展也就没进 `router.ext` 表 —— 所以「打开才出现这张卡片」是天然的，不需要额外的
+ * 状态位。用户在这一行打开后，卡片出现在插件页的「路由组件 → 扩展」组与面板的
+ * 「扩展」页。
+ *
+ * 登记时把扩展开关置为开：本扩展**没有独立的运行期开关**，它的开关就是这一行
+ * （宿主管的那个）。不置上的话，用户开了行还要再点一次，两级开关说同一件事。
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { currentExts, currentExtStore } from '../ext/contract.ts'
+import { createTestExt, EXT_TEST_ID } from './plugin.ts'
+
+/** cordis 插件身份（配置树里这一行的技术名；显示名走同目录的 locale）。 */
+export const name = 'dsh-router-ext-test'
+
+/** 登记本扩展。幂等：同一个 id 已在表里就直接返回，不顶掉别人的登记。 */
+export function apply(ctx: Context): void {
+  ctx.inject(['router.ext'], (sctx) => {
+    const table = currentExts(sctx)
+    if (table === undefined) return
+    if (table[EXT_TEST_ID] !== undefined) return
+    table[EXT_TEST_ID] = createTestExt()
+    currentExtStore(sctx)?.setEnabled(EXT_TEST_ID, true)
+    // 核心持有的是**同一个 live 对象**（它 provide 的空表），且 `/ext` 每次请求都
+    // 现读这张表 —— 所以往里 append 就够了，不需要（也不存在）广播事件。
+  })
+}

package/src/ext-test/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Plugin self-check",
+    "description": "Run a real access test against a supplier/model/connection, or run a contract check over an external supplier plugin (every member: implemented / usable / not executed)"
+  }
+}

package/src/ext-test/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "插件自检",
+    "description": "选供应商、模型与连接跑一次真实访问测试；或对外部供应商插件做契约体检，逐个成员报告实现与可用情况"
+  }
+}

package/src/ext-test/plugin.ts

@@ -0,0 +1,34 @@
+/**
+ * 插件自检扩展（`router.ext` 侧的实现）—— 声明与状态都在这里，**不做任何拦截**。
+ *
+ * 它和 rtk 那类扩展的区别要写清楚：本扩展**不挂任何监听、不改写任何命令**，
+ * 唯一作用是让用户在官方插件页里打开一块自检面板（选供应商 / 模型 / 连接，跑一次
+ * 真实的访问测试并看到底报了什么）。所以它复用 `router.ext` 这条通道只是为了拿到
+ * **发现 + 开关**两件事，而不是为了拦截。
+ *
+ * 面板本身在浏览器侧（`src/client/ExtTestPanel.tsx`），通过原生行的
+ * `plugins.row.config` 座位挂在「包含的组件」里那一行的详情页上；这里只负责让它在
+ * 列表里有个身份、以及报出运行时就绪状态。
+ */
+import type { RouterExt } from '../ext/contract.ts'
+
+/** 扩展开关表里的注册键（也是 URL 面板读它的 id）。 */
+export const EXT_TEST_ID = 'test'
+
+/**
+ * 构造这个扩展器。
+ *
+ * `getState()` 恒为就绪：自检能力不依赖外部二进制（不像 rtk 需要本机装 rtk），
+ * 「能不能测」取决于用户选的供应商/模型/连接，不该由扩展提前否决 —— 真跑一次
+ * 才知道，那时错误信息比一个「未就绪」有用得多。
+ */
+export function createTestExt(): RouterExt {
+  return {
+    id: EXT_TEST_ID,
+    name: '插件自检',
+    description: '选供应商、模型与连接跑一次真实访问测试；或对外部供应商插件做契约体检，逐个成员报告实现与可用情况',
+    // 随核心分发 -> 插件页的原生「包含的组件」里有它一行，自绘节里不再重复列。
+    source: 'builtin' as const,
+    getState: () => ({ ready: true }),
+  }
+}

package/src/ext-test/row.json

@@ -0,0 +1,5 @@
+{
+  "name": "dsh-router-core-ext-test",
+  "type": "module",
+  "description": "插件自检扩展（随 dsh-router 核心分发）"
+}

package/src/host-base-url.test.ts

@@ -0,0 +1,129 @@
+/**
+ * 网关端点按**宿主实际监听端口**解析 —— issue #9 的闸门。
+ *
+ * ## 这条闸门拦的是什么
+ *
+ * `/v1/*` 是注册在**宿主** webServer 上的路由，端口由启动通道给：`dsh web` 默认
+ * 3080，桌面端官方通道、以及 `port: 0`（OS 分配）都不是。adapter 曾把
+ * `http://localhost:3080/v1` 写死，于是那些宿主上 Router 每一轮对话都是
+ * `dsh-router upstream call failed: fetch failed`，而 `/v1` 明明就在本机跑着。
+ *
+ * 判据刻意用**真服务器 + OS 分配端口**而不是打桩 fetch：打桩只能证明字符串拼对了，
+ * 证明不了「非 3080 端口上请求真的落得到」（这正是当初漏掉这条 bug 的原因）。
+ * `listen(0)` 拿到的端口几乎不可能是 3080，于是「用 3080 也能过」的假修法在这条
+ * 闸门下会当场变红。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { readdirSync, readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { RouterAdapter } from './llm/adapter.ts'
+import { loopbackBaseURL } from './host-base-url.ts'
+
+/** 起一个只回一条最小 SSE 的真服务器，回报 OS 分配的端口与收到的路径。 */
+async function serveSse(): Promise<{ port: number; hits: string[]; close: () => Promise<void> }> {
+  const hits: string[] = []
+  const server = createServer((req, res) => {
+    hits.push(req.url ?? '')
+    res.writeHead(200, { 'content-type': 'text/event-stream' })
+    res.end(`data: ${JSON.stringify({ choices: [{ delta: { content: 'ok' } }] })}\n\ndata: [DONE]\n\n`)
+  })
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+  const { port } = server.address() as AddressInfo
+  return { port, hits, close: () => new Promise<void>((resolve) => server.close(() => resolve())) }
+}
+
+/** 跑完一次 adapter 流，返回收到的块类型。 */
+async function drain(adapter: RouterAdapter): Promise<string[]> {
+  const types: string[] = []
+  for await (const c of adapter.stream({ model: 'm', messages: [], signal: AbortSignal.timeout(5000) } as never)) {
+    types.push(c.type)
+  }
+  return types
+}
+
+test('端点：宿主端口不是 3080 时，请求照样落得到（issue #9 的原始现场）', async () => {
+  const up = await serveSse()
+  try {
+    assert.notEqual(up.port, 3080, '这条用例的判据就是「端口不是 3080」')
+    const adapter = new RouterAdapter(loopbackBaseURL(() => up.port), { comboModels: async () => [] })
+    const types = await drain(adapter)
+    assert.deepEqual(up.hits, ['/v1/chat/completions'], `请求应打到宿主 /v1，实际打到：${JSON.stringify(up.hits)}`)
+    assert.ok(types.includes('text-delta'), `应真的收到上游内容，实际块类型：${JSON.stringify(types)}`)
+  } finally {
+    await up.close()
+  }
+})
+
+test('端点：端口每次请求现算（listen 前读不到、宿主重启换端口都不缓存）', async () => {
+  const first = await serveSse()
+  const second = await serveSse()
+  try {
+    let port: number | undefined = first.port
+    let reads = 0
+    const adapter = new RouterAdapter(
+      loopbackBaseURL(() => {
+        reads += 1
+        return port
+      }),
+      { comboModels: async () => [] },
+    )
+    await drain(adapter)
+    port = second.port // 宿主换了端口（重启 / 重新 listen）
+    await drain(adapter)
+    assert.deepEqual(first.hits, ['/v1/chat/completions'], '第一次应打在第一个端口')
+    assert.deepEqual(second.hits, ['/v1/chat/completions'], '端口变了之后应改打新端口（不能缓存第一次的值）')
+    assert.ok(reads >= 2, `端口应每请求现读，实际只读了 ${reads} 次`)
+  } finally {
+    await first.close()
+    await second.close()
+  }
+})
+
+test('端点：端口读不到时报出原因，不回退 3080 硬猜', async () => {
+  const adapter = new RouterAdapter(loopbackBaseURL(() => undefined), { comboModels: async () => [] })
+  await assert.rejects(
+    () => drain(adapter),
+    (err: Error) => {
+      assert.match(err.message, /webServer/, `报错必须带原因，实际：${err.message}`)
+      assert.equal((err as { code?: string }).code, 'TRANSPORT', '应是可重试的传输类错误')
+      return true
+    },
+  )
+})
+
+test('端点：常量形态的 baseURL 仍然可用（测试与显式传入的老调用方）', () => {
+  assert.equal(loopbackBaseURL(() => 19387)(), 'http://127.0.0.1:19387/v1')
+})
+
+test('源码：非测试代码里不得再出现写死的 3080 端点', () => {
+  // 防复发闸门：这次的根因就是一行写死的字符串，只靠「端口现算」的实现测试拦不住
+  // 将来有人在别处再写一遍。判据只看**代码**（先剥掉注释）——注释里可以、也应该
+  // 写明「当年就是这里写死了 3080」。
+  const root = fileURLToPath(new URL('.', import.meta.url))
+  const offenders: string[] = []
+  for (const file of walk(root)) {
+    if (/(?:localhost|127\.0\.0\.1):3080/.test(stripComments(readFileSync(file, 'utf8')))) {
+      offenders.push(file.slice(root.length))
+    }
+  }
+  assert.deepEqual(offenders, [], `这些文件里还有写死的 3080 端点（宿主端口随启动通道变）：${offenders.join(', ')}`)
+})
+
+/** 去掉块注释与行注释，只留可执行代码。 */
+function stripComments(text: string): string {
+  return text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '')
+}
+
+/** 递归列出 src 下的 .ts 文件（跳过测试自身：测试里出现端口字面量是合法的）。 */
+function walk(dir: string): string[] {
+  const out: string[] = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = `${dir}${entry.name}`
+    if (entry.isDirectory()) out.push(...walk(`${path}/`))
+    else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts')) out.push(path)
+  }
+  return out
+}

package/src/host-base-url.ts

@@ -0,0 +1,43 @@
+/**
+ * 网关端点地址（`http://127.0.0.1:<宿主端口>/v1`）的解析。
+ *
+ * ## 为什么端口不能写死
+ *
+ * dsh-router **自己不开端口**：`/v1/*` 是注册在**宿主** web server 上的路由
+ * （见 `index.ts` 的 `ctx.webServer.register`）。所以端点地址里的端口由启动通道
+ * 决定，而不是插件决定 —— `dsh web` 默认 3080，桌面端官方通道、以及配置
+ * `port: 0`（让 OS 分配）时都**不是** 3080。之前 adapter 把
+ * `http://localhost:3080/v1` 写死在构造参数里，于是非 3080 的宿主上 Router
+ * 的每一轮对话都是 `dsh-router upstream call failed: fetch failed`（issue #9）。
+ *
+ * ## 为什么返回函数而不是字符串
+ *
+ * `webServer.port` 是**监听之后**才有值的 getter（listen 前是 `undefined`），
+ * 且宿主重启/换端口后它会变。所以这里返回函数、**每次请求现算**，不在注册时
+ * 算一次 —— 注册发生在启动早期，那时算只会把「拿不到端口」固化成常量。
+ *
+ * ## 拿不到端口时为什么抛，而不是回退 3080
+ *
+ * 回退等于把同一个 bug 换种写法：端口读不到时宿主的路由也没在服务，回退到 3080
+ * 只会重新得到一句无从查证的 `fetch failed`。这里抛明确的话，让它出现在
+ * `LlmError` 消息里（adapter 在 fetch 同一个 try 里调它），报错自带原因。
+ */
+
+/** 回环地址：宿主即使监听 `0.0.0.0`（LAN 模式），走 127.0.0.1 也通。 */
+const LOOPBACK_HOST = '127.0.0.1'
+
+/**
+ * 造一个「每次调用现读宿主端口」的端点解析器。
+ *
+ * @param readPort 读宿主监听端口（`webServer.port`）。取不到时抛错而不是猜。
+ * @param path 端点路径前缀，默认 `/v1`。
+ */
+export function loopbackBaseURL(readPort: () => number | undefined, path: string = '/v1'): () => string {
+  return () => {
+    const port = readPort()
+    if (port === undefined) {
+      throw new Error('dsh-router: 宿主 webServer 端口未就绪（webServer.port 读不到），无法定位 /v1 端点')
+    }
+    return `http://${LOOPBACK_HOST}:${String(port)}${path}`
+  }
+}

package/src/index.ts

@@ -2,7 +2,8 @@
  * Host half of dsh-router — a simplified 9router.
  *
  * dsh-router IS the router: it exposes an OpenAI-compatible `/v1/*` endpoint
- * on the DSH web server (http://localhost:3080/v1), and routes requests to
+ * on the DSH web server (http://127.0.0.1:<宿主监听端口>/v1 — 端口随启动通道
+ * 变，`dsh web` 默认 3080，见 host-base-url.ts), and routes requests to
  * internal suppliers.
  *
  * Routes:
@@ -36,12 +37,13 @@ import { ROUTER_API_BASE, type RouterPeriod } from './shared.ts'
 import { Router } from './router/index.ts'
 import { RouterAdapter, type RouterAttachmentStore } from './llm/adapter.ts'
 import { KeysStore } from './keys.ts'
-import { loadSuppliers, wrapModule, type LoadedSupplier } from './suppliers/loader.ts'
+import { loadSuppliers, supplierWins, wrapModule, type LoadedSupplier } from './suppliers/loader.ts'
 import { supplierRoutes } from './suppliers/registry.ts'
-import type { SupplierEnv, SupplierModule } from './suppliers/contract.ts'
+import type { SupplierEnv, SupplierModule, SupplierRegistry } from './suppliers/contract.ts'
 import { SupplierConfigStore } from './supplier-config.ts'
 import { CredentialStore } from './credential-store.ts'
 import { dataDirOf, profileDirOf } from './data-dir.ts'
+import { loopbackBaseURL } from './host-base-url.ts'
 import { detectHostVersion, isHost017Plus, supportsLastHitDock } from './host-version.ts'
 import { ExtStore } from './ext/store.ts'
 import type { ExtInfo, ExtStoreService, RouterExt, RouterExtService } from './ext/contract.ts'
@@ -91,6 +93,12 @@ interface WebServerRoute {
 }
 interface WebServer {
   register: (route: WebServerRoute) => () => void
+  /**
+   * 宿主**实际监听**的端口（配置 port=0 时是 OS 分配的那个）。
+   * listen 之前为 undefined —— adapter 的端点按请求现读它，见 host-base-url.ts
+   * 与 issue #9。
+   */
+  readonly port?: number
 }
 
 /** Minimal shape of the llm service faces used here (设置-模型 提供方/模型目录). */
@@ -217,7 +225,7 @@ export function apply(rawContext: unknown): void {
     disposers.push(ctx.webServer.register({ kind: 'exact', path, handler }))
   }
 
-  // ---- 供应商注册表：内置 + 用户自定义 js + 外部插件供应商 ----
+  // ---- 供应商注册表：行（内置）+ 用户目录 js + 外部插件供应商 ----
   const loadedSuppliers: LoadedSupplier[] = []
   /** 每个供应商的 webServer 路由注销函数（注销时单独清理）。 */
   const supplierDisposers = new Map<string, Array<() => void>>()
@@ -261,23 +269,38 @@ export function apply(rawContext: unknown): void {
 
   // 内置 + 用户 + 外部插件供应商（异步加载，完成后注册路由 + 加入路由器）
   const registerLoaded = (loaded: LoadedSupplier): void => {
+    // 同 id 已有供应商：只有「级别更高」的那个能顶掉它（用户目录 js > 内置行 >
+    // 外部插件）。级别不高不低就直接丢，别把先到的那份卸了又装回来。
+    const existing = loadedSuppliers.find((l) => l.supplier.id === loaded.supplier.id)
+    if (existing !== undefined) {
+      if (!supplierWins(loaded.source, existing.source)) {
+        log(`supplier ${loaded.supplier.id} (${loaded.source}) skipped: ${existing.source} already registered`)
+        return
+      }
+      log(`supplier ${loaded.supplier.id}: ${existing.source} replaced by ${loaded.source}`)
+      unregisterSupplier(loaded.supplier.id)
+    }
     loadedSuppliers.push(loaded)
     router.add(loaded.supplier)
     registerSupplierRoutes(loaded)
   }
   /** 当前由 router.suppliers service 加载的供应商 id（外部插件卸载时全部注销）。 */
   let externalSupplierIds: string[] = []
-  const loadExternal = (suppliers: Record<string, (env: SupplierEnv) => SupplierModule>): void => {
+  const loadExternal = (suppliers: SupplierRegistry): void => {
     for (const [sid, factory] of Object.entries(suppliers)) {
       if (externalSupplierIds.includes(sid)) continue // 已加载（internal/service + inject 可能重复触发）
       try {
         const module = factory({ dataDir, log, store, credentials })
-        const loaded = wrapModule(module, { dataDir, log, store, credentials }, `service router.suppliers.${sid}`)
+        // 工厂上的 source 标签决定 `/health` 怎么报它：内置行标 'builtin'，独立
+        // 安装的供应商插件不标（= external）。面板按这个值分「内置 / 插件」两组，
+        // 标错就把随核心分发的供应商混进插件组了。
+        const kind = factory.source === 'builtin' ? 'builtin' : 'external'
+        const loaded = wrapModule(module, { dataDir, log, store, credentials }, `service router.suppliers.${sid}`, kind)
         registerLoaded(loaded)
         externalSupplierIds.push(loaded.supplier.id)
-        log(`external supplier loaded: ${sid}`)
+        log(`${kind} supplier loaded: ${sid}`)
       } catch (err) {
-        ctx.logger.warn(`[dsh-router] external supplier ${sid} load failed: ${(err as Error).message}`)
+        ctx.logger.warn(`[dsh-router] supplier ${sid} load failed: ${(err as Error).message}`)
       }
     }
   }
@@ -305,7 +328,6 @@ export function apply(rawContext: unknown): void {
       // 用户供应商目录也在 profile 里：跟着 baseUrl 走，别硬编码 `web`。
       const userDir = join(profileDirOf(ctx.baseUrl), 'suppliers')
       const { suppliers, errors } = await loadSuppliers({
-        builtinDir: join(import.meta.dirname, 'suppliers'), // 内置 js（opencode 等）
         userDir,
         dataDir,
         store,
@@ -394,6 +416,8 @@ export function apply(rawContext: unknown): void {
           apiKeyHint: loaded?.supplier.apiKeyHint,
           capabilities: loaded ? [...loaded.capabilities] : [],
           source: loaded?.source ?? 'external',
+          // 开关状态：关掉的供应商**仍在列表里**（关掉后要能再开），只是不参与路由。
+          enabled: s.enabled,
         }
       }),
     })
@@ -610,6 +634,8 @@ export function apply(rawContext: unknown): void {
           ...(e.icon !== undefined ? { icon: e.icon } : {}),
           enabled: extStore.isEnabled(e.id),
           ready: st?.ready === true,
+          // 随核心分发的扩展带这个标记（插件页自绘节据此不重复列它：它已经有原生行）
+          ...(raw.source === 'builtin' ? { source: 'builtin' as const } : {}),
           ...(st?.detail !== undefined ? { detail: st.detail } : {}),
         }
       })
@@ -724,12 +750,21 @@ export function apply(rawContext: unknown): void {
       // 带上组合的上下文窗口：没有它 dsh 的自动压缩算不出阈值、会静默关闭。
       // 图片序列化需要读附件字节：把 ctx.attachments 传给 adapter（dsh-attachment
       // 是宿主注入的 service，插件不直接 import 它，只依赖 duck-typed 切面）。
-      disposers.push(ctx.llm.registerAdapter(['router'], new RouterAdapter('http://localhost:3080/v1', {
+      // 端点**按宿主实际监听端口现算**：`/v1` 路由注册在宿主 webServer 上，端口由
+      // 启动通道给（dsh web 默认 3080，桌面端/port=0 时不是），写死 3080 会让
+      // Router 在那些宿主上每一轮都 `fetch failed`（issue #9）。
+      disposers.push(ctx.llm.registerAdapter(['router'], new RouterAdapter(
+        loopbackBaseURL(() => ctx.webServer?.port), {
         comboModels: async () => (await router.combos()).map((c) => {
           const w = router.comboContextWindow(c)
           return { id: c.name, ...(w !== undefined ? { contextWindow: w } : {}) }
         }),
-      }, () => ctx.get('attachments') as RouterAttachmentStore | undefined)))
+      },
+      () => ctx.get('attachments') as RouterAttachmentStore | undefined,
+      undefined,
+      // 第五个参数 = 降级诊断出口：图片读不到会降级成占位文本，原因必须出口
+      // （曾经那条路径是空 catch，issue #8 的回归因此静默了两个内测版本）。
+      (msg) => ctx.logger.warn(`[dsh-router] ${msg}`))))
       log('llm provider (Router) + discovery + adapter registered ok')
       // 预热模型缓存：`comboContextWindow` 只读缓存、不打上游，缓存空着就
       // 报不出窗口。这里后台填一次，让第一次 resolveModel 就有值。

package/src/llm/adapter.test.ts

@@ -683,13 +683,48 @@ test('resolveModel 透传组合的 contextWindow（自动压缩才能算阈值
 
 /* ---------------- 图片序列化：图片必须真正到上游（不静默丢图） ---------------- */
 
-/** 假附件 store：返回指定 mediaType + bytes 的请求版本。 */
+/**
+ * 假附件 store：**按宿主的方式校验请求目标**，返回指定 mediaType + bytes 的请求版本。
+ *
+ * 为什么必须校验：宿主 0.1.6 起把请求目标从 `ImageRequestPolicy`（maxPixels +
+ * maxBytes）换成 `ImageRequestTarget`（width + height + maxBytes），字段不匹配就在
+ * `validateTarget()` 抛错。之前这个假 store **两个参数都不看**（`async () => ({...})`），
+ * 于是插件侧传错字段没有任何测试会发现 —— 生产里图片静默降级成占位文本，跨两个
+ * 内测版本没人察觉（issue #8）。现在假 store 照宿主那样校验，字段写错会当场红。
+ */
 function fakeAttachments(mediaType = 'image/png', data = new TextEncoder().encode('<png-bytes>')): {
-  readImageRequest: () => Promise<{ mediaType: string; data: Uint8Array }>
+  readImageRequest: (
+    ref: { attachmentId: string; mediaType: string; bytes: number; width: number; height: number },
+    target: { width: number; height: number; maxBytes: number },
+  ) => Promise<{ mediaType: string; data: Uint8Array }>
+  /** 最近一次收到的请求目标，供断言检查。 */
+  lastTarget?: { width: number; height: number; maxBytes: number }
 } {
-  return {
-    readImageRequest: async () => ({ mediaType, data }),
+  // 用闭包记录而不是 `this`：对象字面量里的箭头函数拿不到宿主对象。
+  // 显式标注类型，否则 `store.lastTarget = …` 会被推断出的窄类型挡下。
+  const store: {
+    readImageRequest: (
+      ref: { attachmentId: string; mediaType: string; bytes: number; width: number; height: number },
+      target: { width: number; height: number; maxBytes: number },
+    ) => Promise<{ mediaType: string; data: Uint8Array }>
+    lastTarget?: { width: number; height: number; maxBytes: number }
+  } = {
+    readImageRequest: async (_ref: unknown, target: { width: number; height: number; maxBytes: number }) => {
+      // 与宿主 validateTarget **逐字同规则**：它查的是 width/height/maxBytes 这三个
+      // 键**存在且为正整数**。注意不能写成「遍历传进来的键校验」——那样漏掉整个
+      // 键（0.1.5 的 maxPixels）反而能过，闸门就成了摆设（实测：这么写时把实现改回
+      // maxPixels，45 条测试全绿）。
+      for (const key of ['width', 'height', 'maxBytes']) {
+        const value = (target as unknown as Record<string, unknown>)[key]
+        if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+          throw new Error(`Image request ${key} must be a positive integer.`)
+        }
+      }
+      store.lastTarget = target
+      return { mediaType, data }
+    },
   }
+  return store
 }
 
 /** 用给定 attachments 跑一次 stream()，返回上游收到的 body。 */
@@ -710,6 +745,68 @@ async function captureBodyWith(options: Record<string, unknown>, attachments?: u
   return captured
 }
 
+/* ---------------- 请求目标：形状与像素预算（issue #8 的回归闸门） ---------------- */
+
+test('目标：请求目标是 0.1.6+ 的 target 形状（width/height/maxBytes），没有 0.1.5 的 maxPixels', async () => {
+  const attachments = fakeAttachments()
+  await captureBodyWith({
+    messages: [{ role: 'user', content: [
+      { type: 'image', attachment: { attachmentId: 'sha256:aa', mediaType: 'image/png', bytes: 11, width: 1000, height: 338 } },
+    ] }],
+  }, attachments)
+  const target = attachments.lastTarget
+  assert.ok(target !== undefined, '必须真的调过 readImageRequest')
+  assert.deepEqual(Object.keys(target).sort(), ['height', 'maxBytes', 'width'],
+    '键就是宿主 validateTarget 查的那三个；多一个少一个都会被宿主拒')
+  assert.equal('maxPixels' in (target as unknown as Record<string, unknown>), false,
+    '0.1.5 时代的 maxPixels 不再被宿主接受，带上它等于没传 width/height')
+})
+
+test('目标：大图按 64e4 像素预算等比投影（不放大；小图原样）', async () => {
+  const big = fakeAttachments()
+  await captureBodyWith({
+    messages: [{ role: 'user', content: [
+      { type: 'image', attachment: { attachmentId: 'sha256:bb', mediaType: 'image/png', bytes: 11, width: 4000, height: 3000 } },
+    ] }],
+  }, big)
+  const t = big.lastTarget
+  assert.ok(t !== undefined)
+  // 12MP 投影到 ~64e4 像素内，且不超过预算
+  assert.ok(t.width * t.height <= 64e4, `投影后仍在预算内，实际 ${t.width}x${t.height}`)
+  assert.ok(t.width < 4000 && t.height < 3000, '大图要缩')
+  const small = fakeAttachments()
+  await captureBodyWith({
+    messages: [{ role: 'user', content: [
+      { type: 'image', attachment: { attachmentId: 'sha256:cc', mediaType: 'image/png', bytes: 11, width: 4, height: 2 } },
+    ] }],
+  }, small)
+  assert.deepEqual(small.lastTarget, { width: 4, height: 2, maxBytes: 1024 * 1024 }, '预算内的小图不放大')
+})
+
+test('降级留痕：读图失败会写一条 log，不再静默（issue #8 为什么能静默两个版本）', async () => {
+  const lines: string[] = []
+  const boom = {
+    readImageRequest: async () => { throw new Error('Image request width must be a positive integer.') },
+  }
+  const adapter = new RouterAdapter(
+    'http://x',
+    { comboModels: async () => [] },
+    () => boom as never,
+    undefined,
+    (msg) => lines.push(msg),
+  )
+  globalThis.fetch = (async () => new Response('data: [DONE]\n\n', { status: 200 })) as typeof fetch
+  for await (const _c of adapter.stream({
+    model: 'm',
+    messages: [{ role: 'user', content: [
+      { type: 'image', attachment: { attachmentId: 'sha256:dd', mediaType: 'image/png', bytes: 11, width: 4, height: 2 } },
+    ] }],
+    signal: AbortSignal.timeout(3000),
+  } as never)) { void _c }
+  assert.equal(lines.length, 1, '降级必须留一条痕，否则问题又会是「静默」')
+  assert.match(lines[0] ?? '', /width must be a positive integer/, 'log 要带上真实原因')
+})
+
 test('wire：图片块被序列化成 OpenAI image_url base64 part（不再静默丢图）', async () => {
   const ref = {
     attachmentId: 'sha256:abcdef1234567890',