Skip to main content

acosmi/models/
types.rs

1//! 模型网关域类型。端口自 `models/types.ts`(其端口自 `acosmi-sdk-go/types.go` v0.19.0)。
2//!
3//! 命名约定:字段名 = Go json tag 字面量(wire format),不做 camelCase 重映射。
4//! mix 风格(`modelId` / `max_tokens` / `supports_thinking`)是历史 wire 设计的真实样貌;
5//! camelCase wire 用 `#[serde(rename)]`,snake_case wire 直用。
6//!
7//! ## 联合类型扁平 struct(方案 §4.1 红线)
8//! `ChatContentBlock` / `StreamEvent` 是**扁平 struct + 全 `Option`**,**不是** tagged enum:
9//! `type:String` 判别符 + 动态字段 `serde_json::Value`,忠实镜像 Go json marshaling,
10//! 保前向兼容(未知 type 不 panic)。
11
12use serde::{Deserialize, Serialize};
13use serde_json::Value;
14
15// =============================================================================
16// Managed Models
17// =============================================================================
18
19/// 模型能力矩阵 —— 下游据此决定 UI 功能开关与 Beta Header 注入。
20#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
21pub struct ModelCapabilities {
22    // 思考能力
23    pub supports_thinking: bool,
24    pub supports_adaptive_thinking: bool,
25    /// 交错思考(Interleaved Thinking)。
26    pub supports_isp: bool,
27
28    // 工具与搜索
29    pub supports_web_search: bool,
30    pub supports_tool_search: bool,
31    pub supports_structured_output: bool,
32
33    // 推理控制
34    pub supports_effort: bool,
35    /// 模型是否支持 thinking_level="max" 强度档(深度思考)。
36    pub supports_max_effort: bool,
37    /// Opus 4.6 独有(Speed="fast")。
38    pub supports_fast_mode: bool,
39    /// Auto 模式(模型自主选择工具/搜索策略)。
40    pub supports_auto_mode: bool,
41
42    // 上下文与缓存
43    pub supports_1m_context: bool,
44    pub supports_prompt_cache: bool,
45    /// 通过 context-management beta 控制。
46    pub supports_cache_editing: bool,
47
48    // 输出控制
49    /// Claude 4 内置。
50    pub supports_token_efficient: bool,
51    pub supports_redact_thinking: bool,
52
53    // Token 上限(冗余但便于查询)。
54    pub max_input_tokens: i64,
55    pub max_output_tokens: i64,
56
57    /// 桌面视觉理解 sidecar 能力(v1.2+)。与 `inputModalities=['image']` 正交。
58    #[serde(default, skip_serializing_if = "Option::is_none")]
59    pub supports_desktop_visual_understanding: Option<bool>,
60
61    /// 图片生成能力(v1.3+)。应通过 `generate_image()` 调用。
62    #[serde(default, skip_serializing_if = "Option::is_none")]
63    pub supports_image_generation: Option<bool>,
64
65    /// 视频生成能力(v1.3+)。应通过 `generate_video()` + `poll_video_task()` 调用。
66    #[serde(default, skip_serializing_if = "Option::is_none")]
67    pub supports_video_generation: Option<bool>,
68
69    /// 向量能力(v2.9+)。应通过 `embeddings()` 调用。
70    #[serde(default, skip_serializing_if = "Option::is_none")]
71    pub supports_embedding: Option<bool>,
72
73    /// 重排序能力(v2.9+)。应通过 `rerank()` 调用。
74    #[serde(default, skip_serializing_if = "Option::is_none")]
75    pub supports_rerank: Option<bool>,
76}
77
78/// 图片生成请求(`generate_image`)。
79#[derive(Debug, Clone, Default, Serialize, Deserialize)]
80pub struct ImageGenerationRequest {
81    pub prompt: String,
82    /// 缺省 1024。
83    #[serde(default, skip_serializing_if = "Option::is_none")]
84    pub width: Option<i64>,
85    /// 缺省 1024。
86    #[serde(default, skip_serializing_if = "Option::is_none")]
87    pub height: Option<i64>,
88    #[serde(default, skip_serializing_if = "Option::is_none")]
89    pub style: Option<String>,
90}
91
92/// 图片生成响应。
93#[derive(Debug, Clone, Default, Serialize, Deserialize)]
94pub struct ImageGenerationResponse {
95    #[serde(default, skip_serializing_if = "Option::is_none")]
96    pub url: Option<String>,
97    #[serde(default, skip_serializing_if = "Option::is_none")]
98    pub b64_json: Option<String>,
99    #[serde(default, skip_serializing_if = "Option::is_none")]
100    pub revised_prompt: Option<String>,
101    #[serde(rename = "requestId", default, skip_serializing_if = "Option::is_none")]
102    pub request_id: Option<String>,
103}
104
105/// 视频生成请求(`generate_video`)。
106#[derive(Debug, Clone, Default, Serialize, Deserialize)]
107pub struct VideoGenerationRequest {
108    pub prompt: String,
109    #[serde(default, skip_serializing_if = "Option::is_none")]
110    pub resolution: Option<String>,
111    /// 时长(秒)。
112    #[serde(default, skip_serializing_if = "Option::is_none")]
113    pub duration: Option<i64>,
114}
115
116/// 视频任务响应(创建返回 `taskId`;轮询返回 `status`/`videoUrl`)。
117#[derive(Debug, Clone, Default, Serialize, Deserialize)]
118pub struct VideoTaskResponse {
119    #[serde(rename = "taskId")]
120    pub task_id: String,
121    /// pending | running | completed | failed
122    #[serde(default, skip_serializing_if = "Option::is_none")]
123    pub status: Option<String>,
124    #[serde(rename = "videoUrl", default, skip_serializing_if = "Option::is_none")]
125    pub video_url: Option<String>,
126    #[serde(default, skip_serializing_if = "Option::is_none")]
127    pub error: Option<String>,
128    #[serde(rename = "requestId", default, skip_serializing_if = "Option::is_none")]
129    pub request_id: Option<String>,
130}
131
132// ── 向量 (Embedding) / 重排序 (Rerank) (v2.9.0) ──────────────────────────────
133// SDK 订阅会员经 POST /managed-models/:id/{embeddings,rerank} 调用; 仅
134// capabilities.supports_embedding / supports_rerank 的托管模型可用。上游接 DashScope。
135
136/// 向量输入:单条文本或文本数组(对外 = OpenAI `input` 字段)。
137#[derive(Debug, Clone, Serialize, Deserialize)]
138#[serde(untagged)]
139pub enum EmbeddingInput {
140    /// 单条文本。
141    Single(String),
142    /// 批量文本。
143    Batch(Vec<String>),
144}
145
146/// 多模态内容片段(v2.10+;向量/重排序 `qwen3-vl-embedding` / `qwen3-vl-rerank` 线路)。
147/// `text` / `image` / `video` 至少填一项;`image` / `video` 取 URL 或 base64 data URI。
148#[derive(Debug, Clone, Default, Serialize, Deserialize)]
149pub struct MultimodalContent {
150    /// 文本片段。
151    #[serde(default, skip_serializing_if = "Option::is_none")]
152    pub text: Option<String>,
153    /// 图片(URL 或 base64 data URI)。
154    #[serde(default, skip_serializing_if = "Option::is_none")]
155    pub image: Option<String>,
156    /// 视频(URL);仅多模态线路支持。
157    #[serde(default, skip_serializing_if = "Option::is_none")]
158    pub video: Option<String>,
159}
160
161/// 向量请求(`embeddings`)。文本线路 = OpenAI `/v1/embeddings` 标准;多模态线路用 `contents`。
162#[derive(Debug, Clone, Default, Serialize, Deserialize)]
163pub struct EmbeddingRequest {
164    /// 文本输入(文本向量线路):单条或批量。多模态线路改用 `contents`。
165    #[serde(default, skip_serializing_if = "Option::is_none")]
166    pub input: Option<EmbeddingInput>,
167    /// 多模态内容(v2.10+;`qwen3-vl-embedding` 线路):text/image/video 片段数组。与 `input` 二选一。
168    #[serde(default, skip_serializing_if = "Option::is_none")]
169    pub contents: Option<Vec<MultimodalContent>>,
170    /// 向量维度(可选;DashScope text-embedding-v4 支持 2048/1536/1024/768/512/256/128/64)。
171    #[serde(default, skip_serializing_if = "Option::is_none")]
172    pub dimensions: Option<i64>,
173    /// 编码格式(可选,如 `"float"`)。
174    #[serde(default, skip_serializing_if = "Option::is_none")]
175    pub encoding_format: Option<String>,
176    /// 输出向量类型(可选;多模态线路,如 `"dense"`)。
177    #[serde(default, skip_serializing_if = "Option::is_none")]
178    pub output_type: Option<String>,
179    /// 视频抽帧率 fps(可选;多模态视频输入)。
180    #[serde(default, skip_serializing_if = "Option::is_none")]
181    pub fps: Option<f64>,
182    /// 是否启用多模态特征融合(可选;多模态线路)。
183    #[serde(default, skip_serializing_if = "Option::is_none")]
184    pub enable_fusion: Option<bool>,
185}
186
187/// 单条向量结果(OpenAI 标准)。
188#[derive(Debug, Clone, Default, Serialize, Deserialize)]
189pub struct EmbeddingData {
190    #[serde(default)]
191    pub object: String,
192    #[serde(default)]
193    pub index: i64,
194    #[serde(default)]
195    pub embedding: Vec<f64>,
196}
197
198/// 向量 / 重排序用量。
199#[derive(Debug, Clone, Default, Serialize, Deserialize)]
200pub struct EmbeddingUsage {
201    #[serde(default)]
202    pub prompt_tokens: i64,
203    #[serde(default)]
204    pub total_tokens: i64,
205}
206
207/// 向量响应(OpenAI `/v1/embeddings` 标准)。
208#[derive(Debug, Clone, Default, Serialize, Deserialize)]
209pub struct EmbeddingResponse {
210    #[serde(default)]
211    pub object: String,
212    #[serde(default)]
213    pub model: String,
214    #[serde(default)]
215    pub data: Vec<EmbeddingData>,
216    #[serde(default)]
217    pub usage: EmbeddingUsage,
218    #[serde(default, skip_serializing_if = "Option::is_none")]
219    pub id: Option<String>,
220}
221
222/// 重排序查询(v2.10+):文本字符串,或多模态 `{text|image}`。
223#[derive(Debug, Clone, Serialize, Deserialize)]
224#[serde(untagged)]
225pub enum RerankQuery {
226    /// 文本查询。
227    Text(String),
228    /// 多模态查询(`{text|image}`)。
229    Multimodal(MultimodalContent),
230}
231
232impl From<String> for RerankQuery {
233    fn from(s: String) -> Self {
234        RerankQuery::Text(s)
235    }
236}
237impl From<&str> for RerankQuery {
238    fn from(s: &str) -> Self {
239        RerankQuery::Text(s.to_string())
240    }
241}
242impl From<MultimodalContent> for RerankQuery {
243    fn from(c: MultimodalContent) -> Self {
244        RerankQuery::Multimodal(c)
245    }
246}
247
248/// 重排序候选文档(v2.10+):文本字符串,或多模态 `{text|image|video}`。
249#[derive(Debug, Clone, Serialize, Deserialize)]
250#[serde(untagged)]
251pub enum RerankDocument {
252    /// 文本文档。
253    Text(String),
254    /// 多模态文档(`{text|image|video}`)。
255    Multimodal(MultimodalContent),
256}
257
258impl From<String> for RerankDocument {
259    fn from(s: String) -> Self {
260        RerankDocument::Text(s)
261    }
262}
263impl From<&str> for RerankDocument {
264    fn from(s: &str) -> Self {
265        RerankDocument::Text(s.to_string())
266    }
267}
268impl From<MultimodalContent> for RerankDocument {
269    fn from(c: MultimodalContent) -> Self {
270        RerankDocument::Multimodal(c)
271    }
272}
273
274/// 重排序请求(`rerank`)。统一扁平契约,网关内部按模型线路转换。
275#[derive(Debug, Clone, Serialize, Deserialize)]
276pub struct RerankRequest {
277    /// 查询:文本字符串(文本线路),或多模态 `{text|image}`(`qwen3-vl-rerank` 线路)。
278    pub query: RerankQuery,
279    /// 候选文档:文本字符串或多模态 `{text|image|video}` 对象列表。
280    pub documents: Vec<RerankDocument>,
281    /// 返回前 N 条(可选;缺省返回全部)。
282    #[serde(default, skip_serializing_if = "Option::is_none")]
283    pub top_n: Option<i64>,
284    /// 是否在结果中回传文档原文(可选,缺省 false)。
285    #[serde(default, skip_serializing_if = "Option::is_none")]
286    pub return_documents: Option<bool>,
287    /// 排序指令(可选;仅 OpenAI 兼容线路支持,原生线路忽略)。
288    #[serde(default, skip_serializing_if = "Option::is_none")]
289    pub instruct: Option<String>,
290    /// 视频抽帧率 fps(可选;多模态视频文档)。
291    #[serde(default, skip_serializing_if = "Option::is_none")]
292    pub fps: Option<f64>,
293}
294
295/// 单条重排序结果。
296#[derive(Debug, Clone, Default, Serialize, Deserialize)]
297pub struct RerankResult {
298    /// 文档在原 `documents` 数组中的下标。
299    #[serde(default)]
300    pub index: i64,
301    /// 相关性得分(越高越相关)。
302    #[serde(default)]
303    pub relevance_score: f64,
304    /// 文档原文(仅 `return_documents=true` 时存在)。
305    #[serde(default, skip_serializing_if = "Option::is_none")]
306    pub document: Option<String>,
307}
308
309/// 重排序响应。
310#[derive(Debug, Clone, Default, Serialize, Deserialize)]
311pub struct RerankResponse {
312    #[serde(default)]
313    pub results: Vec<RerankResult>,
314    #[serde(default)]
315    pub usage: EmbeddingUsage,
316    #[serde(default, skip_serializing_if = "Option::is_none")]
317    pub model: Option<String>,
318}
319
320/// 模型可接收的用户输入模态(v1.2+)。闭 union。
321#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
322#[serde(rename_all = "lowercase")]
323pub enum InputModality {
324    /// 文本输入。
325    Text,
326    /// 截图 / 图片输入(多模态)。
327    Image,
328}
329
330impl InputModality {
331    /// 借出 wire 字符串。
332    pub fn as_str(&self) -> &'static str {
333        match self {
334            InputModality::Text => "text",
335            InputModality::Image => "image",
336        }
337    }
338}
339
340/// BucketClass 字面量常量。
341pub const BUCKET_CLASS_COMMERCIAL: &str = "COMMERCIAL";
342/// BucketClass 字面量常量。
343pub const BUCKET_CLASS_GENERIC: &str = "GENERIC";
344
345/// 用户在某 modelId 上的桶余额聚合视图(V30 entitlement-listing)。单位 ETU。
346#[derive(Debug, Clone, Default, Serialize, Deserialize)]
347pub struct BucketInfo {
348    #[serde(rename = "quotaEtu")]
349    pub quota_etu: i64,
350    #[serde(rename = "usedEtu")]
351    pub used_etu: i64,
352    #[serde(rename = "remainingEtu")]
353    pub remaining_etu: i64,
354    #[serde(
355        rename = "sharedPoolEtu",
356        default,
357        skip_serializing_if = "Option::is_none"
358    )]
359    pub shared_pool_etu: Option<i64>,
360    #[serde(rename = "expiresAt", default, skip_serializing_if = "Option::is_none")]
361    pub expires_at: Option<String>,
362    #[serde(rename = "bucketClass")]
363    pub bucket_class: String,
364    #[serde(default, skip_serializing_if = "Option::is_none")]
365    pub expired: Option<bool>,
366    /// v0.19+ —— GENERIC alive 桶 tokenRemaining 求和("免费余额")。
367    #[serde(rename = "freeRemainingEtu")]
368    pub free_remaining_etu: i64,
369    /// v0.19+ —— COMMERCIAL alive 桶 tokenRemaining 求和("付费余额")。
370    #[serde(rename = "paidRemainingEtu")]
371    pub paid_remaining_etu: i64,
372}
373
374/// 大小写不敏感判定 —— 与 `buildBucketView` EqualFold 语义对齐。
375pub fn bucket_info_is_commercial(b: Option<&BucketInfo>) -> bool {
376    match b {
377        None => false,
378        Some(b) => b.bucket_class.to_lowercase() == BUCKET_CLASS_COMMERCIAL.to_lowercase(),
379    }
380}
381
382/// 托管模型。
383#[derive(Debug, Clone, Default, Serialize, Deserialize)]
384pub struct ManagedModel {
385    /// Gateway-declared thinking levels. Missing means unknown; an empty list means
386    /// no selectable levels. Unknown strings are retained for forward compatibility.
387    #[serde(default, skip_serializing_if = "Option::is_none")]
388    pub thinking_levels: Option<Vec<String>>,
389    pub id: String,
390    pub name: String,
391    pub provider: String,
392    #[serde(rename = "modelId")]
393    pub model_id: String,
394    #[serde(rename = "maxTokens")]
395    pub max_tokens: i64,
396    #[serde(rename = "isEnabled")]
397    pub is_enabled: bool,
398    /// @deprecated 公开 `/managed-models` 端点不返回此字段。
399    #[serde(
400        rename = "pricePerMTok",
401        default,
402        skip_serializing_if = "Option::is_none"
403    )]
404    pub price_per_m_tok: Option<f64>,
405    /// @deprecated 公开 `/managed-models` 端点不返回此字段。
406    #[serde(rename = "isDefault", default, skip_serializing_if = "Option::is_none")]
407    pub is_default: Option<bool>,
408    #[serde(
409        rename = "contextWindow",
410        default,
411        skip_serializing_if = "Option::is_none"
412    )]
413    pub context_window: Option<i64>,
414    pub capabilities: ModelCapabilities,
415
416    /// P1 商品化档位门控:0=FREE..4=ULTRA。
417    #[serde(
418        rename = "minPlanTier",
419        default,
420        skip_serializing_if = "Option::is_none"
421    )]
422    pub min_plan_tier: Option<i64>,
423    /// 该模型能否在 C 端对话(ADK 托管运行时)使用;false 时选择器应过滤。
424    #[serde(
425        rename = "chatRuntimeSupported",
426        default,
427        skip_serializing_if = "Option::is_none"
428    )]
429    pub chat_runtime_supported: Option<bool>,
430    /// 模型默认绑定的工具 ID 列表。
431    #[serde(
432        rename = "defaultToolIds",
433        default,
434        skip_serializing_if = "Option::is_none"
435    )]
436    pub default_tool_ids: Option<Vec<String>>,
437    /// 该模型对当前用户档位是否被限制策略锁定。true=展示但置灰+升级引导。
438    #[serde(default, skip_serializing_if = "Option::is_none")]
439    pub locked: Option<bool>,
440    /// 是否属于"免费会员可用"分区(PLAN:FREE 档 allowedModels 内,仅分类,与当前用户档位无关)。
441    ///
442    /// **语义不变,但不再是展示分区依据**:订阅双池之后「哪些模型先扣精选免费池」由
443    /// [`ManagedModel::free_pool_eligible`] 表达,两套集合可以不一致。新代码不要再用本字段分区或打
444    /// "精选"角标;字段保留只为老客户端零破坏(方案 D-14)。
445    #[serde(rename = "freeTier", default, skip_serializing_if = "Option::is_none")]
446    pub free_tier: Option<bool>,
447    /// \[订阅双池 P5 / D-14\] 该模型此刻是否有资格先扣**精选免费池 F**(池类 FREE,或仍在限免期内的
448    /// PROMO_FREE);与 [`QuotaSummaryFreePool::eligible_models`] 同源。用于模型选择器的"精选"角标。
449    ///
450    /// **缺席(`None`)= 老网关(还没有双池),不是 `Some(false)`**:只在 `== Some(true)` 时画角标,
451    /// 绝不在 `!= Some(false)` 时画。限免到期会让同一模型随时间从 `true` 翻成 `false`,不要缓存跨过限免截止日。
452    #[serde(
453        rename = "freePoolEligible",
454        default,
455        skip_serializing_if = "Option::is_none"
456    )]
457    pub free_pool_eligible: Option<bool>,
458
459    /// 上游 gateway 为此模型启用的请求格式列表:"anthropic" | "openai"。
460    /// 空值表示上游未声明,SDK 回落 provider 硬编码分支(向后兼容)。
461    #[serde(default, skip_serializing_if = "Option::is_none")]
462    pub supported_formats: Option<Vec<String>>,
463
464    /// 上游建议客户端优先使用的格式:"anthropic" | "openai";空值等价 `supported_formats[0]`。
465    #[serde(default, skip_serializing_if = "Option::is_none")]
466    pub preferred_format: Option<String>,
467
468    /// 当前用户在此模型上的桶余额聚合(V0.18 V30)。仅非 admin 用户上游才返回。
469    #[serde(
470        rename = "bucketInfo",
471        default,
472        skip_serializing_if = "Option::is_none"
473    )]
474    pub bucket_info: Option<BucketInfo>,
475
476    /// 模型可接收的用户输入模态(v1.2+)。
477    /// 兼容上游字段名 `input_modalities`(snake_case)—— `list_models` 写缓存前会做归一化。
478    /// **缺失语义**:上游未下发时为 `None`,调用方必须保守按 text-only / unknown 处理。
479    #[serde(
480        rename = "inputModalities",
481        default,
482        skip_serializing_if = "Option::is_none"
483    )]
484    pub input_modalities: Option<Vec<InputModality>>,
485
486    /// 上游 snake_case 别名 `input_modalities`。归一化前的原始字段,归一化后 SDK 用户只读
487    /// `input_modalities`(camel 字段 `inputModalities`)。对齐 TS `normalizeInputModalities`。
488    #[serde(
489        rename = "input_modalities",
490        default,
491        skip_serializing_if = "Option::is_none"
492    )]
493    pub input_modalities_snake: Option<Vec<Value>>,
494}
495
496// =============================================================================
497// QuotaSummary —— v0.19+ 账户级权益总览(免费/付费切分)
498// =============================================================================
499
500/// 单桶视图 —— `QuotaSummary.freeBuckets/paidBuckets` 元素。
501#[derive(Debug, Clone, Default, Serialize, Deserialize)]
502pub struct BucketRow {
503    #[serde(rename = "bucketId")]
504    pub bucket_id: String,
505    /// 精确桶为具体 modelId,通配桶为 `"*"`。
506    #[serde(rename = "modelId")]
507    pub model_id: String,
508    /// COMMERCIAL | GENERIC
509    #[serde(rename = "bucketClass")]
510    pub bucket_class: String,
511    #[serde(rename = "tokenQuota")]
512    pub token_quota: i64,
513    #[serde(rename = "tokenUsed")]
514    pub token_used: i64,
515    #[serde(rename = "tokenRemaining")]
516    pub token_remaining: i64,
517    /// 永久桶为 `None`。
518    #[serde(rename = "expiresAt", default, skip_serializing_if = "Option::is_none")]
519    pub expires_at: Option<String>,
520    #[serde(default, skip_serializing_if = "Option::is_none")]
521    pub expired: Option<bool>,
522}
523
524/// 大小写不敏感判定。
525pub fn bucket_row_is_commercial(r: Option<&BucketRow>) -> bool {
526    match r {
527        None => false,
528        Some(r) => r.bucket_class.to_lowercase() == BUCKET_CLASS_COMMERCIAL.to_lowercase(),
529    }
530}
531
532/// 订阅池视图 —— `QuotaSummary.subscriptionPool`,语义 = **付费池 P**(alive COMMERCIAL 桶合计)。
533///
534/// quota / used / remaining 单位为微 Credits(÷1000 = Credits)。`expires_at` 缺席 = 全是永久桶。
535/// 合计额度为 0 的池网关不下发(客户端按 used/quota 画百分比,0 配额会被画成"已用满")。
536///
537/// `booster_*` 三件套(加油包份额)是追加式可选:缺席 = 没有加油包,或扣费通老到不下发 sourceType ——
538/// 两种都不可当 0 读;展示端的合同是"三个字段齐全才渲染副行"。
539#[derive(Debug, Clone, Default, Serialize, Deserialize)]
540pub struct QuotaSummarySubscriptionPool {
541    pub quota: i64,
542    pub used: i64,
543    pub remaining: i64,
544    #[serde(rename = "expiresAt", default, skip_serializing_if = "Option::is_none")]
545    pub expires_at: Option<String>,
546    /// 网关下发的单位标识(`"MICRO_CREDIT"`)。
547    pub unit: String,
548    #[serde(
549        rename = "boosterRemaining",
550        default,
551        skip_serializing_if = "Option::is_none"
552    )]
553    pub booster_remaining: Option<i64>,
554    #[serde(
555        rename = "boosterCount",
556        default,
557        skip_serializing_if = "Option::is_none"
558    )]
559    pub booster_count: Option<i64>,
560    #[serde(
561        rename = "boosterNextExpiresAt",
562        default,
563        skip_serializing_if = "Option::is_none"
564    )]
565    pub booster_next_expires_at: Option<String>,
566}
567
568/// 精选免费池 F(订阅双池 P5 / D-14)—— `QuotaSummary.freePool`,与 [`QuotaSummarySubscriptionPool`] 同单位。
569///
570/// 付费合同有 F 池时下发,老合同没有 F 时 `QuotaSummary.free_pool` 整体为 `None`。`expires_at` 可缺席
571/// (口径同 `QuotaSummarySubscriptionPool::expires_at`)。`eligible_models` = 池类 FREE ∪ 仍在限免期的
572/// PROMO_FREE 的 model id,**可以是空数组** —— `[]` 是网关明确说"此刻没有任何模型有资格",与整个
573/// `free_pool` 缺席不同。
574#[derive(Debug, Clone, Default, Serialize, Deserialize)]
575pub struct QuotaSummaryFreePool {
576    pub quota: i64,
577    pub used: i64,
578    pub remaining: i64,
579    #[serde(rename = "expiresAt", default, skip_serializing_if = "Option::is_none")]
580    pub expires_at: Option<String>,
581    /// 恒为 `"MICRO_CREDIT"`(÷1000 = Credits)。
582    pub unit: String,
583    #[serde(rename = "eligibleModels", default)]
584    pub eligible_models: Vec<String>,
585}
586
587/// 单窗口限额用量 —— `QuotaSummary.windowLimits` 元素(与 hold 阶段窗口闸同源)。
588#[derive(Debug, Clone, Default, Serialize, Deserialize)]
589pub struct WindowLimitStatus {
590    /// `FIVE_HOUR` | `WEEKLY`
591    pub kind: String,
592    #[serde(rename = "limitCredits")]
593    pub limit_credits: i64,
594    #[serde(rename = "usedCredits")]
595    pub used_credits: i64,
596    /// 预计恢复时间(ISO-8601 UTC);窗口内无用量时缺席。
597    #[serde(rename = "resetAt", default, skip_serializing_if = "Option::is_none")]
598    pub reset_at: Option<String>,
599    /// 该窗此刻可否被用户"继续"开关豁免(5h 软限额时 true;周窗恒 false)。老网关缺席。
600    #[serde(default, skip_serializing_if = "Option::is_none")]
601    pub overridable: Option<bool>,
602    /// 服务端合成位:该窗已用满,但用户的"继续"开关正在放行。新网关恒下发,老网关缺席(缺席 ≠ false)。
603    #[serde(
604        rename = "fiveHourSoftContinuing",
605        default,
606        skip_serializing_if = "Option::is_none"
607    )]
608    pub five_hour_soft_continuing: Option<bool>,
609    /// 窗口内在途预占(微 Credits);缺席 = 不知道(老扣费通/取数失败),不能当 0 读;`Some(0)` 是事实。
610    #[serde(
611        rename = "inflightHeldCredits",
612        default,
613        skip_serializing_if = "Option::is_none"
614    )]
615    pub inflight_held_credits: Option<i64>,
616}
617
618/// `GET /api/v4/entitlements/quota-summary` 返回体。
619///
620/// 「免费」一词有两层含义,不可混用:`free_total_etu` / `free_buckets` 是 GENERIC(注册赠送 / 邀请奖励 /
621/// 试用)桶,与订阅合同无关;订阅合同自带的精选免费池是 [`QuotaSummary::free_pool`](订阅双池 P5 / D-14),
622/// 两者不可相加。
623///
624/// 追加式字段(全部可选,老网关缺席;缺席一律不可当 0 读):`subscription_pool` / `window_limits` /
625/// `window_five_hour_continue_enabled` / `free_pool` / `credit_unit`。
626#[derive(Debug, Clone, Default, Serialize, Deserialize)]
627pub struct QuotaSummary {
628    /// GENERIC(免费/赠送)alive 桶 tokenRemaining 求和。
629    #[serde(rename = "freeTotalEtu")]
630    pub free_total_etu: i64,
631    /// COMMERCIAL(付费购买)alive 桶 tokenRemaining 求和。
632    #[serde(rename = "paidTotalEtu")]
633    pub paid_total_etu: i64,
634    /// GENERIC 桶详情(含过期);空时为空数组。
635    #[serde(rename = "freeBuckets", default)]
636    pub free_buckets: Vec<BucketRow>,
637    /// COMMERCIAL 桶详情(含过期);空时为空数组。
638    #[serde(rename = "paidBuckets", default)]
639    pub paid_buckets: Vec<BucketRow>,
640    /// GENERIC alive 桶中最早到期;永久桶/无 alive 时缺失。
641    #[serde(
642        rename = "nextFreeExpiresAt",
643        default,
644        skip_serializing_if = "Option::is_none"
645    )]
646    pub next_free_expires_at: Option<String>,
647    /// COMMERCIAL alive 桶中最早到期;同上。
648    #[serde(
649        rename = "nextPaidExpiresAt",
650        default,
651        skip_serializing_if = "Option::is_none"
652    )]
653    pub next_paid_expires_at: Option<String>,
654    /// 订阅额度池 = **付费池 P**,订阅双池之后语义不变。`None` = 老网关,或当前没有 alive 付费桶。
655    #[serde(
656        rename = "subscriptionPool",
657        default,
658        skip_serializing_if = "Option::is_none"
659    )]
660    pub subscription_pool: Option<QuotaSummarySubscriptionPool>,
661    /// 滚动窗口限额用量(5 小时 / 7 天);网关未启用窗口限额时整个字段缺席。
662    #[serde(
663        rename = "windowLimits",
664        default,
665        skip_serializing_if = "Option::is_none"
666    )]
667    pub window_limits: Option<Vec<WindowLimitStatus>>,
668    /// 用户 5h"继续"开关现值(true = 软限额/默认;false = 严格模式);仅网关启用窗口限额时下发。
669    #[serde(
670        rename = "windowFiveHourContinueEnabled",
671        default,
672        skip_serializing_if = "Option::is_none"
673    )]
674    pub window_five_hour_continue_enabled: Option<bool>,
675    /// \[订阅双池 P5 / D-14\] 精选免费池 F:付费合同随每个订阅周期自带的那一半额度,只能被
676    /// `eligible_models` 里的模型先扣,用完后同一请求自动溢出扣付费池 P(`subscription_pool`)。
677    ///
678    /// **`None` = 老合同(没有 F)或老网关(不认识 F)—— 两种都不可当 0 读**:把 `None` 画成
679    /// "精选额度 0 / 已用满",是在向老合同用户断言一件不存在的事。展示端只在 `free_pool.is_some()` 时画第二条进度条。
680    #[serde(rename = "freePool", default, skip_serializing_if = "Option::is_none")]
681    pub free_pool: Option<QuotaSummaryFreePool>,
682    /// \[订阅双池 P5 / D-14\] 本响应所有 Credit 数值的计量口径:`"OFFICIAL_CNY"`(新合同,
683    /// 1 Credit = ¥0.000001 官方价)或 `"COST_CNY"`(老合同,成本口径)。
684    ///
685    /// **`None` = 老网关没下发,不能当任一取值读**,尤其不能默认成 `OFFICIAL_CNY` 去乘 ¥ 单价。
686    /// 保持 `Option<String>`(开放):网关将来新增口径时旧版 SDK 原样透出,消费端对未知值应按"不换算"处理。
687    #[serde(
688        rename = "creditUnit",
689        default,
690        skip_serializing_if = "Option::is_none"
691    )]
692    pub credit_unit: Option<String>,
693}
694
695/// 额度单位:付费池 / 精选免费池 `quota/used/remaining` 的单位(微 Credit,÷1000 = Credits)。
696pub const QUOTA_UNIT_MICRO_CREDIT: &str = "MICRO_CREDIT";
697/// 计量口径:新合同,1 Credit = ¥0.000001 官方价(¥1 = 10⁹ 微 Credit)。
698pub const CREDIT_UNIT_OFFICIAL_CNY: &str = "OFFICIAL_CNY";
699/// 计量口径:老合同,成本口径。
700pub const CREDIT_UNIT_COST_CNY: &str = "COST_CNY";
701
702// =============================================================================
703// Chat
704// =============================================================================
705
706/// 聊天消息(简单文本格式,CrabClaw 使用)。
707#[derive(Debug, Clone, Default, Serialize, Deserialize)]
708pub struct ChatMessage {
709    pub role: String,
710    pub content: String,
711}
712
713/// Anthropic 响应内容块。**扁平 struct**(方案 §4.1 红线):`type:String` 判别符 + 全
714/// `Option` + 动态字段 `serde_json::Value`,**禁 tagged enum**。
715#[derive(Debug, Clone, Default, Serialize, Deserialize)]
716pub struct ChatContentBlock {
717    pub r#type: String,
718    #[serde(default, skip_serializing_if = "Option::is_none")]
719    pub text: Option<String>,
720    #[serde(default, skip_serializing_if = "Option::is_none")]
721    pub citations: Option<Value>,
722    #[serde(default, skip_serializing_if = "Option::is_none")]
723    pub thinking: Option<String>,
724    #[serde(default, skip_serializing_if = "Option::is_none")]
725    pub signature: Option<String>,
726    #[serde(default, skip_serializing_if = "Option::is_none")]
727    pub data: Option<String>,
728    #[serde(default, skip_serializing_if = "Option::is_none")]
729    pub id: Option<String>,
730    #[serde(default, skip_serializing_if = "Option::is_none")]
731    pub name: Option<String>,
732    /// json.RawMessage in Go。
733    #[serde(default, skip_serializing_if = "Option::is_none")]
734    pub input: Option<Value>,
735    #[serde(default, skip_serializing_if = "Option::is_none")]
736    pub server_name: Option<String>,
737    #[serde(default, skip_serializing_if = "Option::is_none")]
738    pub caller: Option<Value>,
739    #[serde(default, skip_serializing_if = "Option::is_none")]
740    pub tool_use_id: Option<String>,
741    #[serde(default, skip_serializing_if = "Option::is_none")]
742    pub content: Option<Value>,
743    #[serde(default, skip_serializing_if = "Option::is_none")]
744    pub is_error: Option<bool>,
745}
746
747/// Anthropic 格式 token 用量。
748#[derive(Debug, Clone, Default, Serialize, Deserialize)]
749pub struct ChatUsage {
750    pub input_tokens: i64,
751    pub output_tokens: i64,
752    #[serde(default, skip_serializing_if = "Option::is_none")]
753    pub cache_creation_input_tokens: Option<i64>,
754    #[serde(default, skip_serializing_if = "Option::is_none")]
755    pub cache_read_input_tokens: Option<i64>,
756}
757
758// ---------- Thinking ----------
759
760/// 三档思考级别(v0.9.0)。
761pub const THINKING_OFF: &str = "off";
762pub const THINKING_LOW: &str = "low";
763/// 三档思考级别(v0.9.0)。
764pub const THINKING_HIGH: &str = "high";
765/// 三档思考级别(v0.9.0)。
766pub const THINKING_MAX: &str = "max";
767
768/// 标准思考最低 maxTokens —— CrabCode 默认 MAX_OUTPUT_TOKENS_DEFAULT = 32_000。
769pub const THINKING_HIGH_MIN_MAX_TOKENS: i64 = 32_000;
770/// 深度思考回退 maxTokens —— Opus 4.6 上限 128K。
771pub const THINKING_MAX_FALLBACK_MAX_TOKENS: i64 = 128_000;
772
773/// 控制模型思考行为。
774#[derive(Debug, Clone, Default, Serialize, Deserialize)]
775pub struct ThinkingConfig {
776    /// "enabled" | "disabled" | "adaptive"
777    pub r#type: String,
778    /// 仅 type="enabled" 时(旧模型回退)。
779    #[serde(default, skip_serializing_if = "Option::is_none")]
780    pub budget_tokens: Option<i64>,
781    /// 思考级别(v0.9.0):"off" | "high" | "max"
782    #[serde(default, skip_serializing_if = "Option::is_none")]
783    pub level: Option<String>,
784    /// "none" | "summary" | ""(默认空=完整)。
785    #[serde(default, skip_serializing_if = "Option::is_none")]
786    pub display: Option<String>,
787}
788
789/// 根据三档 level 创建配置。
790pub fn new_thinking_config(level: &str) -> ThinkingConfig {
791    if level.is_empty() || level == THINKING_OFF {
792        return ThinkingConfig {
793            r#type: "disabled".to_string(),
794            ..Default::default()
795        };
796    }
797    ThinkingConfig {
798        r#type: "adaptive".to_string(),
799        level: Some(level.to_string()),
800        ..Default::default()
801    }
802}
803
804/// 服务端工具定义 —— SDK 将工具 schema 合入 API 请求的 tools 数组。
805#[derive(Debug, Clone, Default, Serialize, Deserialize)]
806pub struct ServerTool {
807    pub r#type: String,
808    pub name: String,
809    #[serde(default, skip_serializing_if = "Option::is_none")]
810    pub config: Option<serde_json::Map<String, Value>>,
811}
812
813/// Server Tool 类型常量。
814pub const SERVER_TOOL_TYPE_WEB_SEARCH: &str = "web_search_20250305";
815
816/// 地理位置。
817#[derive(Debug, Clone, Default, Serialize, Deserialize)]
818pub struct GeoLoc {
819    /// ISO 3166-1 alpha-2。
820    pub country: String,
821    #[serde(default, skip_serializing_if = "Option::is_none")]
822    pub city: Option<String>,
823}
824
825/// `ServerTool.config` 结构(type=web_search_20250305)。
826#[derive(Debug, Clone, Default, Serialize, Deserialize)]
827pub struct WebSearchConfig {
828    /// 每请求最大搜索次数,默认 8。
829    #[serde(default, skip_serializing_if = "Option::is_none")]
830    pub max_uses: Option<i64>,
831    /// 域名白名单(与 `blocked_domains` 互斥)。
832    #[serde(default, skip_serializing_if = "Option::is_none")]
833    pub allowed_domains: Option<Vec<String>>,
834    /// 域名黑名单(与 `allowed_domains` 互斥)。
835    #[serde(default, skip_serializing_if = "Option::is_none")]
836    pub blocked_domains: Option<Vec<String>>,
837    #[serde(default, skip_serializing_if = "Option::is_none")]
838    pub user_location: Option<GeoLoc>,
839}
840
841/// 控制推理努力级别。
842#[derive(Debug, Clone, Default, Serialize, Deserialize)]
843pub struct EffortConfig {
844    /// "low" | "medium" | "high" | "max"
845    pub level: String,
846}
847
848/// 控制输出格式(结构化输出)。
849#[derive(Debug, Clone, Default, Serialize, Deserialize)]
850pub struct OutputConfig {
851    /// "json_schema" | ""
852    #[serde(default, skip_serializing_if = "Option::is_none")]
853    pub format: Option<String>,
854    #[serde(default, skip_serializing_if = "Option::is_none")]
855    pub schema: Option<Value>,
856}
857
858/// 创建搜索 Server Tool 的便捷方法。
859/// `allowed_domains` 与 `blocked_domains` 互斥,同时传入返回 `Err`(对齐 TS throw)。
860pub fn new_web_search_tool(
861    cfg: Option<&WebSearchConfig>,
862) -> crate::shared::errors::Result<ServerTool> {
863    let mut st = ServerTool {
864        r#type: SERVER_TOOL_TYPE_WEB_SEARCH.to_string(),
865        name: "web_search".to_string(),
866        config: None,
867    };
868    if let Some(cfg) = cfg {
869        let allowed_len = cfg.allowed_domains.as_ref().map(|v| v.len()).unwrap_or(0);
870        let blocked_len = cfg.blocked_domains.as_ref().map(|v| v.len()).unwrap_or(0);
871        if allowed_len > 0 && blocked_len > 0 {
872            return Err(crate::shared::errors::Error::other(
873                "web search: allowed_domains and blocked_domains are mutually exclusive",
874            ));
875        }
876        let mut m = serde_json::Map::new();
877        if let Some(mu) = cfg.max_uses {
878            if mu > 0 {
879                m.insert("max_uses".to_string(), Value::from(mu));
880            }
881        }
882        if allowed_len > 0 {
883            m.insert(
884                "allowed_domains".to_string(),
885                serde_json::to_value(cfg.allowed_domains.as_ref().unwrap())?,
886            );
887        }
888        if blocked_len > 0 {
889            m.insert(
890                "blocked_domains".to_string(),
891                serde_json::to_value(cfg.blocked_domains.as_ref().unwrap())?,
892            );
893        }
894        if let Some(loc) = &cfg.user_location {
895            m.insert("user_location".to_string(), serde_json::to_value(loc)?);
896        }
897        if !m.is_empty() {
898            st.config = Some(m);
899        }
900    }
901    Ok(st)
902}
903
904/// 聊天请求。基础字段供 CrabClaw,扩展字段供 CrabCode。所有新增字段零值不改变行为。
905///
906/// 扩展字段(`raw_messages`/`system`/`tools`/...)不会被原样序列化,而由 adapter
907/// `build_request_body` 选择性序列化到请求体。
908#[derive(Debug, Clone, Default)]
909pub struct ChatRequest {
910    // ── 基础字段(CrabClaw 兼容)──
911    pub messages: Option<Vec<ChatMessage>>,
912    pub stream: Option<bool>,
913    pub max_tokens: Option<i64>,
914
915    // ── 完整请求控制(CrabCode 扩展)── 由 build_request_body 处理
916    /// 复杂消息体(含 content blocks / 多模态),非 nil 时优先于 `messages`。
917    pub raw_messages: Option<Value>,
918    /// string 或 ContentBlock[]。
919    pub system: Option<Value>,
920    /// 标准工具定义(Tool[])。
921    pub tools: Option<Value>,
922    pub temperature: Option<f64>,
923    pub thinking: Option<ThinkingConfig>,
924    pub metadata: Option<std::collections::BTreeMap<String, String>>,
925    /// 显式 beta(SDK 自动合并)。
926    pub betas: Option<Vec<String>>,
927    /// 服务端工具(build_request_body 合入 tools 数组)。
928    pub server_tools: Option<Vec<ServerTool>>,
929    /// "" | "fast"(Fast Mode)。
930    pub speed: Option<String>,
931    pub effort: Option<EffortConfig>,
932    pub output_config: Option<OutputConfig>,
933    /// 任意扩展字段(build_request_body 合入请求体)。
934    pub extra_body: Option<serde_json::Map<String, Value>>,
935
936    /// v0.13.0: OpenAI wire format 原生字段。AnthropicAdapter 忽略,OpenAIAdapter 按规范序列化。
937    /// 对应 OpenAI `parallel_tool_calls` 顶层字段,`None` = 不设置(沿用上游默认 true)。
938    pub parallel_tool_calls: Option<bool>,
939
940    /// v1.6.0: 业务侧终端用户 id,跨 provider 通用语义。
941    /// OpenAI wire → 顶层 `body["user_id"]`;Anthropic wire → 合并到 `body["metadata"]["user_id"]`。
942    pub end_user_id: Option<String>,
943}
944
945// ---------- Web Search Sources ----------
946
947/// 联网搜索结果来源(与后端 `adk/stream_helpers.go SourceItem` 对齐)。
948#[derive(Debug, Clone, Default, Serialize, Deserialize)]
949pub struct WebSearchSource {
950    pub title: String,
951    pub url: String,
952    #[serde(default, skip_serializing_if = "Option::is_none")]
953    pub snippet: Option<String>,
954}
955
956/// 搜索来源事件(从 SSE "sources" 事件解析)。
957#[derive(Debug, Clone, Default, Serialize, Deserialize)]
958pub struct SourcesEvent {
959    pub sources: Vec<WebSearchSource>,
960    #[serde(default, skip_serializing_if = "Option::is_none")]
961    pub session_id: Option<String>,
962}
963
964/// Stable structural error codes for sources events (TypeScript parity).
965#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
966#[serde(rename_all = "snake_case")]
967pub enum SourcesEventIssueCode {
968    InvalidJson,
969    MissingSources,
970    SourcesNotArray,
971    SourceNotObject,
972    SourceTitleInvalid,
973    SourceUrlInvalid,
974    SourceSnippetInvalid,
975    SessionIdInvalid,
976}
977
978/// Distinguishes a legitimate empty result from a malformed sources event.
979#[derive(Debug, Clone, Serialize, Deserialize)]
980#[serde(tag = "kind", rename_all = "snake_case")]
981pub enum SourcesEventParseResult {
982    NotSources,
983    EmptySources {
984        #[serde(skip_serializing_if = "Option::is_none")]
985        session_id: Option<String>,
986    },
987    Sources {
988        value: SourcesEvent,
989    },
990    MalformedSources {
991        code: SourcesEventIssueCode,
992    },
993}
994
995/// Classify by SSE event name or JSON `type`, accepting unknown extra fields.
996/// Unlike the legacy [`parse_sources_event`], empty and malformed are distinct.
997pub fn classify_sources_event(ev: &StreamEvent) -> SourcesEventParseResult {
998    use SourcesEventIssueCode::*;
999    use SourcesEventParseResult::*;
1000    let malformed = |code| MalformedSources { code };
1001    let value: Value = match serde_json::from_str(&ev.data) {
1002        Ok(value) => value,
1003        Err(_) if ev.event == "sources" => return malformed(InvalidJson),
1004        Err(_) => return NotSources,
1005    };
1006    if ev.event != "sources" && value.get("type").and_then(Value::as_str) != Some("sources") {
1007        return NotSources;
1008    }
1009    let Some(raw_sources) = value.as_object().and_then(|v| v.get("sources")) else {
1010        return malformed(MissingSources);
1011    };
1012    let session_id = match value.get("session_id") {
1013        None => None,
1014        Some(Value::String(s)) => Some(s.clone()),
1015        Some(_) => return malformed(SessionIdInvalid),
1016    };
1017    let Some(raw_sources) = raw_sources.as_array() else {
1018        return malformed(SourcesNotArray);
1019    };
1020    if raw_sources.is_empty() {
1021        return EmptySources { session_id };
1022    }
1023    let mut sources = Vec::with_capacity(raw_sources.len());
1024    for source in raw_sources {
1025        if !source.is_object() {
1026            return malformed(SourceNotObject);
1027        }
1028        let Some(title) = source.get("title").and_then(Value::as_str) else {
1029            return malformed(SourceTitleInvalid);
1030        };
1031        let Some(url) = source.get("url").and_then(Value::as_str) else {
1032            return malformed(SourceUrlInvalid);
1033        };
1034        let snippet = match source.get("snippet") {
1035            None => None,
1036            Some(Value::String(s)) => Some(s.clone()),
1037            Some(_) => return malformed(SourceSnippetInvalid),
1038        };
1039        sources.push(WebSearchSource {
1040            title: title.into(),
1041            url: url.into(),
1042            snippet,
1043        });
1044    }
1045    Sources {
1046        value: SourcesEvent {
1047            sources,
1048            session_id,
1049        },
1050    }
1051}
1052
1053/// 从 [`StreamEvent`] 中解析搜索来源。返回 `None` 表示该事件不是 sources 类型。
1054pub fn parse_sources_event(ev: &StreamEvent) -> Option<SourcesEvent> {
1055    #[derive(Deserialize)]
1056    struct Wrapper {
1057        #[serde(default)]
1058        r#type: Option<String>,
1059        #[serde(default)]
1060        sources: Option<Vec<WebSearchSource>>,
1061        #[serde(default)]
1062        session_id: Option<String>,
1063    }
1064    let wrapper: Wrapper = serde_json::from_str(&ev.data).ok()?;
1065    if wrapper.r#type.as_deref() != Some("sources") && ev.event != "sources" {
1066        return None;
1067    }
1068    let sources = wrapper.sources.filter(|s| !s.is_empty())?;
1069    Some(SourcesEvent {
1070        sources,
1071        session_id: wrapper.session_id,
1072    })
1073}
1074
1075// =============================================================================
1076// ChatResponse
1077// =============================================================================
1078
1079/// 同步聊天响应(Anthropic format,v0.4.1)。
1080///
1081/// `token_remaining` / `call_remaining` / `model_token_remaining*` 不在 wire JSON 中,
1082/// 由 client 从 Header 填充。哨兵 `-1` 表示服务端未返回。
1083#[derive(Debug, Clone, Default, Serialize, Deserialize)]
1084pub struct ChatResponse {
1085    pub id: String,
1086    pub r#type: String,
1087    pub model: String,
1088    pub role: String,
1089    pub content: Vec<ChatContentBlock>,
1090    pub stop_reason: String,
1091    pub usage: ChatUsage,
1092    /// -1 表示服务端未返回。
1093    #[serde(rename = "tokenRemaining", default)]
1094    pub token_remaining: i64,
1095    #[serde(rename = "callRemaining", default)]
1096    pub call_remaining: i64,
1097    #[serde(rename = "modelTokenRemaining", default)]
1098    pub model_token_remaining: i64,
1099    #[serde(rename = "modelTokenRemainingETU", default)]
1100    pub model_token_remaining_etu: i64,
1101}
1102
1103// =============================================================================
1104// SSE Stream
1105// =============================================================================
1106
1107/// SSE 流式事件。**扁平 struct**(方案 §4.1 红线)。`data` 是裸 JSON 串,由 helper
1108/// ([`parse_sources_event`]/[`parse_settlement`])二次解析。
1109///
1110/// v0.11.0 新增 `blockIndex`/`blockType`/`ephemeral` 三字段(in-band content block 元数据)。
1111#[derive(Debug, Clone, Default, Serialize, Deserialize)]
1112pub struct StreamEvent {
1113    pub event: String,
1114    pub data: String,
1115    /// 对齐 Anthropic content_block_start/delta/stop 的 index 字段。
1116    #[serde(
1117        rename = "blockIndex",
1118        default,
1119        skip_serializing_if = "Option::is_none"
1120    )]
1121    pub block_index: Option<i64>,
1122    /// 由 content_block_start 解析得到,delta/stop 从 index→type 映射查出。
1123    #[serde(rename = "blockType", default, skip_serializing_if = "Option::is_none")]
1124    pub block_type: Option<String>,
1125    /// 网关标记此 block 下一轮不应回传。
1126    #[serde(default, skip_serializing_if = "Option::is_none")]
1127    pub ephemeral: Option<bool>,
1128}
1129
1130/// 流式结算事件(从 settled SSE 事件解析)。
1131#[derive(Debug, Clone, Default, Serialize, Deserialize)]
1132pub struct StreamSettlement {
1133    #[serde(rename = "requestId")]
1134    pub request_id: String,
1135    #[serde(rename = "consumeStatus")]
1136    pub consume_status: String,
1137    #[serde(rename = "inputTokens")]
1138    pub input_tokens: i64,
1139    #[serde(rename = "outputTokens")]
1140    pub output_tokens: i64,
1141    #[serde(rename = "totalTokens")]
1142    pub total_tokens: i64,
1143    /// 结算后剩余 token(-1 表示服务端未返回)。
1144    #[serde(rename = "tokenRemaining")]
1145    pub token_remaining: i64,
1146    /// 结算后剩余调用次数(-1 表示服务端未返回)。
1147    #[serde(rename = "callRemaining")]
1148    pub call_remaining: i64,
1149}
1150
1151/// 从 settled 类型的 [`StreamEvent`] 中解析结算信息。不是 settled 类型则返回 `None`。
1152pub fn parse_settlement(ev: &StreamEvent) -> Option<StreamSettlement> {
1153    if ev.event != "settled" && ev.event != "pending_settle" {
1154        return None;
1155    }
1156    // s 的字段全可选 → 解析失败返回 None,缺字段用默认/哨兵(对齐 TS `?? 默认`)。
1157    #[derive(Deserialize)]
1158    struct Partial {
1159        #[serde(rename = "requestId", default)]
1160        request_id: Option<String>,
1161        #[serde(rename = "consumeStatus", default)]
1162        consume_status: Option<String>,
1163        #[serde(rename = "inputTokens", default)]
1164        input_tokens: Option<i64>,
1165        #[serde(rename = "outputTokens", default)]
1166        output_tokens: Option<i64>,
1167        #[serde(rename = "totalTokens", default)]
1168        total_tokens: Option<i64>,
1169        #[serde(rename = "tokenRemaining", default)]
1170        token_remaining: Option<i64>,
1171        #[serde(rename = "callRemaining", default)]
1172        call_remaining: Option<i64>,
1173    }
1174    let s: Partial = serde_json::from_str(&ev.data).ok()?;
1175    Some(StreamSettlement {
1176        request_id: s.request_id.unwrap_or_default(),
1177        consume_status: s.consume_status.unwrap_or_default(),
1178        input_tokens: s.input_tokens.unwrap_or(0),
1179        output_tokens: s.output_tokens.unwrap_or(0),
1180        total_tokens: s.total_tokens.unwrap_or(0),
1181        token_remaining: s.token_remaining.unwrap_or(-1),
1182        call_remaining: s.call_remaining.unwrap_or(-1),
1183    })
1184}
1185
1186/// 零值 [`ModelCapabilities`](对齐 TS `zeroModelCapabilities`)。模型不在列表时返回。
1187pub fn zero_model_capabilities() -> ModelCapabilities {
1188    ModelCapabilities {
1189        supports_desktop_visual_understanding: Some(false),
1190        ..Default::default()
1191    }
1192}