请求超时诊断器d3vmeh/dsh-turn-doctor

dsh-turn-doctor

一个用于 DeepSeek Harness 的诊断插件，它会告诉你某一轮为何失败，以及究竟是哪个超时或设置导致了失败。

为什么需要它

一次 dsh 请求可能在多个不同的地方超时：

* dsh 的空闲看门狗（streamIdleTimeoutMs）
* SDK 请求超时（timeoutMs）
* Node/undici HTTP 定时器
* 模型服务器
* 单个工具调用

问题在于，UI 通常只显示最终的报错信息，而这些信息往往不够具体。

例如，Request timed out. 可能是 SDK 超时，也可能是 undici 的 300 秒响应头超时。terminated 可能意味着 undici 放弃等待响应体，也可能意味着模型服务器挂了。

这就很容易让人改错设置，然后眼睁睁看着请求又在整整 5:00 处失败。类似问题在 #3157 和 #4518 等讨论中都出现过。

dsh-turn-doctor 会自行测量每一次模型请求（首字节时间、字节之间的最长间隔，以及请求总耗时），并利用这些计时数据来定位最可能的故障点。

示例：

turn-doctor: session=session-ccc41e50 turn 1 attempt 1
verdict: Node's HTTP headers timer (undici) gave up waiting for the server's first response after 300.6 s.
evidence: no reply bytes in 300.6 s
fix: install dsh-fetch-timeouts to raise Node's HTTP timers; on llama.cpp this usually means the request was deferred behind a busy slot

它还能捕获一些否则很容易被忽略的故障，包括压缩失败和工具超时。

它能检测什么

| 层                          | 典型信息                                                | 建议的修复方案                                                                         |
| --------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| dsh 空闲看门狗              | pi-ai stream idle timeout after Nms                   | 调高 streamIdleTimeoutMs；如果请求被排队，检查 gate 或 --parallel                  |
| Node 响应头定时器（undici） | 约 300 秒时无任何字节的 Request timed out.            | 安装/配置 dsh-fetch-timeouts                                                         |
| SDK 请求定时器              | 在 timeoutMs 左右出现的 Request timed out.          | 调高该路由上的 timeoutMs                                                             |
| Node 响应体定时器（undici） | 响应中途约 300 秒无数据后出现 terminated              | 使用 dsh-fetch-timeouts，或将服务器配置为发送数据/心跳                                |
| 服务器关闭/崩溃             | 短暂间隔后出现 terminated 或 Connection error.      | 检查模型服务器日志                                                                     |
| 服务器无法访问          | 几乎立即出现 Connection error.                  | 检查服务器是否正在运行，以及 URL/端口是否正确                          |
| 上下文溢出            | request (N tokens) exceeds the available context size | 压缩、增大上下文，或降低压缩阈值                           |
| 空响应              | 请求完成但无内容                       | 检查 maxTokens / 推理强度                                                   |
| dsh-llm-gate 队列          | QUEUE_TIMEOUT、QUEUE_FULL                           | 提高 queueTimeoutMs 或降低子代理并发数                                  |
| GPU 故障                   | ErrorDeviceLost、decode() failed                    | 重启服务器；尝试更小的上下文                                              |
| llama.cpp 路由器重载     | 500 proxy error                                       | 检查 --models-max                                                                   |
| 压缩失败           | summarization truncated at the token cap              | 提高压缩预设的摘要上限                                              |
| 工具超时                | tool call timed out after Nms                         | 提高该工具的 timeoutMs                                                          |

每次重试尝试都会被单独诊断。dsh 已经显示重试倒计时，因此 turn-doctor 不会重复显示它们。

如果时间信息不足以区分两种可能的原因，它会如实说明，而不是假装知道。

安装

dsh plugin --profile web add dsh-turn-doctor

就这样。

判定结果会打印在 dsh 终端中。你也可以在聊天中运行 /why 来查看当前会话（包括子代理）的近期判定结果。

如果你已将路由超时从默认值修改过，请将它们添加到 ~/.dsh/profiles/web/cordis.patch.yml，以便 turn-doctor 能正确分类故障：

- id: turn-doctor
config:
providers:
llamacpp:
streamIdleTimeoutMs: 7200000
timeoutMs: 7200000
undiciTimeoutMs: 1800000   # if dsh-fetch-timeouts is installed
keep: 10                       # verdicts kept per session for /why

如果某个提供程序未配置，turn-doctor 会假定使用标准的 300 秒默认值。

说明

* turn-doctor 只诊断故障。它不会重试请求、更改设置，也不会向模型上下文注入任何内容。
* 如果 SDK 计时器和 undici 标头计时器都设置为 300 秒，那么首字节超时可能会有歧义。在这种情况下，turn-doctor 会报告 undici，因为修复它需要 dsh-fetch-timeouts；dsh 本身无法更改该计时器。
* 判定结果在 dsh 进程的整个生命周期内驻留在内存中（每个会话保留最近几条，供 /why 使用）。它们不会写入会话日志：dsh 拒绝加载包含它不认识的事件类型的日志，因此如果在那里写入插件事件，会导致会话无法恢复。
* dsh-error-lens 与此相关，但解决的是不同的问题：它在一个 Web 面板中按 HTTP 状态分组显示最近的失败。turn-doctor 使用请求计时来区分不同的超时层级，并且还覆盖了压缩和工具调用。

许可证

MIT