dsh-router-core 0.4.0 → 0.4.1

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/index.ts

@@ -36,9 +36,9 @@ 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'
@@ -217,7 +217,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 +261,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 +320,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 +408,8 @@ export function apply(rawContext: unknown): void {
           apiKeyHint: loaded?.supplier.apiKeyHint,
           capabilities: loaded ? [...loaded.capabilities] : [],
           source: loaded?.source ?? 'external',
+          // 开关状态：关掉的供应商**仍在列表里**（关掉后要能再开），只是不参与路由。
+          enabled: s.enabled,
         }
       }),
     })
@@ -610,6 +626,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 } : {}),
         }
       })
@@ -729,7 +747,12 @@ export function apply(rawContext: unknown): void {
           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',

package/src/llm/adapter.ts

@@ -8,7 +8,9 @@
  * `image` 块序列化成 OpenAI 标准的 `image_url` base64 part，经 /v1 原样透传给
  * 命中的上游供应商。最终能否看图取决于**命中的那个上游模型**——组合里是异构
  * 供应商，可能在网关端声明了图片能力、某条上游却只收文本（此时由上游自行拒收）。
- * 图片字节从 `ctx.attachments` 读取（读不到的按稳定占位文本降级，绝不静默丢图）。
+ * 图片字节从 `ctx.attachments` 读取。读不到时按稳定占位文本降级（不让整条消息失败），
+ * 但**必须留痕**：降级原因走 adapter 的 `log` 出口打到宿主 logger。曾经这里是
+ * 一个空 `catch {}`，字段改名导致的读图失败静默了跨两个内测版本（issue #8）。
  */
 import {
   EMPTY_RESPONSE_CODE,
@@ -31,15 +33,58 @@ import { mergeUsage, normalizeUsage, toTokenUsage, type UsageTokens } from '../r
  * 这一行为，不引入对 dsh-attachment 包编译期/运行期的依赖（它是宿主注入的
  * devDependency）。本地声明与原包 `AttachmentStore.readImageRequest` 形状一致，
  * 宿主注入真实 store 时天然满足。
+ *
+ * ⚠️ **第二个参数是 `ImageRequestTarget`（`width` + `height` + `maxBytes`），
+ * 不是 0.1.5 时代的 `ImageRequestPolicy`（`maxPixels` + `maxBytes`）**。宿主从
+ * 0.1.6 起在 `validateTarget()` 里校验这三个字段，缺一个就抛
+ * `Image request width must be a positive integer`，读图整体失败（issue #8）。
+ * 这两个字段不是摆设：宿主的 `pipeline()` 按 **target 的长边**把图缩到该尺寸，
+ * 短边由它自己推 —— 所以这里传投影后的尺寸，就是「按预算给我这张图」。
  */
 export interface RouterAttachmentStore {
   readImageRequest(
     ref: { attachmentId: string; mediaType: string; bytes: number; width: number; height: number },
-    policy: { maxPixels: number; maxBytes: number },
+    target: { width: number; height: number; maxBytes: number },
     signal?: AbortSignal,
   ): Promise<{ mediaType: string; data: Uint8Array }>
 }
 
+/** 送上游的请求图的像素预算（宽 × 高），沿用 0.1.5 时代 `maxPixels` 的意图。 */
+const MAX_REQUEST_PIXELS = 64e4
+/** 送上游的请求图的字节上限。 */
+const MAX_REQUEST_BYTES = 1024 * 1024
+
+/**
+ * 把源图尺寸投影到「总像素 ≤ maxPixels」的请求目标（等比、只缩不放）。
+ *
+ * 为什么需要它：宿主 0.1.6 起要的是 `ImageRequestTarget`（width/height/maxBytes），
+ * 而「别把一张 12MP 手机照原样塞进对话」这个意图原本靠 `maxPixels` 表达。
+ * 宿主自己**只按 target 的长边**缩放、短边由它推，所以我们要做的只是给出一组
+ * 落在预算内的正整数；短边取 floor 即可（它只参与校验与缓存键，不决定出图尺寸）。
+ *
+ * 没有直接复用官方的 `requestImageDimensions`（`@deepseek-ai/dsh-attachment` 有导出）：
+ * 本文件刻意不依赖那个包（见 `RouterAttachmentStore` 的说明 —— 它是宿主注入的
+ * devDependency，引入它等于给插件加一条编译期/运行期依赖）。这 8 行是纯函数、
+ * 有测试钉住；真要换成官方实现时，语义等价。
+ */
+export function projectImageDimensions(
+  width: number,
+  height: number,
+  maxPixels: number,
+): { width: number; height: number } {
+  const pixels = width * height
+  // 尺寸缺失/非法时不投影：让宿主自己的校验去报错，别在这里造一个假尺寸掩盖问题
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+    return { width, height }
+  }
+  if (pixels <= maxPixels) return { width, height }
+  const scale = Math.sqrt(maxPixels / pixels)
+  return {
+    width: Math.max(1, Math.floor(width * scale)),
+    height: Math.max(1, Math.floor(height * scale)),
+  }
+}
+
 /** 一张 image 块的 attachment ref 的最小形状（value 类型，够用即可）。 */
 interface RouterImgLike {
   attachmentId: string
@@ -96,7 +141,7 @@ const TOOL_RESULT_IMAGE_TEXT = 'Tool result images'
  */
 const STREAM_IDLE_TIMEOUT_MS = 300_000
 
-async function wireMessages(options: GenerateOptions, system: string | undefined, attachments: RouterAttachmentStore | undefined): Promise<Array<Record<string, unknown>>> {
+async function wireMessages(options: GenerateOptions, system: string | undefined, attachments: RouterAttachmentStore | undefined, log?: (msg: string) => void): Promise<Array<Record<string, unknown>>> {
   const out: Array<Record<string, unknown>> = []
   /**
    * 攒着「tool-result 里带出来的图片」，等这一串 tool 消息**发完**再合并成一条
@@ -157,7 +202,7 @@ async function wireMessages(options: GenerateOptions, system: string | undefined
       // 图片不能放进 tool 消息（实测模型会把两张不同图认成同一张），也不能插在两条 tool
       // 之间（同样 400），所以先攒进 pending，等整串 tool 发完再补一条 user(图)。
       const toolCallId = (message as { toolCallId?: unknown }).toolCallId
-      const parts = await contentParts(message.content, attachments, options.signal)
+      const parts = await contentParts(message.content, attachments, options.signal, log)
       const imageParts = parts.filter((p) => p.type !== 'text')
       const text = parts
         .filter((p) => p.type === 'text')
@@ -176,6 +221,7 @@ async function wireMessages(options: GenerateOptions, system: string | undefined
       message.content.filter((b) => b.type !== 'tool-result'),
       attachments,
       options.signal,
+      log,
     )
     // 有实质 user 内容（或压根没有 tool 结果）就先发这条 user 消息；
     // 只有 tool 结果的「纯工具」消息不发空 user，图片留到 pending 里合并。
@@ -189,7 +235,7 @@ async function wireMessages(options: GenerateOptions, system: string | undefined
       // 11148「tool calls and tool results do not match」。
       // 图片不能放进 tool 消息（实测模型会把两张不同的图认成同一张），
       // 也不能插在两条 tool 之间（同样 400），所以先攒起来、发完整串再补一条 user。
-      const parts = await contentParts(result.content, attachments, options.signal)
+      const parts = await contentParts(result.content, attachments, options.signal, log)
       const imageParts = parts.filter((p) => p.type !== 'text')
       const text = parts.filter((p) => p.type === 'text').map((p) => (p as { text?: string }).text ?? '').join('')
       // 空结果就发空串，不要替换成 '(no output)' 之类的字面量 —— 模型会
@@ -224,6 +270,7 @@ async function contentParts(
   blocks: ReadonlyArray<{ type: string }>,
   attachments: RouterAttachmentStore | undefined,
   signal: AbortSignal | undefined,
+  log?: (msg: string) => void,
 ): Promise<Array<Record<string, unknown>>> {
   const parts: Array<Record<string, unknown>> = []
   for (const block of blocks) {
@@ -234,11 +281,11 @@ async function contentParts(
     }
     if (block.type === 'image') {
       const ref = (block as unknown as { attachment: RouterImgLike }).attachment
-      parts.push(...(await imageParts(ref, attachments, signal)))
+      parts.push(...(await imageParts(ref, attachments, signal, log)))
       continue
     }
     if (block.type === 'tool-result') {
-      parts.push(...(await contentParts((block as unknown as { content: ReadonlyArray<{ type: string }> }).content, attachments, signal)))
+      parts.push(...(await contentParts((block as unknown as { content: ReadonlyArray<{ type: string }> }).content, attachments, signal, log)))
     }
     // 其它块（reasoning/tool-call）不属于 user content，忽略
   }
@@ -250,16 +297,23 @@ async function imageParts(
   ref: { attachmentId: string; mediaType: string; bytes: number; width: number; height: number },
   attachments: RouterAttachmentStore | undefined,
   signal: AbortSignal | undefined,
+  log?: (msg: string) => void,
 ): Promise<Array<Record<string, unknown>>> {
-  if (attachments === undefined) return [{ type: 'text', text: imagePlaceholder(ref.attachmentId) }]
+  if (attachments === undefined) {
+    log?.('图片附件 store 不可用（ctx.attachments 未注入），该图降级为占位文本')
+    return [{ type: 'text', text: imagePlaceholder(ref.attachmentId) }]
+  }
+  const ref0 = { attachmentId: ref.attachmentId, mediaType: ref.mediaType, bytes: ref.bytes, width: ref.width, height: ref.height }
+  // 目标 = 源尺寸按 64e4 像素预算等比投影后的宽高 + 字节上限（0.1.6+ 的 target 形状）
+  const target = { ...projectImageDimensions(ref.width, ref.height, MAX_REQUEST_PIXELS), maxBytes: MAX_REQUEST_BYTES }
   try {
-    const img = await attachments.readImageRequest(
-      { attachmentId: ref.attachmentId, mediaType: ref.mediaType, bytes: ref.bytes, width: ref.width, height: ref.height },
-      { maxPixels: 64e4, maxBytes: 1024 * 1024 },
-      signal,
-    )
+    const img = await attachments.readImageRequest(ref0, target, signal)
     return [{ type: 'image_url', image_url: { url: `data:${img.mediaType};base64,${bytesToBase64(img.data)}` } }]
-  } catch {
+  } catch (err) {
+    // 曾经这里是空 catch：宿主把请求目标从 maxPixels 换成 width/height 之后读图
+    // 全失败，图被静默换成占位文本，跨两个内测版本没被发现（issue #8）。降级仍然
+    // 保留（不能让整条消息失败），但原因必须出口。
+    log?.(`读取图片 ${ref.attachmentId} 失败，已降级为占位文本：${(err as Error).message}`)
     return [{ type: 'text', text: imagePlaceholder(ref.attachmentId) }]
   }
 }
@@ -280,8 +334,8 @@ function imagePlaceholder(attachmentId: string): string {
 }
 
 /** 组装 wire 请求体。图片序列化需要读 attachments，故为异步。 */
-async function wireRequest(options: GenerateOptions, attachments: RouterAttachmentStore | undefined): Promise<Record<string, unknown>> {
-  const messages = await wireMessages(options, options.system, attachments)
+async function wireRequest(options: GenerateOptions, attachments: RouterAttachmentStore | undefined, log?: (msg: string) => void): Promise<Record<string, unknown>> {
+  const messages = await wireMessages(options, options.system, attachments, log)
   const body: Record<string, unknown> = {
     model: options.model,
     messages,
@@ -585,22 +639,28 @@ export class RouterAdapter extends LlmAdapter {
   private readonly resolveAttachments: () => RouterAttachmentStore | undefined
   /** 流空闲超时（ms）：上游这么久不吐字节就判 TIMEOUT。 */
   private readonly idleTimeoutMs: number
+  /** 降级/失败诊断的出口（宿主接 ctx.logger.warn）。缺省丢弃 —— 仅为测试可注入。 */
+  private readonly log: ((msg: string) => void) | undefined
 
   /**
    * @param idleTimeoutMs 流空闲超时；缺省用生产值（300s，对齐 pi-ai）。
    *   可注入只为测试能压到几百毫秒，生产不传。
+   * @param log 降级诊断出口。图片读不到时会降级成占位文本，原因走这里 ——
+   *   曾经那条路径是个空 `catch`，出问题跨版本都没人发现（issue #8）。
    */
   constructor(
     baseURL: string,
     source: RouterAdapterSource,
     resolveAttachments?: () => RouterAttachmentStore | undefined,
     idleTimeoutMs: number = STREAM_IDLE_TIMEOUT_MS,
+    log?: (msg: string) => void,
   ) {
     super()
     this.baseURL = baseURL
     this.source = source
     this.resolveAttachments = resolveAttachments ?? (() => undefined)
     this.idleTimeoutMs = idleTimeoutMs
+    this.log = log
   }
 
   providerInfo(provider: string): { id: string; name: string } {
@@ -647,7 +707,7 @@ export class RouterAdapter extends LlmAdapter {
   }
 
   async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    const body = await wireRequest(options, this.resolveAttachments())
+    const body = await wireRequest(options, this.resolveAttachments(), this.log)
     const controller = new AbortController()
     const onAbort = (): void => controller.abort()
     options.signal?.addEventListener('abort', onAbort, { once: true })

package/src/router/disconnect-leak.test.ts

@@ -158,28 +158,24 @@ test('客户端断开：上游流 cancel 链要穿过 tapStreamUsage / normalize
   assert.equal(leak.cancelled(), true, '取消必须穿过两层 wrapper 到达上游')
 })
 
-test('聚合失败：reader 必须被解绑（否则连接还活着时上层无法 cancel）', async () => {
+test('聚合失败：上游流必须被回收（解锁，不能永久锁死）', async () => {
   // 这一条测的**不是**「cancel 回调有没有触发」——那测不出东西：
   // 实测结论（两个都验过）：
   //   - 流 error 后调 cancel()，只会以同一错误 reject，**不触发** cancel 回调
   //     （`pull()` 抛错会把流置为 errored；上游拆连接则流直接 error）
   //   - 这两种情况下 undici **已经自己关了连接**，不需要我们 cancel
-  // 所以聚合失败路径真正要保证的是 **reader 被解绑**：流锁着的话，上层
+  // 所以聚合失败路径真正要保证的是 **上游流不再被锁着**：锁着的话上层
   // （writeChatResult 的失败路径 / 未来的取消逻辑）想 cancel 都会抛
   // `Invalid state: ReadableStream is locked`，连接就永久漏了。
-  let releaseLocked = false
+  //
+  // 注意拓扑：核心现在隔着「首字节截止」wrapper（withFirstByteDeadline）读上游，
+  // 所以判据只能是**最终状态**（locked=false），不能再断言核心直接 releaseLock
+  // 上游的 reader —— 中间隔了一层，核心只会解锁 wrapper 那个 reader。
   const enc = new TextEncoder()
   const failing = new ReadableStream<Uint8Array>({
     start(c) { c.enqueue(enc.encode('data: {"choices":[{"delta":{"content":"a"}}]}\n\n')) },
     pull() { throw new Error('aggregate read failed') },
   })
-  const origGetReader = failing.getReader.bind(failing)
-  ;(failing as unknown as { getReader: () => unknown }).getReader = () => {
-    const r = origGetReader()
-    const origRelease = r.releaseLock.bind(r)
-    r.releaseLock = () => { releaseLocked = true; origRelease() }
-    return r
-  }
 
   const router = new Router('')
   router.add(supplierWith(failing) as never)
@@ -195,8 +191,7 @@ test('聚合失败：reader 必须被解绑（否则连接还活着时上层无
   )
   await new Promise((r) => setTimeout(r, 150))
 
-  assert.equal(releaseLocked, true, '聚合失败后必须 releaseLock，否则流锁死、上层无法回收')
-  assert.equal(failing.locked, false, '流必须处于未锁定状态（可被 cancel / 已被回收）')
+  assert.equal(failing.locked, false, '上游流必须处于未锁定状态（可被 cancel / 已被回收）')
 })
 
 test('fixFrame：把后续 delta 里重发成 null 的 id/name 剥掉（否则外部 OpenAI 客户端会丢工具名）', async () => {