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 对照

安装层面的兼容范围（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 系列均可安装），上表为实测版本。

---

功能一览

安装

方式一：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 补填。

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

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

名称护栏

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

设置卡片配置项

模型候选下拉只列视觉读图模型；生成模型（如 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 会自动加 ↓🌐 图标，属宿主行为，非插件控制。

目录与缓存治理

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

缓存清除机制

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

内容合规与使用边界

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

三类场景的边界：

插件与宿主的职责划分：

• 插件（技术护栏，自动化）：图生图自动追加保护性约束（保持面部特征 / 肢体自然 / 不加文字水印）；不做身份判断——插件无法识别照片里是谁，也不应尝试识别。
• 宿主（判断与拒绝，第一道闸）：从对话上下文判断照片归属与授权——本人照片自用放行；他人照片未表明授权则拒绝或要求说明；公众人物冒充、丑化、低俗、伪造不实场景一律拒绝；未成年人要求监护人同意依据。
• 内容标识：生成内容建议自行添加"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：粘贴图片变成 ![图片](http://127.0.0.1:.../visionforge/image?path=...) 文本？ 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 许可源码，可自由修改与分发）。