前言¶

做智能体开发常碰到这样一个缺口：主 agent 用的模型路由没有声明 image 输入，是个纯文本模型。用户丢过来一个图片路径让它描述，它做不到——要么手动换到有视觉能力的会话，要么自己看一眼图再转述给它。DeepSeek Harness（下称 DSH）的理念是「一切皆插件」，这种单点能力缺口正适合用一个小插件补上。下面介绍 Mappedinfo 维护的 dsh-tool-vision-read，它注册一个 vision_read 工具，把读图这一步路由给专用视觉模型，纯文本 agent 调用一次就能拿到图片的文字描述。

这是什么¶

dsh-tool-vision-read 是一个 DSH 社区插件，包名 @deepseek-ai/dsh-tool-vision-read，当前版本 0.1.0-rc.6，MIT 许可，由 Mappedinfo 独立开发维护，不属于官方 DeepSeek Harness 发行版。

一句话定位：注册 vision_read 工具，通过专用视觉模型路由读取图片文件并返回文字描述，使纯文本 agent 也能「看到」图片。它把「按能力把任务路由到不同模型」的思路收敛到读图这一件事上，不依赖第三方工具，也不需要人工转述。

核心功能¶

工具契约¶

vision_read(file_path: string, focus?: string)

返回 { path, provider, model, description }，其中 description 是视觉模型对图片的文字描述。只接受 PNG/JPEG/WebP/GIF 路径，路径按调用会话的工作区 cwd 解析。

两种执行模式¶

• direct（默认）：插件读文件并经附件服务提交，单次 llm.stream 调用配置的视觉提供方/模型。一次往返，没有 agent loop。
• subagent：进程内启动一个固定到视觉路由的子代理，由它自行调用 read_image，可以迭代缩放、OCR、追问。更灵活，代价是完整的 agent loop。

配置项¶

• provider（string，必填）：持有视觉模型的已注册提供方路由
• model（string，必填）：该路由上的视觉模型 id
• toolName（string，默认 vision_read）：模型侧看到的工具名
• mode（'direct' | 'subagent'，默认 'direct'）：执行模式
• maxImageBytes（number，默认跟随附件服务限制）：发给视觉路由的图片字节上限
• maxOutputTokens（number，默认 1024）：视觉路由输出 token 上限
• prompt（string）：随图发送的指令，支持 {{path}} 与 {{focus}} 占位符

路由校验¶

调用前会先解析路由；如果解析出的路由没有声明 image 输入，调用会失败并给出指引——例如 pi-ai 路由需要在 provider 设置里声明 defaultInput: [text, image]。配置解析在路由 id 缺失时也会直接失败，所以 provider 和 model 必须写清楚。

安装与启用¶

前提：已有 DeepSeek Harness 部署（源码检出或 out-of-tree profile 安装），以及一条支持图片输入的模型路由。插件已针对 Kimi Coding API（k3-256k）验证。

推荐以 Profile Bundle 形式安装到 web profile：

dsh plugin --profile web add github:Mappedinfo/dsh-tool-vision-read

先执行安装，再重启 dsh web。安装成功后包会加入 dsh.profile.bundles，重启后由捆绑的 cordis.patch.yml 自动挂载 vision_read。默认路由是 kimi-coding / k3-256k。

如果你的视觉路由或模型不同，有两种覆盖方式。单次启动用环境变量，不用编辑包：

DSH_VISION_PROVIDER=my-provider DSH_VISION_MODEL=my-vision-model dsh web

持久覆盖则在 profile 自己的 cordis.patch.yml 里按 id 覆盖：

- id: tool-vision-read
  config:
    provider: my-provider
    model: my-vision-model
    mode: direct

两点注意：profile 自身的 cordis.patch.yml 在 Bundle 之后应用；不要在 profile 里插入第二个 tool-vision-read 行。

移除 Bundle 用这条命令：

dsh plugin --profile web remove @deepseek-ai/dsh-tool-vision-read

本地开发时可以链接本地检出：

dsh plugin --profile web add link:/absolute/path/to/dsh-tool-vision-read

如果你在 deepseek-harness monorepo 里开发，也可以把包复制到 packages/vision/tool-vision-read 后执行 pnpm install，再按官方 adding-a-package cookbook 注册与挂载。另外，@deepseek-ai/* 的 peer 依赖由 DSH 安装的模块闭包满足（$DSH_HOME/profiles/node_modules 平铺回退），autoInstallPeers: false 防止 pnpm 拉取旧注册表副本，一般不需要额外处理。

典型用法¶

README 里的端到端示例：纯文本 agent（deepseek-v4-flash）对一个 JPEG 调用 vision_read，描述由 Kimi K3-256K 经 kimi-coding 路由返回。

user: 请用 vision_read 看一下 /Users/shiqi/Downloads/微信图片_20260816082109_883_131.jpg 并描述内容
agent: (vision_read) → "这是一张横构图、白天拍摄的现代城市/园区街景照片……天空与云约占画面上方 2/3……
        左侧一栋多层建筑转角呈弧形……中右一座较低的建筑带弧形屋顶边缘和竖向格栅外立面……"

agent 本身全程没有处理图片，图片 I/O 全部发生在视觉路由那一侧，它拿到的只是文字描述。

适用场景与注意¶

适合的场景：主 agent 是纯文本模型、但需要偶尔读图（截图、照片、图表）的 DSH 部署；已经配好多模型路由、想把读图固定交给某个视觉模型的使用者。

需要注意：

1、这是非官方社区插件，独立开发维护。插件以当前 dsh 进程的权限运行，安装前建议先读一遍源码，确认行为与权限边界可以接受；许可证为 MIT。
2、路由必须声明 image 输入，否则调用会失败并给出指引，比如为 pi-ai 路由设置 defaultInput: [text, image]。
3、图片只接受 PNG/JPEG/WebP/GIF，路径按调用会话的工作区 cwd 解析，跨工作区引用时留意路径解析基准。

结尾¶

经过上面的步骤，一个纯文本 agent 就有了读图能力：vision_read 把图片交给专用视觉模型，再把文字描述带回 agent 的上下文。插件很薄，只做一件事，但正好补上了 DSH「一切皆插件」思路下的一个常见缺口。

GitHub：https://github.com/Mappedinfo/dsh-tool-vision-read
社区目录页：https://www.skillhub.cn/plugins/Mappedinfo/dsh-tool-vision-read （社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系，信息以 GitHub 仓库为准）