视觉桥接 limccn/deepseek-vl-support

deepseek-vl-support

English → README.md

它能做什么

有些 AI 模型（比如 DeepSeek）能读文字，却看不了图片。报错截图、界面草图、图表、手写笔记照片——对它们来说都是"看不见"的。

这个小工具就是给它们装上"眼睛"。装好之后，每当模型想读一张图片，工具会把图片发给一家你选的"看图服务"（Moonshot、OpenRouter、SiliconFlow、Ollama……），拿回一段详细的文字描述，再把描述交给模型——模型就像真的看见了图片一样。

模型读取 screenshot.png → 本工具在读取时拦截 → 图片 → 看图服务 → 返回详细文字描述 → 模型收到："[Vision of screenshot.png]: " → 模型根据描述继续干活

不需要改任何模型设置，也不需要写配置文件——一次性安装后自动生效。一条命令安装，一条命令卸载。MIT 开源。

适用人群

你在任何 AI 编程工具里使用纯文本模型（如 DeepSeek），希望它能看懂图片：报错截图、 UI 稿、图表、笔记照片。在下面的安装向导里找到你的工具——每个受支持的 agent 都有一条命令的安装方式，包括 Claude Code、Codex、Cursor、GitHub Copilot、 VS Code、OpenCode、Trae、Qwen Code 等 22 种。

开始之前（你需要准备什么）

1. Node.js 18 或更新版本 —— 用 node -v 检查；没装的话到 下载。
2. 一个看图服务的账号和它的 API key —— 看图服务就是"替你看图"的网站：云端的 Moonshot、OpenRouter、MiniMax、智谱 GLM、阶跃星辰、OpenCode Zen、SiliconFlow、百炼 DashScope；免费的本地选项（跑在你自己的电脑上）：Ollama、llama.cpp、vLLM、 LM Studio。API key 是这家服务给你的一串密钥（一般在网站"API keys"页面）；安装器只问一次，并且只存在你自己的电脑上。
3. 已经装好你的 AI 工具 —— 下面任意一种。

0.2.x → 0.3.0：变化了什么，如何迁移

0.3.0 起 npm 包改用 scoped 名，并同时发布到 npmjs 与 GitHub Packages 两个源。你的配置、缓存、技能文件、CLI 命令全部不变 —— 只有包引用变了。

| | 0.2.x | 0.3.0 |
| npm 包名 | deepseek-vl-support | @limccn/deepseek-vl-support |
| CLI 命令 | deepseek-vl-support | 不变 |
| 配置 / 缓存 / 标记 | — | 完全兼容，原样保留 |
| 安装来源 | 仅 npmjs（已冻结）| npmjs 和 GitHub Packages |

已经装了 0.2.x？ 一条命令完成迁移 —— 它会把所有托管引用（hook、 MCP 配置、npx 版本钉扎）刷新为 scoped 名，配置与缓存保留不动：

npx @limccn/deepseek-vl-support@latest install --update

然后用 npx @limccn/deepseek-vl-support doctor 验证。

注意：0.2.x 的 deepseek-vl-support 包继续留在 npmjs（冻结 —— 不再更新，留着无害）；两个版本的配置文件互不冲突，新旧安装可以并存。

快速安装向导

在你的项目文件夹里打开终端，运行：

cd 你的项目路径
npx @limccn/deepseek-vl-support@latest install

就这么简单——向导会自动检测你电脑上装了哪些 agent，然后问 7 个简短的问题。
几乎每个问题都有合理的默认值：直接回车即可。 两个值得看一眼的问题：哪些 agent 需要视觉能力（已预选）和用哪家看图服务 + API key（拿不定主意就选最后一项稍后决定，以后随时可以补）。

装完以后，重启你的会话（安装器会打印这个提醒，这是生效的必要步骤）。可选验证：

npx @limccn/deepseek-vl-support@latest doctor # 看到 [OK] 即正常

在同一项目里重复安装？它会问是否保留当前设置——回车即保留。

不想用终端？让你的 agent 自己装。 如果你用的是支持 Agent Plugins 标准的工具（GitHub Copilot、Cursor、Kiro、OpenClaw、Hermes Agent、VS Code、ChatGPT & Codex、 Grok Bot、NanoClaw 以及其他符合该标准的 agent），直接在对话里说：

安装 https://github.com/limccn/deepseek-vl-support 的插件并启用它

安装后，用
npx @limccn/deepseek-vl-support@latest install --target
（或环境变量，见修改设置）配置一次看图服务即可。

仅安装技能（Agent Skills CLI）

只想要 deepseek-vision 技能——不要 hook、不要 MCP server？仓库以标准 Agent Skills 布局（skills/deepseek-vision/）发布，生态 CLI 直接可用：

npx skills add https://github.com/limccn/deepseek-vl-support

技能会装到 .agents/skills/deepseek-vision/（通用路径，含 references/），并为检测到的 agent（如 Claude Code）建符号链接。它与向导安装的是同一个技能。
首次使用前先配置一次看图服务（环境变量，或
npx @limccn/deepseek-vl-support@latest install --target ，见
修改设置）。

每种 agent 的一键安装

下面每条命令与上面的向导等价——只是只针对某一个 agent。找到你的：

Claude Code

1. 安装
npx @limccn/deepseek-vl-support@latest install --target claude

2. 装完 — 重启会话，然后直接读取任意图片：描述会自动送达（手动触发： /vision 图片路径.png）。

Codex

1. 一句话安装 — 在 Codex 会话里说：安装 https://github.com/limccn/deepseek-vl-support 的插件并启用它

2. 或用 npx 安装
npx @limccn/deepseek-vl-support@latest install --target codex

3. 装完 — 重启 Codex，然后让它描述一张图片。

OpenCode

1. 安装
npx @limccn/deepseek-vl-support@latest install --target opencode

2. 装完 — 重启 OpenCode。

Trae

1. 安装
npx @limccn/deepseek-vl-support@latest install --target trae

2. 装完 — 手动导入一次技能：设置 → 规则与技能 → 创建/导入。

Pi Coding Agent

1. 原生安装（推荐） — 一条命令同时装上技能和扩展 pi install npm:@limccn/deepseek-vl-support

2. 或用 npx 安装
npx @limccn/deepseek-vl-support@latest install --target pi

3. 装完 — 重启 Pi。

Oh My Pi

1. 原生安装（推荐） omp install npm:@limccn/deepseek-vl-support

2. 或用 npx 安装
npx @limccn/deepseek-vl-support@latest install --target omp

3. 装完 — 执行 /reload-plugins 激活（无需重启）。

DeepSeek Harness

1. 原生安装（推荐） — 进程内获得工具，不启子进程
dsh plugin --profile web add @limccn/deepseek-vl-support@latest

2. 或用 npx 安装
npx @limccn/deepseek-vl-support@latest install --target dsh

3. 装完 — 重启 dsh web 会话。

Qwen Code

1. 安装
npx @limccn/deepseek-vl-support@latest install --target qwen

2. 装完 — 重启 Qwen Code。

Reasonix

1. 安装
npx @limccn/deepseek-vl-support@latest install --target reasonix

2. 装完 — 重启 Reasonix。

Kilo Code

1. 安装
npx @limccn/deepseek-vl-support@latest install --target kilo

2. 装完 — 重启 Kilo Code。

WorkBuddy（CodeBuddy Code）

1. 安装
npx @limccn/deepseek-vl-support@latest install --target workbuddy

2. 装完 — 重启 WorkBuddy。

Devin

1. 安装
npx @limccn/deepseek-vl-support@latest install --target devin

2. 装完 — 重启 Devin。（Devin 的 CLI 没有官方 npm 包——从下载。）

GitHub Copilot

1. 一句话安装 — 在 Copilot 会话里说：安装 https://github.com/limccn/deepseek-vl-support 的插件并启用它

2. 或用 npx 安装
npx @limccn/deepseek-vl-support@latest install --target copilot

3. 装完 — 用 copilot plugin list 检查。

Cursor

1. 一句话安装 — 在 Cursor 会话里说：安装 https://github.com/limccn/deepseek-vl-support 的插件并启用它

2. 或用 npx 安装
npx @limccn/deepseek-vl-support@latest install --target cursor

3. 装完 — 重载窗口（Developer → Reload Window）。

Kiro

1. 一句话安装 — 在 Kiro 会话里说：安装 https://github.com/limccn/deepseek-vl-support 的插件并启用它

2. 或用 npx 安装
npx @limccn/deepseek-vl-support@latest install --target kiro

3. 装完 — 手动导入一次：Kiro → Powers → 添加自定义 Power → 从文件夹导入 → 选择 ~/.deepseek-vl/plugin。

OpenClaw

1. 一句话安装 — 在 OpenClaw 会话里说：安装 https://github.com/limccn/deepseek-vl-support 的插件并启用它

2. 或用 npx 安装
npx @limccn/deepseek-vl-support@latest install --target openclaw

3. 装完 — 重启网关，用 openclaw plugins list 检查。

Hermes Agent

1. 一句话安装 — 在 Hermes 会话里说：安装 https://github.com/limccn/deepseek-vl-support 的插件并启用它

2. 或用 npx 安装
npx @limccn/deepseek-vl-support@latest install --target hermes

3. 装完 — 用 hermes plugins list 检查。

VS Code

1. 一句话安装 — 在 VS Code 聊天里说：安装 https://github.com/limccn/deepseek-vl-support 的插件并启用它

2. 或用 npx 安装
npx @limccn/deepseek-vl-support@latest install --target vscode

3. 装完 — 重载窗口。

ChatGPT & Codex

1. 一句话安装 — 让 ChatGPT 或 Codex 安装：安装 https://github.com/limccn/deepseek-vl-support 的插件并启用它

2. 或用 npx 安装
npx @limccn/deepseek-vl-support@latest install --target chatgpt-codex

3. 装完 — 新开一个 Codex 线程（或 ChatGPT 会话）。

Grok Bot

1. 一句话安装 — 在 Grok 会话里说：安装 https://github.com/limccn/deepseek-vl-support 的插件并启用它

2. 或用 npx 安装
npx @limccn/deepseek-vl-support@latest install --target grok

3. 装完 — 在插件页按 r（刷新）或新开会话。

NanoClaw

1. 一句话安装 — 在 NanoClaw 会话里说：安装 https://github.com/limccn/deepseek-vl-support 的插件并启用它

2. 或用 npx 安装
npx @limccn/deepseek-vl-support@latest install --target nanoclaw

3. 装完 — 按打印的指引运行 ncl wirings create。

其他类型Agent（适配Agent Plugins 开放标准）

1. 一句话安装 — 在聊天会话里说：安装 https://github.com/limccn/deepseek-vl-support 的插件并启用它

2. 或用 npx 安装
npx @limccn/deepseek-vl-support@latest install --target other

混合安装（一次装多个Agent）

任意组合都可以，逗号分隔：

npx @limccn/deepseek-vl-support@latest install --target claude,copilot

或一次装齐全部 10 个插件客户端：

npx @limccn/deepseek-vl-support@latest install --target copilot,cursor,kiro,openclaw,hermes,vscode,chatgpt-codex,grok,nanoclaw,other

所有受支持的 agent 一览：

| Agent | --target |
| Claude Code | claude |
| Codex | codex |
| OpenCode | opencode |
| Trae | trae |
| Pi Coding Agent | pi |
| Oh My Pi | omp |
| DeepSeek Harness | dsh |
| Qwen Code | qwen |
| Reasonix | reasonix |
| Kilo Code | kilo |
| WorkBuddy（CodeBuddy Code） | workbuddy |
| Devin | devin |
| GitHub Copilot | copilot |
| Cursor | cursor |
| Kiro | kiro |
| OpenClaw | openclaw |
| Hermes Agent | hermes |
| VS Code | vscode |
| ChatGPT & Codex | chatgpt-codex |
| Grok Bot | grok |
| NanoClaw | nanoclaw |
| 其他 agent | other |

试一试

最快的验证——直接在终端描述一张图片：

npx @limccn/deepseek-vl-support@latest describe 图片路径.png

返回一段像样的文字描述 → 一切就绪。之后照常在你的 agent 里读图片，描述会自动送达。

选择看图服务

安装器会把上面的服务列成菜单让你选——手动配置时才需要记住这些地址：

| 服务 | base URL | 示例模型 |
| Moonshot | https://api.moonshot.cn/v1 | moonshot-v1-32k-vision-preview |
| OpenRouter | https://openrouter.ai/api/v1 | qwen/qwen2.5-vl-72b-instruct |
| MiniMax | https://api.minimaxi.com/v1 | MiniMax-VL-01 |
| 智谱 GLM | https://open.bigmodel.cn/api/paas/v4 | glm-4v-flash |
| 阶跃星辰 | https://api.stepfun.com/v1 | step-1o-turbo-vision |
| OpenCode Zen | https://opencode.ai/zen/v1 | mimo-v2.5-free |
| SiliconFlow | https://api.siliconflow.cn/v1 | Qwen/Qwen2.5-VL-72B-Instruct |
| 百炼 DashScope | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen-vl-max |
| Ollama（本地） | http://localhost:11434/v1 | qwen2.5vl:7b（先运行 ollama pull qwen2.5vl:7b） |
| llama.cpp（本地） | http://localhost:8080/v1 | llava（llama-server -m llava.gguf） |
| vLLM（本地） | http://localhost:8000/v1 | deepseek-ai/deepseek-vl2 |
| LM Studio（本地） | http://localhost:1234/v1 | qwen2.5-vl-7b-instruct |

常用命令

| 想做什么 | 命令 |
| 安装 | npx @limccn/deepseek-vl-support@latest install |
| 健康检查 | npx @limccn/deepseek-vl-support@latest doctor |
| 立刻描述一张图片 | npx @limccn/deepseek-vl-support@latest describe picture.png |
| 查看当前设置 | npx @limccn/deepseek-vl-support@latest config get |
| 修改设置 | npx @limccn/deepseek-vl-support@latest config set maxBytes 5242880 |
| 卸载 | npx @limccn/deepseek-vl-support@latest uninstall |

修改设置

你的回答保存在项目文件夹里的 .deepseek-vl/config.json——通常完全不用碰它。两个值得知道的设置：

| 设置 | 含义 | 默认值 |
| maxBytes | 超过这个大小的图片跳过（省钱省时间） | 10485760（10 MB） |
| timeoutMs | 等一次描述的最长时间 | 120000（2 分钟） |

示例——跳过 5 MB 以上的图片：

npx @limccn/deepseek-vl-support@latest config set maxBytes 5242880

同一张图片描述两次是免费的：结果会缓存在你电脑上（上限 64 MB）。图片改动了就会重新描述。所有设置也都能用环境变量（VISION_MODEL、VISION_BASE_URL……）设置——完整参考见 CLAUDE.md。

常见问题

| 现象 | 怎么办 |
| 模型还是不会描述图片 | 重启会话（安装后必须），然后运行 … doctor 看是否有 [OK]。 |
| doctor 提示未配置模型 | 安装时选了稍后决定。现在补：config set model （非默认服务再加 config set baseUrl ）。 |
| doctor 显示 "unreachable" / 没有 [OK] | 服务地址或密钥不对——检查 base URL 是否以 /v1 结尾、API key 是否正确。 |
| 提示"图片太大" | 压缩或裁剪图片（如 5 MB 以内、长边约 2000 像素），或用 config set maxBytes … 提高上限。 |
| 描述很慢 | 调低上限，或换更快的服务（见上表）。 |
| 粘贴（Ctrl+V）的图片不生效 | 粘贴的图片不经过读取通道——先把图片存成文件再读（或使用 /vision / describe_image）。 |

更多边界情况（Windows 编码、Codex 特有坑、推理模型注意事项）见 CLAUDE.md 和 README.md。

致谢

本项目受 pi-deepseek-vision 启发——感谢 psychobarge 的开源工作。

参与贡献

欢迎贡献——如何报问题、搭开发环境，见 CONTRIBUTING.md。

开源许可

MIT