Grok 小图规范化RailgunHamster/dsh-grok-adaptation

dsh-grok-adaptation

DeepSeek Harness 插件，用于在 OpenAI Responses HTTP/SSE 路径上规范化尺寸过小的 Grok 图像输入。

英文

功能

该插件让 Grok 请求保持在标准的 Responses HTTP/SSE 路径上。它不会打开或要求 WebSocket 连接。

对于 Responses message 或 function_call_output 项中的每个 input_image，插件使用 Sharp/libvips 读取图像元数据。如果图像的任一边长为 24 像素或更小，它会：

1. 使用最近邻处理解码原始图像。
2. 将实际像素按比例缩放到 32x32 的透明画布上。
3. 添加一条文本注释，包含原始尺寸和生成的内容尺寸。

正方形图像会填满画布。窄图或矩形图像会保持其宽高比，并获得透明填充，而不是被拉伸。宽度和高度均大于 24 像素的图像会原样发送。

Sharp 为 PNG、JPEG、GIF、WebP、TIFF、AVIF 及其他受支持的格式提供了一条成熟的解码路径。该插件不维护单独手写的图像解码器。

适用范围

仅当以下所有条件均满足时，才会执行图像规范化：

- 端点：/v1/responses 或 /responses
- 模型：以 grok- 开头（可通过 autoModelPrefixes 配置）

可选的插件配置：

- hostnames：如果设置，则仅拦截这些主机名；空列表表示任意主机
- markerHeader / markerValue：可选的路由标记，默认为 x-dsh-grok-adaptation: v2

模型前缀检查是强制性的。Gemini、Qwen、GPT、web-search 及其他非 Grok 请求会原样转发，即使它们携带该标记。

安装

将该包安装到 DSH web 配置文件中：

dsh plugin --profile web add https://github.com/RailgunHamster/dsh-grok-adaptation.git
dsh plugin --profile web install

安装后重启 dsh-web。该包包含 Sharp 及其平台二进制依赖。

路由配置

仅将标记添加到 Grok 路由：

llm-pi-ai:
providers:
grok:
api: openai-responses
baseURL: https://api.example.com/v1
apiKeyEnv: GROK_API_KEY
headers:
x-dsh-grok-adaptation: v2

不要将此标记添加到普通的 GPT 或 web-search 提供商路由。

要将拦截限制到单个上游主机，请设置插件配置：

- id: grok-adaptation
config:
hostnames: ['api.example.com']
autoModelPrefixes: ['grok-']

开发

该包不包含任何凭据。它使用 DSH 已创建的 Authorization 头。

pnpm install
pnpm run check

测试用例包括带有当前轮次图像和工具结果图像重放的 Grok 4.6 Responses 请求，使用 PNG、JPEG、GIF、WebP、1x16、16x26、16x32 和 16x16 输入。尺寸过小的图像已被规范化，生成的请求成功完成。

许可证

MIT

中文

功能

插件让 Grok 请求继续使用标准 Responses HTTP/SSE，不打开也不依赖 WebSocket。
对于 Responses message 或 function_call_output 中的每个 input_image，插件使用 Sharp/libvips 读取图片信息。如果图片任意一边不超过 24 像素，插件会：

1. 使用最近邻方式解码原图。
2. 按比例把真实像素放大到 32x32 透明画布中。
3. 添加包含原图尺寸和实际内容尺寸的文字备注。

正方形图片会填满画布。窄图或矩形图保持原始比例，使用透明留白，不会被强行拉伸。宽度和高度都大于 24 像素的图片原样发送。

Sharp 为 PNG、JPEG、GIF、WebP、TIFF、AVIF 以及其他支持的格式提供统一且成熟的解码路径。插件不再维护手写的格式专用解码器。

作用范围

只有以下条件同时满足时才会进行图片规范化：

- 接口：/v1/responses 或 /responses
- 模型：名称以 grok- 开头（可通过 autoModelPrefixes 配置）

可选插件配置：

- hostnames：若填写，则只拦截这些主机名；空列表表示不限制主机
- markerHeader / markerValue：可选路由标记，默认 x-dsh-grok-adaptation: v2

实际生效仍以模型前缀为准。即使 Gemini、Qwen、GPT、web search 或其他非 Grok 请求带有该标记，也会原样转发，不会被修改。

安装

将插件安装到 DSH web profile：

dsh plugin --profile web add https://github.com/RailgunHamster/dsh-grok-adaptation.git
dsh plugin --profile web install

安装后重启 dsh-web。插件依赖中包含 Sharp 及其对应平台的二进制依赖。

路由配置

只给 Grok 路由添加标记：

llm-pi-ai:
providers:
grok:
api: openai-responses
baseURL: https://api.example.com/v1
apiKeyEnv: GROK_API_KEY
headers:
x-dsh-grok-adaptation: v2

不要给普通 GPT 或 web-search provider 路由添加这个标记。

如果只想拦截某一个上游主机，可以在插件配置里写：

- id: grok-adaptation
config:
hostnames: ['api.example.com']
autoModelPrefixes: ['grok-']

开发

插件不包含任何凭据，使用 DSH 已经生成的 Authorization 请求头。

pnpm install
pnpm run check

已测试 Grok 4.6 Responses 请求，包括当前轮图片和工具结果图片回放，覆盖 PNG、JPEG、GIF、WebP、1x16、16x26、16x32 和 16x16 图片。小图经过规范化后，请求成功完成。

许可证

MIT