vision-relay

🖼️ Vision Relay — 让 DeepSeek 也能"看图"和"画图"

Vision Relay(视觉中继) 是一个 Agent Skills 格式的技能 + 零依赖本地桥接服务,解决一个核心问题:

DeepSeek V4 等文本模型无法直接处理图片——既不能"看到"用户发来的图,也不能"画出"用户要的图。

它通过一条本地 HTTP 桥接服务,自动把识图/生图请求转发给配置好的外部 API,再把结果带回对话:

• 识图 → 调用视觉理解模型(默认:mimo 官网 mimo-v2.5)
• 文生图 → 调用图像生成模型(默认:阿里 qwen-image-3.0-pro)
• 图生图 → 带参考图重绘(基于参考图换风格/改内容)

DeepSeek 全程只需要处理文字,不需要有视觉能力。

你发图片/要求识图           你要求画图/改图
      │                          │
      ▼                          ▼
DeepSeek V4(文本模型)── 路由判断 ─┐
      │                          │
      │ POST /api/analyze        │ POST /api/generate(可带参考图)
      ▼                          ▼
本地桥接服务 bridge.js(127.0.0.1:8659,零依赖 Node 脚本)
      │                          │
      ▼                          ▼
mimo-v2.5 识图             qwen-image-3.0-pro 生图
(可换任意视觉模型)          (可换任意生图服务商)
      │                          │
      └──── 文字结果 / 图片文件 ──┘
      ▼
DeepSeek 基于结果回答你

---

✨ 功能特性

特性	说明
零依赖	纯 Node.js 内置模块(http/fetch/fs),Node ≥ 18 即可运行,无需 npm install
网页配置界面	浏览器打开 http://127.0.0.1:8659 即可配置,无需改文件
识图/生图独立配置	两个 API 完全独立,互不影响
支持图生图	传参考图即可重绘/换风格(阿里 qwen-image 系列)
多服务商兼容	OpenAI 兼容服务商 + 阿里 DashScope 原生端点自动识别
未配置不调用	未配置生图时,收到生图请求会如实告知,绝不调用生图模型
仅本机监听	只绑定 127.0.0.1,不对外网开放
图片本地保存	生成的图片存到 output/,按时间戳命名不覆盖

---

📁 目录结构

vision-relay/
├── SKILL.md              技能定义(触发条件 + 路由逻辑 + 工作流)
├── README.md             本文档(使用教程)
├── config.example.json   配置示例(可复制为 config.json)
├── config.json           运行时生成:你的 API 配置(含密钥,已 gitignore,勿提交)
├── .gitignore            排除 config.json / output/
├── start-hidden.ps1      隐藏启动脚本(开机自启用,无窗口)
├── output/               运行时生成:生图结果保存目录
├── 启动桥接服务.bat       Windows 一键启动(启动服务 + 打开配置网页)
└── scripts/
    ├── bridge.js         零依赖 Node 桥接服务(核心)
    └── config.html       网页配置界面(由 bridge.js 提供)

---

⚙️ 启用与关闭(完整方法)

核心概念:本技能"启用"分两层——① 技能本体(告诉 DeepSeek 何时触发)和 ② 桥接服务(真正干活的后台进程)。两层都要就位才能用。

一、启用 Skill

1️⃣ 安装技能本体(一次)

兼容范围:本技能是标准 Agent Skills 格式(SKILL.md + name/description 元数据),凡是支持该规范的工具 均可使用——ZCode、Claude Code、Codex CLI、Cursor 等。桥接服务是独立的本地 Node 服务,与任何工具无关。

把整个 vision-relay 文件夹放到你所用工具能发现技能的位置:

位置	适用工具	作用范围
~/.agents/skills/vision-relay/	跨工具通用(Claude Code / Codex / Cursor / ZCode 均会扫描)	用户级,所有项目生效(推荐)
~/.zcode/skills/vision-relay/	ZCode(优先于 .agents)	用户级,所有项目生效
<项目>/.zcode/skills/vision-relay/	ZCode	仅该项目生效

技能不需要手动开开关。工具每次会话自动加载技能描述,你说"看看这张图/画一只猫"时自动触发。

2️⃣ 启动桥接服务(每次使用前)

• 手动:双击 启动桥接服务.bat,或运行 node scripts/bridge.js;

• 开机自启(推荐):把下面两个文件放到 Windows 启动文件夹(Win+R 输入 shell:startup 回车打开):

  VisionRelay-AutoStart.bat    ← 启动入口(检查端口 → 调 PowerShell 隐藏启动)
  

  脚本内容示例(会自动跳过"端口已被占用"的情况,避免重复启动):

  @echo off
  netstat -ano | findstr ":8659" | findstr "LISTENING" >nul 2>&1
  if not errorlevel 1 exit /b 0
  cd /d "%~dp0"
  powershell.exe -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "start-hidden.ps1"
  

  自启后 node.exe 以完全隐藏、无窗口方式运行(窗口句柄 = 0,任务栏/任务管理器里看不到窗口)。

3️⃣ 验证是否就绪

curl http://127.0.0.1:8659/api/health

返回 "running": true、"configured": true 即为就绪。也可以在支持斜杠命令的工具里输入 /vision-relay 强制加载本技能(如 ZCode)。

二、关闭 Skill

按需要关闭的程度,分三档:

① 仅停止服务(临时,不卸载)

方法	操作
关窗口	关闭运行服务的命令行窗口
任务管理器	结束 node.exe 进程
命令行	taskkill /F /IM node.exe(⚠️ 会杀掉所有 node 进程)

服务停了但技能仍在,DeepSeek 会提示你先启动服务,不会误报成功。

② 取消开机自启(保留技能,开机不再自动运行)

删除启动文件夹里的 VisionRelay-AutoStart.bat 即可。以后想用时手动双击 启动桥接服务.bat。

③ 彻底卸载(连技能一起移除)

方法	操作
删除技能目录	删掉 ~/.agents/skills/vision-relay/ 或 ~/.zcode/skills/vision-relay/(按你的安装位置)
工具设置	在所用工具(如 ZCode)的 Settings → Skills 中找到 vision-relay 禁用
仅禁用触发	把技能目录移出上述发现目录(如改名或移到别处),保留文件

三、常见状态速查

想做什么	要动哪层
让 DeepSeek 收到图片能识图	技能本体(已装)+ 服务(要开)
画图/改图	技能本体 + 服务 + 生图 API 已配置
只是暂时不用	关服务即可,技能留着
不想开机自动跑	删启动文件夹的 bat
彻底不想要了	删技能目录

---

🚀 快速开始(5 步)

第 1 步:安装技能

本技能是标准 Agent Skills 格式,适用于所有支持该规范的工具:ZCode、Claude Code、Codex、Cursor 等。 放在哪个目录取决于你用的工具(见上方「启用与关闭」章节的兼容表)。常见做法:

把整个 vision-relay 文件夹放到你所用工具能发现技能的位置(任选其一):

位置	适用工具	作用范围
~/.agents/skills/vision-relay/	跨工具通用(Claude/Codex/Cursor/ZCode)	用户级,所有项目生效(推荐)
~/.zcode/skills/vision-relay/	ZCode(优先于 .agents)	用户级,所有项目生效
<项目>/.zcode/skills/vision-relay/	ZCode	仅该项目生效,可随仓库共享

同一技能名在多个位置时,工具按各自发现顺序加载,靠前的位置优先,冲突时只加载优先的那份。

第 2 步:启动桥接服务

Windows:双击 启动桥接服务.bat(自动启动并打开配置网页,关闭窗口即停止)。

命令行(任意系统):

cd vision-relay
node scripts/bridge.js

看到 配置网页: http://127.0.0.1:8659 即启动成功。改端口:

VISION_RELAY_PORT=9000 node scripts/bridge.js   # Windows CMD: set VISION_RELAY_PORT=9000

⚠️ 服务需要保持运行。每次使用前确认它开着——这就是"拒绝连接"的原因。

第 3 步:配置识图 API(网页)

浏览器打开 **http://127.0.0.1:8659**,在「视觉模型 API 配置(识图)」填写:

字段	说明	示例
Base URL	OpenAI 兼容地址	https://api.xiaomimimo.com/v1
API Key	服务商密钥	sk-...
模型名	支持视觉的模型	mimo-v2.5、gpt-4o、qwen-vl-max
max_tokens / temperature	可选	1024 / 0.3

点 保存识图配置 → 测试连接 → 在「识图测试」选一张本地图片验证完整链路。

第 4 步:配置生图 API(网页)

在「生图 API 配置(可选)」:

1. 勾选 启用生图;
2. 填写 Base URL / API Key / 模型名、选择默认尺寸;
3. 点 保存生图配置,在「生图测试」输入一句画面描述验证。

生图服务商示例:阿里 DashScope https://dashscope.aliyuncs.com/compatible-mode/v1 + qwen-image-3.0-pro(自动走原生生图端点,支持图生图);智谱 CogView、硅基流动 FLUX、OpenAI gpt-image-1 等走标准 OpenAI 兼容路径。

第 5 步:开始使用

对着 DeepSeek 正常说话即可,技能自动触发:

• 识图:"帮我看看 C:\Users\me\Desktop\photo.png 里有什么" / "这张图是什么?https://example.com/a.png"
• 文生图:"画一只戴帽子的橘猫,卡通风格"
• 图生图:"把这张图改成油画风格:D:\pic\cat.png"

---

📖 使用教程(详解)

路由逻辑(技能如何决定调谁)

你的需求	调用接口	后端
仅识别图片(看图/描述/图里是什么/OCR)	POST /api/analyze	识图配置(mimo-v2.5)
文生图(画一张.../根据文字生成图片)	POST /api/generate(不带 image)	生图配置(qwen-image-3.0-pro)
图生图(把这张图改成.../参考图重绘)	POST /api/generate(带 image 参考图)	生图配置(qwen-image-3.0-pro)

判断规则:

• 除非用户明确说明要生成/创建一张新图片(画/生成/制作/绘制...),否则一律不得调用生图接口; 用户发图片来"看看/识别/分析/这图是什么",即使语气像在"改图",只要没明确说"生成/画/改成",都优先走识图;
• 只给了图片、要求"看看/识别/描述/里面是什么" → 识图;
• 给了画面描述、要求"画/生成/制作一张图"(无参考图)→ 文生图;
• 给了一张图并明确要求生成新版本("改成/基于它/参考它/换风格/重绘")→ 图生图;
• 拿不准时宁可走识图或直接询问用户,也不要擅自调用生图模型;
• 不要用识图接口"生成"图片,也不要用生图接口"识别"图片。

识图

1. 确认服务运行、配置完成(GET /api/health 的 configured: true);
2. 提供图片,三种形式均可:
   • 本地路径:C:\Users\me\Desktop\photo.png(绝对路径,或相对当前目录);
   • URL:https://example.com/a.png(自动下载转 base64);
   • data URL:data:image/png;base64,...;
3. 技能调用识图接口,返回视觉模型的文字描述,并基于它回答你。

多张图片会多次调用,分别取回结果再综合回答。

文生图

1. 确认 GET /api/health 的 genConfigured: true(否则如实告知未配置,不调用);
2. 说清楚画面内容,可加风格词(卡通/写实/赛博朋克/水墨...)和比例要求;
3. 生成的图片保存到 output/ 目录(时间戳命名),技能会告诉你文件路径,可打开查看。

图生图

把参考图路径和修改要求一起说出来,例如:

"把 C:\Users\me\Desktop\cat.png 改成梵高星空风格"

技能会把参考图转为 data URL 传给生图模型重绘。参考图支持本地路径/URL/data URL。

图生图能力取决于所配生图服务商:阿里百炼(qwen-image 系列)走原生多模态端点; 其他 OpenAI 兼容服务商(如智谱、OpenAI 等)走 /images/edits 图生图端点, 若服务商不支持会返回错误信息。

直接调用 API(给开发者)

桥接服务提供以下 HTTP 接口(可用 curl / Postman 等直接调用):

方法	路径	说明
GET	/	网页配置界面
GET	/output/<file>	已生成图片的静态访问(网页预览)
GET	/api/health	服务状态 + 识图/生图是否已配置
GET	/api/config	当前配置(Key 已打码)
POST	/api/config	保存配置(识图字段 + gen 生图块)
POST	/api/test	识图配置文本连通性测试
POST	/api/analyze	识图:{"image": "...", "prompt": "..."}
POST	/api/generate	生图:{"prompt": "...", "size": "1024x1024", "n": 1, "image": "可选参考图"}

识图示例:

curl -s http://127.0.0.1:8659/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"image": "C:/Users/me/Desktop/photo.png", "prompt": "描述这张图片的内容"}'

生图示例(文生图):

curl -s http://127.0.0.1:8659/api/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "一只戴帽子的橘猫,卡通风格", "size": "1024x1024"}'

生图示例(图生图):

curl -s http://127.0.0.1:8659/api/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "改成油画风格", "image": "C:/Users/me/Desktop/cat.png"}'

配置示例(也可以让助手直接写配置,不必开网页):

# 识图配置(apiKey 传空串 = 保留已有 Key)
curl -s http://127.0.0.1:8659/api/config \
  -H "Content-Type: application/json" \
  -d '{"baseUrl": "https://api.xiaomimimo.com/v1", "apiKey": "sk-xxx", "model": "mimo-v2.5"}'

# 生图配置
curl -s http://127.0.0.1:8659/api/config \
  -H "Content-Type: application/json" \
  -d '{"gen": {"enabled": true, "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", "apiKey": "sk-xxx", "model": "qwen-image-3.0-pro", "size": "1024x1024"}}'

---

🔌 支持的模型与服务商

识图(OpenAI 兼容,填各自的 v1 地址):

服务商	Base URL	模型示例
MiMo(小米)	https://api.xiaomimimo.com/v1	mimo-v2.5、mimo-v2.5-pro
OpenAI	https://api.openai.com/v1	gpt-4o
通义千问	https://dashscope.aliyuncs.com/compatible-mode/v1	qwen-vl-max
智谱	https://open.bigmodel.cn/api/paas/v4	glm-4v-plus、glm-4v-flash
Kimi	https://api.moonshot.cn/v1	moonshot-v1-8k-vision-preview
硅基流动	https://api.siliconflow.cn/v1	支持视觉的开源模型

生图:

服务商	Base URL	模型示例	图生图
阿里百炼	https://dashscope.aliyuncs.com/compatible-mode/v1	qwen-image-3.0-pro	✅(原生多模态端点)
智谱	https://open.bigmodel.cn/api/paas/v4	cogview-3-flash	视模型而定(/images/edits)
OpenAI	https://api.openai.com/v1	gpt-image-1	✅(/images/edits)
硅基流动	https://api.siliconflow.cn/v1	black-forest-labs/FLUX.1-schnell	视模型而定

图生图参考图支持三种路径:阿里百炼走原生多模态端点;其他 OpenAI 兼容服务商走 /images/edits; 都不支持时会返回服务商错误信息。

注意:OpenCode GO 套餐、MiMo 官方等"全模态理解"套餐没有生图模型(实测 mimo-v2.5 系列均拒绝生图),生图需配支持生图的服务商。

---

⚙️ config.json 说明

运行时生成在技能目录,结构如下(密钥已被本仓库 .gitignore 排除,切勿提交):

{
  "baseUrl": "https://api.xiaomimimo.com/v1",      // 识图 API 地址
  "apiKey": "sk-xxx",                               // 识图密钥
  "model": "mimo-v2.5",                             // 识图模型
  "maxTokens": 1024,
  "temperature": 0.3,
  "gen": {                                          // 生图配置(独立)
    "enabled": false,                               // false = 未配置,不调用生图
    "baseUrl": "",                                  // 生图 API 地址
    "apiKey": "",
    "model": "",
    "size": "1024x1024"
  }
}

网页配置和 POST /api/config 都会写入此文件。正在运行的 bridge.js 读写的是它所在目录的 config.json——多副本部署时注意改对那份。

---

🛠️ 故障排查(FAQ)

现象	原因与处理
网页打不开/拒绝连接	服务没在运行。启动:node scripts/bridge.js 或双击 bat;确认端口没被占用
测试连接失败	baseUrl 是否以 /v1 结尾;Key 是否有效;模型名是否拼对
识图返回空内容	模型不支持视觉输入,换成支持视觉的模型(如 mimo-v2.5)
图片找不到	给完整绝对路径;相对路径会按"当前目录 → 技能目录"查找
大图超时	压缩到几 MB 内再试
生图提示"未配置生图 API"	打开网页启用生图并填全 Base URL / API Key / 模型名
生图 404 不支持端点	该服务商没有 OpenAI 兼容生图路径;阿里 DashScope 会自动走原生端点,无需手改
图生图报"不支持参考图"	服务商不支持图生图端点,换支持参考图的服务商/模型(如 qwen-image、gpt-image 系列)
Cannot convert argument to a ByteString	API Key 被误填成中文/URL/错误消息,清掉重填

---

🔒 安全说明

• 桥接服务只绑定 127.0.0.1,不对外网开放;
• config.json 明文保存 API 密钥,仅存本机,已加入 .gitignore;不要把配置文件提交到公共仓库;
• 图片只从你的电脑发往你配置的 API 服务商,桥接服务本身不记录任何内容;
• 生图结果保存于 output/,按需清理。

---

📄 许可证

MIT License — 可自由使用、修改、分发。