前言¶

在 DSH Web 中，有些 Agent 只接入文本模型。当用户上传图片、Agent 产生截图、浏览器截图或读图工具返回图片时，文本模型本身无法直接完成图片理解；如果需要生成或编辑图片，也需要额外接入图片 API。

dsh-vision-mix 是 DeepSeek Harness 的视觉增强插件。它把文本模型、视觉模型和可选图片生成 API 组合成一个 Mix 模型，用于识图、跨轮追问、图片生成与编辑。

这是什么¶

• 插件名：dsh-vision-mix
• 维护者：haiziyao
• 许可证：MIT
• 定位：DeepSeek Harness 的视觉增强插件
• 用途：把识图、图片追问、图片生成与编辑能力接入 DSH 对话流程

Mix 是插件注册的模型入口，不是独立要求单独填写 API Key 的模型服务。模型凭据仍由 DSH 的 Provider 配置和凭据系统管理。

核心功能¶

• 把文本模型、视觉模型和可选的图片生成 API 组合成一个 Mix 模型
• 让原本不支持图片的 Agent 识别上传图片、理解网页截图并持续追问图片内容
• 支持生成或编辑图片
• 在“设置 → Vision Mix”中检测并声明模型 image 能力
• 支持测试并启用 image
• 支持强制启用 image
• 支持独立的 OpenAI-compatible 图片生成与编辑 API
• 支持 vision_mix_image_generate 根据提示词生成新图片
• 支持 vision_mix_image_edit 编辑当前会话中出现过的用户图片或生成图
• 支持分析 Agent 截图、浏览器截图和读图工具返回的图片
• 识图、基础对话、意图判断和生图可以分别使用不同 Provider

安装与启用¶

安装¶

在 DeepSeek Harness 仓库目录执行：

pnpm dsh plugin --profile web add dsh-vision-mix

安装后启动 Web：

pnpm dsh web

配置基础模型与识图模型¶

先做模型配置：

1. 打开“设置 → 模型”
2. 配置基础模型
3. 配置识图模型
4. 识图、基础对话、意图判断和生图可以分别使用不同 Provider

如果需要图片生成与编辑，再配置独立的 OpenAI-compatible 图片生成与编辑 API Provider。

检测并声明 image 能力¶

在“设置 → Vision Mix”的“模型图片能力”中完成：

1. 选择已配置的视觉模型
2. 选择“测试并启用 image”或“强制启用 image”
3. 如果选择测试，插件会临时授予该模型 image 能力
4. 测试失败会自动回滚
5. 启用成功后，回到“基础设置”
6. 选择基础模型、图片模型和可选意图识别模型
7. 点击“保存路由”

启用图片生成与编辑¶

配置图片生成 Provider 后，在“图片生成与编辑”中测试生图 API。

测试生图 API 会：

• 固定使用 low
• 固定使用 1024×1024
• 固定使用 PNG
• 产生一次实际生图费用
• 只在内存中预览并校验结果
• 不会把测试图片永久写入 attachment 存储

启用后，可以调用：

• vision_mix_image_generate：根据提示词生成新图片
• vision_mix_image_edit：编辑当前会话中出现过的用户图片或生成图

典型用法¶

新建对话，并在模型选择器中选择 Mix。下面这些操作都属于该插件支持的典型场景：

1. 上传图片，让 Agent 识别图片内容
2. 下一轮继续追问图片中的局部或细节
3. 要求 Agent 截图，并分析 Agent 截图、浏览器截图或读图工具返回的图片
4. 要求根据提示词生成图片
5. 要求编辑当前会话中出现过的用户图片或生成图

凭据、附件与记录¶

插件的凭据和记录边界如下：

• 插件不包含或持久化硬编码 API Key
• 模型调用通过所选 Provider 的 credential reference 解析凭据
• 配置写回原 Provider 的模型 profile
• API Key 仍保存在 DSH 凭据系统中
• 会话记录保存 attachment id，而不是宿主机器绝对路径或图片 base64
• vision_mix_attachment_query 只能读取当前会话消息、工具结果或识图记录中出现过的附件
• vision_mix_image_edit 只能编辑当前会话消息、工具结果、识图记录或生图记录中出现过的附件
• 图片预览同时校验会话 id 和调用记录 id，不能跨会话枚举

历史记录默认路径：

识图历史：

$DSH_HOME/vision-mix/v1/calls/

生图历史：

$DSH_HOME/vision-mix/v1/generations/

适用场景与注意¶

适合以下场景：

• 已在 DSH 中配置文本模型，并希望 Agent 支持上传图片、截图和跨轮追问
• 已配置视觉模型，需要检测并声明 image 能力
• 已配置 OpenAI-compatible 图片生成与编辑 API，希望在对话中生成或编辑图片

使用前注意：

• 插件以当前 dsh 进程权限运行
• 安装前应检查源码与 MIT 许可证
• 测试图片能力会临时授予 image 能力，失败自动回滚
• 测试生图 API 固定使用 low、1024×1024、PNG，并会产生一次实际生图费用
• dsh-better-sidebar 不是必需依赖
• 未安装 dsh-better-sidebar 时，核心路由、识图、跨轮追问、生图和对话图片显示仍正常

项目地址¶

GitHub 仓库：https://github.com/haiziyao/dsh-vision-mix

社区目录可按插件名 dsh-vision-mix 检索。