# 格式转换失败诊断导出

## 使用方法

在请求详情的失败或跳过节点中，点击「失败诊断」面板的复制按钮。
复制时才会读取已采集的正文；页面预览本身不会批量加载正文。
请分享整个 JSON，而不是只分享 `summary`。复制成功标志仅在剪贴板写入成功后出现。

## Schema v2

- `diagnostic`：错误码、请求/响应/流式阶段、源/目标格式、转换器标识、完整 JSON 路径及期望约束/实际值。
- `path_source`：`structured` 是后端结构化路径，`message_inference` 是历史文案推断，`protocol_inference` 是根据上游协议推断的原始字段路径，`unavailable` 表示没有可靠字段路径。通用 `$.finish_reason` 会按协议定位到具体原始字段，同时保留 `reported_path`。
- `stage_source`：区分后端阶段信息与历史记录推断。请求转换方向为客户端到上游；响应/流式转换方向相反。
- `versions`：前端版本、导出时网关版本、失败时运行版本。历史记录没有运行版本时保留 `null`，不能把导出版本当作失败版本。
- `request` / `node`：请求、候选、重试、模型及时间等定位信息。
- `reproduction.sources`：脱敏正文片段、字段样本和流式失败事件窗口。数组通配路径的样本带具体下标。
- `reproduction.missing_context`：未采集、无权限、正文过大、读取失败、缺少失败事件或路径等缺口。

后端只为明确匹配 `candidate_id` 的候选提供上游正文记录。历史记录仅有候选索引时，不把最后一次重试的正文猜成当前失败的正文。
原始客户端请求可在同一请求内共享，但不会把其他候选的上游请求/响应当作失败现场。
`body_ref` 不是下载地址；前端不访问其中的 URL，而是使用现有、受权限保护的正文接口。

## 完整性与安全边界

- `not_loaded`：尚未补取上下文。
- `sanitized_context`：必要来源已取得，但仍然经过脱敏、大小限制或事件窗口裁剪。
- `insufficient_context`：还缺少明确列出的信息，不能据此假设能够完整复现。
- `replay_ready: false`：导出的是供排查的证据包，不是可以无条件自动执行的请求。修改前应根据样本建立最小回归测试。

每份正文的下载/解码处理上限为 1 MiB，读取超时为 5 秒；导出 JSON 上限为 64 Ki 字符。
字符串、数组、对象深度与节点数量也有限制。流式窗口保留匹配失败的事件、帧序号及邻近事件；匹配不到时明确标记，而不是认定流尾就是故障点。

默认移除常见认证头、密钥、令牌、Cookie、密码、签名 URL 参数、正文文本和二进制数据。
脱敏是规则化处理，分享前仍需检查自定义字段和错误消息是否含业务敏感信息。
不会为了诊断绕过正文采集策略、授权或存储限制；也不会把 `error` 或未知结束原因映射成正常成功。

## 建议处理流程

1. 检查 `diagnostic.stage`、`path_source` 和 `missing_context`，区分转换器缺陷、合法的无损转换拒绝和上游失败。
2. 对照源/目标格式以及字段样本，建立最小失败输入；流式问题同时保留必要的前序事件。
3. 先补失败回归测试，再修复转换规则。
4. 验证原有正常映射、失败闭合以及凭据脱敏没有回退。