dsh-tool-describe-image

dsh-tool-describe-image — 图像理解工具插件

English | 中文

模型侧 describe_image 工具：为纯文本模型（DeepSeek V4 等）提供图像理解能力。 每次调用加载一张图片——本地文件路径、http(s) URL，或会话附件引用——交给 OpenAI 兼容的视觉模型端点（Qwen-VL、GLM-4V、GPT-4o、本地 Ollama 等）回答， 支持 Chat Completions 与 Responses 两种协议；只有返回的文本进入对话，图片本身绝不进入会话记录。

本包由 deepseek-harness packages/vision/tool-describe-image 移植（镜像仓库 whitelonng/dsh-plugin-describe-image）， 按 dsh-web-ui 全家桶规范适配：仅官方 NPM SDK、host 侧插件配浏览器半部、设置区实时配置，不修改 DSH 源码。

能力

安全模型

• 视觉请求与图片下载均拒绝 HTTP 重定向（redirect: 'error'），bearer 凭证与图片字节 不会转发到部署配置之外的源。
• 请求体携带 base64 图片但不携带密钥；不记录请求头与已解析凭证。
• 仅接受 http(s) URL 与本地路径，其余 URL 协议一律拒绝。
• attach 路由先校验 base64、magic bytes 与字节上限，再交给附件存储持久化； 只有引用 JSON（文本）进入会话。
• 响应体先按上限（maxOutputTokens * 8 + 64 KiB）截断再解析。

安装

推荐直接安装全家桶聚合包 @linxin666/dsh-web-ui-all（一个包装齐全部功能插件与皮肤），或单独安装本插件：

# 推荐：直接从 npm 安装
dsh plugin --profile web add @linxin666/dsh-tool-describe-image

聚合包默认无配置挂载本插件：加载不受影响，首次调用会以清晰的错误提示 （describe-image: baseURL must be an absolute http(s) URL）告知尚未配置。 在「设置 → 插件配置 → Image understanding」卡填写端点与模型即可立即使用，无需重启。 （与上游差异：上游在加载时强校验；全家桶聚合挂载没有配置入口，故改为 「组合条目实际配置时才加载时校验、否则调用时校验」。）

配置

带配置的挂载示例（profile 的 cordis.patch.yml / 组合文件）：

- id: describe-image
  name: '@linxin666/dsh-tool-describe-image'
  config:
    baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1
    model: qwen-vl-max
    apiKey: !!js process.env.VISION_API_KEY

只开放 Responses API 的端点设置 apiStyle: responses：

- id: describe-image
  name: '@linxin666/dsh-tool-describe-image'
  config:
    baseURL: https://api.openai.com/v1
    apiStyle: responses
    model: gpt-4o-mini
    apiKey: !!js process.env.VISION_API_KEY

使用

自定义指令

工具接受 prompt 参数：告诉视觉模型你具体要什么——「转录全部文字」、「把表格提取为 CSV」、 「诊断这个 UI 的布局问题」、「把文字翻译成中文」。针对性指令远胜泛泛描述；工具描述会引导 文本模型优先传指令。未传 prompt 的调用回退到 defaultPrompt。

从输入框发送图片

DSH 输入框对纯文本模型没有图片入口，因此在输入框里拖拽或粘贴图片：发送时插件会把携带图片的 发送改写为 describe-image 引用（![图片](/describe-image/raw/sha256:…)），而不是模型读不了的 图片块——图片在会话里正常渲染，模型经工具分析它。图片字节经 host 端 /describe-image/attach 路由上传（校验大小与 magic bytes，持久化到附件存储）；只有引用文本进入会话记录。

已知限制

• 仅 magic-byte 门校验类型、不解码图片：头合法但内容损坏的文件会在视觉端点才报错。
• 单图单答：不支持多图输入、追问上一张图、结构化输出（坐标 / 框）。
• 抽取文本仍消耗一次 VLM 调用：仅需 OCR 的部署可把 baseURL 指向更便宜的 OCR 模型。
• 仅 OpenAI 兼容协议：支持 Chat Completions（/chat/completions）与 Responses（/responses） 两种形态，请求 / 响应形态不同的厂商需要单独适配。

来源与版权

• 来源：本包移植自 whitelonng/dsh-plugin-describe-image （deepseek-harness packages/vision/tool-describe-image），2026-08 迁入，测试随源码一并移植 （pnpm --filter @linxin666/dsh-tool-describe-image test）。
• 版权：原代码版权归原作者（deepseek-ai / whitelonng）所有，本仓库仅托管与维护，不主张版权； 贡献移植部分由贡献者授权以全家桶许可证发布。
• 许可证：全家桶以 Apache-2.0 授权（见仓库根 LICENSE），本包 license 字段为 Apache-2.0。