DeepSeek Harness messages transport failed：DSH plugin 报错排查

DeepSeek Messages transport failed（code: TRANSPORT）不是「网络坏了」的结论，而是 DeepSeek Harness 传输层的兜底标签：它在 packages/llm/llm-deepseek/src/adapter.ts 的 catch-all 里抛出——只要逃出来的错误既不是 LlmError、也不是空闲超时或主动取消，就一律被包成 TRANSPORT（来源）。 所以排查的第一动作不是换网络，而是分清「这次请求到底发出去了没有」，再去读 cause 里的真实错误。想核对环境里最近动过什么插件，可以到 DSH Plugin Hub 看已安装列表。（这里说的插件，中文也常写作 DSH插件、DeepSeek插件。）如果 transport failed 与流式断流、半包混在一起，按《transport failed 与流式断流：5 分钟分诊》判断。

这条报错出在 DeepSeek Harness 哪一层：传输层兜底，不是模型推理失败

源码里这个 catch 明确分四路，只有「都不是」的那一类才叫 TRANSPORT（来源）：

1. 空闲看门狗超时 → 报 TIMEOUT，文案是 DeepSeek Messages stream idle timeout；
2. 请求被主动取消（signal 已 abort）→ 报 ABORTED，文案是 DeepSeek Messages request aborted；
3. 本来就是 LlmError → 原样再抛，保留自己的错误码；
4. 其余一切 → 包成 TRANSPORT，这正是你看到的那句。

从这四路能推出两个很有用的结论：

1. 真正的模型 / API 业务错误不会长成这句。鉴权失败、参数不合法、配额不足这类问题本身就是 LlmError，走的是第 3 路，会带着自己的 code 出现。所以看到 TRANSPORT，说明失败发生在请求准备、连接建立或流式传输这一圈，而不是模型那头给出的业务拒绝。
2. 真实原因没丢，就在 cause 里。抛错时以 { cause: error } 保留了原始对象——外层那句话是标签，底层那个才是身份。

DeepSeek Harness 传输类报错速查：四种归类，先对号

同样一次请求失败，落到日志里可能是四个不同的 code；先看清自己在哪一格，再决定要不要重试（来源）：

一句话：只有最后一行是「没能归类」，前三行都自带明确身份。所以拿到 TRANSPORT 时，要做的不是「再试一次」，而是把它还原成 cause 里的真实 code。

按层排查：从网络到 DeepSeek Harness 会话日志里的 cause

推荐顺序：先看请求发没发出去，再看端点返回码，最后读会话日志里的真实错误。 逐层检查：

1. 网络与代理：能不能直连模型端点、代理有没有对 HTTPS 做重签。若环境里有杀软或企业代理，先看《杀软 TLS 证书链报错》——那类故障也会落到同一句文案上。
2. 这次请求发出去了没有：这是信息量最大的一条判据。HTTP 请求数为 0、失败在几十毫秒量级，说明错误发生在本地准备阶段；若请求已发出后在流式过程中被截断，才是连接层的问题。
3. 端点上最近一次请求的返回码：200 说明通了、问题在流式阶段或本地；401 / 429 这类属于 LlmError，本不该显示为这句，若显示为这句，多半是请求还没走到应用层就被拦了。模型端点的配置方式见官方文档。
4. 会话日志里该轮的真实错误：翻 turn/end 记录的 reason 与错误对象，把 cause 展开，看里面的 code 到底是什么——附件缺失会写 ATTACHMENT_NOT_FOUND，而不是 TRANSPORT。
5. 重试与续跑：TRANSPORT 在默认可重试集合里，会按退避链重试若干次，耗尽后该轮才失败；日志里的 llm/retry 条数就是重试次数的痕迹（#7834）。会话本身不会因为这一轮失败而消失，定位到真因、修好之后再重跑该轮即可。

一个常见误区：看到 TRANSPORT 就去反复重试。 如果底层是「本地文件不存在」这种确定性错误，重试是纯延迟——把错误还原成原始 code 后，它本来就不该进入重试集合。

翻日志之前：两条命令先确认「本地能出去」

在打开会话日志之前，先用两条命令把本地这一层确定下来，能省掉一半猜测。

# 1) 本地有没有代理在拦（企业代理 / 抓包工具常在这里露头）
env | grep -i -E 'https?_proxy|no_proxy'
# 没有输出 = 未设代理；有输出 = 记下地址，对照它是否对 HTTPS 做了重签

# 2) 直连模型端点，看连接是否建立、耗时是否正常（URL 换成你的提供方基础地址）
curl -sS -o /dev/null \
  -w 'HTTP %{http_code}  连接 %{time_connect}s  总耗时 %{time_total}s\n' \
  https://api.deepseek.com/v1/models

预期：第 2 条能打出 HTTP 200 / 401 / 403 这类真实返回码，说明本地网络层是通的，问题更可能在流式阶段或本地准备阶段；若连接耗时可忽略不计却直接报证书错误，则对应到「代理 / 杀软重签」那一类。注意：这一步只能证明「本地能出去」，不能证明「会话里的失败就是网络原因」——最终判据仍是前面那条：请求发出去没有。

与相邻 DeepSeek Harness 报错区分，以及怎么预防复发

同样是 DeepSeek Messages transport failed 这一句，至少有两种成因，判据就是「请求发出去了没有」。

还要和另外两类报错分开：

1. 模型连通性配置类（《模型连接排查》）：那是端点、密钥、网络出站的白名单问题，通常报的是鉴权或连接类错误，不是这句兜底标签；
2. 前端连不上宿主类（《Web UI 连接报错》）：那是浏览器与 DeepSeek Harness 之间的通道问题，与模型请求的传输层是两段不同的链路。

预防复发的几条实用做法：

1. 让流式请求跑完：别在模型生成中途切网、切代理或休眠；
2. 给代理与杀软放行：把模型端点加入白名单，避免 HTTPS 被中间重签；
3. 别手删附件对象：附件是内容寻址存储，删掉且无备份就无法重建，引用它的会话会持续失败；
4. 环境变更有迹可查：插件增删、版本更新都集中管理，排查时先看「最近动了什么」，DSH Plugin Hub 的已安装列表与系统日志可以对照着看。

关于 DeepSeek Harness messages transport failed 的注意事项

一句话总结：它是「没能归类」的标签，排查顺序是「请求发没发出 → 端点返回码 → cause 里的真实 code」。

1. 别先怪网络：这句由兜底 catch 抛出，业务错误根本不会长成它；
2. 先看请求数：0 请求 = 本地准备阶段，有请求 = 连接或流式阶段；
3. 一定翻 cause：真实错误码一直在里面，只是没渲染到外层；
4. 区分 TIMEOUT 与 ABORTED：空闲超时和主动取消各有自己的归类，不要都当成传输失败；
5. 重试要看值不值：确定性错误重试无意义，先定位再重跑；
6. 同字符串不同成因：附件缺失与 TLS 重签都会落到这句，按「请求发没发出」分流；
7. 相邻报错另查：连通性配置看《模型连接排查》，前端通道看《Web UI 连接报错》。

关于 DeepSeek Harness messages transport failed 的常见误解

五个最容易走偏的判断，逐条纠正：

1. 「既然叫 transport failed，那一定是网络问题」——不是。它由兜底 catch 抛出，含义是「失败没能归类」，网络只是可能的成因之一。
2. 「模型拒绝了请求才会报这句」——反了。业务拒绝本身是 LlmError，会带着自己的 code 原样抛出，不会长成这句兜底文案。
3. 「把 TRANSPORT 加进重试就能解决」——未必。若底层是「本地文件不存在」这类确定性错误，重试只是纯延迟。
4. 「空闲超时和主动取消也算传输失败」——不算。它们分别是 TIMEOUT 与 ABORTED，是与 TRANSPORT 并列的另外两条归类。
5. 「同一句报错，处理方式就一样」——不一样。附件缺失与 TLS 重签都会落到这句文案上，要靠「请求发没发出」来分流。

来源：DeepSeek Harness 源码 - llm-deepseek/src/adapter.ts、DeepSeek Harness 官方文档 - 配置模型提供方、#7834。