# 模型流式参数诊断

小型内置动作的参数流仍受 16384 字符保护。超限时关闭输出流、丢弃不完整参数，不执行该次动作；一次新响应重试和可用备用端点耗尽后，只结束当前任务，不进入共享的模型暂停。批次仍遵循“失败即停止”、人工暂停和取消设置。网络故障、认证错误和最终验收保留各自的恢复规则。

长度保护不是生成进度判断：小于上限但一直没有闭合或终止的参数，仍可能持续到单次请求或外层任务超时。超时、取消和完整性校验共同约束这条路径，未完成的参数不能作为动作执行。

## 请求关联

每个模型请求尝试沿用现有 `llm_diagnostic` 记录，不另建日志数据库。

| 字段 / 请求头 | 含义 |
| --- | --- |
| `request_id` / `X-Client-Request-Id` | 同一次恢复循环内保持稳定的逻辑请求编号；切换备用调用或恢复暂停后可能建立新的逻辑请求 |
| `attempt_id` / `X-Client-Attempt-Id` | 本次客户端尝试编号；重试时变化，`previous_attempt_id` 关联前次尝试 |
| `client_*_id_matches` | 实际发送的请求头是否与本地编号一致；调用方已指定的头保留原值 |
| `server_request_id` | 首个有效的 `X-Oneapi-Request-Id`、`X-Request-Id` 或 `Request-Id`，按此前后顺序选择 |
| `response_x_request_id` | 响应中的原始 `X-Request-Id`，不推定它来自模型上游 |
| `error_request_id` | SDK 异常带回的编号，不覆盖已经从响应头读取的编号 |
| `response_id` | SDK 实际返回的 Responses 响应编号 |

编号只接收有长度限制的可打印白名单字符。请求头不控制会话亲和性，不替换 `thread-id` / `session-id`。网关自身的重试应使用独立编号或序号，不能假装是一次新的客户端尝试。

## 参数指纹 v1

`tool_observation_layer=langchain_tool_call_chunks` 明确表示客户端观测的是 SDK 转换后的参数片段，不是原始 SSE 帧。每工具记录实际可得的 `call_id`、`chunk_index`、工具名，以及：

- `argument_chars`：参数片段的 Unicode 字符数之和。
- `argument_bytes` / `argument_sha256`：按原顺序连接片段后，其 UTF-8 字节长度和 SHA256；不解析、重排参数 JSON，也不规范化空白或 Unicode。
- `argument_deltas`：非空参数片段数，不能直接与网关原始事件数比较。
- `argument_prefixes`：每 4096 字节的累计 SHA256，最多保留前 16 个。可以在分片大小不同、上游预读或中途取消时比较相同字节位置。
- `argument_encoding_valid`：遇到不能编码为 UTF-8 的片段时为 false，当前总字节数和总哈希留空，避免伪造可比结果；诊断本身不改变执行流程。
- `argument_json_whitespace_chars` / `argument_json_whitespace_run` / `argument_json_whitespace_run_max`：实际空格、制表、回车和换行字符的总数、当前尾部连续数和最长连续数。统计的是这四种 JSON 空白码点，也包含字符串内部的实际字符；转义文本 `\\n`、不换行空格不计入。不据此判断 JSON 是否有效。
- `argument_delta_chars_min` / `argument_delta_chars_max`：非空参数增量的最小、最大字符数；尚无非空增量时最小值为空。
- `argument_same_delta_run` / `argument_same_delta_run_max`：连续相同非空增量的当前、最长出现次数，首个增量算一次，空增量不打断。只保留上一增量的 SHA256，不保留正文。相同增量内容不等于重复的协议事件，例如连续空格也可能来自不同的合法事件。

最多记录 64 个工具；超过时设置 `tool_stats_truncated=true`，总参数字符计数仍继续。诊断不保留参数正文。哈希仅证明已收到的字节前缀，不能证明输出完整或动作成功；完整性仍由响应终止状态和解析校验决定。

跨三端优先使用 `response_id + call_id` 关联。LangChain 的 `chunk_index` 可能因文本或推理子块不同于原始 `output_index`，缺失编号时不能按数组位置猜测。正常的 `arguments.done`、`output_item.done`、`response.completed` 快照不重复计入参数；自定义工具转换、非空初始参数或协议异常需要先核对 SDK 映射，不能仅凭跨层哈希不同认定某一端重复发送。

历史日志没有保存的原始帧无法由新增诊断恢复。HTTP 200 只说明响应头已到达；客户端保护后出现的 499 或 Broken pipe 也不能证明最初原因。网关写入本机下游 writer 成功不等于客户端已消费或执行。

## 客户端原始 Responses 观测

`wire_responses` 被动观察 HTTP 客户端实际读取的 SSE 字节，在 SDK 转换之前统计。同一网络读取中可能包含多个事件，因此原始统计可以领先 SDK；SDK 回调阻塞也会扩大两者差距。这一边界不是服务器写出时刻，也不是工具执行时刻。诊断不增加预读任务、队列或重传，不过滤、改写交给 SDK 的字节。

每个响应记录 `response_id`、事件数及 `sequence_number` 的首末值。`sequence_forward_gaps` / `sequence_forward_missing_total` 统计相邻观测间的向前跳变次数及跳过的序号数；乱序事件可能随后补上，不能直接称为永久丢包。`sequence_non_increasing` 统计非递增，`sequence_equal_previous` 统计与前一个序号相等。`sequence_missing_events` 表示事件本身没有有效序号，不表示传输丢失。没有响应编号时不猜测，记录 `unknown_response_events`；标准流中没有编号的后续事件沿用当前响应编号。

每个函数调用记录与 SDK 相同的参数指纹和形态统计，另记原始 `delta_events`、首末参数到达时间，以及两类 done 事件的次数。只累计非空初始 arguments 和 arguments.delta，不重复累计 done 的完整快照。关联优先使用响应编号与实际 `call_id`，`item_id` / `output_index` 用于同一原始流内关联；`identity_unknown`、`identity_conflicts` 表明身份不足或冲突，此时不能据此归责。

每次尝试最多观察 4 条 HTTP 流；每条流最多 16 个响应、64 个工具、128 个索引别名，每工具最多 16 个固定前缀。单个待解析 SSE 帧最多 256KiB，超出后仅跳过该帧的诊断，继续原样交给 SDK。`oversized_frames`、`parse_errors`、`statistics_truncated`、`wire_streams_truncated` 说明覆盖缺口；`incomplete_sse_frame` 与 `body_eof_observed` 区分未闭合帧和正常字节流结束。待解析字节仅临时保留，关闭时释放，日志不保存帧或参数正文。

原始分帧支持 LF / CRLF。HTTP 体声明 gzip 等压缩编码时，标记 `sse_observation=skipped_content_encoding`，只统计读取字节与时间，不把压缩字节误当成 SSE；SDK 仍按原路径解压。这种记录缺少原始事件统计，不能把零计数当成没有收到参数。

## 实际工具约束与耗时

`wire_request_constraints` 检查 HTTP 请求已经序列化的正文，不记录提示、图片或 Schema 正文。逐工具记录 `strict` 为 `omitted`、`false`、`true`，异常值为 `invalid`；不能把省略当成 false，更不能把 Pydantic 本地严格校验当成上游约束。Schema 只保存 SHA256、对象数、非 required 的属性数及未关闭对象数。这是语法统计，不展开引用，也不是上游 Schema 兼容性验证。

当前 `click`、`action_sequence`、`drag` 的真实 SDK 离线请求均省略 strict，保留可选字段。不能只把 strict 开关改为 true：应先按目标接口支持的 Schema 子集处理对象和 required，保留可选值的 nullable 语义，再单独验证兼容性。

请求正文超过 4MiB 时跳过检查并记录 `body_too_large`；流式上传正文不可直接读取时记录 `streaming_body_unavailable`，不会为了诊断消费上传流。最多检查 64 个工具或命名空间节点，每个 Schema 最多统计 1024 个节点，达到上限标记截断。响应事件如果回传 tools，则保存同样的 `returned_tool_constraints`；回显不证明服务端实际执行了约束。

`max_output_tokens` 与 `returned_max_output_tokens` 只表示本层实际观察到的字段。本次核对的 CodexManager 通道会过滤输出 token 上限；短合成探针成功也不能证明上限被执行。不能把设置 max_tokens / max_output_tokens 当成这条链路可靠的止损办法，客户端长度、超时和取消保护仍然必要。

`stream_work` 记录每阶段的调用次数、总耗时和最长耗时：`wire_observe` 为原始帧诊断，`sdk_observe` 为 SDK 片段诊断，`merge` 为聚合，`emit` 为界面回调，`await_sdk_chunk` 为等待 SDK 交出下一个片段。最后一项包含网络读取、原始观测、SDK 转换和 SDK 回调等工作，与其他阶段可能重叠，不能相加或直接当成网络延迟。

聚合每 128 个片段合并一次，降低 SDK 反复解析半截 JSON 的开销；长度保护、诊断和界面输出仍逐片段执行，异步压缩继续使用原异步调用路径。分批合并不修复参数 JSON，最终仍须经过完整性和严格解析校验。

## 取消与关闭

`cancel_observed_at` / `cancel_observed_phase` 记录本次尝试首次在客户端观测到取消的时间与阶段，不等于用户点击停止的时间。`cancel_phase` / `cancel_reason` 沿用恢复层最终记录的取消阶段和来源，可能反映后续重试等待中的停止。首末 SDK 参数时间为 `first_tool_arguments_at` / `last_tool_arguments_at`。原始流内的读取、参数和关闭时间采用 Unix 秒。

SDK 读取中、回调中或两次 yield 之间触发长度保护后，尝试结束路径都会主动关闭已观察的 HTTP 流，不等待垃圾回收。`close_started_at` 记录关闭开始，只有实际成功才写 `closed_at`；失败只记录异常类型，关闭等待最多 1 秒。关闭超时不能覆盖用户停止而变成可重试的请求超时。未能关闭时保留错误证据，不声称连接已成功释放。

## 已核对的上游异常样本（2026-11-02）

一次真实 `action_sequence` 调用在任务超时前持续接收参数，没有完成该工具调用。该样本发生在 `action_sequence` 纳入参数保护之前。按同一 `response_id + call_id` 核对生产诊断，得到以下字符数；请求编号和设备信息不在文档中保留：

| 观测边界 | 参数字符数 |
| --- | ---: |
| CodexManager 收到的官方上游 WebSocket | 40907 |
| CodexManager 本地下游 writer | 40906 |
| NewAPI 收到的上游 SSE | 40904 |
| NewAPI 本地下游 writer | 40904 |
| ARTEMIS 的 SDK 参数片段 | 40619 |

五个边界在 4096 到 36864 字节的九个累计 SHA256 上一致。NewAPI 使用透传模式，收到和写出的完整参数哈希也一致。上游没有终止事件，也没有完成参数快照。该样本证明参数在官方上游返回时就已持续增长，不能归因于 NewAPI 转换、下游重复累计完成快照或 ARTEMIS 最终消息拼接。取消、预读和缓冲会使各层停止计数的位置不同；尾部总长度不同本身不能证明重复发送或字符丢失。

诊断没有参数正文，不能进一步断言是模型生成循环、空白循环、重复描述或官方服务内部的重复事件，也不能排除请求结构触发异常。这个定位只排除已核对样本的下游放大作为最初来源，不能追溯证明没有原始诊断的历史事故。另一次 `click` 异常同样在 NewAPI 接收时已超过四万字符，说明这种现象并非新动作序列独有。

CodexManager 另行修正了普通函数放入 functions 命名空间的兼容性问题。其短上下文、低思考强度合成测试通过，仅能作为兼容性对照，尚不能代替原事故的长上下文、多图、高思考强度复现，也不能称为参数膨胀的根因修复。

本地保护覆盖 `action_sequence`、`drag` 及其他小型内置动作：超限后关闭流、丢弃参数，并按既有策略有限重试；它限制异常对当前任务的影响，不修复上游生成行为，也不保证业务任务一定成功。缩放面板自动隐藏导致的定位失败由动作序列的 `ensure_visible` 准备步骤处理，与参数流异常分别诊断。

## 离线验证

`tests/unit/test_llm_stream_guard.py` 验证保护、有限重试、相同/不同备用端点，以及不会创建或清除其他请求的全局暂停。`tests/unit/test_request_diagnostics.py` 验证请求编号、超时重试、响应头及单次参数计数。`tests/unit/test_argument_fingerprint.py` 验证不同分片、中文和 emoji、固定字节前缀、有界统计与异常编码。这些测试不调用真实模型或设备。

`tests/unit/test_responses_diagnostics.py` 验证原始分帧、序号、done 去重、有界统计和 strict 三态。`tests/unit/test_responses_wire_lifecycle.py` 使用已安装的真实 OpenAI/LangChain SDK 与内存 HTTP 传输，验证小于长度阈值的未闭合流、SDK 回调背压、请求/任务超时、用户停止、超限后主动关闭和关闭失败，以及实际工具 Schema；不发网络请求。`tests/unit/test_chunk_accumulator.py` 对比逐片段聚合结果，验证交错工具、元数据和使用量保持一致，减少半截 JSON 重复解析，异常参数仍由最终校验拒绝。离线通过不代表原业务任务的稳定性已验收。