fix(trae): 解析 TRAE 官方缓存字段 cache_read_input_tokens

实时请求验证：TRAE token_usage 真实返回
cache_read_input_tokens / cache_creation_input_tokens（未命中为 0），
此前解析器只找 OpenAI 惯例字段导致 cached_tokens 恒 NULL。
- _parse_usage 解析链：prompt_tokens_details.cached_tokens → 顶层
  cached_tokens → TRAE cache_read_input_tokens（0 是有效值，保留）
- 补充 0/缺失/优先级测试；PROPOSAL 同步字段事实
- Credit 确认无此字段，TRAE 恒 None 不变

Author: RobbsLuo

PROPOSAL.md

@@ -80,7 +80,7 @@
 - Token 刷新：`POST /cloudide/api/v3/trae/oauth/ExchangeToken`（refreshToken 轮换）
 - 签到：`/trae/api/v2/ug/checkin_credits/{status,claim}`；额度：`/trae/api/v2/pay/ide_user_ent_usage`
 - SSE 事件序列：`metadata` → `timing_cost` → `output`×N → `extra_info` → `token_usage` → `done`
-- SSE **只有 `token_usage`，无 per-request credit**
+- SSE `token_usage` 含缓存字段：`cache_read_input_tokens` / `cache_creation_input_tokens`（未命中时为 0，非缺失），映射为统计的 cached_tokens；**无 per-request credit**
 - 错误码 `1005` = 权益不足；上游仅流式，非流式需聚合
 
 ### 3.2 冲突与陷阱

src/provider/trae/events.py

@@ -135,11 +135,15 @@ def as_int(key: str) -> int | None:
         value = payload.get(key)
         return value if isinstance(value, int) and not isinstance(value, bool) else None
 
-    # 缓存命中：OpenAI 惯例在 prompt_tokens_details.cached_tokens，顶层 cached_tokens 兜底
+    # 缓存命中解析链：OpenAI 惯例（prompt_tokens_details.cached_tokens）→ 顶层
+    # cached_tokens 兜底 → TRAE 官方字段 cache_read_input_tokens（实测真实返回该
+    # 字段，且未命中时值为 0——0 是有效值必须保留，不能当缺失）。
     details = payload.get("prompt_tokens_details")
     cached = (details or {}).get("cached_tokens") if isinstance(details, dict) else None
     if not isinstance(cached, int) or isinstance(cached, bool):
         cached = as_int("cached_tokens")
+    if not isinstance(cached, int) or isinstance(cached, bool):
+        cached = as_int("cache_read_input_tokens")
 
     return Usage(
         input_tokens=as_int("prompt_tokens"),

tests/test_m1a_trae.py

@@ -1127,7 +1127,7 @@ def test_parse_all_events_non_dict_tool_call_entry_skipped():
     assert EventKind.TOOL_CALLS not in kinds
 
 def test_trae_usage_cached_tokens():
-    """TRAE usage：details 路径 + 顶层兜底 + 缺省 None。"""
+    """TRAE usage：details 路径 + 顶层兜底 + TRAE 官方字段 + 缺省 None。"""
     from src.provider.trae.events import SSEFrame
 
     frame = SSEFrame(event="token_usage", data=(
@@ -1138,6 +1138,20 @@ def test_trae_usage_cached_tokens():
     frame = SSEFrame(event="token_usage", data='{"prompt_tokens":9,"cached_tokens":2}')
     assert trae_events.parse_frame(frame).usage.cached_tokens == 2
 
+    # TRAE 官方字段：命中>0 与未命中=0 都要保留（0 是有效值不是缺失）
+    frame = SSEFrame(event="token_usage", data=(
+        '{"prompt_tokens":13,"completion_tokens":159,'
+        '"cache_read_input_tokens":7,"reasoning_tokens":148}'))
+    assert trae_events.parse_frame(frame).usage.cached_tokens == 7
+    frame = SSEFrame(event="token_usage", data=(
+        '{"prompt_tokens":13,"cache_read_input_tokens":0}'))
+    assert trae_events.parse_frame(frame).usage.cached_tokens == 0
+
+    # OpenAI 惯例字段优先于 TRAE 字段
+    frame = SSEFrame(event="token_usage", data=(
+        '{"prompt_tokens":9,"cached_tokens":2,"cache_read_input_tokens":5}'))
+    assert trae_events.parse_frame(frame).usage.cached_tokens == 2
+
     frame = SSEFrame(event="token_usage", data='{"prompt_tokens":9}')
     assert trae_events.parse_frame(frame).usage.cached_tokens is None