Sorwcyra/ds-vision-plugin ↗★ 0
用于 DeepSeek Harness 的自动 Web 图像到文本桥接器以及视觉与 OCR 工具
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:Sorwcyra/ds-vision-plugin
agent/pre-step[!NOTE] 不需要修改或 fork Harness 源码。插件同时提供
vision_analyze与vision_status，用于工作区文件识别和配置诊断。
| 用户需求 | 插件方案 |
|---|---|
| 把截图直接贴进纯文本 DeepSeek 对话 | 自动把 Web 附件转换为文本 |
| 不想被单个视觉服务的慢响应或故障拖住 | 四个模型同时启动，首个有效结果获胜 |
复用经过验证的 ds-vision-skill 路由思路 | Agnes 2.5 + Agnes 2.0 + GLM-4V-Flash + GLM-4.1V-Thinking-Flash |
| 接入私有中转、付费模型或本地运行时 | 可添加任意数量的 OpenAI-compatible 竞速或降级路由 |
| 不想手工编辑 YAML | CLI 引导配置、密钥、状态、自定义模型和真实图片验证 |
| 失败时需要知道发生了什么 | 显式错误标注或严格失败，图片不会被静默丢弃 |
ds-vision-skill 的四模型思路：默认同时调用 Agnes 2.5、Agnes 2.0、GLM-4V-Flash、GLM-4.1V-Thinking-Flash，首个有效结果直接交给 DeepSeek。glm-4.6v-flash。agent/pre-step 扩展点，插件可独立安装和卸载。四路竞速意味着每张未命中缓存的图片最多会启动四个云端请求。适合重视低延迟与可用性的场景；对调用次数、费用或敏感数据更在意时，可以从 routing.race 删除通道，或改用本地模型/OCR。
flowchart LR
U["Web 输入框
粘贴 / 拖入图片"] --> A["Harness 附件存储
已校验字节"]
A --> P["ds-vision-plugin
agent/pre-step"]
P --> R["四模型竞速
Agnes 2.5 + Agnes 2.0
GLM-4V + GLM Thinking"]
P --> O["OCR 路由
百度 / Tesseract"]
P --> C["自定义路由
云端 / 中转 / 本地"]
R --> T["可靠文本 block"]
O --> T
C --> T
T --> D["纯文本 DeepSeek
继续推理"]
deepseek-official 路由。agnes-2.5-flash、agnes-2.0-flash、glm-4v-flash、glm-4.1v-thinking-flash；第一个有效结果获胜，其余请求立即取消。glm-4.6v-flash。vision_status 不返回密钥。要求 Node.js 22.19+ 或 24+，以及 DeepSeek Harness 0.1.0-rc.6（或兼容的 0.1.x，须提供 agents、attachments、llm、tools 服务）。
从 GitHub 安装当前版本：
$env:npm_config_ignore_workspace_root_check = 'true'
npx -y @deepseek-ai/dsh plugin --profile web add "github:Sorwcyra/ds-vision-plugin"
安装仓库中已经构建好的 tarball：
$env:npm_config_ignore_workspace_root_check = 'true'
npx -y @deepseek-ai/dsh plugin --profile web add "C:\absolute\path\to\ds-vision-plugin-0.3.0.tgz"
如果已经全局安装 dsh，也可以直接使用 dsh plugin ...。若 PowerShell 提示无法识别 dsh，就使用上面的 npx -y @deepseek-ai/dsh，无需再全局安装。
本地源码安装：
pnpm install
pnpm run build
dsh plugin --profile web add file:/absolute/path/to/ds-vision-plugin
确认 bundle 层和 ds-vision 行已进入最终配置：
dsh --profile web --dump-config
安装后运行向导。它会在 ~/.dsh/ds-vision/vision.yml 生成四模型竞速配置、显示缺少的密钥，并可继续添加自定义模型：
& "$env:USERPROFILE\.dsh\profiles\web\node_modules\.bin\ds-vision.cmd" configure
查看状态：
& "$env:USERPROFILE\.dsh\profiles\web\node_modules\.bin\ds-vision.cmd" status
交互式保存 GLM 或 Agnes 用户级密钥（输入时隐藏）：
& "$env:USERPROFILE\.dsh\profiles\web\node_modules\.bin\ds-vision.cmd" key glm
& "$env:USERPROFILE\.dsh\profiles\web\node_modules\.bin\ds-vision.cmd" key agnes-2.5-flash
同一个 GLM_API_KEY 同时启用 glm 和 glm-thinking；同一个 AGNES_API_KEY 同时启用两个 Agnes 模型。未配置对应密钥的通道会立即跳过，不会影响其他已配置通道。
用一张图片验证真实四路竞速并显示获胜模型：
& "$env:USERPROFILE\.dsh\profiles\web\node_modules\.bin\ds-vision.cmd" verify --image "C:\path\test.png"
向导支持任意数量的 OpenAI-compatible 模型，不再限制 custom-1/2/3：
& "$env:USERPROFILE\.dsh\profiles\web\node_modules\.bin\ds-vision.cmd" add `
--id my-vlm `
--base-url "https://example.com/v1/chat/completions" `
--model "your-vision-model" `
--api-key-env "MY_VLM_API_KEY" `
--pool fallback
--pool race 会加入并发竞速；--pool fallback 会在四模型全部失败后按顺序调用。密钥仍单独存放，不写入 YAML，也不会被 vision_status 返回。
也可以直接编辑配置，或通过 DS_VISION_CONFIG 指定其他路径。
Linux/macOS：
export DS_VISION_CONFIG=/absolute/path/to/vision.yml
export GLM_API_KEY=...
export AGNES_API_KEY=...
dsh web
Windows PowerShell：
$env:DS_VISION_CONFIG = 'C:\absolute\path\to\vision.yml'
$env:GLM_API_KEY = '...'
$env:AGNES_API_KEY = '...'
npx -y @deepseek-ai/dsh web
更新插件后必须退出旧的 dsh web 进程再启动；只刷新网页不会重新加载 bundle。如果提示 EADDRINUSE 127.0.0.1:3080，说明旧服务仍在占用端口，应先关闭启动它的 PowerShell 窗口（或在该窗口按 Ctrl+C），再执行启动命令。
bundle patch 支持以下环境变量：
| 变量 | 默认值 | 作用 |
|---|---|---|
DS_VISION_AUTO_CONVERT | true | 设为 false 可关闭 Web 图片自动转换。 |
DS_VISION_AUTO_PROVIDERS | deepseek-official | 逗号分隔的主模型 provider 路由。自定义 patch 中设为空数组可匹配全部 provider。 |
DS_VISION_AUTO_INTENT | auto | auto、reason 或 ocr；用户要求提取文字时，auto 会选择 OCR。 |
DS_VISION_AUTO_FAILURE_MODE | annotate | annotate 用可见错误标记替换失败图片；error 直接让当前 step 失败。 |
高级选项 autoPrompt、autoComplex、autoAccurateOcr 可在 profile 的 cordis.patch.yml 中覆盖。注意 Harness 的后续 patch 会整体替换该行的 config，不是深度合并，因此要把 ds-vision 行所需字段完整写出。
启动 Web profile，选择 DeepSeek provider，把一张或多张 PNG/JPEG/WebP/GIF 图片粘贴或拖入输入框，可同时输入问题，然后直接发送；不需要填写路径或点名工具。插件只为 autoProviders 中的路由向 Host 声明可接收图片，随后在模型调用前把图片转换为文本，因此纯文本 DeepSeek 适配器不会收到任何 image block。插件卸载时会恢复原始模型能力解析。
对于工作区文件，模型仍可调用：
vision_analyze(path, prompt, intent, complex, accurate_ocr, no_cache)
可用 vision_status() 查看自动转换和后端路由状态，不会泄露密钥。
Web 图片只通过 Harness 已校验的私有附件服务读取；配置的云端通道会收到图片字节。allowedRoots 只限制显式文件路径工具，不限制 Web 附件。敏感图片请使用本地视觉模型/Tesseract，或关闭自动转换。
默认 annotate 模式会移除纯文本模型不支持的图片 block，并留下明确的转换失败说明，让 DeepSeek 告知用户；需要强一致性时请改为 error。
pnpm run build
pnpm run check
pnpm run pack:check
pnpm pack --pack-destination ./artifacts
ds-vision-skill 的默认四路竞速无需真实密钥即可单独运行 Mock 竞速测试：
pnpm run build
pnpm run test:race
测试服务器会模拟以下响应时间：
| 模型 | Mock 延迟 |
|---|---|
glm-4v-flash | 40 ms |
agnes-2.5-flash | 120 ms |
agnes-2.0-flash | 160 ms |
glm-4.1v-thinking-flash | 200 ms |
断言会验证四个模型请求全部启动、glm-4v-flash 首先胜出，并且配置中不存在 4.6。完整 pnpm run check 还覆盖 Web Host 放行、附件转文本、失败策略、CLI 自定义模型和路径安全。
VERIFICATION.md 记录了参考的官方源码提交、自动化覆盖、包内容和隔离环境安装结果。
本插件把 ds-vision-skill 的四模型路由思路适配到了 DeepSeek Harness Web 输入框和插件生命周期中。
欢迎提交 bug、视觉通道修复、文档优化和新的路由策略。
本项目使用 MIT License。