视觉工坊 LR611415/visionforge

VisionForge

给 DeepSeek Harness 装上「眼睛」和「画笔」：视觉理解 + 图片生成 + 图片编辑，一个插件搞定。

🌐 English | 中文

VisionForge 基于开源视觉插件 liustack/modlens（MIT）深度改造而来：接入千问（Qwen）引擎、新增图片生成与编辑能力、内置图形化设置卡片、支持官方 / 插件双解析优先级调度。改造点全部保留原插件的轻量架构——在 DSH 上只是一个插件目录，卸载即删除，不修改任何 DSH 官方组件，不影响原生功能。

适配环境：DSH Desktop v2.0.17 / DSH harness 0.2.0-rc.2（2026-10 实测）。DSH 大版本更新可能改变插件接口，升级后请重新验证。

桌面端说明：插件只与 harness 版本相关——官方桌面端与第三方桌面端只要 harness 版本相同，对插件功能无实质差异（工具注册、图片预览 / 放大 / 下载等行为一致）；但推荐使用官方 DSH Desktop，第三方桌面端不受上游官方支持。

插件版本 × DSH harness 对照

| 插件版本 | 发布日 | 适配 DSH harness | 适配 DSH Desktop | 说明 |
| 0.1.8 及更早 | ≤ 2026-09-27 | harness 0.1.x 早期 | — | 基于 liustack/modlens 3.26.3 的分叉/桥接版（品牌化 + 初步集成） |
| 0.1.9 | 2026-09-28 | harness 0.1.7-rc.1 | — | 连接层重写第一版（约 90% 自研，保留上游致谢），功能基线 |
| 0.1.10 | 2026-09-30 | harness 0.1.7 系列（-rc.1 / -rc.2） | v2.0.14（2026-09 实测） | 0.1.9 增强版：内容合规文档、设置卡片增强、上架准备 |
| 0.2.1（当前） | 2026-10-02 | harness 0.2.0-rc.2（2026-10 实测）；兼容 0.1.7 系列 | v2.0.17（2026-10 实测） | 0.1.10 增强版：提示词 100 字门槛 + 六维检测强化 + 细节写作指南 + 多图并行不超时等 5-bug 修复 |

安装层面的兼容范围（npm peerDependencies）：@deepseek-ai/dsh-client-ui-primitives 允许 >=0.0.1-rc.1 <0.1.0 || >=0.1.0-rc.1 <0.2.0-0 || >=0.2.0-0 <0.3.0-0（即 harness 0.1.x 与 0.2.x 系列均可安装），上表为实测版本。

功能一览

| 能力 | 说明 |
| 🖼️ 粘贴即读 | 官方视觉模型下图片粘贴进输入框原生预览；纯文本模型下由插件接管转成本地路径并解析，两种模式都无需手动复制路径 |
| 🔭 多提供商视觉引擎 | Qwen / OpenAI（任意 OpenAI 兼容端点）/ Anthropic / Gemini / Antigravity / Claude / Kimi，自动组成故障转移链，一个密钥失败自动轮换下一个 |
| 🎨 图片生成 | visionforge_generate_image：文字描述生成图片（Qwen-Image / GLM-Image），支持 1–6 张、多种尺寸 |
| ✏️ 图片编辑 | visionforge_edit_image：换装、换背景、多图融合、改表情（Qwen-Image edit），支持 1–3 张输入、批量输出变体（每张不同，绝不重复） |
| 🔍 图片放大 | 对话内生成的图片以90px 缩略图呈现，点击图片本体直接用电脑系统图片查看器打开缓存位置的原图放大——不弹 DSH 侧边栏 |
| ⬇️ 一键下载 | 点击「保存图片 N」把缓存图复制到 D 盘根目录（无 D 盘则用户目录 VisionForge 文件夹），并在资源管理器中自动选中刚保存的文件；同样不经过侧边栏 |
| ⚖️ 解析优先级 | 官方优先：官方视觉模型能看图时先解析，不行才走插件；插件优先：始终先用你配置的提供商密钥，全部失败才试官方 |
| ⚙️ 设置卡片 | DSH 设置页内置「VisionForge 配置」卡片，引擎 / 密钥 / 接口 / 模型 / 优先级全部由你自己填写；密钥保存后显示 •••••• 掩码，不写死在代码里；改动内容时保存按钮高亮，保存成功后恢复灰色 |
| 🧩 引擎翻译器（自定义引擎） | 内置引擎之外的任意厂商（Google Gemini、Imagen、OpenAI 兼容网关等）无需改代码即可接入：设置卡片「添加 / 编辑自定义引擎」或 visionforge config add-engine。名称自动规范化并带护栏，接口地址自动识别协议族，读图 / 生图 / 编辑按模型级能力声明 |
| 🎨 画质与提示词增强 | 未指定画质时：支持 2K 的引擎（Qwen / Imagen / Gemini）默认 2K（2560×1440），不支持 2K 的引擎（GLM）默认其最大分辨率（2048×2048）；支持 4K / 2.5K / 2K / 1080P 分辨率词表，超引擎上限自动降级并说明。图生图自动追加保护性约束（保持面部特征、肢体自然、不加水印），用户明确改某项时自动跳过对应约束，可关 |
| 🗂️ 统一目录 | 生成图缓存、粘贴原图缓存、下载目录全部收敛固定，不散落在系统临时目录 |
| 🧹 缓存清理 | 生成图与粘贴缓存超过 3 天自动过期清理（启动时执行）；已下载的永久副本不受影响 |
| 🔗 本地回环服务 | 预览 / 放大 / 下载走本机固定候选端口（45999/46999/47999/48999）loopback 路由，不依赖提供商的临时 OSS 链接（24h 失效），重启 DSH 后旧消息的图仍可预览、放大、下载 |

安装

方式一：npm 安装（推荐）

npx -y @deepseek-ai/dsh plugin --profile desktop add @lr611/visionforge

安装后进入 DSH 设置 → 内置插件 → VisionForge 配置 卡片填写引擎与密钥，完全重启 DSH Desktop 生效。
若本机已安装旧版 @liustack/modlens，请先移除再安装本包，避免两套插件同时注册同名工具：
npx -y @deepseek-ai/dsh plugin --profile desktop remove @liustack/modlens

方式二：把安装交给你的 AI（不熟悉命令行的用户）

把下面这句话发给你的 AI 助手（DSH 内的助手，或任何能访问本机终端 / 文件的 AI）：

按 https://github.com/LR611415/visionforge 的 INSTALL.md 安装并配置 visionforge 插件，完成后运行体检（doctor）并把结果告诉我。

AI 会按 INSTALL.md 的步骤执行：npm 一键安装（或本地复制兜底）→ 配置引擎（可跳过，跳过则随时可去设置卡片补填）→ doctor 体检 → 报告结果。支持 Skill 的 AI 环境可直接加载项目内 skills/visionforge/SKILL.md。

方式三：本地源码复制兜底（离线 / 未发布场景）

见仓库 INSTALL.md 的 Path B：把 dsh/、src/、skills/、cordis.patch.yml、package.json 复制到 DSH 插件安装目录并 npm install。

历史版本：下载与安装

当前版本为 0.2.1。需要回到旧版本（如 v0.1.10 适配 harness 0.1.7 系列）时，两种方式任选：

A. 免下载压缩包（推荐）——DSH CLI 直接指定版本安装

1. 先确认 profile 名（一般为 desktop）： Get-ChildItem "$env:USERPROFILE\.dsh\profiles" -Directory | Select-Object -ExpandProperty Name

2. 指定版本安装（<profile> 换成上一步查到的名字）：
npx -y @deepseek-ai/dsh plugin --profile desktop add @lr611/visionforge@0.1.10
npx -y @deepseek-ai/dsh plugin --profile desktop add @lr611/visionforge@0.1.9
npx -y @deepseek-ai/dsh plugin --profile desktop add @lr611/visionforge@0.1.8

3. 完全退出并重启 DSH。切回最新版：add @lr611/visionforge@0.2.1。

B. 压缩包手动安装（离线 / 想要源码快照）

1. 下载源码压缩包（GitHub Releases → Assets，或直接链接，v0.1.9 / v0.1.8 同理换 tag 名）： https://github.com/LR611415/visionforge/archive/refs/tags/v0.1.10.zip

2. 解压得到 visionforge-0.1.10/ 文件夹
3. 若插件未在 DSH 声明过，先执行一次 npx -y @deepseek-ai/dsh plugin --profile desktop add @lr611/visionforge
4. 把解压文件夹里面的内容整体覆盖到（先备份原目录）： %USERPROFILE%\.dsh\profiles\desktop\node_modules\@lr611\visionforge\
5. 完全退出并重启 DSH

⚠️ 历史版本必须与 harness 匹配：见上文「插件版本 × DSH harness 对照」表。在 harness 0.2.0-rc.2 上直接装 v0.1.10 会因 peerDependencies 不兼容而加载失败——跑历史版本前，先把桌面端 / harness 退回对照表对应版本。

快速开始

1. 配引擎：DSH 设置 → 内置插件 → VisionForge 配置 → 选择引擎（如 Qwen）→ 填入 API 密钥、接口地址、模型 → 保存（密钥框显示 •••••• 即保存成功）。
2. 看图：把图片复制 / 粘贴进输入框——官方视觉模型下显示原生预览，直接发送即可解析；插件优先时会转路径交给你的提供商密钥解析。
3. 生图：对话里说"生成一张田间的稻草人"，模型调用 visionforge_generate_image，对话内直接出现 90px 缩略图，点击图片用系统图片查看器放大，点「保存图片 N」下载到 D 盘根目录。
4. 改图：粘贴 1–3 张图，说"把女生的衣服换成白色 JK 裙"，模型调用 visionforge_edit_image 完成编辑，同样带预览与下载。

自定义引擎（引擎翻译器）

内置引擎之外，你可以添加任意厂商引擎（如 Google Gemini、Imagen、自定义 OpenAI 兼容网关），无需改代码即可读图、生图、编辑。图片怎么传给引擎由「协议族」自动决定——你不需要知道 image_url 与 inline_data 的区别。

在设置卡片添加

1. DSH 设置 → VisionForge 配置卡片 → 底部「+ 添加 / 编辑自定义引擎」。
2. 填：引擎名称（自动规范为小写 a-z0-9._-，与内置引擎重名会被拒绝，拼写相近会提示）、显示名（可选）、接口地址（粘贴后自动按域名预填读图协议族）、读图协议族、生图协议族、API 密钥（可留空稍后补）、视觉模型、生图模型（填了才启用生图）。
3. 保存后引擎会出现在顶部引擎下拉中，可设为默认引擎参与解析。

命令行添加

读图 + 生图（Google Gemini 示例）
visionforge config add-engine google \
--base-url https://generativelanguage.googleapis.com \
--display-name "Google Gemini" \
--read-family gemini --gen-family chat-native \
--model gemini-3.1 --gen-model imagen-4.0

visionforge config list-custom # 查看已添加的自定义引擎 visionforge config remove-engine google # 删除 visionforge config test google # 用 1×1 占位图实测连通性（花极少配额）

密钥与模型可稍后在设置卡片或 visionforge config set custom.<name>.apiKey 补填。

协议族（决定图片上传格式）

| 协议族 | 图片格式 | 适用 |
| openai-compatible（默认兜底） | image_url + data URI | OpenAI 兼容网关、千问、GLM、月之暗面、DeepSeek 等约 90% 厂商 |
| anthropic | image + source base64 块 | Anthropic / Claude 兼容端点 |
| gemini | inline_data（远程图自动拉回 base64） | Google Gemini |
| raw-base64 | 私有端点直接放 base64 字段 | 自定义私有网关 |

生图协议族：dashscope-image（Qwen-Image 原生）、openai-image（/images/generations）、chat-native（Gemini 多模态生成）、google-imagen（Imagen :predict / :editImage）。尺寸格式按协议族自动转换（如 Qwen 要 10241024、OpenAI 要 1024x1024、Imagen 用比例 1:1），不支持的能力会明确报错而非静默。

名称护栏

- 名称自动规范化（大小写 / 空格 / 连字符 / 下划线统一）；
- 与内置引擎或已有自定义引擎重名 → 拒绝并说明；
- 与内置引擎拼写相近（编辑距离 ≤ 2，如 qwenx → qwen）→ 提示「你是不是指内置引擎」，不静默改名；
- 接口地址域名可识别协议族并自动预填。

设置卡片配置项

| 字段 | 说明 |
| 引擎 | Qwen / OpenAI / Anthropic / Gemini / Antigravity / Claude / Kimi，或自动（按已配置的密钥自动组成故障转移链，谁可用谁解析） |
| API 密钥 | 由你自己填写，支持英文逗号分隔多 key，鉴权 / 限流 / 配额失败自动轮换；保存后显示 •••••• 掩码，可点选删除 |
| 接口地址 | 该引擎的 Base URL（如千问 AI 平台 OpenAI 兼容端点；Antigravity / Claude / Kimi 为 CLI 引擎无需地址） |
| 模型 | 视觉读图模型（如 qwen3.8-max）；切换引擎后下拉列表自动切换为对应引擎的常用模型，也可自定义 |
| 图生图提示词自动增强 | 开启（推荐）：简短编辑指令自动追加保护性约束（保持面部特征、肢体自然、不加水印），你明确要求改某项时自动跳过对应约束；关闭则原样发送 |
| 解析优先级 | 官方优先（默认）或 插件优先 |
| 图片输出目录 | 生成图片的缓存目录，默认 D:\VisionForge\out |
| 粘贴转路径 | 智能接管开关（纯文本模型下把粘贴图转成本地路径供插件读取） |

模型候选下拉只列视觉读图模型；生成模型（如 qwen-image-3.0）由生图 / 编辑命令自动调用，不需要在这里选。
引擎为 CLI 类（Antigravity / Claude / Kimi）时，密钥与接口地址无需填写，保存按钮会根据实际改动亮起 / 熄灭。

生成图交互说明

- 画质（默认与分辨率词表）：未指定画质时——支持 2K 的引擎（Qwen / Imagen / Gemini）默认 2560×1440（2K）；不支持 2K 的引擎（GLM 等边长上限 2048）默认该引擎最大分辨率（2048×2048）。支持口头分辨率词表：4K（3840×2160）、2.5K / 2K（2560×1440）、1080P / 高清（1920×1080）、超清。真 4K 超所有引擎原生上限：Qwen 按总像素上限降为约 2.7K（2728×1536），GLM 按边长上限把 2K 降为 2048×1152，并在结果里给出 sizeNote 说明（不静默降级、不假装 4K）。
- 降级提示（sizeNote）：用户明确要求的分辨率引擎不支持时，结果会说明「该引擎不支持需求分辨率 + 最终生成的分辨率 + 支持该分辨率的引擎建议」（如 2K 建议 Qwen / Imagen 4 / Gemini；4K 说明常见引擎暂无原生支持、需外部超分）。
- 图生图提示词自动增强：edit 默认开启——简短指令自动追加保护性约束（严格保持面部特征/五官/发型/身材、肢体与手指自然无畸变、保持构图光影、不添加文字水印）；你明确要求改某项（如"换发型"）时自动跳过对应约束。可整体关闭（设置卡片开关或 --no-enhance）。
- 缩略图：对话内显示 90px 小图，指向本地 loopback 缓存（不依赖提供商的临时链接）。
- 点击图片：由插件捕获点击 → 请求本机 loopback /visionforge/open → 电脑系统图片查看器打开缓存原图（可放大、缩放、另存）；不弹 DSH 侧边栏。
- 保存图片 N：点击后插件拦截该按钮 → 请求本机 loopback /visionforge/download-local → 缓存图复制到 D 盘根目录（无 D 盘则 C:\Users\<你>\VisionForge）+ 资源管理器自动选中刚保存的文件；全程不弹 DSH 侧边栏。
- 宿主自动装饰：链接渲染成按钮时 DSH 会自动加 ↓🌐 图标，属宿主行为，非插件控制。

目录与缓存治理

统一目录（全部固定，可配置）

| 内容 | 位置 | 说明 |
| 生成图缓存 | D:\VisionForge\out（可在设置卡片改 outputDir） | 插件生成的图片，供对话预览 / 放大 / 下载 |
| 粘贴原图缓存 | D:\VisionForge\out\paste | 粘贴接管后写入的本地副本（不再落系统临时目录） |
| 下载永久副本 | D:\ 根目录（无 D 盘则 C:\Users\<你>\VisionForge） | 点击「保存图片 N」后缓存复制到此，永久保留 |
| 插件配置 | C:\Users\<你>\.visionforge\config.json | 引擎、密钥、模型、优先级、输出目录 |

缓存清除机制

- TTL 3 天：生成图缓存与粘贴缓存超过 3 天自动删除（插件启动时清扫）。
- 下载即永久：已下载的副本在 D 盘根目录，不受清理影响。
- 设置卡可视化清理：DSH 设置 → VisionForge →「缓存管理」实时显示输出目录 / 生成图 / 粘贴 / 特征摘要的占用，可一键按 TTL 清理（当前会话生成的图片保留，不影响对话内放大 / 下载）。
- 对话里的预览链接指向缓存；缓存过期后旧消息的缩略图失效属预期行为——重新生成或下载即可。

内容合规与使用边界

VisionForge 提供「真人照片 → 真人照片」的图生图能力。请在使用中遵守下列边界（依据现行法规：民法典第 1019 条、《互联网信息服务深度合成管理规定》、《生成式人工智能服务管理暂行办法》第 12 条、最高法《关于依法审理涉人工智能纠纷案件的意见》（法发〔2026〕10 号）、《人工智能生成合成内容标识办法》）。

三类场景的边界：

| 场景 | 边界 | 说明 |
| 本人照片自用（写真 / 换装 / 场景） | ✅ 允许 | 由你本人确认照片归属即可 |
| 他人照片 | ⚠️ 需授权 | 未经肖像权人同意不得制作、使用、公开其肖像——「制作」本身即侵权，不公开也算；深度合成编辑人脸、人声等生物识别信息需取得被编辑者单独同意 |
| 公众人物冒充 / AI 换脸 / 丑化 / 低俗 / 伪造不实场景 / 未成年人 | ❌ 禁止 | 未经同意生成可识别特定自然人的虚拟数字形象并使用、公开，即构成对姓名权、肖像权等人格权益的侵害（最高法 2026《意见》）；AI 换脸做广告已有判赔 80 万的公开判例；未成年人肖像需监护人许可 |

插件与宿主的职责划分：

- 插件（技术护栏，自动化）：图生图自动追加保护性约束（保持面部特征 / 肢体自然 / 不加文字水印）；不做身份判断——插件无法识别照片里是谁，也不应尝试识别。
- 宿主（判断与拒绝，第一道闸）：从对话上下文判断照片归属与授权——本人照片自用放行；他人照片未表明授权则拒绝或要求说明；公众人物冒充、丑化、低俗、伪造不实场景一律拒绝；未成年人要求监护人同意依据。
- 内容标识：生成内容建议自行添加「AI 生成」标识（现行《人工智能生成合成内容标识办法》要求显式标识 + 隐式元数据标识）；公开传播前由用户自行确认合规。

注意：对真人照片的身体敏感部位（如胸围 / 腰围等尺寸）进行特征性修改，属于平台审核红线与上述法律边界范畴，插件与引擎均不支持此类请求。请勿尝试通过改写措辞绕过审核——图像引擎对「内衣尺码术语 / 敏感身体部位尺寸」类描述统一拦截，这不是提示词技巧可以绕过的。

边界与卸载（不干扰原生 DSH）

- 作用域严格限定：前端注入的所有行为（点击捕获、按钮拦截、样式、粘贴接管）都以命中插件图片为前提（img[src="/visionforge/image"]、插件渲染的保存按钮）；DSH 原生组件、官方消息、其他插件零影响。
- 卸载即干净：移除插件后 DSH 重启即不再注入脚本、不再启动本地服务、端口释放。插件代码全部在插件包内（dsh/index.js、dsh/client.js），不修改任何 DSH 官方文件。
- 先查残留再卸载：npx @lr611/visionforge doctor --uninstall-check 会列出插件在本机留下的全部足迹（配置目录 / 缓存 / 特征摘要 / DSH profile 安装与声明 / 环境变量），对照输出逐项清理即可。
- 可选彻底清理（卸载后）： powershell -ExecutionPolicy Bypass -File scripts\uninstall.ps1 # 一键引导式卸载（自动清理 profile 声明/插件目录/配置/缓存，含确认提示）

或手动： Remove-Item -Recurse -Force "C:\Users\<你>\.visionforge" # 插件配置与密钥 Remove-Item -Recurse -Force "D:\VisionForge" # 缓存目录（含已下载副本！先备份要留的）

- 注意：D:\ 根目录下已下载的图片是独立副本，不在 D:\VisionForge 内，卸载后仍保留，需自行确认是否删除。

常见问题

Q：粘贴图片变成 图片 文本？ A：你当前选中的模型被判定为纯文本模型，插件接管转成了路径文本（右下角有悬浮缩略图条可预览 / 删除）。切到官方 DeepSeek-V4-Pro / DeepSeek-V4-Flash（或任何声明 image 的视觉模型）即可原生预览。

Q：点击图片没有放大？ A：确认已完全重启 DSH 使插件生效；点击的是图片本体（不是旁边的链接文字）。若仍无效，检查 D:\VisionForge\out\click-debug.log 是否有记录：有记录说明点击已到达插件（问题在系统查看器调用），无记录说明点击未到达插件脚本（宿主沙箱限制）。

Q：点击「保存图片 N」没有反应？ A：确认按钮文字为「保存图片 N」（不是宿主自动渲染的其他链接）。成功后 D 盘根目录出现文件并自动在资源管理器中选中；若沙箱拒绝 explorer 会自动回退打开目录。

Q：密钥框保存后为什么是空的？ A：保存后密钥以 •••••• 掩码显示；若显示为空说明该引擎未配置密钥（或保存失败），重新粘贴密钥再保存。

Q：怎么彻底卸载 VisionForge？ A：插件市场 / dsh plugin remove @lr611/visionforge → 完全重启 DSH →（可选）删除 ~/.visionforge 与 D:\VisionForge。卸载后 DSH 原生功能不受任何影响。

Acknowledgements

VisionForge 基于 liustack/modlens（MIT）的图像桥接设计改造而来：在其成熟的视觉解析引擎（OCR / 布局 / 语义证据、失败切换链）之上，独立实现了 Qwen / GLM 生图与编辑、粘贴直读、对话内缩略图预览、系统查看器放大、一键下载与配置卡片等能力。感谢 liustack 的开源贡献。

License

MIT（上游 ModLens 同许可；本改造基于其 MIT 许可源码，可自由修改与分发）。