翻译模块

ignore更新
音乐模块调整
2026-09-17 17:32:20 +08:00 · 2026-09-15 17:30:08 +08:00 · 2026-09-15 17:17:16 +08:00 · 2026-09-12 16:29:30 +08:00 · 2026-09-12 16:23:48 +08:00 · 2026-09-12 16:16:57 +08:00
81 changed files with 14577 additions and 2217 deletions
@@ -7,10 +7,10 @@ yarn-error.log*
 pnpm-debug.log*
 lerna-debug.log*
-# 发布暂存目录
+.trae
 .workbuddy
 temp/
 release_stage/
 # musicdl 手动测试产物（search_results.pkl 等）
 musicdl_outputs/
 node_modules
@@ -1,253 +0,0 @@
 # 2026-09-12
 ## 设置页图标修复 + WebDAV 凭据加密存储 / 配置后隐藏
 - **图标不显示根因**：设置页模板用了 `HardDriveDownload` 但从未 import——`vue-tsc` 不报错（未在 script 中引用、模板解析为未知组件静默失败），**运行时图标直接消失**。以后设置页新增图标必须同步加到 lucide import 列表。
 - **WebDAV 凭据加密**：新增 Rust 命令 `webdav_get_secret` / `webdav_save_secret`（`commands.rs`，非 specta，走 raw invoke；已注册 mod.rs 导出 + lib.rs generate_handler）。Windows 用 **keyring v3（windows-native，凭据管理器，DPAPI 保护）**，service="Thing" user="webdav-credentials"，blob 为 `{"username","password"}` JSON；NoEntry 视为未配置。
 - **feiniuStore**：`WEBDAV_KEY` localStorage 现在只存 `{url, dir}`；`patchWebdav` 检测 `username/password` 字段时调 `webdav_save_secret`；`init()` 从凭据管理器加载凭据，并做一次性迁移（localStorage 有旧明文凭据 → 写入凭据管理器 + 立即改写 LS 去掉明文；用 `hasStoredSecret` 标志避免误覆盖）。`davConfig()` 仍从内存取明文传给 webdav_* 命令，链路不变。
 - **设置页 UI**：`webdavEditing` ref 控制——`webdavReady && !webdavEditing` 时显示摘要卡（服务地址/目标目录 + 「账号/密码已保存（系统凭据管理器加密存储）」），带「修改配置」「测试连接」；编辑态完整表单（密码框 type=password 本身掩码）+「收起」。
 - 校验：cargo check（新增 keyring 3.6.3）/ vue-tsc / vite build 全 0。
 ## 音乐模块全链路检查 + 排序/设置页/任务页调整
 - **模块排序**：`music/index.ts` order 55→15（代理=10 之后、整体第二）；`appStore.ts` loadSettings 增加一次性迁移（`musicOrderMigrated` 标记随设置持久化，声明在 store setup 内的非响应式 let），已保存过 moduleOrder 的用户下次启动自动把 music 移到 proxy 后，之后尊重手动拖动。
 - **隐藏 bug 修复（MusicModule.vue）**：
  1. `downloadToFeiniu` 早退分支（Rust 引擎/无下载源）未清理 `feiniuUploadingKeys` → 行按钮 spinner 永久卡死；
  2. `resolvePendingUploads` 只处理 done，临时「下载到飞牛」任务 error/cancelled/interrupted 或被手动移除时 spinner 同样卡死 → 增加失败/移除清理分支（注意：临时任务的 tempTaskIds.add 发生在任务进入 tasks 之后，watch 触发时序依赖后续状态变化再触发一次）；
  3. `feiniu.uploading` 时不再叠加触发 `uploadRecentToFeiniu`。
 - **下载任务 tabs**：去掉标题上的进行中计数（连同 `activeTaskCount` computed，noUnusedLocals 会拦未用变量）；任务卡片容器 `py-4`→`pb-4`，贴近 tabs。
 - **设置页 UI 重做**：section+Separator 改为 Card/CardHeader/CardTitle/CardContent 卡片式（max-w-2xl、gap-4、图标+text-base 标题，与 DownloaderModule 设置页一致）；「播放条常驻在所有模块底部」等过时文案改为「标题栏播放控制」。
 - 全链路审查结论：旧审查的 P0（曲库搜索失效/重启后播放键失效/双音频引擎）均已在现码修复；musicdl 事件幂等、任务持久化签名 watch、歌词二分+邻近缓存等设计良好。
 - 校验：`vue-tsc --noEmit` 0 错误，`vite build` 通过。
 ## 「下载到飞牛」改为同链路落地即传（用户实测 URL 直传失败）
 用户确认：WebDAV 测试连接 OK、下载+自动上传 OK，但发现音乐行的「下载并上传」失败（旧的 URL 拉流直传机制）。按要求改为与「下载完成后自动上传」完全同链路：
 - `downloadToFeiniu`：直接 `store.startDownload([song])`（musicdl 引擎，含引擎侧解析/代理/音质），不再手动 resolve + 拼 headers；记 `tempTaskStarts`（taskId→创建时刻，扫描下界）。
 - 任务 done → `finishTempUpload`：`uploadRecentToFeiniu(0, { since, deleteLocal: true })` 上传 → `feiniu_delete_local` 删本地音频及同名 lrc/封面 → `store.removeTask` 移除记录。**失败时保留本地文件与任务记录**供排查重试。
 - `uploadRecentToFeiniu` 扩展 opts `{ since?, deleteLocal? }`；默认行为（自动上传）不变、不删本地。
 - 后端新增 `feiniu_delete_local`（音频/歌词/封面扩展名白名单 + 拒绝目录）；**删除** `webdav_upload_from_url` 命令与 webdav.rs `upload_from_url`（机制废弃）。
 - musicdl 引擎守卫保留：Rust 引擎任务在「下载器」模块，无法回传。
 - 校验：tsc / vite / cargo 全 0。
 ## 文件服务 → WebDAV（飞牛传输改版，最终形态）
 fnOS 文件服务（WS + RSA/AES 登录）经三轮协议修复仍无法在用户 NAS 上稳定登录，且会话易失（重启要重登）。用户确认局域网场景改用标准文件协议，整体替换为 **WebDAV**（fnOS 系统设置 → 文件服务 → WebDAV，HTTP 5005/HTTPS 5006，Basic 认证，文件夹需在可见范围+团队文件夹要勾"允许协议挂载"）。
 - **删除**：`fnos.rs`（WS 客户端）、`Feiniu.fnos_sessions`、`feiniu_fnos_*` 与 `feiniu_upload_from_url` 命令、ConnectionsSettings 云朵登录弹窗。
 - **新增**：`src-tauri/src/music/feiniu/webdav.rs`——无状态：`test`（PROPFIND Depth 0）、`upload_file`（128KB 分块流式 PUT，unfold 转 Stream 免 tokio-util）、`upload_from_url`（GET 拉流→直接 PUT，本地不落地，**不再要求 Content-Length**）、`delete`；上传前逐级 MKCOL；URL 逐段百分号编码；401/403/404/409 可读错误。
 - **命令**：`webdav_test` / `webdav_upload` / `webdav_upload_from_url` / `webdav_delete`（config 由前端每次传入，serde+specta 结构 `WebDavConfig`）。
 - **前端**：`feiniuStore.webdav = {url, username, password, dir}` 持久化 `thing.music.feiniu.webdav`（密码明文 localStorage，LAN 工具可接受）；`webdavReady` computed 四项齐备；`patchWebdav` / `testWebdav`；曲库目标目录语义改为 **WebDAV 根下相对路径**。设置页「存储与上传」为配置表单 + 测试按钮 + fnOS 侧设置折叠提示；TrackItem/发现音乐「下载到飞牛」门控全部改 `webdavReady`。
 - 校验：vue-tsc / vite build / cargo check 全 0。
 ## fnOS 登录协议修复（第三轮："fnOS 登录未返回 token"）
 第二轮修复后登录请求**有响应了**（不再超时），但 rid 命中的回包里没有 token。对照 pyfnos 发现关键行为：**登录最终成功包可能不按 reqid 关联**——pyfnos 的 `_is_final_login_success` 是按内容特征（`result=="succ" && token && secret`）识别任意消息，而非按 reqid 匹配。rid 命中的那条很可能只是中间应答，带 token 的包以独立推送到达，被旧 reader 直接丢弃。
 修复（`fnos.rs`）：
 - 新增 `login_waiter` 通道；reader 对每条消息先做内容识别，命中最终成功包就投递给登录流程，reqid 匹配照旧（并容忍服务端把 reqid 回显成数字，`resp_rid` 辅助函数）。
 - `login()` 双通道等待：rid 应答里直接有 token → 用之；是中间应答 → 最多再等 8s 登录推送；send_and_wait 超时 → 再宽限 5s 等推送。
 - 识别两步验证挑战（`isBindTwofaSecret` / `isTwofaEnforced` / `accessToken`），明确报"账号开启了两步验证"而不是干等。
 - 诊断兜底：若始终等不到 token，报错里带上服务端实际回包的前 300 字符，用户可直接贴回继续定位。
 - 断开时同时唤醒登录等待者（Null）。
 `cargo check` 通过。协议参考：pyfnos `client.py`（响应扁平结构：`result/token/secret/longToken/reqid` 顶层）。
 ## fnOS 登录协议修复（第二轮："fnOS 请求超时(encrypted)"）
 上一轮修完 WS 并发缺陷后，错误变成"请求超时(encrypted)"——说明握手和 `util.crypto.getRSAPub` 都通了，**卡在登录这一条**。根因：**加密登录体里缺字段**。
 已对照两个参考实现逐字核对并修复：
 - **FNOSP/fnnas-api** `sdk/encryption.py` 的 `login_encrypt()` 示例（原开发注释里引用的就是它）
 - **Timandes/pyfnos** `fnos/client.py` 的 `_encrypt_login_data()`
 ### 正确的加密登录体（必须逐字段对齐）
 ```json
 {"reqid":"...","user":"...","password":"...","deviceType":"Browser",
 "deviceName":"...","stay":false,"req":"user.login","si":"..."}
 ```
 要点：
 - **`req: "user.login"` 必须在加密体内** —— 服务端靠它路由；缺了就静默不回包（=超时）。
 - **`reqid` 必须在加密体内**，且与 `pending` 等待者登记的 key 一致；外层 `encrypted` **不带** reqid。
 - **没有 `did` 字段**（FNOSP 示例没有；pyfnos 有但非必需，为减少变量已去掉）。
 - `stay: false`。
 - 加密方式：AES-256-CBC(key=32 字节随机 ASCII 串, iv=16 字节随机) + PKCS7，RSA 只加密那个 32 字符 key（PKCS1v1.5），全部 base64。
 ### 顺带核对过、确认我们原本就正确的部分
 - 签名：`hmac_sha256_b64(sign_key, json) + json`（签名前置）；`sign_key` = 登录响应 `secret` → AES 解密 → base64(明文) → **base64 解码后的字节**。
 - **不签名白名单**：`encrypted` / `util.getSI` / `util.crypto.getRSAPub`（已按参考实现补上 `UNSIGNED_REQ`）。
 - 后续请求不携带 token 字段，服务端靠 WS 连接 + 签名识别会话；HTTP 上传走 `Trim-Token` 头。
 - reqid 格式宽松（各实现 18~28 位不等），我们现有的 `0000000000000000<hex毫秒>` 服务端接受（getRSAPub 已验证）。
 ### 其他改动
 - `request()` 拆成 `send_and_wait(message, rid, label)` + `request()`，登录走前者以便用加密体内的 reqid 关联。
 - 错误处理补齐 `result=="fail"` 分支并带出 `msg`/`errmsg`（密码错误等现在能看到具体原因）。
 - 新增**应用层心跳**：fnOS 网关会关闭长时间无消息的连接（参考实现默认 10s 一次 `{"req":"ping"}`）。做成"发请求前按需补发"（>20s 才发），避免常驻任务的生命周期问题——多文件批量上传时 WS 不会被闲置断开。
 - 报错里的 label 更可读（如 `user.login(encrypted)`）。
 校验：`cargo check` exit 0。**仍未对真实 NAS 验证**，需要用户实测。
 ---
 ## 修复 fnOS 文件服务登录（"输入密码没反应，很久后报发送请求失败"）
 ### 根因（`src-tauri/src/music/feiniu/fnos.rs`）
 1. **WS 读写共用一个 `tokio::sync::Mutex`，且 reader 在持锁状态下 `await stream.next()`** —— `request()` 要拿同一把锁才能发送。第一次 `request()` 里 `ensure_reader()` 先 spawn 了 reader，reader 抢到锁后就在等一条永远不会发出的消息；发送方要么永久阻塞（超时也覆盖不到锁获取），要么在 reader 已退出后发送才报错 —— 这正是"等很久 → 发送请求失败"的来源。
 2. **握手没带 `Origin`**。浏览器发起的 WS 必带 `Origin`，Rust 客户端默认不带；fnOS 会据此判断来源，缺了它会"握手成功但立刻被对端关闭"。这是"连上了却什么都没发生"的典型原因。
 3. **没有回 Pong**。tungstenite 的 Stream/Sink API 不会自动回 Pong，服务端 ping 得不到响应会判定死连接。
 4. 连接/请求均**没有超时覆盖**（`timeout` 只包了 `rx`，不含锁获取与握手），主机不可达时会干等系统 TCP 重试。
 ### 修复
 - 读写分离：`futures_util::StreamExt::split(ws)` → writer 任务独占写半边（mpsc 队列），reader 独占读半边。发送不再与"等响应"争锁。
 - 握手请求改为构造 `Request` 并注入 `Origin`（由 ws url 反推 `http://host:port`）与浏览器 UA。
 - reader 显式处理 `Ping → Pong`，并记录断开原因到 `closed: Arc<Mutex<Option<String>>>`。
 - `connect_async` 加 12s 超时；`request` 的 15s 超时改为覆盖整个等待，并在入口先检查 `closed`，断开时立刻带原因报错。
 - 所有报错都带上尝试的 ws 地址或断开原因，例如 `连接 fnOS 文件服务失败：ws://ip:port/websocket?type=main → ...`。
 - 前端：`ConnectionsSettings` 的 fnOS 弹窗加 `fnosConnecting`（按钮显示"连接中…"）与弹窗内联错误块（错误里含地址/状态码，留在弹窗里可复制），并显示"当前地址"供核对。
 - `feiniuStore.fnosLogin(connectionId, ...)` 改为显式接收 connectionId 并校验它等于 activeId —— 上传命令按 `settings.feiniu_active_id` 找会话，登录非激活连接会存成永远用不上的会话。
 **注意**：以上都只做了 `cargo check` + 前端构建校验，没有对真实飞牛 NAS 验证过协议细节（`Origin` 校验、`file.checkUpload`/`Trim-Path` 约定可能随 fnOS 版本不同）。如果仍失败，报错文案已包含具体地址与失败阶段。
 ---
 ## 发现音乐：分组头去白底 + 新增「下载到飞牛」一条龙 + 飞牛上传链路修复
 ### 分组头
 `MusicModule.vue` 里源分组头原来是 `sticky top-0 z-10 bg-background/95 backdrop-blur`，在浅色背景下会形成一条白色横条。已去掉 sticky 与底色，改为普通的 `border-b border-border/60 px-2` 分组标签（px-2 与行对齐）。
 ### 新增 Rust 命令 `feiniu_upload_from_url`（下载 + 上传一条龙，本地不留文件）
 链路：前端 `feiniuStore.uploadUrlToFeiniu()` → `invoke('feiniu_upload_from_url')` → `Feiniu::fnos_upload_from_url()` → `fnos::upload_stream()`。
 - `fnos.rs` 新增泛型 `upload_stream<S, E>()`：`Part::stream_with_length(Body::wrap_stream(stream), size)`，配套 `upload_client(proxy)`（`proxy` 为空则 `no_proxy()`）。
 - `upload_file()` 重写为**流式**（`stream::unfold` + `tokio::fs::File` 分块 128KB）。原来用 `std::fs::read` 把整个文件读进内存，100MB 无损会直接吃 100MB RAM。用 unfold 是为了不引入 `tokio-util` 依赖。
 - `FnOsSession::connect` 增加 scheme 校验：`https://` 直接返回可读错误（`ws_url` 只把 `http://` 换成 `ws://`，https 会变成非法 WS scheme 并抛出难懂的 tungstenite 错误）。
 - `guess_mime(&Path)` 改为 `mime_of(&str)`（现在需要按 NAS 上的文件名推断）。
 - **依赖音源返回 `Content-Length`**（fnOS `checkUpload` 需要精确 size），缺失时返回可读错误，而不是先把整首缓冲进内存。
 - 前端 `downloadToFeiniu()`：懒解析歌曲先 `resolveSong(source, index, quality)` 拿真实链接（quality 取默认下载音质），合并 `defaultDownloadHeaders` + `defaultDownloadCookies` 为 Cookie 头，并**过滤非 ASCII 头**（reqwest 遇到非法头值会 panic，不能把外部数据直接塞进去）。
 ### 飞牛上传链路审查结论（重要）
 1. **fnOS 会话只存在内存里**（`Feiniu.fnos_sessions`），应用重启即失效 → 设置页显示的「未连接」是准确的，需要重新点云朵图标登录。已在设置页与登录弹窗里明确写出"仅本次运行有效"。
 2. **仅支持 `http://` 局域网直连**，https/frp 无法上传（协议限制），已给出明确报错。
 3. `feiniu_scan_local` 扫描 `savedir` + `feiniu_local_dirs`，因此下载到本地目录的文件能被"上传最近下载"找到；但该功能是**按 mtime 10 分钟窗口**筛选，与具体下载任务无关联——这是它不可靠的根因（这就是为什么要新增 URL 直传）。
 4. `feiniu_fnos_upload` 用 `settings.feiniu_active_id` 找连接，`fnos_login` 用传入的 connection_id；只要激活连接一致就没问题。
 ### 校验（本机 bash 不可用，PowerShell + 绝对路径）
 - `cargo check`（`src-tauri`，`%USERPROFILE%\.cargo\bin\cargo.exe`）→ exit 0，仅 3 个既有 warning
 - `vue-tsc --noEmit` → exit 0；`vite build` → exit 0
 ---
 ## 曲库左栏：去掉灰底容器、数量列对齐、行高统一
 用户反馈截图问题（灰底 + 文字竖向不齐）后的修正，`MyMusicLibrary.vue`：
 - **去掉 `bg-muted` 容器**：来源项不再包在灰色圆角块里。选中态保留 `bg-background font-medium shadow-sm`，并**补 `ring-1 ring-border`**——否则白底上的白色胶囊只有 5% 透明度的阴影，几乎看不见（顶部 Tabs 那个"可见边框"其实是 `:focus-visible` 的 ring，不是常态样式，不能照抄）。
 - **数量列始终渲染**：原来 `v-if="nav.count"` 会在 0 时隐藏整列，造成右侧数字列参差。改为无歌曲时显示 `0`，并加 `min-w-[3ch] text-right tabular-nums` 让个位数/三位数右边缘对齐。
 - **行高统一为固定值**：来源项 `h-8`、歌单子项 `h-7`，配合 `items-center`，不再依赖 `py-1.5` + 行高推算，彻底消除逐行细微的垂直错位。
 - 未选中项 hover 从 `hover:bg-accent/50` 统一为 `hover:bg-accent/60`（无容器后需要更明显的悬停反馈）。
 - 歌单子项的选中态也同步改成同一套胶囊样式，保持层级内一致。
 ---
 ## 曲库左栏收窄 + 选中态对齐顶部 Tabs + 切换动画
 `MyMusicLibrary.vue`：
 - 左栏宽度 `w-[210px]` → `w-[168px]`（"飞牛曲库 → 数量"之间的大段空白因此明显收窄）。内边距 `p-2.5` → `p-2`，字号 13px → 保留。
 - 三个来源（飞牛曲库/本地曲库/我的歌单）从裸列表改为 **`rounded-lg bg-muted p-1` 容器 + 选中项 `bg-background font-medium shadow-sm rounded-md`**，与顶部 `TabsList`/`TabsTrigger` 的默认选中态一致。
 - 歌单子树加 `border-l` 缩进表示层级；展开/收起加了 `pl-list` Transition（opacity + translateY(-6px)，0.18s）。
 - **标签截断修复**：`<span class="truncate">` 在 flex 行里不会真正截断（flex item 默认 `min-width:auto`）。改成 `min-w-0 flex-1 truncate` + 右侧计数 `shrink-0`，并去掉 `ml-auto`。以后左栏加条目记得照这个写。
 - 右栏内容切换动画：给 `<section>` 加 `:key="view"` + 全局 `tab-animate`，靠重挂载触发动画（与模块级 TabsContent 的做法一致，无需自造 Transition）。
 ---
 ## 歌单新增「编辑音乐」编辑器
 - 新组件 `src/modules/music/components/PlaylistEditorDialog.vue`（props `open` / `playlistId`，emit `update:open`）。
  - 双 Tab：**全部音乐**（来源筛选 全部/飞牛/本地 → 勾选加入；已在歌单的项置灰并标「已加入」，不可重复勾选）、**已在歌单**（勾选批量移出，勾选框用 destructive 色）。
  - 含搜索（歌名/歌手/专辑）、全选当前列表、增量渲染每批 120 + 「显示更多」、飞牛曲库「继续加载」、本地曲库未扫描时的内联「扫描本地」按钮。
  - 勾选框**不用** `Checkbox` 组件：整行是 `<button>`，视觉勾选框是纯 span（避免 label/按钮与 Checkbox 双重触发导致 net-zero toggle）。若以后要加交互型复选框，注意这个坑。
  - 关闭/打开时 `resetState()`，切 Tab 与切来源时清空选择（避免"看不见的项仍被选中"导致数量对不上）。
 - 入口：`MyMusicLibrary.vue` 歌单详情工具栏的「编辑音乐」按钮，以及歌单为空时 `Empty` 里的按钮。
 - 依赖 store 既有 API：`addToPlaylist`（内部已按 `guid+source` 去重）、`removeItemsFromPlaylist(id, keys)`（key 形如 `${source}:${guid}`）。
 ---
 ## 音乐模块播放器入口改版 + tabs 统一（在同日重构之后）
 > 本节修订上面「结构变更」里的播放器结论，以本节为准。
 - **删除底部播放条**：`GlobalPlayerBar.vue` 已删除，`App.vue` 不再渲染播放条。不要再新增底部坞站播放条。
 - **新增标题栏音乐栏** `src/components/layout/TitleBarMusic.vue`，插在 `TitleBar.vue` 里**搜索输入框的左侧**（在保存设置按钮与搜索框之间），外层包 `pointer-events-auto`，触发按钮带 `@mousedown.stop`（标题栏是 Tauri 拖拽区，不加会导致点击被拖拽吞掉）。
  - 未播放过（`store.nowPlaying` 为空）→ 只显示唱片图标，隐藏歌名。
  - 有曲目 → 图标替换为封面（`rounded-full` + `overflow-hidden`），`store.playing` 为真时用 CSS `animation-play-state` 旋转（8s/圈，暂停保留角度）。
  - 点击弹出方形控制窗（`Popover`，`w-[300px]`，约 300×340）：封面（点击进大屏）、曲目信息、`ScrubBar` 进度、循环/上下首/播放/队列、音量 `ScrubBar`、歌词/队列入口。
  - `feiniu.playError` 的 toast 消费点从 GlobalPlayerBar 移到了这里——**删播放条时容易漏掉这个 watcher**，导致播放失败静默。
 - **音乐模块 tabs 回归统一写法**：改回 `<Tabs><div ref="tabsListRef" class="shrink-0"><TabsList class="grid w-full max-w-md grid-cols-4 !bg-transparent !p-0 !shadow-none">…<TabsTrigger class="gap-1.5"><Icon class="size-3.5"/>标签</TabsTrigger>` + `<TabsContent class="mt-4 min-h-0 flex-1 tab-animate">`；模块根节点恢复 `h-full p-6 overflow-hidden flex flex-col`。`SegmentedNav` 不再被 MusicModule 使用，仅 `NowPlayingDialog` 的歌词/队列切换仍在用。
 - 发现音乐 / 任务 / 设置三块内部的横向内边距改为 `0`（由模块根 `p-6` 统一提供，避免左右不对称）。
 ---
 ## 音乐模块重构（审查之后落地实施）
 ### 结构变更（重要，改这块前先读）
 - ~~**播放器已提升到全局层**：`GlobalPlayerBar.vue` + `NowPlayingDialog.vue`~~ → 已被上一节取代；`NowPlayingDialog.vue`（大屏，含歌词/队列）保留，由标题栏方形控制窗打开。
 - **新增通用组件**：`src/components/common/ScrubBar.vue`（提交式 seek 进度条，含缓冲层/时间气泡/键盘支持）、`SegmentedNav.vue`（分段导航，现由 NowPlayingDialog 使用）。
 - **音乐模块导航**：模块级 `Tabs`（曲库/发现音乐/下载任务/设置）；「曲库」内部是 `MyMusicLibrary` 的「左侧来源树 + 右侧列表」两栏，来源树含飞牛曲库/本地曲库/我的歌单（歌单列表在树内展开）。
 - `TrackItem.vue` 重写为 44px 紧凑行（网格列 `28px 36px 1fr 74px 28px`，有专辑时多一列）；序号列悬停原位切换播放按钮，播放中显示 `.music-eq` 跳动均衡器（该 CSS 已加到 `style.css` 全局，NowPlayingDialog 复用）。
 - 所有列表表头/行网格用**字面量** Tailwind 类或内联 `gridTemplateColumns`（Tailwind v4 不识别运行时拼接的类名）。
 ### feiniuStore 关键 API 变化
 - `PlayableItem.source` 增加 `'preview'`，另加 `coverUrl` / `url` / `ext` 字段。
 - 新增 `nowPlaying`（试听优先于队列当前项）、`playPreview` / `stopPreview`、`playNext` / `addToQueue` / `removeFromQueue` / `clearQueue`、`loadMoreTracks`（分页 200/页）、`searchKeyword`（曲库搜索，之前是孤立局部变量导致搜索无效）、`playError` / `clearPlayError`、`muted` / `toggleMute`、`setPlayMode`、`bufferedPercent`、`nowPlayingTab`。
 - `playItem(item, context?)` 第二参数是播放上下文；不传则退化为单曲播放。
 - `init()` 幂等；`setCacheMode`/`clearCache` 不再中断播放；shuffle 用「待播池 + 历史栈」，自动切歌也随机；`currentLine()` 改为缓存索引 + 二分。
 - 已移除 `queueVisible` / `lyricVisible`（改用 `nowPlayingOpen` + `nowPlayingTab`）。
 - `musicStore.startDownload` 返回值改为 `{ engine, skipped, taskId? }`。
 ### 校验方式（本机 bash 工具不可用，用 PowerShell + node 直接跑）
 ```
 node node_modules/vue-tsc/bin/vue-tsc.js --noEmit -p tsconfig.json
 node node_modules/vite/bin/vite.js build
 ```
 两者在本次重构后均为 exit 0。注意：PowerShell 工具不返回 stdout，需 `| Out-File` 后再 Read；`Remove-Item` 被沙箱拦截（静默失败），删文件要用 `node -e "fs.unlinkSync(...)"`。
 排障经验：`feiniuStore` 任何「返回对象里引用了不存在的变量」（如漏掉 `clearQueue` 函数体）都会让 TS 对整个 store 的类型推断失败，进而让所有 `store.xxx` 变成 `any`，报出一堆看似无关的 `TS7006 implicitly has an 'any' type`。遇到成片 implicit any，先检查 store 自身的错误。
 ### 报告
 `MUSIC_MODULE_REVIEW.md` 已追加「§9 重构落地记录」，逐条对应 30 项改动与「仍未做」清单。
 ---
 ## 音乐模块全链路审查（数据请求 / 播放控制 / 状态管理 / UI）
 产出：
 - `MUSIC_MODULE_REVIEW.md` —— 完整审查报告（P0/P1 bug + 性能瓶颈 + 25 条界面缺陷 + 重设计方案 + 分阶段落地路径）
 - `music-redesign-mockup.html` —— 「当前实现 / 建议方案」可切换的界面改版对照稿（浅色主题）
 ### 关键结论（后续如要动这块，先看这些）
 **架构共识（不要改错方向）**
 - 搜索/解析/下载 → Python 桥接 musicdl；播放 → Rust 本地流代理 `127.0.0.1:<port>/feiniu/stream`（`src-tauri/src/music/feiniu/proxy.rs`），**真流式透传 Range，seek 依赖它，别改成前端直连 NAS**。
 - 播放内核在 `src/stores/feiniuStore.ts`（不是 musicStore）；`musicStore` 只管搜索/下载任务。
 - `PlayerBar.vue` / `PlayerFull.vue` 用的是 `useFeiniuStore`，不是 musicStore。
 **P0（确认可复现）**
 1. 飞牛曲库搜索框完全无效：`MyMusicLibrary.vue:21` 的 `keywordInput` 从未写入 `feiniuStore.keyword`，而 `loadTracks` 读的是 store 的 `keyword`（全仓无赋值点）。
 2. 重启后点播放键无反应：`restoreQueue()` 只恢复队列不设 `audio.src`，`toggle()` 里 `play()` 被空 catch 吞掉。
 3. 双音频引擎可同时发声：`MusicModule.vue:1413` 的试听 `<audio>` 与 `feiniuStore` 的 `new Audio()` 互不感知。
 **最值得优先做的一件事**
 把 `PlayerBar` + `PlayerFull` 从 `MusicModule.vue` 提升到 `App.vue` 全局层。原因：`App.vue` 的模块容器是 `:key="activeModule"` 重挂载，切到其他模块时播放条整体卸载，但音频继续播 → 用户失去所有控制入口。
 **其它已确认的坑**
 - shuffle 模式下自动切歌是顺序的（`next(manual)` 的随机分支带 `manual` 条件）。
 - `setCacheMode('stream')` / `clearCache()` 都会 `clearPlayback()`，改设置即中断播放。
 - `CacheSettings.vue` 的 `cacheEnabled` 开关从不回填 store 的 `cacheMode`，状态不同步；`cacheMax` 是死代码（后端字段是 `feiniu_cache_max_gb`）。
 - `feiniuStore.init()` 被 `MyMusicLibrary`/`CacheSettings` 重复调用，内含 `restoreQueue()` 会覆盖内存队列，应加幂等标志。
 - `musicStore` 任务持久化把每首歌的 `rawSearch` 一起写 localStorage，大歌单会爆 5MB 配额且静默失败。
 - `playItem` 未命中队列时替换整个队列（单曲播放语义），歌单里的 TrackItem 还没有双击且播放键会被 disabled → 正在播的歌无法暂停。
 - rust 下载引擎下 `doDownload` 仍跳「下载任务」tab，但该 tab 是空的（任务在下载器模块）。
 - 拖动进度条即写 `currentTime` → 流式下反复中断 Range 请求，应改「拖动预览 + 松手提交」。
 **界面主线（详见报告 §5）**
 播放条未贴底且离开模块即消失；模块左右内边距不对称（左 28 / 右 40 含滚动条）；三套切换控件（模块 Tabs / 自绘 segmented / 裸文字）；音质徽标 5 色抢戏；列表是「卡片堆」而非紧凑行；`Empty` 组件被裸 children 误用（gap-6 + md:p-12 + border-dashed 无 border）。改版方向：左侧来源树 + 紧凑表格列表 + 全宽坞站播放条 + 可折叠「正在播放」右栏。
@@ -1,31 +0,0 @@
 # 项目长期记忆（Thing / F:\AtieProject\Thing）
 Tauri + Vue 3 + Pinia + Tailwind v4 + reka-ui(shadcn-vue) 的桌面工具箱，按模块组织（`src/modules/<id>/`）。
 ## 架构约定
 - **模块挂载**：`App.vue` 的 `ModuleContainer` 用 `:key="activeModule"` 重挂载，**模块不 keep-alive**。因此任何「需要跨模块常驻」的 UI 都必须挂在 `App.vue` 层，不能放在模块内部。
 - **音乐播放器**：内核在 `src/stores/feiniuStore.ts`（不是 musicStore）；UI 入口在**标题栏** `src/components/layout/TitleBarMusic.vue`（搜索框左侧：唱片图标 + 歌名，点击弹出方形控制窗，播放中图标换封面并旋转），大屏 `src/components/layout/NowPlayingDialog.vue`（歌词/队列）由控制窗的入口打开，由 `App.vue` 渲染。`musicStore` 只负责搜索/歌单解析/下载任务。
  - 历史沿革：`PlayerBar/PlayerFull`（模块内）→ `GlobalPlayerBar`（App 全局坞站）→ 现为 `TitleBarMusic`（标题栏）。前者们均已删除，不要再新增底部播放条。
 - **模块顶部 tabs 统一写法**：`<Tabs v-model>` → `<div ref="tabsListRef" class="shrink-0">` → `<TabsList class="grid w-full max-w-md grid-cols-N !bg-transparent !p-0 !shadow-none">` → `TabsTrigger`(带 `class="gap-1.5"` + 图标) → `TabsContent class="mt-4 min-h-0 flex-1 ... tab-animate"`；模块根节点统一 `h-full p-6 overflow-hidden flex flex-col`。
  - 注意：顶部 Tabs 上那个"可见边框"是 `:focus-visible` 的 ring，并非常态样式。别处若要复刻选中态且背景也是白色，需要自己补 `ring-1 ring-border`，否则白色胶囊只靠 `shadow-sm`（5% 透明度）在白底上几乎不可见。
 - **列表/导航行的对齐**：行高用固定值（`h-8` / `h-7`）+ `items-center`，不要靠 `py-x` 推算；右侧数字列始终渲染（空时显示 `0`）并加 `min-w-[3ch] text-right tabular-nums`，否则数字列会参差。
 - 音乐播放走 Rust 本地流代理 `127.0.0.1:<port>/feiniu/stream`，**真流式透传 Range**（`src-tauri/src/music/feiniu/proxy.rs`），seek 依赖它，不要改成前端直连 NAS。
 - 模块生命周期钩子：`src/modules/<id>/index.ts` 的 `lifecycle.onActivate/onDeactivate/onEnable/onDisable`。
 - 模块内分段导航统一用 `src/components/common/SegmentedNav.vue`；进度/音量统一用 `src/components/common/ScrubBar.vue`（拖动只预览、松手才提交 seek）。
 ## 工程约定
 - **Tailwind v4**：不识别运行时拼接的类名。动态网格用内联 `gridTemplateColumns`，或把完整字面量类名写在模板里。
 - **tsconfig 开启 `noUnusedLocals` / `noUnusedParameters`**，未使用的 import 会导致构建失败。
 - 主题 token 在 `src/style.css`（`--primary` / `--muted` / `--background` 等）。**禁止硬编码** `bg-white` / `border-white/10`，否则暗色主题会失效。
 - 全局可复用动画类写在 `src/style.css`（如 `.music-eq`、`.tab-animate`）。
 - 构建校验：`npm run build`（= `vue-tsc --noEmit && vite build`）。
 ## 本机环境注意事项
 - Bash 工具在本机不可用（PATH 未初始化，`ls`/`find` 等均 not found）。用 PowerShell + 显式绝对路径的 node 执行命令。
 - PowerShell 工具**不返回 stdout**：需 `| Out-File` 写文件后再用 Read 读取。
 - `Remove-Item` 被沙箱静默拦截；删除文件用 `node -e "require('fs').unlinkSync('绝对路径')"`。
 - 受管 node：`C:\Users\Administrator\.workbuddy\binaries\node\versions\22.22.2-3\node.exe`。
 - 排障经验：Pinia setup store 里若返回对象引用了未定义变量，TS 会让整个 store 退化成 `any`，进而报出成片无关的 `TS7006 implicitly has an 'any' type`。先查 store 自身的错误。
@@ -1,465 +0,0 @@
 # 音乐模块全链路审查报告
 > 审查范围：数据请求（搜索/歌单解析/下载/解析真实链接）、播放控制（试听、播放器内核、队列、歌词、缓存）、状态管理（musicStore / feiniuStore）、UI 交互与视觉。
 > 覆盖文件（前端 11 个 + Rust 4 个）：
 > `src/stores/musicStore.ts`、`src/stores/feiniuStore.ts`、`src/modules/music/MusicModule.vue`、`components/PlayerBar.vue`、`components/PlayerFull.vue`、`components/MyMusicLibrary.vue`、`components/TrackItem.vue`、`components/settings/ConnectionsSettings.vue`、`components/settings/CacheSettings.vue`、`SourcePicker.vue`、`sources.ts`、`index.ts`、`src/App.vue`、`src/components/layout/ModuleContainer.vue`、`src-tauri/src/music/{mod,commands}.rs`、`src-tauri/src/music/feiniu/{mod,proxy}.rs`
 ---
 ## 0. 结论摘要
 整体架构是清晰的：**搜索/下载走 Python 桥接（musicdl）**，**播放走飞牛 NAS 本地流代理（Rust axum，支持 Range 透传）**，两个 store 职责分离，流代理与缓存设计是对的。问题集中在三类：
 | 类别 | 数量 | 代表问题 |
 |---|---|---|
 | P0 功能性失效 | 3 | 飞牛曲库搜索框完全无效；重启后播放键无响应；两个音频引擎可同时发声 |
 | P1 逻辑/状态缺陷 | 12 | shuffle 自动切歌不随机；缓存开关状态不同步；队列被单曲播放重置；任务持久化写入 `rawSearch` 撑爆 localStorage |
 | P2 性能瓶颈 | 9 | 拖动进度条即发 Range 请求；歌词/队列无虚拟滚动；全屏模糊背景；每行 2 个 Tooltip |
 | P3 界面与交互缺陷 | 25 | 播放条未贴底且离开模块即消失；左右内边距不对称；三套切换控件；徽标 5 色抢戏；列表变卡片堆 |
 **最需要优先决策的一件事**：把 `PlayerBar` / `PlayerFull` 从 `MusicModule.vue` 提升到 `App.vue` 全局层。当前它们挂载在音乐模块内部，而模块容器是 `:key="activeModule"` 重挂载（`App.vue:36-41`）——**切到任何其他模块，播放条和"正在播放"大屏整体卸载，但音频仍在后台播放，用户完全失去控制入口**。这是当前体验上最严重的问题。
 ---
 ## 1. P0 功能性失效（必须修）
 ### 1.1 飞牛曲库搜索框完全无效
 **现象**：输入关键词、回车，曲库列表纹丝不动。
 **根因**：`MyMusicLibrary.vue:21` 定义了本地 `keywordInput`，`onSearchInput`（:24-29）只做了防抖后调用 `store.loadTracks(1)`，而 `loadTracks` 读的是 **store 里的 `keyword`**（`feiniuStore.ts:381`）。检查全仓：`store.keyword` **从未被任何 UI 赋值**。
 ```ts
 // feiniuStore.ts:375-382
 const data = await invoke('feiniu_list_tracks', {
  page: p, size: 50,
  keyword: keyword.value.trim() || null   // ← keyword 永远是 ''
 })
 ```
 **修复**：把输入直接接到 store 字段，去掉中间层。
 ```vue
 <!-- MyMusicLibrary.vue -->
 <Input v-model="store.keyword" placeholder="搜索飞牛曲库（歌名 / 歌手）"
       @input="onSearchInput" @keydown.enter="onSearchInput" />
 ```
 ```ts
 // onSearchInput 里补一句：清空关键词时立即回全量
 function onSearchInput() {
  clearTimeout(searchTimer)
  searchTimer = setTimeout(() => store.loadTracks(1).catch(e => toast.error(String(e))), 400)
 }
 ```
 ---
 ### 1.2 应用重启后，播放键点了没反应
 **现象**：重启应用，底部播放条显示着上次的歌，点播放键没任何反应，也没有提示。
 **根因**：`restoreQueue()`（`feiniuStore.ts:644-655`）只恢复了 `queue` / `queueIndex`，**没有给 audio 设置 `src`**。此时点击播放走 `toggle()`（:564-568）：
 ```ts
 function toggle() {
  const a = ensureAudio()
  if (a.paused) a.play().catch(() => {})   // ← 无 src，play() 直接 reject，被静默吞掉
  else a.pause()
 }
 ```
 `ensureAudio()` 新建的 `Audio()` 没有 `src`，`play()` 抛 `NotSupportedError`，被空 catch 吞掉。点「上一首/下一首」反而能用（走 `playCurrent()` 会设 src），所以表现为"只有播放键坏了"。
 **修复**：`toggle()` 检测无 src 时先走一次 `playCurrent()`；同时给失败加可见提示。
 ```ts
 function toggle() {
  const a = ensureAudio()
  if (!a.src) {                 // 恢复队列后首次播放
    if (current.value) playCurrent()
    return
  }
  if (a.paused) a.play().catch(err => { playing.value = false; logger.error(`播放失败: ${err}`) })
  else a.pause()
 }
 ```
 另外建议 `startPlayback` 的 catch 里落一条 `toast.error('播放失败：' + err.message)`，当前 `:558-561` 是先 catch 再静默，用户拿不到任何信息。
 ---
 ### 1.3 两个独立音频引擎，可同时发声
 **现象**：在「发现音乐」点某首歌试听，再回到播放器播另一首 → 两首歌同时响；或者试听中点播放器播放，两路声音叠加。
 **根因**：存在两个互不知晓的 `<audio>`：
 - `MusicModule.vue:1413` —— 试听用的模板 `<audio ref="audioEl">`（`togglePlay` :372-406 驱动）
 - `feiniuStore.ts:109-126` —— 播放器内核 `new Audio()`
 二者没有互斥，`playingKey` 与 `store.playing` 彼此独立。附带问题：试听音频在**切换 tab / 卸载模块时不会停止**（模板 audio 被移除，引用置空，媒体仍可能继续播到自然结束）。
 **修复（推荐）**：废弃模块内试听 audio，试听直接走同一内核——`playQueue([{...}], 0)`，source 用 `'preview'`，播完即止。若短期不想动内核，至少在 `togglePlay` 之前 `feiniu.clearPlayback()`，并在 `onBeforeUnmount` 里 `audioEl.value?.pause()`。
 ---
 ## 2. P1 逻辑与状态缺陷
 | # | 问题 | 位置 | 说明与改法 |
 |---|---|---|---|
 | 2.1 | **shuffle 自动切歌不随机** | `feiniuStore.ts:570-586` | `next(manual)` 的随机分支带 `manual` 条件，`onEnded → next(false)` 在 shuffle 下走的是顺序 `++`。用户开了随机，一首播完却是下一首。改：把随机逻辑与 `manual` 解耦，`shuffle` 时无论手动/自动都随机（并记录已播集合避免短期重复）。 |
 | 2.2 | **prev 在 shuffle 下也是顺序** | `feiniuStore.ts:598-607` | 同上；随机模式应回退到历史栈。 |
 | 2.3 | **切缓存模式/清缓存会中断播放** | `feiniuStore.ts:266-280` | `setCacheMode('stream')` 和 `clearCache()` 都调 `clearPlayback()`；而 `CacheSettings.setEnabled(false)` 又会触发 `setCacheMode('stream')`。改设置就把歌停了，属于误伤。应只在必要（如清掉正在播的那首缓存）时停止，或改为"下一首生效"。 |
 | 2.4 | **缓存开关与真实模式不同步** | `CacheSettings.vue:13-23,32-35` | `cacheEnabled` 初始恒为 `false`，`onMounted` 只读了 `cacheMode` 没回填开关；若历史已是 cache 模式，打开设置页看到的是"关"，但实际在缓存。另外 `cacheMax = ref(5)` 是死代码（从未使用，后端对应字段是 `feiniu_cache_max_gb`），`cacheStatus` 在 onMounted 也没刷新。 |
 | 2.5 | **单曲播放会重置整个队列** | `feiniuStore.ts:500-511` | `playItem` 未命中队列时 `queue.value = [{...item}]`——用户从 2000 首的曲库点播放，队列被替换成 1 首，播完就停。播放器语义应是"以所在列表为上下文播放"。改：`playItem(item, contextList?)`，命中则跳转，未命中则以 `contextList` 建队列。 |
 | 2.6 | **歌单内的曲目无法暂停 / 无法整单播放** | `MyMusicLibrary.vue:228-233` | 歌单里的 `TrackItem` 既没有 `@dblclick`，播放按钮又被 `TrackItem.vue:71` 的 `:disabled="store.playing && store.current?.guid === item.guid"` 禁用——正在播这首时按钮变灰，**没有任何方式暂停**。且点击播放会走 2.5 的"单曲替换队列"。 |
 | 2.7 | **`init()` 被重复调用，会覆盖内存中的队列** | `feiniuStore.ts:129-157` | `MyMusicLibrary.onMounted`（:64-69）与 `CacheSettings.onMounted`（:16-20）都调 `store.init()`；`init` 内含 `restoreQueue()`，会在用户切到设置页时用 localStorage 的旧值覆盖当前队列/索引。应加 `inited` 标志位做幂等，或把 `restoreQueue` 只放在应用启动路径。 |
 | 2.8 | **任务持久化把 `rawSearch` 一起写进 localStorage** | `musicStore.ts:79-93,228-234,439` | `songsData: songs` 保留了每首歌的 `rawSearch`（上游 API 原始响应）。一个 500 首歌单任务 → 序列化后极易超过 5MB 配额，`persistTasks` 的 catch 会静默失败，历史记录随机丢失。改：持久化前剥离 `rawSearch` / `defaultDownloadHeaders`，只留重下所需字段。 |
 | 2.9 | **`pendingUploadOnDone` 泄漏，造成误上传** | `MusicModule.vue:60,74-82,483-500` | 该标志在下发下载请求时置 `true`，只有"检测到有任务 done"才清 `false`。若下载报错/被取消、或用户在选择音质弹窗点了取消，标志会残留，之后**任意一个无关任务完成**都会触发一次上传。`autoUpload` 打开时则是每个任务完成都重复全量上传一次。建议改为按 `taskId` 记录"待上传任务集合"，完成时精确消费。 |
 | 2.10 | **Rust 引擎下载后跳到空的任务页** | `MusicModule.vue:460` | `doDownload` 无条件 `activeTab.value = 'tasks'`，但 `downloadEngine === 'rust'` 时任务被交给「下载器」模块（`musicStore.ts:391-430` 不创建本模块任务），本模块任务列表是空的，用户看到"暂无下载任务"。且此时 `downloadTarget === 'feiniu'` 的自动上传链路也永远不会触发。应在 rust 引擎下改为提示"已交给下载器模块"并跳转到对应模块。 |
 | 2.11 | **`duration` 未知时拖动进度条无效** | `feiniuStore.ts:609-613`（配合 `PlayerBar.vue:18-20`） | `onProgress` 用 `store.duration` 换算秒数；若流没有返回 `Content-Length`，`loadedmetadata` 后 `duration` 为 `NaN`，`a.currentTime = NaN` 被忽略，进度条要么不动要么跳回 0。应在 `seek` 内做 `if (!isFinite(a.duration) || a.duration <= 0) return` 并给出"当前音频不支持跳转"的提示。 |
 | 2.12 | **`nowPlayingOpen` 状态跨模块残留** | `feiniuStore.ts:105` + `PlayerFull.vue:43` | 大屏开着时切走模块，Dialog 随模块卸载消失，但 `nowPlayingOpen` 仍是 `true`；回到音乐模块会突兀地自动弹出。建议改为由组件本地 `ref` 承载，或在 `onMounted` 时重置。 |
 其它可在后续清理的小项：`doneCount` 在重复 `done` 事件下会虚增（`musicStore.ts:320`）；`redownloadTask` 用的是**当前默认音质**而非原任务音质（`musicStore.ts:523`）；音质弹窗取消后 `selectedKeys` 已被清空（`MusicModule.vue:505-509`）；`installRuntime` 的进度监听清理逻辑正确，但 `installError` 与最后一条进度事件之间缺少"失败即清进度"的处理（注释已提到，代码未做）。
 ---
 ## 3. 性能瓶颈与优化点
 ### 3.1 拖动进度条 = 连续发起 Range 请求（最该改的一项）
 `PlayerBar.vue:104-110` / `PlayerFull.vue:75-80` 把 Slider 的 `update:model-value` 直接接到 `store.seek()`，而 `seek` 立刻写 `a.currentTime`。飞牛流代理是**真流式透传 Range**（`proxy.rs:131-133`），所以拖动一次会触发几十次"中断旧请求 → 发新 Range 请求"：
 - 占用带宽、NAS 侧反复建连
 - 拖动过程中出现爆音/卡顿
 - 拖到底后又从新位置重新缓冲
 **推荐**：拖动期间只更新本地"预览位置"，`pointerup` / `change` 时提交 `seek`。
 ```ts
 // 父组件维护 dragging + previewValue
 const dragging = ref(false)
 const preview = ref(0)
 function onProgressInput(v?: number[]) { dragging.value = true; preview.value = v?.[0] ?? 0 }
 function onProgressCommit(v?: number[]) {
  dragging.value = false
  store.seek(((v?.[0] ?? 0) / 100) * store.duration)
 }
 ```
 ```vue
 <Slider :model-value="[dragging ? preview : store.progress]" @update:model-value="onProgressInput" @value-commit="onProgressCommit" />
 ```
 另外 `:step="0.5"`（200 档）对 4 分钟歌 ≈ 1.2s 粒度尚可，但对播客/长音频（1 小时以上）单档 ≈ 18s，建议改为按 `duration` 动态计算 step（如 `100 / duration`）。
 ### 3.2 进度时间轴以 4Hz 驱动整棵组件树
 `timeupdate` 约每 250ms 一次写 `position.value`，凡是读它的组件都会重渲染。当前影响面：
 - `PlayerBar` + `PlayerFull` **同时挂载**（大屏打开时）→ 双份重渲染
 - `PlayerFull` 的 `currentLine()`（`feiniuStore.ts:710-717`）是**线性扫描**，每次重算 O(歌词行数)。改：缓存上次命中的索引，只在 `position > 下一行时间` 时 `idx++`（歌词已排序，单调推进），或二分查找。
 - `PlayerFull.vue:33-39` 的 `watchEffect` 每次行切换都 `querySelectorAll('[data-line]')` 全量查询后再 `scrollIntoView({behavior:'smooth'})`。改：用 `ref` 数组或在 v-for 里收集 DOM，仅对目标行滚动；并给滚动加 `prefers-reduced-motion` 降级。
 ```ts
 let lastLineIdx = -1
 function currentLine(): number {
  const lines = lyricLines.value
  if (lastLineIdx >= 0 && lastLineIdx < lines.length
      && (lastLineIdx + 1 >= lines.length || position.value < lines[lastLineIdx + 1].t)) {
    while (lastLineIdx > 0 && position.value < lines[lastLineIdx].t) lastLineIdx--
    while (lastLineIdx + 1 < lines.length && lines[lastLineIdx + 1].t <= position.value) lastLineIdx++
    return lastLineIdx
  }
  lastLineIdx = -1
  for (let k = 0; k < lines.length; k++) if (lines[k].t <= position.value) lastLineIdx = k; else break
  return lastLineIdx
 }
 ```
 同时建议歌词/队列上**虚拟滚动**：LRC 常有 80~200 行，长播放列表可上千行，当前是全量 DOM。
 ### 3.3 大屏背景的整图高斯模糊
 `PlayerFull.vue:50-52`：`<img class="h-full w-full scale-110 object-cover blur-2xl opacity-30">` 铺满整个弹窗（`min-h-[70vh]`，实际常超 900×700）。一张全尺寸图叠加 `blur-2xl` + `scale-110`，在打开期间持续占用合成/光栅资源，低端机上会明显掉帧（拖进度条时最明显）。
 **推荐**：改为一次性低分辨率方案——用同图 `size=96` 缩略图 + CSS 渐变遮罩，或直接用取色（后端返回主色）生成柔和纯色/线性渐变背景。收益远大于视觉损失。
 ### 3.4 搜索结果行每行 2 个 Tooltip 组件
 `MusicModule.vue:928-965`：每首歌行包了 2 个 `Tooltip`（reka-ui 组件 + 上下文）。首批 80 行 = 160 个 Tooltip 实例，滚动加载到 500 行 = 1000 个。挂载/更新成本高，且 Tooltip 会随列表 diff 频繁重建。
 **推荐**：列表行用原生 `title` 属性承载提示（无需组件）；只对"需要富文本提示"的 `+N` 音质档位保留一个 Tooltip。
 ### 3.5 其它
 - **下载任务聚合计算**：`taskAggDone/taskAggTotal`（`MusicModule.vue:547-548`）每次渲染都遍历全部 `songs`。一个 500 首歌的任务，每来一次进度事件就重算 500×2。改：在 `handleDownloadEvent` 里维护 `task.doneBytes/totalBytes` 增量字段。
 - **`displayItems` / `groupKeys` / `groupAllSelected`**：模板中对每个源分组头调用 `groupAllSelected`，内部 `filteredResults.filter(...)` 是 O(n)；结果集大时是 O(n × 分组数)。改：用一次 `computed` 预生成 `Map<source, keys[]>`。
 - **飞牛曲库无分页**：`loadTracks` 固定 `size: 50`，`page/total` 暴露了却没有 UI。曲库 > 50 首时后面的歌**完全访问不到**（`playAll` 也只能播前 50 首）。应加无限滚动或分页。
 - **本地扫描无上限**：`scanLocal` 一次性返回全部条目，超大音乐目录下会长时间占住主线程做映射与渲染。
 - **缓存模式首播延迟**：`feiniu_cache_fetch`（`commands.rs:421-429` → `cache_fetch`）是"**下载完整文件后返回路径**"，即 `cache` 模式下首次播放要等整首下完；而 `loadingPlay` 这个状态在 UI 上**从未被使用**（`PlayerBar`/`PlayerFull` 都没读），用户看到的是"点了没反应"。要么改用边下边播的双源策略，要么至少把 `loadingPlay` 接上 spinner。
 ---
 ## 4. 交互体验问题（按操作路径）
 **播放控制**
 1. 播放/暂停按钮 `disabled` 时无视觉降级（`PlayerBar.vue:76-84`），看起来可点却没反应。
 2. 音量图标（`PlayerBar.vue:117`）不可点击，没有"一键静音"；音量条只有 80px，长按/滚轮调节都没有。
 3. 切歌没有 crossfade，也没有间奏/淡出，切歌瞬间是硬切。
 4. 播放模式按钮图标随状态变（Repeat/Repeat1/Shuffle），初看像三个不同功能，且没有文字提示（只有 Tooltip）。
 5. 队列入口用 `ListMusic` 图标 + 数字角标，但点击是**平铺开关**（`store.queueVisible = !store.queueVisible`），而队列实际渲染在 `PlayerFull` 的右栏里——在大屏没打开时点这个图标看不到任何反馈（因为它只切了右栏的 tab，而弹窗没开）。
 6. 上一首/下一首没有"按住快进/快退"（老播放器的常见预期）。
 **进度条**
 7. 没有 hover 时间气泡、没有缓冲进度层、没有"拖动时显示预览时间"。当前拖动时只能看两侧的小字。
 8. 轨道 6px + 16px 白色圆点滑块，`Slider.vue:40` 硬编码 `bg-white`，在浅色主题下白滑块白描边几乎隐形。
 **列表切换**
 9. 发现音乐页切到「我的音乐」再切回，搜索关键词和结果**全部丢失**（模块内 tab 用 `Tabs` 非 keep-alive，`flatResults` 被重算但 store 里 `results` 还在——实际是因为 `MusicModule` 未卸载所以结果还在，但 `visibleCount` 会被 `watch(filteredResults)` 重置，滚动位置丢失）。
 10. 列表里双击行不会播放（只有点小图标才播），不符合音乐软件的肌肉记忆。
 11. 键盘：无空格播放/暂停、无 ↑↓ 选行、无 Enter 播放；所有列表行都不可聚焦。
 12. 多选操作只有"下载所选"，缺"加入歌单""加入队列""下一首播放"。
 ---
 ## 5. 界面缺陷清单（具体位置 + 改法）
 ### 5.1 结构与布局
 | # | 缺陷 | 位置 | 改法 |
 |---|---|---|---|
 | L1 | **播放条没贴底**：被模块根 `p-6` 包住，`border-t` 只在左右各缩进 24px 的宽度上出现，视觉上像一张"飘着的卡片"而非底部坞站 | `MusicModule.vue:688,1416` | 把 `PlayerBar` 提升到 `App.vue`，作为 `flex-col` 壳层的最后一行（全宽、`border-t`、`h-[72px]`）；音乐模块内容区 `pb-[72px]` 让位 |
 | L2 | **左右内边距不对称**：模块左 24px + `px-1`(4px) = 28px；右 24px + `pr-3`(12px) + `px-1` = 40px，右侧被滚动条再吃一层，卡片右边距明显窄于左边 | `MusicModule.vue:688,706-707,987-988` | 统一成 `px-6`，滚动区改成 `[&>[data-slot=scroll-area-viewport]]:pr-6` 或让 ScrollArea 用 `scrollbar-gutter: stable`，避免内边距被滚动条挤压 |
 | L3 | **三套切换控件**：模块级 `TabsList`（半透明覆盖）、`MyMusicLibrary` 自绘分段按钮（:89-114）、`PlayerFull` 的裸文字切换（:113-129）——三种视觉语言表达同一件事 | 三处 | 统一为一种 segmented 控件（建议用现有 `Tabs`/`TabsList`，或统一样式的 `ButtonGroup`），并用同一套"选中=主色底/浅底 + 中粗字"的规则 |
 | L4 | **`Empty` 组件误用**：直接塞裸 children，继承 `gap-6`(24px) 与 `md:p-12`(48px)，图标与文案间距过大且垂直被撑高；`border-dashed` 没有宽度声明，虚线框实际不显示 | `MusicModule.vue:801-809, 977-980`、`MyMusicLibrary.vue:76-83,135-140` | 用组件既定的子结构：`EmptyMedia / EmptyTitle / EmptyDescription`；或给容器加 `border` + `border-dashed`、`gap-3`、`p-8` |
 | L5 | **横向 Tab 与子 Tab 层级混乱**：顶层 4 个 tab 里，「我的音乐」内部又横排 3 个子 tab，「设置」内部又竖排 5 张卡；导航成本高 | `MusicModule.vue:691-696`、`MyMusicLibrary.vue:88-114` | 见 §6 的"左侧来源树 + 右侧主区"结构，把两级 tab 压成一级 |
 | L6 | **首屏被低价值信息占据**：「下载到 本地/飞牛」占一整个卡片行（`MusicModule.vue:709-726`），说明文字是 12px 灰字却放在最显眼位置；真正的搜索框被挤到第二行 | `MusicModule.vue:708-794` | 把"下载目标"收进搜索工具栏右侧的 `Select`（与源选择器同排），或放进设置页；首行只留 搜索输入 + 源选择 + 搜索按钮 |
 | L7 | **歌单详情页底部孤零零一个"移除最后一首"按钮** | `MyMusicLibrary.vue:234-243` | 语义错误，删掉。改为：行 hover 显示「⋯」菜单（从歌单移除 / 上移 / 下移），或支持多选后批量移除 |
 | L8 | **歌单左栏无滚动**：`grid-cols-[220px_1fr]`，左栏是普通 `div`，歌单多了会撑高整页 | `MyMusicLibrary.vue:189-205` | 左栏用 `ScrollArea` 并固定高度（`h-[calc(100vh-260px)]`），或整体改三栏布局 |
 | L9 | **设置页信息密度过低 + 语义重复**：「飞牛音乐连接」管连接，「上传到飞牛曲库」又要求用户回头去前一张卡点云朵登录；5 张卡片纵向拉得很长 | `MusicModule.vue:1123-1371` | 合并为「连接与存储」一张卡：连接列表 + NAS 文件服务登录 + 曲库目录 + 自动上传；「播放缓存」并入「播放」分组；「环境检查」做成折叠的"诊断"面板 |
 ### 5.2 视觉与色彩
 | # | 缺陷 | 位置 | 改法 |
 |---|---|---|---|
 | V1 | **音质徽标 5 色抢戏**：Hi-Res=琥珀、无损=紫、320K=天蓝、192K=橙、128K=锌灰，一行里 2 个高饱和徽标 + 1 个 `+N`，视觉噪音压过歌名 | `MusicModule.vue:336-355, 879-905` | 降为**两档**：无损/高解析用实心浅色徽标（一个色），其余用 `outline` 中性色；颜色不承担"档位"信息，档位靠文字。或改为歌名后的一个小图标 + Tooltip 详情 |
 | V2 | **列表变成卡片堆**：每行 `border` + `rounded-lg` + `p-2.5` + `space-y-2`，80 行 = 80 张卡，行间 8px 空隙，扫描效率低 | `MusicModule.vue:845-859` | 改紧凑单行：行高 44~48px、无独立边框、`border-b border-border/60` 或干脆无分隔、hover `bg-accent/60`；表头一行（`# / 标题 / 专辑 / 时长 / 操作`） |
 | V3 | **源分组头与大卡片行不匹配**：分组头只是 12px 小字，紧贴一堆 56px 卡片 | `MusicModule.vue:848-857` | 分组头改 `sticky top-0 z-10 bg-background/95 backdrop-blur` + 底部分隔线，字号 13px medium；或改用左侧来源 Tab 过滤，取消组内嵌头 |
 | V4 | **当前播放项用"选中态"表达**：`border-primary bg-primary/10` 在浅色主题下是"近黑边框 + 10% 黑底"，像复选框选中而非"正在播放" | `TrackItem.vue:53-54` | 改为：左侧 3px 主色竖条 + 歌名主色 + 一个 12px 的跳动均衡器图标；hover 与 active 语义分离 |
 | V5 | **`PlayerFull` 硬编码白色边框**：`border-l border-white/10`，浅色主题下完全不可见 | `PlayerFull.vue:112` | 改用 `border-border` |
 | V6 | **`PlayerFull` 背景被"洗白"**：整图 `opacity-30` + 白→白渐变，浅色下糊成一片；同时是持续 GPU 开销 | `PlayerFull.vue:50-53` | 改为缩略图小尺寸模糊，或纯色/双色线性渐变（从封面取色）；浅色主题下用极浅的封面色调，深色主题下用暗化封面色 |
 | V7 | **滑块基本不可见**：`Slider.vue:40` 硬编码 `bg-white`，16px 白色滑块 + 白色描边叠在浅底上；轨道仅 6px | `Slider.vue:36-41` | 滑块改 `bg-background` + 主色描边（或直接用 `bg-primary`）；静息轨道 4px、hover/拖动时平滑增到 8px；加 `transition-[height]` |
 | V8 | **`PlayerFull` 歌词行区分度不足**：非当前行 `text-muted-foreground/60`，当前行仅 `font-medium text-foreground`，没有位置指示 | `PlayerFull.vue:136-145` | 当前行放大到 17~18px + `text-foreground` + 左侧或下方主色指示；两侧行逐级降透明度（60/40/25）形成景深；点击区域扩大到整行并加 hover 背景 |
 | V9 | **`PlayerFull` 进度时间只在下方一行小字**，且控制按钮组与进度条分属两个块，视觉不聚合 | `PlayerFull.vue:74-108` | 进度条与控制键合并为一块：`[时间] ──●──── [时间]` 上、`[模式][上一首][播放][下一首][队列]` 下的居中控制簇 |
 | V10 | **「词」按钮用单个汉字**当歌词开关 | `PlayerBar.vue:125-132` | 换成 `Lyrics` 图标（`FileText`/`MicVocal`），与两侧图标风格一致 |
 | V11 | **下载任务标题行过载**：状态标签 + 歌名 + 歌手 + 音质标签 + 已下载/总量 + 最多 4 个图标按钮挤在一行；且 `Card` 被 `gap-0 py-0` + `CardContent py-2` 覆盖，内边距与模块内其它卡片不一致 | `MusicModule.vue:995-1060` | 拆两行：第一行 `[状态] 歌名 · 歌手 ……… [音质] [⋯菜单]`；第二行进度条 + 大小 + "打开目录/取消/重下"收进 `⋯` 菜单。`Card` 统一 `p-0` + 内部 `p-3` |
 | V12 | **多曲目任务行进度条只有 56px**（`w-14`），几乎读不出进度；错误信息被截断到 112px | `MusicModule.vue:1086-1097` | 进度条改占满剩余宽度（去掉固定宽度，放歌名下方一行）；错误信息用 Tooltip 或点击展开 |
 | V13 | **`TrackItem` 悬停才出现的播放按钮占 40px 固定宽度**，未悬停时标题左侧留出空白列，触屏/键盘用户无法触发 | `TrackItem.vue:68-75` | 改为：封面左下角 24px 半透明播放浮层（hover 显现），或整行 hover 时标题左侧淡入小图标；并支持双击整行播放 |
 | V14 | **飞牛曲库行/本地曲库行/歌单行的"来源"标识不统一**：本地用行内小标签「本地」，飞牛没有标识，歌单混排时无法区分 | `TrackItem.vue:81` | 统一在行尾或封面角标显示来源（NAS 云图标 / 本机图标），并在歌单详情里按来源分组或加筛选 |
 | V15 | **搜索历史下拉不适合键盘操作**：`@focusout` 关闭 + `@mousedown.prevent` 的组合同样让 Tab 导航无法进入历史项 | `MusicModule.vue:738-760` | 改用 `Combobox`/`Popover` + `Command` 组件（仓库已有 `components/ui/combobox`），支持 ↑↓ 选择、Enter 确认、Esc 关闭 |
 | V16 | **`+N` 音质档位靠 Tooltip**，触屏不可达；`visibleTiers` 固定展示 2 个，长歌名下把歌名挤窄 | `MusicModule.vue:888-904` | 行内只留 1 个"最高音质"徽标，全部档位收进右侧 `⋯` 菜单或点击弹出 popover |
 | V17 | **`PlayerBar` 缺少播放态反馈**：`loadingPlay` 未接 UI；NAS 慢时点播放毫无反应 | `PlayerBar.vue:76-84` | 播放键上叠加 spinner（`loadingPlay` 时），或封面加旋转/脉冲 |
 | V18 | **`PlayerBar` 三段留白失衡**：左侧信息 `max-w-44`，中间控制区 `flex-1` 里塞了模式/上下首/播放/队列 + 进度条，右侧音量+词+最大化；窄窗口下中间进度条被压到很短 | `PlayerBar.vue:34-141` | 采用标准三段：左 `w-[240px]` 固定、中 `flex-1 min-w-0`（控制 + 进度）、右 `w-[200px]`（音量/词/大屏）；窄容器下用 `container query` 渐进隐藏音量条与歌词按钮 |
 | V19 | **`TabsList` 同时带 `grid w-full max-w-md` 与组件默认 `inline-flex w-fit`**，并靠 `!p-0 !bg-transparent !shadow-none` 强行覆盖 | `MusicModule.vue:691` | 不要用覆盖式改写；把"模块级分段导航"抽成一个 `SegmentedNav` 组件（`grid grid-cols-N`、`bg-muted p-0.5`、激活项 `bg-background shadow-sm`） |
 | V20 | **封面圆角/阴影规格不统一**：列表 40px `rounded-md`、播放条 44px `rounded-md shadow`、大屏 256px `rounded-xl shadow-2xl` | 多处 | 定规格：列表 6px 无阴影、播放条 6px 无阴影、大屏 12px + `ring-1 ring-border/60` 无重阴影 |
 | V21 | **下载任务空态文案指向错误**：「去"搜索"页选择歌曲下载」，但 tab 已改名为「发现音乐」 | `MusicModule.vue:991` | 改为"去「发现音乐」页选择歌曲下载" |
 | V22 | **`PlayerFull` 未提供音量、队列收起、下一首信息**；队列项没有播放态指示（只有 `bg-primary/10`） | `PlayerFull.vue:147-163` | 补：右上角音量滑条；队列项用序号↔均衡器切换表示当前项，hover 显示"下一首播放/移除" |
 | V23 | **`ConnectionsSettings` 图标按钮语义不明**：`Power` 既表示"激活"又表示"登出"，两个含义相同的图标相邻 | `ConnectionsSettings.vue:157-171` | 激活用 `CircleCheck`/`RadioButton`，登出用 `LogOut`，删除保留 `Trash2`；并为所有 icon-only 按钮补 `Tooltip` + `aria-label` |
 | V24 | **歌单/曲库的「播放全部」用文字 `▶ 播放全部`**，与其他按钮的图标风格不统一 | `MyMusicLibrary.vue:115-117,214-216` | 统一为图标 + 文字：`<Play class="size-4"/> 播放全部` |
 | V25 | **`MusicModule` 里两处搜索框文案不一致**（"输入歌名/歌手/专辑关键词" vs "粘贴歌单链接"）且歌单解析行的 Input 靠 `border-0 bg-transparent` 融进容器，缺少"这是一行输入"的暗示 | `MusicModule.vue:730-782` | 歌单解析改为折叠的"粘贴歌单链接"次级入口（默认收起），避免与主搜索竞争注意力 |
 ---
 ## 6. 重设计方案
 ### 6.1 参考基准
 - **Spotify / Apple Music**：左侧来源树 + 中间列表 + 底部全宽播放条 + 右侧可折叠"正在播放"。
 - **网易云音乐 / QQ 音乐**：紧凑表格行（`# / 标题 / 歌手 / 专辑 / 时长`）、行内 hover 操作、双击播放、底部播放条 + 播放列表面板。
 - **foobar2000 / MusicBee**：信息密度高、可排序表头、键盘优先。
 本项目的定位是"NAS 曲库 + 本地曲库 + 多平台搜索下载"的**工具型播放器**，建议取 **Spotify 的骨架 + 网易云的列表密度**，避免做成消费级流媒体的强视觉风格。
 ### 6.2 目标信息架构（三级 tab → 一级导航）
 ```
 音乐
 ├── 曲库
 │   ├── 飞牛曲库        (NAS 曲目，分页/无限滚动 + 搜索 + 排序)
 │   ├── 本地曲库        (扫描目录，按文件夹浏览)
 │   └── 我的歌单        (歌单列表 → 歌单详情，可拖拽排序)
 ├── 发现音乐            (多平台搜索 + 歌单解析 + 下载)
 ├── 下载任务            (进行中 / 已完成 分组)
 └── 设置                (连接与存储 / 播放 / 下载 / 诊断，用左侧锚点或分段)
 ```
 把「我的音乐」内部的 3 个子 tab 提升为导航的一级子项（来源树），「设置」内部的 5 张卡片改为分组锚点。
 ### 6.3 布局结构（目标）
 ```
 ┌───────────────────────────────────────────────────────────────────────┐
 │ TitleBar（含模块浮动切换器）                                            │
 ├──────────┬──────────────┬─────────────────────────────────────────────┤
 │ Sidebar  │ 来源树        │ 内容主区                                     │
 │ （模块）  │ 240px        │  ┌ 固定工具栏 ────────────────────────────┐  │
 │          │              │  │ 搜索  来源筛  音质筛  排序   多选操作    │  │
 │          │ 曲库          │  ├ 表头 (# 标题 歌手 专辑 时长 操作) ──────┤  │
 │          │  · 飞牛曲库    │  │ 44px 紧凑行，hover 显示操作             │  │
 │          │  · 本地曲库    │  │ 播放中：主色竖条 + 跳动的均衡器          │  │
 │          │  · 我的歌单    │  │ ...                                    │  │
 │          │ 发现音乐      │  └────────────────────────────────────────┘  │
 │          │ 下载任务      │                                              │
 │          │ 设置          │         （可选右栏 320px：正在播放/歌词/队列） │
 ├──────────┴──────────────┴─────────────────────────────────────────────┤
 │ MiniPlayer 72px（全宽坞站：左曲目 中控制+进度 右音量/歌词/大屏）           │
 └───────────────────────────────────────────────────────────────────────┘
 ```
 要点：
 1. **MiniPlayer 提升到 `App.vue`**，全宽贴底、不参与任何模块内边距；音乐模块内容区 `pb-[72px]`。这样在任何模块都能控制播放。
 2. **`PlayerFull` 也提升到 `App.vue`**（全局 Dialog/Overlay），解决跨模块残留问题。
 3. **去掉"模块级横向 Tab"**，音乐模块内部用来源树；`useModuleTabs` 仍可保留，用于把来源树的第一级注册给 TitleBar 浮动切换器（保持现有能力）。
 4. **右栏"正在播放"可折叠**：窄窗口默认收起，宽窗口（≥1280px）默认展开，用 `container query` 或 `useMediaQuery` 决定。
 ### 6.4 视觉规范（建议写入项目 Design Token）
 | 项目 | 规范 |
 |---|---|
 | 主色使用 | 只用于：主操作按钮、播放中指示、"正在播放"高亮。**不用于**徽标分类、分组头 |
 | 中性色阶 | 文本 `foreground` / 次文本 `muted-foreground` / 三级文本 `muted-foreground/70`；分隔线 `border/60`；hover 面 `accent/60` |
 | 圆角 | 行/输入 6px（`radius-md`）、卡片 10px（`radius-lg`）、大图 12px、头像/封面圆形仅用于单曲大图 |
 | 阴影 | 列表与播放条**不用阴影**，靠 `border` 分层；只有 Dialog/Popover 用 `shadow-lg` |
 | 行高 | 列表行 44px（紧凑）/ 48px（标准）；表头 32px |
 | 字号 | 歌名 14px/500，歌手·专辑 12px/400，时长时间数字 12px `tabular-nums` |
 | 徽标 | 一类语义一个样式：状态用实心浅底，属性（音质/格式）用 `outline` 中性色 + 文字；不超过 2 个 |
 | 动效 | 仅 `opacity` / `transform`，120~180ms `ease-out`；进度条高度过渡 150ms；尊重 `prefers-reduced-motion` |
 | 明暗主题 | **禁止硬编码** `bg-white` / `border-white/10` / `text-white`；一律走 token |
 | 空状态 | 统一 `EmptyMedia(32px 图标) → EmptyTitle(14px) → EmptyDescription(12px)`，`gap-3`、`p-10`、无边框 |
 ### 6.5 关键组件规格
 **MiniPlayer**
 ```
 高度 72px | 全宽 | border-t | bg-background/85 backdrop-blur
 左 240px ：封面 48px(6px 圆角) + 歌名 14px/500 截断 + 歌手 12px 截断 + ♥
 中 flex-1：① [模式][上一首][播放 40px 圆形主色][下一首][队列] 居中
           ② [时间 00:00] ──进度条(hover 4→8px，含缓冲层)── [总时长]  居中 max-w-[560px]
 右 200px ：音量图标(可点静音) + 音量条 96px | 歌词 | 大屏 | （窄屏只留大屏）
 播放中：封面右侧叠加 3 条均衡器动效；`loadingPlay` 时播放键显示 spinner
 ```
 **列表行（TrackItem 重写）**
 ```
 [#/均衡器 24px] [封面 40px] [标题 14px/500 + 歌手 12px] [专辑 12px 可隐藏] [时长 12px tabular] [⋯ hover 显示]
 高度 44px | 无边框 | border-b border-border/50 | hover:bg-accent/60 | 当前项：左侧 3px 主色条 + 标题主色
 双击整行播放；⋯ 菜单：下一首播放 / 加入队列 / 加入歌单 / 查看文件位置 / 下载
 ```
 **进度条交互**
 ```
 拖动中：只更新预览位置 + 显示时间气泡；轨道加粗；不写 currentTime
 释放时：一次性 seek；若 duration 未知则禁用拖动并提示"该音频不支持跳转"
 缓冲层：在轨道里用 bg-muted-foreground/25 画已缓冲区间（audio.buffered）
 ```
 ---
 ## 7. 落地路径（按性价比排序）
 | 阶段 | 内容 | 影响面 | 预估 |
 |---|---|---|---|
 | **S1 修 Bug（不做设计变更）** | 1.1 搜索框绑定 store.keyword；1.2 `toggle()` 无 src 兜底；1.3 试听与播放器互斥（或合并内核）；2.1/2.2 shuffle 自动切歌；2.4 缓存开关回填；2.7 `init` 幂等；2.8 持久化剥离 `rawSearch` | 仅改逻辑，风险低 | 半天 |
 | **S2 播放器骨架调整** | 3.1 拖动提交式 seek；3.2 歌词行索引缓存；3.3 大屏背景降级；4.1 播放键 loading 态；L1/V18 MiniPlayer 全宽贴底；V5/V7 主题 token 修正 | 播放条 + 大屏 | 1~2 天 |
 | **S3 列表与信息架构** | V2 紧凑列表；V1 徽标降噪；V3 分组头；V13/V4 TrackItem 重写；L6 首屏工具栏重构；2.5 上下文队列；2.6 歌单播放/暂停 | 发现音乐 + 曲库 | 3~4 天 |
 | **S4 结构性重构** | §6.2/6.3 左侧来源树 + 全局播放条；PlayerBar/PlayerFull 提升到 App.vue；右栏正在播放；设置页分组 | 模块外壳 | 1 周 |
 | **S5 体验补全** | 键盘快捷键、虚拟滚动、分页/无限滚动、拖拽排序歌单、音质档位 popover、缓冲层、桌面歌词 | — | 按需 |
 **建议先做 S1 + S2**：S1 全是低风险的逻辑修复，S2 集中在两个组件文件里，能立刻解决"卡顿 + 没有控制感 + 拖动难用"的主观感受；S4 的结构调整等到前面稳定后再动，避免一次改动面过大。
 ---
 ## 8. 附：值得保留的设计
 - 流代理走 `127.0.0.1` 动态端口 + `Cookie` 注入 + **Range 透传**（`proxy.rs`）——这是正确做法，seek 能真正生效，不要改成前端直连。
 - 桥接进程按需拉起、禁用模块时停止（`music/index.ts:34-45`）——避免了常驻 Python 进程。
 - `tasksSignature` 轻量签名代替深度 watch（`musicStore.ts:257-266`）——思路正确（只是 payload 需要瘦身）。
 - 搜索结果**懒解析**（搜索阶段拿档位、播放/下载前才解析真实链接）+ `rawSearch` 支持隔夜链接重解析（`musicStore.ts:355-370,458`）——设计合理。
 - 发现音乐列表的**增量渲染 + IntersectionObserver 哨兵**（`MusicModule.vue:265-305`）——方向正确，可平滑迁移为新列表的基础。
 ---
 ## 9. 重构落地记录（本次已实施）
 ### 9.1 新增文件
 | 文件 | 作用 |
 |---|---|
 | `src/components/layout/TitleBarMusic.vue` | 标题栏音乐栏：唱片图标 + 歌名，点击弹出**方形播放控制窗** |
 | `src/modules/music/components/PlaylistEditorDialog.vue` | 歌单音乐编辑器：从全部音乐勾选加入 / 批量移出 |
 | `src/components/layout/NowPlayingDialog.vue` | 「正在播放」大屏（封面 + 控制 + 歌词 / 队列），由方形控制窗的「歌词 / 队列」入口打开 |
 | `src/components/common/ScrubBar.vue` | 通用拖拽进度条：**拖动只预览、松手才 seek**，含缓冲层与时间气泡 |
 | `src/components/common/SegmentedNav.vue` | 分段导航（现由 `NowPlayingDialog` 的「歌词 / 队列」切换使用） |
 `PlayerBar.vue` / `PlayerFull.vue` 已删除；`GlobalPlayerBar.vue` 曾短暂作为全局坞站播放条存在，现已被标题栏音乐栏取代并删除。
 **播放器入口最终形态**：标题栏搜索框左侧的音乐栏（`TitleBarMusic`）——未播放过时只显示唱片图标；有曲目后图标替换为封面并随播放旋转，右侧显示截断歌名。点击弹出约 300×340 的方形控制窗（封面 / 曲目信息 / 进度 / 循环·上下首·播放·队列 / 音量 / 歌词·队列入口），点击封面或「歌词 / 队列」进入大屏。
 ### 9.2 修复的缺陷
 **P0**
 1. 飞牛曲库搜索框：直接 `v-model="store.searchKeyword"` 并新增 `loadTracks(page, append)` + `loadMoreTracks()`，搜索真正生效且支持分页续拉。
 2. 重启后播放键失效：`toggle()` 在 `audio` 无 src 时先按当前条目装载（试听或队列当前曲），失败原因经 `playError` 冒泡成 toast。
 3. 双音频引擎：删除模块内试听 `<audio>`，试听改走 `feiniu.playPreview()`，与队列播放**共用同一个 audio 实例**，天然互斥。
 **P1**
 4. shuffle 自动切歌：`next()` 不再区分手动/自动，随机模式下都从「待播池」抽取；新增切歌历史栈，`prev()` 在随机模式下真正回退。播放模式持久化。
 5. 缓存模式：`setCacheMode` / `clearCache` 不再调用 `clearPlayback`，改设置不中断播放。
 6. 缓存开关状态：`CacheSettings` 的开关改为 `cacheMode` 的双向 computed，删除死代码 `cacheMax`，补 `ensureCacheStatus` 刷新。
 7. `init()` 幂等化（`inited` 标志），不会再覆盖内存队列。
 8. 任务持久化：超过 1.5MB 时自动剥离 `rawSearch` / `defaultDownloadHeaders` 后重试。
 9. 上传触发：`pendingUploadOnDone` 布尔标志改为 `uploadOnDoneTaskIds` 任务集合 + `uploadedTaskIds` 去重表，每个任务最多触发一次；启动时的历史任务不触发重传。
 10. Rust 引擎下载：`startDownload` 返回 `{ engine, skipped, taskId }`；Rust 引擎不再跳到空的任务页，改为提示到「下载器」查看；「下载到飞牛 + Rust 引擎」组合直接给出可读的错误提示并阻止。
 11. 队列语义：`playItem(item, context?)` 支持以所在列表为播放上下文，解决「从大曲库点一首就只剩一首」；新增 `playNext` / `addToQueue` / `removeFromQueue`。
 12. `done` 事件幂等，`doneCount` 不再虚增；`redownloadTask` 沿用原任务音质。
 **性能**
 13. 提交式 seek（`ScrubBar`），拖动不再触发几十次 Range 请求中断重建。
 14. 歌词行索引由 O(n) 全量扫描改为「命中缓存微调 + 未命中二分」，并缓存上次索引。
 15. 大屏背景从「整图 `blur-2xl scale-110`」改为主题色径向渐变，去掉持续 GPU 开销。
 16. 列表行去掉 reka Tooltip（改用原生 `title` + 单个 Popover 展示音质档位），500 行不再产生 1000 个组件实例。
 17. 歌词滚动用函数 ref 收集节点，不再每次 `querySelectorAll`。
 18. 播放队列增量渲染（每批 200 行）。
 19. 曲库分页 200/页 + 滚动续拉；任务明细进度条由固定 56px 改为占满剩余宽度。
 **交互与视觉**
 20. 播放入口改到**标题栏**：移除模块内播放条与全局坞站播放条，在自定义标题栏搜索框左侧新增音乐栏（唱片图标 + 歌名，未播放过时隐藏歌名）；点击弹出方形控制窗；播放中图标替换为封面并旋转。
 21. 音乐模块顶部 tabs 改回与其余模块完全一致的写法：`<Tabs><div ref="tabsListRef"><TabsList class="grid w-full max-w-md grid-cols-4 !bg-transparent !p-0 !shadow-none">` + `TabsTrigger` + `TabsContent class="mt-4 min-h-0 flex-1 ... tab-animate"`，根节点恢复为 `h-full p-6 overflow-hidden flex flex-col`。
 22. 三级 tab 压成「模块 tab → 曲库内左侧来源树」两级。左栏由 `w-[210px]` 收窄到 `w-[168px]`，来源项的选中态对齐顶部 Tabs（`rounded-lg bg-muted` 容器 + `bg-background shadow-sm` 胶囊），歌单子树用 `border-l` 缩进 + 展开动画；右栏内容切换加 `tab-animate`（`:key="view"` 重挂载触发），不再生硬。
 23. 首屏工具栏：搜索框回到首行，下载目标 / 来源筛选 / 音质筛选收到筛选条，歌单解析收进 Popover。
 24. 列表改 44px 紧凑行：无独立边框、hover 高亮、双击整行播放、序号列悬停原位切换为播放按钮（不再出现 40px 空白列）；播放中行用 `music-eq` 跳动均衡器 + 主色文字。
 25. 音质徽标由 5 色降为单枚中性 outline 徽标 + Popover 详情。
 26. `Empty` 全部改为组件既定结构（`EmptyMedia` / `EmptyTitle` / `EmptyDescription`）。
 27. 歌单：删除语义奇怪的「移除最后一首」，改为行内「⋯」菜单的支持上移 / 下移 / 移除；新增重命名；左侧歌单列表可独立滚动。
 28. **歌单页新增「编辑音乐」**（`components/PlaylistEditorDialog.vue`）：双 Tab 编辑器——「全部音乐」按来源（全部 / 飞牛 / 本地）勾选加入，已在歌单的曲目置灰标记「已加入」不可重复勾选；「已在歌单」批量勾选移出。含搜索、全选当前列表、增量渲染（每批 120）、飞牛曲库续拉、本地未扫描时的内联扫描入口。
 29. 源分组头去掉 `sticky` 与白色底色（原 `bg-background/95 backdrop-blur` 会在浅色背景上形成白色横条）。
 30. **发现音乐每行新增「下载到飞牛」**（试听 / 下载右侧）：走新增的 Rust 命令 `feiniu_upload_from_url`，由后端边拉音源边传给 NAS，**本地不落地文件**；懒解析歌曲会先按默认音质解析真实链接，并合并 `defaultDownloadHeaders` + `defaultDownloadCookies`（过滤非 ASCII 头，避免 reqwest panic）。
 31. 设置页从「5 张卡片」改为「连接 / 存储与上传 / 播放 / 搜索与下载 / 环境与诊断（折叠）」分组，并把「NAS 文件服务登录」并入存储分组。
 32. 主题一致性：删除 `border-white/10`、`bg-white` 等硬编码；滑块、均衡器、进度条全部走 `--primary` / `--muted` / `--background` token。
 33. 连接管理图标语义修正（激活用 `CircleCheck`、登出用 `LogOut`），全部 icon-only 按钮补齐 `title` + `aria-label`。
 34. 搜索历史下拉改为 `focusin/focusout` 容器判定，Tab 键可以进入历史项。
 ### 9.2.1 飞牛上传链路：fnOS 文件服务 → WebDAV（最终形态）
 > 演进：multipart over WS 的 fnOS 文件服务存在会话易失、握手/登录协议联调困难等问题（三轮修复：
 > WS 读写分离与 Origin → 加密登录体补 `req`/`reqid` → 登录结果双通道等待），最终整体替换为 **WebDAV**。
 | 结论 | 说明 |
 |---|---|
 | **协议选型** | fnOS 提供的 SMB / WebDAV / FTP / NFS 中选 **WebDAV**：纯 HTTP 语义、reqwest 即可实现、Basic 认证随请求携带**无会话**（重启免登录）；SMB 的 Rust 客户端生态差、FTP 明文且被动模式易出问题、NFS 无 Windows 客户端方案 |
 | 后端实现 | `src-tauri/src/music/feiniu/webdav.rs`（`fnos.rs` 已删除）：`test`（PROPFIND Depth 0）/ `upload_file`（本地文件 128KB 分块流式 PUT）/ `delete`；上传前逐级 MKCOL 补目录 |
 | 「下载到飞牛」机制 | **与自动上传同链路**：正常走 musicdl 下载（引擎侧解析/代理/音质）→ 任务完成后扫描下载目录（下界=任务创建时刻）→ WebDAV 上传 → 删除本地音频及同名歌词/封面（`feiniu_delete_local`，扩展名白名单）→ 移除任务记录。失败时保留本地文件与任务记录供排查。早期的「URL 拉流直传」（`webdav_upload_from_url`）因可靠性不足已移除 |
 | 前端配置 | `feiniuStore.webdav = { url, username, password, dir }` 持久化 localStorage（`thing.music.feiniu.webdav`）；`webdavReady` 四项齐备才放行上传；设置页「存储与上传」分组内配置 + 「测试连接」 |
 | fnOS 侧设置 | 系统设置 → 文件服务 → WebDAV 开启（HTTP 5005 / HTTPS 5006）；目标文件夹在「可见文件夹范围」内；团队文件夹需勾选「允许通过文件共享协议挂载」；账号需读写权限（已写成设置页折叠提示） |
 | 路径语义 | 目标目录是 **WebDAV 根下的相对路径**（不是 NAS 内部绝对路径），URL 逐段百分号编码 |
 | 错误可读化 | 401 认证失败 / 403 无权限 / 404 目录不存在或不在可见范围 / 409 父目录不存在，均带上下文 |
 ### 9.3 校验
 ```
 vue-tsc --noEmit   → exit 0（0 error）
 vite build         → exit 0（11.5s）
 cargo check        → exit 0
 ```
 ### 9.4 仍未做的部分（建议后续）
 - 键盘全局快捷键（空格播放/暂停、↑↓ 选行）——需接入项目既有快捷键体系，避免与输入框冲突。
 - 列表虚拟滚动（当前为增量渲染，千级以上仍有优化空间）。
 - 歌单拖拽排序（`vue-draggable-plus` 已在依赖中，可直接接入）。
 - 本地文件的时长 / 内嵌封面解析（当前时长列退化为文件大小）。
 - 缓存模式改为「边下边播」的双源策略（当前 `cache` 模式首播仍需等整首下完）。
@@ -1,430 +0,0 @@
 <!DOCTYPE html>
 <html lang="zh-CN">
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>音乐模块 · 界面改版对照稿</title>
 <style>
  * { box-sizing: border-box; margin: 0; padding: 0; }
  :root{
    --bg:#f4f4f5; --panel:#ffffff; --panel-2:#fafafa; --line:#e7e7e9; --line-2:#f0f0f1;
    --fg:#18181b; --fg-2:#71717a; --fg-3:#a1a1aa;
    --primary:#18181b; --primary-fg:#fafafa; --accent:#f4f4f5;
    --ok:#0f7b4f; --warn:#9a3412; --err:#b91c1c;
  }
  body{
    font-family: system-ui,-apple-system,"Segoe UI","Microsoft YaHei","PingFang SC",sans-serif;
    background:var(--bg); color:var(--fg); font-size:13px; line-height:1.55; padding:28px 20px 60px;
    -webkit-font-smoothing:antialiased;
  }
  .wrap{ max-width:1180px; margin:0 auto; }
  h1{ font-size:19px; font-weight:600; letter-spacing:-.01em; }
  .sub{ color:var(--fg-2); font-size:12.5px; margin-top:4px; }
  .toolbar{ display:flex; align-items:center; gap:10px; margin:18px 0 14px; flex-wrap:wrap; }
  .seg{ display:inline-flex; background:#e9e9eb; border-radius:8px; padding:3px; gap:2px; }
  .seg button{
    border:0; background:transparent; font:inherit; font-size:12.5px; color:var(--fg-2);
    padding:6px 14px; border-radius:6px; cursor:pointer; transition:.15s;
  }
  .seg button.on{ background:#fff; color:var(--fg); font-weight:500; box-shadow:0 1px 2px rgba(0,0,0,.08); }
  .hint{ color:var(--fg-3); font-size:12px; }
  /* ---------- window frame ---------- */
  .win{
    background:var(--panel); border:1px solid var(--line); border-radius:11px; overflow:hidden;
    box-shadow:0 8px 28px rgba(0,0,0,.07); display:flex; flex-direction:column; height:640px;
  }
  .titlebar{
    height:38px; flex:0 0 38px; display:flex; align-items:center; gap:8px; padding:0 12px;
    background:var(--panel-2); border-bottom:1px solid var(--line);
  }
  .dots{ display:flex; gap:5px; }
  .dots i{ width:9px; height:9px; border-radius:50%; background:#dcdce0; display:block; }
  .tb-title{ font-size:12px; color:var(--fg-2); margin-left:6px; }
  .tb-tabs{ margin-left:auto; display:flex; gap:4px; }
  .tb-tabs span{ font-size:11px; color:var(--fg-2); padding:3px 9px; border-radius:5px; }
  .tb-tabs span.on{ background:#e9e9eb; color:var(--fg); }
  .body{ flex:1; display:flex; min-height:0; }
  /* ---------- left module rail ---------- */
  .rail{
    width:52px; flex:0 0 52px; border-right:1px solid var(--line); background:var(--panel-2);
    display:flex; flex-direction:column; align-items:center; gap:4px; padding:10px 0;
  }
  .rail i{
    width:32px; height:32px; border-radius:8px; background:#ececed; display:grid; place-items:center;
    font-size:12px; color:var(--fg-2); font-style:normal;
  }
  .rail i.on{ background:var(--primary); color:#fff; }
  /* ---------- source tree ---------- */
  .tree{ width:186px; flex:0 0 186px; border-right:1px solid var(--line); padding:12px 10px; background:var(--panel); }
  .tree h4{ font-size:11px; color:var(--fg-3); font-weight:500; padding:6px 8px 4px; letter-spacing:.03em; }
  .tree a{
    display:flex; align-items:center; gap:8px; padding:6px 8px; border-radius:6px;
    color:var(--fg-2); text-decoration:none; font-size:12.5px; margin-bottom:1px;
  }
  .tree a.on{ background:#ececed; color:var(--fg); font-weight:500; }
  .tree a b{ margin-left:auto; font-weight:400; font-size:11px; color:var(--fg-3); }
  /* ---------- main ---------- */
  .main{ flex:1; min-width:0; display:flex; flex-direction:column; background:var(--panel); }
  .main-head{ padding:12px 16px 10px; border-bottom:1px solid var(--line-2); display:flex; align-items:center; gap:8px; }
  .field{
    height:30px; border:1px solid var(--line); border-radius:7px; background:#fff;
    display:flex; align-items:center; padding:0 10px; color:var(--fg-3); font-size:12.5px; flex:1; max-width:330px;
  }
  .btn{ height:30px; padding:0 12px; border-radius:7px; border:1px solid var(--line); background:#fff; color:var(--fg); font-size:12.5px; display:inline-flex; align-items:center; gap:5px; }
  .btn.dark{ background:var(--primary); color:#fff; border-color:var(--primary); }
  .main-body{ flex:1; min-height:0; overflow:hidden; }
  .thead{
    display:grid; grid-template-columns:34px 44px minmax(0,3fr) minmax(0,2fr) 52px 34px;
    gap:10px; align-items:center; padding:6px 16px; border-bottom:1px solid var(--line-2);
    font-size:11px; color:var(--fg-3);
  }
  .row{
    display:grid; grid-template-columns:34px 44px minmax(0,3fr) minmax(0,2fr) 52px 34px;
    gap:10px; align-items:center; padding:5px 16px; height:44px; border-bottom:1px solid var(--line-2);
  }
  .row:hover{ background:var(--accent); }
  .row.on{ background:#f4f4f5; }
  .row.on .t1{ color:var(--fg); font-weight:500; }
  .idx{ font-size:11.5px; color:var(--fg-3); text-align:right; }
  .eq{ display:flex; align-items:flex-end; gap:2px; height:12px; }
  .eq i{ width:2.5px; background:var(--primary); border-radius:1px; display:block; }
  .eq i:nth-child(1){ height:5px } .eq i:nth-child(2){ height:11px } .eq i:nth-child(3){ height:8px }
  .cov{ width:36px; height:36px; border-radius:6px; background:#e9e9eb; }
  .t1{ font-size:13px; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
  .t2{ font-size:11.5px; color:var(--fg-2); white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
  .tag{ font-size:10px; padding:1px 6px; border-radius:4px; border:1px solid var(--line); color:var(--fg-2); white-space:nowrap; }
  .tag.solid{ background:#ececed; border-color:transparent; }
  .dur{ font-size:11.5px; color:var(--fg-3); font-variant-numeric:tabular-nums; text-align:right; }
  .more{ color:var(--fg-3); text-align:center; opacity:0; }
  .row:hover .more{ opacity:1; }
  /* ---------- right now playing ---------- */
  .np{ width:250px; flex:0 0 250px; border-left:1px solid var(--line); padding:16px; display:flex; flex-direction:column; gap:12px; background:var(--panel); }
  .np-cover{ width:100%; aspect-ratio:1; border-radius:10px; background:linear-gradient(150deg,#e8e8ea,#d6d6da); }
  .np h3{ font-size:14px; font-weight:500; }
  .np p{ font-size:12px; color:var(--fg-2); }
  .lyric{ display:flex; flex-direction:column; gap:7px; margin-top:4px; }
  .lyric span{ font-size:12.5px; color:var(--fg-3); }
  .lyric span.on{ font-size:14px; color:var(--fg); font-weight:500; }
  /* ---------- player bar ---------- */
  .player{
    flex:0 0 72px; height:72px; border-top:1px solid var(--line); background:rgba(255,255,255,.92);
    backdrop-filter:blur(12px); display:flex; align-items:center; gap:14px; padding:0 16px;
  }
  .pl-left{ width:236px; flex:0 0 236px; display:flex; align-items:center; gap:10px; min-width:0; }
  .pl-left .cov{ width:44px; height:44px; border-radius:6px; }
  .pl-mid{ flex:1; min-width:0; display:flex; flex-direction:column; align-items:center; gap:4px; }
  .pl-ctrl{ display:flex; align-items:center; gap:16px; color:var(--fg-2); }
  .pl-play{ width:34px; height:34px; border-radius:50%; background:var(--primary); color:#fff; display:grid; place-items:center; font-size:11px; }
  .pl-seek{ width:100%; max-width:520px; display:flex; align-items:center; gap:8px; }
  .pl-seek .time{ font-size:10.5px; color:var(--fg-3); font-variant-numeric:tabular-nums; width:34px; }
  .track{ flex:1; height:4px; border-radius:2px; background:#e4e4e7; position:relative; }
  .track .buf{ position:absolute; inset:0 auto 0 0; width:34%; background:#d4d4d8; border-radius:2px; }
  .track .fill{ position:absolute; inset:0 auto 0 0; width:22%; background:var(--primary); border-radius:2px; }
  .track .knob{ position:absolute; left:22%; top:50%; width:10px; height:10px; margin:-5px 0 0 -5px; border-radius:50%; background:var(--primary); }
  .pl-right{ width:196px; flex:0 0 196px; display:flex; align-items:center; justify-content:flex-end; gap:10px; color:var(--fg-2); }
  .vol{ width:76px; height:4px; border-radius:2px; background:#e4e4e7; position:relative; }
  .vol i{ position:absolute; inset:0 auto 0 0; width:70%; background:var(--primary); border-radius:2px; display:block; }
  /* ---------- before view ---------- */
  .before-pad{ padding:22px 22px 0; flex:1; min-height:0; display:flex; flex-direction:column; gap:14px; overflow:hidden; }
  .b-tabs{ display:grid; grid-template-columns:repeat(4,1fr); max-width:430px; background:#ececed; border-radius:8px; padding:3px; font-size:12.5px; text-align:center; }
  .b-tabs span{ padding:5px 0; border-radius:6px; color:var(--fg-2); }
  .b-tabs span.on{ background:#fff; color:var(--fg); font-weight:500; }
  .b-card{ border:1px solid var(--line); border-radius:9px; padding:9px 12px; display:flex; align-items:center; gap:10px; font-size:12.5px; }
  .b-card.muted{ background:#fafafa; }
  .b-row{ border:1px solid var(--line); border-radius:9px; padding:9px 11px; display:flex; align-items:center; gap:11px; margin-bottom:7px; }
  .b-sub{ display:inline-flex; gap:3px; background:#ececed; border-radius:7px; padding:3px; font-size:12px; }
  .b-sub span{ padding:4px 11px; border-radius:5px; color:var(--fg-2); }
  .b-sub span.on{ background:var(--primary); color:#fff; }
  .b-player{ border-top:1px solid var(--line); margin:0 22px; padding:10px 0; display:flex; align-items:center; gap:12px; }
  .mark{
    width:17px; height:17px; border-radius:50%; background:#b91c1c; color:#fff; font-size:10.5px;
    display:inline-grid; place-items:center; flex:0 0 17px; font-weight:500;
  }
  .mark.g{ background:#0f7b4f; }
  .mark.amber{ background:#b45309; }
  /* ---------- legend ---------- */
  .legend{ margin-top:20px; display:grid; grid-template-columns:repeat(auto-fit,minmax(310px,1fr)); gap:10px; }
  .li{ background:#fff; border:1px solid var(--line); border-radius:9px; padding:11px 13px; display:flex; gap:10px; }
  .li b{ display:block; font-size:12.5px; font-weight:500; margin-bottom:2px; }
  .li p{ font-size:12px; color:var(--fg-2); }
  .hide{ display:none !important; }
  .note{ font-size:11.5px; color:var(--fg-3); margin-top:6px; }
 </style>
 </head>
 <body>
 <div class="wrap">
  <h1>音乐模块 · 界面改版对照稿</h1>
  <p class="sub">左边是当前实现的实际问题，右边是按建议方案重排后的目标形态。改版要点见下方图例。</p>
  <div class="toolbar">
    <div class="seg" id="seg">
      <button data-v="before" class="on">当前实现</button>
      <button data-v="after">建议方案</button>
    </div>
    <span class="hint" id="hint">红/橙标记 = 缺陷位置</span>
  </div>
  <!-- ================= BEFORE ================= -->
  <div class="win" id="view-before">
    <div class="titlebar">
      <div class="dots"><i></i><i></i><i></i></div>
      <span class="tb-title">Thing</span>
      <div class="tb-tabs"><span class="on">我的音乐</span><span>发现音乐</span><span>下载任务</span><span>设置</span></div>
    </div>
    <div class="body">
      <div class="rail">
        <i class="on">音</i><i>载</i><i>监</i><i>代</i><i>设</i>
      </div>
      <div class="before-pad">
        <div style="display:flex;align-items:center;gap:10px">
          <div class="b-tabs">
            <span class="on">我的音乐</span><span>发现音乐</span><span>下载任务</span><span>设置</span>
          </div>
        </div>
        <div style="display:flex;align-items:center;gap:10px">
          <span class="b-sub"><span class="on">飞牛曲库</span><span>本地曲库</span><span>我的歌单</span></span>
          <span class="hint">← 第二套切换控件，与上一行风格不同</span>
          <span class="mark" style="margin-left:auto">3</span>
        </div>
        <div class="b-card">
          <span class="hint">下载到</span>
          <span class="tag">本地目录 ▾</span>
          <span class="hint">下载到本地目录（musicdl）</span>
          <span class="mark" style="margin-left:auto">1</span>
        </div>
        <div style="display:flex;gap:8px;align-items:center">
          <div class="field" style="max-width:none">输入歌名 / 歌手 / 专辑关键词</div>
          <span class="tag">已选 3 个源 ▾</span>
          <span class="btn dark">搜索</span>
        </div>
        <div class="b-card muted">
          <span class="hint">粘贴歌单链接（网易云 / QQ 音乐等）</span>
          <span class="btn" style="margin-left:auto">解析歌单</span>
        </div>
        <div style="margin-top:2px">
          <div class="b-row">
            <span class="tag">☐</span><div class="cov" style="width:38px;height:38px"></div>
            <div style="flex:1;min-width:0">
              <div class="t1">海阔天空 <span class="tag" style="color:#7c3aed">无损 flac 32.4 MB</span> <span class="tag" style="color:#0369a1">320K mp3</span> <span class="tag">+2</span></div>
              <div class="t2">Beyond · 乐与怒</div>
            </div>
            <span class="tag">05:21</span><span class="tag">▷</span><span class="tag">⤓</span>
            <span class="mark">2</span><span class="mark">5</span>
          </div>
          <div class="b-row">
            <span class="tag">☐</span><div class="cov" style="width:38px;height:38px"></div>
            <div style="flex:1;min-width:0">
              <div class="t1">光辉岁月 <span class="tag" style="color:#b45309">Hi-Res flac 96.1 MB</span> <span class="tag" style="color:#a16207">192K mp3</span></div>
              <div class="t2">Beyond · 命运派对</div>
            </div>
            <span class="tag">04:58</span><span class="tag">▷</span><span class="tag">⤓</span>
            <span class="mark">2</span>
          </div>
          <div class="b-row">
            <span class="tag">☐</span><div class="cov" style="width:38px;height:38px"></div>
            <div style="flex:1;min-width:0">
              <div class="t1">喜欢你</div><div class="t2">Beyond · 秘密警察</div>
            </div>
            <span class="tag">04:35</span><span class="tag">▷</span><span class="tag">⤓</span>
            <span class="mark">6</span>
          </div>
          <span class="note">每行都是独立圆角卡片 + 8px 间距；一行内 6~8 个视觉元素，彩色徽标抢过歌名。</span>
        </div>
      </div>
    </div>
    <div class="b-player">
      <div class="cov" style="width:44px;height:44px;border-radius:6px"></div>
      <div style="min-width:0;max-width:150px">
        <div class="t1">未播放</div><div class="t2">选择一首歌曲开始播放</div>
      </div>
      <div style="flex:1;display:flex;flex-direction:column;align-items:center;gap:4px">
        <div class="pl-ctrl" style="font-size:13px"><span>⟳</span><span>⏮</span><span class="pl-play">▶</span><span>⏭</span><span>☰</span></div>
        <div class="pl-seek" style="max-width:360px">
          <span class="time">--:--</span>
          <div class="track"><div class="fill" style="width:0"></div><div class="knob" style="left:0"></div></div>
          <span class="time">--:--</span>
        </div>
      </div>
      <div class="pl-right"><span>🔊</span><div class="vol"><i></i></div><span>词</span><span>⤢</span></div>
      <span class="mark" style="position:absolute">4</span>
    </div>
    <div style="position:relative">
      <span class="mark" style="position:absolute;right:14px;bottom:44px">7</span>
      <span class="mark" style="position:absolute;left:14px;bottom:60px">8</span>
    </div>
  </div>
  <!-- ================= AFTER ================= -->
  <div class="win hide" id="view-after">
    <div class="titlebar">
      <div class="dots"><i></i><i></i><i></i></div>
      <span class="tb-title">Thing</span>
      <div class="tb-tabs"><span class="on">曲库</span><span>发现音乐</span><span>下载任务</span><span>设置</span></div>
      <span class="mark g" style="margin-left:8px">3</span>
    </div>
    <div class="body">
      <div class="rail">
        <i class="on">音</i><i>载</i><i>监</i><i>代</i><i>设</i>
      </div>
      <div class="tree">
        <h4>曲库</h4>
        <a class="on">飞牛曲库 <b>1.2k</b></a>
        <a>本地曲库 <b>318</b></a>
        <a>我的歌单 <b>7</b></a>
        <h4>其他</h4>
        <a>发现音乐</a>
        <a>下载任务 <b>2</b></a>
        <a>设置</a>
        <span class="mark g" style="margin:10px 0 0 8px">3</span>
      </div>
      <div class="main">
        <div class="main-head">
          <div class="field">搜索歌名 / 歌手 / 专辑</div>
          <span class="tag">全部来源 ▾</span>
          <span class="tag">全部音质 ▾</span>
          <span class="btn" style="margin-left:auto">排序 ▾</span>
          <span class="btn">扫描本地</span>
          <span class="btn dark">▶ 播放全部</span>
          <span class="mark g" style="margin-left:6px">1</span>
        </div>
        <div class="main-body">
          <div class="thead">
            <span style="text-align:right">#</span><span></span><span>标题</span><span>专辑</span><span style="text-align:right">时长</span><span></span>
          </div>
          <div class="row on">
            <span class="idx"><span class="eq"><i></i><i></i><i></i></span></span>
            <div class="cov"></div>
            <div style="min-width:0">
              <div class="t1">海阔天空</div>
              <div class="t2">Beyond · 1993</div>
            </div>
            <div class="t2">乐与怒</div>
            <span class="dur">05:21</span>
            <span class="more">⋯</span>
          </div>
          <div class="row">
            <span class="idx">2</span>
            <div class="cov"></div>
            <div style="min-width:0"><div class="t1">光辉岁月</div><div class="t2">Beyond</div></div>
            <div class="t2">命运派对</div>
            <span class="dur">04:58</span>
            <span class="more">⋯</span>
          </div>
          <div class="row">
            <span class="idx">3</span>
            <div class="cov"></div>
            <div style="min-width:0"><div class="t1">喜欢你</div><div class="t2">Beyond</div></div>
            <div class="t2">秘密警察</div>
            <span class="dur">04:35</span>
            <span class="more">⋯</span>
          </div>
          <div class="row">
            <span class="idx">4</span>
            <div class="cov"></div>
            <div style="min-width:0"><div class="t1">冷雨夜</div><div class="t2">Beyond</div></div>
            <div class="t2">现代舞台</div>
            <span class="dur">04:12</span>
            <span class="more">⋯</span>
          </div>
          <div class="row">
            <span class="idx">5</span>
            <div class="cov"></div>
            <div style="min-width:0"><div class="t1">真的爱你</div><div class="t2">Beyond</div></div>
            <div class="t2">Beyond IV</div>
            <span class="dur">04:41</span>
            <span class="more">⋯</span>
          </div>
          <div style="padding:8px 16px" class="note">
            行高 44px、无独立边框、hover 高亮、双击整行播放；播放中行用主色竖条 + 均衡器表示，不再用“选中框”。
            <span class="mark g">2</span>
          </div>
        </div>
      </div>
      <div class="np">
        <div class="np-cover"></div>
        <div>
          <h3>海阔天空</h3>
          <p>Beyond · 乐与怒</p>
        </div>
        <div class="track" style="height:4px"><div class="fill" style="width:38%"></div><div class="knob" style="left:38%"></div></div>
        <div class="lyric">
          <span>今天我 寒夜里看雪飘过</span>
          <span>怀着冷却了的心窝漂远方</span>
          <span class="on">风雨里追赶 雾里分不清影踪</span>
          <span>天空海阔你与我</span>
          <span>可会变（谁没在变）</span>
        </div>
        <span class="note">右栏“正在播放”可折叠（窄窗口自动收起）</span>
      </div>
    </div>
    <div class="player">
      <div class="pl-left">
        <div class="cov"></div>
        <div style="min-width:0">
          <div class="t1">海阔天空</div>
          <div class="t2">Beyond · 乐与怒</div>
        </div>
        <span class="mark g" style="margin-left:auto">4</span>
      </div>
      <div class="pl-mid">
        <div class="pl-ctrl"><span>🔀</span><span>⏮</span><span class="pl-play">❚❚</span><span>⏭</span><span>☰</span></div>
        <div class="pl-seek">
          <span class="time">01:12</span>
          <div class="track"><div class="buf"></div><div class="fill"></div><div class="knob"></div></div>
          <span class="time">05:21</span>
        </div>
        <span class="note" style="margin:0">拖动只更新预览，松手才 seek；轨道含缓冲层，hover 加粗到 8px</span>
      </div>
      <div class="pl-right">
        <span class="mark g">5</span>
        <span>🔊</span><div class="vol"><i></i></div><span>詞</span><span>⤢</span>
      </div>
    </div>
  </div>
  <div class="legend" id="legend">
    <div class="li"><span class="mark">1</span><div><b>首屏信息层级</b><p>“下载到 本地/飞牛”不再独占一行卡片，收进工具栏；搜索框回到首行黄金位置。</p></div></div>
    <div class="li"><span class="mark">2</span><div><b>列表密度与徽标降噪</b><p>卡片堆 → 44px 紧凑表格行；音质徽标从 5 色降为 1 类中性 outline，档位详情收进 ⋯ 菜单。</p></div></div>
    <div class="li"><span class="mark">3</span><div><b>两级横向 Tab → 左侧来源树</b><p>模块级 Tab + 子 Tab 合并为一条来源树，导航层级从三层降到两层。</p></div></div>
    <div class="li"><span class="mark g">4</span><div><b>播放条全宽贴底</b><p>MiniPlayer 提升到 App 全局层：任何模块都能控制播放；离开音乐模块不再丢失控制入口。</p></div></div>
    <div class="li"><span class="mark g">5</span><div><b>进度与音量交互</b><p>提交式 seek + 缓冲进度层；音量图标可点静音；滑块配色改走主题 token（原为硬编码纯白）。</p></div></div>
    <div class="li"><span class="mark">6</span><div><b>来源与来源标识统一</b><p>本地/NAS/歌单混排时用统一图标标识来源，不再靠行内小标签。</p></div></div>
    <div class="li"><span class="mark">7</span><div><b>内边距不对称</b><p>模块左 28px / 右 40px（含滚动条），卡片右边距明显偏窄；统一为 24px 并保留滚动条槽位。</p></div></div>
    <div class="li"><span class="mark">8</span><div><b>播放条未贴底</b><p>被模块 p-6 包住，分隔线左右各缩进 24px，读作“漂浮卡片”而非底部坞站。</p></div></div>
  </div>
 </div>
 <script>
  var seg = document.getElementById('seg');
  var before = document.getElementById('view-before');
  var after = document.getElementById('view-after');
  var hint = document.getElementById('hint');
  seg.addEventListener('click', function (e) {
    var b = e.target.closest('button');
    if (!b) return;
    var v = b.getAttribute('data-v');
    seg.querySelectorAll('button').forEach(function (x) { x.classList.toggle('on', x === b); });
    before.classList.toggle('hide', v !== 'before');
    after.classList.toggle('hide', v !== 'after');
    hint.textContent = v === 'before' ? '红/橙标记 = 缺陷位置' : '绿色标记 = 改版要点';
  });
 </script>
 </body>
 </html>
@@ -1,7 +1,7 @@
 {
  "name": "thing",
  "private": true,
-  "version": "26.9.1",
+  "version": "26.9.3",
  "type": "module",
  "scripts": {
    "dev": "vite",
@@ -1,16 +0,0 @@
 import sys, importlib.util
 sys.stdout.reconfigure(encoding="utf-8")
 from musicdl.modules.sources.qq import QQMusicClient
 from musicdl.modules.sources.netease import NeteaseMusicClient
 from musicdl.modules.sources.kugou import KugouMusicClient
 from musicdl.modules.utils.qqutils import SongFileType
 # find MUSIC_QUALITIES in source modules
 for mod in (QQMusicClient, NeteaseMusicClient, KugouMusicClient):
    src = mod.__module__
    m = getattr(mod, 'source', '?')
    names = [x for x in mod.__init__.__globals__.keys() if 'QUALIT' in x.upper()]
    print("SRC", m, "quality-names-in-globals:", names)
    for n in names:
        v = mod.__init__.__globals__[n]
        print("   ", n, "=", v)
 print("QQ SORTED_QUALITIES:", SongFileType.SORTED_QUALITIES.value)
@@ -1,21 +0,0 @@
 import sys, json, importlib.util
 sys.stdout.reconfigure(encoding="utf-8")
 spec = importlib.util.spec_from_file_location("bridge", r"d:\Atie\Gitea\Thing\src-tauri\src\music\bridge.py")
 b = importlib.util.module_from_spec(spec); spec.loader.exec_module(b)
 client = b.get_client(["QQMusicClient"])
 res = client.search("海阔天空")
 s = res["QQMusicClient"][0]
 rs = (s.raw_data or {}).get("search")
 src = b._get_resolve_client("QQMusicClient")
 print("raw song:", s.song_name, "| id", s.identifier)
 # official alone, lossless_quality_is_sufficient=False, no cap
 from musicdl.modules.utils.data import SongInfo
 official = src._parsewithofficialapiv1
 r2 = official(search_result=rs, song_info_flac=SongInfo(source="QQMusicClient"), lossless_quality_is_sufficient=False)
 print("official-only uncapped -> ext=", getattr(r2,"ext",None), "valid=", getattr(r2,"with_valid_download_url",None))
 for target in ("", "最高", "无损", "320K", "128K"):
    r = b._resolve_song(src, rs, target)
    print("target=%r ->" % target, "ext=", getattr(r,"ext",None), "bitrate=", getattr(r,"bitrate",None), "valid=", getattr(r,"with_valid_download_url",None))
 # verify constant restored
 import musicdl.modules.utils.qqutils as qq
 print("restored SORTED len:", len(qq.SongFileType.SORTED_QUALITIES.value))
@@ -54,17 +54,18 @@ $tauriConf = Join-Path $Root 'src-tauri\tauri.conf.json'
 $cargoToml = Join-Path $Root 'src-tauri\Cargo.toml'
 $pkgJson   = Join-Path $Root 'package.json'
-$t = Get-Content $tauriConf -Raw
+# UTF-8 安全读写：`Get-Content` 默认按系统 ANSI(如 GBK) 解码，会把本就含中文/乱码的文件二次编码损坏（曾导致
-$t = $t -replace '("version"\s*:\s*")[^"]*(")', "`${1}$Version`${2}"
+# Cargo.toml 的 keyring 依赖行被弄丢）。这里统一用显式 UTF-8 无 BOM 读写，保证逐字节稳定往返。
-[System.IO.File]::WriteAllText($tauriConf, $t, (New-Object System.Text.UTF8Encoding($false)))
+function Set-Utf8Version([string]$Path, [string]$Pattern, [string]$NewVersion) {
  $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
  $content = [System.IO.File]::ReadAllText($Path, $utf8NoBom)
  $content = $content -replace $Pattern, "`${1}$NewVersion`${2}"
  [System.IO.File]::WriteAllText($Path, $content, $utf8NoBom)
 }
-$c = Get-Content $cargoToml -Raw
+Set-Utf8Version -Path $tauriConf -Pattern '("version"\s*:\s*")[^"]*(")' -NewVersion $Version
-$c = $c -replace '(?m)^(version\s*=\s*")[^"]*(")', "`${1}$Version`${2}"
+Set-Utf8Version -Path $cargoToml -Pattern '(?m)^(version\s*=\s*")[^"]*(")' -NewVersion $Version
-[System.IO.File]::WriteAllText($cargoToml, $c, (New-Object System.Text.UTF8Encoding($false)))
+Set-Utf8Version -Path $pkgJson   -Pattern '("version"\s*:\s*")[^"]*(")' -NewVersion $Version
 $p = Get-Content $pkgJson -Raw
 $p = $p -replace '("version"\s*:\s*")[^"]*(")', "`${1}$Version`${2}"
 [System.IO.File]::WriteAllText($pkgJson, $p, (New-Object System.Text.UTF8Encoding($false)))
 Write-Step "版本号已同步：tauri.conf.json / Cargo.toml / package.json"
 # ---------- 2. 构建 ----------
@@ -3318,6 +3318,32 @@ dependencies = [
 "scopeguard",
 ]
 [[package]]
 name = "lofty"
 version = "0.22.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ca260c51a9c71f823fbfd2e6fbc8eb2ee09834b98c00763d877ca8bfa85cde3e"
 dependencies = [
 "byteorder",
 "data-encoding",
 "flate2",
 "lofty_attr",
 "log",
 "ogg_pager",
 "paste",
 ]
 [[package]]
 name = "lofty_attr"
 version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed9983e64b2358522f745c1251924e3ab7252d55637e80f6a0a3de642d6a9efc"
 dependencies = [
 "proc-macro2",
 "quote",
 "syn 2.0.118",
 ]
 [[package]]
 name = "log"
 version = "0.4.33"
@@ -3934,6 +3960,15 @@ dependencies = [
 "objc2-foundation",
 ]
 [[package]]
 name = "ogg_pager"
 version = "0.7.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9d36b1d6964c3ac92b7aea701057e02b6b91143d70d83b20abf75a231a3c0216"
 dependencies = [
 "byteorder",
 ]
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -6149,9 +6184,10 @@ dependencies = [
 [[package]]
 name = "thing"
-version = "26.9.1"
+version = "26.9.3"
 dependencies = [
 "aes",
 "async-trait",
 "axum 0.7.9",
 "base64 0.22.1",
 "bytes",
@@ -6163,6 +6199,7 @@ dependencies = [
 "image",
 "keyring",
 "librqbit",
 "lofty",
 "md-5",
 "notify",
 "rand 0.8.8",
@@ -0,0 +1,19 @@
 {
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "translate-popup",
  "description": "Capability for the non-activating translate popup window",
  "windows": ["translate-popup"],
  "permissions": [
    "core:default",
    "core:window:allow-hide",
    "core:window:allow-show",
    "core:window:allow-close",
    "core:window:allow-set-theme",
    "core:window:allow-set-effects",
    "core:window:allow-set-background-color",
    "core:window:allow-start-dragging",
    "core:event:allow-listen",
    "core:event:allow-emit",
    "snap-layout:default"
  ]
 }
@@ -12,6 +12,7 @@ use specta::Type;
 use super::monitor::start_monitor;
 use super::reader::{write_dib, write_files, write_text};
 use super::storage::Storage;
 use super::suppress::SuppressState;
 use windows_sys::Win32::System::DataExchange::GetClipboardSequenceNumber;
 /// 剪贴板设置（持久化到 clipboard/settings.json）
@@ -56,8 +57,9 @@ impl Default for ClipboardSettings {
 pub struct ClipboardManager {
    storage: Arc<Storage>,
    settings: Arc<Mutex<ClipboardSettings>>,
-    /// 本应用 copy_back 写入后的剪贴板序列号，用于跳过自身写入产生的记录
+    /// 写入抑制状态。由本模块持有（谁启动监听谁负责），但**对其他模块开放**：
-    suppress: Arc<Mutex<Option<u32>>>,
+    /// 划词取词会连续改三次剪贴板，同样需要屏蔽，见 `super::suppress`。
    suppress: Arc<SuppressState>,
    monitor_stop: Arc<AtomicBool>,
    monitor_handle: Mutex<Option<JoinHandle<()>>>,
    settings_path: PathBuf,
@@ -75,7 +77,7 @@ impl ClipboardManager {
        };
        let settings_path = clip_dir.join("settings.json");
        let settings = Arc::new(Mutex::new(load_settings(&settings_path)));
-        let suppress = Arc::new(Mutex::new(None));
+        let suppress = Arc::new(SuppressState::new());
        let monitor_stop = Arc::new(AtomicBool::new(true));
        Self {
            storage,
@@ -167,7 +169,7 @@ impl ClipboardManager {
            // 绑定到写入完成后的剪贴板序列号：仅跳过本次写入产生的记录，
            // 用户后续复制（序列号不同）不会被误吞。
            let seq = unsafe { GetClipboardSequenceNumber() };
-            *self.suppress.lock().unwrap_or_else(|e| e.into_inner()) = Some(seq);
+            self.suppress.mark_seq(seq);
            Ok(())
        } else {
            Err("写回剪贴板失败".into())
@@ -177,6 +179,20 @@ impl ClipboardManager {
    pub fn storage(&self) -> &Arc<Storage> {
        &self.storage
    }
    /// 写入抑制状态（供划词取词等会改剪贴板的其他模块共享）
    pub fn suppress(&self) -> Arc<SuppressState> {
        self.suppress.clone()
    }
    /// 把**当前**剪贴板序列号登记为「应跳过」。
    ///
    /// 给其他模块写完剪贴板后调用：它们自己拿不到「写入后」的序列号，
    /// 但知道「刚刚写完」这件事。把 win32 调用留在这个模块里，
    /// 别处就不必重复引入 DataExchange。
    pub fn suppress_current_sequence(&self) {
        self.suppress.mark_seq(unsafe { GetClipboardSequenceNumber() });
    }
 }
 impl Drop for ClipboardManager {
@@ -6,6 +6,7 @@ pub mod monitor;
 pub mod popup;
 pub mod reader;
 pub mod storage;
 pub mod suppress;
 pub use commands::{
    clipboard_clear, clipboard_copy_back, clipboard_count, clipboard_delete, clipboard_get_history,
@@ -12,15 +12,17 @@ use tauri::{AppHandle, Emitter};
 use super::reader::{read_clipboard, ClipData};
 use super::storage::{NewItem, Storage};
 use super::suppress::SuppressState;
 use windows_sys::Win32::System::DataExchange::GetClipboardSequenceNumber;
 /// 启动监听线程，返回 JoinHandle。
-/// `suppress` 记录本应用 copy_back 写入后的剪贴板序列号，用于跳过自身写入产生的记录。
+/// `suppress` 记录本应用写入剪贴板产生的序列号、以及取词等流程的屏蔽窗口，
 /// 用于跳过自身写入产生的记录。
 pub fn start_monitor(
    storage: Arc<Storage>,
    app: AppHandle,
    settings: Arc<Mutex<super::manager::ClipboardSettings>>,
-    suppress: Arc<Mutex<Option<u32>>>,
+    suppress: Arc<SuppressState>,
    stop: Arc<AtomicBool>,
 ) -> thread::JoinHandle<()> {
    thread::spawn(move || loop {
@@ -41,14 +43,11 @@ pub fn start_monitor(
        if seq == last {
            continue;
        }
-        // 序列号变化：仅当变化来自本应用 copy_back（序列号精确匹配）时跳过，
+        // 序列号变化，但可能来自本应用：精确记账（copy_back）或屏蔽窗口内（取词流程）。
-        // 避免旧布尔标志在用户后续复制时被误吞。
+        // 判定放在读剪贴板之前，避免为一次注定要丢弃的变化做无谓的读取与解码。
-        if let Ok(mut s) = suppress.lock() {
+        if suppress.should_skip(seq) {
            if *s == Some(seq) {
                *s = None;
            continue;
        }
        }
        let (rec_text, rec_image, rec_files, max_items, max_image_kb, dedup) = {
            let s = settings.lock().unwrap_or_else(|e| e.into_inner());
            (
@@ -0,0 +1,142 @@
 //! 剪贴板写入抑制。
 //!
 //! 存在的理由：剪贴板监听线程会把**任何**序列号变化录进历史。而应用自身也会写剪贴板
 //! （copy_back 写回、划词取词时模拟 Ctrl+C 与随后的还原），这些都不该出现在用户的
 //! 历史里。抑制状态因此必须能被**多个模块**访问，而不是某个模块的私有字段。
 //!
 //! 两种机制并存，因为要解决的问题不同：
 //!
 //! - **精确抑制（seq）**：只跳过「本应用刚写入的那一次变化」。写入者是我们自己时，
 //!   写入后的序列号可以立刻读到，于是能精确记账一次；用户随后的复制是另一个序列号，
 //!   不会被误吞。`copy_back` 用这条。
 //!
 //! - **时间窗抑制（burst）**：屏蔽一个区间内的**所有**变化。划词取词要连续动三次剪贴板
 //!   （Ctrl+C 覆盖 → 我们读走 → 还原原文），而监听线程是 250ms 轮询：按序列号逐个记账
 //!   存在竞态——监听恰好落在我们两次操作之间时，选区文本就被录进历史了。
 //!   因此取词期间必须整体屏蔽，读完并还原之后再解除。
 //!
 //! burst 用**计数**而非布尔：取词流程内部可能再触发一次写入，用布尔会在内层先结束时
 //! 提前解除屏蔽。配对由 [`SuppressState::burst`] 返回的 RAII 守卫保证，提前 return 也安全。
 use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::Mutex;
 #[derive(Default)]
 pub struct SuppressState {
    /// 待跳过的序列号（消费一次即清空）
    seq: Mutex<Option<u32>>,
    /// 屏蔽窗口嵌套计数
    burst: AtomicUsize,
 }
 /// 屏蔽窗口守卫：析构时自动解除，保证与 `begin` 严格配对。
 pub struct BurstGuard<'a>(&'a SuppressState);
 impl Drop for BurstGuard<'_> {
    fn drop(&mut self) {
        self.0.end_burst();
    }
 }
 impl SuppressState {
    pub fn new() -> Self {
        Self::default()
    }
    /// 记账：跳过 `seq` 这一次变化（消费一次）。
    /// 只记一个序列号即可——本应用的写入是串行的，不会同时积压多次。
    pub fn mark_seq(&self, seq: u32) {
        if let Ok(mut guard) = self.seq.lock() {
            *guard = Some(seq);
        }
    }
    /// 开始屏蔽窗口。返回的守卫析构时自动结束，**不要**手动配对 end。
    pub fn burst(&self) -> BurstGuard<'_> {
        self.burst.fetch_add(1, Ordering::SeqCst);
        BurstGuard(self)
    }
    fn end_burst(&self) {
        // saturating：异常路径下的多余 end 不应让计数下溢，否则会永久屏蔽
        let _ = self
            .burst
            .fetch_update(Ordering::SeqCst, Ordering::SeqCst, |v| {
                Some(v.saturating_sub(1))
            });
    }
    /// 当前是否处于屏蔽窗口内（供调用方在取词前做提示，不参与判定）
    pub fn in_burst(&self) -> bool {
        self.burst.load(Ordering::SeqCst) > 0
    }
    /// 监听线程询问：这次变化是否应当跳过。
    /// 命中序列号时**消费**该记账（下次同序列号不再跳过），避免误吞用户后续的复制。
    pub fn should_skip(&self, seq: u32) -> bool {
        if self.in_burst() {
            return true;
        }
        let mut guard = match self.seq.lock() {
            Ok(g) => g,
            Err(e) => e.into_inner(),
        };
        if *guard == Some(seq) {
            *guard = None;
            true
        } else {
            false
        }
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn seq_suppression_is_consumed_once() {
        let s = SuppressState::new();
        s.mark_seq(7);
        assert!(s.should_skip(7), "记账的那次应被跳过");
        assert!(!s.should_skip(7), "同序列号不应被反复跳过");
        assert!(!s.should_skip(8), "其他序列号不受影响");
    }
    #[test]
    fn burst_suppresses_everything_until_dropped() {
        let s = SuppressState::new();
        {
            let _guard = s.burst();
            assert!(s.should_skip(1));
            assert!(s.should_skip(2));
            assert!(s.in_burst());
        }
        assert!(!s.in_burst());
        assert!(!s.should_skip(3));
    }
    #[test]
    fn burst_is_reentrant() {
        let s = SuppressState::new();
        let outer = s.burst();
        {
            let _inner = s.burst();
        }
        // 内层结束不应提前解除外层
        assert!(s.in_burst());
        assert!(s.should_skip(9));
        drop(outer);
        assert!(!s.in_burst());
    }
    #[test]
    fn extra_end_does_not_underflow() {
        let s = SuppressState::new();
        s.end_burst();
        s.end_burst();
        // 下溢会让计数变成极大值从而永久屏蔽，这里确保不会
        assert!(!s.in_burst());
        assert!(!s.should_skip(4));
    }
 }
@@ -14,6 +14,8 @@ pub mod windows {
    pub const SCREENSHOT_PIN: &str = "screenshot-pin";
    #[allow(dead_code)]
    pub const SCREENSHOT_SCROLL: &str = "screenshot-scroll";
    /// 取词翻译悬浮窗（由 translate 模块预创建，非激活显示）
    pub const TRANSLATE_POPUP: &str = "translate-popup";
 }
 /// Tauri 事件名（与前端 constants::EVENTS 对应）
@@ -53,16 +55,22 @@ pub mod events {
    // 截图
    pub const SCREENSHOT_SHORTCUT: &str = "screenshot-shortcut";
    pub const SCREENSHOT_PIN_SHORTCUT: &str = "screenshot-pin-shortcut";
    /// 截图结果导出（含覆盖层/编辑器/滚动截图会话）
    pub const SCREENSHOT_EXPORTED: &str = "screenshot-exported";
    /// 滚动截图会话：实时进度 { width, height, auto }
    pub const SCROLL_PROGRESS: &str = "screenshot-scroll-progress";
-    /// 滚动截图会话：完成并导出（负载与 SCREENSHOT_EXPORTED 相同）
+    /// 滚动截图会话：完成并导出
    pub const SCROLL_COMPLETE: &str = "screenshot-scroll-complete";
    /// 滚动截图会话：已取消（无负载）
    pub const SCROLL_CANCELLED: &str = "screenshot-scroll-cancelled";
    // 内核安装进度
    pub const KERNEL_INSTALL_PROGRESS: &str = "kernel-install-progress";
    // 翻译：取词悬浮窗显示（负载见 translate::popup::PopupPayload）/ 隐藏（无负载）
    pub const TRANSLATE_POPUP_SHOW: &str = "translate-popup-show";
    pub const TRANSLATE_POPUP_HIDE: &str = "translate-popup-hide";
    // 翻译：流式输出（负载见 translate::engines::StreamEvent；失败经 start 的 Promise reject，
    // 已发出 requestId 之后的失败额外走 error 事件兜底）
    pub const TRANSLATE_STREAM_CHUNK: &str = "translate-stream-chunk";
    pub const TRANSLATE_STREAM_DONE: &str = "translate-stream-done";
    pub const TRANSLATE_STREAM_ERROR: &str = "translate-stream-error";
    // 音乐模块：Python 便携运行时安装进度
    pub const MUSIC_RUNTIME_INSTALL_PROGRESS: &str = "music-runtime-install-progress";
    // 音乐模块：下载任务事件（桥接事件行 → 前端，负载见 bridge.py _emit_event）
@@ -12,9 +12,11 @@ mod osd_window;
 mod process_manager;
 mod quickpanel;
 mod screenshot;
 mod secrets;
 mod setup;
 mod shortcut;
 mod snap_fix;
 mod translate;
 mod tray_menu;
 mod updater;
 mod win32_util;
@@ -45,12 +47,15 @@ use monitor_kernel::{
 use music::{
    feiniu_activate_connection, feiniu_cache_clear, feiniu_cache_fetch, feiniu_cache_status,
    feiniu_delete_connection, feiniu_delete_local, feiniu_fnconnect_resolve, feiniu_get_config,
-    feiniu_list_connections, feiniu_list_tracks, feiniu_login, feiniu_logout, feiniu_lyric,
+    feiniu_list_connections, feiniu_list_audio_files, feiniu_list_tracks, feiniu_login,
    feiniu_logout, feiniu_lyric,
    feiniu_media_prefix, feiniu_save_connection, feiniu_scan_local, feiniu_test_connection,
    music_cancel_runtime_install, music_download, music_download_cancel, music_env_status,
    music_get_settings, music_get_sources, music_install_runtime, music_parse_playlist, music_ping,
-    music_resolve, music_save_settings, music_search, music_stop_bridge, webdav_delete,
+    music_resolve, music_save_settings, music_search, music_secret_get, music_secret_set,
-    webdav_get_secret, webdav_save_secret, webdav_test, webdav_upload, MusicManager,
+    music_stop_bridge, music_update_musicdl, webdav_delete, webdav_get_secret,
    webdav_save_secret, webdav_test,
    webdav_upload, MusicManager,
 };
 use network_monitor::network_status;
 use osd_window::{
@@ -98,6 +103,18 @@ use quickpanel::{
    quickpanel_show_window, quickpanel_unregister_shortcut, quickpanel_focus_main_window,
 };
 use tray_menu::{tray_menu_action, tray_menu_hide, tray_menu_ready};
 use translate::{
    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,
 };
 use updater::{
    app_version, update_check, update_install, update_thinghk_apply, update_thinghk_cancel,
    update_thinghk_confirm, ThinghkUpdateState,
@@ -110,11 +127,16 @@ fn quit_app(app: tauri::AppHandle) {
 }
 /// 导出 tauri-specta 生成的 TypeScript 类型与命令绑定（仅 debug 构建，开发时自动刷新）。
-/// 覆盖 proxy / quickpanel / clipboard / download_engine / screenshot 五个模块；
+/// 覆盖 proxy / quickpanel / clipboard / download_engine / screenshot / translate 等模块；
 /// 豁免清单（返回 serde_json::Value 或 tauri::ipc::Response/Request，specta 无法生成）：
 /// proxy_version / proxy_get_proxies / proxy_get_connections / proxy_patch_configs、
 /// downloader_status / downloader_get_extension_info、
-/// screenshot_get_fullscreen_bmp（返回 ipc::Response）/ screenshot_compose_copy（接收 ipc::Request）。
+/// screenshot_get_fullscreen_bmp（返回 ipc::Response）/ screenshot_compose_copy（接收 ipc::Request）、
 /// music_ping / music_get_sources / music_search（返回 serde_json::Value）。
 ///
 /// 注意：export 结果写入 `../src/lib/bindings.ts`，因此**新增模块的命令后需至少以 debug
 /// 构建运行一次**，前端才能用 `commands.xxx` 拿到类型。在此之前前端若需调用，
 /// 只能退回原生 `invoke`（返回类型需自行声明）。
 #[cfg(debug_assertions)]
 fn export_bindings() {
    use specta_typescript::Typescript;
@@ -175,6 +197,17 @@ fn export_bindings() {
            screenshot_set_scroll_hole,
            screenshot_copy_image, screenshot_save_png,
            screenshot_save_cache, screenshot_load_cache, screenshot_delete_cache,
            // translate（20）
            translate_get_settings, translate_save_settings, translate_apply_shortcuts,
            translate_engines_list, translate_engine_save, translate_engine_delete,
            translate_secret_set, translate_secret_clear, translate_engine_test_config,
            translate_engine_models, translate_run, translate_copy_text,
            translate_preview_popup, translate_popup_ready, translate_popup_hide,
            translate_popup_edit_mode, translate_popup_set_pinned, translate_popup_prefs_set,
            translate_popup_resize, translate_screenshot_region, translate_ocr_languages,
            translate_history_list, translate_history_delete, translate_history_clear,
            translate_history_set_favorited,
            translate_stream_start, translate_abort, translate_paste_back,
        ])
        .export(Typescript::default(), "../src/lib/bindings.ts")
        .expect("failed to export bindings");
@@ -261,6 +294,7 @@ pub fn run() {
            music_env_status,
            music_install_runtime,
            music_cancel_runtime_install,
            music_update_musicdl,
            music_ping,
            music_stop_bridge,
            music_get_sources,
@@ -283,6 +317,7 @@ pub fn run() {
            feiniu_lyric,
            feiniu_media_prefix,
            feiniu_scan_local,
            feiniu_list_audio_files,
            feiniu_cache_status,
            feiniu_cache_clear,
            feiniu_cache_fetch,
@@ -292,6 +327,8 @@ pub fn run() {
            webdav_delete,
            webdav_get_secret,
            webdav_save_secret,
            music_secret_get,
            music_secret_set,
            feiniu_delete_local,
            network_status,
            osd_apply_overlay_style,
@@ -408,7 +445,35 @@ pub fn run() {
            screenshot_unregister_pin_shortcut,
            screenshot_disable_transitions,
            screenshot_compose_copy,
-            screenshot_compose_png
+            screenshot_compose_png,
            translate_get_settings,
            translate_save_settings,
            translate_apply_shortcuts,
            translate_engines_list,
            translate_engine_save,
            translate_engine_delete,
            translate_secret_set,
            translate_secret_clear,
            translate_engine_test_config,
            translate_engine_models,
            translate_run,
            translate_copy_text,
            translate_preview_popup,
            translate_popup_ready,
            translate_popup_hide,
            translate_popup_edit_mode,
            translate_popup_set_pinned,
            translate_popup_prefs_set,
            translate_popup_resize,
            translate_screenshot_region,
            translate_ocr_languages,
            translate_history_list,
            translate_history_delete,
            translate_history_clear,
            translate_history_set_favorited,
            translate_stream_start,
            translate_abort,
            translate_paste_back
        ])
        .setup(setup::init)
        .on_window_event(|window, event| {
@@ -10,12 +10,12 @@ Response (one JSON per line on stdout):
 Methods:
    ping             -> {"version", "python"}
    env_status       -> {"musicdl": version|null}
    get_sources      -> {"sources": [registered music client names]}
    search           -> {"results": {source: [song...]}, "sources": [...]}
-                        params: {"keyword", "sources": []}
+                        params: {"keyword", "sources": [], "proxy": url-or-""}
    resolve          -> {"songs": [resolved-song-or-null, ...], "resolved": n}
                        params: {"song": {...}} or {"songs": [...]}
                                可选 "proxy": url-or-""
                        (懒解析：对搜索结果歌曲执行真实解析链，返回带下载链接
                         的完整歌曲；输入顺序对齐，失败位为 null)
    download         -> {"taskId"} (runs in background worker pool)
@@ -62,6 +62,7 @@ import tempfile
 import threading
 import time
 import uuid
 from urllib.parse import parse_qs, urlparse
 # Fallback sources used when the frontend passes an empty list
 DEFAULT_SOURCES = [
@@ -127,6 +128,31 @@ _LAZY_URL = "http://lazy.internal/unresolved"
 _PATCHED = False
 # 当前命令生效的代理地址（"" = 明确不走代理）。
 #
 # 必须显式控制：requests 未指定 proxies 时会去读**系统代理**（环境变量，以及
 # Windows 下 urllib 读取注册表 Internet Settings 里 mihomo 写入的 ProxyEnable/
 # ProxyServer）。所以只把「没配置代理」理解为"不传 proxies"是不够的——
 # 用户开了代理模块的系统代理后，搜索/解析会被静默送进 mihomo；
 # 国内音乐源经境外节点出去就会超时或返回空结果。
 _CURRENT_PROXY = ""
@contextlib.contextmanager
 def _use_proxy(url):
    """在块内决定所有「未显式指定代理」的 requests 请求怎么走。
    `url` 为空串 = 强制直连（禁用系统代理）；非空 = 统一走该代理。
    显式传了 proxies 的请求（如下载路径）不受影响。
    """
    global _CURRENT_PROXY
    prev = _CURRENT_PROXY
    _CURRENT_PROXY = (url or "").strip()
    try:
        yield
    finally:
        _CURRENT_PROXY = prev
 def _cap_timeout(timeout, stream):
    """按 stream 与否收紧超时，返回新的 timeout 值。"""
@@ -157,6 +183,16 @@ def _patch_musicdl():
    def _capped_request(self, method, url, **kwargs):
        kwargs["timeout"] = _cap_timeout(kwargs.get("timeout"), bool(kwargs.get("stream")))
        # 未显式指定代理时按当前命令的设置决定（见 _use_proxy）。
        # trust_env=False 是为了彻底屏蔽环境变量/系统（注册表）代理：
        # 只传 {"http": None} 在 ALL_PROXY 存在时可能仍被代理接管。
        if kwargs.get("proxies") is None:
            kwargs["proxies"] = (
                {"http": _CURRENT_PROXY, "https": _CURRENT_PROXY}
                if _CURRENT_PROXY
                else {"http": None, "https": None}
            )
        self.trust_env = False
        return _orig_request(self, method, url, **kwargs)
    requests.Session.request = _capped_request
@@ -378,12 +414,27 @@ def _resolve_song(src_client, search_result, target=None):
 # ---------------------------------------------------------------------------
 # 按目标音质解析（取 ≤ 所选的最优档）
 #
-# musicdl 官方解析按「质量常量」循环、取首个有效档。这里在全局锁保护下临时替换
+# musicdl 官方解析按「质量常量」循环、取首个有效档。这里临时替换各源的质量常量
-# 各源质量常量（只保留 ≤ 目标档位），让官方解析只循环这些档位；解析完成后立即恢复。
+# （只保留 ≤ 目标档位），让官方解析只循环这些档位；解析完成后立即恢复。
 # 由于替换的是模块级常量，必须用 _RESOLVE_CAP_LOCK 串行化所有封顶解析，避免并发竞态。
 # 有损码率目标用 lossless_quality_is_sufficient=False，使官方解析不采纳第三方 flac/hires。
 #
 # 锁的粒度是**按源**而不是一把全局锁：被替换的是各源自己模块里的常量，
 # 不同源之间不会互相干扰；而一把全局锁会把并发下载里所有源的解析串起来
 # （每个解析都含网络请求，持锁跨越请求 = 解析阶段吞吐退化成串行）。
 # 同一源内必须串行：否则 A 恢复常量时 B 还在解析，B 会拿到未封顶的档位。
 # ---------------------------------------------------------------------------
-_RESOLVE_CAP_LOCK = threading.Lock()
+_RESOLVE_CAP_LOCKS = {}
 _RESOLVE_CAP_LOCKS_GUARD = threading.Lock()
 def _resolve_cap_lock(source):
    """取该源的封顶解析锁（惰性创建；字典本身受 _RESOLVE_CAP_LOCKS_GUARD 保护）。"""
    with _RESOLVE_CAP_LOCKS_GUARD:
        lock = _RESOLVE_CAP_LOCKS.get(source)
        if lock is None:
            lock = threading.Lock()
            _RESOLVE_CAP_LOCKS[source] = lock
        return lock
 # QQ：SongFileType.SORTED_QUALITIES 前缀（F000=flac, O8xx/O6xx=ogg, M800=320K, M500=128K, C6xx=m4a）
 _QQ_CAPS = {
@@ -488,7 +539,7 @@ def _resolve_to_quality(src_client, search_result, target):
    from musicdl.modules.utils.data import SongInfo
    official = getattr(src_client, "_real_parsewithofficialapiv1", None) or src_client._parsewithofficialapiv1
-    with _RESOLVE_CAP_LOCK:
+    with _resolve_cap_lock(source):
        _swap_quality_constants(source, allowed)
        try:
            # 空 song_info_flac + lossless_quality_is_sufficient=False：
@@ -511,28 +562,39 @@ _RESOLVE_CLIENTS = {}
 _RESOLVE_CLIENTS_LOCK = threading.Lock()
-def _get_resolve_client(source):
+def _get_resolve_client(source, cookies=None):
-    """按源缓存的独立源客户端（resolve/试听/批量解析用），失败返回 None。"""
+    """按源（+Cookie）缓存的独立源客户端（resolve/试听/批量解析用），失败返回 None。"""
    cookie_dict = _cookie_str_to_dict(cookies) if source == "QQMusicClient" else None
    cache_key = f"{source}|{json.dumps(cookie_dict, sort_keys=True) if cookie_dict else ''}"
    with _RESOLVE_CLIENTS_LOCK:
-        if source in _RESOLVE_CLIENTS:
+        if cache_key in _RESOLVE_CLIENTS:
-            return _RESOLVE_CLIENTS[source]
+            return _RESOLVE_CLIENTS[cache_key]
        try:
            from musicdl.musicdl import MusicClient
-            client = MusicClient(
+            init_cfg = {
                music_sources=[source],
                init_music_clients_cfg={
                source: {
                    "maintain_session": True,
                    "max_retries": 1,
                    "work_dir": _SEARCH_WORK_DIR,
                }
-                },
+            }
            if cookie_dict:
                init_cfg[source].update(
                    {
                        "default_search_cookies": cookie_dict,
                        "default_parse_cookies": cookie_dict,
                        "default_download_cookies": cookie_dict,
                    }
                )
            client = MusicClient(
                music_sources=[source],
                init_music_clients_cfg=init_cfg,
            )
            src_client = client.music_clients.get(source)
        except Exception:
            src_client = None
-        _RESOLVE_CLIENTS[source] = src_client
+        _RESOLVE_CLIENTS[cache_key] = src_client
        return src_client
 # Persistent MusicClient cache; keyed by the sorted source list because the
@@ -557,10 +619,31 @@ def _out():
    return _PROTOCOL_STDOUT if _PROTOCOL_STDOUT is not None else sys.stdout
-def get_client(sources):
+def _cookie_str_to_dict(value):
-    """Return a cached MusicClient, recreating it when the source set changes."""
+    """把浏览器复制的 Cookie 字符串（``k=v; k2=v2``）解析成 dict。
    musicdl 的部分接口（如 ``Credential.fromcookiesdict``）只接受 dict，
    而用户从 DevTools 复制到的是字符串，这里统一转换。已是 dict 时原样返回。
    """
    if isinstance(value, dict):
        return value
    if not isinstance(value, str) or not value.strip():
        return None
    out = {}
    for part in value.split(";"):
        if "=" not in part:
            continue
        k, _, v = part.strip().partition("=")
        if k:
            out[k] = v
    return out or None
 def get_client(sources, cookies=None):
    """Return a cached MusicClient, recreating it when the source set or cookies change."""
    global _CLIENT, _CLIENT_KEY
-    key = "|".join(sorted(sources or []))
+    cookie_dict = _cookie_str_to_dict(cookies)
    key = "|".join(sorted(sources or [])) + f"|cookies={json.dumps(cookie_dict, sort_keys=True) if cookie_dict else ''}"
    if _CLIENT is None or _CLIENT_KEY != key:
        try:
            from musicdl.musicdl import MusicClient
@@ -585,6 +668,18 @@ def get_client(sources):
                "maintain_session": True,
                "max_retries": 1,
            }
        # 登录态：目前仅 QQ 音乐用得上（解析需登录的歌单 / VIP 音质）。
        # 三组 Cookie 都要给：search/lossless 判定用 default_search_cookies（即
        # self.default_cookies），歌单解析用 default_parse_cookies，下载用 default_download_cookies。
        # 注意 musicdl 的既有逻辑：配置 Cookie 后 QQ 会跳过第三方解析源，全走官方接口。
        if cookie_dict and "QQMusicClient" in init_cfg:
            init_cfg["QQMusicClient"].update(
                {
                    "default_search_cookies": cookie_dict,
                    "default_parse_cookies": cookie_dict,
                    "default_download_cookies": cookie_dict,
                }
            )
        threadings = {src: _SEARCH_SIZE_PER_SOURCE for src in effective}
        _CLIENT = MusicClient(
            music_sources=effective,
@@ -919,7 +1014,9 @@ def handle_search(params):
    if not keyword:
        raise ValueError("keyword 不能为空")
    sources = params.get("sources") or DEFAULT_SOURCES
-    client = get_client(sources)
+    # 搜索全程按模块设置决定是否走代理（缺省强制直连，避免被系统代理带走）
    with _use_proxy(params.get("proxy")):
        client = get_client(sources, params.get("cookies"))
        # musicdl 的 rich 进度条写 sys.stdout，必须重定向到 stderr 保持 JSON 通道干净
        with _CLIENT_LOCK:
            with contextlib.redirect_stdout(sys.stderr):
@@ -954,12 +1051,154 @@ def handle_get_sources(params):
    return {"sources": keys}
 _NETEASE_HOSTS = (
    "music.163.com",
    "y.music.163.com",
    "m.music.163.com",
    "3g.music.163.com",
    "163cn.tv",
 )
 def _is_netease_url(url: str) -> bool:
    try:
        host = (urlparse(url).hostname or "").lower()
    except Exception:
        return False
    return any(host == h or host.endswith("." + h) for h in _NETEASE_HOSTS)
 def _netease_playlist_id(url: str):
    """从查询串或 "#" 片段里取数字歌单 id（都取不到返回 None）。
    注意 "#" 片段常见形态是 ``/playlist?id=NNN``（带路径前缀），
    直接 parse_qs 会把键解析成 "/playlist"，需先取 "?" 之后的部分。
    """
    try:
        parts = urlparse(url)
    except Exception:
        return None
    frag = parts.fragment
    if "?" in frag:
        frag = frag.split("?", 1)[1]
    for source in (parts.query, frag):
        pid = (parse_qs(source, keep_blank_values=True).get("id") or [None])[0]
        if pid and str(pid).isdigit():
            return pid
    return None
 def _normalize_netease_playlist_url(url: str) -> str:
    """把网易云歌单链接规范化成 musicdl 认得出的形式。
    musicdl 的网易云 ``parseplaylist`` 只从 URL 的 **"#\" 片段**或**路径末段**取歌单 id，
    而「分享/复制链接」出来的地址普遍是 ``.../playlist?id=NNN``（id 在查询串里）——
    会被当成路径末段 ``playlist`` 去查询，恒返回 0 首。
    这里把 id 直接提出来，改写成它认得的 ``https://music.163.com/#/playlist?id=NNN``。
    """
    try:
        parts = urlparse(url)
    except Exception:
        return url
    host = (parts.hostname or "").lower()
    if not any(host == h or host.endswith("." + h) for h in _NETEASE_HOSTS):
        return url
    for source in (parts.query, parts.fragment):
        pid = (parse_qs(source, keep_blank_values=True).get("id") or [None])[0]
        if pid and str(pid).isdigit():
            return f"https://music.163.com/#/playlist?id={pid}"
    return url
 def _parse_netease_playlist_lazy(client, url):
    """网易云歌单：懒解析——只取曲目元数据，**全部返回**，下载/试听时再解析链接。
    musicdl 的 ``parseplaylist`` 走完整急切解析链，且只保留解析出下载链接的歌，
    所以歌单会"少歌"（本例 7 首只剩 2 首）。这里与搜索对齐：
    1~2 个请求批量拉元数据（v6 歌单详情 + v3 歌曲详情），直接返回全部曲目；
    ``rawSearch`` 为歌曲详情原始对象，试听/下载时由 resolve 走真实解析链。
    返回 None 表示当前源集合里没有网易云客户端（交回通用路径处理）。
    """
    src_client = (client.music_clients or {}).get("NeteaseMusicClient")
    extract = _META_EXTRACTORS.get("NeteaseMusicClient")
    if src_client is None or extract is None:
        return None
    playlist_id = _netease_playlist_id(url)
    if not playlist_id:
        return None
    from musicdl.modules.utils import resp2json, safeextractfromdict
    try:
        playlist_result = resp2json(
            resp=src_client.post(
                "https://music.163.com/api/v6/playlist/detail", data={"id": playlist_id}
            )
        )
    except Exception as e:
        print(f"[playlist] 网易云歌单详情请求失败: {e}", file=sys.stderr)
        return []
    tracks = safeextractfromdict(playlist_result, ["playlist", "tracks"], []) or []
    # v6 响应顶层带 privileges（与曲目一一对应），合入以便无损/音质提示推断
    # （与搜索结果同构：_lossless_hint 读 raw_search.privilege.maxbr）
    for r, p in zip(tracks, playlist_result.get("privileges") or []):
        if isinstance(r, dict) and isinstance(p, dict) and p.get("id") in (None, r.get("id")):
            r["privilege"] = p
    if not tracks:
        track_ids = safeextractfromdict(playlist_result, ["playlist", "trackIds"], []) or []
        if not track_ids:
            return []
        # 歌单详情只回 trackIds（裸 id）：批量补全元数据（v3 song/detail 支持一次传全部 id）
        try:
            detail = resp2json(
                resp=src_client.post(
                    "https://interface3.music.163.com/api/v3/song/detail",
                    data={
                        "c": json.dumps(
                            [{"id": t.get("id"), "v": 0} for t in track_ids if isinstance(t, dict) and t.get("id")]
                        )
                    },
                )
            )
        except Exception as e:
            print(f"[playlist] 网易云歌单曲目元数据请求失败: {e}", file=sys.stderr)
            return []
        tracks = detail.get("songs") or []
        # privileges 与 songs 顺序对齐，合入便于音质档位/无损提示推断
        for r, p in zip(tracks, detail.get("privileges") or []):
            if isinstance(r, dict) and isinstance(p, dict):
                r["privilege"] = p
    out, seen = [], set()
    for r in tracks:
        if not isinstance(r, dict) or not r.get("id") or r["id"] in seen:
            continue
        seen.add(r["id"])
        try:
            d = song_to_dict(_make_lazy_songinfo(src_client, extract, r))
        except Exception as e:
            print(f"[playlist] 网易云歌单曲目元数据构造失败: {e}", file=sys.stderr)
            continue
        # 与搜索同一套脏数据过滤（空歌名 / "NULL" 元数据）
        if d.get("songName") and not _meta_garbage(d):
            out.append(d)
    return out
 def handle_parse_playlist(params):
-    url = (params.get("url") or "").strip()
+    url = _normalize_netease_playlist_url((params.get("url") or "").strip())
    if not url:
        raise ValueError("url 不能为空")
    sources = params.get("sources") or DEFAULT_SOURCES
-    client = get_client(sources)
+    # 与搜索一致：按模块设置决定是否走代理（缺省强制直连）
    with _use_proxy(params.get("proxy")):
        client = get_client(sources, params.get("cookies"))
        # 网易云：懒解析——全部曲目都返回（含元数据），下载/试听时再逐首解析链接，
        # 与搜索体验一致；musicdl 原生实现只保留解析出链接的歌，会让歌单"少歌"。
        lazy_songs = _parse_netease_playlist_lazy(client, url) if _is_netease_url(url) else None
        if lazy_songs is not None:
            return {"songs": lazy_songs, "count": len(lazy_songs)}
        # 其他源沿用 musicdl 的急切解析（QQ 的实现先查查询串取 id，无此问题）。
        # musicdl 会按源依次尝试解析（第一个成功的源 break），rich 进度写 stdout 需重定向。
        # 歌单解析须临时关闭懒解析：网易云歌单接口只回 trackIds（仅 id 无元数据），
        # 懒元数据提取会得到空结果；此处保持急切解析（歌曲自带解析好的链接）
@@ -988,6 +1227,7 @@ def handle_resolve(params):
    if not songs:
        raise ValueError("songs 不能为空")
    target_quality = (params.get("quality") or "").strip()
    resolve_cookies = params.get("cookies") or ""
    from concurrent.futures import ThreadPoolExecutor
    def _resolve_one(song):
@@ -995,7 +1235,7 @@ def handle_resolve(params):
        raw_search = song.get("rawSearch")
        if not source or not isinstance(raw_search, dict):
            return None
-        src_client = _get_resolve_client(source)
+        src_client = _get_resolve_client(source, resolve_cookies)
        if src_client is None:
            return None
        # musicdl 的 rich 进度条写 sys.stdout，重定向到 stderr 保持 JSON 通道干净
@@ -1006,6 +1246,9 @@ def handle_resolve(params):
        return song_to_dict(resolved)
    with ThreadPoolExecutor(max_workers=min(4, len(songs))) as pool:
        # 解析同样要联网：按模块设置决定是否走代理（缺省强制直连）。
        # 工作线程读取的是同一个 _CURRENT_PROXY，块内一致。
        with _use_proxy(params.get("proxy")):
            out = list(pool.map(_resolve_one, songs))
    return {"songs": out, "resolved": sum(1 for r in out if r)}
@@ -1017,6 +1260,7 @@ def handle_download(params):
    lyric = bool(params.get("lyric", True))
    cover = bool(params.get("cover", True))
    proxy_url = params.get("proxy") or ""
    cookies = params.get("cookies") or ""
    max_concurrent = max(1, min(int(params.get("maxConcurrent") or 1), 16))
    target_quality = (params.get("quality") or "").strip()
    if not songs:
@@ -1026,7 +1270,7 @@ def handle_download(params):
    _TASKS[task_id] = state
    thread = threading.Thread(
        target=_download_supervisor,
-        args=(task_id, songs, savedir, lyric, cover, proxy_url, state, max_concurrent, target_quality),
+        args=(task_id, songs, savedir, lyric, cover, proxy_url, cookies, state, max_concurrent, target_quality),
        daemon=True,
    )
    thread.start()
@@ -1041,7 +1285,7 @@ def handle_cancel(params):
    return {"taskId": task_id, "cancelled": False}
-def _download_supervisor(task_id, songs, savedir, lyric, cover, proxy_url, state, max_concurrent, target_quality=""):
+def _download_supervisor(task_id, songs, savedir, lyric, cover, proxy_url, cookies, state, max_concurrent, target_quality=""):
    """下载监督线程：按 maxConcurrent 启动工作线程，逐首领取歌曲下载。
    每个工作线程持有独立 MusicClient（互不共享、不与搜索客户端争锁），
    因此搜索期间下载照常推进；取消为队列级（当前歌曲完成，其余标记取消）。"""
@@ -1062,11 +1306,22 @@ def _download_supervisor(task_id, songs, savedir, lyric, cover, proxy_url, state
                # maintain_session=True 复用连接（默认每请求新建 Session）；
                # max_retries=1 封顶死链重试（下载前链接均已验证）
                sources_list = sources or DEFAULT_SOURCES
                worker_cfg = {
                    src: {"maintain_session": True, "max_retries": 1} for src in sources_list
                }
                # QQ 音乐 Cookie（VIP 音质 / 官方 vkey 接口）
                cookie_dict = _cookie_str_to_dict(cookies)
                if cookie_dict and "QQMusicClient" in worker_cfg:
                    worker_cfg["QQMusicClient"].update(
                        {
                            "default_search_cookies": cookie_dict,
                            "default_parse_cookies": cookie_dict,
                            "default_download_cookies": cookie_dict,
                        }
                    )
                client = MusicClient(
                    music_sources=sources_list,
-                    init_music_clients_cfg={
+                    init_music_clients_cfg=worker_cfg,
                        src: {"maintain_session": True, "max_retries": 1} for src in sources_list
                    },
                )
            except Exception as exc:
                with lock:
@@ -1303,8 +1558,6 @@ def handle(method, params):
            "version": "0.1.0",
            "python": sys.version.split()[0],
        }
    if method == "env_status":
        return check_env()
    if method == "get_sources":
        return handle_get_sources(params)
    if method == "parse_playlist":
@@ -1320,20 +1573,6 @@ def handle(method, params):
    raise ValueError("unknown method: %s" % method)
 def check_env():
    """Report whether musicdl is importable and its version."""
    result = {"musicdl": None}
    try:
        import musicdl
        result["musicdl"] = getattr(musicdl, "__version__", "unknown")
    except Exception as exc:
        # Not installed / broken deps: report None so the frontend can prompt
        # the user to install the runtime first.
        sys.stderr.write("musicdl import failed: %s\n" % exc)
    return result
 def main():
    global _PROTOCOL_STDOUT
    # 编码对齐：Rust 侧以 UTF-8 字节写入 stdin（serde_json 序列化不转义非 ASCII），
@@ -36,6 +36,27 @@ pub fn music_cancel_runtime_install(state: State<'_, MusicManager>) -> Result<()
    Ok(())
 }
 /// 把 musicdl 对齐到本应用锁定的版本（`force = true` 表示强制重装）。
 ///
 /// 与「安装便携版」的区别：安装的闸门是「能否 import」，所以版本不一致时它什么都不做；
 /// 更新则是显式对齐到 `MUSICDL_VERSION`。**只升到锁定版本，不升 PyPI 最新版**
 /// （bridge.py 的 monkey patch 与 musicdl 版本强耦合，见 `update_musicdl` 的说明）。
 ///
 /// 成功后顺手停掉桥接进程：它可能已经 import 了旧版 musicdl 并缓存了 MusicClient，
 /// 不重启就会继续用旧代码跑。下一次搜索/下载会自动拉起新进程。
 ///
 /// 返回更新后的环境状态，前端一次往返即可刷新面板。
 #[tauri::command]
 pub async fn music_update_musicdl(
    state: State<'_, MusicManager>,
    app: AppHandle,
    force: Option<bool>,
 ) -> Result<MusicEnvStatus, String> {
    state.update_musicdl(&app, force.unwrap_or(false)).await?;
    state.stop_bridge();
    state.env_status().await
 }
 /// ping 桥接进程（未启动则自动拉起），返回 {"version","python"}；
 /// 返回 Value 且未标注 specta：前端直接按 JSON 使用
 #[tauri::command]
@@ -63,8 +84,17 @@ pub async fn music_search(
    state: State<'_, MusicManager>,
    keyword: String,
    sources: Option<Vec<String>>,
    proxy_url: Option<String>,
    qq_cookie: Option<String>,
 ) -> Result<serde_json::Value, String> {
-    let params = serde_json::json!({ "keyword": keyword, "sources": sources.unwrap_or_default() });
+    // proxy_url 为空串表示「明确不走代理」（桥接侧会强制直连、屏蔽系统代理）；
    // qq_cookie 为空表示游客身份（桥接侧不注入 Cookie）
    let params = serde_json::json!({
        "keyword": keyword,
        "sources": sources.unwrap_or_default(),
        "proxy": proxy_url.unwrap_or_default(),
        "cookies": qq_cookie.unwrap_or_default(),
    });
    state
        .request_with_timeout("search", params, std::time::Duration::from_secs(90))
        .await
@@ -76,8 +106,15 @@ pub async fn music_parse_playlist(
    state: State<'_, MusicManager>,
    url: String,
    sources: Option<Vec<String>>,
    proxy_url: Option<String>,
    qq_cookie: Option<String>,
 ) -> Result<serde_json::Value, String> {
-    let params = serde_json::json!({ "url": url, "sources": sources.unwrap_or_default() });
+    let params = serde_json::json!({
        "url": url,
        "sources": sources.unwrap_or_default(),
        "proxy": proxy_url.unwrap_or_default(),
        "cookies": qq_cookie.unwrap_or_default(),
    });
    state
        .request_with_timeout("parse_playlist", params, std::time::Duration::from_secs(90))
        .await
@@ -91,13 +128,31 @@ pub fn music_get_settings(state: State<'_, MusicManager>) -> MusicSettings {
 }
 /// 保存音乐模块设置（立即生效）
 ///
 /// 飞牛音乐**连接相关字段一律以磁盘为准**，不接受前端传值：
 /// 连接列表 / 激活连接 / 旧版单连接字段只由 `feiniu_save_connection`、
 /// `feiniu_activate_connection`、`feiniu_delete_connection`、`feiniu_login`
 /// 等专用命令维护。
 ///
 /// 原因：前端 `musicStore` 只在 init 时读一次整份设置并长期复用快照，
 /// 若允许它整份回写，删除连接后任意一次设置保存（哪怕是切页触发的）
 /// 都会把已删除的连接从旧快照里写回来。
 #[tauri::command]
 #[specta::specta]
 pub fn music_save_settings(
    state: State<'_, MusicManager>,
    settings: MusicSettings,
 ) -> Result<(), String> {
-    state.save_settings(&settings)
+    let persisted = state.load_settings();
    let mut next = settings;
    next.feiniu_connections = persisted.feiniu_connections;
    next.feiniu_active_id = persisted.feiniu_active_id;
    next.feiniu_base_url = persisted.feiniu_base_url;
    next.feiniu_token = persisted.feiniu_token;
    next.feiniu_username = persisted.feiniu_username;
    next.feiniu_device_id = persisted.feiniu_device_id;
    next.feiniu_access_code = persisted.feiniu_access_code;
    state.save_settings(&next)
 }
 /// 解析歌曲真实下载链接（懒解析：搜索只取元数据，试听/下载前调用）。
@@ -108,6 +163,8 @@ pub async fn music_resolve(
    song: Option<serde_json::Value>,
    songs: Option<Vec<serde_json::Value>>,
    quality: Option<String>,
    proxy_url: Option<String>,
    qq_cookie: Option<String>,
 ) -> Result<serde_json::Value, String> {
    let mut list: Vec<serde_json::Value> = songs.unwrap_or_default();
    if let Some(s) = song {
@@ -116,7 +173,12 @@ pub async fn music_resolve(
    if list.is_empty() {
        return Err("未提供歌曲".into());
    }
-    let params = serde_json::json!({ "songs": list, "quality": quality.unwrap_or_default() });
+    let params = serde_json::json!({
        "songs": list,
        "quality": quality.unwrap_or_default(),
        "proxy": proxy_url.unwrap_or_default(),
        "cookies": qq_cookie.unwrap_or_default(),
    });
    state
        .request_with_timeout("resolve", params, std::time::Duration::from_secs(180))
        .await
@@ -136,6 +198,7 @@ pub async fn music_download(
    proxy_url: Option<String>,
    max_concurrent: Option<u32>,
    quality: Option<String>,
    qq_cookie: Option<String>,
 ) -> Result<serde_json::Value, String> {
    if songs.is_empty() {
        return Err("未选择任何歌曲".into());
@@ -149,6 +212,7 @@ pub async fn music_download(
        "proxy": proxy_url.unwrap_or_default(),
        "maxConcurrent": max_concurrent.unwrap_or(1).clamp(1, 16),
        "quality": quality.unwrap_or_default(),
        "cookies": qq_cookie.unwrap_or_default(),
    });
    state
        .request_with_timeout("download", params, std::time::Duration::from_secs(15))
@@ -170,6 +234,7 @@ pub async fn music_download_cancel(
 // 全部命令返回 serde_json::Value、不加 specta：前端用裸 invoke，映射在 feiniuStore。
 /// 连接列表 + 激活 id。返回 `{ activeId, list: [{id,name,kind,baseUrl,username,loggedIn,accessCode,insecure}] }`。
 /// `loggedIn` 的权威是系统凭据管理器里的 token（结构体字段只在凭据库不可用降级时才有值）。
 #[tauri::command]
 pub fn feiniu_list_connections(state: State<'_, MusicManager>) -> Result<serde_json::Value, String> {
    let s = state.load_settings();
@@ -183,10 +248,11 @@ pub fn feiniu_list_connections(state: State<'_, MusicManager>) -> Result<serde_j
                "kind": c.kind,
                "baseUrl": c.base_url,
                "username": c.username,
-                "loggedIn": !c.token.is_empty(),
+                "loggedIn": !c.token.is_empty() || crate::music::secrets::has_feiniu_token(&c.id),
                "accessCode": c.access_code,
                "insecure": c.insecure,
                "fnId": c.fn_id,
                "relay": c.relay,
            })
        })
        .collect();
@@ -205,14 +271,18 @@ pub fn feiniu_save_connection(
    if conn.id.is_empty() {
        conn.id = new_conn_id();
    }
    let id = conn.id.clone();
    if let Some(existing) = settings.feiniu_connections.iter_mut().find(|c| c.id == conn.id) {
        conn.token = existing.token.clone(); // 保留既有 token
        // relay 是解析结果而非用户输入：同为 fnconnect 时沿用，切换类型则重置
        conn.relay = conn.kind == "fnconnect" && existing.kind == "fnconnect" && existing.relay;
        *existing = conn;
    } else {
        settings.feiniu_connections.push(conn);
    }
    state.save_settings(&settings)?;
-    Ok(json!({ "ok": true }))
+    // 回传 id：新建时前端无需按「地址 + 名称」反查，避免 FnConnect（地址为空）匹配失败
    Ok(json!({ "ok": true, "id": id }))
 }
 /// 删除一条连接；若删的是激活连接，自动切换激活到第一条。
@@ -230,7 +300,16 @@ pub fn feiniu_delete_connection(
            .map(|c| c.id.clone())
            .unwrap_or_default();
    }
    // 旧版单连接字段是迁移逻辑的输入：残留会让「列表为空」再次被迁移出一条连接。
    // 删除是明确意图，顺手清掉，保证删了就是删了。
    settings.feiniu_base_url.clear();
    settings.feiniu_token.clear();
    settings.feiniu_username.clear();
    settings.feiniu_device_id.clear();
    settings.feiniu_access_code.clear();
    state.save_settings(&settings)?;
    // 顺带清掉该连接在系统凭据管理器里的 token，避免留下孤儿凭据
    let _ = crate::music::secrets::secret_delete(&crate::music::secrets::feiniu_token_key(&id));
    state.feiniu.sync_with_settings(&settings);
    Ok(json!({ "ok": true }))
 }
@@ -270,10 +349,12 @@ pub async fn feiniu_login(
    // fnconnect：用 fnId 解析 base_url
    if conn.kind == "fnconnect" {
        let fid = extract_fn_id(&conn.fn_id).ok_or_else(|| "FnConnect 连接缺少有效 fnId".to_string())?;
-        let (url, _relay) = resolve_base_url(&fid).await?;
+        let (url, relay) = resolve_base_url(&fid).await?;
        conn.base_url = url;
        conn.relay = relay;
        if let Some(c) = settings.feiniu_connections.iter_mut().find(|c| c.id == connection_id) {
            c.base_url = conn.base_url.clone();
            c.relay = relay;
        }
        state.save_settings(&settings)?;
    }
@@ -284,8 +365,12 @@ pub async fn feiniu_login(
    let (token, device_id) = state.feiniu.login(&conn.base_url, &username, &password).await?;
    // token 存进系统凭据管理器；只有写入失败才降级为明文落 settings.json（并记日志）。
    // 顺序很重要：先确认凭据库写成功，再决定要不要把明文留在结构体里。
    let token_key = crate::music::secrets::feiniu_token_key(&connection_id);
    let token_protected = crate::music::secrets::try_store(&token_key, &token);
    if let Some(existing) = settings.feiniu_connections.iter_mut().find(|c| c.id == connection_id) {
-        existing.token = token.clone();
+        existing.token = if token_protected { String::new() } else { token.clone() };
        existing.device_id = device_id;
        existing.username = username;
    }
@@ -293,16 +378,23 @@ pub async fn feiniu_login(
    state.save_settings(&settings)?;
    state.feiniu.sync_with_settings(&settings);
    let prefix = state.feiniu.media_prefix().await?;
-    Ok(json!({ "ok": true, "userToken": token, "mediaPrefix": prefix }))
+    // 不把 token 回传前端：前端除了 mediaPrefix 之外不需要它，少一处明文暴露面
    Ok(json!({ "ok": true, "mediaPrefix": prefix, "protected": token_protected }))
 }
 /// 登出某连接（清 token，保留地址/账号），代理 Cookie 同步失效。
 ///
 /// 顺序有讲究：**必须先删凭据库里的 token 再 sync**，
 /// 否则 `sync_with_settings` 会从凭据库把刚登出的 token 又读回运行期（看起来「登出无效」）。
 #[tauri::command]
 pub fn feiniu_logout(
    state: State<'_, MusicManager>,
    connection_id: String,
 ) -> Result<serde_json::Value, String> {
    let mut settings = state.load_settings();
    let _ = crate::music::secrets::secret_delete(&crate::music::secrets::feiniu_token_key(
        &connection_id,
    ));
    if let Some(c) = settings.feiniu_connections.iter_mut().find(|c| c.id == connection_id) {
        c.token.clear();
    }
@@ -312,24 +404,37 @@ pub fn feiniu_logout(
    Ok(json!({ "ok": true }))
 }
-/// 测试某连接是否能登录（不持久化 token），探测后恢复原激活连接的运行期状态。
+/// 测试一条连接**草案**能否登录（不持久化任何变更）。
 ///
 /// 入参是编辑对话框里的完整草案而非连接 id：新建连接在保存前没有 id，
 /// 若按 id 查库，对话框里的「测试」在保存前必然报 missing required key。
 /// 探测以「草案作为唯一连接」装备运行期，结束后恢复持久化的激活连接。
 #[tauri::command]
 pub async fn feiniu_test_connection(
    state: State<'_, MusicManager>,
-    connection_id: String,
+    connection: FeiniuConnection,
    username: String,
    password: String,
 ) -> Result<serde_json::Value, String> {
    let mut conn = connection;
    conn.base_url = normalize_base_url(&conn.base_url);
    // fnconnect：先解析 fnId（解析结果只用于本次探测，不回写设置）
    if conn.kind == "fnconnect" {
        let fid = extract_fn_id(&conn.fn_id).ok_or_else(|| "FnConnect 连接缺少有效 fnId".to_string())?;
        let (url, relay) = resolve_base_url(&fid).await?;
        conn.base_url = url;
        conn.relay = relay;
    }
    if conn.base_url.trim().is_empty() {
        return Err("请先填写服务器地址或飞牛 ID".to_string());
    }
    let settings = state.load_settings();
    let conn = settings
        .feiniu_connections
        .iter()
        .find(|c| c.id == connection_id)
        .cloned()
        .ok_or_else(|| "连接不存在".to_string())?;
    let mut tmp = settings.clone();
    tmp.feiniu_connections = vec![conn.clone()];
    tmp.feiniu_active_id = conn.id.clone();
    state.feiniu.sync_with_settings(&tmp);
    let r = state.feiniu.login(&conn.base_url, &username, &password).await;
    // 探测可能污染运行期：恢复为持久化的激活连接
    state.feiniu.sync_with_settings(&state.load_settings());
@@ -390,9 +495,9 @@ pub async fn feiniu_media_prefix(
    Ok(json!({ "mediaPrefix": prefix }))
 }
-/// 扫描本地曲库目录中的音频文件：{ items }（目录 = 下载 savedir + 用户自定义 dirs）。
+/// 允许访问的本地目录（下载目录 + 自定义曲库目录）。
-#[tauri::command]
+/// 本地文件的**列举与删除**都限定在其中——前端只应能操作曲库范围内的文件。
-pub fn feiniu_scan_local(state: State<'_, MusicManager>) -> Result<serde_json::Value, String> {
+fn allowed_local_roots(state: &MusicManager) -> Vec<String> {
    let s = state.load_settings();
    let mut dirs: Vec<String> = vec![s.savedir.clone()];
    for d in &s.feiniu_local_dirs {
@@ -400,7 +505,55 @@ pub fn feiniu_scan_local(state: State<'_, MusicManager>) -> Result<serde_json::V
            dirs.push(d.clone());
        }
    }
-    Ok(state.feiniu.scan_local(&dirs))
+    dirs.into_iter().filter(|d| !d.trim().is_empty()).collect()
 }
 /// 路径是否位于允许的根目录之下。
 /// 两侧都先 `canonicalize`：`..` 与符号链接因此无法越出根目录。
 fn is_within_roots(path: &std::path::Path, roots: &[String]) -> bool {
    let Ok(target) = std::fs::canonicalize(path) else {
        return false;
    };
    roots.iter().any(|r| {
        std::fs::canonicalize(r)
            .map(|root| target.starts_with(&root))
            .unwrap_or(false)
    })
 }
 /// 列出某个下载目录中的音频文件（非递归）：`{ items: [{path,name,size,mtim}] }`。
 ///
 /// 供上传编排在下载目录里定位「刚落盘的文件」——用 `feiniu_scan_local` 会递归遍历
 /// 整个曲库并解析标签，为一次上传扫全库是纯浪费。不解析标签（匹配只需要文件名与时间）。
 #[tauri::command]
 pub async fn feiniu_list_audio_files(
    state: State<'_, MusicManager>,
    dir: String,
 ) -> Result<serde_json::Value, String> {
    let roots = allowed_local_roots(&state);
    if roots.is_empty() || !is_within_roots(std::path::Path::new(&dir), &roots) {
        return Err(format!("拒绝列举曲库目录之外的路径：{dir}"));
    }
    tauri::async_runtime::spawn_blocking(move || crate::music::feiniu::list_audio_files(&dir))
        .await
        .map_err(|e| format!("列举目录失败: {e}"))
 }
 /// 扫描本地曲库目录中的音频文件：{ items }（目录 = 下载 savedir + 用户自定义 dirs）。
 /// 标签解析结果缓存在 CacheManager（size+mtim 未变即复用）。
 ///
 /// **必须 async + spawn_blocking**：Tauri 中不带 async 的命令在主线程执行，
 /// 而 walkdir 递归 + lofty 全量标签解析在万级曲库下会阻塞数秒——UI 直接冻住。
 /// 目录与缓存路径都先取出为自有值，避免把 `State` 借进 'static 的阻塞任务。
 #[tauri::command]
 pub async fn feiniu_scan_local(state: State<'_, MusicManager>) -> Result<serde_json::Value, String> {
    let dirs = allowed_local_roots(&state);
    let tags_cache = state.feiniu.local_tags_path();
    tauri::async_runtime::spawn_blocking(move || {
        crate::music::scan_local_dirs(&dirs, Some(tags_cache.as_path()))
    })
    .await
    .map_err(|e| format!("本地曲库扫描任务失败: {e}"))
 }
 /// 播放缓存状态：{ count, usedBytes, usedMb }。
@@ -478,73 +631,67 @@ pub async fn webdav_delete(
    Ok(json!({ "ok": true }))
 }
-// ============ WebDAV 凭据加密存储（Windows 凭据管理器，DPAPI 保护） ============
+// ============ 敏感串（系统凭据管理器，DPAPI 保护） ============
-
+// 统一实现在 crate::music::secrets：WebDAV 账号密码、QQ 音乐 Cookie、飞牛登录 token
-/// 凭据以 JSON blob 存入系统凭据管理器：{"username","password"}。
+// 三类凭据同构存放，不再出现「一类进凭据库、另一类明文落盘」的双标。
 /// 明文仅存在于内存与系统凭据库，绝不写回 localStorage / 配置文件。
 #[cfg(windows)]
 const WEBDAV_SECRET_SERVICE: &str = "Thing";
 #[cfg(windows)]
 const WEBDAV_SECRET_USER: &str = "webdav-credentials";
 #[cfg(windows)]
 fn webdav_secret_entry() -> Result<keyring::Entry, String> {
    keyring::Entry::new(WEBDAV_SECRET_SERVICE, WEBDAV_SECRET_USER)
        .map_err(|e| format!("无法访问系统凭据管理器: {e}"))
 }
 #[cfg(windows)]
 fn webdav_secret_read() -> Result<Option<serde_json::Value>, String> {
    let entry = webdav_secret_entry()?;
    match entry.get_password() {
        Ok(blob) => serde_json::from_str(&blob)
            .map(Some)
            .map_err(|e| format!("凭据数据损坏: {e}")),
        // 未配置过凭据不算错误
        Err(keyring::Error::NoEntry) => Ok(None),
        Err(e) => Err(format!("读取凭据失败: {e}")),
    }
 }
 #[cfg(windows)]
 fn webdav_secret_write(username: &str, password: &str) -> Result<(), String> {
    let blob = json!({ "username": username, "password": password }).to_string();
    let entry = webdav_secret_entry()?;
    entry.set_password(&blob).map_err(|e| format!("保存凭据失败: {e}"))
 }
 /// 读取 WebDAV 凭据。未配置时 username/password 为 null。
 #[tauri::command]
 pub fn webdav_get_secret() -> Result<serde_json::Value, String> {
-    #[cfg(windows)]
+    let parsed = crate::music::secrets::secret_read(crate::music::secrets::KEY_WEBDAV)
-    {
+        .unwrap_or(None)
-        Ok(webdav_secret_read()?.unwrap_or_else(|| json!({ "username": null, "password": null })))
+        .and_then(|raw| serde_json::from_str::<serde_json::Value>(&raw).ok());
-    }
+    Ok(parsed.unwrap_or_else(|| json!({ "username": null, "password": null })))
    #[cfg(not(windows))]
    {
        Ok(json!({ "username": null, "password": null }))
    }
 }
 /// 保存 WebDAV 凭据（账号 + 密码整体覆盖）。
 #[tauri::command]
 pub fn webdav_save_secret(username: String, password: String) -> Result<serde_json::Value, String> {
-    #[cfg(windows)]
+    let blob = json!({ "username": username, "password": password }).to_string();
-    {
+    crate::music::secrets::secret_write(crate::music::secrets::KEY_WEBDAV, &blob)?;
-        webdav_secret_write(&username, &password)?;
+    Ok(json!({ "ok": true }))
 }
 /// 校验前端可访问的凭据键：只允许白名单内的键（见 `secrets::FRONTEND_KEYS`）。
 ///
 /// 白名单刻意不含 `webdav-credentials` 与飞牛 token——
 /// 前端因此无法通过这两个通用命令去读写它们，只能碰自己的 QQ 音乐 Cookie。
 fn assert_frontend_secret_key(key: &str) -> Result<(), String> {
    if crate::music::secrets::frontend_key_allowed(key) {
        Ok(())
    } else {
        Err(format!("不允许访问的凭据键：{key}"))
    }
-    #[cfg(not(windows))]
+}
-    {
+
-        let _ = (&username, &password);
+/// 读取一个音乐模块的敏感串（如 QQ 音乐 Cookie）：{ value }（未设置 → null）。
 #[tauri::command]
 pub fn music_secret_get(key: String) -> Result<serde_json::Value, String> {
    assert_frontend_secret_key(&key)?;
    Ok(json!({ "value": crate::music::secrets::secret_read(&key)? }))
 }
 /// 写入 / 清除一个音乐模块的敏感串。`value` 为空表示删除该凭据。
 #[tauri::command]
 pub fn music_secret_set(key: String, value: String) -> Result<serde_json::Value, String> {
    assert_frontend_secret_key(&key)?;
    if value.is_empty() {
        crate::music::secrets::secret_delete(&key)?;
    } else {
        crate::music::secrets::secret_write(&key, &value)?;
    }
    Ok(json!({ "ok": true }))
 }
 /// 删除本地媒体文件（「下载到飞牛」落地即传流程的收尾）。
-/// 仅允许音频 / 歌词 / 封面扩展名，且拒绝目录——防止前端误删任意文件。
+/// 仅允许音频 / 歌词 / 封面扩展名，拒绝目录，且**必须落在已配置的下载/曲库目录内**——
 /// 只校验扩展名的话，前端一旦传错路径就能删掉用户的任意音乐文件。
 #[tauri::command]
 #[specta::specta]
-pub fn feiniu_delete_local(path: String) -> Result<serde_json::Value, String> {
+pub fn feiniu_delete_local(
    state: State<'_, MusicManager>,
    path: String,
 ) -> Result<serde_json::Value, String> {
    const ALLOWED: [&str; 13] = [
        "mp3", "flac", "wav", "m4a", "aac", "ogg", "ape", "wma", "lrc", "jpg", "jpeg", "png", "webp",
    ];
@@ -561,6 +708,9 @@ pub fn feiniu_delete_local(path: String) -> Result<serde_json::Value, String> {
    if meta.is_dir() {
        return Err("拒绝删除目录".to_string());
    }
    if !is_within_roots(p, &allowed_local_roots(&state)) {
        return Err(format!("拒绝删除曲库目录之外的文件：{path}"));
    }
    std::fs::remove_file(p).map_err(|e| format!("删除失败: {e}"))?;
    Ok(json!({ "ok": true }))
 }
@@ -34,6 +34,13 @@ impl CacheManager {
        Self { root, index_path }
    }
    /// 本地曲库标签缓存文件：{cache_root}/local-tags.json。
    /// 记录 path -> {size, mtim, 标签}，扫描时未变化的文件直接复用，
    /// 避免万级曲库每次都重新解析音频标签。
    pub fn local_tags_path(&self) -> PathBuf {
        self.root.join("local-tags.json")
    }
    fn load_index(&self) -> HashMap<String, CacheEntry> {
        fs::read_to_string(&self.index_path)
            .ok()
@@ -1,58 +1,86 @@
-//! FnConnect 远程连接解析（参考 feiniu-car-music `fn-api.js`）。
+//! FnConnect 远程连接解析。
 //!
-//! fnId → 网关 `https://5ddd.com/api/v1/fn/con`（authx md5 签名）→ 内网/公网/中继候选 →
+//! 链路参考第三方客户端 FnMusic 的 `fn_connection_probe_service.dart`：
-//! 探测可达性 → 得到可用的 base_url（含 mode=relay 的中继地址）。
+//! fnId → 网关 `<网关>/api/v1/fn/con`（authx md5 签名）→ 内网 / 公网 IPv6 / 公网 IPv4 / 中继
 //! 候选 → 并发探测（按优先级早停）→ 首个可达的 base_url。
 //!
 //! 关键约束（实测确认）：
 //! 1. authx 原文为 `PREFIX_url_nonce_timestamp_md5(body)_API_KEY`，
 //!    md5 与 API_KEY 之间是**单个**下划线；多一个下划线网关即返回 `invalid sign`。
 //! 2. 中继地址（`<fnId>.fnos.net`）必须携带 `Cookie: mode=relay` 才会被网关转发到
 //!    NAS 音乐后端，否则网关直接 302 回登录页。
-use md5::Md5;
+use std::time::Duration;
 use futures_util::stream::{FuturesUnordered, StreamExt};
 use md5::{Digest, Md5};
 use rand::RngCore;
 use serde_json::{json, Value};
 use sha2::{Digest, Sha256};
-/// 网关地址与签名常量（对齐 feiniu-car-music）。
+/// 网关主机（按序回退；5ddd.com 与 fnos.net 为同一服务的不同集群入口）。
-const FN_CONNECT_URL: &str = "https://5ddd.com/api/v1/fn/con";
+const FN_CONNECT_HOSTS: [&str; 2] = ["https://5ddd.com", "https://fnos.net"];
 /// 连接参数接口路径（签名原文中的 url 部分）。
 const FN_CON_PATH: &str = "/api/v1/fn/con";
 /// 签名常量（对齐第三方实现）。
 const FN_AUTHX_PREFIX: &str = "NDzZTVxnRKP8Z0jXg1VAMonaG8akvh";
 const FN_API_KEY: &str = "zIGtkc3dqZnJpd29qZXJqa2w7c";
 /// 网关查询超时。
 const FN_QUERY_TIMEOUT: Duration = Duration::from_secs(10);
 /// 直连候选（内网/公网 IP）探测超时。
 const FN_PROBE_TIMEOUT_DIRECT: Duration = Duration::from_secs(3);
 /// 中继候选探测超时（走公网网关，放宽）。
 const FN_PROBE_TIMEOUT_RELAY: Duration = Duration::from_secs(10);
 fn md5_hex(input: &str) -> String {
    let mut h = Md5::new();
    h.update(input.as_bytes());
    format!("{:x}", h.finalize())
 }
-fn sha256_hex(input: &str) -> String {
+/// 从输入识别 fnId：`fnos.net/<id>`、`5ddd.com/<id>`、`<id>.fnos.net`、`<id>.5ddd.com`、或裸 fnId。
    let mut h = Sha256::new();
    h.update(input.as_bytes());
    format!("{:x}", h.finalize())
 }
 /// 从输入识别 fnId：`fnos.net/<id>`、`<id>.5ddd.com`、或裸 fnId。
 pub fn extract_fn_id(input: &str) -> Option<String> {
    let s = input.trim();
    if s.is_empty() {
        return None;
    }
-    if let Some(id) = s.split_once("fnos.net/").map(|(_, r)| r.split('/').next().unwrap_or("")) {
+    // 去协议后统一按「可能带路径的 host」处理
    let mut t = s;
    for p in ["https://", "http://"] {
        if let Some(r) = t.strip_prefix(p) {
            t = r;
            break;
        }
    }
    let t = t.trim_end_matches('/');
    // 形如 <网关>/<id>
    for gw in ["fnos.net/", "5ddd.com/"] {
        if let Some((_, rest)) = t.split_once(gw) {
            let id = rest.split('/').next().unwrap_or("").trim();
            if !id.is_empty() {
-            return Some(id.trim().to_string());
+                return Some(id.to_string());
            }
        }
-    if let Some(rest) = s.rsplit_once("/") {
+    }
-        let last = rest.1;
+    // 形如 <id>.<网关>
-        if last.ends_with(".5ddd.com") {
+    for suffix in [".fnos.net", ".5ddd.com"] {
-            return Some(last.trim_end_matches(".5ddd.com").to_string());
+        if let Some(id) = t.strip_suffix(suffix) {
            if !id.is_empty() {
                return Some(id.to_string());
            }
        }
    if s.ends_with(".5ddd.com") {
        return Some(s.trim_end_matches(".5ddd.com").to_string());
    }
    // 裸 fnId
-    if s.len() >= 3 && s.chars().all(|c| c.is_alphanumeric() || c == '-' || c == '_') && !s.starts_with("http") {
+    if s.len() >= 3 && s.chars().all(|c| c.is_alphanumeric() || c == '-' || c == '_') {
        return Some(s.to_string());
    }
    None
 }
 /// 计算网关 authx 签名。
 ///
 /// 原文（下划线连接，**注意 md5 与 API_KEY 之间只有一个下划线**）：
 /// `PREFIX_url_nonce_timestamp_md5(body)_API_KEY` → 取 md5 作为 sign。
 fn fn_authx(method: &str, url: &str, data: &Value) -> String {
    let body = if method.eq_ignore_ascii_case("get") {
        String::new()
@@ -69,98 +97,199 @@ fn fn_authx(method: &str, url: &str, data: &Value) -> String {
        .map(|d| d.as_millis().to_string())
        .unwrap_or_default();
    let raw = format!(
-        "{FN_AUTHX_PREFIX}_{url}_{nonce}_{timestamp}_{}__{FN_API_KEY}",
+        "{FN_AUTHX_PREFIX}_{url}_{nonce}_{timestamp}_{}_{FN_API_KEY}",
        md5_hex(&body)
    );
    format!("nonce={nonce}&timestamp={timestamp}&sign={}", md5_hex(&raw))
 }
-/// 从网关查询 fnId 的连接参数。
+/// 从网关查询 fnId 的连接参数（多网关按序回退）。
 pub async fn query_fn_connect(fn_id: &str) -> Result<Value, String> {
    let client = reqwest::Client::builder()
-        .timeout(std::time::Duration::from_secs(10))
+        .timeout(FN_QUERY_TIMEOUT)
        .build()
        .map_err(|e| e.to_string())?;
    let body = json!({ "fnId": fn_id });
-    let resp = client
+    let authx = fn_authx("post", FN_CON_PATH, &body);
-        .post(FN_CONNECT_URL)
+
    let mut last_err = String::from("FnConnect 网关不可达");
    for host in FN_CONNECT_HOSTS {
        let resp = match client
            .post(format!("{host}{FN_CON_PATH}"))
            .header("Content-Type", "application/json")
-        .header("authx", fn_authx("post", "/api/v1/fn/con", &body))
+            .header("authx", authx.clone())
            .json(&body)
            .send()
            .await
-        .map_err(|e| format!("FnConnect 网关不可达: {e}"))?;
+        {
-    let b: Value = resp.json().await.map_err(|e| e.to_string())?;
+            Ok(r) => r,
-    if b["code"].as_i64().unwrap_or(-1) != 0 {
+            Err(e) => {
-        return Err(b["msg"].as_str().unwrap_or("FnConnect 网关返回错误").to_string());
+                last_err = format!("FnConnect 网关不可达: {e}");
                continue;
            }
-    Ok(b["data"].clone())
+        };
        let b: Value = match resp.json().await {
            Ok(v) => v,
            Err(e) => {
                last_err = format!("FnConnect 网关响应异常: {e}");
                continue;
            }
        };
        if b["code"].as_i64().unwrap_or(-1) != 0 {
            last_err = b["msg"]
                .as_str()
                .filter(|s| !s.is_empty())
                .map(|s| s.to_string())
                .unwrap_or_else(|| "FnConnect 网关返回错误".to_string());
            continue;
        }
        return Ok(b["data"].clone());
    }
    Err(last_err)
 }
-/// 构建候选 base_url 列表。返回 (url, is_relay)。
+/// 去掉 `host:port` 形式的端口（仅用于中继域名，中继恒走 443）。
-pub fn build_candidates(data: &Value) -> Vec<(String, bool)> {
+fn strip_port(addr: &str) -> &str {
    match addr.rsplit_once(':') {
        Some((host, port)) if !host.is_empty() && port.chars().all(|c| c.is_ascii_digit()) => host,
        _ => addr,
    }
 }
 /// 构建候选 base_url 列表。返回 `(url, is_relay)`，顺序即优先级：
 /// 内网 IPv4 → 公网 IPv6 → 公网 IPv4 → 中继。
 ///
 /// IP 直连地址 HTTP 优先、HTTPS 兜底（自签证书场景 HTTP 更易通）；
 /// `forbbidPublicIpv6` 为真时跳过公网 IPv6。
 pub fn build_candidates(data: &Value, fn_id: &str) -> Vec<(String, bool)> {
    let mut out: Vec<(String, bool)> = Vec::new();
    let port = &data["port"];
    let http = port["httpPort"].as_u64().unwrap_or(5666);
    let https = port["httpsPort"].as_u64().unwrap_or(5667);
-    let empty = vec![];
+    let empty: Vec<Value> = Vec::new();
-    for ip in data["ipv4"].as_array().unwrap_or(&empty).iter().filter_map(|v| v.as_str()) {
+
    let strings = |key: &str| -> Vec<String> {
        data[key]
            .as_array()
            .unwrap_or(&empty)
            .iter()
            .filter_map(|v| v.as_str())
            .map(|s| s.to_string())
            .collect()
    };
    // 1) 内网 IPv4
    for ip in strings("ipv4") {
        out.push((format!("http://{ip}:{http}"), false));
        out.push((format!("https://{ip}:{https}"), false));
    }
-    for ip in data["publicIpv4"].as_array().unwrap_or(&empty).iter().filter_map(|v| v.as_str()) {
+    // 2) 公网 IPv6（NAS 侧可禁用）
-        out.push((format!("http://{ip}:{http}"), false));
+    if !data["forbbidPublicIpv6"].as_bool().unwrap_or(false) {
-        out.push((format!("https://{ip}:{https}"), false));
+        for ip in strings("publicIpv6") {
    }
    for ip in data["publicIpv6"].as_array().unwrap_or(&empty).iter().filter_map(|v| v.as_str()) {
            out.push((format!("http://[{ip}]:{http}"), false));
            out.push((format!("https://[{ip}]:{https}"), false));
        }
-    let relays = data["fn"].as_array().unwrap_or(&empty);
+    }
-    let relay_addrs: Vec<String> = if relays.is_empty() {
+    // 3) 公网 IPv4
-        vec!["5ddd.com".to_string()]
+    for ip in strings("publicIpv4") {
-    } else {
+        out.push((format!("http://{ip}:{http}"), false));
-        relays
+        out.push((format!("https://{ip}:{https}"), false));
-            .iter()
+    }
-            .filter_map(|v| v.as_str().map(|s| s.to_string()))
+    // 4) 中继：仅 HTTPS；网关未返回时按两种集群域名兜底
-            .collect()
+    let mut relays = strings("fn");
-    };
+    if relays.is_empty() {
-    for addr in relay_addrs {
+        relays = vec![
-        let domain = addr.split(':').next().unwrap_or(&addr).to_string();
+            format!("{fn_id}.fnos.net"),
            format!("{fn_id}.5ddd.com"),
        ];
    }
    for addr in relays {
        let domain = strip_port(&addr);
        if !domain.is_empty() {
            out.push((format!("https://{domain}"), true));
        }
    }
    out
 }
-/// 探测某个 base_url 是否可用。
+/// 探测单个 base_url 是否可用（中继候选携带 `mode=relay` 才会被网关转发）。
-async fn probe(url: &str) -> bool {
+///
-    let client = reqwest::Client::builder()
+/// 判据必须排除 3xx：重定向说明请求**没有真正落到 NAS 音乐后端**
-        .timeout(std::time::Duration::from_secs(6))
+/// （中继缺 `mode=relay` 时网关 302 回登录页；端口上实际是 fnOS Web UI 时同样 302）。
-        .build()
+/// 早先把「任何 < 500」都当可达，结果候选探测通过、紧接着登录报 `HTTP 302 Found`。
-        .unwrap_or_else(|_| reqwest::Client::new());
+async fn probe(client: &reqwest::Client, url: &str, relay: bool) -> bool {
-    let full = format!("{}/music/api/v1/track/list?page=1&size=1", url.trim_end_matches('/'));
+    let timeout = if relay {
-    match client.get(&full).send().await {
+        FN_PROBE_TIMEOUT_RELAY
-        Ok(resp) => resp.status().as_u16() < 500,
+    } else {
        FN_PROBE_TIMEOUT_DIRECT
    };
    let full = format!(
        "{}/music/api/v1/track/list?page=1&size=1",
        url.trim_end_matches('/')
    );
    let mut rb = client.get(&full).timeout(timeout);
    if relay {
        rb = rb.header("cookie", "mode=relay");
    }
    match rb.send().await {
        // 未登录时中继会返回 401（已触达 NAS 音乐后端），直连返回 200/401，
        // 均视为链路可达；3xx（重定向）与 5xx 视为不可达。
        Ok(resp) => {
            let code = resp.status().as_u16();
            code < 500 && !(300..400).contains(&code)
        }
        Err(_) => false,
    }
 }
-/// 解析 fnId → 第一个可达的 base_url；返回 (base_url, is_relay)。
+/// 解析 fnId → 首个可达的 base_url；返回 `(base_url, is_relay)`。
 ///
 /// 所有候选并发探测，按优先级（索引越小越优先）取首个确认可达者并早停，
 /// 避免远程场景下顺序探测逐个等待超时。
 pub async fn resolve_base_url(fn_id: &str) -> Result<(String, bool), String> {
    let data = query_fn_connect(fn_id).await?;
-    let candidates = build_candidates(&data);
+    let candidates = build_candidates(&data, fn_id);
    if candidates.is_empty() {
        return Err("FnConnect 未返回可用地址".into());
    }
    for (url, relay) in &candidates {
        if probe(url).await {
            return Ok((url.clone(), *relay));
        }
    }
    Err(format!("FnConnect 候选均不可达（{} 个）", candidates.len()))
 }
-/// sha256 hex（登录用）。
+    let client = reqwest::Client::builder()
-pub fn sha256_hex_pub(input: &str) -> String {
+        .timeout(FN_PROBE_TIMEOUT_RELAY)
-    sha256_hex(input)
+        .build()
        .map_err(|e| e.to_string())?;
    let mut pending = FuturesUnordered::new();
    for (i, (url, relay)) in candidates.iter().enumerate() {
        let client = client.clone();
        let url = url.clone();
        let relay = *relay;
        pending.push(async move {
            let ok = probe(&client, &url, relay).await;
            (i, url, relay, ok)
        });
    }
    let mut undecided: Vec<usize> = (0..candidates.len()).collect();
    let mut best: Option<(usize, String, bool)> = None;
    while let Some((i, url, relay, ok)) = pending.next().await {
        undecided.retain(|x| *x != i);
        if ok && best.as_ref().map_or(true, |(bi, _, _)| i < *bi) {
            best = Some((i, url, relay));
        }
        // 早停：已有可达候选，且不存在索引更小（优先级更高）的未决候选
        if let Some((bi, _, _)) = best.as_ref() {
            if !undecided.iter().any(|x| x < bi) {
                break;
            }
        }
    }
    match best {
        Some((idx, url, relay)) => {
            let _ = idx;
            Ok((url, relay))
        }
        None => Err(format!("FnConnect 候选均不可达（{} 个）", candidates.len())),
    }
 }
@@ -5,11 +5,14 @@
 //! 对照 FeiNiuMusic(Flutter) `api_client.dart` 的第三方纯前端实现翻译。
 //! 所有对 NAS 的 HTTP 请求在本模块收敛（页面/命令层不直接发请求）。
-use std::path::Path;
+use std::fs;
 use std::path::{Path, PathBuf};
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
 use axum::http::StatusCode;
 use lofty::file::{AudioFile, TaggedFileExt};
 use lofty::tag::Accessor;
 use serde::{Deserialize, Serialize};
 use specta::Type;
 use serde_json::{json, Value};
@@ -48,6 +51,10 @@ pub struct FeiniuConnection {
    /// fnconnect 连接的 fnId（如 fnos.net/<id> 或裸 id）
    #[serde(default)]
    pub fn_id: String,
    /// 是否经由 FnConnect 中继链路（`<fnId>.fnos.net`）。
    /// 中继要求所有请求携带 `Cookie: mode=relay`，否则网关 302 回登录页。
    #[serde(default)]
    pub relay: bool,
 }
 impl Default for FeiniuConnection {
@@ -63,6 +70,7 @@ impl Default for FeiniuConnection {
            access_code: String::new(),
            insecure: false,
            fn_id: String::new(),
            relay: false,
        }
    }
 }
@@ -75,6 +83,8 @@ struct Conn {
    device_id: String,
    access_code: String,
    insecure: bool,
    /// FnConnect 中继链路标记
    relay: bool,
 }
 /// LAN 直连，`no_proxy` 避免被代理模块(mihomo)拦走；按 insecure 惰性重建（支持自签证书）。
@@ -83,8 +93,26 @@ struct ClientSlot {
    client: reqwest::Client,
 }
 /// 构建飞牛请求 client。
 ///
 /// `streaming = true` 时不设**总超时**：reqwest 的 `timeout` 覆盖到响应体读完为止，
 /// 用来取整首音频会把流式中途掐断（大文件/慢链路下播放器会一直缓冲）。
 /// 流式只限制建连时间。
 fn build_client(insecure: bool, streaming: bool) -> reqwest::Client {
    let mut b = reqwest::Client::builder()
        .no_proxy()
        .connect_timeout(Duration::from_secs(10))
        .danger_accept_invalid_certs(insecure);
    if !streaming {
        b = b.timeout(Duration::from_secs(10));
    }
    b.build().unwrap_or_else(|_| reqwest::Client::new())
 }
 pub struct Feiniu {
    client: Mutex<Option<ClientSlot>>,
    /// 流代理专用 client（无总超时）
    stream_client: Mutex<Option<ClientSlot>>,
    conn: Mutex<Conn>,
    proxy: Mutex<Option<(u16, ProxyShared)>>,
    cache: CacheManager,
@@ -94,6 +122,7 @@ impl Default for Feiniu {
    fn default() -> Self {
        Self {
            client: Mutex::new(None),
            stream_client: Mutex::new(None),
            conn: Mutex::new(Conn {
                base_url: String::new(),
                token: String::new(),
@@ -101,6 +130,7 @@ impl Default for Feiniu {
                device_id: String::new(),
                access_code: String::new(),
                insecure: false,
                relay: false,
            }),
            proxy: Mutex::new(None),
            cache: CacheManager::new(Path::new("placeholder")), // 由 set_cache_root 重建
@@ -108,40 +138,56 @@ impl Default for Feiniu {
    }
 }
 /// 按 insecure 惰性构建 client（`streaming` 决定是否免总超时）。
 fn slot_client(slot: &Mutex<Option<ClientSlot>>, insecure: bool, streaming: bool) -> reqwest::Client {
    let mut g = slot.lock().unwrap_or_else(|e| e.into_inner());
    let hit = g.as_ref().map(|s| s.insecure == insecure).unwrap_or(false);
    if !hit {
        *g = Some(ClientSlot {
            insecure,
            client: build_client(insecure, streaming),
        });
    }
    g.as_ref().unwrap().client.clone()
 }
 impl Feiniu {
    /// 设置缓存根目录（{app_data}/music/cache），应用启动时调用一次。
    pub fn set_cache_root(&mut self, app_data_dir: &Path) {
        self.cache = CacheManager::new(app_data_dir);
    }
-    /// 取（并惰性构建）对应 insecure 的 reqwest client。
+    /// 本地曲库标签缓存文件路径（{cache_root}/local-tags.json）。
-    fn client(&self, insecure: bool) -> reqwest::Client {
+    pub fn local_tags_path(&self) -> PathBuf {
-        let mut g = self.client.lock().unwrap_or_else(|e| e.into_inner());
+        self.cache.local_tags_path()
        let hit = g.as_ref().map(|s| s.insecure == insecure).unwrap_or(false);
        if !hit {
            *g = Some(ClientSlot {
                insecure,
                client: reqwest::Client::builder()
                    .no_proxy()
                    .timeout(Duration::from_secs(10))
                    .danger_accept_invalid_certs(insecure)
                    .build()
                    .unwrap_or_else(|_| reqwest::Client::new()),
            });
    }
-        g.as_ref().unwrap().client.clone()
+    /// 取（并惰性构建）对应 insecure 的 reqwest client（普通请求，10s 总超时）。
    fn client(&self, insecure: bool) -> reqwest::Client {
        slot_client(&self.client, insecure, false)
    }
    /// 取流式请求专用 client（无总超时）。
    fn stream_client(&self, insecure: bool) -> reqwest::Client {
        slot_client(&self.stream_client, insecure, true)
    }
    /// 从持久化设置刷新运行期连接与代理配置（以激活连接为准；幂等）。
    pub fn sync_with_settings(&self, s: &MusicSettings) {
-        let (base_url, token, username, device_id, access_code, insecure) =
+        let (base_url, token, username, device_id, access_code, insecure, relay) =
            match s.feiniu_active() {
                Some(c) => (
                    c.base_url.clone(),
-                    c.token.clone(),
+                    // token 常态存放在系统凭据管理器（见 crate::music::secrets），
                    // 结构体字段为空；只有凭据库不可用（降级）时才回落到明文。
                    if c.token.is_empty() {
                        super::secrets::read_feiniu_token(&c.id)
                    } else {
                        c.token.clone()
                    },
                    c.username.clone(),
                    c.device_id.clone(),
                    c.access_code.clone(),
                    c.insecure,
                    c.relay,
                ),
                None => (
                    String::new(),
@@ -150,6 +196,7 @@ impl Feiniu {
                    String::new(),
                    String::new(),
                    false,
                    false,
                ),
            };
        if let Ok(mut c) = self.conn.lock() {
@@ -159,6 +206,7 @@ impl Feiniu {
            c.device_id = device_id;
            c.access_code = access_code;
            c.insecure = insecure;
            c.relay = relay;
        }
        // 确保 client 构建到位（insecure 变化时重建）
        self.client(insecure);
@@ -178,7 +226,8 @@ impl Feiniu {
    }
    fn sync_proxy_client(&self) {
-        let (_, client) = self.conn_client();
+        // 代理必须用流式 client：普通 client 的 10s 总超时会把长音频流掐断
        let (_, client) = self.conn_stream_client();
        if let Ok(mut g) = self.proxy.lock() {
            if let Some((_, shared)) = g.as_mut() {
                shared.client = client;
@@ -191,18 +240,44 @@ impl Feiniu {
        (insecure, self.client(insecure))
    }
    fn conn_stream_client(&self) -> (bool, reqwest::Client) {
        let insecure = self.conn.lock().unwrap_or_else(|e| e.into_inner()).insecure;
        (insecure, self.stream_client(insecure))
    }
    fn current_cfg(&self) -> ProxyCfg {
        let c = self.conn.lock().unwrap_or_else(|e| e.into_inner());
        ProxyCfg {
            base_url: c.base_url.clone(),
            token: c.token.clone(),
            access_code: c.access_code.clone(),
            relay: c.relay,
        }
    }
-    fn auth_triple(&self) -> (String, String, String) {
+    /// 构造鉴权 Cookie 头。
    ///
    /// 中继链路需把 `mode=relay` 与 `music-token` 合并进**同一个** Cookie 头
    /// （拆成两个 Cookie 头会互相覆盖）；未登录的中继请求只带 `mode=relay`。
    /// 无 token 且非中继时返回 None，表示无需携带 Cookie。
    fn auth_cookie(token: &str, relay: bool) -> Option<String> {
        match (token.is_empty(), relay) {
            (false, true) => Some(format!("music-token={token}; mode=relay")),
            (false, false) => Some(format!("music-token={token}")),
            (true, true) => Some("mode=relay".to_string()),
            (true, false) => None,
        }
    }
    /// 鉴权上下文：`(base_url, token, access_code, relay)`。
    fn auth_triple(&self) -> (String, String, String, bool) {
        let c = self.conn.lock().unwrap_or_else(|e| e.into_inner());
-        (c.base_url.clone(), c.token.clone(), c.access_code.clone())
+        (
            c.base_url.clone(),
            c.token.clone(),
            c.access_code.clone(),
            c.relay,
        )
    }
    /// 对某个 base_url 执行登录（探测/登录连接共用）。
@@ -228,10 +303,20 @@ impl Feiniu {
            "password": sha256_hex(password),
            "deviceId": device_id,
        });
-        let resp = self
+        let relay = self
            .conn
            .lock()
            .unwrap_or_else(|e| e.into_inner())
            .relay;
        let mut rb = self
            .client(insecure)
            .post(format!("{base}/music/api/v1/user/password-login"))
-            .json(&body)
+            .json(&body);
        // 中继链路：登录请求也需带 mode=relay，否则网关 302 回登录页
        if let Some(cookie) = Self::auth_cookie("", relay) {
            rb = rb.header("cookie", cookie);
        }
        let resp = rb
            .send()
            .await
            .map_err(|e| {
@@ -321,53 +406,6 @@ impl Feiniu {
        Ok(format!("http://127.0.0.1:{port}/feiniu"))
    }
    /// 递归扫描本地曲库目录中的音频文件，返回轻量条目（不解析时长/封面）。
    pub fn scan_local(&self, dirs: &[String]) -> Value {
        const EXTS: [&str; 7] = ["mp3", "flac", "wav", "m4a", "aac", "ogg", "ape"];
        let mut items: Vec<Value> = Vec::new();
        for dir in dirs {
            let p = Path::new(dir);
            if !p.is_dir() {
                continue;
            }
            for entry in walkdir::WalkDir::new(p).follow_links(false) {
                let Ok(entry) = entry else { continue };
                if !entry.file_type().is_file() {
                    continue;
                }
                let path = entry.path();
                let ext = path
                    .extension()
                    .and_then(|e| e.to_str())
                    .map(|e| e.to_lowercase())
                    .unwrap_or_default();
                if !EXTS.contains(&ext.as_str()) {
                    continue;
                }
                let size = entry.metadata().map(|m| m.len()).unwrap_or(0);
                let mtim = entry
                    .metadata()
                    .ok()
                    .and_then(|m| m.modified().ok())
                    .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
                    .map(|d| d.as_secs())
                    .unwrap_or(0);
                let name = path
                    .file_stem()
                    .and_then(|n| n.to_str())
                    .unwrap_or("未知")
                    .to_string();
                items.push(json!({
                    "path": path.to_string_lossy(),
                    "title": name,
                    "size": size,
                    "mtim": mtim,
                    "dir": dir,
                }));
            }
        }
        json!({ "items": items })
    }
    /// 缓存状态。
    pub fn cache_status(&self) -> Value {
@@ -385,13 +423,16 @@ impl Feiniu {
        if let Some(hit) = self.cache.hit(guid) {
            return Ok(Some(hit));
        }
-        let (base, token, access_code) = self.auth_triple();
+        let (base, token, access_code, relay) = self.auth_triple();
        if base.is_empty() || token.is_empty() {
            return Err("未登录".into());
        }
-        let (_, client) = self.conn_client();
+        // 整首拉取写入缓存：同样用无总超时的 client，否则大文件会被 10s 超时截断
        let (_, client) = self.conn_stream_client();
        let mut rb = client.get(format!("{base}/music/api/v1/track/stream?guid={guid}"));
-        rb = rb.header("cookie", format!("music-token={token}"));
+        if let Some(cookie) = Self::auth_cookie(&token, relay) {
            rb = rb.header("cookie", cookie);
        }
        if !access_code.is_empty() {
            use base64::Engine;
            rb = rb
@@ -439,7 +480,8 @@ impl Feiniu {
                return Ok(*port);
            }
        }
-        let (_, client) = self.conn_client();
+        // 流代理用无总超时的 client（见 build_client）
        let (_, client) = self.conn_stream_client();
        let shared = ProxyShared {
            client,
            cfg: Arc::new(Mutex::new(self.current_cfg())),
@@ -452,14 +494,16 @@ impl Feiniu {
    }
    async fn authed_get(&self, path: &str, query: Vec<(String, String)>) -> Result<Value, String> {
-        let (base, token, access_code) = self.auth_triple();
+        let (base, token, access_code, relay) = self.auth_triple();
        if base.is_empty() || token.is_empty() {
            return Err("未登录".into());
        }
        let (_, client) = self.conn_client();
        let qrefs: Vec<(&str, &str)> = query.iter().map(|(k, v)| (k.as_str(), v.as_str())).collect();
        let mut rb = client.get(format!("{base}{path}")).query(&qrefs);
-        rb = rb.header("cookie", format!("music-token={token}"));
+        if let Some(cookie) = Self::auth_cookie(&token, relay) {
            rb = rb.header("cookie", cookie);
        }
        if !access_code.is_empty() {
            use base64::Engine;
            rb = rb
@@ -490,6 +534,190 @@ impl Feiniu {
    }
 }
 /// 本地曲库 / 下载目录里认可的音频扩展名。
 /// 扫描（递归）与单目录列举共用同一份，避免两处判定不一致。
 pub const AUDIO_EXTS: [&str; 7] = ["mp3", "flac", "wav", "m4a", "aac", "ogg", "ape"];
 /// 该路径是否为认可的音频文件（只看扩展名，不校验存在性）。
 pub fn is_audio_path(path: &Path) -> bool {
    path.extension()
        .and_then(|e| e.to_str())
        .map(|e| AUDIO_EXTS.contains(&e.to_lowercase().as_str()))
        .unwrap_or(false)
 }
 /// 列出一个**目录**（非递归）下的音频文件：`{ items: [{path,name,size,mtim}] }`。
 ///
 /// 与 [`scan_local_dirs`] 的分工：那个是「曲库全量扫描 + 标签解析」，
 /// 用于曲库视图；这个是「只看一层目录、不读标签」的轻量列举，
 /// 用于上传编排（只需在下载目录里找到刚落盘的文件）。
 /// 为一次上传去递归遍历整个曲库目录是纯浪费。
 pub fn list_audio_files(dir: &str) -> Value {
    let mut items: Vec<Value> = Vec::new();
    let p = Path::new(dir);
    if !p.is_dir() {
        return json!({ "items": items });
    }
    let Ok(entries) = fs::read_dir(p) else {
        return json!({ "items": items });
    };
    for entry in entries.flatten() {
        let path = entry.path();
        if !path.is_file() || !is_audio_path(&path) {
            continue;
        }
        let size = entry.metadata().map(|m| m.len()).unwrap_or(0);
        let mtim = entry
            .metadata()
            .ok()
            .and_then(|m| m.modified().ok())
            .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
            .map(|d| d.as_secs())
            .unwrap_or(0);
        let name = path
            .file_stem()
            .and_then(|n| n.to_str())
            .unwrap_or("未知")
            .to_string();
        items.push(json!({
            "path": path.to_string_lossy(),
            "name": name,
            "size": size,
            "mtim": mtim,
        }));
    }
    json!({ "items": items })
 }
 /// 递归扫描本地曲库目录中的音频文件，返回轻量条目。
 ///
 /// 元数据（标题/歌手/专辑/时长/是否有内嵌封面）用 lofty 解析音频标签；
 /// 结果按 path 缓存（size+mtim 未变即复用），避免万级曲库每次全量重解析。
 /// `tags_cache_path` 为标签缓存文件路径（由命令层传入 CacheManager）。
 ///
 /// **纯函数（不依赖 &self）**：全量解析是重活，命令层必须把它放进
 /// `spawn_blocking`（Tauri 的同步命令在主线程执行，会冻结 UI）。
 pub fn scan_local_dirs(dirs: &[String], tags_cache_path: Option<&Path>) -> Value {
    // ---- 标签缓存 ----
    let mut tag_cache: serde_json::Map<String, Value> = tags_cache_path
        .and_then(|p| fs::read_to_string(p).ok())
        .and_then(|s| serde_json::from_str(&s).ok())
        .unwrap_or_default();
    let cache_hit = |cache: &serde_json::Map<String, Value>,
                     path: &str,
                     size: u64,
                     mtim: u64|
     -> Option<Value> {
        cache
            .get(path)
            .and_then(|v| v.as_object())
            .filter(|e| {
                e.get("size").and_then(|x| x.as_u64()) == Some(size)
                    && e.get("mtim").and_then(|x| x.as_u64()) == Some(mtim)
            })
            .map(|e| Value::Object(e.clone()))
    };
    let mut items: Vec<Value> = Vec::new();
    // 本次扫描命中的音频路径：用于修剪缓存（见函数末尾）
    let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
    // 至少有一个目录可访问才允许修剪，避免目录临时不可用（外接盘未挂载）时清空整个缓存
    let mut scanned_any_dir = false;
    for dir in dirs {
        let p = Path::new(dir);
        if !p.is_dir() {
            continue;
        }
        scanned_any_dir = true;
        for entry in walkdir::WalkDir::new(p).follow_links(false) {
            let Ok(entry) = entry else { continue };
            if !entry.file_type().is_file() {
                continue;
            }
                let path = entry.path();
                if !is_audio_path(path) {
                    continue;
                }
            let size = entry.metadata().map(|m| m.len()).unwrap_or(0);
            let mtim = entry
                .metadata()
                .ok()
                .and_then(|m| m.modified().ok())
                .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
                .map(|d| d.as_secs())
                .unwrap_or(0);
            let path_str = path.to_string_lossy().to_string();
            let name = path
                .file_stem()
                .and_then(|n| n.to_str())
                .unwrap_or("未知")
                .to_string();
            seen.insert(path_str.clone());
            // 标签：命中缓存直接复用；否则 lofty 解析并写回缓存
            let tags = match cache_hit(&tag_cache, &path_str, size, mtim) {
                Some(hit) => hit,
                None => {
                    let mut t = json!({
                        "size": size,
                        "mtim": mtim,
                        "title": name,
                        "artist": "",
                        "album": "",
                        "durationS": 0,
                        "cover": false,
                    });
                    if let Ok(tagged) = lofty::read_from_path(path) {
                        let tag = tagged.primary_tag().or_else(|| tagged.first_tag());
                        if let Some(tag) = tag {
                            if let Some(v) = tag.title().filter(|s| !s.trim().is_empty()) {
                                t["title"] = json!(v.trim());
                            }
                            if let Some(v) = tag.artist().filter(|s| !s.trim().is_empty()) {
                                t["artist"] = json!(v.trim());
                            }
                            if let Some(v) = tag.album().filter(|s| !s.trim().is_empty()) {
                                t["album"] = json!(v.trim());
                            }
                            t["cover"] = json!(!tag.pictures().is_empty());
                        }
                        let secs = tagged.properties().duration().as_secs();
                        if secs > 0 {
                            t["durationS"] = json!(secs);
                        }
                    }
                    tag_cache.insert(path_str.clone(), t.clone());
                    t
                }
            };
            items.push(json!({
                "path": path_str,
                "name": name,
                "title": tags.get("title").cloned().unwrap_or(json!(name)),
                "artist": tags.get("artist").cloned().unwrap_or(json!("")),
                "album": tags.get("album").cloned().unwrap_or(json!("")),
                "durationS": tags.get("durationS").cloned().unwrap_or(json!(0)),
                "cover": tags.get("cover").cloned().unwrap_or(json!(false)),
                "size": size,
                "mtim": mtim,
                "dir": dir,
            }));
        }
    }
    // 修剪：删掉本次扫描中未再出现的缓存条目（文件已删除/改名/移出曲库目录）。
    // 只增不减的缓存会随使用时间无限膨胀，且每次扫描都要整份读写。
    if scanned_any_dir {
        tag_cache.retain(|k, _| seen.contains(k));
    }
    if let Some(p) = tags_cache_path {
        if let Ok(s) = serde_json::to_string(&tag_cache) {
            fs::write(p, s).ok();
        }
    }
    json!({ "items": items })
 }
 /// 尽力从 /lyric/list 响应中取第一段歌词文本（响应结构未文档化，做宽松映射）。
 fn extract_lyric_text(v: &Value) -> String {
    match v {
@@ -15,6 +15,8 @@ use axum::{
    Router,
 };
 use lofty::file::TaggedFileExt;
 use super::conn::normalize_base_url;
 /// 由 Feiniu 运行期与代理 handler 共享的连接配置（登录更新、登出置空）。
@@ -23,6 +25,8 @@ pub struct ProxyCfg {
    pub base_url: String,
    pub token: String,
    pub access_code: String,
    /// FnConnect 中继链路：所有请求需携带 `Cookie: mode=relay`
    pub relay: bool,
 }
 #[derive(Clone)]
@@ -44,6 +48,7 @@ pub async fn start(shared: ProxyShared) -> Result<u16, String> {
    let app = Router::new()
        .route("/feiniu/stream", get(proxy_stream))
        .route("/feiniu/cover", get(proxy_cover))
        .route("/feiniu/local-cover", get(proxy_local_cover))
        .with_state(shared);
    tokio::spawn(async move {
        if let Err(e) = axum::serve(listener, app).await {
@@ -53,6 +58,48 @@ pub async fn start(shared: ProxyShared) -> Result<u16, String> {
    Ok(port)
 }
 /// 本地音频文件的内嵌封面：`GET /feiniu/local-cover?path=<绝对路径>`。
 ///
 /// 供「本地曲库」列表显示封面（无需 NAS 登录）。只接受音频扩展名，且必须
 /// 能被 lofty 解析出内嵌图片——非音频文件在这里必然 404，不构成任意文件读取。
 /// 响应带 immutable 缓存头：path 不变时 WebView 直接复用。
 async fn proxy_local_cover(Query(q): Query<HashMap<String, String>>) -> Response {
    const AUDIO_EXTS: [&str; 7] = ["mp3", "flac", "wav", "m4a", "aac", "ogg", "ape"];
    let Some(path) = q.get("path") else {
        return (StatusCode::BAD_REQUEST, "missing path").into_response();
    };
    let p = std::path::Path::new(path);
    let ext_ok = p
        .extension()
        .and_then(|e| e.to_str())
        .map(|e| AUDIO_EXTS.contains(&e.to_lowercase().as_str()))
        .unwrap_or(false);
    if !ext_ok || !p.is_file() {
        return StatusCode::NOT_FOUND.into_response();
    }
    let picture = lofty::read_from_path(p).ok().and_then(|tagged| {
        tagged
            .primary_tag()
            .or_else(|| tagged.first_tag())
            .and_then(|t| t.pictures().first())
            .cloned()
    });
    let Some(pic) = picture else {
        return StatusCode::NOT_FOUND.into_response();
    };
    // lofty 0.22 的 mime_type 返回 Option<MimeType>
    let mime = pic
        .mime_type()
        .map(|m| m.to_string())
        .unwrap_or_else(|| "image/jpeg".to_string());
    let mut resp = ([(header::CONTENT_TYPE, mime)], pic.data().to_vec()).into_response();
    resp.headers_mut().insert(
        header::CACHE_CONTROL,
        header::HeaderValue::from_static("public, max-age=2592000, immutable"),
    );
    resp
 }
 async fn proxy_stream(
    State(s): State<ProxyShared>,
    Query(q): Query<HashMap<String, String>>,
@@ -118,7 +165,15 @@ async fn forward(
    let qrefs: Vec<(&str, &str)> = query.iter().map(|(k, v)| (k.as_str(), v.as_str())).collect();
    let mut rb = s.client.get(&url).query(&qrefs);
-    rb = rb.header("cookie", format!("music-token={}", cfg.token));
+    // 中继链路必须带 mode=relay，网关据此转发到 NAS（与 music-token 合并进同一个 Cookie 头）。
    rb = rb.header(
        "cookie",
        if cfg.relay {
            format!("music-token={}; mode=relay", cfg.token)
        } else {
            format!("music-token={}", cfg.token)
        },
    );
    if !cfg.access_code.is_empty() {
        use base64::Engine;
        rb = rb
@@ -143,6 +198,12 @@ async fn forward(
    let cl = resp.headers().get(header::CONTENT_LENGTH).cloned();
    let cr = resp.headers().get(header::CONTENT_RANGE).cloned();
    let ar = resp.headers().get(header::ACCEPT_RANGES).cloned();
    // 缓存头必须透传：NAS 的封面接口带 `public, max-age=2592000, immutable`，
    // 丢掉它就等于告诉 WebView「这个响应不可缓存」——每次进曲库页都要重新下载全部封面。
    let cc = resp.headers().get(header::CACHE_CONTROL).cloned();
    let et = resp.headers().get(header::ETAG).cloned();
    let lm = resp.headers().get(header::LAST_MODIFIED).cloned();
    let ex = resp.headers().get(header::EXPIRES).cloned();
    let body = axum::body::Body::from_stream(resp.bytes_stream());
    let mut out = Response::new(body);
@@ -160,5 +221,17 @@ async fn forward(
    if let Some(v) = ar {
        h.insert(header::ACCEPT_RANGES, v);
    }
    if let Some(v) = cc {
        h.insert(header::CACHE_CONTROL, v);
    }
    if let Some(v) = et {
        h.insert(header::ETAG, v);
    }
    if let Some(v) = lm {
        h.insert(header::LAST_MODIFIED, v);
    }
    if let Some(v) = ex {
        h.insert(header::EXPIRES, v);
    }
    out
 }
@@ -202,16 +202,4 @@ pub fn mime_of(name: &str) -> &'static str {
    }
 }
-/// 保留给调用方校验配置完整性。
+
 pub fn validate(cfg: &WebDavConfig, dir: &str) -> Result<(), String> {
    if cfg.url.trim().is_empty() {
        return Err("请先填写 WebDAV 服务地址（如 http://192.168.110.100:5005）".into());
    }
    if cfg.username.trim().is_empty() {
        return Err("请先填写 WebDAV 账号".into());
    }
    if dir.trim().is_empty() {
        return Err("请先填写 WebDAV 曲库目标目录".into());
    }
    Ok(())
 }
@@ -19,18 +19,23 @@ mod bridge;
 mod commands;
 mod feiniu;
 mod runtime;
 mod secrets;
-pub use feiniu::{extract_fn_id, normalize_base_url, resolve_base_url, Feiniu, FeiniuConnection};
+pub use feiniu::{
    extract_fn_id, normalize_base_url, resolve_base_url, scan_local_dirs, Feiniu, FeiniuConnection,
 };
 pub use commands::{
    feiniu_activate_connection, feiniu_cache_clear, feiniu_cache_fetch, feiniu_cache_status,
    feiniu_delete_connection, feiniu_delete_local, feiniu_fnconnect_resolve, feiniu_get_config,
-    feiniu_list_connections, feiniu_list_tracks, feiniu_login, feiniu_logout, feiniu_lyric,
+    feiniu_list_connections, feiniu_list_audio_files, feiniu_list_tracks, feiniu_login,
    feiniu_logout, feiniu_lyric,
    feiniu_media_prefix, feiniu_save_connection, feiniu_scan_local, feiniu_test_connection,
    music_cancel_runtime_install, music_download, music_download_cancel, music_env_status,
    music_get_settings, music_get_sources, music_install_runtime, music_parse_playlist, music_ping,
-    music_resolve, music_save_settings, music_search, music_stop_bridge, webdav_delete,
+    music_resolve, music_save_settings, music_search, music_secret_get, music_secret_set,
-    webdav_get_secret, webdav_save_secret, webdav_test, webdav_upload,
+    music_stop_bridge, music_update_musicdl, webdav_delete, webdav_get_secret,
    webdav_save_secret, webdav_test, webdav_upload,
 };
 use serde::{Deserialize, Serialize};
@@ -84,6 +89,11 @@ pub struct MusicEnvStatus {
    pub musicdl_installed: bool,
    /// musicdl 版本
    pub musicdl_version: Option<String>,
    /// 本应用锁定的 musicdl 版本（`MUSICDL_VERSION`）：是否过期、更新到哪个版本都以它为准
    pub musicdl_expected: String,
    /// 已装 musicdl 是否与锁定版本不一致。
    /// 未安装时恒为 false（那是「安装」引导的事，不是「更新」）。
    pub musicdl_outdated: bool,
    /// FFmpeg 是否可用（部分音源需要，非必需）
    pub ffmpeg: Option<String>,
    /// 桥接进程是否在运行
@@ -125,6 +135,10 @@ pub struct MusicSettings {
    pub select_quality_on_download: bool,
    /// 下载时默认音质："" 表示最高；否则为搜索音质档位 label（如 "无损"、"320K"）
    pub default_download_quality: String,
    /// QQ 音乐 Cookie（可选）：用于解析需要登录的歌单（含自己的隐私歌单）与 VIP 音质。
    /// 传给 musicdl 的 default_search/parse/download_cookies；空=游客身份。
    #[serde(default)]
    pub qq_cookie: String,
    /// 飞牛音乐(NAS)连接：服务器地址（如 http://192.168.1.10:5666，空=未配置）
    #[serde(default)]
    pub feiniu_base_url: String,
@@ -140,7 +154,7 @@ pub struct MusicSettings {
    /// 飞牛音乐访问安全码（可选；仅需访问码的库才填，LAN 通常为空）
    #[serde(default)]
    pub feiniu_access_code: String,
-    /// 飞牛音乐连接列表（多连接：本地 / frp / 预留 fnconnect）
+    /// 飞牛音乐连接列表（多连接：局域网 / FnConnect）
    #[serde(default)]
    pub feiniu_connections: Vec<FeiniuConnection>,
    /// 当前激活连接的 id
@@ -175,10 +189,17 @@ impl MusicSettings {
            .or_else(|| self.feiniu_connections.first())
    }
-    /// 兼容旧版单连接字段：若连接列表为空且存在旧 feiniu_* 字段，则迁移为一条默认连接。
+    /// 兼容旧版单连接字段：把旧字段迁移成列表里的一条连接，并**清除旧字段**。
-    pub fn migrate_feiniu(&mut self) {
+    ///
-        if self.feiniu_connections.is_empty() {
+    /// 必须是「一次性」的：旧字段一旦残留，用户把连接删光后，下一次 `load_settings()`
-            if !self.feiniu_base_url.trim().is_empty() {
+    /// 会再次命中「列表为空 + 旧字段非空」而重新造出一条连接，
    /// 表现为「删掉的连接切个页又回来了」。因此迁移完成后要清空旧字段，
    /// 且返回是否发生变更，由 `load_settings` 负责落盘。
    pub fn migrate_feiniu(&mut self) -> bool {
        let mut changed = false;
        // 1) 旧单连接字段 → 连接列表（仅在列表为空时迁移）
        if self.feiniu_connections.is_empty() && !self.feiniu_base_url.trim().is_empty() {
            let base = self.feiniu_base_url.clone();
            self.feiniu_connections.push(FeiniuConnection {
                id: "default".to_string(),
@@ -191,16 +212,61 @@ impl MusicSettings {
                access_code: self.feiniu_access_code.clone(),
                insecure: false,
                fn_id: String::new(),
                relay: false,
            });
            self.feiniu_active_id = "default".to_string();
            changed = true;
        }
-        } else if self.feiniu_active_id.is_empty()
+
        // 2) 无论列表是否为空，旧字段都已无意义（内容已并入连接，或本就没有连接），
        //    一律清空并落盘，杜绝其再次触发迁移。
        for v in [
            &mut self.feiniu_base_url,
            &mut self.feiniu_token,
            &mut self.feiniu_username,
            &mut self.feiniu_device_id,
            &mut self.feiniu_access_code,
        ] {
            if !v.is_empty() {
                v.clear();
                changed = true;
            }
        }
        // 3) 激活 id 兜底（内存态修正，无需落盘）
        if self.feiniu_active_id.is_empty()
            || !self.feiniu_connections.iter().any(|c| c.id == self.feiniu_active_id)
        {
            if let Some(c) = self.feiniu_connections.first() {
                self.feiniu_active_id = c.id.clone();
            }
        }
        changed
    }
    /// 把明文凭据迁入系统凭据管理器，并从结构体里清掉（返回是否有变更）。
    ///
    /// 与 `migrate_feiniu` 同一套「一次性迁移」原则：**凭据库写入成功才清明文**，
    /// 并由 `load_settings` 落盘，避免每次读取反复尝试。
    /// 写失败时保留明文——宁可姿态不一致，也不能让用户莫名掉登录态。
    pub fn migrate_secrets(&mut self) -> bool {
        let mut changed = false;
        for c in self.feiniu_connections.iter_mut() {
            let token = c.token.trim().to_string();
            if token.is_empty() {
                continue;
            }
            let key = secrets::feiniu_token_key(&c.id);
            // 凭据库已有值时不覆盖：它可能比 settings.json 里的明文更新
            let stored = secrets::secret_read(&key).ok().flatten().unwrap_or_default();
            if stored.is_empty() && !secrets::try_store(&key, &token) {
                continue;
            }
            c.token.clear();
            changed = true;
        }
        changed
    }
 }
@@ -292,6 +358,7 @@ impl MusicManager {
            download_engine: "musicdl".to_string(),
            select_quality_on_download: false,
            default_download_quality: "最高".to_string(), // 默认下载最高音质
            qq_cookie: String::new(),
            feiniu_base_url: String::new(),
            feiniu_token: String::new(),
            feiniu_username: String::new(),
@@ -338,14 +405,22 @@ impl MusicManager {
        if settings.sources.is_empty() {
            settings.sources = defaults.sources;
        }
-        // 飞牛音乐多连接迁移：旧单连接字段 → 连接列表
+        // 飞牛音乐多连接迁移：旧单连接字段 → 连接列表，并清除旧字段。
-        settings.migrate_feiniu();
+        // 变更必须落盘，否则每次读取都会重新迁移，导致删掉的连接"复活"。
        let migrated = settings.migrate_feiniu();
        // 明文凭据（连接 token）→ 系统凭据管理器，成功后从结构体清除。
        let secrets_migrated = settings.migrate_secrets();
        if let Ok(mut cache) = self.settings_cache.lock() {
            *cache = Some(SettingsCacheEntry {
                read_at: Instant::now(),
                settings: settings.clone(),
            });
        }
        if migrated || secrets_migrated {
            if let Err(e) = self.save_settings(&settings) {
                crate::logger::log_error("music", &format!("迁移飞牛连接设置落盘失败: {e}"));
            }
        }
        settings
    }
@@ -412,7 +487,10 @@ impl MusicManager {
            python_source: probe.python_source.to_string(),
            bundled_python: probe.bundled_python,
            musicdl_installed: probe.musicdl_installed,
            musicdl_outdated: probe.musicdl_installed
                && !version_matches(probe.musicdl_version.as_deref(), MUSICDL_VERSION),
            musicdl_version: probe.musicdl_version,
            musicdl_expected: MUSICDL_VERSION.to_string(),
            ffmpeg: probe.ffmpeg,
            bridge_running,
            runtime_dir,
@@ -554,6 +632,16 @@ fn parse_python_version(text: &str) -> Option<String> {
    })
 }
 /// 已装版本是否就是本应用锁定的版本。
 ///
 /// `unknown` / 空值一律视为**不匹配**：`check_musicdl` 拿不到 `__version__` 时
 /// 无法确认它是不是受支持的那一版，宁可提示更新。
 /// 兼容 `v2.13.11` 这类带前缀的写法。
 fn version_matches(installed: Option<&str>, expected: &str) -> bool {
    let v = installed.unwrap_or("").trim().trim_start_matches('v');
    !v.is_empty() && !v.eq_ignore_ascii_case("unknown") && v == expected
 }
 /// 检查指定 Python 能否导入 musicdl（同步子进程调用，仅在设置页触发）
 fn check_musicdl(exe: &PathBuf) -> (bool, Option<String>) {
    let mut cmd = std::process::Command::new(exe);
@@ -158,6 +158,86 @@ impl MusicManager {
        ok
    }
    /// 把已装的 musicdl 对齐到本应用锁定的版本（`MUSICDL_VERSION`）。
    ///
    /// 为什么必须有这个动作：`install_runtime_inner` 的闸门是「能否 import」而不是
    /// 「版本是否一致」——仅升级应用（哪怕代码里的锁定版本提高了）**不会**触发 pip，
    /// 已装环境会永远停在旧版本。这里显式执行 `pip install --upgrade musicdl==<pinned>`；
    /// `force = true` 用 `--force-reinstall` 兜住「能 import 但依赖已损坏」的灰区
    /// （`check_musicdl` 只验证 `import musicdl` 与 `__version__`，证明不了子模块可用）。
    ///
    /// 只允许升到**锁定版本**，绝不升到 PyPI 最新：`bridge.py` 对 musicdl 的 monkey patch
    /// 与版本强耦合（第三方解析链方法名、各源搜索字段映射、音质常量前缀），
    /// 任意升版会静默破坏解析链。升锁定版本时必须同步核对那些补丁。
    pub async fn update_musicdl(&self, app: &AppHandle, force: bool) -> Result<(), String> {
        self.runtime_cancel.store(false, std::sync::atomic::Ordering::SeqCst);
        let result = self.update_musicdl_inner(app, force).await;
        if let Err(ref e) = result {
            if e != RUNTIME_CANCELLED {
                let _ = app.emit(
                    MUSIC_RUNTIME_INSTALL_PROGRESS,
                    MusicInstallProgress {
                        stage: "error".into(),
                        percent: 0,
                        downloaded_bytes: 0,
                        total_bytes: None,
                        message: e.clone(),
                    },
                );
            }
        }
        result
    }
    async fn update_musicdl_inner(&self, app: &AppHandle, force: bool) -> Result<(), String> {
        let python_exe = self.bundled_python_exe();
        // 便携 Python 不可用（或跑不起来）：直接走完整安装流程，
        // 它会把 Python / pip / setuptools / musicdl 一次装齐
        if !(python_exe.exists() && super::run_python_version(&python_exe).is_some()) {
            return self.install_runtime_inner(app).await;
        }
        let mut args: Vec<String> = vec![
            "-m".into(),
            "pip".into(),
            "install".into(),
            "--no-warn-script-location".into(),
            "--timeout".into(),
            "60".into(),
            "--index-url".into(),
            PIP_INDEX_URL.into(),
        ];
        args.push(if force {
            "--force-reinstall".into()
        } else {
            "--upgrade".into()
        });
        args.push(format!("musicdl=={}", super::MUSICDL_VERSION));
        let msg = if force {
            "正在修复 musicdl（强制重装，依赖较多，可能需几分钟）...".to_string()
        } else {
            format!("正在更新 musicdl 到 {}...", super::MUSICDL_VERSION)
        };
        let exe = python_exe.clone();
        self.run_blocking_step(
            app,
            "musicdl",
            10,
            95,
            move |pid| {
                let mut cmd = std::process::Command::new(&exe);
                cmd.args(&args);
                run_cmd_blocking(cmd, pid)
            },
            &msg,
        )
        .await?;
        self.emit_progress(app, "done", 100, 0, None, "musicdl 已对齐到锁定版本")
            .await;
        Ok(())
    }
    // ---------- 阶段工具 ----------
    async fn emit_progress(
        &self,
@@ -0,0 +1,54 @@
 //! 音乐模块的凭据键约定与便捷读取。
 //!
 //! 底层读写原语已抽到 crate 级 [`crate::secrets`]（同一套 `Thing` 服务名与迁移
 //! 策略，翻译模块等其他使用者共享）。本文件只保留**音乐自己的键名**与
 //! 「前端可达范围」这道闸门，读写一律委托给公共模块，避免出现第二套实现。
 //!
 //! 约定：
 //! - 一律使用 `Thing` 作为凭据服务名，`key` 作为用户名（Entry 的 account）。
 //!   服务名是历史值，改动会导致已有凭据读不到。
 //! - 明文只允许存在于内存与系统凭据库，禁止回写 `settings.json` / localStorage。
 //! - 迁移采用「先写凭据库成功、再清明文」的顺序；**写失败时保留明文**，
 //!   宁可牺牲一致性也不能把用户已登录的会话弄丢。
 //! - 非 Windows 平台没有凭据管理器：读取返回 None、写入报错，
 //!   调用方据此退化为「明文存 settings」（功能优先）。
 pub use crate::secrets::{secret_delete, secret_read, secret_write, try_store};
 /// WebDAV 凭据的 key（**历史值，不可更改**）。
 pub const KEY_WEBDAV: &str = "webdav-credentials";
 /// QQ 音乐 Cookie 的 key（前端 `musicStore` 使用）。
 pub const KEY_QQ_COOKIE: &str = "music-qq-cookie";
 /// 允许**前端**通过 `music_secret_*` 命令读写的凭据键白名单。
 ///
 /// 用白名单而不是前缀匹配：前端不该有能力枚举/试探凭据库，
 /// `webdav-credentials` 与飞牛 token 因此都在前端的可达范围之外。
 /// 新增键必须在此显式登记（改 Rust 代码），这是一道有意的闸门。
 pub const FRONTEND_KEYS: [&str; 1] = [KEY_QQ_COOKIE];
 /// 飞牛连接 token 的 key 前缀（**只由后端使用**，不暴露给前端）。
 const TOKEN_KEY_PREFIX: &str = "music-feiniu-token-";
 /// 某条飞牛连接的登录 token 的 key。
 pub fn feiniu_token_key(connection_id: &str) -> String {
    format!("{TOKEN_KEY_PREFIX}{connection_id}")
 }
 /// 前端是否允许访问该凭据键。
 pub fn frontend_key_allowed(key: &str) -> bool {
    FRONTEND_KEYS.contains(&key)
 }
 /// 读取飞牛连接 token；未配置或读取失败 → 空串（等价于未登录）。
 pub fn read_feiniu_token(connection_id: &str) -> String {
    if connection_id.is_empty() {
        return String::new();
    }
    crate::secrets::read_or_empty(&feiniu_token_key(connection_id))
 }
 /// 该连接是否已有可用 token（供前端展示「已登录」）。
 pub fn has_feiniu_token(connection_id: &str) -> bool {
    !read_feiniu_token(connection_id).is_empty()
 }
@@ -0,0 +1,110 @@
 //! 敏感串的统一存放处（Windows 系统凭据管理器，DPAPI 保护）。
 //!
 //! 从 `music::secrets` 抽出为 crate 级公共模块。抽出的理由：本项目早期出现过
 //! **两种安全姿态**——WebDAV 账号密码走凭据管理器，而飞牛登录 token 与 QQ 音乐
 //! Cookie 明文躺在 `settings.json` / localStorage。同样是可冒充身份的凭据，不该
 //! 区别对待。此后翻译模块又要接入多家 AI 的 API Key，若每个模块自带一套实现，
 //! 姿态只会再次分叉，因此把「原语」收敛到这里，各模块只保留自己的键名约定。
 //!
 //! 约定：
 //! - 一律使用 `Thing` 作为凭据服务名，`key` 作为用户名（Entry 的 account）。
 //!   **服务名不可更改**：已有凭据（`webdav-credentials`、`music-feiniu-token-*`、
 //!   `music-qq-cookie`）都以它存盘，改动会导致这些凭据读不到。
 //! - 明文只允许存在于内存与系统凭据库，禁止回写 `settings.json` / localStorage。
 //! - 迁移采用「先写凭据库成功、再清明文」的顺序；**写失败时保留明文**，
 //!   宁可牺牲一致性也不能把用户已登录的会话弄丢。
 //! - 非 Windows 平台没有凭据管理器：读取返回 None、写入报错，
 //!   调用方据此退化为「明文存设置」（功能优先）。
 /// 凭据服务名（**历史值，不可更改**）。
 pub const SERVICE: &str = "Thing";
 /// 读取明文（未配置 → `Ok(None)`）。
 #[cfg(windows)]
 pub fn secret_read(key: &str) -> Result<Option<String>, String> {
    let entry =
        keyring::Entry::new(SERVICE, key).map_err(|e| format!("无法访问系统凭据管理器: {e}"))?;
    match entry.get_password() {
        Ok(v) => Ok(Some(v)),
        Err(keyring::Error::NoEntry) => Ok(None),
        Err(e) => Err(format!("读取凭据失败: {e}")),
    }
 }
 /// 写入明文（覆盖式）。
 #[cfg(windows)]
 pub fn secret_write(key: &str, value: &str) -> Result<(), String> {
    let entry =
        keyring::Entry::new(SERVICE, key).map_err(|e| format!("无法访问系统凭据管理器: {e}"))?;
    entry
        .set_password(value)
        .map_err(|e| format!("保存凭据失败: {e}"))
 }
 /// 删除凭据（不存在视为成功）。
 #[cfg(windows)]
 pub fn secret_delete(key: &str) -> Result<(), String> {
    let entry =
        keyring::Entry::new(SERVICE, key).map_err(|e| format!("无法访问系统凭据管理器: {e}"))?;
    match entry.delete_credential() {
        Ok(()) => Ok(()),
        Err(keyring::Error::NoEntry) => Ok(()),
        Err(e) => Err(format!("删除凭据失败: {e}")),
    }
 }
 #[cfg(not(windows))]
 pub fn secret_read(_key: &str) -> Result<Option<String>, String> {
    Ok(None)
 }
 #[cfg(not(windows))]
 pub fn secret_write(_key: &str, _value: &str) -> Result<(), String> {
    Err("当前平台不支持系统凭据管理器".to_string())
 }
 #[cfg(not(windows))]
 pub fn secret_delete(_key: &str) -> Result<(), String> {
    Ok(())
 }
 /// 把明文**尽力**迁入凭据库（失败只记日志，不抛错）。
 ///
 /// 返回「明文是否可以安全清除」：只有写入成功才为 true。
 /// 调用方用这个返回值决定要不要清空内存/配置里的明文。
 pub fn try_store(key: &str, value: &str) -> bool {
    if value.is_empty() {
        return true;
    }
    match secret_write(key, value) {
        Ok(()) => true,
        Err(e) => {
            crate::logger::log_error(
                "secrets",
                &format!("凭据 {key} 写入系统凭据管理器失败（保留明文作为降级）: {e}"),
            );
            false
        }
    }
 }
 /// 读取明文，失败或未配置一律退化为空串（调用方无需区分「没配」与「读不到」）。
 pub fn read_or_empty(key: &str) -> String {
    secret_read(key).ok().flatten().unwrap_or_default()
 }
 /// 掩码展示：保留前 3 位与后 4 位，中间以圆点替代。
 /// 长度不足时全部打码，绝不泄露完整明文。
 pub fn mask(value: &str) -> String {
    let v = value.trim();
    let n = v.chars().count();
    if n == 0 {
        return String::new();
    }
    if n <= 8 {
        return "•".repeat(n);
    }
    let head: String = v.chars().take(3).collect();
    let tail: String = v.chars().skip(n - 4).collect();
    format!("{head}••••{tail}")
 }
@@ -7,6 +7,7 @@
 //! - 下载：DownloadEngine + 扩展 HTTP API 服务
 //! - 剪贴板：ClipboardManager + 快捷键 + 预创建弹窗
 //! - 快速面板：快捷键 + 预创建弹窗 + 文件索引
 //! - 翻译：TranslateManager（设置与密钥按需读取，启动时不发网络请求）
 //! - 托盘：自定义菜单窗口
 //! - 进程：监控线程
@@ -20,6 +21,7 @@ use crate::monitor_kernel::{MonitorKernel, check_and_relaunch_if_needed};
 use crate::music::MusicManager;
 use crate::network_monitor::NetworkMonitor;
 use crate::process_manager::{ProcessManager, start_monitoring_thread};
 use crate::translate::TranslateManager;
 /// 应用启动初始化入口（setup 闭包调用）。
 /// 初始化顺序即依赖顺序：日志 → 数据目录 → 各管理器 → 托盘 → 进程监控 → 自动启动。
@@ -61,6 +63,15 @@ pub fn init(app: &mut App<Wry>) -> Result<(), Box<dyn std::error::Error>> {
    music.set_app(app.handle().clone());
    app.manage(music);
    // ===== 翻译模块：TranslateManager =====
    // 仅注册状态：设置与密钥都在命令调用时按需读取，启动阶段不发任何网络请求
    // （模型可用性校验因此改为懒校验：首次翻译失败时解释原因 + 设置页手动拉取模型列表）。
    let translate = TranslateManager::new(app_data_dir.clone());
    app.manage(translate);
    // 按设置注册「翻译取词 / 翻译剪贴板」两个全局快捷键并预创建悬浮窗。
    // 失败只记日志（快捷键被占用不该阻断启动）。
    crate::translate::init_on_launch(app.handle());
    // 网速采样不依赖提权，应用启动即开始
    let network_monitor = Arc::new(NetworkMonitor::new());
    app.manage(network_monitor.clone());
@@ -0,0 +1,500 @@
 //! 取词：智能路径（UIA 直读）优先，兼容路径（模拟 Ctrl+C）兜底。
 //!
 //! 整个流程在**调用方的阻塞线程**上执行（最长约 1s）。**严禁在主线程调用**：
 //! 全局快捷键回调与 UI 线程都不该被这段等待卡住。命令层用 `spawn_blocking` 包装，
 //! 快捷键回调自行 `std::thread::spawn`。
 use std::time::{Duration, Instant};
 use serde::Serialize;
 use specta::Type;
 use tauri::{AppHandle, Manager};
 use crate::clipboard::reader::{read_clipboard, write_dib, write_files, write_text, ClipData};
 use crate::clipboard::ClipboardManager;
 use crate::translate::engines::{ErrorKind, TranslateError};
 use windows_sys::Win32::Foundation::CloseHandle;
 use windows_sys::Win32::System::DataExchange::GetClipboardSequenceNumber;
 use windows_sys::Win32::System::Threading::{
    OpenProcess, QueryFullProcessImageNameW, PROCESS_QUERY_LIMITED_INFORMATION,
 };
 use windows_sys::Win32::UI::Input::KeyboardAndMouse::{
    GetAsyncKeyState, SendInput, INPUT, INPUT_KEYBOARD, KEYBDINPUT, KEYEVENTF_KEYUP, VK_CONTROL,
 };
 use windows_sys::Win32::UI::WindowsAndMessaging::{
    GetForegroundWindow, GetWindowThreadProcessId,
 };
 /// 模拟按键后等待剪贴板更新的上限。
 ///
 /// 300ms 偏短：浏览器、Electron 应用、带插件的编辑器在复制前还要走一遍自己的
 /// 命令分发，慢一点的直接超时。放宽到 600ms 后失败率明显下降，而用户感知的
 /// 「按下到弹出」延迟仍在可接受范围（取词是主动行为，不是输入反馈）。
 const PASTE_WAIT: Duration = Duration::from_millis(600);
 /// 轮询间隔
 const POLL_INTERVAL: Duration = Duration::from_millis(10);
 /// 等用户自然松开修饰键的时间（见 [`neutralise_modifiers`]）
 const MOD_RELEASE_WAIT: Duration = Duration::from_millis(400);
 const VK_C: u16 = 0x43;
 const VK_V: u16 = 0x56;
 const VK_INSERT: u16 = 0x2D;
 const VK_MENU: u16 = 0x12; // Alt
 const VK_SHIFT: u16 = 0x10;
 const VK_LWIN: u16 = 0x5B;
 const VK_RWIN: u16 = 0x5C;
 /// 会「污染」Ctrl+C 的修饰键：按下时目标应用看到的是 Alt+Ctrl+C 之类，
 /// 没有任何应用把它当复制。Alt 与 Shift 会被强制松开（见 [`neutralise_modifiers`]）。
 const BLOCKING_MODIFIERS: [u16; 2] = [VK_MENU, VK_SHIFT];
 /// 参与「等自然松开」但不强制合成的键：合成 Win 抬起会触发开始菜单，代价太大。
 const WAIT_ONLY_MODIFIERS: [u16; 2] = [VK_LWIN, VK_RWIN];
 /// 取词参数（来自设置）
 #[derive(Debug, Clone)]
 pub struct CaptureRequest {
    /// 文本字符数上限，超出直接拒绝而不是发一个巨大的请求
    pub max_chars: usize,
    /// 取词后是否还原剪贴板
    pub restore_clipboard: bool,
    /// 跳过取词的进程名黑名单（终端类）
    pub blacklist: Vec<String>,
    /// 取词方式："smart"（UIA 直读优先，失败退回模拟按键）| "compat"（只用模拟按键）
    pub mode: String,
 }
 /// 取词结果
 #[derive(Debug, Clone, Serialize, Type)]
 #[serde(rename_all = "camelCase")]
 pub struct CaptureOutcome {
    pub text: String,
    /// 取词来源："clipboard"（模拟 Ctrl+C）
    pub source: String,
    /// 取词时的前台窗口句柄（P3 回填替换选区时要用，事后无法补齐）
    pub source_hwnd: i64,
    /// 前台窗口所属进程名（用于提示与黑名单判定）
    pub source_process: String,
    /// 剪贴板是否被成功还原。false 有两种情况：备份时剪贴板是**不支持的格式**
    /// （如仅含 HTML/RTF，无法原样写回），或还原本身失败——此时选区文本会留在剪贴板上。
    pub restored_clipboard: bool,
 }
 /// 执行一次取词。**阻塞**，见模块头注释。
 ///
 /// 并发互斥：连按快捷键（以为没反应再按一次是常见操作）会让两套
 /// 「备份 → Ctrl+C → 轮询 → 还原」并发执行，互相覆盖剪贴板状态。
 /// 在途时后来者直接放弃，静默返回。
 pub fn capture_selection(
    app: &AppHandle,
    req: &CaptureRequest,
 ) -> Result<CaptureOutcome, TranslateError> {
    use std::sync::atomic::{AtomicBool, Ordering};
    static IN_FLIGHT: AtomicBool = AtomicBool::new(false);
    if IN_FLIGHT.swap(true, Ordering::SeqCst) {
        return Err(TranslateError::new(
            ErrorKind::Empty,
            "上一次取词仍在进行中",
        ));
    }
    let result = capture_selection_inner(app, req);
    IN_FLIGHT.store(false, Ordering::SeqCst);
    result
 }
 fn capture_selection_inner(
    app: &AppHandle,
    req: &CaptureRequest,
 ) -> Result<CaptureOutcome, TranslateError> {
    let (hwnd, process) = foreground_window_process();
    let process_name = process.clone().unwrap_or_default();
    if !process_name.is_empty()
        && req
            .blacklist
            .iter()
            .any(|b| b.trim().eq_ignore_ascii_case(&process_name))
    {
        return Err(TranslateError::unsupported(format!(
            "「{process_name}」中 Ctrl+C 是中断信号，无法用于取词。\
             请选中文字后复制，再用「翻译剪贴板」快捷键。"
        )));
    }
    // ===== 智能路径：UIA 直读（不动键盘、不碰剪贴板）=====
    // 命中即返回：既避免了修饰键残留 / 提权窗口 / 剪贴板占用这三类兼容路径问题，
    // 也快得多（一次跨进程 COM 调用 vs 一次 600ms 的剪贴板等待）。
    if req.mode.trim() != "compat" {
        if let Some(text) = uia_selection() {
            crate::logger::log_info(
                "translate",
                &format!(
                    "取词：UIA 直读命中（{} 字符），前台进程 {:?}",
                    text.chars().count(),
                    process_name
                ),
            );
            return finish_text(req, text, hwnd, &process_name, true);
        }
    }
    // 屏蔽窗口覆盖「Ctrl+C 覆盖剪贴板 → 读走 → 还原」的全过程。
    // 守卫析构时自动解除，提前 return 也不会漏。
    let suppress = app.try_state::<ClipboardManager>().map(|m| m.suppress());
    let _guard = suppress.as_ref().map(|s| s.burst());
    let backup = read_clipboard();
    let before = clipboard_seq();
    // 关键：先让修饰键回到「都没按」的状态，再发 Ctrl+C。
    // 全局快捷键是在**按下**的瞬间触发的，此刻 Alt 必然还被物理按住；
    // 直接补发 Ctrl+C，目标应用收到的是 Alt+Ctrl+C —— 复制不会发生，
    // 于是必然走到下面的「取词超时」。这是兼容路径取不到词最主要的原因。
    let forced = neutralise_modifiers();
    send_ctrl_c();
    let mut updated = wait_clipboard_change(before, PASTE_WAIT);
    // 重试一次：部分应用首次按键被自身的输入法/菜单状态吃掉，第二次才真正复制。
    // 复制是幂等的，多按一次没有副作用，比直接判定失败划算。
    if !updated {
        send_ctrl_c();
        updated = wait_clipboard_change(before, PASTE_WAIT / 2);
    }
    // Ctrl+Insert 兜底：个别应用对合成的 Ctrl+C 不响应，但认经典的复制和弦
    // （控制台/部分老程序对 Ctrl+Insert 的处理路径也与 Ctrl+C 不同）。
    // 无选区时该组合键无副作用，与「复制是幂等的」同理。
    if !updated {
        crate::logger::log_info(
            "translate",
            &format!("取词：Ctrl+C 未更新剪贴板（前台进程 {process_name:?}），改试 Ctrl+Insert"),
        );
        send_ctrl_insert();
        updated = wait_clipboard_change(before, PASTE_WAIT / 2);
    }
    let clip = if updated { read_clipboard() } else { None };
    // 键盘状态尽早复原：越早把 Alt 按回去，越不容易让目标应用进入菜单栏模式
    restore_modifiers(&forced);
    if !updated {
        return Err(TranslateError::new(
            ErrorKind::Empty,
            "取词失败：模拟 Ctrl+C 后剪贴板没有更新。\
             常见原因是目标窗口以管理员权限运行（系统会丢弃来自普通权限程序的模拟按键），\
             或该应用不支持复制选区。可改用「翻译剪贴板」：先复制，再按对应快捷键。"
                .to_string(),
        ));
    }
    // 剪贴板已被目标应用覆盖为选区内容。**先还原再做一切判定**：
    // 还原必须覆盖所有后续路径（非文本 / 空文本 / 超限 / 成功），
    // 否则「取词失败」的代价是用户剪贴板被悄悄换掉，与 restore_clipboard 设置矛盾。
    let restored = if req.restore_clipboard {
        restore_clipboard(backup)
    } else {
        false
    };
    // 还原本身也改了剪贴板。虽然还在屏蔽窗口内，但窗口解除后监听可能才轮到这一次变化，
    // 于是额外精确记账一次，把边界情况的漏网也堵上。
    if restored {
        if let Some(s) = suppress.as_ref() {
            s.mark_seq(clipboard_seq());
        }
    }
    let text = match clip {
        Some(ClipData::Text(t)) => t,
        Some(_) => {
            return Err(TranslateError::new(
                ErrorKind::Empty,
                "取到的内容不是文本（选区可能是图片或文件）",
            ))
        }
        None => {
            return Err(TranslateError::new(
                ErrorKind::Empty,
                "未获取到选中文本：目标窗口可能不允许复制，或当前没有选中任何文字",
            ))
        }
    };
    finish_text(
        req,
        text,
        hwnd,
        &process_name,
        // UIA 路径：剪贴板从头到尾没被碰过
        restored,
    )
 }
 /// 取到文本后的公共收尾：裁剪 → 空判定 → 字数上限 → 组装结果。
 ///
 /// 两条取词路径（UIA 直读 / 模拟 Ctrl+C）都必须过这套校验，否则「字数上限」
 /// 只对其中一条生效——那正是配置里写「上限」却仍被绕过的原因。
 fn finish_text(
    req: &CaptureRequest,
    text: String,
    hwnd: i64,
    process_name: &str,
    clip_intact: bool,
 ) -> Result<CaptureOutcome, TranslateError> {
    let trimmed = text.trim();
    if trimmed.is_empty() {
        return Err(TranslateError::new(
            ErrorKind::Empty,
            "未获取到选中文本（取到的内容为空）",
        ));
    }
    let char_count = trimmed.chars().count();
    if req.max_chars > 0 && char_count > req.max_chars {
        return Err(TranslateError::unsupported(format!(
            "选中内容 {char_count} 字符，超过取词上限（{}）。\
             请在「翻译 → 设置 → 划词翻译」中调高上限，或改用主面板翻译。",
            req.max_chars
        )));
    }
    Ok(CaptureOutcome {
        text: trimmed.to_string(),
        source: "selection".to_string(),
        source_hwnd: hwnd,
        source_process: process_name.to_string(),
        restored_clipboard: clip_intact,
    })
 }
 fn clipboard_seq() -> u32 {
    unsafe { GetClipboardSequenceNumber() }
 }
 /// UIA 直读选区（智能路径）。`windows` crate 只在 Windows 目标上参与构建，
 /// 因此非 Windows 目标这里直接返回 None（等价于「读不到」→ 走兼容路径）。
 #[cfg(windows)]
 fn uia_selection() -> Option<String> {
    super::uia_capture::read_selection()
 }
 #[cfg(not(windows))]
 fn uia_selection() -> Option<String> {
    None
 }
 /// 等剪贴板序号变化（即目标应用完成了复制）。
 fn wait_clipboard_change(before: u32, timeout: Duration) -> bool {
    let deadline = Instant::now() + timeout;
    while Instant::now() < deadline {
        if clipboard_seq() != before {
            return true;
        }
        std::thread::sleep(POLL_INTERVAL);
    }
    false
 }
 fn key_down(vk: u16) -> bool {
    (unsafe { GetAsyncKeyState(vk as i32) } as u16 & 0x8000) != 0
 }
 /// 发送单个按键事件（`up` 为真表示抬起）。
 fn send_key(vk: u16, up: bool) {
    let mut input: INPUT = unsafe { std::mem::zeroed() };
    input.r#type = INPUT_KEYBOARD;
    input.Anonymous.ki = KEYBDINPUT {
        wVk: vk,
        wScan: 0,
        dwFlags: if up { KEYEVENTF_KEYUP } else { 0 },
        time: 0,
        dwExtraInfo: 0,
    };
    unsafe {
        SendInput(1, &input, std::mem::size_of::<INPUT>() as i32);
    }
 }
 /// 让修饰键回到「都没按」的状态，返回被**强制**松开的键（调用方负责按回去）。
 ///
 /// 两步走，顺序很重要：
 /// 1. **先等用户自然松开**。全局快捷键在按键**按下**的瞬间触发，此刻 Alt 一定还按着；
 ///    绝大多数情况用户几十毫秒内就松手了，等一下既解决了问题，又完全不用合成按键
 ///    （合成 Alt 抬起有让目标应用进入菜单栏模式的风险）。
 /// 2. 超时仍未松开（长按、卡键）才合成抬起事件。只处理 Alt/Shift：合成 Win 抬起
 ///    会触发开始菜单，代价远大于收益——Win 参与的组合键本就罕见。
 fn neutralise_modifiers() -> Vec<u16> {
    let deadline = Instant::now() + MOD_RELEASE_WAIT;
    let all: Vec<u16> = BLOCKING_MODIFIERS
        .iter()
        .chain(WAIT_ONLY_MODIFIERS.iter())
        .copied()
        .collect();
    while Instant::now() < deadline {
        if !all.iter().copied().any(key_down) {
            break;
        }
        std::thread::sleep(Duration::from_millis(8));
    }
    let mut forced = Vec::new();
    for vk in BLOCKING_MODIFIERS {
        if key_down(vk) {
            send_key(vk, true);
            forced.push(vk);
        }
    }
    if !forced.is_empty() {
        // 给目标应用一点时间处理抬起事件，避免紧接着的 Ctrl+C 被合并成 Alt+Ctrl+C
        std::thread::sleep(Duration::from_millis(10));
    }
    forced
 }
 /// 把 [`neutralise_modifiers`] 强制松开的键按回去，让用户自己松手时状态一致。
 ///
 /// **只还原仍然物理按住的键**：用户可能在等待期间就松手了，此时再合成一个 keydown
 /// 会把 Alt 留在「按下」状态——他下一次敲任意键都会变成 Alt+某键，比不还原糟糕得多。
 fn restore_modifiers(keys: &[u16]) {
    for vk in keys {
        if key_down(*vk) {
            send_key(*vk, false);
        }
    }
 }
 /// 把备份内容原样写回。仅支持文本 / 图片 / 文件三种格式——其余格式（HTML/RTF 等）
 /// 在备份阶段就读不出来，因此无法还原，返回 false 而不是假装成功。
 fn restore_clipboard(backup: Option<ClipData>) -> bool {
    match backup {
        Some(ClipData::Text(t)) => write_text(&t),
        Some(ClipData::Image { dib, .. }) => write_dib(&dib),
        Some(ClipData::Files(files)) => write_files(&files),
        None => false,
    }
 }
 /// 模拟 Ctrl+V（译文回填替换选区用）。
 ///
 /// 与 [`send_ctrl_c`] 相同的修饰键处理：若用户仍按着 Ctrl，只补发 V 键，
 /// 避免把用户的修饰键一并释放。
 pub fn send_ctrl_v() {
    let ctrl_held = (unsafe { GetAsyncKeyState(VK_CONTROL as i32) } as u16 & 0x8000) != 0;
    let mut inputs: Vec<INPUT> = Vec::with_capacity(4);
    let mut push = |vk: u16, up: bool| {
        let mut input: INPUT = unsafe { std::mem::zeroed() };
        input.r#type = INPUT_KEYBOARD;
        input.Anonymous.ki = KEYBDINPUT {
            wVk: vk,
            wScan: 0,
            dwFlags: if up { KEYEVENTF_KEYUP } else { 0 },
            time: 0,
            dwExtraInfo: 0,
        };
        inputs.push(input);
    };
    // 取词悬浮窗是非激活的，前台窗口仍是原应用：Ctrl+V 会落在原选区上
    let own_ctrl = !ctrl_held;
    if own_ctrl {
        push(VK_CONTROL, false);
    }
    push(VK_V, false);
    push(VK_V, true);
    if own_ctrl {
        push(VK_CONTROL, true);
    }
    unsafe {
        SendInput(
            inputs.len() as u32,
            inputs.as_ptr(),
            std::mem::size_of::<INPUT>() as i32,
        );
    }
 }
 /// 取前台窗口句柄与所属进程名。
 fn foreground_window_process() -> (i64, Option<String>) {
    unsafe {
        let hwnd = GetForegroundWindow();
        if hwnd == 0 {
            return (0, None);
        }
        let mut pid: u32 = 0;
        GetWindowThreadProcessId(hwnd, &mut pid);
        let hwnd_i64 = hwnd as i64;
        if pid == 0 {
            return (hwnd_i64, None);
        }
        let handle = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, pid);
        if handle == 0 {
            // 目标进程权限更高时连句柄都拿不到——这本身就是一个有效信号，
            // 但不必在这里下结论，让后续「取词超时」去提示
            return (hwnd_i64, None);
        }
        let mut buf = [0u16; 512];
        let mut size = buf.len() as u32;
        let ok = QueryFullProcessImageNameW(handle, 0, buf.as_mut_ptr(), &mut size);
        CloseHandle(handle);
        if ok == 0 {
            return (hwnd_i64, None);
        }
        let path = String::from_utf16_lossy(&buf[..size as usize]);
        let name = path
            .rsplit(['\\', '/'])
            .next()
            .unwrap_or(path.as_str())
            .to_string();
        (hwnd_i64, if name.is_empty() { None } else { Some(name) })
    }
 }
 /// 模拟「Ctrl + 某键」。
 ///
 /// 关键细节：若用户此刻**正按着 Ctrl**（例如取词快捷键本身带 Ctrl），
 /// 我们发出的 Ctrl 抬起会把用户的修饰键一并释放，造成「按一次快捷键后
 /// Ctrl 行为异常」。因此先探测 Ctrl 的物理状态，只补发缺失的那一段。
 fn send_ctrl_chord(vk: u16) {
    // 高位为 1 表示当前处于按下状态
    let ctrl_held = (unsafe { GetAsyncKeyState(VK_CONTROL as i32) } as u16 & 0x8000) != 0;
    let mut inputs: Vec<INPUT> = Vec::with_capacity(4);
    let mut push = |vk: u16, up: bool| {
        let mut input: INPUT = unsafe { std::mem::zeroed() };
        input.r#type = INPUT_KEYBOARD;
        input.Anonymous.ki = KEYBDINPUT {
            wVk: vk,
            wScan: 0,
            dwFlags: if up { KEYEVENTF_KEYUP } else { 0 },
            time: 0,
            dwExtraInfo: 0,
        };
        inputs.push(input);
    };
    let own_ctrl = !ctrl_held;
    if own_ctrl {
        push(VK_CONTROL, false);
    }
    push(vk, false);
    push(vk, true);
    if own_ctrl {
        push(VK_CONTROL, true);
    }
    unsafe {
        SendInput(
            inputs.len() as u32,
            inputs.as_ptr(),
            std::mem::size_of::<INPUT>() as i32,
        );
    }
 }
 /// 模拟 Ctrl+C。
 fn send_ctrl_c() {
    send_ctrl_chord(VK_C);
 }
 /// 模拟 Ctrl+Insert：部分应用对合成的 Ctrl+C 不响应，但认这条经典复制和弦。
 fn send_ctrl_insert() {
    send_ctrl_chord(VK_INSERT);
 }
@@ -0,0 +1,28 @@
 //! 取词：把「用户选中的文本」弄到手。
 //!
 //! 两条路径，由 `selection.mode` 决定（默认 `"smart"`）：
 //! - **UIA 直读**（[`uia_capture`]）：向目标进程的自动化提供者要当前选区。
 //!   不模拟按键、不碰剪贴板，因此不受修饰键残留、UIPI、剪贴板占用影响。读不到就
 //!   返回 None，自动退回下一条路径。
 //! - **兼容路径**（[`clipboard_capture`]）：备份剪贴板 → 模拟 Ctrl+C → 读走 → 还原。
 //!   覆盖最广（几乎所有支持复制的宿主都行），代价是短暂占用剪贴板。
 //!
 //! 调用方不该关心用了哪条路径，只看 [`clipboard_capture::CaptureOutcome::source`] 即可。
 //!
 //! 四条必须显式处理的现实约束（都是踩过才知道的）：
 //! 0. **修饰键残留**：全局快捷键在按键**按下**瞬间触发，此时 Alt 仍被物理按住，
 //!    补发的 Ctrl+C 在目标应用看来是 `Alt+Ctrl+C` —— 没有任何应用把它当复制。
 //!    这是「按了快捷键却取不到词」最主要的原因，见
 //!    [`clipboard_capture`] 里的 `neutralise_modifiers`。
 //! 1. **剪贴板必须被屏蔽**：整个取词过程会动三次剪贴板，而监听线程是 250ms 轮询，
 //!    按序列号逐个记账存在竞态。见 [`crate::clipboard::suppress`]。
 //! 2. **终端类应用不能取词**：Ctrl+C 在那里是中断信号。走进程黑名单，给出可行的替代做法。
 //! 3. **提权窗口取不到词**：目标进程以管理员权限运行时，非提权进程的 `SendInput`
 //!    会被 UIPI 直接丢弃（不报错、无反馈）。因此必须区分「超时」与「剪贴板变了但没有文本」，
 //!    否则用户只会看到一句含糊的失败。
 pub mod clipboard_capture;
 #[cfg(windows)]
 pub mod uia_capture;
 pub use clipboard_capture::{capture_selection, send_ctrl_v, CaptureRequest};
@@ -0,0 +1,174 @@
 //! UIA 直读取词：不模拟任何按键，直接从焦点元素读出选区文本。
 //!
 //! 为什么需要它 —— 模拟 Ctrl+C 这条兼容路径有三个绕不过去的现实问题：
 //! 1. **修饰键残留**。全局快捷键在**按键按下**的瞬间触发，此时 Alt 仍被物理按住，
 //!    我们补发的 Ctrl+C 在目标应用看来是 `Alt+Ctrl+C` —— 没有任何应用把它当「复制」，
 //!    于是必然走到「取词超时」。这正是「试了好几个程序都取不到」的主因。
 //! 2. **提权窗口**。UIPI 会静默丢弃来自低完整性级别进程的模拟按键。
 //! 3. **剪贴板占用**。取词期间用户的剪贴板被临时换掉，任何并发的复制都会丢。
 //!
 //! UIA 三条全避开：它只是「问」目标进程的自动化提供者要当前选区，不改键盘状态、
 //! 不碰剪贴板。浏览器（Chromium / Firefox）、Office、多数 Qt / Win32 编辑控件都提供
 //! TextPattern；读不到就返回 `None`，由调用方退回兼容路径。
 //!
 //! 两条工程约束：
 //! - **必须在独立线程上执行并带超时**。UIA 是跨进程 COM 调用，目标进程无响应时
 //!   `GetFocusedElement` 会一直挂着（既不返回也不报错）。没有超时就会漏线程、
 //!   并且让「取词」这个动作永久卡住。
 //! - **只能尽力而为**。这里不返回 `Result`：UIA 读不到是正常的（很多程序没有
 //!   TextPattern），调用方只需按「有 / 没有」分支，不需要错误文案。
 use std::sync::atomic::{AtomicU32, Ordering};
 use std::sync::mpsc as std_mpsc;
 use std::time::Duration;
 use windows::Win32::System::Com::{
    CoCreateInstance, CoInitializeEx, CoUninitialize, CLSCTX_SERVER, COINIT_MULTITHREADED,
 };
 use windows::Win32::UI::Accessibility::{
    CUIAutomation, IUIAutomation, IUIAutomationElement, IUIAutomationTextPattern,
    IUIAutomationTextRangeArray, UIA_TextPatternId,
 };
 /// 单次 UIA 读取的超时上限。
 ///
 /// 700ms 的依据：本地跨进程 COM 往返正常在 10ms 量级；给到 700ms 足以覆盖目标进程
 /// 偶发忙碌，又不会让用户感到「按了没反应」。再长就该交给兼容路径去兜底了。
 const UIA_TIMEOUT: Duration = Duration::from_millis(700);
 /// 沿焦点元素向上找 TextPattern 的最大层数。
 ///
 /// 浏览器里焦点常落在一个深层节点（甚至是 body），而 TextPattern 挂在更上层的
 /// 文档节点上；但要限制层数——一路上溯到桌面根节点既慢又可能读到整页文本。
 const MAX_ANCESTORS: usize = 4;
 /// 连续超时次数上限。达到后本次进程内暂停尝试 UIA。
 ///
 /// 超时意味着目标进程（或 UIA 服务）无响应。每次取词都起一个注定挂住的线程
 /// 会持续泄漏，因此给它一个熔断。熔断带 60s 衰减（见 [`read_selection`]）：
 /// 只针对当下无响应的目标，不该让一次抖动永久禁用 UIA。
 static TIMEOUTS: AtomicU32 = AtomicU32::new(0);
 const TIMEOUT_LIMIT: u32 = 3;
 /// 最近一次 UIA 超时的系统时间（毫秒），配合 TIMEOUTS 做衰减复位
 static LAST_TIMEOUT_MS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
 /// 熔断衰减窗口：距上次超时超过该时长即清零计数，重新给 UIA 机会
 const TIMEOUT_DECAY_MS: u64 = 60_000;
 fn system_millis() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_millis() as u64)
        .unwrap_or(0)
 }
 /// 尝试用 UIA 直读当前选区文本。读不到返回 `None`。
 pub fn read_selection() -> Option<String> {
    // 熔断 + 衰减：达到上限后跳过 UIA，但 60s 内未再超时就清零重新启用。
    // 没有衰减的话，一次抖动（目标进程短暂忙碌）就会让 UIA 在整个进程生命周期里失效，
    // 之后所有取词都退到模拟按键路径——症状正是「换个程序也取不到」。
    if TIMEOUTS.load(Ordering::SeqCst) >= TIMEOUT_LIMIT {
        let last = LAST_TIMEOUT_MS.load(Ordering::SeqCst);
        let now = system_millis();
        if last != 0 && now.saturating_sub(last) < TIMEOUT_DECAY_MS {
            return None;
        }
        TIMEOUTS.store(0, Ordering::SeqCst);
    }
    let (tx, rx) = std_mpsc::channel();
    std::thread::spawn(move || {
        let result = read_selection_blocking();
        let _ = tx.send(result);
    });
    match rx.recv_timeout(UIA_TIMEOUT) {
        Ok(Some(text)) => {
            // 命中即清零熔断计数：超时针对的是「当下的目标」，成功说明 UIA 服务正常
            TIMEOUTS.store(0, Ordering::SeqCst);
            Some(text)
        }
        // 读不到（没有 TextPattern / 无选区）：正常情况，交给兼容路径
        Ok(None) => None,
        Err(_) => {
            LAST_TIMEOUT_MS.store(system_millis(), Ordering::SeqCst);
            let n = TIMEOUTS.fetch_add(1, Ordering::SeqCst) + 1;
            crate::logger::log_warn(
                "translate",
                &format!("UIA 取词超时（第 {n} 次），本次改用模拟 Ctrl+C 兜底"),
            );
            None
        }
    }
 }
 /// 真正的读取逻辑。**阻塞**，且必须在独立线程上调用（见模块头注释）。
 fn read_selection_blocking() -> Option<String> {
    unsafe {
        let hr = CoInitializeEx(None, COINIT_MULTITHREADED);
        // 只在本次调用确实初始化了 COM 时才配平 Uninitialize
        let uninit = hr.is_ok();
        let result = read_selection_inner();
        if uninit {
            CoUninitialize();
        }
        result
    }
 }
 fn read_selection_inner() -> Option<String> {
    unsafe {
        let automation: IUIAutomation = CoCreateInstance(&CUIAutomation, None, CLSCTX_SERVER).ok()?;
        let walker = automation.ControlViewWalker().ok()?;
        let mut element: Option<IUIAutomationElement> = automation.GetFocusedElement().ok();
        let mut depth = 0;
        while let Some(el) = element {
            if let Some(text) = selection_text_of(&el) {
                let trimmed = text.trim();
                if !trimmed.is_empty() {
                    return Some(trimmed.to_string());
                }
            }
            if depth >= MAX_ANCESTORS {
                break;
            }
            depth += 1;
            element = walker.GetParentElement(&el).ok();
        }
        None
    }
 }
 /// 取某个元素上「当前选区」的文本。元素不支持 TextPattern 或没有选区 → None。
 fn selection_text_of(element: &IUIAutomationElement) -> Option<String> {
    unsafe {
        let pattern = element
            .GetCurrentPatternAs::<IUIAutomationTextPattern>(UIA_TextPatternId)
            .ok()?;
        let ranges: IUIAutomationTextRangeArray = pattern.GetSelection().ok()?;
        join_ranges(&ranges)
    }
 }
 /// 把多个选区区间拼成一段文本（`-1` 表示不限长度，取区间全部内容）。
 fn join_ranges(ranges: &IUIAutomationTextRangeArray) -> Option<String> {
    unsafe {
        let count = ranges.Length().ok()?;
        if count <= 0 {
            return None;
        }
        let mut parts: Vec<String> = Vec::new();
        for i in 0..count {
            let range = ranges.GetElement(i).ok()?;
            let text = range.GetText(-1).ok()?.to_string();
            if !text.trim().is_empty() {
                parts.push(text);
            }
        }
        if parts.is_empty() {
            None
        } else {
            Some(parts.join("\n"))
        }
    }
 }
@@ -0,0 +1,593 @@
 //! OpenAI 兼容引擎。
 //!
 //! 一套代码覆盖 DeepSeek / OpenAI / 通义（DashScope 兼容模式）/ Kimi / 智谱 /
 //! 本地 Ollama / LM Studio / one-api 等中转服务——它们都提供
 //! `POST {baseUrl}/chat/completions` 且请求响应结构一致，因此差异只在配置项里。
 //!
 //! 翻译场景刻意**不开思考模式**：不写 `thinking` / `reasoning_effort`，换低延迟与低费用。
 //! 若用户确实需要，可通过 `extra_body`（JSON 文本）自行透传。
 use std::time::{Duration, Instant};
 use serde::Deserialize;
 use serde_json::json;
 use super::{
    apply_common_params, build_user_content, render_template, EngineRequest, ErrorKind, TokenUsage,
    TranslateEngine, TranslateError, TranslateMode, TranslateResult,
 };
 use crate::translate::settings::{PromptTemplates, TranslateEngineConfig};
 /// 自检与连通性测试使用的探测文本
 const PROBE_TEXT: &str = "Hello, world.";
 pub struct AiEngine {
    cfg: TranslateEngineConfig,
    templates: PromptTemplates,
    client: reqwest::Client,
 }
 impl AiEngine {
    pub fn new(
        cfg: TranslateEngineConfig,
        templates: PromptTemplates,
        client: reqwest::Client,
    ) -> Self {
        Self {
            cfg,
            templates,
            client,
        }
    }
    /// API 根地址。容错处理：用户常把完整端点（`.../chat/completions`）直接粘进来，
    /// 若不在末尾剥掉，就会拼出 `.../chat/completions/chat/completions`，
    /// 而这类错误在上游表现为 404，排查成本远高于此处一行判断。
    fn api_root(&self) -> Result<String, TranslateError> {
        let raw = self.cfg.base_url.trim();
        if raw.is_empty() {
            return Err(TranslateError::config(format!(
                "引擎「{}」尚未配置 Base URL",
                self.cfg.name
            )));
        }
        if !(raw.starts_with("http://") || raw.starts_with("https://")) {
            return Err(TranslateError::config(format!(
                "Base URL 需以 http:// 或 https:// 开头，当前为「{raw}」"
            )));
        }
        let mut root = raw.trim_end_matches('/').to_string();
        for suffix in ["/chat/completions", "/completions", "/models"] {
            if let Some(stripped) = root.strip_suffix(suffix) {
                root = stripped.trim_end_matches('/').to_string();
                break;
            }
        }
        Ok(root)
    }
    fn chat_endpoint(&self) -> Result<String, TranslateError> {
        Ok(format!("{}/chat/completions", self.api_root()?))
    }
    fn models_endpoint(&self) -> Result<String, TranslateError> {
        Ok(format!("{}/models", self.api_root()?))
    }
    /// 密钥只从系统凭据管理器读，不进配置文件、不经前端。
    fn api_key(&self) -> String {
        crate::translate::engine_api_key(&self.cfg.id)
    }
    fn require_key(&self) -> Result<String, TranslateError> {
        let key = self.api_key();
        if key.trim().is_empty() {
            return Err(TranslateError::auth(format!(
                "引擎「{}」尚未配置 API Key，请在翻译设置中填写",
                self.cfg.name
            )));
        }
        Ok(key)
    }
    fn require_model(&self) -> Result<String, TranslateError> {
        let model = self.cfg.model.trim();
        if model.is_empty() {
            return Err(TranslateError::config(format!(
                "引擎「{}」尚未选择模型，可在设置中拉取模型列表后选择",
                self.cfg.name
            )));
        }
        Ok(model.to_string())
    }
    /// 有效 system prompt：实例级自定义提示词优先，否则用模式对应的全局模板。
    fn system_prompt(&self, req: &EngineRequest) -> String {
        if !self.cfg.system_prompt.trim().is_empty() {
            return render_template(&self.cfg.system_prompt, req);
        }
        render_template(self.templates.for_mode(req.mode), req)
    }
    /// 流式收尾。空内容不直接判死：**自动改用同步接口重试一次**。
    ///
    /// 上游偶发「流正常结束但 content 为空」（安全拦截、思维链吃满 max_tokens、
    /// 中转服务抖动都会导致）。用户视角这与请求失败无异，但同步接口往往能正常
    /// 返回——与其抛错让人手动重试，不如在这里自愈一次。重试失败才把错误交给上层。
    async fn finish_stream_with_fallback(
        &self,
        tx: &tokio::sync::mpsc::Sender<super::StreamEvent>,
        request_id: String,
        content: String,
        req: &EngineRequest,
        started: Instant,
        finish_reason: Option<String>,
    ) -> Result<(), TranslateError> {
        if content.trim().is_empty() {
            if tx.is_closed() {
                // 调用方已放弃（停止 / 新请求顶替），不再花一次 API 调用
                return Ok(());
            }
            crate::logger::log_warn(
                "translate",
                &format!(
                    "「{}」流式返回为空（finish_reason={:?}），自动改用同步接口重试",
                    self.cfg.name, finish_reason
                ),
            );
            // 同步路径的错误更具体（认证/额度/响应解析都能区分），直接透传
            let result = self.translate(req).await?;
            let _ = tx.send(super::StreamEvent::Done { request_id, result }).await;
            return Ok(());
        }
        finish_stream(
            tx,
            request_id,
            content,
            req,
            &self.cfg,
            started.elapsed().as_millis() as u64,
        )
        .await
    }
 }
 #[async_trait::async_trait]
 impl TranslateEngine for AiEngine {
    fn config(&self) -> &TranslateEngineConfig {
        &self.cfg
    }
    async fn translate(&self, req: &EngineRequest) -> Result<TranslateResult, TranslateError> {
        if req.text.trim().is_empty() {
            return Err(TranslateError::empty());
        }
        let key = self.require_key()?;
        let model = self.require_model()?;
        let endpoint = self.chat_endpoint()?;
        let mut body = serde_json::Map::new();
        body.insert("model".to_string(), json!(model));
        body.insert("stream".to_string(), json!(false));
        body.insert(
            "messages".to_string(),
            json!([
                { "role": "system", "content": self.system_prompt(req) },
                { "role": "user", "content": build_user_content(req, self.cfg.supports_vision) },
            ]),
        );
        apply_common_params(&mut body, &self.cfg);
        let started = Instant::now();
        let resp = self
            .client
            .post(&endpoint)
            .bearer_auth(&key)
            .timeout(Duration::from_millis(self.cfg.timeout_ms.max(1000)))
            .json(&serde_json::Value::Object(body))
            .send()
            .await
            .map_err(|e| classify_reqwest(e, &self.cfg.name))?;
        let status = resp.status();
        let raw = resp
            .text()
            .await
            .map_err(|e| TranslateError::network(format!("读取「{}」响应失败: {e}", self.cfg.name)))?;
        if !status.is_success() {
            return Err(classify_http(status.as_u16(), &raw, &self.cfg.name, &model));
        }
        let parsed: ChatResponse = serde_json::from_str(&raw).map_err(|e| {
            TranslateError::parse(format!("「{}」响应不是预期的 JSON: {e}", self.cfg.name))
                .with_detail(&raw)
        })?;
        if let Some(err) = parsed.error {
            let msg = err
                .message
                .filter(|m| !m.trim().is_empty())
                .unwrap_or_else(|| "上游返回了错误对象".to_string());
            return Err(
                TranslateError::new(ErrorKind::Unknown, format!("「{}」返回错误：{msg}", self.cfg.name))
                    .with_detail(&raw),
            );
        }
        let text = parsed
            .choices
            .into_iter()
            .next()
            .and_then(|c| c.message.content)
            .map(|s| s.trim().to_string())
            .filter(|s| !s.is_empty())
            .ok_or_else(TranslateError::empty)?;
        let latency_ms = started.elapsed().as_millis() as u64;
        let usage = parsed.usage.map(|u| {
            let total = if u.total_tokens > 0 {
                u.total_tokens
            } else {
                u.prompt_tokens + u.completion_tokens
            };
            TokenUsage {
                prompt_tokens: u.prompt_tokens,
                completion_tokens: u.completion_tokens,
                total_tokens: total,
            }
        });
        Ok(TranslateResult {
            text,
            // AI 引擎不做语言检测：显式指定了源语言时回显，auto 时留空由前端展示「自动」
            detected: if req.from.trim().is_empty() || req.from == "auto" {
                None
            } else {
                Some(req.from.clone())
            },
            engine_id: self.cfg.id.clone(),
            engine_name: self.cfg.name.clone(),
            latency_ms,
            usage,
        })
    }
    /// 流式翻译（SSE）。增量经通道下发，`data: [DONE]` 或流结束时发 Done。
    ///
    /// 错误处理约定：**本方法不发送 `StreamEvent::Error`**——任何失败都通过 `Err` 返回，
    /// 由命令层统一转成错误事件，避免前端收到两条错误。通道关闭（调用方已放弃，
    /// 例如用户点了停止）时安静返回 `Ok(())`，不当作失败。
    async fn translate_stream(
        &self,
        req: &EngineRequest,
        request_id: String,
        tx: tokio::sync::mpsc::Sender<super::StreamEvent>,
    ) -> Result<(), TranslateError> {
        if req.text.trim().is_empty() && req.image_png.is_none() {
            return Err(TranslateError::empty());
        }
        let key = self.require_key()?;
        let model = self.require_model()?;
        let endpoint = self.chat_endpoint()?;
        let mut body = serde_json::Map::new();
        body.insert("model".to_string(), json!(model));
        body.insert("stream".to_string(), json!(true));
        body.insert(
            "messages".to_string(),
            json!([
                { "role": "system", "content": self.system_prompt(req) },
                { "role": "user", "content": build_user_content(req, self.cfg.supports_vision) },
            ]),
        );
        apply_common_params(&mut body, &self.cfg);
        let started = Instant::now();
        let resp = self
            .client
            .post(&endpoint)
            .bearer_auth(&key)
            .timeout(Duration::from_millis(self.cfg.timeout_ms.max(1000)))
            .json(&serde_json::Value::Object(body))
            .send()
            .await
            .map_err(|e| classify_reqwest(e, &self.cfg.name))?;
        let status = resp.status();
        if !status.is_success() {
            let raw = resp.text().await.unwrap_or_default();
            return Err(classify_http(status.as_u16(), &raw, &self.cfg.name, &model));
        }
        // SSE 逐行解析：字节块可能把一行劈成两半，必须先攒缓冲再按 \n 切
        use futures_util::StreamExt;
        let mut stream = resp.bytes_stream();
        let mut buffer: Vec<u8> = Vec::new();
        let mut content = String::new();
        let mut finish_reason: Option<String> = None;
        while let Some(item) = stream.next().await {
            let bytes =
                item.map_err(|e| TranslateError::network(format!("读取流失败: {e}")))?;
            buffer.extend_from_slice(&bytes);
            while let Some(pos) = buffer.iter().position(|&b| b == b'\n') {
                let line_bytes: Vec<u8> = buffer.drain(..=pos).collect();
                let line = String::from_utf8_lossy(&line_bytes[..line_bytes.len() - 1]);
                let Some(payload) = line.trim().strip_prefix("data:") else {
                    continue;
                };
                let payload = payload.trim();
                if payload.is_empty() {
                    continue;
                }
                if payload == "[DONE]" {
                    return self
                        .finish_stream_with_fallback(
                            &tx,
                            request_id,
                            content,
                            req,
                            started,
                            finish_reason,
                        )
                        .await;
                }
                let Ok(value) = serde_json::from_str::<serde_json::Value>(payload) else {
                    continue;
                };
                // 上游在流中携带错误对象时终止
                if let Some(message) = value
                    .pointer("/error/message")
                    .and_then(|m| m.as_str())
                    .filter(|m| !m.trim().is_empty())
                {
                    return Err(TranslateError::new(
                        ErrorKind::Unknown,
                        format!("「{}」流中返回错误：{message}", self.cfg.name),
                    ));
                }
                if let Some(fr) = value
                    .pointer("/choices/0/finish_reason")
                    .and_then(|v| v.as_str())
                {
                    finish_reason = Some(fr.to_string());
                }
                let Some(delta) = value
                    .pointer("/choices/0/delta/content")
                    .and_then(|c| c.as_str())
                    .filter(|d| !d.is_empty())
                else {
                    continue;
                };
                content.push_str(delta);
                if tx
                    .send(super::StreamEvent::Chunk {
                        request_id: request_id.clone(),
                        delta: delta.to_string(),
                    })
                    .await
                    .is_err()
                {
                    // 通道已关 = 调用方放弃（停止 / 新请求顶替），安静退出
                    return Ok(());
                }
            }
        }
        // 流结束但没收到 [DONE]：部分上游异常断流。已有内容仍视为成功，
        // 否则用户会看着已译出一半的结果被告知失败。
        self.finish_stream_with_fallback(
            &tx,
            request_id,
            content,
            req,
            started,
            finish_reason,
        )
        .await
    }
    async fn list_models(&self) -> Result<Vec<String>, TranslateError> {
        let key = self.require_key()?;
        let endpoint = self.models_endpoint()?;
        let resp = self
            .client
            .get(&endpoint)
            .bearer_auth(&key)
            .timeout(Duration::from_millis(self.cfg.timeout_ms.clamp(3_000, 15_000)))
            .send()
            .await
            .map_err(|e| classify_reqwest(e, &self.cfg.name))?;
        let status = resp.status();
        let raw = resp
            .text()
            .await
            .map_err(|e| TranslateError::network(format!("读取「{}」模型列表失败: {e}", self.cfg.name)))?;
        if !status.is_success() {
            return Err(classify_http(
                status.as_u16(),
                &raw,
                &self.cfg.name,
                self.cfg.model.as_str(),
            ));
        }
        let parsed: ModelsResponse = serde_json::from_str(&raw).map_err(|e| {
            TranslateError::parse(format!("「{}」的模型列表无法解析: {e}", self.cfg.name))
                .with_detail(&raw)
        })?;
        let mut ids: Vec<String> = parsed
            .data
            .into_iter()
            .map(|m| m.id)
            .filter(|id| !id.trim().is_empty())
            .collect();
        ids.sort();
        ids.dedup();
        Ok(ids)
    }
    async fn test(&self) -> Result<String, TranslateError> {
        let req = EngineRequest {
            text: PROBE_TEXT.to_string(),
            from: "en".to_string(),
            to: "zh-Hans".to_string(),
            to_label: "简体中文".to_string(),
            from_label: "英语".to_string(),
            mode: TranslateMode::Translate,
            image_png: None,
            via: "preview".to_string(),
        };
        let started = Instant::now();
        let result = self.translate(&req).await?;
        let total = started.elapsed().as_millis() as u64;
        Ok(format!(
            "连通正常 · 模型 {} · {}ms · 回显「{}」",
            self.cfg.model, total, result.text
        ))
    }
 }
 /// 收尾：把累积内容封装成结果下发。空内容按「上游没产出」处理。
 async fn finish_stream(
    tx: &tokio::sync::mpsc::Sender<super::StreamEvent>,
    request_id: String,
    content: String,
    req: &EngineRequest,
    cfg: &TranslateEngineConfig,
    latency_ms: u64,
 ) -> Result<(), TranslateError> {
    let text = content.trim().to_string();
    if text.is_empty() {
        return Err(TranslateError::new(
            ErrorKind::Empty,
            format!("「{}」未返回任何译文（流提前结束）", cfg.name),
        ));
    }
    let _ = tx
        .send(super::StreamEvent::Done {
            request_id,
            result: TranslateResult {
                text,
                detected: if req.from.trim().is_empty() || req.from == "auto" {
                    None
                } else {
                    Some(req.from.clone())
                },
                engine_id: cfg.id.clone(),
                engine_name: cfg.name.clone(),
                latency_ms,
                // 流式路径不索取 usage：stream_options 是各家扩展，兼容性不一
                usage: None,
            },
        })
        .await;
    Ok(())
 }
 /// 网络层错误分类。
 fn classify_reqwest(e: reqwest::Error, engine: &str) -> TranslateError {
    if e.is_timeout() {
        return TranslateError::timeout(format!(
            "请求「{engine}」超时，可在引擎设置中调大超时时间，或检查网络"
        ));
    }
    if e.is_connect() {
        return TranslateError::network(format!(
            "无法连接「{engine}」：{e}（若该服务在境外，请检查网络或开启代理）"
        ));
    }
    TranslateError::network(format!("请求「{engine}」失败：{e}"))
 }
 /// HTTP 状态码分类。把「Key 不对」「模型名不对」「被限流」分开，
 /// 是因为这三者在前端的处置动作完全不同。
 fn classify_http(status: u16, body: &str, engine: &str, model: &str) -> TranslateError {
    let snippet = body.trim();
    let lower = snippet.to_lowercase();
    let err = match status {
        401 | 403 => TranslateError::auth(format!(
            "「{engine}」认证失败（HTTP {status}），请检查 API Key 是否正确、是否有该模型的权限"
        )),
        402 => TranslateError::auth(format!("「{engine}」余额不足或未开通计费（HTTP 402）")),
        429 => TranslateError::rate_limit(format!(
            "「{engine}」请求过于频繁（HTTP 429），请稍后重试或降低频率"
        )),
        400 | 404 | 422 => {
            if lower.contains("model") {
                TranslateError::config(format!(
                    "「{engine}」不识别模型「{model}」（HTTP {status}）：上游模型名可能已变更，\
                     请在设置中拉取模型列表后重新选择"
                ))
            } else {
                TranslateError::new(
                    ErrorKind::Config,
                    format!("「{engine}」拒绝了该请求（HTTP {status}）"),
                )
            }
        }
        408 | 504 => TranslateError::timeout(format!("「{engine}」上游超时（HTTP {status}）")),
        s if (500..600).contains(&s) => {
            TranslateError::network(format!("「{engine}」服务端错误（HTTP {status}），可稍后重试"))
        }
        s => TranslateError::new(ErrorKind::Unknown, format!("「{engine}」返回 HTTP {s}")),
    };
    err.with_detail(snippet)
 }
 // ===== 响应结构（宽松解析：缺字段不报错，由业务层判断内容是否可用） =====
 #[derive(Debug, Deserialize)]
 struct ChatResponse {
    #[serde(default)]
    choices: Vec<ChatChoice>,
    #[serde(default)]
    usage: Option<ChatUsage>,
    #[serde(default)]
    error: Option<ApiErrorBody>,
 }
 #[derive(Debug, Deserialize)]
 struct ChatChoice {
    #[serde(default)]
    message: ChatMessage,
 }
 #[derive(Debug, Default, Deserialize)]
 struct ChatMessage {
    /// 部分实现会返回 null（例如只产出思维链时），故用 Option 而非 String
    #[serde(default)]
    content: Option<String>,
 }
 #[derive(Debug, Deserialize)]
 struct ChatUsage {
    #[serde(default)]
    prompt_tokens: u32,
    #[serde(default)]
    completion_tokens: u32,
    #[serde(default)]
    total_tokens: u32,
 }
 #[derive(Debug, Deserialize)]
 struct ApiErrorBody {
    #[serde(default)]
    message: Option<String>,
 }
 #[derive(Debug, Deserialize)]
 struct ModelsResponse {
    #[serde(default)]
    data: Vec<ModelEntry>,
 }
 #[derive(Debug, Deserialize)]
 struct ModelEntry {
    #[serde(default)]
    id: String,
 }
@@ -0,0 +1,255 @@
 //! DeepL 云厂商翻译源。
 //!
 //! 选它作云厂商第一家 purely 因为接入成本：`Authorization: DeepL-Auth-Key <key>`
 //! 一个头就完成鉴权，没有 MD5/TC3 那类签名流程。其它云厂商（百度/腾讯/阿里/有道）
 //! 签名各不相同，按需再加。
 //!
 //! 三个必须如实告知用户的限制：
 //! - **免费 Key 与付费 Key 的端点不同**（`api-free.deepl.com` / `api.deepl.com`）。
 //!   用错端点会返回 403，错误信息里必须把这个可能性讲出来，否则用户只会反复重输 Key。
 //! - **目标语言只有简体中文**（`ZH`）。DeepL 暂无繁体中文目标，本实现会把
 //!   `zh-Hant` 也映射到 `ZH`，译出的会是简体——不是 bug，是上游能力边界。
 //! - 无流式接口，走 trait 默认实现（同步完成后整体下发）。
 //!
 //! HTTP 形态：`POST {base}/translate`，body `{"text":["..."],"target_lang":"ZH"}`，
 //! `source_lang` 省略时由上游自动检测。
 use std::time::{Duration, Instant};
 use serde::Deserialize;
 use super::{
    is_auto, provider_code, ErrorKind, TranslateEngine, TranslateError, TranslateResult,
 };
 use crate::translate::settings::TranslateEngineConfig;
 const PROBE_TEXT: &str = "Hello, world.";
 pub struct DeepLEngine {
    cfg: TranslateEngineConfig,
    client: reqwest::Client,
 }
 impl DeepLEngine {
    pub fn new(cfg: TranslateEngineConfig, client: reqwest::Client) -> Self {
        Self { cfg, client }
    }
    /// API 根地址（容错：剥掉误粘的 `/translate`，与 AI 引擎同一思路）
    fn api_root(&self) -> Result<String, TranslateError> {
        let raw = self.cfg.base_url.trim();
        if raw.is_empty() {
            return Err(TranslateError::config(format!(
                "引擎「{}」尚未配置 Base URL（免费 Key 用 https://api-free.deepl.com/v2，\
                 付费 Key 用 https://api.deepl.com/v2）",
                self.cfg.name
            )));
        }
        if !(raw.starts_with("http://") || raw.starts_with("https://")) {
            return Err(TranslateError::config(format!(
                "Base URL 需以 http:// 或 https:// 开头，当前为「{raw}」"
            )));
        }
        let mut root = raw.trim_end_matches('/').to_string();
        if let Some(stripped) = root.strip_suffix("/translate") {
            root = stripped.trim_end_matches('/').to_string();
        }
        Ok(root)
    }
    fn require_key(&self) -> Result<String, TranslateError> {
        let key = crate::translate::engine_api_key(&self.cfg.id);
        if key.trim().is_empty() {
            return Err(TranslateError::auth(format!(
                "引擎「{}」尚未配置 DeepL Auth Key",
                self.cfg.name
            )));
        }
        Ok(key)
    }
    /// 目标语言码。DeepL 要求变体形式：英语必须是 EN-GB/EN-US，葡语必须是 PT-PT/PT-BR。
    fn target_code(internal: &str) -> Result<String, TranslateError> {
        let code = provider_code(internal);
        let lower = code.to_lowercase();
        let out = match lower.as_str() {
            "zh" | "zh-cn" => "ZH".to_string(),
            "zh-tw" | "zh-hant" => "ZH".to_string(),
            "en" => "EN-US".to_string(),
            "en-gb" => "EN-GB".to_string(),
            "en-us" => "EN-US".to_string(),
            "pt" => "PT-BR".to_string(),
            "pt-pt" => "PT-PT".to_string(),
            "pt-br" => "PT-BR".to_string(),
            other => other.split('-').next().unwrap_or(other).to_uppercase(),
        };
        if out.trim().is_empty() {
            return Err(TranslateError::config("未指定目标语言"));
        }
        Ok(out)
    }
    /// 源语言码。省略（auto）时不上送，由上游检测。
    fn source_code(internal: &str) -> Option<String> {
        if is_auto(internal) {
            return None;
        }
        let code = provider_code(internal);
        Some(code.split('-').next().unwrap_or(&code).to_uppercase())
    }
 }
 #[async_trait::async_trait]
 impl TranslateEngine for DeepLEngine {
    fn config(&self) -> &TranslateEngineConfig {
        &self.cfg
    }
    async fn translate(
        &self,
        req: &super::EngineRequest,
    ) -> Result<TranslateResult, TranslateError> {
        let text = req.text.trim();
        if text.is_empty() {
            return Err(TranslateError::empty());
        }
        let key = self.require_key()?;
        let target = Self::target_code(&req.to)?;
        let root = self.api_root()?;
        let mut body = serde_json::json!({ "text": [text], "target_lang": target });
        if let Some(source) = Self::source_code(&req.from) {
            body["source_lang"] = serde_json::json!(source);
        }
        let started = Instant::now();
        let resp = self
            .client
            .post(format!("{root}/translate"))
            .header("Authorization", format!("DeepL-Auth-Key {key}"))
            .timeout(Duration::from_millis(self.cfg.timeout_ms.max(2_000)))
            .json(&body)
            .send()
            .await
            .map_err(|e| classify_reqwest(e, self.cfg.name.as_str()))?;
        let status = resp.status();
        let raw = resp.text().await.map_err(|e| {
            TranslateError::network(format!("读取「{}」响应失败: {e}", self.cfg.name))
        })?;
        if !status.is_success() {
            return Err(classify_http(status.as_u16(), &raw, self.cfg.name.as_str()));
        }
        let parsed: DeepLResponse = serde_json::from_str(&raw).map_err(|e| {
            TranslateError::parse(format!("「{}」响应不是预期的 JSON: {e}", self.cfg.name))
                .with_detail(&raw)
        })?;
        // DeepL 的翻译结果按 text 数组分段返回；单段请求时取第一段即可
        let text_out = parsed
            .translations
            .first()
            .and_then(|t| t.text.clone())
            .map(|t| t.trim().to_string())
            .filter(|s| !s.is_empty())
            .ok_or_else(|| {
                TranslateError::new(
                    ErrorKind::Empty,
                    format!("「{}」未返回译文", self.cfg.name),
                )
                .with_detail(raw.trim())
            })?;
        let detected = parsed
            .translations
            .first()
            .and_then(|t| t.detected_source_language.clone())
            .filter(|s| !s.trim().is_empty())
            // 上游返回大写（如 "EN"），统一转小写与内部语言码对齐
            .map(|s| s.to_lowercase());
        Ok(TranslateResult {
            text: text_out,
            detected,
            engine_id: self.cfg.id.clone(),
            engine_name: self.cfg.name.clone(),
            latency_ms: started.elapsed().as_millis() as u64,
            usage: None,
        })
    }
    async fn list_models(&self) -> Result<Vec<String>, TranslateError> {
        Ok(Vec::new())
    }
    async fn test(&self) -> Result<String, TranslateError> {
        let req = super::EngineRequest {
            text: PROBE_TEXT.to_string(),
            from: "en".to_string(),
            to: "zh-Hans".to_string(),
            to_label: "简体中文".to_string(),
            from_label: "英语".to_string(),
            mode: super::TranslateMode::Translate,
            image_png: None,
            via: "preview".to_string(),
        };
        let started = Instant::now();
        let result = self.translate(&req).await?;
        Ok(format!(
            "连通正常 · {}ms · 回显「{}」",
            started.elapsed().as_millis(),
            result.text
        ))
    }
 }
 fn classify_reqwest(e: reqwest::Error, engine: &str) -> TranslateError {
    if e.is_timeout() {
        return TranslateError::timeout(format!("请求「{engine}」超时，可调大超时时间"));
    }
    if e.is_connect() {
        return TranslateError::network(format!("无法连接「{engine}」：{e}，请检查网络"));
    }
    TranslateError::network(format!("请求「{engine}」失败：{e}"))
 }
 fn classify_http(status: u16, body: &str, engine: &str) -> TranslateError {
    let err = match status {
        403 => TranslateError::auth(format!(
            "「{engine}」认证失败（HTTP 403）：Key 无效，或免费 Key 用了付费端点（反之亦然）。\
             免费 Key 应使用 https://api-free.deepl.com/v2"
        )),
        456 => TranslateError::rate_limit(format!(
            "「{engine}」本月翻译额度已用尽（HTTP 456）"
        )),
        429 => TranslateError::rate_limit(format!(
            "「{engine}」请求过于频繁（HTTP 429），请稍后重试"
        )),
        400 => TranslateError::config(format!(
            "「{engine}」拒绝了该请求（HTTP 400）：目标语言或文本不合法"
        )),
        414 => TranslateError::unsupported(format!(
            "文本过长，「{engine}」拒绝了该请求（HTTP 414）"
        )),
        s if (500..600).contains(&s) => {
            TranslateError::network(format!("「{engine}」服务端错误（HTTP {status}），可稍后重试"))
        }
        s => TranslateError::new(ErrorKind::Unknown, format!("「{engine}」返回 HTTP {s}")),
    };
    err.with_detail(body.trim())
 }
 #[derive(Debug, Deserialize)]
 struct DeepLResponse {
    #[serde(default)]
    translations: Vec<DeepLTranslation>,
 }
 #[derive(Debug, Deserialize)]
 struct DeepLTranslation {
    #[serde(default)]
    text: Option<String>,
    #[serde(rename = "detected_source_language", default)]
    detected_source_language: Option<String>,
 }
@@ -0,0 +1,244 @@
 //! LibreTranslate 自托管翻译源。
 //!
 //! 定位：用户自部署的开源翻译服务（https://github.com/LibreTranslate/LibreTranslate），
 //! 数据发往用户自己的服务器，不受境外免费接口的 IP 风控（429）限制。
 //!
 //! 接入形态：
 //! - HTTP：`POST {base}/translate`，body `{"q":..., "source":..., "target":..., "format":"text", "api_key":...}`，
 //!   返回 `{"translatedText": "...", "detectedLanguage": {"language": ..., "confidence": ...}}`。
 //! - **语言码不能走 [`super::provider_code`]**：LibreTranslate 用 `zh-Hans` / `zh-Hant` / `en` / `ja`
 //!   这类代码，与内部语言码一致，原样透传即可；`provider_code` 会把 `zh-Hans` 换成 `zh-CN`，
 //!   那是 Google / MyMemory 那套写法。
 //! - 目标语言集取决于部署时的语言包（常见部署仅含 en / ja / zh-Hans 等少数语言）；
 //!   不支持的语言对上游返回 400 + 错误说明，这里把错误说明透传进 detail，而不是猜一个原因。
 //! - **API Key 可选**：部署启用 `LT_API_KEYS` 后必需；未启用时传不传都行，
 //!   本实现仅在已配置密钥时才上送 `api_key` 字段。
 use std::time::{Duration, Instant};
 use serde::Deserialize;
 use super::{is_auto, ErrorKind, TranslateEngine, TranslateError, TranslateResult};
 use crate::translate::settings::TranslateEngineConfig;
 const PROBE_TEXT: &str = "Hello, world.";
 pub struct LibreTranslateEngine {
    cfg: TranslateEngineConfig,
    client: reqwest::Client,
 }
 impl LibreTranslateEngine {
    pub fn new(cfg: TranslateEngineConfig, client: reqwest::Client) -> Self {
        Self { cfg, client }
    }
    /// API 根地址（容错：剥掉误粘的 `/translate`，与 DeepL / AI 引擎同一思路）
    fn api_root(&self) -> Result<String, TranslateError> {
        let raw = self.cfg.base_url.trim();
        if raw.is_empty() {
            return Err(TranslateError::config(format!(
                "引擎「{}」尚未配置服务地址：请填写自建 LibreTranslate 的地址（如 https://translate.example.com）",
                self.cfg.name
            )));
        }
        if !(raw.starts_with("http://") || raw.starts_with("https://")) {
            return Err(TranslateError::config(format!(
                "服务地址需以 http:// 或 https:// 开头，当前为「{raw}」"
            )));
        }
        let mut root = raw.trim_end_matches('/').to_string();
        if let Some(stripped) = root.strip_suffix("/translate") {
            root = stripped.trim_end_matches('/').to_string();
        }
        Ok(root)
    }
    /// API Key（可选）。部署未启用密钥校验时留空即可。
    fn api_key(&self) -> Option<String> {
        let key = crate::translate::engine_api_key(&self.cfg.id);
        let key = key.trim();
        if key.is_empty() {
            None
        } else {
            Some(key.to_string())
        }
    }
    /// 源语言码：auto 原样上送（LibreTranslate 支持自动检测）；显式语言原样透传。
    fn source_code(&self, from: &str) -> String {
        if is_auto(from) {
            "auto".to_string()
        } else {
            from.to_string()
        }
    }
    /// 目标语言码：原样透传。不能走 provider_code（见文件头注释）。
    fn target_code(&self, to: &str) -> Result<String, TranslateError> {
        let code = to.trim();
        if code.is_empty() {
            return Err(TranslateError::config("未指定目标语言"));
        }
        Ok(code.to_string())
    }
 }
 #[async_trait::async_trait]
 impl TranslateEngine for LibreTranslateEngine {
    fn config(&self) -> &TranslateEngineConfig {
        &self.cfg
    }
    async fn translate(
        &self,
        req: &super::EngineRequest,
    ) -> Result<TranslateResult, TranslateError> {
        let text = req.text.trim();
        if text.is_empty() {
            return Err(TranslateError::empty());
        }
        let target = self.target_code(&req.to)?;
        let source = self.source_code(&req.from);
        let root = self.api_root()?;
        let mut body = serde_json::json!({
            "q": text,
            "source": source,
            "target": target,
            "format": "text",
        });
        if let Some(key) = self.api_key() {
            body["api_key"] = serde_json::json!(key);
        }
        let started = Instant::now();
        let resp = self
            .client
            .post(format!("{root}/translate"))
            .timeout(Duration::from_millis(self.cfg.timeout_ms.max(2_000)))
            .json(&body)
            .send()
            .await
            .map_err(|e| classify_reqwest(e, self.cfg.name.as_str()))?;
        let status = resp.status();
        let raw = resp.text().await.map_err(|e| {
            TranslateError::network(format!("读取「{}」响应失败: {e}", self.cfg.name))
        })?;
        if !status.is_success() {
            return Err(classify_http(status.as_u16(), &raw, self.cfg.name.as_str()));
        }
        let parsed: LibreTranslateResponse = serde_json::from_str(&raw).map_err(|e| {
            TranslateError::parse(format!("「{}」响应不是预期的 JSON: {e}", self.cfg.name))
                .with_detail(&raw)
        })?;
        let text_out = parsed
            .translated_text
            .map(|t| t.trim().to_string())
            .filter(|s| !s.is_empty())
            .ok_or_else(|| {
                TranslateError::new(
                    ErrorKind::Empty,
                    format!("「{}」未返回译文（该语言对可能不受支持）", self.cfg.name),
                )
                .with_detail(raw.trim())
            })?;
        // 仅 source=auto 时上游会回检测结果；显式源语言时该字段缺失
        let detected = parsed
            .detected_language
            .and_then(|d| d.language)
            .filter(|s| !s.trim().is_empty());
        Ok(TranslateResult {
            text: text_out,
            detected,
            engine_id: self.cfg.id.clone(),
            engine_name: self.cfg.name.clone(),
            latency_ms: started.elapsed().as_millis() as u64,
            usage: None,
        })
    }
    /// 免密钥/自托管端点没有「模型」概念
    async fn list_models(&self) -> Result<Vec<String>, TranslateError> {
        Ok(Vec::new())
    }
    async fn test(&self) -> Result<String, TranslateError> {
        let req = super::EngineRequest {
            text: PROBE_TEXT.to_string(),
            from: "en".to_string(),
            to: "zh-Hans".to_string(),
            to_label: "简体中文".to_string(),
            from_label: "英语".to_string(),
            mode: super::TranslateMode::Translate,
            image_png: None,
            via: "preview".to_string(),
        };
        let started = Instant::now();
        let result = self.translate(&req).await?;
        Ok(format!(
            "连通正常 · {}ms · 回显「{}」",
            started.elapsed().as_millis(),
            result.text
        ))
    }
 }
 fn classify_reqwest(e: reqwest::Error, engine: &str) -> TranslateError {
    if e.is_timeout() {
        return TranslateError::timeout(format!("请求「{engine}」超时，可调大超时时间"));
    }
    if e.is_connect() {
        return TranslateError::network(format!("无法连接「{engine}」：{e}，请检查服务地址与网络"));
    }
    TranslateError::network(format!("请求「{engine}」失败：{e}"))
 }
 fn classify_http(status: u16, body: &str, engine: &str) -> TranslateError {
    // LibreTranslate 的错误体是 JSON `{"error": "..."}`，取这条说明作 detail 比整段响应可读
    let detail = serde_json::from_str::<serde_json::Value>(body)
        .ok()
        .and_then(|v| v.get("error").and_then(|e| e.as_str()).map(String::from))
        .unwrap_or_else(|| body.to_string());
    let err = match status {
        400 => TranslateError::config(format!(
            "「{engine}」拒绝了该请求（HTTP 400）：目标语言可能不在该部署支持范围内"
        )),
        401 => TranslateError::auth(format!(
            "「{engine}」要求 API Key（HTTP 401）：该部署启用了密钥校验，请配置 API Key"
        )),
        403 => TranslateError::auth(format!(
            "「{engine}」API Key 无效（HTTP 403）：请检查 Key 与该部署的密钥设置"
        )),
        429 => TranslateError::rate_limit(format!(
            "「{engine}」请求过于频繁（HTTP 429），请稍后重试"
        )),
        404 => TranslateError::config(format!(
            "「{engine}」地址无效（HTTP 404）：请确认 Base URL 是 LibreTranslate 服务根地址而非某个页面"
        )),
        s if (500..600).contains(&s) => {
            TranslateError::network(format!("「{engine}」服务端错误（HTTP {status}），可稍后重试"))
        }
        s => TranslateError::new(ErrorKind::Unknown, format!("「{engine}」返回 HTTP {s}")),
    };
    err.with_detail(detail)
 }
 #[derive(Debug, Deserialize)]
 struct LibreTranslateResponse {
    #[serde(rename = "translatedText", default)]
    translated_text: Option<String>,
    #[serde(rename = "detectedLanguage", default)]
    detected_language: Option<DetectedLanguage>,
 }
 #[derive(Debug, Deserialize)]
 struct DetectedLanguage {
    #[serde(default)]
    language: Option<String>,
 }
@@ -0,0 +1,477 @@
 //! 翻译引擎抽象层。
 //!
 //! 设计要点：
 //! - 所有引擎实现同一个 [`TranslateEngine`] trait，命令层只面对 `Box<dyn TranslateEngine>`，
 //!   因此「多源」与「指定源」都不需要在上层写分支。
 //! - 错误被细分为 [`ErrorKind`]：网络类失败可以重试到下一个源，认证/额度类失败重试
 //!   没有意义。前端也据此给出不同提示（「检查 Key」与「检查网络/代理」是两件事）。
 //! - 目标语言一律传**自然语言全称**给模型（`to_label`），语言码只用于记录与查询——
 //!   模型对「繁体中文」的遵循度明显高于 `zh-Hant`。
 pub mod ai;
 pub mod deepl;
 pub mod libretranslate;
 pub mod mymemory;
 use serde::{Deserialize, Serialize};
 use serde_json::json;
 use specta::Type;
 use super::settings::{PromptTemplates, TranslateEngineConfig};
 /// 翻译模式（P0 只用 Translate；其余三档为 P3 的同入口扩展预留）。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum TranslateMode {
    Translate,
    Polish,
    Explain,
    Summarize,
 }
 impl TranslateMode {
    /// 宽松解析：未知值一律按「翻译」处理，不因前端多传一个枚举值而报错。
    pub fn parse(raw: Option<&str>) -> Self {
        match raw.unwrap_or("").trim() {
            "polish" => Self::Polish,
            "explain" => Self::Explain,
            "summarize" => Self::Summarize,
            _ => Self::Translate,
        }
    }
 }
 /// 引擎请求（内部结构，不参与类型绑定导出）。
 #[derive(Debug, Clone)]
 pub struct EngineRequest {
    /// 待处理文本
    pub text: String,
    /// 源语言代码，"auto" 表示自动检测
    pub from: String,
    /// 目标语言代码（如 zh-Hans）
    pub to: String,
    /// 目标语言自然语言全称（如 简体中文），提示词用
    pub to_label: String,
    /// 源语言自然语言全称，auto 时为空
    pub from_label: String,
    pub mode: TranslateMode,
    /// 图像输入（base64 PNG，不含 data: 前缀）。仅截图翻译的「视觉直译」模式使用。
    /// 免密钥源与未声明 supports_vision 的 AI 引擎会拒绝该请求。
    pub image_png: Option<String>,
    /// 记入历史时的来源标签："manual" | "selection" | "clipboard" | "screenshot" | "preview"
    pub via: String,
 }
 /// Token 用量（AI 引擎返回；其余引擎为 None）
 #[derive(Debug, Clone, Serialize, Deserialize, Type)]
 #[serde(rename_all = "camelCase")]
 pub struct TokenUsage {
    pub prompt_tokens: u32,
    pub completion_tokens: u32,
    pub total_tokens: u32,
 }
 /// 翻译结果
 #[derive(Debug, Clone, Serialize, Deserialize, Type)]
 #[serde(rename_all = "camelCase")]
 pub struct TranslateResult {
    /// 译文
    pub text: String,
    /// 检测到的源语言（免费源会上报；AI 引擎为显式指定值或 None）
    pub detected: Option<String>,
    /// 实际使用的引擎实例 id
    pub engine_id: String,
    /// 实际使用的引擎展示名（自动降级时前端要能看出「是谁答的」）
    pub engine_name: String,
    /// 耗时（毫秒）
    pub latency_ms: u64,
    pub usage: Option<TokenUsage>,
 }
 /// 错误分类。区分它们的意义在于**前端能给出可操作的提示**：
 /// `Auth` 要用户去改 Key，`Network` 要用户查网络/代理，`RateLimit` 只需等待。
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Type)]
 #[serde(rename_all = "camelCase")]
 pub enum ErrorKind {
    /// 配置缺失或不合法（未填 Base URL、模型名无效等）
    Config,
    /// 认证失败 / 无权限 / 额度耗尽
    Auth,
    /// 被限流
    RateLimit,
    /// 网络不可达（含代理问题）
    Network,
    /// 超时
    Timeout,
    /// 响应无法解析（上游改了格式）
    Parse,
    /// 不支持的引擎类型或语言对
    Unsupported,
    /// 输入为空（取词失败或用户未输入）
    Empty,
    /// 被风控/验证码拦截（免费源常见）
    Captcha,
    Unknown,
 }
 /// 结构化错误：作为 Tauri 命令的 error 类型返回，前端按 `kind` 分支处理。
 #[derive(Debug, Clone, Serialize, Deserialize, Type)]
 #[serde(rename_all = "camelCase")]
 pub struct TranslateError {
    pub kind: ErrorKind,
    pub message: String,
    /// 上游原始响应片段（已截断），用于排查；不含密钥
    pub detail: Option<String>,
 }
 /// 上游响应片段入库前的截断长度（避免把整页 HTML 塞进错误对象）
 const DETAIL_LIMIT: usize = 400;
 impl TranslateError {
    pub fn new(kind: ErrorKind, message: impl Into<String>) -> Self {
        Self {
            kind,
            message: message.into(),
            detail: None,
        }
    }
    pub fn with_detail(mut self, detail: impl Into<String>) -> Self {
        let raw = detail.into();
        let trimmed = raw.trim();
        if !trimmed.is_empty() {
            let clipped: String = trimmed.chars().take(DETAIL_LIMIT).collect();
            self.detail = Some(clipped);
        }
        self
    }
    pub fn config(msg: impl Into<String>) -> Self {
        Self::new(ErrorKind::Config, msg)
    }
    pub fn auth(msg: impl Into<String>) -> Self {
        Self::new(ErrorKind::Auth, msg)
    }
    pub fn rate_limit(msg: impl Into<String>) -> Self {
        Self::new(ErrorKind::RateLimit, msg)
    }
    pub fn network(msg: impl Into<String>) -> Self {
        Self::new(ErrorKind::Network, msg)
    }
    pub fn timeout(msg: impl Into<String>) -> Self {
        Self::new(ErrorKind::Timeout, msg)
    }
    pub fn parse(msg: impl Into<String>) -> Self {
        Self::new(ErrorKind::Parse, msg)
    }
    pub fn unsupported(msg: impl Into<String>) -> Self {
        Self::new(ErrorKind::Unsupported, msg)
    }
    pub fn empty() -> Self {
        Self::new(ErrorKind::Empty, "没有可翻译的内容")
    }
    /// 该错误是否值得「换一个源再试」。
    ///
    /// 只有 `Empty` 不可重试：输入本身为空，换任何源结果都一样。
    /// `Unsupported`（本源超长上限 / 不支持该语言对 / 类型未接入）**必须可降级**——
    /// 「这个源处理不了这个请求」的含义就是「换下一个」，否则配了
    /// MyMemory + DeepSeek 的用户翻译一篇超长文本会整体失败（MyMemory 优先时）。
    pub fn retryable(&self) -> bool {
        self.kind != ErrorKind::Empty
    }
 }
 impl std::fmt::Display for TranslateError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.message)
    }
 }
 impl std::error::Error for TranslateError {}
 /// 把模板中的占位符替换为实际语言名。
 pub fn render_template(template: &str, req: &EngineRequest) -> String {
    let target = if req.to_label.trim().is_empty() {
        req.to.as_str()
    } else {
        req.to_label.as_str()
    };
    let source = if req.from_label.trim().is_empty() {
        "原文的语言（自动判断）"
    } else {
        req.from_label.as_str()
    };
    template
        .replace("{target}", target)
        .replace("{source}", source)
 }
 /// 翻译模式下统一附加的「混排」指令。
 ///
 /// 截图 OCR 经常抽出中英日混排的文本；显式源语言提示（如「源语言：日语」）反而
 /// 会诱导模型把与目标语言字形相同的部分（日文汉字）当作「已经是译文」原样保留
 /// ——这正是「日转中却总有一些日语没被翻译」的主因。
 ///
 /// 固定追加在 user 内容末尾而不是改进提示词模板：模板是用户已保存的存量设置，
 /// 改默认值对老用户不生效；这条属于引擎层的硬约束，不该被模板覆盖。
 const MIXED_LANG_NOTE: &str = "注意：原文可能是多语言混排（如中英日混排）。\
 请把全部内容统一译为目标语言——包括与目标语言字形相同的文字（如日文汉字）也要译，\
 不要原样保留；仅专有名词可保留原文。";
 /// 构造送给模型的用户内容。
 ///
 /// 纯文本时：仅在**显式指定了源语言**时补一行提示——模型对「源语言是日语」的显式声明
 /// 比让它自行判断更稳；不指定时什么都不加，避免制造无谓的 token 与
 /// 「别输出提示」的博弈。
 ///
 /// 带图像时：改为 OpenAI 视觉消息的 content-parts 结构（文本段 + image_url 段），
 /// 与 `https://platform.openai.com/docs/guides/vision` 的请求体一致；
 /// 兼容该格式的服务（DeepSeek 的实验视觉模型、通义、GLM-4V 等）可直接受理。
 pub fn build_user_content(req: &EngineRequest, supports_vision: bool) -> serde_json::Value {
    let source_hint = if req.mode == TranslateMode::Translate
        && !req.from.trim().is_empty()
        && req.from != "auto"
        && !req.from_label.trim().is_empty()
    {
        Some(format!("源语言：{}", req.from_label))
    } else {
        None
    };
    match &req.image_png {
        Some(data_url) if supports_vision => {
            let mut parts = vec![];
            if let Some(hint) = source_hint {
                parts.push(json!({ "type": "text", "text": hint }));
            }
            parts.push(json!({
                "type": "text",
                "text": "识别图中的文字并按系统提示翻译。保持原有排版与分段。"
            }));
            if req.mode == TranslateMode::Translate {
                parts.push(json!({ "type": "text", "text": MIXED_LANG_NOTE }));
            }
            parts.push(json!({
                "type": "image_url",
                "image_url": { "url": format!("data:image/png;base64,{data_url}") }
            }));
            json!(parts)
        }
        Some(_) => {
            // 带图但引擎不支持：这不该发生（命令层已拦截），兜底只发文本说明，
            // 而不是让请求带着一个模型无法理解的字段出去
            let note = "（请求包含图像，但当前引擎不支持图像输入，仅能处理文本。）";
            json!(format!("{}{}", note, req.text))
        }
        None => {
            let text = req.text.clone();
            let base = match source_hint {
                Some(hint) => format!("{hint}\n\n{text}"),
                None => text,
            };
            // 翻译模式统一追加混排指令；其他模式（润色/解释/总结）语义不同，不追加
            if req.mode == TranslateMode::Translate {
                json!(format!("{base}\n\n{MIXED_LANG_NOTE}"))
            } else {
                json!(base)
            }
        }
    }
 }
 /// 参数对齐后的公共请求体骨架（`model` / `messages` / `stream` 由各引擎补充）。
 pub fn apply_common_params(
    body: &mut serde_json::Map<String, serde_json::Value>,
    cfg: &TranslateEngineConfig,
 ) {
    body.insert("temperature".to_string(), serde_json::json!(cfg.temperature));
    body.insert("max_tokens".to_string(), serde_json::json!(cfg.max_tokens));
    if let Some(extra) = cfg.extra_body.as_deref().map(str::trim) {
        if !extra.is_empty() {
            if let Ok(serde_json::Value::Object(map)) = serde_json::from_str::<serde_json::Value>(extra) {
                for (k, v) in map {
                    body.insert(k, v);
                }
            }
            // 解析失败按「无额外参数」处理：不能让一次笔误导致整个翻译不可用，
            // 具体错误由命令层的 translate_engine_test 反馈给用户。
        }
    }
 }
 /// 流式翻译的单条事件。
 ///
 /// 引擎 → 命令层用 `mpsc` 通道传递（引擎不持有 AppHandle，保持传输层与 UI 层分离），
 /// 命令层再转发为 Tauri 事件给前端。
 ///
 /// **序列化形态是前端契约的一部分**：`tag = "type"` 让事件扁平化为
 /// `{"type":"chunk","requestId":"...","delta":"..."}`，而不是 serde 默认的外层标签
 /// `{"Chunk":{...}}`。前端按 `requestId` 过滤事件，多一层嵌套会让 `requestId` 取到
 /// `undefined`、所有事件被丢弃——表现为「历史里有结果，界面上一片空白」。
 ///
 /// **注意 serde 的一个坑**：`rename_all` 用在枚举上只重命名**变体名**（Chunk → chunk），
 /// 不作用于变体内的字段——`request_id` 会原样序列化成 `request_id`，前端拿
 /// `payload.requestId` 永远是 undefined。因此每个变体的 `request_id` 字段都显式
 /// `#[serde(rename = "requestId")]`，别合并成 `rename_all_fields`（依赖 serde 版本）。
 /// 改动这里必须同步改 `src/lib/translate/api.ts` 的 `StreamEventPayload`。
 ///
 /// `Error` 变体是**兜底通道**：主通道仍是命令的 `Err`（Promise reject）。保留它
 /// 是为了覆盖「命令已返回 requestId、之后才失败」的情形，否则前端会永远停在
 /// 「翻译中」而没有出口。
 #[derive(Debug, Clone, serde::Serialize)]
 #[serde(tag = "type", rename_all = "camelCase")]
 pub enum StreamEvent {
    /// 增量片段
    Chunk {
        #[serde(rename = "requestId")]
        request_id: String,
        delta: String,
    },
    /// 完成（携带完整结果，含实际引擎名）
    Done {
        #[serde(rename = "requestId")]
        request_id: String,
        result: TranslateResult,
    },
    /// 失败（兜底通道，见类型注释）
    Error {
        #[serde(rename = "requestId")]
        request_id: String,
        error: TranslateError,
    },
 }
 /// 引擎统一接口。
 ///
 /// 用 `async_trait` 而非原生 `async fn in trait`：本 trait 需要 `Box<dyn>` 动态分派
 /// （多源切换是运行期决定的），原生 async fn 在 dyn 场景下不可用。
 #[async_trait::async_trait]
 pub trait TranslateEngine: Send + Sync {
    /// 引擎配置。id / name 等一律由此读取，避免在每个实现里重复存字段。
    fn config(&self) -> &TranslateEngineConfig;
    /// 展示名（自动降级时用于记录「是谁失败了」）
    fn name(&self) -> &str {
        &self.config().name
    }
    /// 执行一次翻译
    async fn translate(&self, req: &EngineRequest) -> Result<TranslateResult, TranslateError>;
    /// 流式翻译：增量经 `tx` 下发，结束时发一条 [`StreamEvent::Done`]。
    ///
    /// 默认实现是「同步翻译后整体下发」——**不支持流式的引擎不需要实现它**，
    /// 前端因此可以统一走流式入口，无需自己判断引擎能力。
    /// 通道关闭（`send` 失败）意味着调用方已放弃本次请求，实现方应尽快返回而不是报错。
    async fn translate_stream(
        &self,
        req: &EngineRequest,
        request_id: String,
        tx: tokio::sync::mpsc::Sender<StreamEvent>,
    ) -> Result<(), TranslateError> {
        let result = self.translate(req).await?;
        let _ = tx.send(StreamEvent::Done { request_id, result }).await;
        Ok(())
    }
    /// 拉取可用模型列表（用于「上游改名」这类失效场景的自救入口）
    async fn list_models(&self) -> Result<Vec<String>, TranslateError>;
    /// 连通性自检：返回一句人类可读的成功描述（含实际模型回显）
    async fn test(&self) -> Result<String, TranslateError>;
 }
 /// 内部语言码 → 第三方源使用的语言码。
 ///
 /// 只有中文需要换算：内部统一用 BCP-47 的 `zh-Hans` / `zh-Hant`，而 MyMemory
 /// 沿用 `zh-CN` / `zh-TW` 这一代写法。其余语言码两边一致，原样透传——
 /// 与其维护一张可能过期的全量映射表，不如只处理确有差异的项。
 /// 注意 LibreTranslate 用的是 `zh-Hans` / `zh-Hant`，与内部一致，**不走本函数**。
 pub fn provider_code(code: &str) -> String {
    match code {
        "zh-Hans" => "zh-CN".to_string(),
        "zh-Hant" => "zh-TW".to_string(),
        other => other.to_string(),
    }
 }
 /// 免费源的语言支持是「尽力而为」的：第三方接口对不支持的语言对通常返回
 /// 空译文而不是明确报错，因此统一在这里识别，给出可操作的提示。
 pub fn is_auto(code: &str) -> bool {
    let c = code.trim();
    c.is_empty() || c == "auto"
 }
 #[cfg(test)]
 mod tests {
    use super::StreamEvent;
    /// 前端契约测试：事件必须扁平化为 `{"type":"chunk","requestId":...}`。
    /// 守护枚举字段命名的 serde 坑（rename_all 在枚举上不改字段名），
    /// 一旦回退，前端所有流式事件都会因 requestId 取到 undefined 被丢弃。
    #[test]
    fn stream_event_serializes_flat_with_camel_case_request_id() {
        let json = serde_json::to_value(StreamEvent::Chunk {
            request_id: "r1".into(),
            delta: "x".into(),
        })
        .unwrap();
        assert_eq!(json["type"], "chunk", "实际形态: {json}");
        assert_eq!(json["requestId"], "r1", "实际形态: {json}");
        assert!(json.get("request_id").is_none(), "实际形态: {json}");
        let json = serde_json::to_value(StreamEvent::Done {
            request_id: "r1".into(),
            result: super::TranslateResult {
                text: "t".into(),
                detected: None,
                engine_id: "e".into(),
                engine_name: "n".into(),
                latency_ms: 1,
                usage: None,
            },
        })
        .unwrap();
        assert_eq!(json["type"], "done", "实际形态: {json}");
        assert_eq!(json["requestId"], "r1", "实际形态: {json}");
        assert_eq!(json["result"]["engineName"], "n", "实际形态: {json}");
    }
 }
 /// 依据配置构造引擎实例。
 ///
 /// P0/P1 已实现：`ai`（OpenAI 兼容家族）与 `free` 下的 libretranslate / mymemory；
 /// `cloud`（需签名的云厂商）在 P3。未实现的类型显式返回 `Unsupported` 而不是静默忽略，
 /// 避免用户配了却「以为生效」。
 pub fn build_engine(
    cfg: &TranslateEngineConfig,
    templates: &PromptTemplates,
    client: reqwest::Client,
 ) -> Result<Box<dyn TranslateEngine>, TranslateError> {
    match cfg.kind.as_str() {
        "ai" => Ok(Box::new(ai::AiEngine::new(
            cfg.clone(),
            templates.clone(),
            client,
        ))),
        "free" => match cfg.preset.as_str() {
            "libretranslate" => Ok(Box::new(libretranslate::LibreTranslateEngine::new(
                cfg.clone(),
                client,
            ))),
            "mymemory" => Ok(Box::new(mymemory::MyMemoryEngine::new(cfg.clone(), client))),
            other => Err(TranslateError::unsupported(format!(
                "免密钥源「{other}」尚未接入（可选：libretranslate / mymemory）"
            ))),
        },
        "cloud" => match cfg.preset.as_str() {
            "deepl" => Ok(Box::new(deepl::DeepLEngine::new(cfg.clone(), client))),
            other => Err(TranslateError::unsupported(format!(
                "云厂商源「{other}」尚未接入（可选：deepl）"
            ))),
        },
        other => Err(TranslateError::config(format!(
            "未知的引擎类型「{other}」（仅支持 ai / free / cloud）"
        ))),
    }
 }
@@ -0,0 +1,216 @@
 //! MyMemory 免密钥翻译源。
 //!
 //! 定位：国内可直接访问的免密兜底。质量不如大模型，但胜在零配置、无代理依赖。
 //!
 //! 两个必须知道的限制：
 //! - **不支持自动检测源语言**。`langpair` 要求显式源语言，因此源语言为 `auto` 时
 //!   直接返回可操作的配置错误（而不是发一个注定失败的请求），让「自动」模式降级到下一个源。
 //! - 免费额度按**字节**计（约 500 字节/次，匿名另有每日上限）。超限时上游返回
 //!   `responseStatus: 403` 并在 `responseDetails` 里说明，这里原样透传给用户看。
 use std::time::{Duration, Instant};
 use serde::Deserialize;
 use super::{
    is_auto, provider_code, ErrorKind, TranslateEngine, TranslateError, TranslateResult,
 };
 use crate::translate::settings::TranslateEngineConfig;
 const ENDPOINT: &str = "https://api.mymemory.translated.net/get";
 /// 单次查询的字节上限（上游按字节限制，且 langpair 也占额度的一部分）
 const MAX_QUERY_BYTES: usize = 500;
 const PROBE_TEXT: &str = "Hello, world.";
 pub struct MyMemoryEngine {
    cfg: TranslateEngineConfig,
    client: reqwest::Client,
 }
 impl MyMemoryEngine {
    pub fn new(cfg: TranslateEngineConfig, client: reqwest::Client) -> Self {
        Self { cfg, client }
    }
 }
 #[async_trait::async_trait]
 impl TranslateEngine for MyMemoryEngine {
    fn config(&self) -> &TranslateEngineConfig {
        &self.cfg
    }
    async fn translate(
        &self,
        req: &super::EngineRequest,
    ) -> Result<TranslateResult, TranslateError> {
        let text = req.text.trim();
        if text.is_empty() {
            return Err(TranslateError::empty());
        }
        if is_auto(&req.from) {
            // 不猜：源语言未知时上游无法工作，明确返回配置类错误（可降级）。
            // 文案要同时覆盖两个入口：主面板的源语言下拉、划词弹窗顶部的「自」循环按钮
            // ——弹窗的源语言是独立记忆项，与主面板的选择无关，不点明用户会以为
            // 「主界面选过了为什么还报错」。
            return Err(TranslateError::config(format!(
                "「{}」需要显式指定源语言：主面板请在源语言下拉中选具体语言；\
                 划词弹窗请点击顶部的「自」按钮切换源语言（选择会被记住）",
                self.cfg.name
            )));
        }
        if text.len() > MAX_QUERY_BYTES {
            return Err(TranslateError::unsupported(format!(
                "文本 {} 字节，超过「{}」的单次上限（{MAX_QUERY_BYTES} 字节）",
                text.len(),
                self.cfg.name
            )));
        }
        let target = provider_code(&req.to);
        if target.trim().is_empty() {
            return Err(TranslateError::config("未指定目标语言"));
        }
        let pair = format!("{}|{}", provider_code(&req.from), target);
        let started = Instant::now();
        let resp = self
            .client
            .get(ENDPOINT)
            .query(&[("q", text), ("langpair", pair.as_str())])
            .timeout(Duration::from_millis(self.cfg.timeout_ms.max(2_000)))
            .send()
            .await
            .map_err(|e| classify_reqwest(e, self.cfg.name.as_str()))?;
        let status = resp.status();
        let raw = resp.text().await.map_err(|e| {
            TranslateError::network(format!("读取「{}」响应失败: {e}", self.cfg.name))
        })?;
        if !status.is_success() {
            return Err(TranslateError::network(format!(
                "「{}」返回 HTTP {status}",
                self.cfg.name
            ))
            .with_detail(raw.trim()));
        }
        let parsed: MyMemoryResponse = serde_json::from_str(&raw).map_err(|e| {
            TranslateError::parse(format!("「{}」响应不是预期的 JSON: {e}", self.cfg.name))
                .with_detail(&raw)
        })?;
        // responseStatus 可能是数字 200 也可能是字符串 "403"，统一取整再判断
        let code = parsed
            .response_status
            .as_ref()
            .and_then(status_as_u64);
        if let Some(c) = code {
            if c != 200 {
                let detail = parsed
                    .response_details
                    .clone()
                    .unwrap_or_else(|| "上游未提供说明".to_string());
                let kind = if c == 403 { ErrorKind::RateLimit } else { ErrorKind::Unknown };
                return Err(TranslateError::new(
                    kind,
                    format!("「{}」拒绝了请求（status={c}）", self.cfg.name),
                )
                .with_detail(detail));
            }
        }
        let text_out = parsed
            .response_data
            .and_then(|d| d.translated_text)
            .map(|s| s.trim().to_string())
            .filter(|s| !s.is_empty());
        let out = match text_out {
            Some(t) => t,
            None => {
                // 免费额度用尽时也会走到这里，把上游说明带上，用户才知所以然
                let detail = parsed
                    .response_details
                    .filter(|d| !d.trim().is_empty())
                    .unwrap_or_else(|| raw.clone());
                return Err(TranslateError::new(
                    ErrorKind::Empty,
                    format!("「{}」未返回译文（额度用尽或语言对不支持）", self.cfg.name),
                )
                .with_detail(detail));
            }
        };
        Ok(TranslateResult {
            text: out,
            // 源语言是用户显式指定的，没有可上报的检测结果
            detected: None,
            engine_id: self.cfg.id.clone(),
            engine_name: self.cfg.name.clone(),
            latency_ms: started.elapsed().as_millis() as u64,
            usage: None,
        })
    }
    async fn list_models(&self) -> Result<Vec<String>, TranslateError> {
        Ok(Vec::new())
    }
    async fn test(&self) -> Result<String, TranslateError> {
        let req = super::EngineRequest {
            text: PROBE_TEXT.to_string(),
            from: "en".to_string(),
            to: "zh-Hans".to_string(),
            to_label: "简体中文".to_string(),
            from_label: "英语".to_string(),
            mode: super::TranslateMode::Translate,
            image_png: None,
            via: "preview".to_string(),
        };
        let started = Instant::now();
        let result = self.translate(&req).await?;
        Ok(format!(
            "连通正常 · {}ms · 回显「{}」",
            started.elapsed().as_millis(),
            result.text
        ))
    }
 }
 /// 从数字或字符串形式的 status 字段取整
 fn status_as_u64(v: &serde_json::Value) -> Option<u64> {
    match v {
        serde_json::Value::Number(n) => n.as_u64(),
        serde_json::Value::String(s) => s.trim().parse::<u64>().ok(),
        _ => None,
    }
 }
 fn classify_reqwest(e: reqwest::Error, engine: &str) -> TranslateError {
    if e.is_timeout() {
        return TranslateError::timeout(format!(
            "请求「{engine}」超时，可调大超时时间或检查网络"
        ));
    }
    if e.is_connect() {
        return TranslateError::network(format!("无法连接「{engine}」：{e}，请检查网络"));
    }
    TranslateError::network(format!("请求「{engine}」失败：{e}"))
 }
 #[derive(Debug, Deserialize)]
 struct MyMemoryResponse {
    #[serde(rename = "responseData", default)]
    response_data: Option<ResponseData>,
    #[serde(rename = "responseStatus", default)]
    response_status: Option<serde_json::Value>,
    #[serde(rename = "responseDetails", default)]
    response_details: Option<String>,
 }
 #[derive(Debug, Deserialize)]
 struct ResponseData {
    #[serde(rename = "translatedText", default)]
    translated_text: Option<String>,
 }
@@ -0,0 +1,532 @@
 //! 翻译历史（SQLite）。
 //!
 //! 存储约定：`{app_data_dir}/translate/history.db`。去重键是
 //! `(source_text, to_lang, engine_id)` —— 同一段文字、同一个目标语言、同一个引擎
 //! 只保留一条，重复翻译只更新时间与译文。**不含 `via`**：划词翻过的句子再用主面板翻，
 //! 是同一件事，拆成两条只会让历史变得难搜。
 //!
 //! 收藏条目不参与容量淘汰（`prune_to_max`）——用户明确说「留着」的东西，
 //! 不该因为新记录挤进来而消失。
 //!
 //! 搜索走 FTS5 三元组索引（`history_fts`），详见 `FTS_MIN_CHARS` 与 `fts_phrase` 的说明。
 use std::path::Path;
 use std::sync::Mutex;
 use rusqlite::{params, Connection};
 use serde::Serialize;
 use specta::Type;
 /// 库结构版本。
 ///
 /// 与本值不等的库在打开时**整库重建**（见 `History::new`）。现阶段模块仍在开发、
 /// 未实装，历史属于可丢弃数据，因此不做增量迁移——维护一堆迁移分支、还要处理
 /// 「迁移到一半失败」留下的半新半旧库，成本远高于丢掉几条测试记录。
 /// **实装之后再改结构就必须换成真正的迁移。**
 const SCHEMA_VERSION: i64 = 2;
 /// 走 FTS 索引所需的最小字符数。
 ///
 /// trigram 分词器把文本切成连续 3 字符的 n-gram，索引里不存在长度小于 3 的片段，
 /// 因此 1~2 个字符的 MATCH **不会报错，只会静默返回空结果**。「条件明明对却搜不到」
 /// 比「慢一点」糟糕得多（中文里两字词又恰恰最常见），所以短词回退到 LIKE 全表扫描：
 /// 此时无论走哪条路都谈不上选择性，扫描是可接受的代价。
 const FTS_MIN_CHARS: usize = 3;
 /// 一条历史记录
 #[derive(Debug, Clone, Serialize, Type)]
 #[serde(rename_all = "camelCase")]
 pub struct HistoryItem {
    pub id: i64,
    /// 毫秒时间戳
    pub ts: i64,
    pub from_lang: String,
    pub to_lang: String,
    pub engine_id: String,
    pub engine_name: String,
    pub source_text: String,
    pub result_text: String,
    /// 来源："manual" | "selection" | "clipboard" | "screenshot" | "preview"
    pub via: String,
    pub favorited: bool,
    pub latency_ms: i64,
 }
 pub struct History {
    conn: Mutex<Connection>,
 }
 /// 全部建表语句。结构版本变化时整库重建，所以这里不需要考虑兼容旧结构。
 ///
 /// `history_fts` 是**外部内容表**（`content='history'`）：索引只存倒排表，
 /// 正文仍只留在 `history` 里一份，不做双份存储。代价是它不会自己感知主表变化，
 /// 必须靠下面三个触发器手动同步——漏了任何一个，索引就会和主表静默错位。
 const SCHEMA_SQL: &str = "
    CREATE TABLE IF NOT EXISTS history (
       id           INTEGER PRIMARY KEY,
       ts           INTEGER NOT NULL,
       from_lang    TEXT NOT NULL,
       to_lang      TEXT NOT NULL,
       engine_id    TEXT NOT NULL,
       engine_name  TEXT NOT NULL DEFAULT '',
       source_text  TEXT NOT NULL,
       result_text  TEXT NOT NULL,
       via          TEXT NOT NULL DEFAULT 'manual',
       favorited    INTEGER NOT NULL DEFAULT 0,
       latency_ms   INTEGER NOT NULL DEFAULT 0,
       UNIQUE(source_text, to_lang, engine_id)
    );
    CREATE INDEX IF NOT EXISTS idx_history_ts ON history(ts DESC);
    CREATE INDEX IF NOT EXISTS idx_history_fav ON history(favorited, ts DESC);
    CREATE VIRTUAL TABLE IF NOT EXISTS history_fts USING fts5(
       source_text, result_text,
       content='history', content_rowid='id',
       tokenize='trigram'
    );
    CREATE TRIGGER IF NOT EXISTS history_fts_ai AFTER INSERT ON history BEGIN
       INSERT INTO history_fts(rowid, source_text, result_text)
       VALUES (new.id, new.source_text, new.result_text);
    END;
    CREATE TRIGGER IF NOT EXISTS history_fts_ad AFTER DELETE ON history BEGIN
       INSERT INTO history_fts(history_fts, rowid, source_text, result_text)
       VALUES ('delete', old.id, old.source_text, old.result_text);
    END;
    CREATE TRIGGER IF NOT EXISTS history_fts_au AFTER UPDATE ON history BEGIN
       INSERT INTO history_fts(history_fts, rowid, source_text, result_text)
       VALUES ('delete', old.id, old.source_text, old.result_text);
       INSERT INTO history_fts(rowid, source_text, result_text)
       VALUES (new.id, new.source_text, new.result_text);
    END;
 ";
 impl History {
    pub fn new(dir: &Path) -> Result<Self, String> {
        std::fs::create_dir_all(dir).map_err(|e| format!("创建翻译目录失败: {e}"))?;
        let conn =
            Connection::open(dir.join("history.db")).map_err(|e| format!("打开历史库失败: {e}"))?;
        conn.execute_batch("PRAGMA journal_mode = WAL;")
            .map_err(|e| format!("初始化历史库失败: {e}"))?;
        let version: i64 = conn
            .query_row("PRAGMA user_version", [], |row| row.get(0))
            .map_err(|e| format!("读取历史库版本失败: {e}"))?;
        if version != SCHEMA_VERSION {
            // 先删 FTS 表再删主表：触发器挂在主表上，会跟着一起消失
            conn.execute_batch(
                "DROP TABLE IF EXISTS history_fts;
                 DROP TABLE IF EXISTS history;",
            )
            .map_err(|e| format!("重建历史库失败: {e}"))?;
        }
        conn.execute_batch(SCHEMA_SQL)
            .map_err(|e| format!("初始化历史表失败: {e}"))?;
        conn.execute_batch(&format!("PRAGMA user_version = {SCHEMA_VERSION};"))
            .map_err(|e| format!("写入历史库版本失败: {e}"))?;
        Ok(Self {
            conn: Mutex::new(conn),
        })
    }
    fn conn(&self) -> std::sync::MutexGuard<'_, Connection> {
        self.conn.lock().unwrap_or_else(|e| e.into_inner())
    }
    /// 记录一次翻译（去重：命中则更新时间与译文）。
    pub fn record(
        &self,
        from_lang: &str,
        to_lang: &str,
        engine_id: &str,
        engine_name: &str,
        source_text: &str,
        result_text: &str,
        via: &str,
        latency_ms: i64,
    ) -> Result<(), String> {
        if source_text.trim().is_empty() || result_text.trim().is_empty() {
            return Ok(());
        }
        let now = chrono::Utc::now().timestamp_millis();
        self.conn()
            .execute(
                "INSERT INTO history (ts, from_lang, to_lang, engine_id, engine_name,
                     source_text, result_text, via, favorited, latency_ms)
                 VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, 0, ?9)
                 ON CONFLICT(source_text, to_lang, engine_id)
                 DO UPDATE SET ts = excluded.ts, result_text = excluded.result_text,
                     via = excluded.via, latency_ms = excluded.latency_ms",
                params![
                    now,
                    from_lang,
                    to_lang,
                    engine_id,
                    engine_name,
                    source_text,
                    result_text,
                    via,
                    latency_ms
                ],
            )
            .map_err(|e| format!("写入历史失败: {e}"))?;
        Ok(())
    }
    /// 列表。`query` 非空时按原文/译文模糊匹配。
    ///
    /// 两种 SQL 形态互斥，但**参数个数与顺序固定为 (limit, offset, ?3)**，
    /// 这样绑定点不需要跟着分支走：
    /// - 关键词 ≥ `FTS_MIN_CHARS` 走 FTS5 索引（`history_fts MATCH`）；
    /// - 更短（或没有关键词）走 LIKE。
    ///
    /// 两条路径都是子串语义、都忽略 ASCII 大小写，行为一致。
    pub fn list(
        &self,
        offset: i64,
        limit: i64,
        query: Option<&str>,
        favorited_only: bool,
    ) -> Result<Vec<HistoryItem>, String> {
        let term = query.map(str::trim).filter(|s| !s.is_empty());
        let use_fts = term.is_some_and(|t| t.chars().count() >= FTS_MIN_CHARS);
        let mut sql = String::new();
        if use_fts {
            // 列必须带 h. 前缀：source_text / result_text 在两张表里同名，不加限定会歧义。
            sql.push_str(
                "SELECT h.id, h.ts, h.from_lang, h.to_lang, h.engine_id, h.engine_name,
                        h.source_text, h.result_text, h.via, h.favorited, h.latency_ms
                 FROM history_fts f JOIN history h ON h.id = f.rowid
                 WHERE history_fts MATCH ?3",
            );
            if favorited_only {
                sql.push_str(" AND h.favorited = 1");
            }
            sql.push_str(" ORDER BY h.ts DESC LIMIT ?1 OFFSET ?2");
        } else {
            sql.push_str(
                "SELECT id, ts, from_lang, to_lang, engine_id, engine_name, source_text,
                        result_text, via, favorited, latency_ms FROM history WHERE ",
            );
            if favorited_only {
                sql.push_str("favorited = 1 AND ");
            }
            // 无关键词时 pattern 为 NULL，`?3 IS NULL` 让条件恒真。
            // 这样参数个数固定，避免「有/无 ?3」两种形态下绑定索引不一致。
            // ESCAPE '\'：SQLite 的 LIKE 默认没有转义符，不写这个子句
            // escape_like 对 %/_ 的转义就是无效代码。
            sql.push_str(
                "(?3 IS NULL OR source_text LIKE ?3 ESCAPE '\\' OR result_text LIKE ?3 ESCAPE '\\')
                 ORDER BY ts DESC LIMIT ?1 OFFSET ?2",
            );
        }
        let param3 = term.map(|t| {
            if use_fts {
                fts_phrase(t)
            } else {
                format!("%{}%", escape_like(t))
            }
        });
        let conn = self.conn();
        let mut stmt = conn.prepare(&sql).map_err(|e| format!("查询历史失败: {e}"))?;
        let rows = stmt
            .query_map(params![limit, offset, param3], row_to_item)
            .map_err(|e| format!("查询历史失败: {e}"))?;
        let mut items = Vec::new();
        for row in rows {
            items.push(row.map_err(|e| format!("读取历史失败: {e}"))?);
        }
        Ok(items)
    }
    pub fn delete(&self, id: i64) -> Result<(), String> {
        self.conn()
            .execute("DELETE FROM history WHERE id = ?1", params![id])
            .map_err(|e| format!("删除历史失败: {e}"))?;
        Ok(())
    }
    pub fn clear(&self) -> Result<(), String> {
        self.conn()
            .execute("DELETE FROM history", [])
            .map_err(|e| format!("清空历史失败: {e}"))?;
        Ok(())
    }
    pub fn set_favorited(&self, id: i64, favorited: bool) -> Result<(), String> {
        self.conn()
            .execute(
                "UPDATE history SET favorited = ?1 WHERE id = ?2",
                params![favorited as i64, id],
            )
            .map_err(|e| format!("更新收藏失败: {e}"))?;
        Ok(())
    }
    /// 容量淘汰：超出上限时优先删最旧的非收藏记录。
    pub fn prune_to_max(&self, max_items: i64) {
        if max_items <= 0 {
            return;
        }
        let Ok(conn) = self.conn.lock() else {
            return;
        };
        let _ = conn.execute(
            "DELETE FROM history WHERE id IN (
                SELECT id FROM history WHERE favorited = 0
                ORDER BY ts DESC LIMIT -1 OFFSET ?1
             )",
            params![max_items],
        );
    }
 }
 fn escape_like(input: &str) -> String {
    input.replace('\\', "\\\\").replace('%', "\\%").replace('_', "\\_")
 }
 /// 把用户输入包成一个 FTS5 短语查询。
 ///
 /// **必须包引号**：FTS5 的 MATCH 参数有自己的一套查询语法，`-`、`*`、`(`、`^`
 /// 以及 `AND`/`OR`/`NOT` 都会被当作操作符——用户搜 `a-b` 会被解释成「含 a 但不含 b」，
 /// 搜 `(` 之类则直接抛语法错误。整串加双引号后退化成「按字面顺序出现的短语」，
 /// 与原本 LIKE 子串语义对齐；引号内的 `"` 用双写转义。
 fn fts_phrase(term: &str) -> String {
    format!("\"{}\"", term.replace('"', "\"\""))
 }
 fn row_to_item(row: &rusqlite::Row<'_>) -> rusqlite::Result<HistoryItem> {
    Ok(HistoryItem {
        id: row.get(0)?,
        ts: row.get(1)?,
        from_lang: row.get(2)?,
        to_lang: row.get(3)?,
        engine_id: row.get(4)?,
        engine_name: row.get(5)?,
        source_text: row.get(6)?,
        result_text: row.get(7)?,
        via: row.get(8)?,
        favorited: row.get::<_, i64>(9)? != 0,
        latency_ms: row.get(10)?,
    })
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use std::path::{Path, PathBuf};
    use std::sync::atomic::{AtomicUsize, Ordering};
    /// 每个用例一个独立目录。`History` 持有连接，测试结束前无法删目录（Windows 会拒绝），
    /// 因此这里只保证不互相踩，不留清理——落在系统临时目录里是可以接受的代价。
    fn open(tag: &str) -> (History, PathBuf) {
        static SEQ: AtomicUsize = AtomicUsize::new(0);
        let n = SEQ.fetch_add(1, Ordering::Relaxed);
        let dir = std::env::temp_dir().join(format!(
            "thing-history-test-{}-{tag}-{n}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let history = History::new(&dir).expect("建库失败");
        (history, dir)
    }
    /// 一组覆盖两种分词行为的样例：
    /// 中日英混排、含 FTS 元字符（`-` `*` `"`）、含 LIKE 元字符（`%`）、含 FTS 操作符关键字。
    const SOURCE_JA: &str = "日本語の翻訳を確認します";
    const RESULT_JA: &str = "确认日本语翻译";
    const SOURCE_EN: &str = "return the formatted date string";
    const RESULT_EN: &str = "返回格式化后的日期字符串";
    const SOURCE_JA2: &str = "すべての項目に入力をしてください";
    const RESULT_JA2: &str = "请在所有项目中输入。";
    const SOURCE_META: &str = "tail with \"quote\" and *star and a-b";
    const SOURCE_PCT: &str = "100% done";
    const SOURCE_KW: &str = "a AND b";
    fn seed(h: &History) {
        let rows = [
            (SOURCE_JA, RESULT_JA, "manual"),
            (SOURCE_EN, RESULT_EN, "clipboard"),
            (SOURCE_JA2, RESULT_JA2, "selection"),
            (SOURCE_META, "x", "manual"),
            (SOURCE_PCT, "y", "manual"),
            (SOURCE_KW, "z", "manual"),
        ];
        for (i, (src, res, via)) in rows.iter().enumerate() {
            h.record("auto", "zh-Hans", "mock", "Mock", src, res, via, i as i64)
                .expect("写入失败");
        }
    }
    /// 用原生 LIKE 算出的基准集合，作为 FTS 路径的正确性参照。
    fn like_baseline(dir: &Path, term: &str, favorited_only: bool) -> Vec<i64> {
        let conn = Connection::open(dir.join("history.db")).unwrap();
        let pattern = format!("%{}%", escape_like(term));
        let sql = if favorited_only {
            "SELECT id FROM history WHERE favorited = 1
             AND (source_text LIKE ?1 ESCAPE '\\' OR result_text LIKE ?1 ESCAPE '\\')"
        } else {
            "SELECT id FROM history WHERE
             source_text LIKE ?1 ESCAPE '\\' OR result_text LIKE ?1 ESCAPE '\\'"
        };
        let mut stmt = conn.prepare(sql).unwrap();
        let rows = stmt.query_map(params![pattern], |r| r.get::<_, i64>(0)).unwrap();
        rows.map(|r| r.unwrap()).collect()
    }
    /// 按集合比较，忽略顺序：`record()` 用 wall clock 打时间戳，同一用例内的记录
    /// ts 可能相同，`ORDER BY ts DESC` 的先后不稳定，比顺序会随机失败。
    fn sorted_ids(h: &History, term: &str, favorited_only: bool) -> Vec<i64> {
        let mut ids: Vec<i64> = h
            .list(0, 100, Some(term), favorited_only)
            .expect("查询失败")
            .iter()
            .map(|i| i.id)
            .collect();
        ids.sort_unstable();
        ids
    }
    fn sorted(v: Vec<i64>) -> Vec<i64> {
        let mut v = v;
        v.sort_unstable();
        v
    }
    /// 两种 SQL 形态必须给出**完全一致**的结果。
    ///
    /// 这条测试的核心是钉住长度分流：trigram 索引里没有短于 3 字符的片段，
    /// 对 1~2 字的关键词 `MATCH` 不报错、只返回空集。少了回退分支，中文两字词
    /// （最常见的一类查询）就会「条件明明对却搜不到」。
    #[test]
    fn fts_and_like_paths_agree_across_query_lengths() {
        let (h, dir) = open("paths-agree");
        seed(&h);
        let ids: Vec<i64> = h.list(0, 100, None, false).unwrap().iter().map(|i| i.id).collect();
        assert_eq!(ids.len(), 6, "样例数据应为 6 条（去重键各不相同）");
        h.set_favorited(ids[1], true).unwrap();
        let terms = [
            "确",         // 1 字 → LIKE 回退
            "确认",       // 2 字 → LIKE 回退（中文里最常见，最容易踩坑的长度）
            "fo",         // 2 字符 ASCII → LIKE 回退
            "确认日",     // 3 字 → FTS
            "日本语翻译", // 5 字 → FTS
            "form",       // 4 字符 → FTS，且是 formatted 的子串
            "the formatted",
            "zzz",        // 无命中
            "100%",       // LIKE 元字符：两条路径都必须按字面处理
            "a-b",        // FTS 里 `-` 是操作符，必须被短语引号中和
            "*star",
            "with \"quote\"",
            "AND", // FTS 关键字，必须按字面匹配而不是当运算符
            "(((",
        ];
        for term in terms {
            for favorited_only in [false, true] {
                assert_eq!(
                    sorted_ids(&h, term, favorited_only),
                    sorted(like_baseline(&dir, term, favorited_only)),
                    "关键词 {term:?}（favoritedOnly={favorited_only}）两条路径结果不一致"
                );
            }
        }
    }
    /// 外部内容表不会自动感知主表变化，全靠触发器。漏一个就会让索引与正文静默错位
    /// ——表现是「刚翻过的句子搜不到」或「已删掉的记录还能搜出来」，都很难归因。
    #[test]
    fn triggers_keep_fts_in_sync_with_upsert_and_delete() {
        let (h, _dir) = open("trigger-sync");
        h.record("ja", "zh-Hans", "mock", "Mock", SOURCE_JA, RESULT_JA, "manual", 1)
            .unwrap();
        assert_eq!(sorted_ids(&h, "日本语翻译", false).len(), 1, "新记录应可搜到");
        // 去重键命中 → 走 ON CONFLICT DO UPDATE，应触发 update 触发器
        h.record("ja", "zh-Hans", "mock", "Mock", SOURCE_JA, "换了译文的说法", "manual", 2)
            .unwrap();
        assert_eq!(h.list(0, 100, None, false).unwrap().len(), 1, "应仍是同一条记录");
        assert_eq!(sorted_ids(&h, "换了译文的说法", false).len(), 1, "更新后新译文应可搜到");
        assert!(sorted_ids(&h, "日本语翻译", false).is_empty(), "更新后旧译文不应再命中");
        let id = h.list(0, 100, None, false).unwrap()[0].id;
        h.delete(id).unwrap();
        assert!(sorted_ids(&h, "换了译文的说法", false).is_empty(), "删除后不应再命中");
        h.record("ja", "zh-Hans", "mock", "Mock", SOURCE_JA, RESULT_JA, "manual", 3)
            .unwrap();
        h.clear().unwrap();
        assert!(h.list(0, 100, None, false).unwrap().is_empty());
        assert!(sorted_ids(&h, "换了译文的说法", false).is_empty(), "清空后索引应为空");
    }
    /// FTS 索引必须与主表行数一致。用 FTS5 自带的完整性检查暴露静默错位。
    #[test]
    fn fts_index_passes_integrity_check() {
        let (h, _dir) = open("integrity");
        seed(&h);
        let conn = h.conn();
        conn.execute("INSERT INTO history_fts(history_fts) VALUES('integrity-check')", [])
            .expect("FTS 索引与主表不一致");
    }
    /// 收藏条目不参与容量淘汰（既有约定，顺手一起守住）。
    #[test]
    fn prune_drops_oldest_unfavorited_only() {
        let (h, _dir) = open("prune");
        for i in 0..6 {
            // 原文必须各不相同：去重键含 source_text，同一段文字只会留一条
            let src = format!("{SOURCE_JA}{i}");
            h.record("auto", "zh-Hans", "mock", "Mock", &src, RESULT_JA, "manual", i)
                .unwrap();
        }
        let ids: Vec<i64> = h.list(0, 100, None, false).unwrap().iter().map(|i| i.id).collect();
        assert_eq!(ids.len(), 6);
        let favorite = ids[2];
        h.set_favorited(favorite, true).unwrap();
        h.prune_to_max(3);
        let left: Vec<i64> = h.list(0, 100, None, false).unwrap().iter().map(|i| i.id).collect();
        assert!(left.contains(&favorite), "收藏条目被淘汰了");
        assert_eq!(left.len(), 4, "上限 3 之外只该多留那条收藏，实际剩 {left:?}");
    }
    /// 结构版本变化时整库重建。这条是「现在允许丢数据」这个前提的守卫：
    /// 一旦有人把 SCHEMA_VERSION 忘了改，旧库会带着不兼容的结构跑下去。
    #[test]
    fn stale_schema_is_dropped_and_rebuilt() {
        let (h, dir) = open("schema-reset");
        seed(&h);
        assert_eq!(h.list(0, 100, None, false).unwrap().len(), 6);
        drop(h);
        {
            let conn = Connection::open(dir.join("history.db")).unwrap();
            conn.execute("INSERT INTO history(ts, from_lang, to_lang, engine_id, engine_name, source_text, result_text, via, favorited, latency_ms)
                          VALUES (1,'auto','zh-Hans','mock','Mock','stale row','stale row','manual',0,0)", []).unwrap();
            conn.execute_batch("PRAGMA user_version = 1;").unwrap();
        }
        let rebuilt = History::new(&dir).expect("重建失败");
        assert!(
            rebuilt.list(0, 100, None, false).unwrap().is_empty(),
            "版本不匹配时旧数据应被清掉"
        );
        assert!(sorted_ids(&rebuilt, "stale row", false).is_empty(), "重建后不应残留旧索引");
    }
    /// 短语化必须中和 FTS5 的查询语法，否则用户搜 `a-b` 会被解释成「含 a 但不含 b」，
    /// 搜 `(` 之类则直接抛语法错误。
    #[test]
    fn fts_phrase_quotes_and_escapes() {
        assert_eq!(fts_phrase("a-b"), "\"a-b\"");
        assert_eq!(fts_phrase("say \"hi\""), "\"say \"\"hi\"\"\"");
        assert_eq!(fts_phrase("("), "\"(\"");
    }
 }
@@ -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);
    }
 }
@@ -0,0 +1,15 @@
 //! OCR：把图变字。
 //!
 //! 目前只有 Windows 本地识别（`Windows.Media.Ocr`）。抽象成独立模块的原因是
 //! **截图翻译有两条并行的取字路径**：本地 OCR（离线、零成本、图片不外发）与
 //! 视觉大模型直译（识别 + 翻译一步完成，对表格/菜单这类复杂排版明显更好）。
 //! 两条路径对上层暴露相同的入口签名，`screenshot.ocrMode` 决定走哪条。
 //!
 //! 关于本地 OCR 的三个已知限制（都会在错误信息里引导，而不是含糊报错）：
 //! - 依赖系统 OCR 语言包：英文永远可用，中/日/韩等需要系统安装对应语言包；
 //! - 印刷体效果好，竖排、艺术字、低对比度截图效果差；
 //! - `Windows.Media.Ocr` 要求输入为 BGRA8 格式，其它格式需先转换。
 pub mod windows_ocr;
 pub use windows_ocr::{available_languages, ocr_png};
@@ -0,0 +1,201 @@
 //! Windows.Media.Ocr 本地识别。
 //!
 //! 实现要点（三个坑都已规避）：
 //! 1. **不落盘**。走「`image` 解码 PNG → RGBA 转 BGRA → `CryptographicBuffer` 构造
 //!    `IBuffer` → `SoftwareBitmap::CreateCopyFromBuffer`」的纯内存路径。
 //!    0.52 版 windows crate 的 `RandomAccessStreamReference` 没有 `CreateFromByteArray`，
 //!    走 BitmapDecoder 的流路径既要临时流又要二次解码，因此放弃。
 //! 2. **像素格式**。`RecognizeAsync` 要求 BGRA8，而 PNG 解出来常是 Rgba8，
 //!    转换在这里显式完成（同时交换 R/B 通道），不做这一步识别会失败。
 //! 3. **`IAsyncOperation::get()` 会阻塞当前线程**。调用方必须在阻塞线程池执行，
 //!    并初始化 MTA——在 STA 上 `get()` 有死锁风险。
 //!
 //! 若干方法（`Lines` / `AvailableRecognizerLanguages`）在 windows crate 里按 feature
 //! 裁剪（返回 `IVectorView` 需要 `Foundation_Collections`），缺 feature 时表现为
 //! 「方法不存在」而不是链接错误，排查时先看 Cargo.toml。
 use serde::Serialize;
 use specta::Type;
 use windows::Globalization::Language;
 use windows::Graphics::Imaging::{BitmapPixelFormat, SoftwareBitmap};
 use windows::Media::Ocr::OcrEngine;
 use windows::Security::Cryptography::CryptographicBuffer;
 use windows::Win32::System::Com::{CoInitializeEx, COINIT_MULTITHREADED};
 use super::super::engines::{ErrorKind, TranslateError};
 /// 一行识别结果
 #[derive(Debug, Clone, Serialize, Type)]
 #[serde(rename_all = "camelCase")]
 pub struct OcrLine {
    pub text: String,
    /// 行边界框（相对输入图像的物理像素）。多个词的矩形取并集。
    /// 一并返回是为了给「译文叠加在原文位置上」留出能力——这是截图翻译体验质变的前提。
    pub x: f64,
    pub y: f64,
    pub width: f64,
    pub height: f64,
 }
 /// 一次识别的完整结果
 #[derive(Debug, Clone, Serialize, Type)]
 #[serde(rename_all = "camelCase")]
 pub struct OcrResult {
    pub lines: Vec<OcrLine>,
    /// 实际使用的识别语言（BCP-47）
    pub lang: String,
 }
 /// 对 PNG 图像执行本地 OCR。
 ///
 /// `lang`：`None` 或 "auto" 跟随用户配置的语言，否则用指定的 BCP-47 标签。
 pub fn ocr_png(png: &[u8], lang: Option<&str>) -> Result<OcrResult, TranslateError> {
    // MTA：`get()` 阻塞等待需要正确初始化的公寓；已初始化（S_FALSE）与
    // 变更模式（RPC_E_CHANGED_MODE）都忽略——后者说明调用方已是 STA。
    unsafe {
        let _ = CoInitializeEx(None, COINIT_MULTITHREADED);
    }
    let engine = match lang.map(str::trim).filter(|s| !s.is_empty() && *s != "auto") {
        Some(tag) => create_engine_for(tag)?,
        None => match OcrEngine::TryCreateFromUserProfileLanguages() {
            Ok(e) => e,
            Err(_) => {
                return Err(missing_language_pack(
                    "未检测到可用的 OCR 引擎",
                    "请在系统「设置 → 时间和语言 → 语言和区域」中添加语言并勾选「文本识别」",
                ))
            }
        },
    };
    let used_tag = engine
        .RecognizerLanguage()
        .ok()
        .and_then(|l| l.LanguageTag().ok())
        .map(|t| t.to_string_lossy())
        .unwrap_or_default();
    let bitmap = bitmap_from_png(png)?;
    let recognized = match engine.RecognizeAsync(&bitmap) {
        Ok(op) => match op.get() {
            Ok(r) => r,
            Err(e) => return Err(TranslateError::new(ErrorKind::Unknown, format!("识别失败: {e}"))),
        },
        Err(e) => return Err(TranslateError::new(ErrorKind::Unknown, format!("识别失败: {e}"))),
    };
    let mut lines = Vec::new();
    if let Ok(view) = recognized.Lines() {
        let count = view.Size().unwrap_or(0);
        for i in 0..count {
            let Ok(line) = view.GetAt(i) else { continue };
            let Ok(text) = line.Text() else { continue };
            let text = text.to_string_lossy();
            if text.trim().is_empty() {
                continue;
            }
            let (mut x0, mut y0, mut x1, mut y1) = (f64::MAX, f64::MAX, 0.0_f64, 0.0_f64);
            if let Ok(words) = line.Words() {
                let wcount = words.Size().unwrap_or(0);
                for j in 0..wcount {
                    let Ok(word) = words.GetAt(j) else { continue };
                    let Ok(rect) = word.BoundingRect() else { continue };
                    x0 = x0.min(rect.X as f64);
                    y0 = y0.min(rect.Y as f64);
                    x1 = x1.max((rect.X + rect.Width) as f64);
                    y1 = y1.max((rect.Y + rect.Height) as f64);
                }
            }
            let (x, y, width, height) = if x1 > x0 && y1 > y0 {
                (x0, y0, x1 - x0, y1 - y0)
            } else {
                (0.0, 0.0, 0.0, 0.0)
            };
            lines.push(OcrLine {
                text: text.trim().to_string(),
                x,
                y,
                width,
                height,
            });
        }
    }
    Ok(OcrResult {
        lines,
        lang: used_tag,
    })
 }
 /// 列出系统当前可用的 OCR 语言（BCP-47 标签）。
 /// 设置页用它展示「哪些语言能识别、哪些需要先装语言包」，而不是让用户撞一次错才知道。
 pub fn available_languages() -> Result<Vec<String>, TranslateError> {
    unsafe {
        let _ = CoInitializeEx(None, COINIT_MULTITHREADED);
    }
    let view = OcrEngine::AvailableRecognizerLanguages()
        .map_err(|e| TranslateError::parse(format!("读取系统 OCR 语言失败: {e}")))?;
    let count = view.Size().unwrap_or(0);
    let mut tags = Vec::with_capacity(count as usize);
    for i in 0..count {
        if let Ok(lang) = view.GetAt(i) {
            if let Ok(tag) = lang.LanguageTag() {
                let tag = tag.to_string_lossy();
                if !tag.is_empty() {
                    tags.push(tag);
                }
            }
        }
    }
    tags.sort();
    tags.dedup();
    Ok(tags)
 }
 /// PNG → BGRA8 `SoftwareBitmap`（纯内存，不落盘）。
 fn bitmap_from_png(png: &[u8]) -> Result<SoftwareBitmap, TranslateError> {
    let img = image::load_from_memory(png)
        .map_err(|e| TranslateError::parse(format!("解码截图失败: {e}")))?;
    let rgba = img.to_rgba8();
    let (width, height) = rgba.dimensions();
    // OCR 引擎要求 BGRA8：RGBA 与 BGRA 只差 R/B 两个通道，就地交换
    let mut bgra = rgba.into_raw();
    for px in bgra.chunks_exact_mut(4) {
        px.swap(0, 2);
    }
    let buffer = CryptographicBuffer::CreateFromByteArray(&bgra)
        .map_err(|e| TranslateError::parse(format!("构造图像缓冲失败: {e}")))?;
    SoftwareBitmap::CreateCopyFromBuffer(
        &buffer,
        BitmapPixelFormat::Bgra8,
        width as i32,
        height as i32,
    )
    .map_err(|e| TranslateError::parse(format!("构造位图失败: {e}")))
 }
 fn create_engine_for(tag: &str) -> Result<OcrEngine, TranslateError> {
    let language = match Language::CreateLanguage(&windows::core::HSTRING::from(tag)) {
        Ok(l) => l,
        Err(e) => {
            return Err(TranslateError::config(format!(
                "无法解析 OCR 语言「{tag}」: {e}"
            )))
        }
    };
    match OcrEngine::TryCreateFromLanguage(&language) {
        Ok(engine) => Ok(engine),
        // Try* 系列「失败」的返回形态（空对象 / Err）在 windows-rs 里不完全一致，
        // 统一在这里兜住，给用户「去哪儿装语言包」的确切指引
        Err(_) => Err(missing_language_pack(
            &format!("系统未安装「{tag}」的 OCR 语言包"),
            "请在系统「设置 → 时间和语言 → 语言和区域」中添加该语言并勾选「文本识别」，\
             或把识别语言改回「自动」",
        )),
    }
 }
 fn missing_language_pack(what: &str, how: &str) -> TranslateError {
    TranslateError::config(format!("{what}。{how}"))
 }
@@ -0,0 +1,770 @@
 //! 取词结果的悬浮窗（非激活）。
 //!
 //! 沿用剪贴板预览窗已验证的模式（屏幕外预创建、按光标定位、工作区钳制、内容自适应），
 //! 但有一处**刻意的差异**：本窗口在创建时就打上 `WS_EX_NOACTIVATE`（[`apply_no_activate`]），
 //! 因此显示时永远不会抢走焦点。这对划词翻译是硬要求——抢焦点会取消用户的选区、打断阅读，
 //! 弹出一次就把原文弄没了，功能等于不可用。
 //!
 //! 代价是**收不到键盘事件**：非激活窗口不持有键盘焦点，Escape 之类的快捷键不可靠。
 //! 所以本窗口的交互全部走鼠标（复制、换源、关闭都是按钮），并且靠看护线程在
 //! 「点击窗口外部」时自动收起——不能像剪贴板弹窗那样依赖 `Focused(false)`。
 //!
 //! [`apply_no_activate`]: crate::win32_util::apply_no_activate
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Mutex;
 use std::time::{Duration, Instant};
 use serde::Serialize;
 use tauri::window::{Effect, EffectsBuilder};
 use tauri::{AppHandle, Emitter, Manager, WebviewUrl, WebviewWindowBuilder};
 use super::capture::{self, CaptureRequest};
 use super::settings::TranslateSettings;
 use super::TranslateManager;
 use crate::clipboard::reader::{read_clipboard, ClipData};
 use crate::win32_util::{
    get_cursor_pos, get_dpi_for_point, get_work_area_at_point,
 };
 /// 窗口 label（与 `capabilities/translate-popup.json`、前端 `WINDOWS.translatePopup` 三处对齐，
 /// 因此统一取常量而不是写字面量）
 pub const POPUP_LABEL: &str = crate::constants::windows::TRANSLATE_POPUP;
 /// 弹窗逻辑尺寸。双栏布局（左原文右译文）宽度翻倍；高度只是初值，
 /// 前端测完内容会调 `translate_popup_resize` 贴合（内容区上限 26rem，见前端模板）。
 const POPUP_W: f64 = 840.0;
 const POPUP_BASE_H: f64 = 480.0;
 /// 尺寸上下限（逻辑像素）：防止前端异常值把窗口撑到屏幕外或压成一条线。
 /// MAX_H 高于前端根节点的 max-height（920px）——前端会在内容超过时自行出滚动条，
 /// 这里只是兜住异常值；实际窗口高度以 syncSize 上报为准，不会被钳到。
 const MIN_W: f64 = 300.0;
 const MAX_W: f64 = 900.0;
 const MIN_H: f64 = 72.0;
 const MAX_H: f64 = 960.0;
 /// 光标与弹窗之间的间距
 const GAP: f64 = 12.0;
 /// 看护线程的最大看护时长。超过则自动收起，避免用户离开后弹窗长期滞留在屏幕上。
 const WATCH_MAX: Duration = Duration::from_secs(120);
 /// 看护轮询间隔
 const WATCH_TICK: Duration = Duration::from_millis(40);
 /// 兜底创建路径：窗口是新建的，等前端 `onMounted` 调 ready 再显示
 static PENDING_SHOW: AtomicBool = AtomicBool::new(false);
 /// 兜底路径下待投递的负载（前端 ready 时取走）
 static PENDING_PAYLOAD: Mutex<Option<PopupPayload>> = Mutex::new(None);
 /// 弹窗当前是否可见（同步单一事实来源，hide 时立刻置 false）
 static POPUP_VISIBLE: AtomicBool = AtomicBool::new(false);
 /// 钉住状态：钉住后点击外部与超时都不再自动收起（只能手动关闭）。
 /// hide 时复位——收起即视为本次会话结束，下次打开回到默认自动收起。
 static PINNED: AtomicBool = AtomicBool::new(false);
 /// 本次显示的光标锚点与落位偏好。resize 时沿用它重算位置，
 /// 否则内容变高会从固定左上角往下长、越出工作区。
 #[derive(Clone, Copy)]
 struct Anchor {
    x: i32,
    y: i32,
    /// 优先落在光标右侧（否则左侧）
    prefer_right: bool,
    /// 优先落在光标下方（否则上方）
    prefer_bottom: bool,
 }
 static ANCHOR: Mutex<Option<Anchor>> = Mutex::new(None);
 /// 看护线程防重入
 static WATCHING: AtomicBool = AtomicBool::new(false);
 /// 面板候选条目（翻译面板打开时收集）。
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PanelCandidate {
    /// 候选文本
    pub text: String,
    /// 来源标签："划词" | "剪贴板"（展示用）
    pub origin: String,
 }
 /// 投递给悬浮窗前端的负载。
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PopupPayload {
    /// 待翻译文本（取词失败时为空串）
    pub text: String,
    /// 取词来源："selection"（模拟 Ctrl+C）| "clipboard"（直接读剪贴板）| "screenshot"（截图）| "panel"（翻译面板）
    pub source: String,
    /// 取词失败原因（成功时为 None）
    pub error: Option<String>,
    /// 来源窗口进程名（展示用）
    pub process: String,
    /// 头部补充说明（如「本地识别」「图片已上传至 xx」），比 source 更能回答用户关心的问题
    pub source_note: Option<String>,
    /// 来源窗口句柄（P3 回填替换选区用）
    pub hwnd: i64,
    /// 剪贴板是否已还原
    pub restored_clipboard: bool,
    /// 目标语言（语言码；展示名由前端查语言表得出，避免两处维护同一张表）
    pub to_lang: String,
    /// 源语言（"auto" 表示交给引擎判断）。
    ///
    /// 弹窗必须能自己指定源语言：MyMemory 这类源**不支持自动检测**，
    /// 而划词场景天然不知道原文是什么语言。没有它，这类源在划词里等于不可用。
    pub source_lang: String,
    /// 默认引擎实例 id（"auto" 表示按优先级）
    pub engine_id: String,
    /// 是否默认展开原文
    pub show_original: bool,
    pub font_size: u32,
    /// 正文字号之外的整窗不透明度百分比（100 = 不透明）
    pub opacity: u32,
    /// 优先落位："bottom-right" | "bottom-left" | "top-right" | "top-left"
    pub position_preference: String,
    /// 显示后是否立即翻译。截图翻译关闭「自动翻译」时为 false：只展示识别文本，
    /// 由用户决定是否发翻译请求。
    pub auto_start: bool,
    /// 是否写入历史。预览悬浮窗为 false（固定样例文本，入库只是噪音）。
    pub record: bool,
    /// 预置结果（视觉直译路径用）：识别与翻译在 Rust 侧一步完成，弹窗直接展示，
    /// 不再发第二次请求。为 None 时弹窗自行用 `text` 走翻译引擎。
    pub preset_result: Option<super::engines::TranslateResult>,
    /// 面板候选（仅 source == "panel"）：划词结果与剪贴板首条。
    /// 为空时面板直接聚焦原文输入框，等用户手动输入。
    #[serde(default)]
    pub candidates: Vec<PanelCandidate>,
 }
 // ===== 窗口生命周期 =====
 /// 应用启动时预创建（隐藏）。首次按快捷键时窗口已就绪，直接显示，避免首次创建的时序问题。
 pub fn ensure_window(app: &AppHandle) {
    if app.get_webview_window(POPUP_LABEL).is_some() {
        return;
    }
    create_window(app);
 }
 fn create_window(app: &AppHandle) {
    let win = match WebviewWindowBuilder::new(
        app,
        POPUP_LABEL,
        WebviewUrl::App("index.html#translate-popup".into()),
    )
    .title("翻译")
    .inner_size(POPUP_W, POPUP_BASE_H)
    .position(-10000.0, -10000.0) // 屏幕外，避免隐藏状态下闪一下
    .decorations(false)
    .transparent(true)
    .shadow(true)
    .always_on_top(true)
    .skip_taskbar(true)
    .resizable(false)
    .visible(false)
    .focused(false) // 不抢占焦点
    .effects(EffectsBuilder::new().effects(vec![Effect::Mica]).build())
    .build()
    {
        Ok(w) => w,
        Err(e) => {
            crate::logger::log_error("translate", &format!("创建取词悬浮窗失败: {e}"));
            return;
        }
    };
    // 非激活：显示时不夺取前台。圆角：NOACTIVATE 悬浮窗系统不自动圆角，需显式指定，
    // 否则与剪贴板弹窗外观不一致。
    #[cfg(windows)]
    if let Ok(hwnd) = win.hwnd() {
        crate::win32_util::apply_no_activate(hwnd.0 as isize);
        crate::win32_util::apply_rounded_corners(hwnd.0 as isize);
    }
    crate::logger::log_info("translate", "取词悬浮窗已预创建（隐藏状态）");
 }
 /// 显示悬浮窗并把负载投递给前端（锚点取当前光标位置）。
 pub fn show(app: &AppHandle, payload: PopupPayload) {
    let Some((mx, my)) = get_cursor_pos() else {
        return;
    };
    // 先取锚点再移交 payload：show_with_anchor 会拿走所有权，参数求值顺序里
    // 「先 move 后借用」是编译错误
    let anchor = Anchor::from(mx, my, &payload.position_preference);
    show_with_anchor(app, payload, anchor);
 }
 /// 指定锚点显示（截图翻译用）：结果要贴在**选区**旁，而截图流程里光标
 /// 已经离开了原位置，跟着光标走会飘到别处。
 pub fn show_at(app: &AppHandle, payload: PopupPayload, anchor_x: i32, anchor_y: i32) {
    let anchor = Anchor::from(anchor_x, anchor_y, &payload.position_preference);
    show_with_anchor(app, payload, anchor);
 }
 fn show_with_anchor(app: &AppHandle, payload: PopupPayload, anchor: Anchor) {
    if let Some(win) = app.get_webview_window(POPUP_LABEL) {
        // 用**当前实际尺寸**参与定位：上一次可能是长译文撑高的窗口，
        // 恒按 200px 基础高度定位会让底部越界、等前端 resize 才跳回。
        // outer_size 含四周不可见边框（各约 8px），偏差方向是保守的。
        let scale = anchor.scale();
        let (w, h) = win
            .outer_size()
            .map(|s| {
                (
                    (s.width as f64 / scale).max(POPUP_W),
                    s.height as f64 / scale,
                )
            })
            .unwrap_or((POPUP_W, POPUP_BASE_H));
        mark_shown(anchor);
        let (x, y) = position_for(anchor, w, h);
        let _ = win.set_position(tauri::Position::Physical(tauri::PhysicalPosition { x, y }));
        reveal(&win);
        let _ = app.emit(crate::constants::events::TRANSLATE_POPUP_SHOW, payload);
        return;
    }
    // 兜底：窗口被销毁过，重新创建并等前端 ready
    PENDING_SHOW.store(true, Ordering::SeqCst);
    if let Ok(mut slot) = PENDING_PAYLOAD.lock() {
        *slot = Some(payload);
    }
    mark_shown(anchor);
    create_window(app);
 }
 /// 前端挂载完成后调用（仅兜底创建路径真正显示）。
 pub fn ready(app: &AppHandle) {
    if !PENDING_SHOW.swap(false, Ordering::SeqCst) {
        return;
    }
    let payload = PENDING_PAYLOAD.lock().ok().and_then(|mut slot| slot.take());
    let Some(win) = app.get_webview_window(POPUP_LABEL) else {
        return;
    };
    // 兜底路径窗口建在屏幕外，显示前必须按锚点定位，否则弹窗出现在屏幕外不可见
    if let Some(anchor) = ANCHOR.lock().ok().and_then(|a| *a) {
        let (x, y) = position_for(anchor, POPUP_W, POPUP_BASE_H);
        let _ = win.set_position(tauri::Position::Physical(tauri::PhysicalPosition { x, y }));
    }
    reveal(&win);
    if let Some(p) = payload {
        let _ = app.emit(crate::constants::events::TRANSLATE_POPUP_SHOW, p);
    }
 }
 /// 隐藏（保留复用，不销毁）。
 pub fn hide(app: &AppHandle) {
    POPUP_VISIBLE.store(false, Ordering::SeqCst);
    // 钉住状态随之复位：收起即视为本次会话结束
    PINNED.store(false, Ordering::SeqCst);
    if let Some(win) = app.get_webview_window(POPUP_LABEL) {
        // 若本次显示期间进入过编辑模式（NOACTIVATE 被移除），在这里恢复，
        // 保证下一次显示仍然不抢焦点
        #[cfg(windows)]
        if let Ok(hwnd) = win.hwnd() {
            crate::win32_util::set_no_activate(hwnd.0 as isize, true);
        }
        let _ = win.hide();
        // 以原生 SW_SHOWNOACTIVATE 显示的窗口，Tauri 内部可见性状态可能不同步，
        // 补一次原生 SW_HIDE，确保任何路径下都被可靠隐藏。
        #[cfg(windows)]
        if let Ok(hwnd) = win.hwnd() {
            crate::win32_util::hide_window(hwnd.0 as isize);
        }
    }
    let _ = app.emit(crate::constants::events::TRANSLATE_POPUP_HIDE, ());
 }
 /// 弹窗编辑模式开关：移除/恢复 WS_EX_NOACTIVATE，开启时把弹窗推到前台。
 ///
 /// 弹窗默认是非激活窗口（不抢焦点），代价是收不到键盘事件——原文编辑框因此
 /// 无法输入。用户点击原文编辑区或译文卡片时前端调用 `enable=true`：移除
 /// NOACTIVATE 并把弹窗推到前台，编辑框即可获得键盘焦点、译文可 Ctrl+C。
 /// 弹窗隐藏（[`hide`]）与下次显示（[`reveal`]）都会恢复 NOACTIVATE。
 pub fn set_edit_mode(app: &AppHandle, enable: bool) -> Result<(), String> {
    let Some(win) = app.get_webview_window(POPUP_LABEL) else {
        return Err("弹窗不可用".to_string());
    };
    #[cfg(windows)]
    {
        let Ok(hwnd) = win.hwnd() else {
            return Err("无法获取弹窗句柄".to_string());
        };
        crate::win32_util::set_no_activate(hwnd.0 as isize, !enable);
        if enable {
            // 用户刚点击了弹窗（本进程持有最新输入），force_foreground 可绕过前台锁定
            crate::win32_util::force_foreground(hwnd.0 as isize);
        }
    }
    #[cfg(not(windows))]
    let _ = enable;
    Ok(())
 }
 /// 按内容尺寸自适应（前端测高后调用），返回前端根节点应使用的 max-height。
 ///
 /// 返回值 = 光标所在显示器工作区允许的最大内容高度（逻辑像素，0 表示不限制）。
 /// **刻意来自工作区而不是窗口自身高度**：前端若用 100vh 当上限，窗口缩 → vh 缩 →
 /// 测得高度缩 → 再缩窗口，形成收缩反馈循环（实测窗口一路缩到 MIN_H）。
 /// 工作区是稳定值，前端把它设为根节点 max-height 后整个测量回路收敛。
 ///
 /// 其余行为：**只在越界时钳制，绝不重排回打开时的锚点**。历史实现每次 resize 都按
 /// `ANCHOR`（打开时的光标位置）重算并 `set_position`——窗口尺寸因内容变化而
 /// 调整时，会把用户拖动后的位置覆盖掉（实测：钉住面板拖到别处，粘贴内容
 /// 触发 resize 又跳回原位）。现在以窗口**当前位置**为基准：内容变高向
 /// 下/向右生长越出工作区时，才把位置钳回来。
 pub fn resize(app: &AppHandle, width: f64, height: f64) -> f64 {
    let Some(win) = app.get_webview_window(POPUP_LABEL) else {
        return 0.0;
    };
    if !POPUP_VISIBLE.load(Ordering::SeqCst) {
        return 0.0;
    }
    let w = width.clamp(MIN_W, MAX_W);
    let h = height.clamp(MIN_H, MAX_H);
    let Ok(pos) = win.outer_position() else {
        return 0.0;
    };
    let scale = scale_for(pos.x, pos.y);
    let mut w_px = (w * scale).round() as i32;
    let mut h_px = (h * scale).round() as i32;
    let mut max_inner_logical = 0.0f64;
    let work_area = get_work_area_at_point(pos.x, pos.y);
    // 小屏适配：窗口尺寸不得超过所在显示器的工作区（留边距）
    if let Some((left, top, right, bottom)) = work_area {
        let max_h_px = (bottom - top - 16).max(200);
        let max_w_px = (right - left - 16).max(200);
        h_px = h_px.min(max_h_px);
        w_px = w_px.min(max_w_px);
        max_inner_logical = max_h_px as f64 / scale;
    }
    let _ = win.set_size(tauri::Size::Physical(tauri::PhysicalSize {
        width: w_px.max(1) as u32,
        height: h_px.max(1) as u32,
    }));
    // 越界才钳制：不越界时保持用户拖动后的位置不动
    if let Some((left, top, right, bottom)) = work_area {
        let x = pos.x.clamp(left, (right - w_px).max(left));
        let y = pos.y.clamp(top, (bottom - h_px).max(top));
        if x != pos.x || y != pos.y {
            let _ = win.set_position(tauri::Position::Physical(tauri::PhysicalPosition { x, y }));
        }
    }
    max_inner_logical
 }
 fn reveal(win: &tauri::WebviewWindow) {
    // 每次显示都重置为「不激活」：上一次会话可能以编辑模式结束（NOACTIVATE 被移除）
    #[cfg(windows)]
    if let Ok(hwnd) = win.hwnd() {
        crate::win32_util::set_no_activate(hwnd.0 as isize, true);
    }
    // 不激活显示：保持用户当前窗口的前台状态与选区
    #[cfg(windows)]
    if let Ok(hwnd) = win.hwnd() {
        crate::win32_util::show_no_activate(hwnd.0 as isize);
    }
    #[cfg(not(windows))]
    let _ = win.show();
    spawn_click_outside_watch(win.app_handle().clone());
 }
 impl Anchor {
    fn from(x: i32, y: i32, preference: &str) -> Self {
        match preference {
            "bottom-left" => Self {
                x,
                y,
                prefer_right: false,
                prefer_bottom: true,
            },
            "top-right" => Self {
                x,
                y,
                prefer_right: true,
                prefer_bottom: false,
            },
            "top-left" => Self {
                x,
                y,
                prefer_right: false,
                prefer_bottom: false,
            },
            // "bottom-right" 与未知值：落回默认（右下），与设置页文案一致
            _ => Self {
                x,
                y,
                prefer_right: true,
                prefer_bottom: true,
            },
        }
    }
    fn scale(&self) -> f64 {
        scale_for(self.x, self.y)
    }
 }
 fn mark_shown(anchor: Anchor) {
    POPUP_VISIBLE.store(true, Ordering::SeqCst);
    if let Ok(mut slot) = ANCHOR.lock() {
        *slot = Some(anchor);
    }
 }
 fn scale_for(x: i32, y: i32) -> f64 {
    get_dpi_for_point(x, y).unwrap_or(96) as f64 / 96.0
 }
 /// 按锚点与落位偏好算出弹窗左上角（物理像素）。
 ///
 /// 两级处理，意义不同：先按偏好落位，放不下时**翻到另一侧**（处理常见情况，
 /// 例如光标贴着屏幕右缘）；最后再钳制到工作区（兜住极端情况，例如窗口比屏幕还宽）。
 fn position_for(anchor: Anchor, w: f64, h: f64) -> (i32, i32) {
    let (left, top, right, bottom) =
        get_work_area_at_point(anchor.x, anchor.y).unwrap_or((0, 0, 1920, 1040));
    let scale = anchor.scale();
    let w_px = w * scale;
    let h_px = h * scale;
    let mut x = if anchor.prefer_right {
        anchor.x as f64 + GAP
    } else {
        anchor.x as f64 - GAP - w_px
    };
    if anchor.prefer_right && x + w_px > right as f64 {
        x = anchor.x as f64 - GAP - w_px;
    } else if !anchor.prefer_right && x < left as f64 {
        x = anchor.x as f64 + GAP;
    }
    let mut y = if anchor.prefer_bottom {
        anchor.y as f64 + GAP
    } else {
        anchor.y as f64 - GAP - h_px
    };
    if anchor.prefer_bottom && y + h_px > bottom as f64 {
        y = anchor.y as f64 - GAP - h_px;
    } else if !anchor.prefer_bottom && y < top as f64 {
        y = anchor.y as f64 + GAP;
    }
    let min_x = left as f64;
    let max_x = (right as f64 - w_px).max(min_x);
    let min_y = top as f64;
    let max_y = (bottom as f64 - h_px).max(min_y);
    (
        x.clamp(min_x, max_x).round() as i32,
        y.clamp(min_y, max_y).round() as i32,
    )
 }
 /// 设置钉住状态（前端钉住按钮调用）。
 pub fn set_pinned(pinned: bool) {
    PINNED.store(pinned, Ordering::SeqCst);
 }
 /// 点击弹窗外部即收起。
 ///
 /// 为什么不用 `Focused(false)`：本窗口是 NOACTIVATE 的，永远不会获得焦点，
 /// 也就永远收不到失焦事件。只能主动轮询「左键按下沿是否发生在窗口外」。
 /// **钉住时整条自动收起路径失效**（点击外部与超时都不收），只能手动关闭。
 fn spawn_click_outside_watch(app: AppHandle) {
    if WATCHING.swap(true, Ordering::SeqCst) {
        return;
    }
    std::thread::spawn(move || {
        let start = Instant::now();
        let mut was_down = false;
        loop {
            std::thread::sleep(WATCH_TICK);
            if !POPUP_VISIBLE.load(Ordering::SeqCst)
                || app.get_webview_window(POPUP_LABEL).is_none()
            {
                break;
            }
            let pinned = PINNED.load(Ordering::SeqCst);
            if start.elapsed() > WATCH_MAX && !pinned {
                hide(&app);
                break;
            }
            let down = crate::win32_util::is_left_button_down();
            // 按下沿判定：上一轮未按下、本轮按下，且落点在窗口外
            if down && !was_down && !pinned && !cursor_in_popup(&app) {
                hide(&app);
                break;
            }
            was_down = down;
        }
        WATCHING.store(false, Ordering::SeqCst);
    });
 }
 fn cursor_in_popup(app: &AppHandle) -> bool {
    let Some(win) = app.get_webview_window(POPUP_LABEL) else {
        return false;
    };
    let (Ok(pos), Ok(size)) = (win.outer_position(), win.outer_size()) else {
        return false;
    };
    let Some((cx, cy)) = get_cursor_pos() else {
        return false;
    };
    cx >= pos.x && cx <= pos.x + size.width as i32 && cy >= pos.y && cy <= pos.y + size.height as i32
 }
 // ===== 快捷键与翻译面板入口 =====
 /// 按当前设置注册/注销「翻译面板」全局快捷键（默认 Ctrl+2）。
 ///
 /// 面板打开时会尝试读取当前划词（若「启用划词翻译」）与剪贴板首条文本作为候选，
 /// 覆盖了旧版「翻译取词 Alt+T」「翻译剪贴板 Alt+Shift+T」两个入口的全部场景；
 /// 那两个快捷键因此移除，这里顺带注销其历史注册（升级后首次应用设置时清理）。
 ///
 /// 设置项为空串即注销（`register_shortcut` 的既定语义）。
 pub fn apply_shortcuts(app: &AppHandle) -> Result<(), String> {
    let Some(manager) = app.try_state::<TranslateManager>() else {
        return Ok(());
    };
    let panel_key = manager.load_settings().selection.panel_shortcut.clone();
    // 旧版入口已不存在，显式清理历史注册，释放被 Alt+T / Alt+Shift+T 占用的组合键
    crate::shortcut::unregister_shortcut(app, "翻译取词");
    crate::shortcut::unregister_shortcut(app, "翻译剪贴板");
    let mut errors: Vec<String> = Vec::new();
    let r = crate::shortcut::register_shortcut(app, "翻译面板", &panel_key, |handle| {
        let handle = handle.clone();
        // 收集候选含最长约 1s 的阻塞等待，绝不能跑在快捷键回调线程上
        std::thread::spawn(move || on_panel_shortcut(&handle));
    });
    if let Err(e) = r {
        errors.push(e);
    }
    // 快捷键生效就顺手预创建窗口，避免首次触发时现建 WebView
    if !panel_key.trim().is_empty() {
        ensure_window(app);
    }
    if errors.is_empty() {
        Ok(())
    } else {
        Err(errors.join("；"))
    }
 }
 /// 面板候选：划词（若启用且非 clipboard 模式）+ 剪贴板首条文本（去重）。
 ///
 /// 顺序执行而非并行：兼容路径取词会临时占用剪贴板，并行读会拿到中间状态。
 /// 取词失败静默跳过——面板里还有剪贴板候选与手动输入，失败提示反而碍事
 /// （与旧取词路径「失败也弹窗」不同，这里失败不阻断打开面板）。
 fn collect_candidates(app: &AppHandle) -> Vec<PanelCandidate> {
    let Some(manager) = app.try_state::<TranslateManager>() else {
        return Vec::new();
    };
    let settings = manager.load_settings();
    let sel = settings.selection.clone();
    let mut out: Vec<PanelCandidate> = Vec::new();
    if sel.enabled && sel.mode.trim() != "clipboard" {
        let req = CaptureRequest {
            max_chars: sel.max_chars as usize,
            restore_clipboard: sel.restore_clipboard,
            blacklist: sel.blacklist.clone(),
            mode: sel.mode.clone(),
        };
        if let Ok(outcome) = capture::capture_selection(app, &req) {
            if !outcome.text.trim().is_empty() {
                out.push(PanelCandidate {
                    text: outcome.text,
                    origin: "划词".to_string(),
                });
            }
        }
    }
    // 只读不写：不模拟按键，终端里的 Ctrl+C 不受影响
    if let Some(ClipData::Text(t)) = read_clipboard() {
        let t = t.trim().to_string();
        if !t.is_empty() && !out.iter().any(|c| c.text == t) {
            out.push(PanelCandidate {
                text: t,
                origin: "剪贴板".to_string(),
            });
        }
    }
    out
 }
 fn on_panel_shortcut(app: &AppHandle) {
    // 已显示：保持原状态（内容不动），只把它带到前台恢复键盘输入
    if POPUP_VISIBLE.load(Ordering::SeqCst) {
        focus_panel(app);
        return;
    }
    let Some(manager) = app.try_state::<TranslateManager>() else {
        return;
    };
    let settings = manager.load_settings();
    // 候选必须在面板抢焦点**之前**收集：取词（UIA / 模拟按键）都作用在
    // 当时的前台目标应用上，面板一旦激活，取到的就只剩面板自己了。
    // 代价是按下快捷键到面板出现要等一次取词（UIA 命中时毫秒级，最差约 1s）。
    let candidates = collect_candidates(app);
    // 收集期间用户可能已通过其他方式打开了面板（如再次连按）：不再覆盖
    if POPUP_VISIBLE.load(Ordering::SeqCst) {
        focus_panel(app);
        return;
    }
    let mut payload =
        build_payload(&settings, String::new(), "panel", None, String::new(), 0, false);
    // 面板不自动翻译：原文空着，等用户选候选或手动输入
    payload.auto_start = false;
    payload.candidates = candidates;
    show(app, payload);
    // 面板需要键盘输入（候选导航、原文编辑），显示后立即取得焦点
    focus_panel(app);
 }
 /// 把弹窗带到前台并恢复键盘输入（移除 NOACTIVATE + 强制前台）。
 fn focus_panel(app: &AppHandle) {
    if let Some(win) = app.get_webview_window(POPUP_LABEL) {
        #[cfg(windows)]
        if let Ok(hwnd) = win.hwnd() {
            crate::win32_util::set_no_activate(hwnd.0 as isize, false);
            crate::win32_util::force_foreground(hwnd.0 as isize);
        }
    }
 }
 #[allow(clippy::too_many_arguments)]
 fn build_payload(
    settings: &TranslateSettings,
    text: String,
    source: &str,
    error: Option<String>,
    process: String,
    hwnd: i64,
    restored_clipboard: bool,
 ) -> PopupPayload {
    build_payload_with(
        settings,
        text,
        source,
        error,
        process,
        hwnd,
        restored_clipboard,
        None,
        None,
    )
 }
 /// 组装弹窗负载。`source_note` / `preset_result` 只有截图链路会用到。
 #[allow(clippy::too_many_arguments)]
 fn build_payload_with(
    settings: &TranslateSettings,
    text: String,
    source: &str,
    error: Option<String>,
    process: String,
    hwnd: i64,
    restored_clipboard: bool,
    source_note: Option<String>,
    preset_result: Option<super::engines::TranslateResult>,
 ) -> PopupPayload {
    PopupPayload {
        text,
        source: source.to_string(),
        error,
        process,
        source_note,
        hwnd,
        restored_clipboard,
        to_lang: settings
            .popup
            .effective_target_lang(&settings.default_target)
            .to_string(),
        source_lang: settings.popup.effective_source_lang().to_string(),
        engine_id: settings.default_engine_id.clone(),
        show_original: settings.popup.show_original,
        font_size: settings.popup.font_size,
        opacity: settings.popup.opacity,
        position_preference: settings.popup.position_preference.clone(),
        auto_start: true,
        // 预览（source == "preview"）用固定样例文本走链路，入库只是噪音
        record: source != "preview",
        preset_result,
        candidates: Vec::new(),
    }
 }
 /// 预览用负载：用一段固定文本走完整链路（窗口定位、非激活显示、翻译、复制）。
 ///
 /// 存在的理由：**从应用内无法真正测试取词**——测试时前台窗口是本应用自己，
 /// Ctrl+C 只会落到一个没有选区的窗口上。所以就"验证悬浮窗这条链路"而言，
 /// 预览比伪造一次取词更有意义，也让用户不必离开设置页去试。
 pub fn preview_payload(settings: &TranslateSettings) -> PopupPayload {
    build_payload(
        settings,
        "The quick brown fox jumps over the lazy dog.".to_string(),
        "preview",
        None,
        String::new(),
        0,
        false,
    )
 }
 /// 截图翻译的结果弹窗入口（锚点为选区右下角，结果贴在选区旁）。
 ///
 /// `preset_result` 为 Some 时表示识别与翻译已在 Rust 侧一步完成（视觉直译），
 /// 弹窗只负责展示；为 None 时弹窗用 `text`（OCR 文本）自行走翻译引擎。
 #[allow(clippy::too_many_arguments)]
 pub fn show_screenshot_result(
    app: &AppHandle,
    settings: &TranslateSettings,
    text: String,
    source_note: Option<String>,
    preset_result: Option<super::engines::TranslateResult>,
    auto_start: bool,
    anchor_x: i32,
    anchor_y: i32,
 ) {
    let mut payload = build_payload(
        settings,
        text,
        "screenshot",
        None,
        String::new(),
        0,
        false,
    );
    payload.source_note = source_note;
    payload.preset_result = preset_result;
    payload.auto_start = auto_start;
    show_at(app, payload, anchor_x, anchor_y);
 }
 /// 截图链路的失败弹窗：识别失败也弹窗，用户视线就在选区那里。
 pub fn show_screenshot_error(
    app: &AppHandle,
    settings: &TranslateSettings,
    message: String,
    anchor_x: i32,
    anchor_y: i32,
 ) {
    let mut payload = build_payload(
        settings,
        String::new(),
        "screenshot",
        Some(message),
        String::new(),
        0,
        false,
    );
    payload.auto_start = false;
    show_at(app, payload, anchor_x, anchor_y);
 }
@@ -0,0 +1,400 @@
 //! 翻译模块设置的数据模型与默认值。
 //!
 //! 持久化位置：`{app_data_dir}/translate/settings.json`（与音乐模块同一范式）。
 //! 容器级 `#[serde(default)]`：新增字段对旧配置文件是**向后兼容**的——缺字段取
 //! 默认值而不是让整份设置反序列化失败，避免用户因为一次升级丢掉全部配置。
 //!
 //! 安全姿态：**API Key 不在这里**。本结构只允许出现 `hasApiKey` 这类派生展示字段
 //! （且由命令层回填，不落盘），明文一律进系统凭据管理器，见 [`super::engine_secret_key`]。
 use serde::{Deserialize, Serialize};
 use specta::Type;
 use super::engines::TranslateMode;
 /// 提示词模板。`{target}` 为占位符，翻译时替换为目标语言的自然语言全称
 /// （用全称而非语言码，模型遵循度明显更高）。
 #[derive(Debug, Clone, Serialize, Deserialize, Type)]
 #[serde(rename_all = "camelCase", default)]
 pub struct PromptTemplates {
    /// 纯翻译（默认模式）
    pub translate: String,
    /// 润色（P3）
    pub polish: String,
    /// 解释（P3）
    pub explain: String,
    /// 总结（P3）
    pub summarize: String,
 }
 impl Default for PromptTemplates {
    fn default() -> Self {
        Self {
            translate: "你是专业翻译引擎。将用户内容翻译为{target}。\n\
                 要求：只输出译文，不解释、不加引号、不保留原文；保持术语、代码片段、\
                 专有名词、数字与原有格式（Markdown / 换行 / 列表）不变；\
                 若原文已经是{target}，则原样返回。"
                .to_string(),
            polish:
                "你是专业文字编辑。将用户内容改写为更地道、通顺的{target}，保持原意与信息量不变。\
                 只输出改写结果，不解释。"
                    .to_string(),
            explain:
                "你是专业讲解者。用{target}解释用户给出的内容：先说要点，再说明背景与可能的歧义。\
                 保持简洁，不要复述原文。"
                    .to_string(),
            summarize:
                "你是专业摘要助手。用{target}总结用户给出的内容，保留关键事实、数字与结论，\
                 去掉冗余表述。只输出摘要。"
                    .to_string(),
        }
    }
 }
 impl PromptTemplates {
    /// 取指定模式的模板（未填写时退回默认模板）。
    pub fn for_mode(&self, mode: TranslateMode) -> &str {
        let candidate = match mode {
            TranslateMode::Translate => &self.translate,
            TranslateMode::Polish => &self.polish,
            TranslateMode::Explain => &self.explain,
            TranslateMode::Summarize => &self.summarize,
        };
        if candidate.trim().is_empty() {
            self.translate.as_str()
        } else {
            candidate.as_str()
        }
    }
 }
 /// 单个翻译引擎实例的配置。
 ///
 /// 「实例」而非「类型」：同一类型可以配置多份（例如官方 API 与本地 Ollama 并存），
 /// 每份有自己的 id / 优先级 / 模型与参数。
 #[derive(Debug, Clone, Serialize, Deserialize, Type)]
 #[serde(rename_all = "camelCase", default)]
 pub struct TranslateEngineConfig {
    /// 实例唯一标识（同时是凭据键的一部分，创建后不建议修改）
    pub id: String,
    /// 展示名称
    pub name: String,
    /// 引擎类型："ai"（OpenAI 兼容）| "free"（免密钥网络源）| "cloud"（需签名的云厂商，P3）
    pub kind: String,
    /// 预设标识："deepseek" | "openai" | "ollama" | "custom" | "libretranslate" | "mymemory"
    pub preset: String,
    /// 是否参与「自动」模式的候选
    pub enabled: bool,
    /// 优先级（数值越小越先尝试；自动模式下失败按序降级到下一个）
    pub priority: i32,
    /// API 根地址，如 https://api.deepseek.com（末尾可有可无 /，不可含 /chat/completions）
    pub base_url: String,
    /// 模型标识，如 deepseek-flash
    pub model: String,
    /// 采样温度（翻译建议 0.2~0.3）
    pub temperature: f64,
    /// 单次请求最大输出 token
    pub max_tokens: u32,
    /// 请求超时（毫秒）
    pub timeout_ms: u64,
    /// 自定义 system prompt；**非空时覆盖模式模板**（留空表示用全局模板）
    pub system_prompt: String,
    /// 额外请求体字段的 JSON 文本（用于 thinking / enable_thinking 这类非标准参数）；
    /// 用文本而非结构化字段：一是前端直接给文本域，二是避免把任意 JSON 塞进类型绑定。
    pub extra_body: Option<String>,
    /// 是否支持图像输入（截图翻译的「视觉直译」模式只发给勾选了此项的引擎）。
    /// 默认 false：多模态模型与文本模型的计费和端点约束不同，宁可让用户显式勾选。
    #[serde(default)]
    pub supports_vision: bool,
 }
 impl Default for TranslateEngineConfig {
    fn default() -> Self {
        Self {
            id: String::new(),
            name: String::new(),
            kind: "ai".to_string(),
            preset: "custom".to_string(),
            enabled: true,
            priority: 100,
            base_url: String::new(),
            model: String::new(),
            temperature: 0.3,
            max_tokens: 4096,
            timeout_ms: 30_000,
            system_prompt: String::new(),
            extra_body: None,
            supports_vision: false,
        }
    }
 }
 impl TranslateEngineConfig {
    /// 内置 DeepSeek 预设：默认引擎。模型标识取现行名 `deepseek-flash`
    /// （`deepseek-chat` / `deepseek-reasoner` 已于 2026-07-24 停用；`deepseek-v4-flash`
    /// 等旧名虽仍被受理，但请求已被路由到 V4.1-Flash，不适合再写进默认配置）。
    pub fn deepseek_default() -> Self {
        Self {
            id: "deepseek".to_string(),
            name: "DeepSeek Flash".to_string(),
            kind: "ai".to_string(),
            preset: "deepseek".to_string(),
            enabled: true,
            priority: 10,
            base_url: "https://api.deepseek.com".to_string(),
            model: "deepseek-flash".to_string(),
            temperature: 0.3,
            max_tokens: 4096,
            timeout_ms: 30_000,
            // 翻译场景用非思考模式：不写 thinking / reasoning_effort，换低延迟低费用
            system_prompt: String::new(),
            extra_body: None,
            supports_vision: false,
        }
    }
 }
 /// 划词翻译设置（P1 生效；结构在 P0 即定型，避免 P2 改数据结构）。
 ///
 /// P2 重构说明：原「取词快捷键 Alt+T」「翻译剪贴板 Alt+Shift+T」已移除，
 /// 统一为「翻译面板」快捷键（`panel_shortcut`）——面板打开时自动尝试读取
 /// 当前划词与剪贴板首条作为候选，覆盖了原来两个入口的全部场景。
 #[derive(Debug, Clone, Serialize, Deserialize, Type)]
 #[serde(rename_all = "camelCase", default)]
 pub struct SelectionSettings {
    /// 总开关：打开翻译面板时是否尝试读取当前划词作为候选
    pub enabled: bool,
    /// 打开翻译面板的全局快捷键（默认 Ctrl+2）
    #[serde(default = "default_panel_shortcut")]
    pub panel_shortcut: String,
    /// 取词方式：
    /// - "smart"（默认）：先用 UIA 直读选区，读不到再退回模拟 Ctrl+C。不碰剪贴板，
    ///   因此不受「目标窗口提权」「Alt 仍被按住导致 Ctrl+C 变成 Alt+Ctrl+C」这两类问题影响。
    /// - "compat"：只用模拟 Ctrl+C（覆盖最广，但会短暂占用剪贴板）。
    /// - "clipboard"：不取词，面板只提供剪贴板首条作为候选。
    pub mode: String,
    /// 取词后是否还原剪贴板（关掉则保留选中文本）
    pub restore_clipboard: bool,
    /// 单次取词的字符数上限。超出直接拒绝并提示：划词误选整篇文档时，
    /// 发一个几万字的请求既慢又费钱，不如让用户明确知道发生了什么。
    pub max_chars: u32,
    /// 取词跳过的进程名黑名单（终端类 Ctrl+C 是中断信号，必须排除）
    pub blacklist: Vec<String>,
 }
 fn default_panel_shortcut() -> String {
    "Ctrl+2".to_string()
 }
 impl Default for SelectionSettings {
    fn default() -> Self {
        Self {
            // P0 未实现取词，默认关闭以免给出「已开启但无反应」的错误预期
            enabled: false,
            panel_shortcut: default_panel_shortcut(),
            // 默认「智能」：UIA 直读优先，读不到再退回模拟 Ctrl+C
            mode: "smart".to_string(),
            restore_clipboard: true,
            max_chars: 2000,
            blacklist: vec![
                "WindowsTerminal.exe".to_string(),
                "conhost.exe".to_string(),
                "mintty.exe".to_string(),
                "OpenConsole.exe".to_string(),
            ],
        }
    }
 }
 /// 划词结果悬浮窗外观（P1 生效）。
 #[derive(Debug, Clone, Serialize, Deserialize, Type)]
 #[serde(rename_all = "camelCase", default)]
 pub struct PopupSettings {
    /// 正文字号（逻辑像素）
    pub font_size: u32,
    /// 不透明度百分比（100 = 不透明）
    pub opacity: u32,
    /// 优先落位："bottom-right" | "bottom-left" | "top-right" | "top-left"
    pub position_preference: String,
    /// 是否默认展开原文
    pub show_original: bool,
    /// 划词弹窗的源语言（"auto" 表示交给引擎判断）。
    ///
    /// 存在的理由：MyMemory 这类源**不支持自动检测**，而划词场景天然不知道源语言。
    /// 与其让弹窗永远传 auto、把这类源判成「不可用」，不如让用户在这里定一次并记住。
    #[serde(default = "default_source_lang")]
    pub source_lang: String,
    /// 划词弹窗的目标语言。空串表示跟随全局「默认目标语言」。
    #[serde(default)]
    pub target_lang: String,
 }
 fn default_source_lang() -> String {
    "auto".to_string()
 }
 impl Default for PopupSettings {
    fn default() -> Self {
        Self {
            font_size: 13,
            opacity: 100,
            position_preference: "bottom-right".to_string(),
            show_original: true,
            source_lang: default_source_lang(),
            target_lang: String::new(),
        }
    }
 }
 impl PopupSettings {
    /// 生效的源语言：空串（旧配置）按 auto 处理。
    pub fn effective_source_lang(&self) -> &str {
        let v = self.source_lang.trim();
        if v.is_empty() {
            "auto"
        } else {
            v
        }
    }
    /// 生效的目标语言：未单独设置时跟随全局默认。
    pub fn effective_target_lang<'a>(&'a self, fallback: &'a str) -> &'a str {
        let v = self.target_lang.trim();
        if v.is_empty() {
            fallback
        } else {
            v
        }
    }
 }
 /// 截图翻译设置。
 #[derive(Debug, Clone, Serialize, Deserialize, Type)]
 #[serde(rename_all = "camelCase", default)]
 pub struct ScreenshotSettings {
    /// 识别方式："windows"（Windows.Media.Ocr，本地离线，默认）| "vision"（视觉模型直译）
    pub ocr_mode: String,
    /// OCR 语言："auto" 或 BCP-47 标签（如 en-US / zh-Hans-CN）
    pub ocr_lang: String,
    /// 框选完成后是否自动翻译（关闭则只识别，译文由用户在悬浮窗手动触发）
    pub auto_translate: bool,
 }
 impl Default for ScreenshotSettings {
    fn default() -> Self {
        Self {
            ocr_mode: "windows".to_string(),
            ocr_lang: "auto".to_string(),
            auto_translate: true,
        }
    }
 }
 /// 翻译历史设置（P2 生效）。
 #[derive(Debug, Clone, Serialize, Deserialize, Type)]
 #[serde(rename_all = "camelCase", default)]
 pub struct HistorySettings {
    pub enabled: bool,
    /// 保留条数上限（超出按时间淘汰）
    pub max_items: u32,
 }
 impl Default for HistorySettings {
    fn default() -> Self {
        Self {
            enabled: true,
            max_items: 2000,
        }
    }
 }
 /// 翻译模块设置根结构。
 #[derive(Debug, Clone, Serialize, Deserialize, Type)]
 #[serde(rename_all = "camelCase", default)]
 pub struct TranslateSettings {
    /// 结构版本号（用于后续迁移判断）
    pub version: u32,
    /// 默认目标语言（内部代码，如 zh-Hans）
    pub default_target: String,
    /// 默认引擎实例 id（"auto" 表示按优先级自动降级）
    pub default_engine_id: String,
    /// 自动模式下的失败降级开关
    pub auto_fallback: bool,
    /// 翻译请求是否走代理模块（mihomo mixed 端口）。
    /// **默认关闭**：自建 LibreTranslate 在境内、MyMemory 与 DeepSeek 均可直连，
    /// 不需要代理；仅当翻译服务部署在境外或直连被拦截时由用户显式打开。
    pub use_proxy: bool,
    /// 引擎实例列表
    pub engines: Vec<TranslateEngineConfig>,
    pub selection: SelectionSettings,
    pub popup: PopupSettings,
    pub screenshot: ScreenshotSettings,
    pub history: HistorySettings,
    pub prompt_templates: PromptTemplates,
 }
 impl Default for TranslateSettings {
    fn default() -> Self {
        Self {
            version: 1,
            default_target: "zh-Hans".to_string(),
            default_engine_id: "deepseek".to_string(),
            auto_fallback: true,
            use_proxy: false,
            engines: vec![TranslateEngineConfig::deepseek_default()],
            selection: SelectionSettings::default(),
            popup: PopupSettings::default(),
            screenshot: ScreenshotSettings::default(),
            history: HistorySettings::default(),
            prompt_templates: PromptTemplates::default(),
        }
    }
 }
 impl TranslateSettings {
    /// 按 id 找引擎实例。
    pub fn engine(&self, id: &str) -> Option<&TranslateEngineConfig> {
        self.engines.iter().find(|e| e.id == id)
    }
    /// 参与「自动」模式的引擎，按优先级升序。
    pub fn auto_candidates(&self) -> Vec<&TranslateEngineConfig> {
        let mut list: Vec<&TranslateEngineConfig> = self.engines.iter().filter(|e| e.enabled).collect();
        list.sort_by_key(|e| e.priority);
        list
    }
    /// 自愈：列表为空时补回 DeepSeek 默认实例；默认引擎 id 失效时回落到第一个可用实例。
    /// 返回是否发生了变更（由调用方决定落盘）。
    pub fn heal(&mut self) -> bool {
        let mut changed = false;
        if self.engines.is_empty() {
            self.engines.push(TranslateEngineConfig::deepseek_default());
            changed = true;
        }
        if self.default_target.trim().is_empty() {
            self.default_target = "zh-Hans".to_string();
            changed = true;
        }
        if self.default_engine_id.trim().is_empty() {
            self.default_engine_id = "auto".to_string();
            changed = true;
        }
        if self.default_engine_id != "auto" && self.engine(&self.default_engine_id).is_none() {
            // 指向的实例已被删除：不要静默改写成某个实例，改为「自动」更符合用户预期
            self.default_engine_id = "auto".to_string();
            changed = true;
        }
        // v1 → v2：取词方式默认值从 "compat" 改为 "smart"（UIA 直读已实现）。
        // v1 里这个字段没有任何 UI 入口，用户不可能主动选过它，因此直接迁移是安全的；
        // 迁移后用户再选 "compat" 会被原样保留（版本号已推进，不会再被改写）。
        if self.version < 2 {
            if self.selection.mode.trim() == "compat" {
                self.selection.mode = "smart".to_string();
            }
            self.version = 2;
            changed = true;
        }
        changed
    }
 }
@@ -137,6 +137,30 @@ pub fn apply_no_activate(hwnd: isize) {
    }
 }
 /// 按需添加/移除 WS_EX_NOACTIVATE（不动 WS_EX_TOOLWINDOW）。
 ///
 /// 取词悬浮窗默认不激活；但弹窗里的原文编辑框需要键盘焦点——NOACTIVATE 窗口
 /// 永远拿不到焦点，根本无法输入。用户点击编辑区时移除该样式并强制激活
 /// （见 [`force_foreground`]），弹窗隐藏时恢复，保证下一次划词仍不抢焦点。
 #[cfg(windows)]
 pub fn set_no_activate(hwnd: isize, no_activate: bool) {
    use windows_sys::Win32::UI::WindowsAndMessaging::{
        GetWindowLongPtrW, SetWindowLongPtrW, GWL_EXSTYLE, WS_EX_NOACTIVATE,
    };
    unsafe {
        let ex = GetWindowLongPtrW(hwnd, GWL_EXSTYLE);
        let new_ex = if no_activate {
            ex | (WS_EX_NOACTIVATE as isize)
        } else {
            ex & !(WS_EX_NOACTIVATE as isize)
        };
        SetWindowLongPtrW(hwnd, GWL_EXSTYLE, new_ex);
    }
 }
 #[cfg(not(windows))]
 pub fn set_no_activate(_hwnd: isize, _no_activate: bool) {}
 /// 鼠标左键当前是否按下（GetAsyncKeyState，全局异步状态，无需窗口焦点）。
 /// 供看护线程轮询检测"点击外部"（配合按下沿判定）。
 #[cfg(windows)]
@@ -1,7 +1,7 @@
 {
  "$schema": "https://schema.tauri.app/config/2",
  "productName": "thing",
-  "version": "26.9.1",
+  "version": "26.9.3",
  "identifier": "thing.lfeng.me",
  "build": {
    "beforeDevCommand": "bun run dev",
@@ -24,7 +24,7 @@
      }
    ],
    "security": {
-      "csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: asset: http://asset.localhost; font-src 'self' data:; connect-src ipc: http://ipc.localhost; media-src 'self' data: blob:"
+      "csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: asset: http://asset.localhost http://127.0.0.1:*; font-src 'self' data:; connect-src ipc: http://ipc.localhost; media-src 'self' data: blob: http://127.0.0.1:*"
    }
  },
  "bundle": {
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue'
-import { Music2, Pause, Play, Plus, Repeat, Repeat1, Shuffle, SkipBack, SkipForward, Trash2, X } from '@lucide/vue'
+import { ListMusic, Music2, Pause, Play, Repeat, Repeat1, Shuffle, SkipBack, SkipForward, Trash2, X } from '@lucide/vue'
 import { useFeiniuStore } from '@/stores/feiniuStore'
 import ScrubBar from '@/components/common/ScrubBar.vue'
 import SegmentedNav from '@/components/common/SegmentedNav.vue'
@@ -210,10 +210,11 @@ function toggleAt(index: number) {
                  type="button"
                  class="text-muted-foreground transition-colors hover:text-foreground"
                  :class="{ 'text-foreground': store.nowPlayingTab === 'queue' }"
-                  aria-label="播放队列"
+                  :aria-label="`播放队列（${store.queue.length}）`"
                  :title="`播放队列（${store.queue.length}）`"
                  @click="store.nowPlayingTab = 'queue'"
                >
-                  <Plus class="size-4" />
+                  <ListMusic class="size-4" />
                </button>
              </div>
            </div>
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, ref, watch } from 'vue'
+import { computed, onMounted, ref, watch } from 'vue'
 import { toast } from 'vue-sonner'
 import {
  Disc3,
@@ -17,13 +17,116 @@ import {
  VolumeX
 } from '@lucide/vue'
 import { useFeiniuStore } from '@/stores/feiniuStore'
 import { createLogger } from '@/lib/logger'
 import ScrubBar from '@/components/common/ScrubBar.vue'
-import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
+import { Popover, PopoverAnchor, PopoverContent } from '@/components/ui/popover'
 const store = useFeiniuStore()
 const logger = createLogger('music-widget')
 const open = ref(false)
 /** 悬停多久后打开播放控制窗 */
 const HOVER_OPEN_DELAY = 300
 /** 弹层是否由悬停打开：据此决定鼠标移出时是否自动关闭（点击打开则不自动关） */
 let hoverOpened = false
 let hoverTimer: ReturnType<typeof setTimeout> | null = null
 let closeTimer: ReturnType<typeof setTimeout> | null = null
 /** 整库起播进行中（拉列表可能耗时，兼作重复点击保护） */
 const starting = ref(false)
 function cancelHoverTimer() {
  if (hoverTimer) {
    clearTimeout(hoverTimer)
    hoverTimer = null
  }
 }
 function cancelCloseTimer() {
  if (closeTimer) {
    clearTimeout(closeTimer)
    closeTimer = null
  }
 }
 /** 悬停 0.3s 打开控制窗（不依赖 Popover 默认的点击展开） */
 function onTriggerEnter() {
  cancelCloseTimer()
  cancelHoverTimer()
  hoverTimer = setTimeout(() => {
    hoverTimer = null
    if (open.value) return
    hoverOpened = true
    open.value = true
  }, HOVER_OPEN_DELAY)
 }
 function onTriggerLeave() {
  cancelHoverTimer()
  // 悬停打开的：给鼠标从按钮移到弹层留一点余量
  if (!open.value || !hoverOpened) return
  cancelCloseTimer()
  closeTimer = setTimeout(() => (open.value = false), 250)
 }
 function onContentEnter() {
  cancelCloseTimer()
 }
 function onContentLeave() {
  if (!hoverOpened) return
  cancelCloseTimer()
  closeTimer = setTimeout(() => (open.value = false), 180)
 }
 watch(open, (v) => {
  if (v) return
  cancelCloseTimer()
  cancelHoverTimer()
  hoverOpened = false
 })
 /** 点击标题：打开播放控制窗（点击打开的弹层不随鼠标移出自动关闭） */
 function onTitleClick() {
  cancelHoverTimer()
  cancelCloseTimer()
  hoverOpened = false
  open.value = true
 }
 /**
 * 点击**音乐图标**：播放 / 暂停。
 * - 有播放上下文（队列非空）→ 播放 / 暂停；
 * - 完全空载 → 依次尝试飞牛曲库**全部列表** → 本地曲库；两者皆空则不做任何反应。
 */
 async function onIconClick() {
  if (store.nowPlaying || store.queue.length) {
    store.toggle()
    return
  }
  if (starting.value) return
  starting.value = true
  try {
    try {
      await store.loadAllTracks()
    } catch (e) {
      // 未登录 / 网络不通：按「飞牛曲库为空」处理，继续尝试本地
      logger.error(`加载飞牛曲库失败: ${e}`)
    }
    if (store.tracks.length) {
      store.playQueue(store.tracks, 0)
      return
    }
    try {
      await store.scanLocal()
    } catch (e) {
      logger.error(`扫描本地曲库失败: ${e}`)
    }
    if (store.localTracks.length) store.playQueue(store.localTracks, 0)
  } finally {
    starting.value = false
  }
 }
 const coverUrl = computed(() => {
  const t = store.nowPlaying
  if (!t) return ''
@@ -84,44 +187,81 @@ watch(
    store.clearPlayError()
  }
 )
 // 应用启动即初始化音乐 store（幂等）：恢复播放列表/播放进度并预载上次在播的曲目。
 // 这样标题栏控件不必等用户先进「音乐库」页，也能显示并续播上次的歌。
 onMounted(() => {
  store.init().catch((e) => logger.error(`音乐初始化失败: ${e}`))
 })
 </script>
 <template>
  <Popover v-model:open="open">
-    <PopoverTrigger as-child>
+    <PopoverAnchor as-child>
-      <!-- 音乐栏：唱片图标 + 歌名（未播放过时只显示图标） -->
+      <!-- 音乐栏：图标 = 播放/暂停（悬停有遮罩），标题 = 打开控制窗；
-      <button
+           悬停 0.3s 也会打开控制窗。容器本身不响应点击，避免与图标语义冲突 -->
-        type="button"
+      <div
-        class="mr-2 flex h-7 max-w-[210px] items-center gap-2 rounded-md px-1.5 text-left transition-colors hover:bg-secondary/60"
+        class="mr-2 flex h-7 max-w-[210px] items-center gap-2 rounded-md px-1.5 transition-colors hover:bg-secondary/60"
-        :title="hasTrack ? `${title}${subtitle ? ' · ' + subtitle : ''}` : '未在播放'"
+        @mouseenter="onTriggerEnter"
-        :aria-label="hasTrack ? `音乐控制：${title}` : '音乐控制'"
+        @mouseleave="onTriggerLeave"
        @mousedown.stop
      >
-        <span
+        <!-- 唱片图标：点击开始/暂停 -->
-          class="disc flex size-5 shrink-0 items-center justify-center overflow-hidden rounded-full"
+        <button
-          :class="{ 'is-playing': store.playing }"
+          type="button"
          class="group/icon relative flex size-5 shrink-0 cursor-pointer items-center justify-center overflow-hidden rounded-full"
          :aria-label="store.playing ? '暂停' : '播放'"
          @click.stop="onIconClick"
        >
          <!-- 旋转动画只作用于这一层，否则遮罩图标会被带着一起转 -->
          <span
            class="disc flex size-5 items-center justify-center rounded-full ring-1 ring-border/50"
            :class="{ 'is-playing': store.playing && !starting }"
          >
            <span
              v-if="starting"
              class="size-3 animate-spin rounded-full border-2 border-current border-t-transparent text-muted-foreground"
            />
            <img
-            v-if="coverUrl && !coverFailed"
+              v-else-if="coverUrl && !coverFailed"
              :src="coverUrl"
-            class="size-full object-cover"
+              class="size-full rounded-full object-cover"
              alt=""
              referrerpolicy="no-referrer"
              @error="coverFailed = true"
            />
            <Disc3 v-else class="size-4 text-muted-foreground" />
          </span>
-        <span v-if="hasTrack" class="min-w-0 flex-1 truncate text-xs text-foreground/90">
+          <!-- 播放态遮罩：悬停图标时浮现当前可执行的操作 -->
-          {{ title }}
+          <span
            v-if="!starting"
            class="absolute inset-0 hidden items-center justify-center bg-foreground/50 text-primary-foreground group-hover/icon:flex"
          >
            <Pause v-if="store.playing" class="size-3" />
            <Play v-else class="size-3 translate-x-px" />
          </span>
        </button>
-    </PopoverTrigger>
+
        <!-- 标题：点击打开播放控制窗 -->
        <button
          v-if="hasTrack"
          type="button"
          class="min-w-0 flex-1 cursor-pointer truncate text-left text-xs text-foreground/90"
          :aria-label="`打开播放控制：${title}`"
          @click.stop="onTitleClick"
        >
          {{ title }}
        </button>
      </div>
    </PopoverAnchor>
    <!-- 方形播放控制窗 -->
    <PopoverContent
      align="end"
      :side-offset="8"
      class="w-[300px] p-3"
      @mouseenter="onContentEnter"
      @mouseleave="onContentLeave"
      @mousedown.stop
    >
      <div class="flex flex-col items-center gap-3">
@@ -254,7 +254,18 @@ export const commands = {
 	musicStopBridge: () => __TAURI_INVOKE<null>("music_stop_bridge"),
 	/**  读取音乐模块设置 */
 	musicGetSettings: () => __TAURI_INVOKE<MusicSettings>("music_get_settings"),
-	/**  保存音乐模块设置（立即生效） */
+	/**
 	 *  保存音乐模块设置（立即生效）
 	 * 
 	 *  飞牛音乐**连接相关字段一律以磁盘为准**，不接受前端传值：
 	 *  连接列表 / 激活连接 / 旧版单连接字段只由 `feiniu_save_connection`、
 	 *  `feiniu_activate_connection`、`feiniu_delete_connection`、`feiniu_login`
 	 *  等专用命令维护。
 	 * 
 	 *  原因：前端 `musicStore` 只在 init 时读一次整份设置并长期复用快照，
 	 *  若允许它整份回写，删除连接后任意一次设置保存（哪怕是切页触发的）
 	 *  都会把已删除的连接从旧快照里写回来。
 	 */
 	musicSaveSettings: (settings: MusicSettings) => __TAURI_INVOKE<null>("music_save_settings", { settings }),
 	/**  禁用指定窗口（按 label 查找）的显示/隐藏过渡动画，消除覆盖层出现/消失时的缩放动画 */
 	screenshotDisableTransitions: (label: string) => __TAURI_INVOKE<null>("screenshot_disable_transitions", { label }),
@@ -344,6 +355,158 @@ export const commands = {
 	screenshotLoadCache: (path: string) => __TAURI_INVOKE<string>("screenshot_load_cache", { path }),
 	/**  删除历史缓存文件（历史项移除/清空时调用，静默忽略不存在文件） */
 	screenshotDeleteCache: (path: string) => __TAURI_INVOKE<null>("screenshot_delete_cache", { path }),
 	/**  读取翻译设置 */
 	translateGetSettings: () => __TAURI_INVOKE<TranslateSettings>("translate_get_settings"),
 	/**
 	 *  保存翻译设置。
 	 * 
 	 *  保存后立即重新应用全局快捷键：快捷键改动若不能即时生效，用户会以为「设置没保存」，
 	 *  而重新注册本身是幂等的（内部先注销旧的）。快捷键注册失败**不当作保存失败**——
 	 *  设置已经落盘了，把失败原因作为返回的错误信息告知即可。
 	 */
 	translateSaveSettings: (settings: TranslateSettings) => __TAURI_INVOKE<null>("translate_save_settings", { settings }),
 	/**  按当前设置重新注册全局快捷键（设置页改动后或启动时调用） */
 	translateApplyShortcuts: () => __TAURI_INVOKE<null>("translate_apply_shortcuts"),
 	/**  列出引擎实例（含密钥状态与可用性） */
 	translateEnginesList: () => __TAURI_INVOKE<EngineView[]>("translate_engines_list"),
 	/**
 	 *  新增或更新一个引擎实例（按 id upsert）。
 	 * 
 	 *  校验 id：它会进入凭据键（`translate-engine-<id>`），含特殊字符会让键名难以排查，
 	 *  因此限定为字母/数字/下划线/短横线。
 	 */
 	translateEngineSave: (config: TranslateEngineConfig) => __TAURI_INVOKE<null>("translate_engine_save", { config }),
 	/**  删除引擎实例（连同它在系统凭据管理器中的密钥）。 */
 	translateEngineDelete: (id: string) => __TAURI_INVOKE<null>("translate_engine_delete", { id }),
 	/**  写入引擎的 API Key（明文只在此处进入系统凭据管理器，永不回写配置文件）。 */
 	translateSecretSet: (id: string, apiKey: string) => __TAURI_INVOKE<null>("translate_secret_set", { id, apiKey }),
 	/**  清除引擎的 API Key */
 	translateSecretClear: (id: string) => __TAURI_INVOKE<null>("translate_secret_clear", { id }),
 	/**
 	 *  连通性自检：用前端传入的配置测试（**不落盘**）。
 	 * 
 	 *  与「按 id 测已保存配置」的区别：编辑草稿里的 Base URL / 模型改动还没保存时，
 	 *  按 id 测的是旧配置——用户改完地址立刻点「测试」会得到「未配置服务地址」，
 	 *  让人以为自己的输入没生效。这里直接收草稿配置，让「改完立刻测」成立；
 	 *  API Key 仍按 `config.id` 从系统凭据管理器读取（引擎需先保存过一次才能配 Key）。
 	 */
 	translateEngineTestConfig: (config: TranslateEngineConfig) => __TAURI_INVOKE<EngineTestResult>("translate_engine_test_config", { config }),
 	/**
 	 *  拉取上游模型列表（应对「上游改名」导致预设失效的自救入口）。
 	 *  免密钥源没有模型概念，返回空列表。
 	 */
 	translateEngineModels: (id: string) => __TAURI_INVOKE<string[]>("translate_engine_models", { id }),
 	/**
 	 *  执行一次翻译。
 	 * 
 	 *  错误以结构化的 [`TranslateError`] 返回，前端按 `kind` 分支给出不同提示
 	 *  （改 Key / 查网络 / 稍后重试是三件不同的事）。
 	 */
 	translateRun: (params: TranslateRunParams) => __TAURI_INVOKE<TranslateResult>("translate_run", { params }),
 	/**
 	 *  把文本写入系统剪贴板（供主面板与取词悬浮窗复制译文）。
 	 *  写入会登记进剪贴板抑制表，因此不会在剪贴板历史里留下一条「自己复制自己」的记录。
 	 */
 	translateCopyText: (text: string) => __TAURI_INVOKE<null>("translate_copy_text", { text }),
 	/**
 	 *  预览取词悬浮窗：用固定样例文本走一遍完整链路（窗口定位、非激活显示、翻译）。
 	 * 
 	 *  为什么不提供「测试取词」按钮：从应用内触发取词必然失败——前台窗口是本应用自己，
 	 *  Ctrl+C 会落到一个没有选区的窗口上。要验证取词只能去别的应用里按快捷键。
 	 */
 	translatePreviewPopup: () => __TAURI_INVOKE<void>("translate_preview_popup"),
 	/**  悬浮窗挂载完成（仅兜底创建路径真正显示） */
 	translatePopupReady: () => __TAURI_INVOKE<void>("translate_popup_ready"),
 	/**  隐藏悬浮窗 */
 	translatePopupHide: () => __TAURI_INVOKE<void>("translate_popup_hide"),
 	/**
 	 *  弹窗编辑模式开关（原文编辑框 / 译文选中复制需要键盘焦点）。
 	 * 
 	 *  弹窗平时是 NOACTIVATE 的（不抢焦点、收不到键盘事件）；用户点击原文编辑区时
 	 *  前端请求 `enable=true`，临时移除 NOACTIVATE 并把弹窗推到前台。隐藏与下次显示
 	 *  时由后端自动恢复，不依赖前端记得关。
 	 */
 	translatePopupEditMode: (enable: boolean) => __TAURI_INVOKE<null>("translate_popup_edit_mode", { enable }),
 	/**
 	 *  钉住弹窗：钉住后点击外部与长时间停留都不再自动收起，只能手动关闭。
 	 *  弹窗收起时后端自动复位钉住状态。
 	 */
 	translatePopupSetPinned: (pinned: boolean) => __TAURI_INVOKE<void>("translate_popup_set_pinned", { pinned }),
 	/**
 	 *  记住划词悬浮窗里选的语言（源 / 目标）。
 	 * 
 	 *  弹窗是独立窗口且**收不到键盘事件**（非激活窗口不持有焦点），所有交互只能用鼠标，
 	 *  因此语言切换做成了循环按钮而不是下拉；切换结果必须落盘，否则用户每次划词都要重选一遍
 	 *  ——对「MyMemory 必须显式源语言」这类源来说，等于每次都得手动指定。
 	 * 
 	 *  刻意不重新注册快捷键：这里只改弹窗外观相关的字段，走一遍快捷键注册是白费功夫，
 	 *  还可能在注册失败时把一个无关的错误抛给前端。
 	 */
 	translatePopupPrefsSet: (sourceLang: string, targetLang: string) => __TAURI_INVOKE<null>("translate_popup_prefs_set", { sourceLang, targetLang }),
 	/**
 	 *  按内容自适应悬浮窗尺寸（前端测高后调用）。
 	 * 
 	 *  返回前端根节点应使用的 max-height（逻辑像素，来自工作区而非窗口自身——
 	 *  用 100vh 会形成收缩反馈循环，见 `popup::resize` 的注释）；0 表示不限制。
 	 */
 	translatePopupResize: (width: number | null, height: number | null) => __TAURI_INVOKE<number | null>("translate_popup_resize", { width, height }),
 	/**
 	 *  翻译一个已框选的屏幕区域。
 	 * 
 	 *  由截图覆盖层的「翻译」按钮调用（选区确认后）。流程：
 	 *  本地模式 → 裁剪 → 本地 OCR → 识别文本交给悬浮窗（弹窗自己走翻译引擎，语言表在前端）；
 	 *  视觉模式 → 裁剪 → 图像直接交给支持图像输入的模型，识别与翻译一步完成。
 	 * 
 	 *  识别/翻译失败**也弹窗**：用户视线就在选区那里，失败原因出现在视线里
 	 *  比回到主界面看 toast 有用得多。OCR 在阻塞线程池执行（WinRT 的 `get()` 会阻塞）。
 	 */
 	translateScreenshotRegion: (x: number, y: number, w: number, h: number, toLabel: string | null) => __TAURI_INVOKE<ScreenshotOutcome>("translate_screenshot_region", { x, y, w, h, toLabel }),
 	/**
 	 *  列出系统可用的 OCR 语言（设置页据此提示语言包缺失）。
 	 * 
 	 *  **必须带超时**：`OcrEngine.AvailableRecognizerLanguages` 在部分机器上会卡住不返回
 	 *  （WinRT 激活失败时既不成功也不报错）。直接在阻塞线程池上等它，设置页的按钮就会
 	 *  永远转圈——用户只能重启应用。这里改为在**独立线程**上执行并用 `recv_timeout` 兜底：
 	 *  超时就当失败，让前端显示可重试的错误，而不是把一个线程永远挂在 WinRT 里。
 	 */
 	translateOcrLanguages: () => __TAURI_INVOKE<string[]>("translate_ocr_languages"),
 	/**  分页列出历史（按时间倒序） */
 	translateHistoryList: (offset: number | null, limit: number | null, query: string | null, favoritedOnly: boolean | null) => __TAURI_INVOKE<HistoryItem[]>("translate_history_list", { offset, limit, query, favoritedOnly }),
 	translateHistoryDelete: (id: number) => __TAURI_INVOKE<null>("translate_history_delete", { id }),
 	/**  清空全部历史（含收藏）。破坏性操作，前端需二次确认后调用。 */
 	translateHistoryClear: () => __TAURI_INVOKE<null>("translate_history_clear"),
 	translateHistorySetFavorited: (id: number, favorited: boolean) => __TAURI_INVOKE<null>("translate_history_set_favorited", { id, favorited }),
 	/**
 	 *  启动一次流式翻译，返回 requestId；增量与结果经事件下发。
 	 * 
 	 *  与 `translate_run` 的差异（刻意为之）：
 	 *  - **降级只在「还没吐出任何内容」时发生**。降级发生在请求被拒绝的瞬间才有意义；
 	 *    一旦已经输出了一半再换引擎重译，用户只会看到内容跳变。所以这里用
 	 *    `produced` 标记首个 chunk 是否已下发：没产出且还有候选 → 静默换下一个源；
 	 *    已产出或已是最后一个候选 → 把错误交给前端。
 	 *    这一条正是「MyMemory 需要显式源语言」这类配置类失败能在划词场景自动落到
 	 *    DeepSeek 上的原因。
 	 *  - **不透传 thinking**：翻译场景要低延迟，流式下更是如此。
 	 * 
 	 *  **requestId 由前端在发请求前生成并经 `request_id` 参数传入**：本命令要等翻译
 	 *  结束才返回，chunk/done 事件全部先于 Promise 到达；若前端等返回值才知道
 	 *  requestId，所有事件都会因对不上号被过滤（表现为「历史里有译文、界面空白」）。
 	 *  该参数为空时（旧调用方）回退到本地生成，行为兼容。
 	 * 
 	 *  停止：`translate_abort(requestId)` 置位停止标志 → 命令层放弃转发并 drop 引擎 future
 	 *  → HTTP 流随之取消（而不是等下一块数据到来才发现被放弃）。
 	 */
 	translateStreamStart: (params: TranslateRunParams, requestId: string | null) => __TAURI_INVOKE<string>("translate_stream_start", { params, requestId }),
 	/**  停止一次流式请求（requestId 不存在时静默成功） */
 	translateAbort: (requestId: string) => __TAURI_INVOKE<void>("translate_abort", { requestId }),
 	/**
 	 *  译文回填：把译文写入剪贴板并模拟 Ctrl+V 粘贴回原窗口，替换原选区。
 	 * 
 	 *  只对划词来源有意义——剪贴板/截图来源没有「原处」可回填。
 	 *  能成立的前提是**悬浮窗从不抢焦点**（非激活窗口），因此原窗口的键盘焦点与选区
 	 *  在翻译期间一直保持原样。回填前校验原窗口仍然存活，避免粘贴进毫不相干的窗口。
 	 */
 	translatePasteBack: (text: string, hwnd: number) => __TAURI_INVOKE<null>("translate_paste_back", { text, hwnd }),
 };
 /* Types */
@@ -537,6 +700,64 @@ export type DuplicateKind =
 /**  磁盘文件已存在 */
 "fileExists";
 /**
 *  引擎连通性自检结果。
 * 
 *  与其它命令不同，这里**失败也返回 Ok**：测试失败是「数据」而不是「命令异常」，
 *  前端要显示具体原因，不该走 try/catch 分支。
 */
 export type EngineTestResult = {
 	ok: boolean,
 	latencyMs: number,
 	message: string,
 	/**  失败时的错误分类（成功时为 None） */
 	errorKind: ErrorKind | null,
 	/**  上游原始响应片段（已截断） */
 	detail: string | null,
 };
 /**
 *  引擎实例的前端视图：配置 + 派生状态（密钥是否已配、是否可用）。
 * 
 *  拆成「config + 派生」而不是直接回传配置，是为了让前端保存时能原样回传
 *  `view.config`，不必自己去拼装结构，也不会误把派生字段写回配置。
 */
 export type EngineView = {
 	config: TranslateEngineConfig,
 	/**  是否已在系统凭据管理器中配置密钥 */
 	hasApiKey: boolean,
 	/**  密钥掩码（未配置时为空串） */
 	apiKeyMasked: string,
 	/**  是否已具备发起翻译的完整配置 */
 	ready: boolean,
 	/**  不可用原因（ready 为 true 时为空） */
 	issue: string | null,
 };
 /**
 *  错误分类。区分它们的意义在于**前端能给出可操作的提示**：
 *  `Auth` 要用户去改 Key，`Network` 要用户查网络/代理，`RateLimit` 只需等待。
 */
 export type ErrorKind = 
 /**  配置缺失或不合法（未填 Base URL、模型名无效等） */
 "config" | 
 /**  认证失败 / 无权限 / 额度耗尽 */
 "auth" | 
 /**  被限流 */
 "rateLimit" | 
 /**  网络不可达（含代理问题） */
 "network" | 
 /**  超时 */
 "timeout" | 
 /**  响应无法解析（上游改了格式） */
 "parse" | 
 /**  不支持的引擎类型或语言对 */
 "unsupported" | 
 /**  输入为空（取词失败或用户未输入） */
 "empty" | 
 /**  被风控/验证码拦截（免费源常见） */
 "captcha" | "unknown";
 /**  已存在的任务信息（用于前端展示） */
 export type ExistingTaskInfo = {
 	id: string,
@@ -567,6 +788,11 @@ export type FeiniuConnection = {
 	insecure: boolean,
 	/**  fnconnect 连接的 fnId（如 fnos.net/<id> 或裸 id） */
 	fnId?: string,
 	/**
 	 *  是否经由 FnConnect 中继链路（`<fnId>.fnos.net`）。
 	 *  中继要求所有请求携带 `Cookie: mode=relay`，否则网关 302 回登录页。
 	 */
 	relay?: boolean,
 };
 export type FileEntry = {
@@ -585,12 +811,36 @@ export type FileRecord = {
 	isDir: boolean,
 };
 /**  一条历史记录 */
 export type HistoryItem = {
 	id: number,
 	/**  毫秒时间戳 */
 	ts: number,
 	fromLang: string,
 	toLang: string,
 	engineId: string,
 	engineName: string,
 	sourceText: string,
 	resultText: string,
 	/**  来源："manual" | "selection" | "clipboard" | "screenshot" | "preview" */
 	via: string,
 	favorited: boolean,
 	latencyMs: number,
 };
 /**  历史查询结果（含总数，用于分页） */
 export type HistoryPage = {
 	items: ClipboardItem[],
 	total: number,
 };
 /**  翻译历史设置（P2 生效）。 */
 export type HistorySettings = {
 	enabled?: boolean,
 	/**  保留条数上限（超出按时间淘汰） */
 	maxItems?: number,
 };
 /**  索引状态（返回给前端） */
 export type IndexStats = {
 	total: number,
@@ -623,6 +873,13 @@ export type MusicEnvStatus = {
 	musicdlInstalled: boolean,
 	/**  musicdl 版本 */
 	musicdlVersion: string | null,
 	/**  本应用锁定的 musicdl 版本（`MUSICDL_VERSION`）：是否过期、更新到哪个版本都以它为准 */
 	musicdlExpected: string,
 	/**
 	 *  已装 musicdl 是否与锁定版本不一致。
 	 *  未安装时恒为 false（那是「安装」引导的事，不是「更新」）。
 	 */
 	musicdlOutdated: boolean,
 	/**  FFmpeg 是否可用（部分音源需要，非必需） */
 	ffmpeg: string | null,
 	/**  桥接进程是否在运行 */
@@ -651,6 +908,11 @@ export type MusicSettings = {
 	selectQualityOnDownload: boolean,
 	/**  下载时默认音质："" 表示最高；否则为搜索音质档位 label（如 "无损"、"320K"） */
 	defaultDownloadQuality: string,
 	/**
 	 *  QQ 音乐 Cookie（可选）：用于解析需要登录的歌单（含自己的隐私歌单）与 VIP 音质。
 	 *  传给 musicdl 的 default_search/parse/download_cookies；空=游客身份。
 	 */
 	qqCookie?: string,
 	/**  飞牛音乐(NAS)连接：服务器地址（如 http://192.168.1.10:5666，空=未配置） */
 	feiniuBaseUrl?: string,
 	/**  飞牛音乐登录 token（登录成功后保存） */
@@ -661,7 +923,7 @@ export type MusicSettings = {
 	feiniuDeviceId?: string,
 	/**  飞牛音乐访问安全码（可选；仅需访问码的库才填，LAN 通常为空） */
 	feiniuAccessCode?: string,
-	/**  飞牛音乐连接列表（多连接：本地 / frp / 预留 fnconnect） */
+	/**  飞牛音乐连接列表（多连接：局域网 / FnConnect） */
 	feiniuConnections?: FeiniuConnection[],
 	/**  当前激活连接的 id */
 	feiniuActiveId?: string,
@@ -679,6 +941,27 @@ export type MusicSettings = {
 	feiniuAutoUpload?: boolean,
 };
 /**  划词结果悬浮窗外观（P1 生效）。 */
 export type PopupSettings = {
 	/**  正文字号（逻辑像素） */
 	fontSize?: number,
 	/**  不透明度百分比（100 = 不透明） */
 	opacity?: number,
 	/**  优先落位："bottom-right" | "bottom-left" | "top-right" | "top-left" */
 	positionPreference?: string,
 	/**  是否默认展开原文 */
 	showOriginal?: boolean,
 	/**
 	 *  划词弹窗的源语言（"auto" 表示交给引擎判断）。
 	 * 
 	 *  存在的理由：MyMemory 这类源**不支持自动检测**，而划词场景天然不知道源语言。
 	 *  与其让弹窗永远传 auto、把这类源判成「不可用」，不如让用户在这里定一次并记住。
 	 */
 	sourceLang?: string,
 	/**  划词弹窗的目标语言。空串表示跟随全局「默认目标语言」。 */
 	targetLang?: string,
 };
 /**  进程信息（返回给前端） */
 export type ProcessInfo = {
 	id: string,
@@ -700,6 +983,21 @@ export type ProfileMeta = {
 	size?: number | null,
 };
 /**
 *  提示词模板。`{target}` 为占位符，翻译时替换为目标语言的自然语言全称
 *  （用全称而非语言码，模型遵循度明显更高）。
 */
 export type PromptTemplates = {
 	/**  纯翻译（默认模式） */
 	translate?: string,
 	/**  润色（P3） */
 	polish?: string,
 	/**  解释（P3） */
 	explain?: string,
 	/**  总结（P3） */
 	summarize?: string,
 };
 export type ProxySettings = {
 	mixedPort?: number,
 	externalController?: string,
@@ -770,6 +1068,26 @@ export type ScreenRect = {
 	height: number,
 };
 /**  截图翻译的结果摘要（展示交给悬浮窗，这里供调用方与历史记录使用） */
 export type ScreenshotOutcome = {
 	/**  本地 OCR 的识别文本（视觉直译模式为空） */
 	ocrText: string,
 	/**  OCR 使用的语言（BCP-47，本地模式） */
 	ocrLang: string,
 	engineName: string,
 	translated: boolean,
 };
 /**  截图翻译设置。 */
 export type ScreenshotSettings = {
 	/**  识别方式："windows"（Windows.Media.Ocr，本地离线，默认）| "vision"（视觉模型直译） */
 	ocrMode?: string,
 	/**  OCR 语言："auto" 或 BCP-47 标签（如 en-US / zh-Hans-CN） */
 	ocrLang?: string,
 	/**  框选完成后是否自动翻译（关闭则只识别，译文由用户在悬浮窗手动触发） */
 	autoTranslate?: boolean,
 };
 /**  滚动截图区域（屏幕物理像素坐标，通常为覆盖层框选区平移到屏幕） */
 export type ScrollRegion = {
 	x: number,
@@ -790,6 +1108,37 @@ export type Segment = {
 	completed: number,
 };
 /**
 *  划词翻译设置（P1 生效；结构在 P0 即定型，避免 P2 改数据结构）。
 * 
 *  P2 重构说明：原「取词快捷键 Alt+T」「翻译剪贴板 Alt+Shift+T」已移除，
 *  统一为「翻译面板」快捷键（`panel_shortcut`）——面板打开时自动尝试读取
 *  当前划词与剪贴板首条作为候选，覆盖了原来两个入口的全部场景。
 */
 export type SelectionSettings = {
 	/**  总开关：打开翻译面板时是否尝试读取当前划词作为候选 */
 	enabled?: boolean,
 	/**  打开翻译面板的全局快捷键（默认 Ctrl+2） */
 	panelShortcut?: string,
 	/**
 	 *  取词方式：
 	 *  - "smart"（默认）：先用 UIA 直读选区，读不到再退回模拟 Ctrl+C。不碰剪贴板，
 	 *    因此不受「目标窗口提权」「Alt 仍被按住导致 Ctrl+C 变成 Alt+Ctrl+C」这两类问题影响。
 	 *  - "compat"：只用模拟 Ctrl+C（覆盖最广，但会短暂占用剪贴板）。
 	 *  - "clipboard"：不取词，面板只提供剪贴板首条作为候选。
 	 */
 	mode?: string,
 	/**  取词后是否还原剪贴板（关掉则保留选中文本） */
 	restoreClipboard?: boolean,
 	/**
 	 *  单次取词的字符数上限。超出直接拒绝并提示：划词误选整篇文档时，
 	 *  发一个几万字的请求既慢又费钱，不如让用户明确知道发生了什么。
 	 */
 	maxChars?: number,
 	/**  取词跳过的进程名黑名单（终端类 Ctrl+C 是中断信号，必须排除） */
 	blacklist?: string[],
 };
 /**  快捷位置条目 */
 export type SpecialLocation = {
 	id: string,
@@ -824,6 +1173,13 @@ export type TaskStatus =
 /**  已取消（用户取消：进度与文件已清除，仅保留记录，只能再次下载） */
 "cancelled";
 /**  Token 用量（AI 引擎返回；其余引擎为 None） */
 export type TokenUsage = {
 	promptTokens: number,
 	completionTokens: number,
 	totalTokens: number,
 };
 /**  种子信息（inspect 解析结果，供命令返回给前端做文件勾选） */
 export type TorrentInfo = {
 	/**  种子名称 */
@@ -850,6 +1206,118 @@ export type TrafficSnapshot = {
 	activeConnections: number,
 };
 /**
 *  单个翻译引擎实例的配置。
 * 
 *  「实例」而非「类型」：同一类型可以配置多份（例如官方 API 与本地 Ollama 并存），
 *  每份有自己的 id / 优先级 / 模型与参数。
 */
 export type TranslateEngineConfig = {
 	/**  实例唯一标识（同时是凭据键的一部分，创建后不建议修改） */
 	id?: string,
 	/**  展示名称 */
 	name?: string,
 	/**  引擎类型："ai"（OpenAI 兼容）| "free"（免密钥网络源）| "cloud"（需签名的云厂商，P3） */
 	kind?: string,
 	/**  预设标识："deepseek" | "openai" | "ollama" | "custom" | "libretranslate" | "mymemory" */
 	preset?: string,
 	/**  是否参与「自动」模式的候选 */
 	enabled?: boolean,
 	/**  优先级（数值越小越先尝试；自动模式下失败按序降级到下一个） */
 	priority?: number,
 	/**  API 根地址，如 https://api.deepseek.com（末尾可有可无 /，不可含 /chat/completions） */
 	baseUrl?: string,
 	/**  模型标识，如 deepseek-flash */
 	model?: string,
 	/**  采样温度（翻译建议 0.2~0.3） */
 	temperature?: number | null,
 	/**  单次请求最大输出 token */
 	maxTokens?: number,
 	/**  请求超时（毫秒） */
 	timeoutMs?: number,
 	/**  自定义 system prompt；**非空时覆盖模式模板**（留空表示用全局模板） */
 	systemPrompt?: string,
 	/**
 	 *  额外请求体字段的 JSON 文本（用于 thinking / enable_thinking 这类非标准参数）；
 	 *  用文本而非结构化字段：一是前端直接给文本域，二是避免把任意 JSON 塞进类型绑定。
 	 */
 	extraBody?: string | null,
 	/**
 	 *  是否支持图像输入（截图翻译的「视觉直译」模式只发给勾选了此项的引擎）。
 	 *  默认 false：多模态模型与文本模型的计费和端点约束不同，宁可让用户显式勾选。
 	 */
 	supportsVision?: boolean,
 };
 /**  结构化错误：作为 Tauri 命令的 error 类型返回，前端按 `kind` 分支处理。 */
 export type TranslateError = {
 	kind: ErrorKind,
 	message: string,
 	/**  上游原始响应片段（已截断），用于排查；不含密钥 */
 	detail: string | null,
 };
 /**  翻译结果 */
 export type TranslateResult = {
 	/**  译文 */
 	text: string,
 	/**  检测到的源语言（免费源会上报；AI 引擎为显式指定值或 None） */
 	detected: string | null,
 	/**  实际使用的引擎实例 id */
 	engineId: string,
 	/**  实际使用的引擎展示名（自动降级时前端要能看出「是谁答的」） */
 	engineName: string,
 	/**  耗时（毫秒） */
 	latencyMs: number,
 	usage: TokenUsage | null,
 };
 /**  单次翻译请求参数。 */
 export type TranslateRunParams = {
 	text: string,
 	/**  源语言代码，"auto" 或省略表示自动检测 */
 	from?: string | null,
 	/**  目标语言代码（如 zh-Hans） */
 	to?: string | null,
 	/**  目标语言自然语言全称（如 简体中文），提示词用 */
 	toLabel?: string | null,
 	/**  源语言自然语言全称，仅显式指定源语言时有意义 */
 	fromLabel?: string | null,
 	/**  指定引擎实例 id；省略或 "auto" 表示按优先级自动（含降级） */
 	engineId?: string | null,
 	/**  模式："translate"（默认）| "polish" | "explain" | "summarize" */
 	mode?: string | null,
 	/**  记入历史时的来源："manual"（主面板）| "selection" | "clipboard" | "screenshot" */
 	via?: string | null,
 	/**  是否写入历史。默认 true；**多引擎对比与预览必须传 false**。 */
 	record?: boolean | null,
 };
 /**  翻译模块设置根结构。 */
 export type TranslateSettings = {
 	/**  结构版本号（用于后续迁移判断） */
 	version?: number,
 	/**  默认目标语言（内部代码，如 zh-Hans） */
 	defaultTarget?: string,
 	/**  默认引擎实例 id（"auto" 表示按优先级自动降级） */
 	defaultEngineId?: string,
 	/**  自动模式下的失败降级开关 */
 	autoFallback?: boolean,
 	/**
 	 *  翻译请求是否走代理模块（mihomo mixed 端口）。
 	 *  **默认关闭**：自建 LibreTranslate 在境内、MyMemory 与 DeepSeek 均可直连，
 	 *  不需要代理；仅当翻译服务部署在境外或直连被拦截时由用户显式打开。
 	 */
 	useProxy?: boolean,
 	/**  引擎实例列表 */
 	engines?: TranslateEngineConfig[],
 	selection?: SelectionSettings,
 	popup?: PopupSettings,
 	screenshot?: ScreenshotSettings,
 	history?: HistorySettings,
 	promptTemplates?: PromptTemplates,
 };
 /**  release 中的一个资产 */
 export type UpdateAsset = {
 	name: string,
@@ -16,6 +16,8 @@ export const WINDOWS = {
  screenshotScroll: 'screenshot-scroll',
  /** 单文件一次性下载窗口前缀，实际 label = `${downloadWindow}-<taskId>` */
  downloadWindow: 'download-window',
  /** 取词翻译悬浮窗（非激活显示，由 Rust 预创建） */
  translatePopup: 'translate-popup',
 } as const
 /** Tauri 事件名（前端 emit / listen 与 Rust constants::events 对应） */
@@ -64,6 +66,13 @@ export const EVENTS = {
  screenshotEditorLoad: 'screenshot-editor-load',
  // 内核安装进度
  kernelInstallProgress: 'kernel-install-progress',
  // 翻译：取词悬浮窗显示（负载见 Rust translate::popup::PopupPayload）/ 隐藏
  translatePopupShow: 'translate-popup-show',
  translatePopupHide: 'translate-popup-hide',
  // 翻译：流式输出（失败经 start 的 Promise reject，不走事件）
  translateStreamChunk: 'translate-stream-chunk',
  translateStreamDone: 'translate-stream-done',
  translateStreamError: 'translate-stream-error',
  // 后端自动切换节点完成（后台执行，刷新节点列表并提示）
  proxyAutoSwitch: 'proxy-auto-switch',
  // 应用更新进度
@@ -0,0 +1,169 @@
 /**
 * 翻译模块的后端调用封装。
 *
 * 单独抽一层的原因：**取词悬浮窗是独立窗口，不加载 Pinia**（`main.ts` 的
 * `standaloneWindowApps` 分支只 createApp，不装 store）。要让主面板与悬浮窗共用同一套
 * 调用与错误规整逻辑，就不能把它写在 store 里。
 *
 * 调用方式仍用原生 `invoke` 而非 `@/lib/bindings` 的 `commands.*`：specta 绑定只在
 * debug 构建启动时生成，新增命令在首次 `tauri dev` 之前不存在于 bindings.ts。
 * 全部收敛在这一个文件与 translateStore 里，将来替换只需改这两处。
 */
 import { invoke } from '@tauri-apps/api/core'
 import { listen, type UnlistenFn } from '@tauri-apps/api/event'
 import { EVENTS } from '@/lib/constants'
 import type {
  EngineView,
  TranslateError,
  TranslateErrorKind,
  TranslateResult,
  TranslateRunParams
 } from '@/types/translate'
 /**
 * 把任意异常规整为 TranslateError。
 *
 * 后端有两种错误形态：翻译命令返回结构化对象 `{ kind, message, detail }`，
 * 其余命令返回字符串 —— 这里一并兼容，调用方只需处理一种形状。
 */
 export function normalizeTranslateError(e: unknown): TranslateError {
  if (e && typeof e === 'object') {
    const o = e as Record<string, unknown>
    if (typeof o.kind === 'string' && typeof o.message === 'string') {
      return {
        kind: o.kind as TranslateErrorKind,
        message: o.message,
        detail: typeof o.detail === 'string' ? o.detail : null
      }
    }
    try {
      return { kind: 'unknown', message: JSON.stringify(o), detail: null }
    } catch {
      /* 循环引用等异常，落到下面的兜底 */
    }
  }
  return { kind: 'unknown', message: String(e ?? '未知错误'), detail: null }
 }
 /** 执行一次翻译（含后端的自动降级） */
 export function runTranslate(params: TranslateRunParams): Promise<TranslateResult> {
  return invoke<TranslateResult>('translate_run', { params })
 }
 /** 引擎实例列表（含密钥状态、可用性、代理状态） */
 export function listEngines(): Promise<EngineView[]> {
  return invoke<EngineView[]>('translate_engines_list')
 }
 /**
 * 写文本到系统剪贴板。
 *
 * 走 Rust 而不是 `navigator.clipboard`：悬浮窗是非激活窗口，浏览器会以
 * 「无用户激活」为由拒绝写入；走 Rust 还能顺带把这次写入登记进剪贴板抑制表，
 * 不在剪贴板历史里留下一条自己复制给自己的记录。
 */
 export function copyToClipboard(text: string): Promise<void> {
  return invoke('translate_copy_text', { text })
 }
 // ===== 流式输出 =====
 /**
 * 流式事件的负载形状。
 *
 * 与 Rust `translate::engines::StreamEvent` 一一对应：该枚举用 `#[serde(tag = "type")]`
 * 序列化，因此 `requestId` 与 `delta` / `result` 是**平级字段**，而不是嵌在
 * `{"Chunk": {...}}` 里。曾经因为两边形状不一致，所有事件都被 `requestId` 过滤掉，
 * 表现为「历史里有译文、界面上一片空白」——改任一处都要同时看另一处。
 */
 interface StreamEventPayload {
  requestId: string
  type?: 'chunk' | 'done' | 'error'
  delta?: string
  result?: TranslateResult
  error?: TranslateError
 }
 export interface StreamHandlers {
  onChunk?: (delta: string) => void
  onDone?: (result: TranslateResult) => void
  onError?: (error: TranslateError) => void
 }
 /**
 * 一次流式翻译的会话。
 *
 * 三条事件（chunk/done/error）都带 requestId，监听器按它过滤——弹窗是常驻窗口，
 * 用户连续划词时前一次的残留事件不能串进新请求。
 *
 * 「统一走流式入口」的含义：不支持流式的引擎（免密钥源、DeepL）在后端走
 * 同步兜底并发整条 Done，前端无需关心引擎能力差异。
 */
 export class StreamSession {
  private unlisten: UnlistenFn[] = []
  private requestId: string | null = null
  private finished = false
  /** 客户端生成 requestId 用的自增序号（配合时间戳保证同毫秒内不重复） */
  private static seq = 0
  constructor(private handlers: StreamHandlers) {}
  /** 注册事件监听。必须在首次 start 之前调用。 */
  async init(): Promise<void> {
    this.unlisten.push(
      await listen<StreamEventPayload>(EVENTS.translateStreamChunk, e => {
        if (e.payload.requestId !== this.requestId || this.finished) return
        if (e.payload.delta) this.handlers.onChunk?.(e.payload.delta)
      })
    )
    this.unlisten.push(
      await listen<StreamEventPayload>(EVENTS.translateStreamDone, e => {
        if (e.payload.requestId !== this.requestId || this.finished) return
        this.finished = true
        if (e.payload.result) this.handlers.onDone?.(e.payload.result)
      })
    )
    // 兜底通道：命令已返回 requestId、之后才失败的情形（引擎降级失败等）。
    // 没有它，前端会永远停在「翻译中」——Promise 与事件谁先到没有保证。
    this.unlisten.push(
      await listen<StreamEventPayload>(EVENTS.translateStreamError, e => {
        if (e.payload.requestId !== this.requestId || this.finished) return
        this.finished = true
        if (e.payload.error) this.handlers.onError?.(e.payload.error)
      })
    )
  }
  /**
   * 启动一次流式翻译。启动即失败（如没有可用引擎）时走 onError。
   *
   * requestId 由**客户端在发请求之前生成**并随参数带给后端：流式命令要等翻译
   * 全部结束才返回，chunk/done 事件全部先于 Promise 到达。若等 invoke 返回才
   * 拿后端生成的 requestId，期间所有事件都因对不上号被过滤——表现为
   * 「历史里有译文、界面上一片空白」。后端仅在客户端未提供时才自行生成。
   */
  async start(params: TranslateRunParams): Promise<void> {
    this.requestId = `c${Date.now()}-${++StreamSession.seq}`
    this.finished = false
    try {
      await invoke('translate_stream_start', { params, requestId: this.requestId })
    } catch (e) {
      this.handlers.onError?.(normalizeTranslateError(e))
    }
  }
  /** 停止当前请求（后端会取消 HTTP 流）。 */
  stop(): void {
    if (this.requestId && !this.finished) {
      void invoke('translate_abort', { requestId: this.requestId }).catch(() => {})
    }
    this.finished = true
  }
  dispose(): void {
    this.stop()
    this.unlisten.forEach(fn => fn())
    this.unlisten = []
  }
 }
@@ -0,0 +1,89 @@
 /**
 * 语言表。
 *
 * 内部统一用 BCP-47 短码（`zh-Hans` / `en` / `ja`…）作为**唯一标识**，用于设置持久化、
 * 历史记录与前端状态；各翻译源自己的语言码方言（如 Google 的 `zh-CN`、Bing 的 `zh-Hans`、
 * 云厂商的 `zh`）由各自的适配器在内部映射，不向上暴露——否则上层会被迫处处判断
 * 「这个源认哪种写法」。
 *
 * `promptName` 是送给 AI 模型的自然语言全称。刻意不用语言码：模型对「繁体中文」的
 * 遵循度明显高于 `zh-Hant`，而这是零成本的改动。
 */
 export interface LanguageDef {
  /** 内部统一代码 */
  code: string
  /** 中文展示名 */
  label: string
  /** 送给模型的自然语言全称 */
  promptName: string
  /** 常用语言（下拉置顶） */
  common?: boolean
 }
 /** 自动检测的伪语言项（仅出现在源语言下拉中） */
 export const AUTO_DETECT: LanguageDef = {
  code: 'auto',
  label: '自动检测',
  promptName: ''
 }
 export const LANGUAGES: LanguageDef[] = [
  { code: 'zh-Hans', label: '简体中文', promptName: '简体中文', common: true },
  { code: 'zh-Hant', label: '繁体中文', promptName: '繁体中文', common: true },
  { code: 'en', label: '英语', promptName: '英语', common: true },
  { code: 'ja', label: '日语', promptName: '日语', common: true },
  { code: 'ko', label: '韩语', promptName: '韩语', common: true },
  { code: 'fr', label: '法语', promptName: '法语' },
  { code: 'de', label: '德语', promptName: '德语' },
  { code: 'es', label: '西班牙语', promptName: '西班牙语' },
  { code: 'pt', label: '葡萄牙语', promptName: '巴西葡萄牙语' },
  { code: 'ru', label: '俄语', promptName: '俄语' },
  { code: 'it', label: '意大利语', promptName: '意大利语' },
  { code: 'nl', label: '荷兰语', promptName: '荷兰语' },
  { code: 'pl', label: '波兰语', promptName: '波兰语' },
  { code: 'tr', label: '土耳其语', promptName: '土耳其语' },
  { code: 'ar', label: '阿拉伯语', promptName: '阿拉伯语' },
  { code: 'hi', label: '印地语', promptName: '印地语' },
  { code: 'th', label: '泰语', promptName: '泰语' },
  { code: 'vi', label: '越南语', promptName: '越南语' },
  { code: 'id', label: '印尼语', promptName: '印尼语' },
  { code: 'ms', label: '马来语', promptName: '马来语' }
 ]
 const BY_CODE = new Map<string, LanguageDef>(LANGUAGES.map(l => [l.code, l]))
 export function findLanguage(code: string | null | undefined): LanguageDef | undefined {
  if (!code) return undefined
  return BY_CODE.get(code)
 }
 /** 展示用名称（未知代码原样返回，避免出现空白） */
 export function labelOf(code: string | null | undefined): string {
  if (!code || code === 'auto') return AUTO_DETECT.label
  return BY_CODE.get(code)?.label ?? code
 }
 /**
 * 送模型的自然语言语言名。
 * 未知代码时退回语言码本身——总比留空让模型自行猜测要好。
 */
 export function promptNameOf(code: string | null | undefined): string {
  if (!code || code === 'auto') return ''
  return BY_CODE.get(code)?.promptName ?? code
 }
 /** 常用语言在前、其余按表内顺序 */
 export function orderedLanguages(includeAuto: boolean): LanguageDef[] {
  const common = LANGUAGES.filter(l => l.common)
  const rest = LANGUAGES.filter(l => !l.common)
  return includeAuto ? [AUTO_DETECT, ...common, ...rest] : [...common, ...rest]
 }
 /**
 * 推断本次请求的目标语言标签。
 * 目标语言必须显式选择（没有「自动」一说），因此仅在代码未知时退回代码本身。
 */
 export function resolveTargetLabel(code: string): string {
  return promptNameOf(code) || labelOf(code)
 }
@@ -29,16 +29,18 @@ import { useModuleTabsStore, type ModuleTab } from '@/stores/moduleTabsStore'
 * ```
 *
 * ## 工作原理
- * 1. onMounted 时注册标签到 moduleTabsStore，TitleBar 据此渲染浮动切换器
+ * 1. onMounted 时注册标签到 moduleTabsStore（**并复用该模块上次停留的 tab**），
 *    TitleBar 据此渲染浮动切换器
 * 2. 用 IntersectionObserver 监听 TabsList 可见性（rootMargin 裁剪 TitleBar 高度）
 * 3. 双向 watch 同步本地 activeTab 与 store.activeTab
 * 4. 消费搜索导航的待跳转 tab（模块尚未挂载的场景）
- * 5. onUnmounted 时清理 observer 并注销标签
+ * 5. onUnmounted 时清理 observer 并把当前 tab 记到 store（按模块）后注销标签
 *
 * ## 约束
 * - TitleBar 高度固定为 40px (h-10)，composable 内部已用 44px 裁剪（含缓冲）
 * - 一个模块同一时间只能注册一组标签（store 是单例）
 * - 模块卸载时务必让 composable 的 onUnmounted 执行（已自动处理，无需手动调用）
 * - tab 记忆只保内存、不落盘：tab 集合可能随版本变化，跨重启恢复旧值风险更大
 */
 export function useModuleTabs(
  moduleId: string,
@@ -97,10 +99,12 @@ export function useModuleTabs(
  })
  onMounted(async () => {
-    tabsStore.registerTabs(tabs, activeTab.value)
+    // 注册时带上模块 id：store 据此复用「上次停留的 tab」（模块卸载时保存）
    const restored = tabsStore.registerTabs(moduleId, tabs, activeTab.value)
    if (restored !== activeTab.value) activeTab.value = restored
    await nextTick()
    setupObserver()
-    // 搜索导航跳转：模块刚挂载，消费待跳转 tab
+    // 搜索导航跳转：模块刚挂载，消费待跳转 tab（优先级高于上次停留）
    applyPendingTab()
  })
@@ -109,7 +113,7 @@ export function useModuleTabs(
      observer.disconnect()
      observer = null
    }
-    tabsStore.unregisterTabs()
+    tabsStore.unregisterTabs(moduleId)
  })
  return tabsListRef
@@ -39,6 +39,7 @@ const standaloneWindowApps: Array<[hash: string, label: string, loader: () => Pr
  ['#screenshot-pin', '贴图窗口', () => import('./modules/screenshot/ScreenshotPin.vue')],
  ['#screenshot-scroll', '滚动截图', () => import('./modules/screenshot/ScrollControl.vue')],
  ['#download-window', '下载窗口', () => import('./modules/downloader/DownloadWindow.vue')],
  ['#translate-popup', '翻译悬浮窗', () => import('./modules/translate/TranslatePopup.vue')],
 ]
 const winHash = window.location.hash
@@ -8,7 +8,8 @@ import {
  Download,
  Command,
  Wrench,
-  Music
+  Music,
  Languages
 } from '@lucide/vue'
 /**
@@ -27,7 +28,8 @@ export const moduleIconMap: Record<string, Component> = {
  downloader: Download,
  quickpanel: Command,
  devtools: Wrench,
-  music: Music
+  music: Music,
  translate: Languages
 }
 /** 获取模块图标组件，未找到时回退到 Settings 图标 */
@@ -11,6 +11,7 @@ import { moduleConfig as quickpanel } from './quickpanel'
 import { moduleConfig as devtools } from './devtools'
 import { moduleConfig as settings } from './settings'
 import { moduleConfig as music } from './music'
 import { moduleConfig as translate } from './translate'
 const allModules: ModuleConfig[] = [
  proxy,
@@ -21,7 +22,8 @@ const allModules: ModuleConfig[] = [
  quickpanel,
  devtools,
  settings,
-  music
+  music,
  translate
 ]
 // 启动时注册所有模块
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
 import { toast } from 'vue-sonner'
 import {
  Cloud,
@@ -16,7 +16,7 @@ import {
  Search,
  Trash2
 } from '@lucide/vue'
-import { useFeiniuStore } from '@/stores/feiniuStore'
+import { useFeiniuStore, type PlayableItem } from '@/stores/feiniuStore'
 import TrackItem from './TrackItem.vue'
 import PlaylistEditorDialog from './PlaylistEditorDialog.vue'
 import { Button } from '@/components/ui/button'
@@ -46,21 +46,96 @@ const sourceNav = computed(() => [
  { value: 'playlists' as const, label: '我的歌单', icon: ListMusic, count: store.playlists.length }
 ])
-// ===== 飞牛曲库：搜索（直接绑定 store.searchKeyword，此前绑定的是孤立局部变量，导致搜索完全无效）=====
+// ===== 曲库搜索：飞牛 track/list 接口**不支持**关键字过滤（实测忽略该参数），
 // 因此搜索框只做**本地筛选**（歌名/歌手/专辑）；输入时自动补齐剩余分页，
 // 保证筛选覆盖全库而不是已加载的前几页。两个视图（飞牛/本地）共用同一个关键字。
 let searchTimer: ReturnType<typeof setTimeout> | undefined
 let searchSeq = 0
-function onSearchInput() {
+/** 全量补齐进行中：输入防抖与视图切换可能同时触发，用标志位避免并发重复翻页 */
-  clearTimeout(searchTimer)
+let fillingAll = false
-  searchTimer = setTimeout(async () => {
+/** 本组件已完成挂载初始化：此前不触发补齐，避免与 ensureTracksFresh 的首页请求并发 */
 let mountedReady = false
 /**
 * 补齐飞牛曲库的剩余分页。
 * 飞牛 `track/list` 不支持关键字过滤，搜索框只做**本地筛选**，
 * 因此必须先把剩余分页拉完，否则只能在「已加载的前几页」里找，
 * 表现为「曲库里明明有这首歌却搜不到」。
 *
 * 必须避让任何在途的分页请求：补齐是「按页追加」，而首页刷新是
 * `tracks = mapped`（整体替换）；两者交错会把刚追加的页直接抹掉，造成曲目缺口。
 */
 async function fillRemainingFeiniu() {
  if (fillingAll || !store.hasMoreTracks) return
  if (store.loading || store.refreshing || store.loadingMore) return
  fillingAll = true
  const seq = ++searchSeq
  try {
-      await store.loadTracks(1)
+    await store.loadRemainingTracks()
  } catch (e) {
    if (seq === searchSeq) toast.error(String(e))
  } finally {
    fillingAll = false
  }
  }, 400)
 }
 /**
 * 搜索框输入：仅飞牛曲库需要补齐分页（本地曲库是已全量在内存的数组，输入即筛）。
 * 两个视图共用同一个关键字，但按各自的数据来源决定是否发请求。
 */
 function onSearchInput() {
  clearTimeout(searchTimer)
  searchTimer = setTimeout(() => {
    if (view.value !== 'feiniu') return
    void fillRemainingFeiniu()
  }, 300)
 }
 const isFiltering = computed(() => !!filterKeyword.value)
 /** 关键字规范化：全角空格→半角、压缩连续空白、转小写（中文不受影响） */
 function normalizeKeyword(s: string) {
  return s
    .replace(/\u3000/g, ' ')
    .trim()
    .replace(/\s+/g, ' ')
    .toLowerCase()
 }
 const filterKeyword = computed(() => normalizeKeyword(store.searchKeyword))
 /**
 * 保证飞牛曲库的筛选覆盖全库。
 * 关键字在两个视图之间共享，所以「带着关键字从本地切回飞牛曲库」时
 * 也必须补齐分页，否则只会在已加载的前几页里筛，结果数明显偏小。
 * 挂载阶段由 onMounted 的串行链负责，此处只在挂载后响应视图 / 关键字变化。
 */
 function ensureFeiniuFilterCoverage() {
  if (!mountedReady) return
  if (view.value !== 'feiniu' || !filterKeyword.value) return
  void fillRemainingFeiniu()
 }
 watch([view, filterKeyword], ensureFeiniuFilterCoverage)
 function matchesKeyword(t: PlayableItem, kw: string) {
  // 曲库条目（PlayableItem）的字段是 title=歌名 / artistNames=歌手 / album=专辑。
  // 千万不要用 musicdl 的 songName/singers——那是「发现音乐」的结构，用错字段
  // 会导致 haystack 只剩专辑，表现为"歌名/歌手都搜不到"。
  return `${t.title ?? ''} ${t.artistNames ?? ''} ${t.album ?? ''}`.toLowerCase().includes(kw)
 }
 const filteredTracks = computed(() => {
  const kw = filterKeyword.value
  if (!kw) return store.tracks
  return store.tracks.filter((t) => matchesKeyword(t, kw))
 })
 const filteredLocalTracks = computed(() => {
  const kw = filterKeyword.value
  if (!kw) return store.localTracks
  return store.localTracks.filter((t) => matchesKeyword(t, kw))
 })
 function refreshFeiniu() {
  store.loadTracks(1).catch((e) => toast.error(String(e)))
 }
@@ -69,23 +144,66 @@ function refreshLocal() {
 }
 function playFeiniu() {
-  if (store.tracks.length) store.playQueue(store.tracks, 0)
+  // 有筛选时只播放筛选结果
  if (filteredTracks.value.length) store.playQueue(filteredTracks.value, 0)
 }
 function playLocal() {
-  if (store.localTracks.length) store.playQueue(store.localTracks, 0)
+  if (filteredLocalTracks.value.length) store.playQueue(filteredLocalTracks.value, 0)
 }
 function playActivePlaylist() {
  if (activePlaylist.value?.items.length) store.playQueue(activePlaylist.value.items, 0)
 }
-// ===== 滚动加载更多（飞牛曲库分页）=====
+// ===== 列表增量渲染 + 滚动加载更多 =====
 /**
 * 一次挂载多少行。曲库没有虚拟滚动，补齐分页后行数可达 MAX_QUEUE_TRACKS(4000)，
 * 一次性挂载 4000 个 TrackItem（每个含封面 <img> 与下拉菜单）会明显卡顿，
 * 因此改成「先渲染一屏，滚到底再追加」（与发现音乐页、播放队列同一策略）。
 */
 const LIST_STEP = 200
 const renderLimit = ref(LIST_STEP)
 /** 当前视图正在展示的完整列表 */
 const activeList = computed<PlayableItem[]>(() => {
  if (view.value === 'feiniu') return filteredTracks.value
  if (view.value === 'local') return filteredLocalTracks.value
  return activePlaylist.value?.items ?? []
 })
 const visibleFeiniu = computed(() => filteredTracks.value.slice(0, renderLimit.value))
 const visibleLocal = computed(() => filteredLocalTracks.value.slice(0, renderLimit.value))
 const visiblePlaylistItems = computed(() => (activePlaylist.value?.items ?? []).slice(0, renderLimit.value))
 /** 还有没渲染出来的行 */
 const hasMoreRows = computed(() => renderLimit.value < activeList.value.length)
 /** 实际渲染出来的行数（提示文案用） */
 const shownRows = computed(() => Math.min(renderLimit.value, activeList.value.length))
 /** 哨兵是否显示：要么还有行没渲染，要么飞牛曲库还有分页没拉 */
 const showSentinel = computed(
  () => hasMoreRows.value || (view.value === 'feiniu' && store.hasMoreTracks)
 )
 // 换视图 / 换关键字 / 换歌单时把渲染窗口收回一屏（监听放在 activePlaylistId 声明之后）
 const loadMoreRef = ref<HTMLElement | null>(null)
 let loadMoreObserver: IntersectionObserver | null = null
 onMounted(() => {
  loadMoreObserver = new IntersectionObserver(
    (entries) => {
      if (!entries.some((e) => e.isIntersecting)) return
-      store.loadMoreTracks().catch(() => {})
+      // 先把已加载的数据渲染出来，都渲染完了再向 NAS 要下一页
      if (renderLimit.value < activeList.value.length) {
        renderLimit.value += LIST_STEP
        // 哨兵节点没换位置、仍处于交叉状态时 IntersectionObserver 不会再触发，
        // 需要重新 observe 一次才能连续追加
        nextTick(() => {
          const el = loadMoreRef.value
          if (el && loadMoreObserver) {
            loadMoreObserver.unobserve(el)
            loadMoreObserver.observe(el)
          }
        })
        return
      }
      if (view.value === 'feiniu' && store.hasMoreTracks) store.loadMoreTracks().catch(() => {})
    },
    { rootMargin: '400px' }
  )
@@ -118,6 +236,11 @@ const editorOpen = ref(false)
 // 切换歌单时关闭编辑器，避免对着已切换的目标继续编辑
 watch(activePlaylistId, () => (editorOpen.value = false))
 // 换视图 / 换关键字 / 换歌单时把增量渲染窗口收回一屏，避免「切回来看到一屏旧内容」
 watch([view, filterKeyword, activePlaylistId], () => {
  renderLimit.value = LIST_STEP
 })
 // 切到歌单视图时自动选中第一个
 watch(
  [view, () => store.playlists.length],
@@ -159,9 +282,44 @@ function removePlaylist() {
  activePlaylistId.value = ''
 }
 // ===== 视图与筛选持久化：曲库页每次挂载都会重置本地状态，
 // 而"搜索结果每次都要重新输"是用户明确反馈的问题 → 存 localStorage（跨重启） =====
 const LIB_VIEW_KEY = 'thing.music.library.view'
 const LIB_FILTER_KEY = 'thing.music.library.filter'
 watch(
  () => [view.value, store.searchKeyword] as const,
  ([v, kw]) => {
    try {
      localStorage.setItem(LIB_VIEW_KEY, v)
      localStorage.setItem(LIB_FILTER_KEY, kw ?? '')
    } catch {
      /* 存储不可用时静默 */
    }
  }
 )
 onMounted(async () => {
  try {
    // 恢复上次的视图与筛选关键字
    const savedView = localStorage.getItem(LIB_VIEW_KEY)
    if (savedView === 'feiniu' || savedView === 'local' || savedView === 'playlists') {
      view.value = savedView
    }
    store.searchKeyword = localStorage.getItem(LIB_FILTER_KEY) ?? ''
    await store.init()
-  if (store.config.loggedIn) store.loadTracks(1).catch(() => {})
+    // 进入曲库页：命中新鲜窗口直接用内存缓存（不请求），过期才后台静默刷新，
    // 避免每次切页都清空列表 + 重新拉取 + 重下封面
    if (store.config.loggedIn) await store.ensureTracksFresh().catch(() => {})
    // 恢复的是本地视图时自动扫描（标签有缓存，通常很快），否则恢复的筛选无内容可筛
    if (view.value === 'local') void store.scanLocal().catch(() => {})
  } finally {
    // 挂载初始化结束才让「视图 / 关键字变化 → 补齐分页」的监听生效，
    // 避免它与上面的首页请求并发（并发会因列表整体替换而丢页）；
    // 随后按同一串行顺序补一次，覆盖「启动时已带关键字」的情况
    mountedReady = true
    ensureFeiniuFilterCoverage()
  }
 })
 /** 表格表头与 TrackItem 行保持同一条网格 */
@@ -169,10 +327,9 @@ const GRID = { gridTemplateColumns: '28px 36px minmax(0,1fr) 74px 28px' }
 const listEmptyHint = computed(() => {
  if (view.value === 'feiniu') {
    if (store.searchKeyword.trim()) return '没有匹配「' + store.searchKeyword.trim() + '」的曲目'
    return store.config.loggedIn ? '曲库为空，试试刷新或检查 NAS 曲库目录' : '请先在「设置 → 飞牛音乐连接」登录'
  }
-  return '暂无本地音乐，点击「扫描本地曲库」或先到「发现音乐」下载'
+  return '暂无本地音乐，点击「扫描本地曲库」，或到「设置 → 存储与上传」添加本地曲库目录'
 })
 </script>
@@ -249,15 +406,19 @@ const listEmptyHint = computed(() => {
    <!-- ===== 右：内容（key 随来源变化，复用全局 tab-animate 切换动画） ===== -->
    <section :key="view" class="tab-animate flex min-w-0 flex-1 flex-col">
-      <!-- 未登录态 -->
+      <!-- 未登录态：**只挡飞牛曲库**。本地曲库与「我的歌单」完全不依赖 NAS 登录，
-      <div v-if="needsLogin" class="flex min-h-0 flex-1 items-center justify-center px-6">
+           此前把它们一起挡掉，等于让「只用发现音乐 + 本地曲库」的用户点进来只看得到登录提示 -->
      <div
        v-if="view === 'feiniu' && needsLogin"
        class="flex min-h-0 flex-1 items-center justify-center px-6"
      >
        <Empty>
          <EmptyMedia>
            <Music2 class="size-8 text-muted-foreground" />
          </EmptyMedia>
-          <EmptyTitle>还没有可用的飞牛音乐连接</EmptyTitle>
+          <EmptyTitle>飞牛曲库需要一个可用的音乐连接</EmptyTitle>
          <EmptyDescription>
-            到「设置 → 飞牛音乐连接」添加并登录，或先到「发现音乐」下载歌曲到本地曲库。
+            到「设置 → 飞牛音乐连接」添加并登录。本地曲库与「我的歌单」不依赖 NAS，可直接在左侧切换查看。
          </EmptyDescription>
        </Empty>
      </div>
@@ -266,36 +427,65 @@ const listEmptyHint = computed(() => {
        <!-- 工具栏 -->
        <header class="flex shrink-0 items-center gap-2 border-b px-4 py-2.5">
          <template v-if="view === 'feiniu'">
-            <div class="relative w-full max-w-sm">
+            <div class="relative w-full max-w-[280px]">
              <Search class="pointer-events-none absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
              <Input
                v-model="store.searchKeyword"
                class="h-8 pl-8"
-                placeholder="搜索歌名 / 歌手 / 专辑"
+                placeholder="搜索歌名 / 歌手 / 专辑（本地筛选）"
                @input="onSearchInput"
                @keydown.enter="onSearchInput"
              />
            </div>
-            <Button variant="outline" size="sm" class="h-8" :disabled="store.loading" @click="refreshFeiniu">
+            <Button
-              <RefreshCw :class="store.loading ? 'size-3.5 animate-spin' : 'size-3.5'" />
+              variant="outline"
              size="sm"
              class="h-8"
              :disabled="store.loading || store.refreshing"
              @click="refreshFeiniu"
            >
              <RefreshCw :class="store.loading || store.refreshing ? 'size-3.5 animate-spin' : 'size-3.5'" />
              刷新
            </Button>
-            <span class="ml-1 text-[11.5px] text-muted-foreground">
+            <span class="ml-1 shrink-0 whitespace-nowrap text-[11.5px] text-muted-foreground">
              <template v-if="isFiltering">
                匹配 {{ filteredTracks.length }} / 已加载 {{ store.tracks.length }} 首
              </template>
              <template v-else>
                {{ store.tracks.length }}<template v-if="store.total > store.tracks.length"> / {{ store.total }}</template> 首
              </template>
            </span>
-            <Button size="sm" class="ml-auto h-8" :disabled="!store.tracks.length" @click="playFeiniu">
+            <Button size="sm" class="ml-auto h-8" :disabled="!filteredTracks.length" @click="playFeiniu">
              <Play class="size-3.5" /> 播放全部
            </Button>
          </template>
          <template v-else-if="view === 'local'">
            <!-- 结构与飞牛曲库完全一致：搜索框 → 操作按钮 → 计数 → 播放全部；
                 提示语与筛选字段（歌名 / 歌手 / 专辑）也保持一致。
                 宽度收窄到与飞牛曲库同宽，把余量留给右侧的匹配数与「播放全部」 -->
            <div class="relative w-full max-w-[280px]">
              <Search class="pointer-events-none absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
              <Input
                v-model="store.searchKeyword"
                class="h-8 pl-8"
                placeholder="搜索歌名 / 歌手 / 专辑（本地筛选）"
                @input="onSearchInput"
                @keydown.enter="onSearchInput"
              />
            </div>
            <Button variant="outline" size="sm" class="h-8" :disabled="store.localScanBusy" @click="refreshLocal">
              <Loader2 v-if="store.localScanBusy" class="size-3.5 animate-spin" />
              <FolderOpen v-else class="size-3.5" />
              扫描本地曲库
            </Button>
-            <span class="text-[11.5px] text-muted-foreground">{{ store.localTracks.length }} 首</span>
+            <span class="ml-1 shrink-0 whitespace-nowrap text-[11.5px] text-muted-foreground">
-            <Button size="sm" class="ml-auto h-8" :disabled="!store.localTracks.length" @click="playLocal">
+              <template v-if="isFiltering">
                匹配 {{ filteredLocalTracks.length }} / 已扫描 {{ store.localTracks.length }} 首
              </template>
              <template v-else>{{ store.localTracks.length }} 首</template>
            </span>
            <Button size="sm" class="ml-auto h-8" :disabled="!filteredLocalTracks.length" @click="playLocal">
              <Play class="size-3.5" /> 播放全部
            </Button>
          </template>
@@ -344,8 +534,8 @@ const listEmptyHint = computed(() => {
            <!-- 表头 -->
            <div
              v-if="
-                (view === 'feiniu' && store.tracks.length) ||
+                (view === 'feiniu' && filteredTracks.length) ||
-                (view === 'local' && store.localTracks.length) ||
+                (view === 'local' && filteredLocalTracks.length) ||
                (view === 'playlists' && activePlaylist?.items.length)
              "
              class="grid h-8 items-center gap-3 px-2 text-[11px] text-muted-foreground"
@@ -365,26 +555,25 @@ const listEmptyHint = computed(() => {
              </div>
              <Empty v-else-if="!store.tracks.length">
                <EmptyMedia><Music2 class="size-8 text-muted-foreground" /></EmptyMedia>
-                <EmptyTitle>{{ store.searchKeyword.trim() ? '没有匹配的曲目' : '曲库为空' }}</EmptyTitle>
+                <EmptyTitle>曲库为空</EmptyTitle>
                <EmptyDescription>{{ listEmptyHint }}</EmptyDescription>
              </Empty>
              <Empty v-else-if="!filteredTracks.length">
                <EmptyMedia><Search class="size-8 text-muted-foreground" /></EmptyMedia>
                <EmptyTitle>没有匹配「{{ store.searchKeyword.trim() }}」的曲目</EmptyTitle>
                <EmptyDescription>
                  已在{{ store.tracks.length }}首曲库中筛选（歌名 / 歌手 / 专辑）。
                </EmptyDescription>
              </Empty>
              <template v-else>
                <TrackItem
-                  v-for="(t, i) in store.tracks"
+                  v-for="(t, i) in visibleFeiniu"
                  :key="t.guid || i"
                  :item="t"
                  :index="i"
-                  :context="store.tracks"
+                  :context="filteredTracks"
                  :active="store.current?.guid === t.guid"
                />
                <div
                  v-if="store.hasMoreTracks"
                  ref="loadMoreRef"
                  class="flex items-center justify-center gap-2 py-4 text-[12px] text-muted-foreground"
                >
                  <Loader2 v-if="store.loadingMore" class="size-3.5 animate-spin" />
                  正在加载更多…
                </div>
              </template>
            </template>
@@ -395,13 +584,18 @@ const listEmptyHint = computed(() => {
                <EmptyTitle>暂无本地音乐</EmptyTitle>
                <EmptyDescription>{{ listEmptyHint }}</EmptyDescription>
              </Empty>
-              <template v-else>
+              <Empty v-else-if="store.localTracks.length && !filteredLocalTracks.length">
                <EmptyMedia><Search class="size-8 text-muted-foreground" /></EmptyMedia>
                <EmptyTitle>没有匹配「{{ store.searchKeyword.trim() }}」的本地曲目</EmptyTitle>
                <EmptyDescription>已在扫描到的 {{ store.localTracks.length }} 首中筛选。</EmptyDescription>
              </Empty>
              <template v-else-if="filteredLocalTracks.length">
                <TrackItem
-                  v-for="(t, i) in store.localTracks"
+                  v-for="(t, i) in visibleLocal"
                  :key="t.guid || i"
                  :item="t"
                  :index="i"
-                  :context="store.localTracks"
+                  :context="filteredLocalTracks"
                  :active="store.current?.guid === t.guid"
                />
              </template>
@@ -422,7 +616,7 @@ const listEmptyHint = computed(() => {
                  </Button>
                </Empty>
                <TrackItem
-                  v-for="(t, i) in activePlaylist.items"
+                  v-for="(t, i) in visiblePlaylistItems"
                  :key="`${t.source}:${t.guid}:${i}`"
                  :item="t"
                  :index="i"
@@ -439,6 +633,17 @@ const listEmptyHint = computed(() => {
                <EmptyDescription>点击左侧「新建歌单」开始整理你的收藏。</EmptyDescription>
              </Empty>
            </template>
            <!-- 增量渲染 / 分页共用哨兵：滚到这里先追加一批行，行渲染完了再向 NAS 要下一页 -->
            <div
              v-if="showSentinel && activeList.length"
              ref="loadMoreRef"
              class="flex items-center justify-center gap-2 py-4 text-[12px] text-muted-foreground"
            >
              <Loader2 v-if="store.loadingMore" class="size-3.5 animate-spin" />
              <template v-if="hasMoreRows">已显示 {{ shownRows }} / {{ activeList.length }} 首，继续滚动加载</template>
              <template v-else>正在加载更多…</template>
            </div>
          </div>
        </ScrollArea>
      </template>
@@ -106,26 +106,26 @@ async function uploadToFeiniu() {
 <template>
  <div
-    class="group grid h-11 items-center gap-3 rounded-md px-2 outline-none transition-colors focus-visible:ring-2 focus-visible:ring-ring/50"
+    class="group grid h-11 items-center gap-3 rounded-md px-2 transition-colors"
    :class="[
      showAlbum
        ? 'grid-cols-[28px_36px_minmax(0,1fr)_minmax(0,0.75fr)_74px_28px]'
        : 'grid-cols-[28px_36px_minmax(0,1fr)_74px_28px]',
      isCurrent ? 'bg-accent/60' : 'hover:bg-accent/40'
    ]"
    role="button"
    tabindex="0"
    @dblclick="play"
    @keydown.enter.prevent="play"
  >
-    <!-- 序号 / 播放态指示：悬停时原位切换，不占用固定的空白列 -->
+    <!-- 序号 / 播放态指示 / 播放按钮。
-    <div class="flex size-7 items-center justify-center text-[11.5px] tabular-nums text-muted-foreground">
+         行本身不再是 role=button（内部还嵌着下拉菜单的按钮，嵌套交互元素对读屏是噪音）；
         播放改由下面这个**常驻 DOM** 的按钮承担——原来它是 hover 才 display:none→block，
         而 display:none 的元素无法获得焦点，键盘用户根本按不到 -->
    <div class="relative flex size-7 items-center justify-center text-[11.5px] tabular-nums text-muted-foreground">
      <span v-if="isCurrent" class="music-eq" :class="{ 'is-paused': !store.playing }"><i /><i /><i /></span>
      <template v-else>
-        <span class="group-hover:hidden">{{ index + 1 }}</span>
+        <span class="transition-opacity group-hover:opacity-0">{{ index + 1 }}</span>
        <button
          type="button"
-          class="hidden text-foreground group-hover:block"
+          class="absolute inset-0 flex items-center justify-center rounded text-foreground opacity-0 outline-none transition-opacity group-hover:opacity-100 focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-ring/50"
          :aria-label="'播放 ' + item.title"
          @click.stop="play"
        >
@@ -223,9 +223,11 @@ async function uploadToFeiniu() {
          >
            <Cloud class="size-4" /> 上传到飞牛曲库
          </DropdownMenuItem>
-          <DropdownMenuItem disabled>
+          <!-- 所在目录只是信息，不是动作：用 disabled 的菜单项展示会让人以为点了没反应 -->
-            <FolderOpen class="size-4" /> {{ item.dir || '未知目录' }}
+          <div class="flex items-center gap-2 px-2 py-1.5 text-[11.5px] text-muted-foreground">
-          </DropdownMenuItem>
+            <FolderOpen class="size-3.5 shrink-0" />
            <span class="truncate" :title="item.dir || ''">{{ item.dir || '未知目录' }}</span>
          </div>
        </template>
        <template v-if="playlistId">
@@ -22,6 +22,7 @@ const editing = ref<Partial<FeiniuConnection> | null>(null)
 const editOpen = ref(false)
 const password = ref('')
 const testing = ref(false)
 const saving = ref(false)
 function newForm() {
  editing.value = { name: '', kind: 'lan', baseUrl: '', username: '', accessCode: '', insecure: false, fnId: '' }
@@ -30,46 +31,94 @@ function newForm() {
 }
 function editForm(c: FeiniuConnection) {
-  editing.value = { ...c }
+  // 历史数据里的 frp 等内网转发方式已并入「局域网」
  editing.value = { ...c, kind: c.kind === 'fnconnect' ? 'fnconnect' : 'lan' }
  password.value = ''
  editOpen.value = true
 }
 async function save() {
-  if (!editing.value) return
+  if (!editing.value || saving.value) return
-  if (!editing.value.name?.trim() || !editing.value.baseUrl?.trim()) {
+  const draft = { ...editing.value }
-    toast.error('请填写名称与服务器地址')
+  if (!draft.name?.trim()) {
    toast.error('请填写名称')
    return
  }
  // 局域网需要服务器地址；FnConnect 需要飞牛 ID（服务器地址在登录时自动解析）
  if (draft.kind === 'fnconnect') {
    if (!draft.fnId?.trim()) {
      toast.error('请填写飞牛 ID')
      return
    }
  } else if (!draft.baseUrl?.trim()) {
    toast.error('请填写服务器地址')
    return
  }
  const pw = password.value
  saving.value = true
  try {
    const id = await store.saveConnection({
-      id: editing.value.id || '',
+      id: draft.id || '',
-      name: editing.value.name.trim(),
+      name: draft.name.trim(),
-      kind: editing.value.kind || 'lan',
+      kind: draft.kind || 'lan',
-      baseUrl: editing.value.baseUrl.trim(),
+      baseUrl: draft.baseUrl?.trim() || '',
-      username: editing.value.username || '',
+      username: draft.username || '',
-      accessCode: editing.value.accessCode || '',
+      accessCode: draft.accessCode || '',
-      insecure: !!editing.value.insecure,
+      insecure: !!draft.insecure,
-      fnId: editing.value.fnId || ''
+      fnId: draft.fnId?.trim() || '',
      relay: !!draft.relay
    })
-    if (password.value) {
+    // 先关闭对话框再登录：FnConnect 登录要先探测可达地址（可能数秒），
-      await store.login(id, editing.value.username || '', password.value)
+    // 若等待其完成才关窗，观感就是「已保存但对话框卡住」。
    }
    editOpen.value = false
    toast.success('已保存')
    if (pw && id) {
      void store
        .login(id, draft.username || '', pw)
        .then(() => toast.success('登录成功'))
        .catch((e) => toast.error(`登录失败：${e}`))
    }
  } catch (e) {
    toast.error(String(e))
  } finally {
    saving.value = false
  }
 }
-async function test(c: FeiniuConnection) {
+/** 测试当前对话框里的草案（无需先保存，新建连接也可以直接测） */
 async function test() {
  const d = editing.value
  if (!d || testing.value) return
  if (!password.value) {
    toast.error('请输入密码再测试')
    return
  }
  if (d.kind === 'fnconnect') {
    if (!d.fnId?.trim()) {
      toast.error('请填写飞牛 ID')
      return
    }
  } else if (!d.baseUrl?.trim()) {
    toast.error('请填写服务器地址')
    return
  }
  testing.value = true
  try {
-    await store.testConnection(c.id, c.username, password.value)
+    await store.testConnection(
      {
        id: d.id || '',
        name: d.name?.trim() || '测试',
        kind: d.kind || 'lan',
        baseUrl: d.baseUrl?.trim() || '',
        username: d.username || '',
        accessCode: d.accessCode || '',
        insecure: !!d.insecure,
        fnId: d.fnId?.trim() || '',
        relay: !!d.relay
      },
      d.username || '',
      password.value
    )
    toast.success('连接成功')
  } catch (e) {
    toast.error(String(e))
@@ -93,8 +142,9 @@ async function remove(c: FeiniuConnection) {
  toast.success('已删除')
 }
 /** kind → 展示名：局域网涵盖 frp / 内网转发等直连方式，其余为 FnConnect */
 function kindLabel(k: string) {
-  return k === 'lan' ? '局域网' : k === 'frp' ? 'frp 域名' : 'FnConnect'
+  return k === 'fnconnect' ? 'FnConnect' : '局域网'
 }
 onMounted(() => store.refreshConnections())
@@ -122,7 +172,8 @@ onMounted(() => store.refreshConnections())
            <Badge v-if="store.activeId === c.id" variant="default" class="text-[10px]">激活</Badge>
          </div>
          <div class="truncate text-xs text-muted-foreground">
-            {{ c.baseUrl }}<template v-if="c.username"> · {{ c.username }}</template>
+            {{ c.baseUrl }}<template v-if="c.kind === 'fnconnect' && c.relay"> · 中继</template
            ><template v-if="c.username"> · {{ c.username }}</template>
          </div>
        </div>
        <div class="flex shrink-0 items-center gap-1">
@@ -167,7 +218,7 @@ onMounted(() => store.refreshConnections())
        </div>
      </div>
      <p v-if="!store.connections.length" class="text-xs text-muted-foreground">
-        还没有连接。新建一个并填写 NAS 地址（局域网 http://192.168.x.x:5666、frp 域名或 FnConnect fnId）。
+        还没有连接。新建一个并填写 NAS 地址（局域网 http://192.168.x.x:5666，frp 等内网转发同样填最终访问地址）或 FnConnect fnId。
      </p>
    </div>
@@ -179,17 +230,17 @@ onMounted(() => store.refreshConnections())
        <div class="flex flex-col gap-3">
          <div class="space-y-1.5">
            <Label>名称</Label>
-            <Input v-model="editing!.name" placeholder="如：家里 NAS / frp 远程 / FnConnect" />
+            <Input v-model="editing!.name" placeholder="如：家里 NAS / FnConnect 远程" />
          </div>
          <div class="space-y-1.5">
            <Label>类型</Label>
            <div class="flex gap-2">
              <Button
-                v-for="k in (['lan', 'frp', 'fnconnect'] as const)"
+                v-for="k in (['lan', 'fnconnect'] as const)"
                :key="k"
                type="button"
                size="sm"
-                :variant="editing!.kind === k ? 'default' : 'outline'"
+                :variant="(editing!.kind ?? 'lan') === k ? 'default' : 'outline'"
                @click="editing!.kind = k"
              >
                {{ kindLabel(k) }}
@@ -197,15 +248,19 @@ onMounted(() => store.refreshConnections())
            </div>
          </div>
          <div v-if="editing!.kind === 'fnconnect'" class="space-y-1.5">
-            <Label>FnConnect fnId（fnos.net/xxx 或裸 id）</Label>
+            <Label>飞牛 ID</Label>
-            <Input v-model="editing!.fnId" placeholder="fnos.net/zy2060537" />
+            <Input v-model="editing!.fnId" placeholder="请输入飞牛 ID，如 abc123" />
            <p class="text-xs text-muted-foreground">
-              保存后点登录会自动解析到可达地址；服务器地址会回填。
+              即 fnos.net/ 后面的那段（也可直接粘贴 fnos.net/abc123）。
              保存后点登录会自动解析到可达地址（内网 / 公网 / 中继），服务器地址会回填。
            </p>
          </div>
          <div v-else class="space-y-1.5">
            <Label>服务器地址</Label>
-            <Input v-model="editing!.baseUrl" placeholder="http://192.168.1.10:5666 或 https://xxx.xxx.com" />
+            <Input
              v-model="editing!.baseUrl"
              placeholder="http://192.168.1.10:5666 或 https://xxx.xxx.com（frp 填转发后的地址）"
            />
          </div>
          <div class="space-y-1.5">
            <Label>账号</Label>
@@ -221,17 +276,14 @@ onMounted(() => store.refreshConnections())
          </div>
        </div>
        <DialogFooter class="gap-2">
-          <Button variant="outline" :disabled="testing" @click="test(editing as unknown as FeiniuConnection)">
+          <Button variant="outline" :disabled="testing || saving" @click="test">
            <Loader2 v-if="testing" class="size-4 animate-spin" /> 测试
          </Button>
-          <Button @click="save">保存</Button>
+          <Button :disabled="saving" @click="save">
            <Loader2 v-if="saving" class="size-4 animate-spin" /> 保存
          </Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
    <p class="text-xs text-muted-foreground">
      提示：上传音乐到 NAS（「下载到飞牛」/ 上传 / 删除）已改用 <strong class="font-medium">WebDAV</strong>，
      在「存储与上传」分组里配置，无需在此登录文件服务。
    </p>
  </div>
 </template>
@@ -7,8 +7,9 @@ import { EVENTS, STORAGE_KEYS, WINDOWS } from '@/lib/constants'
 // Rust 端通过 tauri-specta 生成的命令绑定（bindings.ts）
 import { commands } from '@/lib/bindings'
 import {
-  Undo2, Redo2, Eraser, Copy, Save, ChevronsDown,
+  Undo2, Redo2, Eraser, Copy, Save, ChevronsDown, Languages,
 } from '@lucide/vue'
 import { resolveTargetLabel } from '@/lib/translate/languages'
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
 import { Slider } from '@/components/ui/slider'
 import { TooltipProvider, Tooltip, TooltipTrigger, TooltipContent } from '@/components/ui/tooltip'
@@ -1577,14 +1578,59 @@ function composeCanvas(): HTMLCanvasElement | null {
 }
 /** 纯导出（保存用，无副作用）：canvas → toDataURL base64 */
-async function exportBase64(): Promise<ExportOut | null> {
+async function exportBase64(): Promise<ExportOut | null> {  if (annotations.value.length === 0) return cropFromStored()
  if (annotations.value.length === 0) return cropFromStored()
  const canvas = composeCanvas()
  if (!canvas) return null
  const sp = selPhys.value
  return { b64: canvas.toDataURL('image/png').split(',')[1] ?? '', w: sp.w, h: sp.h }
 }
 // ===== 截图翻译 =====
 const translating = ref(false)
 let cachedToLabel = ''
 /** 目标语言的自然语言名（提示词用），从翻译设置读取并缓存 */
 async function resolveToLabel(): Promise<string> {
  if (cachedToLabel) return cachedToLabel
  try {
    const s = await invoke<{ defaultTarget: string }>('translate_get_settings')
    cachedToLabel = resolveTargetLabel(s.defaultTarget) || 'zh-Hans'
  } catch {
    cachedToLabel = 'zh-Hans'
  }
  return cachedToLabel
 }
 /**
 * 翻译选区：把选区交给翻译模块（本地 OCR 或视觉直译 → 悬浮窗展示）。
 *
 * 与「复制」同样的先隐藏后处理模式：OCR 与翻译耗时不可控，先隐藏覆盖层给用户即时反馈；
 * 结果与失败提示都由非激活悬浮窗在选区旁展示，不在主界面 toast。
 */
 async function onTranslate() {
  if (translating.value) return
  const sp = selPhys.value
  if (sp.w < 2 || sp.h < 2) return
  translating.value = true
  magVisible.value = false
  await win.hide().catch(() => {})
  try {
    await invoke('translate_screenshot_region', {
      x: sp.x,
      y: sp.y,
      w: sp.w,
      h: sp.h,
      toLabel: await resolveToLabel(),
    })
    // 裁剪已完成，释放全屏底图内存（与正常关闭路径共用清理逻辑，重复清空无害）
    await invoke('screenshot_clear_fullscreen')
  } catch (e) {
    console.error('[screenshot] 翻译选区失败', e)
  } finally {
    translating.value = false
  }
 }
 async function finish() {
  if (exporting.value) return
  exporting.value = true
@@ -2297,6 +2343,20 @@ onUnmounted(() => {
      <div class="tb-sep" />
      <!-- 翻译（截图翻译：选区 → 本地 OCR / 视觉直译 → 悬浮窗展示） -->
      <div class="tb-group">
        <Tooltip>
          <TooltipTrigger as-child>
            <button class="tb-icon" @click="onTranslate">
              <Languages class="tb-svg" />
            </button>
          </TooltipTrigger>
          <TooltipContent>翻译选区</TooltipContent>
        </Tooltip>
      </div>
      <div class="tb-sep" />
      <!-- 复制 / 保存（置末） -->
      <div class="tb-group">
        <Tooltip>
@@ -0,0 +1,61 @@
 <script setup lang="ts">
 import { onMounted, ref } from 'vue'
 import { History, Languages, Settings } from '@lucide/vue'
 import { useModuleTabs } from '@/lib/use-module-tabs'
 import { useTranslateStore } from '@/stores/translateStore'
 import { createLogger } from '@/lib/logger'
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'
 import TranslateWorkbench from './components/TranslateWorkbench.vue'
 import TranslateSettings from './components/TranslateSettings.vue'
 import TranslateHistory from './components/TranslateHistory.vue'
 const logger = createLogger('translate')
 const store = useTranslateStore()
 const activeTab = ref('workbench')
 const tabsListRef = useModuleTabs('translate', activeTab, [
  { value: 'workbench', label: '翻译' },
  { value: 'history', label: '历史' },
  { value: 'settings', label: '设置' }
 ])
 onMounted(async () => {
  try {
    await store.init()
  } catch (e) {
    logger.error(`翻译模块初始化失败：${String(e)}`)
  }
 })
 </script>
 <template>
  <div class="h-full overflow-hidden p-6 flex flex-col">
    <Tabs v-model="activeTab" class="flex-1 min-h-0 flex flex-col">
      <div ref="tabsListRef" class="shrink-0">
        <TabsList class="grid w-full max-w-md grid-cols-3 !bg-transparent !p-0 !shadow-none">
          <TabsTrigger value="workbench" class="gap-1.5">
            <Languages class="size-3.5" />翻译
          </TabsTrigger>
          <TabsTrigger value="history" class="gap-1.5">
            <History class="size-3.5" />历史
          </TabsTrigger>
          <TabsTrigger value="settings" class="gap-1.5">
            <Settings class="size-3.5" />设置
          </TabsTrigger>
        </TabsList>
      </div>
      <TabsContent value="workbench" class="flex-1 min-h-0 flex flex-col mt-4 tab-animate">
        <TranslateWorkbench />
      </TabsContent>
      <TabsContent value="history" class="flex-1 min-h-0 flex flex-col mt-4 tab-animate">
        <TranslateHistory />
      </TabsContent>
      <TabsContent value="settings" class="flex-1 min-h-0 overflow-hidden mt-4 tab-animate">
        <TranslateSettings />
      </TabsContent>
    </Tabs>
  </div>
 </template>
@@ -0,0 +1,368 @@
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue'
 import { toast } from 'vue-sonner'
 import { CircleAlert, CircleCheck, Eraser, KeyRound, LoaderCircle, RefreshCw, Trash2, Zap } from '@lucide/vue'
 import { useTranslateStore } from '@/stores/translateStore'
 import { ERROR_HINTS, type EngineTestResult, type EngineView, type TranslateEngineConfig } from '@/types/translate'
 import { Button } from '@/components/ui/button'
 import { Badge } from '@/components/ui/badge'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { Textarea } from '@/components/ui/textarea'
 import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
 } from '@/components/ui/select'
 const props = defineProps<{ view: EngineView }>()
 const emit = defineEmits<{
  (e: 'deleted'): void
 }>()
 const store = useTranslateStore()
 /** 编辑草稿。保存前的改动只在这里，不影响已生效配置 */
 const draft = ref<TranslateEngineConfig>({ ...props.view.config })
 const apiKey = ref('')
 const models = ref<string[]>([])
 const testResult = ref<EngineTestResult | null>(null)
 const busy = ref<'' | 'save' | 'key' | 'test' | 'models'>('')
 const confirmingDelete = ref(false)
 // 外部刷新（保存成功、密钥变更后 store.reload）时重置草稿
 watch(
  () => props.view,
  v => {
    draft.value = { ...v.config }
    apiKey.value = ''
    testResult.value = null
  }
 )
 const dirty = computed(() => {
  const a = JSON.stringify(draft.value)
  const b = JSON.stringify(props.view.config)
  return a !== b
 })
 const canFetchModels = computed(() => props.view.hasApiKey && props.view.config.kind === 'ai')
 /** 数值输入的收敛：NaN 一律退回默认值，避免把空输入写进配置 */
 function toNumber(raw: string | number, fallback: number, min: number, max: number): number {
  const n = typeof raw === 'number' ? raw : Number.parseFloat(raw)
  if (!Number.isFinite(n)) return fallback
  return Math.min(max, Math.max(min, n))
 }
 async function withBusy(kind: typeof busy.value, fn: () => Promise<void>) {
  busy.value = kind
  try {
    await fn()
  } catch (e) {
    toast.error(String(e))
  } finally {
    busy.value = ''
  }
 }
 const save = () =>
  withBusy('save', async () => {
    // extraBody 只接受 JSON 对象：留空视为「无额外参数」，写了但解析失败要拦下来，
    // 否则会静默传一份空参数，用户以为生效了其实没有
    const extra = draft.value.extraBody?.trim()
    if (extra) {
      try {
        const parsed = JSON.parse(extra)
        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
          toast.error('额外请求体必须是 JSON 对象，例如 {"thinking":{"type":"disabled"}}')
          return
        }
      } catch {
        toast.error('额外请求体不是合法 JSON')
        return
      }
    }
    await store.saveEngine({ ...draft.value, extraBody: extra || null })
    toast.success('已保存')
  })
 const saveKey = () =>
  withBusy('key', async () => {
    // 后端按「空串即清除」处理，因此这里必须挡住空提交，否则一次误点会清掉已有密钥
    if (!apiKey.value.trim()) {
      toast.error('请输入 API Key')
      return
    }
    await store.setSecret(props.view.config.id, apiKey.value.trim())
    apiKey.value = ''
    toast.success('密钥已写入系统凭据管理器')
  })
 const clearKey = () =>
  withBusy('key', async () => {
    await store.clearSecret(props.view.config.id)
    toast.success('密钥已清除')
  })
 const test = () =>
  withBusy('test', async () => {
    // 传草稿而非已保存配置：未保存的 Base URL 改动也能立刻测试
    testResult.value = await store.testEngine({ ...draft.value })
    if (testResult.value.ok) toast.success('连通正常')
    else toast.error(testResult.value.message)
  })
 const fetchModels = () =>
  withBusy('models', async () => {
    models.value = await store.fetchModels(props.view.config.id)
    if (models.value.length === 0) toast.info('上游未返回任何模型')
    else toast.success(`拉取到 ${models.value.length} 个模型`)
  })
 const remove = () =>
  withBusy('save', async () => {
    if (!confirmingDelete.value) {
      confirmingDelete.value = true
      return
    }
    await store.deleteEngine(props.view.config.id)
    toast.success('引擎已删除')
    emit('deleted')
  })
 </script>
 <template>
  <div class="space-y-3 rounded-lg border bg-muted/20 p-3">
    <div class="grid grid-cols-2 gap-3">
      <div class="space-y-1.5">
        <Label class="text-[12px]">名称</Label>
        <Input v-model="draft.name" class="h-8 text-[13px]" />
      </div>
      <div class="space-y-1.5">
        <Label class="text-[12px]">优先级（越小越先尝试）</Label>
        <Input
          :model-value="draft.priority"
          type="number"
          class="h-8 text-[13px]"
          @update:model-value="v => (draft.priority = toNumber(v, 100, 0, 9999))"
        />
      </div>
      <div
        v-if="draft.kind === 'ai' || draft.preset === 'libretranslate'"
        class="col-span-2 space-y-1.5"
      >
        <Label class="text-[12px]">Base URL</Label>
        <Input
          v-model="draft.baseUrl"
          :placeholder="draft.preset === 'libretranslate' ? 'https://translate.example.com' : 'https://api.deepseek.com'"
          class="h-8 text-[13px]"
        />
        <p class="text-[11px] text-muted-foreground">
          <template v-if="draft.kind === 'ai'">
            填到 /v1 为止即可；若粘入了完整端点（…/chat/completions）后端会自动剥掉。
          </template>
          <template v-else>
            填 LibreTranslate 服务根地址；若粘入了 /translate 结尾后端会自动剥掉。
          </template>
        </p>
      </div>
      <div v-if="draft.kind === 'ai'" class="space-y-1.5">
        <Label class="text-[12px]">模型</Label>
        <Input v-model="draft.model" placeholder="deepseek-flash" class="h-8 text-[13px]" />
      </div>
      <div class="space-y-1.5">
        <Label class="text-[12px]">超时（毫秒）</Label>
        <Input
          :model-value="draft.timeoutMs"
          type="number"
          class="h-8 text-[13px]"
          @update:model-value="v => (draft.timeoutMs = toNumber(v, 30000, 1000, 600000))"
        />
      </div>
      <div v-if="draft.kind === 'ai'" class="space-y-1.5">
        <Label class="text-[12px]">温度（0~2）</Label>
        <Input
          :model-value="draft.temperature"
          type="number"
          step="0.1"
          class="h-8 text-[13px]"
          @update:model-value="v => (draft.temperature = toNumber(v, 0.3, 0, 2))"
        />
      </div>
      <div v-if="draft.kind === 'ai'" class="space-y-1.5">
        <Label class="text-[12px]">最大输出 tokens</Label>
        <Input
          :model-value="draft.maxTokens"
          type="number"
          class="h-8 text-[13px]"
          @update:model-value="v => (draft.maxTokens = toNumber(v, 4096, 64, 384000))"
        />
      </div>
      <div
        v-if="draft.kind !== 'ai'"
        class="col-span-2 space-y-1 rounded-md border bg-background p-2.5 text-[11px] text-muted-foreground"
      >
        <p v-if="draft.preset === 'libretranslate'">
          LibreTranslate：文本发往你自己的服务器。API Key 可选——部署启用密钥校验时才必须填写。
        </p>
        <p v-else-if="draft.preset === 'mymemory'">
          MyMemory：需要显式源语言（源语言为「自动检测」时该源会被跳过），单次约 500 字节。
        </p>
        <p>免密钥源会把文本送交第三方接口，请自行判断内容是否适合外发。</p>
      </div>
    </div>
    <div v-if="draft.kind === 'ai'" class="flex items-start gap-3 rounded-md border bg-background p-2.5">
      <Switch
        :model-value="draft.supportsVision"
        @update:model-value="(v: boolean) => (draft.supportsVision = v)"
      />
      <div class="min-w-0 flex-1">
        <Label class="text-[12px]">支持图像输入</Label>
        <p class="mt-0.5 text-[11px] text-muted-foreground">
          勾选后「截图翻译」可用视觉直译模式：把截图直接发给该模型，识别与翻译一步完成。
          仅对支持图像输入的模型勾选（如 GLM-4V、Qwen-VL、gpt-4o 等）。
        </p>
      </div>
    </div>
    <div
      v-if="draft.kind === 'ai' || draft.preset === 'libretranslate'"
      class="space-y-1.5 rounded-md border bg-background p-2.5"
    >
      <div class="flex items-center gap-1.5">
        <KeyRound class="size-3.5 text-muted-foreground" />
        <Label class="text-[12px]">
          {{ draft.preset === 'libretranslate' ? 'API Key（可选）' : 'API Key' }}
        </Label>
        <span class="text-[11px] text-muted-foreground">
          存入 Windows 凭据管理器，不写入配置文件、不回传前端明文
        </span>
      </div>
      <div class="flex gap-2">
        <Input
          v-model="apiKey"
          type="password"
          autocomplete="off"
          class="h-8 text-[13px]"
          :placeholder="view.hasApiKey ? `已配置：${view.apiKeyMasked}` : '尚未配置'"
        />
        <Button size="sm" :disabled="busy === 'key' || !apiKey.trim()" @click="saveKey">
          <LoaderCircle v-if="busy === 'key'" class="animate-spin" />
          保存
        </Button>
        <Button
          v-if="view.hasApiKey"
          variant="outline"
          size="sm"
          :disabled="busy === 'key'"
          @click="clearKey"
        >
          <Eraser />
          清除
        </Button>
      </div>
    </div>
    <details class="rounded-md border bg-background p-2.5">
      <summary class="cursor-pointer select-none text-[12px] font-medium">
        高级：自定义提示词与额外请求体
      </summary>
      <div class="mt-2 space-y-3">
        <div class="space-y-1.5">
          <Label class="text-[12px]">自定义 System Prompt</Label>
          <Textarea
            v-model="draft.systemPrompt"
            class="min-h-20 text-[12px]"
            placeholder="留空则使用「设置 → 提示词模板」中的模板；{target} 会替换为目标语言"
          />
        </div>
        <div class="space-y-1.5">
          <Label class="text-[12px]">额外请求体（JSON 对象）</Label>
          <Textarea
            :model-value="draft.extraBody ?? ''"
            class="min-h-16 font-mono text-[12px]"
            placeholder='例如 {"thinking":{"type":"disabled"}}'
            @update:model-value="v => (draft.extraBody = String(v) || null)"
          />
          <p class="text-[11px] text-muted-foreground">
            用于透传非标准参数。翻译场景默认不传 thinking / reasoning_effort。
          </p>
        </div>
      </div>
    </details>
    <div v-if="models.length > 0" class="space-y-1.5 rounded-md border bg-background p-2.5">
      <Label class="text-[12px]">从上游拉取到的模型（选择即填入上方「模型」）</Label>
      <Select :model-value="draft.model" @update:model-value="v => (draft.model = String(v))">
        <SelectTrigger class="h-8 text-[12px]"><SelectValue placeholder="选择模型" /></SelectTrigger>
        <SelectContent>
          <SelectItem v-for="m in models" :key="m" :value="m">{{ m }}</SelectItem>
        </SelectContent>
      </Select>
    </div>
    <div
      v-if="testResult"
      class="space-y-1 rounded-md border p-2.5 text-[12px]"
      :class="testResult.ok ? 'bg-emerald-50 dark:bg-emerald-950/20' : 'bg-red-50 dark:bg-red-950/20'"
    >
      <div class="flex items-start gap-2">
        <CircleCheck v-if="testResult.ok" class="mt-0.5 size-3.5 shrink-0" />
        <CircleAlert v-else class="mt-0.5 size-3.5 shrink-0" />
        <div class="min-w-0 flex-1">
          <p class="break-words">{{ testResult.message }}</p>
          <p v-if="!testResult.ok && testResult.errorKind" class="mt-0.5 text-muted-foreground">
            {{ ERROR_HINTS[testResult.errorKind] }}
          </p>
          <pre
            v-if="testResult.detail"
            class="mt-1 whitespace-pre-wrap break-all rounded bg-background/60 p-1.5 text-[11px]"
          >{{ testResult.detail }}</pre>
        </div>
      </div>
    </div>
    <div class="flex flex-wrap items-center gap-2">
      <Button size="sm" :disabled="busy === 'save' || !dirty" @click="save">
        <LoaderCircle v-if="busy === 'save'" class="animate-spin" />
        保存配置
      </Button>
      <Button variant="outline" size="sm" :disabled="busy === 'test'" @click="test">
        <LoaderCircle v-if="busy === 'test'" class="animate-spin" />
        <Zap v-else />
        测试连通性
      </Button>
      <Button
        variant="outline"
        size="sm"
        :disabled="busy === 'models' || !canFetchModels"
        :title="canFetchModels ? '从上游拉取模型列表' : '需先配置 API Key'"
        @click="fetchModels"
      >
        <LoaderCircle v-if="busy === 'models'" class="animate-spin" />
        <RefreshCw v-else />
        拉取模型
      </Button>
      <div class="flex-1" />
      <Badge v-if="dirty" variant="outline" class="text-[11px]">有未保存的改动</Badge>
      <Button
        :variant="confirmingDelete ? 'destructive' : 'outline'"
        size="sm"
        :disabled="busy === 'save'"
        @click="remove"
      >
        <Trash2 />
        {{ confirmingDelete ? '确认删除？' : '删除' }}
      </Button>
    </div>
  </div>
 </template>
@@ -0,0 +1,270 @@
 <script setup lang="ts">
 import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
 import { toast } from 'vue-sonner'
 import { Copy, LoaderCircle, Search, Star, Trash2 } from '@lucide/vue'
 import { useTranslateStore } from '@/stores/translateStore'
 import { labelOf } from '@/lib/translate/languages'
 import { copyToClipboard } from '@/lib/translate/api'
 import { Button } from '@/components/ui/button'
 import { Badge } from '@/components/ui/badge'
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
 import { Input } from '@/components/ui/input'
 import { ScrollArea } from '@/components/ui/scroll-area'
 import { Switch } from '@/components/ui/switch'
 const store = useTranslateStore()
 const VIA_LABELS: Record<string, string> = {
  manual: '主面板',
  selection: '划词',
  clipboard: '剪贴板',
  screenshot: '截图',
  preview: '预览'
 }
 function viaLabel(via: string): string {
  return VIA_LABELS[via] ?? via
 }
 function formatTs(ts: number): string {
  const d = new Date(ts)
  const pad = (n: number) => `${n}`.padStart(2, '0')
  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`
 }
 /** 是否处于筛选态：决定空列表该提示「还没记录」还是「没有匹配」 */
 const hasFilter = computed(() => store.historyQuery.trim().length > 0 || store.historyFavOnly)
 /** 只有一条都没加载到时才让整块区域让位给加载态，否则改关键词时列表会闪没 */
 const showInitialLoading = computed(
  () => store.historyLoading && store.historyItems.length === 0
 )
 /** 搜索是防抖的：逐键查询没有意义，200ms 停顿后再发 */
 let searchTimer: ReturnType<typeof setTimeout> | null = null
 function onSearchInput() {
  if (searchTimer) clearTimeout(searchTimer)
  searchTimer = setTimeout(() => void store.reloadHistory(), 200)
 }
 async function copyItem(text: string) {
  try {
    await copyToClipboard(text)
    toast.success('已复制')
  } catch (e) {
    toast.error(String(e))
  }
 }
 async function onDelete(id: number) {
  try {
    await store.deleteHistoryItem(id)
  } catch (e) {
    toast.error(String(e))
  }
 }
 async function onClear() {
  if (!window.confirm('确定清空全部历史（含收藏）？此操作不可恢复。')) return
  try {
    await store.clearHistory()
    toast.success('历史已清空')
  } catch (e) {
    toast.error(String(e))
  }
 }
 // ===== 触底加载下一页 =====
 /**
 * 哨兵放进滚动视口内（而不是监听 ScrollArea 的 scroll 事件）：
 * 分页由 store 管，组件只需要知道「到达底部了」这一个信号。
 */
 const loadMoreRef = ref<HTMLElement | null>(null)
 let loadMoreObserver: IntersectionObserver | null = null
 onMounted(() => {
  loadMoreObserver = new IntersectionObserver(
    entries => {
      if (!entries.some(e => e.isIntersecting)) return
      void store.loadMoreHistory()
      // 追加后哨兵位置变了但可能仍处于交叉状态，此时不会再触发回调，必须重新 observe
      nextTick(() => {
        const el = loadMoreRef.value
        if (el && loadMoreObserver) {
          loadMoreObserver.unobserve(el)
          loadMoreObserver.observe(el)
        }
      })
    },
    // 提前一屏取数，滚到底时数据已就位，不会看到「停顿—跳出」
    { rootMargin: '300px' }
  )
  /**
   * 必须用 watch 而不是「挂载时 observe 一次」。
   *
   * 哨兵在 v-if/v-else 分支里：首屏是「加载中…」或「还没有记录」，哨兵根本不存在，
   * 挂载那一刻拿到的是 null。之后数据到了、哨兵被创建，ref 才会变——不监听就永远
   * 不会 observe，第二页永远加载不出来。
   *
   * watch 放在 onMounted 内注册：此时 loadMoreObserver 已就绪，immediate 能立刻接管
   * 已经存在的哨兵；放在 setup 顶层会在观察者创建之前跑，被守卫挡掉后再无第二次机会。
   */
  watch(
    loadMoreRef,
    el => {
      if (!loadMoreObserver) return
      loadMoreObserver.disconnect()
      if (el) loadMoreObserver.observe(el)
    },
    { immediate: true }
  )
  void store.reloadHistory()
 })
 onBeforeUnmount(() => {
  if (searchTimer) clearTimeout(searchTimer)
  loadMoreObserver?.disconnect()
 })
 </script>
 <template>
  <div class="flex h-full min-h-0 flex-col">
    <div class="mx-auto flex min-h-0 w-full max-w-3xl flex-col gap-3">
      <!-- 工具条 -->
      <div class="flex shrink-0 flex-wrap items-center gap-2">
        <div class="relative min-w-56 flex-1">
          <Search class="absolute left-2.5 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
          <Input
            v-model="store.historyQuery"
            class="h-8 pl-8 text-[13px]"
            placeholder="搜索原文或译文…"
            @input="onSearchInput"
          />
        </div>
        <label class="flex items-center gap-1.5 text-[12px] text-muted-foreground">
          <Switch
            :model-value="store.historyFavOnly"
            @update:model-value="
              v => {
                store.historyFavOnly = Boolean(v)
                void store.reloadHistory()
              }
            "
          />
          只看收藏
        </label>
        <Button variant="outline" size="sm" @click="onClear">
          <Trash2 />
          清空
        </Button>
      </div>
      <!--
        这里把 Card 当「带固定标题栏的滚动容器」用，所以要在本地覆盖掉 Card 的
        内容卡片默认值：gap-6 会在标题与列表之间留 24px 空带、py-6 会在卡片底部
        留 24px 死区、缺 overflow-hidden 则滚动条会溢出圆角。
      -->
      <Card class="flex min-h-0 flex-1 flex-col gap-0 overflow-hidden py-0">
        <CardHeader class="shrink-0 gap-0 px-4 py-2.5">
          <CardTitle class="text-[13px]">翻译历史</CardTitle>
        </CardHeader>
        <!-- 分隔线放在内容侧：CardHeader 带 [.border-b]:pb-6，加 border-b 会把标题栏重新顶高 -->
        <CardContent class="min-h-0 flex-1 border-t p-0">
          <div
            v-if="showInitialLoading"
            class="flex items-center gap-2 px-4 py-6 text-[13px] text-muted-foreground"
          >
            <LoaderCircle class="size-3.5 animate-spin" />
            加载中…
          </div>
          <p
            v-else-if="store.historyItems.length === 0"
            class="px-4 py-8 text-center text-[13px] text-muted-foreground"
          >
            {{ hasFilter ? '没有匹配的记录。' : '还没有翻译记录。' }}
          </p>
          <ScrollArea v-else class="h-full min-h-0">
            <!--
              分割线容器里**只能放记录本身**。
              Tailwind v4 的 divide-y 展开成 `> :not(:last-child){border-bottom-width:1px}`，
              哨兵一旦放进这个容器，真正的末条就被挤成「非末位」而多画一条底部分割线；
              它又紧贴卡片下边框（中间只隔哨兵那 1px），看起来就是双线。
            -->
            <div class="divide-y">
              <div
                v-for="item in store.historyItems"
                :key="item.id"
                class="history-row group px-4 py-3"
              >
                <div class="flex flex-wrap items-center gap-2 text-[11px] text-muted-foreground">
                  <span class="tabular-nums">{{ formatTs(item.ts) }}</span>
                  <Badge variant="outline" class="text-[11px]">{{ viaLabel(item.via) }}</Badge>
                  <span>{{ labelOf(item.fromLang) }} → {{ labelOf(item.toLang) }}</span>
                  <span v-if="item.engineName">{{ item.engineName }}</span>
                  <div class="flex-1" />
                  <button
                    class="rounded p-1 transition-colors hover:bg-accent"
                    :class="{ 'text-amber-500': item.favorited }"
                    :title="item.favorited ? '取消收藏' : '收藏'"
                    @click="store.toggleHistoryFavorite(item.id)"
                  >
                    <Star class="size-3.5" />
                  </button>
                  <button
                    class="rounded p-1 text-muted-foreground opacity-0 transition-all hover:bg-accent group-hover:opacity-100"
                    title="复制译文"
                    @click="copyItem(item.resultText)"
                  >
                    <Copy class="size-3.5" />
                  </button>
                  <button
                    class="rounded p-1 text-muted-foreground opacity-0 transition-all hover:bg-accent group-hover:opacity-100"
                    title="删除"
                    @click="onDelete(item.id)"
                  >
                    <Trash2 class="size-3.5" />
                  </button>
                </div>
                <p class="mt-1 line-clamp-2 text-[12px] text-muted-foreground">{{ item.sourceText }}</p>
                <p class="mt-0.5 line-clamp-3 whitespace-pre-wrap break-words text-[13px]">
                  {{ item.resultText }}
                </p>
              </div>
            </div>
            <!-- 触底哨兵：在分割线容器之外，本身不占位，只作 observer 的观察目标 -->
            <div ref="loadMoreRef" class="h-px" />
            <div
              v-if="store.historyLoadingMore"
              class="flex items-center justify-center gap-2 py-3 text-[12px] text-muted-foreground"
            >
              <LoaderCircle class="size-3.5 animate-spin" />
              加载中…
            </div>
          </ScrollArea>
        </CardContent>
      </Card>
    </div>
  </div>
 </template>
 <style scoped>
 /**
 * 行级渲染跳过。
 *
 * 分页后列表仍会随用户持续滚动累积到上千行，每行含原文、译文两段可变长文本。
 * `content-visibility: auto` 让浏览器跳过视口外行的布局与绘制，效果接近虚拟列表，
 * 但不需要自己接管滚动位置；`contain-intrinsic-size` 提供未渲染时的占位高度，
 * 其中 `auto` 关键字让浏览器按首次渲染的实际高度记忆，避免滚动条反复抖动。
 * 84px 只是首屏的估算值（py-3 + 三行文本），估偏只影响滚动条长度的第一帧。
 */
 .history-row {
  content-visibility: auto;
  contain-intrinsic-size: auto 84px;
 }
 </style>
@@ -0,0 +1,731 @@
 <script setup lang="ts">
 import { computed, onMounted, ref, watch } from 'vue'
 import { toast } from 'vue-sonner'
 import { CircleAlert, LoaderCircle, Plus, Save, ScanText, Sparkles } from '@lucide/vue'
 import { useTranslateStore } from '@/stores/translateStore'
 import { orderedLanguages } from '@/lib/translate/languages'
 import {
  ENGINE_PRESETS,
  type HistorySettings,
  type PromptTemplates,
  type SelectionSettings,
  type TranslateEngineConfig,
  type TranslateSettings
 } from '@/types/translate'
 import { Button } from '@/components/ui/button'
 import { Badge } from '@/components/ui/badge'
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { Separator } from '@/components/ui/separator'
 import { Switch } from '@/components/ui/switch'
 import { Textarea } from '@/components/ui/textarea'
 import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
 } from '@/components/ui/select'
 import EngineEditor from './EngineEditor.vue'
 const store = useTranslateStore()
 /** 展开编辑的引擎 id（空表示全部收起） */
 const editingId = ref('')
 const presetKey = ref(ENGINE_PRESETS[0].key)
 const newEngineName = ref('')
 const savingTemplates = ref(false)
 /** 提示词模板是长文本，不做逐键落盘，改为本地草稿 + 显式保存 */
 const templates = ref<PromptTemplates | null>(null)
 watch(
  () => store.settings?.promptTemplates,
  p => {
    if (p) templates.value = { ...p }
  },
  { immediate: true }
 )
 onMounted(async () => {
  try {
    await store.init()
  } catch (e) {
    toast.error(`读取设置失败：${String(e)}`)
  }
 })
 const targetLanguages = computed(() => orderedLanguages(false))
 const templatesDirty = computed(() => {
  if (!templates.value || !store.settings) return false
  return JSON.stringify(templates.value) !== JSON.stringify(store.settings.promptTemplates)
 })
 /** 生成不与现有实例冲突的 id（id 会进入凭据键，必须唯一且字符集受限） */
 function nextEngineId(base: string): string {
  const used = new Set(store.engines.map(e => e.config.id))
  if (!used.has(base)) return base
  let i = 2
  while (used.has(`${base}-${i}`)) i += 1
  return `${base}-${i}`
 }
 const selectedPreset = computed(() => ENGINE_PRESETS.find(p => p.key === presetKey.value))
 async function addEngine() {
  const preset = selectedPreset.value
  if (!preset) return
  const name = newEngineName.value.trim() || preset.label
  const config: TranslateEngineConfig = {
    id: nextEngineId(preset.key),
    name,
    kind: 'ai',
    preset: preset.key,
    enabled: true,
    priority: 100,
    baseUrl: '',
    model: '',
    temperature: 0.3,
    maxTokens: 4096,
    timeoutMs: 30000,
    systemPrompt: '',
    extraBody: null,
    ...preset.template,
    // 显式兜底：preset.template 是 Partial，缺省必须落成 false
    supportsVision: preset.template.supportsVision ?? false
  }
  try {
    await store.saveEngine(config)
    newEngineName.value = ''
    editingId.value = config.id
    toast.success(`已新增引擎「${name}」，请填写 API Key`)
  } catch (e) {
    toast.error(String(e))
  }
 }
 async function patch(patch: Partial<TranslateSettings>) {
  try {
    await store.patchSettings(patch)
  } catch (e) {
    toast.error(String(e))
  }
 }
 // ===== 翻译面板：快捷键与黑名单需要显式保存 =====
 // 快捷键是文本输入，逐键保存会在「Ctrl」这种半成品状态下反复注册/注销并报错；
 // 黑名单同理（一行一个进程名，输入到一半不该落盘）。这两项因此走草稿 + 保存按钮，
 // 其余开关类项改动即生效。
 const shortcutDraft = ref({ panelShortcut: '' })
 const blacklistDraft = ref('')
 const applyingShortcuts = ref(false)
 watch(
  () => store.settings?.selection,
  s => {
    if (!s) return
    shortcutDraft.value = { panelShortcut: s.panelShortcut }
    blacklistDraft.value = s.blacklist.join('\n')
  },
  { immediate: true, deep: true }
 )
 const shortcutsDirty = computed(() => {
  const s = store.settings?.selection
  if (!s) return false
  return shortcutDraft.value.panelShortcut.trim() !== s.panelShortcut
 })
 const blacklistDirty = computed(() => {
  const s = store.settings?.selection
  if (!s) return false
  return blacklistDraft.value !== s.blacklist.join('\n')
 })
 async function patchSelection(next: Partial<SelectionSettings>) {
  if (!store.settings) return
  await patch({ selection: { ...store.settings.selection, ...next } })
 }
 // ===== 历史：条数需要草稿 + 显式提交 =====
 // 与快捷键、黑名单同理，数字输入也不该逐键落盘：删掉「2000」的中间态是空串或「2」，
 // 一提交就把上限改成 2、随即触发一次大规模淘汰，是不可逆的。改成失焦 / 回车才写。
 /** 后端默认上限，也是输入框的兜底值 */
 const HISTORY_MAX_ITEMS_MIN = 100
 const HISTORY_MAX_ITEMS_MAX = 20000
 const maxItemsDraft = ref<number | undefined>(undefined)
 watch(
  () => store.settings?.history.maxItems,
  v => {
    maxItemsDraft.value = v ?? undefined
  },
  { immediate: true }
 )
 async function patchHistory(next: Partial<HistorySettings>) {
  if (!store.settings) return
  await patch({ history: { ...store.settings.history, ...next } })
 }
 /** 提交保留条数。越界就夹回区间，而不是静默丢弃用户输入。 */
 async function commitMaxItems() {
  const current = store.settings?.history.maxItems
  if (current === undefined) return
  const raw = Number(maxItemsDraft.value)
  if (!Number.isFinite(raw)) {
    maxItemsDraft.value = current
    return
  }
  const clamped = Math.min(HISTORY_MAX_ITEMS_MAX, Math.max(HISTORY_MAX_ITEMS_MIN, Math.round(raw)))
  maxItemsDraft.value = clamped
  if (clamped === current) return
  await patchHistory({ maxItems: clamped })
  toast.success(`保留条数已设为 ${clamped}`)
 }
 /** 应用快捷键：保存设置后后端会立刻重新注册，无需重启应用 */
 async function applyShortcuts() {
  if (!store.settings) return
  applyingShortcuts.value = true
  try {
    await store.persist({
      ...store.settings,
      selection: {
        ...store.settings.selection,
        panelShortcut: shortcutDraft.value.panelShortcut.trim()
      }
    })
    toast.success('快捷键已应用')
  } catch (e) {
    toast.error(String(e))
  } finally {
    applyingShortcuts.value = false
  }
 }
 async function saveBlacklist() {
  const list = blacklistDraft.value
    .split('\n')
    .map(line => line.trim())
    .filter(Boolean)
  await patchSelection({ blacklist: list })
  toast.success('名单已保存')
 }
 async function previewPopup() {
  try {
    await store.previewPopup()
  } catch (e) {
    toast.error(String(e))
  }
 }
 async function saveTemplates() {
  if (!templates.value || !store.settings) return
  savingTemplates.value = true
  try {
    await store.persist({ ...store.settings, promptTemplates: { ...templates.value } })
    toast.success('提示词模板已保存')
  } catch (e) {
    toast.error(String(e))
  } finally {
    savingTemplates.value = false
  }
 }
 /** 模板占位符校验：漏了 {target} 会让模型不知道该译成什么语言 */
 function templateWarning(text: string): string {
  if (text.trim() && !text.includes('{target}')) {
    return '未包含 {target} 占位符，模型将无法得知目标语言'
  }
  return ''
 }
 </script>
 <template>
  <div v-if="store.loading && !store.settings" class="flex items-center gap-2 py-2 text-[13px] text-muted-foreground">
    <LoaderCircle class="size-3.5 animate-spin" />
    正在读取设置…
  </div>
  <div v-else class="h-full overflow-y-auto pb-2">
    <div class="mx-auto max-w-3xl space-y-4">
      <!-- ===== 引擎 ===== -->
      <Card>
        <CardHeader class="pb-3">
          <CardTitle class="flex items-center gap-2 text-[14px]">
            <Sparkles class="size-4" />
            翻译引擎
          </CardTitle>
          <p class="text-[12px] text-muted-foreground">
            同一类引擎可配置多个实例（如官方 API 与本地 Ollama 并存）。「自动」模式会按优先级依次尝试。
          </p>
        </CardHeader>
        <CardContent class="space-y-3">
          <div
            v-for="view in store.engines"
            :key="view.config.id"
            class="rounded-lg border p-3"
          >
            <div class="flex items-center gap-2">
              <span class="text-[13px] font-medium">{{ view.config.name }}</span>
              <Badge variant="outline" class="text-[11px]">
                {{ view.config.kind === 'ai' ? 'AI · OpenAI 兼容' : view.config.kind }}
              </Badge>
              <Badge variant="secondary" class="text-[11px] tabular-nums">
                P{{ view.config.priority }}
              </Badge>
              <Badge v-if="view.ready" variant="secondary" class="text-[11px]">就绪</Badge>
              <div class="flex-1" />
              <span class="text-[11px] text-muted-foreground">{{ view.config.model }}</span>
              <Switch
                :model-value="view.config.enabled"
                @update:model-value="
                  v =>
                    store
                      .saveEngine({ ...view.config, enabled: Boolean(v) })
                      .catch(e => toast.error(String(e)))
                "
              />
              <Button
                variant="outline"
                size="sm"
                @click="editingId = editingId === view.config.id ? '' : view.config.id"
              >
                {{ editingId === view.config.id ? '收起' : '编辑' }}
              </Button>
            </div>
            <p v-if="view.issue" class="mt-1.5 flex items-center gap-1.5 text-[12px] text-amber-700 dark:text-amber-300">
              <CircleAlert class="size-3.5 shrink-0" />
              {{ view.issue }}
            </p>
            <div v-if="editingId === view.config.id" class="mt-3">
              <EngineEditor :view="view" @deleted="editingId = ''" />
            </div>
          </div>
          <Separator />
          <div class="space-y-2">
            <Label class="text-[12px]">新增引擎</Label>
            <div class="flex gap-2">
              <Select v-model="presetKey">
                <SelectTrigger class="h-8 w-44 text-[12px]"><SelectValue /></SelectTrigger>
                <SelectContent>
                  <SelectItem v-for="p in ENGINE_PRESETS" :key="p.key" :value="p.key">
                    {{ p.label }}
                  </SelectItem>
                </SelectContent>
              </Select>
              <Input
                v-model="newEngineName"
                class="h-8 flex-1 text-[13px]"
                :placeholder="selectedPreset?.label ?? '引擎名称'"
              />
              <Button size="sm" @click="addEngine">
                <Plus />
                新增
              </Button>
            </div>
            <p v-if="selectedPreset" class="text-[11px] text-muted-foreground">
              {{ selectedPreset.description }}
            </p>
          </div>
        </CardContent>
      </Card>
      <!-- ===== 通用 ===== -->
      <Card>
        <CardHeader class="pb-3">
          <CardTitle class="text-[14px]">通用</CardTitle>
        </CardHeader>
        <CardContent class="space-y-4">
          <div class="flex items-center gap-3">
            <Label class="w-32 shrink-0 text-[12px]">默认目标语言</Label>
            <Select
              :model-value="store.settings?.defaultTarget"
              @update:model-value="v => patch({ defaultTarget: String(v) })"
            >
              <SelectTrigger class="h-8 w-40 text-[12px]"><SelectValue /></SelectTrigger>
              <SelectContent>
                <SelectItem v-for="l in targetLanguages" :key="l.code" :value="l.code">
                  {{ l.label }}
                </SelectItem>
              </SelectContent>
            </Select>
          </div>
          <div class="flex items-center gap-3">
            <Label class="w-32 shrink-0 text-[12px]">默认引擎</Label>
            <Select
              :model-value="store.settings?.defaultEngineId"
              @update:model-value="v => patch({ defaultEngineId: String(v) })"
            >
              <SelectTrigger class="h-8 w-52 text-[12px]"><SelectValue /></SelectTrigger>
              <SelectContent>
                <SelectItem value="auto">自动（按优先级降级）</SelectItem>
                <SelectItem
                  v-for="e in store.engines"
                  :key="e.config.id"
                  :value="e.config.id"
                >
                  {{ e.config.name }}
                </SelectItem>
              </SelectContent>
            </Select>
          </div>
          <div class="flex items-start gap-3">
            <Label class="w-32 shrink-0 pt-0.5 text-[12px]">失败自动降级</Label>
            <div>
              <Switch
                :model-value="store.settings?.autoFallback"
                @update:model-value="v => patch({ autoFallback: Boolean(v) })"
              />
              <p class="mt-1 text-[11px] text-muted-foreground">
                开启后「自动」模式会在某个源失败时尝试下一个；关闭则只用默认引擎。
                <br />无论开关如何，手动指定某个引擎时都不会降级——否则「指定了 A 却拿到 B 的译文」更难排查。
              </p>
            </div>
          </div>
          <div class="flex items-start gap-3">
            <Label class="w-32 shrink-0 pt-0.5 text-[12px]">走代理模块</Label>
            <div>
              <Switch
                :model-value="store.settings?.useProxy"
                @update:model-value="v => patch({ useProxy: Boolean(v) })"
              />
              <p class="mt-1 text-[11px] text-muted-foreground">
                默认关闭。自建 LibreTranslate 在境内、MyMemory 与 DeepSeek 均可直连；
                仅当翻译服务部署在境外或直连被拦截时打开。
              </p>
            </div>
          </div>
        </CardContent>
      </Card>
      <!-- ===== 历史 ===== -->
      <Card v-if="store.settings">
        <CardHeader class="pb-3">
          <CardTitle class="text-[14px]">历史记录</CardTitle>
          <p class="text-[12px] text-muted-foreground">
            搜索走 SQLite FTS5 三元组索引；不足 3 个字符的关键词无法命中该索引，会退回全表扫描
            ——仍然搜得到，只是更慢。
          </p>
        </CardHeader>
        <CardContent class="space-y-4">
          <div class="flex items-start gap-3">
            <Label class="w-32 shrink-0 pt-0.5 text-[12px]">记录历史</Label>
            <div>
              <Switch
                :model-value="store.settings.history.enabled"
                @update:model-value="v => patchHistory({ enabled: Boolean(v) })"
              />
              <p class="mt-1 text-[11px] text-muted-foreground">
                关闭后不再写入新记录，已有记录不受影响。
              </p>
            </div>
          </div>
          <div class="flex items-start gap-3">
            <Label class="w-32 shrink-0 pt-1.5 text-[12px]">保留条数</Label>
            <div>
              <Input
                v-model.number="maxItemsDraft"
                type="number"
                :min="HISTORY_MAX_ITEMS_MIN"
                :max="HISTORY_MAX_ITEMS_MAX"
                step="100"
                class="h-8 w-32 text-[12px]"
                @blur="commitMaxItems"
                @keydown.enter="commitMaxItems"
              />
              <p class="mt-1 text-[11px] text-muted-foreground">
                超出后按时间淘汰最旧的非收藏记录（{{ HISTORY_MAX_ITEMS_MIN }}–{{ HISTORY_MAX_ITEMS_MAX }}）。
                收藏条目不占这个额度，收藏得足够多时总占用会超过上限。
              </p>
            </div>
          </div>
        </CardContent>
      </Card>
      <!-- ===== 提示词模板 ===== -->
      <Card v-if="templates">
        <CardHeader class="pb-3">
          <CardTitle class="text-[14px]">提示词模板</CardTitle>
          <p class="text-[12px] text-muted-foreground">
            <code class="rounded bg-muted px-1">{'{target}'}</code> 会替换为目标语言的自然语言名称，
            <code class="rounded bg-muted px-1">{'{source}'}</code> 为源语言名称。
          </p>
        </CardHeader>
        <CardContent class="space-y-3">
          <div class="space-y-1.5">
            <Label class="text-[12px]">翻译（默认模式）</Label>
            <Textarea v-model="templates.translate" class="min-h-24 text-[12px]" />
            <p v-if="templateWarning(templates.translate)" class="text-[11px] text-amber-700 dark:text-amber-300">
              {{ templateWarning(templates.translate) }}
            </p>
          </div>
          <details class="rounded-md border p-2.5">
            <summary class="cursor-pointer select-none text-[12px] font-medium">
              备用模板：润色 / 解释 / 总结（计划 P3 接入划词弹窗）
            </summary>
            <div class="mt-2 space-y-3">
              <div class="space-y-1.5">
                <Label class="text-[12px]">润色</Label>
                <Textarea v-model="templates.polish" class="min-h-16 text-[12px]" />
              </div>
              <div class="space-y-1.5">
                <Label class="text-[12px]">解释</Label>
                <Textarea v-model="templates.explain" class="min-h-16 text-[12px]" />
              </div>
              <div class="space-y-1.5">
                <Label class="text-[12px]">总结</Label>
                <Textarea v-model="templates.summarize" class="min-h-16 text-[12px]" />
              </div>
            </div>
          </details>
          <Button size="sm" :disabled="!templatesDirty || savingTemplates" @click="saveTemplates">
            <LoaderCircle v-if="savingTemplates" class="animate-spin" />
            <Save v-else />
            保存提示词
          </Button>
        </CardContent>
      </Card>
      <!-- ===== 翻译面板与划词取词 ===== -->
      <Card v-if="store.settings">
        <CardHeader class="pb-3">
          <CardTitle class="text-[14px]">翻译面板</CardTitle>
          <p class="text-[12px] text-muted-foreground">
            按全局快捷键打开翻译面板：自动尝试读取<span class="text-foreground">当前划词</span>与
            <span class="text-foreground">剪贴板首条</span>作为候选，↑↓ 选择、Enter 直接翻译；
            也可以在原文框里手动输入（Enter 翻译，Alt+Enter 换行）。
          </p>
        </CardHeader>
        <CardContent class="space-y-4">
          <div class="flex items-center gap-3">
            <Label class="w-32 shrink-0 text-[12px]">面板快捷键</Label>
            <Input
              v-model="shortcutDraft.panelShortcut"
              class="h-8 w-40 text-[13px]"
              placeholder="Ctrl+2"
            />
            <span class="text-[11px] text-muted-foreground">全局生效；留空禁用</span>
          </div>
          <div class="flex flex-wrap items-center gap-2 pl-[8.75rem]">
            <Button size="sm" :disabled="!shortcutsDirty || applyingShortcuts" @click="applyShortcuts">
              <LoaderCircle v-if="applyingShortcuts" class="animate-spin" />
              <Save v-else />
              应用快捷键
            </Button>
            <Button variant="outline" size="sm" @click="previewPopup">
              <Sparkles />
              预览面板
            </Button>
            <span class="text-[11px] text-muted-foreground">
              预览用固定样例文本走完整链路，便于确认窗口与翻译都正常
            </span>
          </div>
          <Separator />
          <div class="flex items-start gap-3">
            <Label class="w-32 shrink-0 pt-0.5 text-[12px]">读取当前划词</Label>
            <div>
              <Switch
                :model-value="store.settings.selection.enabled"
                @update:model-value="v => patchSelection({ enabled: Boolean(v) })"
              />
              <p class="mt-1 text-[11px] text-muted-foreground">
                打开面板时尝试读取当前选中的文字作为第一条候选；关闭后仅提供剪贴板候选。
              </p>
            </div>
          </div>
          <div class="flex items-start gap-3">
            <Label class="w-32 shrink-0 pt-0.5 text-[12px]">取词方式</Label>
            <div class="space-y-1">
              <Select
                :model-value="store.settings.selection.mode || 'smart'"
                @update:model-value="v => patchSelection({ mode: String(v) })"
              >
                <SelectTrigger class="h-8 w-56 text-[12px]"><SelectValue /></SelectTrigger>
                <SelectContent>
                  <SelectItem value="smart">智能（UIA 直读优先，失败再模拟复制）</SelectItem>
                  <SelectItem value="compat">兼容（只用模拟 Ctrl+C）</SelectItem>
                  <SelectItem value="clipboard">不取词（仅剪贴板候选）</SelectItem>
                </SelectContent>
              </Select>
              <p class="max-w-xl text-[11px] text-muted-foreground">
                「智能」直接从目标程序的无障碍接口读选区，<span class="text-foreground">不模拟按键、不占用剪贴板</span>，
                因此不受「目标窗口提权」影响；读不到时自动退回兼容方式。
              </p>
            </div>
          </div>
          <div class="flex items-start gap-3">
            <Label class="w-32 shrink-0 pt-0.5 text-[12px]">取词后还原剪贴板</Label>
            <div>
              <Switch
                :model-value="store.settings.selection.restoreClipboard"
                @update:model-value="v => patchSelection({ restoreClipboard: Boolean(v) })"
              />
              <p class="mt-1 max-w-xl text-[11px] text-muted-foreground">
                取词会临时占用剪贴板，还原可保留你原来的内容。注意：只有文本 / 图片 / 文件三种格式
                能被备份还原；若原内容是不支持的格式（例如只含 HTML/RTF），选区文本会留在剪贴板上。
              </p>
            </div>
          </div>
          <div class="flex items-center gap-3">
            <Label class="w-32 shrink-0 text-[12px]">取词字数上限</Label>
            <Input
              :model-value="store.settings.selection.maxChars"
              type="number"
              class="h-8 w-24 text-[13px]"
              @update:model-value="
                v => patchSelection({ maxChars: Math.max(1, Number(v) || 2000) })
              "
            />
            <span class="text-[11px] text-muted-foreground">
              超出直接拒绝并提示，避免误选整篇文档时发一个又慢又费钱的请求
            </span>
          </div>
          <div class="space-y-1.5">
            <Label class="text-[12px]">跳过取词的应用（每行一个进程名）</Label>
            <Textarea v-model="blacklistDraft" class="min-h-20 text-[12px]" spellcheck="false" />
            <p class="text-[11px] text-muted-foreground">
              这些应用里 Ctrl+C 是中断信号，取词时自动跳过。
            </p>
            <Button size="sm" :disabled="!blacklistDirty" @click="saveBlacklist">保存名单</Button>
          </div>
          <p class="rounded-md border bg-muted/30 p-2.5 text-[11px] leading-relaxed text-muted-foreground">
            取不到划词的常见原因：当前没有选中任何文字、目标窗口以管理员权限运行
            （兼容方式下系统会丢弃来自普通权限程序的模拟按键）、终端类应用（已默认跳过）、
            该程序没有暴露选区给无障碍接口（智能方式下会退回兼容方式）。<br />
            兜底路径：任何程序里都可以「选中 → 复制 → 打开翻译面板」，剪贴板首条会作为候选出现。
          </p>
        </CardContent>
      </Card>
      <!-- ===== 截图翻译 ===== -->
      <Card v-if="store.settings">
        <CardHeader class="pb-3">
          <CardTitle class="flex items-center gap-2 text-[14px]">
            <ScanText class="size-4" />
            截图翻译
          </CardTitle>
          <p class="text-[12px] text-muted-foreground">
            在截图覆盖层框选区域后点「翻译选区」，识别结果以非激活悬浮窗展示在选区旁。
          </p>
        </CardHeader>
        <CardContent class="space-y-4">
          <div class="flex items-center gap-3">
            <Label class="w-32 shrink-0 text-[12px]">识别方式</Label>
            <Select
              :model-value="store.settings.screenshot.ocrMode"
              @update:model-value="
                v =>
                  patch({
                    screenshot: { ...store.settings!.screenshot, ocrMode: String(v) }
                  })
              "
            >
              <SelectTrigger class="h-8 w-56 text-[12px]"><SelectValue /></SelectTrigger>
              <SelectContent>
                <SelectItem value="windows">本地 OCR（离线，零成本）</SelectItem>
                <SelectItem value="vision">视觉模型直译（质量更高，需图像模型）</SelectItem>
              </SelectContent>
            </Select>
          </div>
          <p
            v-if="store.settings.screenshot.ocrMode === 'vision'"
            class="rounded-md border bg-muted/30 p-2.5 text-[11px] leading-relaxed text-muted-foreground"
          >
            视觉直译会把截图上传给所选引擎：请在引擎设置中勾选「支持图像输入」并确认该模型支持图像。
            识别与翻译一步完成，对表格、菜单等复杂排版效果更好。
          </p>
          <template v-else>
            <div class="flex items-center gap-3">
              <Label class="w-32 shrink-0 text-[12px]">识别语言</Label>
              <Input
                :model-value="store.settings.screenshot.ocrLang"
                class="h-8 w-40 text-[13px]"
                placeholder="auto"
                @update:model-value="
                  v =>
                    patch({
                      screenshot: {
                        ...store.settings!.screenshot,
                        ocrLang: String(v) || 'auto'
                      }
                    })
                "
              />
              <Button variant="outline" size="sm" :disabled="store.ocrLanguagesLoading" @click="store.loadOcrLanguages()">
                <LoaderCircle v-if="store.ocrLanguagesLoading" class="animate-spin" />
                {{ store.ocrLanguagesLoading ? '读取中…' : '可用语言' }}
              </Button>
            </div>
            <p class="pl-[8.75rem] text-[11px] text-muted-foreground">
              auto 跟随系统语言配置；也可填 BCP-47 标签（如 en-US、ja）。
            </p>
            <p
              v-if="store.ocrLanguagesError"
              class="rounded-md border border-destructive/40 bg-destructive/5 p-2.5 text-[11px] leading-relaxed text-destructive"
            >
              {{ store.ocrLanguagesError }}
            </p>
            <p
              v-else-if="store.ocrLanguages"
              class="rounded-md border bg-muted/30 p-2.5 text-[11px] leading-relaxed text-muted-foreground"
            >
              <span class="text-foreground">系统已装 {{ store.ocrLanguages.length }} 个 OCR 语言包：</span>
              {{ store.ocrLanguages.join('、') || '（无）' }}
              <br />缺语言时，在系统「设置 → 时间和语言 → 语言和区域」添加并勾选「文本识别」。
            </p>
          </template>
          <div class="flex items-start gap-3">
            <Label class="w-32 shrink-0 pt-0.5 text-[12px]">自动翻译</Label>
            <div>
              <Switch
                :model-value="store.settings.screenshot.autoTranslate"
                @update:model-value="
                  v =>
                    patch({
                      screenshot: {
                        ...store.settings!.screenshot,
                        autoTranslate: Boolean(v)
                      }
                    })
                "
              />
              <p class="mt-1 max-w-xl text-[11px] text-muted-foreground">
                关闭后框选只做识别，译文需在悬浮窗手动触发。
              </p>
            </div>
          </div>
        </CardContent>
      </Card>
    </div>
  </div>
 </template>
@@ -0,0 +1,467 @@
 <script setup lang="ts">
 import { computed, nextTick, onMounted, onUnmounted, ref } from 'vue'
 import { toast } from 'vue-sonner'
 import {
  ArrowLeftRight,
  CircleAlert,
  Columns2,
  Copy,
  LoaderCircle,
  Sparkles,
  Square
 } from '@lucide/vue'
 import { useTranslateStore } from '@/stores/translateStore'
 import { labelOf, orderedLanguages, promptNameOf, resolveTargetLabel } from '@/lib/translate/languages'
 import { ERROR_HINTS } from '@/types/translate'
 import { copyToClipboard, StreamSession } from '@/lib/translate/api'
 import { Button } from '@/components/ui/button'
 import { Badge } from '@/components/ui/badge'
 import { ScrollArea } from '@/components/ui/scroll-area'
 import { Separator } from '@/components/ui/separator'
 import { Textarea } from '@/components/ui/textarea'
 import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
 } from '@/components/ui/select'
 const store = useTranslateStore()
 /** 源语言可含「自动检测」，目标语言不能 */
 const sourceLanguages = computed(() => orderedLanguages(true))
 const targetLanguages = computed(() => orderedLanguages(false))
 /** 无可用引擎时的引导（比让用户点下去才报错要好） */
 const showEngineWarning = computed(
  () => !store.loading && store.engines.length > 0 && store.usableEngines.length === 0
 )
 /** 对比面板：与右侧单引擎结果并存（左列 = 输入 + 对比，右列 = 当前引擎译文） */
 const showCompare = ref(false)
 const comparing = computed(() => store.comparing)
 function toggleCompare() {
  if (showCompare.value) {
    showCompare.value = false
    return
  }
  showCompare.value = true
  void store.compare()
 }
 const errorHint = computed(() =>
  store.lastError ? ERROR_HINTS[store.lastError.kind] : ''
 )
 /** 回车翻译：单行输入是主用法（与取词弹窗一致）；Alt+Enter / Shift+Enter 换行 */
 function onKeydown(e: KeyboardEvent) {
  if (e.key !== 'Enter') return
  if (e.altKey) {
    // Alt+Enter：在光标处插入换行（textarea 默认行为不含 Alt 变体）
    e.preventDefault()
    const el = e.target as HTMLTextAreaElement
    const start = el.selectionStart ?? store.sourceText.length
    const end = el.selectionEnd ?? start
    store.sourceText = store.sourceText.slice(0, start) + '\n' + store.sourceText.slice(end)
    void nextTick(() => {
      el.selectionStart = el.selectionEnd = start + 1
    })
    return
  }
  // Shift+Enter：textarea 默认行为即换行，直接放行
  if (e.shiftKey) return
  e.preventDefault()
  if (streaming.value) stopStream()
  else runStreamed()
 }
 // ===== 流式输出 =====
 // 主面板的翻译动作在组件内走 StreamSession：流式文本只属于当前视图，
 // Done 时回写 store.result（供复制与引擎信息展示），历史仍由后端统一记录。
 const streaming = ref(false)
 const streamText = ref('')
 let session: StreamSession | null = null
 function runStreamed() {
  const text = store.sourceText.trim()
  if (!text || streaming.value) return
  store.normalizeDirection()
  streaming.value = true
  streamText.value = ''
  store.result = null
  store.lastError = null
  void session?.start({
    text,
    from: store.fromLang,
    to: store.toLang,
    toLabel: resolveTargetLabel(store.toLang),
    fromLabel: promptNameOf(store.fromLang),
    engineId: store.engineId,
    mode: 'translate',
    via: 'manual'
  })
 }
 function stopStream() {
  session?.stop()
  streaming.value = false
 }
 onMounted(async () => {
  const created = new StreamSession({
    onChunk: delta => {
      streamText.value += delta
    },
    onDone: r => {
      store.result = r
      streamText.value = ''
      streaming.value = false
    },
    onError: e => {
      store.lastError = e
      streamText.value = ''
      streaming.value = false
    }
  })
  session = created
  // 监听必须先于任何请求注册：注册晚于 start 会整批丢掉事件，
  // 表现为「历史里有译文、界面上一片空白」。
  await created.init()
 })
 onUnmounted(() => {
  session?.dispose()
  session = null
 })
 async function copyResult() {
  const ok = await store.copyResult()
  if (ok) toast.success('译文已复制')
  else toast.error('复制失败')
 }
 async function copyText(text: string) {
  try {
    await copyToClipboard(text)
    toast.success('已复制')
  } catch (e) {
    toast.error(String(e))
  }
 }
 // ===== 双栏滚动同步（与取词弹窗同一套比例映射） =====
 const sourceWrapRef = ref<HTMLElement | null>(null)
 const targetCardRef = ref<HTMLElement | null>(null)
 /** 抑制标志：程序化设置 scrollTop 会再次触发 scroll 事件，不同步回自己 */
 let syncingScroll = false
 function sourceTextarea(): HTMLTextAreaElement | null {
  return sourceWrapRef.value?.querySelector('textarea') ?? null
 }
 /** 译文卡的 ScrollArea 视口（真正的滚动容器） */
 function targetViewport(): HTMLElement | null {
  return (
    targetCardRef.value?.querySelector('[data-slot="scroll-area-viewport"]') as HTMLElement
  ) ?? null
 }
 /** 行高：两侧字号/行距一致（同 leading-relaxed），行高相同才谈得上整行对齐 */
 function lineHeightOf(el: HTMLElement): number {
  const v = parseFloat(getComputedStyle(el).lineHeight)
  return Number.isFinite(v) && v > 0 ? v : 20
 }
 /**
 * 行级对齐的滚动同步：把源侧滚动位置换算成「整行行数」，按两侧总行数比例映射，
 * 再落到目标侧整行边界（顶部不切半行）。两侧换行一致时即逐行精确对齐；
 * 不一致时按行数比例，比纯像素比例更贴合译文对齐习惯。
 *
 * 抑制窗口用 rAF 而非定时器：程序化赋值引发的回声 scroll 事件在 rAF 前送达、
 * 一帧内即解除抑制——原先 80ms 定时器会把紧随其后的用户滚动也吞掉，产生抽搐感。
 */
 function syncScroll(from: HTMLElement, to: HTMLElement) {
  if (syncingScroll) return
  const fromMax = from.scrollHeight - from.clientHeight
  const toMax = to.scrollHeight - to.clientHeight
  if (toMax <= 0) return
  const lineH = lineHeightOf(from)
  const fromLines = Math.max(1, Math.round(fromMax / lineH))
  const toLines = Math.max(1, Math.round(toMax / lineH))
  const scrolled = fromMax > 0 ? Math.round(from.scrollTop / lineH) : 0
  const target = Math.min(toMax, Math.round((scrolled / fromLines) * toLines) * lineH)
  if (Math.abs(to.scrollTop - target) < 1) return
  syncingScroll = true
  to.scrollTop = target
  window.requestAnimationFrame(() => {
    syncingScroll = false
  })
 }
 function onSourceScroll(e: Event) {
  const to = targetViewport()
  if (to) syncScroll(e.target as HTMLElement, to)
 }
 /** 只响应译文视口本身的滚动：嵌套滚动区（错误详情 pre 等）滚动不参与同步 */
 function onTargetScroll(e: Event) {
  const ta = sourceTextarea()
  if (!ta) return
  if (e.target !== targetViewport()) return
  syncScroll(e.target as HTMLElement, ta)
 }
 </script>
 <template>
  <div class="flex h-full min-h-0 flex-col">
    <div class="flex shrink-0 flex-wrap items-center gap-2 pb-3">
      <Select v-model="store.fromLang">
        <SelectTrigger class="h-8 w-32 text-[12px]"><SelectValue /></SelectTrigger>
        <SelectContent>
          <SelectItem v-for="l in sourceLanguages" :key="l.code" :value="l.code">
            {{ l.label }}
          </SelectItem>
        </SelectContent>
      </Select>
      <Button
        variant="ghost"
        size="icon-sm"
        :disabled="store.fromLang === 'auto'"
        :title="store.fromLang === 'auto' ? '自动检测时无法互换' : '互换源与目标语言'"
        @click="store.swapLanguages()"
      >
        <ArrowLeftRight />
      </Button>
      <Select v-model="store.toLang">
        <SelectTrigger class="h-8 w-32 text-[12px]"><SelectValue /></SelectTrigger>
        <SelectContent>
          <SelectItem v-for="l in targetLanguages" :key="l.code" :value="l.code">
            {{ l.label }}
          </SelectItem>
        </SelectContent>
      </Select>
      <Separator orientation="vertical" class="mx-1 h-5" />
      <Select v-model="store.engineId">
        <SelectTrigger class="h-8 w-44 text-[12px]"><SelectValue /></SelectTrigger>
        <SelectContent>
          <SelectItem value="auto">自动（按优先级降级）</SelectItem>
          <SelectItem v-for="e in store.engines" :key="e.config.id" :value="e.config.id">
            {{ e.config.name }}{{ e.ready ? '' : '（未就绪）' }}
          </SelectItem>
        </SelectContent>
      </Select>
      <div class="flex-1" />
      <span class="text-[12px] text-muted-foreground tabular-nums">
        {{ store.sourceText.length }} 字符
      </span>
      <Button
        variant="ghost"
        size="sm"
        :disabled="!store.sourceText"
        @click="store.clear()"
      >
        清空
      </Button>
      <Button
        variant="outline"
        size="sm"
        :disabled="!store.sourceText || comparing"
        :title="`把这句并发发给 ${store.usableEngines.length} 个就绪引擎`"
        @click="toggleCompare()"
      >
        <Columns2 v-if="!comparing" />
        <LoaderCircle v-else class="animate-spin" />
        对比
      </Button>
      <Button
        v-if="streaming"
        variant="destructive"
        size="sm"
        @click="stopStream()"
      >
        <Square />
        停止
      </Button>
      <Button v-else size="sm" :disabled="!store.canRun" @click="runStreamed()">
        <Sparkles />
        翻译
      </Button>
    </div>
    <div v-if="showEngineWarning" class="mb-3 shrink-0 rounded-lg border border-amber-300/60 bg-amber-50 px-3 py-2 text-[12px] text-amber-900 dark:bg-amber-950/30 dark:text-amber-200">
      <div class="flex items-start gap-2">
        <CircleAlert class="mt-0.5 size-3.5 shrink-0" />
        <span>
          还没有可用的翻译引擎。请到「设置」页填写引擎的 API Key，或新增一个引擎实例。
        </span>
      </div>
    </div>
    <div class="grid min-h-[26rem] flex-1 grid-cols-2 gap-3">
      <div class="flex h-full min-h-0 flex-col gap-3">
        <div ref="sourceWrapRef" class="flex min-h-0 flex-1">
          <Textarea
            v-model="store.sourceText"
            class="h-full w-full resize-none leading-relaxed [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
            placeholder="输入或粘贴要翻译的内容…&#10;&#10;Enter 翻译 · Alt+Enter / Shift+Enter 换行"
            @keydown="onKeydown"
            @scroll="onSourceScroll"
          />
        </div>
        <!-- 多引擎并排对比 -->
        <div
          v-if="showCompare"
          class="min-h-0 flex-[1.2] overflow-hidden rounded-lg border bg-card"
        >
          <div class="flex items-center gap-2 border-b px-3 py-2">
            <span class="text-[12px] font-medium">多引擎对比</span>
            <span class="text-[11px] text-muted-foreground">
              {{ comparing ? '请求中…' : `${store.compareResults.length} 个引擎` }}
            </span>
            <div class="flex-1" />
            <button
              class="rounded p-1 text-[13px] leading-none text-muted-foreground hover:bg-accent"
              title="收起"
              @click="showCompare = false"
            >
              ×
            </button>
          </div>
          <div class="h-[calc(100%-2.4rem)] overflow-y-auto p-2">
            <p
              v-if="store.compareResults.length === 0"
              class="px-1 py-2 text-[12px] text-muted-foreground"
            >
              {{ comparing ? '正在向各引擎并发请求…' : '点击「对比」开始。' }}
            </p>
            <div v-else class="space-y-2">
              <div
                v-for="entry in store.compareResults"
                :key="entry.engineId"
                class="rounded-md border px-2.5 py-2"
              >
                <div class="flex items-center gap-2">
                  <span class="text-[12px] font-medium">{{ entry.engineName }}</span>
                  <span v-if="entry.latencyMs" class="text-[11px] text-muted-foreground tabular-nums">
                    {{ entry.latencyMs }}ms
                  </span>
                  <div class="flex-1" />
                  <button
                    v-if="entry.text"
                    class="rounded p-1 text-muted-foreground hover:bg-accent"
                    title="复制该译文"
                    @click="copyText(entry.text)"
                  >
                    <Copy class="size-3" />
                  </button>
                </div>
                <p v-if="entry.text" class="mt-1 select-text cursor-text whitespace-pre-wrap break-words text-[12px] leading-relaxed">
                  {{ entry.text }}
                </p>
                <p v-else-if="entry.error" class="mt-1 break-words text-[11px] text-destructive">
                  {{ entry.error.message }}
                </p>
              </div>
            </div>
          </div>
        </div>
      </div>
      <!-- 右：译文（无标题栏；引擎信息与复制按钮在底部，与取词弹窗一致） -->
      <div
        ref="targetCardRef"
        class="flex h-full min-h-0 flex-col overflow-hidden rounded-lg border bg-muted/20"
        @scroll.capture="onTargetScroll"
      >
        <ScrollArea class="min-h-0 flex-1">
          <div class="px-3 py-2">
          <!-- 流式进行中：边到边显示，光标提示仍在输出 -->
          <div
            v-if="streaming"
            class="select-text cursor-text whitespace-pre-wrap break-words text-[13px] leading-relaxed"
          >{{ streamText }}<span class="animate-pulse">▍</span></div>
          <div
            v-else-if="streamText && !store.result"
            class="select-text cursor-text whitespace-pre-wrap break-words text-[13px] text-muted-foreground leading-relaxed"
          >
            {{ streamText }}
          </div>
          <div v-else-if="store.lastError" class="space-y-2 py-1">
            <div class="flex items-center gap-2">
              <Badge variant="destructive" class="text-[11px]">
                {{ store.lastError.kind }}
              </Badge>
              <span class="text-[13px]">{{ store.lastError.message }}</span>
            </div>
            <p v-if="errorHint" class="text-[12px] text-muted-foreground">
              {{ errorHint }}
            </p>
            <details v-if="store.lastError.detail" class="text-[11px] text-muted-foreground">
              <summary class="cursor-pointer select-none">上游原始响应</summary>
              <pre class="mt-1 whitespace-pre-wrap break-all rounded bg-muted/50 p-2">{{ store.lastError.detail }}</pre>
            </details>
          </div>
          <div
            v-else-if="store.result"
            class="select-text cursor-text whitespace-pre-wrap break-words text-[13px] leading-relaxed"
          >
            {{ store.result.text }}
          </div>
          <p v-else class="py-1 text-[13px] text-muted-foreground">
            译文会显示在这里。
          </p>
          </div>
        </ScrollArea>
        <!-- 底部：引擎信息 + 复制（与取词弹窗的底栏一致） -->
        <div
          v-if="store.result || streaming"
          class="flex shrink-0 items-center gap-2 border-t px-3 py-1.5"
        >
          <template v-if="store.result">
            <Badge variant="secondary" class="text-[11px]">{{ store.result.engineName }}</Badge>
            <span
              v-if="store.result.detected"
              class="text-[11px] text-muted-foreground"
            >
              检测：{{ labelOf(store.result.detected) }}
            </span>
            <span class="text-[11px] text-muted-foreground tabular-nums">
              {{ store.result.latencyMs }}ms
            </span>
            <span
              v-if="store.result.usage"
              class="text-[11px] text-muted-foreground tabular-nums"
            >
              {{ store.result.usage.totalTokens }} tokens
            </span>
          </template>
          <span v-else class="text-[11px] text-muted-foreground">流式输出中…</span>
          <div class="flex-1" />
          <Button
            v-if="store.result"
            variant="ghost"
            size="icon-sm"
            title="复制译文"
            @click="copyResult()"
          >
            <Copy />
          </Button>
        </div>
      </div>
    </div>
  </div>
 </template>
@@ -0,0 +1,66 @@
 import type { ModuleConfig } from '@/types/module'
 import type { SearchIndexItem } from '@/stores/searchIndex'
 const searchItems: SearchIndexItem[] = [
  {
    title: '翻译',
    description: '多源翻译与 AI 翻译工作台',
    keywords: ['翻译', '译', 'translate', 'translation', '中英', '互译', '英文'],
    tab: 'workbench'
  },
  {
    title: '翻译引擎设置',
    description: '配置 AI 引擎、Base URL、模型与 API Key',
    keywords: ['引擎', '模型', 'api key', '密钥', 'deepseek', 'openai', 'ollama', '中转'],
    tab: 'settings'
  },
  {
    title: '默认目标语言',
    description: '设置默认翻译到的语言',
    keywords: ['语言', '目标语言', 'target', '中文', '英文', '日语'],
    tab: 'settings'
  },
  {
    title: '自动降级',
    description: '某个引擎失败时自动尝试下一个引擎',
    keywords: ['降级', 'fallback', '容错', '备用源', '自动'],
    tab: 'settings'
  },
  {
    title: '划词翻译',
    description: '选中文字后按快捷键，非激活悬浮窗显示译文',
    keywords: ['划词', '取词', '选中', '快捷键', 'selection', '悬浮窗', '弹窗'],
    tab: 'settings'
  },
  {
    title: '翻译剪贴板',
    description: '复制文字后按快捷键翻译剪贴板内容（终端类应用也能用）',
    keywords: ['剪贴板翻译', '复制翻译', '快捷键', 'clipboard'],
    tab: 'settings'
  },
  {
    title: '截图翻译',
    description: '框选屏幕区域，本地 OCR 或视觉直译后展示译文',
    keywords: ['截图', 'ocr', '识别', '图片翻译', '屏幕翻译', '翻译选区'],
    tab: 'settings'
  },
  {
    title: '翻译历史',
    description: '查看、搜索、收藏与清理翻译记录',
    keywords: ['历史', '记录', '收藏', 'history', '搜索'],
    tab: 'history'
  }
 ]
 export const moduleConfig: ModuleConfig = {
  id: 'translate',
  name: '翻译',
  icon: 'translate',
  description: '多源翻译与 AI 翻译，含划词、截图翻译',
  category: 'tool',
  defaultEnabled: true,
  loader: () => import('./TranslateModule.vue'),
  searchItems,
  // 排在剪贴板（20）之后、截图（30）之前
  order: 25
 }
@@ -31,6 +31,17 @@ export const useModuleTabsStore = defineStore('moduleTabs', () => {
  /** 待跳转 tab（搜索导航设置）：{ moduleId, tab }，模块挂载/已挂载时消费 */
  const pendingTab = ref<{ moduleId: string; tab: string } | null>(null)
  /**
   * 各模块上次停留的 tab（内存记忆）。
   *
   * 模块被切走时组件卸载、`activeTab` 随之丢失，再切回来总是回到第一个 tab——
   * 对「曲库 / 发现音乐 / 设置」这种三级结构的模块尤其别扭。
   * 只做内存记忆（不落盘）：tab 集合可能随版本变化，跨版本恢复旧值反而容易出错。
   */
  const lastTabByModule = ref<Record<string, string>>({})
  /** 当前已注册的模块 id（unregister 时据此保存） */
  let currentModuleId = ''
  /** 设置待跳转 tab（搜索结果点击时调用） */
  const setPendingTab = (moduleId: string, tab: string) => {
    pendingTab.value = { moduleId, tab }
@@ -56,15 +67,30 @@ export const useModuleTabsStore = defineStore('moduleTabs', () => {
  /** 是否显示保存按钮（当前在设置 tab 且注册了保存处理函数） */
  const saveVisible = computed(() => saveHandler.value !== null && activeTab.value === 'settings')
-  /** 模块注册标签（onMounted 时调用） */
+  /**
-  const registerTabs = (tabList: ModuleTab[], current: string) => {
+   * 模块注册标签（onMounted 时调用）。
   * 返回该模块**应当使用**的 tab：优先复用上次停留的（且在当前 tab 集合内），
   * 否则用传入的初始值。调用方若拿到不同值，需同步自己的 activeTab。
   */
  const registerTabs = (moduleId: string, tabList: ModuleTab[], current: string): string => {
    currentModuleId = moduleId
    tabs.value = tabList
-    activeTab.value = current
+    const remembered = lastTabByModule.value[moduleId]
    const restored =
      remembered && tabList.some((t) => t.value === remembered) ? remembered : current
    activeTab.value = restored
    floatingVisible.value = false
    return restored
  }
-  /** 模块注销标签（onUnmounted 时调用） */
+  /**
-  const unregisterTabs = () => {
+   * 模块注销标签（onUnmounted 时调用）。
   * `moduleId` 缺省时用当前注册的模块（保留旧调用点的语义）。
   */
  const unregisterTabs = (moduleId?: string) => {
    const id = moduleId ?? currentModuleId
    if (id && activeTab.value) lastTabByModule.value[id] = activeTab.value
    currentModuleId = ''
    tabs.value = []
    activeTab.value = ''
    floatingVisible.value = false
@@ -119,6 +119,8 @@ const logger = createLogger('music')
 export const useMusicStore = defineStore('music', () => {
  const settings = ref<MusicSettings | null>(null)
  const env = ref<MusicEnvStatus | null>(null)
  /** 环境探测进行中（探测要串行 spawn 4 个子进程，便携 Python 冷启动可达数秒） */
  const envLoading = ref(false)
  /** musicdl 已注册的全部搜索源（客户端名） */
  const availableSources = ref<string[]>([])
@@ -136,23 +138,118 @@ export const useMusicStore = defineStore('music', () => {
  const installError = ref('')
  let progressUnlisten: UnlistenFn | null = null
-  async function init() {
+  /**
   * 幂等初始化。
   *
   * 标题栏音乐控件与音乐模块各会调用一次：不做守卫就会**重复**执行
   * `restoreTasks()` 与 `refreshEnv()`，而后者每次要串行 spawn 4 个探测子进程
   * （便携 Python 冷启动可达数秒）——表现为每次进入音乐模块都重新探测一遍环境、
   * 环境面板反复闪「检测中」。失败时清空在途 Promise，允许下次重试。
   */
  let initPromise: Promise<void> | null = null
  function init(): Promise<void> {
    if (initPromise) return initPromise
    initPromise = (async () => {
      restoreTasks()
      await Promise.all([loadSettings(), refreshEnv()])
    })().catch((e) => {
      initPromise = null
      throw e
    })
    return initPromise
  }
  /**
   * QQ 音乐 Cookie 存放在**系统凭据管理器**（Rust 侧 `music_secret_*`），
   * 不再明文写进 settings.json —— 与 WebDAV 密码、飞牛 token 保持同一安全姿态。
   * 这里保留内存副本供同步读取（`currentQqCookie()`）。
   */
  const QQ_COOKIE_KEY = 'music-qq-cookie'
  const qqCookie = ref('')
  let qqCookieTimer: ReturnType<typeof setTimeout> | null = null
  async function loadQqCookie() {
    try {
      const r = (await invoke('music_secret_get', { key: QQ_COOKIE_KEY })) as { value: string | null }
      qqCookie.value = r?.value ?? ''
    } catch (e) {
      // 凭据库不可用：退回 settings 里的明文（若历史版本留下过）
      logger.error(`读取 QQ 音乐 Cookie 失败: ${e}`)
      qqCookie.value = settings.value?.qqCookie ?? ''
    }
  }
  /** 写入 QQ 音乐 Cookie（节流落盘；空串表示清除） */
  function setQqCookie(v: string) {
    qqCookie.value = v.trim()
    if (qqCookieTimer) clearTimeout(qqCookieTimer)
    qqCookieTimer = setTimeout(() => {
      qqCookieTimer = null
      invoke('music_secret_set', { key: QQ_COOKIE_KEY, value: qqCookie.value }).catch((e) =>
        logger.error(`保存 QQ 音乐 Cookie 失败: ${e}`)
      )
    }, 600)
  }
  /**
   * 一次性迁移：旧版本把 Cookie 明文写在 `settings.qqCookie`。
   * 先写凭据库成功，再清字段并落盘；写失败就保留明文（功能优先，不丢用户配置）。
   */
  async function migrateQqCookie() {
    const legacy = settings.value?.qqCookie?.trim() ?? ''
    if (!legacy) {
      await loadQqCookie()
      return
    }
    try {
      await invoke('music_secret_set', { key: QQ_COOKIE_KEY, value: legacy })
      qqCookie.value = legacy
      if (settings.value) {
        settings.value.qqCookie = ''
        await saveSettings()
      }
    } catch (e) {
      logger.error(`迁移 QQ 音乐 Cookie 到凭据管理器失败（保留明文）: ${e}`)
      qqCookie.value = legacy
    }
  }
  /**
   * 最近一次与后端一致的设置快照（JSON）。
   * `musicGetSettings()` 读回来的对象会被 `watch(store.settings, {deep:true})` 观察到，
   * 若不比对就会把刚读到的内容原样写回——既是无谓写盘，又可能用旧快照覆盖后端新状态。
   */
  let syncedSettingsJson = ''
  async function loadSettings() {
    settings.value = await commands.musicGetSettings()
    syncedSettingsJson = settings.value ? JSON.stringify(settings.value) : ''
    // Cookie 的真身在系统凭据管理器：先做一次性迁移，再从凭据库读回内存
    await migrateQqCookie()
  }
  /** 相对上次读取/保存是否有真实改动（供 debounce 保存前判断，避免回写快照） */
  function settingsChanged(): boolean {
    if (!settings.value) return false
    return JSON.stringify(settings.value) !== syncedSettingsJson
  }
  /** 保存设置（调用方先修改 settings 再调用；前端用 400ms debounce） */
  async function saveSettings() {
    if (!settings.value) return
    await commands.musicSaveSettings(settings.value)
    syncedSettingsJson = JSON.stringify(settings.value)
  }
  async function refreshEnv() {
    // 探测期间 `env` 可能是旧的/为 null，UI 必须靠这个标志区分
    // 「正在检测」与「确实未安装」，否则冷启动会短暂误报「未安装」并诱导用户重装
    envLoading.value = true
    try {
      env.value = await commands.musicEnvStatus()
    } finally {
      envLoading.value = false
    }
  }
  async function loadSources() {
@@ -169,11 +266,41 @@ export const useMusicStore = defineStore('music', () => {
    return (await invoke('music_ping')) as MusicPingPayload
  }
  /**
   * 音乐请求（搜索 / 解析 / 下载）该使用的代理地址。
   *
   * 未开「搜索/下载走代理」时返回**空串**，桥接侧据此强制直连并屏蔽系统代理——
   * 这一点必须显式传：requests 缺省会读系统代理（Windows 下连注册表的
   * Internet Settings 都会读），用户一开代理模块的系统代理，搜索就会被静默
   * 送进 mihomo，国内源无结果。
   */
  function currentProxyUrl(): string {
    if (!settings.value?.useProxy) return ''
    const port = useProxyStore().settings?.mixedPort
    return port ? `http://127.0.0.1:${port}` : ''
  }
  /**
   * QQ 音乐 Cookie（可选，用户在设置里粘贴）。
   * 用于：解析需要登录的歌单（含自己的隐私歌单）、VIP 音质（无损）下载。
   * 桥接侧只在配置了 Cookie 时注入（musicdl 的既有逻辑：配了 Cookie 的源
   * 会跳过第三方解析源，全部走官方接口）。
   * 真身存在系统凭据管理器，这里只返回内存副本。
   */
  function currentQqCookie(): string {
    return qqCookie.value.trim()
  }
  async function search(keyword: string, sources: string[]) {
    searching.value = true
    searchError.value = ''
    try {
-      const v = (await invoke('music_search', { keyword, sources })) as MusicSearchPayload
+      const v = (await invoke('music_search', {
        keyword,
        sources,
        proxyUrl: currentProxyUrl(),
        qqCookie: currentQqCookie()
      })) as MusicSearchPayload
      results.value = v.results ?? {}
      resultTotal.value = v.total ?? 0
      searched.value = true
@@ -194,7 +321,12 @@ export const useMusicStore = defineStore('music', () => {
    parsing.value = true
    parseError.value = ''
    try {
-      const v = (await invoke('music_parse_playlist', { url, sources })) as {
+      const v = (await invoke('music_parse_playlist', {
        url,
        sources,
        proxyUrl: currentProxyUrl(),
        qqCookie: currentQqCookie()
      })) as {
        songs: MusicSong[]
        count: number
      }
@@ -376,7 +508,12 @@ export const useMusicStore = defineStore('music', () => {
    if (!song) return null
    if (song.downloadUrl) return song
    if (!song.rawSearch) return null
-    const v = (await invoke('music_resolve', { song, quality })) as {
+    const v = (await invoke('music_resolve', {
      song,
      quality,
      proxyUrl: currentProxyUrl(),
      qqCookie: currentQqCookie()
    })) as {
      songs: (MusicSong | null)[]
    }
    const resolved = v.songs?.[0]
@@ -412,7 +549,12 @@ export const useMusicStore = defineStore('music', () => {
      const lazy = songs.filter((s) => !s.downloadUrl && s.rawSearch)
      if (lazy.length > 0) {
        try {
-          const v = (await invoke('music_resolve', { songs: lazy, quality })) as {
+          const v = (await invoke('music_resolve', {
            songs: lazy,
            quality,
            proxyUrl: currentProxyUrl(),
            qqCookie: currentQqCookie()
          })) as {
            songs: (MusicSong | null)[]
          }
          // 返回与输入顺序对齐，失败位为 null
@@ -479,6 +621,7 @@ export const useMusicStore = defineStore('music', () => {
        lyric: opts.lyric,
        cover: opts.cover,
        proxyUrl: opts.proxyUrl,
        qqCookie: currentQqCookie(),
        maxConcurrent: opts.maxConcurrent,
        quality
      })
@@ -526,17 +669,11 @@ export const useMusicStore = defineStore('music', () => {
    }
    const s = settings.value
    if (!s) return
    // 代理 URL：惰性读取代理模块设置（避免 store 初始化时跨 store 依赖）
    let proxy = ''
    if (s.useProxy) {
      const port = useProxyStore().settings?.mixedPort
      proxy = port ? `http://127.0.0.1:${port}` : ''
    }
    await startDownload(task.songsData, {
      savedir: s.savedir,
      lyric: s.lyricDownload,
      cover: s.coverDownload,
-      proxyUrl: proxy,
+      proxyUrl: currentProxyUrl(),
      engine: s.downloadEngine,
      maxConcurrent: s.maxConcurrent,
      // 沿用原任务的目标音质（"最高" 存为空串），而不是当前默认音质
@@ -544,32 +681,59 @@ export const useMusicStore = defineStore('music', () => {
    })
  }
-  async function installRuntime() {
+  /** 挂上运行时安装 / 更新的进度监听（两个动作共用同一条事件通道） */
-    if (installing.value) return
+  async function attachRuntimeProgress() {
-    installing.value = true
+    if (progressUnlisten) return
-    installError.value = ''
+    progressUnlisten = await listen<MusicInstallProgress>('music-runtime-install-progress', (e) => {
    installProgress.value = null
    if (!progressUnlisten) {
      progressUnlisten = await listen<MusicInstallProgress>(
        'music-runtime-install-progress',
        (e) => {
      installProgress.value = e.payload
    })
  }
-      )
+
-    }
+  /** 动作收尾：摘掉监听。失败原因留下面板展示；进度停在最后事件值需清掉，避免误导 */
-    try {
+  function detachRuntimeProgress(err: unknown) {
      env.value = await commands.musicInstallRuntime()
    } catch (e) {
      // 保留失败原因供设置页面板展示；进度停在最后事件值，需清掉避免误导
      installError.value = typeof e === 'string' ? e : JSON.stringify(e)
      throw e
    } finally {
    installing.value = false
    installError.value = err ? (typeof err === 'string' ? err : JSON.stringify(err)) : ''
    if (progressUnlisten) {
      progressUnlisten()
      progressUnlisten = null
    }
  }
  async function installRuntime() {
    if (installing.value) return
    installing.value = true
    installError.value = ''
    installProgress.value = null
    try {
      await attachRuntimeProgress()
      env.value = await commands.musicInstallRuntime()
    } catch (e) {
      detachRuntimeProgress(e)
      throw e
    }
    detachRuntimeProgress(null)
  }
  /**
   * 把 musicdl 对齐到本应用锁定的版本（`force = true` 为强制重装）。
   *
   * 存在的理由：安装流程的闸门是「能否 import」，不看版本，所以仅升级应用
   * 不会让已装环境换版本；版本不一致时必须由用户显式触发这次更新。
   * 只升到锁定版本，不升 PyPI 最新（bridge.py 的补丁与 musicdl 版本强耦合）。
   */
  async function updateMusicdl(force = false) {
    if (installing.value) return
    installing.value = true
    installError.value = ''
    installProgress.value = null
    try {
      await attachRuntimeProgress()
      env.value = (await invoke('music_update_musicdl', { force })) as MusicEnvStatus
    } catch (e) {
      detachRuntimeProgress(e)
      throw e
    }
    detachRuntimeProgress(null)
  }
  function cancelInstall() {
@@ -583,6 +747,9 @@ export const useMusicStore = defineStore('music', () => {
  return {
    settings,
    env,
    envLoading,
    qqCookie,
    setQqCookie,
    availableSources,
    searching,
    searchError,
@@ -597,10 +764,13 @@ export const useMusicStore = defineStore('music', () => {
    tasks,
    init,
    loadSettings,
    settingsChanged,
    saveSettings,
    refreshEnv,
    loadSources,
    pingBridge,
    currentProxyUrl,
    currentQqCookie,
    search,
    parsePlaylist,
    resolveSong,
@@ -609,6 +779,7 @@ export const useMusicStore = defineStore('music', () => {
    removeTask,
    redownloadTask,
    installRuntime,
    updateMusicdl,
    cancelInstall,
    stopBridge
  }
@@ -0,0 +1,323 @@
 import { defineStore } from 'pinia'
 import { ref, watch } from 'vue'
 import { toast } from 'vue-sonner'
 import { invoke } from '@tauri-apps/api/core'
 import { useMusicStore, type MusicDownloadTask, type MusicSong } from '@/stores/musicStore'
 import { useFeiniuStore } from '@/stores/feiniuStore'
 import { createLogger } from '@/lib/logger'
 const logger = createLogger('music-upload')
 /** feiniu_scan_local 返回的本地音频条目（只取用到的字段） */
 interface LocalAudioFile {
  path: string
  /** 文件名（不含扩展名） */
  name?: string
  /** 音频标签里的标题 */
  title?: string
  /** 修改时间（Unix 秒） */
  mtim?: number
 }
 /**
 * 下载 → 上传飞牛的记账中枢。
 *
 * 为什么必须是一个 **store** 而不是组件内逻辑：
 * 这套记账是「任务完成时触发上传」的**唯一触发点**，一旦放在 `MusicModule.vue`
 * 的 setup 里，用户下载途中切走音乐模块（组件卸载 → watcher 被销毁）就永远不会触发——
 * 表现为「下载到飞牛」下载完了却没上传、本地副本也没删，自动上传同样静默失效。
 * Pinia 的 setup store 活在独立 effect scope 中，watcher 不随组件卸载而销毁。
 *
 * 记账粒度到**任务**（而非「最近 N 分钟的文件」）：
 * 任务行上的「上传到飞牛曲库」只应传它自己下载的文件，
 * 否则会把别的任务、甚至用户手动放进下载目录的文件一起传上去。
 *
 * 所有上传走**同一条串行队列**：`feiniu_scan_local` 要遍历整个曲库目录做标签解析，
 * 并发跑两个上传等于并发扫两遍盘，还会让 `uploading` 标志提前归位（按钮状态错乱）。
 */
 export const useMusicUploadStore = defineStore('musicUpload', () => {
  const music = useMusicStore()
  const feiniu = useFeiniuStore()
  /** 行级「下载到飞牛」进行中的 key（`${source}|${index}`），驱动行内 spinner */
  const rowUploadingKeys = ref<Set<string>>(new Set())
  /** 已上传过的任务 id：每个任务最多上传一次，避免重复全量上传 */
  const handledTaskIds = new Set<string>()
  /** 「下载到飞牛」的临时任务：完成后上传 → 删本地副本 → 移除记录 */
  const tempTaskIds = new Set<string>()
  /** taskId → 行按钮 spinner 的 key */
  const tempTaskKeys = new Map<string, string>()
  /** 下载目标选「飞牛」的 musicdl 任务：完成后自动上传 */
  const uploadOnDoneTaskIds = new Set<string>()
  /**
   * 初始化完成前不触发自动上传。
   * 由 UI 在 `music.init()`（恢复历史任务）之后调用 `armAfterInit()` 置真，
   * 否则启动时会拿着上一轮已完成的任务重传一遍。
   */
  let armed = false
  function setRowUploading(key: string, on: boolean) {
    const next = new Set(rowUploadingKeys.value)
    if (on) next.add(key)
    else next.delete(key)
    rowUploadingKeys.value = next
  }
  function releaseRowKey(taskId: string) {
    const key = tempTaskKeys.get(taskId)
    tempTaskKeys.delete(taskId)
    if (key) setRowUploading(key, false)
  }
  // ===== 上传串行队列 =====
  const uploadQueue: Array<() => Promise<void>> = []
  let draining = false
  /**
   * 入队一个上传作业并保证串行执行。
   * 队列排空后再扫一遍任务列表：上传期间新完成的任务在这一轮被接上，
   * 因此不需要「跳过并等下一次状态变化」这种会漏单的写法。
   */
  function enqueueUpload(job: () => Promise<void>) {
    uploadQueue.push(job)
    if (draining) return
    draining = true
    void (async () => {
      try {
        while (uploadQueue.length > 0) {
          const next = uploadQueue.shift()
          if (!next) break
          await next().catch((e) => {
            logger.error(`上传作业失败: ${e}`)
            toast.error(`上传到飞牛失败：${e}`)
          })
        }
      } finally {
        draining = false
      }
      resolvePendingUploads()
    })()
  }
  /**
   * 上传某个下载任务产出的音频文件。
   *
   * 匹配策略（从精确到宽松）：
   * 1. 文件名或音频标签标题命中任务内任一歌曲名；
   * 2. 文件名以「歌名 - 」开头也算命中——`bridge.py::_rename_downloaded_files`
   *    在下载完成后会把落盘文件从「歌名 - <标识>.ext」改名成「歌名 - 歌手.ext」；
   * 3. 都不命中时退回「修改时间 ≥ 任务创建时刻」。
   * 所有规则都限定在任务时间之后，因此不会带上历史文件。
   */
  async function uploadTaskFiles(
    task: MusicDownloadTask,
    deleteLocal: boolean
  ): Promise<{ total: number; ok: number; deleted: number }> {
    if (!feiniu.webdavReady) throw new Error('请先在「设置 → 存储与上传」完成 WebDAV 配置')
    // 同步置位：UI 的「上传中」禁用态依赖它
    feiniu.uploading = true
    try {
      // 只列举下载目录（非递归，不解析标签）：musicdl 的落盘位置恒为 savedir
      // （bridge.py `si.work_dir = savedir`）。用 feiniu_scan_local 会递归遍历整个
      // 曲库目录并解析标签——为一次上传扫全库是纯浪费。
      const dir = task.savedir || music.settings?.savedir || ''
      if (!dir) throw new Error('未配置下载目录，无法定位下载产物')
      const r = await invoke<{ items: LocalAudioFile[] }>('feiniu_list_audio_files', { dir })
      const items = r?.items ?? []
      // 任务创建时刻（毫秒）→ 秒，留 5s 余量吸收文件系统时间戳抖动
      const since = task.createdAt / 1000 - 5
      const recent = items.filter((f) => (f.mtim || 0) >= since)
      const names = [
        ...new Set(task.songsData.map((s) => (s.songName ?? '').trim().toLowerCase()).filter(Boolean))
      ]
      const nameSet = new Set(names)
      const byName =
        names.length > 0
          ? recent.filter((f) => {
              const stem = String(f.name ?? '').trim().toLowerCase()
              const title = String(f.title ?? '').trim().toLowerCase()
              if (nameSet.has(stem) || nameSet.has(title)) return true
              return names.some((n) => stem.startsWith(`${n} - `))
            })
          : []
      const list = byName.length > 0 ? byName : recent
      let ok = 0
      let deleted = 0
      for (const f of list) {
        const path = String(f.path)
        const name = path.split(/[\\/]/).pop() || 'music.bin'
        try {
          await feiniu.uploadToFeiniu(path, name)
          ok++
          if (deleteLocal) deleted += await feiniu.deleteLocalMedia(path)
        } catch (e) {
          logger.error(`上传失败 ${name}: ${e}`)
        }
      }
      return { total: list.length, ok, deleted }
    } finally {
      feiniu.uploading = false
    }
  }
  /** 任务行上的「上传到飞牛曲库」：只传该任务下载的文件 */
  function uploadTask(taskId: string) {
    const task = music.tasks.find((t) => t.taskId === taskId)
    if (!task) return
    if (!feiniu.webdavReady) {
      toast.error('请先在「设置 → 存储与上传」完成 WebDAV 配置（地址 / 账号 / 密码 / 目标目录）')
      return
    }
    enqueueUpload(async () => {
      const { total, ok } = await uploadTaskFiles(task, false)
      if (total === 0) toast.info('未找到该任务下载的文件（可能已被移动或删除）')
      else toast.success(`已上传 ${ok}/${total} 首到飞牛曲库`)
    })
  }
  /** 临时任务的收尾：上传 → 删本地副本 → 移除任务记录。失败时保留本地文件与记录供排查。 */
  async function finishTempUpload(taskId: string) {
    const task = music.tasks.find((t) => t.taskId === taskId)
    try {
      if (!task) throw new Error('任务记录已不存在')
      const { total, ok, deleted } = await uploadTaskFiles(task, true)
      const name = task.songs?.[0]?.songName || ''
      if (ok > 0) {
        toast.success(`已保存到飞牛曲库${name ? `：${name}` : ''}`)
        music.removeTask(taskId)
        if (deleted < total) toast.info(`${total - deleted} 个本地副本未能删除（可能被占用）`)
      } else if (total === 0) {
        toast.error('下载完成，但未在下载目录找到新文件——请检查下载目录设置')
      } else {
        throw new Error('上传失败')
      }
    } finally {
      releaseRowKey(taskId)
    }
  }
  /**
   * 单曲「下载到飞牛」：走 musicdl 下载（含引擎侧解析、代理、音质），
   * 任务完成后上传并删除本地副本，最后移除任务记录。
   */
  async function downloadToFeiniu(song: MusicSong, source: string, index: number) {
    const key = `${source}|${index}`
    if (rowUploadingKeys.value.has(key)) return
    if (!feiniu.webdavReady) {
      toast.error('请先在「设置 → 存储与上传」完成 WebDAV 配置（地址 / 账号 / 密码 / 目标目录）')
      return
    }
    const s = music.settings
    if (!s) return
    // Rust 引擎的任务在「下载器」模块管理，本模块拿不到落盘结果
    if (s.downloadEngine === 'rust') {
      toast.error(
        'Rust 引擎的下载任务在「下载器」模块中管理，无法自动回传飞牛曲库。请改用 musicdl 引擎。'
      )
      return
    }
    setRowUploading(key, true)
    try {
      const { engine, skipped, taskId } = await music.startDownload([song], {
        savedir: s.savedir,
        lyric: s.lyricDownload,
        cover: s.coverDownload,
        proxyUrl: s.useProxy ? music.currentProxyUrl() : '',
        engine: s.downloadEngine,
        maxConcurrent: s.maxConcurrent,
        quality: s.defaultDownloadQuality ?? ''
      })
      if (engine === 'rust' || skipped > 0) {
        toast.error(skipped > 0 ? '该歌曲没有可用的下载源' : 'Rust 引擎无法回传飞牛曲库')
        setRowUploading(key, false)
        return
      }
      if (taskId) {
        tempTaskIds.add(taskId)
        tempTaskKeys.set(taskId, key)
      } else {
        setRowUploading(key, false)
      }
    } catch (e) {
      toast.error(`启动下载失败：${e}`)
      setRowUploading(key, false)
    }
  }
  /** 标记「该任务完成后自动上传」（下载目标选了飞牛时调用） */
  function markUploadOnDone(taskId: string) {
    uploadOnDoneTaskIds.add(taskId)
  }
  /** 由 UI 在 music.init() 之后调用一次：把历史已完成任务视为已处理，然后开始接收新任务 */
  function armAfterInit() {
    if (armed) return
    for (const t of music.tasks) if (t.status === 'done') handledTaskIds.add(t.taskId)
    armed = true
  }
  /**
   * 任务状态变化的唯一驱动：
   * - 临时任务（下载到飞牛）完成 → 上传 + 删本地副本 + 移除记录；
   * - 普通任务完成且要求自动上传 → 上传该任务的文件；
   * - 临时任务失败/被取消/被移除 → 释放行内 spinner 并提示。
   *
   * 只负责「发现作业并入队」，并发控制交给串行队列。
   */
  function resolvePendingUploads() {
    if (!armed) return
    const alive = new Set(music.tasks.map((t) => t.taskId))
    for (const id of [...handledTaskIds]) if (!alive.has(id)) handledTaskIds.delete(id)
    for (const t of music.tasks) {
      if (t.status !== 'done') continue
      if (tempTaskIds.has(t.taskId)) {
        // 先摘标记再入队：队列可能同步执行，重复入队会导致同一任务上传两次
        tempTaskIds.delete(t.taskId)
        const id = t.taskId
        enqueueUpload(() => finishTempUpload(id))
        continue
      }
      const wanted = uploadOnDoneTaskIds.has(t.taskId) || feiniu.autoUpload
      if (!wanted || handledTaskIds.has(t.taskId)) continue
      handledTaskIds.add(t.taskId)
      uploadOnDoneTaskIds.delete(t.taskId)
      const task = t
      enqueueUpload(async () => {
        const { total, ok } = await uploadTaskFiles(task, false)
        if (total > 0 && ok > 0) toast.success(`已上传 ${ok}/${total} 首到飞牛曲库`)
      })
    }
    // 临时任务下载失败/被取消：释放行按钮 spinner 与临时标记，避免永久转圈
    for (const t of music.tasks) {
      if (t.status === 'done' || t.status === 'downloading' || t.status === 'cancelling') continue
      if (!tempTaskIds.has(t.taskId)) continue
      tempTaskIds.delete(t.taskId)
      releaseRowKey(t.taskId)
      toast.error(`下载到飞牛失败：${t.errorMessage || '任务未完成，文件保留在本地下载目录'}`)
    }
    // 临时任务记录被手动删除（下载中移除）：同样释放 spinner
    for (const id of [...tempTaskIds]) {
      if (alive.has(id)) continue
      tempTaskIds.delete(id)
      releaseRowKey(id)
    }
  }
  watch(
    () => music.tasks.map((t) => `${t.taskId}:${t.status}`).join('|'),
    resolvePendingUploads
  )
  return {
    rowUploadingKeys,
    uploadTask,
    uploadTaskFiles,
    downloadToFeiniu,
    markUploadOnDone,
    armAfterInit
  }
 })
@@ -0,0 +1,425 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
 import { invoke } from '@tauri-apps/api/core'
 import { createLogger } from '@/lib/logger'
 import {
  copyToClipboard,
  listEngines,
  normalizeTranslateError,
  runTranslate
 } from '@/lib/translate/api'
 // 注意：主面板与弹窗的翻译走 `lib/translate/api.ts` 的 StreamSession（流式），
 // runTranslate 目前只服务于多引擎对比；store 不再持有翻译动作本身。
 import { promptNameOf, resolveTargetLabel } from '@/lib/translate/languages'
 import type {
  EngineTestResult,
  EngineView,
  HistoryItem,
  TranslateEngineConfig,
  TranslateError,
  TranslateResult,
  TranslateSettings
 } from '@/types/translate'
 const logger = createLogger('translate')
 /** 多引擎对比的单条结果 */
 export interface CompareEntry {
  engineId: string
  engineName: string
  text?: string
  latencyMs?: number
  error?: TranslateError
 }
 /**
 * 翻译模块状态。
 *
 * 调用方式说明：P0 阶段用原生 `invoke` 而不是 `@/lib/bindings` 的 `commands.*`——
 * specta 绑定只在 debug 构建启动时重新生成，新增命令在首次 `tauri dev` 之前不存在于
 * bindings.ts。把调用点全部收敛在此处，是为了将来替换成 `commands.*` 时只改这一个文件。
 */
 export const useTranslateStore = defineStore('translate', () => {
  /** 服务端设置（保存后的真源） */
  const settings = ref<TranslateSettings | null>(null)
  /** 引擎实例视图列表（含密钥状态与可用性） */
  const engines = ref<EngineView[]>([])
  const loading = ref(false)
  const result = ref<TranslateResult | null>(null)
  const lastError = ref<TranslateError | null>(null)
  // ===== 输入区状态 =====
  // 刻意放在 store 而不是组件里：模块切换会卸载组件，输入被清空很恼人。
  const sourceText = ref('')
  const fromLang = ref('auto')
  const toLang = ref('zh-Hans')
  const engineId = ref('auto')
  /** 是否已用设置里的默认值填充过输入区（避免每次刷新设置都把用户选择覆盖掉） */
  let inputSeeded = false
  const canRun = computed(() => sourceText.value.trim().length > 0)
  /** 可作为「自动」候选的引擎（已启用且配置完整） */
  const usableEngines = computed(() => engines.value.filter(e => e.config.enabled && e.ready))
  const currentEngineView = computed<EngineView | undefined>(() =>
    engineId.value === 'auto' ? undefined : engines.value.find(e => e.config.id === engineId.value)
  )
  /**
   * 把任意异常规整为 TranslateError。
   * 实现已抽到 `@/lib/translate/api`：取词悬浮窗是独立窗口（不加载 Pinia），
   * 也要用同一套规整逻辑，因此不能留在 store 里。
   */
  const normalizeError = normalizeTranslateError
  /** 读取设置与引擎列表 */
  async function load() {
    loading.value = true
    try {
      const s = await invoke<TranslateSettings>('translate_get_settings')
      settings.value = s
      engines.value = await listEngines()
      if (!inputSeeded) {
        toLang.value = s.defaultTarget || 'zh-Hans'
        engineId.value = s.defaultEngineId || 'auto'
        inputSeeded = true
      }
    } catch (e) {
      logger.error(`读取翻译设置失败：${String(e)}`)
      throw e
    } finally {
      loading.value = false
    }
  }
  /** 幂等初始化（模块挂载与设置页都会调用） */
  async function init() {
    if (settings.value) return
    await load()
  }
  async function persist(next: TranslateSettings) {
    await invoke('translate_save_settings', { settings: next })
    settings.value = next
    engines.value = await listEngines()
  }
  /** 局部更新设置并立即落盘（开关类项用） */
  async function patchSettings(patch: Partial<TranslateSettings>) {
    const base = settings.value
    if (!base) return
    await persist({ ...base, ...patch })
  }
  // ===== 引擎管理 =====
  async function saveEngine(config: TranslateEngineConfig) {
    await invoke('translate_engine_save', { config })
    await load()
  }
  async function deleteEngine(id: string) {
    await invoke('translate_engine_delete', { id })
    if (engineId.value === id) engineId.value = 'auto'
    await load()
  }
  async function setSecret(id: string, apiKey: string) {
    await invoke('translate_secret_set', { id, apiKey })
    await load()
  }
  async function clearSecret(id: string) {
    await invoke('translate_secret_clear', { id })
    await load()
  }
  async function testEngine(config: TranslateEngineConfig): Promise<EngineTestResult> {
    // 走「用草稿配置测试」的命令：用户改了 Base URL / 模型还没保存时，
    // 测的也是最新输入而不是旧配置
    return invoke<EngineTestResult>('translate_engine_test_config', { config })
  }
  async function fetchModels(id: string): Promise<string[]> {
    return invoke<string[]>('translate_engine_models', { id })
  }
  // ===== 翻译 =====
  /** 校正目标语言：源与目标相同时自动互换（避免「中文→中文」这种空转请求） */
  function normalizeDirection() {
    if (fromLang.value !== 'auto' && fromLang.value === toLang.value) {
      const previousTarget = toLang.value
      toLang.value = fromLang.value
      fromLang.value = previousTarget
    }
  }
  function swapLanguages() {
    if (fromLang.value === 'auto') return
    const prevFrom = fromLang.value
    fromLang.value = toLang.value
    toLang.value = prevFrom
  }
  function clear() {
    sourceText.value = ''
    result.value = null
    lastError.value = null
  }
  /** 把译文写到系统剪贴板（主面板与取词悬浮窗共用同一条 Rust 路径） */
  async function copyResult(): Promise<boolean> {
    const text = result.value?.text
    if (!text) return false
    try {
      await copyToClipboard(text)
      return true
    } catch (e) {
      logger.error(`复制译文失败：${String(e)}`)
      return false
    }
  }
  // ===== 划词取词（设置页的验证入口） =====
  /** 按当前设置重新注册全局快捷键（改完快捷键文本后手动触发；保存设置时后端也会自动应用） */
  async function applyShortcuts(): Promise<void> {
    await invoke('translate_apply_shortcuts')
  }
  /**
   * 预览取词悬浮窗（固定样例文本）。
   *
   * 为什么不提供「测试取词」：从应用内触发取词必然失败——前台窗口是本应用自己，
   * Ctrl+C 会落到一个没有选区的窗口上。取词是否可用只能去别的应用按快捷键验证。
   */
  async function previewPopup(): Promise<void> {
    await invoke('translate_preview_popup')
  }
  // ===== 历史 =====
  const historyItems = ref<HistoryItem[]>([])
  const historyQuery = ref('')
  const historyFavOnly = ref(false)
  /** 首屏加载（整页替换） */
  const historyLoading = ref(false)
  /** 追加下一页 */
  const historyLoadingMore = ref(false)
  /** 是否还有未加载的页 */
  const historyHasMore = ref(false)
  /**
   * 每页条数。
   *
   * 刻意不一次拉全：历史是无界增长的数据，单条含原文与译文两段文本，
   * 一次性把上限（默认 2000）条塞进 WebView 再全部挂载，首屏会有可感知的卡顿。
   * 分页后首屏只承担 50 条，其余按需追加。
   */
  const HISTORY_PAGE_SIZE = 50
  /**
   * 请求序号，用于丢弃过期响应。
   *
   * 搜索框是防抖的，但请求本身不串行：快速改关键词时先发的请求可能后返回，
   * 若不加判别就把结果写进 items，会出现「列表与输入框内容对不上」。
   */
  let historyToken = 0
  async function fetchHistoryPage(offset: number): Promise<void> {
    const token = ++historyToken
    // 多取一条只为判断「还有下一页」，省掉一次 count 查询
    const rows = await invoke<HistoryItem[]>('translate_history_list', {
      offset,
      limit: HISTORY_PAGE_SIZE + 1,
      query: historyQuery.value || null,
      favoritedOnly: historyFavOnly.value
    })
    if (token !== historyToken) return
    const hasMore = rows.length > HISTORY_PAGE_SIZE
    const page = hasMore ? rows.slice(0, HISTORY_PAGE_SIZE) : rows
    historyItems.value = offset === 0 ? page : [...historyItems.value, ...page]
    historyHasMore.value = hasMore
  }
  /** 从第一页重新加载。关键词、收藏筛选变化后必须走这条，否则会与旧结果拼接。 */
  async function reloadHistory(): Promise<void> {
    historyLoading.value = true
    try {
      await fetchHistoryPage(0)
    } catch (e) {
      logger.error(`读取历史失败：${String(e)}`)
    } finally {
      historyLoading.value = false
    }
  }
  /** 追加下一页 */
  async function loadMoreHistory(): Promise<void> {
    if (historyLoading.value || historyLoadingMore.value || !historyHasMore.value) return
    historyLoadingMore.value = true
    try {
      await fetchHistoryPage(historyItems.value.length)
    } catch (e) {
      logger.error(`读取更多历史失败：${String(e)}`)
    } finally {
      historyLoadingMore.value = false
    }
  }
  async function toggleHistoryFavorite(id: number): Promise<void> {
    const item = historyItems.value.find(i => i.id === id)
    if (!item) return
    await invoke('translate_history_set_favorited', { id, favorited: !item.favorited })
    item.favorited = !item.favorited
  }
  async function deleteHistoryItem(id: number): Promise<void> {
    await invoke('translate_history_delete', { id })
    historyItems.value = historyItems.value.filter(i => i.id !== id)
  }
  /** 清空全部历史（含收藏）。调用方负责二次确认。 */
  async function clearHistory(): Promise<void> {
    await invoke('translate_history_clear')
    await reloadHistory()
  }
  // ===== 截图翻译 =====
  /** 系统可用的 OCR 语言（BCP-47）。null 表示尚未查询。 */
  const ocrLanguages = ref<string[] | null>(null)
  const ocrLanguagesLoading = ref(false)
  /**
   * 查询失败的文案。
   *
   * 必须暴露给 UI：WinRT 这一路在部分机器上会卡住不返回（后端已用超时兜底），
   * 只写日志的话按钮会「转完圈什么也没发生」，用户无从判断是没装语言包还是接口挂了。
   */
  const ocrLanguagesError = ref<string | null>(null)
  async function loadOcrLanguages(): Promise<void> {
    ocrLanguagesLoading.value = true
    ocrLanguagesError.value = null
    try {
      ocrLanguages.value = await invoke<string[]>('translate_ocr_languages')
    } catch (e) {
      ocrLanguagesError.value = String(e)
      logger.error(`读取 OCR 语言失败：${String(e)}`)
    } finally {
      ocrLanguagesLoading.value = false
    }
  }
  // ===== 多引擎对比 =====
  const comparing = ref(false)
  const compareResults = ref<CompareEntry[]>([])
  /**
   * 并发请求所有就绪引擎，同一句看多个源的结果。
   *
   * 刻意**不写历史**：对比是探索行为，一次会同时产生 N 条结果，全部入库只会污染记录；
   * 用户看到满意的结果后用主面板正常翻译即可入库。
   * 每个引擎独立捕获错误而不是整体失败——一个源挂了不影响看其它源的结果。
   */
  async function compare() {
    const text = sourceText.value.trim()
    const targets = usableEngines.value
    if (!text || comparing.value || targets.length === 0) return
    comparing.value = true
    lastError.value = null
    compareResults.value = []
    try {
      compareResults.value = await Promise.all(
        targets.map(async e => {
          try {
            const r = await runTranslate({
              text,
              from: fromLang.value,
              to: toLang.value,
              toLabel: resolveTargetLabel(toLang.value),
              fromLabel: promptNameOf(fromLang.value),
              engineId: e.config.id,
              mode: 'translate',
              via: null,
              // 对比一次产生 N 条结果，全部入库只会污染记录
              record: false
            })
            return {
              engineId: e.config.id,
              engineName: e.config.name,
              text: r.text,
              latencyMs: r.latencyMs
            }
          } catch (err) {
            return {
              engineId: e.config.id,
              engineName: e.config.name,
              error: normalizeError(err)
            }
          }
        })
      )
    } finally {
      comparing.value = false
    }
  }
  return {
    // 状态
    settings,
    engines,
    loading,
    result,
    lastError,
    sourceText,
    fromLang,
    toLang,
    engineId,
    // 派生
    canRun,
    usableEngines,
    currentEngineView,
    // 动作
    init,
    load,
    persist,
    patchSettings,
    saveEngine,
    deleteEngine,
    setSecret,
    clearSecret,
    testEngine,
    fetchModels,
    swapLanguages,
    normalizeDirection,
    clear,
    copyResult,
    applyShortcuts,
    previewPopup,
    // 历史
    historyItems,
    historyQuery,
    historyFavOnly,
    historyLoading,
    historyLoadingMore,
    historyHasMore,
    reloadHistory,
    loadMoreHistory,
    toggleHistoryFavorite,
    deleteHistoryItem,
    clearHistory,
    loadOcrLanguages,
    ocrLanguages,
    ocrLanguagesLoading,
    ocrLanguagesError,
    comparing,
    compareResults,
    compare,
    normalizeError
  }
 })
@@ -0,0 +1,275 @@
 /**
 * 翻译模块类型定义。
 *
 * 与 Rust 侧 `src-tauri/src/translate/` 的 specta 类型一一对应（字段名 camelCase）。
 *
 * 为什么手写而非直接引用 `@/lib/bindings`：specta 的绑定只在 **debug 构建启动时**
 * 重新生成（见 `lib.rs::export_bindings`），新增命令后需先以 `bun run tauri dev`
 * 跑一次才会出现在 bindings.ts 里。在那之前若直接写 `commands.translateRun`，
 * `vue-tsc` 会因属性不存在而报错。因此 P0 先用原生 `invoke` + 本文件的类型，
 * 待首次 dev 启动生成绑定后，可平滑替换为 `commands.*`（调用点集中在 translateStore）。
 */
 /** 引擎类型：AI（OpenAI 兼容）| 免密钥网络源 | 需签名的云厂商 */
 export type EngineKind = 'ai' | 'free' | 'cloud'
 /** 错误分类。前端据此决定给出「改 Key」「查网络」还是「稍后重试」的提示 */
 export type TranslateErrorKind =
  | 'config'
  | 'auth'
  | 'rateLimit'
  | 'network'
  | 'timeout'
  | 'parse'
  | 'unsupported'
  | 'empty'
  | 'captcha'
  | 'unknown'
 export interface TranslateError {
  kind: TranslateErrorKind
  message: string
  detail: string | null
 }
 export interface TokenUsage {
  promptTokens: number
  completionTokens: number
  totalTokens: number
 }
 export interface TranslateResult {
  text: string
  detected: string | null
  engineId: string
  engineName: string
  latencyMs: number
  usage: TokenUsage | null
 }
 export interface PromptTemplates {
  translate: string
  polish: string
  explain: string
  summarize: string
 }
 export interface TranslateEngineConfig {
  id: string
  name: string
  kind: EngineKind
  preset: string
  enabled: boolean
  priority: number
  baseUrl: string
  model: string
  temperature: number
  maxTokens: number
  timeoutMs: number
  systemPrompt: string
  extraBody: string | null
  /** 是否支持图像输入（截图翻译的视觉直译模式只发给勾选了此项的引擎） */
  supportsVision: boolean
 }
 export interface SelectionSettings {
  enabled: boolean
  /** 打开翻译面板的全局快捷键（默认 Ctrl+2） */
  panelShortcut: string
  mode: string
  restoreClipboard: boolean
  maxChars: number
  blacklist: string[]
 }
 export interface PopupSettings {
  fontSize: number
  opacity: number
  positionPreference: string
  showOriginal: boolean
 }
 export interface ScreenshotSettings {
  ocrMode: string
  ocrLang: string
  autoTranslate: boolean
 }
 export interface HistorySettings {
  enabled: boolean
  maxItems: number
 }
 export interface TranslateSettings {
  version: number
  defaultTarget: string
  defaultEngineId: string
  autoFallback: boolean
  useProxy: boolean
  engines: TranslateEngineConfig[]
  selection: SelectionSettings
  popup: PopupSettings
  screenshot: ScreenshotSettings
  history: HistorySettings
  promptTemplates: PromptTemplates
 }
 /** 引擎实例的前端视图：配置 + 后端派生的密钥/可用性状态 */
 export interface EngineView {
  config: TranslateEngineConfig
  hasApiKey: boolean
  apiKeyMasked: string
  ready: boolean
  issue: string | null
 }
 /** 连通性自检结果（失败也是 Ok 返回，细节在 message/detail 里） */
 export interface EngineTestResult {
  ok: boolean
  latencyMs: number
  message: string
  errorKind: TranslateErrorKind | null
  detail: string | null
 }
 export interface TranslateRunParams {
  text: string
  from?: string | null
  to?: string | null
  toLabel?: string | null
  fromLabel?: string | null
  engineId?: string | null
  mode?: string | null
  /** 记入历史时的来源："manual" | "selection" | "clipboard" | "screenshot" */
  via?: string | null
  /** 是否写入历史，默认 true；对比 / 预览必须传 false */
  record?: boolean | null
 }
 /** 一条翻译历史记录（与 Rust translate::history::HistoryItem 对应） */
 export interface HistoryItem {
  id: number
  ts: number
  fromLang: string
  toLang: string
  engineId: string
  engineName: string
  sourceText: string
  resultText: string
  via: string
  favorited: boolean
  latencyMs: number
 }
 /** 引擎预设：用于「新增引擎」时给出可直接用的起点 */
 export interface EnginePreset {
  key: string
  label: string
  description: string
  template: Partial<TranslateEngineConfig>
 }
 export const ENGINE_PRESETS: EnginePreset[] = [
  {
    key: 'deepseek',
    label: 'DeepSeek',
    description: 'OpenAI 兼容 · 默认引擎，翻译场景用非思考模式，低延迟低成本',
    template: {
      kind: 'ai',
      baseUrl: 'https://api.deepseek.com',
      model: 'deepseek-flash',
      temperature: 0.3,
      maxTokens: 4096,
      timeoutMs: 30000
    }
  },
  {
    key: 'openai',
    label: 'OpenAI',
    description: 'OpenAI 兼容 · 官方端点',
    template: {
      kind: 'ai',
      baseUrl: 'https://api.openai.com/v1',
      model: 'gpt-4o-mini',
      temperature: 0.3,
      maxTokens: 4096,
      timeoutMs: 30000
    }
  },
  {
    key: 'ollama',
    label: 'Ollama（本地）',
    description: '本地推理，数据不出机器；需先在 Ollama 中拉取模型',
    template: {
      kind: 'ai',
      baseUrl: 'http://localhost:11434/v1',
      model: 'qwen2.5:7b',
      temperature: 0.3,
      maxTokens: 4096,
      timeoutMs: 120000
    }
  },
  {
    key: 'proxy-gateway',
    label: '中转 / one-api',
    description: '任意 OpenAI 兼容中转服务，自行填写 Base URL 与模型名',
    template: {
      kind: 'ai',
      baseUrl: '',
      model: '',
      temperature: 0.3,
      maxTokens: 4096,
      timeoutMs: 30000
    }
  },
  {
    key: 'deepl',
    label: 'DeepL（云厂商）',
    description: '质量口碑最好的传统机翻之一。免费 Key 用 api-free 端点，目标语言仅简体中文',
    template: {
      kind: 'cloud',
      preset: 'deepl',
      baseUrl: 'https://api-free.deepl.com/v2',
      model: '',
      timeoutMs: 20000
    }
  },
  {
    key: 'libretranslate',
    label: 'LibreTranslate（自部署）',
    description: '开源自托管翻译服务。需自行填写服务地址；API Key 可选（部署启用密钥校验时需要）',
    template: {
      kind: 'free',
      preset: 'libretranslate',
      baseUrl: '',
      model: '',
      timeoutMs: 20000
    }
  },
  {
    key: 'mymemory',
    label: 'MyMemory（免密钥）',
    description: '国内可直接访问的免密兜底。需显式指定源语言，单次约 500 字节内有免费额度',
    template: {
      kind: 'free',
      preset: 'mymemory',
      baseUrl: '',
      model: '',
      timeoutMs: 15000
    }
  }
 ]
 /** 错误分类 → 用户可执行的动作提示 */
 export const ERROR_HINTS: Record<TranslateErrorKind, string> = {
  config: '检查引擎配置：Base URL、模型名是否填对',
  auth: '检查 API Key 是否正确、账户是否有该模型权限',
  rateLimit: '上游限流，稍后重试即可',
  network: '网络不可达：检查网络连接，若该服务在境外请开启代理模块',
  timeout: '请求超时：可调大该引擎的超时时间',
  parse: '上游返回格式异常，可能是接口变更',
  unsupported: '该引擎类型尚未接入',
  empty: '没有可翻译的内容：请先输入文本',
  captcha: '被上游风控拦截，稍后重试或更换引擎',
  unknown: '未知错误，详见下方原始响应'
 }
@@ -1 +0,0 @@
 {"error":"internal","message":".NET number values such as positive and negative infinity cannot be written as valid JSON. To make it work when using 'JsonSerializer', consider specifying 'JsonNumberHandling.AllowNamedFloatingPointLiterals' (see https://docs.microsoft.com/dotnet/api/system.text.json.serialization.jsonnumberhandling)."}
Author	SHA1	Message	Date
zhongluofeng	f6c1cc250e	翻译模块	2026-09-17 17:32:20 +08:00
zhongluofeng	79c43d5340	ignore更新	2026-09-15 17:30:08 +08:00
zhongluofeng	8f853f7ef3	音乐模块调整	2026-09-15 17:17:16 +08:00
zhongluofeng	4f574cb5fa	调整	2026-09-12 16:29:30 +08:00
zhongluofeng	10a95ddeea	调整	2026-09-12 16:23:48 +08:00
zhongluofeng	069aa58c9f	调整	2026-09-12 16:16:57 +08:00
LFeng	8e940f164b	删除 probe_target.py	2026-09-12 16:00:41 +08:00
LFeng	272246fb61	删除 probe_q.py	2026-09-12 16:00:32 +08:00
LFeng	78d272859c	删除目录「.workbuddy」	2026-09-12 16:00:18 +08:00
LFeng	70d2d4e1d0	删除 music-redesign-mockup.html	2026-09-12 15:59:46 +08:00
LFeng	706b32e1f2	删除 MUSIC_MODULE_REVIEW.md	2026-09-12 15:59:28 +08:00
LFeng	3664120808	删除 MODULE_DEV_GUIDE.md	2026-09-12 15:59:19 +08:00
		`@@ -1 +0,0 @@`
			`{"error":"internal","message":".NET number values such as positive and negative infinity cannot be written as valid JSON. To make it work when using 'JsonSerializer', consider specifying 'JsonNumberHandling.AllowNamedFloatingPointLiterals' (see https://docs.microsoft.com/dotnet/api/system.text.json.serialization.jsonnumberhandling)."}`