deepseek-vision-analyzer — DeepSeek Vision Analyzer / 图像视觉识别分析师

deepseek-vision-analyzer lets LLMs / Agents without vision capabilities still understand images: it drives your system Chrome (via CDP WebSocket) into the vision mode of chat.deepseek.com, hands the images to the DeepSeek vision model, and prints the answer as plain text to stdout while logs go to stderr — ready for the calling model to parse directly.

deepseek-vision-analyzer 让没有视觉能力的 LLM / Agent 也能看图:它驱动系统 Chrome(CDP WebSocket)打开 chat.deepseek.com 的识图模式,把图片交给 DeepSeek 视觉模型,回答以纯文本输出到 stdout,日志走 stderr——模型拿到即可直接解析。

True multimodal understanding, not OCR: images without any text can still be recognized for objects, colors, and composition. Zero npm dependencies, zero browser drivers, single file.

真·多模态理解,不是 OCR:没有文字的图片也能识别物体、颜色与构图。零 npm 依赖、零浏览器驱动、单文件。

Quick Start

快速上手

Requirements: Node ≥ 22 (global fetch + WebSocket) plus a system-installed Chrome / Edge.

要求:Node ≥ 22(全局 fetch + WebSocket)+ 系统安装的 Chrome / Edge。

# Install: put skills/deepseek-vision-analyzer/deepseek-vision-analyzer.js on your PATH, or create an alias
# 安装: 把 skills/deepseek-vision-analyzer/deepseek-vision-analyzer.js 放到 PATH,或建个别名
alias deepseek-vision-analyzer="node /path/to/skills/deepseek-vision-analyzer/deepseek-vision-analyzer.js"        # Windows: add this directory to PATH / 可将本目录加入 PATH

# First run handles login automatically (headless probe → one popup if needed); seamless afterwards
# 首次运行会自动处理登录(无头探测 → 必要时弹窗一次),之后全程无感
deepseek-vision-analyzer photo.jpg "描述这张图"

The script is not on PATH by default — you must call it via node <path>/deepseek-vision-analyzer.js unless you add an alias / PATH entry as above.

脚本默认不在 PATH 中,不建别名 / 不加 PATH 的话,必须用 node <路径>/deepseek-vision-analyzer.js 按路径调用。

Install as a Skill

安装为 Skill

This repository doubles as a Claude / opencode Skill — copy the whole skills/deepseek-vision-analyzer/ folder (SKILL.md + deepseek-vision-analyzer.js) into your skills directory, and the agent will auto-load its calling conventions on the next session.

本仓库同时是一个 Claude / opencode Skill——把整个 skills/deepseek-vision-analyzer/ 目录(SKILL.md + deepseek-vision-analyzer.js)复制到你的 skills 目录,下一个会话起 Agent 会自动加载其中的调用约定。

Agent	Skills directory
opencode (global / 全局)	~/.agents/skills/
opencode (this project / 当前项目)	.opencode/skills/
Claude Code	~/.claude/skills/

# macOS / Linux — e.g. for opencode global
mkdir -p ~/.agents/skills
cp -r skills/deepseek-vision-analyzer ~/.agents/skills/

# Windows (PowerShell)
Copy-Item -Recurse skills/deepseek-vision-analyzer "$HOME\.agents\skills\"

Not a git clone? Download deepseek-vision-analyzer-skills-<version>.zip from GitHub Releases, extract it into your skills directory — the zip contains the deepseek-vision-analyzer/ folder.

没有 clone 仓库?从 GitHub Releases 下载 deepseek-vision-analyzer-skills-<version>.zip,解压到你的 skills 目录即可——zip 内已包含 deepseek-vision-analyzer/ 文件夹。

Verify the install:

验证安装:

~/.agents/skills/deepseek-vision-analyzer/
├── SKILL.md                        # agent triggers + calling conventions / Agent 触发条件与调用约定
└── deepseek-vision-analyzer.js     # the CLI itself / CLI 本体

Note: the CLI inside a skill folder is not on PATH — the agent invokes it via node <SKILL.md 同目录>/deepseek-vision-analyzer.js; see the skill's SKILL.md for details.

注意:Skill 目录里的 CLI 不在 PATH 中——Agent 会通过 node <SKILL.md 同目录>/deepseek-vision-analyzer.js 调用;详见 SKILL.md。

Sample output (real run, excerpt) — green is the model answer (stdout), gray is deepseek-vision-analyzer logs (stderr):

示例输出(真实运行,节选)——绿色为模型回答(stdout),灰色为 deepseek-vision-analyzer 日志(stderr):

$ deepseek-vision-analyzer photo.jpg "描述这张图"
[deepseek-vision-analyzer] ⏱ 登录: 5.4s
[deepseek-vision-analyzer] ⏱ 上传: 8.1s
[deepseek-vision-analyzer] ⏱ 回答: 15.8s
[deepseek-vision-analyzer] 已删除会话: 55a5b0d6-…
❯ 画面主体是几棵高大的银杏树,
❯ 树冠与地面铺满金黄落叶…

Command Reference

命令速查

Scenario	Command
Basic recognition	deepseek-vision-analyzer photo.jpg
With a question	deepseek-vision-analyzer screenshot.png "描述这个界面的布局"
Multiple images in one session	deepseek-vision-analyzer a.png b.png "对比这两张图"
Wildcard batch	deepseek-vision-analyzer '*.png' "识别全部"
Keep the session (deleted by default)	deepseek-vision-analyzer --keep img.png "识别"
Clear login state	deepseek-vision-analyzer --logout
Quit background Chrome	deepseek-vision-analyzer --quit
Help	deepseek-vision-analyzer --help

场景	命令
基本识图	deepseek-vision-analyzer photo.jpg
带问题	deepseek-vision-analyzer screenshot.png "描述这个界面的布局"
多图一次会话	deepseek-vision-analyzer a.png b.png "对比这两张图"
通配符批量	deepseek-vision-analyzer '*.png' "识别全部"
保留会话(默认用后即删)	deepseek-vision-analyzer --keep img.png "识别"
清除登录态	deepseek-vision-analyzer --logout
关闭后台 Chrome	deepseek-vision-analyzer --quit
帮助	deepseek-vision-analyzer --help

• Without a question, the built-in default prompt is used (scene / detail checklist / text transcription / composition / inference, bullet-style in Chinese)

• Relative / absolute paths and * / ? / [...] wildcards are supported (non-recursive); multiple images are compressed to ≤1024px and sent in one session

• 未给问题文本时,使用内置默认提示词(场景 / 细节清单 / 文字转写 / 构图 / 推断,中文条目式)

• 支持相对 / 绝对路径与 * / ? / [...] 通配符(不递归);多图会压缩至 ≤1024px 后一次会话发送

How It Works

它是如何工作的

• Zero drivers: launches system Chrome directly over CDP; the PoW anti-scraping challenge is computed by the real browser frontend — no algorithms are broken

• Fully automatic login: when the token is invalid it first probes browser profiles headlessly, only popping a headed window for manual login as a last resort, then switches back to headless after capturing

• Self-cleaning: the session is deleted automatically after each recognition (zero pollution in your chat list); --keep retains it

• 零驱动:直接通过 CDP 拉起系统 Chrome;PoW 反爬由真实浏览器前端自动计算,不破解任何算法

• 登录全自动:token 失效时先无头探测浏览器配置,仍失败才弹有头窗口等待手动登录,捕获后自动换回无头

• 用后即删:识别完成自动删除本次会话(对话列表零污染),--keep 保留

Output Conventions & Exit Codes

输出约定与退出码

Channel	Content
stdout	model answer plain text (parse directly, no post-processing)
stderr	deepseek-vision-analyzer logs (timing, upload status, etc. — no need to relay to the user)

通道	内容
stdout	模型回答纯文本(直接供模型解析,不要二次加工)
stderr	deepseek-vision-analyzer 日志(耗时、上传状态等,无需回传给用户)

Exit code	Meaning
0	Success
1	Argument or image error
3	Chrome failed to start
4	Login not completed

退出码	含义
0	成功
1	参数或图片错误
3	Chrome 启动失败
4	登录未完成

• A single image takes about 20–30 seconds (upload ~12s + model generation ~18s); leave the caller timeout at least 60s, and more for multiple images.

• 单图约 20–30 秒(上传 ~12s + 模型生成 ~18s),调用方超时请至少留 60s,多图更久。

Environment Variables

环境变量

Variable	Default	Description
CHROME_PATH	auto-detected	Chrome / Edge executable path
DSVA_PORT	9223	CDP debug port
DSVA_PROFILE	~/.dsva_chrome	dedicated browser profile directory
DSVA_HEADED=1	—	force the browser window to show

变量	默认值	说明
CHROME_PATH	自动探测	指定 Chrome / Edge 路径
DSVA_PORT	9223	CDP 调试端口
DSVA_PROFILE	~/.dsva_chrome	独立浏览器配置目录
DSVA_HEADED=1	—	强制显示浏览器窗口

The login state is stored in ~/.dsva_token. Note: login must happen in the Chrome window popped up by deepseek-vision-analyzer (~/.dsva_chrome is a dedicated profile); logging in from your everyday browser does not count.

登录状态保存在 ~/.dsva_token。注意:登录必须发生在 deepseek-vision-analyzer 弹出的 Chrome 窗口里(~/.dsva_chrome 是独立配置),日常浏览器里登录无效。

Troubleshooting

故障排查

Symptom	Fix
Chrome failed to start (exit 3)	Install Chrome / Edge, or set CHROME_PATH
Login window pops up	Log in there and it continues automatically; no SMS = risk control triggered, cool down and retry
Answer timed out / missing	SPA slow or server busy, retry once
wait timeout: xxx	Usually a UI change or slow network, retry; if persistent see references/DEVELOPMENT.md

现象	处理
Chrome 启动失败(exit 3)	装 Chrome / Edge,或设置 CHROME_PATH
弹出登录窗口	在窗口里登录后自动继续;收不到短信 = 触发风控,冷却后再试
回答超时 / 未出现	SPA 加载慢或服务端繁忙,重试一次
等待超时: xxx	多为 UI 改版或网络慢,重试;持续失败见 references/DEVELOPMENT.md

Dependencies & Limitations

依赖与限制

• Requires Node ≥ 22 and system Chrome / Edge; optionally npm i jpeg-js pngjs improves captcha auto-solving (pure JS, no compilation)

• Depends on the current state of the DeepSeek web app; a redesign can break the tool — troubleshooting and reverse-engineering notes in references/DEVELOPMENT.md

• This repository doubles as a Claude / opencode Skill; see skills/deepseek-vision-analyzer/SKILL.md for agent-side triggers and calling conventions

• 需要 Node ≥ 22 与系统 Chrome / Edge;可选 npm i jpeg-js pngjs 提升验证码自动通过率(纯 JS,零编译)

• 依赖 DeepSeek 网页版的现状,改版可能导致工具失效——排查与逆向知识见 references/DEVELOPMENT.md

• 本仓库同时是 Claude / opencode 的 Skill,Agent 侧的触发条件与调用约定见 skills/deepseek-vision-analyzer/SKILL.md

Acknowledgments

致谢

This project is inspired by menghuanshiguang/deepseek-vision-cli. Thanks to menghuanshiguang for the open-source contribution.

本项目受到 menghuanshiguang/deepseek-vision-cli 的启发,在此感谢 menghuanshiguang 的开源贡献。

Disclaimer

免责声明

• This project implements image recognition by driving the DeepSeek Chat web app through browser automation, relying on its current page structure and APIs. DeepSeek may change web features, APIs, or the login flow at any time, partially or fully breaking this tool; no continuous availability is guaranteed.

• This project is for learning and research only. Usage may trigger account risk control (e.g., failing to receive SMS codes). Please assess the risks yourself and comply with DeepSeek's terms of service; any consequences are borne by the user.

• 本项目通过浏览器自动化驱动 DeepSeek Chat 网页版实现识图,依赖其当前的页面结构与接口。DeepSeek 官方随时可能调整网页功能、接口或登录流程,导致工具部分或完全失效,本项目不保证持续可用。

• 本项目仅供学习研究使用。使用过程中可能触发账号风控(如收不到验证短信),请自行评估风险并遵守 DeepSeek 服务条款,由此产生的任何后果由使用者自行承担。