前言¶

DeepSeek Harness (DSH) 在处理模型请求失败时，通常会将错误归一化，例如在界面显示“本轮运行失败”。对于开发者而言，上游返回的具体 401、403、429 或 400 错误详情往往隐藏在这一句描述背后。当需要排查密钥失效、速率限制或请求体格式问题时，缺乏原始报文会导致调试困难。

dsh-request-error-dump 是一款 DSH 插件，旨在解决这一问题。它在模型请求失败时，将完整的原始请求体和上游错误响应体写入本地文件，保留完整的上下文信息。

核心功能¶

该插件专注于捕获模型推理过程中的失败场景，记录内容包含以下四个区块：

1. 请求信息 (request)：记录 URL、HTTP 方法、请求头（支持脱敏）、请求体原文 (body.raw) 及解析视图 (body.json)。
2. 响应信息 (response)：记录状态码、状态文案、响应头、以及上游返回的原始响应体 (body.raw) 和解析视图。
3. 传输层异常 (transportError)：记录 DNS 查询失败、TLS 握手错误、连接超时等网络层面的异常。
4. DSH 上下文 (dsh)：记录当前轮次 (turn)、步骤 (step)、提供商 (provider)、失败原因 (failure) 以及关联 ID (correlation)。

此外，插件支持配置 bodyFormat（仅 raw / 仅 parsed / 两者皆有）和 redactHeaders（指定需要脱敏的请求头名），默认开启零配置模式，仅抓取模型请求。

安装与启用¶

本插件无运行时依赖，安装后需重启 DSH 以使配置生效。

# 从 GitHub 安装
dsh plugin --profile desktop add github:exynos967/dsh-request-error-dump

安装完成后，失败的请求记录将默认保存在 ~/.dsh/request-error-dump/ 目录下。

配置说明¶

所有配置项均有默认值，不配置亦可正常运行。如需调整，需在 profile 的 cordis.patch.yml 中进行覆盖：

- id: request-error-dump
  config:
    outDir: ~/.dsh/request-error-dump      # 落盘目录
    maxFiles: 50                           # 保留最新的文件数量，0 表示不清理
    maxCaptureBytes: 0                     # 单体体积上限（字节），0 表示不截断
    bodyFormat: both                        # raw / parsed / both
    redactHeaders: ['authorization', 'api-key', 'cookie']  # 脱敏头列表
    flushDelayMs: 1500                     # 等待上下文补全的延迟时间（毫秒）
    ignoreAborted: true                     # 用户取消时不记录
    modelRequestsOnly: true                 # 是否仅抓取模型请求
    excludeUrls: ['/user/balance']          # 排除的 URL 列表（正则匹配）
    log: true                               # 是否在日志中输出落盘提示

关键参数说明：
* maxCaptureBytes：默认为 0，表示不截断请求体。一旦截断，json 视图将标记为 truncated: true。
* redactHeaders：默认脱敏 authorization、api-key 等常见凭证头。设为 [] 可关闭脱敏（存在隐私风险）。
* flushDelayMs：默认 1500ms。插件会等待 agent/request-error 事件来补全 DSH 侧的上下文信息。设为 0 则立即写入。
* excludeUrls：默认排除 /user/balance，防止桌面版余额组件轮询导致的垃圾日志。

判定与隐私¶

插件通过两条信号判断是否为“模型请求”：
1. 权威信号：DSH 循环派发 agent/request-error 事件认领。
2. 兜底信号：请求结构符合模型调用特征（POST 且 JSON body 包含 model 或 modelId 字段，或命中特定路径形态）。

隐私边界：由于请求体通常包含系统提示词、源码、工具结果甚至密钥，插件默认仅脱敏请求头中的凭证，正文一律原样保存。请勿在不可信环境或共享目录中开启此插件。

诚实边界¶

插件并非完美，存在以下限制：
* 判定精度：并非 100% 精确，极端情况（自定义网关且无 model 字段）可能漏抓。
* 捕获范围：不抓取流中途失败、FormData/Blob/ReadableStream 请求体（读取即消费）。
* 前置错误：不抓取发请求之前就失败的错误（如密钥未配置、路由无适配器）。
* 无修改能力：纯观察者模式，不重试、不注入、不修改请求。

结语¶

dsh-request-error-dump 通过拦截 HTTP 请求层，填补了 DSH 标准错误处理与开发者调试需求之间的空白。它以零运行时依赖和透明的工作机制，帮助开发者快速定位模型调用失败的根本原因。

插件目录 | GitHub 仓库