翻译模块

This commit is contained in:
zhongluofeng committed 2026-09-17 17:32:20 +08:00
1 parent 79c43d5340
commit f6c1cc250e
47 files changed
+10822 -104

No files matched your search

+452
View File
@@ -0,0 +1,452 @@
//! 翻译模块:多源翻译 + 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 ocr;
mod popup;
mod settings;
pub use commands::{
translate_abort, 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;
use engines::EngineRequest;
use settings::TranslateEngineConfig;
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-";
/// 某引擎实例的凭据键。
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(未配置或读取失败 → 空串)。
pub fn engine_api_key(engine_id: &str) -> String {
if engine_id.trim().is_empty() {
return String::new();
}
crate::secrets::read_or_empty(&engine_secret_key(engine_id))
}
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>>,
/// 代理地址解析缓存:`(解析时刻, 结果)`;结果为 None 表示已开启但不可用
proxy_cache: Mutex<Option<(Instant, 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 healed = settings.heal();
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 缓存)。未开启开关时返回 None。
async fn resolve_proxy_url(&self) -> Option<String> {
if !self.load_settings().use_proxy {
return None;
}
if let Ok(cache) = self.proxy_cache.lock() {
if let Some((at, url)) = cache.as_ref() {
if 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(), resolved.clone()));
// 地址变了(或可用性变了)就丢弃旧客户端,否则会继续用已失效的代理
if changed {
if let Ok(mut client) = self.proxied_client.lock() {
*client = None;
}
}
}
resolved
}
/// 选择本次请求使用的 HTTP 客户端:开了代理且可用 → 走代理,否则直连。
/// 代理不可用时**静默回退直连**:让请求自己去失败,比在这里造一个错误更接近真相
/// (也许代理确实不通但目标站恰好可达)。
async fn select_client(&self) -> reqwest::Client {
let Some(url) = self.resolve_proxy_url().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()
}
}
}
// ===== 引擎 =====
/// 按配置装配引擎实例(异步:需要先决定走不走代理)。
pub async fn build(
&self,
cfg: &TranslateEngineConfig,
) -> Result<Box<dyn TranslateEngine>, TranslateError> {
let templates = self.load_settings().prompt_templates;
let client = self.select_client().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 explicit = engine_id
.map(str::trim)
.filter(|s| !s.is_empty() && *s != "auto");
if let Some(id) = explicit {
return settings
.engine(id)
.cloned()
.map(|cfg| vec![cfg])
.ok_or_else(|| TranslateError::config(format!("找不到引擎实例「{id}」")));
}
if settings.auto_fallback {
let list: Vec<TranslateEngineConfig> =
settings.auto_candidates().into_iter().cloned().collect();
if list.is_empty() {
return Err(TranslateError::config(
"没有已启用的翻译引擎,请先在翻译设置中启用至少一个",
));
}
return Ok(list);
}
// 未开启降级:只尝试默认引擎;默认引擎失效时回落到优先级最高的已启用实例
let preferred = settings
.engine(&settings.default_engine_id)
.cloned()
.or_else(|| settings.auto_candidates().first().map(|c| (*c).clone()));
preferred.map(|cfg| vec![cfg]).ok_or_else(|| {
TranslateError::config("没有已启用的翻译引擎,请先在翻译设置中启用至少一个")
})
}
/// 执行一次翻译(含自动降级)。
///
/// `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);
}
}