Adds image understanding to text-only models: sends images to OpenAI-compatible vision endpoints for parsing, with only text results returned to the conversation and image bytes excluded from logs.
Categories
Install
$ dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/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 中的纯文本模型补齐"看图"能力：在工具调用时把图片交给 OpenAI 兼容的视觉端点解析，仅把模型返回的文字结果送回会话，图片字节本身不进对话日志。
核心能力
- 给纯文本模型补齐图像理解：模型可主动调用
describe_image工具，分析一张图片并拿到文字描述 - 接受三种图片来源：本地绝对路径、
http(s)链接（拒绝重定向）、会话附件引用（拖拽/粘贴产生的 markdown 引用） - 直接在纯文本会话里发图：拖拽或粘贴图片会被自动改写为引用，图片正常渲染，模型通过工具分析
- 支持自定义指令：调用时可传
prompt（OCR、图表解读、UI 诊断、翻译等），未传则用defaultPrompt兜底 - 双协议适配：
chat-completions走/chat/completions，responses走/responses，覆盖 Qwen-VL、GLM-4V、GPT-4o、Ollama 等 - 实时配置卡：设置 → 插件配置 → Web UI 插件组 → 图像理解，修改端点、模型、密钥、上限后即时生效，无需重启
技术实现
- 语言: TypeScript
- 关键依赖:
@deepseek-ai/cordis（cordis 插件运行时）、@deepseek-ai/dsh-tools（模型工具注册）、@deepseek-ai/dsh-credentials（密钥解析服务）、schemastery（设置卡 schema） - 架构模式: host + client 双半区 cordis bundle；host 半区在 DSH 进程注册
describe_image工具与/describe-image/attach//describe-image/raw路由，client 半区在浏览器侧改写图片发送并渲染设置卡；通过cordis.patch.yml注入，零修改 DSH 源码 - 入口文件:
src/index.ts（host 半区）、src/client/index.ts（浏览器半区）
适用场景
当你在 DSH 中使用 DeepSeek V4 这类不支持原生图像输入的文本模型，又希望它能"看图"：上传截图让模型描述界面、把表格图转 CSV、做 OCR 识别、对 UI 截图做问题诊断等。插件把"图"翻译成"描述文字"喂给文本模型，整个过程图片字节不写入会话历史，规避敏感截图泄入日志的风险。
前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 0.1.0-rc.7+ | devDependencies 中各 @deepseek-ai/dsh-* 包均声明 ^0.1.0-rc.7 |
| Node | ^22.19.0 或 >=24.0.0 | engines.node 字段声明 |
| 平台 | 跨平台 | host 半区跑在 Node，client 半区跑在浏览器，无需操作系统特定依赖 |
| 原生模块 | 无 | 仅依赖官方 SDK 与 schemastery，无需编译原生扩展 |
安装方式
dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-tool-describe-image
配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
baseURL | 字符串 | OpenAI 兼容视觉端点的根地址（如 https://dashscope.aliyuncs.com/compatible-mode/v1），末尾斜杠会被自动去掉 | 必填，无默认 |
model | 字符串 | 要调用的视觉模型 id | 必填，无默认 |
apiKey | 字符串 | 内联 API 密钥，本地调试用，建议用环境变量注入而非明文 | 无（未设置时按 apiKeyEnv 解析） |
apiKeyEnv | 字符串 | 凭证引用对应的环境变量名；插件按"内联 key → 凭证服务 → 启动环境"逐级回退 | VISION_API_KEY |
defaultPrompt | 字符串 | 模型未传 prompt 时的兜底指令（让模型"按事实描述、转录可读文字、提示异常"） | 见源码中 DEFAULT_PROMPT |
apiStyle | 枚举 | 端点协议形态：chat-completions 走 /chat/completions，responses 走 /responses | chat-completions |
maxBytes | 整数 | 图片字节上限（本地文件与下载链接共用），超出则拒绝 | 10485760（10 MiB） |
maxOutputTokens | 整数 | 单次请求输出 token 上限，分别映射为 max_tokens 或 max_output_tokens | 1024 |
timeoutMs | 整数 | 单次视觉请求超时（毫秒） | 60000 |
常见问题
Q: 第一次调用就报错说 baseURL 不对，怎么修？
A: 打开"设置 → 插件配置 → Web UI 插件组 → 图像理解"卡片，把端点根地址（如 https://dashscope.aliyuncs.com/compatible-mode/v1）和模型 id 填进去，保存后立即生效，不用重启。
Q: API key 应该写在哪里比较安全？
A: 不建议把 key 直接写进配置文件。默认会从环境变量 VISION_API_KEY 读取（可通过 apiKeyEnv 改成别的名字），也可以在设置卡里粘贴内联 apiKey 用于本地调试；密钥不会写入日志。
Q: 在纯文本会话里拖图片，模型能"看到"吗？
A: 不能直接看到。插件在发送时会自动把图片块改写为引用（形如 ），图片字节经 attach 路由上传到附件存储、只把引用文本带进会话，模型再通过 describe_image 工具间接"看到"并分析。
Q: 协议选 chat-completions 还是 responses？
A: 默认 chat-completions，访问 baseURL/chat/completions；如果端点只提供 OpenAI Responses API，把 apiStyle 设为 responses，会改用 baseURL/responses 和 input/max_output_tokens/output_text 形态。
Q: 一张图片不够用，能不能一次给多张？
A: 目前一次只能处理一张图片，不支持多图输入，也不支持追问上一张图或输出坐标框等结构化结果，这是已声明的功能边界。
Q: 把插件卸载干净要怎么操作？
A: 在 dsh profile 中移除 describe-image 这个组合条目（cordis.patch.yml 对应的行），并按需清理本地 .npmrc 与符号链接；插件本身不向宿主持久化任何状态。
上手难度
入门 — 配置项集中在设置卡的一张表单里，填好端点、模型、API key 就能用；无需编写代码或修改 DSH 源码。
已知问题与限制
- 仅做 magic-byte 头校验、不解码图片内容：扩展名正确但文件实际损坏的情况下，要等到请求打到视觉端点才会报错
- 单图单答：每次
describe_image调用只能处理一张图片，不支持多图输入、不支持追问上一张图、不输出坐标/框等结构化结果 - OCR 也算一次 VLM 调用：纯文字提取场景下仍消耗视觉模型额度，可将
baseURL指向更便宜的 OCR 专用端点来降本 - 仅 OpenAI 兼容协议：只支持 Chat Completions 与 Responses 两种请求/响应形态，使用其他私有协议的厂商需要单独适配
- 响应体按
maxOutputTokens * 8 + 64 KiB截断后解析，模型回答极长时被截断的风险由maxOutputTokens控制
