dsh-router-core 0.3.21 → 0.4.1

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
@@ -77,6 +122,10 @@ export interface RouterAdapterSource {
  * 图片：`image` 块被序列化成 OpenAI `content` 数组里的 `image_url` part（data URI
  * base64）。图片字节经 `resolveAttachments` 读取；读不到时回退为稳定的占位文本，
  * **绝不静默丢图**（丢图 = 模型看到一条没有图的消息却毫无提示）。
+ *
+ * 工具结果双模型兼容：0.1.5/0.1.6 里 tool result 是 user 消息里的 'tool-result' 块
+ * （旧路径）；0.1.7+ 改成了独立 role:'tool' 消息、toolCallId 挂消息级（新分支）。
+ * 两者在 wire 上统一序列化为 role:'tool'，产物一致。见主循环里的 role==='tool' 分支。
  */
 /** tool-result 里图片挂到 user 消息时用的说明文字（与官方适配器一致）。 */
 const TOOL_RESULT_IMAGE_TEXT = 'Tool result images'
@@ -92,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 消息**发完**再合并成一条
@@ -139,6 +188,32 @@ async function wireMessages(options: GenerateOptions, system: string | undefined
       })
       continue
     }
+    // tool 结果的消息形态：**同一宿主内两种形态都合法**，按消息实际形状分派。
+    //   新形态：独立 role:'tool' 消息、toolCallId 挂消息级（0.1.7 loop-built）；
+    //   旧形态：user 消息里的 'tool-result' 块（0.1.5/0.1.6，以及 0.1.7 下经
+    //           session-format 迁移/重放的老会话历史——实测 0.1.7 仍会出现）。
+    // 所以**不能**用宿主版本号判断形态对错（0.1.7-alpha.2 也是 0.1.7，同样会出现
+    // 旧形态）——形状才是事实，按形状分派这一份 adapter 就同时吃两版。
+    const isToolRoleMessage = (message.role as string) === 'tool'
+    if (isToolRoleMessage) {
+      // tool 消息必须紧跟 assistant(tool_calls)：中间插进任何 user 消息，上游都会判定
+      // tool_call 与 tool_result 失配 → codebuddy 直接 400 网关码 11148（bad_request
+      // 按核心设计不罚账号，面板上看不到异常，易误判成额度/风控）。
+      // 图片不能放进 tool 消息（实测模型会把两张不同图认成同一张），也不能插在两条 tool
+      // 之间（同样 400），所以先攒进 pending，等整串 tool 发完再补一条 user(图)。
+      const toolCallId = (message as { toolCallId?: unknown }).toolCallId
+      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')
+        .map((p) => (p as { text?: string }).text ?? '')
+        .join('')
+      // 空结果就发空串：不要替换成 '(no output)' 之类字面量——模型会以为工具真的打印了
+      // 那句话。上游接受 content:""（0.1.7 探测矩阵第 6 项确认）。
+      out.push({ role: 'tool', tool_call_id: String(toolCallId ?? ''), content: text })
+      pendingToolImages.push(...imageParts)
+      continue
+    }
     // user / tool-result
     const toolResults = message.content.filter((b) => b.type === 'tool-result')
     // 这条消息自己的（非 tool-result 的）user 部分：文本 + 图片。
@@ -146,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 里合并。
@@ -159,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)' 之类的字面量 —— 模型会
@@ -194,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) {
@@ -204,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，忽略
   }
@@ -220,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) }]
   }
 }
@@ -250,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,
@@ -555,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 } {
@@ -617,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 })
@@ -632,6 +722,9 @@ export class RouterAdapter extends LlmAdapter {
           ...attributionHeaders(),
           'content-type': 'application/json',
           accept: 'text/event-stream',
+          // 宿主盖的会话身份转成内部头：核心据此把用量按会话归因，
+          // 供「最近命中」徽章按当前会话显示。宿主没给就不带（外部调用）。
+          ...options.sessionId === undefined ? {} : { 'x-dsh-router-session': String(options.sessionId) },
         },
         body: JSON.stringify(body),
         signal: controller.signal,