docs: spell out that a reported zero is not a missing value

2026-07-31 07:53:42 -04:00
parent 0aa7202c87
commit cd1a9520ff
2 changed files with 13 additions and 3 deletions
@@ -38,7 +38,15 @@ Issue 称「两者的数据都已经存在于 `TransportResult.raw` 里」。核

 **选 A2**。`TransportResult` 是库内部流转类型(非三项目消费面),但仍按「新增必带默认值」处理,使 `openai_compat` 之外的构造点零改动;全库该类型仅 2 处构造(`openai_compat.py:354/436`)。

-解析纪律(P5 一切外部输入校验后使用):`cached_tokens` 与 `model` 均来自网关响应,类型不可信。取值走一个防御 helper——非 `int`/非正、非 `str`/空串一律归 `None`,不抛异常(可观测字段缺失绝不能打断主路径)。
+解析纪律(P5 一切外部输入校验后使用):`cached_tokens` 与 `model` 均来自网关响应,类型不可信。取值走防御 helper,不抛异常(可观测字段缺失绝不能打断主路径):
+
+| 输入 | 结果 |
+|---|---|
+| `cached_tokens` 为非负 `int`(**含 `0`**) | 如实保留——`0` 是「该源上报了一次真实零命中」,与「未上报」的 `None` 语义不同,这正是本 issue 的核心诉求 |
+| `cached_tokens` 为负数 / 非 `int` / `bool` | `None`(`bool` 必须显式排除:`isinstance(True, int)` 在 Python 里为真) |
+| `usage` 或 `prompt_tokens_details` 非 dict | `None` |
+| `model` 为非空 `str` | 保留 |
+| `model` 为非 `str` / 空白串 | `None` |

 ## 3. 决策 B:缓存命中回放时两字段取什么值