Aether/docs/operations/conversion-failure-diagnostics.md

格式转换失败诊断导出

使用方法

在请求详情的失败或跳过节点中，点击「失败诊断」面板的复制按钮。 复制时才会读取已采集的正文；页面预览本身不会批量加载正文。 请分享整个 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. 验证原有正常映射、失败闭合以及凭据脱敏没有回退。