dsh-image-router

[!IMPORTANT] 当前版本 0.4.4，已发布到 npm，适配 DSH 0.1.5-rc.1+（已在 0.1.5-rc.1 上真机验证）。 若你装到的是更早的 0.1.0，那是本插件的第一个（已废弃的）构建，会让「设置 → 模型」页加载失败 —— 用 dsh plugin --profile web add dsh-image-router@latest 直接装最新版即可。

让纯文本模型也能「看图」
图片在进入会话之前，先由你指定的视觉模型转成文字 —— 你的会话模型自始至终不变，模型选择器也不会跳。

你贴一张截图，问「这个报错怎么修」
      ↓  插件在「提示词准入」之前拦下这次提示词
qwen-token-plan-cn / qwen3.8-flash   ← 一次旁路调用（不改会话路由、不写 model/selection）
      ↓  分析结果替换掉图片，成为提示词里的一段文字
你原本选定的模型（GUI 里显示的那个）继续作答

📑 目录

• ⚡ 一分钟安装
• ✨ 功能一览
• 🖼️ 它长什么样
• 🧭 给视觉模型的两种方式
• 🔐 安全 · ⚠️ 已知限制 · 🖥️ 兼容性
• 🛠️ 开发与测试 · 🤝 参与贡献
• 🔍 审计与排查（折叠） · ⚙️ 配置项（折叠） · 🧩 工作原理（折叠）

⚡ 一分钟安装

前置：已装好 DSH（dsh web 能正常跑），Node.js ≥ 20。

方式一：命令行一条

dsh plugin --profile web add dsh-image-router && dsh web

就这一条。 dsh plugin 是 pnpm 的薄封装：它把包装进 profile，并自动把声明了 dsh.bundle 的依赖加进 dsh.profile.bundles（按已安装状态 reconcile），不需要手动编辑 package.json。卸载同理：dsh plugin --profile web remove dsh-image-router。

不想走 npm？把 dsh-image-router 换成 github:zhiwuli0228/dsh-image-router 即为等价形态（前沿代码、未经 registry 校验）。

方式二：让 DSH 自己装 —— 把下面这段发给任意一个 DSH 会话：

帮我安装 dsh-image-router 图片旁路识别插件（DSH 插件，让纯文本模型也能看图），步骤：
1. 执行 dsh plugin --profile web add dsh-image-router
2. 确认 dsh-image-router 已出现在 $DSH_HOME/profiles/web/package.json 的 dsh.profile.bundles 里
3. 提醒我重启 dsh web
4. 重启后告诉我：打开「设置 → 插件 → 插件配置 → image-router」，视觉模型那栏怎么填
遇到报错先查 https://github.com/zhiwuli0228/dsh-image-router README 的常见问题。

方式三：本地源码（想改代码时）——见下方〈从源码安装〉。

装完 2 步

1. 打开 设置 → 插件 → 插件配置 → image-router。
2. 「视觉模型」下拉里选一个支持图片的模型；没有现成的就切到「自定义端点」，只填三样：地址、模型名、API Key → 保存。

然后随便发一张图 —— 你会看到 [图片分析 · <你选的模型>] 开头的文字，代替图片进入会话。

# 装/升到最新版
dsh plugin --profile web add dsh-image-router@latest

若它打印 Already up to date 却仍是旧版：pnpm 11 的发布年龄门槛（minimumReleaseAge）把「刚发布不久」的版本排除在版本解析之外。全新安装不受影响（pnpm 会把该版本自动加进排除项，实测发布 20 分钟后 @latest 即可装到），但升级已有依赖时会把新版本滤掉、解析回旧版 —— 看起来像更新失败，其实是策略挡的。这时显式写出版本号即可，pnpm 会打印 Added 1 entry to minimumReleaseAgeExclude 并立即安装：

dsh plugin --profile web add dsh-image-router@<版本号>

改完硬刷新浏览器（Ctrl/Cmd+Shift+R）。配置项的改动不需要重启（保存后下一次判定即生效）；插件代码的改动需要重启 dsh web。

# 1. 装进 profile（file: 指向你的克隆目录）
dsh plugin --profile web add file:E:\path\to\dsh-image-router

# 2. 重启 dsh web
dsh web

零安装也可以：不装依赖，直接按路径挂载（见 examples/cordis.patch.yml）：

# $DSH_HOME/profiles/web/cordis.patch.yml
- insert:
    - id: image-router
      name: '<repo>\lib\index.js'      # 绝对路径或 ./-相对路径都接受
      config:
        mode: digest
        vision: { provider: qwen-token-plan-cn, model: qwen3.8-flash }
        traceFile: '<repo>\trace.log'

profile 补丁层有 live reload（patchReload: live），实测配置改动会重新 apply —— 但它不会重新 import 已经加载过的宿主模块，所以代码变更只有重启才可靠生效。

✨ 功能一览

• 🖼️ 提示词里的图片自动转文字：贴图 / 上传的图片在准入前被旁路分析，图片块替换成文字分析 —— 连纯文本模型也能收到「带图」的提示词，而它收到的是文字。
• 🔒 会话模型一动不动：这是与「切换到视觉模型」类方案的根本区别。不写 model/selection，模型选择器不跳，没有 [model changed] 提示，会话历史里留下的是文字分析。
• 🔧 describe_image 工具（按需）：模型可以像调用普通工具那样分析磁盘上的图片文件（describe_image(file_path, question?)），任何模型都能用 —— 因为图片从不进入会话，read_image 那道「当前路由必须声明 image」的门槛不适用。
• 🧭 两种给视觉模型的方式：① 从「设置 → 模型」里已配好的模型中点选支持图片的（宿主侧图片能力 oracle 按 inputModalities 过滤）；② 填自定义端点（baseURL + 模型 + API Key），插件把它翻译成上游 llm-pi-ai 的一条普通路由。
• ⚙️ 图形界面配置，保存即生效：设置 → 插件 → 插件配置 里的卡片，改完立刻用于下一次判定（不需要重启、不需要手写 YAML）。
• 🔐 API Key 只写不落盘：密钥写进凭据库（refs.IMAGE_ROUTER_VISION_API_KEY），只留引用名在路由里；解析结果、设置节、卡片草稿三处都会剥掉它，不回显、不写进配置文件、不进审计日志。
• 🧩 不自己实现协议：线协议、模型发现、图片投影、重试全部交给 @deepseek-ai/dsh-llm-pi-ai，插件只负责把卡片上的字段写成 DSH 的配置。
• 🛡️ 失败即放行：视觉调用失败（配额 / 超时 / 报错）时不替换图片，把原请求交给原路径，让它给出真实的错误，而不是被插件掩盖。任何插件内部异常都只写审计 + 一条 warning。
• 📝 审计文件：挂载、每次分析、用了哪条路由、重试、失败原因都记一行 —— 「我配的端点到底生效了吗」有一个可读的答案。
• 🧪 68 个单测 + 全平台 CI：Ubuntu + Windows × Node 20/22/24。

🖼️ 它长什么样

贴图之后，会话里收到的是这样一段（label: true 时会带前缀标记）：

[图片分析 · qwen-token-plan-cn/qwen3.8-flash]
1. 文字内容：
设置 / 通用设置 / Theme · 外观 / 模型 / 插件 / Agent 预设 / 插件市场
模型 —— 填入各提供方的 API 密钥即可使用其模型。/ DeepSeek / qwen-token-plan-cn / huawei / Image Router Vision
2. 画面描述：
浅色背景的设置页面。左侧为垂直导航栏，当前选中「模型」；右侧列出四个已配置的模型服务卡片，
每个名称旁有绿色圆点，后三项带红色「删除」按钮；底部两个虚线框按钮「+ 添加提供方」「+ 添加自定义提供方」。

模型收到的是这段文字，不是图片。审计文件里对应这一行：

digest session=<id> vision=image-router-vision/qwen3.8-max images=1 chars=408 names=image.png

🧭 给视觉模型的两种方式

优先级：设置节写了端点 → 端点赢；设置节写了路由 → 路由赢；两者都没写 → 用 profile 的默认配置。合并 vision 时按字段进行，空值不覆盖有内容的值。

⚙️ 配置项

两种模式

auto / sticky 是旧的模式名，仍被接受并映射到 switch。

🔍 审计与排查

mounted mode=digest vision=image-router-vision/qwen3.8-max maxTokens=900 timeoutMs=120000 label=true dryRun=false
config-resolved overrides=… visionKeys=endpoint -> image-router-vision/qwen3.8-max   # 生效的是哪条路由
endpoint-route-live provider=image-router-vision model=qwen3.8-max modalities=text+image
tool-registered name=describe_image vision=…
digest session=<id> vision=<provider>/<model> images=1 chars=147 names=probe.png   # 一次成功的旁路分析
digest-retry reason=reasoning-consumed-budget budget=900->4096 images=1            # 预算被思考吃光，重试
digest-retry-ok budget=4096 chars=408
tool session=<id> path=<路径> mediaType=image/png bytes=2322 chars=113             # 一次 describe_image 调用
digest-dryRun session=<id> images=2                                                # dryRun 下的判定
digest-failed reason=<消息> code=<码> images=1                                     # 视觉调用失败 → 保留图片
digest-empty images=1 budget=900 chunks=… finish=…                                 # 模型没输出文本 → 保留图片
digest-admit-failed <原因>                                                         # 图片落盘失败 → 不替换
digest-skipped no attachment service                                               # 没有 attachments 服务
settings-invalid <问题>                                                            # 保存的配置没通过校验，沿用上一份
session=<id> error=<消息> at=<栈帧>                                                # 插件内部异常（已兜住，提示词照常发出）

排查顺序：有没有 mounted（没有 → 没挂上）→ 有没有 config-resolved … -> <路由>（确认生效的是哪条）→ 贴图那一刻有没有 digest … chars=（没有 → 看是 digest-failed、digest-empty 还是 digest-skipped）→ 工具是否可用看有没有 tool-registered。

🔐 安全

• API Key 只写不读：Host 收到后写进凭据库；normalizeConfig 从解析结果里剥掉 endpoint.apiKey（env.config 的任何读者都看不到密钥），configBase 不把它写进设置节，卡片编辑器用 withoutKey(...) 播种（旧版本写下的密钥不会被回填进草稿、也就不会被下一次保存写回去）。端点档写凭据时从声明它的那一层现场读取明文。
• 凭据存成引用名：$DSH_HOME/.credentials.yaml 的 refs.IMAGE_ROUTER_VISION_API_KEY（可用 apiKeyEnv 改名）。选引用名而不是泛型 key，是因为 pi-ai 解析 apiKeyEnv 走的正是这一层（credentialRef(name) → ctx.credentials.resolve(...)），与你原有的 provider 同一种形态。
• 只写自己那一条路径：端点档用 settings.mutate('llm-pi-ai', [{op:'set', path:['providers','image-router-vision'], …}])，你原有的 provider 不会被整体覆盖；写入前先读回现值做合并 —— 你在「设置 → 模型」给这条路由加过的 headers / compat / timeoutMs 不会被一次保存抹掉。
• 旁路调用计入你自己的额度：走的是 vision 路由的 provider 与凭证（和正常请求同一套配额），但不写入会话日志。

⚠️ 已知限制

• 会话历史里留下的是文字分析，不是图片：这是「不切模型」的必然代价（图片块被替换）。附件本身仍持久保存在 $DSH_HOME/attachments/ 下，审计行也记了文件名。
• 准入会等旁路调用：发送时 session/prompt 会等到分析完成才返回（通常几秒到十几秒；推理模型可能 40 秒以上，必要时再加一次重试），GUI 的发送按钮在此期间保持等待。
• 一次提示词一次调用：同一条提示词里的多张图合并成一次视觉调用，产出一个文字块；describe_image 每次调用只处理一个文件。
• describe_image 与内置 read_image 的分工：read_image 受「当前步骤路由必须声明 image」限制；describe_image 走旁路调用，任何模型都能用。主力换成纯文本模型后让模型改用后者即可。
• 包装 sessionController.prompt 是非官方扩展点：未来版本若改名 / 换实现，插件会退化为「不处理 + 记 warning」，不会崩。工具注册走官方 ctx.tools.register()。
• switch 模式会出现模型切换提示：借出视觉路由会写 model/selection，模型选择器会跳、GUI 会出现 [model changed]。想要全程无感请用默认的 digest。

🖥️ 兼容性

🛠️ 开发与测试

node --test                  # 标准写法（Node 自带发现，20/22/24 通用）
node test/routing.test.js    # 单进程直跑：没有管道支持的沙箱里用这个
node tools/check-contract.mjs   # 打包契约（CI 跑的就是它）

node --test test/ 不可移植：Node 20 会扫描目录，Node 22+ 把 test/ 当成单个入口文件去加载而报 MODULE_NOT_FOUND。

打包契约由 tools/check-contract.mjs 一处定义，ci.yml 与 release.yml 都调它，所以两边不会漂移、你也能跑 CI 跑的同一份。它守住四件事:① 声明的补丁文件存在;② 声明的浏览器一半存在;③ 入口导出满足 loader 消费的那套(含 Config 必须能答 Cordis 的 ~standard.validate、settings 服务的调用与 toJSON() 字段图 —— 断言的是两种 schema 形态都满足的契约,safeParse 刻意不在其中,因为 fallback 有而真 schemastery 没有);④ README 顶部那行版本号与 package.json 一致 —— 这两个文件靠人手同步,而 npm 页面显示一个、registry 服务另一个,除此之外没人会发现它们漂移。

68 个用例：配置归一化与校验（含旧模式名映射、schema 物化出的空对象/空数组、端点档补齐 vision 路由与两档优先级）、图片信号判定、digest 的替换/多图合并/失败保留/无图直通/dryRun/落盘失败/完成块兜底/对象 finish 原因/预算被思考吃光后重试、describe_image 的注册/读文件/问题透传/拒绝路径、设置节的注册与「保存后下一轮即生效」、校验失败被忽略、自定义端点写入上游路由与凭据（含"跳过/失败不得记为已同步"的可重试契约、以及"合并而非覆盖上游 profile"）、图片能力 oracle、schema 契约、浏览器半边激活契约、section base 不得遮蔽端点、switch 的借出‑归还‑放弃状态机、holdTurns、sticky、冷会话不路由也不告警、审计可写与不可写、无 sessionController 时不包装、卸载恢复。

CI（.github/workflows/ci.yml）在 Ubuntu + Windows × Node 20/22/24 上跑同一套用例，并跑上面那份打包契约。

lib/index.js             宿主一半：配置归一化、准入前替换、describe_image、审计、端点档
lib/endpoint.js          自定义端点档：翻译成上游 llm-pi-ai 路由 + 凭据
lib/settings.js          设置命名空间注册
client/client.js         浏览器一半：设置卡片（两档选择器、端点表单）
cordis.patch.yml         包内补丁：只插入一条 loader 条目（部署无关）
examples/                配置示例
tools/check-contract.mjs 打包契约（两个工作流共用）
tools/release.mjs        发版准备：同步两处版本号 → 校验 → 提交 → 打 tag
tools/*-probe.mjs        五个运行时探针（digest / tool / switch 序列 / 服务形状 / 调用链）

🤝 参与贡献

• 改代码走 PR（feat/* / fix/*）；纯文档可直接推 main。

• 提交前自检：node --test 与 node tools/check-contract.mjs，并确认 README 里描述的行为与代码一致 —— 本仓库的约定是每条实现要点都来自实测，README 里的「已验证」表也是这么攒出来的。

• 报 bug 时请附上审计文件里对应的那几行（mounted / config-resolved / digest 或 digest-failed）—— 这条链路上的失败方式大多是静默的，那几行是唯一可读的线索。

• 发版：一条命令准备，一个 tag 发布。版本号写在两个文件里（package.json 与 README 顶部），release.mjs 会同时改掉、并在打 tag 前跑完契约检查与单测 —— CI 会拒绝的东西，本地就先拒绝掉：

  node tools/release.mjs 0.4.5          # 改版本号 → 校验 → 提交 → 打 tag（不推送）
  git push origin main v0.4.5           # 这一步触发发布
  # 想一步到底：node tools/release.mjs 0.4.5 --push
  # 只看会发生什么：node tools/release.mjs 0.4.5 --dry-run
  

  它还会拦住几种"不可撤销"的情形：工作树脏（tag 会指向一个不存在的树）、版本号不递增、tag 已存在、该版本已在 npm 上（版本号不可覆盖）。--push 是显式选填的 —— 不可逆的那一步应该是决定,而不是某个参数的副作用。

  CI 会先跑单测与打包契约检查，再校验 tag 与 package.json 版本一致（不一致直接失败，避免把错版本发出去），然后发布到 npm 并创建 GitHub Release。用的是 npm Trusted Publishing（OIDC）：仓库里不存任何 token，也不需要交互式 2FA，npm 会为产物生成 provenance 签名。也可以在 Actions 页面手动触发，默认是 dry run（只打包校验、不发布）。

• 发布是异步的：npm publish 返回成功只代表 registry 受理了。packument 会先更新，tarball 与 npm install 可能还要几分钟才可用 —— 刚发完就装会看到 ERR_PNPM_FETCH_404，那是传播延迟，不是失败（本项目实测约 5 分钟）。

🧩 工作原理

1. 准入前替换：包装 sessionController.prompt，在调用原方法之前改写 request.content。图片块被移除、替换成一段文字 —— 因此准入校验看不到图片，不会拒绝、也不需要改模型。
2. 图片内容的两种形态：wire 形态 { type:'image', mediaType, data(base64), name? }；准入后形态 { type:'image', attachment: ImageAttachmentRef }。插件用 ctx.attachments.admitPromptContent(images) 把前者落盘成后者。
3. 旁路调用是标准一次性请求：ctx.llm.stream({ provider, model, messages, maxTokens, sessionId, signal })，消息为 { id, role:'user', source:{kind:'plugin', plugin:'image-router'}, content:[…] }。端点、凭证、重试策略、附件解析全部复用部署自己的配置。
   • 不传 purpose：它的类型是封闭枚举 'compaction' | 'session-title'，自定义值不合法。
   • signal 是 AbortSignal.any([调用方 signal, AbortSignal.timeout(timeoutMs)])。
   • 这次调用不写入会话日志。
4. 失败就保留图片：视觉调用失败时不替换，把原请求交给原路径，让它给出真实的错误，而不是被插件掩盖。
5. 替换文本里不放文件名：shot.png 这种名字会被模型当成可读路径去调 read_image，在纯文本模型上换来一条没必要的报错。文件名只留在审计文件里。
6. 必须用可选注入：sessionController 只由 dsh-web-app 提供；顶层 inject 会让 headless/sdk/acp profile 启动失败（1 entry did not activate）。
7. 端点档要等三个服务一起就绪：ctx.inject(['llm', 'settings', 'credentials'], …)。只等 llm 是个真实的坑 —— 那个回调在 entry 激活时就跑，此时设置节还没注册，get('settings') 返回 undefined，端点同步被静默跳过。
8. "跳过"不能算"已完成"：同步只在真正落盘（endpoint-route-ok）后才记下签名。签名初值是 '' 而不是 undefined —— 否则每次启动都会被判成"要撤回"，误发一次 unset 把上一次会话写入的路由删掉。
9. 密钥只写不读：apiKey 从配置里取走后立即从解析结果上剥掉，并且不参与签名比对 —— 否则同一个端点会不断被判定为"变了"而重复写凭据。
10. 自定义路由必须声明图片模态：pi-ai 的 defaultInput 是 ["text"]，模型条目不写 input: [text, image] 就会被当成纯文本模型，图片会被投影成占位文字而不是发到端点。
11. 解析探测留痕：写完后做一次只读的 llm.resolveModelInfo(provider, model)，把结果写进审计 —— 这是"我配的端点到底生效没有"唯一可读的答案。
12. 图片能力 oracle 注册在自己的命名空间上：浏览器唯一能发的模型类请求是 remote.llm.discoverModels(settingsNs, request)，而 settingsNs 只能填它知道的命名空间。过滤必须留在宿主：inputModalities 从不过河到浏览器。
13. 写入必须"读-改-写"：settings.mutate 的路径操作在 ['providers','image-router-vision'] 上是整体替换，而这条路由同时也是「设置 → 模型」页能编辑的路由 —— 直接写会抹掉用户在那边加的字段。
14. 答复要同时读 delta 和完成块：dsh-llm-pi-ai 把 text_delta 映射成 {type:'text-delta', text}、把 text_end 映射成 {type:'block-end', block:{type:'text', text}}。不发增量的 provider 只给后者 —— 只读 delta 会拿到空串，且 finish 是 stop、没有任何报错。
15. finish.reason 是对象：mapStopReason 返回 { kind: 'stop' | 'max-tokens' | 'error' | … }，失败细节在 reason.failure.{code,message}。拿字符串比会吞掉适配器报的每一个错误，把可诊断的失败变成静默的空答复。
16. token 预算与模型思考共享：在 openai-completions 上 maxTokens 作为 max_completion_tokens 发出，推理和正文共用。推理模型可能把预算全花在思考上 —— 此时插件自动用 max(4×, 4096)（上限 32768）重试一次。
17. Config 的 schema 是双形态的：能解析 @deepseek-ai/schemastery 时用它，否则退回零依赖等价实现。解析是多锚点的（本文件位置 → 运行中的 CLI → npm 全局根），因为插件装进 profile 后宿主的 node_modules 不在 profile 往上的解析路径上。设置页是遍历 schema.toJSON() 渲染的，所以一个"字段图为空"的描述会让整个模型页加载失败 —— 这是真机踩到的。

✅ 已验证

🔗 参考实现

• kanchengw/image-router — Codex++ 的 HTTP 代理：拦截 image_url，调 VL API 生成 [IMAGE ANALYSIS] 文字后替换图片再转发（本插件 digest 模式即此语义）
• lll888666/codex-deepseek-vision-fallback
• rongyaozhixing/codex-vision-plugin
• ningyougan/deepseek-vision-mcp