@oadank/dsh-input-tools 0.3.11 → 0.3.13

package/lib/client.js

@@ -32,6 +32,10 @@ window.__ModuleLoader__.load({
 
     // ── 附件槽桥：官方 onAddImages 由 attachments 槽组件挂载时存入，left 按钮调用 ──
     let sharedOnAddImages = null;
+    // [2026-08-21] draft 图片共享：attachments 槽挂载时把当前 draft 图（ComposerAttachment[]）
+    // 与移除回调存入模块级，语音发送时可一起带上、发完清掉（解决"选了图发语音图被留下"）。
+    let sharedDraftImages = [];
+    let sharedRemoveImage = null;
 
     // ── [2026-08-21] 语音气泡（聊天界面 DOM 注入，安装即用，不依赖 dsh 源码支持）────
     // 录音 → 存服务器（/voice/outbox/save）→ ASR 转文本 → 发【用户语音】标记文本；
@@ -158,13 +162,38 @@ window.__ModuleLoader__.load({
           if (voiceErrorTimerRef.current !== null) window.clearTimeout(voiceErrorTimerRef.current);
           voiceErrorTimerRef.current = window.setTimeout(() => setVoiceError(null), 6000);
         };
-        const sendAsText = async (text) => {
+        // [2026-08-21] draft 图片转 image content（File→base64），语音可与图片一起发送
+        const draftImageContents = async () => {
+          const imgs = Array.isArray(sharedDraftImages) ? sharedDraftImages : [];
+          const out = [];
+          for (const a of imgs) {
+            const file = a?.file;
+            if (!file) continue;
+            const b64 = await new Promise((resolve) => {
+              const r = new FileReader();
+              r.onload = () => resolve(String(r.result).split(",")[1] ?? "");
+              r.onerror = () => resolve("");
+              r.readAsDataURL(file);
+            });
+            if (b64 !== "") out.push({ type: "image", mediaType: file.type || "image/jpeg", data: b64, name: file.name });
+          }
+          return out;
+        };
+        // [2026-08-21] 语音发送成功后清掉 draft 图片（否则图还留在输入框上）
+        const clearDraftImages = () => {
+          const imgs = Array.isArray(sharedDraftImages) ? sharedDraftImages : [];
+          if (typeof sharedRemoveImage === "function") {
+            for (const a of imgs) { try { sharedRemoveImage(a.id); } catch { /* ignore */ } }
+          }
+          sharedDraftImages = [];
+        };
+        const sendAsText = async (text, images) => {
           // [2026-08-21] 降级路径：XDN(npm rc.7) 不支持 voice content。带【用户语音】标记让 AI
           // 知道这是语音转的文本，可以按规则(自动 TTS)回复。
           const marked = "【用户语音】" + text;
           const response = await connection.api.sessions.prompt({
             sessionId, mode: "queue",
-            content: [{ type: "text", text: marked }],
+            content: [{ type: "text", text: marked }, ...images],
           });
           const result = response?.result;
           if (!result || !result.ok) {
@@ -172,25 +201,26 @@ window.__ModuleLoader__.load({
               ? result.error.message : "语音发送失败，请重试");
           }
         };
-        const sendAsVoice = async () => {
+        const sendAsVoice = async (images) => {
           // 首选：多模态直发（AI 能听原音，消息渲染为语音气泡）——本机 lecoo / dev rc.8 支持
           const response = await connection.api.sessions.prompt({
             sessionId, mode: "queue",
-            content: [{ type: "voice", mediaType, data }],
+            content: [{ type: "voice", mediaType, data }, ...images],
           });
           return response?.result;
         };
         try {
+          const images = await draftImageContents();
           // [2026-08-21 修] 先直发 voice，失败时降级 ASR 转文本（rc.7 兼容）。
           // 这样本机/rc.8 享受多模态（AI 听到原音 + 语音消息气泡），XDN/rc.7 自动降级不报错。
           let result;
           try {
-            result = await sendAsVoice();
+            result = await sendAsVoice(images);
           } catch (voiceErr) {
             result = null;
           }
           // 直发成功（rc.8/dev）：result.ok true
-          if (result && result.ok) return;
+          if (result && result.ok) { clearDraftImages(); return; }
           // 失败或不支持：尝试降级
           const errMsg = result?.error?.message ?? "";
           // 只有"contract/payload"类错误才降级；其他业务错误直接提示
@@ -216,7 +246,8 @@ window.__ModuleLoader__.load({
           if (!td?.ok) { fail(td?.error ?? "语音识别失败，请检查 ASR 配置"); return; }
           const text = typeof td?.text === "string" ? td.text.trim() : "";
           if (text === "") { fail("没听清，请再说一次"); return; }
-          await sendAsText(text);
+          await sendAsText(text, images);
+          clearDraftImages();
         } catch (e) {
           fail(String(e && typeof e.message === "string" && e.message !== "" ? e.message : e));
         }
@@ -318,6 +349,12 @@ window.__ModuleLoader__.load({
         if (typeof onAddImages === "function") sharedOnAddImages = onAddImages;
       }, [onAddImages]);
 
+      // [2026-08-21] draft 图同步到模块级（语音发送一起带 + 发完清掉）
+      useEffect(() => {
+        sharedDraftImages = Array.isArray(attachments) ? attachments : [];
+        if (typeof onRemoveImage === "function") sharedRemoveImage = onRemoveImage;
+      }, [attachments, onRemoveImage]);
+
       useEffect(() => {
         if (zoom !== null && !items.some((a) => a.id === zoom.id)) setZoom(null);
       }, [items, zoom]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oadank/dsh-input-tools",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "private": false,
   "type": "module",
   "main": "lib/index.js",

package/patches/dsh-voice-rc8.patch

@@ -10,6 +10,56 @@ index 6a5164f160..f5a57a5e65 100644
    WorkspaceId, WorkspaceView,
  } from '@deepseek-ai/dsh-client-connection/client'
  export type {} from '@deepseek-ai/dsh-api-gateway/client'
+diff --git a/packages/attachment/attachment-local/src/store.ts b/packages/attachment/attachment-local/src/store.ts
+index 723df98720..0068b2f00b 100644
+--- a/packages/attachment/attachment-local/src/store.ts
++++ b/packages/attachment/attachment-local/src/store.ts
+@@ -1,7 +1,7 @@
+ /** Content-addressed, owner-private local attachment storage. */
+ 
+ import { createHash, randomUUID } from 'node:crypto'
+-import { constants } from 'node:fs'
++import { constants, existsSync } from 'node:fs'
+ import { chmod, link, mkdir, open, readFile, unlink } from 'node:fs/promises'
+ import { dirname, join, parse, resolve } from 'node:path'
+ import {
+@@ -19,6 +19,16 @@ import { detectImage, probeImage } from './image.ts'
+ const ID_PATTERN = /^sha256:([a-f0-9]{64})$/
+ const durableHomes = new Set<string>()
+ 
++/**
++ * [本地改造 2026-08-21] 内容寻址对象（无扩展名）的"带扩展名别名"路径。
++ * zai-vision 等视觉 MCP 按扩展名（.jpg/.jpeg/.png）校验，无扩展名会被拒绝。
++ * jpeg→.jpg、png→.png、webp→.png（webp 由调用方用 sharp 转码成 png 别名）。
++ */
++function extensionAliasPath(target: string, mediaType: ImageAttachmentRef['mediaType']): string | null {
++  const ext = mediaType === 'image/jpeg' ? '.jpg' : mediaType === 'image/png' ? '.png' : mediaType === 'image/webp' ? '.png' : null
++  return ext === null ? null : `${target}${ext}`
++}
++
+ function digest(data: Uint8Array): string {
+   return createHash('sha256').update(data).digest('hex')
+ }
+@@ -162,6 +172,19 @@ export async function saveImageFile(root: string, input: SaveImageAttachment, li
+       const existing = new Uint8Array(await readFile(target))
+       if (digest(existing) !== sha256) throw new AttachmentError('Stored attachment failed integrity verification.', 'ATTACHMENT_CORRUPT')
+     }
++    // [本地改造 2026-08-21] 确保带扩展名别名存在（首次存储与 dedup 命中都执行）：
++    // jpeg/png 硬链接（零拷贝）；webp 用 sharp 转成 png 别名。供 zai-vision 等按扩展名校验的 MCP 使用。
++    const alias = extensionAliasPath(target, metadata.mediaType)
++    if (alias !== null && !(await existsSync(alias))) {
++      try {
++        if (metadata.mediaType === 'image/webp') {
++          const { default: sharpMod } = await import('sharp')
++          await sharpMod(input.data).png().toFile(alias)
++        } else {
++          await link(target, alias)
++        }
++      } catch { /* 别名失败可忽略（主对象已持久化） */ }
++    }
+     // Persist the target entry and close a concurrent bucket-creation window
+     // before the reference can reach a session checkpoint. The dedup path
+     // repeats both syncs because it may observe another writer's link before
 diff --git a/packages/attachment/attachment/src/error.ts b/packages/attachment/attachment/src/error.ts
 index 2e2d695dae..c91a4f862f 100644
 --- a/packages/attachment/attachment/src/error.ts
@@ -3645,7 +3695,7 @@ index 638d555b1e..f93aaa2ed8 100644
      const apiKey = await this.config.resolveApiKey(connection)
      const userId = this.config.resolveUserId()
 diff --git a/packages/llm/llm-deepseek/src/serialize.ts b/packages/llm/llm-deepseek/src/serialize.ts
-index 498b3fb2f7..a5e8458366 100644
+index 498b3fb2f7..1a5c9aa6e4 100644
 --- a/packages/llm/llm-deepseek/src/serialize.ts
 +++ b/packages/llm/llm-deepseek/src/serialize.ts
 @@ -17,6 +17,7 @@ import type {
@@ -3656,7 +3706,7 @@ index 498b3fb2f7..a5e8458366 100644
  
  /** Adapter-level request defaults (from plugin config). */
  export interface RequestDefaults {
-@@ -79,11 +80,58 @@ function flattenText(blocks: ContentBlock[]): string {
+@@ -79,11 +80,60 @@ function flattenText(blocks: ContentBlock[]): string {
      .join('')
  }
  
@@ -3666,7 +3716,8 @@ index 498b3fb2f7..a5e8458366 100644
 -    throw new LlmError('The DeepSeek chat-completions adapter does not support image content.', 'UNSUPPORTED_CONTENT')
 +/** [本地改造 2026-08-16] 把 image 块转成含本地附件路径的文本（参考 dsh-vscode-layout 补丁）：
 + * 文本模型收到路径后，必须通过视觉 MCP（mcp__visionqa__look / mcp__zai-vision__analyze_image）
-+ * 识图；该文件无扩展名，read_image 等按扩展名校验的工具会拒绝，禁止使用。 */
++ * 识图。路径带扩展名（jpeg→.jpg / png→.png / webp→.png，attachment-local 存储时已生成
++ * 带扩展名别名，见 store.ts extensionAliasPath），zai-vision 等按扩展名校验的工具可用。 */
 +function imageAsText(block: ContentBlock): ContentBlock {
 +  const ref = (block as { attachment?: { attachmentId?: unknown; name?: string; mediaType?: string } }).attachment
 +  const rawId = typeof ref?.attachmentId === 'string' ? ref.attachmentId : ''
@@ -3674,10 +3725,11 @@ index 498b3fb2f7..a5e8458366 100644
 +  const name = typeof ref?.name === 'string' && ref.name.length > 0 ? ref.name : 'image'
 +  const mediaType = ref?.mediaType ?? 'image/jpeg'
 +  const home = process.env.DSH_HOME ?? ''
++  const ext = mediaType === 'image/jpeg' ? '.jpg' : '.png'
 +  const path = hex.length > 0 && home !== ''
-+    ? join(home, 'attachments', 'v1', 'objects', hex.slice(0, 2), hex)
++    ? join(home, 'attachments', 'v1', 'objects', hex.slice(0, 2), hex) + ext
 +    : '(unknown)'
-+  return { type: 'text', text: `[用户发送了一张图片，名称 "${name}"，类型 ${mediaType}。请用视觉 MCP 工具识图（mcp__visionqa__look 或 mcp__zai-vision__analyze_image，传入 image_path），不要用 read_image（该文件无扩展名，read_image 会拒绝）：${path}]` }
++  return { type: 'text', text: `[用户发送了一张图片，名称 "${name}"，类型 ${mediaType}。请用视觉 MCP 工具识图（mcp__visionqa__look 或 mcp__zai-vision__analyze_image，传入 image_path）：${path}]` }
 +}
 +
 +function imagesAsText(blocks: readonly ContentBlock[]): ContentBlock[] {
@@ -3719,7 +3771,7 @@ index 498b3fb2f7..a5e8458366 100644
  }
  
  /** Reject roles whose DeepSeek history format cannot carry image input. */
-@@ -203,19 +251,22 @@ function serializeAssistant(message: Message): WireMessage {
+@@ -203,19 +253,22 @@ function serializeAssistant(message: Message): WireMessage {
  export function serializeMessages(messages: Message[]): WireMessage[] {
    const wire: WireMessage[] = []
    for (const message of messages) {
@@ -3747,6 +3799,327 @@ index 498b3fb2f7..a5e8458366 100644
      if (text.length > 0 || toolResults.length === 0) {
        wire.push({ role: 'user', content: text })
      }
+diff --git a/packages/llm/llm-pi-ai/src/context.ts b/packages/llm/llm-pi-ai/src/context.ts
+index d66a48115d..9e3127d2e6 100644
+--- a/packages/llm/llm-pi-ai/src/context.ts
++++ b/packages/llm/llm-pi-ai/src/context.ts
+@@ -4,51 +4,122 @@
+  * @module dsh-llm-pi-ai/context
+  */
+ 
+-import { CallId, contentHasImage, LlmError, offloadRequestImages } from '@deepseek-ai/dsh-llm'
+-import type { ContentBlock, GenerateOptions, Message } from '@deepseek-ai/dsh-llm'
++import { CallId, contentHasImage, LlmError } from '@deepseek-ai/dsh-llm'
++import type { ContentBlock, GenerateOptions } from '@deepseek-ai/dsh-llm'
+ import type { AttachmentStore } from '@deepseek-ai/dsh-attachment'
+ import type { Context as PiContext, ImageContent, Message as PiMessage, TextContent, Tool as PiTool } from '@earendil-works/pi-ai'
+ import { toPiAssistant } from './replay.ts'
++import { join } from 'node:path'
+ 
+-/** Join the text blocks of a harness message. */
+-function flattenText(message: Message): string {
+-  return message.content
+-    .filter(block => block.type === 'text')
+-    .map(block => block.text)
+-    .join('')
++/** [本地改造 2026-08-16] 把已转为文本的内容块扁平化为纯文本（非视觉模型路径）。 */
++function flattenBlocks(blocks: readonly ContentBlock[]): string {
++  let out = ''
++  for (const block of blocks) {
++    if (block.type === 'text') {
++      out += block.text
++    } else if (block.type === 'voice') {
++      const asText = voiceAsText(block)
++      if (asText.type === 'text') out += asText.text
++    } else if (block.type === 'tool-result') {
++      out += flattenBlocks(block.content)
++    }
++    // image 已在 imagesToText 转成 text，此处不再出现。
++  }
++  return out
+ }
+ 
++/**
++ * [本地改造 2026-08-16] 把 voice 块转成文本：attachment.transcript 存在时直接给出
++ * 识别文本；否则输出本地语音文件路径——与 llm-deepseek serialize.ts 的 voiceAsText
++ * 同一策略，保证切换 provider（deepseek-official ↔ qwen/pi-ai）后语音识别行为一致。
++ */
++function voiceAsText(block: ContentBlock): ContentBlock {
++  if (block.type !== 'voice') return block
++  const ref = (block as { attachment?: { voiceId?: unknown; durationMs?: unknown; transcript?: unknown } }).attachment
++  const rawId = typeof ref?.voiceId === 'string' ? ref.voiceId : ''
++  const hex = rawId.startsWith('sha256:') ? rawId.slice('sha256:'.length) : rawId
++  const transcript = typeof ref?.transcript === 'string' && ref.transcript.length > 0
++    ? ref.transcript
++    : null
++  const durationMs = typeof ref?.durationMs === 'number' ? ref.durationMs : null
++  const duration = durationMs === null ? '' : `（时长 ${Math.round(durationMs / 1000)} 秒）`
++  if (transcript !== null) {
++    return { type: 'text', text: `[用户发送了一条语音${duration}，识别内容：${transcript}]` }
++  }
++  const home = process.env.DSH_HOME ?? ''
++  const path = hex.length > 0 && home !== ''
++    ? join(home, 'attachments', 'v1', 'objects', hex.slice(0, 2), hex)
++    : '(unknown)'
++  return { type: 'text', text: `[用户发送了一条语音${duration}，本地语音文件路径: ${path}]` }
++}
+ 
+-/** Flatten text recursively inside one tool result. */
+-function toolResultText(blocks: readonly ContentBlock[]): string {
+-  return blocks.map(block => block.type === 'text'
+-    ? block.text
+-    : block.type === 'tool-result' ? toolResultText(block.content) : '').join('')
++/**
++ * [本地改造 2026-08-16] 把 image 块转成含本地附件路径的文本（与 llm-deepseek
++ * serialize.ts 的 imageAsText 同一策略）：非视觉模型（pi-ai input 不含 image）
++ * 收到路径文本后，必须通过视觉 MCP（mcp__visionqa__look / mcp__zai-vision__analyze_image）
++ * 识图。路径带扩展名（jpeg→.jpg / png→.png / webp→.png，attachment-local 存储时已生成
++ * 带扩展名别名，见 store.ts extensionAliasPath），zai-vision 等按扩展名校验的工具可用。
++ */
++function imageAsText(block: ContentBlock): ContentBlock {
++  if (block.type !== 'image') return block
++  const ref = (block as { attachment?: { attachmentId?: unknown; name?: unknown; mediaType?: unknown } }).attachment
++  const rawId = typeof ref?.attachmentId === 'string' ? ref.attachmentId : ''
++  const hex = rawId.startsWith('sha256:') ? rawId.slice('sha256:'.length) : rawId
++  const name = typeof ref?.name === 'string' && ref.name.length > 0 ? ref.name : 'image'
++  const mediaType = typeof ref?.mediaType === 'string' ? ref.mediaType : 'image/jpeg'
++  const home = process.env.DSH_HOME ?? ''
++  const ext = mediaType === 'image/jpeg' ? '.jpg' : '.png'
++  const path = hex.length > 0 && home !== ''
++    ? join(home, 'attachments', 'v1', 'objects', hex.slice(0, 2), hex) + ext
++    : '(unknown)'
++  return { type: 'text', text: `[用户发送了一张图片，名称 "${name}"，类型 ${mediaType}。请用视觉 MCP 工具识图（mcp__visionqa__look 或 mcp__zai-vision__analyze_image，传入 image_path）：${path}]` }
+ }
+ 
+-/** Reject image roles that pi-ai cannot replay before request-size offloading can replace them. */
+-function assertSupportedImageRoles(messages: readonly Message[]): void {
+-  for (const message of messages) {
+-    if (message.role !== 'user' && contentHasImage(message.content)) {
+-      throw new LlmError(
+-        `pi-ai cannot represent an image in an in-history ${message.role} message`,
+-        'UNSUPPORTED_CONTENT',
+-      )
++/** Convert image blocks to path-text when the route model is not a vision model. */
++function imagesToText(blocks: readonly ContentBlock[], vision: boolean): readonly ContentBlock[] {
++  if (vision) return blocks
++  const out: ContentBlock[] = []
++  for (const block of blocks) {
++    if (block.type === 'image') {
++      out.push(imageAsText(block))
++    } else if (block.type === 'tool-result') {
++      out.push({ ...block, content: [...imagesToText(block.content, vision)] })
++    } else {
++      out.push(block)
+     }
+   }
++  return out
+ }
+ 
+ async function userContent(
+   blocks: readonly ContentBlock[],
+-  attachments: AttachmentStore,
++  attachments: AttachmentStore | undefined,
++  vision: boolean,
+ ): Promise<string | (TextContent | ImageContent)[]> {
++  // [本地改造 2026-08-16] 非视觉模型：图片块先整体转路径文本（agent 用视觉 MCP 看图），
++  // 不再需要 attachments；视觉模型保持原逻辑（读原图送 pi-ai）。
++  const converted = imagesToText(blocks, vision)
++  if (!vision) {
++    return flattenBlocks(converted)
++  }
+   const content: (TextContent | ImageContent)[] = []
+-  for (const block of blocks) {
++  for (const block of converted) {
+     switch (block.type) {
+       case 'text':
+         if (block.text.length > 0) content.push({ type: 'text', text: block.text })
+         break
++      case 'voice': {
++        // [本地改造 2026-08-16] 语音块转文本（识别文本/本地路径），与文本块同路进模型。
++        const asText = voiceAsText(block)
++        if (asText.type === 'text' && asText.text.length > 0) {
++          content.push({ type: 'text', text: asText.text })
++        }
++        break
++      }
+       case 'image': {
++        if (attachments === undefined) {
++          throw new LlmError('pi-ai image conversion requires the durable attachment service', 'UNSUPPORTED_CONTENT')
++        }
+         const stored = await attachments.readImage(block.attachment)
+         content.push({
+           type: 'image',
+@@ -59,7 +130,7 @@ async function userContent(
+       }
+       case 'tool-result':
+         {
+-          const nested = await userContent(block.content, attachments)
++          const nested = await userContent(block.content, attachments, vision)
+           if (typeof nested === 'string') {
+             if (nested.length > 0) content.push({ type: 'text', text: nested })
+           } else {
+@@ -96,34 +167,45 @@ function piContext(options: GenerateOptions, messages: PiMessage[]): PiContext {
+   }
+ }
+ 
+-function textOnlyContext(options: GenerateOptions, onReplayDegrade?: (reason: string) => void): PiContext {
++function textOnlyContext(options: GenerateOptions, vision: boolean): PiContext {
+   const toolNames = new Map<CallId, string>()
+   const messages: PiMessage[] = []
+   for (const message of options.messages) {
+-    if (contentHasImage(message.content)) {
+-      throw new LlmError('pi-ai image conversion requires the durable attachment service', 'UNSUPPORTED_CONTENT')
+-    }
+     if (message.role === 'system') {
+-      messages.push({ role: 'user', content: flattenText(message), timestamp: 0 })
++      // 视觉模型无法在 pi-ai 单一 systemPrompt 槽内表达图片；非视觉模型
++      // （vision=false）走文本路径（imagesToText 转路径文本）。
++      if (vision && contentHasImage(message.content)) {
++        throw new LlmError('pi-ai cannot represent an image in an in-history system message', 'UNSUPPORTED_CONTENT')
++      }
++      messages.push({ role: 'user', content: flattenBlocks(imagesToText(message.content, vision)), timestamp: 0 })
+       continue
+     }
+     if (message.role === 'assistant') {
+-      const assistant = toPiAssistant(message, onReplayDegrade)
++      const assistant = toPiAssistant(message)
+       for (const block of assistant.content) if (block.type === 'toolCall') toolNames.set(CallId(block.id), block.name)
+       messages.push(assistant)
+       continue
+     }
+-    const text = flattenText(message)
++    const regular = message.content.filter(block => block.type !== 'tool-result')
++    // [本地改造 2026-08-16] 非视觉模型（vision=false）：图片块转路径文本后扁平化；
++    // 视觉模型（vision=true）无 durable attachment 服务时仍拒绝（必须读原图）。
++    if (vision && contentHasImage(regular)) {
++      throw new LlmError('pi-ai image conversion requires the durable attachment service', 'UNSUPPORTED_CONTENT')
++    }
++    const text = flattenBlocks(imagesToText(regular, vision))
+     const results = message.content.filter(block => block.type === 'tool-result')
+     if (text.length > 0 || results.length === 0) messages.push({ role: 'user', content: text, timestamp: 0 })
+     for (const result of results) {
++      if (vision && contentHasImage(result.content)) {
++        throw new LlmError('pi-ai image conversion requires the durable attachment service', 'UNSUPPORTED_CONTENT')
++      }
+       messages.push({
+         role: 'toolResult',
+         toolCallId: result.toolCallId,
+         toolName: toolNames.get(result.toolCallId) ?? 'unknown',
+         content: [{
+           type: 'text',
+-          text: toolResultText(result.content) || '(no output)',
++          text: flattenBlocks(imagesToText(result.content, vision)) || '(no output)',
+         }],
+         isError: result.isError ?? false,
+         timestamp: 0,
+@@ -133,69 +215,42 @@ function textOnlyContext(options: GenerateOptions, onReplayDegrade?: (reason: st
+   return piContext(options, messages)
+ }
+ 
+-/**
+- * Convert text-only harness history to a synchronous pi-ai Context. Tool
+- * result names are recovered from preceding assistant tool calls.
+- * @param options - the harness request; `options.system` maps to pi-ai's single `systemPrompt` slot.
+- * @param attachments - absent; selects the synchronous conversion.
+- * @param onReplayDegrade - forwarded to {@link toPiAssistant} for each assistant message.
+- * @returns the pi-ai context; `tools` is omitted when the request declares none.
+- */
+-export function toPiContext(
+-  options: GenerateOptions,
+-  attachments?: undefined,
+-  onReplayDegrade?: (reason: string) => void,
+-): PiContext
+ /**
+  * Convert harness history to a pi-ai Context while resolving durable images.
+- * Tool result names are recovered from preceding assistant tool calls. When
+- * the accumulated base64 image payload exceeds `maxRequestImageBytes`, the
+- * oldest images are replaced by text placeholders until the request fits, so
+- * an image-heavy session keeps clearing gateway request-size caps.
++ * Tool result names are recovered from preceding assistant tool calls.
++ * [本地改造 2026-08-16] vision=false（模型 input 不含 image）时，图片块转为
++ * 本地路径文本（agent 用视觉 MCP 识图），与 llm-deepseek serialize.ts 一致；
++ * attachments 可为 undefined（非视觉路径不需要 durable attachment 服务）。
+  * @param options - the harness request; `options.system` maps to pi-ai's single `systemPrompt` slot.
+- * @param attachments - durable byte resolver for image references.
+- * @param onReplayDegrade - forwarded to {@link toPiAssistant} for each assistant message.
+- * @param maxRequestImageBytes - request-level bound on base64-encoded image payload; omission leaves every image in place.
++ * @param attachments - durable byte resolver for image references (vision models); optional.
++ * @param vision - whether the route model accepts image input.
+  * @returns the asynchronously resolved pi-ai context.
+  */
+-export function toPiContext(
+-  options: GenerateOptions,
+-  attachments: AttachmentStore,
+-  onReplayDegrade?: (reason: string) => void,
+-  maxRequestImageBytes?: number,
+-): Promise<PiContext>
+-export function toPiContext(
+-  options: GenerateOptions,
+-  attachments?: AttachmentStore,
+-  onReplayDegrade?: (reason: string) => void,
+-  maxRequestImageBytes?: number,
+-): PiContext | Promise<PiContext> {
+-  return attachments === undefined
+-    ? textOnlyContext(options, onReplayDegrade)
+-    : toPiContextWithImages(options, attachments, onReplayDegrade, maxRequestImageBytes)
++export function toPiContext(options: GenerateOptions, attachments?: undefined, vision?: boolean): PiContext
++export function toPiContext(options: GenerateOptions, attachments: AttachmentStore, vision?: boolean): Promise<PiContext>
++export function toPiContext(options: GenerateOptions, attachments?: AttachmentStore, vision = true): PiContext | Promise<PiContext> {
++  return attachments === undefined ? textOnlyContext(options, vision) : toPiContextWithImages(options, attachments, vision)
+ }
+ 
+-async function toPiContextWithImages(
+-  options: GenerateOptions,
+-  attachments: AttachmentStore,
+-  onReplayDegrade?: (reason: string) => void,
+-  maxRequestImageBytes?: number,
+-): Promise<PiContext> {
+-  assertSupportedImageRoles(options.messages)
+-  const requestMessages = offloadRequestImages(options.messages, maxRequestImageBytes)
++async function toPiContextWithImages(options: GenerateOptions, attachments: AttachmentStore, vision: boolean): Promise<PiContext> {
+   const toolNames = new Map<CallId, string>()
+   const messages: PiMessage[] = []
+ 
+-  for (const message of requestMessages) {
++  for (const message of options.messages) {
+     if (message.role === 'system') {
++      // 视觉模型无法在 pi-ai 单一 systemPrompt 槽内表达图片；非视觉模型
++      // （vision=false）走文本路径（imagesToText 转路径文本）。
++      if (vision && contentHasImage(message.content)) {
++        throw new LlmError('pi-ai cannot represent an image in an in-history system message', 'UNSUPPORTED_CONTENT')
++      }
+       // pi-ai has a single systemPrompt slot; in-history system messages are
+       // folded into user messages to preserve order (rare in practice — the
+       // harness sends the system prompt via options.system).
+-      messages.push({ role: 'user', content: flattenText(message), timestamp: 0 })
++      messages.push({ role: 'user', content: flattenBlocks(imagesToText(message.content, vision)), timestamp: 0 })
+       continue
+     }
+     if (message.role === 'assistant') {
+-      const assistant = toPiAssistant(message, onReplayDegrade)
++      const assistant = toPiAssistant(message)
+       for (const block of assistant.content) {
+         if (block.type === 'toolCall') toolNames.set(CallId(block.id), block.name)
+       }
+@@ -204,15 +259,13 @@ async function toPiContextWithImages(
+     }
+     // user role: text + tool results (each result becomes its own message).
+     const regular = message.content.filter(block => block.type !== 'tool-result')
+-    const content = await userContent(regular, attachments)
+-    const results = message.content.filter((block): block is Extract<ContentBlock, { type: 'tool-result' }> => (
+-      block.type === 'tool-result'
+-    ))
++    const content = await userContent(regular, attachments, vision)
++    const results = message.content.filter(block => block.type === 'tool-result')
+     if (content.length > 0 || results.length === 0) {
+       messages.push({ role: 'user', content, timestamp: 0 })
+     }
+     for (const result of results) {
+-      const resultContent = await userContent(result.content, attachments)
++      const resultContent = await userContent(result.content, attachments, vision)
+       messages.push({
+         role: 'toolResult',
+         toolCallId: result.toolCallId,
 diff --git a/packages/llm/llm/src/types.ts b/packages/llm/llm/src/types.ts
 index 8c5be187dd..750496f164 100644
 --- a/packages/llm/llm/src/types.ts