hansjone/dsh-im-ops

Fork 0

mirror of https://github.com/hansjone/dsh-im-ops.git synced 2026-10-09 00:33:20 +08:00

xmanrui 9d2e9c800b fix(im): preserve cancellation during image fallback

2026-09-02 01:35:48 +08:00

14 KiB

Raw Blame History

入站图片非视觉模型文件回退方案

状态：已实施（P0）；Ubuntu CI、包产物验证与真实宿主非视觉模型端到端验收通过

日期：2026-09-01

关联：出站图片原生呈现落地方案、渠道原生能力建设方案

1. 结论

IM 对话中，非视觉模型收到图片时当前是准入即硬失败：图片字节在宿主 session.prompt 准入检查处被整体丢弃，LLM 收不到任何内容；而发送文件（如 zip）却能成功。本方案不改宿主、不新建媒体框架，只做一件事：

当宿主以 MODEL_DOES_NOT_SUPPORT_IMAGES 拒绝带图片的 prompt 时，dsh-im 自动把同一批图片字节转入现有入站文件管线（落盘到 Session 工作区 + <dsh_im_files> 清单），替换掉多模态内容块后重发一次 prompt。

效果：

非视觉模型不再对图片报错；图片以工作区文件形式到达 Agent，Agent 可用 run_code/pwsh（读字节、EXIF、OCR、图像库等）"以其他方式识图"。
视觉模型行为完全不变（继续原生多模态内容块）。
其他图片错误（超大、格式不支持、下载失败等）继续走现有报错，不回退。
收口在 harness-client.mjs 的 ask() 单点，九渠道 Bridge 无需各自改动。

与出站方案同样的原则：复用现有 inbound-file 生命周期（落盘、清单、turn 结束清理），不新增配置开关、不新增产物类型。

1.1 实施结果（2026-09-01）

本方案已按上述最小边界落地：

src/channels/shared/image-prompt.mjs 新增 IMAGE_FILE_FALLBACK_PROMPT（模型侧指引，含英文翻译）、imageFileSourcesFromContent()（图片内容块 → 文件源，含扩展名映射与文件名清洗）、contentWithoutImages()、isModelImageRejection()。
src/channels/shared/harness-client.mjs 的 ask() 将原入站文件落盘逻辑抽为 #stageWorkspaceFiles()；session.prompt 被以 MODEL_DOES_NOT_SUPPORT_IMAGES 拒绝且 content 含图片块时，把同一批字节经该管线落盘、重建纯文本 prompt（原文本 + 指引 + 合并后的单个 <dsh_im_files> 清单）并复用同一 promptRpcId 重试一次；重试不再回退，落盘失败时保留原始错误文案。staged 批次统一进入既有 turn 结束清理。
test/image-fallback.test.mjs 新增 9 个用例：转换/判定辅助函数、完整回退（复用 rpcId、字节一致、清单正确、turn 后清理）、混合消息合并清单、非模型原因不回退、落盘失败保留原错误、落盘期间保留调用方取消语义、重试失败不再重试、纯文本路径不变。
回归：Windows 本机以逐文件直跑方式执行全部 137 个测试文件，失败集与改动前基线（git worktree 对照）完全一致（23 个均为仓库既有的 Windows/沙箱环境性失败，CI 在 ubuntu 上通过）；npm run build 通过；verify-package 的可执行位检查在 Windows 上为既有环境性失败。
端到端：在真实 DSH 宿主进程内通过生产 apiProxy 与 fileIngressExecutor 链路向文本模型注入入站 PNG，验证了宿主拒绝、图片落盘、纯文本重试与模型工具分析的完整路径。

2. 现状与根因

2.1 入站文件链路（zip 能成功）

message.files ──► harness.ask(…, { files })
                 └► fileIngressExecutor（宿主进程内执行）
                    └► stageInboundFiles() 写入 <workspace>/.dsh-im/inbound/turn-XXXX/NN-名字（0600）
                 └► appendInboundFilesToPrompt() 在 prompt 末尾追加 <dsh_im_files> JSON 清单（工作区相对路径）
                 └► session.prompt（纯文本内容块）

代码：src/channels/shared/inbound-file.mjs（stageInboundFiles、appendInboundFilesToPrompt）、src/channels/shared/harness-client.mjs ask() 内 inboundFiles 分支、plugin-src/host/harness-session-coordinator.mjs 的 createFileIngressExecutor。
纯文本 prompt 不依赖模型输入模态，任何模型都能收到路径清单，再用工具处理文件。

2.2 入站图片链路（被拦截）

message.images ──► promptContentForMessage()（Bridge 内，含大小/数量/魔数校验）
                  └► content = [{type:'text'}, {type:'image', mediaType, data: base64}]
                  └► session.prompt RPC
                     └► 宿主 dsh-host-apiproxy prompt 准入：
                        resolveModelInfo(provider, model).inputModalities 不含 'image'
                        ──► 返回 attachment-error / MODEL_DOES_NOT_SUPPORT_IMAGES
                        （发生在 createUserMessage 之前，未产生任何 durable 消息）
                  └► HarnessRpcError 冒泡回 Bridge
                  └► imagePromptUserMessage() 翻译为用户文案：
                     "当前模型不支持图片，请用 /models 查看可用模型，再用 /model <序号> 切换后重发。"

代码：src/channels/shared/image-prompt.mjs（promptContentForMessage、HOST_ATTACHMENT_USER_MESSAGES）；宿主侧为 @deepseek-ai/dsh-host-apiproxy prompt handler（hasImage → resolveModelInfo 检查 → err）。
六个图片构建点（共享 text-harness-bridge.mjs 及飞书/QQ/钉钉/微信/企业微信各自 Bridge）全部经 harness.ask() 收口，因此回退只需改一处。

2.3 不对称的根源

维度	文件（zip）	图片
交付形态	工作区路径文本	多模态内容块
对模型能力的要求	无	`inputModalities` 含 `image`
失败时的降级	不适用	无（直接丢弃字节）

另一个限制：session.models / llm.models 返回的模型目录只有 id/name/description/reasoning，不含输入模态，dsh-im 无法预判当前模型是否支持图片；唯一的信号就是宿主拒绝时的 MODEL_DOES_NOT_SUPPORT_IMAGES 错误码——这也正是回退的触发器。

3. 设计原则

图片字节必须到达 Session 工作区，而不是被丢弃——这是"非视觉模型以其他方式识图"的前提。
不修改宿主。@deepseek-ai/dsh-host-apiproxy 是安装的 npm 包，改了会被升级覆盖；宿主侧改进作为上游建议另行反馈（见 §7）。
复用入站文件管线，不创建第二条图片生命周期：同样的目录结构、权限（0600）、turn 结束清理语义。
单点收口：回退逻辑只存在于 harness-client.mjs ask() 内，所有渠道自动获益。
不新增配置开关：对 MODEL_DOES_NOT_SUPPORT_IMAGES 的回退严格优于硬失败，默认启用；其余错误原因维持现有行为。
至多重试一次，防止错误码异常时的循环。

4. 方案设计

4.1 触发条件

在 ask() 中包装 session.prompt 调用，捕获 HarnessRpcError，当且仅当：

error.code === 'attachment-error' 且
error.details.reason === 'MODEL_DOES_NOT_SUPPORT_IMAGES' 且
本次 content 含 {type:'image'} 内容块

进入回退；否则原样抛出。

4.2 图片 → 文件源转换

从被拒 content 的 image 内容块直接构造文件源（字节已在内存，无第二次网络下载）：

// image-prompt.mjs 新增 helper（图片知识内聚；stageInboundFiles 无需改动）
const IMAGE_EXTENSIONS = new Map([
  ['image/png', '.png'],
  ['image/jpeg', '.jpg'],
  ['image/gif', '.gif'],
  ['image/webp', '.webp'],
]);

export function imageFileSourcesFromContent(content) {
  return content
    .filter((part) => part?.type === 'image')
    .map((part, index) => ({
      name: part.name ?? ('image-' + (index + 1) + (IMAGE_EXTENSIONS.get(part.mediaType) ?? '.img')),
      mediaType: part.mediaType,
      data: Buffer.from(part.data, 'base64'),
    }));
}

stageInboundFiles 的 loadedFile() 已接受 {data: Buffer, name, mediaType} 形态，无需改动即可落盘。
storageName() 已做文件名清洗；扩展名映射保证下游工具能按扩展名识别格式。
大小限制天然满足：promptContentForMessage 已按单张 5MB / 总量 20MB / 20 张校验过，转换不放大。

4.3 重发 prompt

保留 append 文件清单之前的 basePrompt（当前代码在 ask() 内先 prompt = appendInboundFilesToPrompt(prompt, stagedInboundFiles) 再发 prompt；回退需从原始 prompt 重建，避免出现两个 <dsh_im_files> 块）。
新 content = 原 text 内容块 + 回退提示文本 + 合并后的单个 <dsh_im_files> 清单（原 staged 文件 + 图片文件，一次 appendInboundFilesToPrompt 生成）。
提示文本（走 t()，中英双语）：

当前会话模型不支持直接接收图片输入。用户发送的图片已作为文件保存到工作区（见下方清单）。
请使用可用工具分析这些图片文件后回答，例如 run_code/pwsh 读取字节、解析元数据、
调用图像处理或 OCR 库；不要假设自己能直接看到图片内容。

再次调用 session.prompt（此时内容为纯文本，宿主不再走图片准入分支，也不受 serializeImageAdmission 串行化影响）。

4.4 生命周期与安全

幂等：宿主检查发生在 createUserMessage 之前，被拒的 prompt 未入队、未产生 durable 消息，重发不会造成重复消息或空 turn。
清理：图片文件与现有入站文件同语义——turn 结束后由既有 stagedInboundFiles.cleanup() 一并删除（回退实现需把图片 staged 结果并入同一清理集合；重试仍失败时立即清理）。
降级失败：若 #fileIngressExecutor 不可用（inbound-file-ingress-unavailable）或落盘失败，则不重试，按现有链路向用户报错（保留 MODEL_DOES_NOT_SUPPORT_IMAGES 的既有文案作为兜底，可追加"图片转文件失败"说明）。
旧宿主兼容：错误码不存在时（旧版本宿主不检查模态或行为不同）回退不触发，行为与今天一致。

4.5 用户可见行为

回退成功后不再报错，Agent 正常处理并回复；可选（P1）：通过现有 onUpdate 流在开头推一条一次性提示"当前模型不支持直接识图，已将图片保存为工作区文件进行工具分析"，让用户知情。
/models 文案与 HOST_ATTACHMENT_USER_MESSAGES 映射保留：仅在回退自身失败时作为兜底呈现。

4.6 改动清单

文件	改动	量级
`src/channels/shared/harness-client.mjs`	ask() 内 `session.prompt` 包回退：触发判断、保留 basePrompt、图片落盘、清单合并、重试一次、清理集合	~80 行
`src/channels/shared/image-prompt.mjs`	新增 `imageFileSourcesFromContent()`、扩展名映射	~30 行
`src/channels/shared/inbound-file.mjs`	（若需要）导出合并两个 staged 清单的 helper	~10 行
`src/channels/shared/i18n-en/*.mjs`	回退提示文本英文翻译	若干
`test/image-fallback.test.mjs`（新增）、`test/inbound-file.test.mjs`	见 §6	~150 行

5. 备选方案对比

方案	说明	取舍
A. 客户端响应式回退（本方案）	收到 `MODEL_DOES_NOT_SUPPORT_IMAGES` 后转文件重发	✅ 不改宿主、单点收口、旧宿主兼容；代价是多一次被拒往返
B. 宿主准入降级	apiproxy 在准入处把 image part 换成附件路径文本而非拒绝	效果最好（所有 API 客户端获益），但改的是安装的 npm 包，升级即丢；建议作为上游 issue 反馈，dsh-im 不依赖它
C. 模型目录暴露 `inputModalities`	宿主在 `session.models`/`llm.models` 增加模态字段	可让 dsh-im 预判、直接走文件路径省一次往返，`/models` 可加视觉标记；需宿主支持，旧宿主下仍靠 A 兜底；作为上游建议一并反馈
D. 纯文案优化	不回退，只改报错文案教用户切换模型	不解决"非视觉模型识图可能性"被阻断的问题

推荐：本期实施 A；B、C 作为上游反馈（对 DSH 宿主仓库提 issue），A 在 C 落地后仍作为旧宿主兜底保留。

6. 测试与验收

6.1 单元测试（新增 `test/image-fallback.test.mjs`，fake rpc/executor）

首次 session.prompt 返回 attachment-error/MODEL_DOES_NOT_SUPPORT_IMAGES → 断言：调用了第二次 prompt；第二次 content 无 image part；含 <dsh_im_files> 清单与回退提示文本；文件以正确扩展名写入 executor 收到的 sources；仅重试一次。
混合消息（图片+文件）→ 断言只出现一个合并后的 <dsh_im_files> 块。
其他拒绝原因（IMAGE_TOO_LARGE、TOO_MANY_IMAGES 等）→ 不回退，原错误冒泡，用户文案不变。
落盘失败时保留原始模型拒绝错误；落盘期间取消时保留调用方的取消原因。
回退 prompt 再次失败 → 仅报错一次，不继续重试。
纯文本/纯文件消息 → 不触发任何回退路径（回归）。
turn 正常结束后 staged 图片文件被 cleanup（复用 test/inbound-file.test.mjs 的断言模式）。

6.2 回归与手工验收

npm run check 全量通过。
真实宿主端到端：文本模型收到图片后走完“模态拒绝 → 工作区文件落盘 → 纯文本重试 → 工具分析”链路并正常回复；视觉模型与普通文件消息的原有行为保持不变。

7. 上游反馈（非本仓库范围）

向 DSH 宿主（@deepseek-ai/dsh-host-apiproxy）反馈两个改进建议：

prompt 准入遇到非视觉模型时，将 image part 降级为持久化附件路径文本（对应方案 B），使所有 IM/API 客户端天然获得该能力；
模型目录响应增加 inputModalities（对应方案 C），让客户端可预判并在 /models 中展示视觉能力标记。

8. 分期

P0（本期）：方案 A 全部内容 + 单测 + 真机验收。
P1：回退触发时的用户可见一次性提示；<dsh_im_files> 清单 description 中补充"非视觉会话请用工具分析图片"的指引（依赖 C 落地后可精化为按模型分流）。
P2：上游 B/C 跟进结果回流后，评估是否保留响应式回退作为兜底（预期保留）。

14 KiB Raw Blame History Unescape Escape