前言¶

DeepSeek Harness（dsh）是 DeepSeek 开源的智能体运行时，官方定位是开发者预览版，口号是「一切皆插件」：模型适配、工具注册、会话日志、Agent 循环，都可以用插件替换，而不必改运行时源码。启动 Web UI 的官方入口是：

npx @deepseek-ai/dsh web

编码智能体这边更常见的缺口是另一面：DeepSeek、GLM 这类主力对话模型是纯文本的，看不见图。报错界面、设计稿、长聊天截图、前端渲染结果，往往只能先口述，再让模型猜。社区目录 deepseek-harness-plugin.com 是独立站点，与 DeepSeek / 幻方没有官方从属关系；它把这类扩展按分类收录，其中「工具与能力」下有一个被标成精选的插件：agent-vision-toolkit。

本文按该目录详情页、GitHub 仓库 README / README_CN / AGENT_INSTALL.md、许可证，以及 DeepSeek Harness 官方说明核对后整理：它是什么、工具怎么分工、命令怎么写、和原生 dsh 接入包是什么关系。

这是什么¶

agent-vision-toolkit 由 Anionex 维护，仓库地址是 Anionex/agent-vision-toolkit，许可证 MIT，主要语言 Python。仓库创建于 2026-08-01。社区目录把它分在「工具与能力」，收录日期 2026-08-14；GitHub API 在 2026-08-17 显示 950 star（目录页快照为 874，星标以仓库页面为准）。项目主页是 agent-vision.anionex.me。

目录页和仓库 README 的定位一致：给纯文本编码智能体装上眼睛。它提供的不是「把图片丢给多模态模型，拿回一段通用描述」，而是一套视觉工具箱，外加一份教 agent 何时调用、按什么顺序验收的 skill。仓库写明已在真实 Codex + DeepSeek 会话中验证，同一套管线也在 Claude Code、Pi、Oh My Pi、OpenCode 里做过端到端验证。

仓库把内容分成两类：

1. 视觉工具 CLI + skill：glance、ground、detect、trace、crop 等命令行工具，加上 vision-tools skill。任何能调 shell 的 agent 都能用。
2. 无缝接入（可选升级）：本地透明代理，或单文件原生扩展。装上之后，直接粘贴的图片和 agent 内置看图工具都可以走通，不必再额外提示。

2026-08-13 起，同一维护者另开了原生 DeepSeek Harness 接入包 dsh-vision-toolkit（npm：@anionex/dsh-vision-toolkit）。它以 Git submodule 链在本仓库里，把上述工具箱做成 Web / Headless Profile 的 Bundle。社区目录里也有单独条目。本文以工具箱本体为主，原生 dsh 安装只在后文单独说明。

核心功能¶

1. 带意图的看图，而不是一段空泛描述¶

仓库 README 把常见「缝合方案」的损失写得很直接：多数转接只是让多模态模型生成一段通用描述，再交给纯文本模型去拼。中间多了一层语义，当前这一步真正要用的细节容易被冲掉。

agent-vision-toolkit 的做法是先抽出 agent 为什么要看这张图。来源可以是用户消息，也可以是模型调用内置看图工具时自述的理由；这段动机作为 focus hint 一并交给视觉模型。拿回来的是贴合当前任务的描述，而不是「详细描述一下这张图」。仓库把它概括成：视觉能力不一定长在模型上，也可以长在 harness 上。

它仍然是图片转文字的一层，不会把视觉 token 直接交给纯文本模型。整体质量由主模型和多模态模型共同决定。这一点仓库自己列在限制里。

2. 一组可组合的 CLI¶

工具按问题选型，而不是一个万能入口：

glance 只需要 Python 3.11+。ground / detect / crop 以及长截图 OCR 用例需要 pillow；trace 需要 pillow + numpy，只有显式使用 --outline 轮廓回退时才需要 vtracer。仓库建议只为实际用到的工具在隔离 venv 里装可选依赖。

坐标约定是原图像素。ground / detect 打出的盒子可以直接喂给 crop 或 trace；同一个区域后面还要做多次检查时，先裁成文件再复用。

3. vision-tools skill 与用例 playbook¶

CLI 只解决「怎么调」。skill 解决「什么时候调、按什么顺序、最后怎么验收」。随仓库提供的 vision-tools 里有一组可对照执行的用例，文档在 skills/vision-tools/references/：

• 长截图 / 聊天记录 / 滚动页面：找低内容切口，按块 OCR，保留发言人、时间和引用，只合并确实重复的重叠，并标出需要复查的边界。仓库给了 Telegram 实跑示例。
• 按截图或设计稿还原 UI：优先复用项目已有组件和素材，再结合原生 UI 代码、截图、渲染结果和视觉对比，逐轮对齐。
• 还原图标、Logo、插画：提取透明 PNG；需要可编辑或无损缩放时重建 SVG，并核形状、颜色和透明边缘。
• 草图 / 示意图 / 白板 → 结构化代码：识别节点、文字、连线和方向，输出 Mermaid、Graphviz 等。
• 按截图操作 GUI：定位控件、执行一次操作、重新截图并验证，再继续下一步，避免在过期截图上连续点。

仓库 README 还记录了若干原样效果，用来说明粒度，不是第三方评测：信息图截图还原成可编辑 HTML/CSS；手绘稿还原 JupyterLab 工作区（Codex + deepseek-v4-flash）；快速 UI 还原以约三分钟给出第一张截图；用 glance 做多轮图片问答；用 ground 定位屏幕元素、DeepSeek V4 自主下棋；按截图排查字段名不符预期。

4. 可选的无缝接入层¶

CLI 适合「agent 自己调 shell」。若希望粘贴图片和内置看图工具也直接可用，仓库提供可选接入：

代理不保存上游文本模型的 API key。Codex / Claude Code 原有的 Authorization 原样转发；代理 env 只配视觉侧的 VISION_API_KEY、VISION_BASE_URL、VISION_MODEL。完整步骤在 AGENT_INSTALL.md，安装前要求先备份宿主配置。

安装与启用¶

社区目录给出的命令¶

插件详情页上的安装命令原文是：

dsh plugin add github:Anionex/agent-vision-toolkit

需要可复现安装时，目录页要求固定 commit 哈希：

dsh plugin add github:Anionex/agent-vision-toolkit#<commit>

目录页同时提示：插件以当前 dsh 进程的权限运行，安装时可能执行代码；安装前应检查源代码仓库和许可证。

需要先说清边界。写作时该仓库根目录没有 package.json，也没有 dsh.bundle 声明。DeepSeek Harness 官方文档写过：没有 dsh.bundle 的包仍可被 dsh plugin add 装进 profile，但只会作为普通依赖，打印警告，不会激活配置层。因此这条目录命令对应的是 GitHub 源码仓库，并不等于「装完就能在 Web UI 里粘贴图片」。dsh Web / Headless 上的原生 Bundle，维护者写明走下面的 @anionex/dsh-vision-toolkit。

仓库推荐：让 agent 按文档安装¶

最省事的方式是把这句话发给当前 agent（原文来自 README_CN）：

根据 https://github.com/Anionex/agent-vision-toolkit 的仓库指引，在本地安装视觉工具箱和 skill。如果视觉 API 尚未配置，请按当前系统找到配置文件，并引导我填写 VISION_API_KEY、VISION_BASE_URL 和 VISION_MODEL。

若还要装可选无缝接入层，改发：

完整阅读 https://github.com/Anionex/agent-vision-toolkit/blob/main/AGENT_INSTALL.md，根据我们当前使用的 agent 应用，安装适用的视觉代理或原生 extension/plugin。如果视觉 API 尚未配置，请按当前系统找到配置文件，并引导我填写 VISION_API_KEY、VISION_BASE_URL 和 VISION_MODEL。

需要准备的是一个支持 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages 的多模态 API，以及它的 base URL、API key 和模型名。

三步手动安装¶

1. 指向一个视觉 API

在 ~/.config/agent-vision-toolkit/env 写入三个环境变量，并把文件权限设为 chmod 600：

VISION_API_KEY=sk-...
VISION_BASE_URL=https://openrouter.ai/api/v1
VISION_MODEL=google/gemini-3.6-flash

任何支持 /chat/completions 与 image_url 的 OpenAI 兼容端点都可以。仓库举例：阿里云百炼 https://dashscope.aliyuncs.com/compatible-mode/v1 + qwen-vl-max-latest。Python 客户端 / 代理还可设置：

• VISION_API_PROTOCOL=responses：走 /responses + input_image
• VISION_API_PROTOCOL=anthropic：走 Anthropic Messages；此时 Base URL 应以 /v1 结尾，不要带 /messages

需要英文描述时加 LANG=en，默认中文。

2. 把 CLI 放进 PATH

git clone https://github.com/Anionex/agent-vision-toolkit.git
export PATH="$PWD/agent-vision-toolkit/bin:$PATH"

要持久生效，把 export 写进 shell 配置。若同时需要仓库里的 dsh 子包，克隆时加 --recurse-submodules，或在已有 checkout 里执行 git submodule update --init --recursive。

3. 安装 skill

npx skills add Anionex/agent-vision-toolkit --skill vision-tools -a codex -g --copy -y

也可以把 skills/vision-tools/ 复制到当前 agent 的 skills 目录（例如 ~/.codex/skills/），重启后生效。

在 DeepSeek Harness 里走原生 Bundle¶

只在 dsh Web 或 Headless 里用、希望粘贴图片、Settings、Artifacts 都接上时，维护者给出的命令是（写作时 npm 版本 0.1.19）：

dsh plugin --profile web add @anionex/dsh-vision-toolkit

Headless Profile 把 --profile web 换成 headless。该包声明了 dsh.bundle，peer 依赖钉在 DeepSeek Harness ^0.1.0-rc.6，要求 Node.js ^22.19.0 或 >=24.0.0，并自带一份钉死的 agent-vision-toolkit 快照，运行时不会在后台拉取上游 main。装完重启 Web Profile，打开 Settings → Vision Toolkit，默认可先用内置的共享视觉服务做连通性测试。细节以 dsh-vision-toolkit 仓库 为准；社区目录也有对应页。

典型用法¶

下面命令和流程都来自仓库 README，不是另行编造的案例。

1. 对一张截图提问或做 OCR¶

glance screenshot.png -q "这张图片的主色调是什么？"
glance screenshot.png --ocr

长聊天截图不要指望一次 glance 吃完整张图。skill 内置脚本会切块、逐段 OCR、合并重叠并写出边界复查：

python3 skills/vision-tools/scripts/long_screenshot_ocr.py long-chat.png --mode chat -o long-chat.ocr.md

2. 定位控件，再裁切或矢量化¶

ground screenshot.png "发送按钮"
crop screenshot.png --region 1563,514,1668,621 -o send-button.png
trace screenshot.png --region 1563,514,1668,621 -o icon.svg

ground 每次分析一张完整图。目标很小就加 --region X1,Y1,X2,Y2，只在该框内查找，输出仍是原图坐标。密集页面要完整清单时，用 detect 按区域逐块盘点，而不是指望整屏一遍。

3. 还原页面或图形¶

仓库 playbook 的顺序可以概括成：先定位和裁切需要的视觉素材，再写代码或重建 SVG，然后渲染、对比、验收。快速 UI 还原允许颜色和图标库近似，目标是尽快给出第一张可看的截图；精细还原则继续用视觉对比往下对齐。GUI 操作同样是「看一次、动一次、再看一次」，不要在过期截图上连点。

4. 粘贴图片直接可用¶

在 Codex 或 Claude Code 上装好可选代理并重启宿主之后，直接粘贴图片，或让模型调用内置看图工具。Pi、Oh My Pi、OpenCode 走单文件原生 extension，不走代理，步骤见各目录 README。代理默认直连上游，不读 Windows 系统代理；需要显式走本地代理时，用 --upstream-proxy 或环境变量 VISION_UPSTREAM_PROXY。

适用场景与注意事项¶

比较适合：

• 主力模型是 DeepSeek 这类纯文本模型，但日常要看报错界面、设计稿、长截图
• 需要的不只是「描述这张图」，还要坐标、裁切、OCR 流水线、UI / 图形还原
• 已经在 Codex、Claude Code、Pi、OpenCode 等能调 shell 的 agent 里工作，希望同一套工具箱跨宿主复用
• 在 dsh 里需要原生粘贴和 Web Settings 时，改走维护者提供的 @anionex/dsh-vision-toolkit

使用前注意下面几条，均来自目录页或仓库文档：

1. 权限与许可证。 以 dsh 插件方式安装时，代码以当前 dsh 进程权限运行，安装过程可能执行代码。安装前检查 源码 和 MIT 许可证。社区目录不是官方应用商店。
2. dsh 仍是开发者预览。 插件接口可能变化。本仓库本身是 Python 工具箱；dsh 上的原生形态是另一个包，不要把两条安装命令混用。
3. 这是图片转文字层。 不会把视觉 token 交给纯文本模型。效果取决于主模型加多模态模型。代理缓存只存在于进程内，重启即清空。
4. 视觉 API 是刚需。 CLI 和 Python 代理至少要配 VISION_API_KEY、VISION_BASE_URL、VISION_MODEL。本地小模型可以用来压成本，仓库提到的选项包括 Gemma 4 和 Qwen 3.5 / 3.6 系列；具体可用性以各服务商当前文档为准。
5. 依赖按工具安装。 glance 对 Python 3.11+ 即可；定位、裁切、长图 OCR 需要 pillow；trace 还要 numpy。不要把可选依赖一次性装进系统 Python。
6. 密钥不要进 argv。 env 文件权限设为 600。代理 env 不要重复保存上游文本模型的 key。
7. 修改宿主配置前先备份。 Codex 只应改当前 provider 的 base_url 指向本地代理；Claude Code 只改 ANTHROPIC_BASE_URL。AGENT_INSTALL.md 要求用 TOML/JSON 解析器结构化编辑，不要手工拼坏配置。
8. 上游额度自负。 多模态 API 的费用、限流和条款由提供方决定。仓库说明每次看图只传递当前意图和图片，并有截断，避免上下文越积越长。

小结¶

agent-vision-toolkit 要解决的问题很具体：纯文本编码智能体看不见图，而一段通用描述又不够用。它把看图拆成可组合的 CLI，用 vision-tools skill 规定选型、顺序和验收；需要粘贴图片和内置看图工具时，再加一层本地代理或原生扩展。视觉能力放在 harness 侧，主模型继续做推理和改代码。

在 DeepSeek Harness 社区目录里，它被收在「工具与能力」。目录安装命令指向这个 GitHub 仓库；若要在 dsh Web / Headless 里作为原生 Bundle 使用，同一维护者提供的是 @anionex/dsh-vision-toolkit。

目录页与仓库：

• 社区目录：https://deepseek-harness-plugin.com/zh-CN/plugins/agent-vision-toolkit/
• GitHub：https://github.com/Anionex/agent-vision-toolkit
• 中文 README：https://github.com/Anionex/agent-vision-toolkit/blob/main/README_CN.md
• Agent 安装说明：https://github.com/Anionex/agent-vision-toolkit/blob/main/AGENT_INSTALL.md
• 原生 dsh 接入包：https://github.com/Anionex/dsh-vision-toolkit
• 项目主页：https://agent-vision.anionex.me
• DeepSeek Harness：https://github.com/deepseek-ai/deepseek-harness