VisionForge

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

🌐 English | 中文

VisionForge 基于开源视觉插件 liustack/modlens（MIT）深度改造而来：接入千问（Qwen）引擎、新增图片生成与编辑能力、内置图形化设置卡片、支持官方 / 插件双解析优先级调度。改造点全部保留原插件的轻量架构——在 DSH 上只是一个插件目录，卸载即删除，不修改任何 DSH 官方组件，不影响原生功能。0.1.8 及更早版本为 modlens 分叉基础上的桥接版；0.1.9 起连接层重写为自研实现（保留上游致谢与架构启发）。

适配环境：当前版本（0.1.11 / 0.2.1）适配 DSH harness 0.2.x（0.2.0-rc.2 实测）；0.1.10 适配 harness 0.1.7 系列。各版本与 harness 的完整适配矩阵见 CHANGELOG.md「版本与 DSH harness 适配矩阵」。DSH 大版本更新可能改变插件接口，升级后请重新验证。

功能一览

能力	说明
🖼️ 粘贴即读	官方视觉模型下图片粘贴进输入框原生预览；纯文本模型下由插件接管转成本地路径并解析，两种模式都无需手动复制路径
🔭 多提供商视觉引擎	`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。

快速开始

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

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

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

在设置卡片添加

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

命令行添加

# 读图 + 生图（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 要 1024*1024、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：粘贴图片变成 ![图片](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 许可源码，可自由修改与分发）。

VisionForge

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

🌐 English | 中文

适配环境：当前版本（0.1.11 / 0.2.1）适配 DSH harness 0.2.x（0.2.0-rc.2 实测）；0.1.10 适配 harness 0.1.7 系列。各版本与 harness 的完整适配矩阵见 CHANGELOG.md「版本与 DSH harness 适配矩阵」。DSH 大版本更新可能改变插件接口，升级后请重新验证。

功能一览

能力	说明
🖼️ 粘贴即读	官方视觉模型下图片粘贴进输入框原生预览；纯文本模型下由插件接管转成本地路径并解析，两种模式都无需手动复制路径
🔭 多提供商视觉引擎	`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）并把结果告诉我。

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

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

快速开始

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

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

在设置卡片添加

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

命令行添加

# 读图 + 生图（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 字段	自定义私有网关

名称护栏

名称自动规范化（大小写 / 空格 / 连字符 / 下划线统一）；
与内置引擎或已有自定义引擎重名 → 拒绝并说明；
与内置引擎拼写相近（编辑距离 ≤ 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 清理（当前会话生成的图片保留，不影响对话内放大 / 下载）。
对话里的预览链接指向缓存；缓存过期后旧消息的缩略图失效属预期行为——重新生成或下载即可。

内容合规与使用边界

三类场景的边界：

场景	边界	说明
本人照片自用（写真 / 换装 / 场景）	✅ 允许	由你本人确认照片归属即可
他人照片	⚠️ 需授权	未经肖像权人同意不得制作、使用、公开其肖像——"制作"本身即侵权，不公开也算；深度合成编辑人脸、人声等生物识别信息需取得被编辑者单独同意
公众人物冒充 / 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 内，卸载后仍保留，需自行确认是否删除。

常见问题

Acknowledgements

License

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

LR611415/visionforge

VisionForge

功能一览

安装

方式一：npm 安装（推荐）

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

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

快速开始

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

在设置卡片添加

命令行添加

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

名称护栏

设置卡片配置项

生成图交互说明

目录与缓存治理

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

缓存清除机制

内容合规与使用边界

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

常见问题

Acknowledgements

License

Community comments

LR611415/visionforge

VisionForge

功能一览

安装

方式一：npm 安装（推荐）

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

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

快速开始

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

在设置卡片添加

命令行添加

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

名称护栏

设置卡片配置项

生成图交互说明

目录与缓存治理

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

缓存清除机制

内容合规与使用边界

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

常见问题

Acknowledgements

License

Community comments