识图补全 YJLTF/dsh-vision-tool

dsh-vision-tool

一个 DeepSeek Harness 插件：为纯文本主模型补上识图能力。它把图片理解委托给你配置的一个小参数多模态模型，再把结果以文本形式交还给主模型；当活跃模型自身支持图片输入时，插件完全退避，原生多模态体验不受任何影响。

面向 dsh 0.2.0-rc.2（peer 范围 ^0.2.0-rc.1，@deepseek-ai/cordis ^4.0.1）。

这个插件干了什么

DeepSeek Harness 的引擎依据模型声明的 inputModalities 做字节投影：路由不含 image 的模型（纯文本模型）永远收不到图片字节——用户贴进会话的截图，纯文本主模型是"看不见"的。此外，宿主在消息准入时会把带图消息对纯文本模型整条拒绝（MODEL_DOES_NOT_SUPPORT_IMAGES），文本模型连消息都收不到。本插件不碰请求消息改写，补上三条补偿路径：

1. 放行带图消息——放宽会话消息准入的图片门（包装 llm.resolveModelInfo 服务方法，见文末实现说明），让贴图消息进入纯文本模型的会话；引擎仍按适配器真实元数据把图片字节投影为文本占位符，不会把图片字节发给文本模型。
2. 注册 understand_image / list_conversation_images 工具——understand_image 不带 path 时自动检查会话中最近的一张图（正是"刚贴图"的典型场景），带 path 则读取指定文件；经 ctx.attachments.saveImages 入库 → ctx.llm.stream 向配置好的小参数多模态模型发起一次多模态请求 → 把回答以文本块返回，主模型据此继续推理。list_conversation_images 列出会话中出现过的全部图片供挑选。
3. 注入识图指导——对纯文本 agent，在系统提示中注入一段指导：看到 [image omitted because this model accepts text only; …] 占位符就意味着图片可用 understand_image 检查，且 prompt 必须是从当前任务和对话中提炼出的具体问题，而不是笼统的"描述这张图"。
4. 按能力退避——活跃模型声明了图片能力、或被用户显式标记为多模态时，不注入任何指导，也绝不触碰原生图片路径。

特性

- 贴图即用：放宽宿主对带图消息的准入拒绝后，直接贴图提问即可——纯文本主模型看到占位符后会自主调用 understand_image（不带 path），无需用户指明文件路径。
- 零干扰退避：模态判定优先级为 用户 overrides > 适配器声明的 inputModalities（按 provider/model 路由缓存一次）> 保守默认（视作纯文本，与引擎投影行为一致）。agent 创建时与会话中途切换模型时（model/selection 日志事件）都会预热该路由的判定，判定失败的路由下轮自动重试；系统提示指导还会在装配瀑布之后按实际选中路由复核一次，因此会话中途切换模型后，下一轮的指导去留会跟着正确翻转。
- 高质量识图：工具强制要求主模型传入结合上下文的具体问题，拒绝空 prompt、不做"笼统描述"兜底；视觉模型系统提示要求"精确完整描述 + 逐字转录可见文本"。
- 配置即改即生效：本插件的 Config schema 整段标记 volatile——dsh 0.2.0 的设置栈把配置改动就地提交进运行中的活引用，保存后立即作用于后续请求，无需重启会话或插件。
- 官方风格配置卡片：卡片按官方「新增设置页」配方注册进插件管理页的 plugins.bundle.config 键控 slot，出现在 web 端「插件」按钮打开的插件管理页 → 已安装 → dsh-vision-tool 详情页，与内置插件配置同观感——暂存编辑 + 保存/放弃；模型下拉直接读取 dsh 的 Host 代模型目录（可「刷新列表」重读），overrides 声明也可在卡片里增删。卡片仅在 Host 服务该条目命名空间期间存在，未组合本插件的部署不留任何痕迹。
- 可关的指导注入：guidanceInjection 可单独关闭系统提示指导，只保留工具本身。
- 支持常见图片格式：png / jpg / jpeg / webp / gif。
- 随请求中止：视觉流式调用跟随工具执行的 AbortSignal，取消即中断。
- 干净卸载：工具、指导、事件监听与准入放行均随插件 dispose 注销/还原。
- 零运行时依赖：lib/index.js 只外置导入宿主提供的 dsh 包与 schemastery（peerDependencies 声明，与 Host 共享同一实例），产物约 18 kB，天然适合离线分发。

安装

方式 A：从 GitHub 安装（联网环境）

在目标 dsh 环境里执行（<profile> 换成你的 profile 名）：

dsh plugin --profile <profile> add github:YJLTF/dsh-vision-tool

与 dsh 官方打包安装文档一致，有三点注意：

- 构建授权：git 安装拉取的是源码而非构建产物，装完会由包内的 prepare 脚本构建出 lib/。pnpm ≥ 10 默认拒绝为 git 依赖运行 prepare，首次 add 会失败——按 dsh 的提示，在 profile 的 pnpm-workspace.yaml 里放行后重试： allowBuilds: dsh-vision-tool: true

- 安全与钉版本：放行构建即允许该包代码在安装期于你机器上执行，请只对可信的包放行；建议钉住 commit：
dsh plugin --profile <profile> add github:YJLTF/dsh-vision-tool#<commit-sha>

- 层激活：本包声明了 dsh.bundle（cordis.patch.yml + 挂载清单），dsh plugin add 安装后会自动作为 profile 层激活，无需手工改 patch 文件。

方式 B：离线安装（配合 dsh-plugin-offline-packager）

无网络的目标环境可先用 dsh-plugin-offline-packager 在联网机器上把本插件打成自包含离线包，再拷贝安装：

联网机器：安装打包器插件后，在 web 会话里直接说——请将 ./dsh-vision-tool 打包为离线安装包得到 dsh-vision-tool-<version>.tgz（附 .meta.json 审计元数据）

离线机器：一条命令安装，零 registry 访问
dsh plugin --profile <profile> add ./dsh-vision-tool-<version>.tgz

本插件对离线打包天然友好：零 npm 运行时依赖（dsh 包与 schemastery 均为 peerDependencies，由宿主提供，不会被打入离线包）、构建产物 lib/ 随包携带、files 字段已限定 tarball 内容（lib/ + cordis.patch.yml）。已构建的检出里直接 npm pack 也能得到等价的自包含 tgz。tarball 内的 dsh.bundle 声明同样会让安装自动激活插件层。

方式 C：从源码构建并挂载

git clone https://github.com/YJLTF/dsh-vision-tool
cd dsh-vision-tool
pnpm install
pnpm build # tsdown（lib/index.js）+ tsc（lib/types，含 client 声明）+ 客户端 bundle（lib/client.js）
pnpm typecheck # Host 半侧类型检查（typecheck:client 为浏览器半侧）
pnpm smoke # 冒烟测试：以假 Host 启动 lib/index.js 走查注册/指导/工具/卸载全链路

然后在 dsh 的 profile（例如 cordis.patch.yml）中以挂载任意树外插件 bundle 的方式挂载 lib/index.js。

配置

dsh 0.2.0 的设置栈没有插件自注册的命名空间：Loader 直接把插件导出的 Config schema 变成 profile 插件条目的配置（条目 id 即包名 dsh-vision-tool），schema 标记为 volatile，改动经设置文档提交后即时生效、无需重启。

推荐入口是 web 端的配置卡片：顶部「插件」按钮 → 插件管理页 → 已安装 → dsh-vision-tool 详情页，配置表单就在页面描述与组件列表之间。卡片为暂存式编辑——改动后点 保存 一次原子写回（立即生效、无需重启），放弃 丢弃草稿；识图模型从下拉里选（列表即 dsh 已配置的全部模型，可用「刷新列表」重读），下方文本框同步显示当前选择；overrides 声明也可在卡片里增删。

等价地，直接编辑 profile 的 cordis.patch.yml（改文件需重启 dsh 读取一次，之后经卡片/设置文档提交的修订即时生效）：

- id: dsh-vision-tool
name: dsh-vision-tool
config:
visionProvider: zai-coding-cn
visionModel: glm-5.3-flash
maxTokens: 4096

| 字段 | 类型 | 默认值 | 含义 |
| enabled | boolean | true | 总开关。关闭后指导不注入，两个识图工具都会拒绝执行。 |
| visionProvider | string | '' | 小参数多模态模型的提供方路由（从 dsh 已配置模型中选）。 |
| visionModel | string | '' | 小参数多模态模型的精确模型 id。 |
| visionSystemPrompt | string | 内置 | 视觉模型每次调用遵循的系统提示词。 |
| maxTokens | number | 2048 | 视觉调用最大输出 token 数（256–8192）。 |
| guidanceInjection | boolean | true | 是否为纯文本模型注入识图指导。 |
| overrides | {model, modality}[] | [] | 按模型显式声明模态；优先级高于适配器元数据（退避依据）。 |

最小可用配置就是 provider / model 两项——任一为空时，understand_image 会报错提示"未配置视觉模型"，指导也不会注入。

必须的前置条件：所选的视觉模型要在 dsh 的模型配置（settings.yaml 的 provider models 列表）里声明图片输入能力，否则引擎会把发往视觉模型的请求中的图片字节一并投影掉——视觉模型只会看到一个 sha256: 占位符，无法真正识图：

llm-pi-ai:
providers:
<provider>:
models:
- id: <vision-model>
input: [text, image] # 关键：声明后引擎才放行图片字节

同理，overrides 中把某个模型标记为 image 也能达到同样效果（并触发本插件对该模型退避）。

使用

配置完成后，在会话里直接贴图提问即可：纯文本主模型收到的图片是一个文本占位符，系统提示中的指导会告诉它占位符背后的图片可以检查——它会自主调用：

{ "prompt": "结合当前任务与对话的具体问题" }

（省略 path 时检查会话中最近的一张图；多图场景模型可先调 list_conversation_images 挑选。）工具返回视觉模型的文本回答，主模型据此继续推理。若你的主模型本身支持图片输入，装不装这个插件没有区别——准入不拦、指导不注入、消息不改写。

实现说明：准入放行与配置卡片

准入放行：宿主在 session/prompt 准入时，通过 llm.resolveModelInfo 服务方法判定模型能力。声明里不含 image 的路由会收到 MODEL_DOES_NOT_SUPPORT_IMAGES，整条被拒。本插件包装该方法，对这类路由在元数据中补报 image 能力，让准入放行；请求层的字节投影读的是适配器自身元数据（不经过该方法），行为不变——纯文本模型的请求里，图片仍是文本占位符。原生多模态路由不受影响。其它消费方（ACP、子代理等）最多元数据展示失真，行为上有投影兜底。插件卸载时恢复原方法；若服务门面不可写，则跳过放行，其余功能不受影响。未来若 dsh 提供官方的准入开关，应迁移过去。

配置卡片：按官方「新增设置页」配方实现——package.json 声明 dsh.client（platform: "web" + 对 ui-settings / ui-plugin-manager / api-remotes 的加载边），./client 导出 lazy-CJS 格式的浏览器 bundle（scripts/build-client.mjs 独立复刻 monorepo 的 tsdown.client 产物形状）。客户端插件在 Host 服务条目命名空间期间（ctx.configForms.whileServed），向 plugins.bundle.config 键控 slot 注册（key = 包名），并经由共享的 ctx.configForms.get(条目id) 表单暂存编辑、以修订围栏的原子 mutate 写回。注意 bundle 配置卡片不接收页面宿主的 form prop（一个 bundle 可含多个条目，没有单一表单），需要自行取共享表单；注入给组件的快照必须缓存引用——React useSyncExternalStore 对每次 getSnapshot 返回新对象会直接判定无限循环并崩溃。

目录

- src/meta.ts — 无依赖共享常量（命名空间 / 插件名 / 默认提示词），Host 半侧与浏览器卡片共用。
- src/config.ts — 插件条目的 Config schema（整段 volatile + 中文 i18n 标签：改动即时生效，免重载）。
- src/index.ts — Host apply：volatile 活引用读取 + 准入放行 + 模态判定缓存 + 指导注入与瀑布复核，按 agent 能力退避；导出 Config schema 供 Loader 生成条目表单。
- src/tool-understand-image.ts — understand_image / list_conversation_images 工具与视觉流调用。
- src/client/index.ts — 浏览器半侧：模型目录读取 + plugins.bundle.config 卡片注册。
- src/client/vision-model-card.tsx — 配置卡片组件（暂存编辑、模型下拉、overrides 编辑）。
- scripts/build-client.mjs — 构建 lib/client.js（ModuleLoader lazy-CJS 包装格式）。
- scripts/smoke.mjs — 冒烟测试：以最小假 Host 启动 lib/index.js，走查配置、注册、准入放行、指导决策、工具执行与卸载全链路。