图片识别 LuRia-yzk/dsh-tool-image-recognize

dsh-tool-image-recognize

图片内容识别工具（安全版）：给纯文本模型（如 DeepSeek）补视觉能力。

功能

注册 image_recognize 工具，把图片文件发送给可配置的视觉模型（默认千问 qwen3-vl-flash），返回文字描述：

| 参数 | 类型 | 说明 |
| path | string（必填）| 图片路径（绝对路径或工作区内相对路径）|
| mode | auto / ocr / describe | auto 自动判断（PNG 截图→提取文字，照片→描述）；缺省 auto |
| question | string | 自定义问题（提供时优先生效）|

⚠️ 数据流说明（重要）

本工具会把指定文件的内容发送到 baseURL 指向的第三方视觉 API（字节离开本机）。这是本工具的工作原理——图片必须先发给视觉模型才能被识别。请确认：
- 只把真正的图片文件路径交给模型调用（本工具已做魔数校验，非图片会拒绝）；
- baseURL 使用 HTTPS 端点；
- apiKeyEnv 只应指向视觉专用 key，不要把主模型（如 DEEPSEEK_API_KEY）的 key 指向这里。

安全设计

- 只通过 ctx.tools.register 注册工具，不修改任何框架核心文件
- 文件读取走 ctx.fs（沙箱合规），不直接碰磁盘
- 魔数校验：读取后校验文件头（PNG/JPEG/WebP/GIF/BMP），非图片直接拒绝——杜绝"任意可读文件被外发"
- 端点/模型/key 环境变量全部可配置，不硬编码
- 图片大小上限（默认 15MB）+ 请求超时（默认 30s）+ 响应大小上限（默认 1MB）
- 读取后发送 fs/observed，与官方 read 工具一致

安装

1. 插件源码放 $DSH_HOME/profiles/web/plugins/dsh-tool-image-recognize/
2. package.json 的 dependencies 加："dsh-tool-image-recognize": "file:plugins/dsh-tool-image-recognize"，然后 pnpm install
3. cordis.patch.yml 加：

- insert:
- id: tool-image-recognize
name: 'dsh-tool-image-recognize'
config:
baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1
apiKeyEnv: VISION_API_KEY
model: qwen3-vl-flash

4. 设置环境变量（~/.dsh/.env）：VISION_API_KEY=sk-xxx（视觉专用 key）
5. 重启 dsh

使用

新会话里对智能体说：

用 image_recognize 看一下 C:\path\to\image.png 用 image_recognize 提取这个截图里的文字: C:\path\to\screenshot.png (mode: ocr) 用 image_recognize 看看这张图里的二维码是什么: C:\path\to\qr.png

配置项

| 键 | 默认值 | 说明 |
| baseURL | https://dashscope.aliyuncs.com/compatible-mode/v1 | OpenAI 兼容端点（建议 HTTPS）|
| apiKeyEnv | VISION_API_KEY | 视觉专用 API key 的环境变量名 |
| model | qwen3-vl-flash | 视觉模型 |
| maxBytes | 15728640 (15MB) | 图片大小上限 |
| timeoutMs | 30000 | 请求超时 |
| maxTokens | 1024 | 输出 token 上限 |
| maxResponseBytes | 1048576 (1MB) | 响应大小上限 |