deepseek-vision

August 6, 2026 · View on GitHub

让 WorkBuddy 中的纯文本模型（如 DeepSeek）也能"看见"图片：发图即自动识别，识别结果注入对话。

GitHub License GitHub stars GitHub release

为什么需要它

WorkBuddy 默认支持图片输入，但当你使用纯文本模型（如 DeepSeek，不支持视觉）作为后端时：

发一张图片，模型完全看不到内容；
你只能自己用别的工具 OCR / 描述，再粘贴文字过来。

deepseek-vision 解决这个问题：它在 WorkBuddy 里挂了一个 UserPromptSubmit 钩子，自动检测你消息中的图片 → 调用任意视觉大模型 API 提取内容 → 把识别结果注入给后端模型。纯文本模型从此"看见"图片，对话无缝继续。

特性

✅ 全自动：粘贴图片 / @image 引用 / 文件路径引用 / @"..." 路径，发消息即识别，无需手动操作
✅ 零打扰：无图片时钩子零输出，纯文本对话完全不受影响
✅ 失败静默降级：网络错误 / Key 失效 / 超时（20s），绝不影响你的对话
✅ SVG 支持：自动用 Chrome headless 渲染成 4096px 高清图再识别，小字也认得清
✅ 技能兜底：附带 image-understanding 技能，手动说"看图"也能识别
✅ 一键安装 / 卸载：install.sh / uninstall.sh
✅ 模型可切换：config.json 改一个字段即可换 qwen-vl-plus / qwen3-vl-flash 等任意 OpenAI 兼容视觉模型

架构

┌─────────────┐  粘贴/引用图片   ┌──────────────────────┐
│  WorkBuddy  │ ──────────────► │ UserPromptSubmit 钩子  │
│  (纯文本模型) │                 │  hooks/vision-hook.py │
└─────────────┘                 └──────────┬───────────┘
                                           │ 读 transcript 拿图片真实路径
                                           ▼
                                 lib/dashscope_client.py
                                           │ 调用视觉大模型 API（OpenAI 兼容）
                                           ▼
                                 识别文本 → additionalContext 注入模型
                                           │
                                           ▼
                               DeepSeek "看见"图片，继续回答

文件结构

~/.workbuddy/
├── deepseek-vision/                 # 插件主目录（本仓库安装位置）
│   ├── hooks/vision-hook.py         # UserPromptSubmit 钩子（自动拦截）
│   ├── lib/dashscope_client.py      # 视觉 API 客户端（零第三方依赖）
│   ├── config.json                  # 你的配置（含 API Key，chmod 600）
│   ├── install.sh / uninstall.sh    # 一键安装/卸载
│   └── README.md
├── skills/image-understanding/      # 兜底技能（模型驱动）
│   ├── SKILL.md
│   └── scripts/vision.py
└── settings.json                    # 钩子注册（install.sh 自动 merge）

📖 新手完整教程（0 到 1，约 10 分钟）

第 0 步：确认你的模型是"纯文本模型"

这一步决定你是否需要本插件。 只有后端模型不支持图片输入时才需要：

macOS：打开终端执行 cat ~/.workbuddy/models.json，找到你的模型配置：
```
{ "id": "deepseek-v4-flash", "supportsImages": false, ... }
```
看到 "supportsImages": false → 纯文本模型 → 需要本插件 ✅ 看到 "supportsImages": true → 模型自带视觉 → 不需要安装本插件
不确定的话，直接发一张图片给模型，如果它说"我看不到图片"，就说明需要。

第 1 步：申请视觉 API Key（阿里云百炼，推荐）

本插件需要一个视觉大模型来"替"DeepSeek 看图，默认用阿里云百炼的 qwen 系列：

打开阿里云百炼控制台（用阿里云账号登录，未注册先注册）
首次使用按提示开通百炼（DashScope）服务
进入 API-KEY 管理 → 创建 API-KEY → 复制 sk- 开头的 Key

计费提示：qwen3-vl-flash 按量计费，日常看图成本极低（约 ¥0.001/张级别）；也可以选有免费额度的模型，或在控制台购买优惠套餐。Key 只保存在你本机，不会上传。

第 2 步：克隆并一键安装

git clone https://github.com/rison114514/deepseek-vision.git
cd deepseek-vision
bash install.sh

install.sh 会自动完成三件事：

部署插件到 ~/.workbuddy/deepseek-vision/
部署兜底技能到 ~/.workbuddy/skills/image-understanding/
在 ~/.workbuddy/settings.json 注册 UserPromptSubmit 钩子（自动备份原文件到 settings.json.bak）

第 3 步：填入你的 API Key

cp config.example.json ~/.workbuddy/deepseek-vision/config.json
open -e ~/.workbuddy/deepseek-vision/config.json    # 打开编辑器

把 api_key 替换成第 1 步申请的 Key，保存：

{
  "api_key": "sk-你的百炼Key",
  "model": "qwen3-vl-flash",
  "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "timeout": 20
}

想换视觉模型？只需改 model（如 qwen3-vl-plus 质量更高，qwen-vl-max 更强）。

第 4 步：重启 WorkBuddy（关键！）

必须完全退出并重新打开 WorkBuddy（不是新建对话，是退出 App 再打开）。钩子在启动时加载，不重启不生效。

重启后可以先发一条纯文本消息确认一切正常（钩子应零输出、无感）。

第 5 步：验证——发一张图试试

复制一张图片（Cmd+C，比如截图或下载的图片）
在 WorkBuddy 对话里直接粘贴（Cmd+V），并输入：这张图里有什么？

发送后等待 1-3 秒，如果看到回复里出现类似这样的内容，就说明成功了：

【图片识别结果（由外部多模态模型 qwen-vl 提供）】
这是一张...（图片描述）

也可以换个方式：消息里直接写完整路径 看看 /Users/你/Desktop/xxx.png，或 @".../xxx.svg" 分析

如何确认插件真的在干活（三种信号）

信号	怎么看
① 日志	`tail -f ~/.workbuddy/logs/deepseek-vision/vision.log`，发图时会出现 `image detected` / `injected desc`
② 识别注入	模型回复前，会先出现"【图片识别结果】"的内容（部分版本显示在消息上下文中）
③ 技能	直接说"识别图片"，模型会自主调用 `image-understanding` 技能

使用方式

方式	示例	说明
粘贴图片	粘贴一张图 + 问"这张图里有什么"	自动识别（推荐）
`@image` 引用	`识别这个 @image#1:xxx.png`	自动识别
文件路径	`看看 /path/to/img.png` 或 `@".../deco.svg" 分析`	自动识别（支持 SVG）
手动技能	说"识别图片 / 看图"	模型自主调用技能识别

配置说明

字段	说明	默认
`api_key`	视觉模型 API Key（必填）	—
`model`	视觉模型 ID	`qwen3-vl-flash`
`base_url`	OpenAI 兼容接口地址	`https://dashscope.aliyuncs.com/compatible-mode/v1`
`timeout`	API 调用超时（秒）	`20`

换其他视觉模型：改 model 即可（如 qwen3-vl-plus、qwen-vl-max），或把 base_url 换成其他 OpenAI 兼容服务（GLM-4V、GPT-4o、通义千问等均可，对照表见 docs/PROMPT_TEMPLATE.md）。

常见问题（排障）

现象	原因与排查
发图后没有识别结果	① 重启 WorkBuddy 了吗？（必须完全退出重开）② `config.json` 的 `api_key` 填了吗？③ 看日志：`tail -20 ~/.workbuddy/logs/deepseek-vision/vision.log`——如果显示 `API call failed: 401` 是 Key 错误，`404/400` 是模型名或 base_url 错误
日志里没有记录	钩子没注册成功：检查 `~/.workbuddy/settings.json` 里有没有 `hooks.UserPromptSubmit`（install.sh 已自动写入，确认没被还原）；重新跑一次 `bash install.sh`
对话变慢 / 卡顿	钩子有 20s 硬超时且失败静默降级，正常情况下无感；SVG 渲染约多 2-3s 属正常
识别结果不准（小字）	已自动用 4096px 渲染；仍不准可换更强的模型（`qwen3-vl-plus`）
想换视觉模型	改 config.json 的 `model` / `base_url`，重启生效
不想用了	`bash ~/.workbuddy/deepseek-vision/uninstall.sh`，重启即完全移除

卸载

bash ~/.workbuddy/deepseek-vision/uninstall.sh
# 重启 WorkBuddy 生效（自动移除钩子 + 删除插件与技能，其余配置不受影响）

工作原理（给开发者）

WorkBuddy 的 UserPromptSubmit 钩子 stdin 中 prompt 字段只含文件名引用（如 @image#1:xxx.png），完整路径藏在 transcript_path 指向的 jsonl 会话记录里、用 <image_local_path>...</image_local_path> 标签包裹。钩子读 transcript 即可拿到图片真实路径，稳定可靠（详见 docs/DEVELOPMENT.md）。

文档

开发心得与踩坑记录 —— 完整开发流程复盘
可复现开发提示词 —— 想给 WorkBuddy 开发其他视觉技能？直接套用这份提示词
阿里云百炼视觉模型文档

开源协议

MIT