纯文本模型读图OoWJZZoO/dsh-read-image

dsh-read-image

English

让非多模态大模型也能"看图"的 DeepSeek Harness 插件——即插即用，无需修改任何 preset：图片不再被拦截、投影为 [Image #N]、由一等公民 read_image 工具配合可配置的视觉模型读回。

功能

- 不再拦截：用户发送图片时，文本路由被声明为可接受图片输入，api-proxy 的准入闸门放行。
- [Image #N] 投影：文本路由的模型请求中，图片块被原位替换为 [Image #N] 文本，像素永远不会进入文本 API；多模态路由原样放行。
- 一等公民 read_image 工具（每个会话自动注册，遮蔽内置同名工具）：
- image_index：读取会话中第 N 张图片（[Image #N]）；
- file_path：读取文件路径的图片（PNG/JPEG/WebP/GIF）；
- prompt / reasoning_effort / timeout_ms / max_tokens / max_thinking_tokens：可选参数，缺省使用配置默认值（工具描述内插当前真实默认值，Agent 无需猜测）；
- 文本路由通过配置的视觉模型把图片转成文字描述返回；多模态路由直接返回图片本身；
- 无状态、可重复调用（包括重复读取同一张图）。
- 原生多模态路由回退内置工具：会话基础路由本身声明图片输入时（如 mimo-v2.5），不注册自定义工具、不注入 [Image #N] 提示词段——该路由下图片直接进模型上下文，模型看到的是 harness 内置 read_image（仅 file_path，"return the image itself"）。
- 可视化配置：设置面板（侧边栏齿轮）里的「读图」页，编辑视觉模型与默认参数；浏览器与 host 之间走 typert Remote 桥（readImageConfig），绕开 harness 对插件命名空间的设置白名单。

安装

要求 DeepSeek Harness（dsh）0.1.0-rc.6 或更高（harness 处于开发者预览阶段，更新的 release candidate 可能需要兼容性适配）。

Windows：插件运行时是纯 Node.js，在 Windows 上原样可用——harness 原生适配 Windows 路径（盘符、大小写不敏感文件系统、PowerShell 命令执行）。dsh 经 npm 安装为 dsh.cmd（在 PATH 中），~/.dsh 对应 %USERPROFILE%\.dsh（如 C:\Users\\.dsh）。下面的命令全部通用；凡出现字面路径处，把 ~/.dsh/... 换成 %USERPROFILE%\.dsh\... 即可。

方式一：dsh plugin add（推荐）

dsh plugin --profile web add github:OoWJZZoO/dsh-read-image

然后重启 dsh web。本包通过 dsh.bundle 清单附带 cordis.patch.yml，profile bundle 机制会自动合成插件行，无需手工改 patch。

方式二：手动安装

把本包加入 web profile，并手工注册插件行：

// ~/.dsh/profiles/web/package.json → dependencies
"@deepseek-ai/dsh-read-image": "github:OoWJZZoO/dsh-read-image#v0.1.0"

cd ~/.dsh/profiles/web && pnpm install

在 ~/.dsh/profiles/web/cordis.patch.yml 插入一行：

- insert:
- id: read-image
name: '@deepseek-ai/dsh-read-image'
config: {}   # 可选：部署默认值（用户层可覆盖）

然后重启 dsh web。

不要同时走两条路：dsh plugin add 已自动合成插件行，若再手工添加依赖并插入同一行，插件会被注册两次。

配置

配置写在 $DSH_HOME/settings.yaml（热加载，无需重启）——Windows 上未设置 DSH_HOME 时是 %USERPROFILE%\.dsh\settings.yaml——也可在 Web 的「设置 → 读图」页编辑（写进 user layer，覆盖 settings.yaml 对应项）：

1) 给视觉模型声明图片输入能力（pi-ai 路由）
llm-pi-ai:
providers:
:
models:
- id:
…contextWindow / maxTokens…
input: [text, image]      # ← 关键

2) 本插件配置
dsh-read-image:
visionProvider:    # 视觉模型所在的路由 provider
visionModel:   # 视觉模型 id（须声明 input: [text, image]）

| 键 | 默认值 | 说明 |
| --- | --- | --- |
| visionProvider | '' | 视觉模型所在的路由 provider（下拉选项来自「模型」页） |
| visionModel | '' | 负责读图任务的多模态模型（该 provider 下的下拉选项） |
| defaultPrompt | 英文分步描述提示词（分类 → 文本逐字转 Markdown / 视觉描述） | read_image 未传 prompt 时使用 |
| defaultReasoningEffort | low | 默认思考强度。low 是各主流模型普遍支持并生效的最低档位；off 在很多适配器上等于「不传该字段」，对默认开思考的模型（如 mimo-v2.5）不生效，思考会挤占 max_tokens 使小预算输出为空 |
| defaultTimeoutMs | 300000 | 默认视觉调用超时（5 分钟，宽松） |
| defaultMaxThinkingTokens | 4096 | 默认最大思考 token（独立预算，不占输出配额）；思考 token 超出预算导致输出为空时，read_image 会显式报错而非静默返回空 |
| defaultMaxTokens | 8192 | 默认实际输出 token 上限；传给 API 的 max_tokens = 该值 + defaultMaxThinkingTokens（reasoning_effort=off 时预算为 0，原样透传） |
| guard.enabled | true | 环境自检开关；false 跳过自检强行加载插件（见「安全」） |

说明：浏览器设置协议（settings.）对插件命名空间有硬编码白名单（WEB_SETTINGS_NAMESPACES），插件 settings.register() 的命名空间对客户端只回 settings-not-exposed，因此「读图」页不走 settings 协议，而是经 host 侧 typert Remote 桥（readImageConfig.get/set，见 lib/config-remote.js）读写同一命名空间——settings.yaml 仍是底座，Web 写入进 user layer，scope.watch 热同步运行时，headless 与 Web 配置一致。

使用

- 直接粘贴图片：文本模型会看到 [Image #1]，调用 read_image image_index=1 即可查看；
- read_image file_path=/path/to/image.png 读取文件图片（Windows 上 C:\Users\... 与 C:/Users/... 两种写法都行——反斜杠由 harness 文件服务处理）；
- 可传 prompt（问视觉模型的具体问题）、reasoning_effort、timeout_ms、max_tokens、max_thinking_tokens 覆盖对应默认值；
- 可反复调用，包括反复读取同一张图。

安全

本插件依赖的 harness 内部契约可能在升级后改变形态。启动时插件会对所有触及的 harness 契约做环境自检；任一检查失败时插件安全失败：不安装任何东西、harness 照常启动——完整诊断写入 ~/.dsh/logs/dsh-read-image-guard.log（Windows 上为 %USERPROFILE%\.dsh\logs\dsh-read-image-guard.log），前台只打一条简短提示。若你清楚自己在做什么，可在 settings.yaml 的 dsh-read-image 段写 guard.enabled: false 跳过自检强行加载（自担风险）。

工作原理

| 机制 | 平面 | 作用 |
| --- | --- | --- |
| M1 准入放行 | host | 包装 llm.resolveModelInfo，文本路由声明接受图片输入（dispose 恢复）→ 发送/换模型闸门放行 |
| M2 投影 | host | llm/stream waterfall 同步监听器：文本路由上 image 块 → [Image #N] 文本，harness deepFreeze 后重入派发 |
| M3 工具 | per-agent | session/created 时经 agent 作用域注册 read_image（遮蔽内置同名工具）+ 提示词段 |
| 设置 | host | 注册 dsh-read-image settings 命名空间（schema 默认值即 fallback），scope.watch 热同步运行时配置 |
| 配置桥 | host | ReadImageConfigService（typert Remote，readImageConfig.get/set）读写同一命名空间，Gateway 自动发现 |
| 配置页 | browser | settings.section 注册「读图」页（order 12），apply 内 ctx.remote.$mount 自挂载 remote.readImageConfig |
| G1 自检 | host + browser | 总保险丝：apply 时探测全部 harness 契约，任一失效 → 插件不加载、harness 不受影响（见「安全」） |

- 能力真值表：用包装前的原始 resolveModelInfo 构建（绝不用被 M1 包装后的方法），llm/adapters-updated 时重建 + 启动重试兜底；
- 视觉调用：复用 ctx.llm（凭证/重试/日志与 harness 一致），AbortSignal.any([exec.signal, timeout]) 控制超时；
- 会话日志是唯一事实源：图片引用照常持久化，只在模型可见边界做 [Image #N] 替换。

开发

贡献者指南与全部 harness 绕行 hack 的决策记录（作用 / 风险 / 加固方向）见 AGENTS.md 与 docs/known-hacks.md。测试：node --test test/（从 dev profile 副本运行，见测试文件头注释）。

插件代码本身跨平台（纯 Node.js，无 OS 专属 API）；开发/部署脚本（scripts/.sh）是 POSIX bash——Windows 上请用 Git Bash / WSL / MSYS2 运行，或手工镜像拷贝步骤（它们只是把 package.json、lib/ 与 cordis.patch.yml 拷进 profile 的 node_modules/@deepseek-ai/dsh-read-image）。

License

MIT