Files
Thing/src-tauri/src/translate/mod.rs
T
2026-09-25 18:23:56 +08:00

576 lines
24 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! 翻译模块:多源翻译 + 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-<engineId>`)。
const ENGINE_KEY_PREFIX: &str = "translate-engine-";
/// 某引擎实例的凭据键(free/cloud 源使用;AI 供应商用 `ai-provider-<id>`)。
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<Option<SettingsCache>>,
/// 代理地址解析缓存:`(解析时刻, 是否开启代理, 结果)`。
/// 必须把「是否开启」一并缓存:AI 引擎看 AI 服务的开关、free/cloud 看本模块开关,
/// 两个值不同却共用一份缓存时,先被解析的一方会把另一方带偏。
proxy_cache: Mutex<Option<(Instant, bool, Option<String>)>>,
/// 带代理的客户端缓存:`(代理地址, 客户端)`。与地址一一对应,地址变了就重建。
proxied_client: Mutex<Option<(String, reqwest::Client)>>,
/// 翻译历史。打开失败时为 None:历史是锦上添花,不值得为它让整个模块不可用。
history: Option<std::sync::Arc<history::History>>,
}
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::<TranslateSettings>(&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<String> {
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<TranslateEngineConfig> {
let settings = self.load_settings();
let ai = crate::ai::AiManager::load_settings_sync(&self.data_dir);
let mut list: Vec<TranslateEngineConfig> = 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<Box<dyn TranslateEngine>, 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<Vec<TranslateEngineConfig>, 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<TranslateEngineConfig> =
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<TranslateResult, TranslateError> {
let candidates = self.resolve_candidates(engine_id)?;
let mut last_error: Option<TranslateError> = 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<std::sync::Arc<history::History>> {
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);
}
}