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

使用

新会话里对 agent 说：

用 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)	响应大小上限