dsh-custom-vision

DSH（DeepSeek Harness）插件：用你自己的 OpenAI 兼容视觉模型解析图片。

两个能力：

1. 发图自动识别（核心）——你在对话里粘贴/上传图片后，请求到达主模型之前， 插件先用你的视觉模型把图片读成详细文字，主模型一步就能回答细节问题。 对纯文本主模型（如 deepseek-v4.1-flash）尤其有用。
2. image_understand 工具——模型可传本地图片路径、http(s) 图片 URL、 粘贴图片的引用文本或 data URI，返回视觉模型的解析结果（看图 / OCR / 界面 / 报错截图 / 图表）。

不依赖任何第三方运行时：只用 Node 内置能力 + @deepseek-ai/schemastery（配置 schema）。

---

1. 安装

从插件市场安装（推荐）

DSH 设置里的「插件市场」搜索 dsh-custom-vision，一键安装，然后重启应用。

命令行安装

# 从 npm
dsh plugin --profile desktop add dsh-custom-vision

# 或直接从 GitHub 源码安装
dsh plugin --profile desktop add github:LightingHa/dsh-custom-vision

本地开发安装

在本目录下：

# 拷贝安装（稳定；改代码后需重新执行本命令 + 重启应用）
dsh plugin --profile desktop add "file:D:\dshproject\dshtest01\dsh-custom-vision"

# 或者链接安装（开发用；改代码立即生效，无需重装）
dsh plugin --profile desktop add "link:D:/dshproject/dshtest01/dsh-custom-vision"

命令会把包加进 profile 的 package.json（dependencies + dsh.profile.bundles）。 装完后必须重启 DSH（桌面版：退出应用再打开）才会加载，因为 bundles 在启动时组装。

验证是否加载：重启后打开「设置」，能看到 自定义视觉 卡片即表示已加载。

2. 配置

三种方式，优先级从低到高：

方式	位置	说明
profile 配置	cordis.patch.yml 的 config:	适合随 profile 分发
设置文件	~/.dsh/custom-vision.json	设置界面写入；改完下一次调用即生效，无需重启
环境变量	CUSTOM_VISION_API_KEY	仅作 API Key 兜底

最简做法：重启后在 设置 → 自定义视觉 卡片里填写，或直接用命令行写入：

// ~/.dsh/custom-vision.json
{
  "baseURL": "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
  "model": "qwen3.8-flash",
  "provider": "custom",
  "keys": { "custom": "sk-your-key" },
  "autoDescribe": true
}

baseURL 填到 /v1 为止即可（插件自己拼 /chat/completions）。 兼容 OpenAI / 阿里云百炼 / 火山方舟 / 硅基流动 / 智谱 / Ollama / vLLM / LM Studio / one-api 等任意兼容端点。

主要配置项

字段	默认	含义
baseURL	空	OpenAI 兼容地址（到 /v1）
model	空	视觉模型名，如 qwen3.8-flash
apiKey / keys.<provider>	空	API Key（keys 支持多套端点）
provider	custom	密钥槽名
autoDescribe	true	发图自动识别（关闭后只有工具可用）
describePrompt	内置详细描述词	自动识别用的提示词，越详细后续追问越准
describeCacheSize	64	识别结果缓存条数（按图片 sha256，避免重复计费）
toolName	image_understand	工具公开名
maxTokens / temperature	4096 / 0.2	视觉模型采样参数
timeoutMs / retries	180000 / 2	单次超时与限流重试
maxImageBytes	10 MiB	单图字节上限；超过时借宿主附件服务自动压缩
allowedDirs	空（不限制）	允许读取图片的目录，; 或 , 分隔
extraBody	{}	额外请求字段，如 {"top_p":0.8}
debug	false	在日志里打印调用诊断（不含密钥与图片内容）

3. 用法

发图自动识别

直接粘贴/上传图片并提问即可。插件识别后，主模型看到的是图片的描述文本， 并在回答里提示可继续追问细节。

• 如果主模型本身支持图片输入（例如 qwen3.8-flash），插件不介入，把请求原样交给主模型。
• 识别结果按图片 sha256 缓存，同一张图只调用一次视觉模型。
• 识别失败时不会中断对话：该图退化为可解析引用（![图片](https://raw.githubusercontent.com/LightingHa/dsh-custom-vision/HEAD/dsh-custom-vision/raw/sha256:…)）， 模型仍可用工具针对它追问。

为什么需要「图片能力声明」

DSH 在发送图片时就会校验模型能力：inputModalities 不含 image 直接拒收 （session/attachment-invalid · MODEL_DOES_NOT_SUPPORT_IMAGES，界面提示 「当前模型不支持图片，请切换支持图片的模型」）。这个校验发生在图片入库之前， 比插件能介入的 llm/stream 更早，所以纯文本主模型下根本发不出图片。

因此自动识别开启时，插件会覆盖 llm.resolveModelInfo，把选中模型声称为可接收图片：

• 这个声明由插件自己兑现——请求分发前，图片已被换成视觉模型的文字描述，纯文本主模型永远收不到图片块；
• 自动识别关闭时立即还原真实能力，宿主重新按原样拒收（不谎报）；
• 插件卸载时还原原始方法；对同一 provider/model 只查询真实能力一次（shouldDescribeFor 走原始方法，避免被自己的声明误导成"主模型能看图"）。

工具

image_understand(
  image_source = "D:\\pics\\shot.png",     # 路径 / URL / 粘贴引用 / data URI
  prompt       = "这张报错截图是什么原因？",
  task_type    = "debug"                  # auto | general | describe | ocr | ui | debug
)

设置界面里的「测试连接」

设置 → 自定义视觉 → 测试连接：插件内嵌生成一张 64×64 纯色 PNG，真调一次你的端点， 显示延迟、模型名、用量与模型回答，用来确认地址/密钥/模型名是否正确。

4. 自检与测试

cd D:\dshproject\dshtest01\dsh-custom-vision

node test/unit.test.mjs             # 16 项：图片嗅探、引用解析、请求体、错误处理、重试
node test/host-integration.test.mjs # 13 项：假宿主跑通「发图→自动识别→重写请求」与工具/接口
node test/client-bundle.test.mjs    #  5 项：客户端设置卡片注册与渲染

node test/e2e-remote.mjs            # 真实端点端到端（读 ~/.dsh/custom-vision.json 或 free-vision.json）
node test/make-fixtures.py          # 重新生成测试图（需 Pillow）

插件还暴露三个只读接口，便于排障（需浏览器信任凭据）：

• GET /dsh-custom-vision/config —— 当前生效配置（密钥已掩码）+ 运行诊断
• GET /dsh-custom-vision/tools —— 工具是否真的注册进宿主、注册错误、诊断信息
• POST /dsh-custom-vision/test —— 真调一次视觉模型
• GET /dsh-custom-vision/raw/sha256:<hex> —— 按内容地址回显图片（缩略图用）

5. 排障

现象	处理
发送图片报「当前模型不支持图片，请切换支持图片的模型」	图片能力声明没生效：看 GET /dsh-custom-vision/config 的 status.imageClaim 是否为 applied。若为 failed 说明宿主服务不可写；若 autoDescribe 被关掉也会如此（此时确实不该发图）
设置里看不到「自定义视觉」	插件没加载：确认 dsh --profile desktop --dump-config 里有 dsh-custom-vision，并已重启应用
卡片折叠态一直显示「读取中…」	配置接口没返回：确认 GET /dsh-custom-vision/config 可访问。徽章是三态（读取中 / 已配置·缺密钥 / 未配置），不会把"还没读到"当成"未配置"
改了代码但行为没变	file: 安装是拷贝，且 pnpm add 因依赖已满足会跳过：先删掉 profiles\<profile>\node_modules\dsh-custom-vision，再执行 dsh plugin --profile <profile> add "file:…"。客户端半部改动刷新页面即可，宿主半部改动需重启应用
发图后回答"我看不到图片"	打开 debug，看日志是否有 llm/stream：请求含图片块；若没有，说明图片没进请求（会话未附加图片）。若显示"主模型可看图"，属正常不介入
工具没出现在工具列表	GET /dsh-custom-vision/tools 看 registrationErrors（宿主 schema 方言很严格）
HTTP 401/403	密钥无效或无该模型权限
HTTP 404	baseURL 或 model 不对（确认以 /v1 结尾且模型名在该端点存在）
HTTP 429	限流/额度，插件会自动重试 retries 次
国内端点 502	代理问题：插件默认剔除 HTTP(S)_PROXY 直连；如需保留代理设 CUSTOM_VISION_KEEP_PROXY=1
图片太大被拒	调大 maxImageBytes，或让宿主的附件服务压缩（默认自动尝试）

6. 开发

# 改了源码后（link: 安装可跳过这步）
dsh plugin --profile desktop add "file:D:\dshproject\dshtest01\dsh-custom-vision"
# 重启应用

源码结构：

文件	职责
dsh/index.js	Cordis 插件入口：工具注册、llm/stream 自动识别、Web 路由、配置
dsh/image.js	图片格式嗅探、引用解析、data URI、URL 规范化（纯函数）
dsh/vision-client.js	OpenAI 兼容 /chat/completions 调用、重试、错误可读化
client/client.js	浏览器半部：settings.section 设置卡片
cordis.patch.yml	bundle 层：把插件挂进 profile

已知注意点：

• 工具 schema 不能用属性级 required: true（DSH schema 方言会拒绝，导致工具静默注册失败）。
• attachments 图片读取按「宿主规范化副本路径 → 服务读取 → 内容寻址对象文件」三级回退。
• 自动识别在 llm/stream waterfall 上改写消息；改写后请求不再含图片块，因此不会递归。

7. 发布

维护者视角的发布流程（GitHub 建仓、npm 发布、向 awesome-dsh-plugin 提条目 PR，以及 CI 的硬性门槛） 见 PUBLISHING.md。待提交的市场条目在 contrib/LightingHa__dsh-custom-vision.yml。