dsh-tool-describe-image

让 DeepSeek 看懂图片的 DSH 插件 —— 通过阿里云百炼（DashScope）qwen-vl 视觉模型，把图片转成文字描述，纯文本模型也能"看见"图片。

项目特点

• 粘贴即识别（Web）：在 DSH Web 会话里直接 Ctrl+V 粘贴图片，自动识别成文字描述填入输入框，回车即可发送——不需要文件路径
• describe_image 工具：模型按路径读取图片并转成文字，任何 surface（Web / headless）都可用
• 零源码改动：完全通过 DSH 公开扩展点实现（工具注册、RPC 通道、client-modules），不改 Harness 任何代码
• 单包全包：一个 npm 包 = host 半区（工具 + RPC）+ 浏览器半区（粘贴识别），dsh plugin add 即装即用
• 安全设计：RPC 通道仅限 loopback；图片字节不进入模型上下文，只把文字描述带给模型
• 双语文案：跟随 Web 界面语言自动切换中文 / 英文

工作原理

DeepSeek 官方适配器是纯文本路由，DSH 内置的 read_image 工具会在模型不支持 image 输入时拒绝。本插件绕开这道限制：

粘贴图片 / 指定路径
  → 图片字节交给百炼 qwen-vl 视觉模型
  → 返回文字描述（作为 tool result 或 draft 文本）
  → DeepSeek 基于文字理解图片

• 工具模式：describe_image(file_path, question?) 注册到 ctx.tools，schema 自动流入系统提示词
• 粘贴模式：浏览器半区在 document 上挂 capture 阶段 paste 监听，拦截图片 → base64 → host RPC（/dsh-describe-image）→ 文字填入输入框，带"正在识别…"提示与失败 toast

安装

需要已安装 DSH（0.1.0-rc.6+）。

npm install -g dsh-tool-describe-image
dsh plugin --profile web add dsh-tool-describe-image

配置

需要阿里云百炼 API Key（百炼控制台免费开通）：

$env:DASHSCOPE_API_KEY = "sk-你的key"

推荐写入 ~/.dsh/profiles/web/.env，免去每次手动设置：

DASHSCOPE_API_KEY=sk-你的key

可配置项

字段	默认值	说明
apiKey	无（读 DASHSCOPE_API_KEY）	DashScope API key
model	qwen-vl-plus	视觉模型 id（qwen-vl-plus / qwen-vl-max）
baseUrl	https://dashscope.aliyuncs.com	DashScope 端点
prompt	详细描述指令	随图发送的指令文本
maxImageBytes	8 MiB	单张图片读取上限
timeoutMs	60000	HTTP 协作超时

在 ~/.dsh/profiles/web/cordis.patch.yml 中覆盖：

- insert:
    - id: describe-image
      name: 'dsh-tool-describe-image'
      config:
        model: qwen-vl-max

使用

dsh web

方式一：粘贴图片（Web）

1. 任意截图 Ctrl+C
2. 输入框 Ctrl+V
3. 看到"正在识别图片…" → 文字描述自动填入输入框
4. 回车发送

方式二：按路径描述

对模型说：

描述一下 C:\Users\你的用户名\Pictures\image.png

模型会自动调用 describe_image 工具并基于描述回答。

常见问题

问题	解决
启动报 DashScope API key missing	未配置 key，见「配置」
粘贴后没有反应	确认安装最新版、重启过 dsh web
识别结果不理想	patch 中把 model 换成 qwen-vl-max
图片格式不支持	仅支持 PNG / JPG / WebP / GIF（按字节检测，不信扩展名）

开发

npm install
npm run typecheck   # 类型检查（host + client）
npm run build       # host 构建
npm run bundle      # client bundle 构建

测试见 TESTING.md。

技术架构

┌─────────────────────────── dsh-tool-describe-image ───────────────────────────┐
│ Host 半区 (lib/index.js)            Browser 半区 (lib/client.js)             │
│  ├ describe_image 工具 (ctx.tools)   └ paste 监听 → RPC → setDraft           │
│  └ /dsh-describe-image RPC 通道       (dsh.client 声明 → client-modules 发现) │
│        ↑ 共享 rpc-contract 契约                                                │
└──────────────────────────────────────────────────────────────────────────────┘

许可证

MIT

联系方式

• 作者：sala003
• 邮箱：841115144sala@gmail.com
• GitHub：https://github.com/sala003/dsh-tool-describe-image
• npm：https://www.npmjs.com/package/dsh-tool-describe-image