sala003

dsh-tool-describe-image

Name: dsh-tool-describe-image
Author: sala003

No description

Stars: 0
Language: TypeScript
Created: Aug 13, 2026
Updated: Aug 13, 2026

Other

GitHub repo

Introduction

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）

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

方式二：按路径描述

对模型说：

描述一下 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