DeepSeek Harness 报 transport failed:图片工具结果与 TRANSPORT
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 毫秒说明请求根本没发出去,问题在发请求之前的本地准备阶段。 判据拆成三条:
- 看耗时。 预期:错误在约 0ms 返回。真网络失败要么等连接超时,要么经历重试周期,不会瞬间结束。
- 看复现范围。 预期:同一会话每轮都失败;新建一个不调用该工具的会话则完全正常。这条能直接排除 provider、账号、网络。
- 看触发点。 预期:故障总在某次返回图片的工具调用之后出现,本例是
dsh-cad-design@0.2.0的cad_render。 - 看重试有没有用。 预期:默认重试策略对
TRANSPORT有 5 次重试,但这里重试也无效——因为每一轮的失败点都在同一个本地附件上,不会自愈。 - 看错误文案是否逐字相同。 预期:每次都是同一句
DeepSeek Messages transport failed,没有附带任何 HTTP 状态或网关细节。真网络失败往往会在cause里留下状态码或连接信息,逐字不变的包装文案反而说明源头是同一个本地异常。
这五条同时成立,就不要再查 DNS、代理、API key;把注意力转到「这条图片结果里到底有什么」。
机制:catch-all 把本地错误改写成网络错误
一句话结论:适配层为了统一错误类型做了 catch-all,代价是丢失原始错误语义,让本地附件问题伪装成传输失败。 两处实现:
-
包装点在
packages/llm/llm-deepseek/src/adapter.ts:80。 请求生成器内抛出的任何非LlmError异常,都会被包成LlmError('DeepSeek Messages transport failed', 'TRANSPORT')。原始的Error通常留在cause上——这就是为什么「看 host 日志里那条 error 的 cause」是第一步。 -
抛错点在
packages/llm/llm-deepseek/src/images.ts:41-62的prepareImages。 它遍历每条用户消息与工具消息,对每个图片引用在:55调attachments.readImageRequest(...)。附件缺失或读不出就抛普通 Error,于是被上一层包成TRANSPORT。
为什么是「永久」而不是「偶发」:那个坏块留在了会话历史里。之后每轮都要重建请求,prepareImages 又会把同一附件读一遍、又失败一次。除非你把坏块从历史里拿掉或换会话,否则它永远不会自己好。
这也解释了为什么报错文案指向网络:包装层只保留了错误码,没有把 cause 提升到用户可见的位置,于是所有人第一反应都是「网络断了」。
三步取证:cause、附件是否存在、字节是否可解码
关键判据是:cause 里能看到附件读取失败,而 attachmentId 指向的记录不存在或读不出。 按顺序:
-
在 host 日志里找到那条
TRANSPORT并读它的cause。 预期:cause不是网络栈错误,而是附件读取相关错误(找不到记录、读取失败、解码失败)。这一步就能把「真网络失败」和「本地包装」分开。 -
核对图片块里的
attachmentId是否真的存在。 本例的结构是:
{"type":"image","attachment":{"attachmentId":"sha256:ce7f7d98…","mediaType":"image/png","bytes":9466,"width":472,"height":472,"name":"cad-preview.png"}}
预期:去附件存储里查 sha256:ce7f7d98… 是否有对应记录。如果查不到,就说明插件是手工拼了一个带 id 的结构,而没有真正把字节登记进附件服务。
-
如果记录存在但读取失败,验字节。 预期:把该附件取出来,检查字节长度是否与声明的
bytes一致、能否按image/png解码。长度不符或解码失败,说明内容损坏或媒体类型写错。 -
对照一个正常会话做确认。 新建会话、不调用
cad_render,预期:对话正常。再回到原会话发一句普通消息,预期:仍然 0ms 失败。两次对照就把「坏块在历史里」这件事钉死。
插件侧的正确写法:先落盘,再返回块
一句话结论:图片结果里的 attachmentId 必须来自 attachment API 的真实登记,harness 没有能力凭一个 id 造出字节。 讨论里的结论很直接:如果第 2 步查到附件不存在,插件就需要先通过 attachment API 存储图片,再返回结果块。
给插件作者的检查清单:
- 不要在工具结果里手拼
{"type":"image","attachment":{...}}。 结构看起来对,但缺少真实落盘,prepareImages一定读不到。 - 先调用附件服务把字节写进去,拿到真实的
attachmentId、bytes、mediaType、宽高,再组装结果块。 - 返回前自检一次:用同一个
attachmentId调一次读取接口,确认能读出、长度与声明一致。 - 出错要带结构化错误,不要抛裸
Error。 否则会被适配层包成TRANSPORT,把「我的图片没存好」伪装成「用户网络坏了」。 - 升级时回归这条路径。 图片结果属于高风险返回值:一次失败就让整个会话不可用,测试成本远高于普通文本块。
- 考虑给结果块加自描述字段,例如渲染宽度、来源工具与生成时间,方便用户在会话不可用时判断该块来自哪次调用,而不是只看到一个
sha256:前缀。
边界说明:这条约束属于插件与 harness 之间的约定,不是 DSH 的配置项。用户在界面里找不到「修复图片附件」的开关,也不应该去找——问题只能由插件侧修正返回方式。
用户侧应急:换会话,别在坏会话里硬聊
一句话结论:坏块已经写进历史,当前会话无法靠重试救回来;最实际的做法是新建会话,并升级或替换出问题的插件。 步骤:
- 新建会话继续工作。 预期:只要不触发同一个图片工具,对话与模型调用都正常。
- 确认是哪个插件。 回看崩溃前最后一次成功的工具调用,本例是
dsh-cad-design的cad_render。把它禁用或升级后,再试一次同类调用。 - 如果要保留原会话,需要移除那条带坏附件的工具结果。 这属于会话文件手术,先备份再改;不想动文件就放弃该会话,成本更低。
- 不要反复点重试。 默认重试策略对
TRANSPORT有 5 次重试,但每一轮都会在同一处失败,重试只是重复同一条路径。 - 反馈时带上三样东西:
TRANSPORT的cause、attachmentId、附件存储里是否存在该记录。这三样能让作者一次定位,不必来回猜。
一张表分开「真网络失败」与「本地包装」
一句话结论:耗时、复现范围、cause 三者组合,足以区分两类 TRANSPORT,不需要抓包。 对照如下:
| 特征 | 真网络失败 | 本地错误被包装 |
|---|---|---|
| 耗时 | 有连接/超时耗时,通常数百毫秒以上 | 约 0ms |
| 复现范围 | 所有会话、所有请求都可能失败 | 只在特定会话,新会话正常 |
| 触发条件 | 网络抖动、代理、DNS、限流 | 某次带图片的工具结果之后 |
| cause | 网络栈错误、超时、连接重置 | 附件读取/解码错误、普通 Error |
| 重试效果 | 偶发时可恢复 | 每轮必现,重试无效 |
把这张表贴进排查记录,下次看到 TRANSPORT 先花十秒对一遍,能省掉大半无效尝试。
排查注意事项
TRANSPORT 这个错误码最大的坑是「名字太像网络」,排查原则是先看耗时与复现范围。 六条要点:
- 0ms 基本等于「没发出去」,先怀疑本地准备阶段。
cause才是原始错误,不要只看最外层的transport failed。- 每轮必现 + 新会话正常 = 历史里有坏块,不是 provider 问题。
attachmentId必须可查,查不到就是插件没走 attachment API。- 重试对这类错误无效,别把时间花在反复点发送上。
- 插件作者要主动避免裸
Error,否则下一次还会有人被这句话误导。
常见问题
DeepSeek Harness 的这个报错通常不是网络失败,而是本地错误被 adapter 的 catch-all 包装成了 TRANSPORT。adapter.ts 把请求生成器内任何非 LlmError 的普通 Error 都包成 LlmError('DeepSeek Messages transport failed', 'TRANSPORT'),真正抛错的多是 prepareImages 读取图片附件失败。
在 DeepSeek Harness 里看耗时:报错约 0ms 说明请求根本没发出去,属于本地错误被包装;真网络失败通常要等连接超时或重试周期。再看是否每轮必现——坏块留在会话历史里,每轮重建请求都会重新解析同一附件并再次失败,而新会话不调用该工具就正常。
在 DeepSeek Harness 的附件存储里查这个 sha256 id 对应的记录是否存在、字节数是否与声明的 bytes 一致。如果不存在,说明插件是手工拼出了图片块而没有通过 attachment API 落盘;如果存在但读不出,再检查字节能否按声明的 image/png 解码,排除内容损坏或媒体类型写错。
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
来源
- #11658 — cad_render 图片导致会话永久 TRANSPORT 报错· deepseek-ai(GitHub Discussions)