自定义视觉 LightingHa/dsh-custom-vision

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 缓存，同一张图只调用一次视觉模型。
- 识别失败时不会中断对话：该图退化为可解析引用（图片），模型仍可用工具针对它追问。

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

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。