DeepSeek Visionary

DeepSeek Visionary

DeepSeek のウェブ版ビジョンモデルを、あらゆる AI アシスタントの「目」にしましょう。 Zed、OpenCode、Codex、Claude Code、Cursor、Claude Desktop など、MCP に対応する任意のエージェントや DeepSeek Harness（DSH、ネイティブプラグインまたは skill + CLI）で、画像を直接認識できます。ブラウザーが自動でログインするため、API key も token の手動コピーも不要です。

Python 版 deepseek-vision-mcp を Rust で全面的に書き換えました。単一のネイティブバイナリをマルチプラットフォームで配布し、一度インストールするだけでどこでも使えます。DSH ユーザーは dsh plugin でネイティブプラグインパッケージ @xlight-oss/visionary-dsh をワンクリックでインストールできます。5 つのネイティブツールにテキストモデル向け画像ブリッジを加えた、必要なものがすべてそろったパッケージです。

アーキテクチャ

graph TD
    subgraph 宿主[任意 MCP 宿主]
        AG["Zed / OpenCode / Codex / Claude Code / Cursor / Claude Desktop"]
        AG -->|spawn 独立进程| SRV
    end
    subgraph DSH[DeepSeek Harness]
        DP["@xlight-oss/visionary-dsh 插件<br/>deepseek_vision 等 5 个原生工具<br/>+ 文本模型图片桥接"]
        DP -->|宿主进程 spawn| SRV
    end
    subgraph visionary-server 原生二进制
        SRV["CLI + MCP stdio 服务<br/>vision / ocr / status / login / logout / skill / init / doctor<br/>mcp-stdio CLI"]
        CFG["~/.deepseek-visionary/config.json<br/>token + smidV2 + cf_clearance + 会话"]
        SRV --> CFG
    end
    SRV -->|HTTPS| DS["DeepSeek 网页后端"]
    SRV -->|CDP 启动 + 监听| BRO["Chrome 系浏览器<br/>仅登录时出现"]

• visionary-server：単一バイナリで、デフォルトは CLI モード（vision / ocr / status / login / logout / skill / init / doctor）です。mcp-stdio サブコマンドで MCP stdio サービスを明示的に起動します。完全な vision / OCR パイプライン（PoW → アップロード → fork → HIF 署名 → SSE ストリーミング completion）と CDP 自動ログインを実装しています
• @xlight-oss/visionary-dsh：DSH ネイティブプラグインパッケージ（npm、ビルド不要の純粋な ESM、単一パッケージに 2 つのプラグインを同梱）です。ctx.tools 経由で deepseek_vision / deepseek_ocr など 5 つのネイティブツールを登録し、ホストプロセス内で visionary-server を spawn して Rust のパイプラインを再利用します（継続会話／ログインは bash サンドボックスの制限を受けません）。テキストモデル向けの画像ブリッジを内蔵しており、テキスト専用モデルのセッションで貼り付けた画像を自動的に受け入れ、テキストによる案内に書き換えます
• visionary-zed-ext：Zed 拡張機能のシェル（Zed のみ必要）です。プラットフォームに応じて GitHub Releases から visionary-server をダウンロード／キャッシュして起動します

インストール

1. バイナリをインストールする

# macOS / Linux 一键脚本
curl -LsSf https://github.com/xlight/deepseek-visionary/releases/latest/download/visionary-server-installer.sh | sh

# Windows（PowerShell 一键，自动绕过执行策略）
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/xlight/deepseek-visionary/releases/latest/download/visionary-server-installer.ps1 | iex"

# 或 Homebrew
brew install xlight/tap/visionary-server

# 或 npm（全平台）
npm install -g @xlight-oss/visionary-server

GitHub Releases から、お使いのプラットフォームに対応する visionary-server-<target-triple> のバイナリを直接ダウンロードして PATH に追加することもできます（Windows では .exe、または .zip を解凍してください）。 Windows のインストールスクリプトは、デフォルトで $HOME\.cargo\bin にインストールして PATH に自動追加します（-NoModifyPath を指定するとスキップできます）。このディレクトリは cargo-dist のデフォルトの命名規則にすぎず、cargo のインストールは不要です。Rust を使わないユーザーは、環境変数 VISIONARY_SERVER_INSTALL_DIR でインストール先を変更するか、npm のグローバルパッケージを直接使用できます。初回起動時に SmartScreen の警告が表示された場合は、「詳細情報 → 実行」をクリックしてください。 npm グローバルパッケージに関する注意：Windows では npm install -g @xlight-oss/visionary-server を実行すると、PATH に shim（.cmd / .ps1）のみが追加されます。DSH ネイティブプラグインは shim から実際の exe の場所を自動的に特定します。インストール後に DSH を再起動すれば使用できます。

2. クイックスタート（CLI + skill、推奨）

CLI は設定不要で使える入口です。インストール後すぐに、ターミナル／スクリプト／AI エージェントから vision を呼び出して画像を認識できます。MCP の設定は必要ありません。初回利用時は、まずログインしてください。

# 浏览器自动登录（后续无需重复）
visionary-server login

# 识图（agent/脚本调用务必加 --json 原子输出）
visionary-server vision screenshot.png
visionary-server vision img.png --json --prompt "图中有什么？" --thinking

AI エージェントで使う場合は、組み込みの呼び出し契約 skill をエージェントの skills ディレクトリにインストールしてください。エージェントは --json によるアトミックな出力で正しく呼び出す方法を学習します。

# skill 内嵌于二进制，一条命令安装/更新
visionary-server skill install
# → 写入 ~/.agents/skills/visionary-cli/SKILL.md
# 可将该目录移动到所用 agent 的默认 skills 目录

3. 応用：MCP ホストに接続する

deepseek_vision を MCP ツールとしてホスト（Zed / OpenCode / Codex / Claude Code / Cursor / Claude Desktop）に公開するには、init で一括設定します。

# 一键检测并接入（列出已安装 agent）
visionary-server init

# 接入指定 agent
visionary-server init opencode
visionary-server init codex
visionary-server init claude
visionary-server init cursor
visionary-server init claude-desktop
visionary-server init dsh   # DeepSeek Harness（skill + CLI 轻量接入）

# 批量接入多个 agent（免交互）
visionary-server init --opencode --codex --dsh --yes

# 先预览将写入的配置（不落盘）
visionary-server init opencode --dry-run

各エージェントの詳しい接続手順については、docs/integrations/ を参照してください。

エージェント	ドキュメント	ワンクリックコマンド
Zed	zed.md	拡張機能マーケットプレイスからインストール（下記参照）
OpenCode	opencode.md	visionary-server init opencode
Codex	codex.md	visionary-server init codex
Claude Code	claude-code.md	visionary-server init claude
Cursor	cursor.md	visionary-server init cursor
Claude Desktop	claude-desktop.md	visionary-server init claude-desktop
DeepSeek Harness	deepseek-harness.md	ネイティブプラグイン dsh plugin --profile web add @xlight-oss/visionary-dsh（推奨）、または visionary-server init dsh（skill + CLI による軽量な接続）

DeepSeek Harness ネイティブプラグイン：DSH ユーザーは npm プラグインパッケージ @xlight-oss/visionary-dsh もインストールできます。deepseek_vision / deepseek_ocr / deepseek_vision_status / deepseek_vision_login / deepseek_vision_logout を DSH ネイティブツールとして登録できます（構造化 schema、ホストレベルでの実行に対応し、継続会話／ログインは bash サンドボックスの制限を受けません）。インストール方法については packages/dsh-plugin/README.md を参照してください。

新しい接続方法：Microsoft Agent Package Manager のユーザーは、次のコマンドを直接実行できます。 apm install --mcp io.github.xlight/deepseek-visionary（MCP Registry 識別子を再利用します）。

4. DeepSeek Harness 原生插件（DSH 用户推荐）

DSH 用户除 init dsh（skill + CLI）外，更推荐安装原生插件，获得宿主级权限与结构化工具 schema：

# 前置：安装二进制（见上文）并确保能被插件找到
#       （Config.binaryPath → DEEPSEEK_VISIONARY_BIN → PATH 任一即可）

# 一键安装（npm 包，发布后）
dsh plugin --profile web add @xlight-oss/visionary-dsh

# 或本地路径（开发验证）
dsh plugin --profile web add /path/to/packages/dsh-plugin

dsh plugin 经包内 dsh.bundle.patch 声明自动注册 visionary-vision、visionary-image-bridge 两个插件行，重启 DSH 后 5 个原生工具出现在工具目录，桥接同时生效（模型可直接调用，无需手写任何配置）；两行的配置页由包自身 dsh.client 声明、随主行下发，在 设置 → 插件 → Plugins 打开（不额外占插件行）。验证：dsh --profile web --dump-config 应出现单个 @xlight-oss/visionary-dsh 层。要求 DSH ≥ 0.1.7-rc.1（0.1.5 线请固定 @xlight-oss/[email protected]，更早的装 0.7.2）。详见 packages/dsh-plugin/README.md。

文本模型下粘贴图片被拒绝？ 本插件已内置图片桥接（visionary-image-bridge 插件行，无需额外安装）： 纯文本模型会话中粘贴的图片经桥接放行 → 落盘 → 改写为文本引导， agent 用 deepseek_vision 完成分析，模型只收到文本；VL 模型原生看图不受干扰。 配置/隐私说明见 packages/dsh-plugin/README.md 的「工具」与「图片桥接」节（设置面板 设置 → 插件 → Plugins 下的两个行配置页，对应 visionary-vision: / visionary-image-bridge: settings 命名空间，热重载）。

5. 登录

登录凭据保存在 ~/.deepseek-visionary/config.json，CLI / MCP / DSH 插件三路共享；浏览器自动登录会打开窗口导航到 chat.deepseek.com，登录后自动抓取 token 并保存：

• CLI：visionary-server login（可先 status --json 预检）
• MCP / DSH 原生工具：调用 deepseek_vision_login

手动兜底：登录 chat.deepseek.com 后，DevTools → Application → Local Storage → userToken → 复制 JSON.parse(value).value，写入 ~/.deepseek-visionary/config.json：

{ "user_token": "你的 token" }

6. 使用

• CLI：visionary-server vision <image> 识图（详见下文「CLI 工具」）
• MCP / DSH 原生工具：调用 deepseek_vision 传入图片路径 / base64 / data URI 即可识图

Zed 扩展安装

如果你只用 Zed，也可以直接从扩展市场安装：

1. Zed 命令面板（Cmd+Shift+P）→ zed: extensions → 搜索 DeepSeek Visionary → Install
2. 扩展壳自动下载/缓存 visionary-server 二进制并启动 MCP 服务
3. 授权工具权限（见 docs/integrations/zed.md）

CLI 工具

命令	说明
visionary-server（无参数）	输出 help 用法信息并退出码 2（不进入任何模式）
visionary-server --version	输出版本号
visionary-server mcp-stdio	显式启动 MCP stdio 服务（MCP 模式入口，所有 agent 配置均以此启动）
visionary-server vision <image>...	用视觉模型分析一张或多张图片（CLI 版 deepseek_vision）。image 支持路径 / base64 / data URI / -（stdin，仅单图）；多图一次上传联合分析（与网页端多图行为一致）；--prompt / --thinking / --continue-conversation / --session-id / --json / --stream / --no-stream / --model-type（vision 或 ocr，默认 vision）
visionary-server ocr <image>...	用纯 OCR 管道原样提取图片中的文字（CLI 版 deepseek_ocr，等价 vision --model-type ocr）。参数面对齐 vision（无 --model-type，恒为 ocr）；默认提示词为文字提取语义；无文字图片输出业务提示并退出非零
visionary-server status	轻量鉴权状态检查（CLI 版 deepseek_vision_status），--json 输出结构化状态
visionary-server login	浏览器自动登录（CLI 版 deepseek_vision_login）
visionary-server logout	清除保存的凭据（CLI 版 deepseek_vision_logout）
visionary-server skill install	安装 agent 调用契约 skill 到 ~/.agents/skills/（内嵌于二进制）
visionary-server doctor	诊断环境：config 路径/权限、浏览器、token 有效性、平台
visionary-server init [agent]	检测并接入已安装的 AI agent（--dry-run / --yes / 多选 flags，含 dsh）

CLI 输出模式（vision）

vision 的输出模式由 stdout 是否 TTY 与显式开关共同决定：

场景	默认行为	消费方
终端（TTY）	流式打印回答文本	人
管道/脚本（非 TTY）	一次性输出完整文本	脚本兑底
visionary-server vision img.png --json	原子 JSON：{"text", "session_id", "parent_message_id"}（失败为 {"error"}）	脚本 / AI agent（推荐）

--stream / --no-stream 可强制指定模式；--json 恒为原子输出（不与 --stream 同用）。失败时退出码非零。

# 终端交互：流式输出
visionary-server vision screenshot.png

# 脚本/agent：结构化输出
visionary-server vision img.png --json --prompt "图中有什么？"

# 管道输入
cat img.png | visionary-server vision - --json

AI agent 使用（CLI + Skill）

CLI 也是 AI agent 的零 MCP 配置工具面：只要 visionary-server 在 PATH，任何能执行 shell 的 agent 都可以调用它。二进制内嵌 agent 调用契约 SKILL.md（随安装具备），核心约定：agent 调用 vision 必须加 --json 原子输出（流式文本无结构化边界，不可可靠解析）。

安装 skill 到 agent skill 目录（以 Zed 为例）：

# skill 内嵌于二进制，无需本地仓库，一条命令安装/更新
visionary-server skill install
# → 写入 ~/.agents/skills/visionary-cli/SKILL.md

DeepSeek Harness（DSH）：DSH 默认扫描 ~/.agents/skills 与 ~/.dsh/skills 作为技能根，上述位置天然兼容；运行 visionary-server init dsh 会额外写入 DSH 专属技能根并汇总提示（见 deepseek-harness.md）。DSH 用户更推荐安装原生插件 @xlight-oss/visionary-dsh（dsh plugin --profile web add），把 deepseek_vision 等注册为宿主级原生工具，续聊/登录不受 bash 沙箱限制（见 packages/dsh-plugin/README.md）。

ツール（MCP / DSH ネイティブ）

同じツール群を、MCP ホストには MCP ツールとして公開し、DeepSeek Harness には DSH ネイティブツールとして登録します（名前とスキーマは共通です）：

ツール	説明
deepseek_vision	1 枚以上の画像（パス / base64 / data URI）をアップロードし、DeepSeek のビジョンモデルで分析します。複数画像は images 配列で一度にアップロードし、モデルがまとめて分析します（ウェブ版の複数画像の動作と同じです）。パラメーター：images（複数画像）/ image（単一画像、後方互換性あり、どちらか一方）、prompt、thinking、continue_conversation、session_id
deepseek_ocr	純粋な OCR パイプラインを使い、画像内のテキストをそのまま抽出します（CLI の visionary-server ocr と同等）。内容の理解ではなく、テキストの抽出に特化しています：スクリーンショット / ドキュメント / コード / 表 / 標識。パラメーターは deepseek_vision と完全に同じです。画像にテキストがない場合は、エラーメッセージ「画像からテキストを抽出できませんでした」を返します
deepseek_vision_status	ログイン状態とトークンの有効性を確認します（実際の検証プローブを含む）
deepseek_vision_login	ブラウザーで自動ログインし、認証情報を取得します（ブロッキング処理、タイムアウトは設定可能）
deepseek_vision_logout	保存済みの認証情報を消去します

品質に関する注意：OCR の結果はサーバー側のテキスト抽出パイプラインによるもので、鮮明なスクリーンショットやドキュメントでは良好な結果が得られます。拡大したぼやけた画像、手書き、複雑なレイアウトでは、結果が不完全になる場合があります。内容の理解（翻訳、レイアウトの要約など）に文脈が必要な場合は deepseek_vision を使用してください。deepseek_ocr は原文の取得のみを担当します。

会話の継続

deepseek_vision（および deepseek_ocr）は複数ターンの会話に対応しています：

• continue_conversation=true：直前の会話を再利用し、複数の画像を比較できます
• session_id：指定した会話スレッドに明示的に切り替えます

会話状態は ~/.deepseek-visionary/session.json に永続化されます。

環境変数

変数	説明
DEEPSEEK_USER_TOKEN	config.json のトークンを上書きします（任意）
DEEPSEEK_SMIDV2 / DEEPSEEK_CF_CLEARANCE	対応する cookie を上書きします（任意）
DEEPSEEK_BASE_URL	API のベース URL（デフォルトは https://chat.deepseek.com）
DEEPSEEK_LOGIN_TIMEOUT	ログイン待機のタイムアウト秒数（デフォルトは 600）
DEEPSEEK_VISIONARY_MODEL_TYPE	デフォルトのアップロードパイプラインのモデルタイプ（vision または ocr、デフォルトは vision。CLI の --model-type がこの変数より優先されます）
DEEPSEEK_VISIONARY_BIN	DSH プラグインがバイナリのパスを解決する際の指定順（Config.binaryPath → この変数 → PATH）

開発

# 构建原生服务
cargo build -p visionary-server --release

# 构建扩展壳（wasm32-wasip2）
rustup target add wasm32-wasip2
cargo build -p visionary-zed-ext --release --target wasm32-wasip2

# 测试
cargo test -p visionary-server

# DSH 插件包（纯 ESM，无构建；开发需装 devDependencies 供本地 link 安装解析 peer）
cd packages/dsh-plugin && pnpm install

リリース

バージョン番号は scripts/bump_version.py で一元管理します（Cargo.toml / Cargo.lock×2 / extension.toml / packages/dsh-plugin/package.json / packages/dsh-plugin/lib/index.mjs の COMPAT_MINOR / server.json の計 7 つのバージョン項目を同期し、一貫性を検証します）：

# 只 bump + 校验 + 打印步骤
python3 scripts/bump_version.py <new-version>

# 一键发布：bump + commit + tag vX.Y.Z + push
# （tag push 触发 cargo-dist 二进制发布 / Zed 扩展同步 / npm 发布三个 workflow）
python3 scripts/bump_version.py <new-version> --release

リリース完了後、update-server-json workflow（workflow_run が Release の成功を監視）が 5 プラットフォームの .mcpb を自動ダウンロードし、 scripts/update_server_json.py を実行して、server.json の fileSha256 に実際の成果物のハッシュを反映します（MCP Registry のメタデータ。commit を main に反映）。 この workflow が起動しなかった場合（手動で release を作成した場合など）は、手動で補完できます：

gh release download v<version> --pattern "*.mcpb" --dir dist --clobber
python3 scripts/update_server_json.py <version> v<version> dist/

プラットフォームのサポート

• macOS（Apple Silicon / Intel）
• Linux（x86_64 / aarch64）
• Windows（x86_64）

自動ログインには、Chrome / Chromium / Edge のいずれかが必要です。

動作の仕組み（要点）

• PoW：wasmtime で DeepSeek サイト内の sha3_wasm_bg.*.wasm（リポジトリに同梱）を読み込み、wasm_solve を呼び出して upload_file と completion の challenge を解決します
• TLS フィンガープリント：completion エンドポイントは Python 版（curl_cffi chrome131）に合わせています。Rust 側ではデフォルトで通常の reqwest を使用し、403 が発生した場合はフィンガープリントの模倣を有効にします（design.md の spike 記録を参照）
• ログイン：CDP で Chrome 系ブラウザーを制御し、専用プロファイル ~/.deepseek-visionary/browser/ から localStorage.userToken と smidV2 / cf_clearance cookie を読み取ります
• 認証情報の保護：~/.deepseek-visionary/config.json の権限は 0600、ブラウザープロファイルの権限は 0700 です

ライセンス

MIT