//! 翻译模块:多源翻译 + AI 翻译 + 划词翻译 + 截图翻译。 //! //! 架构(详见仓库根目录 `TRANSLATE_MODULE_PLAN.md`): //! //! ```text //! 前端(主面板 / 划词悬浮窗 / 截图选区) //! ↓ Tauri IPC //! commands.rs 命令层(薄:参数整形 + 交给 manager) //! ↓ //! TranslateManager(本文件):设置读写 / 引擎装配 / 代理判定 / 自动降级编排 //! ↓ //! engines/ 引擎实现(ai = OpenAI 兼容;free = libretranslate / mymemory) //! capture/ 取词(P1:Ctrl+C 兼容路径) //! popup.rs 取词结果的非激活悬浮窗 //! ↓ reqwest //! DeepSeek / OpenAI 兼容端点 / LibreTranslate / MyMemory //! ``` //! //! 三条贯穿全模块的约束: //! 1. **网络请求只在 Rust 侧发生**。生产构建的 CSP 只允许 `ipc:` 连接,前端直连外部 //! API 会被静默拦截;且密钥若进入 WebView,等于把凭据暴露给了页面上下文。 //! 2. **引擎实例按请求即时构造**,不缓存。引擎是有状态的(密钥、模型、超时), //! 而设置页改完就该立刻生效——缓存实例反而要额外处理失效,得不偿失。 //! 3. **代理只在这里判定一次**。reqwest 的代理必须在建 Client 时指定、不能按请求覆盖, //! 因此「直连还是走代理」的决策收敛到 [`TranslateManager::select_client`], //! 各引擎一律拿现成的客户端。 mod capture; mod commands; mod engines; mod history; mod migrate; mod ocr; mod popup; mod settings; pub use commands::{ translate_abort, translate_ai_engine_remove, translate_ai_params_save, translate_apply_shortcuts, translate_copy_text, translate_engine_delete, translate_engine_models, translate_engine_save, translate_engine_test_config, translate_engines_list, translate_get_settings, translate_history_clear, translate_history_delete, translate_history_list, translate_history_set_favorited, translate_ocr_languages, translate_paste_back, translate_popup_edit_mode, translate_popup_hide, translate_popup_prefs_set, translate_popup_ready, translate_popup_resize, translate_popup_set_pinned, translate_preview_popup, translate_run, translate_save_settings, translate_screenshot_region, translate_secret_clear, translate_secret_set, translate_stream_start, }; pub use engines::{TranslateEngine, TranslateError, TranslateResult}; // 只再导出本模块内部(mod.rs / commands.rs / popup.rs)实际用到的类型。其余类型仍保留在 // `engines::` / `settings::` 下,等真正用到时再提升到此处——提前摆出一堆无人消费的再导出, // 只会让「谁在用」更难判断。 pub use settings::TranslateSettings; // TranslateEngineConfig / TranslateAiParams 供命令层、ai 迁移与前端类型共用。 pub use settings::{TranslateAiParams, TranslateEngineConfig}; // 启动阶段的一次性迁移(把旧版存在翻译设置里的 AI 引擎搬进主设置 → AI 服务)。 pub use migrate::migrate_legacy_ai_engines; use engines::EngineRequest; use std::path::PathBuf; use std::sync::Mutex; use std::time::{Duration, Instant}; /// 设置内存缓存有效期。设置页存在「读一次、改一处、再读」的高频往返, /// 不缓存会反复读盘;缓存过长又会让外部改动不可见,500ms 与音乐模块保持一致。 const SETTINGS_CACHE_TTL: Duration = Duration::from_millis(500); /// 代理可用性的缓存有效期。控制端探测是一次本机 HTTP 请求(通常 1ms 内拒绝/返回), /// 但设置页刷一次引擎列表就要探测一次,加个短缓存避免无谓往返。 const PROXY_CACHE_TTL: Duration = Duration::from_millis(5000); /// 引擎 API Key 的凭据键前缀(键名格式:`translate-engine-`)。 const ENGINE_KEY_PREFIX: &str = "translate-engine-"; /// 某引擎实例的凭据键(free/cloud 源使用;AI 供应商用 `ai-provider-`)。 pub fn engine_secret_key(engine_id: &str) -> String { format!("{ENGINE_KEY_PREFIX}{engine_id}") } /// 启动时按设置注册全局快捷键并预创建取词悬浮窗。 /// 失败只记日志、不阻断启动——快捷键被别的程序占用不该让应用起不来。 pub fn init_on_launch(app: &tauri::AppHandle) { if let Err(e) = popup::apply_shortcuts(app) { crate::logger::log_warn("translate", &format!("启动时注册取词快捷键失败: {e}")); } } /// 读取某引擎实例的 API Key(未配置或读取失败 → 空串)。 /// /// AI 引擎(kind = "ai")的密钥在 `ai-provider-*`,走 [`crate::ai::provider_api_key`]; /// free/cloud 读本模块的 `translate-engine-*`。两条路径互不通气——AI 侧不认识旧键, /// 密钥由 [`migrate_legacy_ai_engines`] 一次性复制过去。 pub fn engine_api_key(engine_id: &str) -> String { engine_api_key_with_kind(engine_id, None) } /// 按 kind 读取密钥。`kind_hint` 为 Some("ai") 时走 AI 凭据键。 pub fn engine_api_key_with_kind(engine_id: &str, kind_hint: Option<&str>) -> String { if engine_id.trim().is_empty() { return String::new(); } if kind_hint == Some("ai") { return crate::ai::provider_api_key(engine_id); } crate::secrets::read_or_empty(&engine_secret_key(engine_id)) } /// 把全局 AI 供应商转换为翻译引擎配置(kind = "ai")。 /// /// 连接与生成参数来自 AI 侧;**启用 / 优先级 / 超时 / 提示词覆盖**来自翻译设置的 /// [`TranslateAiParams`](场景参数归翻译管)。翻译候选与视觉直译都消费转换后的结果。 /// /// `enabled` 取两层开关的与:供应商自身关掉(AI 服务里停用)或翻译侧关掉,都不上场。 pub fn ai_provider_as_engine( p: &crate::ai::AiProviderConfig, params: &TranslateAiParams, ) -> TranslateEngineConfig { TranslateEngineConfig { id: p.id.clone(), name: p.name.clone(), kind: "ai".to_string(), preset: p.preset.clone(), enabled: p.enabled && params.enabled, priority: params.priority, base_url: p.base_url.clone(), model: p.model.clone(), temperature: p.temperature, max_tokens: p.max_tokens, timeout_ms: params.timeout_ms.max(1_000), system_prompt: params.system_prompt.clone(), extra_body: p.extra_body.clone(), supports_vision: p.supports_vision, } } struct SettingsCache { read_at: Instant, settings: TranslateSettings, } /// 翻译模块管理器(Tauri State)。 pub struct TranslateManager { /// 应用数据目录(proxy 模块的配置也在这一层,代理判定需要) data_dir: PathBuf, /// 模块自身目录:{app_data_dir}/translate root: PathBuf, /// 直连客户端 client: reqwest::Client, cache: Mutex>, /// 代理地址解析缓存:`(解析时刻, 是否开启代理, 结果)`。 /// 必须把「是否开启」一并缓存:AI 引擎看 AI 服务的开关、free/cloud 看本模块开关, /// 两个值不同却共用一份缓存时,先被解析的一方会把另一方带偏。 proxy_cache: Mutex)>>, /// 带代理的客户端缓存:`(代理地址, 客户端)`。与地址一一对应,地址变了就重建。 proxied_client: Mutex>, /// 翻译历史。打开失败时为 None:历史是锦上添花,不值得为它让整个模块不可用。 history: Option>, } impl TranslateManager { pub fn new(app_data_dir: PathBuf) -> Self { let root = app_data_dir.join("translate"); std::fs::create_dir_all(&root).ok(); let client = reqwest::Client::builder() // 兜底超时:单个请求还会按引擎配置设置更精确的超时 .timeout(Duration::from_secs(120)) .build() .unwrap_or_else(|_| reqwest::Client::new()); let history = match history::History::new(&root) { Ok(h) => Some(std::sync::Arc::new(h)), Err(e) => { crate::logger::log_warn("translate", &format!("翻译历史不可用: {e}")); None } }; Self { data_dir: app_data_dir, root, client, cache: Mutex::new(None), proxy_cache: Mutex::new(None), proxied_client: Mutex::new(None), history, } } fn settings_path(&self) -> PathBuf { self.root.join("settings.json") } // ===== 设置 ===== /// 读取设置(带短时缓存;文件缺失/损坏回退默认值;自愈结果落盘)。 pub fn load_settings(&self) -> TranslateSettings { if let Ok(cache) = self.cache.lock() { if let Some(entry) = cache.as_ref() { if entry.read_at.elapsed() < SETTINGS_CACHE_TTL { return entry.settings.clone(); } } } // 文件缺失或损坏一律回退默认值:翻译是可随时重建的配置, // 不值得为「读不懂的旧文件」让整个模块不可用。 let mut settings = std::fs::read_to_string(self.settings_path()) .ok() .and_then(|s| serde_json::from_str::(&s).ok()) .unwrap_or_default(); let mut healed = settings.heal(); // 默认引擎指向「本模块里没有、也已不在翻译候选里的 AI 供应商」→ 改为「自动」。 // 放在 Manager 而不是 settings::heal:那里拿不到 data_dir,读不了 AI 供应商。 // 判定必须连 ai_params 一起看:供应商在 AI 服务里存在、但被用户移出翻译候选时, // 它同样不能再当默认引擎。 if settings.default_engine_id != "auto" && settings.engine(&settings.default_engine_id).is_none() { // 只有「已加入翻译候选、且供应商仍存在」的 AI 引擎才保留 let still_valid = settings.has_ai_engine(&settings.default_engine_id) && crate::ai::AiManager::load_settings_sync(&self.data_dir) .provider(&settings.default_engine_id) .is_some(); if !still_valid { settings.default_engine_id = "auto".to_string(); healed = true; } } if let Ok(mut cache) = self.cache.lock() { *cache = Some(SettingsCache { read_at: Instant::now(), settings: settings.clone(), }); } if healed { if let Err(e) = self.save_settings(&settings) { crate::logger::log_error("translate", &format!("设置自愈落盘失败: {e}")); } } settings } /// 保存设置并刷新缓存。 pub fn save_settings(&self, settings: &TranslateSettings) -> Result<(), String> { let json = serde_json::to_string_pretty(settings) .map_err(|e| format!("序列化翻译设置失败: {e}"))?; std::fs::write(self.settings_path(), json).map_err(|e| format!("写入翻译设置失败: {e}"))?; if let Ok(mut cache) = self.cache.lock() { *cache = Some(SettingsCache { read_at: Instant::now(), settings: settings.clone(), }); } Ok(()) } // ===== 代理 ===== /// 读代理模块(mihomo)配置:`{app_data_dir}/proxy/settings.json` 的 mixedPort。 /// 返回 `(mixedPort, externalController)`;缺失或非法返回 None。 /// /// 这里刻意**只读文件不依赖 MihomoManager 状态**:翻译模块不该因为代理模块被禁用 /// 就拿不到端口;端口是否可用由下面的控制端探测回答。 fn read_mixed_port(&self) -> Option<(u16, String)> { let path = self.data_dir.join("proxy").join("settings.json"); let raw = std::fs::read_to_string(path).ok()?; let value: serde_json::Value = serde_json::from_str(&raw).ok()?; let port = value.get("mixedPort").and_then(|v| v.as_u64())?; if port == 0 || port > 65535 { return None; } let controller = value .get("externalController") .and_then(|v| v.as_str()) .unwrap_or("127.0.0.1:9090") .to_string(); Some((port as u16, controller)) } /// 探测 mihomo 控制端是否在线。 /// /// 判定标准是「能建立连接」而不是「返回 200」:控制端设了 secret 时会返回 401, /// 但那恰恰说明内核在运行、代理端口可用。只有连接失败才算离线。 async fn probe_controller(&self, controller: &str) -> bool { let base = if controller.starts_with("http://") || controller.starts_with("https://") { controller.to_string() } else { format!("http://{controller}") }; let url = format!("{}/version", base.trim_end_matches('/')); self.client .get(&url) .timeout(Duration::from_millis(800)) .send() .await .is_ok() } /// 解析当前应使用的代理地址(带 TTL 缓存)。`enabled` 为 false 时直接返回 None。 /// /// `enabled` 由调用方按引擎归属给出:AI 引擎取 AI 服务的开关,其余取本模块的开关。 async fn resolve_proxy_url(&self, enabled: bool) -> Option { if !enabled { return None; } if let Ok(cache) = self.proxy_cache.lock() { if let Some((at, cached_enabled, url)) = cache.as_ref() { if *cached_enabled == enabled && at.elapsed() < PROXY_CACHE_TTL { return url.clone(); } } } let resolved = match self.read_mixed_port() { Some((port, controller)) => { let url = format!("http://127.0.0.1:{port}"); if self.probe_controller(&controller).await { Some(url) } else { None } } None => None, }; if let Ok(mut cache) = self.proxy_cache.lock() { let previous = cache.as_ref().and_then(|(_, _, u)| u.clone()); let changed = previous != resolved; *cache = Some((Instant::now(), enabled, resolved.clone())); // 地址变了(或可用性变了)就丢弃旧客户端,否则会继续用已失效的代理 if changed { if let Ok(mut client) = self.proxied_client.lock() { *client = None; } } } resolved } /// 选择本次请求使用的 HTTP 客户端:开了代理且可用 → 走代理,否则直连。 /// 代理不可用时**静默回退直连**:让请求自己去失败,比在这里造一个错误更接近真相 /// (也许代理确实不通但目标站恰好可达)。 async fn select_client(&self, use_proxy: bool) -> reqwest::Client { let Some(url) = self.resolve_proxy_url(use_proxy).await else { return self.client.clone(); }; if let Ok(cache) = self.proxied_client.lock() { if let Some((cached_url, client)) = cache.as_ref() { if *cached_url == url { return client.clone(); } } } let built = reqwest::Proxy::all(&url).ok().and_then(|proxy| { reqwest::Client::builder() .timeout(Duration::from_secs(120)) .proxy(proxy) .build() .ok() }); match built { Some(client) => { if let Ok(mut cache) = self.proxied_client.lock() { *cache = Some((url, client.clone())); } client } None => { crate::logger::log_warn("translate", "构造带代理的 HTTP 客户端失败,本次回退直连"); self.client.clone() } } } // ===== 引擎 ===== /// 本模块自有引擎(free/cloud)+ **已加入翻译候选的**全局 AI 供应商 /// (转换为 kind = "ai"),按优先级升序。 /// /// 这是翻译候选的**唯一真源**:显式指定、自动降级、视觉直译都从这里取。 /// /// 两条筛选: /// - AI 供应商必须先在翻译设置里「加入」(= `ai_params` 有记录)。主设置里配好的 /// 供应商不自动参与翻译,用户要哪几个就加哪几个; /// - 历史遗留的 kind = "ai" 引擎(早期版本把 AI 存在翻译设置里)直接丢弃: /// 它的连接配置已搬去 AI 服务、密钥也读不到,留着只会与 AI 供应商重复且删不掉。 /// /// **不过滤 enabled**——列表 UI 要能看到已禁用项;启用过滤发生在 /// [`Self::resolve_candidates`] 的 auto 分支。 pub fn all_engines(&self) -> Vec { let settings = self.load_settings(); let ai = crate::ai::AiManager::load_settings_sync(&self.data_dir); let mut list: Vec = settings .engines .iter() .filter(|e| e.kind != "ai") .cloned() .collect(); list.extend( ai.providers .iter() .filter(|p| settings.has_ai_engine(&p.id)) .map(|p| ai_provider_as_engine(p, &settings.ai_params_for(&p.id))), ); list.sort_by_key(|e| e.priority); list } /// 本次请求该不该走代理。 /// /// AI 引擎的连接配置归主设置(AI 服务)管,代理开关也跟着那边走;free/cloud 是 /// 本模块自己的源,用本模块的开关。两边开关同名不同域,混用会出现「终端里能通、 /// 翻译里不通(或反过来)」这种极难排查的现象。 fn proxy_enabled_for(&self, kind: &str) -> bool { if kind == "ai" { crate::ai::AiManager::load_settings_sync(&self.data_dir).use_proxy } else { self.load_settings().use_proxy } } /// 按配置装配引擎实例(异步:需要先决定走不走代理)。 pub async fn build( &self, cfg: &TranslateEngineConfig, ) -> Result, TranslateError> { let templates = self.load_settings().prompt_templates; let client = self.select_client(self.proxy_enabled_for(&cfg.kind)).await; engines::build_engine(cfg, &templates, client) } /// 解析本次请求实际要尝试的引擎序列。 /// /// - 显式指定了 `engineId`:只用它(用户要的就是「这个源」)——请求失败不做降级, /// 否则「指定了 A 却拿到 B 的译文」比报错更令人困惑。 /// - `auto` / 未指定:开启降级时按优先级依次尝试;关闭降级时只用默认引擎。 pub fn resolve_candidates( &self, engine_id: Option<&str>, ) -> Result, TranslateError> { let settings = self.load_settings(); let all = self.all_engines(); let explicit = engine_id .map(str::trim) .filter(|s| !s.is_empty() && *s != "auto"); if let Some(id) = explicit { return all .into_iter() .find(|e| e.id == id) .map(|cfg| vec![cfg]) .ok_or_else(|| TranslateError::config(format!("找不到引擎实例「{id}」"))); } if settings.auto_fallback { // 自动模式只尝试已启用的(free + AI 同一规则) let list: Vec = all.into_iter().filter(|e| e.enabled).collect(); if list.is_empty() { return Err(TranslateError::config( "没有可用的翻译引擎:请在主设置 → AI 服务中配置供应商,\ 再到翻译设置里把它加入翻译候选(或启用免密钥/云引擎)", )); } return Ok(list); } // 未开启降级:只尝试默认引擎;默认引擎失效时回落到优先级最高的已启用实例 let preferred = all .iter() .find(|e| e.id == settings.default_engine_id && e.enabled) .cloned() .or_else(|| { all.into_iter() .filter(|e| e.enabled) .min_by_key(|e| e.priority) }); preferred .map(|cfg| vec![cfg]) .ok_or_else(|| { TranslateError::config( "没有可用的翻译引擎:请在主设置 → AI 服务中配置供应商,\ 再到翻译设置里把它加入翻译候选,并启用至少一个引擎", ) }) } /// 执行一次翻译(含自动降级)。 /// /// `record`:是否写入历史。正常翻译为 true;**多引擎对比必须传 false**—— /// 对比一次产生 N 条结果,全部入库只会污染记录。历史是否记录由此参数 /// 显式决定,而不是靠调用方绕开本方法(绕开会让「哪些入口记历史」无从查起)。 pub async fn run( &self, req: EngineRequest, engine_id: Option<&str>, record: bool, ) -> Result { let candidates = self.resolve_candidates(engine_id)?; let mut last_error: Option = None; for cfg in candidates { let engine = match self.build(&cfg).await { Ok(e) => e, Err(e) => { // 装配失败(如未接入的引擎类型)继续尝试下一个候选, // 让「自动」模式真正具备容错意义 last_error = Some(e); continue; } }; match engine.translate(&req).await { Ok(result) => { if record { self.record_history(&req, &result, &result.engine_id); } return Ok(result); } Err(e) => { crate::logger::log_warn( "translate", &format!( "引擎「{}」翻译失败:{}(kind={:?})", engine.name(), e.message, e.kind ), ); // 输入为空、语言对不支持这类错误换源也没用,直接返回首个错误 if !e.retryable() { return Err(e); } last_error = Some(e); } } } Err(last_error.unwrap_or_else(|| { TranslateError::config("没有可用的翻译引擎,请先在翻译设置中启用至少一个") })) } /// 历史库(打开失败时为 None)。`Arc` 便于流式转发任务独立持有。 pub(crate) fn history(&self) -> Option> { self.history.clone() } /// 记录一次成功翻译(失败不记:历史是「翻过的东西」,不是「试过的东西」)。 /// 历史开关关闭或库不可用时静默跳过。 fn record_history(&self, req: &EngineRequest, result: &TranslateResult, engine_id: &str) { let settings = self.load_settings(); if !settings.history.enabled { return; } let Some(history) = self.history.as_ref() else { return; }; // 截图(视觉直译)没有原文文本,用占位说明来源 let source = if req.text.trim().is_empty() { "(屏幕截图)" } else { req.text.as_str() }; if let Err(e) = history.record( &req.from, &req.to, engine_id, &result.engine_name, source, &result.text, &req.via, result.latency_ms as i64, ) { crate::logger::log_warn("translate", &format!("记录历史失败: {e}")); } history.prune_to_max(settings.history.max_items as i64); } }