nvidia-vision

视觉能力补充 CLI — 给纯文本模型（不能看图的大模型）补充视觉识别能力。

💡 核心场景：你在用 DeepSeek V4 Pro、GLM-5.1、MiMo 等纯文本大模型？ 它们无法识别图片。nvidia-vision 帮它们"看"——图片分析、OCR、UI 截图审查， 一个 CLI 命令搞定。

目标用户

| 类型 | 典型对象 | 说明 | |------|----------|------| | 纯文本大模型 | DeepSeek V4 Pro、GLM-5.1、MiMo V2.5 Pro | 完全不具备视觉能力，nvidia-vision 是唯一视觉补充方案 | | AI Agent 框架 | WorkBuddy、Claude Code、Hermes Agent、OpenClaw | 配置了纯文本模型时无法看图，nvidia-vision 作为视觉扩展 | | AI Coding 工具 | Codex CLI + DeepSeek 等 | 代码模型通常无视觉能力，看图全靠 nvidia-vision |

✨ 特性

• 🖼️ 视觉分析 — 图片内容理解、OCR、UI 截图分析
• 📋 剪贴板读取 — 直接分析剪贴板中的截图（macOS / Linux / Windows）
• 📸 浏览器截图 — 通过 Playwriter 截取并分析当前页面
• 🧠 智能路由 — 默认 Qwen3-VL-8B（12s），自动升级/跨 provider fallback
• 🔀 多 Provider — SiliconFlow（国内低延迟）+ NVIDIA NIM（免费备选），自动切换
• 📦 npx 即用 — 无需 clone，npx nvidia-vision 直接运行
• 🔌 一键集成 — nvidia-vision install-skill 自动配置 WorkBuddy / Claude Code / Hermes / OpenClaw / Codex

🚀 快速开始

1. 安装

# 方式 A：npx 直接运行（无需安装）
npx nvidia-vision analyze photo.png "描述图片"

# 方式 B：全局安装
npm install -g nvidia-vision

# 方式 C：从源码安装（开发者）
git clone https://github.com/moriweiji/nvidia-vision-mcp.git
cd nvidia-vision-mcp
npm install && npm run build && npm link

2. 获取 API Key

| Provider | 注册地址 | 费用 | |----------|---------|------| | SiliconFlow（推荐） | cloud.siliconflow.cn | 按量计费 | | NVIDIA NIM（备选） | build.nvidia.com | 免费 |

3. 配置 API Key

# SiliconFlow（推荐，国内低延迟）
echo 'export SILICONFLOW_API_KEY=sk-your-key' >> ~/.zshrc

# NVIDIA NIM（免费备选，高延迟）
echo 'export NVIDIA_NIM_API_KEY=nvapi-your-key' >> ~/.zshrc

source ~/.zshrc

两个都配了 → SiliconFlow 优先，挂了自动切 NVIDIA。

4. 一键安装 AI 集成

nvidia-vision install-skill              # 所有平台
nvidia-vision install-skill --target workbuddy
nvidia-vision install-skill --target claude
nvidia-vision install-skill --target hermes
nvidia-vision install-skill --target openclaw
nvidia-vision install-skill --target codex     # Codex + DeepSeek 等纯文本模型

5. 验证

nvidia-vision models        # 列出所有 provider 的模型
nvidia-vision models -p siliconflow   # 只看 SiliconFlow 的

📖 CLI 使用

# 分析图片（默认 SiliconFlow + Qwen3-VL-8B）
nvidia-vision analyze screenshot.png "描述这张图片"

# 指定 provider
nvidia-vision analyze screenshot.png "描述" -p nvidia

# OCR 提取文字
nvidia-vision analyze document.png "提取所有文字" -t ocr

# UI 分析
nvidia-vision analyze ui.png "分析界面结构" -t describe_ui

# 看剪贴板截图
nvidia-vision clipboard "找出UI中的bug"

# 看浏览器页面（需要 Playwriter 扩展）
nvidia-vision screenshot "描述页面布局"

# 指定模型
nvidia-vision analyze photo.jpg "描述" -m Qwen/Qwen3-VL-32B-Instruct

# JSON 输出
nvidia-vision analyze photo.jpg "描述" --json

# 查看可用模型
nvidia-vision models

可选参数

| 参数 | 说明 | 默认值 | |------|------|--------| | -t, --task-type <type> | 任务类型：analyze / ocr / describe_ui | analyze | | -p, --provider <name> | provider：siliconflow / nvidia | siliconflow | | -m, --model <model> | 指定模型 ID | 按 provider 默认 | | --api-key <key> | 本次命令的 API Key | 读环境变量 | | --json | JSON 格式输出 | 关闭 |

🔌 AI 工具集成

任何能执行 shell 命令的 AI 工具都可以集成。只需：

1. 确保 nvidia-vision 在 PATH 中
2. 确保至少一个 provider 的 API Key 已设置
3. 执行 nvidia-vision install-skill 自动安装配置

WorkBuddy

nvidia-vision install-skill --target workbuddy

WorkBuddy 的图片保存在 ~/.workbuddy/clipboard-images/，LLM 能通过 ls -t 自动发现。

Claude Code

nvidia-vision install-skill --target claude

安装三层：skill 到 ~/.claude/skills/ + CLAUDE.md 追加 + 视觉能力段落。

Hermes / OpenClaw / Codex

nvidia-vision install-skill --target hermes
nvidia-vision install-skill --target openclaw
nvidia-vision install-skill --target codex

Codex 没有 skill 目录，写入 ~/.codex/AGENTS.md。

🧠 模型路由策略

SiliconFlow（默认）

| 角色 | 模型 | 耗时 | 说明 | |------|------|------|------| | 默认 | Qwen3-VL 8B | 2~12s | 快速高质量，日常首选 | | 升级 | Qwen3-VL 32B | 10~35s | 最强视觉，Markdown 输出 | | 备选 | Qwen3-VL 30B MoE | 5~18s | 平衡速度与质量 | | 中文 | GLM-4.5V | 5~15s | 带深度思考 | | OCR | DeepSeek-OCR | 1~3s | OCR 专用 |

NVIDIA NIM（免费备选）

| 角色 | 模型 | 耗时 | 说明 | |------|------|------|------| | 默认 | Nemotron Nano 12B VL | 6~15s | 快速稳定 | | 升级 | Llama 3.2 90B | 30~130s | 最高精度 | | 兜底 | Llama 3.2 11B | 3~10s | 轻量备选 | | 中文 | Kimi K2.6 | 10~30s | 中文场景 |

自动升级逻辑

• -t ocr 或 prompt 含「完整提取」「所有文字」「详细分析」等 → 自动走高精度模型
• 结果含「不确定」「看不清」→ 升级重试
• 手动 -m 指定模型 → 跳过自动升级

💻 平台支持

| 命令 | macOS | Linux | Windows | |------|-------|-------|---------| | analyze | ✅ | ✅ | ✅ | | clipboard | ✅ (AppleScript) | ✅ (xclip / wl-clipboard) | ✅ (PowerShell) | | screenshot | ✅ | ✅ | ✅ | | models | ✅ | ✅ | ✅ | | install-skill | ✅ | ✅ | ✅ |

📁 项目结构

src/
├── providers.ts       # 多 provider 配置（SiliconFlow / NVIDIA）
├── nim-client.ts      # OpenAI 兼容 API 客户端（超时、重试、限流 backoff）
├── model-router.ts    # 模型路由器（自动升级 + 跨 provider fallback）
└── cli.ts             # CLI 入口（analyze/clipboard/screenshot/models/install-skill）

🔒 隐私与安全

• API Key 通过环境变量传入，不会硬编码在代码中
• --api-key 传参可能暴露在进程列表中，推荐使用环境变量
• .env 文件已在 .gitignore 中排除
• 临时文件使用 os.tmpdir()，分析后自动清理
• 图片通过第三方 API 处理（SiliconFlow / NVIDIA NIM）

⚠️ 已知限制

• screenshot 命令需要 Playwriter 浏览器扩展
• SiliconFlow 按量计费，NVIDIA NIM 免费但有速率限制（~40 RPM）
• Linux clipboard 需要预装 xclip（X11）或 wl-clipboard（Wayland）
• 图片最大 50MB，超过会警告但不阻断
• 不持多图同时输入，跨图对比基于各图文本描述推断

📜 License

MIT