附件校验失败被包装为泛化 TRANSPORT 错误，且会话无恢复手段——单条坏附件可永久瘫痪会话

[zztmly]

对应已提交至 DSH Desktop 仓库的反馈：https://github.com/anywhere-labs/dsh-desktop/issues/714（本贴发在 Harness 核心仓库，供 dsh-llm-deepseek / dsh-attachment-local 维护者定位）

环境信息

项	值
DSH Desktop	2.0.3（Windows 11）
Harness	DeepSeek Harness web UI（desktop-hosted）
模型	deepseek-official / deepseek-v4-flash-vision-exp

现象

1. 会话历史中存在一条图片附件引用 { mediaType: "image/png", bytes: 87349, width: 820, height: 582 }，而其实际存储的字节是 JPEG（52×70）——格式/尺寸与引用不符；
2. 此后每一个包含该引用的模型请求（含后续所有轮次的新请求）都立即失败，界面只显示：

   DeepSeek API stream from https://api.deepseek.com failed  (code: TRANSPORT)
   

   并重试 5/5 全部失败；
3. 该会话从此无法再使用：重发消息、重新点击重试均失败，且没有任何"跳过失效附件""移除坏引用""查看真实原因"的入口；
4. 用户只能靠推断发现真因（应用日志里才有 AttachmentError: Stored attachment metadata does not match its reference）。

关键问题：这是确定性的、与网络无关的失败——同一时刻其它会话的模型请求完全正常，仅携带坏附件的会话瘫痪。但用户看到的错误信息是"网络/流"层面的 TRANSPORT，排查方向完全错误。

根因分析

1. 错误被泛化包装，丢弃真实原因（dsh-llm-deepseek）

lib/index.js streamWithConnection() 的 catch 分支（约 L1417–L1421）：

} catch (error) {
  if (timeoutOf(...)) throw new LlmError(`DeepSeek stream idle timeout ...`, "TIMEOUT", { cause: error });
  if (options.signal?.aborted) throw new LlmError("DeepSeek request aborted by caller", "ABORTED", { cause: error });
  if (error instanceof LlmError) throw error;
  throw new LlmError(`DeepSeek API stream from ${connection.baseURL} failed`, "TRANSPORT", { cause: error });
}

任何非 LlmError 的原始异常（包括附件解析阶段抛出的 AttachmentError / 文件读取错误）都被包装成统一的 TRANSPORT。cause 没有暴露到错误记录（会话 jsonl 中仅持久化 message/code），用户和排查者都看不到真实原因。

2. 附件校验严格且只在请求时才发现（dsh-attachment-local）

lib/index.js readImageFile()（约 L493–L508）：对存储字节做 sha256 校验并探测媒体类型/尺寸，与引用逐项比对，不一致抛 AttachmentError ATTACHMENT_CORRUPT（"Stored attachment metadata does not match its reference"）。

由于附件写入时（attachments.saveImage）未对字节做同样的探测/校验，三方插件可以轻易写入"字节与引用不符"的附件；失败被推迟到模型请求构建时，并且每次请求都重新失败——会话历史里没有任何机制移除或替换这条坏引用。

3. 无恢复路径

• 会话 jsonl 中该引用一经写入即不可变，重发消息会带着它再次失败；
• 没有"忽略损坏附件继续""移除该附件"的选项；
• 错误发生时 UI 无提示附件损坏，也没有指向 AttachmentError 的线索。

影响评估

• 任何集成 attachments.saveImage 的三方插件（画图、截图、网页快照等）一次字段错误即可让一个会话永久瘫痪，且误导用户排查网络/代理/API；
• 错误分类不准确：此类失败应属于"请求内容/数据"错误，而非传输错误；
• 无补偿手段：用户被迫新建会话，丢失全部上下文。

复现步骤

1. 在任意插件中调用 attachments.saveImage，传入 mediaType: "image/png"，但 data 为 JPEG 字节（可人工构造：把一张 PNG 重编码为 JPEG 后按 PNG 提交）；
2. 在会话中让模型请求包含该附件历史；
3. 观察：下一次模型请求立即报 DeepSeek API stream from https://api.deepseek.com failed（TRANSPORT），重试 5/5 全败；会话无法继续。

建议改进（按优先级）

1. 保留并展示真实原因：TRANSPORT 包装时把 cause（至少是 error 类型/消息）持久化并显示；或对附件类错误单独给出明确的错误码（如 ATTACHMENT_CORRUPT / ATTACHMENT_MISMATCH）与人类可读消息（"附件 xxx (sha256:…) 校验失败：存储为 JPEG 52×70，引用为 PNG 820×582"）；
2. 写入时校验：attachments.saveImage 在入库时即探测字节（mediaType/尺寸），与输入不一致时拒绝或修正引用，避免坏引用进入任何会话；
3. 恢复手段：提供"会话中移除/忽略坏附件"的能力（如重发时跳过失败附件并给出提示），或提供一键"克隆会话并丢弃失效附件"；
4. UI 提示：会话失败时若错误包含附件原因，提示用户可直接从该会话历史删除/替换对应图片。

本地证据

• 附件对象 1：sha256:79d3e8293c1746d1710b8b87c2a62ae99012b2c0a27fce1351ed379597978c9f（JPEG，87,349 B，SOF0 52×70；引用声明 image/png 820×582）
• 附件对象 2：sha256:4228a140df28101dd47c80b96db7a9b4459ea2a17d4edb494ee104abef48e804（JPEG，82,935 B，SOF0 108×48；引用声明 image/png）
• 应用日志：AttachmentError: Stored attachment metadata does not match its reference.（dsh-attachment-local/lib/index.js readImageFile）
• 会话记录：finish: error …TRANSPORT × 6（首次 + 5 次重试），turn/end error 同文案；两次独立测试均 100% 复现

[argszero]

对 alpha.1（HEAD cd5ef81481）逐条复核了三个根因——结论是三分之二的缺口仍在，但有一处已被新代码修复，值得区分清楚，避免修复方向打偏。

① 错误泛化（TRANSPORT 丢弃真因）—— alpha.1 仍然成立

packages/llm/llm-deepseek/src/adapter.ts:497-509 的 catch 与 rc.2 同构：

if (error instanceof LlmError) throw error
throw new LlmError(`DeepSeek API stream from ${connection.baseURL} failed`, 'TRANSPORT', { cause: error })

附件读取 :224 attachments.readImageRequest(ref, policy, signal) 位于 request() 异步生成器内、try（:488）之内——readImageFile 抛出的 AttachmentError 不属于 LlmError，必然落到 :509 被包装成 TRANSPORT。我 grep 了 packages/llm/ 全部源码：零处 AttachmentError / isImageAdmissionError 路由。值得注意的是 packages/attachment/attachment/src/error.ts:30 的类文档自称 "Stable failures suitable for host RPC error mapping"——文档与实现存在落差：错误码体系建好了，llm 适配层却从未消费它。

② 写入时校验缺失 —— alpha.1 已修复（这是最重要的一处）

rc.2 时代 saveImage 不校验字节与声明是否一致；alpha.1 的 attachment-local 重构已堵上：

• packages/attachment/attachment-local/src/index.ts:210-214 saveImage → prepareImageFile
• packages/attachment/attachment-local/src/store.ts:60-65 inspectMetadata：detected.mediaType !== declaredMediaType → IMAGE_TYPE_MISMATCH（:63）
• 批量路径 saveImages（index.ts:200-207）先 validateImageBatch；还暴露了公开的 validateImage()（:195-197）

也就是说，你复现步骤里"saveImage 传 PNG 声明 + JPEG 字节"在 alpha.1 写入时就会被拒绝，不会再产生坏引用。你那个坏引用是旧版代码写进去的——升级不会治愈已存在的坏引用（见 ③）。

③ 无恢复路径 —— alpha.1 仍然成立（存量会话仍会被永久瘫痪）

读取侧校验依旧严格且无降级分支：

• store.ts:281-309 readImageFile：:297 sha256 校验 → ATTACHMENT_CORRUPT；:305 元数据对照引用 → ATTACHMENT_CORRUPT
• readImageRequest → requestVersion（index.ts:225-231）：无 skip/salvage；request-projection.ts 也没有占位/忽略分支

所以升级到 alpha.1 后，历史遗留的坏引用依然每次请求都抛、会话依然打不开——写入时校验只防增量，不救存量。

修复建议（贴合现有机制，非新发明）

1. 分类：在 adapter.ts:508（instanceof LlmError 之后）加一条 AttachmentError 路由 → 独立 LlmError code（如 REQUEST_CONTENT 或专用 ATTACHMENT），把 error.ts 的文档承诺兑现；同时把 cause.message 持久化进会话错误记录，让用户看到"附件损坏"而不是"网络失败"。适配层已有同族先例：:226 的 providerRejectedNormalizedImage 说明图片错误分类机制是现成的，只是没接 AttachmentError。
2. 恢复：给 readImageRequest 加降级选项——ATTACHMENT_CORRUPT 时以占位块替代该图并写一条会话事件（"attachment corrupted, omitted"），而不是整请求硬失败；贴合 requestVersion 的变体机制（requestImageVariantId 已按 policy 区分变体，加一个 corrupt 变体是自然的扩展）。
3. 存量修复：这个场景与 Bug: Failed tool call causing session dead lock #4048（WebP 被 LM Studio 400 拒 → 每次重试同错死锁）同属"毒上下文重放"家族——持久坏输入 + 无逃生通道。离线侧可仿 dsh-doctor S7 的思路做一个"扫描坏附件引用并替换/移除"的会话修复工具（写时校验拦住新的，工具救存量）。

一句话：新代码已经拦住了源头（②），但错误分类（①）与存量恢复（③）仍是 alpha.1 的真实缺口——尤其 ③，升级用户手里的坏会话需要明确的处理路径。

[denial123789]

补充已发布的附件排查更新（v0.5.285）：https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/integrations/general-file-attachments.md\n\n本次把 metadata mismatch、被泛化为 TRANSPORT 的失败边界、写入时校验和不可变 Session 的 clone/omit 恢复契约加入指南。手册是独立社区资料，不是官方插件或 API wrapper。