vision-toolkit — 多供应商视觉识别 / OCR 工具箱

零依赖（仅 Node.js 内置模块）的图片识别与 OCR 工具：命令行 + 本地图形界面，支持切换任意 OpenAI 兼容视觉大模型供应商（智谱 GLM、通义千问、OpenAI、OpenRouter、硅基流动、自定义端点）。

特性

• 🖼️ 图片问答 / OCR：一张图 + 一个问题，返回模型识别结果
• 🔄 多供应商：6 个预设一键切换（智谱 / 通义 / OpenAI / OpenRouter / 硅基流动 / 自定义 OpenAI 兼容端点），随时换 Key、换模型
• 🖥️ 本地 GUI：node vision-server.js 启动浏览器设置页（127.0.0.1:8650）——切换供应商、填 Key、测连接、直接识别
• ⏱️ 健壮重试：429/5xx/超时自动指数退避重试，尊重服务端 Retry-After
• 🧩 DSH 集成：附带 DeepSeek Harness skill（skills/vision-ocr.md），让 agent 自动调用

环境要求

• Node.js 18+（使用内置 fetch，无需 npm install）
• Windows / macOS / Linux 均可（GUI 自动打开浏览器仅在 Windows 实测）

快速开始（CLI）

# 1. 配置 Key（三选一，优先级从高到低）
export ZHIPU_API_KEY=sk-xxx        # 环境变量（或 VISION_API_KEY）
# 或复制 .env.example 为 .env 填入 Key
# 或用 GUI / --set 写入 vision-config.json

# 2. 识别图片
node vision.js <图片路径> [问题]
node vision.js examples/sample.png "提取图中所有文字"

# 3. 命令行切换供应商 / Key / 模型
node vision.js --set provider=zhipu model=glm-4.6v-flash key=sk-xxx

Key / 端点 / 模型生效顺序（高→低）：

1. 环境变量 VISION_API_KEY / VISION_BASE_URL / VISION_MODEL（兼容 ZHIPU_API_KEY）
2. vision-config.json（GUI 或 --set 生成）
3. 同目录 .env（ZHIPU_API_KEY=...）
4. 智谱默认端点与模型（glm-4.6v-flash）

GUI 设置页

node vision-server.js            # 启动后自动打开浏览器
node vision-server.js --port 9000 --no-open
# Windows 下也可直接双击 vision-server.bat（或后台版 vision-server-hidden.vbs，停止用 vision-server-stop.bat）

页面功能：供应商下拉切换（自动带出端点与模型，可手改）→ 填 API Key（留空保持已保存）→ 保存配置 → 测试连接（用 examples/sample.png 实测）→ 快速识别（填图片路径 + 问题直接出结果）。

常见问题：页面能打开但按钮报「Failed to fetch」= 服务没在运行，重新运行 vision-server.bat 并保持窗口开启。

遇到问题？先让 AI 自己排查

本项目自带两个 DeepSeek Harness skill——先问自己的 agent，别急着找作者：

1. 把 skills/vision-ocr.md（使用）和 skills/vision-debug.md（排障）复制到 DSH 工作区的 .dsh/skills/
2. 报错时对你的 agent 说：「加载 vision-debug skill，按流程排查 vision 识别报错」
3. agent 会按流程自检：环境 → 脱敏配置 → 最小复现 → 错误码分类，给出可执行修复或诊断报告
4. 真解决不了，带着诊断报告来提 issue（模板见 .github/ISSUE_TEMPLATE/bug_report.md）

原则：让 AI 挡在第一线。绝大多数问题属于 429 限流 / 401 无效 Key / 404 模型名错误 / 服务没启动（Failed to fetch），vision-debug 都能自己处理；诊断报告也会让真正需要人工的问题一次说清。

供应商预设

id	名称	baseUrl	默认模型
zhipu	智谱 GLM	https://open.bigmodel.cn/api/paas/v4	glm-4.6v-flash（免费，限流较多）
dashscope	通义千问	https://dashscope.aliyuncs.com/compatible-mode/v1	qwen-vl-max
openai	OpenAI	https://api.openai.com/v1	gpt-4o-mini
openrouter	OpenRouter	https://openrouter.ai/api/v1	google/gemini-2.5-flash
siliconflow	硅基流动	https://api.siliconflow.cn/v1	Qwen/Qwen2.5-VL-72B-Instruct
custom	自定义	任意	任意

DeepSeek Harness 集成（可选）

把 skills/vision-ocr.md 复制到你的 DSH 工作区 .dsh/skills/ 目录（与 vision.js、.env 同目录），之后每个会话中 agent 遇到图片识别任务会自动加载该 skill 并调用 node vision.js。

目录结构

vision-toolkit/
├── vision.js              # CLI 入口
├── vision-core.js         # 共享核心：预设 / 配置 / 统一调用
├── vision-server.js       # GUI 服务（零依赖）
├── vision-gui.html        # GUI 页面
├── vision-server.bat      # Windows 启动器（任意目录可用）
├── vision-server-hidden.vbs / vision-server-stop.bat  # 后台常驻 / 停止
├── examples/sample.png    # 测试用示例图
├── skills/vision-ocr.md   # DSH skill（可选）
└── .env.example           # Key 配置模板

发布与更新

publish.bat "fix: 描述"

一键 git add -A → 提交 → 推送到 GitHub（消息缺省为 update）。内置密钥安全门：若 .env 或 vision-config.json 被暂存，会中止提交并回滚暂存区。

安全说明

• API Key 以明文保存在本地 .env 或 vision-config.json，两者均已加入 .gitignore，不会被提交；请勿把含真实 Key 的这两个文件上传到任何仓库
• GUI 的 /api/config 只返回脱敏 Key（sk-****abcd），不回传明文
• 服务仅绑定 127.0.0.1，不对外网开放

许可证

MIT © vision-toolkit contributors