图像格式兼容垫片 wuyiwuaa1-ship-it/dsh-read-image-jpeg-fallback

dsh-read-image-jpeg-fallback

一个用于 LM Studio 的零配置 DSH 图像兼容垫片。

它保持 DSH 原生的 read_image + 多模态模型流程不变，但在构建下一个提供商请求之前，透明地将 PNG/WebP 工具附件转换为不透明的 sRGB JPEG。

当你的主模型已经支持图像，但 LM Studio 的 openai-completions 路由拒绝 DSH 图像附件并报出如下错误时，请使用它：

400 'url' field must be a base64 encoded image

这是一个媒体格式兼容插件，不是视觉模型、OCR 插件或图像转文本回退方案。

为什么需要它

在某些 DSH + LM Studio 路径中，read_image 可能生成一个 PNG/WebP 图像块，该图像块随后以 LM Studio 不接受的格式到达提供商请求。

此插件仅修复这一传输不匹配问题：

read_image
↓
DSH 图像附件 ↓ PNG / WebP ?
├─ 否 → 原样传递 └─ 是 → 不透明 sRGB JPEG（质量 90） ↓ 同一个多模态模型

模型仍然接收图像本身。没有 OCR 步骤，没有辅助 VLM 调用，也不会转换为文本描述。

它的不同之处

| 方案 | 图像会发生什么 | 主模型路径 |
| 本插件 | PNG/WebP 被重新编码为 JPEG | 保留；同一个多模态模型接收图像 |
| 视觉回退插件 | 图像被发送到另一个 VLM，通常转换为文本 | 主模型接收描述/结果 |
| OCR / 图像读取插件 | 图像由专用工具分析 | 主模型消费工具输出 |
| 独立的 LM Studio 视觉工具 | 智能体调用专用的视觉工具/模型 | 绕过原生 read_image → 当前模型路径 |

此插件有意保持狭窄的适用范围：当原生 DSH 视觉路径已经是你想要的行为，而只有图像编码不兼容时，它很有用。

它做什么

该插件在成功的 read_image 工具调用之后挂接到 DSH，并按如下方式转换模型可见的图像块：

- image/png → 不透明 sRGB JPEG
- image/webp → 不透明 sRGB JPEG
- JPEG 及其他媒体类型 → 不变

它不会替换内置的 read_image 工具，也不会修补 DSH 核心源代码。

转换本身在本地进行。生成的 JPEG 随后遵循你现有的 DSH/提供商请求路径。

何时使用它

当以下所有条件都成立时，此插件非常适合：

- 你选择的/主模型已经支持图像输入；
- 你通过 OpenAI 兼容的 openai-completions 路由使用 LM Studio；
- read_image 一直正常工作，直到构建后续模型请求时，在图像附件上失败；
- 你希望保留原生多模态流程，而不是将图像路由到另一个视觉模型。

如果你的提供商已经接受 DSH 发送的图像格式，或者你的主模型是纯文本的，而你实际上需要视觉回退/OCR 解决方案，那么你很可能不需要它。

安装

需要：
- DSH 0.1.1-rc.2
- Node.js >= 22
- pnpm 在 PATH 中可用

从 npm 安装

dsh plugin --profile web add dsh-read-image-jpeg-fallback

从 GitHub 安装

dsh plugin --profile web add github:wuyiwuaa1-ship-it/dsh-read-image-jpeg-fallback

要显式固定当前 main 分支：

dsh plugin --profile web add github:wuyiwuaa1-ship-it/dsh-read-image-jpeg-fallback#main

从 tarball 安装

dsh plugin --profile web add .\dsh-read-image-jpeg-fallback-0.1.1.tgz

安装后重启 DSH Web。

用法

无需任何配置。

正常使用 read_image 即可。当其成功结果包含 PNG 或 WebP 图像块时，插件会在构建下一次提供商请求之前，为模型可见的附件创建一个 JPEG 替代版本。

无需学习新的面向模型的工具，正常的代理工作流也不会发生变化。

失败行为

该插件被设计为失败开放（fail open）。

如果读取、转换或保存替代图像失败：

- 保留原始的 read_image 结果；
- 向 DSH 日志写入一条警告；
- 不会将成功的工具调用转换为插件错误。

支持的环境

已验证于：

- DSH 0.1.1-rc.2
- LM Studio openai-completions
- Node.js 26.x
- sharp 0.35.3
- Windows

除非经过明确测试，否则不保证与其他 DSH 版本、操作系统或提供商的兼容性。

已知问题

在某些 Windows + pnpm 环境中，移除插件时可能会在 pnpm 已完成其文件系统更改后挂起，尤其是在清理 sharp 时。

如果出现这种情况，在 DSH 配置文件中直接固定 sharp 可避免该问题：

cd \profiles\web
pnpm add sharp@0.35.3

卸载

dsh plugin --profile web remove dsh-read-image-jpeg-fallback

之后重启 DSH Web。

工作原理

该插件使用 DSH 的 tools/post-execute 钩子。

对于包含 PNG 或 WebP 图像块的已接受的 read_image 结果，它会：

1. 读取已存储的附件；
2. 使用 sharp 将其转换为不透明的 sRGB JPEG，质量为 90；
3. 通过 DSH 的附件存储保存一个新附件；
4. 仅将模型可见的图像块替换为新的 JPEG 引用。

规范的工具结果和内置的 read_image 实现保持不变。

范围

目标刻意保持很小：提供一个透明的图像格式兼容层，直到提供商/宿主路径能够直接接受原始媒体格式。

如果上游 DSH 或 LM Studio 获得了等效的处理能力，那么对于该配置而言，此插件可能就不再必要了。

许可证

MIT