ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness 报 transport failed:图片工具结果与 TRANSPORT

故障排查发布于 2026-11-03作者: DeepSeek Plugin 插件市场
DeepSeek HarnessTRANSPORTtransport failedattachment图片工具结果prepareImages
一次工具返回图片后,DeepSeek Harness 会话每轮都报 DeepSeek Messages transport failed,耗时约 0ms。这不是网络问题:adapter 把普通 Error 兜成 TRANSPORT,真正抛错的是 prepareImages 读附件失败。本文给 0ms 判据与插件写法。

DeepSeek Harness(DSH)里最容易被甩锅给网络的一句报错,就是 DeepSeek Messages transport failed(TRANSPORT)。 它有时是真传输失败,但另一种常见情形是:某次工具调用返回了带 image 的结果块,之后这个会话每一轮都报同一句,耗时约 0ms,而网络完全正常。原因是 adapter.ts:80 把请求生成器内任何非 LlmError 的普通 Error 一律包成 LlmError('DeepSeek Messages transport failed', 'TRANSPORT')——真正抛错的是 prepareImages 在读取图片附件时失败。判据很干脆:0ms + 每轮必现 + 新会话正常 = 本地包装,不是网络(#11658)。

0 毫秒就是判据:真网络失败不会瞬间返回

一句话结论:报错耗时接近 0 毫秒说明请求根本没发出去,问题在发请求之前的本地准备阶段。 判据拆成三条:

  1. 看耗时。 预期:错误在约 0ms 返回。真网络失败要么等连接超时,要么经历重试周期,不会瞬间结束。
  2. 看复现范围。 预期:同一会话每轮都失败;新建一个不调用该工具的会话则完全正常。这条能直接排除 provider、账号、网络。
  3. 看触发点。 预期:故障总在某次返回图片的工具调用之后出现,本例是 dsh-cad-design@0.2.0 的 cad_render。
  4. 看重试有没有用。 预期:默认重试策略对 TRANSPORT 有 5 次重试,但这里重试也无效——因为每一轮的失败点都在同一个本地附件上,不会自愈。
  5. 看错误文案是否逐字相同。 预期:每次都是同一句 DeepSeek Messages transport failed,没有附带任何 HTTP 状态或网关细节。真网络失败往往会在 cause 里留下状态码或连接信息,逐字不变的包装文案反而说明源头是同一个本地异常。

这五条同时成立,就不要再查 DNS、代理、API key;把注意力转到「这条图片结果里到底有什么」。

机制:catch-all 把本地错误改写成网络错误

一句话结论:适配层为了统一错误类型做了 catch-all,代价是丢失原始错误语义,让本地附件问题伪装成传输失败。 两处实现:

  1. 包装点在 packages/llm/llm-deepseek/src/adapter.ts:80。 请求生成器内抛出的任何非 LlmError 异常,都会被包成 LlmError('DeepSeek Messages transport failed', 'TRANSPORT')。原始的 Error 通常留在 cause 上——这就是为什么「看 host 日志里那条 error 的 cause」是第一步。

  2. 抛错点在 packages/llm/llm-deepseek/src/images.ts:41-62 的 prepareImages。 它遍历每条用户消息与工具消息,对每个图片引用在 :55 调 attachments.readImageRequest(...)。附件缺失或读不出就抛普通 Error,于是被上一层包成 TRANSPORT。

为什么是「永久」而不是「偶发」:那个坏块留在了会话历史里。之后每轮都要重建请求,prepareImages 又会把同一附件读一遍、又失败一次。除非你把坏块从历史里拿掉或换会话,否则它永远不会自己好。

这也解释了为什么报错文案指向网络:包装层只保留了错误码,没有把 cause 提升到用户可见的位置,于是所有人第一反应都是「网络断了」。

三步取证:cause、附件是否存在、字节是否可解码

关键判据是:cause 里能看到附件读取失败,而 attachmentId 指向的记录不存在或读不出。 按顺序:

  1. 在 host 日志里找到那条 TRANSPORT 并读它的 cause。 预期:cause 不是网络栈错误,而是附件读取相关错误(找不到记录、读取失败、解码失败)。这一步就能把「真网络失败」和「本地包装」分开。

  2. 核对图片块里的 attachmentId 是否真的存在。 本例的结构是:

json
{"type":"image","attachment":{"attachmentId":"sha256:ce7f7d98…","mediaType":"image/png","bytes":9466,"width":472,"height":472,"name":"cad-preview.png"}}

预期:去附件存储里查 sha256:ce7f7d98… 是否有对应记录。如果查不到,就说明插件是手工拼了一个带 id 的结构,而没有真正把字节登记进附件服务。

  1. 如果记录存在但读取失败,验字节。 预期:把该附件取出来,检查字节长度是否与声明的 bytes 一致、能否按 image/png 解码。长度不符或解码失败,说明内容损坏或媒体类型写错。

  2. 对照一个正常会话做确认。 新建会话、不调用 cad_render,预期:对话正常。再回到原会话发一句普通消息,预期:仍然 0ms 失败。两次对照就把「坏块在历史里」这件事钉死。

插件侧的正确写法:先落盘,再返回块

一句话结论:图片结果里的 attachmentId 必须来自 attachment API 的真实登记,harness 没有能力凭一个 id 造出字节。 讨论里的结论很直接:如果第 2 步查到附件不存在,插件就需要先通过 attachment API 存储图片,再返回结果块。

给插件作者的检查清单:

  1. 不要在工具结果里手拼 {"type":"image","attachment":{...}}。 结构看起来对,但缺少真实落盘,prepareImages 一定读不到。
  2. 先调用附件服务把字节写进去,拿到真实的 attachmentId、bytes、mediaType、宽高,再组装结果块。
  3. 返回前自检一次:用同一个 attachmentId 调一次读取接口,确认能读出、长度与声明一致。
  4. 出错要带结构化错误,不要抛裸 Error。 否则会被适配层包成 TRANSPORT,把「我的图片没存好」伪装成「用户网络坏了」。
  5. 升级时回归这条路径。 图片结果属于高风险返回值:一次失败就让整个会话不可用,测试成本远高于普通文本块。
  6. 考虑给结果块加自描述字段,例如渲染宽度、来源工具与生成时间,方便用户在会话不可用时判断该块来自哪次调用,而不是只看到一个 sha256: 前缀。

边界说明:这条约束属于插件与 harness 之间的约定,不是 DSH 的配置项。用户在界面里找不到「修复图片附件」的开关,也不应该去找——问题只能由插件侧修正返回方式。

用户侧应急:换会话,别在坏会话里硬聊

一句话结论:坏块已经写进历史,当前会话无法靠重试救回来;最实际的做法是新建会话,并升级或替换出问题的插件。 步骤:

  1. 新建会话继续工作。 预期:只要不触发同一个图片工具,对话与模型调用都正常。
  2. 确认是哪个插件。 回看崩溃前最后一次成功的工具调用,本例是 dsh-cad-design 的 cad_render。把它禁用或升级后,再试一次同类调用。
  3. 如果要保留原会话,需要移除那条带坏附件的工具结果。 这属于会话文件手术,先备份再改;不想动文件就放弃该会话,成本更低。
  4. 不要反复点重试。 默认重试策略对 TRANSPORT 有 5 次重试,但每一轮都会在同一处失败,重试只是重复同一条路径。
  5. 反馈时带上三样东西:TRANSPORT 的 cause、attachmentId、附件存储里是否存在该记录。这三样能让作者一次定位,不必来回猜。

一张表分开「真网络失败」与「本地包装」

一句话结论:耗时、复现范围、cause 三者组合,足以区分两类 TRANSPORT,不需要抓包。 对照如下:

特征真网络失败本地错误被包装
耗时有连接/超时耗时,通常数百毫秒以上约 0ms
复现范围所有会话、所有请求都可能失败只在特定会话,新会话正常
触发条件网络抖动、代理、DNS、限流某次带图片的工具结果之后
cause网络栈错误、超时、连接重置附件读取/解码错误、普通 Error
重试效果偶发时可恢复每轮必现,重试无效

把这张表贴进排查记录,下次看到 TRANSPORT 先花十秒对一遍,能省掉大半无效尝试。

排查注意事项

TRANSPORT 这个错误码最大的坑是「名字太像网络」,排查原则是先看耗时与复现范围。 六条要点:

  1. 0ms 基本等于「没发出去」,先怀疑本地准备阶段。
  2. cause 才是原始错误,不要只看最外层的 transport failed。
  3. 每轮必现 + 新会话正常 = 历史里有坏块,不是 provider 问题。
  4. attachmentId 必须可查,查不到就是插件没走 attachment API。
  5. 重试对这类错误无效,别把时间花在反复点发送上。
  6. 插件作者要主动避免裸 Error,否则下一次还会有人被这句话误导。

来源:Discussion #11658。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DeepSeek Harness 工具返回图片后每轮都报 transport failed,但网络是好的,为什么?

DeepSeek Harness 的这个报错通常不是网络失败,而是本地错误被 adapter 的 catch-all 包装成了 TRANSPORT。adapter.ts 把请求生成器内任何非 LlmError 的普通 Error 都包成 LlmError('DeepSeek Messages transport failed', 'TRANSPORT'),真正抛错的多是 prepareImages 读取图片附件失败。

怎么判断 DeepSeek Harness 的 TRANSPORT 报错是真网络问题还是本地包装?

在 DeepSeek Harness 里看耗时:报错约 0ms 说明请求根本没发出去,属于本地错误被包装;真网络失败通常要等连接超时或重试周期。再看是否每轮必现——坏块留在会话历史里,每轮重建请求都会重新解析同一附件并再次失败,而新会话不调用该工具就正常。

工具返回的 image 块里有 attachmentId sha256:…,怎么确认这个附件是否真的存在?

在 DeepSeek Harness 的附件存储里查这个 sha256 id 对应的记录是否存在、字节数是否与声明的 bytes 一致。如果不存在,说明插件是手工拼出了图片块而没有通过 attachment API 落盘;如果存在但读不出,再检查字节能否按声明的 image/png 解码,排除内容损坏或媒体类型写错。

插件作者应该怎么返回图片,才不会让 DeepSeek Harness 会话卡死在 TRANSPORT?

DeepSeek Harness 的插件必须先把图片字节通过 attachment API 落盘,拿到真实的 attachmentId,再返回带 image 的结果块;不能只拼一个带 attachmentId 的 JSON 结构。harness 无法凭一个 id 凭空造出字节,prepareImages 在每轮重新读取附件时就会失败。

相关术语

TRANSPORT
TRANSPORT 是 DeepSeek Harness 调用模型时表示传输层失败的错误码,文案为 DeepSeek Messages transport failed。它既可能来自真实网络异常,也可能是 adapter 用 catch-all 包装了任意本地普通 Error,因此不能单凭错误码判断归因。— https://github.com/deepseek-ai/deepseek-harness/discussions/11658
prepareImages
prepareImages 是 llm-deepseek 包在构造请求前处理图片的函数,位于 packages/llm/llm-deepseek/src/images.ts 约 41-62 行。它会遍历每条用户与工具消息,对每个图片引用调用 attachments.readImageRequest,读取失败就抛出普通 Error。— https://github.com/deepseek-ai/deepseek-harness/discussions/11658
LlmError
LlmError 是 DeepSeek Harness 模型适配层定义的结构化错误类型,带错误码以便上层按类型重试或提示。非 LlmError 的异常会被适配层统一包装,这正是本地附件读取错误被显示成 TRANSPORT 的原因。— https://github.com/deepseek-ai/deepseek-harness/discussions/11658

来源