- Language
- TypeScript
- License
- Apache-2.0
- Branch
- dev
deepseek-harnessdshdsh-pluginweb-ui
Adds image understanding to text-only models: automatically calls a vision model to describe dropped images, with only text entering the conversation.
$ dsh plugin --profile web add github:zhu1090093659/dsh-web-ui/packages/dsh-tool-describe-imageRun the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial
为 DSH Web GUI 增加模型侧的 describe_image 工具：让纯文本模型（DeepSeek V4 等）也能读懂图片——会话里拖入或粘贴一张图，插件自动把图片发给视觉模型（Qwen-VL、GLM-4V、GPT-4o、Claude 风格、本地 Ollama 等），只把返回的文字送回对话，图片本身不进入会话日志。
describe_image 模型工具：模型可调用它让视觉模型描述任意图片（本地绝对路径、http(s) URL、附件引用、自描述 Markdown 引用），返回结构化结果 { text, model, image, mimeType, bytes }，模型侧只看到 text（src/index.ts:189-232）。 引用，图片字节通过 /describe-image/attach 路由上传（校验 base64、magic bytes 与字节上限），持久化到附件存储，只有引用文本进入会话（src/attach-routes.ts:1-13）。/describe-image/capability 探测当前会话模型是否声明 image 输入；声明了直接把原图交给模型原生视觉并隐藏 describe_image 工具（包括 run_code 嵌套调用），未声明则走改写路径（src/model-capability.ts:1-22 / src/client/send-hook.ts:97-103）。baseURL / apiStyle / model / API key / 默认指令 / 各项上限（走设置服务），即时生效无需重启（README.md:23）。/describe-image/models 列出端点可用模型 id（解析草稿值以验证未保存的连接），列表切换为下拉选择；「测试连通性」控件以 max_tokens=1 最小补全测模型往返延迟（README.md:24 / src/model-probe.ts）。chat-completions（默认 /chat/completions）、responses（OpenAI Responses API 的 /responses）、anthropic-messages（Claude 风格 /v1/messages + x-api-key），适配 OpenAI、Qwen、GLM、Kimi、OpenCode Go 等不同厂商（src/config-resolve.ts:29-32 / README.md:75）。用户日常用 DeepSeek V4 这类纯文本模型与 DSH 对话时，遇到需要读图的任务——截屏报错、UI 截图诊断、拍照发图、扫描件 OCR——直接拖入输入框即可。模型看不到图片字节本身，而是收到一段引用与上下文，再调用 describe_image 把图片发给视觉模型，让模型侧既能聊纯文本又能像多模态模型一样读图。
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness (DSH) | 0.1.0-rc.8 | 所有 @deepseek-ai/* 依赖锁定 ^0.1.0-rc.8（package.json:61-73） |
| Node.js | ^22.19.0 或 >=24.0.0 | package.json#engines（package.json:7-9） |
| 平台 | 跨平台 | 仅使用 Node 内置模块（node:fs/promises、node:crypto、node:http），无原生模块依赖 |
| 原生模块 | 无 | — |
dsh plugin --profile web add github:zhu1090093659/dsh-web-ui/packages/dsh-tool-describe-image
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
baseURL | 字符串（必填） | 视觉模型端点根地址，按协议自动追加 /chat/completions / /responses 或归一化为 /v1/messages；末尾斜杠自动去除；仅接受 http(s) | — |
model | 字符串（必填） | 视觉模型 id，可带思考控制后缀：:off 显式关闭思考，:low :medium :high 开启思考，不带后缀则不发送思考控制字段 | — |
apiStyle | 枚举 | 视觉端点协议：chat-completions（默认，OpenAI 兼容）、responses（OpenAI Responses API）、anthropic-messages（Claude 风格，x-api-key 鉴权） | chat-completions |
apiKey | 字符串（密钥） | 内联 API key，本地调试用，建议用环境变量而非明文 | — |
apiKeyEnv | 环境变量名 | 凭证引用：先看 dsh-credentials 服务，再回退到启动环境 | VISION_API_KEY |
defaultPrompt | 字符串 | 模型未传 prompt 参数时的兜底指令（OCR、UI 评审、翻译等场景可按需调优） | 一段描述图片客观内容并转录可见文字的指令 |
maxBytes | 整数 | 图片字节上限（本地文件与下载 URL 一致） | 10485760（10 MiB） |
maxOutputTokens | 整数 | 单次输出 token 上限 | 1024 |
timeoutMs | 整数 | 单次视觉请求超时 | 120000（120 秒） |
renderImagePreview | 布尔 | 把会话里图片引用原地升级为缩略图（点击看大图）；仅影响本地显示 | true |
interceptImageSend | 布尔 | 发送时改写图片块为 describe-image 引用；关掉可让其他视觉插件接收原图 | true |
Q: 模型本身已经支持图片输入，还需要装这个插件吗？
A: 不需要。插件会在每次发送时通过 /describe-image/capability 探测当前会话模型是否声明 image 输入；声明了就把原图直接交给模型原生视觉能力，并自动隐藏 describe_image 工具，避免重复。
Q: 安装后一定要立即配置 endpoint 吗？
A: 不强制。全家桶聚合包默认无配置挂载，加载不受影响；首次调用会以 describe-image: baseURL must be an absolute http(s) URL 错误退出，到「设置 → 插件配置 → Image understanding」卡填好端点、模型、密钥即可使用，无需重启。
Q: 怎么切换视觉模型协议（OpenAI 风格、Anthropic 风格）？
A: 设置卡的「API style」字段控制：chat-completions（默认）请求 /chat/completions；responses 适配 OpenAI Responses API；anthropic-messages 用于 Claude 风格端点（OpenCode Go、智谱 GLM、月之暗面 Kimi 等），走 /v1/messages 并使用 x-api-key 鉴权。
Q: 模型 id 后面的 :off / :low / :medium / :high 是什么意思？
A: 思考控制后缀。:off 显式关闭思考，:low :medium :high 开启思考（chat-completions 协议三档都映射为 enabled，因为该协议没有 effort 档）；不带后缀则不发送控制字段，沿用端点默认。仅这四个已知后缀会被剥离，其他冒号变体（如 OpenRouter 的 :free）会原样转发。
Q: API key 应该怎么放？
A: 推荐走环境变量：把密钥放到环境变量 VISION_API_KEY（或 apiKeyEnv 自定义名），用 !!js process.env.VISION_API_KEY 注入到 cordis 配置；插件在每次调用时按「内联 apiKey → 凭证服务（dsh-credentials）→ 启动环境」三级回退解析，密钥不会出现在请求体里，也不会进入日志。
Q: 「会话内渲染图片预览」开关要不要开？
A: 默认开（renderImagePreview: true）。开启后客户端会把发送的 describe-image 引用原地升级为缩略图，点击查看大图；关闭则保留原始引用文本。两者都只是显示层差异，对消息文本与模型分析没有影响。如果反向代理没转发 /describe-image/raw 路由，缩略图会加载失败，文本仍按原样保留。
Q: 怎么让其他视觉插件接管图片处理？
A: 关闭设置卡的「发送时改写图片为 describe-image 引用」开关（interceptImageSend: false）。关闭后带图片的发送原样放行，由同会话的其他视觉插件接收原始图片块；此时纯文本模型的改写需要由它们自己负责。
Q: 一个调用能传多张图或获取结构化结果吗？
A: 不支持。插件只支持单图单答：不接受多图输入、不能追问上一张图、不输出坐标或框选这类结构化字段；纯 OCR 场景可以把 baseURL 指向更便宜的 OCR 模型降低单次成本。
进阶 — 多数场景安装即用，但要发挥多协议 / 思考控制 / 原生图片切换这些能力需要理解视觉模型协议差异与会话模型能力，零基础用户可能需要先读 README 才能用对设置项。
thinking.type / reasoning.effort）；不接受这些字段的端点（如普通 OpenAI 视觉模型）应使用不带后缀的模型 id（README.md:185-191）。MODEL_DOES_NOT_SUPPORT_IMAGES）（src/model-capability.ts:18-22）。