一句话定位

DSH 插件，把 DeepSeek 网页版视觉与 OCR 能力封装为宿主级原生工具（无需 API Key），并补齐"纯文本模型粘贴图片就被拒绝"的桥接能力。

核心能力

• 注册 5 个 DSH 原生工具：deepseek_vision（识图，支持多图/续聊）、deepseek_ocr（纯文字提取）、deepseek_vision_status（登录状态）、deepseek_vision_login（浏览器自动登录）、deepseek_vision_logout（清除凭据）
• 复用 visionary-server Rust 二进制处理 PoW、上传、fork、HIF、SSE 等重活，插件仅做参数映射与 JSON 解析
• 在宿主进程内直接执行（不经 bash 沙箱），所以浏览器登录与多轮会话续聊不受工作区写权限限制
• 为纯文本模型（如 deepseek-v4-flash）自动桥接粘贴图片：落盘到 pastedDir 后改写为引导文本，由 agent 调 deepseek_vision 完成分析
• 设置面板与 $DSH_HOME/settings.yaml 双入口，修改即时热重载，无需重启 DSH
• 桥接支持 deterministic 模式：直接调用 CLI 完成分析并以"不可信证据"标注注入模型消息

技术实现

• 语言: Node.js（ESM，"type": "module"）
• 关键依赖: @deepseek-ai/dsh-tools（defineTool）、@deepseek-ai/dsh-settings（installSettingsSection）、@deepseek-ai/dsh-attachment、@deepseek-ai/cordis + @deepseek-ai/schemastery（运行时配置 schema）
• 架构模式: Cordis 插件，通过 packages/dsh-plugin/cordis.patch.yml 在 dsh.profile.bundles 叠加层注册 3 个插件行（visionary-vision、visionary-image-bridge、visionary-settings-card）；exec.signal 与子进程 kill 联动实现可取消超时
• 入口文件: packages/dsh-plugin/lib/index.mjs（主工具集），子路径 lib/image-bridge/index.mjs、lib/settings-card/index.mjs

适用场景

在 DeepSeek Harness 中希望让模型"看懂"用户粘贴的图片、截图、文档，但不愿自备 API Key 或受限于 bash 沙箱的开发者。特别适用于使用纯文本模型（如 deepseek-v4-flash）又希望支持图片输入的用户，以及需要在多个工具调用之间对同一张图做多轮追问的场景。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:xlight/deepseek-visionary#path:packages/dsh-plugin

配置项

visionary-vision 命名空间（视觉工具配置）：

visionary-image-bridge 命名空间（图片桥接配置）：

常见问题

Q: 安装后工具没出现在 DSH 工具列表里怎么办？

A: 确认通过 dsh plugin --profile web add 安装成功，并已重启 DSH（bundle 装载需要重启）。可用 dsh --profile web --dump-config 检查是否出现 @xlight-oss/visionary-dsh 层，且其中包含 visionary-vision 与 visionary-image-bridge 两行。

Q: 需要 DeepSeek API Key 吗？

A: 不需要。本插件调用的是 DeepSeek 网页版视觉模型（chat.deepseek.com），通过浏览器自动登录复用网页端凭据；首次使用前需运行 deepseek_vision_login 完成登录，凭据保存到 ~/.deepseek-visionary/config.json，与 skill/CLI/MCP 路径共用。

Q: 纯文本模型粘贴图片被宿主拒绝，怎么开启桥接？

A: visionary-image-bridge 默认开启（enabled: true）。如果被关闭，前往"设置 → 左侧导航 → Visionary"将 enabled 重新打开；如显式配置了 routes，需要把当前会话的 provider/model 列入白名单。设置面板修改无需重启 DSH。

Q: 图片和会话数据保存在哪里？会自动清理吗？

A: 桥接会把粘贴图片落到 ~/.deepseek-visionary/pasted（目录权限 0700、文件 0600），按 retainHours 默认 7 天惰性清理；宿主附件库中的原始图片字节永久保留，不受 retainHours 影响，如需彻底删除请清除对应会话。

Q: 如何卸载插件？

A: 使用 dsh plugin --profile web remove @xlight-oss/visionary-dsh 卸载并重启 DSH。卸载后纯文本模型粘贴图片会恢复为宿主原行为（直接拒绝）。

Q: deepseek_vision 报 File ... processing failed: status=CONTENT_EMPTY 怎么办？

A: 这是上游二进制已知问题：后端会对上传图片做 OCR 文本提取，纯插画、渐变、深色无文字图会被标记 CONTENT_EMPTY。已在 visionary-server ≥0.5.x 修复（不再中止，继续走 vision 模型）。请按 README 指引重新安装最新二进制。

Q: 支持哪些操作系统？二进制怎么装？

A: 插件本体跨平台。visionary-server 在 macOS、Linux、Windows 都提供安装脚本（一键安装脚本、Homebrew、npm install -g）；Windows 下插件会额外解析 npm shim（.cmd / .ps1）文本，定位包内 .bin_real/visionary-server.exe 真身来避免丢 stdout 管道与孤儿进程。

上手难度

入门 — 安装即用，工具自动出现在 DSH 中；只有当默认行为不符合预期（如只想桥接特定模型、想关闭 deterministic 模式）时才需要进设置面板调配置。

已知问题与限制

• 上游二进制旧版（<0.5.x）会在无 OCR 文字的图片（如纯插画/渐变/纯色）上报 CONTENT_EMPTY 并中止；用户必须升级 visionary-server 到 ≥0.5.x 才能正常使用
• 落盘副本（pastedDir）按 retainHours 独立清理，与宿主附件库永久保留策略分离：清理可能删掉旧会话仍在引用的路径副本，导致用户很久后翻旧会话重分析拿到失效路径；可通过调大 retainHours 或设为 <= 0 缓解
• Windows 上 binaryPath 解析依赖 shim 文本匹配 node_modules\@xlight-oss\visionary-server\run-visionary-server.js 模式；若通过非常规方式（如手动改名/自定义目录结构）安装，二进制可能找不到并返回安装指引错误
• 自定义 promptTemplate 必须含 {path} 占位符，缺失会被设置面板写入与加载两侧拒绝（fail-loud）；自定义时需自行保留"不可信证据"框架以避免提示注入面
• 设置面板的 Visionary 入口依赖宿主 webServer / settings 服务；只读部署或未启用 Web 面板的宿主演示为「设置服务不可用」
• settings-card 插件行提供独立的 /visionary/api/settings.* 路由（loopback + Origin 校验），目的是绕过宿主 settings.describe 对第三方命名空间的白名单；禁用该插件行会导致面板不可用，但不影响工具与桥接行

DeepSeek Visionary

让 DeepSeek 网页版视觉模型，成为你所有 AI 助手的"眼睛"。 在 Zed、OpenCode、Codex、Claude Code、Cursor、Claude Desktop 等任意支持 MCP 的 agent，以及 DeepSeek Harness（DSH，原生插件或 skill + CLI）中直接识图——浏览器自动登录，无需 API key、无需手动复制 token。

Python 版 deepseek-vision-mcp 的 Rust 全量重写：单原生二进制、多平台分发，一处安装处处可用。DSH 用户更可 dsh plugin 一键安装原生插件包 @xlight-oss/visionary-dsh——4 个原生视觉工具 + 文本模型图片桥接，一包全齐。

架构

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 / 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 / status / login / logout / skill / init / doctor），mcp-stdio 子命令显式启动 MCP stdio 服务；实现完整 vision 流水线（PoW → 上传 → fork → HIF 签名 → SSE 流式 completion）与 CDP 自动登录
• @xlight-oss/visionary-dsh：DSH 原生插件包（npm，纯 ESM 无构建，单包双插件行），经 ctx.tools 注册 deepseek_vision / deepseek_ocr 等 5 个原生工具，宿主进程内 spawn visionary-server 复用 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 agent 中调用 vision 识图，无需任何 MCP 配置。首次使用先登录：

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

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

给 AI agent 使用时，把内嵌的调用契约 skill 装进 agent 的 skills 目录，agent 即学会以 --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

各 agent 的详细接入文档见 docs/integrations/：

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 --profile web --dump-config 应出现单个 @xlight-oss/visionary-dsh 层。详见 packages/dsh-plugin/README.md。

文本模型下粘贴图片被拒绝？ 本插件已内置图片桥接（visionary-image-bridge 插件行，无需额外安装）： 纯文本模型会话中粘贴的图片经桥接放行 → 落盘 → 改写为文本引导， agent 用 deepseek_vision 完成分析，模型只收到文本；VL 模型原生看图不受干扰。 配置/隐私说明见 packages/dsh-plugin/README.md 的「工具」与「图片桥接」节（设置面板 → 左侧导航 → Visionary，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 工具

CLI 输出模式（vision）

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

--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 宿主，也以 DSH 原生工具注册给 DeepSeek Harness（命名与 schema 一致）：

质量提示：OCR 结果来自服务端文本提取管道，对清晰截图/文档效果好；放大模糊、手写或复杂版式时结果可能不完整。需要结合上下文理解内容（翻译、总结版式）时用 deepseek_vision，deepseek_ocr 只负责拿原文。

会话续聊

deepseek_vision（及 deepseek_ocr）支持多轮对话：

• continue_conversation=true：复用上一次会话，可对比多张图片
• session_id：显式切换到指定会话线程

会话状态持久化在 ~/.deepseek-visionary/session.json。

环境变量

开发

# 构建原生服务
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 系浏览器（专用 profile ~/.deepseek-visionary/browser/），读取 localStorage.userToken 与 smidV2 / cf_clearance cookie
• 凭据安全：~/.deepseek-visionary/config.json 权限 0600，浏览器 profile 0700

License

MIT