视觉读取工具 Mappedinfo/dsh-tool-vision-read

dsh-tool-vision-read

非官方社区插件。 独立开发和维护；不属于官方 DeepSeek Harness 发行版的一部分。

一个轻量级的 DeepSeek Harness 插件，它注册了一个 vision_read 工具：它通过专用的视觉模型路由读取图像文件并返回文本描述——因此纯文本 agent（其路由未声明 image 输入的模型，例如没有视觉能力的聊天模型）仍然可以“看到”图像。

这与将不同角色路由到不同模型（例如 oh-my-pi 的 modelRoles）是同一思路，只是应用于一个狭窄的能力：图像描述。无需第三方 CLI（modlens 等），无需手动委派——插件在一次调用中完成。

工作原理

| 模式 | 行为 | 成本 |
| direct（默认） | 插件读取文件，通过附件服务提交，并向配置的视觉提供商/模型发起一次 llm.stream 调用，携带文本+图像消息。 | 一次往返，无 agent 循环。 |
| subagent | 插件启动一个进程内子 agent，固定到视觉路由（agentOptions），它自己调用 read_image 并可迭代（缩放、OCR、后续追问）。 | 完整 agent 循环，更灵活。 |

该工具始终路由到配置的视觉路由，无论调用模型是什么。当任一路由 id 被省略时，配置解析会失败；调用会在图像 I/O 之前解析路由，当解析出的路由未声明 image 输入时，会带着指引失败（在提供商设置中声明它，例如 pi-ai 路由的 defaultInput: [text, image]）。

要求

- 一个 DeepSeek Harness 部署（源码检出或树外 profile 安装）。
- 一个具备视觉能力的模型路由。该插件已针对 Kimi Coding API（k3-256k，接受图像输入）验证——任何支持图像内容块的提供商均可使用。

安装

选项 A：在 deepseek-harness monorepo 内（推荐用于开发）

将此包复制到 packages/vision/tool-vision-read 下（或从 git 安装），然后：

pnpm install

在 tsconfig.base.json 中注册该包（将 ./packages/vision//src 添加到 @deepseek-ai/dsh- 通配符和 @deepseek-ai/dsh-/invariant 通配符），并在 tsconfig.host.json references 中注册，然后挂载它——参见官方 adding-a-package cookbook。

选项 B：安装 Profile Bundle（推荐）

通过 DSH 插件管理器将 Git 仓库安装到 profile 中：

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

对于本地开发，改为链接检出目录：

dsh plugin --profile web add link:/absolute/path/to/dsh-tool-vision-read
该包声明了一个 DSH Profile Bundle，因此成功安装后会将其添加到 dsh.profile.bundles。重启 dsh web；其捆绑的 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 会在 Bundle 之后应用。当路由或其他选项需要持久化时，请使用以 id 为目标的覆盖：

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

不要在 profile 中插入第二行 tool-vision-read。使用 dsh plugin --profile web remove @deepseek-ai/dsh-tool-vision-read 移除该 Bundle。@deepseek-ai/ 对等包由 DSH 安装的模块闭包满足（$DSH_HOME/profiles/node_modules 扁平回退）——autoInstallPeers: false 可防止 pnpm 拉取较旧的注册表副本。

配置

| 键 | 类型 | 默认值 | 含义 |
| provider | string | —（必填） | 拥有该视觉模型的已注册 provider 路由。 |
| model | string | —（必填） | 该路由上的视觉模型 id。 |
| toolName | string | vision_read | 面向模型的工具名称。 |
| mode | 'direct' \| 'subagent' | 'direct' | 执行模式。 |
| maxImageBytes | number | 附件限制 | 发送到视觉路由的图像字节数上限。 |
| maxOutputTokens | number | 1024 | 视觉路由输出 token 数上限。 |
| prompt | string | 见源码 | 随图像一同发送的指令；{{path}} 和 {{focus}} 占位符。 |

工具契约

vision_read(file_path: string, focus?: string)

返回 { path, provider, model, description } —— 视觉模型对图像的文本描述。仅接受 PNG/JPEG/WebP/GIF 路径；路径相对于调用会话的工作区 cwd 解析。

示例

一个纯文本 agent（deepseek-v4-flash）对一张校园大门照片调用 vision_read，描述由 Kimi K3-256K 通过 kimi-coding 路由生成：

DeepSeek Harness GUI 中的 vision_read 演示

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

目录结构

src/index.ts # plugin (name/inject/apply/Config) + vision_read tool
src/invariant.ts # package invariant companion (no runtime invariant)
cordis.patch.yml # auto-mounted DSH Profile Bundle layer
lib/ # reference build emitted from the deepseek-harness monorepo
tests/ # vitest spec (runs in the monorepo context)
docs/dsh-discussion-draft.md # DeepSeek Harness "Show Your Plugins!" draft

备注
- lib/ 是从 deepseek-harness monorepo（packages/vision/tool-vision-read）内的包生成的参考构建；测试针对 monorepo 工具链运行。git 依赖会直接安装已提交的 lib/。
- 已端到端开发和验证：一个纯文本 agent（deepseek-v4-flash）对一张 JPEG 调用 vision_read，从 Kimi K3-256K 收到了正确的描述。

许可证

MIT