Skip to main content

acosmi/core/
client.rs

1//! 主 API 客户端。端口自 `core/client.ts`(其端口自 `acosmi-sdk-go/client.go`)。
2//!
3//! 相位说明:P1 仅建**最小骨架**(Config / Client / 构造 / create / 同步 helper /
4//! token 字段 / ensure_token 骨架)。chat / listModels / 各业务方法及 refresh 实现待 P2-P5。
5//!
6//! ## 可变状态模型(方案 §4.2)
7//! TS 直接 mutate `this.tokens` / `this.meta` 并用 `withMu`(异步互斥) 包裹 refresh 临界区。
8//! Rust 拆为:`RwLock<Option<TokenSet>>`(快速 sync 读写,不跨 await)+ `tokio::Mutex<()>`
9//! 单航班门(refresh-rotation 临界区,跨 await)+ `AtomicBool`(login 进行中)。
10//! Client 持 `Arc<ClientInner>`,`Clone` 廉价共享。
11
12use crate::auth::auth as oauth;
13use crate::auth::types::{token_set_is_expired, ServerMetadata, TokenSet};
14use crate::core::authority::{
15    tokens_equal, AuthorityState, StrictState, StrictTokenAuthority, TokenAuthorityError,
16};
17use crate::core::http::{
18    iter_sse_lines_result as iter_sse_lines, parse_http_error_with_retry_after, parse_stream_error,
19    read_limited_text_result as read_limited_text, CHAT_REQUEST_TIMEOUT_MS,
20    DEFAULT_JSON_TIMEOUT_MS, MAX_ERROR_BODY_SIZE, MODEL_CACHE_TTL_MS,
21};
22use crate::core::observer::ChatOptions;
23use crate::core::retry::{effective_policy, EffectiveRetryPolicy, RetryPolicy, RetryRequestInfo};
24use crate::core::store::{FileTokenStore, InMemoryTokenStore, TokenStore};
25use crate::core::transport::{with_cancel, HttpClient, HttpContext, HttpPurpose, HttpTransport};
26use crate::macros::open_string_union;
27use crate::models::adapters::openai::parse_openai_response_to_anthropic;
28use crate::models::adapters::{get_adapter_for_model, Adapter, ProviderFormat};
29use crate::models::is_sse_comment_line;
30use crate::models::stream_meta::{extract_anthropic_block_meta, BlockMeta};
31use crate::models::types::{
32    parse_settlement, parse_sources_event, zero_model_capabilities, ChatRequest, ChatResponse,
33    EmbeddingRequest, EmbeddingResponse, ImageGenerationRequest, ImageGenerationResponse,
34    InputModality, ManagedModel, ModelCapabilities, QuotaSummary, RerankRequest, RerankResponse,
35    SourcesEvent, StreamEvent, StreamSettlement, VideoGenerationRequest, VideoTaskResponse,
36};
37use crate::models::wire_anthropic::AnthropicResponse;
38use crate::shared::api_response::ApiResponse;
39use crate::shared::errors::{Error, Result};
40use futures::Stream;
41use futures::StreamExt;
42use serde::de::DeserializeOwned;
43use std::collections::HashMap;
44use std::sync::atomic::{AtomicBool, Ordering};
45use std::sync::{Arc, RwLock};
46use tokio_util::sync::CancellationToken;
47use url::Url;
48
49/// 默认网关 base URL。
50pub const DEFAULT_GATEWAY_BASE_URL: &str = "https://acosmi.com";
51/// 非流式 JSON 子 client 默认超时(毫秒)。
52pub const DEFAULT_API_TIMEOUT_MS: u64 = 60_000;
53
54/// OAuth CORS 被拦截错误码标识。
55pub const ERR_OAUTH_CORS_BLOCKED: &str = "oauth_cors_blocked";
56/// refresh 代理失败错误码标识。
57pub const ERR_REFRESH_PROXY_FAILED: &str = "refresh_proxy_failed";
58/// token 过期错误码标识。
59pub const ERR_TOKEN_EXPIRED: &str = "token_expired";
60
61open_string_union! {
62    /// 网关 entitlement 过滤状态(来自 `X-Entitlement-Filter-Status` 响应头)。开放联合。
63    FilterStatus {
64        OK => "ok",
65        ADMIN_BYPASS => "admin-bypass",
66        INTERNAL_BYPASS => "internal-bypass",
67        DISABLED_BY_FLAG => "disabled-by-flag",
68        FALLBACK_TKDIST_ERROR => "fallback-tkdist-error",
69        FALLBACK_TKDIST_SKEW => "fallback-tkdist-deployment-skew",
70        FALLBACK_NO_BUCKETS => "fallback-no-buckets",
71        FALLBACK_MISSING_USER => "fallback-missing-userid",
72        /// 空串 = Unknown / 老 nexus。
73        UNKNOWN => "",
74    }
75}
76
77/// 浏览器 token 刷新模式。
78#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
79pub enum BrowserRefreshMode {
80    /// issuer 直刷(默认)。
81    #[default]
82    Direct,
83    /// 经 refresh 代理(规避 issuer CORS)。
84    ServerProxy,
85    /// 不刷新。
86    None,
87}
88
89/// OAuth 元数据 profile。
90#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
91pub enum OAuthMetadataProfile {
92    /// 桌面(默认)。
93    #[default]
94    Desktop,
95    /// 浏览器 / Web。
96    Web,
97}
98
99/// 客户端配置。所有字段可选。
100///
101/// 偏移说明:TS 有 `serverURL`/`baseURL`/`baseUrl` 三别名(JS 命名容忍);Rust 收敛为
102/// 单一 `server_url`。
103#[derive(Default)]
104pub struct Config {
105    /// 网关 base URL;缺省 [`DEFAULT_GATEWAY_BASE_URL`]。
106    pub server_url: Option<String>,
107    /// 自定义 TokenStore;缺省按平台选(原生 = File)。
108    pub store: Option<Arc<dyn TokenStore>>,
109    /// 自定义 HTTP client(对应 TS `fetchImpl`)。
110    #[cfg(feature = "native-http")]
111    pub http: Option<reqwest::Client>,
112    /// 重试策略;`None` = 禁用重试(与 TS 默认一致)。
113    pub retry_policy: Option<RetryPolicy>,
114    /// compliance 端点 base override。
115    pub compliance_base_url: Option<String>,
116    /// 业务 API 端点 base override。
117    pub api_base_url: Option<String>,
118    /// OAuth 元数据 profile。
119    pub oauth_metadata_profile: Option<OAuthMetadataProfile>,
120    /// 浏览器刷新模式。
121    pub browser_refresh_mode: Option<BrowserRefreshMode>,
122    /// refresh 代理 URL(server-proxy 模式)。
123    pub refresh_proxy_url: Option<String>,
124}
125
126/// Client 可变 token 状态。
127pub(crate) struct ClientInner {
128    // ── 不可变配置 ──
129    server_url: String,
130    compliance_base_url: Option<String>,
131    api_base_url: Option<String>,
132    oauth_metadata_profile: OAuthMetadataProfile,
133    browser_refresh_mode: BrowserRefreshMode,
134    refresh_proxy_url: Option<String>,
135    /// 共享 HTTP client。
136    http: HttpClient,
137    store: Arc<dyn TokenStore>,
138    strict: Option<StrictState>,
139    /// 生效重试策略。
140    retry_policy: Option<EffectiveRetryPolicy>,
141
142    // ── 可变状态 ──
143    tokens: RwLock<Option<zeroize::Zeroizing<TokenSet>>>,
144    /// 模型列表缓存(缺省模式 list_models 写入,全集模式不写)。对应 TS `modelCache`。
145    model_cache: RwLock<Vec<crate::models::ManagedModel>>,
146    /// 模型缓存写入时刻(TTL 判定基准)。对应 TS `modelCacheTimeMs`。
147    model_cache_time: RwLock<Option<std::time::Instant>>,
148    /// lazy 加载的 OAuth server 元数据(discover 结果缓存)。
149    meta: RwLock<Option<ServerMetadata>>,
150    /// login 进行中标志(单航班)。`ensure_token` 在 tokens==null 时据此决定是否等待。
151    login_in_flight: AtomicBool,
152    /// refresh-rotation 临界区门(对应 TS withMu):进程内单航班,串行化 refresh。
153    mu: tokio::sync::Mutex<()>,
154    /// login 就绪信号(等待方解阻塞)。login 成功 / token 写入后 `notify_waiters()`。
155    token_ready: tokio::sync::Notify,
156    /// V29 模型系数缓存(TTL 8s;对应 TS `coefCacheData`/`coefCacheTimeMs`)。
157    /// `@deprecated` 系数已退役(网关恒返回 `[]`),仅向后兼容。
158    coef_cache: RwLock<Option<(Vec<crate::billing::ModelCoefficient>, std::time::Instant)>>,
159    /// 当前 WebSocket 长连接状态句柄(对应 TS `this.ws`)。`None` = 未连接。
160    /// 重复 connect 前先 disconnect 旧连接(防 ws-reconnect-leak)。
161    #[cfg(feature = "notifications-ws")]
162    ws: tokio::sync::Mutex<Option<crate::notifications::WsHandle>>,
163    /// P8 sanitize-bridge:请求前底线防御配置(体积 / deny-list / 深度)。`None` = 未配置
164    /// (对齐 TS `defensiveCfg == null`)。并发安全 sync 读写(不跨 await)。
165    #[cfg(feature = "sanitize")]
166    pub(crate) defensive_cfg: RwLock<Option<crate::sanitize::MinimalSanitizeConfig>>,
167    /// P8 sanitize-bridge:是否每次请求前从 `raw_messages` 剥 `acosmi_ephemeral` 标记块
168    /// (对齐 TS `autoStripEphemeral`)。
169    #[cfg(feature = "sanitize")]
170    pub(crate) auto_strip_ephemeral: AtomicBool,
171}
172
173/// 主 API 客户端。`Clone` 廉价(内部 `Arc`)。
174#[derive(Clone)]
175pub struct Client {
176    inner: Arc<ClientInner>,
177}
178
179impl Client {
180    /// 同步构造(对应 TS constructor)。校验并归一化 URL;不预载 token(见 [`Client::create`])。
181    ///
182    /// # Examples
183    ///
184    /// ```
185    /// use acosmi::{Client, Config};
186    ///
187    /// # #[cfg(feature = "native-http")]
188    /// # {
189    /// let client = Client::new(Config {
190    ///     server_url: Some("https://acosmi.com".into()),
191    ///     ..Default::default()
192    /// })
193    /// .unwrap();
194    /// assert_eq!(client.base_url(), "https://acosmi.com");
195    /// # }
196    /// ```
197    pub fn new(cfg: Config) -> Result<Self> {
198        Self::new_inner(cfg, None, None)
199    }
200
201    /// Construct with an exclusive custom HTTP transport. `Config.http` is ignored.
202    /// Inject a TokenStore separately when caller-owned persistence is required.
203    pub fn new_with_transport(cfg: Config, transport: Arc<dyn HttpTransport>) -> Result<Self> {
204        Self::new_inner(cfg, Some(transport), None)
205    }
206
207    /// Construct with custom transport and load the configured token store.
208    pub async fn create_with_transport(
209        cfg: Config,
210        transport: Arc<dyn HttpTransport>,
211    ) -> Result<Self> {
212        let client = Self::new_with_transport(cfg, transport)?;
213        client.sync_from_disk().await;
214        Ok(client)
215    }
216
217    /// Create a client with caller-owned durable token authority. Config.store is
218    /// ignored. Missing is an unauthenticated client; load errors and Pending fail.
219    pub async fn create_with_authority(
220        cfg: Config,
221        transport: Arc<dyn HttpTransport>,
222        authority: Arc<dyn StrictTokenAuthority>,
223        signal: Option<CancellationToken>,
224    ) -> Result<Self> {
225        let client = Self::new_inner(cfg, Some(transport), Some(authority))?;
226        client.reconcile_authority(signal).await?;
227        Ok(client)
228    }
229
230    fn new_inner(
231        cfg: Config,
232        transport: Option<Arc<dyn HttpTransport>>,
233        authority: Option<Arc<dyn StrictTokenAuthority>>,
234    ) -> Result<Self> {
235        let server_url = match &cfg.server_url {
236            Some(s) => normalize_gateway_base_url(s)?,
237            None => DEFAULT_GATEWAY_BASE_URL.to_string(),
238        };
239        let compliance_base_url = match &cfg.compliance_base_url {
240            Some(s) => Some(normalize_override_base_url(s, "complianceBaseURL")?),
241            None => None,
242        };
243        let api_base_url = match &cfg.api_base_url {
244            Some(s) => Some(normalize_override_base_url(s, "apiBaseURL")?),
245            None => None,
246        };
247
248        let http = if let Some(transport) = transport {
249            HttpClient::new(transport)
250        } else {
251            #[cfg(feature = "native-http")]
252            {
253                HttpClient::legacy(match cfg.http {
254                    Some(c) => c,
255                    None => reqwest::Client::builder()
256                        // 🔴 绝不设 client 级 `.timeout(...)`:reqwest 的 timeout 覆盖整个响应体(含 SSE 流)
257                        // 的总死线,会 abort >60s 的流式 SSE,也会抢先砍掉 11min 非流式 chat 的 per-request
258                        // 死线(TS 用 fetch 无 client 级总超时)。死线一律靠 per-request `derive_timeout_token`
259                        // (非流式)/ 调用方 signal(流式保长连接)派生。这里仅兜底连接握手。
260                        .connect_timeout(std::time::Duration::from_secs(30))
261                        .build()
262                        .map_err(Error::from)?,
263                })
264            }
265            #[cfg(not(feature = "native-http"))]
266            {
267                return Err(Error::other("native HTTP disabled: inject HttpTransport"));
268            }
269        };
270
271        let store: Arc<dyn TokenStore> = if authority.is_some() {
272            Arc::new(InMemoryTokenStore::new())
273        } else {
274            match cfg.store {
275                Some(s) => s,
276                None => default_store(),
277            }
278        };
279
280        let retry_policy = effective_policy(cfg.retry_policy.as_ref());
281
282        Ok(Client {
283            inner: Arc::new(ClientInner {
284                server_url,
285                compliance_base_url,
286                api_base_url,
287                oauth_metadata_profile: cfg.oauth_metadata_profile.unwrap_or_default(),
288                browser_refresh_mode: cfg.browser_refresh_mode.unwrap_or_default(),
289                refresh_proxy_url: cfg.refresh_proxy_url,
290                http,
291                store,
292                strict: authority.map(StrictState::new),
293                retry_policy,
294                tokens: RwLock::new(None),
295                model_cache: RwLock::new(Vec::new()),
296                model_cache_time: RwLock::new(None),
297                meta: RwLock::new(None),
298                login_in_flight: AtomicBool::new(false),
299                mu: tokio::sync::Mutex::new(()),
300                token_ready: tokio::sync::Notify::new(),
301                coef_cache: RwLock::new(None),
302                #[cfg(feature = "notifications-ws")]
303                ws: tokio::sync::Mutex::new(None),
304                #[cfg(feature = "sanitize")]
305                defensive_cfg: RwLock::new(None),
306                #[cfg(feature = "sanitize")]
307                auto_strip_ephemeral: AtomicBool::new(false),
308            }),
309        })
310    }
311
312    /// crate 内访问共享内部状态(sanitize-bridge 等同 crate 子模块用)。
313    #[cfg(feature = "sanitize")]
314    pub(crate) fn inner(&self) -> &ClientInner {
315        &self.inner
316    }
317
318    /// 异步工厂(对应 TS `Client.create`)。从 store 预载 token;store 损坏静默忽略。
319    pub async fn create(cfg: Config) -> Result<Self> {
320        let client = Client::new(cfg)?;
321        if let Ok(Some(t)) = client.inner.store.load().await {
322            *client.inner.tokens.write().unwrap() = Some(zeroize::Zeroizing::new(t));
323        }
324        Ok(client)
325    }
326
327    // ── 同步 helper(对应 TS isAuthorized / getServerURL / getBaseURL / getTokenSet)──
328
329    /// 是否已持有 token(同步)。
330    pub fn is_authorized(&self) -> bool {
331        if self
332            .inner
333            .strict
334            .as_ref()
335            .is_some_and(|s| s.check().is_err())
336        {
337            return false;
338        }
339        self.inner.tokens.read().unwrap().is_some()
340    }
341
342    /// 网关 base URL。
343    pub fn server_url(&self) -> &str {
344        &self.inner.server_url
345    }
346
347    /// `server_url` 的别名(对应 TS getBaseURL)。
348    pub fn base_url(&self) -> &str {
349        &self.inner.server_url
350    }
351
352    /// 当前 token 快照(克隆)。
353    pub fn token_set(&self) -> Option<TokenSet> {
354        if self
355            .inner
356            .strict
357            .as_ref()
358            .is_some_and(|s| s.check().is_err())
359        {
360            return None;
361        }
362        self.inner
363            .tokens
364            .read()
365            .unwrap()
366            .as_ref()
367            .map(|t| (**t).clone())
368    }
369
370    /// compliance 端点 base override(`None` = 走默认 `{server_url}/admin-api`)。
371    pub fn compliance_base_url(&self) -> Option<&str> {
372        self.inner.compliance_base_url.as_deref()
373    }
374
375    /// 业务 API 端点 base override(`None` = 走默认 `server_url`)。
376    pub fn api_base_url(&self) -> Option<&str> {
377        self.inner.api_base_url.as_deref()
378    }
379
380    /// OAuth 元数据 profile。
381    pub fn oauth_metadata_profile(&self) -> OAuthMetadataProfile {
382        self.inner.oauth_metadata_profile
383    }
384
385    /// 浏览器刷新模式。
386    pub fn browser_refresh_mode(&self) -> BrowserRefreshMode {
387        self.inner.browser_refresh_mode
388    }
389
390    /// refresh 代理 URL。
391    pub fn refresh_proxy_url(&self) -> Option<&str> {
392        self.inner.refresh_proxy_url.as_deref()
393    }
394
395    /// 共享 HTTP client(内部 / 业务方法使用)。
396    pub(crate) fn http(&self) -> &HttpClient {
397        &self.inner.http
398    }
399
400    /// V29 系数缓存槽(billing/entitlements 业务方法用)。
401    pub(crate) fn coef_cache(
402        &self,
403    ) -> &RwLock<Option<(Vec<crate::billing::ModelCoefficient>, std::time::Instant)>> {
404        &self.inner.coef_cache
405    }
406
407    /// 当前 WebSocket 状态槽(notifications/ws 业务方法用)。
408    #[cfg(feature = "notifications-ws")]
409    pub(crate) fn ws_slot(&self) -> &tokio::sync::Mutex<Option<crate::notifications::WsHandle>> {
410        &self.inner.ws
411    }
412
413    /// 生效重试策略(`None` = 禁用)。
414    pub(crate) fn uses_strict_authority(&self) -> bool {
415        self.inner.strict.is_some()
416    }
417
418    pub(crate) fn retry_policy(&self) -> Option<&EffectiveRetryPolicy> {
419        self.inner.retry_policy.as_ref()
420    }
421
422    // ── 授权生命周期(对应 TS login / loginWithHandler / logout)──
423
424    /// 完整授权流程:发现 → 注册 → 授权(PKCE loopback)→ 换 token → 持久化。
425    /// 对应 TS `login`。`app_name` 为桌面智能体名称;`scopes` 见 [`crate::auth::scopes`] 预设。
426    pub async fn login(
427        &self,
428        app_name: &str,
429        scopes: &[String],
430        signal: Option<CancellationToken>,
431    ) -> Result<()> {
432        self.login_internal(app_name, scopes, None, &Default::default(), signal)
433            .await
434    }
435
436    /// 带事件回调的登录流程(CrabCode 使用)。对应 TS `loginWithHandler`。
437    ///
438    /// `handler` 在以下时刻被调用:`EVENT_AUTH_URL`(授权 URL 就绪)/ `EVENT_COMPLETE`
439    /// (登录成功,tokens 已持久化)/ `EVENT_ERROR`(某步骤失败,附错误码)。
440    pub async fn login_with_handler(
441        &self,
442        app_name: &str,
443        scopes: &[String],
444        handler: Option<&(dyn Fn(oauth::LoginEvent) + Send + Sync)>,
445        opts: &oauth::LoginOptions,
446        signal: Option<CancellationToken>,
447    ) -> Result<()> {
448        self.login_internal(app_name, scopes, handler, opts, signal)
449            .await
450    }
451
452    async fn login_internal(
453        &self,
454        app_name: &str,
455        scopes: &[String],
456        handler: Option<&(dyn Fn(oauth::LoginEvent) + Send + Sync)>,
457        opts: &oauth::LoginOptions,
458        signal: Option<CancellationToken>,
459    ) -> Result<()> {
460        let strict = self.inner.strict.as_ref();
461        let _authority_guards = if let Some(strict) = strict {
462            strict.check()?;
463            let mutex = with_cancel(signal.as_ref(), self.inner.mu.lock()).await?;
464            strict.check()?;
465            let guard = with_cancel(signal.as_ref(), strict.authority.lock()).await??;
466            let state = with_cancel(signal.as_ref(), self.read_authority(strict)).await??;
467            self.cache_authority_state(state);
468            Some((mutex, guard))
469        } else {
470            None
471        };
472        let emit = |e: oauth::LoginEvent| {
473            if let Some(h) = handler {
474                h(e);
475            }
476        };
477        let emit_error = |code: &str, err: &Error| {
478            emit(oauth::LoginEvent::error(code, err.to_string()));
479        };
480
481        // 单航班门:标记 login 进行中,确保 finally 复位。
482        self.inner.login_in_flight.store(true, Ordering::SeqCst);
483        struct LoginReset<'a>(&'a AtomicBool, &'a tokio::sync::Notify);
484        impl Drop for LoginReset<'_> {
485            fn drop(&mut self) {
486                self.0.store(false, Ordering::SeqCst);
487                self.1.notify_waiters();
488            }
489        }
490        let _reset = LoginReset(&self.inner.login_in_flight, &self.inner.token_ready);
491        let result = with_cancel(
492            signal.as_ref(),
493            self.login_steps(
494                app_name,
495                scopes,
496                handler,
497                opts,
498                signal.clone(),
499                &emit,
500                &emit_error,
501            ),
502        )
503        .await?;
504        self.inner.login_in_flight.store(false, Ordering::SeqCst);
505        result
506    }
507
508    #[allow(clippy::too_many_arguments)]
509    async fn login_steps(
510        &self,
511        app_name: &str,
512        scopes: &[String],
513        handler: Option<&(dyn Fn(oauth::LoginEvent) + Send + Sync)>,
514        opts: &oauth::LoginOptions,
515        signal: Option<CancellationToken>,
516        emit: &dyn Fn(oauth::LoginEvent),
517        emit_error: &dyn Fn(&str, &Error),
518    ) -> Result<()> {
519        // 1. 发现
520        let meta = match oauth::discover_with_transport(
521            &self.http().with_cancellation(signal.clone()),
522            &self.inner.server_url,
523        )
524        .await
525        {
526            Ok(m) => m,
527            Err(e) => {
528                emit_error(oauth::ERR_DISCOVERY, &e);
529                return Err(Error::other(format!("discovery failed: {e}")));
530            }
531        };
532        *self.inner.meta.write().unwrap() = Some(meta.clone());
533
534        // 2. 已有 client_id 则复用,无则注册
535        let mut client_id = self.cached_client_id();
536        if client_id.is_empty() {
537            match oauth::register_with_transport(
538                &self.http().with_cancellation(signal.clone()),
539                &meta,
540                app_name,
541            )
542            .await
543            {
544                Ok(reg) => client_id = reg.client_id,
545                Err(e) => {
546                    emit_error(oauth::ERR_REGISTRATION, &e);
547                    return Err(Error::other(format!("registration failed: {e}")));
548                }
549            }
550        }
551
552        // 3. 授权(PKCE + loopback callback)。失败 → 清 client_id 重注册再试一次。
553        let (result, verifier) = match self
554            .do_authorize(&meta, &client_id, scopes, opts, handler, signal.clone())
555            .await
556        {
557            Ok(r) => r,
558            Err(first_err) => {
559                match oauth::register_with_transport(
560                    &self.http().with_cancellation(signal.clone()),
561                    &meta,
562                    app_name,
563                )
564                .await
565                {
566                    Ok(reg) => client_id = reg.client_id,
567                    Err(reg_err) => {
568                        emit_error(oauth::ERR_REGISTRATION, &reg_err);
569                        return Err(Error::other(format!(
570                            "authorization failed (retry registration also failed): {first_err}"
571                        )));
572                    }
573                }
574                match self
575                    .do_authorize(&meta, &client_id, scopes, opts, handler, signal.clone())
576                    .await
577                {
578                    Ok(r) => r,
579                    Err(e2) => return Err(Error::other(format!("authorization failed: {e2}"))),
580                }
581            }
582        };
583
584        if let Some(strict) = &self.inner.strict {
585            self.begin_authority_rotation(strict).await?;
586        }
587        // 4. 换 token(支持自定义 expires_in)
588        let token_resp = {
589            let exchange = if let Some(exp) = opts.expires_in.filter(|&e| e > 0) {
590                oauth::exchange_code_with_expiry_with_transport(
591                    &self.http().with_cancellation(signal.clone()),
592                    &meta,
593                    &client_id,
594                    &result.code,
595                    &result.redirect_uri,
596                    &verifier,
597                    exp,
598                )
599                .await
600            } else {
601                oauth::exchange_code_with_transport(
602                    &self.http().with_cancellation(signal.clone()),
603                    &meta,
604                    &client_id,
605                    &result.code,
606                    &result.redirect_uri,
607                    &verifier,
608                )
609                .await
610            };
611            match exchange {
612                Ok(r) => r,
613                Err(e) => {
614                    let code = if oauth::is_ssl_error(&e.to_string()) {
615                        oauth::ERR_SSL_PROXY
616                    } else {
617                        oauth::ERR_TOKEN_EXCHANGE
618                    };
619                    emit_error(code, &e);
620                    return Err(Error::other(format!("token exchange failed: {e}")));
621                }
622            }
623        };
624
625        // 5. 持久化 + 通知等待方
626        let token_resp = zeroize::Zeroizing::new(token_resp);
627        let tokens = zeroize::Zeroizing::new(oauth::new_token_set(
628            &token_resp,
629            &client_id,
630            &self.inner.server_url,
631        ));
632        if let Some(strict) = &self.inner.strict {
633            self.commit_authority_rotation(strict, &tokens).await?;
634        } else {
635            *self.inner.tokens.write().unwrap() = Some(zeroize::Zeroizing::new((*tokens).clone()));
636            self.inner.token_ready.notify_waiters();
637            if self.inner.store.save(&tokens).await.is_err() {
638                return Err(Error::other("save tokens failed"));
639            }
640        }
641
642        emit(oauth::LoginEvent::complete());
643        Ok(())
644    }
645
646    /// loopback 授权步骤。feature `desktop-loopback` 启用时走真实 loopback HTTP server;
647    /// 否则返回占位错误(desktop-loopback: P2 占位)。
648    #[allow(unused_variables)]
649    async fn do_authorize(
650        &self,
651        meta: &ServerMetadata,
652        client_id: &str,
653        scopes: &[String],
654        opts: &oauth::LoginOptions,
655        handler: Option<&(dyn Fn(oauth::LoginEvent) + Send + Sync)>,
656        signal: Option<CancellationToken>,
657    ) -> Result<(oauth::AuthorizeResult, String)> {
658        #[cfg(feature = "desktop-loopback")]
659        {
660            oauth::authorize(meta, client_id, scopes, opts, handler, signal).await
661        }
662        #[cfg(not(feature = "desktop-loopback"))]
663        {
664            // desktop-loopback: 未启用 feature 时不内置 loopback HTTP server。
665            // 浏览器侧应改用 create_web_authorization_request / complete_web_authorization_request
666            // (平台无关纯逻辑);桌面 loopback 登录请开启 `desktop-loopback` feature。
667            Err(Error::other(
668                "login() requires the `desktop-loopback` feature (loopback HTTP callback server); \
669                 for browser flows use create_web_authorization_request / complete_web_authorization_request",
670            ))
671        }
672    }
673
674    /// 吊销 token 并清除本地存储。对应 TS `logout`。
675    pub async fn logout(&self, signal: Option<CancellationToken>) -> Result<()> {
676        if self.inner.strict.is_some() {
677            return with_cancel(signal.as_ref(), self.logout_authority(signal.clone())).await?;
678        }
679        let tokens = self.inner.tokens.write().unwrap().take();
680        let mut meta = self.inner.meta.write().unwrap().take();
681        // 重置等待信号:下次 login 重新触发等待→唤醒流程。
682        self.inner.login_in_flight.store(false, Ordering::SeqCst);
683
684        if let Some(tokens) = tokens {
685            if meta.is_none() {
686                // token-lifecycle discovery:revoke 必须打与签发 token 同 profile 的端点。
687                match self.discover_for_lifecycle(signal.clone()).await {
688                    Ok(m) => meta = Some(m),
689                    Err(_) => {
690                        eprintln!("[acosmi-sdk] warning: discover for revocation failed");
691                    }
692                }
693            }
694            if let Some(meta) = meta {
695                // 吊销失败静默忽略(best-effort)。
696                let _ = oauth::revoke_token_with_transport(
697                    &self.http().with_cancellation(signal.clone()),
698                    &meta,
699                    &tokens.access_token,
700                )
701                .await;
702                let _ = oauth::revoke_token_with_transport(
703                    &self.http().with_cancellation(signal.clone()),
704                    &meta,
705                    &tokens.refresh_token,
706                )
707                .await;
708            }
709        }
710
711        with_cancel(signal.as_ref(), self.inner.store.clear())
712            .await?
713            .map_err(|_| Error::other("token store clear failed"))
714    }
715
716    // ── Token 管理(对应 TS ensureToken / forceRefresh)──
717
718    /// 确保有有效 access_token,过期则自动刷新。对应 TS `ensureToken`。
719    ///
720    /// 并发语义(对齐 TS withMu + storeWithLock + syncFromDisk + tokenReady):
721    ///   - tokens==null 且 login 进行中 → 等 `token_ready`(配合 `signal` 取消);非进行中 → 报未授权。
722    ///   - 未过期 → 直接返回(无锁路径)。
723    ///   - 过期 → 双层串行:`mu`(进程内单航班)+ `store.lock`(跨进程临界区);进入临界区后
724    ///     先 `store.load()` 重读磁盘(多进程 rotation 防 400),双检过期决定是否真刷新。
725    pub async fn ensure_token(&self, signal: Option<CancellationToken>) -> Result<String> {
726        {
727            let result = with_cancel(signal.as_ref(), self.ensure_token_internal(signal.clone()))
728                .await
729                .and_then(|r| r);
730            if result.is_err() && self.inner.strict.is_some() {
731                self.clear_authority_cache();
732            }
733            result
734        }
735    }
736
737    async fn ensure_token_internal(&self, signal: Option<CancellationToken>) -> Result<String> {
738        if self.inner.strict.is_some() {
739            return self.ensure_authority_token(false, signal).await;
740        }
741        let mut tokens = self.token_set();
742
743        if tokens.is_none() {
744            if !self.inner.login_in_flight.load(Ordering::SeqCst) {
745                return Err(Error::other("not authorized, call login() first"));
746            }
747            // login 进行中:等待 token 就绪或 abort。
748            // 先注册 notified()(避免 lost-wakeup),再复检 token;循环到 token 出现或 abort。
749            loop {
750                let notified = self.inner.token_ready.notified();
751                if let Some(t) = self.token_set() {
752                    tokens = Some(t);
753                    break;
754                }
755                if !self.inner.login_in_flight.load(Ordering::SeqCst) {
756                    // login 已结束但仍无 token(失败 / 被 logout 重置)。
757                    return Err(Error::other("not authorized, call login() first"));
758                }
759                match &signal {
760                    Some(cancel) => {
761                        tokio::select! {
762                            _ = notified => {}
763                            _ = cancel.cancelled() => {
764                                return Err(Error::other("waiting for token: aborted"));
765                            }
766                        }
767                    }
768                    None => notified.await,
769                }
770                if let Some(t) = self.token_set() {
771                    tokens = Some(t);
772                    break;
773                }
774            }
775        }
776
777        let tokens = tokens.expect("tokens present after wait");
778        if !token_set_is_expired(&tokens) {
779            return Ok(tokens.access_token);
780        }
781
782        // 需刷新 — 双层串行:mu 进程内 + store.lock 跨进程。
783        let _g = self.inner.mu.lock().await;
784        let _lock = self
785            .inner
786            .store
787            .lock()
788            .await
789            .map_err(|_| Error::other("token store lock failed"))?;
790
791        // 进入临界区后先同步磁盘(别的进程可能已 rotation)。
792        self.sync_from_disk().await;
793        // 双检。
794        let cur = self
795            .token_set()
796            .ok_or_else(|| Error::other("not authorized, call login() first"))?;
797        if !token_set_is_expired(&cur) {
798            return Ok(cur.access_token);
799        }
800
801        self.refresh_current_token(signal).await?;
802        self.token_set()
803            .map(|t| t.access_token)
804            .ok_or_else(|| Error::other("not authorized, call login() first"))
805    }
806
807    /// 强制刷新 token(401 重试用)。对应 TS `forceRefresh`。
808    ///
809    /// 同 [`Self::ensure_token`] 的刷新路径:mu + store.lock + syncFromDisk。别的进程刚 rotation
810    /// 过的话磁盘上是新 RT,本进程用磁盘新 RT 即可成功;否则用旧 RT 必撞 "refresh token not found" 400。
811    pub async fn force_refresh(&self, signal: Option<CancellationToken>) -> Result<()> {
812        let result = with_cancel(signal.as_ref(), self.force_refresh_internal(signal.clone()))
813            .await
814            .and_then(|r| r);
815        if result.is_err() && self.uses_strict_authority() {
816            self.clear_authority_cache();
817        }
818        result
819    }
820
821    async fn force_refresh_internal(&self, signal: Option<CancellationToken>) -> Result<()> {
822        if self.inner.strict.is_some() {
823            self.ensure_authority_token(true, signal).await?;
824            return Ok(());
825        }
826        let _g = self.inner.mu.lock().await;
827        let _lock = self
828            .inner
829            .store
830            .lock()
831            .await
832            .map_err(|_| Error::other("token store lock failed"))?;
833        self.sync_from_disk().await;
834        if self.token_set().is_none() {
835            return Err(Error::other("no tokens to refresh"));
836        }
837        self.refresh_current_token(signal).await
838    }
839
840    async fn read_authority(&self, strict: &StrictState) -> Result<AuthorityState> {
841        let state = match strict.authority.load().await {
842            Ok(state) => state,
843            Err(error) => {
844                self.clear_authority_cache();
845                return Err(error.into());
846            }
847        };
848        if matches!(state, AuthorityState::RotationPending) {
849            strict.block();
850            self.clear_authority_cache();
851            return Err(TokenAuthorityError::RotationPending.into());
852        }
853        Ok(state)
854    }
855
856    fn clear_authority_cache(&self) {
857        *self.inner.tokens.write().unwrap() = None;
858    }
859    fn cache_authority_state(&self, state: AuthorityState) -> bool {
860        match state {
861            AuthorityState::Ready(tokens) => {
862                *self.inner.tokens.write().unwrap() = Some(zeroize::Zeroizing::new(tokens));
863                true
864            }
865            AuthorityState::Missing | AuthorityState::RotationPending => {
866                self.clear_authority_cache();
867                false
868            }
869        }
870    }
871
872    /// Pure authority read, never refreshes or resolves durable Pending. The host
873    /// must first resolve uncertain transactions and actor/revision fencing.
874    /// Calling this explicitly accepts that host reconciliation has completed.
875    pub async fn reconcile_authority(&self, signal: Option<CancellationToken>) -> Result<bool> {
876        self.clear_authority_cache();
877        let strict = self
878            .inner
879            .strict
880            .as_ref()
881            .ok_or_else(|| Error::other("strict token authority not configured"))?;
882        with_cancel(signal.as_ref(), async {
883            let _mutex = self.inner.mu.lock().await;
884            let _guard = strict.authority.lock().await?;
885            let state = self.read_authority(strict).await?;
886            let ready = self.cache_authority_state(state);
887            strict.reconcile();
888            Ok(ready)
889        })
890        .await?
891    }
892
893    async fn begin_authority_rotation(&self, strict: &StrictState) -> Result<()> {
894        // Set before awaiting: cancellation or an ambiguous begin may already have committed.
895        strict.block();
896        self.clear_authority_cache();
897        strict.authority.begin_rotation().await?;
898        Ok(())
899    }
900
901    async fn commit_authority_rotation(
902        &self,
903        strict: &StrictState,
904        tokens: &TokenSet,
905    ) -> Result<()> {
906        strict.authority.commit_rotation(tokens).await?;
907        // Do not expose either a mismatching or unconfirmed readback.
908        let state = strict.authority.load().await?;
909        match state {
910            AuthorityState::Ready(confirmed) => {
911                let confirmed = zeroize::Zeroizing::new(confirmed);
912                if !tokens_equal(&confirmed, tokens) {
913                    return Err(TokenAuthorityError::CommitUnverified.into());
914                }
915                *self.inner.tokens.write().unwrap() =
916                    Some(zeroize::Zeroizing::new((*confirmed).clone()));
917                strict.reconcile();
918                self.inner.token_ready.notify_waiters();
919                Ok(())
920            }
921            _ => Err(TokenAuthorityError::CommitUnverified.into()),
922        }
923    }
924
925    async fn ensure_authority_token(
926        &self,
927        force: bool,
928        signal: Option<CancellationToken>,
929    ) -> Result<String> {
930        let strict = self
931            .inner
932            .strict
933            .as_ref()
934            .ok_or(TokenAuthorityError::Unavailable)?;
935        strict.check()?;
936        let _mutex = self.inner.mu.lock().await;
937        strict.check()?;
938        let _guard = strict.authority.lock().await?;
939        let state = self.read_authority(strict).await?;
940        let tokens = match state {
941            AuthorityState::Ready(tokens) => zeroize::Zeroizing::new(tokens),
942            _ => {
943                self.clear_authority_cache();
944                return Err(TokenAuthorityError::Missing.into());
945            }
946        };
947        if !force && !token_set_is_expired(&tokens) {
948            *self.inner.tokens.write().unwrap() = Some(zeroize::Zeroizing::new((*tokens).clone()));
949            return Ok(tokens.access_token.clone());
950        }
951        if self.inner.browser_refresh_mode == BrowserRefreshMode::None {
952            self.clear_authority_cache();
953            return Err(Error::other("token refresh disabled"));
954        }
955        self.begin_authority_rotation(strict).await?;
956        let new_set = zeroize::Zeroizing::new(match self.inner.browser_refresh_mode {
957            BrowserRefreshMode::ServerProxy => {
958                self.fetch_refresh_via_proxy(&tokens, signal).await?
959            }
960            BrowserRefreshMode::Direct => self.fetch_refresh_direct(&tokens, signal).await?,
961            BrowserRefreshMode::None => return Err(Error::other("token refresh disabled")),
962        });
963        self.commit_authority_rotation(strict, &new_set).await?;
964        Ok(new_set.access_token.clone())
965    }
966
967    async fn logout_authority(&self, signal: Option<CancellationToken>) -> Result<()> {
968        let strict = self
969            .inner
970            .strict
971            .as_ref()
972            .ok_or(TokenAuthorityError::Unavailable)?;
973        strict.check()?;
974        let _mutex = self.inner.mu.lock().await;
975        strict.check()?;
976        let _guard = strict.authority.lock().await?;
977        let state = self.read_authority(strict).await?;
978        let tokens = match state {
979            AuthorityState::Ready(t) => Some(zeroize::Zeroizing::new(t)),
980            _ => None,
981        };
982        strict.block();
983        self.clear_authority_cache();
984        strict.authority.clear().await?;
985        if !matches!(strict.authority.load().await?, AuthorityState::Missing) {
986            return Err(TokenAuthorityError::CommitUnverified.into());
987        }
988        strict.reconcile();
989        self.inner.login_in_flight.store(false, Ordering::SeqCst);
990        if let Some(tokens) = tokens {
991            if let Ok(meta) = self.discover_for_lifecycle(signal.clone()).await {
992                let http = self.http().with_cancellation(signal);
993                let _ =
994                    oauth::revoke_token_with_transport(&http, &meta, &tokens.access_token).await;
995                let _ =
996                    oauth::revoke_token_with_transport(&http, &meta, &tokens.refresh_token).await;
997            }
998        }
999        Ok(())
1000    }
1001
1002    // ── 私有 helper ──
1003
1004    fn cached_client_id(&self) -> String {
1005        self.inner
1006            .tokens
1007            .read()
1008            .unwrap()
1009            .as_ref()
1010            .map(|t| t.client_id.clone())
1011            .unwrap_or_default()
1012    }
1013
1014    /// token-lifecycle discovery:revoke / refresh 必须打与签发 token 同 profile 的端点。
1015    async fn discover_for_lifecycle(
1016        &self,
1017        signal: Option<CancellationToken>,
1018    ) -> Result<ServerMetadata> {
1019        let profile = match self.inner.oauth_metadata_profile {
1020            OAuthMetadataProfile::Desktop => oauth::OAuthMetadataProfile::Desktop,
1021            OAuthMetadataProfile::Web => oauth::OAuthMetadataProfile::Web,
1022        };
1023        oauth::discover_with_profile_with_transport(
1024            &self.http().with_cancellation(signal),
1025            &self.inner.server_url,
1026            profile,
1027        )
1028        .await
1029    }
1030
1031    /// 刷新当前 token(轮换:换新撤旧)。`browser_refresh_mode` 决定 direct / server-proxy / none。
1032    async fn refresh_current_token(&self, signal: Option<CancellationToken>) -> Result<()> {
1033        if self.token_set().is_none() {
1034            return Err(Error::other("no tokens to refresh"));
1035        }
1036        match self.inner.browser_refresh_mode {
1037            BrowserRefreshMode::None => Err(Error::other(format!(
1038                "{ERR_TOKEN_EXPIRED}: token refresh disabled"
1039            ))),
1040            BrowserRefreshMode::ServerProxy => self.refresh_legacy(true, signal).await,
1041            BrowserRefreshMode::Direct => self.refresh_legacy(false, signal).await,
1042        }
1043    }
1044
1045    async fn refresh_legacy(&self, proxy: bool, signal: Option<CancellationToken>) -> Result<()> {
1046        let cur = zeroize::Zeroizing::new(
1047            self.token_set()
1048                .ok_or_else(|| Error::other("no tokens to refresh"))?,
1049        );
1050        let new_set = zeroize::Zeroizing::new(if proxy {
1051            self.fetch_refresh_via_proxy(&cur, signal).await?
1052        } else {
1053            self.fetch_refresh_direct(&cur, signal).await?
1054        });
1055        *self.inner.tokens.write().unwrap() = Some(zeroize::Zeroizing::new((*new_set).clone()));
1056        self.save_refreshed_token(&new_set).await;
1057        Ok(())
1058    }
1059
1060    async fn fetch_refresh_direct(
1061        &self,
1062        cur: &TokenSet,
1063        signal: Option<CancellationToken>,
1064    ) -> Result<TokenSet> {
1065        // 确保 meta(与签发同 profile)。
1066        if self.inner.meta.read().unwrap().is_none() {
1067            match self.discover_for_lifecycle(signal.clone()).await {
1068                Ok(m) => *self.inner.meta.write().unwrap() = Some(m),
1069                Err(e) => return Err(Error::other(format!("discover for refresh: {e}"))),
1070            }
1071        }
1072        let meta = self
1073            .inner
1074            .meta
1075            .read()
1076            .unwrap()
1077            .clone()
1078            .ok_or_else(|| Error::other("discover for refresh: no metadata"))?;
1079
1080        let token_resp = match oauth::refresh_token_with_transport(
1081            &self.http().with_cancellation(signal),
1082            &meta,
1083            &cur.client_id,
1084            &cur.refresh_token,
1085        )
1086        .await
1087        {
1088            Ok(r) => r,
1089            Err(e) => {
1090                if oauth::is_invalid_grant_error(&e) {
1091                    if self.inner.strict.is_none() {
1092                        self.clear_invalid_refresh_token().await;
1093                    }
1094                    return Err(Error::other(format!("refresh token invalid: {e}")));
1095                }
1096                let msg = e.to_string();
1097                if is_likely_browser_oauth_cors_error(&msg) {
1098                    return Err(Error::other(format!(
1099                        "{ERR_OAUTH_CORS_BLOCKED}: refresh token: {msg}"
1100                    )));
1101                }
1102                return Err(Error::other(format!("refresh token: {msg}")));
1103            }
1104        };
1105
1106        let token_resp = zeroize::Zeroizing::new(token_resp);
1107        let new_set = zeroize::Zeroizing::new(oauth::new_token_set(
1108            &token_resp,
1109            &cur.client_id,
1110            &self.inner.server_url,
1111        ));
1112        Ok((*new_set).clone())
1113    }
1114
1115    async fn fetch_refresh_via_proxy(
1116        &self,
1117        cur: &TokenSet,
1118        signal: Option<CancellationToken>,
1119    ) -> Result<TokenSet> {
1120        let proxy_url = self.inner.refresh_proxy_url.as_deref().ok_or_else(|| {
1121            Error::other(format!(
1122                "{ERR_REFRESH_PROXY_FAILED}: refreshProxyURL is required"
1123            ))
1124        })?;
1125
1126        let server_url = if cur.server_url.is_empty() {
1127            self.inner.server_url.clone()
1128        } else {
1129            cur.server_url.clone()
1130        };
1131        let body = serde_json::json!({
1132            "client_id": cur.client_id,
1133            "refresh_token": cur.refresh_token,
1134            "server_url": server_url,
1135        });
1136
1137        let req = self
1138            .http()
1139            .post(proxy_url)
1140            .purpose(HttpPurpose::OAuthToken)
1141            .cancel(signal.clone())
1142            .json(&body);
1143        let send = req.send();
1144        let resp = match signal {
1145            Some(cancel) => tokio::select! {
1146                r = send => r,
1147                _ = cancel.cancelled() => {
1148                    return Err(Error::other(format!("{ERR_REFRESH_PROXY_FAILED}: aborted")));
1149                }
1150            },
1151            None => send.await,
1152        }
1153        .map_err(|e| Error::other(format!("{ERR_REFRESH_PROXY_FAILED}: {e}")))?;
1154
1155        if !resp.status().is_success() {
1156            let status = resp.status().as_u16();
1157            let oauth_error = resp
1158                .json::<serde_json::Value>()
1159                .await
1160                .ok()
1161                .and_then(|body| {
1162                    body.get("error")
1163                        .and_then(|v| v.as_str())
1164                        .map(str::to_owned)
1165                });
1166            if oauth_error.as_deref() == Some("invalid_grant") {
1167                if self.inner.strict.is_none() {
1168                    self.clear_invalid_refresh_token().await;
1169                }
1170                return Err(Error::other(format!(
1171                    "{ERR_REFRESH_PROXY_FAILED}: refresh token invalid"
1172                )));
1173            }
1174            return Err(Error::other(format!(
1175                "{ERR_REFRESH_PROXY_FAILED}: HTTP {status}"
1176            )));
1177        }
1178
1179        #[derive(serde::Deserialize)]
1180        struct ProxyResp {
1181            #[serde(default)]
1182            #[serde(rename = "tokenSet")]
1183            token_set: Option<TokenSet>,
1184        }
1185        let parsed: ProxyResp = resp
1186            .json()
1187            .await
1188            .map_err(|_| Error::other(format!("{ERR_REFRESH_PROXY_FAILED}: decode failed")))?;
1189        let new_set = parsed.token_set.ok_or_else(|| {
1190            Error::other(format!(
1191                "{ERR_REFRESH_PROXY_FAILED}: response missing tokenSet"
1192            ))
1193        })?;
1194
1195        Ok(new_set)
1196    }
1197
1198    async fn save_refreshed_token(&self, tokens: &TokenSet) {
1199        if self.inner.store.save(tokens).await.is_err() {
1200            eprintln!("[acosmi-sdk] warning: save refreshed token failed");
1201        }
1202    }
1203
1204    async fn clear_invalid_refresh_token(&self) {
1205        *self.inner.tokens.write().unwrap() = None;
1206        *self.inner.meta.write().unwrap() = None;
1207        self.inner.login_in_flight.store(false, Ordering::SeqCst);
1208        if self.inner.store.clear().await.is_err() {
1209            eprintln!("[acosmi-sdk] warning: clear invalid token failed");
1210        }
1211    }
1212
1213    /// 从磁盘同步 token(refresh 前)。对应 TS `syncFromDisk`。
1214    ///
1215    /// 别的进程 rotation 后磁盘 refresh_token 已变,本进程内存仍是旧 R0;不同步直接 refresh
1216    /// 必撞网关 400。load 失败保留内存继续(容错)。
1217    async fn sync_from_disk(&self) {
1218        let on_disk = match self.inner.store.load().await {
1219            Ok(Some(t)) => t,
1220            Ok(None) => return,
1221            // 磁盘读失败(损坏 / 权限)— 不阻塞 refresh,让后续 refresh_token 暴露真实错误。
1222            Err(_) => return,
1223        };
1224        let adopt = {
1225            let cur = self.inner.tokens.read().unwrap();
1226            match cur.as_ref() {
1227                None => true,
1228                Some(c) => on_disk.refresh_token != c.refresh_token,
1229            }
1230        };
1231        if adopt {
1232            *self.inner.tokens.write().unwrap() = Some(zeroize::Zeroizing::new(on_disk));
1233        }
1234    }
1235
1236    // ===========================================================================
1237    // URL 拼接(对应 TS apiURL)
1238    // ===========================================================================
1239
1240    /// 业务 API URL 拼接。`api_base_url` 覆盖(未配置时 === server_url);尾段非 `/api/v4` 时追加。
1241    /// 对应 TS `apiURL`。
1242    pub fn api_url(&self, path: &str) -> String {
1243        let mut base = self
1244            .inner
1245            .api_base_url
1246            .clone()
1247            .unwrap_or_else(|| self.inner.server_url.clone());
1248        if !base.ends_with("/api/v4") {
1249            base.push_str("/api/v4");
1250        }
1251        base.push_str(path);
1252        base
1253    }
1254
1255    // ===========================================================================
1256    // 通用 JSON GET(最小 do_json_get:GET + Bearer + ApiResponse 解包 + 401 单次重试)
1257    // ===========================================================================
1258
1259    /// GET 请求并反序列化为 `T`,同时返回响应头。对应 TS `doJSONFull<T>('GET',...)` 的 GET 子集。
1260    ///
1261    /// 行为对齐 `doJSONFullInternal`:ensure_token → Bearer → 非 2xx 抛 HttpError(含 Retry-After)→
1262    /// 401 单次 force_refresh 重试 → 空 body 跳业务码(这里 GET 端点都返回 ApiResponse,调用方自处理)→
1263    /// JSON 反序列化 + 业务码检查(`code != 0` 抛 BusinessError)。
1264    pub(crate) async fn do_json_get_full<T: DeserializeOwned>(
1265        &self,
1266        path: &str,
1267        signal: Option<CancellationToken>,
1268    ) -> Result<(T, http::header::HeaderMap)> {
1269        self.do_json_get_internal(path, signal, false).await
1270    }
1271
1272    /// 公共端点 GET(**无 token**,对应 TS `doPublicJSON`)。skill-store 浏览/详情/resolve 用。
1273    ///
1274    /// 不附 Authorization(公共端点),不做 401 force_refresh 重试(无凭证可刷)。
1275    /// 非 2xx → [`Error::Http`];空体 → 强 Err(公共 ApiResponse 端点不应空体)。
1276    pub(crate) async fn do_public_json_full<T: DeserializeOwned>(
1277        &self,
1278        path: &str,
1279        signal: Option<CancellationToken>,
1280    ) -> Result<T> {
1281        let url = self.api_url(path);
1282        // per-request 死线(对齐 TS doPublicJSON 30s):去掉 client 级总超时后,公共 GET 必须
1283        // 自派生 30s 子 token,否则变无超时。超时或 parent signal 取消任一触发即 abort。
1284        let signal = self.derive_timeout_token(DEFAULT_JSON_TIMEOUT_MS, signal);
1285        let send = self.http().get(&url).cancel(signal.clone()).send();
1286        let resp = match &signal {
1287            Some(cancel) => tokio::select! {
1288                r = send => r,
1289                _ = cancel.cancelled() => {
1290                    return Err(Error::other(format!("GET {path}: aborted")));
1291                }
1292            },
1293            None => send.await,
1294        }?;
1295
1296        let status = resp.status();
1297        if !status.is_success() {
1298            let retry_after = parse_retry_after_secs(resp.headers());
1299            let body = read_limited_text(resp.bytes_stream(), MAX_ERROR_BODY_SIZE).await?;
1300            return Err(Error::Http(parse_http_error_with_retry_after(
1301                status.as_u16(),
1302                &body,
1303                retry_after,
1304            )));
1305        }
1306
1307        let text = resp
1308            .text()
1309            .await
1310            .map_err(|e| Error::other(format!("GET {path}: read body: {e}")))?;
1311        if text.is_empty() {
1312            return Err(Error::other(format!("GET {path}: empty response body")));
1313        }
1314        serde_json::from_str(&text).map_err(|e| Error::other(format!("GET {path}: decode: {e}")))
1315    }
1316
1317    async fn do_json_get_internal<T: DeserializeOwned>(
1318        &self,
1319        path: &str,
1320        signal: Option<CancellationToken>,
1321        retried: bool,
1322    ) -> Result<(T, http::header::HeaderMap)> {
1323        // per-request 死线(对齐 TS doJSONGet 30s):去掉 client 级总超时后,GET 必须自派生 30s
1324        // 子 token,否则变无超时。401 重试沿用原 `signal` 各自重新派生(见下方递归调用)。
1325        let req_signal = self.derive_timeout_token(DEFAULT_JSON_TIMEOUT_MS, signal.clone());
1326        let token = zeroize::Zeroizing::new(self.ensure_token(req_signal.clone()).await?);
1327        let url = self.api_url(path);
1328
1329        let send = self
1330            .http()
1331            .get(&url)
1332            .cancel(req_signal.clone())
1333            .header(
1334                http::header::AUTHORIZATION,
1335                format!("Bearer {}", token.as_str()),
1336            )
1337            .send();
1338        let resp = match &req_signal {
1339            Some(cancel) => tokio::select! {
1340                r = send => r,
1341                _ = cancel.cancelled() => {
1342                    return Err(Error::other(format!("GET {path}: aborted")));
1343                }
1344            },
1345            None => send.await,
1346        }?;
1347
1348        let status = resp.status();
1349
1350        // 401:单次 force_refresh 重试(防递归)。重试沿用原 `signal`(非派生子 token),
1351        // 递归入口会重新派生新的 30s 死线。
1352        if status.as_u16() == 401 && !retried {
1353            self.force_refresh(signal.clone())
1354                .await
1355                .map_err(|e| Error::other(format!("unauthorized and refresh failed: {e}")))?;
1356            return Box::pin(self.do_json_get_internal(path, signal, true)).await;
1357        }
1358
1359        if !status.is_success() {
1360            let retry_after = resp
1361                .headers()
1362                .get(http::header::RETRY_AFTER)
1363                .and_then(|v| v.to_str().ok())
1364                .and_then(|s| s.trim().parse::<i64>().ok())
1365                .filter(|&s| s > 0)
1366                .unwrap_or(0);
1367            let body = read_limited_text(resp.bytes_stream(), MAX_ERROR_BODY_SIZE).await?;
1368            return Err(Error::Http(parse_http_error_with_retry_after(
1369                status.as_u16(),
1370                &body,
1371                retry_after,
1372            )));
1373        }
1374
1375        let headers = resp.headers().clone();
1376        let text = resp
1377            .text()
1378            .await
1379            .map_err(|e| Error::other(format!("GET {path}: read body: {e}")))?;
1380        if text.is_empty() {
1381            // 空 body 成功响应 —— ApiResponse<T> 端点不应空体;按强类型显式 Err(方案 §4.4)。
1382            return Err(Error::other(format!("GET {path}: empty response body")));
1383        }
1384        let result: T = serde_json::from_str(&text)
1385            .map_err(|e| Error::other(format!("GET {path}: decode: {e}")))?;
1386        Ok((result, headers))
1387    }
1388
1389    // ===========================================================================
1390    // Managed Models
1391    // ===========================================================================
1392
1393    /// 获取可用的托管模型列表。对应 TS `listModels`。
1394    ///
1395    /// 不返回 entitlement-filter-status header;想据 fallback 状态显示降级提示请改用
1396    /// [`Self::list_models_with_status`]。`include_locked=true` 请求全集模式(picker=1)。
1397    pub async fn list_models(
1398        &self,
1399        signal: Option<CancellationToken>,
1400        include_locked: bool,
1401    ) -> Result<Vec<ManagedModel>> {
1402        Ok(self
1403            .list_models_with_status(signal, include_locked)
1404            .await?
1405            .0)
1406    }
1407
1408    /// 获取可用模型列表,同时返回 `X-Entitlement-Filter-Status` header。对应 TS `listModelsWithStatus`。
1409    ///
1410    /// `include_locked=true` → 全集模式(picker=1,含越档 locked 模型供 picker 展示),
1411    /// **不写** model_cache(避免 locked 模型混入可用集);缺省模式照旧缓存。
1412    pub async fn list_models_with_status(
1413        &self,
1414        signal: Option<CancellationToken>,
1415        include_locked: bool,
1416    ) -> Result<(Vec<ManagedModel>, FilterStatus)> {
1417        let path = if include_locked {
1418            "/managed-models?picker=1"
1419        } else {
1420            "/managed-models"
1421        };
1422        let (result, headers): (ApiResponse<Vec<ManagedModel>>, _) =
1423            self.do_json_get_full(path, signal).await?;
1424        if let Some(err) = result.business_error() {
1425            return Err(err);
1426        }
1427        // v1.2:写缓存前归一化 input_modalities(snake)→ input_modalities(camel `inputModalities`)。
1428        let normalized = normalize_input_modalities(result.data);
1429
1430        if !include_locked {
1431            *self.inner.model_cache.write().unwrap() = normalized.clone();
1432            *self.inner.model_cache_time.write().unwrap() = Some(std::time::Instant::now());
1433        }
1434
1435        let status: FilterStatus = headers
1436            .get("X-Entitlement-Filter-Status")
1437            .and_then(|v| v.to_str().ok())
1438            .filter(|s| !s.is_empty())
1439            .map(FilterStatus::from)
1440            .unwrap_or_else(|| FilterStatus::UNKNOWN.into());
1441        Ok((normalized, status))
1442    }
1443
1444    /// 查询当前用户账户级权益总览(v0.19+)。对应 TS `getQuotaSummary`。
1445    pub async fn get_quota_summary(
1446        &self,
1447        signal: Option<CancellationToken>,
1448    ) -> Result<QuotaSummary> {
1449        let (resp, _): (ApiResponse<QuotaSummary>, _) = self
1450            .do_json_get_full("/entitlements/quota-summary", signal)
1451            .await?;
1452        if let Some(err) = resp.business_error() {
1453            return Err(err);
1454        }
1455        Ok(resp.data)
1456    }
1457
1458    /// 查询单个模型的能力矩阵。优先从 list_models 缓存读取,miss 时刷新一次。
1459    /// 对应 TS `getModelCapabilities`。仍 miss → 零值(与 Go/TS 一致)。
1460    pub async fn get_model_capabilities(
1461        &self,
1462        model_id: &str,
1463        signal: Option<CancellationToken>,
1464    ) -> Result<ModelCapabilities> {
1465        if let Some(caps) = self.cached_capabilities(model_id) {
1466            return Ok(caps);
1467        }
1468        self.list_models(signal, false).await?;
1469        if let Some(caps) = self.cached_capabilities(model_id) {
1470            return Ok(caps);
1471        }
1472        // 模型不在列表中,返回零值。
1473        Ok(zero_model_capabilities())
1474    }
1475
1476    /// 从缓存查 capabilities(缓存空或过 TTL → None)。对应 TS `getCachedCapabilities`。
1477    fn cached_capabilities(&self, model_id: &str) -> Option<ModelCapabilities> {
1478        let cache = self.inner.model_cache.read().unwrap();
1479        let time = *self.inner.model_cache_time.read().unwrap();
1480        let expired = match time {
1481            Some(t) => t.elapsed().as_millis() as u64 > MODEL_CACHE_TTL_MS,
1482            None => true,
1483        };
1484        if cache.is_empty() || expired {
1485            return None;
1486        }
1487        for m in cache.iter() {
1488            if m.id == model_id || m.model_id == model_id {
1489                return Some(m.capabilities.clone());
1490            }
1491        }
1492        None
1493    }
1494
1495    /// 从缓存查找完整 [`ManagedModel`](未命中返 `None`)。对应 TS `getCachedModel`。
1496    fn cached_model(&self, model_id: &str) -> Option<ManagedModel> {
1497        let cache = self.inner.model_cache.read().unwrap();
1498        cache
1499            .iter()
1500            .find(|m| m.id == model_id || m.model_id == model_id)
1501            .cloned()
1502    }
1503
1504    /// 确保指定 `model_id` 的 [`ManagedModel`] 已在缓存中。对应 TS `ensureModelCached`。
1505    ///
1506    /// 1. 缓存命中 → 直接返回;
1507    /// 2. 未命中 → 调 `list_models` 刷新一次;
1508    /// 3. 刷新后仍未命中 → `Error::ModelNotFound`。
1509    ///
1510    /// 根因修复(对齐 TS):消除未预热场景下 `provider="anthropic"` 硬编码回退,
1511    /// 该回退会让 non-anthropic 模型被按 Anthropic 格式编码并打到错误端点。
1512    pub async fn ensure_model_cached(
1513        &self,
1514        model_id: &str,
1515        signal: Option<CancellationToken>,
1516    ) -> Result<ManagedModel> {
1517        if let Some(m) = self.cached_model(model_id) {
1518            return Ok(m);
1519        }
1520        self.list_models(signal, false).await?;
1521        if let Some(m) = self.cached_model(model_id) {
1522            return Ok(m);
1523        }
1524        Err(Error::ModelNotFound {
1525            model_id: model_id.to_string(),
1526        })
1527    }
1528
1529    // ===========================================================================
1530    // 请求层(do_request / do_request_with_retry / do_json_full_raw)
1531    //
1532    // 红线区分:
1533    //   - do_request           = 单次 HTTP,**绝不重试**(流式路径独占)。
1534    //   - do_request_with_retry = 经 retry_policy + safe_to_retry 闸门的非流式包装
1535    //                             (POST 默认 safe_to_retry=false,不重试,计费安全)。
1536    //   - 401 单次 force_refresh 重试由 do_json_full_raw / 流式 gen 各自的 `retried` guard 管。
1537    // ===========================================================================
1538
1539    /// 单次 HTTP 请求(**无重试**)。对应 TS `doRequest`。
1540    ///
1541    /// 传输层错误经 `classify_transport` 转 [`Error::Network`](便于 retry policy 判定)。
1542    /// 取消信号经 `select!` 接入。**流式路径必须直接走此函数**,绝不经 [`Self::do_request_with_retry`]。
1543    pub(crate) async fn do_request(
1544        &self,
1545        method: http::Method,
1546        url: &str,
1547        headers: &[(http::header::HeaderName, String)],
1548        body: Option<&str>,
1549        signal: Option<&CancellationToken>,
1550        context: HttpContext,
1551    ) -> Result<crate::core::transport::Response> {
1552        // A retry is another protected request: re-read authority before dispatch.
1553        let authority_token = if self.uses_strict_authority()
1554            && headers
1555                .iter()
1556                .any(|(name, _)| name == http::header::AUTHORIZATION)
1557        {
1558            Some(zeroize::Zeroizing::new(
1559                self.ensure_token(signal.cloned()).await?,
1560            ))
1561        } else {
1562            None
1563        };
1564        let mut rb = self
1565            .http()
1566            .request(method.clone(), url)
1567            .context(context)
1568            .cancel(signal.cloned());
1569        for (k, v) in headers {
1570            rb = if k == http::header::AUTHORIZATION {
1571                if let Some(token) = &authority_token {
1572                    rb.header(k.clone(), format!("Bearer {}", token.as_str()))
1573                } else {
1574                    rb.header(k.clone(), v.clone())
1575                }
1576            } else {
1577                rb.header(k.clone(), v.clone())
1578            };
1579        }
1580        if let Some(b) = body {
1581            rb = rb.body(b.to_string());
1582        }
1583        rb.send().await
1584    }
1585
1586    /// 带 RetryPolicy 的 [`Self::do_request`] 包装 —— **仅用于非流式路径**。对应 TS `doRequestWithRetry`。
1587    ///
1588    /// 闸门:`retry_policy` 缺省(`None`)或 `safe_to_retry` 判定不可重试(POST 默认 false)→
1589    /// 直接走单次 [`Self::do_request`]。仅 5xx/429 进入 retry 评估(构造 [`Error::Http`] 喂
1590    /// `on_retryable`);transport 层错误([`Error::Network`])也喂 `on_retryable`。
1591    ///
1592    /// **流式路径([`Self::chat_stream`] / [`Self::chat_messages_stream`])绝不调用此函数**,
1593    /// 必须直接用 [`Self::do_request`](重试 = 双 token + 重复消息 = 双扣,计费安全红线)。
1594    async fn do_request_with_retry(
1595        &self,
1596        method: http::Method,
1597        url: &str,
1598        headers: &[(http::header::HeaderName, String)],
1599        body: Option<&str>,
1600        signal: Option<&CancellationToken>,
1601        context: HttpContext,
1602    ) -> Result<crate::core::transport::Response> {
1603        let policy = match self.retry_policy() {
1604            Some(p) => p.clone(),
1605            None => {
1606                return self
1607                    .do_request(method, url, headers, body, signal, context)
1608                    .await
1609            }
1610        };
1611        let info = RetryRequestInfo {
1612            method: method.as_str().to_string(),
1613            url: url.to_string(),
1614        };
1615        if !(policy.safe_to_retry)(&info) {
1616            return self
1617                .do_request(method, url, headers, body, signal, context)
1618                .await;
1619        }
1620
1621        let mut last_err: Option<Error> = None;
1622        let mut attempt: u32 = 0;
1623        while attempt < policy.max_attempts {
1624            match self
1625                .do_request(method.clone(), url, headers, body, signal, context)
1626                .await
1627            {
1628                Ok(resp) => {
1629                    let status = resp.status().as_u16();
1630                    // 仅 5xx/429 进入 retry 评估,其余直接返回。
1631                    if status < 500 && status != 429 {
1632                        return Ok(resp);
1633                    }
1634                    let retry_after = parse_retry_after_secs(resp.headers());
1635                    let peek = read_limited_text(resp.bytes_stream(), MAX_ERROR_BODY_SIZE).await?;
1636                    last_err = Some(Error::Http(parse_http_error_with_retry_after(
1637                        status,
1638                        &peek,
1639                        retry_after,
1640                    )));
1641                }
1642                Err(e) => last_err = Some(e),
1643            }
1644
1645            if attempt + 1 == policy.max_attempts {
1646                break;
1647            }
1648            let err_ref = last_err.as_ref().expect("last_err set");
1649            if !(policy.on_retryable)(err_ref) {
1650                break;
1651            }
1652            let backoff = crate::core::retry::compute_backoff(&policy, attempt, err_ref);
1653            sleep_with_cancel(backoff, signal).await;
1654            attempt += 1;
1655        }
1656        Err(last_err.unwrap_or_else(|| Error::other("do_request_with_retry: no attempts ran")))
1657    }
1658
1659    /// POST/GET JSON 请求,返回 **raw bytes** + 响应头(chat / 媒体用,不立即反序列化)。
1660    /// 对应 TS `doJSONFullRaw`。
1661    ///
1662    /// 行为:ensure_token → Bearer → [`Self::do_request_with_retry`](POST 默认不重试)→
1663    /// 401 单次 force_refresh 重试(`retried` guard 防递归)→ 非 2xx 抛 [`Error::Http`](含 Retry-After)→
1664    /// 读 body bytes。
1665    pub(crate) async fn do_json_full_raw(
1666        &self,
1667        method: http::Method,
1668        path: &str,
1669        body: Option<&str>,
1670        signal: Option<CancellationToken>,
1671        timeout_ms: u64,
1672        options: Option<ChatOptions>,
1673    ) -> Result<(Vec<u8>, http::header::HeaderMap)> {
1674        // per-request 超时(对应 TS withRequestTimeout):派生子 token,超时或 parent 取消任一触发即 abort。
1675        let ctl = self.derive_timeout_token(timeout_ms, signal);
1676        self.do_json_full_raw_internal(
1677            method,
1678            path,
1679            body,
1680            ctl.as_ref(),
1681            timeout_ms,
1682            options.unwrap_or_default(),
1683        )
1684        .await
1685    }
1686
1687    async fn do_json_full_raw_internal(
1688        &self,
1689        method: http::Method,
1690        path: &str,
1691        body: Option<&str>,
1692        signal: Option<&CancellationToken>,
1693        timeout_ms: u64,
1694        mut options: ChatOptions,
1695    ) -> Result<(Vec<u8>, http::header::HeaderMap)> {
1696        let mut retried = false;
1697        loop {
1698            let token = zeroize::Zeroizing::new(self.ensure_token(signal.cloned()).await?);
1699            let url = self.api_url(path);
1700
1701            let mut headers: Vec<(http::header::HeaderName, String)> = vec![(
1702                http::header::AUTHORIZATION,
1703                format!("Bearer {}", token.as_str()),
1704            )];
1705            if body.is_some() {
1706                headers.push((http::header::CONTENT_TYPE, "application/json".to_string()));
1707            }
1708
1709            let resp = self
1710                .do_request_with_retry(
1711                    method.clone(),
1712                    &url,
1713                    &headers,
1714                    body,
1715                    signal,
1716                    HttpContext::buffered(
1717                        if timeout_ms == CHAT_REQUEST_TIMEOUT_MS {
1718                            HttpPurpose::Model
1719                        } else {
1720                            HttpPurpose::Api
1721                        },
1722                        timeout_ms,
1723                    ),
1724                )
1725                .await?;
1726
1727            // 401:单次 force_refresh 重试(防递归)。
1728            if resp.status().as_u16() == 401 && !retried {
1729                drop(resp); // 释放连接(对应 TS resp.body?.cancel())。
1730                self.force_refresh(signal.cloned())
1731                    .await
1732                    .map_err(|e| Error::other(format!("unauthorized and refresh failed: {e}")))?;
1733                retried = true;
1734                continue;
1735            }
1736
1737            options.response(resp.headers());
1738            if !resp.status().is_success() {
1739                let status = resp.status().as_u16();
1740                let retry_after = parse_retry_after_secs(resp.headers());
1741                let text = read_limited_text(resp.bytes_stream(), MAX_ERROR_BODY_SIZE).await?;
1742                return Err(Error::Http(parse_http_error_with_retry_after(
1743                    status,
1744                    &text,
1745                    retry_after,
1746                )));
1747            }
1748
1749            let headers = resp.headers().clone();
1750            let bytes = resp
1751                .bytes()
1752                .await
1753                .map_err(|e| Error::other(format!("{method} {path}: read body: {e}")))?;
1754            return Ok((bytes.to_vec(), headers));
1755        }
1756    }
1757
1758    /// POST/GET JSON + ApiResponse 解包(业务码检查)+ **空体契约**(方案 §4.4)。对应 TS `doJSONFull<T>`。
1759    ///
1760    /// 空 body:返回 `Ok((None, headers))`(调用方据返回类型决定是否容忍);
1761    /// 非空 body:反序列化 `T`,若 `T` 含 `code` 字段且 `code != 0` 抛 BusinessError。
1762    /// 这里返回 `Option<T>`,让调用方对空体显式处理(与 GET-only `do_json_get_full` 的强 Err 互补)。
1763    pub(crate) async fn do_json_full<T: DeserializeOwned>(
1764        &self,
1765        method: http::Method,
1766        path: &str,
1767        body: Option<&str>,
1768        signal: Option<CancellationToken>,
1769    ) -> Result<(Option<T>, http::header::HeaderMap)> {
1770        let (bytes, headers) = self
1771            .do_json_full_raw(method, path, body, signal, DEFAULT_JSON_TIMEOUT_MS, None)
1772            .await?;
1773        if bytes.is_empty() {
1774            // 空 body 成功响应:跳业务码检查,返回 None(对应 TS `undefined as T`)。
1775            return Ok((None, headers));
1776        }
1777        let result: T = serde_json::from_slice(&bytes)
1778            .map_err(|e| Error::other(format!("{path}: decode: {e}")))?;
1779        Ok((Some(result), headers))
1780    }
1781
1782    // ===========================================================================
1783    // Chat
1784    // ===========================================================================
1785
1786    /// 构建完整聊天请求体(v0.5.0 adapter 模式)。对应 TS `buildChatRequest`。
1787    ///
1788    /// `ensure_model_cached` → `get_adapter_for_model` → adapter `build_request_body`。
1789    /// 返回 `(JSON body 字符串, adapter)`。
1790    pub async fn build_chat_request(
1791        &self,
1792        model_id: &str,
1793        req: &ChatRequest,
1794        signal: Option<CancellationToken>,
1795    ) -> Result<(String, Adapter)> {
1796        // P8: apply_request_sanitizers —— 请求前防御(体积 / deny-list / 深度 / ephemeral 剥离)。
1797        // 对齐 TS buildChatRequest 开头调用:未配置零开销 early-return;失败返 Err 放弃本次请求。
1798        // sanitize 在浅拷贝上原地改写 raw_messages(不污染调用方 req);用 Cow 避免无配置时拷贝。
1799        #[cfg(feature = "sanitize")]
1800        let sanitized: std::borrow::Cow<'_, ChatRequest> = {
1801            let mut s = req.clone();
1802            self.apply_request_sanitizers(&mut s)?;
1803            std::borrow::Cow::Owned(s)
1804        };
1805        #[cfg(feature = "sanitize")]
1806        let req: &ChatRequest = &sanitized;
1807
1808        let m = self.ensure_model_cached(model_id, signal).await?;
1809        let adapter = get_adapter_for_model(&m);
1810        let caps = self
1811            .cached_capabilities(model_id)
1812            .unwrap_or_else(zero_model_capabilities);
1813        let body_map = adapter.build_request_body(&caps, req);
1814        let body = serde_json::to_string(&body_map)
1815            .map_err(|e| Error::other(format!("serialize chat request: {e}")))?;
1816        Ok((body, adapter))
1817    }
1818
1819    /// 同步聊天(适合短回复)。对应 TS `chat`。
1820    ///
1821    /// 响应的 `token_remaining` / `call_remaining` / `model_token_remaining*` 来自服务端响应头
1822    /// (反映结算后余额);缺失保持 [`ChatResponse`] 默认哨兵。v0.5.0 按 provider 路由
1823    /// `/anthropic` 或 `/chat`。
1824    ///
1825    /// # Examples
1826    ///
1827    /// ```no_run
1828    /// # use acosmi::Client;
1829    /// # use acosmi::models::{ChatRequest, ChatMessage};
1830    /// # async fn demo(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
1831    /// let req = ChatRequest {
1832    ///     messages: Some(vec![ChatMessage { role: "user".into(), content: "Hi".into() }]),
1833    ///     max_tokens: Some(256),
1834    ///     ..Default::default()
1835    /// };
1836    /// let resp = client.chat("claude-opus-4-7", &req, None).await?;
1837    /// println!("{:?}", resp.content);
1838    /// # Ok(()) }
1839    /// ```
1840    pub async fn chat(
1841        &self,
1842        model_id: &str,
1843        req: &ChatRequest,
1844        signal: Option<CancellationToken>,
1845    ) -> Result<ChatResponse> {
1846        self.chat_with_options(model_id, req, signal, ChatOptions::default())
1847            .await
1848    }
1849
1850    /// Chat with optional billing response observation.
1851    pub async fn chat_with_options(
1852        &self,
1853        model_id: &str,
1854        req: &ChatRequest,
1855        signal: Option<CancellationToken>,
1856        options: ChatOptions,
1857    ) -> Result<ChatResponse> {
1858        // 浅拷贝 + 强制 stream=false(避免原地 mutate 调用方 req)。
1859        let mut r = req.clone();
1860        r.stream = Some(false);
1861
1862        let (body, adapter) = self
1863            .build_chat_request(model_id, &r, signal.clone())
1864            .await?;
1865        let endpoint = format!(
1866            "/managed-models/{}{}",
1867            urlencode(model_id),
1868            adapter.endpoint_suffix()
1869        );
1870        let (bytes, headers) = self
1871            .do_json_full_raw(
1872                http::Method::POST,
1873                &endpoint,
1874                Some(&body),
1875                signal,
1876                CHAT_REQUEST_TIMEOUT_MS,
1877                Some(options),
1878            )
1879            .await?;
1880
1881        let mut resp = adapter.parse_response(&bytes)?;
1882
1883        // 从响应头提取 token / call 余额(解析失败保持默认哨兵)。
1884        if let Some(v) = header_i64(&headers, "X-Token-Remaining") {
1885            resp.token_remaining = v;
1886        }
1887        if let Some(v) = header_i64(&headers, "X-Call-Remaining") {
1888            resp.call_remaining = v;
1889        }
1890        if let Some(v) = header_i64(&headers, "X-Token-Remaining-Model") {
1891            resp.model_token_remaining = v;
1892        }
1893        if let Some(v) = header_i64(&headers, "X-Token-Remaining-Model-ETU") {
1894            resp.model_token_remaining_etu = v;
1895        }
1896        Ok(resp)
1897    }
1898
1899    // ===========================================================================
1900    // 向量 / 重排序(v2.9.0)—— 与 chat 同网关、同会员计费(Hold→Settle→Release)
1901    // ===========================================================================
1902
1903    /// 向量(同步)。`POST /managed-models/:id/embeddings`。对应 TS `embeddings`。
1904    ///
1905    /// `model_id` 须为向量托管模型(`capabilities.supports_embedding=true`,上游接 DashScope)。
1906    /// 响应为 OpenAI `/v1/embeddings` 标准格式(网关直通,无 `{code,data}` 包装)。
1907    pub async fn embeddings(
1908        &self,
1909        model_id: &str,
1910        req: &EmbeddingRequest,
1911        signal: Option<CancellationToken>,
1912    ) -> Result<EmbeddingResponse> {
1913        let endpoint = format!("/managed-models/{}/embeddings", urlencode(model_id));
1914        let body = serde_json::to_string(req)
1915            .map_err(|e| Error::other(format!("serialize embedding request: {e}")))?;
1916        let (bytes, _) = self
1917            .do_json_full_raw(
1918                http::Method::POST,
1919                &endpoint,
1920                Some(&body),
1921                signal,
1922                CHAT_REQUEST_TIMEOUT_MS,
1923                None,
1924            )
1925            .await?;
1926        serde_json::from_slice(&bytes).map_err(|e| Error::other(format!("{endpoint}: decode: {e}")))
1927    }
1928
1929    /// 重排序(同步)。`POST /managed-models/:id/rerank`。对应 TS `rerank`。
1930    ///
1931    /// `model_id` 须为重排序托管模型(`capabilities.supports_rerank=true`,上游接 DashScope)。
1932    /// 统一扁平契约;响应 `{ results: [{ index, relevance_score, document? }], usage, model }`
1933    /// (网关已把上游原生嵌套 / OpenAI 兼容扁平两线路归一化,无 `{code,data}` 包装)。
1934    pub async fn rerank(
1935        &self,
1936        model_id: &str,
1937        req: &RerankRequest,
1938        signal: Option<CancellationToken>,
1939    ) -> Result<RerankResponse> {
1940        let endpoint = format!("/managed-models/{}/rerank", urlencode(model_id));
1941        let body = serde_json::to_string(req)
1942            .map_err(|e| Error::other(format!("serialize rerank request: {e}")))?;
1943        let (bytes, _) = self
1944            .do_json_full_raw(
1945                http::Method::POST,
1946                &endpoint,
1947                Some(&body),
1948                signal,
1949                CHAT_REQUEST_TIMEOUT_MS,
1950                None,
1951            )
1952            .await?;
1953        serde_json::from_slice(&bytes).map_err(|e| Error::other(format!("{endpoint}: decode: {e}")))
1954    }
1955
1956    // ===========================================================================
1957    // 媒体生成(v1.3+)—— 图片 / 视频生成托管模型(与 chat 同网关)
1958    // ===========================================================================
1959
1960    /// 解析 nexus-v4 `{code,message,data}` 信封,`code!=0` 抛 BusinessError,返回 `data`。
1961    /// 对应 TS `unwrapAPIResponse`。
1962    fn unwrap_api_response<T: DeserializeOwned>(path: &str, bytes: &[u8]) -> Result<T> {
1963        let env: ApiResponse<T> = serde_json::from_slice(bytes)
1964            .map_err(|e| Error::other(format!("{path}: decode: {e}")))?;
1965        if let Some(err) = env.business_error() {
1966            return Err(err);
1967        }
1968        Ok(env.data)
1969    }
1970
1971    /// 图片生成(同步)。`POST /managed-models/:id/images/generations`。对应 TS `generateImage`。
1972    ///
1973    /// `model_id` 须为图片生成托管模型(`capabilities.supports_image_generation=true`)。
1974    /// 图片生成耗时常超 30s,用 chat 同级超时(11min)容纳上游。
1975    pub async fn generate_image(
1976        &self,
1977        model_id: &str,
1978        req: &ImageGenerationRequest,
1979        signal: Option<CancellationToken>,
1980    ) -> Result<ImageGenerationResponse> {
1981        let endpoint = format!("/managed-models/{}/images/generations", urlencode(model_id));
1982        let body = serde_json::to_string(req)
1983            .map_err(|e| Error::other(format!("serialize image request: {e}")))?;
1984        let (bytes, _) = self
1985            .do_json_full_raw(
1986                http::Method::POST,
1987                &endpoint,
1988                Some(&body),
1989                signal,
1990                CHAT_REQUEST_TIMEOUT_MS,
1991                None,
1992            )
1993            .await?;
1994        Self::unwrap_api_response(&endpoint, &bytes)
1995    }
1996
1997    /// 创建视频生成任务(异步)。`POST /managed-models/:id/videos/generations`。对应 TS `generateVideo`。
1998    ///
1999    /// 返回 `task_id`;用 [`Self::poll_video_task`] 轮询直到 `status=completed`。
2000    /// 上报真物理量(视频秒数)需在 `poll_video_task` 时回传 `duration`。
2001    ///
2002    /// 预算用 [`CHAT_REQUEST_TIMEOUT_MS`] 而非控制面默认值:这是生成端点,上游排队 +
2003    /// 提交返回 `task_id` 本身就可能超过 30s。2026-08-06 前这里传的是
2004    /// `DEFAULT_JSON_TIMEOUT_MS`,与同文件 `chat` / `embeddings` / `rerank` /
2005    /// `generate_image` / `chat_messages` 五个兄弟不一致;同一处错误在 TS 与 Go 两个
2006    /// 兄弟 SDK 上**同时**存在,故本文件底部加了结构闸门。
2007    pub async fn generate_video(
2008        &self,
2009        model_id: &str,
2010        req: &VideoGenerationRequest,
2011        signal: Option<CancellationToken>,
2012    ) -> Result<VideoTaskResponse> {
2013        let endpoint = format!("/managed-models/{}/videos/generations", urlencode(model_id));
2014        let body = serde_json::to_string(req)
2015            .map_err(|e| Error::other(format!("serialize video request: {e}")))?;
2016        let (bytes, _) = self
2017            .do_json_full_raw(
2018                http::Method::POST,
2019                &endpoint,
2020                Some(&body),
2021                signal,
2022                CHAT_REQUEST_TIMEOUT_MS,
2023                None,
2024            )
2025            .await?;
2026        Self::unwrap_api_response(&endpoint, &bytes)
2027    }
2028
2029    /// 轮询视频任务状态。`GET /managed-models/:id/videos/tasks/:taskId`。对应 TS `pollVideoTask`。
2030    ///
2031    /// `duration_seconds`(创建时的时长,秒)透传给网关在 completed 时上报用量。
2032    pub async fn poll_video_task(
2033        &self,
2034        model_id: &str,
2035        task_id: &str,
2036        duration_seconds: Option<i64>,
2037        signal: Option<CancellationToken>,
2038    ) -> Result<VideoTaskResponse> {
2039        let mut endpoint = format!(
2040            "/managed-models/{}/videos/tasks/{}",
2041            urlencode(model_id),
2042            urlencode(task_id)
2043        );
2044        if let Some(d) = duration_seconds.filter(|&d| d > 0) {
2045            endpoint.push_str(&format!("?duration={d}"));
2046        }
2047        let (bytes, _) = self
2048            .do_json_full_raw(
2049                http::Method::GET,
2050                &endpoint,
2051                None,
2052                signal,
2053                DEFAULT_JSON_TIMEOUT_MS,
2054                None,
2055            )
2056            .await?;
2057        Self::unwrap_api_response(&endpoint, &bytes)
2058    }
2059
2060    // ===========================================================================
2061    // Anthropic 原生格式同步聊天(chat_messages*)
2062    // ===========================================================================
2063
2064    /// Anthropic 原生格式同步聊天。对应 TS `chatMessages`。
2065    ///
2066    /// v0.5.0 按 provider 路由:Anthropic → `chat_messages_anthropic`(POST /anthropic);
2067    /// 其他厂商 → `chat_messages_openai`(POST /chat,响应转换为 [`AnthropicResponse`])。
2068    pub async fn chat_messages(
2069        &self,
2070        model_id: &str,
2071        req: &ChatRequest,
2072        signal: Option<CancellationToken>,
2073    ) -> Result<AnthropicResponse> {
2074        self.chat_messages_with_options(model_id, req, signal, ChatOptions::default())
2075            .await
2076    }
2077
2078    /// Chat with optional billing response observation.
2079    pub async fn chat_messages_with_options(
2080        &self,
2081        model_id: &str,
2082        req: &ChatRequest,
2083        signal: Option<CancellationToken>,
2084        options: ChatOptions,
2085    ) -> Result<AnthropicResponse> {
2086        let m = self.ensure_model_cached(model_id, signal.clone()).await?;
2087        let adapter = get_adapter_for_model(&m);
2088        if adapter.format() == ProviderFormat::Anthropic {
2089            self.chat_messages_anthropic(model_id, req, adapter, signal, options)
2090                .await
2091        } else {
2092            self.chat_messages_openai(model_id, req, adapter, signal, options)
2093                .await
2094        }
2095    }
2096
2097    async fn chat_messages_anthropic(
2098        &self,
2099        model_id: &str,
2100        req: &ChatRequest,
2101        adapter: Adapter,
2102        signal: Option<CancellationToken>,
2103        options: ChatOptions,
2104    ) -> Result<AnthropicResponse> {
2105        let mut r = req.clone();
2106        r.stream = Some(false);
2107        let caps = self
2108            .cached_capabilities(model_id)
2109            .unwrap_or_else(zero_model_capabilities);
2110        let body_map = adapter.build_request_body(&caps, &r);
2111        let data = serde_json::to_string(&body_map)
2112            .map_err(|e| Error::other(format!("serialize messages request: {e}")))?;
2113
2114        let endpoint = format!("/managed-models/{}/anthropic", urlencode(model_id));
2115        let (bytes, _) = self
2116            .do_json_full_raw(
2117                http::Method::POST,
2118                &endpoint,
2119                Some(&data),
2120                signal,
2121                CHAT_REQUEST_TIMEOUT_MS,
2122                Some(options),
2123            )
2124            .await?;
2125
2126        // 尝试 APIResponse 包装 {"code":0,"message":"...","data":{...}};data 缺失则 fall through
2127        // 直接当 AnthropicResponse 解(对齐 TS chatMessagesAnthropic 的 lenient 逻辑)。
2128        if let Ok(wrapper) = serde_json::from_slice::<serde_json::Value>(&bytes) {
2129            if let Some(data_val) = wrapper.get("data").filter(|v| !v.is_null()) {
2130                let code = wrapper.get("code").and_then(|v| v.as_i64()).unwrap_or(0);
2131                if code != 0 {
2132                    let msg = wrapper
2133                        .get("message")
2134                        .and_then(|v| v.as_str())
2135                        .unwrap_or_default();
2136                    return Err(Error::business(code, msg));
2137                }
2138                return serde_json::from_value(data_val.clone()).map_err(|e| {
2139                    Error::other(format!("decode anthropic response (wrapped): {e}"))
2140                });
2141            }
2142        }
2143        serde_json::from_slice(&bytes)
2144            .map_err(|e| Error::other(format!("decode anthropic response: {e}")))
2145    }
2146
2147    async fn chat_messages_openai(
2148        &self,
2149        model_id: &str,
2150        req: &ChatRequest,
2151        adapter: Adapter,
2152        signal: Option<CancellationToken>,
2153        options: ChatOptions,
2154    ) -> Result<AnthropicResponse> {
2155        let mut r = req.clone();
2156        r.stream = Some(false);
2157        let caps = self
2158            .cached_capabilities(model_id)
2159            .unwrap_or_else(zero_model_capabilities);
2160        let body_map = adapter.build_request_body(&caps, &r);
2161        let data = serde_json::to_string(&body_map)
2162            .map_err(|e| Error::other(format!("serialize messages request: {e}")))?;
2163
2164        let endpoint = format!(
2165            "/managed-models/{}{}",
2166            urlencode(model_id),
2167            adapter.endpoint_suffix()
2168        );
2169        let (bytes, _) = self
2170            .do_json_full_raw(
2171                http::Method::POST,
2172                &endpoint,
2173                Some(&data),
2174                signal,
2175                CHAT_REQUEST_TIMEOUT_MS,
2176                Some(options),
2177            )
2178            .await?;
2179        // OpenAI 格式响应 → AnthropicResponse 转换(对齐 TS)。
2180        parse_openai_response_to_anthropic(&bytes)
2181    }
2182
2183    // ===========================================================================
2184    // 流式聊天(SSE)—— 计费安全红线:只 do_request,绝不重试
2185    // ===========================================================================
2186
2187    /// 流式聊天(SSE),返回 `impl Stream<Item = Result<StreamEvent>>`。对应 TS `chatStream`。
2188    ///
2189    /// **🔴 计费安全红线**:流式路径**只走单次 `do_request`(内部),绝不经 retry 包装**——
2190    /// SSE 一旦部分写出,重试 = 双 token + 重复消息 = 双扣。401 仅做一次 force_refresh 重试
2191    /// (`retried` guard 防递归)。`signal` 经 `select!` 接入 SSE 读循环。
2192    pub fn chat_stream(
2193        &self,
2194        model_id: &str,
2195        req: &ChatRequest,
2196        signal: Option<CancellationToken>,
2197    ) -> impl Stream<Item = Result<StreamEvent>> {
2198        self.chat_stream_with_options(model_id, req, signal, ChatOptions::default())
2199    }
2200
2201    /// The corresponding stream with optional activity and billing ID observers.
2202    pub fn chat_stream_with_options(
2203        &self,
2204        model_id: &str,
2205        req: &ChatRequest,
2206        signal: Option<CancellationToken>,
2207        options: ChatOptions,
2208    ) -> impl Stream<Item = Result<StreamEvent>> {
2209        let this = self.clone();
2210        let model_id = model_id.to_string();
2211        let req = req.clone();
2212        async_stream::try_stream! {
2213            let inner = this.chat_stream_gen(&model_id, &req, signal, false, options);
2214            futures::pin_mut!(inner);
2215            while let Some(ev) = inner.next().await {
2216                yield ev?;
2217            }
2218        }
2219    }
2220
2221    /// 流式聊天 + 自动解析结算 / 搜索来源事件。对应 TS `chatStreamWithUsage`。
2222    ///
2223    /// tagged 流:`Settle`(结算)/ `Sources`(搜索来源)/ `Content`(内容增量)。
2224    /// `started` 控制事件被过滤;`failed`/`error` 事件经 [`parse_stream_error`] 转 [`Error::Stream`]。
2225    pub fn chat_stream_with_usage(
2226        &self,
2227        model_id: &str,
2228        req: &ChatRequest,
2229        signal: Option<CancellationToken>,
2230    ) -> impl Stream<Item = Result<ChatUsageEvent>> {
2231        self.chat_stream_with_usage_with_options(model_id, req, signal, ChatOptions::default())
2232    }
2233
2234    /// The corresponding stream with optional activity and billing ID observers.
2235    pub fn chat_stream_with_usage_with_options(
2236        &self,
2237        model_id: &str,
2238        req: &ChatRequest,
2239        signal: Option<CancellationToken>,
2240        options: ChatOptions,
2241    ) -> impl Stream<Item = Result<ChatUsageEvent>> {
2242        let this = self.clone();
2243        let model_id = model_id.to_string();
2244        let req = req.clone();
2245        async_stream::try_stream! {
2246            let inner = this.chat_stream_with_options(&model_id, &req, signal, options);
2247            futures::pin_mut!(inner);
2248            while let Some(ev) = inner.next().await {
2249                let ev = ev?;
2250                // 结算事件(settled / pending_settle)。
2251                if let Some(s) = parse_settlement(&ev) {
2252                    yield ChatUsageEvent::Settle(s);
2253                    continue;
2254                }
2255                // 搜索来源事件。
2256                if let Some(src) = parse_sources_event(&ev) {
2257                    yield ChatUsageEvent::Sources(src);
2258                    continue;
2259                }
2260                // 控制事件:过滤。
2261                if ev.event == "started" {
2262                    continue;
2263                }
2264                // 失败 / 错误事件:解析后抛出。
2265                if ev.event == "failed" || ev.event == "error" {
2266                    Err(Error::Stream(parse_stream_error(&ev.data)))?;
2267                }
2268                yield ChatUsageEvent::Content(ev);
2269            }
2270        }
2271    }
2272
2273    /// Anthropic 原生格式流式聊天(SSE)。对应 TS `chatMessagesStream`。
2274    ///
2275    /// 调用 POST `/managed-models/:id/anthropic`(Anthropic 路由)或 `/chat`(OpenAI 路由,
2276    /// 经 `OpenAIStreamConverter` 转 Anthropic 兼容事件)。同样**只走 do_request,绝不重试**。
2277    pub fn chat_messages_stream(
2278        &self,
2279        model_id: &str,
2280        req: &ChatRequest,
2281        signal: Option<CancellationToken>,
2282    ) -> impl Stream<Item = Result<StreamEvent>> {
2283        self.chat_messages_stream_with_options(model_id, req, signal, ChatOptions::default())
2284    }
2285
2286    /// The corresponding stream with optional activity and billing ID observers.
2287    pub fn chat_messages_stream_with_options(
2288        &self,
2289        model_id: &str,
2290        req: &ChatRequest,
2291        signal: Option<CancellationToken>,
2292        options: ChatOptions,
2293    ) -> impl Stream<Item = Result<StreamEvent>> {
2294        let this = self.clone();
2295        let model_id = model_id.to_string();
2296        let req = req.clone();
2297        async_stream::try_stream! {
2298            let inner = this.chat_messages_stream_gen(&model_id, &req, signal, false, options);
2299            futures::pin_mut!(inner);
2300            while let Some(ev) = inner.next().await {
2301                yield ev?;
2302            }
2303        }
2304    }
2305
2306    /// chat_stream 的真实实现(含 401 单次重试递归)。返回 `impl Stream`。
2307    ///
2308    /// 🔴 **只调用 [`Self::do_request`](单次,无重试)**。401 且未重试过 → force_refresh →
2309    /// 递归一次(`retried=true`,防再次 401 递归)。
2310    fn chat_stream_gen<'a>(
2311        &'a self,
2312        model_id: &'a str,
2313        req: &'a ChatRequest,
2314        signal: Option<CancellationToken>,
2315        retried: bool,
2316        mut options: ChatOptions,
2317    ) -> std::pin::Pin<Box<dyn Stream<Item = Result<StreamEvent>> + Send + 'a>> {
2318        Box::pin(async_stream::try_stream! {
2319            let mut r = req.clone();
2320            r.stream = Some(true);
2321            let (body, adapter) = self.build_chat_request(model_id, &r, signal.clone()).await?;
2322            let token = zeroize::Zeroizing::new(self.ensure_token(signal.clone()).await?);
2323
2324            let endpoint = format!(
2325                "/managed-models/{}{}",
2326                urlencode(model_id),
2327                adapter.endpoint_suffix()
2328            );
2329            let url = self.api_url(&endpoint);
2330            let headers = stream_headers(&token);
2331
2332            // 🔴 红线:流式只走 do_request(单次),绝不 do_request_with_retry。
2333            let resp = self
2334                .do_request(http::Method::POST, &url, &headers, Some(&body), signal.as_ref(), HttpContext::streaming(HttpPurpose::Model, CHAT_REQUEST_TIMEOUT_MS))
2335                .await?;
2336
2337            // 401 单次重试:force_refresh 后递归一次(retried guard 防递归)。
2338            if resp.status().as_u16() == 401 && !retried {
2339                drop(resp);
2340                self.force_refresh(signal.clone()).await.map_err(|e| {
2341                    Error::other(format!("stream: unauthorized and refresh failed: {e}"))
2342                })?;
2343                let inner = self.chat_stream_gen(model_id, req, signal, true, options);
2344                futures::pin_mut!(inner);
2345                while let Some(ev) = inner.next().await {
2346                    yield ev?;
2347                }
2348                return;
2349            }
2350
2351            options.response(resp.headers());
2352
2353            if !resp.status().is_success() {
2354                let status = resp.status().as_u16();
2355                let retry_after = parse_retry_after_secs(resp.headers());
2356                let text = read_limited_text(resp.bytes_stream(), MAX_ERROR_BODY_SIZE).await?;
2357                Err(Error::Http(parse_http_error_with_retry_after(status, &text, retry_after)))?;
2358                return;
2359            }
2360
2361            // Anthropic 路由:维护 block 元数据 map;OpenAI 路由:parse_stream_line 自处理。
2362            let mut block_type_map: Option<HashMap<i64, BlockMeta>> =
2363                if adapter.format() == ProviderFormat::Anthropic {
2364                    Some(HashMap::new())
2365                } else {
2366                    None
2367                };
2368
2369            let lines = iter_sse_lines(resp.bytes_stream());
2370            futures::pin_mut!(lines);
2371            let mut current_event = String::new();
2372            loop {
2373                // 取消信号接入 SSE 读循环。cancel 触发 → 注入 abort 错误项。
2374                let next: Option<Result<String>> = match &signal {
2375                    Some(cancel) => tokio::select! {
2376                        biased;
2377                        _ = cancel.cancelled() => Some(Err(Error::other("stream: aborted"))),
2378                        l = lines.next() => l,
2379                    },
2380                    None => lines.next().await,
2381                };
2382                let line = match next {
2383                    Some(l) => l?,
2384                    None => break,
2385                };
2386                // 跳过 SSE 注释行(": keep-alive")与空行。
2387                options.activity();
2388                if is_sse_comment_line(&line) || line.is_empty() {
2389                    continue;
2390                }
2391                if let Some(rest) = line.strip_prefix("event:") {
2392                    current_event = rest.trim().to_string();
2393                } else if let Some(rest) = line.strip_prefix("data:") {
2394                    let data = rest.trim();
2395                    let (mut ev, done) = adapter.parse_stream_line(&current_event, data)?;
2396                    if done {
2397                        return;
2398                    }
2399                    if let Some(map) = block_type_map.as_mut() {
2400                        let (idx, bt, eph) =
2401                            extract_anthropic_block_meta(&current_event, data, map);
2402                        if !bt.is_empty() {
2403                            ev.block_index = Some(idx);
2404                            ev.block_type = Some(bt);
2405                            ev.ephemeral = Some(eph);
2406                        }
2407                    }
2408                    yield ev;
2409                }
2410            }
2411        })
2412    }
2413
2414    /// chat_messages_stream 的真实实现(含 401 单次重试递归)。
2415    ///
2416    /// 🔴 同 [`Self::chat_stream_gen`]:只走 do_request,绝不重试。OpenAI 路由经
2417    /// `OpenAIStreamConverter` 转 Anthropic 兼容事件;Anthropic 路由原生事件直透 + block 元数据回填。
2418    fn chat_messages_stream_gen<'a>(
2419        &'a self,
2420        model_id: &'a str,
2421        req: &'a ChatRequest,
2422        signal: Option<CancellationToken>,
2423        retried: bool,
2424        mut options: ChatOptions,
2425    ) -> std::pin::Pin<Box<dyn Stream<Item = Result<StreamEvent>> + Send + 'a>> {
2426        Box::pin(async_stream::try_stream! {
2427            let mut r = req.clone();
2428            r.stream = Some(true);
2429            let (body, adapter) = self.build_chat_request(model_id, &r, signal.clone()).await?;
2430            let token = zeroize::Zeroizing::new(self.ensure_token(signal.clone()).await?);
2431
2432            let endpoint = format!(
2433                "/managed-models/{}{}",
2434                urlencode(model_id),
2435                adapter.endpoint_suffix()
2436            );
2437            let url = self.api_url(&endpoint);
2438            let headers = stream_headers(&token);
2439
2440            // 🔴 红线:流式只走 do_request(单次),绝不重试。
2441            let resp = self
2442                .do_request(http::Method::POST, &url, &headers, Some(&body), signal.as_ref(), HttpContext::streaming(HttpPurpose::Model, CHAT_REQUEST_TIMEOUT_MS))
2443                .await?;
2444
2445            if resp.status().as_u16() == 401 && !retried {
2446                drop(resp);
2447                self.force_refresh(signal.clone()).await.map_err(|e| {
2448                    Error::other(format!("messages stream: unauthorized and refresh failed: {e}"))
2449                })?;
2450                let inner = self.chat_messages_stream_gen(model_id, req, signal, true, options);
2451                futures::pin_mut!(inner);
2452                while let Some(ev) = inner.next().await {
2453                    yield ev?;
2454                }
2455                return;
2456            }
2457
2458            options.response(resp.headers());
2459
2460            if !resp.status().is_success() {
2461                let status = resp.status().as_u16();
2462                let retry_after = parse_retry_after_secs(resp.headers());
2463                let text = read_limited_text(resp.bytes_stream(), MAX_ERROR_BODY_SIZE).await?;
2464                Err(Error::Http(parse_http_error_with_retry_after(status, &text, retry_after)))?;
2465                return;
2466            }
2467
2468            let is_openai = adapter.format() == ProviderFormat::OpenAI;
2469            let mut converter = if is_openai {
2470                Some(crate::models::new_openai_stream_converter())
2471            } else {
2472                None
2473            };
2474            let mut block_type_map: HashMap<i64, BlockMeta> = HashMap::new();
2475
2476            let lines = iter_sse_lines(resp.bytes_stream());
2477            futures::pin_mut!(lines);
2478            let mut current_event = String::new();
2479            loop {
2480                let next: Option<Result<String>> = match &signal {
2481                    Some(cancel) => tokio::select! {
2482                        biased;
2483                        _ = cancel.cancelled() => Some(Err(Error::other("messages stream: aborted"))),
2484                        l = lines.next() => l,
2485                    },
2486                    None => lines.next().await,
2487                };
2488                let line = match next {
2489                    Some(l) => l?,
2490                    None => break,
2491                };
2492                options.activity();
2493                if is_sse_comment_line(&line) || line.is_empty() {
2494                    continue;
2495                }
2496                if let Some(rest) = line.strip_prefix("event:") {
2497                    current_event = rest.trim().to_string();
2498                } else if let Some(rest) = line.strip_prefix("data:") {
2499                    let data = rest.trim();
2500                    if let Some(conv) = converter.as_mut() {
2501                        // 网关的结构化失败帧带 `event: failed` 发出,帧上没有 choices。判据与同文件
2502                        // `chat_stream_with_usage_with_options` 同源(经 `parse_stream_error` 转
2503                        // `Error::Stream`),对应 TS `chatMessagesStreamGen` OpenAI 分支的事件名判断。
2504                        // 转换器对没有 choices 的帧返回零事件;不在这里分流,失败帧会被静默吞掉,
2505                        // 读循环随后在 EOF 调 `flush`,finish_reason 之后的失败还会以一个看似正常的
2506                        // message_stop 收场。
2507                        if current_event == "failed" || current_event == "error" {
2508                            Err(Error::Stream(parse_stream_error(data)))?;
2509                        }
2510                        // OpenAI SSE → Anthropic 兼容事件。
2511                        let (events, done) = conv.convert(data)?;
2512                        for ev in events {
2513                            yield ev;
2514                        }
2515                        if done {
2516                            return;
2517                        }
2518                    } else {
2519                        // Anthropic SSE:原生事件直透 + content block 元数据回填。
2520                        let mut ev = StreamEvent {
2521                            event: current_event.clone(),
2522                            data: data.to_string(),
2523                            ..Default::default()
2524                        };
2525                        let (idx, bt, eph) =
2526                            extract_anthropic_block_meta(&current_event, data, &mut block_type_map);
2527                        if !bt.is_empty() {
2528                            ev.block_index = Some(idx);
2529                            ev.block_type = Some(bt);
2530                            ev.ephemeral = Some(eph);
2531                        }
2532                        yield ev;
2533                    }
2534                }
2535            }
2536            // 走到这里 = 流在没有 `[DONE]` 的情况下正常结束(EOF)。finish_reason 帧之后,转换器可能
2537            // 还压着一次为等待 usage 尾帧而推迟的 message_delta + message_stop,不在这里补发,下游就
2538            // 永远收不到 message_stop;从未收到 finish_reason 的截断流,flush 不产出任何事件。读取出错
2539            // 与取消经上面的 `?` 提前结束,不会到达这里。对应 TS `chatMessagesStreamGen` 读循环结束处
2540            // 的 `converter.flush()`。
2541            if let Some(conv) = converter.as_mut() {
2542                for ev in conv.flush() {
2543                    yield ev;
2544                }
2545            }
2546        })
2547    }
2548
2549    /// 派生 per-request 超时子 token:超时或 parent 取消任一触发即 abort。对应 TS `withRequestTimeout`。
2550    /// 流式 / 下载路径不应套此短超时(会切断长连接),故仅在非流式 JSON 路径使用。
2551    pub(crate) fn derive_timeout_token(
2552        &self,
2553        timeout_ms: u64,
2554        parent: Option<CancellationToken>,
2555    ) -> Option<CancellationToken> {
2556        if timeout_ms == 0 {
2557            return parent;
2558        }
2559        let child = CancellationToken::new();
2560        let trigger = child.clone();
2561        let parent_clone = parent.clone();
2562        tokio::spawn(async move {
2563            let timeout = tokio::time::sleep(std::time::Duration::from_millis(timeout_ms));
2564            match parent_clone {
2565                Some(p) => {
2566                    tokio::select! {
2567                        _ = timeout => trigger.cancel(),
2568                        _ = p.cancelled() => trigger.cancel(),
2569                    }
2570                }
2571                None => {
2572                    timeout.await;
2573                    trigger.cancel();
2574                }
2575            }
2576        });
2577        Some(child)
2578    }
2579
2580    // ── 测试辅助(仅 cfg(test))──
2581
2582    /// 直接注入未过期 token(测试用,绕过 OAuth 登录流)。对应 TS `primeTokensForTest`。
2583    #[cfg(all(test, feature = "native-http"))]
2584    fn prime_tokens_for_test(&self, tokens: TokenSet) {
2585        *self.inner.tokens.write().unwrap() = Some(zeroize::Zeroizing::new(tokens));
2586    }
2587
2588    /// 直接注入 OAuth server 元数据(测试用,绕过 discover)。
2589    #[cfg(all(test, feature = "native-http"))]
2590    fn prime_meta_for_test(&self, meta: ServerMetadata) {
2591        *self.inner.meta.write().unwrap() = Some(meta);
2592    }
2593
2594    /// 把占位 ManagedModel 塞入缓存(测试用)。对应 TS `primeModelCacheForTest`。
2595    #[cfg(all(test, feature = "native-http"))]
2596    fn prime_model_cache_for_test(&self, models: Vec<ManagedModel>) {
2597        *self.inner.model_cache.write().unwrap() = models;
2598        *self.inner.model_cache_time.write().unwrap() = Some(std::time::Instant::now());
2599    }
2600}
2601
2602/// `chat_stream_with_usage` 的 tagged 事件。对应 TS `{kind:'content'|'sources'|'settle'}`。
2603#[derive(Debug, Clone)]
2604pub enum ChatUsageEvent {
2605    /// 内容增量事件。
2606    Content(StreamEvent),
2607    /// 搜索来源事件。
2608    Sources(SourcesEvent),
2609    /// 结算事件(token 消耗 + 剩余余额)。
2610    Settle(StreamSettlement),
2611}
2612
2613/// 流式请求公共头(Bearer + JSON + SSE Accept)。
2614fn stream_headers(token: &str) -> Vec<(http::header::HeaderName, String)> {
2615    vec![
2616        (http::header::AUTHORIZATION, format!("Bearer {token}")),
2617        (http::header::CONTENT_TYPE, "application/json".to_string()),
2618        (http::header::ACCEPT, "text/event-stream".to_string()),
2619    ]
2620}
2621
2622/// 从响应头解析 `Retry-After` 秒数(0 = 无 / 解析失败)。
2623fn parse_retry_after_secs(headers: &http::header::HeaderMap) -> i64 {
2624    headers
2625        .get(http::header::RETRY_AFTER)
2626        .and_then(|v| v.to_str().ok())
2627        .and_then(|s| s.trim().parse::<i64>().ok())
2628        .filter(|&s| s > 0)
2629        .unwrap_or(0)
2630}
2631
2632/// 从响应头解析 i64(解析失败 → None)。对应 TS `parseInt(headers.get(...))`。
2633fn header_i64(headers: &http::header::HeaderMap, name: &str) -> Option<i64> {
2634    headers
2635        .get(name)
2636        .and_then(|v| v.to_str().ok())
2637        .and_then(|s| s.trim().parse::<i64>().ok())
2638}
2639
2640/// 退避 sleep,可被取消信号打断(取消即立即返回,不再退避)。对应 TS `sleep(ms, signal)`。
2641async fn sleep_with_cancel(ms: u64, signal: Option<&CancellationToken>) {
2642    let dur = std::time::Duration::from_millis(ms);
2643    match signal {
2644        Some(cancel) => {
2645            tokio::select! {
2646                _ = tokio::time::sleep(dur) => {}
2647                _ = cancel.cancelled() => {}
2648            }
2649        }
2650        None => tokio::time::sleep(dur).await,
2651    }
2652}
2653
2654/// URL path 段编码(对齐 TS `encodeURIComponent`)。仅对 path-segment 不安全字符百分号编码。
2655fn urlencode(s: &str) -> String {
2656    let mut out = String::with_capacity(s.len());
2657    for b in s.bytes() {
2658        match b {
2659            b'A'..=b'Z'
2660            | b'a'..=b'z'
2661            | b'0'..=b'9'
2662            | b'-'
2663            | b'_'
2664            | b'.'
2665            | b'!'
2666            | b'~'
2667            | b'*'
2668            | b'\''
2669            | b'('
2670            | b')' => out.push(b as char),
2671            _ => out.push_str(&format!("%{b:02X}")),
2672        }
2673    }
2674    out
2675}
2676
2677/// 归一化上游 ManagedModel 列表的 `input_modalities`(snake)→ `inputModalities`(camel)。
2678/// 对应 TS `normalizeInputModalities`:camelCase 已存在则保留;仅 snake 存在时拷贝并滤白名单;
2679/// 都没有则保 `None`("未声明" ≠ text-only)。
2680fn normalize_input_modalities(mut models: Vec<ManagedModel>) -> Vec<ManagedModel> {
2681    for m in models.iter_mut() {
2682        if m.input_modalities.is_some() {
2683            // camelCase 已存在 —— 清掉 snake 镜像字段,避免重复持有。
2684            m.input_modalities_snake = None;
2685            continue;
2686        }
2687        if let Some(snake) = m.input_modalities_snake.take() {
2688            let filtered: Vec<InputModality> = snake
2689                .into_iter()
2690                .filter_map(|v| match v.as_str() {
2691                    Some("text") => Some(InputModality::Text),
2692                    Some("image") => Some(InputModality::Image),
2693                    _ => None,
2694                })
2695                .collect();
2696            m.input_modalities = Some(filtered);
2697        }
2698    }
2699    models
2700}
2701
2702/// 浏览器 OAuth CORS 错误启发式判定(对应 TS `isLikelyBrowserOAuthCORSError`)。
2703fn is_likely_browser_oauth_cors_error(message: &str) -> bool {
2704    let lower = message.to_lowercase();
2705    lower.contains("failed to fetch")
2706        || lower.contains("networkerror")
2707        || lower.contains("cors")
2708        || lower.contains("http 403")
2709}
2710
2711fn default_store() -> Arc<dyn TokenStore> {
2712    // 原生:优先 File;HOME 不可用时退 InMemory。
2713    if std::env::var_os("HOME").is_some() || std::env::var_os("USERPROFILE").is_some() {
2714        Arc::new(FileTokenStore::new(None))
2715    } else {
2716        Arc::new(InMemoryTokenStore::new())
2717    }
2718}
2719
2720// =============================================================================
2721// URL 归一化(对应 TS normalizeGatewayBaseURL / normalizeOverrideBaseURL)
2722// =============================================================================
2723
2724/// 归一化网关 base URL:仅许 http/https;拒空 / 拒 query / 拒 fragment / 拒非法 URL;
2725/// 去尾随 `/`,返回 `scheme://host[:port]/path`。
2726///
2727/// # Examples
2728///
2729/// ```
2730/// use acosmi::core::normalize_gateway_base_url;
2731///
2732/// assert_eq!(
2733///     normalize_gateway_base_url("https://gw.example/api/v4/").unwrap(),
2734///     "https://gw.example/api/v4",
2735/// );
2736/// assert!(normalize_gateway_base_url("wss://session.example").is_err()); // 仅 http/https
2737/// ```
2738pub fn normalize_gateway_base_url(input: &str) -> Result<String> {
2739    normalize_base(input, "serverURL")
2740}
2741
2742/// 同 [`normalize_gateway_base_url`],用于 complianceBaseURL / apiBaseURL override。
2743pub fn normalize_override_base_url(raw: &str, label: &str) -> Result<String> {
2744    normalize_base(raw, label)
2745}
2746
2747fn normalize_base(input: &str, label: &str) -> Result<String> {
2748    let trimmed = input.trim();
2749    if trimmed.is_empty() {
2750        return Err(Error::other(format!("{label}: must not be empty")));
2751    }
2752    let u = Url::parse(trimmed).map_err(|e| Error::other(format!("{label}: invalid URL: {e}")))?;
2753    match u.scheme() {
2754        "http" | "https" => {}
2755        s => {
2756            return Err(Error::other(format!(
2757                "{label}: unsupported scheme \"{s}\" (only http/https allowed)"
2758            )))
2759        }
2760    }
2761    if u.query().is_some() || u.fragment().is_some() {
2762        return Err(Error::other(format!(
2763            "{label}: must not contain query or fragment"
2764        )));
2765    }
2766    let host = u
2767        .host_str()
2768        .ok_or_else(|| Error::other(format!("{label}: missing host")))?;
2769    let mut out = format!("{}://{}", u.scheme(), host);
2770    if let Some(port) = u.port() {
2771        out.push_str(&format!(":{port}"));
2772    }
2773    let path = u.path().trim_end_matches('/');
2774    out.push_str(path);
2775    Ok(out)
2776}
2777
2778#[cfg(all(test, feature = "native-http"))]
2779mod p4_tests {
2780    use super::*;
2781    use crate::auth::types::{ServerMetadata, TokenSet};
2782    use crate::models::types::ManagedModel;
2783    use std::sync::atomic::{AtomicUsize, Ordering as AtomicOrdering};
2784    use std::sync::Arc as StdArc;
2785    use tokio::io::{AsyncReadExt, AsyncWriteExt};
2786    use tokio::net::TcpListener;
2787
2788    // ── 纯函数红线(无需网络)──
2789
2790    #[test]
2791    fn urlencode_matches_encodeuricomponent() {
2792        // 普通段不变。
2793        assert_eq!(urlencode("claude-opus"), "claude-opus");
2794        // 斜杠 / 空格 / 中文须百分号编码(防 path 注入)。
2795        assert_eq!(urlencode("a b/c"), "a%20b%2Fc");
2796        assert_eq!(urlencode("模型"), "%E6%A8%A1%E5%9E%8B");
2797        // encodeURIComponent 保留字符不编码。
2798        assert_eq!(urlencode("a-_.!~*'()"), "a-_.!~*'()");
2799    }
2800
2801    #[test]
2802    fn header_i64_parses_or_none() {
2803        let mut h = http::header::HeaderMap::new();
2804        h.insert("X-Token-Remaining", "12345".parse().unwrap());
2805        h.insert("X-Bad", "nan".parse().unwrap());
2806        assert_eq!(header_i64(&h, "X-Token-Remaining"), Some(12345));
2807        assert_eq!(header_i64(&h, "X-Bad"), None);
2808        assert_eq!(header_i64(&h, "X-Missing"), None);
2809    }
2810
2811    #[test]
2812    fn parse_retry_after_secs_filters_nonpositive() {
2813        let mut h = http::header::HeaderMap::new();
2814        h.insert(http::header::RETRY_AFTER, "30".parse().unwrap());
2815        assert_eq!(parse_retry_after_secs(&h), 30);
2816        h.insert(http::header::RETRY_AFTER, "0".parse().unwrap());
2817        assert_eq!(parse_retry_after_secs(&h), 0);
2818    }
2819
2820    /// 流式行解析:[DONE] → done;普通事件 event/data 透传(Anthropic 自然结束靠连接关闭)。
2821    #[test]
2822    fn anthropic_adapter_parse_stream_line_basic() {
2823        let adapter = Adapter::Anthropic;
2824        // [DONE] → done。
2825        let (_, done) = adapter.parse_stream_line("", "[DONE]").unwrap();
2826        assert!(done);
2827        // 普通 delta → 非 done,event/data 透传。
2828        let (ev, done2) = adapter
2829            .parse_stream_line(
2830                "content_block_delta",
2831                r#"{"index":0,"delta":{"type":"text_delta","text":"hi"}}"#,
2832            )
2833            .unwrap();
2834        assert!(!done2);
2835        assert_eq!(ev.event, "content_block_delta");
2836    }
2837
2838    #[test]
2839    fn endpoint_suffix_routing_per_adapter() {
2840        // Anthropic → /anthropic, OpenAI → /chat(chat 端点拼接红线)。
2841        assert_eq!(Adapter::Anthropic.endpoint_suffix(), "/anthropic");
2842        assert_eq!(Adapter::OpenAI.endpoint_suffix(), "/chat");
2843        let ep = format!(
2844            "/managed-models/{}{}",
2845            urlencode("m id"),
2846            Adapter::OpenAI.endpoint_suffix()
2847        );
2848        assert_eq!(ep, "/managed-models/m%20id/chat");
2849    }
2850
2851    // ── 端到端:原始 HTTP/1.1 mock server ──
2852
2853    struct MockResponse {
2854        status: u16,
2855        headers: Vec<(&'static str, String)>,
2856        body: String,
2857    }
2858    impl MockResponse {
2859        fn ok(body: &str) -> Self {
2860            Self {
2861                status: 200,
2862                headers: vec![],
2863                body: body.to_string(),
2864            }
2865        }
2866        fn with_header(mut self, k: &'static str, v: &str) -> Self {
2867            self.headers.push((k, v.to_string()));
2868            self
2869        }
2870        fn status(status: u16, body: &str) -> Self {
2871            Self {
2872                status,
2873                headers: vec![],
2874                body: body.to_string(),
2875            }
2876        }
2877    }
2878
2879    /// 启一个按到达顺序逐个回放 `responses` 的 mock server,记录收到的 request 行(METHOD PATH)。
2880    /// 返回 (base_url, 记录器句柄, JoinHandle)。
2881    async fn spawn_mock(
2882        responses: Vec<MockResponse>,
2883    ) -> (
2884        String,
2885        StdArc<std::sync::Mutex<Vec<String>>>,
2886        StdArc<AtomicUsize>,
2887    ) {
2888        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
2889        let addr = listener.local_addr().unwrap();
2890        let base = format!("http://{addr}");
2891        let log = StdArc::new(std::sync::Mutex::new(Vec::<String>::new()));
2892        let count = StdArc::new(AtomicUsize::new(0));
2893        let log2 = log.clone();
2894        let count2 = count.clone();
2895        tokio::spawn(async move {
2896            let mut idx = 0usize;
2897            while idx < responses.len() {
2898                let (mut sock, _) = match listener.accept().await {
2899                    Ok(s) => s,
2900                    Err(_) => break,
2901                };
2902                // 读到 header 结束(\r\n\r\n),再按 Content-Length 读 body(够测试)。
2903                let mut buf = vec![0u8; 8192];
2904                let n = sock.read(&mut buf).await.unwrap_or(0);
2905                let req = String::from_utf8_lossy(&buf[..n]).to_string();
2906                let first = req.lines().next().unwrap_or("").to_string();
2907                let parts: Vec<&str> = first.split_whitespace().collect();
2908                if parts.len() >= 2 {
2909                    log2.lock()
2910                        .unwrap()
2911                        .push(format!("{} {}", parts[0], parts[1]));
2912                }
2913                count2.fetch_add(1, AtomicOrdering::SeqCst);
2914
2915                let r = &responses[idx];
2916                idx += 1;
2917                let reason = match r.status {
2918                    200 => "OK",
2919                    401 => "Unauthorized",
2920                    500 => "Internal Server Error",
2921                    _ => "Status",
2922                };
2923                let mut head = format!(
2924                    "HTTP/1.1 {} {}\r\nContent-Length: {}\r\nConnection: close\r\n",
2925                    r.status,
2926                    reason,
2927                    r.body.len()
2928                );
2929                for (k, v) in &r.headers {
2930                    head.push_str(&format!("{k}: {v}\r\n"));
2931                }
2932                head.push_str("\r\n");
2933                let _ = sock.write_all(head.as_bytes()).await;
2934                let _ = sock.write_all(r.body.as_bytes()).await;
2935                let _ = sock.flush().await;
2936                // 优雅关闭写端,确保 Content-Length 字节全部送达后再 EOF(避免 reqwest IncompleteBody)。
2937                let _ = sock.shutdown().await;
2938            }
2939        });
2940        (base, log, count)
2941    }
2942
2943    fn unexpired_token(base: &str) -> TokenSet {
2944        TokenSet {
2945            access_token: "AT0".to_string(),
2946            refresh_token: "RT0".to_string(),
2947            // 远未来。
2948            expires_at: "2999-01-01T00:00:00Z".to_string(),
2949            scope: String::new(),
2950            client_id: "cid".to_string(),
2951            server_url: base.to_string(),
2952        }
2953    }
2954
2955    fn primed_client(base: &str) -> Client {
2956        let client = Client::new(Config {
2957            server_url: Some(base.to_string()),
2958            ..Default::default()
2959        })
2960        .unwrap();
2961        client.prime_tokens_for_test(unexpired_token(base));
2962        // 缓存一个 Anthropic 模型,避免 build_chat_request 触发 listModels。
2963        client.prime_model_cache_for_test(vec![ManagedModel {
2964            id: "test-model".to_string(),
2965            provider: "anthropic".to_string(),
2966            model_id: "test-model".to_string(),
2967            is_enabled: true,
2968            ..Default::default()
2969        }]);
2970        client
2971    }
2972
2973    #[tokio::test]
2974    async fn chat_routes_to_anthropic_endpoint_and_reads_headers() {
2975        // Anthropic 响应体(最小)。
2976        let body = r#"{"id":"msg_1","type":"message","model":"test-model","role":"assistant","content":[],"stop_reason":"end_turn","usage":{"input_tokens":1,"output_tokens":1}}"#;
2977        let resp = MockResponse::ok(body)
2978            .with_header("X-Token-Remaining", "999")
2979            .with_header("X-Call-Remaining", "42");
2980        let (base, log, _) = spawn_mock(vec![resp]).await;
2981        let client = primed_client(&base);
2982
2983        let req = ChatRequest::default();
2984        let out = client.chat("test-model", &req, None).await.unwrap();
2985        // 端点路由红线:POST 到 /api/v4/managed-models/test-model/anthropic。
2986        let recorded = log.lock().unwrap().clone();
2987        assert_eq!(recorded.len(), 1);
2988        assert_eq!(
2989            recorded[0],
2990            "POST /api/v4/managed-models/test-model/anthropic"
2991        );
2992        // 响应头余额回填。
2993        assert_eq!(out.token_remaining, 999);
2994        assert_eq!(out.call_remaining, 42);
2995        assert_eq!(out.id, "msg_1");
2996    }
2997
2998    #[tokio::test]
2999    async fn do_json_full_empty_body_returns_none() {
3000        // 空体成功响应 → Ok(None)(方案 §4.4 空体契约)。
3001        let (base, _, _) = spawn_mock(vec![MockResponse::ok("")]).await;
3002        let client = Client::new(Config {
3003            server_url: Some(base.clone()),
3004            ..Default::default()
3005        })
3006        .unwrap();
3007        client.prime_tokens_for_test(unexpired_token(&base));
3008        let (out, _) = client
3009            .do_json_full::<serde_json::Value>(http::Method::GET, "/whatever", None, None)
3010            .await
3011            .unwrap();
3012        assert!(out.is_none());
3013    }
3014
3015    #[test]
3016    fn embedding_rerank_request_serialization() {
3017        // EmbeddingInput untagged: Single → 裸字符串, Batch → 数组; 可选字段缺省不出现。
3018        let single = EmbeddingRequest {
3019            input: Some(crate::models::types::EmbeddingInput::Single("hello".into())),
3020            dimensions: Some(512),
3021            ..Default::default()
3022        };
3023        let v = serde_json::to_value(&single).unwrap();
3024        assert_eq!(v["input"], serde_json::json!("hello"));
3025        assert_eq!(v["dimensions"], serde_json::json!(512));
3026        assert!(v.get("encoding_format").is_none());
3027        assert!(v.get("contents").is_none());
3028
3029        let batch = EmbeddingRequest {
3030            input: Some(crate::models::types::EmbeddingInput::Batch(vec![
3031                "a".into(),
3032                "b".into(),
3033            ])),
3034            ..Default::default()
3035        };
3036        let vb = serde_json::to_value(&batch).unwrap();
3037        assert_eq!(vb["input"], serde_json::json!(["a", "b"]));
3038        assert!(vb.get("dimensions").is_none());
3039
3040        let rr = RerankRequest {
3041            query: "q".into(),
3042            documents: vec!["d0".into(), "d1".into()],
3043            top_n: Some(2),
3044            return_documents: Some(true),
3045            instruct: None,
3046            fps: None,
3047        };
3048        let vr = serde_json::to_value(&rr).unwrap();
3049        assert_eq!(vr["query"], serde_json::json!("q"));
3050        assert_eq!(vr["documents"], serde_json::json!(["d0", "d1"]));
3051        assert_eq!(vr["top_n"], serde_json::json!(2));
3052        assert_eq!(vr["return_documents"], serde_json::json!(true));
3053        assert!(vr.get("instruct").is_none());
3054        assert!(vr.get("fps").is_none());
3055    }
3056
3057    #[test]
3058    fn multimodal_embedding_rerank_serialization() {
3059        use crate::models::types::MultimodalContent;
3060        // 多模态向量: contents 取代 input, 多模态参数透传。
3061        let emb = EmbeddingRequest {
3062            contents: Some(vec![
3063                MultimodalContent {
3064                    text: Some("一只猫".into()),
3065                    ..Default::default()
3066                },
3067                MultimodalContent {
3068                    image: Some("https://x/cat.png".into()),
3069                    ..Default::default()
3070                },
3071                MultimodalContent {
3072                    video: Some("https://x/clip.mp4".into()),
3073                    ..Default::default()
3074                },
3075            ]),
3076            output_type: Some("dense".into()),
3077            fps: Some(2.0),
3078            enable_fusion: Some(true),
3079            ..Default::default()
3080        };
3081        let v = serde_json::to_value(&emb).unwrap();
3082        assert!(v.get("input").is_none(), "input 缺省不出现");
3083        assert_eq!(v["contents"][0]["text"], serde_json::json!("一只猫"));
3084        assert_eq!(
3085            v["contents"][1]["image"],
3086            serde_json::json!("https://x/cat.png")
3087        );
3088        assert_eq!(
3089            v["contents"][2]["video"],
3090            serde_json::json!("https://x/clip.mp4")
3091        );
3092        // image/video 在纯文本片段里缺省不出现
3093        assert!(v["contents"][0].get("image").is_none());
3094        assert_eq!(v["output_type"], serde_json::json!("dense"));
3095        assert_eq!(v["fps"], serde_json::json!(2.0));
3096        assert_eq!(v["enable_fusion"], serde_json::json!(true));
3097
3098        // 多模态重排序: query / documents 为多模态对象, 也可混入纯文本字符串。
3099        let rr = RerankRequest {
3100            query: MultimodalContent {
3101                text: Some("红色跑车".into()),
3102                ..Default::default()
3103            }
3104            .into(),
3105            documents: vec![
3106                MultimodalContent {
3107                    image: Some("https://x/car.png".into()),
3108                    ..Default::default()
3109                }
3110                .into(),
3111                "一段文字".into(),
3112            ],
3113            top_n: None,
3114            return_documents: None,
3115            instruct: None,
3116            fps: Some(1.5),
3117        };
3118        let vr = serde_json::to_value(&rr).unwrap();
3119        assert_eq!(vr["query"]["text"], serde_json::json!("红色跑车"));
3120        assert_eq!(
3121            vr["documents"][0]["image"],
3122            serde_json::json!("https://x/car.png")
3123        );
3124        assert_eq!(vr["documents"][1], serde_json::json!("一段文字"));
3125        assert_eq!(vr["fps"], serde_json::json!(1.5));
3126    }
3127
3128    #[tokio::test]
3129    async fn embeddings_posts_and_parses_openai_response() {
3130        let body = r#"{"object":"list","model":"text-embedding-v4","data":[{"object":"embedding","index":0,"embedding":[0.1,0.2,0.3]}],"usage":{"prompt_tokens":5,"total_tokens":5}}"#;
3131        let (base, log, _) = spawn_mock(vec![MockResponse::ok(body)]).await;
3132        let client = primed_client(&base);
3133
3134        let req = EmbeddingRequest {
3135            input: Some(crate::models::types::EmbeddingInput::Single("hello".into())),
3136            dimensions: Some(512),
3137            ..Default::default()
3138        };
3139        let resp = client
3140            .embeddings("text-embedding-v4", &req, None)
3141            .await
3142            .unwrap();
3143
3144        let recorded = log.lock().unwrap().clone();
3145        assert_eq!(recorded.len(), 1);
3146        assert!(
3147            recorded[0].contains("POST")
3148                && recorded[0].contains("/managed-models/text-embedding-v4/embeddings"),
3149            "unexpected request line: {}",
3150            recorded[0]
3151        );
3152        assert_eq!(resp.model, "text-embedding-v4");
3153        assert_eq!(resp.data.len(), 1);
3154        assert_eq!(resp.data[0].embedding, vec![0.1, 0.2, 0.3]);
3155        assert_eq!(resp.usage.total_tokens, 5);
3156    }
3157
3158    #[tokio::test]
3159    async fn rerank_posts_and_parses_normalized_response() {
3160        let body = r#"{"results":[{"index":1,"relevance_score":0.93,"document":"doc1"},{"index":0,"relevance_score":0.42,"document":"doc0"}],"usage":{"total_tokens":79},"model":"gte-rerank-v2"}"#;
3161        let (base, log, _) = spawn_mock(vec![MockResponse::ok(body)]).await;
3162        let client = primed_client(&base);
3163
3164        let req = RerankRequest {
3165            query: "q".into(),
3166            documents: vec!["doc0".into(), "doc1".into()],
3167            top_n: Some(2),
3168            return_documents: Some(true),
3169            instruct: None,
3170            fps: None,
3171        };
3172        let resp = client.rerank("gte-rerank-v2", &req, None).await.unwrap();
3173
3174        let recorded = log.lock().unwrap().clone();
3175        assert!(
3176            recorded[0].contains("POST")
3177                && recorded[0].contains("/managed-models/gte-rerank-v2/rerank"),
3178            "unexpected request line: {}",
3179            recorded[0]
3180        );
3181        assert_eq!(resp.results.len(), 2);
3182        assert_eq!(resp.results[0].index, 1);
3183        assert!((resp.results[0].relevance_score - 0.93).abs() < 1e-9);
3184        assert_eq!(resp.results[0].document.as_deref(), Some("doc1"));
3185        assert_eq!(resp.usage.total_tokens, 79);
3186        assert_eq!(resp.model.as_deref(), Some("gte-rerank-v2"));
3187    }
3188
3189    #[tokio::test]
3190    async fn chat_401_single_refresh_retry_then_succeeds() {
3191        // 序列:①chat POST → 401 ②token_endpoint refresh → 200 新 token ③chat POST 重试 → 200。
3192        let chat_body = r#"{"id":"msg_2","type":"message","model":"test-model","role":"assistant","content":[],"stop_reason":"end_turn","usage":{"input_tokens":1,"output_tokens":1}}"#;
3193        let token_body = r#"{"access_token":"AT1","token_type":"Bearer","expires_in":3600,"refresh_token":"RT1"}"#;
3194        let (base, log, count) = spawn_mock(vec![
3195            MockResponse::status(401, "{}"),
3196            MockResponse::ok(token_body),
3197            MockResponse::ok(chat_body),
3198        ])
3199        .await;
3200
3201        let client = primed_client(&base);
3202        // 注入 meta,使 force_refresh 的 refresh_direct 不触发 discover,直接打 token_endpoint。
3203        client.prime_meta_for_test(ServerMetadata {
3204            issuer: base.clone(),
3205            authorization_endpoint: format!("{base}/authorize"),
3206            token_endpoint: format!("{base}/token"),
3207            revocation_endpoint: format!("{base}/revoke"),
3208            registration_endpoint: format!("{base}/register"),
3209            scopes_supported: vec![],
3210        });
3211
3212        let req = ChatRequest::default();
3213        let out = client.chat("test-model", &req, None).await.unwrap();
3214        assert_eq!(out.id, "msg_2");
3215
3216        let recorded = log.lock().unwrap().clone();
3217        // 红线:恰 3 次请求(chat 401 → refresh → chat 重试),不无限递归。
3218        assert_eq!(count.load(AtomicOrdering::SeqCst), 3, "exactly one retry");
3219        assert_eq!(
3220            recorded[0],
3221            "POST /api/v4/managed-models/test-model/anthropic"
3222        );
3223        assert!(
3224            recorded[1].starts_with("POST /token"),
3225            "refresh hits token_endpoint: {}",
3226            recorded[1]
3227        );
3228        assert_eq!(
3229            recorded[2],
3230            "POST /api/v4/managed-models/test-model/anthropic"
3231        );
3232        // token 已轮换。
3233        assert_eq!(client.token_set().unwrap().access_token, "AT1");
3234    }
3235
3236    #[tokio::test]
3237    async fn chat_401_twice_does_not_recurse() {
3238        // 序列:①chat → 401 ②refresh → 200 ③chat 重试 → 又 401 → 不再重试,抛 HttpError(401)。
3239        let token_body = r#"{"access_token":"AT1","token_type":"Bearer","expires_in":3600,"refresh_token":"RT1"}"#;
3240        let (base, _log, count) = spawn_mock(vec![
3241            MockResponse::status(401, "{}"),
3242            MockResponse::ok(token_body),
3243            MockResponse::status(401, "{}"),
3244        ])
3245        .await;
3246        let client = primed_client(&base);
3247        client.prime_meta_for_test(ServerMetadata {
3248            issuer: base.clone(),
3249            authorization_endpoint: format!("{base}/authorize"),
3250            token_endpoint: format!("{base}/token"),
3251            revocation_endpoint: format!("{base}/revoke"),
3252            registration_endpoint: format!("{base}/register"),
3253            scopes_supported: vec![],
3254        });
3255        let req = ChatRequest::default();
3256        let err = client.chat("test-model", &req, None).await.unwrap_err();
3257        match err {
3258            Error::Http(h) => assert_eq!(h.status_code, 401),
3259            other => panic!("expected HttpError(401), got {other:?}"),
3260        }
3261        // 红线:第二次 401 不再触发 refresh/重试 —— 恰 3 次请求。
3262        assert_eq!(
3263            count.load(AtomicOrdering::SeqCst),
3264            3,
3265            "guard prevents recursion"
3266        );
3267    }
3268
3269    // ── 超时回归(真实时钟 + 控制组对照)──
3270    //
3271    // 设计:reqwest 内部计时器(含 connect_timeout)与 tokio paused 虚拟时钟混用会
3272    // 不确定地抢先误触,故这些回归测试用真实时钟 + 小间隔,并用「控制组 client(显式
3273    // 短全局 .timeout())会被砍」对照「默认 client(无全局 .timeout())不被砍」,
3274    // 来确定性坐实:`Client::new` 默认构造的 http 没有覆盖响应体(含 SSE)的全局总超时。
3275
3276    /// 启一个流式 SSE mock server:建连后立即发响应头 + 第一个 chunk,随后每隔
3277    /// `gap` 真实毫秒下发一个 chunk,共 `n_events` 个。用于「全局总超时是否砍响应体」对照。
3278    async fn spawn_sse_mock_realtime(gap: std::time::Duration, n_events: usize) -> String {
3279        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
3280        let addr = listener.local_addr().unwrap();
3281        let base = format!("http://{addr}");
3282        tokio::spawn(async move {
3283            let (mut sock, _) = match listener.accept().await {
3284                Ok(s) => s,
3285                Err(_) => return,
3286            };
3287            let mut buf = vec![0u8; 8192];
3288            let _ = sock.read(&mut buf).await;
3289
3290            let head = "HTTP/1.1 200 OK\r\nContent-Type: text/event-stream\r\n\
3291                        Transfer-Encoding: chunked\r\n\r\n";
3292            if sock.write_all(head.as_bytes()).await.is_err() {
3293                return;
3294            }
3295            let _ = sock.flush().await;
3296
3297            for i in 0..n_events {
3298                if i > 0 {
3299                    tokio::time::sleep(gap).await;
3300                }
3301                let payload = format!(
3302                    "event: content_block_delta\n\
3303                     data: {{\"type\":\"content_block_delta\",\"index\":0,\
3304                     \"delta\":{{\"type\":\"text_delta\",\"text\":\"chunk{i}\"}}}}\n\n"
3305                );
3306                let chunk = format!("{:x}\r\n{}\r\n", payload.len(), payload);
3307                if sock.write_all(chunk.as_bytes()).await.is_err() {
3308                    return;
3309                }
3310                if sock.flush().await.is_err() {
3311                    return;
3312                }
3313            }
3314            let _ = sock.write_all(b"0\r\n\r\n").await;
3315            let _ = sock.flush().await;
3316            let _ = sock.shutdown().await;
3317        });
3318        base
3319    }
3320
3321    fn primed_client_with_http(base: &str, http: reqwest::Client) -> Client {
3322        let client = Client::new(Config {
3323            server_url: Some(base.to_string()),
3324            http: Some(http),
3325            ..Default::default()
3326        })
3327        .unwrap();
3328        client.prime_tokens_for_test(unexpired_token(base));
3329        client.prime_model_cache_for_test(vec![ManagedModel {
3330            id: "test-model".to_string(),
3331            provider: "anthropic".to_string(),
3332            model_id: "test-model".to_string(),
3333            is_enabled: true,
3334            ..Default::default()
3335        }]);
3336        client
3337    }
3338
3339    /// 控制组:显式带 250ms 全局 `.timeout()` 的 client(模拟「旧 60s 全局总超时」的语义,
3340    /// 只是阈值缩小到 250ms 以便快速触发)。流式总时长跨过 250ms → 必被 reqwest abort。
3341    #[tokio::test]
3342    async fn stream_aborted_by_explicit_global_timeout_control() {
3343        // chunk 间隔 200ms × 3 → 流式总时长 ≈ 400ms > 250ms 全局 timeout。
3344        let base = spawn_sse_mock_realtime(std::time::Duration::from_millis(200), 3).await;
3345        let http = reqwest::Client::builder()
3346            .timeout(std::time::Duration::from_millis(250))
3347            .build()
3348            .unwrap();
3349        let client = primed_client_with_http(&base, http);
3350
3351        let req = ChatRequest::default();
3352        let stream = client.chat_stream("test-model", &req, None);
3353        futures::pin_mut!(stream);
3354
3355        let mut err_seen = false;
3356        let mut count = 0usize;
3357        while let Some(ev) = stream.next().await {
3358            match ev {
3359                Ok(_) => count += 1,
3360                Err(_) => {
3361                    err_seen = true;
3362                    break;
3363                }
3364            }
3365        }
3366        // 控制组红线:全局 .timeout() 会在响应体中途 abort SSE 流(拿不全 3 个 chunk)。
3367        assert!(
3368            err_seen && count < 3,
3369            "带全局 .timeout() 的 client 必在流式响应体中途被 abort(got {count} chunks, err={err_seen})"
3370        );
3371    }
3372
3373    /// 主回归:`Client::new` 默认构造的 http **无全局总超时** → 同样跨过 250ms 的流式
3374    /// 响应体不被 abort,收齐全部 chunk。证明已去除击穿流式 SSE 的全局 60s 总超时。
3375    #[tokio::test]
3376    async fn stream_survives_long_body_no_global_timeout() {
3377        // 同样的间隔/总时长(≈400ms),但用默认 client(无全局 timeout)。
3378        let base = spawn_sse_mock_realtime(std::time::Duration::from_millis(200), 3).await;
3379        let client = primed_client(&base); // 默认 http,无 .timeout()
3380
3381        let req = ChatRequest::default();
3382        let stream = client.chat_stream("test-model", &req, None);
3383        futures::pin_mut!(stream);
3384
3385        let mut events: Vec<StreamEvent> = Vec::new();
3386        while let Some(ev) = stream.next().await {
3387            let ev = ev.expect("默认 client 无全局总超时,流式响应体不应被 abort");
3388            events.push(ev);
3389        }
3390        assert_eq!(
3391            events.len(),
3392            3,
3393            "默认 client 必收齐 3 个 chunk(无全局总超时砍响应体)"
3394        );
3395        for (i, ev) in events.iter().enumerate() {
3396            assert_eq!(ev.event, "content_block_delta");
3397            assert!(ev.data.contains(&format!("chunk{i}")));
3398        }
3399    }
3400
3401    /// 非流式回归:默认 client 对「响应延迟 > 控制组 timeout」的非流式 chat 不被全局总超时砍。
3402    /// 控制组(250ms 全局 timeout)会 abort;默认 client 等到响应(≈400ms)成功。
3403    #[tokio::test]
3404    async fn nonstream_chat_survives_slow_response_no_global_timeout() {
3405        // 单次非流式响应:accept 后延迟 400ms 才回响应体。
3406        async fn spawn_slow_json(delay: std::time::Duration) -> String {
3407            let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
3408            let addr = listener.local_addr().unwrap();
3409            let base = format!("http://{addr}");
3410            tokio::spawn(async move {
3411                if let Ok((mut sock, _)) = listener.accept().await {
3412                    let mut buf = vec![0u8; 8192];
3413                    let _ = sock.read(&mut buf).await;
3414                    tokio::time::sleep(delay).await;
3415                    let body = r#"{"id":"msg_slow","type":"message","model":"test-model","role":"assistant","content":[],"stop_reason":"end_turn","usage":{"input_tokens":1,"output_tokens":1}}"#;
3416                    let resp = format!(
3417                        "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
3418                        body.len(),
3419                        body
3420                    );
3421                    let _ = sock.write_all(resp.as_bytes()).await;
3422                    let _ = sock.flush().await;
3423                    let _ = sock.shutdown().await;
3424                }
3425            });
3426            base
3427        }
3428
3429        // 控制组:250ms 全局 timeout 对 400ms 慢响应 → 被砍。
3430        let ctrl_base = spawn_slow_json(std::time::Duration::from_millis(400)).await;
3431        let http = reqwest::Client::builder()
3432            .timeout(std::time::Duration::from_millis(250))
3433            .build()
3434            .unwrap();
3435        let ctrl = primed_client_with_http(&ctrl_base, http);
3436        let err = ctrl
3437            .chat("test-model", &ChatRequest::default(), None)
3438            .await
3439            .expect_err("控制组 250ms 全局 timeout 必砍 400ms 慢响应");
3440        match err {
3441            Error::Network(n) => assert!(n.timeout, "控制组应为 reqwest 超时错误,got: {n:?}"),
3442            other => panic!("expected Network timeout, got {other:?}"),
3443        }
3444
3445        // 默认 client:无全局总超时 → 同样的 400ms 慢响应应成功(per-request 死线 11min 远未到)。
3446        let base = spawn_slow_json(std::time::Duration::from_millis(400)).await;
3447        let client = primed_client(&base);
3448        let out = client
3449            .chat("test-model", &ChatRequest::default(), None)
3450            .await
3451            .expect("默认 client 无全局总超时,400ms 慢响应不应被砍");
3452        assert_eq!(out.id, "msg_slow");
3453    }
3454}