DSH Vision（本地 Ollama 优先 + 火山方舟兜底）

本地开发备忘（怎么改、改完怎么生效、踩过的坑）：见 NOTES.md。

给 DSH Agent（以及任意 MCP 客户端）装上「看图」能力：新增一个 analyze_image 工具，把本地图片或图片 URL 交给视觉模型，返回文字回答。默认走本机 Ollama，不花钱、不需要账号；愿意接云端时，火山方舟（豆包） 作为第二候选自动兜底，任何一项都可以通过配置或环境变量换掉。

同一个包同时提供两种形态：

功能

• analyze_image({ image, prompt? })

  • image：本机绝对路径（png / jpeg / webp / gif / bmp，≤ 20 MB）或 http(s) URL，必填。

  • prompt：针对图片的提问，可选；省略时给出详细描述。

• 默认候选链：ollama:qwen2.5vl:3b → ark:doubao-seed-2-0-pro-260215。

  • 本地模型需要先 ollama pull qwen2.5vl:3b；没装 Ollama 时该候选网络失败，会自动切下一个。

  • ark: 候选只有配置了 Key 才会被尝试；没配 Key 直接跳过，不会报错（这就是「零花费」的意思）。

• 失败分类：

  • 429、404、408、409、425、5xx、超时、网络错误 → 切下一个候选；

  • 401/403 → 放弃该 provider 剩余候选（Key 无效就没必要重试）；

  • 其它 4xx（如 400 参数错）→ 立即失败，不浪费 token。

• 本地图片自动嗅探 MIME 并转成 base64 data URL；URL 原样透传，不额外下载。

Related MCP server: deepseek-vision-mcp

环境变量

设置文件（接入位置）

不想动环境变量时，把配置写到 ~/.dsh-vision/config.json（Windows：%USERPROFILE%\.dsh-vision\config.json）。 环境变量优先级更高，设置文件只做默认值：

{
  "provider": "ollama",
  "models": "ollama:qwen2.5vl:3b,ark:doubao-seed-2-0-pro-260215",
  "baseUrls": { "ollama": "http://127.0.0.1:11434/v1", "ark": "https://ark.cn-beijing.volces.com/api/v3" },
  "apiKeys": { "ark": "" },
  "timeoutMs": 60000
}

• 换本地模型：把 models 改成 ollama:moondream 之类，并 ollama pull moondream。

• 接云端：填 apiKeys.ark，或设置 VOLCANO_API_KEY，ark: 候选就会生效。

• 接公司内网 / 自建 OpenAI 兼容服务："provider": "openai"，配 baseUrls.openai 与 apiKeys.openai。

安装

1) 本地视觉模型（免费）

Windows：

winget install --id Ollama.Ollama
ollama pull qwen2.5vl:3b

macOS / Linux：

curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5vl:3b

2) DSH / DPH

安装 dsh-vision 插件，并帮我把本地 Ollama 模型配好

或手动指定仓库/包名安装，然后重启 DSH。重启后 analyze_image 直接可用，不需要 Key。

3) 一键脚本

irm https://raw.githubusercontent.com/hunyu-feng/dsh-vision/main/install.ps1 | iex   # Windows
curl -fsSL https://raw.githubusercontent.com/hunyu-feng/dsh-vision/main/install.sh | bash  # macOS / Linux

脚本会检查 Node ≥ 20、提示 Ollama 拉模型、跑一次 npx -y dsh-vision --selftest。

4) 其它 MCP 客户端

{
  "mcpServers": {
    "dsh-vision": { "command": "npx", "args": ["-y", "dsh-vision"] }
  }
}

需要云端兜底时再补 "env": { "VOLCANO_API_KEY": "..." }。

使用示例

analyze_image  D:\pictures\error.png  提示词：这张截图里报了什么错？
analyze_image  ./design.png           提示词：把界面里的字段名全部抄下来
analyze_image  https://example.com/chart.png

返回根值是 { text, model, provider }；DSH 里只渲染 text。

发布（维护者）

打 v* tag 触发 .github/workflows/publish-mcp.yml：

1. npm publish（需要仓库 Secret NPM_TOKEN）；

2. 下载 mcp-publisher，用 GitHub OIDC 登录 MCP Registry；

3. mcp-publisher publish 把 server.json 登记到官方 Registry。

不需要自动发版时，本地手动流程：

npm publish
curl -fsSL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz" | tar xz
./mcp-publisher login github --token "$(gh auth token)"
./mcp-publisher validate server.json && ./mcp-publisher publish

项目结构

index.js                 DSH 插件入口：defineTool + ctx.tools.register
lib/vision.js            核心：provider 解析、图片编码、候选链、失败分类
bin/mcp-server.js        MCP stdio 服务（复用 lib/vision.js）
cordis.patch.yml         DSH bundle 安装补丁
locale/{zh,en}.json      插件在 DSH 里的标题/描述
server.json              MCP Registry 元数据
install.ps1 / install.sh 一键安装脚本
test/                    node --test 用例（本地/URL/兜底/鉴权/设置文件）

隐私

• 本地模式：图片只发给本机 127.0.0.1:11434，不出网。

• 云端模式：图片会发给火山方舟；Key 只从环境变量或设置文件读取，不写进日志。