翻译模块

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
120 changed files with 29270 additions and 1053 deletions
@@ -7,8 +7,11 @@ yarn-error.log*
 pnpm-debug.log*
 lerna-debug.log*
-# 发布暂存目录
+.trae
 .workbuddy
 temp/
 release_stage/
 musicdl_outputs/
 node_modules
 dist
@@ -1,618 +0,0 @@
 # 模块开发指南
 本文档详细说明 Thing 应用的模块系统架构，帮助开发者快速理解并创建新模块。
 ## 架构概述
 Thing 采用**统一模块注册机制**，每个模块通过 `index.ts` 自描述其全部配置（名称、图标、组件、搜索项、进程配置、生命周期钩子等），由中央注册表 `moduleRegistry` 统一管理。
 ```
 ┌─────────────────────────────────────────────────────┐
 │                    main.ts                          │
 │         import './modules' (触发注册)                │
 └──────────────────────┬──────────────────────────────┘
                       ▼
 ┌─────────────────────────────────────────────────────┐
 │              src/modules/index.ts                    │
 │        聚合入口：导入所有模块配置并注册               │
 └──────────────────────┬──────────────────────────────┘
                       ▼
 ┌─────────────────────────────────────────────────────┐
 │           src/modules/registry.ts                    │
 │     ModuleRegistry 单例：注册 / 查询 / 组件懒加载     │
 └──────┬───────────────┬───────────────┬──────────────┘
       │               │               │
       ▼               ▼               ▼
  App.vue         Sidebar.vue     GeneralSettings
  (组件加载)       (侧边栏导航)     (模块开关管理)
 ```
 ## 核心文件说明
 | 文件 | 职责 |
 |------|------|
 | `src/types/module.ts` | 模块配置类型定义 |
 | `src/modules/registry.ts` | 注册表单例：注册、查询、组件懒加载缓存 |
 | `src/modules/index.ts` | 聚合入口：导入并注册所有模块 |
 | `src/modules/icons.ts` | 模块图标映射表 |
 | `src/modules/<name>/index.ts` | 各模块的配置声明 |
 | `src/modules/<name>/*.vue` | 模块前端组件 |
 ## 模块配置类型
 ```typescript
 // src/types/module.ts
 interface ModuleConfig {
  /** 模块唯一标识（如 'proxy'、'clipboard'） */
  id: string
  /** 显示名称 */
  name: string
  /** 图标标识（对应 icons.ts 中的 key） */
  icon: string
  /** 模块描述（显示在设置界面的模块管理中） */
  description: string
  /** 模块分类 */
  category: 'network' | 'tool' | 'system' | 'media'
  /** 默认是否启用（默认 true） */
  defaultEnabled?: boolean
  /** 是否为内置模块（不可禁用，如设置模块） */
  builtin?: boolean
  /** 懒加载组件的 loader 函数（推荐） */
  loader?: () => Promise<{ default: Component }>
  /** 直接组件引用（内置模块可用，无需懒加载） */
  component?: Component
  /** 全局搜索项 */
  searchItems?: SearchIndexItem[]
  /** 进程配置（需要管理子进程的模块填写） */
  process?: ModuleProcessConfig
  /** 生命周期钩子 */
  lifecycle?: ModuleLifecycle
  /** 排序权重（数值越小越靠前，默认 100） */
  order?: number
 }
 ```
 ## 创建新模块
 ### 第 1 步：创建模块目录
 ```
 src/modules/my-module/
 ├── index.ts              # 模块配置
 └── MyModule.vue          # 前端组件
 ```
 ### 第 2 步：编写模块配置
 ```typescript
 // src/modules/my-module/index.ts
 import type { ModuleConfig } from '@/types/module'
 export const moduleConfig: ModuleConfig = {
  id: 'my-module',
  name: '我的模块',
  icon: 'my-module',           // 需在 icons.ts 中添加映射
  description: '模块功能描述',
  category: 'tool',
  defaultEnabled: true,
  loader: () => import('./MyModule.vue'),
  searchItems: [
    {
      title: '功能名称',
      description: '功能描述',
      keywords: ['关键词1', '关键词2', 'keyword']
    }
  ],
  order: 70
 }
 ```
 ### 第 3 步：注册模块
 在 `src/modules/index.ts` 中添加导入：
 ```typescript
 import { moduleConfig as myModule } from './my-module'
 const allModules: ModuleConfig[] = [
  // ... 已有模块
  myModule
 ]
 moduleRegistry.registerAll(allModules)
 ```
 ### 第 4 步：添加图标映射
 在 `src/modules/icons.ts` 中添加：
 ```typescript
 import { Wrench } from '@lucide/vue'  // 选择合适的图标
 export const moduleIconMap: Record<string, Component> = {
  // ... 已有映射
  'my-module': Wrench
 }
 ```
 ### 第 5 步（可选）：添加 Rust 后端命令
 如果模块需要 Rust 后端支持，在 `src-tauri/src/` 中创建命令模块，并在 `lib.rs` 的 `invoke_handler` 中注册。
 ## 进程管理
 需要管理外部子进程的模块（如 mihomo）通过 `ModuleProcessConfig` 声明进程配置。下载器模块使用进程内自建下载引擎，不涉及外部子进程管理。
 ### 配置示例
 ```typescript
 // src/modules/proxy/index.ts
 export const moduleConfig: ModuleConfig = {
  // ...
  process: {
    name: 'mihomo',              // 进程标识
    executable: '',              // 可执行文件路径（运行时确定）
    args: ['-f', 'config.yaml'], // 启动参数
    autoStart: false,            // 模块启用时是否自动启动
    restartOnCrash: true,        // 崩溃后自动重启
    maxRestarts: 3               // 最大重启次数（0 = 不限制）
  }
 }
 ```
 ### 前端 API
 ```typescript
 import { useProcessStore } from '@/stores/processStore'
 const processStore = useProcessStore()
 // 通过模块 ID 启动进程（自动读取模块配置）
 await processStore.startByModule('proxy')
 // 停止进程
 await processStore.stopByModule('proxy')
 // 获取进程状态（从缓存读取）
 const status = processStore.getProcessStatus('proxy')
 // status.status: 'running' | 'stopped' | 'crashed' | 'starting'
 // 刷新所有进程状态
 await processStore.refreshAll()
 ```
 ### 自动化行为
 模块启用/禁用时，`appStore.toggleModule` 会自动处理：
 | 操作 | 禁用模块 | 启用模块 |
 |------|----------|----------|
 | 进程 | 停止运行中的进程 | 若 `autoStart` 为 true，启动进程 |
 | 搜索项 | 移除该模块的搜索项 | 恢复该模块的搜索项 |
 | 组件缓存 | 清除组件缓存，释放内存 | 下次访问时重新懒加载 |
 | 生命周期 | 调用 `onDisable` 钩子 | 调用 `onEnable` 钩子 |
 | 侧边栏 | 从侧边栏隐藏 | 在侧边栏显示 |
 | Toast 通知 | 显示"已禁用 {模块名}" | 显示"已启用 {模块名}" |
 ## 生命周期钩子
 ```typescript
 interface ModuleLifecycle {
  /** 模块首次加载时调用 */
  onInit?: () => void | Promise<void>
  /** 模块组件挂载时调用（切换到该模块） */
  onActivate?: () => void | Promise<void>
  /** 模块组件卸载时调用（切换离开该模块） */
  onDeactivate?: () => void | Promise<void>
  /** 模块被禁用时调用 */
  onDisable?: () => void | Promise<void>
  /** 模块被启用时调用 */
  onEnable?: () => void | Promise<void>
 }
 ```
 使用示例：
 ```typescript
 export const moduleConfig: ModuleConfig = {
  // ...
  lifecycle: {
    onEnable: async () => {
      console.log('模块已启用')
      // 初始化资源、建立连接等
    },
    onDisable: async () => {
      console.log('模块已禁用')
      // 释放资源、关闭连接等
    },
    onActivate: () => {
      console.log('用户切换到本模块')
      // 开始实时数据更新等
    },
    onDeactivate: () => {
      console.log('用户离开本模块')
      // 暂停实时更新以节省资源
    }
  }
 }
 ```
 ## 全局搜索
 模块通过 `searchItems` 声明可被全局搜索的功能项。用户在标题栏搜索框输入关键词时，匹配的搜索项会显示在结果列表中。
 ```typescript
 searchItems: [
  {
    title: '代理设置',           // 显示标题
    description: '配置网络代理',  // 显示描述
    keywords: ['代理', 'proxy', '网络']  // 匹配关键词
  }
 ]
 ```
 如果搜索项需要执行特定操作（如跳转到子页面、触发命令），在模块组件挂载时通过 `searchStore.registerAction` 注册：
 ```typescript
 import { useSearchStore } from '@/stores/searchStore'
 const searchStore = useSearchStore()
 onMounted(() => {
  // 注册第 0 个搜索项的 action
  searchStore.registerAction('my-module', 0, () => {
    // 跳转到特定子页面或执行操作
    activeTab.value = 'settings'
  })
 })
 ```
 ## 模块分类
 | 分类 | 说明 | 适用场景 |
 |------|------|----------|
 | `network` | 网络相关 | 代理、下载器、网络工具 |
 | `tool` | 实用工具 | 剪贴板、文件搜索、文本处理 |
 | `system` | 系统相关 | 硬件监控、系统设置 |
 | `media` | 媒体相关 | 截图、录屏、图片处理 |
 分类目前用于元信息标记，未来可用于设置界面的分组展示。
 ## 模块禁用机制详解
 当用户在设置页面切换模块开关时：
 ```
 用户点击开关
    │
    ▼
 appStore.toggleModule(moduleId, enabled)
    │
    ├─ 禁用时：
    │   ├─ searchStore.unregisterModule(moduleId)   // 移除搜索项
    │   ├─ processStore.stopByModule(moduleId)       // 停止进程
    │   ├─ config.lifecycle?.onDisable?.()           // 生命周期钩子
    │   ├─ moduleRegistry.clearComponentCache(id)    // 清除组件缓存
    │   ├─ modules[id].enabled = false               // 更新状态
    │   └─ toast.success('已禁用 {模块名}')           // 通知用户
    │
    └─ 启用时：
        ├─ modules[id].enabled = true                // 更新状态
        ├─ config.lifecycle?.onEnable?.()            // 生命周期钩子
        ├─ searchStore.registerItem(...)             // 恢复搜索项
        ├─ processStore.startByModule(moduleId)      // 启动进程（若 autoStart）
        └─ toast.success('已启用 {模块名}')            // 通知用户
 ```
 禁用后的效果：
 - 模块从侧边栏导航中隐藏
 - 模块的搜索项从全局搜索中移除
 - 模块的后台进程被停止
 - 模块的组件缓存被清除，释放内存
 - 如果当前正在查看被禁用的模块，自动切换到第一个可用模块
 ## 注意事项
 1. **模块 ID 必须唯一**：重复注册会被忽略并输出警告
 2. **图标必须映射**：模块配置中的 `icon` 字符串必须在 `icons.ts` 中有对应映射，否则回退到 Settings 图标
 3. **懒加载优先**：使用 `loader` 而非 `component`，避免首屏加载所有模块代码
 4. **避免循环依赖**：模块的 `index.ts` 只导出配置，不导入其他模块的 store
 5. **进程配置的 executable**：通常留空，由模块组件在运行时根据用户设置确定实际路径
 6. **内置模块**：设置 `builtin: true` 的模块不可被用户禁用，开关处于禁用状态
 ## 跨模块开发经验（代理模块沉淀）
 以下要点来自代理模块开发，对后续涉及子进程管理、外部 API 交互、shadcn-vue 组件使用的模块同样适用。
 ### Tauri 命令与主线程
 - **同步命令（`pub fn`）会阻塞主线程**：Tauri 的同步命令在主线程执行，其内部的 `std::thread::sleep`、磁盘 I/O、网络请求会阻塞所有 async 命令的调度。涉及等待/阻塞操作的命令必须声明为 `pub async fn`，并用 `tauri::async_runtime::spawn_blocking(|| { std::thread::sleep(...) }).await` 将阻塞操作放到线程池。
 - **Windows 端口释放有延迟**：`child.kill()` + `child.wait()` 后 TCP 端口不会立即可用，需等待约 800ms 再重新绑定。重启类命令应预留此延迟。
 - **`Mutex` 持锁期间禁止 sleep**：`ProcessManager::check_and_cleanup` 等持锁函数中不要执行长时间 sleep，否则会阻塞所有需要该锁的命令（如状态查询）。应先释放锁再 sleep，或移出临界区。
 - **进程监控线程**：`start_monitoring_thread` 每 3 秒检查一次进程状态，崩溃时自动重启（可配置 `maxRestarts`）。前端通过监听 `process-status-changed` 事件更新 UI。
 ### 外部 API 交互
 - **API 就绪轮询**：子进程 spawn 后 API 不会立即可用（需初始化配置、加载 geo 文件等）。前端应在请求前轮询健康检查接口（如 `/version`），500ms 间隔、10s 超时。
 - **缓存配置避免频繁读盘**：后端 Manager 每次方法调用都从磁盘读 settings 会拖慢批量操作。建议在 Manager 内维护内存缓存，`save_settings` 时同步更新。
 - **并发请求限流**：批量测速等场景不要一次性 `Promise.all` 全部请求，应分批（如每批 20 个），避免压垮子进程。
 ### shadcn-vue / reka-ui 注意事项
 - **Select 禁止空字符串 value**：`<SelectItem value="">` 会触发警告并失效。使用哨兵值（如 `__default__`、`__all__`）替代空字符串，在 `@update:model-value` 回调中转回空值。
 - **Select 双击问题**：reka-ui Select 的 DismissableLayer + closeAutoFocus 会导致连续点击两个 Select 时第一次点击仅关闭上一个、需第二次点击才打开下一个。当前未完美解决，建议同一界面避免放置过多相邻 Select。
 - **Switch 使用 `model-value` / `update:model-value`**：reka-ui v2+ 的 Switch 不再使用 `checked` / `update:checked`。
 - **Sonner toast 不可见**：通常是缺少 `vue-sonner/lib/index.css` 导入，而非 z-index 问题。确保在入口处导入该 CSS。
 - **AlertDialog 替代 confirm()**：原生 `confirm()` 在 Tauri WebView 中样式不一致，使用 shadcn-vue AlertDialog 封装 Promise 化的 `showConfirm()` 函数，支持 destructive 样式。
 ### 数据一致性与自愈
 - **配置文件与磁盘 reconcile**：settings.json 中的列表（如订阅 profiles）可能与磁盘文件不同步（用户手动删除、反序列化失败被 default 覆盖）。每次 `load_settings` 时应扫描磁盘补全缺失条目，并在 `currentProfile` 为 null 时自动指向第一个。
 - **操作顺序防重复**：导入文件后写入 settings 时，若先写文件再 load_settings（含 reconcile 扫盘），reconcile 会扫到新文件添加一次，随后 push 又添加一次。应先 load_settings → 写文件 → push（加去重保护）。
 - **子进程崩溃循环防护**：子进程因依赖文件损坏（如 geo 数据库）崩溃时，`restart_on_crash` 会反复重启。需配置备用下载源（如 jsdelivr 镜像）避免无代理时 GitHub 超时。
 ### UI 细节
 - **瀑布流布局避免卡片等高撑开**：使用 `columns-1 md:columns-2 gap-4 [&>*]:mb-4 [&>*]:break-inside-avoid` 替代 `grid`，让卡片按内容高度自然排列。
 - **模块禁用清理系统状态**：模块 `onDisable` 钩子应清理系统级副作用（如系统代理注册表项），避免模块停用后遗留导致系统异常。
 - **应用退出清理**：在 `lib.rs` 的 `quit_app` 命令和托盘退出事件中都要调用 `cleanup_on_exit` + `stop_all`，确保任何退出路径都清理干净。
 ## 近期重要变更（影响其他模块开发）
 以下是最近几次改动中确立的约定和模式，开发新模块时需遵循。
 ### 后端：子进程启动必须隐藏控制台窗口
 `process_manager.rs` 暴露了公共函数 `setup_creation_flags(cmd: &mut Command)`，Windows 上会设置 `CREATE_NO_WINDOW` 标志。
 **所有用 `std::process::Command` 启动外部程序的地方都必须调用它**，否则会弹出黑色控制台窗口（即使程序是后台运行）。包括：
 - `ProcessManager::start()` 启动 mihomo 等内核
 - `ProcessManager::check_and_cleanup()` 崩溃重启
 - 任何调用 `mihomo.exe -v` 等查询版本的场景
 跨平台：非 Windows 平台该函数为空实现，无需条件编译。
 ```rust
 use crate::process_manager::setup_creation_flags;
 let mut cmd = std::process::Command::new(&path);
 cmd.arg("-v");
 setup_creation_flags(&mut cmd);  // 必须调用
 cmd.stdout(Stdio::piped()).stderr(Stdio::null()).stdin(Stdio::null());
 ```
 ### 后端：长时间 wait() 不要阻塞主线程
 `ProcessManager::stop()` 中 `child.kill()` 是快速的，但 `child.wait()` 可能阻塞几十到几百毫秒。**wait() 已移到后台线程**：
 ```rust
 thread::spawn(move || {
    let _ = entry.child.wait();
 });
 ```
 新模块若有类似的"终止外部进程"逻辑，也应遵循此模式，避免 Tauri 命令阻塞导致前端卡顿。
 ### 后端：内核/二进制下载用流式 + 事件推送
 `mihomo_manager/` 目录（`kernel.rs`）的 `install_kernel` 确立了"下载二进制资源"的标准模式，未来若有其他模块需要下载外部内核时应复用：
 - **流式下载**：`reqwest::Response::bytes_stream()` + `futures_util::StreamExt`，避免大文件一次性读入内存
 - **进度事件**：通过 `app.emit("xxx-install-progress", progress)` 推送，事件载荷结构参考 `InstallProgress`
 - **事件节流**：仅在百分比变化 ≥1% 时 emit，避免事件轰炸
 - **zip 解压**：用 `zip` crate（纯 Rust），不要用 PowerShell `Expand-Archive`（有执行策略问题）
 - **文件名匹配**：解压后用 `find_exe_in_dir` 查找 `.exe`（zip 内文件名可能含版本号，不是固定名字），找到后重命名为标准名
 ### 后端：GitHub API rate limit 规避
 `check_kernel_update` 采用 **API 优先 + 重定向回退** 策略：
 1. 先调 `api.github.com/.../releases/latest`（能拿完整资产列表，命名变化时更健壮）
 2. 失败（403 rate limit / 网络错误）时回退到访问 `github.com/.../releases/latest`，从 302 重定向的最终 URL 提取版本号，按稳定命名规则构造下载 URL
 **新模块若需要查 GitHub 最新版本，应复用此模式**，不要直接调 API（未认证 60次/小时/IP 极易超限）。
 ### 后端：资产命名规则适配
 mihomo v1.19+ 改了 Windows 资产命名，按 CPU 微架构分级：
 - 旧：`mihomo-windows-amd64-vX.X.X.zip`（已废弃）
 - 新：`mihomo-windows-amd64-v3-vX.X.X.zip`（v1/v2/v3 对应 CPU level）
 `fetch_latest_via_api` 中的匹配优先级：v3 标准 > v3-go124 > v3-go123 > v3 其他 > v2 > v1 > 旧命名。若未来其他内核也有类似分级，参考此优先级策略。
 ### 前端：Transition 内的 v-if/v-else 必须加 key
 **这是 dev 模式的坑**。`<Transition mode="out-in">` 内的 `v-if`/`v-else` 分支如果缺 `:key`，Vue 3.5.x dev 模式下会触发 `__vnode` 写入竞态，导致：
 - 控制台报错 `Cannot set properties of null (setting '__vnode')`
 - vnode 树损坏，所有事件派发失效（按钮点击没反应）
 - **build 模式不报错**（生产构建剥除了 `__vnode` instrumentation），容易漏掉
 **约定**：`<Transition>` 内所有分支（v-if/v-else-if/v-else）都必须加 `:key`，即使是原生 div 也要加。
 ```vue
 <Transition name="fade" mode="out-in">
  <ComponentA v-if="cond" key="a" />
  <div v-else key="empty">占位</div>
 </Transition>
 ```
 `ModuleContainer.vue` 和 `ProxyModule.vue` 的 Progress 区块已修复，新模块开发时注意。
 ### 前端：模块内 Tabs 顶部固定模式
 模块根容器用 `h-full overflow-hidden flex flex-col`，Tabs 用 `flex-1 min-h-0 flex flex-col`，TabsList 加 `shrink-0`，TabsContent 加 `flex-1 min-h-0 overflow-y-auto`：
 ```vue
 <div class="h-full p-6 overflow-hidden flex flex-col">
  <Tabs v-model="tab" class="flex-1 min-h-0 flex flex-col">
    <TabsList class="shrink-0">...</TabsList>
    <TabsContent value="x" class="flex-1 min-h-0 overflow-y-auto">...</TabsContent>
  </Tabs>
 </div>
 ```
 这样 TabsList 固定在顶部，只有 TabsContent 滚动。`min-h-0` 是 flex 子元素 overflow 生效的关键，不能省。
 ### 前端：Tauri 事件监听需在 store 中管理生命周期
 `proxyStore.ts` 的 `installKernel` 确立了模式：
 - 监听在方法调用时注册，`finally` 块中取消
 - 用模块级变量保存 `UnlistenFn`，避免重复注册
 - 错误事件由后端保证 emit（前端不重复弹 toast，统一由 watch 处理）
 ```typescript
 let progressUnlisten: UnlistenFn | null = null
 const installKernel = async () => {
  if (!progressUnlisten) {
    progressUnlisten = await listen<Progress>('xxx-progress', (e) => {
      progress.value = e.payload
    })
  }
  try {
    await invoke('xxx_command')
  } finally {
    if (progressUnlisten) {
      progressUnlisten()
      progressUnlisten = null
    }
  }
 }
 ```
 ### 前端：窗口隐藏前 blur 焦点
 TitleBar 的关闭按钮实际是 `hide()` 到托盘。webview 快速隐藏时浏览器 `mouseleave` 可能不触发，导致从托盘恢复后按钮仍显示 hover 高亮。
 **修复**：`hide()` 前调用 `document.activeElement.blur()`，并监听 `onFocusChanged` 在窗口重新获得焦点时再 blur 一次。新模块若有类似的"隐藏窗口"操作（如全局快捷键隐藏），同样需要 blur。
 ### 前端：浮动标签切换器（TabsList 滚动遮挡时在 TitleBar 显示）
 模块详情页内容滚动时，顶部 `TabsList` 会被 `TitleBar` 遮挡，导致用户必须滚回顶部才能切换 Tab。已抽取通用 composable `src/lib/use-module-tabs.ts` 自动处理。
 **接入方式**（任何使用 Tabs 的模块都可用，代理/下载器模块已接入）：
 ```ts
 // 模块 <script setup> 顶部
 import { useModuleTabs } from '@/lib/use-module-tabs'
 const activeTab = ref('overview')
 const tabsListRef = useModuleTabs(activeTab, [
  { value: 'overview', label: '概览' },
  { value: 'settings', label: '设置' }
 ])
 ```
 ```vue
 <!-- 模板中给 TabsList 包一层带 ref 的 div -->
 <Tabs v-model="activeTab">
  <div ref="tabsListRef">
    <TabsList>...</TabsList>
  </div>
  <TabsContent .../>
 </Tabs>
 ```
 **工作原理**：
 - composable 内部在 `onMounted` 时注册标签到 `moduleTabsStore`，`onUnmounted` 时注销
 - 用 `IntersectionObserver`（`rootMargin: '-44px 0px 0px 0px'` 裁剪 TitleBar 高度）监听 TabsList 可见性
 - 滚动遮挡时 `TitleBar` 中"Thing"标题右侧自动显示浮动切换按钮（带淡入+左滑动画）
 - 双向 watch 同步本地 `activeTab` 与 store，用户点击 TitleBar 浮动按钮也能切换模块内 Tab
 **约束**：TitleBar 高度固定 40px（h-10），composable 已用 44px 裁剪（含 4px 缓冲）；store 是单例，一个模块同一时间只能注册一组标签。
 ### 前端：内核路径用 %APPDATA% 简化显示
 内核路径较长（如 `C:\Users\xxx\AppData\Roaming\thing.lfeng.me\proxy\cores\mihomo.exe`），展示时用 `%APPDATA%` 替换前缀，并提供复制完整路径 / 在文件夹中显示两个按钮。代理和下载器模块的内核管理区块已采用此模式。
 ```ts
 import { appDataDir } from '@tauri-apps/api/path'
 const appDataPath = ref('')
 onMounted(async () => {
  try { appDataPath.value = await appDataDir() } catch {}
 })
 const pathDisplay = computed(() => {
  const p = store.kernel?.path
  if (!p) return ''
  if (appDataPath.value && p.toLowerCase().startsWith(appDataPath.value.toLowerCase())) {
    return '%APPDATA%' + p.slice(appDataPath.value.length)
  }
  return p
 })
 ```
 `<title>` 放完整路径，显示文本用 `pathDisplay`，复制时复制完整路径。
 ### 前端：任务历史持久化（下载器模块模式）
 下载引擎在进程内运行，状态通过 `engine_state.json` 持久化到磁盘。前端 store 的做法：
 - `onMounted` 时调用 `store.init()`，一次性加载 status/settings/extensionInfo/tasks
 - 通过 Tauri 事件 `download-progress`、`download-complete`、`download-added` 实时更新任务状态
 - 引擎在 `Storage::new` 时自动创建数据目录，`save` 时兜底重建父目录，避免路径不存在错误
 此模式适用于任何"引擎在进程内运行、状态需持久化"的场景。
 ### 前端：轻量设置 Dialog（替代独立 Tab）
 模块设置项较多时，传统做法是单独开一个"设置"Tab。但任务页工具栏需要快速调整少量核心设置（如下载目录、并发数），切到设置 Tab 再切回来体验割裂。
 **模式**：在任务工具栏放一个"下载设置"按钮，点击弹出 Dialog，包含核心设置项（与设置页共用 `store.settings`），保存时调用 `handleSaveSettings`（引擎立即应用新配置，无需重启）并自动关闭弹窗。完整设置仍保留在"设置"Tab。
 适用场景：需要在任务页快速调整的少量高频设置；若设置项不多，可完全用 Dialog 替代设置 Tab。
 ### 后端：opener 插件 scope 限制与绕过
 `tauri-plugin-opener` 的 `opener:allow-open-path` 权限默认 **无 scope**，IPC `open_path` 命令会拒绝任何路径并报错 `Not allowed to open path`。
 **解决方案**：在 Rust 端写一个自定义命令，用 `OpenerExt::opener().open_path()` 直接调用（绕过 IPC scope 检查）：
 ```rust
 use tauri_plugin_opener::OpenerExt;
 #[tauri::command]
 pub fn my_open_dir(app: AppHandle, path: String) -> Result<(), String> {
    let p = std::path::Path::new(&path);
    if !p.exists() {
        return Err(format!("路径不存在: {}", path));
    }
    app.opener().open_path(path, None::<&str>).map_err(|e| e.to_string())
 }
 ```
 在 `lib.rs` 的 `invoke_handler` 中注册，前端通过 `invoke('my_open_dir', { path })` 调用。下载器模块的"打开下载目录"已采用此方案。
 ### 前端：剩余时间（ETA）可读化
 下载卡片直接显示 `(total-completed)/speed` 会得到 `17.217666215634114 B` 这种难懂的字节数。应格式化为时间：
 ```ts
 const formatEta = (seconds: number): string => {
  if (!isFinite(seconds) || seconds <= 0) return ''
  if (seconds < 60) return `剩余 ${Math.ceil(seconds)} 秒`
  if (seconds < 3600) {
    const m = Math.floor(seconds / 60)
    const s = Math.ceil(seconds % 60)
    return `剩余 ${m} 分 ${s} 秒`
  }
  const h = Math.floor(seconds / 3600)
  const m = Math.ceil((seconds % 3600) / 60)
  return `剩余 ${h} 小时 ${m} 分`
 }
 ```
 `getEta(task) = (totalLength - completedLength) / downloadSpeed`，speed≤0 时返回 0（不显示）。
 ### 前端：状态统计用 Badge 替代纯文本
 下载任务工具栏的速度/活跃/等待/已完成数量，以及代理概览页的内核状态/版本，从纯文本改为 `Badge variant="secondary"` 或带颜色的 `Badge`（绿色已安装/红色未安装），视觉更醒目。新模块的状态展示建议统一用 Badge。
 ### 后端：应用退出清理（单一出口）
 退出清理已收敛到 `lib.rs` 的 `RunEvent::ExitRequested` 分支（P0-1/V7）：`quit_app` 命令与托盘退出项都只触发 `app.exit(0)`，清理逻辑（`cleanup_on_exit` + `stop_all`）只在该分支执行一次。新增管理子进程的模块时，在 `ExitRequested` 分支注册自己的 `cleanup_on_exit` 即可，不要在命令或托盘路径重复清理。
@@ -16,6 +16,7 @@
        "class-variance-authority": "^0.7.1",
        "clsx": "^2.1.1",
        "pinia": "^3.0.4",
        "pinyin-pro": "^3.28.2",
        "reka-ui": "^2.10.1",
        "tailwind-merge": "^3.6.0",
        "tailwindcss": "^4.3.2",
@@ -381,6 +382,8 @@
    "pinia": ["pinia@3.0.4", "https://registry.npmmirror.com/pinia/-/pinia-3.0.4.tgz", { "dependencies": { "@vue/devtools-api": "^7.7.7" }, "peerDependencies": { "typescript": ">=4.5.0", "vue": "^3.5.11" }, "optionalPeers": ["typescript"] }, "sha512-l7pqLUFTI/+ESXn6k3nu30ZIzW5E2WZF/LaHJEpoq6ElcLD+wduZoB2kBN19du6K/4FDpPMazY2wJr+IndBtQw=="],
    "pinyin-pro": ["pinyin-pro@3.29.4", "https://registry.npmmirror.com/pinyin-pro/-/pinyin-pro-3.29.4.tgz", {}, "sha512-SPXpDT2cHEy+d26V1RXYMlVzXN42hotFAak1fzyWPi4o2dKXb61UqD4pzxDJHwk6gbv8vQ6EfErd+hYX0Qhzug=="],
    "postcss": ["postcss@8.5.19", "https://registry.npmmirror.com/postcss/-/postcss-8.5.19.tgz", { "dependencies": { "nanoid": "^3.3.12", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" } }, "sha512-Mz8SaolMd8nB+G13WkORcxQKHZ/NE4xXevtkJHVuG+guo9/wYKlIMTKAqGdEmYOXR2ijPjTYNHssizdaVSUNdQ=="],
    "reka-ui": ["reka-ui@2.10.1", "https://registry.npmmirror.com/reka-ui/-/reka-ui-2.10.1.tgz", { "dependencies": { "@floating-ui/dom": "^1.6.13", "@floating-ui/vue": "^1.1.6", "@internationalized/date": "^3.5.0", "@internationalized/number": "^3.5.0", "@tanstack/vue-virtual": "^3.12.0", "@vueuse/core": "^14.1.0", "@vueuse/shared": "^14.1.0", "aria-hidden": "^1.2.4", "defu": "^6.1.5", "ohash": "^2.0.11" }, "peerDependencies": { "vue": ">= 3.4.0" } }, "sha512-drcOQ4rQtDYAcGCsyQBqQg8QQ+H3B+zDaMJU0h8KPEPMa7g9BHu3zcOi4OB39XJSWizceFoNO0Z9tctSGLOXqg=="],
@@ -1,7 +1,7 @@
 {
  "name": "thing",
  "private": true,
-  "version": "26.8.5",
+  "version": "26.9.3",
  "type": "module",
  "scripts": {
    "dev": "vite",
@@ -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. 构建 ----------
@@ -515,6 +515,12 @@ version = "0.23.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5"
 [[package]]
 name = "base64ct"
 version = "1.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 [[package]]
 name = "bit-set"
 version = "0.8.0"
@@ -566,6 +572,15 @@ dependencies = [
 "generic-array 0.14.7",
 ]
 [[package]]
 name = "block-padding"
 version = "0.3.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a8894febbff9f758034a5b8e12d87918f56dfc64a8e1fe757d65e29041538d93"
 dependencies = [
 "generic-array 0.14.7",
 ]
 [[package]]
 name = "block2"
 version = "0.6.2"
@@ -748,6 +763,15 @@ dependencies = [
 "toml 0.9.12+spec-1.1.0",
 ]
 [[package]]
 name = "cbc"
 version = "0.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "26b52a9543ae338f279b96b0b9fed9c8093744685043739079ce85cd58f289a6"
 dependencies = [
 "cipher",
 ]
 [[package]]
 name = "cc"
 version = "1.2.67"
@@ -908,6 +932,12 @@ dependencies = [
 "crossbeam-utils",
 ]
 [[package]]
 name = "const-oid"
 version = "0.9.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8"
 [[package]]
 name = "const_panic"
 version = "0.2.17"
@@ -1192,6 +1222,17 @@ version = "0.1.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ac6b926516df9c60bfa16e107b21086399f8285a44ca9711344b9e553c5146e2"
 [[package]]
 name = "der"
 version = "0.7.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e7c1832837b905bbfb5101e07cc24c8deddf52f93225eee6ead5f4d63d53ddcb"
 dependencies = [
 "const-oid",
 "pem-rfc7468",
 "zeroize",
 ]
 [[package]]
 name = "deranged"
 version = "0.5.8"
@@ -1240,6 +1281,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
 dependencies = [
 "block-buffer",
 "const-oid",
 "crypto-common",
 "subtle",
 ]
@@ -2619,6 +2661,7 @@ version = "0.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01"
 dependencies = [
 "block-padding",
 "generic-array 0.14.7",
 ]
@@ -2822,6 +2865,18 @@ dependencies = [
 "unicode-segmentation",
 ]
 [[package]]
 name = "keyring"
 version = "3.6.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "eebcc3aff044e5944a8fbaf69eb277d11986064cba30c468730e8b9909fb551c"
 dependencies = [
 "byteorder",
 "log",
 "windows-sys 0.60.2",
 "zeroize",
 ]
 [[package]]
 name = "kqueue"
 version = "1.2.0"
@@ -2847,6 +2902,9 @@ name = "lazy_static"
 version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
 dependencies = [
 "spin",
 ]
 [[package]]
 name = "leaky-bucket"
@@ -2908,6 +2966,12 @@ dependencies = [
 "winapi",
 ]
 [[package]]
 name = "libm"
 version = "0.2.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
 [[package]]
 name = "libredox"
 version = "0.1.18"
@@ -3254,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"
@@ -3324,6 +3414,16 @@ version = "0.8.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
 [[package]]
 name = "md-5"
 version = "0.10.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d89e7ee0cfbedfc4da3340218492196241d89eefb6dab27de5df917a6d2e78cf"
 dependencies = [
 "cfg-if",
 "digest",
 ]
 [[package]]
 name = "memchr"
 version = "2.8.3"
@@ -3570,6 +3670,22 @@ dependencies = [
 "num-traits",
 ]
 [[package]]
 name = "num-bigint-dig"
 version = "0.8.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e661dda6640fad38e827a6d4a310ff4763082116fe217f279885c97f511bb0b7"
 dependencies = [
 "lazy_static",
 "libm",
 "num-integer",
 "num-iter",
 "num-traits",
 "rand 0.8.8",
 "smallvec",
 "zeroize",
 ]
 [[package]]
 name = "num-complex"
 version = "0.2.4"
@@ -3623,6 +3739,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
 dependencies = [
 "autocfg",
 "libm",
 ]
 [[package]]
@@ -3843,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"
@@ -3989,6 +4115,15 @@ dependencies = [
 "hmac",
 ]
 [[package]]
 name = "pem-rfc7468"
 version = "0.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "88b39c9bfcfc231068454382784bb460aae594343fb030d46e9f50a645418412"
 dependencies = [
 "base64ct",
 ]
 [[package]]
 name = "percent-encoding"
 version = "2.3.2"
@@ -4065,6 +4200,27 @@ dependencies = [
 "futures-io",
 ]
 [[package]]
 name = "pkcs1"
 version = "0.7.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c8ffb9f10fa047879315e6625af03c164b16962a5368d724ed16323b68ace47f"
 dependencies = [
 "der",
 "pkcs8",
 "spki",
 ]
 [[package]]
 name = "pkcs8"
 version = "0.10.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f950b2377845cebe5cf8b5165cb3cc1a5e0fa5cfa3e1f7f55707d8fd82e0a7b7"
 dependencies = [
 "der",
 "spki",
 ]
 [[package]]
 name = "pkg-config"
 version = "0.3.33"
@@ -4346,13 +4502,24 @@ version = "0.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dc33ff2d4973d518d823d61aa239014831e521c75da58e3df4840d3f47749d09"
 [[package]]
 name = "rand"
 version = "0.8.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e058c7de0b26af77780c769414d6257830bb240f3c38477dbc2c16e5f54d6d4c"
 dependencies = [
 "libc",
 "rand_chacha 0.3.1",
 "rand_core 0.6.4",
 ]
 [[package]]
 name = "rand"
 version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41"
 dependencies = [
- "rand_chacha",
+ "rand_chacha 0.9.0",
 "rand_core 0.9.5",
 ]
@@ -4367,6 +4534,16 @@ dependencies = [
 "rand_core 0.10.1",
 ]
 [[package]]
 name = "rand_chacha"
 version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88"
 dependencies = [
 "ppv-lite86",
 "rand_core 0.6.4",
 ]
 [[package]]
 name = "rand_chacha"
 version = "0.9.0"
@@ -4377,6 +4554,15 @@ dependencies = [
 "rand_core 0.9.5",
 ]
 [[package]]
 name = "rand_core"
 version = "0.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
 dependencies = [
 "getrandom 0.2.17",
 ]
 [[package]]
 name = "rand_core"
 version = "0.9.5"
@@ -4547,6 +4733,7 @@ dependencies = [
 "js-sys",
 "log",
 "mime",
 "mime_guess",
 "native-tls",
 "percent-encoding",
 "pin-project-lite",
@@ -4666,6 +4853,26 @@ dependencies = [
 "libc",
 ]
 [[package]]
 name = "rsa"
 version = "0.9.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b8573f03f5883dcaebdfcf4725caa1ecb9c15b2ef50c43a07b816e06799bb12d"
 dependencies = [
 "const-oid",
 "digest",
 "num-bigint-dig",
 "num-integer",
 "num-traits",
 "pkcs1",
 "pkcs8",
 "rand_core 0.6.4",
 "signature",
 "spki",
 "subtle",
 "zeroize",
 ]
 [[package]]
 name = "rusqlite"
 version = "0.32.1"
@@ -5167,6 +5374,16 @@ dependencies = [
 "libc",
 ]
 [[package]]
 name = "signature"
 version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77549399552de45a898a580c1b41d445bf730df867cc44e6c0233bbc4b8329de"
 dependencies = [
 "digest",
 "rand_core 0.6.4",
 ]
 [[package]]
 name = "simd-adler32"
 version = "0.3.9"
@@ -5327,6 +5544,12 @@ dependencies = [
 "specta",
 ]
 [[package]]
 name = "spin"
 version = "0.9.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3763264f6b73151db08c50ff20d7d8a0b8796e021cdea7ceedad07b80155fa0e"
 [[package]]
 name = "spinning_top"
 version = "0.3.0"
@@ -5336,6 +5559,16 @@ dependencies = [
 "lock_api",
 ]
 [[package]]
 name = "spki"
 version = "0.7.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d91ed6c858b01f942cd56b37a94b3e0a1798290327d1236e4d9cf4eaca44d29d"
 dependencies = [
 "base64ct",
 "der",
 ]
 [[package]]
 name = "stable_deref_trait"
 version = "1.2.1"
@@ -5951,24 +6184,34 @@ dependencies = [
 [[package]]
 name = "thing"
-version = "26.8.5"
+version = "26.9.3"
 dependencies = [
 "aes",
 "async-trait",
 "axum 0.7.9",
 "base64 0.22.1",
 "bytes",
 "cbc",
 "chrono",
 "dirs 5.0.1",
 "futures-util",
 "hmac",
 "image",
 "keyring",
 "librqbit",
 "lofty",
 "md-5",
 "notify",
 "rand 0.8.8",
 "raw-window-handle",
 "regex",
 "reqwest 0.12.28",
 "rsa",
 "rusqlite",
 "serde",
 "serde_json",
 "serde_yaml",
 "sha2",
 "specta",
 "specta-typescript",
 "sysinfo",
@@ -5982,6 +6225,7 @@ dependencies = [
 "tauri-plugin-snap-layout",
 "tauri-specta",
 "tokio",
 "tokio-tungstenite",
 "url",
 "walkdir",
 "windows 0.52.0",
@@ -6156,6 +6400,18 @@ dependencies = [
 "tokio-util",
 ]
 [[package]]
 name = "tokio-tungstenite"
 version = "0.24.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "edc5f74e248dc973e0dbb7b74c7e0d6fcc301c694ff50049504004ef4d0cdcd9"
 dependencies = [
 "futures-util",
 "log",
 "tokio",
 "tungstenite",
 ]
 [[package]]
 name = "tokio-util"
 version = "0.7.18"
@@ -6395,6 +6651,24 @@ version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
 [[package]]
 name = "tungstenite"
 version = "0.24.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "18e5b8366ee7a95b16d32197d0b2604b43a0be89dc5fac9f8e96ccafbaedda8a"
 dependencies = [
 "byteorder",
 "bytes",
 "data-encoding",
 "http",
 "httparse",
 "log",
 "rand 0.8.8",
 "sha1",
 "thiserror 1.0.69",
 "utf-8",
 ]
 [[package]]
 name = "typeid"
 version = "1.0.3"
@@ -6526,6 +6800,12 @@ dependencies = [
 "url",
 ]
 [[package]]
 name = "utf-8"
 version = "0.7.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9"
 [[package]]
 name = "utf8_iter"
 version = "1.0.4"
@@ -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,26 @@ 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）
    pub const MUSIC_DOWNLOAD_EVENT: &str = "music-download-event";
    // 后端自动切换节点完成（前端据以刷新节点列表并提示）
    pub const PROXY_AUTO_SWITCH: &str = "proxy-auto-switch";
    // 应用更新进度
@@ -6,14 +6,17 @@ mod download_engine;
 mod logger;
 mod mihomo_manager;
 mod monitor_kernel;
 mod music;
 mod network_monitor;
 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;
@@ -41,6 +44,19 @@ use monitor_kernel::{
    monitor_set_hardware_config, monitor_start, monitor_start_elevated, monitor_status, monitor_stop,
    MonitorKernel,
 };
 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_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_secret_get, music_secret_set,
    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::{
    osd_apply_overlay_style, osd_begin_drag, osd_set_bounds, osd_set_click_through,
@@ -61,7 +77,7 @@ use screenshot::commands::{
    screenshot_register_shortcut,
    screenshot_save_cache, screenshot_save_png, screenshot_scroll_capture,
    screenshot_scroll_cancel, screenshot_scroll_finish, screenshot_scroll_start,
-    screenshot_show_overlay, screenshot_take_editor_image_raw,
+    screenshot_set_scroll_hole, screenshot_show_overlay, screenshot_take_editor_image_raw,
    screenshot_unregister_pin_shortcut, screenshot_unregister_shortcut,
 };
 use clipboard::{
@@ -87,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,
@@ -99,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;
@@ -149,7 +182,10 @@ fn export_bindings() {
            downloader_get_tasks, downloader_check_url, downloader_add_task, downloader_pause_task,
            downloader_resume_task, downloader_cancel_task, downloader_redownload, downloader_remove_task, downloader_get_settings,
            downloader_save_settings, downloader_open_dir, downloader_open_url, downloader_focus_window, downloader_inspect, downloader_select_bt_files,
-            // screenshot（22，豁免 3：get_fullscreen_bmp / take_editor_image_raw 返回 ipc::Response、
+            // music（6，豁免 3：music_ping / music_get_sources / music_search 返回 serde_json::Value）
            music_env_status, music_install_runtime, music_cancel_runtime_install,
            music_stop_bridge, music_get_settings, music_save_settings,
            // screenshot（23，豁免 3：get_fullscreen_bmp / take_editor_image_raw 返回 ipc::Response、
            // compose_copy / compose_png 接收 ipc::Request）
            screenshot_disable_transitions, screenshot_show_overlay, screenshot_register_shortcut,
            screenshot_unregister_shortcut, screenshot_register_pin_shortcut,
@@ -158,8 +194,20 @@ fn export_bindings() {
            screenshot_crop_copy_stored, screenshot_pick_list, screenshot_cursor_pos,
            screenshot_enum_windows, screenshot_capture_window, screenshot_scroll_capture,
            screenshot_scroll_cancel, screenshot_scroll_finish, screenshot_scroll_start,
            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");
@@ -243,6 +291,45 @@ pub fn run() {
            monitor_set_auto_start,
            monitor_get_hardware_config,
            monitor_set_hardware_config,
            music_env_status,
            music_install_runtime,
            music_cancel_runtime_install,
            music_update_musicdl,
            music_ping,
            music_stop_bridge,
            music_get_sources,
            music_search,
            music_parse_playlist,
            music_resolve,
            music_get_settings,
            music_save_settings,
            music_download,
            music_download_cancel,
            feiniu_list_connections,
            feiniu_save_connection,
            feiniu_delete_connection,
            feiniu_activate_connection,
            feiniu_test_connection,
            feiniu_login,
            feiniu_logout,
            feiniu_get_config,
            feiniu_list_tracks,
            feiniu_lyric,
            feiniu_media_prefix,
            feiniu_scan_local,
            feiniu_list_audio_files,
            feiniu_cache_status,
            feiniu_cache_clear,
            feiniu_cache_fetch,
            feiniu_fnconnect_resolve,
            webdav_test,
            webdav_upload,
            webdav_delete,
            webdav_get_secret,
            webdav_save_secret,
            music_secret_get,
            music_secret_set,
            feiniu_delete_local,
            network_status,
            osd_apply_overlay_style,
            osd_begin_drag,
@@ -344,6 +431,7 @@ pub fn run() {
            screenshot_scroll_cancel,
            screenshot_scroll_finish,
            screenshot_scroll_start,
            screenshot_set_scroll_hole,
            screenshot_take_editor_image_raw,
            screenshot_copy_image,
            screenshot_save_png,
@@ -357,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| {
@@ -395,6 +511,10 @@ pub fn run() {
                    });
                    let _ = rx.recv_timeout(std::time::Duration::from_secs(3));
                }
                if let Some(music) = app.try_state::<MusicManager>() {
                    // 停止音乐桥接进程（kill 快速返回，wait 在后台线程完成）
                    music.cleanup_on_exit();
                }
                if let Some(clip) = app.try_state::<ClipboardManager>() {
                    clip.stop();
                }
@@ -0,0 +1,262 @@
 //! 桥接进程生命周期：spawn（stdio JSON-Lines 协议）→ 请求分发 → 事件转发 → 停止。
 //! 子模块通过 `impl super::MusicManager` 追加方法。
 //!
 //! 协议（与 bridge.py 对应）：
 //! 请求 `{"id":1,"method":"ping","params":{}}`
 //! 响应 `{"id":1,"ok":true,"result":{...}}` 或 `{"id":1,"ok":false,"error":"..."}`
 //! 无 id 的事件行 `{"event":"download","type":"progress",...}` 由 reader 线程
 //! 原样转发为 Tauri 事件 `music-download-event`（见 constants::events）。
 use std::io::{BufRead, BufReader, Write};
 use std::process::{Command, Stdio};
 use tauri::Emitter;
 use super::{BridgeEntry, MusicManager, PythonEnv};
 /// 桥接脚本源码（内置，运行时写出到 {root}/bridge.py，避免资源目录配置）
 const BRIDGE_SCRIPT: &str = include_str!("bridge.py");
 /// 桥接请求错误分类：决定是否允许重启桥接进程重试。
 /// 应用层错误与超时绝不能触发重启——重启会杀掉正在进行的下载任务。
 pub(crate) enum BridgeError {
    /// 传输层错误（进程退出/管道损坏/写入失败/通道关闭）→ 可重启重试
    Transport(String),
    /// 应用层错误（桥接正常响应 ok:false）→ 不重启
    App(String),
    /// 响应超时 → 不重启（进程可能只是忙，如正在执行长耗时搜索）
    Timeout(String),
 }
 impl BridgeError {
    fn into_message(self) -> String {
        match self {
            BridgeError::Transport(m) | BridgeError::App(m) | BridgeError::Timeout(m) => m,
        }
    }
 }
 impl MusicManager {
    /// 桥接进程是否在运行（存在且未退出）
    pub fn bridge_running(&self) -> bool {
        let mut guard = match self.bridge.lock() {
            Ok(g) => g,
            Err(_) => return false,
        };
        match guard.as_mut() {
            Some(entry) => entry.child.try_wait().ok().map(|w| w.is_none()).unwrap_or(false),
            None => false,
        }
    }
    /// 确保桥接进程已启动（已启动则直接返回；并发调用由 start_lock 串行化）
    pub fn ensure_bridge(&self) -> Result<(), String> {
        if self.bridge_running() {
            return Ok(());
        }
        let _guard = self.start_lock().lock().map_err(|e| e.to_string())?;
        // 二次检查（等待锁期间可能已被其他调用方启动）
        if self.bridge_running() {
            return Ok(());
        }
        // 清理可能残留的旧条目
        self.bridge.lock().map_err(|e| e.to_string())?.take();
        let python = self.resolve_python()?;
        self.spawn_bridge(&python)
    }
    /// 启动桥接进程：stdin/stdout 管道直连，stderr 写入 runtime/bridge_stderr.log
    fn spawn_bridge(&self, python: &PythonEnv) -> Result<(), String> {
        let script = self.bridge_script_path();
        // 每次启动前重写脚本，保证与当前版本一致（内容固定，成本极低）
        std::fs::write(&script, BRIDGE_SCRIPT).map_err(|e| format!("写出桥接脚本失败: {}", e))?;
        let stderr_log = self.runtime_dir().join("bridge_stderr.log");
        let stderr_file = std::fs::File::create(&stderr_log).map_err(|e| e.to_string())?;
        let mut cmd = Command::new(&python.exe);
        cmd.arg(&script);
        cmd.stdin(Stdio::piped())
            .stdout(Stdio::piped())
            .stderr(Stdio::from(stderr_file));
        crate::process_manager::setup_creation_flags(&mut cmd);
        // cwd 统一设为模块根目录：musicdl 会在 cwd 落 search_results.pkl 等缓存文件，
        // 不设置时（系统 Python）会污染应用工作目录（开发期为仓库根目录）
        if let Some(parent) = script.parent() {
            cmd.current_dir(parent);
        }
        let mut child = cmd
            .spawn()
            .map_err(|e| format!("启动桥接进程失败 (python: {}): {}", python.exe.display(), e))?;
        crate::process_manager::assign_to_job(&child);
        let stdin = child.stdin.take().ok_or_else(|| "无法获取桥接 stdin".to_string())?;
        let stdout = child.stdout.take().ok_or_else(|| "无法获取桥接 stdout".to_string())?;
        *self.bridge.lock().map_err(|e| e.to_string())? = Some(BridgeEntry { child, stdin });
        // 启动 stdout reader 线程：按行读取，按 id 分发到 pending；无 id 的事件行转发到前端
        let pending = self.pending.clone();
        let app = self.app_handle();
        std::thread::spawn(move || {
            let reader = BufReader::new(stdout);
            for line in reader.lines() {
                let Ok(line) = line else { break };
                let Ok(v) = serde_json::from_str::<serde_json::Value>(&line) else {
                    crate::logger::log_warn("music-bridge", &format!("无法解析 stdout: {}", line));
                    continue;
                };
                if let Some(id) = v.get("id").and_then(|i| i.as_u64()) {
                    if let Some(tx) = pending.lock().ok().and_then(|mut m| m.remove(&id)) {
                        let _ = tx.send(v);
                    }
                } else if v.get("event").is_some() {
                    // 事件行（下载进度等）：原样转发给前端
                    if let Some(app) = app.as_ref() {
                        let _ = app.emit(crate::constants::events::MUSIC_DOWNLOAD_EVENT, &v);
                    }
                } else {
                    // 其他无 id 行仅记日志
                    crate::logger::log_info("music-bridge", &line);
                }
            }
            crate::logger::log_info("music-bridge", "stdout 已关闭，reader 线程退出");
        });
        crate::logger::log_info(
            "music-bridge",
            &format!("桥接进程已启动 (python: {})", python.exe.display()),
        );
        Ok(())
    }
    /// 停止桥接进程：kill 快速返回，wait 移到后台线程；所有 pending 请求置为失败
    pub fn stop_bridge(&self) {
        let entry = self.bridge.lock().ok().and_then(|mut b| b.take());
        if let Some(mut entry) = entry {
            let _ = entry.child.kill();
            // drop stdin/stdout 关闭管道端，reader 线程读到 EOF 退出
            drop(entry.stdin);
            std::thread::spawn(move || {
                let _ = entry.child.wait();
            });
            crate::logger::log_info("music-bridge", "桥接进程已停止");
        }
        // 通知前端：活动中的下载任务应标记为中断
        if let Some(app) = self.app_handle() {
            let _ = app.emit(
                crate::constants::events::MUSIC_DOWNLOAD_EVENT,
                serde_json::json!({ "event": "download", "type": "bridge-stopped" }),
            );
        }
        // 唤醒所有等待中的请求（以 Null 表示已中止）
        if let Ok(mut map) = self.pending.lock() {
            for (_, tx) in map.drain() {
                let _ = tx.send(serde_json::Value::Null);
            }
        }
    }
    /// 发送一条请求并等待响应（默认 5s 超时）。传输层错误时自动重启重试一次。
    pub async fn request(
        &self,
        method: &str,
        params: serde_json::Value,
    ) -> Result<serde_json::Value, String> {
        self.request_with_timeout(method, params, std::time::Duration::from_secs(5))
            .await
    }
    /// 发送一条请求并等待响应（自定义超时，供 search 等长耗时操作使用）。
    /// 仅传输层错误（进程退出/管道损坏）会重启桥接并重试一次；
    /// 应用层错误（桥接返回 ok:false）与超时不重启——重启会误杀正在下载的任务。
    pub async fn request_with_timeout(
        &self,
        method: &str,
        params: serde_json::Value,
        timeout: std::time::Duration,
    ) -> Result<serde_json::Value, String> {
        self.ensure_bridge()?;
        match self.request_inner(method, params.clone(), timeout).await {
            Ok(v) => Ok(v),
            Err(BridgeError::Transport(_)) => {
                // 一次重启机会（进程可能已退出/管道损坏）
                self.stop_bridge();
                self.ensure_bridge()?;
                self.request_inner(method, params, timeout)
                    .await
                    .map_err(BridgeError::into_message)
            }
            Err(e) => Err(e.into_message()),
        }
    }
    async fn request_inner(
        &self,
        method: &str,
        params: serde_json::Value,
        timeout: std::time::Duration,
    ) -> Result<serde_json::Value, BridgeError> {
        let id = self.next_id.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
        let (tx, rx) = tokio::sync::oneshot::channel::<serde_json::Value>();
        self.pending
            .lock()
            .map_err(|e| BridgeError::Transport(e.to_string()))?
            .insert(id, tx);
        // 写入 stdin（同步函数，MutexGuard 在返回时释放，避免跨 await 持有非 Send 值）
        self.write_request(id, method, &params)
            .map_err(BridgeError::Transport)?;
        let v = tokio::time::timeout(timeout, rx)
            .await
            .map_err(|_| BridgeError::Timeout("桥接响应超时".to_string()))?
            .map_err(|_| BridgeError::Transport("桥接响应通道已关闭".to_string()))?;
        // 停止桥接时发送 Null 表示中止
        if v.is_null() {
            return Err(BridgeError::Transport("桥接进程已停止".into()));
        }
        if v.get("ok").and_then(|o| o.as_bool()).unwrap_or(false) {
            Ok(v.get("result").cloned().unwrap_or(serde_json::Value::Null))
        } else {
            Err(BridgeError::App(
                v.get("error")
                    .and_then(|e| e.as_str())
                    .unwrap_or("桥接返回未知错误")
                    .to_string(),
            ))
        }
    }
    /// 写入一条请求到桥接 stdin（同步；进程已退出 / 管道损坏时返回错误）
    fn write_request(&self, id: u64, method: &str, params: &serde_json::Value) -> Result<(), String> {
        let line = format!(
            "{{\"id\":{},\"method\":{},\"params\":{}}}\n",
            id,
            serde_json::to_string(method).map_err(|e| e.to_string())?,
            params
        );
        let mut guard = self.bridge.lock().map_err(|e| e.to_string())?;
        let Some(entry) = guard.as_mut() else {
            return Err("桥接进程未启动".into());
        };
        // 进程已退出 → 立即失败，交给外层重启
        if entry.child.try_wait().map_err(|e| e.to_string())?.is_some() {
            return Err("桥接进程已退出".into());
        }
        entry
            .stdin
            .write_all(line.as_bytes())
            .map_err(|e| format!("写入桥接 stdin 失败: {}", e))?;
        entry.stdin.flush().map_err(|e| format!("刷新桥接 stdin 失败: {}", e))?;
        Ok(())
    }
    /// ping 桥接进程（P0 环境层连通性验证）
    pub async fn ping(&self) -> Result<serde_json::Value, String> {
        let v = self.request("ping", serde_json::Value::Null).await?;
        crate::logger::log_info("music-bridge", &format!("ping 成功: {}", v));
        Ok(v)
    }
 }
@@ -0,0 +1,730 @@
 //! 音乐模块 Tauri 命令层。
 use serde_json::json;
 use std::time::{SystemTime, UNIX_EPOCH};
 use tauri::{AppHandle, State};
 use super::{
    normalize_base_url, resolve_base_url, extract_fn_id, FeiniuConnection, MusicEnvStatus,
    MusicManager, MusicSettings,
 };
 /// 查询环境状态（Python / musicdl / FFmpeg / 桥接进程），设置页「环境检查」面板调用。
 /// 异步命令：子进程探测在阻塞线程池执行，避免冻结主线程/UI。
 #[tauri::command]
 #[specta::specta]
 pub async fn music_env_status(state: State<'_, MusicManager>) -> Result<MusicEnvStatus, String> {
    state.env_status().await
 }
 /// 安装便携 Python + musicdl（幂等），全程推送 music-runtime-install-progress 事件
 #[tauri::command]
 #[specta::specta]
 pub async fn music_install_runtime(
    state: State<'_, MusicManager>,
    app: AppHandle,
 ) -> Result<MusicEnvStatus, String> {
    state.install_runtime(&app).await?;
    Ok(state.env_status().await?)
 }
 /// 取消便携运行时安装/下载
 #[tauri::command]
 #[specta::specta]
 pub fn music_cancel_runtime_install(state: State<'_, MusicManager>) -> Result<(), String> {
    state.cancel();
    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]
 pub async fn music_ping(state: State<'_, MusicManager>) -> Result<serde_json::Value, String> {
    state.ping().await
 }
 /// 停止桥接进程
 #[tauri::command]
 #[specta::specta]
 pub fn music_stop_bridge(state: State<'_, MusicManager>) -> Result<(), String> {
    state.stop_bridge();
    Ok(())
 }
 /// 列出 musicdl 已注册的全部搜索源（客户端名）；返回 Value，未标注 specta
 #[tauri::command]
 pub async fn music_get_sources(state: State<'_, MusicManager>) -> Result<serde_json::Value, String> {
    state.request("get_sources", serde_json::Value::Null).await
 }
 /// 多源搜索（最长 90s）。sources 为空时桥接使用默认 3 个大陆源；返回 Value，未标注 specta
 #[tauri::command]
 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> {
    // 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
 }
 /// 解析歌单链接（网易云/QQ 等），返回歌曲列表；返回 Value，未标注 specta
 #[tauri::command]
 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(),
        "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
 }
 /// 读取音乐模块设置
 #[tauri::command]
 #[specta::specta]
 pub fn music_get_settings(state: State<'_, MusicManager>) -> MusicSettings {
    state.load_settings()
 }
 /// 保存音乐模块设置（立即生效）
 ///
 /// 飞牛音乐**连接相关字段一律以磁盘为准**，不接受前端传值：
 /// 连接列表 / 激活连接 / 旧版单连接字段只由 `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> {
    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)
 }
 /// 解析歌曲真实下载链接（懒解析：搜索只取元数据，试听/下载前调用）。
 /// song（单曲）或 songs（批量）二选一；返回 Value，未标注 specta。
 #[tauri::command]
 pub async fn music_resolve(
    state: State<'_, MusicManager>,
    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 {
        list.insert(0, s);
    }
    if list.is_empty() {
        return Err("未提供歌曲".into());
    }
    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
 }
 /// 启动下载任务（桥接后台工作池执行，立即返回 taskId；进度经 music-download-event 推送）。
 /// songs 为搜索结果的歌曲 dict（桥接端用 SongInfo.fromdict 重建）。
 /// 返回 Value，未标注 specta。
 #[tauri::command]
 pub async fn music_download(
    state: State<'_, MusicManager>,
    task_id: String,
    songs: Vec<serde_json::Value>,
    savedir: String,
    lyric: Option<bool>,
    cover: Option<bool>,
    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());
    }
    let params = serde_json::json!({
        "taskId": task_id,
        "songs": songs,
        "savedir": savedir,
        "lyric": lyric.unwrap_or(true),
        "cover": cover.unwrap_or(true),
        "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))
        .await
 }
 /// 取消下载任务（队列级：正在下载的歌曲会完成，其余标记取消）
 #[tauri::command]
 pub async fn music_download_cancel(
    state: State<'_, MusicManager>,
    task_id: String,
 ) -> Result<serde_json::Value, String> {
    state
        .request("cancel", serde_json::json!({ "taskId": task_id }))
        .await
 }
 // ============ 飞牛音乐(NAS)客户端（多连接） ============
 // 全部命令返回 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();
    let list: Vec<_> = s
        .feiniu_connections
        .iter()
        .map(|c| {
            json!({
                "id": c.id,
                "name": c.name,
                "kind": c.kind,
                "baseUrl": c.base_url,
                "username": c.username,
                "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();
    Ok(json!({ "activeId": s.feiniu_active_id, "list": list }))
 }
 /// 新增/更新一条连接（不触碰已登录的 token；改地址后需重新登录）。
 #[tauri::command]
 pub fn feiniu_save_connection(
    state: State<'_, MusicManager>,
    connection: FeiniuConnection,
 ) -> Result<serde_json::Value, String> {
    let mut settings = state.load_settings();
    let mut conn = connection;
    conn.base_url = normalize_base_url(&conn.base_url);
    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)?;
    // 回传 id：新建时前端无需按「地址 + 名称」反查，避免 FnConnect（地址为空）匹配失败
    Ok(json!({ "ok": true, "id": id }))
 }
 /// 删除一条连接；若删的是激活连接，自动切换激活到第一条。
 #[tauri::command]
 pub fn feiniu_delete_connection(
    state: State<'_, MusicManager>,
    id: String,
 ) -> Result<serde_json::Value, String> {
    let mut settings = state.load_settings();
    settings.feiniu_connections.retain(|c| c.id != id);
    if settings.feiniu_active_id == id {
        settings.feiniu_active_id = settings
            .feiniu_connections
            .first()
            .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 }))
 }
 /// 设某连接为激活连接。
 #[tauri::command]
 pub fn feiniu_activate_connection(
    state: State<'_, MusicManager>,
    id: String,
 ) -> Result<serde_json::Value, String> {
    let mut settings = state.load_settings();
    if !settings.feiniu_connections.iter().any(|c| c.id == id) {
        return Err("连接不存在".into());
    }
    settings.feiniu_active_id = id;
    state.save_settings(&settings)?;
    state.feiniu.sync_with_settings(&settings);
    Ok(json!({ "ok": true }))
 }
 /// 登录激活/某连接：校验通过后写回该连接的 token/device_id 并启动本地流代理。
 /// fnconnect 连接会先用 fnId 解析出可达 base_url 再登录。
 #[tauri::command]
 pub async fn feiniu_login(
    state: State<'_, MusicManager>,
    connection_id: String,
    username: String,
    password: String,
 ) -> Result<serde_json::Value, String> {
    let mut settings = state.load_settings();
    let mut conn = settings
        .feiniu_connections
        .iter()
        .find(|c| c.id == connection_id)
        .cloned()
        .ok_or_else(|| "连接不存在，请先保存连接".to_string())?;
    // 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?;
        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)?;
    }
    // 用该连接配置装备运行期
    let mut tmp = settings.clone();
    tmp.feiniu_active_id = conn.id.clone();
    state.feiniu.sync_with_settings(&tmp);
    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 = if token_protected { String::new() } else { token.clone() };
        existing.device_id = device_id;
        existing.username = username;
    }
    settings.feiniu_active_id = connection_id.clone();
    state.save_settings(&settings)?;
    state.feiniu.sync_with_settings(&settings);
    let prefix = state.feiniu.media_prefix().await?;
    // 不把 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();
    }
    state.save_settings(&settings)?;
    state.feiniu.sync_with_settings(&settings);
    state.feiniu.logout();
    Ok(json!({ "ok": true }))
 }
 /// 测试一条连接**草案**能否登录（不持久化任何变更）。
 ///
 /// 入参是编辑对话框里的完整草案而非连接 id：新建连接在保存前没有 id，
 /// 若按 id 查库，对话框里的「测试」在保存前必然报 missing required key。
 /// 探测以「草案作为唯一连接」装备运行期，结束后恢复持久化的激活连接。
 #[tauri::command]
 pub async fn feiniu_test_connection(
    state: State<'_, MusicManager>,
    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 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());
    match r {
        Ok(_) => Ok(json!({ "ok": true })),
        Err(e) => Err(e),
    }
 }
 /// 查询当前激活连接配置：{ activeId, baseUrl, username, loggedIn }。
 #[tauri::command]
 pub fn feiniu_get_config(state: State<'_, MusicManager>) -> Result<serde_json::Value, String> {
    let settings = state.load_settings();
    state.feiniu.sync_with_settings(&settings);
    let active_id = settings.feiniu_active_id;
    let mut cfg = state.feiniu.config();
    cfg["activeId"] = json!(active_id);
    Ok(cfg)
 }
 /// 分页拉取激活连接曲目列表：{ page, size, keyword? } → NAS 原始 data。
 #[tauri::command]
 pub async fn feiniu_list_tracks(
    state: State<'_, MusicManager>,
    page: Option<u32>,
    size: Option<u32>,
    keyword: Option<String>,
 ) -> Result<serde_json::Value, String> {
    state.feiniu.sync_with_settings(&state.load_settings());
    state
        .feiniu
        .list_tracks(
            page.unwrap_or(1).max(1),
            size.unwrap_or(50).clamp(1, 100),
            keyword.as_deref(),
        )
        .await
 }
 /// 获取某曲目歌词：{ lyric }（无则空字符串）。
 #[tauri::command]
 pub async fn feiniu_lyric(
    state: State<'_, MusicManager>,
    guid: String,
 ) -> Result<serde_json::Value, String> {
    state.feiniu.sync_with_settings(&state.load_settings());
    let text = state.feiniu.lyric(&guid).await?;
    Ok(json!({ "lyric": text }))
 }
 /// 本地媒体地址前缀：{ mediaPrefix }（首次调用惰性启动本地流代理）。
 #[tauri::command]
 pub async fn feiniu_media_prefix(
    state: State<'_, MusicManager>,
 ) -> Result<serde_json::Value, String> {
    state.feiniu.sync_with_settings(&state.load_settings());
    let prefix = state.feiniu.media_prefix().await?;
    Ok(json!({ "mediaPrefix": prefix }))
 }
 /// 允许访问的本地目录（下载目录 + 自定义曲库目录）。
 /// 本地文件的**列举与删除**都限定在其中——前端只应能操作曲库范围内的文件。
 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 {
        if !dirs.iter().any(|x| x == d) {
            dirs.push(d.clone());
        }
    }
    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 }。
 #[tauri::command]
 pub fn feiniu_cache_status(state: State<'_, MusicManager>) -> Result<serde_json::Value, String> {
    Ok(state.feiniu.cache_status())
 }
 /// 清空播放缓存。
 #[tauri::command]
 pub fn feiniu_cache_clear(state: State<'_, MusicManager>) -> Result<serde_json::Value, String> {
    state.feiniu.cache_clear();
    Ok(json!({ "ok": true }))
 }
 /// 缓存一首歌（命中则直接返回）：{ path } 或 { cached }。
 #[tauri::command]
 pub async fn feiniu_cache_fetch(
    state: State<'_, MusicManager>,
    guid: String,
 ) -> Result<serde_json::Value, String> {
    state.feiniu.sync_with_settings(&state.load_settings());
    let max_gb = state.load_settings().feiniu_cache_max_gb;
    let hit = state.feiniu.cache_fetch(&guid, max_gb).await?;
    Ok(json!({ "path": hit, "cached": hit.is_some() }))
 }
 /// 生成一条新连接的 id（时间戳 + 进程号，避免引 rand）。
 fn new_conn_id() -> String {
    let n = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_nanos())
        .unwrap_or(0);
    format!("c{n:x}")
 }
 // ============ P6：下载到飞牛 + 曲库增删（WebDAV，无状态） ============
 /// 测试 WebDAV 连接与目标目录是否可达。
 #[tauri::command]
 #[specta::specta]
 pub async fn webdav_test(
    config: crate::music::feiniu::webdav::WebDavConfig,
    dir: String,
 ) -> Result<serde_json::Value, String> {
    let msg = crate::music::feiniu::webdav::test(&config, &dir).await?;
    Ok(json!({ "ok": true, "message": msg }))
 }
 /// 上传本地文件到 WebDAV 目标目录（流式，不整载内存）。
 #[tauri::command]
 #[specta::specta]
 pub async fn webdav_upload(
    config: crate::music::feiniu::webdav::WebDavConfig,
    local_path: String,
    remote_path: String,
 ) -> Result<serde_json::Value, String> {
    let name = crate::music::feiniu::webdav::upload_file(
        &config,
        std::path::Path::new(&local_path),
        &remote_path,
    )
    .await?;
    Ok(json!({ "ok": true, "name": name }))
 }
 /// 删除 WebDAV 远程文件（404 视为已删除）。
 #[tauri::command]
 #[specta::specta]
 pub async fn webdav_delete(
    config: crate::music::feiniu::webdav::WebDavConfig,
    remote_path: String,
 ) -> Result<serde_json::Value, String> {
    crate::music::feiniu::webdav::delete(&config, &remote_path).await?;
    Ok(json!({ "ok": true }))
 }
 // ============ 敏感串（系统凭据管理器，DPAPI 保护） ============
 // 统一实现在 crate::music::secrets：WebDAV 账号密码、QQ 音乐 Cookie、飞牛登录 token
 // 三类凭据同构存放，不再出现「一类进凭据库、另一类明文落盘」的双标。
 /// 读取 WebDAV 凭据。未配置时 username/password 为 null。
 #[tauri::command]
 pub fn webdav_get_secret() -> Result<serde_json::Value, String> {
    let parsed = crate::music::secrets::secret_read(crate::music::secrets::KEY_WEBDAV)
        .unwrap_or(None)
        .and_then(|raw| serde_json::from_str::<serde_json::Value>(&raw).ok());
    Ok(parsed.unwrap_or_else(|| json!({ "username": null, "password": null })))
 }
 /// 保存 WebDAV 凭据（账号 + 密码整体覆盖）。
 #[tauri::command]
 pub fn webdav_save_secret(username: String, password: String) -> Result<serde_json::Value, String> {
    let blob = json!({ "username": username, "password": password }).to_string();
    crate::music::secrets::secret_write(crate::music::secrets::KEY_WEBDAV, &blob)?;
    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}"))
    }
 }
 /// 读取一个音乐模块的敏感串（如 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(
    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",
    ];
    let p = std::path::Path::new(&path);
    let ext_ok = p
        .extension()
        .and_then(|e| e.to_str())
        .map(|e| ALLOWED.contains(&e.to_lowercase().as_str()))
        .unwrap_or(false);
    if !ext_ok {
        return Err(format!("拒绝删除非媒体文件：{path}"));
    }
    let meta = std::fs::metadata(p).map_err(|e| format!("文件不存在: {e}"))?;
    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 }))
 }
 // ============ P7：FnConnect 远程连接解析 ============
 /// 解析 fnId → 可达 base_url（探测后返回）。命令层在 fnconnect 连接登录前调用。
 #[tauri::command]
 pub async fn feiniu_fnconnect_resolve(
    state: State<'_, MusicManager>,
    fn_id: String,
 ) -> Result<serde_json::Value, String> {
    let _ = &state;
    let (url, relay) = resolve_base_url(&fn_id).await?;
    Ok(json!({ "baseUrl": url, "relay": relay }))
 }
@@ -0,0 +1,162 @@
 //! 飞牛音乐播放缓存（容量限制 + LRU 逐出）。
 //!
 //! 缓存目录：`{app_data}/music/cache`，文件 `guid.<ext>`（ext 缺省记 `bin`）。
 //! 元数据：`index.json` → `{ "guid": { "size", "lastUsed", "file" } }`。
 //! 超上限按 lastUsed 升序逐出，直到总占用低于上限。
 use std::collections::HashMap;
 use std::fs;
 use std::io::Write;
 use std::path::{Path, PathBuf};
 use std::time::{SystemTime, UNIX_EPOCH};
 use serde::{Deserialize, Serialize};
 use serde_json::json;
 /// 单条缓存元数据
 #[derive(Serialize, Deserialize, Clone)]
 pub struct CacheEntry {
    pub size: u64,
    pub last_used: u64,
    pub file: String,
 }
 pub struct CacheManager {
    root: PathBuf,
    index_path: PathBuf,
 }
 impl CacheManager {
    pub fn new(app_data_dir: &Path) -> Self {
        let root = app_data_dir.join("music").join("cache");
        fs::create_dir_all(&root).ok();
        let index_path = root.join("index.json");
        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()
            .and_then(|s| serde_json::from_str(&s).ok())
            .unwrap_or_default()
    }
    fn save_index(&self, idx: &HashMap<String, CacheEntry>) {
        if let Ok(s) = serde_json::to_string(idx) {
            fs::write(&self.index_path, s).ok();
        }
    }
    fn now_ms(&self) -> u64 {
        SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .map(|d| d.as_millis() as u64)
            .unwrap_or(0)
    }
    /// 命中缓存：更新 lastUsed 并返回文件路径。
    pub fn hit(&self, guid: &str) -> Option<String> {
        let mut idx = self.load_index();
        if let Some(e) = idx.get_mut(guid) {
            let path = self.root.join(&e.file);
            if path.exists() {
                e.last_used = self.now_ms();
                self.save_index(&idx);
                return Some(path.to_string_lossy().to_string());
            }
            idx.remove(guid);
            self.save_index(&idx);
        }
        None
    }
    /// 写入缓存（流式 chunk）；按上限（GB）逐出。返回写入总字节数。
    pub async fn put<E: std::fmt::Display>(
        &self,
        guid: &str,
        ext: &str,
        max_gb: u32,
        mut stream: impl futures_util::Stream<Item = Result<bytes::Bytes, E>> + Unpin,
    ) -> Result<u64, String> {
        let safe_guid = sanitize(guid);
        let ext = if ext.is_empty() { "bin" } else { ext };
        let file = format!("{safe_guid}.{ext}");
        let path = self.root.join(&file);
        let mut total: u64 = 0;
        let mut f = fs::File::create(&path).map_err(|e| format!("创建缓存文件失败: {e}"))?;
        while let Some(chunk) = futures_util::StreamExt::next(&mut stream).await {
            let chunk = chunk.map_err(|e| format!("读取流失败: {e}"))?;
            total += chunk.len() as u64;
            f.write_all(chunk.as_ref()).map_err(|e| format!("写入缓存失败: {e}"))?;
        }
        f.flush().ok();
        let mut idx = self.load_index();
        idx.insert(
            guid.to_string(),
            CacheEntry {
                size: total,
                last_used: self.now_ms(),
                file,
            },
        );
        self.save_index(&idx);
        self.evict(max_gb);
        Ok(total)
    }
    /// 按上限（GB）逐出。max_gb==0 视为全部清空。
    fn evict(&self, max_gb: u32) {
        if max_gb == 0 {
            self.clear();
            return;
        }
        let max_bytes = max_gb as u64 * 1024 * 1024 * 1024;
        let mut idx = self.load_index();
        let mut total: u64 = idx.values().map(|e| e.size).sum();
        let mut order: Vec<(String, u64)> = idx.iter().map(|(g, e)| (g.clone(), e.last_used)).collect();
        order.sort_by_key(|(_, t)| *t);
        for (guid, _) in order {
            if total <= max_bytes {
                break;
            }
            if let Some(e) = idx.remove(&guid) {
                let _ = fs::remove_file(self.root.join(&e.file));
                total = total.saturating_sub(e.size);
            }
        }
        self.save_index(&idx);
    }
    /// 当前占用与条目数。
    pub fn status(&self) -> serde_json::Value {
        let idx = self.load_index();
        let total: u64 = idx.values().map(|e| e.size).sum();
        json!({
            "count": idx.len(),
            "usedBytes": total,
            "usedMb": (total as f64 / 1024.0 / 1024.0 * 10.0).round() / 10.0,
        })
    }
    pub fn clear(&self) {
        let idx = self.load_index();
        for e in idx.values() {
            let _ = fs::remove_file(self.root.join(&e.file));
        }
        fs::remove_file(&self.index_path).ok();
    }
 }
 fn sanitize(s: &str) -> String {
    s.chars()
        .map(|c| if c.is_ascii_alphanumeric() || c == '-' || c == '_' { c } else { '_' })
        .collect()
 }
@@ -0,0 +1,31 @@
 //! 飞牛音乐原生接口纯函数工具（登录签名、地址规范化、设备 ID）。
 //! 接口路径/认证方式对照 FeiNiuMusic(Flutter) `api_client.dart` 的第三方实现。
 use sha2::{Digest, Sha256};
 /// 规范化服务器地址：去首尾空白、去尾部各层斜杠、去误粘贴的 `/music/api/v1` 后缀。
 pub fn normalize_base_url(input: &str) -> String {
    let mut u = input.trim().trim_end_matches('/').to_string();
    let lower = u.to_lowercase();
    if lower.ends_with("/music/api/v1") {
        u = u[..u.len() - "/music/api/v1".len()].to_string();
    }
    u.trim_end_matches('/').to_string()
 }
 /// SHA-256 十六进制（登录时密码签名，对齐原生客户端 `sha256Hex(password)`）。
 pub fn sha256_hex(input: &str) -> String {
    let mut hasher = Sha256::new();
    hasher.update(input.as_bytes());
    format!("{:x}", hasher.finalize())
 }
 /// 32 位 hex 设备 ID（首次生成后落 settings 复用；不依赖 rand，用时间戳+进程号哈希）。
 pub fn generate_device_id() -> String {
    use std::time::{SystemTime, UNIX_EPOCH};
    let nanos = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_nanos())
        .unwrap_or(0);
    sha256_hex(&format!("{}-{}", nanos, std::process::id()))[..32].to_string()
 }
@@ -0,0 +1,295 @@
 //! FnConnect 远程连接解析。
 //!
 //! 链路参考第三方客户端 FnMusic 的 `fn_connection_probe_service.dart`：
 //! 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 std::time::Duration;
 use futures_util::stream::{FuturesUnordered, StreamExt};
 use md5::{Digest, Md5};
 use rand::RngCore;
 use serde_json::{json, Value};
 /// 网关主机（按序回退；5ddd.com 与 fnos.net 为同一服务的不同集群入口）。
 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())
 }
 /// 从输入识别 fnId：`fnos.net/<id>`、`5ddd.com/<id>`、`<id>.fnos.net`、`<id>.5ddd.com`、或裸 fnId。
 pub fn extract_fn_id(input: &str) -> Option<String> {
    let s = input.trim();
    if s.is_empty() {
        return None;
    }
    // 去协议后统一按「可能带路径的 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.to_string());
            }
        }
    }
    // 形如 <id>.<网关>
    for suffix in [".fnos.net", ".5ddd.com"] {
        if let Some(id) = t.strip_suffix(suffix) {
            if !id.is_empty() {
                return Some(id.to_string());
            }
        }
    }
    // 裸 fnId
    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()
    } else {
        serde_json::to_string(data).unwrap_or_default()
    };
    let mut nonce = String::new();
    let mut rng = rand::thread_rng();
    for _ in 0..6 {
        nonce.push(char::from(b'0' + (rng.next_u32() % 10) as u8));
    }
    let timestamp = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_millis().to_string())
        .unwrap_or_default();
    let raw = format!(
        "{FN_AUTHX_PREFIX}_{url}_{nonce}_{timestamp}_{}_{FN_API_KEY}",
        md5_hex(&body)
    );
    format!("nonce={nonce}&timestamp={timestamp}&sign={}", md5_hex(&raw))
 }
 /// 从网关查询 fnId 的连接参数（多网关按序回退）。
 pub async fn query_fn_connect(fn_id: &str) -> Result<Value, String> {
    let client = reqwest::Client::builder()
        .timeout(FN_QUERY_TIMEOUT)
        .build()
        .map_err(|e| e.to_string())?;
    let body = json!({ "fnId": fn_id });
    let authx = fn_authx("post", FN_CON_PATH, &body);
    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", authx.clone())
            .json(&body)
            .send()
            .await
        {
            Ok(r) => r,
            Err(e) => {
                last_err = format!("FnConnect 网关不可达: {e}");
                continue;
            }
        };
        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)
 }
 /// 去掉 `host:port` 形式的端口（仅用于中继域名，中继恒走 443）。
 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<Value> = Vec::new();
    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));
    }
    // 2) 公网 IPv6（NAS 侧可禁用）
    if !data["forbbidPublicIpv6"].as_bool().unwrap_or(false) {
        for ip in strings("publicIpv6") {
            out.push((format!("http://[{ip}]:{http}"), false));
            out.push((format!("https://[{ip}]:{https}"), false));
        }
    }
    // 3) 公网 IPv4
    for ip in strings("publicIpv4") {
        out.push((format!("http://{ip}:{http}"), false));
        out.push((format!("https://{ip}:{https}"), false));
    }
    // 4) 中继：仅 HTTPS；网关未返回时按两种集群域名兜底
    let mut relays = strings("fn");
    if relays.is_empty() {
        relays = vec![
            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 是否可用（中继候选携带 `mode=relay` 才会被网关转发）。
 ///
 /// 判据必须排除 3xx：重定向说明请求**没有真正落到 NAS 音乐后端**
 /// （中继缺 `mode=relay` 时网关 302 回登录页；端口上实际是 fnOS Web UI 时同样 302）。
 /// 早先把「任何 < 500」都当可达，结果候选探测通过、紧接着登录报 `HTTP 302 Found`。
 async fn probe(client: &reqwest::Client, url: &str, relay: bool) -> bool {
    let timeout = if relay {
        FN_PROBE_TIMEOUT_RELAY
    } 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)`。
 ///
 /// 所有候选并发探测，按优先级（索引越小越优先）取首个确认可达者并早停，
 /// 避免远程场景下顺序探测逐个等待超时。
 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, fn_id);
    if candidates.is_empty() {
        return Err("FnConnect 未返回可用地址".into());
    }
    let client = reqwest::Client::builder()
        .timeout(FN_PROBE_TIMEOUT_RELAY)
        .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())),
    }
 }
@@ -0,0 +1,743 @@
 //! 飞牛音乐(NAS)原生接口客户端 + 本地流代理的运行期。
 //!
 //! 支持多连接（本地 / frp / 预留 FnConnect），当前以"激活连接"为准。
 //! 原生接口路径/认证（`music-token` Cookie、`x-access-code` 安全码、`/user/password-login` 登录）
 //! 对照 FeiNiuMusic(Flutter) `api_client.dart` 的第三方纯前端实现翻译。
 //! 所有对 NAS 的 HTTP 请求在本模块收敛（页面/命令层不直接发请求）。
 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};
 use super::MusicSettings;
 pub use conn::normalize_base_url;
 mod cache;
 mod conn;
 mod fnconnect;
 pub mod proxy;
 pub mod webdav;
 pub use cache::CacheManager;
 pub use fnconnect::{extract_fn_id, resolve_base_url};
 use conn::{generate_device_id, sha256_hex};
 use proxy::{ProxyCfg, ProxyShared};
 /// 一条飞牛音乐连接（持久化在 `MusicSettings`）。
 #[derive(Serialize, Deserialize, Clone, Type)]
 #[serde(rename_all = "camelCase")]
 pub struct FeiniuConnection {
    pub id: String,
    pub name: String,
    /// "lan" | "frp" | "fnconnect"（fnconnect 预留）
    pub kind: String,
    /// 服务器地址（http://192.168.x.x:5666 或 https://域名）
    pub base_url: String,
    pub username: String,
    pub token: String,
    pub device_id: String,
    pub access_code: String,
    /// https 遇到自签证书时忽略校验
    pub insecure: bool,
    /// 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 {
    fn default() -> Self {
        Self {
            id: String::new(),
            name: String::new(),
            kind: "lan".to_string(),
            base_url: String::new(),
            username: String::new(),
            token: String::new(),
            device_id: String::new(),
            access_code: String::new(),
            insecure: false,
            fn_id: String::new(),
            relay: false,
        }
    }
 }
 /// 当前激活连接信息（运行期副本，与 `MusicSettings` 的激活连接一致）。
 struct Conn {
    base_url: String,
    token: String,
    username: String,
    device_id: String,
    access_code: String,
    insecure: bool,
    /// FnConnect 中继链路标记
    relay: bool,
 }
 /// LAN 直连，`no_proxy` 避免被代理模块(mihomo)拦走；按 insecure 惰性重建（支持自签证书）。
 struct ClientSlot {
    insecure: bool,
    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,
 }
 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(),
                username: String::new(),
                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 重建
        }
    }
 }
 /// 按 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);
    }
    /// 本地曲库标签缓存文件路径（{cache_root}/local-tags.json）。
    pub fn local_tags_path(&self) -> PathBuf {
        self.cache.local_tags_path()
    }
    /// 取（并惰性构建）对应 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, relay) =
            match s.feiniu_active() {
                Some(c) => (
                    c.base_url.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(),
                    String::new(),
                    String::new(),
                    String::new(),
                    String::new(),
                    false,
                    false,
                ),
            };
        if let Ok(mut c) = self.conn.lock() {
            c.base_url = base_url;
            c.token = token;
            c.username = username;
            c.device_id = device_id;
            c.access_code = access_code;
            c.insecure = insecure;
            c.relay = relay;
        }
        // 确保 client 构建到位（insecure 变化时重建）
        self.client(insecure);
        self.sync_proxy_cfg();
        self.sync_proxy_client();
    }
    fn sync_proxy_cfg(&self) {
        if let Ok(g) = self.proxy.lock() {
            if let Some((_, shared)) = g.as_ref() {
                let cfg = self.current_cfg();
                if let Ok(mut c) = shared.cfg.lock() {
                    *c = cfg;
                }
            }
        }
    }
    fn sync_proxy_client(&self) {
        // 代理必须用流式 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;
            }
        }
    }
    fn conn_client(&self) -> (bool, reqwest::Client) {
        let insecure = self.conn.lock().unwrap_or_else(|e| e.into_inner()).insecure;
        (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,
        }
    }
    /// 构造鉴权 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.relay,
        )
    }
    /// 对某个 base_url 执行登录（探测/登录连接共用）。
    /// 成功返回 `(userToken, device_id)` 并更新运行期 conn；命令层负责落回对应连接持久化。
    pub async fn login(
        &self,
        base_url: &str,
        username: &str,
        password: &str,
    ) -> Result<(String, String), String> {
        let base = normalize_base_url(base_url);
        let (device_id, insecure) = {
            let c = self.conn.lock().unwrap_or_else(|e| e.into_inner());
            let d = if c.device_id.is_empty() {
                generate_device_id()
            } else {
                c.device_id.clone()
            };
            (d, c.insecure)
        };
        let body = json!({
            "username": username,
            "password": sha256_hex(password),
            "deviceId": device_id,
        });
        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);
        // 中继链路：登录请求也需带 mode=relay，否则网关 302 回登录页
        if let Some(cookie) = Self::auth_cookie("", relay) {
            rb = rb.header("cookie", cookie);
        }
        let resp = rb
            .send()
            .await
            .map_err(|e| {
                let kind = if e.is_timeout() {
                    "连接超时（NAS 不可达？）"
                } else {
                    "连接失败"
                };
                format!("{kind}: {e}")
            })?;
        let status = resp.status();
        let b: Value = resp
            .json()
            .await
            .unwrap_or_else(|_| json!({ "code": status.as_u16() }));
        let code = b["code"].as_i64().unwrap_or(i64::from(status.as_u16()));
        if code != 0 {
            if code == 120001 {
                return Err("用户名或密码错误".into());
            }
            let msg = b["msg"]
                .as_str()
                .map(|s| s.to_string())
                .unwrap_or_else(|| format!("HTTP {status}"));
            return Err(msg);
        }
        let token = b["data"]["userToken"]
            .as_str()
            .ok_or_else(|| "登录失败：未返回 token".to_string())?
            .to_string();
        if let Ok(mut c) = self.conn.lock() {
            c.base_url = base;
            c.token = token.clone();
            c.username = username.to_string();
            c.device_id = device_id.clone();
        }
        self.sync_proxy_cfg();
        Ok((token, device_id))
    }
    /// 登出：仅清运行期 token（保留连接信息与账号）。
    pub fn logout(&self) {
        if let Ok(mut c) = self.conn.lock() {
            c.token.clear();
        }
        self.sync_proxy_cfg();
    }
    /// 当前激活连接配置（前端状态展示 + 是否已登录）。
    pub fn config(&self) -> Value {
        let c = self.conn.lock().unwrap_or_else(|e| e.into_inner());
        json!({
            "baseUrl": c.base_url,
            "username": c.username,
            "loggedIn": !c.token.is_empty(),
        })
    }
    /// 分页拉取曲目列表：`GET /music/api/v1/track/list`（可选关键词）。
    pub async fn list_tracks(&self, page: u32, size: u32, keyword: Option<&str>) -> Result<Value, String> {
        let mut query = vec![
            ("page".to_string(), page.to_string()),
            ("size".to_string(), size.to_string()),
        ];
        let kw = keyword.unwrap_or("").trim().to_string();
        if !kw.is_empty() {
            query.push(("keyword".to_string(), kw));
        }
        self.authed_get("/music/api/v1/track/list", query).await
    }
    /// 歌词：`GET /music/api/v1/lyric/list?trackGUID=<guid>`。
    pub async fn lyric(&self, guid: &str) -> Result<String, String> {
        let v = self
            .authed_get(
                "/music/api/v1/lyric/list",
                vec![("trackGUID".to_string(), guid.to_string())],
            )
            .await?;
        Ok(extract_lyric_text(&v))
    }
    /// 本地媒体地址前缀：`http://127.0.0.1:<port>/feiniu`。首次调用惰性启动代理。
    pub async fn media_prefix(&self) -> Result<String, String> {
        let port = self.ensure_proxy().await?;
        Ok(format!("http://127.0.0.1:{port}/feiniu"))
    }
    /// 缓存状态。
    pub fn cache_status(&self) -> Value {
        self.cache.status()
    }
    /// 清空缓存。
    pub fn cache_clear(&self) {
        self.cache.clear();
    }
    /// 命中缓存直接返回文件路径；未命中则从 NAS 流式拉取写入缓存后返回。
    /// 返回缓存文件路径。失败返回 Err。
    pub async fn cache_fetch(&self, guid: &str, max_gb: u32) -> Result<Option<String>, String> {
        if let Some(hit) = self.cache.hit(guid) {
            return Ok(Some(hit));
        }
        let (base, token, access_code, relay) = self.auth_triple();
        if base.is_empty() || token.is_empty() {
            return Err("未登录".into());
        }
        // 整首拉取写入缓存：同样用无总超时的 client，否则大文件会被 10s 超时截断
        let (_, client) = self.conn_stream_client();
        let mut rb = client.get(format!("{base}/music/api/v1/track/stream?guid={guid}"));
        if let Some(cookie) = Self::auth_cookie(&token, relay) {
            rb = rb.header("cookie", cookie);
        }
        if !access_code.is_empty() {
            use base64::Engine;
            rb = rb
                .header(
                    "x-access-code",
                    base64::engine::general_purpose::STANDARD.encode(access_code.as_bytes()),
                )
                .header("x-access-source", "app");
        }
        let resp = rb.send().await.map_err(|e| format!("拉取失败: {e}"))?;
        if !resp.status().is_success() {
            return Err(format!("拉取失败（HTTP {}）", resp.status().as_u16()));
        }
        let ct = resp
            .headers()
            .get("content-type")
            .and_then(|v| v.to_str().ok())
            .map(|s| s.to_string())
            .unwrap_or_default();
        let ext = match ct.split('/').last() {
            Some("flac") => "flac",
            Some("mpeg") => "mp3",
            Some("wav") => "wav",
            Some("ogg") => "ogg",
            Some("mp4") => "m4a",
            Some("aac") => "aac",
            _ => "bin",
        };
        let stream = resp.bytes_stream();
        let path = self
            .cache
            .put(guid, ext, max_gb, stream)
            .await
            .map_err(|e| e)?;
        let _ = path;
        Ok(self.cache.hit(guid))
    }
    // ===== WebDAV 传输（下载到飞牛 / 曲库增删）=====
    // 无状态：配置由前端每次调用传入，实现在 webdav 模块，命令层直接调用。
    async fn ensure_proxy(&self) -> Result<u16, String> {
        if let Ok(g) = self.proxy.lock() {
            if let Some((port, _)) = g.as_ref() {
                return Ok(*port);
            }
        }
        // 流代理用无总超时的 client（见 build_client）
        let (_, client) = self.conn_stream_client();
        let shared = ProxyShared {
            client,
            cfg: Arc::new(Mutex::new(self.current_cfg())),
        };
        let port = proxy::start(shared.clone()).await?;
        if let Ok(mut g) = self.proxy.lock() {
            *g = Some((port, shared));
        }
        Ok(port)
    }
    async fn authed_get(&self, path: &str, query: Vec<(String, String)>) -> Result<Value, String> {
        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);
        if let Some(cookie) = Self::auth_cookie(&token, relay) {
            rb = rb.header("cookie", cookie);
        }
        if !access_code.is_empty() {
            use base64::Engine;
            rb = rb
                .header(
                    "x-access-code",
                    base64::engine::general_purpose::STANDARD.encode(access_code.as_bytes()),
                )
                .header("x-access-source", "app");
        }
        let resp = rb.send().await.map_err(|e| format!("请求失败: {e}"))?;
        let status = resp.status();
        let body: Value = resp
            .json()
            .await
            .unwrap_or_else(|_| json!({ "code": status.as_u16() }));
        let code = body["code"].as_i64().unwrap_or(i64::from(status.as_u16()));
        if code != 0 {
            if status == StatusCode::UNAUTHORIZED || status == StatusCode::FORBIDDEN {
                return Err("登录已过期，请重新登录".into());
            }
            let msg = body["msg"]
                .as_str()
                .map(|s| s.to_string())
                .unwrap_or_else(|| format!("请求失败（HTTP {status}）"));
            return Err(msg);
        }
        Ok(body["data"].clone())
    }
 }
 /// 本地曲库 / 下载目录里认可的音频扩展名。
 /// 扫描（递归）与单目录列举共用同一份，避免两处判定不一致。
 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 {
        Value::Array(arr) => arr
            .first()
            .map(|it| {
                it["content"]
                    .as_str()
                    .or_else(|| it["lyric"].as_str())
                    .or_else(|| it["text"].as_str())
                    .unwrap_or("")
                    .to_string()
            })
            .unwrap_or_default(),
        Value::Object(_) => v["content"]
            .as_str()
            .or_else(|| v["lyric"].as_str())
            .or_else(|| v["text"].as_str())
            .unwrap_or("")
            .to_string(),
        _ => String::new(),
    }
 }
@@ -0,0 +1,237 @@
 //! 飞牛音乐本地流代理（axum）。
 //!
 //! 原生 `/track/stream`、`/static/cover` 需要 `Cookie: music-token=<token>`，而
 //! WebView 的 `<audio>/<img>` 无法设置 Cookie。本模块绑定 `127.0.0.1:<动态端口>`，
 //! 转发请求时注入 Cookie 与可选的安全码头，前端直接用本地地址播放/显示，天然支持 Range/seek。
 use std::collections::HashMap;
 use std::sync::{Arc, Mutex};
 use axum::{
    extract::{Query, State},
    http::{header, HeaderMap, StatusCode},
    response::{IntoResponse, Response},
    routing::get,
    Router,
 };
 use lofty::file::TaggedFileExt;
 use super::conn::normalize_base_url;
 /// 由 Feiniu 运行期与代理 handler 共享的连接配置（登录更新、登出置空）。
 #[derive(Clone, Default)]
 pub struct ProxyCfg {
    pub base_url: String,
    pub token: String,
    pub access_code: String,
    /// FnConnect 中继链路：所有请求需携带 `Cookie: mode=relay`
    pub relay: bool,
 }
 #[derive(Clone)]
 pub struct ProxyShared {
    pub client: reqwest::Client,
    pub cfg: Arc<Mutex<ProxyCfg>>,
 }
 /// 启动本地流代理，绑定到 `127.0.0.1:0`（动态空闲端口），返回实际端口。
 /// 代理以独立 tokio 任务常驻应用存活期；token 变化经共享 `ProxyCfg` 即时生效，无需重启。
 pub async fn start(shared: ProxyShared) -> Result<u16, String> {
    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
        .await
        .map_err(|e| format!("绑定本地端口失败: {e}"))?;
    let port = listener
        .local_addr()
        .map_err(|e| e.to_string())?
        .port();
    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 {
            crate::logger::log_error("music", &format!("飞牛流代理异常: {e}"));
        }
    });
    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>>,
    headers: HeaderMap,
 ) -> Response {
    let guid = q.get("guid").cloned().unwrap_or_default().trim().to_string();
    if guid.is_empty() {
        return (StatusCode::BAD_REQUEST, "missing guid").into_response();
    }
    forward(
        &s,
        "/music/api/v1/track/stream",
        vec![("guid".to_string(), guid)],
        &headers,
    )
    .await
 }
 async fn proxy_cover(
    State(s): State<ProxyShared>,
    Query(q): Query<HashMap<String, String>>,
    headers: HeaderMap,
 ) -> Response {
    let cover_id = q
        .get("coverId")
        .cloned()
        .unwrap_or_default()
        .trim()
        .to_string();
    if cover_id.is_empty() {
        return (StatusCode::BAD_REQUEST, "missing coverId").into_response();
    }
    let size = q.get("size").cloned().unwrap_or_else(|| "320".into());
    forward(
        &s,
        "/music/api/v1/static/cover",
        vec![
            ("coverId".to_string(), cover_id),
            ("size".to_string(), size),
        ],
        &headers,
    )
    .await
 }
 /// 统一转发：向 NAS 发起上游 GET，注入 Cookie/安全码，透传 Range 与响应头，流式回传 body。
 async fn forward(
    s: &ProxyShared,
    path: &str,
    query: Vec<(String, String)>,
    headers: &HeaderMap,
 ) -> Response {
    let cfg = match s.cfg.lock() {
        Ok(g) => g.clone(),
        Err(e) => e.into_inner().clone(),
    };
    if cfg.base_url.is_empty() || cfg.token.is_empty() {
        return (StatusCode::UNAUTHORIZED, "飞牛音乐未登录").into_response();
    }
    let base = normalize_base_url(&cfg.base_url);
    let url = format!("{base}{path}");
    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);
    // 中继链路必须带 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
            .header(
                "x-access-code",
                base64::engine::general_purpose::STANDARD.encode(cfg.access_code.as_bytes()),
            )
            .header("x-access-source", "app");
    }
    if let Some(range) = headers.get(header::RANGE) {
        rb = rb.header(header::RANGE, range.clone());
    }
    drop(cfg);
    let resp = match rb.send().await {
        Ok(r) => r,
        Err(e) => return (StatusCode::BAD_GATEWAY, format!("上游错误: {e}")).into_response(),
    };
    let status = resp.status();
    let ct = resp.headers().get(header::CONTENT_TYPE).cloned();
    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);
    *out.status_mut() = status;
    let h = out.headers_mut();
    if let Some(v) = ct {
        h.insert(header::CONTENT_TYPE, v);
    }
    if let Some(v) = cl {
        h.insert(header::CONTENT_LENGTH, v);
    }
    if let Some(v) = cr {
        h.insert(header::CONTENT_RANGE, v);
    }
    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
 }
@@ -0,0 +1,205 @@
 //! WebDAV 客户端（无状态）——用于把音乐传输到 fnOS NAS 的曲库目录。
 //!
 //! 选择 WebDAV 而非 SMB/FTP/NFS 的原因：
 //! - 纯 HTTP 语义，`reqwest` 即可实现，无原生依赖（SMB 在 Rust 侧生态差）；
 //! - **无会话**：Basic 认证随每个请求携带，没有"重启后要重新登录"的问题；
 //! - fnOS 原生支持：系统设置 → 文件服务 → WebDAV（HTTP 5005 / HTTPS 5006）。
 //!
 //! fnOS 侧需要的设置（作为 UI 提示展示）：
 //! 1. 开启 WebDAV 服务并记下端口；
 //! 2. 目标文件夹必须在「可见文件夹范围」内（团队文件夹需勾选
 //!    「允许通过文件共享协议(SMB、WebDAV、FTP)挂载到其他设备上」）；
 //! 3. 账号对该文件夹有读写权限。
 use bytes::Bytes;
 use serde::{Deserialize, Serialize};
 use std::time::Duration;
 /// WebDAV 连接配置（由前端每次调用时传入，后端不持有状态）。
 #[derive(Debug, Clone, Deserialize, Serialize, specta::Type)]
 pub struct WebDavConfig {
    /// 服务地址，如 `http://192.168.110.100:5005`
    pub url: String,
    pub username: String,
    pub password: String,
 }
 /// WebDAV 操作结果状态码相关的可读错误。
 fn status_err(action: &str, status: u16, url: &str) -> String {
    match status {
        401 => format!("WebDAV 认证失败（401）：请检查账号与密码"),
        403 => format!("WebDAV 拒绝访问（403）：账号可能没有该目录的写入权限"),
        404 => format!("WebDAV 目标不存在（404）：{url}（目录需要先在 NAS 上创建，且在 WebDAV 可见范围内）"),
        409 => format!("WebDAV 父目录不存在（409）：{url}"),
        _ => format!("WebDAV {action}失败（HTTP {status}）：{url}"),
    }
 }
 fn dav_client(_cfg: &WebDavConfig) -> Result<reqwest::Client, String> {
    // NAS 通常在内网，默认禁用系统代理（走代理会连不上）；Basic 认证在请求级设置
    reqwest::Client::builder()
        .timeout(Duration::from_secs(600))
        .connect_timeout(Duration::from_secs(10))
        .no_proxy()
        .build()
        .map_err(|e| e.to_string())
 }
 /// 拼接 WebDAV 完整 URL：base + 远程路径（逐段百分号编码，保留 `/`）。
 fn dav_url(cfg: &WebDavConfig, remote_path: &str) -> String {
    let base = cfg.url.trim_end_matches('/');
    let path = remote_path.trim_start_matches('/');
    let encoded: Vec<String> = path
        .split('/')
        .filter(|s| !s.is_empty())
        .map(|seg| {
            let mut out = String::new();
            for b in seg.bytes() {
                match b {
                    b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
                        out.push(b as char)
                    }
                    _ => out.push_str(&format!("%{b:02X}")),
                }
            }
            out
        })
        .collect();
    format!("{base}/{}", encoded.join("/"))
 }
 fn with_auth(mut rb: reqwest::RequestBuilder, cfg: &WebDavConfig) -> reqwest::RequestBuilder {
    if !cfg.username.is_empty() {
        rb = rb.basic_auth(&cfg.username, Some(&cfg.password));
    }
    rb
 }
 /// 逐级 MKCOL 创建远程目录（已存在会被忽略）。
 async fn ensure_dirs(cfg: &WebDavConfig, remote_path: &str) -> Result<(), String> {
    let path = remote_path.trim_start_matches('/');
    let segs: Vec<&str> = path.split('/').filter(|s| !s.is_empty()).collect();
    // 最后一段是文件名，只建目录部分
    let dirs: Vec<String> = segs
        .iter()
        .take(segs.len().saturating_sub(1))
        .fold(Vec::new(), |mut acc, s| {
            let prev = acc.last().cloned().unwrap_or_default();
            acc.push(if prev.is_empty() {
                s.to_string()
            } else {
                format!("{prev}/{s}")
            });
            acc
        });
    let client = dav_client(cfg)?;
    for d in dirs {
        let url = dav_url(cfg, &d);
        let method = reqwest::Method::from_bytes(b"MKCOL").expect("MKCOL 是合法的 HTTP 方法");
        let resp = with_auth(client.request(method, &url), cfg)
            .send()
            .await
            .map_err(|e| format!("WebDAV MKCOL 失败: {e}"))?;
        // 201 创建成功；405 已存在；其余只记不阻断（权限问题会在 PUT 时暴露）
        let code = resp.status().as_u16();
        if code != 201 && code != 405 && code != 301 && code != 409 && code != 200 {
            return Err(status_err("创建目录", code, &url));
        }
    }
    Ok(())
 }
 /// 测试连接：PROPFIND 目标目录（Depth 0）。成功返回目录确认信息。
 pub async fn test(cfg: &WebDavConfig, dir: &str) -> Result<String, String> {
    let url = dav_url(cfg, dir);
    let client = dav_client(cfg)?;
    let resp = with_auth(
        client
            .request(reqwest::Method::from_bytes(b"PROPFIND").unwrap(), &url)
            .header("Depth", "0")
            .body(String::new()),
        cfg,
    )
    .send()
    .await
    .map_err(|e| format!("无法连接 WebDAV 服务：{e}（请确认地址与端口）"))?;
    let code = resp.status().as_u16();
    match code {
        207 | 200 => Ok(format!("连接成功：{url}")),
        404 => Err(format!(
            "WebDAV 服务可达，但目标目录不存在（404）：{url}\n请先在 NAS 上创建该目录，并确认它在 WebDAV「可见文件夹范围」内"
        )),
        401 => Err("WebDAV 认证失败（401）：请检查账号与密码".to_string()),
        403 => Err("WebDAV 拒绝访问（403）：账号可能没有该目录的读取权限".to_string()),
        _ => Err(status_err("连接", code, &url)),
    }
 }
 /// 上传本地文件（流式读取，不整载内存）。返回远程路径。
 pub async fn upload_file(
    cfg: &WebDavConfig,
    local_path: &std::path::Path,
    remote_path: &str,
 ) -> Result<String, String> {
    ensure_dirs(cfg, remote_path).await?;
    let file = tokio::fs::File::open(local_path)
        .await
        .map_err(|e| format!("读取本地文件失败: {e}"))?;
    // 128KB 分块流：用 unfold 把 AsyncRead 转 Stream，避免引入 tokio-util
    let stream = futures_util::stream::unfold(file, |mut f| async move {
        use tokio::io::AsyncReadExt;
        let mut buf = vec![0u8; 128 * 1024];
        match f.read(&mut buf).await {
            Ok(0) => None,
            Ok(n) => Some((Ok::<Bytes, std::io::Error>(Bytes::copy_from_slice(&buf[..n])), f)),
            Err(e) => Some((Err(e), f)),
        }
    });
    let url = dav_url(cfg, remote_path);
    let client = dav_client(cfg)?;
    let resp = with_auth(client.put(&url), cfg)
        .header("Content-Type", mime_of(remote_path))
        .body(reqwest::Body::wrap_stream(stream))
        .send()
        .await
        .map_err(|e| format!("WebDAV 上传失败: {e}"))?;
    let code = resp.status().as_u16();
    if !(200..300).contains(&code) {
        return Err(status_err("上传", code, &url));
    }
    Ok(remote_path.to_string())
 }
 /// 删除远程文件（404 视为已删除）。
 pub async fn delete(cfg: &WebDavConfig, remote_path: &str) -> Result<(), String> {
    let url = dav_url(cfg, remote_path);
    let client = dav_client(cfg)?;
    let resp = with_auth(client.delete(&url), cfg)
        .send()
        .await
        .map_err(|e| format!("WebDAV 删除失败: {e}"))?;
    let code = resp.status().as_u16();
    if code == 404 {
        return Ok(());
    }
    if !(200..300).contains(&code) {
        return Err(status_err("删除", code, &url));
    }
    Ok(())
 }
 pub fn mime_of(name: &str) -> &'static str {
    let ext = name.rsplit('.').next().unwrap_or("").to_lowercase();
    match ext.as_str() {
        "mp3" => "audio/mpeg",
        "flac" => "audio/flac",
        "wav" => "audio/wav",
        "m4a" => "audio/mp4",
        "aac" => "audio/aac",
        "ogg" => "audio/ogg",
        "ape" => "audio/x-ape",
        _ => "application/octet-stream",
    }
 }
@@ -0,0 +1,682 @@
 //! 音乐下载模块（musicdl 桥接）。
 //!
 //! 架构：Vue 前端 → Tauri 命令 → [MusicManager] → stdio JSON-Lines → `bridge.py`
 //! → musicdl（纯 Python 聚合下载器）。
 //!
 //! 目录布局（{app_data_dir}/music/）：
 //! - `bridge.py`：桥接脚本（include_str! 内置，运行时写出）
 //! - `runtime/python/`：便携 Python（python.org embeddable，含 pip）
 //! - `runtime/get-pip.py`：pip 引导脚本（下载后删除）
 //! - `runtime/*.zip`：下载过程中的临时安装包（完成后删除）
 //! - `outputs/`：默认音乐下载目录
 //!
 //! 子模块：
 //! - [`runtime`]：Python 运行时探测与便携版安装
 //! - [`bridge`]：桥接进程生命周期（spawn / JSON 协议 / ping / 停止）
 //! - [`commands`]：Tauri 命令层
 mod bridge;
 mod commands;
 mod feiniu;
 mod runtime;
 mod secrets;
 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_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_secret_get, music_secret_set,
    music_stop_bridge, music_update_musicdl, webdav_delete, webdav_get_secret,
    webdav_save_secret, webdav_test, webdav_upload,
 };
 use serde::{Deserialize, Serialize};
 use specta::Type;
 use std::collections::HashMap;
 use std::fs;
 use std::path::PathBuf;
 use std::process::{Child, ChildStdin};
 use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
 use std::sync::{Arc, Mutex};
 use std::time::{Duration, Instant};
 use tauri::AppHandle;
 /// 便携 Python 版本（python.org embeddable，含 pip 引导）
 pub const BUNDLED_PY_VERSION: &str = "3.12.10";
 /// musicdl 锁定版本（其 API 每周都在变，必须锁版本并定期升级）
 pub const MUSICDL_VERSION: &str = "2.13.11";
 /// pip 镜像源（国内网络直连 PyPI 较慢，默认用清华镜像，可改回官方）
 pub const PIP_INDEX_URL: &str = "https://pypi.tuna.tsinghua.edu.cn/simple";
 /// 默认搜索源（网易云 / QQ音乐 / 酷狗）
 pub const DEFAULT_SOURCES: [&str; 3] = [
    "NeteaseMusicClient",
    "QQMusicClient",
    "KugouMusicClient",
 ];
 /// 桥接进程条目（自管 stdio，不走 ProcessManager）
 pub(crate) struct BridgeEntry {
    pub child: Child,
    pub stdin: ChildStdin,
 }
 /// 解析出的 Python 运行时信息（内部使用，不序列化）
 pub(crate) struct PythonEnv {
    pub source: &'static str, // "system" | "bundled"
    pub exe: PathBuf,
    pub version: String,
 }
 /// 环境状态（返回前端，设置页「环境检查」面板展示）
 #[derive(Serialize, Clone, Type)]
 #[serde(rename_all = "camelCase")]
 pub struct MusicEnvStatus {
    /// 系统 Python 版本（如 "3.14.5"），无则 None
    pub python: Option<String>,
    /// python 来源："system" | "bundled" | "none"
    pub python_source: String,
    /// 便携 Python 可执行文件路径（未安装则 None）
    pub bundled_python: Option<String>,
    /// musicdl 是否可导入
    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>,
    /// 桥接进程是否在运行
    pub bridge_running: bool,
    /// 运行时目录（{app_data_dir}/music）
    pub runtime_dir: String,
 }
 /// 运行时安装进度事件负载（对应 events::MUSIC_RUNTIME_INSTALL_PROGRESS）
 #[derive(Serialize, Clone, Type)]
 #[serde(rename_all = "camelCase")]
 pub struct MusicInstallProgress {
    pub stage: String,
    pub percent: u32,
    pub downloaded_bytes: u64,
    pub total_bytes: Option<u64>,
    pub message: String,
 }
 /// 音乐模块设置（settings.json 持久化；变更即时生效）
 #[derive(Serialize, Deserialize, Clone, Type)]
 #[serde(rename_all = "camelCase")]
 pub struct MusicSettings {
    /// 下载保存目录
    pub savedir: String,
    /// 搜索源（musicdl 客户端名，如 NeteaseMusicClient）
    pub sources: Vec<String>,
    /// 下载时同步保存歌词
    pub lyric_download: bool,
    /// 下载时同步保存封面
    pub cover_download: bool,
    /// 搜索/下载请求是否走代理模块（mihomo mixed 端口）
    pub use_proxy: bool,
    /// 最大并发下载数
    pub max_concurrent: u32,
    /// 下载引擎："musicdl" | "rust"（P2 生效）
    pub download_engine: String,
    /// 下载时是否弹窗选择音质（默认关；开启后点下载弹出所选歌曲档位并集选择）
    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,
    /// 飞牛音乐登录 token（登录成功后保存）
    #[serde(default)]
    pub feiniu_token: String,
    /// 飞牛音乐登录账号（展示 + 重新登录回填用）
    #[serde(default)]
    pub feiniu_username: String,
    /// 飞牛音乐设备 ID（32 位 hex，登录签名用，一次生成复用）
    #[serde(default)]
    pub feiniu_device_id: String,
    /// 飞牛音乐访问安全码（可选；仅需访问码的库才填，LAN 通常为空）
    #[serde(default)]
    pub feiniu_access_code: String,
    /// 飞牛音乐连接列表（多连接：局域网 / FnConnect）
    #[serde(default)]
    pub feiniu_connections: Vec<FeiniuConnection>,
    /// 当前激活连接的 id
    #[serde(default)]
    pub feiniu_active_id: String,
    /// 本地曲库扫描目录（默认含音乐下载 savedir）
    #[serde(default)]
    pub feiniu_local_dirs: Vec<String>,
    /// 播放缓存开关
    #[serde(default)]
    pub feiniu_cache_enabled: bool,
    /// 缓存上限（GB）
    #[serde(default)]
    pub feiniu_cache_max_gb: u32,
    /// 播放模式："stream" 直连流式 | "cache" 缓存后播放
    #[serde(default)]
    pub feiniu_play_mode: String,
    /// 飞牛曲库目标目录（NAS 绝对路径，如 vol1/1000/Music；上传到飞牛用）
    #[serde(default)]
    pub feiniu_library_nas_path: String,
    /// 下载完成后自动上传到飞牛曲库
    #[serde(default)]
    pub feiniu_auto_upload: bool,
 }
 impl MusicSettings {
    /// 取激活连接：优先按 active_id，否则回退到第一条。
    pub fn feiniu_active(&self) -> Option<&FeiniuConnection> {
        self.feiniu_connections
            .iter()
            .find(|c| c.id == self.feiniu_active_id)
            .or_else(|| self.feiniu_connections.first())
    }
    /// 兼容旧版单连接字段：把旧字段迁移成列表里的一条连接，并**清除旧字段**。
    ///
    /// 必须是「一次性」的：旧字段一旦残留，用户把连接删光后，下一次 `load_settings()`
    /// 会再次命中「列表为空 + 旧字段非空」而重新造出一条连接，
    /// 表现为「删掉的连接切个页又回来了」。因此迁移完成后要清空旧字段，
    /// 且返回是否发生变更，由 `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(),
                name: base.clone(),
                kind: "lan".to_string(),
                base_url: base,
                username: self.feiniu_username.clone(),
                token: self.feiniu_token.clone(),
                device_id: self.feiniu_device_id.clone(),
                access_code: self.feiniu_access_code.clone(),
                insecure: false,
                fn_id: String::new(),
                relay: false,
            });
            self.feiniu_active_id = "default".to_string();
            changed = true;
        }
        // 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
    }
 }
 /// settings 内存缓存条目（短时复用，避免高频调用反复读盘）
 struct SettingsCacheEntry {
    read_at: Instant,
    settings: MusicSettings,
 }
 /// 音乐模块管理器
 pub struct MusicManager {
    root: PathBuf,
    client: reqwest::Client,
    /// 桥接进程（stdio 自管）
    bridge: Mutex<Option<BridgeEntry>>,
    /// 待响应请求表：id → oneshot（reader 线程按 id 分发）
    pending: Arc<Mutex<HashMap<u64, tokio::sync::oneshot::Sender<serde_json::Value>>>>,
    /// 请求 id 自增
    next_id: AtomicU64,
    /// 便携运行时安装/下载取消标志
    runtime_cancel: Arc<AtomicBool>,
    /// 正在执行的 pip/python 子进程 pid（取消时 taskkill）
    install_pid: Arc<AtomicU64>,
    /// 桥接启动互斥锁（防止并发 ensure_bridge 双重 spawn）
    start_lock: Mutex<()>,
    /// settings 内存缓存
    settings_cache: Mutex<Option<SettingsCacheEntry>>,
    /// 飞牛音乐(NAS)播放器运行期（连接 + 本地流代理）
    feiniu: Feiniu,
    /// AppHandle（桥接 reader 线程据此将事件转发给前端；setup 时设置）
    app: Mutex<Option<AppHandle>>,
 }
 impl MusicManager {
    pub fn new(app_data_dir: PathBuf) -> Self {
        let root = app_data_dir.join("music");
        for d in ["runtime", "outputs"] {
            fs::create_dir_all(root.join(d)).ok();
        }
        let mut feiniu = Feiniu::default();
        feiniu.set_cache_root(&app_data_dir);
        Self {
            root,
            client: reqwest::Client::builder()
                // 默认 30s 兜底超时；流式下载按块推进，不受此限制
                .timeout(std::time::Duration::from_secs(30))
                .build()
                .unwrap_or_else(|_| reqwest::Client::new()),
            bridge: Mutex::new(None),
            pending: Arc::new(Mutex::new(HashMap::new())),
            next_id: AtomicU64::new(1),
            runtime_cancel: Arc::new(AtomicBool::new(false)),
            install_pid: Arc::new(AtomicU64::new(0)),
            start_lock: Mutex::new(()),
            settings_cache: Mutex::new(None),
            feiniu,
            app: Mutex::new(None),
        }
    }
    /// 设置 AppHandle（setup 阶段调用；桥接 reader 线程据此转发事件到前端）
    pub fn set_app(&self, app: AppHandle) {
        if let Ok(mut guard) = self.app.lock() {
            *guard = Some(app);
        }
    }
    pub(crate) fn app_handle(&self) -> Option<AppHandle> {
        self.app.lock().ok().and_then(|g| g.clone())
    }
    // ---------- 设置 ----------
    /// 默认保存目录：系统「下载」目录（不可用时退回 {root}/outputs）
    fn default_savedir(&self) -> String {
        dirs::download_dir()
            .unwrap_or_else(|| self.outputs_dir())
            .to_string_lossy()
            .to_string()
    }
    fn default_settings(&self) -> MusicSettings {
        MusicSettings {
            savedir: self.default_savedir(),
            sources: DEFAULT_SOURCES.iter().map(|s| s.to_string()).collect(),
            lyric_download: true,
            cover_download: true,
            use_proxy: false,
            max_concurrent: 4,
            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(),
            feiniu_device_id: String::new(),
            feiniu_access_code: String::new(),
            feiniu_connections: Vec::new(),
            feiniu_active_id: String::new(),
            feiniu_local_dirs: Vec::new(),
            feiniu_cache_enabled: false,
            feiniu_cache_max_gb: 5,
            feiniu_play_mode: "stream".to_string(),
            feiniu_library_nas_path: String::new(),
            feiniu_auto_upload: false,
        }
    }
    fn settings_path(&self) -> PathBuf {
        self.root.join("settings.json")
    }
    /// 读取设置（500ms 内存缓存；文件缺失/损坏时回退默认值）
    pub fn load_settings(&self) -> MusicSettings {
        if let Ok(cache) = self.settings_cache.lock() {
            if let Some(entry) = cache.as_ref() {
                if entry.read_at.elapsed() < Duration::from_millis(500) {
                    return entry.settings.clone();
                }
            }
        }
        let defaults = self.default_settings();
        let settings = fs::read_to_string(self.settings_path())
            .ok()
            .and_then(|s| serde_json::from_str::<MusicSettings>(&s).ok())
            .unwrap_or_else(|| defaults.clone());
        // 自愈：保存目录为空 / 源为空时补默认值
        let mut settings = settings;
        if settings.savedir.trim().is_empty() {
            settings.savedir = defaults.savedir;
        }
        // 迁移：旧默认保存目录（{root}/outputs）→ 系统下载目录
        if settings.savedir == self.outputs_dir().to_string_lossy() {
            settings.savedir = self.default_savedir();
        }
        if settings.sources.is_empty() {
            settings.sources = defaults.sources;
        }
        // 飞牛音乐多连接迁移：旧单连接字段 → 连接列表，并清除旧字段。
        // 变更必须落盘，否则每次读取都会重新迁移，导致删掉的连接"复活"。
        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
    }
    /// 保存设置并更新缓存
    pub fn save_settings(&self, settings: &MusicSettings) -> Result<(), String> {
        let json = serde_json::to_string_pretty(settings).map_err(|e| format!("序列化设置失败: {}", e))?;
        fs::write(self.settings_path(), json).map_err(|e| format!("写入设置失败: {}", e))?;
        if let Ok(mut cache) = self.settings_cache.lock() {
            *cache = Some(SettingsCacheEntry {
                read_at: Instant::now(),
                settings: settings.clone(),
            });
        }
        Ok(())
    }
    // ---------- 目录 ----------
    pub fn runtime_dir(&self) -> PathBuf {
        self.root.join("runtime")
    }
    /// 默认音乐下载目录
    pub fn outputs_dir(&self) -> PathBuf {
        self.root.join("outputs")
    }
    pub fn bridge_script_path(&self) -> PathBuf {
        self.root.join("bridge.py")
    }
    pub fn bundled_python_exe(&self) -> PathBuf {
        self.runtime_dir().join("python").join("python.exe")
    }
    // ---------- Python 探测 ----------
    /// 解析桥接要用的 Python 运行时。
    /// 便携版优先：musicdl 只装入便携运行时，系统 Python 无法保证装有 musicdl；
    /// 无便携版时退回系统 Python（此时 search 会报 musicdl 未安装，引导用户装便携版）。
    pub fn resolve_python(&self) -> Result<PythonEnv, String> {
        if let Some(env) = self.detect_bundled_python() {
            return Ok(env);
        }
        if let Some(env) = detect_system_python() {
            return Ok(env);
        }
        Err("未找到 Python 运行时：系统未安装 Python，且便携版未安装。请点击「安装便携版」".into())
    }
    /// 便携 Python 是否可用（exe 存在且能跑 --version）
    pub fn detect_bundled_python(&self) -> Option<PythonEnv> {
        detect_bundled_python_at(&self.bundled_python_exe())
    }
    // ---------- 环境状态 ----------
    /// 查询环境状态。子进程探测（python/musicdl/ffmpeg，便携 Python 冷启动可达数秒）
    /// 放入阻塞线程池执行，避免阻塞主线程导致 UI 冻结。
    pub async fn env_status(&self) -> Result<MusicEnvStatus, String> {
        let bundled_exe = self.bundled_python_exe();
        let bridge_running = self.bridge.lock().map(|b| b.is_some()).unwrap_or(false);
        let runtime_dir = self.root.to_string_lossy().to_string();
        let probe =
            tauri::async_runtime::spawn_blocking(move || probe_env_blocking(bundled_exe))
                .await
                .map_err(|e| format!("环境探测任务失败: {}", e))?;
        Ok(MusicEnvStatus {
            python: probe.python,
            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,
        })
    }
    // ---------- 退出清理 ----------
    /// 应用退出时停止桥接进程（stdin/stdout 随 child drop 关闭，reader 线程读到 EOF 自行退出）
    pub fn cleanup_on_exit(&self) {
        self.stop_bridge();
    }
    // ---------- 内部工具 ----------
    pub(crate) fn cancel(&self) {
        self.runtime_cancel.store(true, Ordering::SeqCst);
        let pid = self.install_pid.load(Ordering::SeqCst);
        if pid != 0 {
            // 杀掉正在执行的 pip/python 子进程，避免安装流程挂住
            let _ = std::process::Command::new("taskkill")
                .args(["/F", "/T", "/PID", &pid.to_string()])
                .stdout(std::process::Stdio::null())
                .stderr(std::process::Stdio::null())
                .status();
        }
    }
    pub(crate) fn is_cancelled(&self) -> bool {
        self.runtime_cancel.load(Ordering::SeqCst)
    }
    pub(crate) fn start_lock(&self) -> &Mutex<()> {
        &self.start_lock
    }
 }
 /// 环境探测结果（spawn_blocking 跨线程返回）
 struct EnvProbe {
    python: Option<String>,
    python_source: &'static str,
    bundled_python: Option<String>,
    musicdl_installed: bool,
    musicdl_version: Option<String>,
    ffmpeg: Option<String>,
 }
 /// 阻塞式环境探测（串行 spawn 多个子进程，必须在阻塞线程池执行，禁止占用主线程）
 fn probe_env_blocking(bundled_exe: PathBuf) -> EnvProbe {
    let bundled = detect_bundled_python_at(&bundled_exe);
    let sys_py = detect_system_python();
    // 便携版优先（与 resolve_python 一致）：musicdl 只装入便携运行时，
    // 若按系统优先检查，装好便携版后 UI 仍会误报 musicdl 未安装
    let python = bundled.as_ref().or(sys_py.as_ref());
    let (musicdl_installed, musicdl_version) = match python {
        Some(env) => check_musicdl(&env.exe),
        None => (false, None),
    };
    EnvProbe {
        python: python.map(|e| e.version.clone()),
        python_source: match python {
            Some(e) => e.source,
            None => "none",
        },
        bundled_python: bundled.map(|e| e.exe.to_string_lossy().to_string()),
        musicdl_installed,
        musicdl_version,
        ffmpeg: check_ffmpeg(),
    }
 }
 /// 指定路径的便携 Python 是否可用（exe 存在且能跑 --version）
 fn detect_bundled_python_at(exe: &PathBuf) -> Option<PythonEnv> {
    if !exe.exists() {
        return None;
    }
    let version = run_python_version(exe)?;
    Some(PythonEnv {
        source: "bundled",
        exe: exe.clone(),
        version,
    })
 }
 /// 探测系统 Python：依次尝试 python / py / python3，解析 `--version` 输出。
 /// 注意：Windows 的「应用商店别名」python 会在无安装时打印提示并以非零码退出，会被自然过滤。
 fn detect_system_python() -> Option<PythonEnv> {
    for candidate in ["python", "py", "python3"] {
        let mut cmd = std::process::Command::new(candidate);
        cmd.arg("--version");
        crate::process_manager::setup_creation_flags(&mut cmd);
        cmd.stdout(std::process::Stdio::piped())
            .stderr(std::process::Stdio::piped())
            .stdin(std::process::Stdio::null());
        let out = cmd.output().ok()?;
        let text = format!(
            "{}{}",
            String::from_utf8_lossy(&out.stdout),
            String::from_utf8_lossy(&out.stderr)
        );
        if let Some(version) = parse_python_version(&text) {
            return Some(PythonEnv {
                source: "system",
                exe: PathBuf::from(candidate),
                version,
            });
        }
    }
    None
 }
 /// 运行 `python --version` 并解析版本号
 fn run_python_version(exe: &PathBuf) -> Option<String> {
    let mut cmd = std::process::Command::new(exe);
    cmd.arg("--version");
    crate::process_manager::setup_creation_flags(&mut cmd);
    cmd.stdout(std::process::Stdio::piped())
        .stderr(std::process::Stdio::piped())
        .stdin(std::process::Stdio::null());
    let out = cmd.output().ok()?;
    let text = format!(
        "{}{}",
        String::from_utf8_lossy(&out.stdout),
        String::from_utf8_lossy(&out.stderr)
    );
    parse_python_version(&text)
 }
 /// 从 "Python 3.14.5" 文本中提取 "3.14.5"
 fn parse_python_version(text: &str) -> Option<String> {
    text.split_whitespace().find_map(|w| {
        let mut parts = w.split('.');
        let major = parts.next()?.parse::<u32>().ok()?;
        let minor = parts.next()?.parse::<u32>().ok()?;
        if (major, minor) >= (3, 8) {
            Some(w.to_string())
        } else {
            None
        }
    })
 }
 /// 已装版本是否就是本应用锁定的版本。
 ///
 /// `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);
    cmd.args([
        "-c",
        "import musicdl; print(getattr(musicdl, '__version__', 'unknown'))",
    ]);
    crate::process_manager::setup_creation_flags(&mut cmd);
    cmd.stdout(std::process::Stdio::piped())
        .stderr(std::process::Stdio::null())
        .stdin(std::process::Stdio::null());
    match cmd.output() {
        Ok(out) if out.status.success() => {
            let version = String::from_utf8_lossy(&out.stdout).trim().to_string();
            (true, Some(version))
        }
        _ => (false, None),
    }
 }
 /// 检查 FFmpeg 是否可用（部分海外音源需要，非必需）
 fn check_ffmpeg() -> Option<String> {
    let mut cmd = std::process::Command::new("ffmpeg");
    cmd.arg("-version");
    crate::process_manager::setup_creation_flags(&mut cmd);
    cmd.stdout(std::process::Stdio::piped())
        .stderr(std::process::Stdio::null())
        .stdin(std::process::Stdio::null());
    cmd.output()
        .ok()
        .and_then(|o| String::from_utf8(o.stdout).ok())
        .and_then(|s| {
            s.lines()
                .next()
                .map(|l| l.trim().to_string())
                .filter(|l| !l.is_empty())
        })
 }
@@ -0,0 +1,478 @@
 //! 便携 Python 运行时安装：流式下载 → 解压 → _pth 补丁 → get-pip 引导 → musicdl 安装。
 //! 子模块通过 `impl super::MusicManager` 追加方法。
 //!
 //! 依赖下载源（已验证）：
 //! - https://www.python.org/ftp/python/{ver}/python-{ver}-embed-amd64.zip
 //! - https://bootstrap.pypa.io/get-pip.py
 //!
 //! 取消：`MusicManager::cancel()` 置标志 + taskkill 当前 pip/python 子进程。
 use std::fs;
 use std::io::{Read, Write};
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
 use futures_util::StreamExt;
 use tauri::{AppHandle, Emitter};
 use super::{MusicInstallProgress, MusicManager, PIP_INDEX_URL};
 use crate::constants::events::MUSIC_RUNTIME_INSTALL_PROGRESS;
 /// 用户主动取消安装的标记错误信息（前端据此静默处理）
 pub(crate) const RUNTIME_CANCELLED: &str = "安装已取消";
 impl MusicManager {
    /// 安装便携 Python + musicdl（幂等：已就绪的步骤自动跳过），全程推送进度事件。
    pub async fn install_runtime(&self, app: &AppHandle) -> Result<(), String> {
        self.runtime_cancel.store(false, std::sync::atomic::Ordering::SeqCst);
        let result = self.install_runtime_inner(app).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 install_runtime_inner(&self, app: &AppHandle) -> Result<(), String> {
        let runtime_dir = self.runtime_dir();
        fs::create_dir_all(&runtime_dir).map_err(|e| e.to_string())?;
        let python_exe = self.bundled_python_exe();
        // ---------- 1. 便携 Python 已就绪则跳过下载/解压 ----------
        if !(python_exe.exists() && super::run_python_version(&python_exe).is_some()) {
            self.emit_progress(app, "download", 2, 0, None, "开始下载便携 Python...").await;
            // 下载 embeddable zip（~11MB，流式写入）
            let zip_path = runtime_dir.join(format!("python-{}-embed.zip", super::BUNDLED_PY_VERSION));
            let zip_url = format!(
                "https://www.python.org/ftp/python/{}/python-{}-embed-amd64.zip",
                super::BUNDLED_PY_VERSION,
                super::BUNDLED_PY_VERSION
            );
            self.download_stream(app, &zip_url, &zip_path).await?;
            // 解压到 runtime/python/
            self.emit_progress(app, "extract", 42, 0, None, "正在解压便携 Python...").await;
            let python_dir = runtime_dir.join("python");
            if python_dir.exists() {
                fs::remove_dir_all(&python_dir).ok();
            }
            fs::create_dir_all(&python_dir).map_err(|e| e.to_string())?;
            self.extract_zip(&zip_path, &python_dir)?;
            fs::remove_file(&zip_path).ok();
            // _pth 补丁：启用 site（否则无法识别 site-packages 与 pip）
            self.emit_progress(app, "patch", 52, 0, None, "正在配置 Python 环境...").await;
            self.patch_pth(&python_dir)?;
            // 下载 get-pip.py 并引导 pip（只装 pip 本体，走官方源，包很小）
            self.emit_progress(app, "pip", 54, 0, None, "正在引导 pip...").await;
            let get_pip = runtime_dir.join("get-pip.py");
            self.download_bytes(&"https://bootstrap.pypa.io/get-pip.py".to_string(), &get_pip)
                .await?;
            let pip_py = python_exe.clone();
            let pip_py2 = pip_py.clone(); // 供 setuptools 步骤闭包使用（先于 move 克隆）
            let get_pip2 = get_pip.clone();
            self.run_blocking_step(
                app,
                "pip",
                55,
                60,
                move |pid| {
                    let mut cmd = std::process::Command::new(&pip_py);
                    cmd.arg(&get_pip2).args(["--no-warn-script-location"]);
                    run_cmd_blocking(cmd, pid)
                },
                "正在安装 pip...",
            )
            .await?;
            fs::remove_file(&get_pip).ok();
            // 安装 setuptools（musicdl 的 setup.py 构建依赖 setuptools.build_meta，
            // 必须先于 musicdl 就位，否则构建阶段报 BackendUnavailable）
            self.run_blocking_step(
                app,
                "pip",
                62,
                66,
                move |pid| {
                    let mut cmd = std::process::Command::new(&pip_py2);
                    cmd.args([
                        "-m", "pip", "install", "--no-warn-script-location",
                        "--timeout", "60",
                        "--index-url", PIP_INDEX_URL,
                        "setuptools",
                    ]);
                    run_cmd_blocking(cmd, pid)
                },
                "正在安装 setuptools...",
            )
            .await?;
        } else {
            self.emit_progress(app, "check", 2, 0, None, "便携 Python 已就绪").await;
        }
        // ---------- 2. 安装 musicdl（幂等：已安装则跳过） ----------
        if !self.musicdl_ready(&python_exe).await {
            let pip_py = python_exe.clone();
            self.run_blocking_step(
                app,
                "musicdl",
                68,
                95,
                move |pid| {
                    let mut cmd = std::process::Command::new(&pip_py);
                    cmd.args([
                        "-m", "pip", "install", "--no-warn-script-location",
                        "--timeout", "60",
                        "--index-url", PIP_INDEX_URL,
                        &format!("musicdl=={}", super::MUSICDL_VERSION),
                    ]);
                    run_cmd_blocking(cmd, pid)
                },
                "正在安装 musicdl（下载依赖较多，可能需几分钟）...",
            )
            .await?;
        }
        self.emit_progress(app, "done", 100, 0, None, "环境就绪").await;
        crate::logger::log_info("music", "便携 Python + musicdl 安装完成");
        Ok(())
    }
    /// 检查便携 Python 能否导入 musicdl
    async fn musicdl_ready(&self, python_exe: &PathBuf) -> bool {
        let exe = python_exe.clone();
        let (ok, _) = super::check_musicdl(&exe);
        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,
        app: &AppHandle,
        stage: &str,
        percent: u32,
        downloaded_bytes: u64,
        total_bytes: Option<u64>,
        message: &str,
    ) {
        let _ = app.emit(
            MUSIC_RUNTIME_INSTALL_PROGRESS,
            MusicInstallProgress {
                stage: stage.into(),
                percent,
                downloaded_bytes,
                total_bytes,
                message: message.into(),
            },
        );
    }
    /// 流式下载（带取消 + 进度事件，percent 0-40 区间），复用内核下载模式
    async fn download_stream(
        &self,
        app: &AppHandle,
        url: &str,
        dest: &Path,
    ) -> Result<(), String> {
        let resp = self
            .client
            .get(url)
            .timeout(std::time::Duration::from_secs(300))
            .send()
            .await
            .map_err(|e| format!("请求下载失败: {}", e))?;
        let status = resp.status();
        if !status.is_success() {
            return Err(format!("下载返回 HTTP {}", status.as_u16()));
        }
        let total: Option<u64> = resp.content_length();
        let mut file = fs::File::create(dest).map_err(|e| format!("创建文件失败: {}", e))?;
        let mut stream = resp.bytes_stream();
        let mut downloaded: u64 = 0;
        let mut last_percent: u32 = 0;
        while let Some(chunk) = stream.next().await {
            if self.is_cancelled() {
                drop(file);
                fs::remove_file(dest).ok();
                return Err(RUNTIME_CANCELLED.to_string());
            }
            let chunk = chunk.map_err(|e| format!("下载中断: {}", e))?;
            file.write_all(&chunk).map_err(|e| format!("写入文件失败: {}", e))?;
            downloaded += chunk.len() as u64;
            let percent = total
                .filter(|t| *t > 0)
                .map(|t| ((downloaded as f64 / t as f64) * 38.0) as u32)
                .unwrap_or(0)
                .min(38);
            if percent >= last_percent + 1 {
                last_percent = percent;
                self.emit_progress(
                    app,
                    "download",
                    percent,
                    downloaded,
                    total,
                    &format!("正在下载便携 Python ({:.1} MB)", downloaded as f64 / 1048576.0),
                )
                .await;
            }
        }
        file.flush().ok();
        self.emit_progress(app, "download", 40, downloaded, total, "下载完成").await;
        Ok(())
    }
    /// 小文件整体下载（get-pip.py），无进度
    async fn download_bytes(&self, url: &str, dest: &Path) -> Result<(), String> {
        let resp = self
            .client
            .get(url)
            .timeout(std::time::Duration::from_secs(120))
            .send()
            .await
            .map_err(|e| format!("请求下载失败: {}", e))?;
        let status = resp.status();
        if !status.is_success() {
            return Err(format!("下载返回 HTTP {}", status.as_u16()));
        }
        let bytes = resp.bytes().await.map_err(|e| format!("读取响应失败: {}", e))?;
        fs::write(dest, &bytes).map_err(|e| format!("写入文件失败: {}", e))?;
        Ok(())
    }
    /// 解压 zip（复用内核解压逻辑）
    fn extract_zip(&self, zip_path: &Path, dest: &Path) -> Result<(), String> {
        let file = fs::File::open(zip_path).map_err(|e| format!("打开 zip 失败: {}", e))?;
        let mut archive = zip::ZipArchive::new(file).map_err(|e| format!("读取 zip 失败: {}", e))?;
        for i in 0..archive.len() {
            let mut entry = archive
                .by_index(i)
                .map_err(|e| format!("读取条目失败: {}", e))?;
            let outpath = match entry.enclosed_name() {
                Some(p) => dest.join(p),
                None => continue,
            };
            if entry.is_dir() {
                fs::create_dir_all(&outpath).map_err(|e| e.to_string())?;
            } else {
                if let Some(parent) = outpath.parent() {
                    fs::create_dir_all(parent).map_err(|e| e.to_string())?;
                }
                let mut outfile = fs::File::create(&outpath).map_err(|e| e.to_string())?;
                let mut buf = [0u8; 8192];
                loop {
                    let n = entry.read(&mut buf).map_err(|e| e.to_string())?;
                    if n == 0 {
                        break;
                    }
                    outfile.write_all(&buf[..n]).map_err(|e| e.to_string())?;
                }
            }
        }
        Ok(())
    }
    /// 修改 pythonXY._pth：启用 `import site`（embeddable 默认注释掉，
    /// 不启用则无法识别 site-packages / pip 安装的包）
    fn patch_pth(&self, python_dir: &Path) -> Result<(), String> {
        let entries = fs::read_dir(python_dir).map_err(|e| e.to_string())?;
        let pth = entries
            .filter_map(|e| e.ok())
            .map(|e| e.path())
            .find(|p| {
                p.extension()
                    .and_then(|e| e.to_str())
                    .map(|e| e.eq_ignore_ascii_case("_pth"))
                    .unwrap_or(false)
            })
            .ok_or_else(|| "解压目录中未找到 ._pth 文件".to_string())?;
        let content = fs::read_to_string(&pth).map_err(|e| e.to_string())?;
        let mut patched = content.replace("#import site", "import site");
        if !patched.contains("import site") {
            patched.push_str("import site\n");
        }
        // 显式把 site-packages 加入 sys.path（pip 默认安装位置）
        if !patched.contains("Lib\\site-packages") && !patched.contains("Lib/site-packages") {
            patched.push_str("Lib\\site-packages\n");
        }
        fs::write(&pth, patched).map_err(|e| format!("写入 _pth 失败: {}", e))?;
        crate::logger::log_info("music", &format!("已补丁 _pth: {}", pth.display()));
        Ok(())
    }
    /// 执行一个阻塞子进程步骤（get-pip / setuptools / musicdl），带进度推送、取消检查与超时看门狗。
    /// start_percent / end_percent：本步骤的进度区间（完成前推进到 end_percent）。
    /// run 闭包接收「子进程 pid 记录器」，供取消时 taskkill。
    async fn run_blocking_step<F>(
        &self,
        app: &AppHandle,
        stage: &str,
        start_percent: u32,
        end_percent: u32,
        run: F,
        msg: &str,
    ) -> Result<(), String>
    where
        F: FnOnce(Arc<std::sync::atomic::AtomicU64>) -> Result<(), String> + Send + 'static,
    {
        if self.is_cancelled() {
            return Err(RUNTIME_CANCELLED.to_string());
        }
        let pid_ref = self.install_pid.clone();
        self.emit_progress(app, stage, start_percent, 0, None, msg).await;
        let result = tauri::async_runtime::spawn_blocking(move || run(pid_ref.clone()))
            .await
            .map_err(|e| format!("任务执行失败: {}", e))?;
        self.install_pid.store(0, std::sync::atomic::Ordering::SeqCst);
        if self.is_cancelled() {
            return Err(RUNTIME_CANCELLED.to_string());
        }
        result?;
        self.emit_progress(app, stage, end_percent, 0, None, "完成").await;
        Ok(())
    }
 }
 /// 同步运行子进程，带超时看门狗（超时 taskkill），并记录 pid 供取消。
 /// 输出（stdout+stderr 尾部）写入日志；失败返回错误信息。
 fn run_cmd_blocking(
    mut cmd: std::process::Command,
    pid_ref: Arc<std::sync::atomic::AtomicU64>,
 ) -> Result<(), String> {
    cmd.stdout(std::process::Stdio::piped())
        .stderr(std::process::Stdio::piped())
        .stdin(std::process::Stdio::null());
    crate::process_manager::setup_creation_flags(&mut cmd);
    let child = cmd.spawn().map_err(|e| format!("启动子进程失败: {}", e))?;
    pid_ref.store(child.id() as u64, std::sync::atomic::Ordering::SeqCst);
    // 超时看门狗：30 分钟后仍未结束则强杀（慢网络下 pip 装 musicdl 依赖可能超过 10 分钟）
    let pid = child.id();
    let (tx, rx) = std::sync::mpsc::channel::<()>();
    let watcher = std::thread::spawn(move || {
        if rx.recv_timeout(std::time::Duration::from_secs(1800)).is_err() {
            let _ = std::process::Command::new("taskkill")
                .args(["/F", "/T", "/PID", &pid.to_string()])
                .stdout(std::process::Stdio::null())
                .stderr(std::process::Stdio::null())
                .status();
        }
    });
    let output = child.wait_with_output();
    let _ = tx.send(());
    let _ = watcher.join();
    match output {
        Ok(out) => {
            let text = format!(
                "{}{}",
                String::from_utf8_lossy(&out.stdout),
                String::from_utf8_lossy(&out.stderr)
            );
            if out.status.success() {
                Ok(())
            } else {
                // 截取尾部 800 字符，便于定位 pip 报错
                let tail: String = text.chars().rev().take(800).collect::<String>().chars().rev().collect();
                Err(format!("子进程退出码 {}: {}", out.status.code().unwrap_or(-1), tail))
            }
        }
        Err(e) => Err(format!("读取子进程输出失败: {}", e)),
    }
 }
@@ -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()
 }
@@ -127,8 +127,9 @@ pub fn setup_creation_flags(_cmd: &mut Command) {
 /// 将已启动的子进程加入 Job Object（异常退出时自动清理）
 /// 在 Windows 上调用，非 Windows 平台为空操作
 /// pub(crate)：音乐模块的桥接进程（自管 stdio，不走 ProcessManager）也需加入 Job
 #[cfg(windows)]
-fn assign_to_job(child: &Child) {
+pub(crate) fn assign_to_job(child: &Child) {
    use std::os::windows::io::AsRawHandle;
    if let Some(job) = get_job_handle() {
        let child_handle = child.as_raw_handle() as winapi::HANDLE;
@@ -18,9 +18,9 @@
 use std::sync::Mutex;
 use windows_sys::Win32::Foundation::{BOOL, HWND, POINT, RECT};
 use windows_sys::Win32::Graphics::Gdi::{
-    BitBlt, CreateCompatibleBitmap, CreateCompatibleDC, DeleteDC, DeleteObject, GetDC, GetDIBits,
+    BitBlt, CombineRgn, CreateCompatibleBitmap, CreateCompatibleDC, CreateRectRgn, DeleteDC,
-    PatBlt, ReleaseDC, SelectObject, BITMAPINFO, BITMAPINFOHEADER, BLACKNESS, DIB_RGB_COLORS,
+    DeleteObject, GetDC, GetDIBits, PatBlt, ReleaseDC, SelectObject, SetWindowRgn, BITMAPINFO,
-    RGBQUAD, SRCCOPY,
+    BITMAPINFOHEADER, BLACKNESS, DIB_RGB_COLORS, RGBQUAD, RGN_DIFF, SRCCOPY,
 };
 use windows_sys::Win32::Storage::Xps::PrintWindow;
 use windows_sys::Win32::System::DataExchange::{
@@ -34,7 +34,7 @@ use windows_sys::Win32::UI::WindowsAndMessaging::{
    WS_EX_TOOLWINDOW,
 };
-use super::{CaptureData, ScreenRect, WindowInfo};
+use super::{CaptureData, ScreenRect, ScrollRegion, WindowInfo};
 /// 捕获结果（PNG 字节 + 原始 BGRA 像素，像素用于剪贴板 DIB 构造，避免重复解码）
 pub struct CapturedImage {
@@ -406,6 +406,71 @@ pub fn disable_window_transitions(hwnd: isize) -> Result<(), String> {
    }
 }
 /// 滚动截图模式：在覆盖层窗口上挖出选区带的"真孔"（内缩 INSET 保留蓝框），或清除恢复整窗。
 ///
 /// 背景：Chromium 系浏览器（Edge/Chrome）的原生窗口遮挡检测（occlusion tracking）
 /// 会把被**完全覆盖**的窗口标记为 occluded 并暂停渲染合成——滚动截图时覆盖层
 /// 铺满全屏盖住目标窗口，网页"看起来完全不滚动"，PrintWindow 抓到的也是静止帧。
 /// 覆盖层并非 layered 窗口，即使其内容视觉透明，窗口矩形对遮挡检测仍算不透明覆盖。
 /// 挖孔后目标窗口仅部分被覆盖（Chromium 要求完全覆盖才判 occluded，实测 60x60
 /// 的小孔即可解除），恢复渲染与滚轮响应，拼接匹配随之正常。
 ///
 /// - `region = Some`：孔 = 选区带内缩 INSET（保留 2px 蓝框 + 1px 白描边）；
 ///   选区过小（< 2*INSET+8）时不挖孔，避免退化区域
 /// - `region = None`：SetWindowRgn(NULL) 清除窗口区域（恢复整窗）
 ///
 /// 坐标：region 为屏幕物理像素（与滚动会话同源），按覆盖层窗口原点换算成窗口坐标。
 /// 区域设置在窗口上持续有效，会话结束/新一轮截图开始时必须传 None 复位。
 pub fn set_scroll_hole(hwnd: isize, region: Option<ScrollRegion>) -> Result<(), String> {
    unsafe {
        match region {
            Some(r) => {
                let mut wr: RECT = std::mem::zeroed();
                if GetWindowRect(hwnd, &mut wr) == 0 {
                    return Err("GetWindowRect 失败".into());
                }
                const INSET: i32 = 4;
                let hx1 = r.x - wr.left + INSET;
                let hy1 = r.y - wr.top + INSET;
                let hx2 = r.x + r.width - wr.left - INSET;
                let hy2 = r.y + r.height - wr.top - INSET;
                if hx2 - hx1 < 8 || hy2 - hy1 < 8 {
                    // 选区太小：不挖孔（保持整窗）
                    if SetWindowRgn(hwnd, 0, 1) == 0 {
                        return Err("SetWindowRgn 失败".into());
                    }
                    return Ok(());
                }
                let full = CreateRectRgn(0, 0, wr.right - wr.left, wr.bottom - wr.top);
                let hole = CreateRectRgn(hx1, hy1, hx2, hy2);
                if full == 0 || hole == 0 {
                    if full != 0 {
                        DeleteObject(full);
                    }
                    if hole != 0 {
                        DeleteObject(hole);
                    }
                    return Err("CreateRectRgn 失败".into());
                }
                CombineRgn(full, full, hole, RGN_DIFF);
                // 组合结果 full 归 SetWindowRgn 所有；hole 用完即删
                DeleteObject(hole);
                if SetWindowRgn(hwnd, full, 1) == 0 {
                    DeleteObject(full);
                    return Err("SetWindowRgn 失败".into());
                }
                Ok(())
            }
            None => {
                if SetWindowRgn(hwnd, 0, 1) == 0 {
                    return Err("SetWindowRgn 失败".into());
                }
                Ok(())
            }
        }
    }
 }
 /// 枚举所有可见、有标题的顶层窗口（供窗口列表选择）
 pub fn enum_visible_windows() -> Vec<WindowInfo> {
    extern "system" fn enum_proc(hwnd: HWND, lparam: isize) -> i32 {
@@ -10,6 +10,9 @@
 //! - screenshot_show_overlay：一次 IPC 完成覆盖层 show + focus（关键路径减少往返）
 //! - screenshot_enum_windows：枚举可见顶层窗口
 //! - screenshot_capture_window：按 hwnd 捕获指定窗口
 //! - screenshot_scroll_capture / screenshot_scroll_start / screenshot_scroll_finish /
 //!   screenshot_scroll_cancel：滚动截图（同步一次调用 / 会话式：启动、完成、取消）
 //! - screenshot_set_scroll_hole：滚动模式遮罩挖孔（防 Chromium 遮挡检测冻结目标窗口）
 //! - screenshot_take_editor_image_raw：取出编辑器图片（raw IPC，滚动截图会话直接写入）
 //! - screenshot_compose_png / screenshot_compose_copy：raw RGBA → PNG（仅编码 / 剪贴板+编码）
 //! - screenshot_copy_image：写入剪贴板（CF_DIB）
@@ -372,6 +375,54 @@ pub fn screenshot_scroll_cancel() -> Result<(), String> {
    }
 }
 /// 滚动模式遮罩挖孔：在截图覆盖层窗口上挖出选区带的真孔（region = None 时复位整窗）。
 ///
 /// Chromium 系浏览器（Edge/Chrome）的窗口遮挡检测会把被完全覆盖的窗口标记为
 /// occluded 并暂停渲染——滚动截图时覆盖层铺满全屏，网页"看起来完全不滚动"。
 /// 挖孔后目标窗口仅部分被覆盖，恢复渲染与滚轮响应（详见 capture::set_scroll_hole）。
 /// 进入滚动模式时带选区调用，会话结束/新一轮截图开始时必须传 None 复位。
 #[tauri::command]
 #[specta::specta]
 pub fn screenshot_set_scroll_hole(
    app: AppHandle,
    region: Option<super::ScrollRegion>,
 ) -> Result<(), String> {
    #[cfg(windows)]
    {
        use raw_window_handle::HasWindowHandle;
        let mut hwnds: Vec<isize> = Vec::new();
        for (label, win) in app.webview_windows() {
            if label.starts_with(crate::constants::windows::SCREENSHOT_OVERLAY) {
                let hwnd = win
                    .window_handle()
                    .ok()
                    .and_then(|h| match h.as_raw() {
                        raw_window_handle::RawWindowHandle::Win32(w) => {
                            Some(w.hwnd.get() as isize)
                        }
                        _ => None,
                    });
                if let Some(h) = hwnd {
                    hwnds.push(h);
                }
            }
        }
        if hwnds.is_empty() {
            return Err("截图覆盖层窗口不存在".into());
        }
        for h in hwnds {
            super::capture::set_scroll_hole(h, region)?;
        }
        Ok(())
    }
    #[cfg(not(windows))]
    {
        let _ = (app, region);
        Ok(())
    }
 }
 /// 取出编辑器图片（原始 PNG 字节，raw IPC → 前端 ArrayBuffer → Blob URL，取出即清除）
 ///
 /// 长图（滚动截图）可达数十 MB：raw IPC 相比 base64 JSON 事件传输省 ~33% 体积，
@@ -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（设置与密钥按需读取，启动时不发网络请求）
 //! - 托盘：自定义菜单窗口
 //! - 进程：监控线程
@@ -17,8 +18,10 @@ use crate::download_engine::{DownloadEngine, ExtensionServer};
 use crate::logger::LogManager;
 use crate::mihomo_manager::MihomoManager;
 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 闭包调用）。
 /// 初始化顺序即依赖顺序：日志 → 数据目录 → 各管理器 → 托盘 → 进程监控 → 自动启动。
@@ -53,6 +56,22 @@ pub fn init(app: &mut App<Wry>) -> Result<(), Box<dyn std::error::Error>> {
    let monitor = MonitorKernel::new(app_data_dir.clone());
    app.manage(monitor);
    // ===== 音乐模块：MusicManager（Python 运行时 + 桥接进程） =====
    // 仅注册状态，不主动启动桥接（由前端模块激活/首次请求时按需拉起）
    let music = MusicManager::new(app_data_dir.clone());
    // 注入 AppHandle：桥接 reader 线程把下载事件行转发给前端
    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.8.5",
+  "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": {
@@ -5,8 +5,10 @@ import { getCurrentWindow } from '@tauri-apps/api/window'
 import TitleBar from '@/components/layout/TitleBar.vue'
 import Sidebar from '@/components/layout/Sidebar.vue'
 import ModuleContainer from '@/components/layout/ModuleContainer.vue'
 import NowPlayingDialog from '@/components/layout/NowPlayingDialog.vue'
 import { Toaster } from '@/components/ui/sonner'
 import { useAppStore } from '@/stores/appStore'
 import { useFeiniuStore } from '@/stores/feiniuStore'
 import { useScreenshotStore } from '@/stores/screenshotStore'
 import { useQuickPanelStore } from '@/stores/quickpanelStore'
 import { useMonitorStore } from '@/stores/monitorStore'
@@ -19,6 +21,7 @@ import { EVENTS, STORAGE_KEYS, WINDOWS } from '@/lib/constants'
 import { commands } from '@/lib/bindings'
 const appStore = useAppStore()
 const feiniuStore = useFeiniuStore()
 const screenshotStore = useScreenshotStore()
 const quickpanelStore = useQuickPanelStore()
 const monitorStore = useMonitorStore()
@@ -197,6 +200,9 @@ const resolveDefaultModule = (): string => {
 onMounted(async () => {
  await appStore.init().catch(e => console.error('App init error:', e))
  // 全局播放器：恢复队列/音量/播放模式等本地状态（幂等，音乐模块内会再次调用但不会重复执行）
  feiniuStore.init().catch(e => console.error('播放器初始化失败:', e))
  // 初始化监控 store：订阅后端 monitor-data / monitor-network 等事件，
  // 使 OSD 窗口在应用启动后即可接收数据流，不依赖用户手动打开监控模块。
  // init() 幂等：MonitorModule 挂载时再次调用不会重复订阅。
@@ -283,7 +289,7 @@ onUnmounted(() => {
  <TooltipProvider>
    <div class="flex flex-col h-screen w-screen overflow-hidden">
      <TitleBar :modules="availableModules" @search="handleSearch" />
-      <div class="flex-1 flex overflow-hidden">
+      <div class="flex-1 flex overflow-hidden min-h-0">
        <Sidebar
          :modules="availableModules"
          :active-module="activeModule"
@@ -292,6 +298,7 @@ onUnmounted(() => {
        <ModuleContainer :active-component="activeComponent" :active-module="activeModule" :loading="moduleLoading" />
      </div>
    </div>
    <NowPlayingDialog />
    <Toaster position="bottom-right" rich-colors close-button :style="{ zIndex: 99999 }" />
  </TooltipProvider>
 </template>
@@ -0,0 +1,293 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 /**
 * 通用拖拽进度条。
 *
 * 关键行为：拖动过程中**不**向外提交，只更新本地预览值；
 * 指针抬起（或键盘操作）时才 emit `seek`。
 * 这样流式音频不会因为拖动而反复中断并重建 Range 请求。
 */
 const props = withDefaults(
  defineProps<{
    /** 当前进度 0~1 */
    value: number
    /** 已缓冲比例 0~1 */
    buffered?: number
    /** 总秒数：>0 时显示两侧时间与拖动气泡 */
    durationSec?: number
    /** 紧凑模式（音量条）：细轨道、无时间、无气泡 */
    compact?: boolean
    disabled?: boolean
    /** 无障碍标签 */
    label?: string
  }>(),
  { buffered: 0, durationSec: 0, compact: false, disabled: false, label: '进度' }
 )
 const emit = defineEmits<{ seek: [ratio: number] }>()
 const rootRef = ref<HTMLElement | null>(null)
 const dragging = ref(false)
 const dragRatio = ref(0)
 const hoverRatio = ref<number | null>(null)
 function clamp(v: number) {
  return Math.min(1, Math.max(0, Number.isFinite(v) ? v : 0))
 }
 function pct(v: number) {
  return `${clamp(v) * 100}%`
 }
 const activeRatio = computed(() => (dragging.value ? dragRatio.value : clamp(props.value)))
 const bubbleRatio = computed(() => (dragging.value ? dragRatio.value : hoverRatio.value))
 const showTime = computed(() => !props.compact && props.durationSec > 0)
 function ratioFromClientX(clientX: number) {
  const el = rootRef.value
  if (!el) return 0
  const r = el.getBoundingClientRect()
  if (r.width <= 0) return 0
  return clamp((clientX - r.left) / r.width)
 }
 function fmt(sec: number) {
  if (!Number.isFinite(sec) || sec < 0) return '--:--'
  const s = Math.floor(sec)
  const h = Math.floor(s / 3600)
  const m = Math.floor((s % 3600) / 60)
  const r = s % 60
  if (h > 0) return `${h}:${String(m).padStart(2, '0')}:${String(r).padStart(2, '0')}`
  return `${String(m).padStart(2, '0')}:${String(r).padStart(2, '0')}`
 }
 function onDown(e: PointerEvent) {
  if (props.disabled) return
  const el = e.currentTarget as HTMLElement
  dragging.value = true
  dragRatio.value = ratioFromClientX(e.clientX)
  try {
    el.focus({ preventScroll: true })
    el.setPointerCapture(e.pointerId)
  } catch {
    /* 部分环境不支持指针捕获/聚焦，降级为普通拖动 */
  }
  e.preventDefault()
 }
 function onMove(e: PointerEvent) {
  const r = ratioFromClientX(e.clientX)
  hoverRatio.value = r
  if (dragging.value) dragRatio.value = r
 }
 function onUp(e: PointerEvent) {
  if (!dragging.value) return
  dragging.value = false
  dragRatio.value = ratioFromClientX(e.clientX)
  emit('seek', dragRatio.value)
 }
 function onLeave() {
  if (!dragging.value) hoverRatio.value = null
 }
 function onKey(e: KeyboardEvent) {
  if (props.disabled) return
  const step = e.shiftKey ? 0.1 : 0.02
  let next: number | null = null
  if (e.key === 'ArrowRight' || e.key === 'ArrowUp') next = clamp(props.value + step)
  else if (e.key === 'ArrowLeft' || e.key === 'ArrowDown') next = clamp(props.value - step)
  else if (e.key === 'Home') next = 0
  else if (e.key === 'End') next = 1
  if (next !== null) {
    emit('seek', next)
    e.preventDefault()
  }
 }
 </script>
 <template>
  <div
    class="scrub"
    :class="{ 'is-compact': compact, 'is-dragging': dragging, 'is-disabled': disabled }"
  >
    <span v-if="showTime" class="scrub-time">{{ fmt(activeRatio * durationSec) }}</span>
    <div
      ref="rootRef"
      class="scrub-track"
      role="slider"
      :tabindex="disabled ? -1 : 0"
      :aria-label="label"
      :aria-valuenow="Math.round(activeRatio * 100)"
      aria-valuemin="0"
      aria-valuemax="100"
      :aria-disabled="disabled"
      @pointerdown="onDown"
      @pointermove="onMove"
      @pointerup="onUp"
      @pointercancel="onUp"
      @pointerleave="onLeave"
      @keydown="onKey"
    >
      <span class="scrub-buffered" :style="{ width: pct(buffered) }" />
      <span class="scrub-played" :style="{ width: pct(activeRatio) }" />
      <span class="scrub-thumb" :style="{ left: pct(activeRatio) }" />
      <span
        v-if="showTime && bubbleRatio !== null"
        class="scrub-bubble"
        :style="{ left: pct(bubbleRatio) }"
      >
        {{ fmt(bubbleRatio * durationSec) }}
      </span>
    </div>
    <span v-if="showTime" class="scrub-time">{{ fmt(durationSec) }}</span>
  </div>
 </template>
 <style scoped>
 .scrub {
  display: flex;
  align-items: center;
  gap: 10px;
  width: 100%;
  min-width: 0;
 }
 .scrub-time {
  font-size: 11px;
  color: var(--muted-foreground);
  font-variant-numeric: tabular-nums;
  flex: 0 0 auto;
  min-width: 38px;
  text-align: center;
  user-select: none;
 }
 .scrub-time:first-child {
  text-align: right;
 }
 .scrub-track {
  position: relative;
  flex: 1 1 auto;
  min-width: 0;
  height: 16px;
  display: flex;
  align-items: center;
  cursor: pointer;
  touch-action: none;
  outline: none;
 }
 /* 视觉轨道（高 4px，hover / 拖动时增到 7px） */
 .scrub-track::before {
  content: '';
  position: absolute;
  left: 0;
  right: 0;
  height: 4px;
  border-radius: 999px;
  background: var(--muted);
  transition: height 0.15s ease;
 }
 .scrub:hover .scrub-track::before,
 .scrub.is-dragging .scrub-track::before {
  height: 7px;
 }
 .scrub-track:focus-visible::before {
  box-shadow: 0 0 0 3px color-mix(in oklab, var(--ring) 45%, transparent);
 }
 .scrub-buffered,
 .scrub-played {
  position: absolute;
  left: 0;
  height: 4px;
  border-radius: 999px;
  transition: height 0.15s ease;
 }
 .scrub:hover .scrub-buffered,
 .scrub.is-dragging .scrub-buffered,
 .scrub:hover .scrub-played,
 .scrub.is-dragging .scrub-played {
  height: 7px;
 }
 .scrub-buffered {
  background: color-mix(in oklab, var(--muted-foreground) 28%, transparent);
 }
 .scrub-played {
  background: var(--primary);
 }
 .scrub-thumb {
  position: absolute;
  top: 50%;
  width: 12px;
  height: 12px;
  margin: -6px 0 0 -6px;
  border-radius: 50%;
  background: var(--primary);
  box-shadow: 0 0 0 2px var(--background);
  opacity: 0;
  transition: opacity 0.15s ease, transform 0.15s ease;
  pointer-events: none;
 }
 .scrub:hover .scrub-thumb,
 .scrub.is-dragging .scrub-thumb,
 .scrub-track:focus-visible .scrub-thumb {
  opacity: 1;
 }
 .scrub.is-dragging .scrub-thumb {
  transform: scale(1.15);
 }
 .scrub-bubble {
  position: absolute;
  bottom: 18px;
  transform: translateX(-50%);
  padding: 2px 6px;
  border-radius: 5px;
  background: var(--popover);
  color: var(--popover-foreground);
  border: 1px solid var(--border);
  font-size: 11px;
  font-variant-numeric: tabular-nums;
  pointer-events: none;
  white-space: nowrap;
 }
 .scrub.is-compact .scrub-time {
  display: none;
 }
 .scrub.is-compact .scrub-track {
  height: 14px;
 }
 .scrub.is-compact .scrub-track::before,
 .scrub.is-compact .scrub-buffered,
 .scrub.is-compact .scrub-played {
  height: 4px;
 }
 .scrub.is-compact:hover .scrub-track::before,
 .scrub.is-compact:hover .scrub-buffered,
 .scrub.is-compact:hover .scrub-played,
 .scrub.is-compact.is-dragging .scrub-track::before,
 .scrub.is-compact.is-dragging .scrub-buffered,
 .scrub.is-compact.is-dragging .scrub-played {
  height: 6px;
 }
 .scrub.is-disabled {
  opacity: 0.5;
  pointer-events: none;
 }
@media (prefers-reduced-motion: reduce) {
  .scrub-track::before,
  .scrub-buffered,
  .scrub-played,
  .scrub-thumb {
    transition: none;
  }
 }
 </style>
@@ -0,0 +1,55 @@
 <script setup lang="ts">
 import type { Component } from 'vue'
 export interface SegmentedItem {
  value: string
  label: string
  /** lucide 图标组件 */
  icon?: Component
  /** 右侧计数徽标 */
  count?: number
 }
 /** 模块内统一的分段导航（替代此前并存的三套切换控件） */
 defineProps<{
  modelValue: string
  items: SegmentedItem[]
  /** 铺满容器宽度（等分） */
  block?: boolean
 }>()
 const emit = defineEmits<{ 'update:modelValue': [value: string] }>()
 </script>
 <template>
  <div
    class="inline-flex items-center rounded-lg bg-muted p-0.5"
    :class="block ? 'flex w-full' : 'w-fit'"
    role="tablist"
  >
    <button
      v-for="item in items"
      :key="item.value"
      type="button"
      role="tab"
      :aria-selected="modelValue === item.value"
      class="flex min-w-0 flex-1 items-center justify-center gap-1.5 rounded-[7px] px-3 py-1.5 text-[13px] transition-colors duration-150 outline-none focus-visible:ring-2 focus-visible:ring-ring/50"
      :class="
        modelValue === item.value
          ? 'bg-background font-medium text-foreground shadow-sm'
          : 'text-muted-foreground hover:text-foreground'
      "
      @click="emit('update:modelValue', item.value)"
    >
      <component :is="item.icon" v-if="item.icon" class="size-3.5 shrink-0" />
      <span class="truncate">{{ item.label }}</span>
      <span
        v-if="item.count"
        class="shrink-0 rounded-full bg-muted px-1.5 text-[10px] tabular-nums text-muted-foreground"
        :class="modelValue === item.value ? 'bg-muted' : 'bg-background/70'"
      >
        {{ item.count }}
      </span>
    </button>
  </div>
 </template>
@@ -0,0 +1,320 @@
 <script setup lang="ts">
 import { computed, ref, watch } from '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'
 import { Dialog, DialogContent, DialogClose, DialogTitle } from '@/components/ui/dialog'
 import { ScrollArea } from '@/components/ui/scroll-area'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
 const store = useFeiniuStore()
 const coverUrl = computed(() => {
  const t = store.nowPlaying
  if (!t) return ''
  if (t.coverUrl) return t.coverUrl
  if (t.source === 'feiniu' && t.coverId && store.mediaPrefix) {
    return `${store.mediaPrefix}/cover?coverId=${encodeURIComponent(t.coverId)}&size=400`
  }
  return ''
 })
 const coverFailed = ref(false)
 watch(coverUrl, () => (coverFailed.value = false))
 const isPreview = computed(() => store.nowPlaying?.source === 'preview')
 const hasTrack = computed(() => !!store.nowPlaying)
 const modeIcon = computed(() => {
  if (store.playMode === 'loopOne') return Repeat1
  if (store.playMode === 'shuffle') return Shuffle
  return Repeat
 })
 const modeLabel = computed(() =>
  store.playMode === 'loopAll' ? '列表循环' : store.playMode === 'loopOne' ? '单曲循环' : '随机播放'
 )
 const tabs = computed(() => [
  { value: 'lyric', label: '歌词' },
  { value: 'queue', label: `队列` }
 ])
 const activeTab = computed({
  get: () => store.nowPlayingTab,
  set: (v: string) => (store.nowPlayingTab = v === 'queue' ? 'queue' : 'lyric')
 })
 const currentLineIdx = computed(() => store.currentLine())
 // ===== 歌词滚动跟随（用函数 ref 收集节点，避免每次全量 querySelectorAll） =====
 const lineEls: (HTMLElement | null)[] = []
 function setLineEl(el: Element | { $el?: Element } | null, idx: number) {
  lineEls[idx] = (el as HTMLElement) ?? null
 }
 const reduceMotion = typeof window !== 'undefined' && window.matchMedia
  ? window.matchMedia('(prefers-reduced-motion: reduce)').matches
  : false
 watch(currentLineIdx, (idx) => {
  if (idx < 0) return
  lineEls[idx]?.scrollIntoView({ block: 'center', behavior: reduceMotion ? 'auto' : 'smooth' })
 })
 watch(
  () => store.lyricLines,
  () => {
    lineEls.length = 0
  }
 )
 // ===== 队列：大列表增量渲染（避免上千行一次性挂载） =====
 const QUEUE_STEP = 200
 const queueLimit = ref(QUEUE_STEP)
 watch(
  () => store.queue.length,
  () => (queueLimit.value = QUEUE_STEP)
 )
 const visibleQueue = computed(() =>
  store.queue.slice(0, queueLimit.value).map((item, index) => ({ item, index }))
 )
 const hasMoreQueue = computed(() => store.queue.length > queueLimit.value)
 function onSeek(ratio: number) {
  store.seek(ratio * store.duration)
 }
 function playAt(index: number) {
  const item = store.queue[index]
  if (item) store.playItem(item)
 }
 /** 暂停/继续当前曲目（不切换上下文） */
 function toggleAt(index: number) {
  if (index === store.queueIndex) store.toggle()
  else playAt(index)
 }
 </script>
 <template>
  <Dialog v-model:open="store.nowPlayingOpen">
    <DialogContent
      class="max-w-5xl overflow-hidden border p-0 sm:max-w-5xl"
      :show-close-button="false"
    >
      <DialogTitle class="sr-only">正在播放</DialogTitle>
      <div class="relative flex h-[min(78vh,600px)] flex-col">
        <!-- 背景：主题色轻渐变（不使用整图高斯模糊，避免持续 GPU 开销） -->
        <div
          class="pointer-events-none absolute inset-0"
          style="
            background:
              radial-gradient(120% 90% at 12% 0%, color-mix(in oklab, var(--muted) 92%, transparent), transparent 62%),
              linear-gradient(180deg, color-mix(in oklab, var(--muted) 55%, transparent), var(--background) 72%);
          "
        />
        <div class="relative flex min-h-0 flex-1">
          <!-- ===== 左：封面 + 控制 ===== -->
          <div class="flex w-[46%] min-w-0 flex-col justify-center gap-5 px-9 py-8">
            <div class="flex justify-center">
              <img
                v-if="coverUrl && !coverFailed"
                :src="coverUrl"
                class="aspect-square w-[min(240px,60%)] rounded-xl object-cover ring-1 ring-border/60"
                alt=""
                referrerpolicy="no-referrer"
                @error="coverFailed = true"
              />
              <div
                v-else
                class="flex aspect-square w-[min(240px,60%)] items-center justify-center rounded-xl bg-muted/60 text-muted-foreground ring-1 ring-border/60"
              >
                <Music2 class="size-16" />
              </div>
            </div>
            <div class="min-w-0 text-center">
              <div class="flex items-center justify-center gap-2">
                <h3 class="truncate text-[19px] font-semibold">{{ store.nowPlaying?.title || '未播放' }}</h3>
                <span
                  v-if="isPreview"
                  class="shrink-0 rounded bg-muted px-1.5 py-0.5 text-[10px] text-muted-foreground"
                >
                  试听
                </span>
              </div>
              <p class="mt-1 truncate text-[13px] text-muted-foreground">
                {{ store.nowPlaying?.artistNames || '—'
                }}<template v-if="store.nowPlaying?.album"> · {{ store.nowPlaying.album }}</template>
              </p>
            </div>
            <div class="flex flex-col gap-2">
              <ScrubBar
                :value="store.progress / 100"
                :buffered="store.bufferedPercent / 100"
                :duration-sec="store.duration"
                :disabled="!hasTrack"
                label="播放进度"
                @seek="onSeek"
              />
              <div class="mt-1 flex items-center justify-center gap-6">
                <Tooltip>
                  <TooltipTrigger as-child>
                    <button
                      type="button"
                      class="text-muted-foreground transition-colors hover:text-foreground"
                      :aria-label="modeLabel"
                      @click="store.togglePlayMode()"
                    >
                      <component :is="modeIcon" class="size-4" />
                    </button>
                  </TooltipTrigger>
                  <TooltipContent>{{ modeLabel }}</TooltipContent>
                </Tooltip>
                <button
                  type="button"
                  class="text-muted-foreground transition-colors hover:text-foreground disabled:opacity-40"
                  :disabled="!store.queue.length"
                  aria-label="上一首"
                  @click="store.prev()"
                >
                  <SkipBack class="size-6" />
                </button>
                <button
                  type="button"
                  class="flex size-14 items-center justify-center rounded-full bg-primary text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-40"
                  :disabled="!hasTrack"
                  :aria-label="store.playing ? '暂停' : '播放'"
                  @click="store.toggle()"
                >
                  <span
                    v-if="store.loadingPlay"
                    class="size-5 animate-spin rounded-full border-2 border-current border-t-transparent"
                  />
                  <Pause v-else-if="store.playing" class="size-6" />
                  <Play v-else class="size-6 translate-x-px" />
                </button>
                <button
                  type="button"
                  class="text-muted-foreground transition-colors hover:text-foreground disabled:opacity-40"
                  :disabled="!store.queue.length"
                  aria-label="下一首"
                  @click="store.next()"
                >
                  <SkipForward class="size-6" />
                </button>
                <button
                  type="button"
                  class="text-muted-foreground transition-colors hover:text-foreground"
                  :class="{ 'text-foreground': store.nowPlayingTab === 'queue' }"
                  :aria-label="`播放队列（${store.queue.length}）`"
                  :title="`播放队列（${store.queue.length}）`"
                  @click="store.nowPlayingTab = 'queue'"
                >
                  <ListMusic class="size-4" />
                </button>
              </div>
            </div>
          </div>
          <!-- ===== 右：歌词 / 队列 ===== -->
          <div class="flex min-w-0 flex-1 flex-col border-l border-border px-6 py-7">
            <div class="mb-4 flex items-center">
              <SegmentedNav v-model="activeTab" :items="tabs" />
            </div>
            <ScrollArea class="min-h-0 flex-1">
              <div v-if="activeTab === 'lyric'" class="flex flex-col gap-0.5 px-1 pb-6" data-slot="lyric-list">
                <p v-if="!store.lyricLines.length" class="py-8 text-center text-[13px] text-muted-foreground">
                  {{ isPreview ? '试听不加载歌词' : store.nowPlaying?.source === 'local' ? '本地文件无歌词' : '暂无歌词' }}
                </p>
                <button
                  v-for="(line, idx) in store.lyricLines"
                  :key="idx"
                  :ref="(el) => setLineEl(el as Element | null, idx)"
                  type="button"
                  class="rounded-md px-3 py-1.5 text-left text-[14px] leading-7 transition-all duration-200"
                  :class="
                    idx === currentLineIdx
                      ? 'bg-accent/60 text-[16px] font-medium text-foreground'
                      : idx < currentLineIdx
                        ? 'text-muted-foreground/45 hover:text-muted-foreground'
                        : 'text-muted-foreground/75 hover:text-foreground'
                  "
                  @click="store.seek(line.t)"
                >
                  {{ line.text }}
                </button>
              </div>
              <div v-else class="flex flex-col gap-0.5 px-1 pb-6">
                <div v-if="!store.queue.length" class="py-8 text-center text-[13px] text-muted-foreground">
                  队列为空
                </div>
                <div
                  v-for="row in visibleQueue"
                  :key="`${row.item.source}:${row.item.guid ?? row.index}`"
                  class="group flex items-center gap-3 rounded-md px-2 py-1.5 transition-colors"
                  :class="row.index === store.queueIndex && !isPreview ? 'bg-accent/60' : 'hover:bg-accent/40'"
                >
                  <button
                    type="button"
                    class="flex size-6 shrink-0 items-center justify-center text-[11px] tabular-nums text-muted-foreground"
                    :aria-label="row.index === store.queueIndex ? '暂停/继续' : '播放'"
                    @click="toggleAt(row.index)"
                  >
                    <span v-if="row.index === store.queueIndex && !isPreview" class="music-eq" :class="{ 'is-paused': !store.playing }">
                      <i /><i /><i />
                    </span>
                    <template v-else>
                      <Play class="size-3.5 opacity-0 transition-opacity group-hover:opacity-100" />
                      <span class="group-hover:hidden">{{ row.index + 1 }}</span>
                    </template>
                  </button>
                  <div class="min-w-0 flex-1">
                    <div
                      class="truncate text-[13px]"
                      :class="row.index === store.queueIndex && !isPreview ? 'font-medium' : ''"
                    >
                      {{ row.item.title }}
                    </div>
                    <div class="truncate text-[11.5px] text-muted-foreground">{{ row.item.artistNames || '—' }}</div>
                  </div>
                  <button
                    type="button"
                    class="shrink-0 text-muted-foreground opacity-0 transition-opacity hover:text-destructive group-hover:opacity-100"
                    aria-label="从队列移除"
                    @click="store.removeFromQueue(row.index)"
                  >
                    <Trash2 class="size-3.5" />
                  </button>
                </div>
                <button
                  v-if="hasMoreQueue"
                  type="button"
                  class="mt-1 rounded-md py-2 text-[12px] text-muted-foreground hover:bg-accent/40"
                  @click="queueLimit += QUEUE_STEP"
                >
                  显示更多（{{ store.queue.length - queueLimit }}）
                </button>
              </div>
            </ScrollArea>
          </div>
        </div>
        <DialogClose as-child>
          <button
            type="button"
            class="absolute right-4 top-4 z-10 rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
            aria-label="关闭"
          >
            <X class="size-5" />
          </button>
        </DialogClose>
      </div>
    </DialogContent>
  </Dialog>
 </template>
@@ -2,6 +2,7 @@
 import { ref, computed, onMounted, onUnmounted, nextTick, watch } from 'vue'
 import { Search, Settings, ChevronRight, ArrowUp, Check, Loader2 } from '@lucide/vue'
 import { Input } from '@/components/ui/input'
 import TitleBarMusic from '@/components/layout/TitleBarMusic.vue'
 import { invoke } from '@tauri-apps/api/core'
 import { getCurrentWindow } from '@tauri-apps/api/window'
 import { useSearchStore, type SearchItem } from '@/stores/searchStore'
@@ -363,6 +364,11 @@ const handleBlur = () => {
          保存设置
        </button>
      </Transition>
      <!-- 音乐栏：唱片图标 + 歌名（点击弹出方形播放控制窗），位于搜索框左侧 -->
      <div class="pointer-events-auto">
        <TitleBarMusic />
      </div>
      <div class="relative max-w-xs mr-3 pointer-events-auto">
        <Search 
          class="absolute left-2.5 top-1/2 -translate-y-1/2 size-4 text-muted-foreground" 
@@ -0,0 +1,436 @@
 <script setup lang="ts">
 import { computed, onMounted, ref, watch } from 'vue'
 import { toast } from 'vue-sonner'
 import {
  Disc3,
  ListMusic,
  Maximize2,
  MicVocal,
  Pause,
  Play,
  Repeat,
  Repeat1,
  Shuffle,
  SkipBack,
  SkipForward,
  Volume2,
  VolumeX
 } from '@lucide/vue'
 import { useFeiniuStore } from '@/stores/feiniuStore'
 import { createLogger } from '@/lib/logger'
 import ScrubBar from '@/components/common/ScrubBar.vue'
 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 ''
  if (t.coverUrl) return t.coverUrl
  if (t.source === 'feiniu' && t.coverId && store.mediaPrefix) {
    return `${store.mediaPrefix}/cover?coverId=${encodeURIComponent(t.coverId)}&size=96`
  }
  return ''
 })
 const bigCoverUrl = computed(() => {
  const t = store.nowPlaying
  if (!t) return ''
  if (t.coverUrl) return t.coverUrl
  if (t.source === 'feiniu' && t.coverId && store.mediaPrefix) {
    return `${store.mediaPrefix}/cover?coverId=${encodeURIComponent(t.coverId)}&size=320`
  }
  return ''
 })
 const coverFailed = ref(false)
 watch(coverUrl, () => (coverFailed.value = false))
 /** 是否已播放过（未播放过时不展示歌名，只留唱片图标） */
 const hasTrack = computed(() => !!store.nowPlaying)
 const title = computed(() => store.nowPlaying?.title ?? '')
 const subtitle = computed(() => {
  const t = store.nowPlaying
  if (!t) return ''
  return t.artistNames || (t.source === 'local' ? '本地文件' : '')
 })
 const isPreview = computed(() => store.nowPlaying?.source === 'preview')
 const modeIcon = computed(() => {
  if (store.playMode === 'loopOne') return Repeat1
  if (store.playMode === 'shuffle') return Shuffle
  return Repeat
 })
 const modeLabel = computed(() =>
  store.playMode === 'loopAll' ? '列表循环' : store.playMode === 'loopOne' ? '单曲循环' : '随机播放'
 )
 const volumePercent = computed(() => (store.muted ? 0 : store.volume))
 function onSeek(ratio: number) {
  store.seek(ratio * store.duration)
 }
 function openLyrics(tab: 'lyric' | 'queue') {
  store.nowPlayingTab = tab
  store.nowPlayingOpen = true
  open.value = false
 }
 // 播放失败统一在这里提示（store 只记录原因）
 watch(
  () => store.playError,
  (msg) => {
    if (!msg) return
    toast.error(msg)
    store.clearPlayError()
  }
 )
 // 应用启动即初始化音乐 store（幂等）：恢复播放列表/播放进度并预载上次在播的曲目。
 // 这样标题栏控件不必等用户先进「音乐库」页，也能显示并续播上次的歌。
 onMounted(() => {
  store.init().catch((e) => logger.error(`音乐初始化失败: ${e}`))
 })
 </script>
 <template>
  <Popover v-model:open="open">
    <PopoverAnchor as-child>
      <!-- 音乐栏：图标 = 播放/暂停（悬停有遮罩），标题 = 打开控制窗；
           悬停 0.3s 也会打开控制窗。容器本身不响应点击，避免与图标语义冲突 -->
      <div
        class="mr-2 flex h-7 max-w-[210px] items-center gap-2 rounded-md px-1.5 transition-colors hover:bg-secondary/60"
        @mouseenter="onTriggerEnter"
        @mouseleave="onTriggerLeave"
        @mousedown.stop
      >
        <!-- 唱片图标：点击开始/暂停 -->
        <button
          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-else-if="coverUrl && !coverFailed"
              :src="coverUrl"
              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="!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>
        <!-- 标题：点击打开播放控制窗 -->
        <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">
        <!-- 封面 -->
        <button
          type="button"
          class="group relative aspect-square w-[132px] overflow-hidden rounded-lg bg-muted ring-1 ring-border/60"
          :title="'打开歌词与大屏'"
          @click="openLyrics('lyric')"
        >
          <img
            v-if="bigCoverUrl"
            :src="bigCoverUrl"
            class="size-full object-cover transition-transform duration-300 group-hover:scale-105"
            alt=""
            referrerpolicy="no-referrer"
            @error="($event.target as HTMLImageElement).style.display = 'none'"
          />
          <span v-else class="flex size-full items-center justify-center text-muted-foreground">
            <Disc3 class="size-10" />
          </span>
          <span
            class="absolute inset-0 hidden items-center justify-center bg-foreground/35 text-primary-foreground group-hover:flex"
          >
            <Maximize2 class="size-5" />
          </span>
        </button>
        <!-- 曲目信息 -->
        <div class="w-full min-w-0 text-center">
          <div class="flex items-center justify-center gap-1.5">
            <span class="truncate text-[13px] font-medium">{{ title || '未播放' }}</span>
            <span
              v-if="isPreview"
              class="shrink-0 rounded bg-muted px-1 py-px text-[10px] text-muted-foreground"
            >
              试听
            </span>
          </div>
          <p class="mt-0.5 truncate text-[11.5px] text-muted-foreground">
            {{ subtitle || '—' }}<template v-if="store.nowPlaying?.album"> · {{ store.nowPlaying.album }}</template>
          </p>
        </div>
        <!-- 进度 -->
        <ScrubBar
          class="w-full"
          :value="store.progress / 100"
          :buffered="store.bufferedPercent / 100"
          :duration-sec="store.duration"
          :disabled="!hasTrack"
          label="播放进度"
          @seek="onSeek"
        />
        <!-- 控制 -->
        <div class="flex w-full items-center justify-center gap-5">
          <button
            type="button"
            class="text-muted-foreground transition-colors hover:text-foreground"
            :title="modeLabel"
            :aria-label="modeLabel"
            @click="store.togglePlayMode()"
          >
            <component :is="modeIcon" class="size-3.5" />
          </button>
          <button
            type="button"
            class="text-muted-foreground transition-colors hover:text-foreground disabled:opacity-40"
            :disabled="!store.queue.length"
            aria-label="上一首"
            @click="store.prev()"
          >
            <SkipBack class="size-5" />
          </button>
          <button
            type="button"
            class="flex size-10 items-center justify-center rounded-full bg-primary text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-40"
            :disabled="!hasTrack"
            :aria-label="store.playing ? '暂停' : '播放'"
            @click="store.toggle()"
          >
            <span
              v-if="store.loadingPlay"
              class="size-4 animate-spin rounded-full border-2 border-current border-t-transparent"
            />
            <Pause v-else-if="store.playing" class="size-4" />
            <Play v-else class="size-4 translate-x-px" />
          </button>
          <button
            type="button"
            class="text-muted-foreground transition-colors hover:text-foreground disabled:opacity-40"
            :disabled="!store.queue.length"
            aria-label="下一首"
            @click="store.next()"
          >
            <SkipForward class="size-5" />
          </button>
          <button
            type="button"
            class="text-muted-foreground transition-colors hover:text-foreground disabled:opacity-40"
            :disabled="isPreview"
            :title="`播放队列（${store.queue.length}）`"
            aria-label="播放队列"
            @click="openLyrics('queue')"
          >
            <ListMusic class="size-3.5" />
          </button>
        </div>
        <!-- 音量 + 入口 -->
        <div class="flex w-full items-center gap-2 border-t pt-2.5">
          <button
            type="button"
            class="shrink-0 text-muted-foreground transition-colors hover:text-foreground"
            :aria-label="store.muted ? '取消静音' : '静音'"
            @click="store.toggleMute()"
          >
            <VolumeX v-if="volumePercent === 0" class="size-3.5" />
            <Volume2 v-else class="size-3.5" />
          </button>
          <div class="w-16 shrink-0">
            <ScrubBar compact :value="volumePercent" label="音量" @seek="store.setVolume($event)" />
          </div>
          <div class="ml-auto flex items-center gap-1">
            <button
              type="button"
              class="flex items-center gap-1 rounded-md px-1.5 py-1 text-[11.5px] text-muted-foreground transition-colors hover:bg-secondary/60 hover:text-foreground"
              @click="openLyrics('lyric')"
            >
              <MicVocal class="size-3.5" />
              歌词
            </button>
            <button
              type="button"
              class="flex items-center gap-1 rounded-md px-1.5 py-1 text-[11.5px] text-muted-foreground transition-colors hover:bg-secondary/60 hover:text-foreground"
              :disabled="isPreview"
              @click="openLyrics('queue')"
            >
              <ListMusic class="size-3.5" />
              队列
            </button>
          </div>
        </div>
      </div>
    </PopoverContent>
  </Popover>
 </template>
 <style scoped>
 /* 唱片图标：播放时旋转（暂停保持当前角度继续待命） */
 .disc {
  animation: discSpin 8s linear infinite;
  animation-play-state: paused;
  background: var(--muted);
 }
 .disc.is-playing {
  animation-play-state: running;
 }
@keyframes discSpin {
  to {
    transform: rotate(360deg);
  }
 }
@media (prefers-reduced-motion: reduce) {
  .disc {
    animation: none;
  }
 }
 </style>
@@ -241,6 +241,32 @@ export const commands = {
 	downloaderInspect: (input: string) => __TAURI_INVOKE<TorrentInfo>("downloader_inspect", { input }),
 	/**  磁力任务：元数据解析成功后，用户勾选文件并确认开始下载 */
 	downloaderSelectBtFiles: (id: string, onlyFiles: number[]) => __TAURI_INVOKE<null>("downloader_select_bt_files", { id, onlyFiles }),
 	/**
 	 *  查询环境状态（Python / musicdl / FFmpeg / 桥接进程），设置页「环境检查」面板调用。
 	 *  异步命令：子进程探测在阻塞线程池执行，避免冻结主线程/UI。
 	 */
 	musicEnvStatus: () => __TAURI_INVOKE<MusicEnvStatus>("music_env_status"),
 	/**  安装便携 Python + musicdl（幂等），全程推送 music-runtime-install-progress 事件 */
 	musicInstallRuntime: () => __TAURI_INVOKE<MusicEnvStatus>("music_install_runtime"),
 	/**  取消便携运行时安装/下载 */
 	musicCancelRuntimeInstall: () => __TAURI_INVOKE<null>("music_cancel_runtime_install"),
 	/**  停止桥接进程 */
 	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 }),
 	/**  一次 IPC 完成指定窗口的显示与聚焦（截图覆盖层显示关键路径，减少串行往返） */
@@ -305,6 +331,20 @@ export const commands = {
 	width: number,
 	height: number,
 } | null, auto: boolean) => __TAURI_INVOKE<null>("screenshot_scroll_start", { hwnd, region, auto }),
 	/**
 	 *  滚动模式遮罩挖孔：在截图覆盖层窗口上挖出选区带的真孔（region = None 时复位整窗）。
 	 * 
 	 *  Chromium 系浏览器（Edge/Chrome）的窗口遮挡检测会把被完全覆盖的窗口标记为
 	 *  occluded 并暂停渲染——滚动截图时覆盖层铺满全屏，网页"看起来完全不滚动"。
 	 *  挖孔后目标窗口仅部分被覆盖，恢复渲染与滚轮响应（详见 capture::set_scroll_hole）。
 	 *  进入滚动模式时带选区调用，会话结束/新一轮截图开始时必须传 None 复位。
 	 */
 	screenshotSetScrollHole: (region: {
 	x: number,
 	y: number,
 	width: number,
 	height: number,
 } | null) => __TAURI_INVOKE<null>("screenshot_set_scroll_hole", { region }),
 	/**  将 PNG base64 写入系统剪贴板（转 CF_DIB） */
 	screenshotCopyImage: (pngBase64: string) => __TAURI_INVOKE<null>("screenshot_copy_image", { pngBase64 }),
 	/**  将 PNG base64 写入文件 */
@@ -315,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 */
@@ -508,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,
@@ -522,6 +772,29 @@ export type ExtractResult = {
 	error: string,
 };
 /**  一条飞牛音乐连接（持久化在 `MusicSettings`）。 */
 export type FeiniuConnection = {
 	id: string,
 	name: string,
 	/**  "lan" | "frp" | "fnconnect"（fnconnect 预留） */
 	kind: string,
 	/**  服务器地址（http://192.168.x.x:5666 或 https://域名） */
 	baseUrl: string,
 	username: string,
 	token: string,
 	deviceId: string,
 	accessCode: string,
 	/**  https 遇到自签证书时忽略校验 */
 	insecure: boolean,
 	/**  fnconnect 连接的 fnId（如 fnos.net/<id> 或裸 id） */
 	fnId?: string,
 	/**
 	 *  是否经由 FnConnect 中继链路（`<fnId>.fnos.net`）。
 	 *  中继要求所有请求携带 `Cookie: mode=relay`，否则网关 302 回登录页。
 	 */
 	relay?: boolean,
 };
 export type FileEntry = {
 	name: string,
 	path: string,
@@ -538,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,
@@ -564,6 +861,107 @@ export type KernelUpdateInfo = {
 	hasUpdate: boolean,
 };
 /**  环境状态（返回前端，设置页「环境检查」面板展示） */
 export type MusicEnvStatus = {
 	/**  系统 Python 版本（如 "3.14.5"），无则 None */
 	python: string | null,
 	/**  python 来源："system" | "bundled" | "none" */
 	pythonSource: string,
 	/**  便携 Python 可执行文件路径（未安装则 None） */
 	bundledPython: string | null,
 	/**  musicdl 是否可导入 */
 	musicdlInstalled: boolean,
 	/**  musicdl 版本 */
 	musicdlVersion: string | null,
 	/**  本应用锁定的 musicdl 版本（`MUSICDL_VERSION`）：是否过期、更新到哪个版本都以它为准 */
 	musicdlExpected: string,
 	/**
 	 *  已装 musicdl 是否与锁定版本不一致。
 	 *  未安装时恒为 false（那是「安装」引导的事，不是「更新」）。
 	 */
 	musicdlOutdated: boolean,
 	/**  FFmpeg 是否可用（部分音源需要，非必需） */
 	ffmpeg: string | null,
 	/**  桥接进程是否在运行 */
 	bridgeRunning: boolean,
 	/**  运行时目录（{app_data_dir}/music） */
 	runtimeDir: string,
 };
 /**  音乐模块设置（settings.json 持久化；变更即时生效） */
 export type MusicSettings = {
 	/**  下载保存目录 */
 	savedir: string,
 	/**  搜索源（musicdl 客户端名，如 NeteaseMusicClient） */
 	sources: string[],
 	/**  下载时同步保存歌词 */
 	lyricDownload: boolean,
 	/**  下载时同步保存封面 */
 	coverDownload: boolean,
 	/**  搜索/下载请求是否走代理模块（mihomo mixed 端口） */
 	useProxy: boolean,
 	/**  最大并发下载数 */
 	maxConcurrent: number,
 	/**  下载引擎："musicdl" | "rust"（P2 生效） */
 	downloadEngine: string,
 	/**  下载时是否弹窗选择音质（默认关；开启后点下载弹出所选歌曲档位并集选择） */
 	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（登录成功后保存） */
 	feiniuToken?: string,
 	/**  飞牛音乐登录账号（展示 + 重新登录回填用） */
 	feiniuUsername?: string,
 	/**  飞牛音乐设备 ID（32 位 hex，登录签名用，一次生成复用） */
 	feiniuDeviceId?: string,
 	/**  飞牛音乐访问安全码（可选；仅需访问码的库才填，LAN 通常为空） */
 	feiniuAccessCode?: string,
 	/**  飞牛音乐连接列表（多连接：局域网 / FnConnect） */
 	feiniuConnections?: FeiniuConnection[],
 	/**  当前激活连接的 id */
 	feiniuActiveId?: string,
 	/**  本地曲库扫描目录（默认含音乐下载 savedir） */
 	feiniuLocalDirs?: string[],
 	/**  播放缓存开关 */
 	feiniuCacheEnabled?: boolean,
 	/**  缓存上限（GB） */
 	feiniuCacheMaxGb?: number,
 	/**  播放模式："stream" 直连流式 | "cache" 缓存后播放 */
 	feiniuPlayMode?: string,
 	/**  飞牛曲库目标目录（NAS 绝对路径，如 vol1/1000/Music；上传到飞牛用） */
 	feiniuLibraryNasPath?: string,
 	/**  下载完成后自动上传到飞牛曲库 */
 	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,
@@ -585,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,
@@ -655,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,
@@ -675,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,
@@ -709,6 +1173,13 @@ export type TaskStatus =
 /**  已取消（用户取消：进度与文件已清除，仅保留记录，只能再次下载） */
 "cancelled";
 /**  Token 用量（AI 引擎返回；其余引擎为 None） */
 export type TokenUsage = {
 	promptTokens: number,
 	completionTokens: number,
 	totalTokens: number,
 };
 /**  种子信息（inspect 解析结果，供命令返回给前端做文件勾选） */
 export type TorrentInfo = {
 	/**  种子名称 */
@@ -735,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
@@ -0,0 +1,157 @@
 <script setup lang="ts">
 import { computed, onMounted, ref, watch } from 'vue'
 import { ArrowLeft, Search } from '@lucide/vue'
 import { Input } from '@/components/ui/input'
 import { Button } from '@/components/ui/button'
 import { Card, CardContent } from '@/components/ui/card'
 import { ScrollArea } from '@/components/ui/scroll-area'
 import { Separator } from '@/components/ui/separator'
 import { useSearchStore } from '@/stores/searchStore'
 import { registerAllTools, TOOLS_META } from './tools'
 import {
  getAllTools, getTool, searchTools,
  CATEGORY_ORDER, CATEGORY_LABEL, type DevTool
 } from './registry'
 const searchStore = useSearchStore()
 registerAllTools()
 const allTools = getAllTools()
 // ===== 列表视图：搜索 + 分类筛选 =====
 const query = ref('')
 const category = ref<'all' | DevTool['category']>('all')
 const filteredTools = computed(() => {
  const list = searchTools(query.value)
  if (category.value === 'all') return list
  return list.filter(t => t.category === category.value)
 })
 interface ToolGroup {
  category: DevTool['category']
  label: string
  tools: DevTool[]
 }
 const groupedTools = computed<ToolGroup[]>(() => {
  if (category.value !== 'all') {
    return [{
      category: category.value as DevTool['category'],
      label: CATEGORY_LABEL[category.value as DevTool['category']],
      tools: filteredTools.value
    }]
  }
  const groups: ToolGroup[] = []
  for (const cat of CATEGORY_ORDER) {
    const tools = filteredTools.value.filter(t => t.category === cat)
    if (tools.length > 0) groups.push({ category: cat, label: CATEGORY_LABEL[cat], tools })
  }
  return groups
 })
 // ===== 详情视图 =====
 const selectedId = ref<string | null>(null)
 const selectedTool = computed<DevTool | null>(() => {
  if (!selectedId.value) return null
  return getTool(selectedId.value) ?? null
 })
 function openTool(id: string) {
  selectedId.value = id
 }
 // ===== 全局搜索跳转：工具索引 → 打开对应工具 =====
 onMounted(() => {
  const actions = new Map<number, () => void>()
  TOOLS_META.forEach((t, i) => {
    actions.set(i, () => openTool(t.id))
  })
  searchStore.registerActions('devtools', actions)
 })
 watch(selectedId, () => {
  query.value = ''
 })
 </script>
 <template>
  <div class="h-full p-6 overflow-hidden flex flex-col">
    <!-- 列表视图 -->
    <template v-if="!selectedTool">
      <div class="flex items-center gap-3 mb-4 shrink-0 flex-wrap">
        <div class="relative flex-1 min-w-[180px] max-w-xs">
          <Search class="absolute left-2.5 top-1/2 -translate-y-1/2 size-4 text-muted-foreground" />
          <Input v-model="query" placeholder="搜索工具..." class="h-8 pl-8 text-sm" />
        </div>
        <Button
          v-for="cat in (['all', ...CATEGORY_ORDER] as const)"
          :key="cat"
          size="sm"
          variant="ghost"
          class="h-7 px-2.5 text-xs"
          :class="category === cat ? 'bg-secondary text-foreground' : 'text-muted-foreground'"
          @click="category = cat as typeof category"
        >
          {{ cat === 'all' ? '全部' : CATEGORY_LABEL[cat as DevTool['category']] }}
        </Button>
        <span class="text-xs text-muted-foreground ml-auto">{{ (category === 'all' ? allTools : filteredTools).length }} 个工具</span>
      </div>
      <ScrollArea class="flex-1 min-h-0 -mr-3 pr-3">
        <div v-if="filteredTools.length === 0" class="h-full flex items-center justify-center text-muted-foreground text-sm">
          没有找到匹配的工具
        </div>
        <!-- 按分类分组 -->
        <div v-for="group in groupedTools" :key="group.category" class="mb-5">
          <div class="flex items-center gap-2 mb-2">
            <span class="text-xs font-medium text-muted-foreground">{{ group.label }}</span>
            <Separator class="flex-1" />
          </div>
          <div class="grid grid-cols-2 md:grid-cols-3 xl:grid-cols-4 gap-3">
            <Card
              v-for="tool in group.tools"
              :key="tool.id"
              class="cursor-pointer transition-all hover:border-primary/50 hover:shadow-sm !py-0 !gap-0"
              @click="openTool(tool.id)"
            >
              <CardContent class="p-4 flex flex-col gap-2">
                <div class="size-9 rounded-lg bg-primary/10 text-primary flex items-center justify-center">
                  <component :is="tool.icon" class="size-5" />
                </div>
                <div class="flex flex-col gap-0.5">
                  <span class="text-sm font-medium leading-tight">{{ tool.name }}</span>
                  <span class="text-xs text-muted-foreground leading-snug line-clamp-2">{{ tool.description }}</span>
                </div>
              </CardContent>
            </Card>
          </div>
        </div>
      </ScrollArea>
    </template>
    <!-- 工具详情视图 -->
    <template v-else>
      <div class="flex items-center gap-3 mb-4 shrink-0">
        <Button size="sm" variant="ghost" class="gap-1 h-8" @click="selectedId = null">
          <ArrowLeft class="size-4" />
          返回
        </Button>
        <div class="size-8 rounded-lg bg-primary/10 text-primary flex items-center justify-center">
          <component :is="selectedTool.icon" class="size-4" />
        </div>
        <div class="flex flex-col">
          <span class="text-sm font-medium leading-tight">{{ selectedTool.name }}</span>
          <span class="text-xs text-muted-foreground leading-snug">{{ selectedTool.description }}</span>
        </div>
      </div>
      <ScrollArea class="flex-1 min-h-0 -mr-3 pr-3">
        <div class="max-w-3xl px-1 pb-6">
          <component :is="selectedTool.component" />
        </div>
      </ScrollArea>
    </template>
  </div>
 </template>
@@ -0,0 +1,75 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { Check, Copy } from '@lucide/vue'
 import { Textarea } from '@/components/ui/textarea'
 import { Button } from '@/components/ui/button'
 const props = withDefaults(
  defineProps<{
    text: string
    editable?: boolean
    placeholder?: string
    label?: string
    minHeight?: string
  }>(),
  { editable: false, placeholder: '结果...', label: '结果', minHeight: '120px' }
 )
 const emit = defineEmits<{
  (e: 'update:text', v: string): void
  (e: 'copy', text: string): void
 }>()
 const copied = ref(false)
 let copyTimer: number
 const lineCount = computed(() => (props.text ? props.text.split('\n').length : 0))
 const charCount = computed(() => props.text.length)
 const copy = async () => {
  try {
    await navigator.clipboard.writeText(props.text)
    emit('copy', props.text)
    copied.value = true
    window.clearTimeout(copyTimer)
    copyTimer = window.setTimeout(() => (copied.value = false), 1500)
  } catch {
    /* 复制失败静默 */
  }
 }
 const onInput = (v: string | number) => {
  if (props.editable) emit('update:text', String(v))
 }
 </script>
 <template>
  <div class="flex flex-col gap-1.5">
    <div class="flex items-center justify-between">
      <span class="text-xs font-medium">{{ label }}</span>
      <div class="flex items-center gap-2 text-[11px] text-muted-foreground">
        <span>{{ lineCount }} 行</span>
        <span>{{ charCount }} 字符</span>
        <Button
          v-if="!editable"
          size="icon"
          variant="ghost"
          class="size-6"
          :title="copied ? '已复制' : '复制'"
          @click="copy"
        >
          <Check v-if="copied" class="size-3.5 text-green-500" />
          <Copy v-else class="size-3.5" />
        </Button>
      </div>
    </div>
    <Textarea
      :model-value="props.text"
      :readonly="!editable"
      :placeholder="placeholder"
      :style="{ minHeight }"
      class="font-mono text-xs leading-relaxed resize-y"
      @update:model-value="onInput"
    />
  </div>
 </template>
@@ -0,0 +1,40 @@
 <script setup lang="ts">
 export interface SegmentedOption {
  value: string
  label: string
 }
 defineProps<{
  options: SegmentedOption[]
  modelValue: string
  label?: string
  size?: 'xs' | 'sm'
 }>()
 const emit = defineEmits<{
  (e: 'update:modelValue', v: string): void
 }>()
 </script>
 <template>
  <div class="flex items-center gap-2 shrink-0">
    <span v-if="label" class="text-sm text-muted-foreground">{{ label }}</span>
    <div class="inline-flex rounded-md border border-border bg-muted/40 p-1">
      <button
        v-for="o in options"
        :key="o.value"
        type="button"
        class="rounded px-3 font-medium transition-colors cursor-pointer"
        :class="[
          size === 'sm' ? 'py-1.5 text-sm' : 'py-1 text-sm',
          modelValue === o.value
            ? 'bg-background text-foreground shadow-sm'
            : 'text-muted-foreground hover:text-foreground'
        ]"
        @click="emit('update:modelValue', o.value)"
      >
        {{ o.label }}
      </button>
    </div>
  </div>
 </template>
@@ -0,0 +1,27 @@
 import type { ModuleConfig } from '@/types/module'
 import type { SearchIndexItem } from '@/stores/searchIndex'
 import { TOOLS_META } from './tools'
 /** 开发者工具模块：聚合大量轻量文本/编码/转换工具 */
 const searchItems: SearchIndexItem[] = TOOLS_META.map((t) => ({
  title: t.name,
  description: t.description,
  keywords: [t.name, ...t.keywords]
 }))
 export const moduleConfig: ModuleConfig = {
  id: 'devtools',
  name: '开发者工具',
  icon: 'devtools',
  description: 'JSON / Base64 / 时间戳 / 正则 / 颜色 / Cron / 密码等 20 个常用开发工具',
  category: 'tool',
  defaultEnabled: true,
  loader: () => import('./DevToolsModule.vue'),
  searchItems,
  lifecycle: {
    onEnable: async () => {},
    onDisable: async () => {}
  },
  order: 60
 }
@@ -0,0 +1,59 @@
 import type { Component } from 'vue'
 export type DevToolCategory = 'encoding' | 'transform' | 'text' | 'generate' | 'reference'
 export interface DevTool {
  id: string
  name: string
  description: string
  category: DevToolCategory
  keywords: string[]
  icon: Component
  component: Component
 }
 /** 分类展示顺序 */
 export const CATEGORY_ORDER: DevToolCategory[] = ['transform', 'encoding', 'text', 'generate', 'reference']
 export const CATEGORY_LABEL: Record<DevToolCategory, string> = {
  transform: '转换',
  encoding: '编码',
  text: '文本',
  generate: '生成',
  reference: '速查'
 }
 const allTools: DevTool[] = []
 const registry = new Map<string, DevTool>()
 export function registerTool(tool: DevTool): void {
  if (registry.has(tool.id)) return
  registry.set(tool.id, tool)
  allTools.push(tool)
 }
 export function getTool(id: string): DevTool | undefined {
  return registry.get(id)
 }
 export function getAllTools(): DevTool[] {
  return [...allTools]
 }
 export function getToolsByCategory(): Record<DevToolCategory, DevTool[]> {
  const result = {} as Record<DevToolCategory, DevTool[]>
  for (const cat of CATEGORY_ORDER) result[cat] = []
  for (const tool of allTools) {
    result[tool.category].push(tool)
  }
  return result
 }
 export function searchTools(query: string): DevTool[] {
  if (!query.trim()) return allTools
  const q = query.trim().toLowerCase()
  return allTools.filter(t =>
    t.name.toLowerCase().includes(q) ||
    t.description.toLowerCase().includes(q) ||
    t.keywords.some(k => k.toLowerCase().includes(q))
  )
 }
@@ -0,0 +1,166 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { ArrowDownUp, Upload } from '@lucide/vue'
 import { Textarea } from '@/components/ui/textarea'
 import { Label } from '@/components/ui/label'
 import { Button } from '@/components/ui/button'
 import Segmented from '../components/Segmented.vue'
 import ResultArea from '../components/ResultArea.vue'
 type Tab = 'convert' | 'file'
 const tab = ref<Tab>('convert')
 const mode = ref<'encode' | 'decode'>('encode')
 const input = ref('')
 const error = ref('')
 function encode(s: string): string {
  const bytes = new TextEncoder().encode(s)
  let bin = ''
  for (const b of bytes) bin += String.fromCharCode(b)
  return btoa(bin)
 }
 function decode(s: string): string {
  const cleaned = s.replace(/[\r\n\s]/g, '')
  const bin = atob(cleaned)
  const bytes = Uint8Array.from(bin, ch => ch.charCodeAt(0))
  return new TextDecoder().decode(bytes)
 }
 const output = computed(() => {
  error.value = ''
  const v = input.value
  if (!v) return ''
  try {
    return mode.value === 'encode' ? encode(v) : decode(v)
  } catch (e) {
    error.value = '解码失败：' + String(e)
    return ''
  }
 })
 const swap = () => {
  if (output.value) {
    input.value = output.value
    mode.value = mode.value === 'encode' ? 'decode' : 'encode'
  }
 }
 // ===== 文件转 Base64 =====
 const file = ref<File | null>(null)
 const fileInput = ref<HTMLInputElement | null>(null)
 const fileBase64 = ref('')
 const fileError = ref('')
 const fileLoading = ref(false)
 const FILE_SIZE_LIMIT = 64 * 1024 * 1024 // 64MB 保护上限（Base64 展示本身就很占内存）
 function formatSize(bytes: number): string {
  if (bytes < 1024) return `${bytes} B`
  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
  return `${(bytes / 1024 / 1024).toFixed(1)} MB`
 }
 const mime = computed(() => file.value?.type || 'application/octet-stream')
 async function onFileChange(e: Event) {
  const el = e.target as HTMLInputElement
  const f = el.files?.[0] ?? null
  fileError.value = ''
  fileBase64.value = ''
  file.value = f
  if (!f) return
  if (f.size > FILE_SIZE_LIMIT) {
    fileError.value = `文件过大（${formatSize(f.size)}），请使用 64MB 以内的文件`
    return
  }
  fileLoading.value = true
  try {
    const buf = await f.arrayBuffer()
    const bytes = new Uint8Array(buf)
    let bin = ''
    const CHUNK = 0x8000
    for (let i = 0; i < bytes.length; i += CHUNK) {
      bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK))
    }
    fileBase64.value = btoa(bin)
  } catch (e) {
    fileError.value = '读取失败：' + String(e)
  } finally {
    fileLoading.value = false
  }
 }
 function clearFile() {
  file.value = null
  fileBase64.value = ''
  fileError.value = ''
  if (fileInput.value) fileInput.value.value = ''
 }
 const dataUrl = computed(() =>
  fileBase64.value ? `data:${mime.value};base64,${fileBase64.value}` : ''
 )
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <Segmented
      v-model="tab"
      :options="[
        { value: 'convert', label: '文本互转' },
        { value: 'file', label: '文件转 Base64' }
      ]"
    />
    <!-- 文本互转 -->
    <template v-if="tab === 'convert'">
      <div class="flex items-center justify-between flex-wrap gap-2">
        <Segmented
          v-model="mode"
          label="操作"
          :options="[
            { value: 'encode', label: '编码' },
            { value: 'decode', label: '解码' }
          ]"
        />
        <Button size="sm" variant="outline" class="h-8 text-sm gap-1" :disabled="!output" @click="swap">
          <ArrowDownUp class="size-3.5" />
          结果回填
        </Button>
      </div>
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs">{{ mode === 'encode' ? '原文' : 'Base64 字符串' }}</Label>
        <Textarea v-model="input" placeholder="在此输入..." class="min-h-[120px] font-mono text-xs resize-y" />
      </div>
      <ResultArea :text="output" placeholder="结果" />
      <p v-if="error" class="text-xs text-destructive">{{ error }}</p>
    </template>
    <!-- 文件转 Base64 -->
    <template v-else>
      <div class="flex items-center gap-2 flex-wrap">
        <Button size="sm" variant="outline" class="h-8 text-sm gap-1.5" @click="fileInput?.click()">
          <Upload class="size-3.5" />
          选择文件
        </Button>
        <input ref="fileInput" type="file" class="hidden" @change="onFileChange" />
        <template v-if="file">
          <span class="text-xs font-mono text-muted-foreground">{{ file.name }}（{{ formatSize(file.size) }}，{{ mime }}）</span>
          <Button size="sm" variant="ghost" class="h-7 text-xs" @click="clearFile">移除</Button>
        </template>
      </div>
      <p v-if="fileError" class="text-xs text-destructive">{{ fileError }}</p>
      <template v-if="fileBase64">
        <ResultArea :text="fileBase64" label="Base64" placeholder="Base64" minHeight="100px" />
        <ResultArea :text="dataUrl" label="Data URL" placeholder="Data URL" minHeight="100px" />
        <p class="text-xs text-muted-foreground">Base64 体积约为原文件的 4/3（{{ formatSize(fileBase64.length) }}）。</p>
      </template>
      <p v-else-if="!fileLoading" class="text-xs text-muted-foreground">选择文件后自动生成 Base64 与 Data URL。</p>
      <p v-else class="text-xs text-muted-foreground">读取中...</p>
    </template>
  </div>
 </template>
@@ -0,0 +1,87 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { Textarea } from '@/components/ui/textarea'
 import { Label } from '@/components/ui/label'
 import Segmented from '../components/Segmented.vue'
 import ResultArea from '../components/ResultArea.vue'
 type CaseMode =
  | 'camel' | 'pascal' | 'snake' | 'kebab'
  | 'upper' | 'lower' | 'title'
  | 'spaceToDash' | 'trimLines' | 'collapseSpace'
 const modes: { value: CaseMode; label: string }[] = [
  { value: 'camel', label: 'camelCase' },
  { value: 'pascal', label: 'PascalCase' },
  { value: 'snake', label: 'snake_case' },
  { value: 'kebab', label: 'kebab-case' },
  { value: 'upper', label: '全大写' },
  { value: 'lower', label: '全小写' },
  { value: 'title', label: '标题式' },
  { value: 'spaceToDash', label: '空格转下划线' },
  { value: 'collapseSpace', label: '合并空行空白' },
  { value: 'trimLines', label: '每行去首尾空格' }
 ]
 const mode = ref<CaseMode>('camel')
 const input = ref('')
 function toWords(s: string): string[] {
  // 拆分 camelCase / snake_case / kebab-case / 空格，得到词
  return s
    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
    .replace(/[_\-\s]+/g, ' ')
    .trim()
    .split(' ')
    .filter(Boolean)
 }
 const output = computed(() => {
  const v = input.value
  if (!v) return ''
  switch (mode.value) {
    case 'upper':
      return v.toUpperCase()
    case 'lower':
      return v.toLowerCase()
    case 'title':
      return v.replace(/\b\w/g, ch => ch.toUpperCase())
    case 'spaceToDash':
      return v.replace(/\s+/g, '_')
    case 'collapseSpace':
      return v.split(/\n+/).map(l => l.trim()).filter(Boolean).join('\n')
    case 'trimLines':
      return v.split('\n').map(l => l.trim()).join('\n')
    case 'camel': // fallthrough
    case 'pascal':
    case 'snake':
    case 'kebab':
      break
  }
  const words = toWords(v).filter(Boolean)
  if (words.length === 0) return ''
  if (mode.value === 'camel') {
    return words[0].toLowerCase() + words.slice(1).map(w => cap(w)).join('')
  }
  if (mode.value === 'pascal') {
    return words.map(cap).join('')
  }
  const sep = mode.value === 'snake' ? '_' : '-'
  return words.map(w => w.toLowerCase()).join(sep)
 })
 function cap(w: string): string {
  return w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()
 }
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <Segmented v-model="mode" :options="modes" />
    <div class="flex flex-col gap-1.5">
      <Label class="text-xs">原文</Label>
      <Textarea v-model="input" placeholder="在此输入..." class="min-h-[140px] font-mono text-xs resize-y" />
    </div>
    <ResultArea :text="output" placeholder="结果" />
  </div>
 </template>
@@ -0,0 +1,129 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { Textarea } from '@/components/ui/textarea'
 import { Label } from '@/components/ui/label'
 import { Switch } from '@/components/ui/switch'
 const input = ref('')
 const showFrequency = ref(true)
 function utf8Bytes(s: string): number {
  return new TextEncoder().encode(s).length
 }
 /** 统计词：中文按字、英文按单词 */
 function countWords(s: string): number {
  const cjk = (s.match(/[\u4e00-\u9fff\u3400-\u4dbf]/g) ?? []).length
  const latin = (s.match(/[a-zA-Z0-9]+(?:[-'’][a-zA-Z0-9]+)*/g) ?? []).length
  return cjk + latin
 }
 interface Stats {
  chars: number
  charsNoSpace: number
  bytes: number
  words: number
  lines: number
  nonEmptyLines: number
  sentences: number
  paragraphs: number
 }
 const stats = computed<Stats>(() => {
  const v = input.value
  const lines = v === '' ? 0 : v.split('\n').length
  const nonEmpty = v.split('\n').filter(l => l.trim()).length
  // 句子：以 。！？.!?;； 结尾的段落片段
  const sentences = (v.match(/[^。！？!?\n]+[。！？!?]?/g) ?? []).filter(s => s.trim()).length
  const paragraphs = v.split(/\n\s*\n/).filter(p => p.trim()).length
  return {
    chars: v.length,
    charsNoSpace: v.replace(/\s/g, '').length,
    bytes: utf8Bytes(v),
    words: countWords(v),
    lines,
    nonEmptyLines: nonEmpty,
    sentences,
    paragraphs
  }
 })
 const FIELDS: Array<{ key: keyof Stats; label: string }> = [
  { key: 'chars', label: '字符数' },
  { key: 'charsNoSpace', label: '字符数（不含空白）' },
  { key: 'bytes', label: '字节数（UTF-8）' },
  { key: 'words', label: '词数（中文按字/英文按词）' },
  { key: 'lines', label: '行数' },
  { key: 'nonEmptyLines', label: '非空行数' },
  { key: 'sentences', label: '句子数' },
  { key: 'paragraphs', label: '段落数（空行分隔）' }
 ]
 /** 高频字符 / 高频词 top 10 */
 const topChars = computed(() => {
  if (!showFrequency.value || !input.value) return []
  const map = new Map<string, number>()
  for (const ch of input.value) {
    if (/\s/.test(ch)) continue
    map.set(ch, (map.get(ch) ?? 0) + 1)
  }
  return [...map.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10)
 })
 const topWords = computed(() => {
  if (!showFrequency.value || !input.value) return []
  const tokens = input.value.match(/[\u4e00-\u9fff]|[a-zA-Z0-9]+(?:[-'’][a-zA-Z0-9]+)*/g) ?? []
  const map = new Map<string, number>()
  for (const t of tokens) {
    map.set(t, (map.get(t) ?? 0) + 1)
  }
  return [...map.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10)
 })
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <div class="flex flex-col gap-1.5">
      <div class="flex items-center justify-between">
        <Label class="text-xs">文本</Label>
        <label class="flex items-center gap-2 text-xs text-muted-foreground cursor-pointer">
          显示高频统计
          <Switch v-model="showFrequency" />
        </label>
      </div>
      <Textarea v-model="input" placeholder="粘贴或输入文本，实时统计..." class="min-h-[160px] font-mono text-xs resize-y" />
    </div>
    <div class="rounded-md border border-border divide-y divide-border text-xs">
      <div v-for="f in FIELDS" :key="f.key" class="flex justify-between px-3 py-1.5">
        <span class="text-muted-foreground">{{ f.label }}</span>
        <span class="font-mono">{{ stats[f.key].toLocaleString() }}</span>
      </div>
    </div>
    <template v-if="showFrequency && input">
      <div class="grid grid-cols-2 gap-3">
        <div class="flex flex-col gap-1.5">
          <Label class="text-xs">高频字符 Top 10</Label>
          <div class="rounded-md border border-border divide-y divide-border text-xs">
            <div v-for="([ch, n], i) in topChars" :key="i" class="flex justify-between px-3 py-1">
              <span class="font-mono w-8 text-center rounded bg-muted">{{ ch }}</span>
              <span class="font-mono text-muted-foreground">{{ n }} 次</span>
            </div>
            <div v-if="topChars.length === 0" class="px-3 py-2 text-muted-foreground">无内容</div>
          </div>
        </div>
        <div class="flex flex-col gap-1.5">
          <Label class="text-xs">高频词 Top 10</Label>
          <div class="rounded-md border border-border divide-y divide-border text-xs">
            <div v-for="([w, n], i) in topWords" :key="i" class="flex justify-between px-3 py-1">
              <span class="font-mono">{{ w }}</span>
              <span class="font-mono text-muted-foreground">{{ n }} 次</span>
            </div>
            <div v-if="topWords.length === 0" class="px-3 py-2 text-muted-foreground">无内容</div>
          </div>
        </div>
      </div>
    </template>
  </div>
 </template>
@@ -0,0 +1,211 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import ResultArea from '../components/ResultArea.vue'
 const input = ref('#3b82f6')
 const alpha = ref(1)
 interface Rgb {
  r: number
  g: number
  b: number
 }
 function clampByte(v: number): number {
  return Math.min(255, Math.max(0, Math.round(v)))
 }
 function parseColor(s: string): Rgb | null {
  const v = s.trim().toLowerCase()
  if (!v) return null
  // #rgb / #rgba / #rrggbb / #rrggbbaa
  const hex = v.match(/^#?([0-9a-f]{3,8})$/)
  if (hex) {
    const h = hex[1]
    if (h.length === 3 || h.length === 4) {
      const [r, g, b] = [h[0], h[1], h[2]].map(c => parseInt(c + c, 16))
      return { r, g, b }
    }
    if (h.length === 6 || h.length === 8) {
      return {
        r: parseInt(h.slice(0, 2), 16),
        g: parseInt(h.slice(2, 4), 16),
        b: parseInt(h.slice(4, 6), 16)
      }
    }
    return null
  }
  // rgb() / rgba()
  const rgb = v.match(/^rgba?\(\s*(\d{1,3})[\s,]+(\d{1,3})[\s,]+(\d{1,3})/)
  if (rgb) {
    return { r: clampByte(Number(rgb[1])), g: clampByte(Number(rgb[2])), b: clampByte(Number(rgb[3])) }
  }
  // hsl() / hsla()
  const hsl = v.match(/^hsla?\(\s*(\d{1,3}(?:\.\d+)?)\s*[,\s]\s*(\d{1,3})%\s*[,\s]\s*(\d{1,3})%/)
  if (hsl) {
    return hslToRgb(Number(hsl[1]), Number(hsl[2]) / 100, Number(hsl[3]) / 100)
  }
  return null
 }
 function hslToRgb(h: number, s: number, l: number): Rgb {
  h = ((h % 360) + 360) % 360
  const c = (1 - Math.abs(2 * l - 1)) * s
  const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
  const m = l - c / 2
  let r = 0, g = 0, b = 0
  if (h < 60) { r = c; g = x }
  else if (h < 120) { r = x; g = c }
  else if (h < 180) { g = c; b = x }
  else if (h < 240) { g = x; b = c }
  else if (h < 300) { r = x; b = c }
  else { r = c; b = x }
  return { r: clampByte((r + m) * 255), g: clampByte((g + m) * 255), b: clampByte((b + m) * 255) }
 }
 function rgbToHsl({ r, g, b }: Rgb): { h: number; s: number; l: number } {
  const rn = r / 255, gn = g / 255, bn = b / 255
  const max = Math.max(rn, gn, bn)
  const min = Math.min(rn, gn, bn)
  const l = (max + min) / 2
  let h = 0
  let s = 0
  if (max !== min) {
    const d = max - min
    s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
    if (max === rn) h = ((gn - bn) / d + (gn < bn ? 6 : 0)) * 60
    else if (max === gn) h = ((bn - rn) / d + 2) * 60
    else h = ((rn - gn) / d + 4) * 60
  }
  return { h: Math.round(h), s: Math.round(s * 100), l: Math.round(l * 100) }
 }
 function rgbToHsv({ r, g, b }: Rgb): { h: number; s: number; v: number } {
  const rn = r / 255, gn = g / 255, bn = b / 255
  const max = Math.max(rn, gn, bn)
  const min = Math.min(rn, gn, bn)
  const d = max - min
  let h = 0
  if (d !== 0) {
    if (max === rn) h = (((gn - bn) / d) % 6) * 60
    else if (max === gn) h = ((bn - rn) / d + 2) * 60
    else h = ((rn - gn) / d + 4) * 60
  }
  h = Math.round(((h % 360) + 360) % 360)
  return { h, s: Math.round((max === 0 ? 0 : d / max) * 100), v: Math.round(max * 100) }
 }
 function toHex({ r, g, b }: Rgb): string {
  return '#' + [r, g, b].map(x => x.toString(16).padStart(2, '0')).join('')
 }
 const rgb = computed<Rgb | null>(() => parseColor(input.value))
 const alphaInput = computed(() => {
  const a = Math.min(1, Math.max(0, alpha.value))
  return Math.round(a * 255)
    .toString(16)
    .padStart(2, '0')
 })
 const formats = computed(() => {
  const c = rgb.value
  if (!c) return null
  const hsl = rgbToHsl(c)
  const hsv = rgbToHsv(c)
  return {
    hex: toHex(c),
    hexA: `${toHex(c)}${alphaInput.value}`,
    rgb: `rgb(${c.r}, ${c.g}, ${c.b})`,
    rgba: `rgba(${c.r}, ${c.g}, ${c.b}, ${alpha.value})`,
    hsl: `hsl(${hsl.h}, ${hsl.s}%, ${hsl.l}%)`,
    hsla: `hsla(${hsl.h}, ${hsl.s}%, ${hsl.l}%, ${alpha.value})`,
    hsv: `hsv(${hsv.h}, ${hsv.s}%, ${hsv.v}%)`,
    cmyk: rgbToCmyk(c)
  }
 })
 function rgbToCmyk({ r, g, b }: Rgb): string {
  const rn = r / 255, gn = g / 255, bn = b / 255
  const k = 1 - Math.max(rn, gn, bn)
  if (k === 1) return 'cmyk(0%, 0%, 0%, 100%)'
  const c = (1 - rn - k) / (1 - k)
  const m = (1 - gn - k) / (1 - k)
  const y = (1 - bn - k) / (1 - k)
  const p = (x: number) => Math.round(x * 100)
  return `cmyk(${p(c)}%, ${p(m)}%, ${p(y)}%, ${p(k)}%)`
 }
 // 亮度判断（W3C 公式），用于预览色上的文字颜色
 const previewTextLight = computed(() => {
  const c = rgb.value
  if (!c) return true
  return (c.r * 0.299 + c.g * 0.587 + c.b * 0.114) < 140
 })
 // 明暗梯度
 const shades = computed(() => {
  const c = rgb.value
  if (!c) return []
  const hsl = rgbToHsl(c)
  return [-60, -40, -20, 0, 20, 40, 60].map(delta => {
    const l = Math.min(96, Math.max(4, hsl.l + delta))
    const rgb2 = hslToRgb(hsl.h, hsl.s / 100, l / 100)
    return { label: delta === 0 ? `${l}%` : `${l}%`, color: toHex(rgb2) }
  })
 })
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <div class="flex items-end gap-3 flex-wrap">
      <div class="flex flex-col gap-1.5 flex-1 min-w-[200px]">
        <Label class="text-xs">颜色（支持 #hex / rgb() / hsl()）</Label>
        <Input v-model="input" placeholder="#3b82f6 或 rgb(59,130,246) 或 hsl(217,91%,60%)" class="font-mono text-sm" />
      </div>
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs">透明度 {{ alpha.toFixed(2) }}</Label>
        <input v-model.number="alpha" type="range" min="0" max="1" step="0.01" class="w-40 accent-primary" />
      </div>
    </div>
    <template v-if="formats && rgb">
      <!-- 预览 -->
      <div
        class="rounded-md border border-border h-20 flex items-center justify-center font-mono text-sm"
        :style="{ backgroundColor: `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${alpha})`, color: previewTextLight ? '#ffffff' : '#000000' }"
      >
        {{ formats.hex }} {{ alpha < 1 ? `（透明度 ${alpha.toFixed(2)}）` : '' }}
      </div>
      <ResultArea :text="formats.hex" label="HEX" placeholder="HEX" minHeight="60px" />
      <ResultArea v-if="alpha < 1" :text="formats.hexA" label="HEX + Alpha" placeholder="HEX" minHeight="60px" />
      <ResultArea :text="formats.rgb" label="RGB" placeholder="RGB" minHeight="60px" />
      <ResultArea v-if="alpha < 1" :text="formats.rgba" label="RGBA" placeholder="RGBA" minHeight="60px" />
      <ResultArea :text="formats.hsl" label="HSL" placeholder="HSL" minHeight="60px" />
      <ResultArea v-if="alpha < 1" :text="formats.hsla" label="HSLA" placeholder="HSLA" minHeight="60px" />
      <ResultArea :text="formats.hsv" label="HSV" placeholder="HSV" minHeight="60px" />
      <ResultArea :text="formats.cmyk" label="CMYK" placeholder="CMYK" minHeight="60px" />
      <!-- 明暗梯度 -->
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs">明暗梯度</Label>
        <div class="flex rounded-md overflow-hidden border border-border h-10">
          <div
            v-for="(s, i) in shades"
            :key="i"
            class="flex-1 flex items-center justify-center text-[10px] font-mono cursor-pointer"
            :style="{ backgroundColor: s.color, color: i < 3 ? '#fff' : '#000' }"
            :title="s.color"
            @click="input = s.color"
          >
            {{ s.label }}
          </div>
        </div>
      </div>
    </template>
    <p v-else-if="input" class="text-xs text-destructive">无法识别的颜色格式，支持 #hex / rgb() / rgba() / hsl() / hsla()。</p>
  </div>
 </template>
@@ -0,0 +1,228 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import ResultArea from '../components/ResultArea.vue'
 const expr = ref('*/5 * * * *')
 interface FieldMatcher {
  /** 该字段是否为非通配（受限） */
  restricted: boolean
  match(v: number): boolean
 }
 function parseField(field: string, min: number, max: number): FieldMatcher {
  const values = new Set<number>()
  let restricted = false
  for (const part of field.split(',')) {
    const [rangePart, stepPart] = part.split('/')
    const step = stepPart ? Number(stepPart) : 1
    if (!Number.isFinite(step) || step < 1) throw new Error(`非法步长：${part}`)
    let lo: number
    let hi: number
    if (rangePart === '*') {
      if (!stepPart) {
        // 纯通配：匹配任意值（不受限）
        return { restricted: false, match: () => true }
      }
      lo = min
      hi = max
    } else if (rangePart.includes('-')) {
      const [a, b] = rangePart.split('-').map(Number)
      if (!Number.isFinite(a) || !Number.isFinite(b) || a < min || b > max || a > b) {
        throw new Error(`非法范围：${part}（应在 ${min}-${max} 内）`)
      }
      lo = a
      hi = b
    } else {
      const n = Number(rangePart)
      if (!Number.isFinite(n) || n < min || n > max) {
        throw new Error(`非法值：${part}（应在 ${min}-${max} 内）`)
      }
      lo = n
      hi = n
    }
    restricted = true
    for (let v = lo; v <= hi; v += step) values.add(v)
  }
  if (values.size === 0) throw new Error(`空字段：${field}`)
  return { restricted, match: v => values.has(v) }
 }
 const FIELD_NAMES = ['分钟', '小时', '日', '月', '星期'] as const
 // 星期允许 0-7（0 与 7 均为周日）
 const FIELD_RANGES: Array<[number, number]> = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 7]]
 const DOW_NAMES = ['日', '一', '二', '三', '四', '五', '六']
 /** 支持英文别名（星期/月份）与中文星期 */
 function normalizeExpr(s: string): string {
  const DOW_MAP: Record<string, string> = {
    sun: '0', mon: '1', tue: '2', wed: '3', thu: '4', fri: '5', sat: '6',
    '日': '0', '一': '1', '二': '2', '三': '3', '四': '4', '五': '5', '六': '6'
  }
  const MON_MAP: Record<string, string> = {
    jan: '1', feb: '2', mar: '3', apr: '4', may: '5', jun: '6',
    jul: '7', aug: '8', sep: '9', oct: '10', nov: '11', dec: '12'
  }
  let out = s.trim().toLowerCase()
  for (const [k, v] of Object.entries(MON_MAP)) {
    out = out.split(k).join(v)
  }
  for (const [k, v] of Object.entries(DOW_MAP)) {
    out = out.split(k).join(v)
  }
  return out
 }
 interface CronParsed {
  minute: FieldMatcher
  hour: FieldMatcher
  dom: FieldMatcher
  month: FieldMatcher
  dow: FieldMatcher
  domRestricted: boolean
  dowRestricted: boolean
 }
 function parseCron(s: string): CronParsed {
  const parts = normalizeExpr(s).split(/\s+/)
  if (parts.length !== 5) {
    throw new Error(`应为 5 个字段（分 时 日 月 周），当前 ${parts.length} 个`)
  }
  const [minute, hour, dom, month, dowRaw] = parts.map((p, i) => parseField(p, FIELD_RANGES[i][0], FIELD_RANGES[i][1]))
  // cron 标准允许星期用 0-7，其中 0 与 7 均为周日
  const dow: FieldMatcher = {
    restricted: dowRaw.restricted,
    match: v => dowRaw.match(v) || (v === 0 && dowRaw.match(7))
  }
  return {
    minute, hour, dom, month, dow,
    domRestricted: dom.restricted,
    dowRestricted: dow.restricted
  }
 }
 /** 标准 cron 语义：日 与 星期 都受限时，任一匹配即可 */
 function matches(p: CronParsed, d: Date): boolean {
  if (!p.minute.match(d.getMinutes())) return false
  if (!p.hour.match(d.getHours())) return false
  if (!p.month.match(d.getMonth() + 1)) return false
  const domOk = p.dom.match(d.getDate())
  const dowOk = p.dow.match(d.getDay())
  if (p.domRestricted && p.dowRestricted) return domOk || dowOk
  return domOk && dowOk
 }
 function nextRuns(p: CronParsed, from: Date, n: number): Date[] {
  const out: Date[] = []
  const t = new Date(from.getTime())
  t.setSeconds(0, 0)
  t.setMinutes(t.getMinutes() + 1)
  // 最多向前扫描 5 年（处理 2 月 29 日等罕见窗口）
  const limit = new Date(from.getTime() + 5 * 365.25 * 24 * 3600 * 1000)
  while (out.length < n && t < limit) {
    if (matches(p, t)) out.push(new Date(t.getTime()))
    t.setMinutes(t.getMinutes() + 1)
  }
  return out
 }
 const pad = (x: number) => String(x).padStart(2, '0')
 function fmt(d: Date): string {
  const week = `周${DOW_NAMES[d.getDay()]}`
  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())} ${week}`
 }
 const parsed = computed<{ runs: string[]; fields: string[] } | null>(() => {
  const s = expr.value.trim()
  if (!s) return null
  try {
    const p = parseCron(s)
    const runs = nextRuns(p, new Date(), 6)
    const fields = s.split(/\s+/)
    return { runs: runs.map(fmt), fields }
  } catch {
    return null
  }
 })
 const error = computed(() => {
  const s = expr.value.trim()
  if (!s) return ''
  try {
    parseCron(s)
    return ''
  } catch (e) {
    return String(e instanceof Error ? e.message : e)
  }
 })
 /** 人类可读的字段说明 */
 const fieldDesc = computed<string[]>(() => {
  const s = expr.value.trim()
  if (!s || error.value) return []
  const fields = normalizeExpr(s).split(/\s+/)
  return fields.map((f, i) => {
    if (f === '*') return `${FIELD_NAMES[i]}：任意`
    return `${FIELD_NAMES[i]}：${f}`
  })
 })
 const EXAMPLES = [
  { expr: '*/5 * * * *', desc: '每 5 分钟' },
  { expr: '0 * * * *', desc: '每小时整点' },
  { expr: '30 9 * * 1-5', desc: '工作日 9:30' },
  { expr: '0 0 1 * *', desc: '每月 1 日零点' },
  { expr: '0 12 */2 * *', desc: '每 2 天的 12:00' }
 ]
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <div class="flex flex-col gap-1.5">
      <Label class="text-xs">Cron 表达式（分 时 日 月 周，支持英文/中文星期与英文月份）</Label>
      <Input v-model="expr" placeholder="*/5 * * * *" class="font-mono text-sm" :class="{ 'border-destructive': !!error }" />
      <div class="flex items-center gap-2 flex-wrap">
        <button
          v-for="ex in EXAMPLES"
          :key="ex.expr"
          type="button"
          class="text-xs px-2 py-0.5 rounded border border-border text-muted-foreground hover:text-foreground cursor-pointer transition-colors"
          @click="expr = ex.expr"
        >
          {{ ex.desc }}
        </button>
      </div>
    </div>
    <p v-if="error" class="text-xs text-destructive">{{ error }}</p>
    <template v-if="parsed">
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs">字段拆解</Label>
        <div class="rounded-md border border-border divide-y divide-border text-xs">
          <div v-for="(f, i) in parsed.fields" :key="i" class="flex gap-3 px-3 py-1.5">
            <span class="w-12 shrink-0 text-muted-foreground">{{ FIELD_NAMES[i] }}</span>
            <span class="font-mono">{{ f }}</span>
            <span class="ml-auto text-muted-foreground">{{ fieldDesc[i]?.split('：')[1] ?? '' }}</span>
          </div>
        </div>
      </div>
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs">接下来 6 次执行时间</Label>
        <div class="rounded-md border border-border divide-y divide-border text-xs font-mono">
          <div v-for="(r, i) in parsed.runs" :key="i" class="px-3 py-1.5 flex gap-3">
            <span class="text-muted-foreground w-4">+{{ i + 1 }}</span>
            <span>{{ r }}</span>
          </div>
          <div v-if="parsed.runs.length === 0" class="px-3 py-2 text-muted-foreground">5 年内无执行时间（表达式可能过严，如 2 月 30 日）。</div>
        </div>
      </div>
      <ResultArea :text="parsed.runs.join('\n')" label="执行时间列表（可复制）" placeholder="执行时间" />
    </template>
    <p v-else-if="!expr" class="text-xs text-muted-foreground">输入 5 段式 cron 表达式，自动计算接下来 6 次执行时间。</p>
  </div>
 </template>
@@ -0,0 +1,146 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { Textarea } from '@/components/ui/textarea'
 import { Label } from '@/components/ui/label'
 import ResultArea from '../components/ResultArea.vue'
 const oldText = ref('')
 const newText = ref('')
 type Op = 'equal' | 'del' | 'add'
 interface DiffLine {
  op: Op
  oldLine: string
  line: string
  newLine: string
 }
 // LCS DP 为 O(n·m)，行数过大会卡死 UI；超过上限停止计算并提示
 const MAX_LINES = 3000
 // 先裁剪公共前缀/后缀，LCS 只算中间差异部分（典型场景提速明显）
 function diffLines(a: string[], b: string[]): DiffLine[] {
  const out: DiffLine[] = []
  let start = 0
  while (start < a.length && start < b.length && a[start] === b[start]) {
    out.push({ op: 'equal', oldLine: a[start], line: a[start], newLine: b[start] })
    start++
  }
  let endA = a.length, endB = b.length
  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
    endA--
    endB--
  }
  const mid = lcsDiff(a.slice(start, endA), b.slice(start, endB))
  // 后缀公共部分：a[endA..] 与 b[endB..] 逐行配对
  const suffix: DiffLine[] = []
  for (let i = a.length - 1; i >= endA; i--) {
    const j = endB + (i - endA)
    suffix.unshift({ op: 'equal', oldLine: a[i], line: a[i], newLine: b[j] })
  }
  return [...out, ...mid, ...suffix]
 }
 function lcsDiff(a: string[], b: string[]): DiffLine[] {
  const n = a.length
  const m = b.length
  if (n === 0) return b.map(line => ({ op: 'add' as const, oldLine: '', line, newLine: '' }))
  if (m === 0) return a.map(line => ({ op: 'del' as const, oldLine: line, line, newLine: '' }))
  // LCS DP
  const dp: number[][] = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0))
  for (let i = n - 1; i >= 0; i--) {
    for (let j = m - 1; j >= 0; j--) {
      dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1])
    }
  }
  const out: DiffLine[] = []
  let i = 0
  let j = 0
  while (i < n && j < m) {
    if (a[i] === b[j]) {
      out.push({ op: 'equal', oldLine: a[i], line: a[i], newLine: b[j] })
      i++
      j++
    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
      out.push({ op: 'del', oldLine: a[i], line: a[i], newLine: '' })
      i++
    } else {
      out.push({ op: 'add', oldLine: '', line: b[j], newLine: b[j] })
      j++
    }
  }
  while (i < n) {
    out.push({ op: 'del', oldLine: a[i], line: a[i], newLine: '' })
    i++
  }
  while (j < m) {
    out.push({ op: 'add', oldLine: '', line: b[j], newLine: b[j] })
    j++
  }
  return out
 }
 const tooLarge = computed(() =>
  oldText.value.split('\n').length > MAX_LINES || newText.value.split('\n').length > MAX_LINES
 )
 const lines = computed(() => {
  if (tooLarge.value) return []
  return diffLines(oldText.value.split('\n'), newText.value.split('\n'))
 })
 const stats = computed(() => {
  let adds = 0
  let dels = 0
  for (const l of lines.value) {
    if (l.op === 'add') adds++
    else if (l.op === 'del') dels++
  }
  return { adds, dels }
 })
 const unifiedText = computed(() => {
  if (lines.value.length === 0) return ''
  return lines.value
    .map(l => (l.op === 'add' ? '+' : l.op === 'del' ? '-' : ' ') + l.line)
    .join('\n')
 })
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <div class="grid grid-cols-2 gap-3">
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs text-red-500">旧文本（删除 {{ stats.dels }} 行）</Label>
        <Textarea v-model="oldText" placeholder="旧文本..." class="min-h-[140px] font-mono text-xs resize-y" />
      </div>
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs text-green-500">新文本（新增 {{ stats.adds }} 行）</Label>
        <Textarea v-model="newText" placeholder="新文本..." class="min-h-[140px] font-mono text-xs resize-y" />
      </div>
    </div>
    <div class="flex flex-col gap-1.5">
      <Label class="text-xs">差异预览</Label>
      <div class="rounded-md border border-border max-h-64 overflow-auto font-mono text-xs leading-relaxed">
        <div v-if="tooLarge" class="p-3 text-destructive">文本超过 {{ MAX_LINES }} 行，差异计算已停止（LCS 算法复杂度 O(n·m)），请缩减输入。</div>
        <div v-else-if="lines.length === 0 || (oldText === '' && newText === '')" class="p-3 text-muted-foreground">输入两边文本查看差异。</div>
        <div
          v-for="(l, i) in lines"
          :key="i"
          class="flex whitespace-pre px-2 py-0.5"
          :class="{
            'bg-red-500/10 text-red-600 dark:text-red-400': l.op === 'del',
            'bg-green-500/10 text-green-600 dark:text-green-400': l.op === 'add',
            'text-muted-foreground': l.op === 'equal'
          }"
        >
          <span class="w-5 shrink-0 select-none">{{ l.op === 'add' ? '+' : l.op === 'del' ? '-' : ' ' }}</span>
          <span class="break-all">{{ l.line }}</span>
        </div>
      </div>
    </div>
    <ResultArea :text="unifiedText" label="统一格式（可复制）" placeholder="unified diff" />
  </div>
 </template>
@@ -0,0 +1,64 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { Textarea } from '@/components/ui/textarea'
 import { Label } from '@/components/ui/label'
 import Segmented from '../components/Segmented.vue'
 import ResultArea from '../components/ResultArea.vue'
 type Eol = 'CRLF' | 'LF' | 'CR'
 const target = ref<Eol>('LF')
 const input = ref('')
 const detectEol = computed<Eol | 'mixed' | 'none'>(() => {
  const v = input.value
  if (!v) return 'none'
  // 注意：\r\n 中的 \n 也会命中 /\n/，必须用负向后顾排除 CRLF 中的 LF
  const hasCrlf = v.includes('\r\n')
  const hasLfOnly = /(?<!\r)\n/.test(v)
  const hasCrOnly = /\r(?!\n)/.test(v)
  if (!hasCrlf && !hasLfOnly && !hasCrOnly) return 'none'
  if (hasCrlf && !hasLfOnly && !hasCrOnly) return 'CRLF'
  if (!hasCrlf && hasLfOnly && !hasCrOnly) return 'LF'
  if (!hasCrlf && !hasLfOnly && hasCrOnly) return 'CR'
  return 'mixed'
 })
 const detectLabel: Record<string, string> = {
  CRLF: 'CRLF（Windows）',
  LF: 'LF（Unix / macOS）',
  CR: 'CR（旧 Mac）',
  mixed: '混合',
  none: '未检测到换行符'
 }
 const output = computed(() => {
  const v = input.value
  if (!v) return ''
  const sep = target.value === 'CRLF' ? '\r\n' : target.value === 'LF' ? '\n' : '\r'
  return v.replace(/\r\n|\r|\n/g, sep)
 })
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <Segmented
      v-model="target"
      label="目标行尾符"
      :options="[
        { value: 'CRLF', label: 'CRLF (\\r\\n)' },
        { value: 'LF', label: 'LF (\\n)' },
        { value: 'CR', label: 'CR (\\r)' }
      ]"
    />
    <p class="text-xs text-muted-foreground">当前检测：<span class="font-medium">{{ detectLabel[detectEol] }}</span></p>
    <div class="flex flex-col gap-1.5">
      <Label class="text-xs">原文</Label>
      <Textarea v-model="input" placeholder="在此输入..." class="min-h-[160px] font-mono text-xs resize-y" />
    </div>
    <ResultArea :text="output" placeholder="结果" />
  </div>
 </template>
@@ -0,0 +1,103 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { ArrowDownUp } from '@lucide/vue'
 import { Textarea } from '@/components/ui/textarea'
 import { Label } from '@/components/ui/label'
 import { Button } from '@/components/ui/button'
 import Segmented from '../components/Segmented.vue'
 import ResultArea from '../components/ResultArea.vue'
 const type = ref<'html' | 'json'>('html')
 const mode = ref<'encode' | 'decode'>('encode')
 const input = ref('')
 function htmlEncode(s: string): string {
  return s
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;')
 }
 function htmlDecode(s: string): string {
  return s
    .replace(/&amp;/g, '&')
    .replace(/&lt;/g, '<')
    .replace(/&gt;/g, '>')
    .replace(/&quot;/g, '"')
    .replace(/&#39;|&#x27;/g, "'")
    .replace(/&nbsp;|&#160;/g, ' ')
 }
 function jsonEncode(s: string): string {
  return JSON.stringify(s).slice(1, -1)
 }
 function jsonDecode(s: string): string {
  // 粘贴的原文可能含真实换行等控制字符，直接拼进 JSON 字符串会解析失败；
  // 仅转义控制字符（已转义的反斜杠序列不受影响，其中的控制字符不是裸的）
  const escaped = s.replace(/[\u0000-\u001f]/g, c => {
    const map: Record<string, string> = { '\n': '\\n', '\r': '\\r', '\t': '\\t', '\b': '\\b', '\f': '\\f' }
    return map[c] ?? '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0')
  })
  return JSON.parse('"' + escaped + '"')
 }
 const output = computed(() => {
  const v = input.value
  if (!v) return { text: '', error: '' }
  try {
    if (type.value === 'html') {
      return { text: mode.value === 'encode' ? htmlEncode(v) : htmlDecode(v), error: '' }
    }
    return { text: mode.value === 'encode' ? jsonEncode(v) : jsonDecode(v), error: '' }
  } catch (e) {
    return { text: '', error: '转换失败：' + String(e) }
  }
 })
 const swap = () => {
  if (output.value.text) {
    input.value = output.value.text
    mode.value = mode.value === 'encode' ? 'decode' : 'encode'
  }
 }
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <div class="flex items-center justify-between flex-wrap gap-3">
      <div class="flex items-center gap-3 flex-wrap">
        <Segmented
          v-model="type"
          label="类型"
          :options="[
            { value: 'html', label: 'HTML' },
            { value: 'json', label: 'JSON 字符串' }
          ]"
        />
        <Segmented
          v-model="mode"
          label="操作"
          :options="[
            { value: 'encode', label: '转义' },
            { value: 'decode', label: '反转义' }
          ]"
        />
      </div>
      <Button size="sm" variant="outline" class="h-8 text-sm gap-1" :disabled="!output.text" @click="swap">
        <ArrowDownUp class="size-3.5" />
        结果回填
      </Button>
    </div>
    <div class="flex flex-col gap-1.5">
      <Label class="text-xs">原文 / 已转义文本</Label>
      <Textarea v-model="input" placeholder="在此输入..." class="min-h-[120px] font-mono text-xs resize-y" />
    </div>
    <ResultArea :text="output.text" placeholder="结果" />
    <p v-if="output.error" class="text-xs text-destructive">{{ output.error }}</p>
  </div>
 </template>
@@ -0,0 +1,249 @@
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue'
 import { Upload } from '@lucide/vue'
 import { Textarea } from '@/components/ui/textarea'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { Switch } from '@/components/ui/switch'
 import Segmented from '../components/Segmented.vue'
 import ResultArea from '../components/ResultArea.vue'
 type HashAlgo = 'MD5' | 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512'
 type Source = 'text' | 'file'
 const algos: { value: HashAlgo; label: string }[] = [
  { value: 'MD5', label: 'MD5' },
  { value: 'SHA-1', label: 'SHA-1' },
  { value: 'SHA-256', label: 'SHA-256' },
  { value: 'SHA-384', label: 'SHA-384' },
  { value: 'SHA-512', label: 'SHA-512' }
 ]
 const algo = ref<HashAlgo>('SHA-256')
 const source = ref<Source>('text')
 const uppercase = ref(false)
 const useHmac = ref(false)
 const hmacKey = ref('')
 const input = ref('')
 const output = ref('')
 const loading = ref(false)
 const error = ref('')
 // ===== 文件 =====
 const file = ref<File | null>(null)
 const fileInput = ref<HTMLInputElement | null>(null)
 const fileError = ref('')
 const FILE_SIZE_LIMIT = 512 * 1024 * 1024 // 512MB 保护上限
 function formatSize(bytes: number): string {
  if (bytes < 1024) return `${bytes} B`
  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
  if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`
  return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`
 }
 async function onFileChange(e: Event) {
  const el = e.target as HTMLInputElement
  fileError.value = ''
  file.value = el.files?.[0] ?? null
  await compute()
 }
 function clearFile() {
  file.value = null
  if (fileInput.value) fileInput.value.value = ''
  void compute()
 }
 // ===== MD5（WebCrypto 不支持，自行实现）=====
 function md5(input: Uint8Array): string {
  const S = [
    7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22,
    5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20,
    4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23,
    6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21
  ]
  const K = new Uint32Array(64)
  for (let i = 0; i < 64; i++) K[i] = Math.floor(Math.abs(Math.sin(i + 1)) * 4294967296)
  const len = input.length
  const bitLenLo = (len * 8) >>> 0
  const bitLenHi = Math.floor(len / 536870912) // len*8 / 2^32
  const paddedLen = (((len + 8) >> 6) + 1) * 64
  const msg = new Uint8Array(paddedLen)
  msg.set(input)
  msg[len] = 0x80
  const dv = new DataView(msg.buffer)
  dv.setUint32(paddedLen - 8, bitLenLo, true)
  dv.setUint32(paddedLen - 4, bitLenHi, true)
  let a0 = 0x67452301
  let b0 = 0xefcdab89
  let c0 = 0x98badcfe
  let d0 = 0x10325476
  const M = new Uint32Array(16)
  for (let off = 0; off < paddedLen; off += 64) {
    for (let i = 0; i < 16; i++) M[i] = dv.getUint32(off + i * 4, true)
    let A = a0, B = b0, C = c0, D = d0
    for (let i = 0; i < 64; i++) {
      let F: number
      let g: number
      if (i < 16) { F = (B & C) | (~B & D); g = i }
      else if (i < 32) { F = (D & B) | (~D & C); g = (5 * i + 1) % 16 }
      else if (i < 48) { F = B ^ C ^ D; g = (3 * i + 5) % 16 }
      else { F = C ^ (B | ~D); g = (7 * i) % 16 }
      F = (F + A + K[i] + M[g]) >>> 0
      A = D
      D = C
      C = B
      B = (B + ((F << S[i]) | (F >>> (32 - S[i])))) >>> 0
    }
    a0 = (a0 + A) >>> 0
    b0 = (b0 + B) >>> 0
    c0 = (c0 + C) >>> 0
    d0 = (d0 + D) >>> 0
  }
  const out = new Uint8Array(16)
  const odv = new DataView(out.buffer)
  odv.setUint32(0, a0, true)
  odv.setUint32(4, b0, true)
  odv.setUint32(8, c0, true)
  odv.setUint32(12, d0, true)
  return Array.from(out, b => b.toString(16).padStart(2, '0')).join('')
 }
 function toHex(buf: ArrayBuffer): string {
  return Array.from(new Uint8Array(buf), b => b.toString(16).padStart(2, '0')).join('')
 }
 async function compute() {
  error.value = ''
  fileError.value = ''
  output.value = ''
  if (source.value === 'text') {
    const text = input.value
    if (!text) return
    loading.value = true
    try {
      const data = new TextEncoder().encode(text)
      output.value = await digest(algo.value, data)
    } catch (e) {
      error.value = '计算失败：' + String(e)
    } finally {
      loading.value = false
    }
  } else {
    const f = file.value
    if (!f) return
    if (f.size > FILE_SIZE_LIMIT) {
      fileError.value = `文件过大（${formatSize(f.size)}），请使用 512MB 以内的文件`
      return
    }
    loading.value = true
    try {
      const data = new Uint8Array(await f.arrayBuffer())
      output.value = await digest(algo.value, data)
    } catch (e) {
      error.value = '计算失败：' + String(e)
    } finally {
      loading.value = false
    }
  }
 }
 async function digest(algorithm: HashAlgo, data: Uint8Array): Promise<string> {
  let hex: string
  if (algorithm === 'MD5') {
    hex = md5(data)
  } else {
    hex = toHex(await crypto.subtle.digest(algorithm, data))
  }
  if (useHmac.value) {
    if (algorithm === 'MD5') {
      throw new Error('HMAC 不支持 MD5，请选择 SHA 系列算法')
    }
    const enc = new TextEncoder()
    const key = await crypto.subtle.importKey(
      'raw', enc.encode(hmacKey.value),
      { name: 'HMAC', hash: { name: algorithm } },
      false, ['sign']
    )
    hex = toHex(await crypto.subtle.sign('HMAC', key, data))
  }
  return hex
 }
 const displayOutput = computed(() =>
  uppercase.value ? output.value.toUpperCase() : output.value
 )
 // 输入、算法、选项、文件变化时自动重算
 watch([input, algo, source, uppercase, useHmac, hmacKey], () => {
  void compute()
 })
 // 首次挂载如有初始值则计算（通常为空）
 void compute()
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <div class="flex items-center gap-3 flex-wrap">
      <Segmented
        v-model="source"
        :options="[
          { value: 'text', label: '文本' },
          { value: 'file', label: '文件' }
        ]"
      />
      <Segmented v-model="algo" label="算法" :options="algos" />
      <label class="flex items-center gap-2 text-xs text-muted-foreground cursor-pointer">
        大写
        <Switch v-model="uppercase" />
      </label>
    </div>
    <div v-if="algo === 'MD5'" class="text-xs text-muted-foreground">
      注：MD5 与 SHA-1 已不推荐用于安全场景，仅用于兼容旧系统或校验比对。
    </div>
    <!-- HMAC -->
    <div class="flex flex-col gap-2 rounded-md border border-border p-3">
      <label class="flex items-center gap-2 text-xs cursor-pointer w-fit">
        <Switch v-model="useHmac" />
        <span class="font-medium">HMAC（密钥签名）</span>
      </label>
      <div v-if="useHmac" class="flex flex-col gap-1.5">
        <Label class="text-xs">密钥</Label>
        <Input v-model="hmacKey" placeholder="HMAC 密钥（仅支持 SHA 系列）" class="font-mono text-sm" />
      </div>
    </div>
    <!-- 文本输入 -->
    <div v-if="source === 'text'" class="flex flex-col gap-1.5">
      <Label class="text-xs">原文（文本）</Label>
      <Textarea v-model="input" placeholder="在此输入文本..." class="min-h-[120px] font-mono text-xs resize-y" />
    </div>
    <!-- 文件输入 -->
    <div v-else class="flex flex-col gap-2">
      <Label class="text-xs">选择文件</Label>
      <div class="flex items-center gap-2 flex-wrap">
        <Button size="sm" variant="outline" class="h-8 text-sm gap-1.5" @click="fileInput?.click()">
          <Upload class="size-3.5" />
          选择文件
        </Button>
        <input ref="fileInput" type="file" class="hidden" @change="onFileChange" />
        <template v-if="file">
          <span class="text-xs font-mono text-muted-foreground">{{ file.name }}（{{ formatSize(file.size) }}）</span>
          <Button size="sm" variant="ghost" class="h-7 text-xs" @click="clearFile">移除</Button>
        </template>
      </div>
      <p v-if="fileError" class="text-xs text-destructive">{{ fileError }}</p>
    </div>
    <ResultArea :text="loading ? '计算中...' : displayOutput" :label="useHmac ? 'HMAC 摘要（十六进制）' : '摘要（十六进制）'" placeholder="摘要" />
    <p v-if="error" class="text-xs text-destructive">{{ error }}</p>
  </div>
 </template>
@@ -0,0 +1,195 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { Input } from '@/components/ui/input'
 import { Badge } from '@/components/ui/badge'
 import Segmented from '../components/Segmented.vue'
 type Tab = 'status' | 'mime'
 const tab = ref<Tab>('status')
 const query = ref('')
 interface StatusDef {
  code: number
  name: string
  desc: string
 }
 const STATUSES: StatusDef[] = [
  // 1xx
  { code: 100, name: 'Continue', desc: '客户端应继续请求，常用于 Expect: 100-continue 大文件上传前探测' },
  { code: 101, name: 'Switching Protocols', desc: '服务器同意切换协议（如升级 WebSocket）' },
  { code: 102, name: 'Processing', desc: '服务器已收到请求，仍在处理（WebDAV）' },
  { code: 103, name: 'Early Hints', desc: '预加载提示，主响应前先返回 Link 头' },
  // 2xx
  { code: 200, name: 'OK', desc: '请求成功' },
  { code: 201, name: 'Created', desc: '请求成功并创建了新资源（POST 之后常见）' },
  { code: 202, name: 'Accepted', desc: '请求已受理，但尚未处理完成（异步任务）' },
  { code: 204, name: 'No Content', desc: '成功但无返回体（DELETE / PUT 常见）' },
  { code: 206, name: 'Partial Content', desc: '范围请求成功（断点续传 / 视频拖动）' },
  // 3xx
  { code: 301, name: 'Moved Permanently', desc: '永久重定向，搜索引擎更新链接（GET 保持、POST 可能转 GET）' },
  { code: 302, name: 'Found', desc: '临时重定向，浏览器可能将 POST 改为 GET' },
  { code: 303, name: 'See Other', desc: '临时重定向，强制使用 GET 访问新地址' },
  { code: 304, name: 'Not Modified', desc: '缓存有效（协商缓存命中，无返回体）' },
  { code: 307, name: 'Temporary Redirect', desc: '临时重定向，严格保持原请求方法与体' },
  { code: 308, name: 'Permanent Redirect', desc: '永久重定向，严格保持原请求方法与体' },
  // 4xx
  { code: 400, name: 'Bad Request', desc: '请求语法错误 / 参数校验失败' },
  { code: 401, name: 'Unauthorized', desc: '未认证（缺少或无效的凭证，应带 WWW-Authenticate 头）' },
  { code: 402, name: 'Payment Required', desc: '要求付费（保留状态码，实际很少使用）' },
  { code: 403, name: 'Forbidden', desc: '已认证但无权限访问该资源' },
  { code: 404, name: 'Not Found', desc: '资源不存在' },
  { code: 405, name: 'Method Not Allowed', desc: '方法不被允许（应返回 Allow 头）' },
  { code: 406, name: 'Not Acceptable', desc: '请求的 Accept 头无法满足内容协商' },
  { code: 408, name: 'Request Timeout', desc: '客户端请求超时' },
  { code: 409, name: 'Conflict', desc: '请求与当前资源状态冲突（并发编辑 / 版本冲突）' },
  { code: 410, name: 'Gone', desc: '资源已永久消失（区别于 404）' },
  { code: 412, name: 'Precondition Failed', desc: '前置条件失败（If-Match / If-None-Match 校验不过）' },
  { code: 413, name: 'Content Too Large', desc: '请求体超过服务器限制' },
  { code: 415, name: 'Unsupported Media Type', desc: 'Content-Type 不支持' },
  { code: 418, name: "I'm a teapot", desc: '愚人节彩蛋：我是茶壶' },
  { code: 422, name: 'Unprocessable Content', desc: '语义正确但校验失败（表单校验常用）' },
  { code: 425, name: 'Too Early', desc: '过早重放（防重放攻击）' },
  { code: 428, name: 'Precondition Required', desc: '要求带条件请求头（防丢失更新）' },
  { code: 429, name: 'Too Many Requests', desc: '请求频率超限（限流，应带 Retry-After 头）' },
  { code: 431, name: 'Request Header Fields Too Large', desc: '请求头过大（Cookie 太多常见）' },
  { code: 451, name: 'Unavailable For Legal Reasons', desc: '因法律原因不可提供（审查）' },
  // 5xx
  { code: 500, name: 'Internal Server Error', desc: '服务器内部错误（后端异常兜底）' },
  { code: 501, name: 'Not Implemented', desc: '服务器不支持该功能' },
  { code: 502, name: 'Bad Gateway', desc: '网关收到上游无效响应（后端挂了 / 崩溃）' },
  { code: 503, name: 'Service Unavailable', desc: '服务不可用（过载 / 维护中，可带 Retry-After）' },
  { code: 504, name: 'Gateway Timeout', desc: '网关等待上游超时（后端太慢）' },
  { code: 505, name: 'HTTP Version Not Supported', desc: 'HTTP 版本不支持' },
  { code: 507, name: 'Insufficient Storage', desc: '存储不足（WebDAV）' },
  { code: 508, name: 'Loop Detected', desc: '检测到无限循环（WebDAV）' },
  { code: 511, name: 'Network Authentication Required', desc: '需要网络认证（公共 Wi-Fi 门户）' }
 ]
 interface MimeDef {
  mime: string
  ext: string
  desc: string
 }
 const MIMES: MimeDef[] = [
  { mime: 'text/html', ext: '.html .htm', desc: 'HTML 文档' },
  { mime: 'text/plain', ext: '.txt', desc: '纯文本' },
  { mime: 'text/css', ext: '.css', desc: '样式表' },
  { mime: 'text/javascript', ext: '.js .mjs', desc: 'JavaScript（旧写法 application/javascript）' },
  { mime: 'application/json', ext: '.json', desc: 'JSON 数据（API 最常用）' },
  { mime: 'application/xml', ext: '.xml', desc: 'XML 数据' },
  { mime: 'application/yaml', ext: '.yaml .yml', desc: 'YAML 配置' },
  { mime: 'application/toml', ext: '.toml', desc: 'TOML 配置' },
  { mime: 'text/csv', ext: '.csv', desc: '逗号分隔表格' },
  { mime: 'text/markdown', ext: '.md', desc: 'Markdown 文档' },
  { mime: 'image/jpeg', ext: '.jpg .jpeg', desc: 'JPEG 图片（有损压缩）' },
  { mime: 'image/png', ext: '.png', desc: 'PNG 图片（无损，支持透明）' },
  { mime: 'image/gif', ext: '.gif', desc: 'GIF 动图' },
  { mime: 'image/webp', ext: '.webp', desc: 'WebP 图片（现代格式，体积小）' },
  { mime: 'image/svg+xml', ext: '.svg', desc: 'SVG 矢量图' },
  { mime: 'image/avif', ext: '.avif', desc: 'AVIF 图片（新一代压缩）' },
  { mime: 'image/x-icon', ext: '.ico', desc: '网站图标' },
  { mime: 'audio/mpeg', ext: '.mp3', desc: 'MP3 音频' },
  { mime: 'audio/ogg', ext: '.ogg', desc: 'OGG 音频' },
  { mime: 'audio/wav', ext: '.wav', desc: 'WAV 无损音频' },
  { mime: 'video/mp4', ext: '.mp4', desc: 'MP4 视频' },
  { mime: 'video/webm', ext: '.webm', desc: 'WebM 视频' },
  { mime: 'video/x-matroska', ext: '.mkv', desc: 'MKV 视频' },
  { mime: 'application/pdf', ext: '.pdf', desc: 'PDF 文档' },
  { mime: 'application/zip', ext: '.zip', desc: 'ZIP 压缩包' },
  { mime: 'application/x-7z-compressed', ext: '.7z', desc: '7z 压缩包' },
  { mime: 'application/x-rar-compressed', ext: '.rar', desc: 'RAR 压缩包' },
  { mime: 'application/gzip', ext: '.gz', desc: 'GZip 压缩' },
  { mime: 'application/x-tar', ext: '.tar', desc: 'TAR 归档' },
  { mime: 'application/octet-stream', ext: '（默认）', desc: '未知二进制（浏览器会下载）' },
  { mime: 'application/wasm', ext: '.wasm', desc: 'WebAssembly 模块' },
  { mime: 'font/woff', ext: '.woff', desc: 'Web 字体（压缩）' },
  { mime: 'font/woff2', ext: '.woff2', desc: 'Web 字体（现代格式）' },
  { mime: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', ext: '.docx', desc: 'Word 文档' },
  { mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', ext: '.xlsx', desc: 'Excel 表格' },
  { mime: 'application/vnd.openxmlformats-officedocument.presentationml.presentation', ext: '.pptx', desc: 'PPT 演示文稿' },
  { mime: 'application/msword', ext: '.doc', desc: 'Word 旧格式' },
  { mime: 'application/vnd.ms-excel', ext: '.xls', desc: 'Excel 旧格式' },
  { mime: 'multipart/form-data', ext: '（表单）', desc: '文件上传表单（带 boundary）' },
  { mime: 'application/x-www-form-urlencoded', ext: '（表单）', desc: 'URL 编码表单（默认）' },
  { mime: 'application/grpc', ext: '（RPC）', desc: 'gRPC 请求（配合 proto）' }
 ]
 const STATUS_CLASS: Record<string, string> = {
  '1xx': 'bg-sky-500/10 text-sky-600 dark:text-sky-400 border-sky-500/30',
  '2xx': 'bg-green-500/10 text-green-600 dark:text-green-400 border-green-500/30',
  '3xx': 'bg-blue-500/10 text-blue-600 dark:text-blue-400 border-blue-500/30',
  '4xx': 'bg-amber-500/10 text-amber-600 dark:text-amber-400 border-amber-500/30',
  '5xx': 'bg-red-500/10 text-red-600 dark:text-red-400 border-red-500/30'
 }
 const statusGroups = computed(() => {
  const q = query.value.trim().toLowerCase()
  const filtered = q
    ? STATUSES.filter(s => String(s.code).includes(q) || s.name.toLowerCase().includes(q) || s.desc.toLowerCase().includes(q))
    : STATUSES
  const groups: Array<{ label: string; class: string; items: StatusDef[] }> = []
  for (const [label, cls] of Object.entries(STATUS_CLASS)) {
    const items = filtered.filter(s => String(s.code).startsWith(label[0]))
    if (items.length > 0) groups.push({ label: `${label} ${label === '1xx' ? '信息' : label === '2xx' ? '成功' : label === '3xx' ? '重定向' : label === '4xx' ? '客户端错误' : '服务器错误'}`, class: cls, items })
  }
  return groups
 })
 const filteredMimes = computed(() => {
  const q = query.value.trim().toLowerCase()
  if (!q) return MIMES
  return MIMES.filter(m => m.mime.includes(q) || m.ext.includes(q) || m.desc.toLowerCase().includes(q))
 })
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <div class="flex items-center gap-3 flex-wrap">
      <Segmented
        v-model="tab"
        :options="[
          { value: 'status', label: 'HTTP 状态码' },
          { value: 'mime', label: 'MIME 类型' }
        ]"
      />
      <div class="relative flex-1 min-w-[160px] max-w-xs">
        <Input v-model="query" placeholder="搜索…" class="h-8 text-sm" />
      </div>
      <span class="text-xs text-muted-foreground ml-auto">
        {{ tab === 'status' ? `${STATUSES.length} 个状态码` : `${MIMES.length} 个常用类型` }}
      </span>
    </div>
    <!-- 状态码 -->
    <template v-if="tab === 'status'">
      <div v-for="group in statusGroups" :key="group.label" class="flex flex-col gap-2">
        <span class="text-xs font-medium text-muted-foreground">{{ group.label }}</span>
        <div class="rounded-md border border-border divide-y divide-border text-xs">
          <div v-for="s in group.items" :key="s.code" class="flex items-start gap-3 px-3 py-2">
            <Badge variant="outline" :class="['py-0 shrink-0 font-mono', group.class]">{{ s.code }}</Badge>
            <div class="flex flex-col gap-0.5 min-w-0">
              <span class="font-medium">{{ s.name }}</span>
              <span class="text-muted-foreground leading-snug">{{ s.desc }}</span>
            </div>
          </div>
        </div>
      </div>
      <p v-if="statusGroups.length === 0" class="text-xs text-muted-foreground">没有匹配的状态码。</p>
    </template>
    <!-- MIME -->
    <template v-else>
      <div class="rounded-md border border-border divide-y divide-border text-xs">
        <div v-for="m in filteredMimes" :key="m.mime" class="flex items-start gap-3 px-3 py-2">
          <span class="font-mono text-primary break-all w-64 shrink-0">{{ m.mime }}</span>
          <span class="font-mono text-muted-foreground w-20 shrink-0">{{ m.ext }}</span>
          <span class="text-muted-foreground min-w-0">{{ m.desc }}</span>
        </div>
        <div v-if="filteredMimes.length === 0" class="px-3 py-2 text-muted-foreground">没有匹配的 MIME 类型。</div>
      </div>
    </template>
  </div>
 </template>
@@ -0,0 +1,189 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import Segmented from '../components/Segmented.vue'
 import ResultArea from '../components/ResultArea.vue'
 type Tab = 'cidr' | 'convert'
 const tab = ref<Tab>('cidr')
 // ===== CIDR 计算 =====
 const cidrInput = ref('192.168.1.0/24')
 function parseIPv4(s: string): bigint | null {
  const parts = s.trim().split('.')
  if (parts.length !== 4) return null
  let n = 0n
  for (const p of parts) {
    if (!/^\d{1,3}$/.test(p)) return null
    const v = Number(p)
    if (v > 255) return null
    n = (n << 8n) | BigInt(v)
  }
  return n
 }
 function ipToString(n: bigint): string {
  return [24n, 16n, 8n, 0n].map(shift => String((n >> shift) & 0xffn)).join('.')
 }
 const cidr = computed(() => {
  const s = cidrInput.value.trim()
  if (!s) return null
  const [ipPart, maskPart] = s.split('/')
  const ip = parseIPv4(ipPart)
  if (ip === null) return { error: 'IPv4 地址格式不正确' }
  let prefix: number
  if (maskPart === undefined) {
    prefix = 24
  } else {
    prefix = Number(maskPart)
    if (!Number.isInteger(prefix) || prefix < 0 || prefix > 32) {
      return { error: '前缀长度应在 0-32 之间' }
    }
  }
  const mask = prefix === 0 ? 0n : (0xffffffffn << BigInt(32 - prefix)) & 0xffffffffn
  const network = ip & mask
  const broadcast = network | (~mask & 0xffffffffn)
  const total = 1n << BigInt(32 - prefix)
  // 主机数：/31 无主机位（点对点），/32 单主机
  const hosts = prefix >= 31 ? total : total - 2n
  const firstHost = prefix >= 31 ? network : network + 1n
  const lastHost = prefix >= 31 ? broadcast : broadcast - 1n
  const wildcard = ~mask & 0xffffffffn
  // 私有地址判断
  const privateNote =
    (ip >> 24n) === 10n ? 'A 类私有（10.0.0.0/8）'
    : (ip >> 20n) === 0xac1n ? 'B 类私有（172.16.0.0/12）'
    : (ip >> 16n) === 0xc0a8n ? 'C 类私有（192.168.0.0/16）'
    : (ip >> 28n) === 14n ? '环回/保留（240.0.0.0/4）'
    : ip === 0n ? '未指定地址'
    : (ip >> 24n) === 127n ? '环回地址（127.0.0.0/8）'
    : (ip >> 24n) === 169n && (ip >> 16n) === 0xa9fen ? '链路本地（169.254.0.0/16）'
    : '公网地址'
  return {
    error: '',
    network: ipToString(network),
    broadcast: ipToString(broadcast),
    mask: ipToString(mask),
    wildcard: ipToString(wildcard),
    firstHost: ipToString(firstHost),
    lastHost: ipToString(lastHost),
    hosts: hosts.toLocaleString(),
    total: total.toLocaleString(),
    prefix,
    isAligned: (ip & mask) === network,
    ipIsNetwork: ip === network,
    privateNote,
    binaryMask: ipToString(mask).split('.').map(p => Number(p).toString(2).padStart(8, '0')).join('.')
  }
 })
 // ===== IP ↔ 整数互转 =====
 const convertInput = ref('192.168.1.1')
 const converted = computed(() => {
  const s = convertInput.value.trim()
  if (!s) return null
  const ip = parseIPv4(s)
  if (ip !== null) {
    return {
      dec: ip.toString(),
      hex: '0x' + ip.toString(16).padStart(8, '0').toUpperCase(),
      oct: ip.toString(8),
      bin: ip.toString(2).padStart(32, '0').replace(/(.{8})(?=.)/g, '$1 '),
      binaryMask: ''
    }
  }
  // 尝试十进制整数
  if (/^\d+$/.test(s)) {
    const n = BigInt(s)
    if (n <= 0xffffffffn) {
      return { dec: s, hex: '0x' + n.toString(16).padStart(8, '0').toUpperCase(), oct: n.toString(8), bin: n.toString(2).padStart(32, '0').replace(/(.{8})(?=.)/g, '$1 '), binaryMask: '' }
    }
  }
  return null
 })
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <Segmented
      v-model="tab"
      :options="[
        { value: 'cidr', label: 'CIDR 子网计算' },
        { value: 'convert', label: 'IP ↔ 整数' }
      ]"
    />
    <!-- CIDR -->
    <template v-if="tab === 'cidr'">
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs">IPv4 地址 / 前缀（如 192.168.1.100/26）</Label>
        <Input v-model="cidrInput" placeholder="192.168.1.0/24" class="font-mono text-sm" />
      </div>
      <template v-if="cidr">
        <p v-if="cidr.error" class="text-xs text-destructive">{{ cidr.error }}</p>
        <template v-else>
          <p v-if="!cidr.ipIsNetwork" class="text-xs text-amber-600 dark:text-amber-400">
            注意：输入地址不是该子网的网络地址，已按网络 {{ cidr.network }}/{{ cidr.prefix }} 计算。
          </p>
          <div class="rounded-md border border-border divide-y divide-border text-xs">
            <div class="flex gap-3 px-3 py-1.5">
              <span class="w-24 shrink-0 text-muted-foreground">网络地址</span>
              <span class="font-mono">{{ cidr.network }}/{{ cidr.prefix }}</span>
            </div>
            <div class="flex gap-3 px-3 py-1.5">
              <span class="w-24 shrink-0 text-muted-foreground">子网掩码</span>
              <span class="font-mono">{{ cidr.mask }}</span>
            </div>
            <div class="flex gap-3 px-3 py-1.5">
              <span class="w-24 shrink-0 text-muted-foreground">掩码二进制</span>
              <span class="font-mono break-all">{{ cidr.binaryMask }}</span>
            </div>
            <div class="flex gap-3 px-3 py-1.5">
              <span class="w-24 shrink-0 text-muted-foreground">反掩码</span>
              <span class="font-mono">{{ cidr.wildcard }}</span>
            </div>
            <div class="flex gap-3 px-3 py-1.5">
              <span class="w-24 shrink-0 text-muted-foreground">广播地址</span>
              <span class="font-mono">{{ cidr.broadcast }}</span>
            </div>
            <div class="flex gap-3 px-3 py-1.5">
              <span class="w-24 shrink-0 text-muted-foreground">可用主机范围</span>
              <span class="font-mono">{{ cidr.firstHost }} ~ {{ cidr.lastHost }}</span>
            </div>
            <div class="flex gap-3 px-3 py-1.5">
              <span class="w-24 shrink-0 text-muted-foreground">可用主机数</span>
              <span class="font-mono">{{ cidr.hosts }}（地址总数 {{ cidr.total }}）</span>
            </div>
            <div class="flex gap-3 px-3 py-1.5">
              <span class="w-24 shrink-0 text-muted-foreground">地址类型</span>
              <span>{{ cidr.privateNote }}</span>
            </div>
          </div>
        </template>
      </template>
      <p v-else class="text-xs text-muted-foreground">输入 IPv4 地址与 CIDR 前缀，自动计算子网信息。</p>
    </template>
    <!-- IP ↔ 整数 -->
    <template v-else>
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs">IP 地址或无符号整数</Label>
        <Input v-model="convertInput" placeholder="192.168.1.1 或 3232235777" class="font-mono text-sm" />
      </div>
      <template v-if="converted">
        <ResultArea :text="converted.dec" label="十进制整数" placeholder="十进制" minHeight="60px" />
        <ResultArea :text="converted.hex" label="十六进制" placeholder="十六进制" minHeight="60px" />
        <ResultArea :text="converted.oct" label="八进制" placeholder="八进制" minHeight="60px" />
        <ResultArea :text="converted.bin" label="二进制" placeholder="二进制" minHeight="60px" />
      </template>
      <p v-else-if="convertInput" class="text-xs text-destructive">无法识别的输入（支持 IPv4 地址或 0-4294967295 整数）。</p>
    </template>
  </div>
 </template>
@@ -0,0 +1,96 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { Textarea } from '@/components/ui/textarea'
 import { Label } from '@/components/ui/label'
 import Segmented from '../components/Segmented.vue'
 import ResultArea from '../components/ResultArea.vue'
 const mode = ref<'format' | 'minify'>('format')
 const indent = ref('2')
 const sortKeys = ref(false)
 const input = ref('')
 const result = computed<{ text: string; error: string }>(() => {
  const v = input.value.trim()
  if (!v) return { text: '', error: '' }
  try {
    const parsed = JSON.parse(v)
    if (mode.value === 'minify') {
      return { text: JSON.stringify(parsed), error: '' }
    }
    return { text: JSON.stringify(parsed, normalizeReplacer(sortKeys.value), Number(indent.value)), error: '' }
  } catch (e) {
    return { text: '', error: 'JSON 解析失败：' + String(e) }
  }
 })
 const output = computed(() => result.value.text)
 const error = computed(() => result.value.error)
 const isValid = computed<boolean | null>(() => {
  if (!input.value.trim()) return null
  try {
    JSON.parse(input.value)
    return true
  } catch {
    return false
  }
 })
 /** 深浅不一：sortKeys 时按 key 排序输出 */
 function normalizeReplacer(sort: boolean): (this: unknown, key: string, value: unknown) => unknown {
  if (!sort) return undefined as never
  return function (this: unknown, _key: string, value: unknown) {
    if (Array.isArray(value)) return value
    if (value && typeof value === 'object') {
      const obj = value as Record<string, unknown>
      const sorted: Record<string, unknown> = {}
      Object.keys(obj)
        .sort()
        .forEach(k => { sorted[k] = obj[k] })
      return sorted
    }
    return value
  }
 }
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <div class="flex items-center justify-between flex-wrap gap-3">
      <div class="flex items-center gap-3 flex-wrap">
        <Segmented
          v-model="mode"
          :options="[
            { value: 'format', label: '美化' },
            { value: 'minify', label: '压缩' }
          ]"
        />
        <Segmented
          v-model="indent"
          label="缩进"
          :options="[
            { value: '2', label: '2' },
            { value: '4', label: '4' },
            { value: '8', label: '8' }
          ]"
        />
        <label class="flex items-center gap-1.5 text-xs text-muted-foreground cursor-pointer">
          <input v-model="sortKeys" type="checkbox" class="accent-primary size-3.5" />
          键排序
        </label>
      </div>
    </div>
    <div class="flex flex-col gap-1.5">
      <Label class="text-xs">原始 JSON</Label>
      <Textarea v-model="input" placeholder='输入 JSON，如 {"a":1,"b":[true,null]}' class="min-h-[160px] font-mono text-xs resize-y" />
    </div>
    <div v-if="isValid !== false" class="flex items-center gap-2 text-xs">
      <span v-if="isValid === true" class="text-green-600 dark:text-green-400">✓ 合法 JSON</span>
    </div>
    <ResultArea :text="output" placeholder="结果" />
    <p v-if="error" class="text-xs text-destructive break-all">{{ error }}</p>
  </div>
 </template>
@@ -0,0 +1,131 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { Textarea } from '@/components/ui/textarea'
 import { Label } from '@/components/ui/label'
 import { Badge } from '@/components/ui/badge'
 import ResultArea from '../components/ResultArea.vue'
 const token = ref('')
 const error = ref('')
 function base64UrlDecode(s: string): string {
  const cleaned = s.replace(/-/g, '+').replace(/_/g, '/')
  const pad = cleaned.length % 4
  const normalized = pad ? cleaned + '='.repeat(4 - pad) : cleaned
  const bin = atob(normalized)
  const bytes = Uint8Array.from(bin, ch => ch.charCodeAt(0))
  return new TextDecoder().decode(bytes)
 }
 interface TimeClaim {
  name: string
  value: string
  local: string
  status: 'ok' | 'expired' | 'not-yet' | 'unknown'
 }
 const parsed = computed<{
  header: string
  payload: string
  signature: string
  timeClaims: TimeClaim[]
 } | null>(() => {
  error.value = ''
  const t = token.value.trim()
  if (!t) return null
  const parts = t.split('.')
  if (parts.length < 2) {
    error.value = 'JWT 格式不正确（应为 header.payload.signature）'
    return null
  }
  try {
    const header = formatJson(base64UrlDecode(parts[0]))
    const payload = formatJson(base64UrlDecode(parts[1]))
    const signature = parts[2] ?? ''
    return { header, payload, signature, timeClaims: parseTimeClaims(payload) }
  } catch (e) {
    error.value = '解码失败：' + String(e)
    return null
  }
 })
 function formatJson(s: string): string {
  let pretty = s
  try {
    pretty = JSON.stringify(JSON.parse(s), null, 2)
  } catch {
    /* 非 JSON（如已损毁），原样展示 */
  }
  return pretty
 }
 /** 解读 iat / nbf / exp 等时间声明（秒级时间戳） */
 function parseTimeClaims(payload: string): TimeClaim[] {
  let obj: unknown
  try {
    obj = JSON.parse(payload)
  } catch {
    return []
  }
  if (!obj || typeof obj !== 'object') return []
  const p = obj as Record<string, unknown>
  const claims: TimeClaim[] = []
  const now = Math.floor(Date.now() / 1000)
  const NAMES: Record<string, string> = { iat: 'iat（签发时间）', nbf: 'nbf（生效时间）', exp: 'exp（过期时间）' }
  const pad = (x: number) => String(x).padStart(2, '0')
  for (const key of ['iat', 'nbf', 'exp']) {
    const v = p[key]
    if (typeof v !== 'number' || !Number.isFinite(v)) continue
    const d = new Date(v * 1000)
    if (Number.isNaN(d.getTime())) continue
    const local = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
    let status: TimeClaim['status'] = 'ok'
    if (key === 'exp' && v < now) status = 'expired'
    else if (key === 'nbf' && v > now) status = 'not-yet'
    else if (key === 'iat' && v > now + 60) status = 'unknown'
    claims.push({ name: NAMES[key], value: String(v), local, status })
  }
  return claims
 }
 const STATUS_BADGE: Record<TimeClaim['status'], { label: string; class: string } | null> = {
  ok: null,
  expired: { label: '已过期', class: 'bg-red-500/10 text-red-600 dark:text-red-400 border-red-500/30' },
  'not-yet': { label: '尚未生效', class: 'bg-amber-500/10 text-amber-600 dark:text-amber-400 border-amber-500/30' },
  unknown: { label: '签发时间在未来（时钟偏差？）', class: 'bg-amber-500/10 text-amber-600 dark:text-amber-400 border-amber-500/30' }
 }
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <div class="flex flex-col gap-1.5">
      <Label class="text-xs">JWT Token</Label>
      <Textarea
        v-model="token"
        placeholder="eyJhbGciOi...（header.payload.signature）"
        class="min-h-[70px] font-mono text-xs resize-y break-all"
      />
    </div>
    <template v-if="parsed">
      <ResultArea :text="parsed.header" label="Header" placeholder="Header" />
      <ResultArea :text="parsed.payload" label="Payload（载荷）" placeholder="Payload" />
      <ResultArea :text="parsed.signature" label="Signature（签名）" placeholder="Signature" />
      <div v-if="parsed.timeClaims.length > 0" class="flex flex-col gap-1.5">
        <Label class="text-xs">时间声明解读</Label>
        <div class="rounded-md border border-border divide-y divide-border text-xs">
          <div v-for="c in parsed.timeClaims" :key="c.name" class="flex items-center gap-3 px-3 py-2 flex-wrap">
            <span class="font-mono text-muted-foreground">{{ c.name }}</span>
            <span class="font-mono">{{ c.local }}</span>
            <Badge v-if="STATUS_BADGE[c.status]" variant="outline" :class="['py-0 text-[10px] ml-auto', STATUS_BADGE[c.status]!.class]">
              {{ STATUS_BADGE[c.status]!.label }}
            </Badge>
          </div>
        </div>
      </div>
    </template>
    <p v-else-if="!token" class="text-xs text-muted-foreground">在左侧粘贴 JWT，下方将自动解析 Header 与 Payload。</p>
    <p v-else class="text-xs text-destructive">{{ error }}</p>
  </div>
 </template>
@@ -0,0 +1,165 @@
 <script setup lang="ts">
 import { computed, onMounted, ref } from 'vue'
 import { Copy, RefreshCw } from '@lucide/vue'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { Button } from '@/components/ui/button'
 import { Switch } from '@/components/ui/switch'
 import { Textarea } from '@/components/ui/textarea'
 const CHARSETS = {
  lower: 'abcdefghijklmnopqrstuvwxyz',
  upper: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ',
  digits: '0123456789',
  symbols: '!@#$%^&*_-+=?',
  // 易混淆字符：l/1/I、O/0、等等
  ambiguous: 'Il1O0o`\'"|'
 }
 const length = ref('16')
 const count = ref('5')
 const useLower = ref(true)
 const useUpper = ref(true)
 const useDigits = ref(true)
 const useSymbols = ref(false)
 const excludeAmbiguous = ref(true)
 const passwords = ref<string[]>([])
 const error = ref('')
 const lengthNum = computed(() => {
  const n = Math.floor(Number(length.value))
  if (!Number.isFinite(n)) return 16
  return Math.min(Math.max(n || 0, 4), 128)
 })
 const countNum = computed(() => {
  const n = Math.floor(Number(count.value))
  if (!Number.isFinite(n)) return 5
  return Math.min(Math.max(n || 0, 1), 100)
 })
 const charset = computed(() => {
  let s = ''
  if (useLower.value) s += CHARSETS.lower
  if (useUpper.value) s += CHARSETS.upper
  if (useDigits.value) s += CHARSETS.digits
  if (useSymbols.value) s += CHARSETS.symbols
  if (excludeAmbiguous.value) {
    for (const c of CHARSETS.ambiguous) s = s.split(c).join('')
  }
  return s
 })
 /** 用 crypto.getRandomValues 生成无偏随机整数 [0, max) */
 function randomInt(max: number): number {
  // 拒绝采样消除模偏差
  const limit = Math.floor(0x100000000 / max) * max
  const buf = new Uint32Array(1)
  let v: number
  do {
    crypto.getRandomValues(buf)
    v = buf[0]
  } while (v >= limit)
  return v % max
 }
 /** 熵估算：log2(charsetSize^length) = length * log2(size) */
 const entropy = computed(() => {
  const size = charset.value.length
  if (size === 0) return 0
  return Math.round(lengthNum.value * Math.log2(size))
 })
 const strength = computed(() => {
  const e = entropy.value
  if (e >= 128) return { label: '极强（128+ bit）', class: 'text-green-600 dark:text-green-400' }
  if (e >= 80) return { label: '强（80-127 bit）', class: 'text-green-600 dark:text-green-400' }
  if (e >= 60) return { label: '中等（60-79 bit）', class: 'text-amber-600 dark:text-amber-400' }
  return { label: '弱（<60 bit）', class: 'text-red-600 dark:text-red-400' }
 })
 function generate() {
  error.value = ''
  if (charset.value.length === 0) {
    error.value = '请至少选择一种字符集'
    passwords.value = []
    return
  }
  const list: string[] = []
  for (let i = 0; i < countNum.value; i++) {
    let pw = ''
    for (let j = 0; j < lengthNum.value; j++) {
      pw += charset.value[randomInt(charset.value.length)]
    }
    list.push(pw)
  }
  passwords.value = list
 }
 const allText = computed(() => passwords.value.join('\n'))
 function copyAll() {
  void navigator.clipboard.writeText(allText.value)
 }
 onMounted(generate)
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <div class="flex items-center gap-6 flex-wrap">
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs">长度（4-128）</Label>
        <Input v-model="length" type="number" min="4" max="128" class="w-24 font-mono text-sm" />
      </div>
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs">数量（1-100）</Label>
        <Input v-model="count" type="number" min="1" max="100" class="w-24 font-mono text-sm" />
      </div>
      <Button size="sm" class="gap-1 self-end" @click="generate">
        <RefreshCw class="size-3.5" />
        重新生成
      </Button>
    </div>
    <div class="flex items-center gap-4 flex-wrap">
      <label class="flex items-center gap-2 text-xs cursor-pointer">
        <Switch v-model="useLower" /> 小写 a-z
      </label>
      <label class="flex items-center gap-2 text-xs cursor-pointer">
        <Switch v-model="useUpper" /> 大写 A-Z
      </label>
      <label class="flex items-center gap-2 text-xs cursor-pointer">
        <Switch v-model="useDigits" /> 数字 0-9
      </label>
      <label class="flex items-center gap-2 text-xs cursor-pointer">
        <Switch v-model="useSymbols" /> 符号 !@#$%
      </label>
      <label class="flex items-center gap-2 text-xs cursor-pointer">
        <Switch v-model="excludeAmbiguous" /> 排除易混淆字符
      </label>
    </div>
    <p v-if="error" class="text-xs text-destructive">{{ error }}</p>
    <template v-if="passwords.length">
      <div class="flex flex-col gap-1.5">
        <div class="flex items-center justify-between">
          <Label class="text-xs">生成结果</Label>
          <span class="text-xs" :class="strength.class">熵约 {{ entropy }} bit · {{ strength.label }}</span>
        </div>
        <Textarea
          readonly
          :model-value="allText"
          class="min-h-[120px] font-mono text-xs resize-y"
        />
      </div>
      <Button size="sm" variant="outline" class="gap-1 w-fit" @click="copyAll">
        <Copy class="size-3.5" />
        复制全部（{{ passwords.length }} 个）
      </Button>
    </template>
  </div>
 </template>
@@ -0,0 +1,192 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { Textarea } from '@/components/ui/textarea'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { Badge } from '@/components/ui/badge'
 import ResultArea from '../components/ResultArea.vue'
 const pattern = ref('')
 const testText = ref('')
 const flags = ref({ g: true, i: false, m: false, s: false, u: false })
 interface MatchInfo {
  index: number
  full: string
  groups: string[]
  groupsLabel: string
 }
 const raw = computed<{ matches: MatchInfo[]; error: string }>(() => {
  if (!pattern.value) return { matches: [], error: '' }
  // 防卡 UI：同步 exec 无超时保护，超长文本截断测试（灾难性回溯正则仍可能慢，限制输入规模是主要防线）
  const MAX_TEXT = 200_000
  const text = testText.value.length > MAX_TEXT ? testText.value.slice(0, MAX_TEXT) : testText.value
  const truncated = testText.value.length > MAX_TEXT
  let fl = ''
  const f = flags.value
  if (f.g) fl += 'g'
  if (f.i) fl += 'i'
  if (f.m) fl += 'm'
  if (f.s) fl += 's'
  if (f.u) fl += 'u'
  try {
    const re = new RegExp(pattern.value, fl)
    const list: MatchInfo[] = []
    let m: RegExpExecArray | null
    let guard = 0
    while ((m = re.exec(text)) !== null) {
      const groups = m.slice(1)
      list.push({
        index: m.index,
        full: m[0],
        groups,
        groupsLabel: groups && groups.length > 0
          ? groups.map((g, i) => `$${i + 1}=${g === undefined ? '∅' : g}`).join(', ')
          : ''
      })
      if (!f.g) break
      if (list.length >= 5000) break // 匹配数上限，防止大文本 + 极宽正则刷爆列表
      if (m[0] === '') {
        if (++guard > 100000) break
        re.lastIndex++
      }
    }
    if (list.length >= 5000) {
      const extra = truncated ? `（文本超过 ${MAX_TEXT} 字符，仅测试前 ${MAX_TEXT} 字符）` : ''
      return { matches: list, error: `匹配数已达 5000 上限，已停止${extra}` }
    }
    return { matches: list, error: '' }
  } catch (e) {
    return { matches: [], error: '正则语法错误：' + String(e) }
  }
 })
 const matches = computed(() => raw.value.matches)
 const error = computed(() => raw.value.error)
 const isValidPattern = computed(() => {
  if (!pattern.value) return null
  try {
    new RegExp(pattern.value, flags.value.g ? 'g' : '')
    return true
  } catch {
    return false
  }
 })
 const matchesText = computed(() => {
  if (matches.value.length === 0) return ''
  return matches.value
    .map((m, i) => `[${i}] @${m.index}: ${m.full}` + (m.groupsLabel ? `  (${m.groupsLabel})` : ''))
    .join('\n')
 })
 const flagDefs = [
  { key: 'g' as const, label: 'g', title: '全局' },
  { key: 'i' as const, label: 'i', title: '忽略大小写' },
  { key: 'm' as const, label: 'm', title: '多行' },
  { key: 's' as const, label: 's', title: '点匹配换行' },
  { key: 'u' as const, label: 'u', title: 'Unicode' }
 ]
 // ===== 替换预览 =====
 const showReplace = ref(false)
 const replacement = ref('')
 const replaceError = computed(() => {
  if (!showReplace.value || !pattern.value) return ''
  try {
    new RegExp(pattern.value, flags.value.g ? 'g' : '')
    return ''
  } catch (e) {
    return '正则语法错误：' + String(e)
  }
 })
 const replacedText = computed<{ text: string; count: number }>(() => {
  if (!showReplace.value || !pattern.value || !testText.value) return { text: '', count: 0 }
  const text = testText.value.length > 200_000 ? testText.value.slice(0, 200_000) : testText.value
  try {
    const fl = (flags.value.g ? 'g' : '') + (flags.value.i ? 'i' : '') + (flags.value.m ? 'm' : '') + (flags.value.s ? 's' : '') + (flags.value.u ? 'u' : '')
    const re = new RegExp(pattern.value, fl)
    const all = (text.match(new RegExp(pattern.value, fl.includes('g') ? fl : fl + 'g')) ?? []).length
    return { text: text.replace(re, replacement.value), count: flags.value.g ? all : Math.min(all, 1) }
  } catch {
    return { text: '', count: 0 }
  }
 })
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <div class="flex flex-col gap-1.5">
      <Label class="text-xs">正则表达式</Label>
      <div class="flex items-center gap-2">
        <span class="text-muted-foreground font-mono text-sm">/</span>
        <Input v-model="pattern" placeholder="如 \b\w+@\w+\.\w+\b" class="font-mono text-sm flex-1" :class="{ 'border-destructive': isValidPattern === false }" />
        <span class="text-muted-foreground font-mono text-sm">/</span>
      </div>
      <div class="flex items-center gap-1 flex-wrap">
        <button
          v-for="fd in flagDefs"
          :key="fd.key"
          type="button"
          class="h-6 px-2 rounded font-mono text-xs border transition-colors cursor-pointer"
          :class="flags[fd.key] ? 'border-primary text-primary bg-primary/10' : 'border-border text-muted-foreground hover:text-foreground'"
          :title="fd.title"
          @click="flags[fd.key] = !flags[fd.key]"
        >
          {{ fd.label }}
        </button>
        <span v-if="matches.length" class="ml-auto text-xs text-muted-foreground">匹配 {{ matches.length }} 处</span>
        <span v-else-if="pattern && testText && !error" class="ml-auto text-xs text-muted-foreground">无匹配</span>
      </div>
    </div>
    <div class="flex flex-col gap-1.5">
      <Label class="text-xs">测试文本</Label>
      <Textarea v-model="testText" placeholder="在此输入文本..." class="min-h-[120px] font-mono text-xs resize-y" />
    </div>
    <div class="flex flex-col gap-1.5">
      <Label class="text-xs">匹配结果</Label>
      <div class="rounded-md border border-border max-h-56 overflow-y-auto divide-y divide-border">
        <div v-if="matches.length === 0 && !error" class="p-3 text-xs text-muted-foreground">输入正则与文本查看匹配。</div>
        <div v-for="(m, i) in matches" :key="i" class="flex items-start gap-2 p-2 text-xs font-mono">
          <Badge variant="outline" class="shrink-0 py-0 px-1.5 text-[10px]">@{{ m.index }}</Badge>
          <span class="break-all min-w-0">{{ m.full }}</span>
          <span v-if="m.groupsLabel" class="text-muted-foreground break-all ml-auto pl-2">{{ m.groupsLabel }}</span>
        </div>
      </div>
    </div>
    <ResultArea :text="matchesText" label="匹配列表（可复制）" placeholder="匹配列表" />
    <!-- 替换预览 -->
    <div class="rounded-md border border-border">
      <button
        type="button"
        class="w-full flex items-center justify-between px-3 py-2 text-xs font-medium cursor-pointer hover:bg-muted/40 transition-colors"
        @click="showReplace = !showReplace"
      >
        <span>替换预览（支持 $1、$&lt;name&gt; 引用分组）</span>
        <span class="text-muted-foreground">{{ showReplace ? '收起' : '展开' }}</span>
      </button>
      <div v-if="showReplace" class="flex flex-col gap-3 p-3 border-t border-border">
        <div class="flex flex-col gap-1.5">
          <Label class="text-xs">替换为</Label>
          <Input v-model="replacement" placeholder="如 [$1]（留空则删除匹配内容）" class="font-mono text-sm" />
        </div>
        <ResultArea
          v-if="replacedText.text"
          :text="replacedText.text"
          :label="`替换结果（已替换 ${replacedText.count} 处）`"
          placeholder="替换结果"
        />
        <p v-else-if="replacement" class="text-xs text-muted-foreground">替换后无内容或无匹配。</p>
        <p v-if="replaceError" class="text-xs text-destructive">{{ replaceError }}</p>
      </div>
    </div>
    <p v-if="error" class="text-xs text-destructive">{{ error }}</p>
  </div>
 </template>
@@ -0,0 +1,82 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { Textarea } from '@/components/ui/textarea'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { Switch } from '@/components/ui/switch'
 import ResultArea from '../components/ResultArea.vue'
 const input = ref('')
 const find = ref('')
 const replacement = ref('')
 const useRegex = ref(false)
 const caseInsensitive = ref(false)
 const multiline = ref(false)
 const result = computed<{ text: string; count: number; error: string }>(() => {
  const v = input.value
  if (!v || !find.value) return { text: '', count: 0, error: '' }
  try {
    let re: RegExp
    let replacementText: string
    if (useRegex.value) {
      const flags = 'g' + (caseInsensitive.value ? 'i' : '') + (multiline.value ? 'm' : '')
      re = new RegExp(find.value, flags)
      // 正则模式：原生支持 $1、$<name> 等引用
      replacementText = replacement.value
    } else {
      // 纯文本模式：查找与替换都按字面处理，需转义正则元字符与替换串中的 $
      const esc = find.value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
      re = new RegExp(esc, 'g' + (caseInsensitive.value ? 'i' : ''))
      replacementText = replacement.value.replace(/\$/g, '$$$$')
    }
    const count = (v.match(re) ?? []).length
    return { text: v.replace(re, replacementText), count, error: '' }
  } catch (e) {
    return { text: '', count: 0, error: '正则语法错误：' + String(e) }
  }
 })
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <div class="flex flex-col gap-1.5">
      <Label class="text-xs">原文</Label>
      <Textarea v-model="input" placeholder="在此输入文本..." class="min-h-[140px] font-mono text-xs resize-y" />
    </div>
    <div class="grid grid-cols-2 gap-3">
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs">查找</Label>
        <Input v-model="find" :placeholder="useRegex ? '正则表达式' : '纯文本'" class="font-mono text-sm" />
      </div>
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs">替换为（留空删除匹配）</Label>
        <Input v-model="replacement" :placeholder="useRegex ? '支持 $1、$<name>' : '纯文本'" class="font-mono text-sm" />
      </div>
    </div>
    <div class="flex items-center gap-4 flex-wrap">
      <label class="flex items-center gap-2 text-xs cursor-pointer">
        <Switch v-model="useRegex" /> 正则模式
      </label>
      <label class="flex items-center gap-2 text-xs cursor-pointer">
        <Switch v-model="caseInsensitive" /> 忽略大小写
      </label>
      <label class="flex items-center gap-2 text-xs cursor-pointer" :class="{ 'opacity-50': !useRegex }">
        <Switch v-model="multiline" :disabled="!useRegex" /> 多行模式（^$ 匹配行首尾）
      </label>
    </div>
    <p v-if="result.error" class="text-xs text-destructive">{{ result.error }}</p>
    <ResultArea
      v-if="result.text"
      :text="result.text"
      :label="`替换结果（已替换 ${result.count} 处）`"
      placeholder="替换结果"
    />
    <p v-else-if="input && find" class="text-xs text-muted-foreground">无匹配或替换后为空。</p>
    <p v-else class="text-xs text-muted-foreground">输入原文与查找内容，实时预览替换结果。</p>
  </div>
 </template>
@@ -0,0 +1,138 @@
 <script setup lang="ts">
 import { computed, onUnmounted, ref } from 'vue'
 import { Clock } from '@lucide/vue'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { Button } from '@/components/ui/button'
 import { Separator } from '@/components/ui/separator'
 import Segmented from '../components/Segmented.vue'
 import ResultArea from '../components/ResultArea.vue'
 type Unit = 'auto' | 's' | 'ms'
 const unit = ref<Unit>('auto')
 const numberInput = ref('')
 const dateInput = ref('')
 const toNumber = (v: string): number | null => {
  const n = Number(v.trim())
  return Number.isFinite(n) ? n : null
 }
 /** 自动识别：13 位（>1e11）视为毫秒，10 位（>1e8）视为秒，其他按数值范围推断 */
 function resolveUnit(n: number): 's' | 'ms' {
  if (unit.value !== 'auto') return unit.value
  if (Math.abs(n) >= 1e11) return 'ms'
  return 's'
 }
 const unixToDate = (n: number, u: 's' | 'ms'): Date =>
  new Date(u === 's' ? n * 1000 : n)
 const formatLocal = (d: Date): string => {
  const pad = (x: number) => String(x).padStart(2, '0')
  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
 }
 const formatUtc = (d: Date): string => {
  const pad = (x: number) => String(x).padStart(2, '0')
  return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())} UTC`
 }
 const fromNumber = computed<{ local: string; utc: string; iso: string; ts: string; unitUsed: 's' | 'ms' } | null>(() => {
  const n = toNumber(numberInput.value)
  if (n === null) return null
  const u = resolveUnit(n)
  const d = unixToDate(n, u)
  if (Number.isNaN(d.getTime())) return null
  return {
    local: formatLocal(d),
    utc: formatUtc(d),
    iso: d.toISOString(),
    ts: String(n),
    unitUsed: u
  }
 })
 const fromDate = computed<string>(() => {
  if (!dateInput.value) return ''
  const d = new Date(dateInput.value)
  if (Number.isNaN(d.getTime())) return ''
  // 日期输入统一同时给出秒与毫秒
  return `${Math.floor(d.getTime() / 1000)}（秒）\n${d.getTime()}（毫秒）`
 })
 // ===== 当前时间戳 =====
 const nowTick = ref(0)
 const timer = window.setInterval(() => (nowTick.value++), 1000)
 onUnmounted(() => window.clearInterval(timer))
 const now = computed(() => {
  void nowTick.value
  const d = new Date()
  return {
    s: String(Math.floor(d.getTime() / 1000)),
    ms: String(d.getTime()),
    local: formatLocal(d)
  }
 })
 function copy(text: string) {
  void navigator.clipboard.writeText(text)
 }
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <Segmented
      v-model="unit"
      label="单位"
      :options="[
        { value: 'auto', label: '自动' },
        { value: 's', label: '秒' },
        { value: 'ms', label: '毫秒' }
      ]"
    />
    <!-- 时间戳 → 时间 -->
    <div class="flex flex-col gap-3">
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs">Unix 时间戳 → 日期时间</Label>
        <Input v-model="numberInput" placeholder="例如 1757419200 或 1757419200000" class="font-mono text-sm" />
      </div>
      <template v-if="fromNumber">
        <ResultArea :text="fromNumber.local" label="本地时间" placeholder="本地时间" />
        <ResultArea :text="fromNumber.utc" label="UTC 时间" placeholder="UTC 时间" />
        <ResultArea :text="fromNumber.iso" label="ISO 8601" placeholder="ISO 8601" />
        <p class="text-xs text-muted-foreground">已识别为{{ fromNumber.unitUsed === 's' ? '秒级' : '毫秒级' }}时间戳</p>
      </template>
      <p v-else-if="numberInput" class="text-xs text-destructive">请输入有效的数字时间戳</p>
    </div>
    <Separator />
    <!-- 时间 → 时间戳 -->
    <div class="flex flex-col gap-1.5">
      <Label class="text-xs">日期时间 → Unix 时间戳</Label>
      <Input v-model="dateInput" type="datetime-local" class="font-mono text-sm" />
      <ResultArea v-if="fromDate" :text="fromDate" label="结果" placeholder="结果" />
    </div>
    <Separator />
    <!-- 当前时间戳 -->
    <div class="flex flex-col gap-2">
      <Label class="text-xs">当前时间（{{ now.local }}）</Label>
      <div class="flex items-center gap-2 flex-wrap">
        <Button size="sm" variant="outline" class="h-8 font-mono text-xs gap-1.5" @click="copy(now.s)">
          <Clock class="size-3.5" />
          {{ now.s }}（秒，点击复制）
        </Button>
        <Button size="sm" variant="outline" class="h-8 font-mono text-xs gap-1.5" @click="copy(now.ms)">
          <Clock class="size-3.5" />
          {{ now.ms }}（毫秒，点击复制）
        </Button>
      </div>
    </div>
  </div>
 </template>
@@ -0,0 +1,187 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { ArrowDownUp } from '@lucide/vue'
 import { Textarea } from '@/components/ui/textarea'
 import { Label } from '@/components/ui/label'
 import { Button } from '@/components/ui/button'
 import { Switch } from '@/components/ui/switch'
 import Segmented from '../components/Segmented.vue'
 import ResultArea from '../components/ResultArea.vue'
 type Tab = 'convert' | 'parse'
 const tab = ref<Tab>('convert')
 const mode = ref<'encode' | 'decode'>('encode')
 const usePlus = ref(false)
 const input = ref('')
 // ===== 编解码 =====
 const output = computed<{ text: string; error: string }>(() => {
  const v = input.value
  if (!v) return { text: '', error: '' }
  if (mode.value === 'encode') {
    const enc = encodeURIComponent(v)
    return { text: usePlus.value ? enc.replace(/%20/g, '+') : enc, error: '' }
  }
  // decode：先处理 + 与 %20 两种形式
  const normalized = usePlus.value ? v.replace(/\+/g, ' ') : v
  try {
    return { text: decodeURIComponent(normalized), error: '' }
  } catch (e) {
    return { text: '', error: '解码失败（存在非法百分号序列）：' + String(e) }
  }
 })
 const swap = () => {
  if (output.value.text) {
    input.value = output.value.text
    mode.value = mode.value === 'encode' ? 'decode' : 'encode'
  }
 }
 // ===== URL 解析 =====
 const parseInput = ref('https://user:pass@example.com:8080/path/to/page?a=1&b=hello%20world&c=3#section')
 interface ParsedUrl {
  href: string
  protocol: string
  username: string
  password: string
  host: string
  hostname: string
  port: string
  pathname: string
  search: string
  hash: string
  origin: string
  params: Array<[string, string]>
  paramError: string
 }
 const parsedUrl = computed<{ url: ParsedUrl | null; error: string }>(() => {
  const v = parseInput.value.trim()
  if (!v) return { url: null, error: '' }
  let u: URL
  try {
    u = new URL(v)
  } catch {
    // 无协议时尝试补 http:// 再解析
    try {
      u = new URL('http://' + v)
    } catch (e) {
      return { url: null, error: 'URL 解析失败：' + String(e) }
    }
  }
  const params: Array<[string, string]> = []
  let paramError = ''
  try {
    u.searchParams.forEach((value, key) => params.push([key, value]))
  } catch (e) {
    paramError = String(e)
  }
  return {
    url: {
      href: u.href,
      protocol: u.protocol,
      username: u.username,
      password: u.password,
      host: u.host,
      hostname: u.hostname,
      port: u.port,
      pathname: u.pathname,
      search: u.search,
      hash: u.hash,
      origin: u.origin,
      params,
      paramError
    },
    error: ''
  }
 })
 const FIELDS: Array<{ key: keyof ParsedUrl; label: string }> = [
  { key: 'protocol', label: '协议' },
  { key: 'username', label: '用户名' },
  { key: 'password', label: '密码' },
  { key: 'hostname', label: '主机名' },
  { key: 'port', label: '端口' },
  { key: 'pathname', label: '路径' },
  { key: 'search', label: '查询串' },
  { key: 'hash', label: '锚点' },
  { key: 'origin', label: 'Origin' }
 ]
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <Segmented
      v-model="tab"
      :options="[
        { value: 'convert', label: '编解码' },
        { value: 'parse', label: 'URL 解析' }
      ]"
    />
    <!-- 编解码 -->
    <template v-if="tab === 'convert'">
      <div class="flex items-center justify-between flex-wrap gap-3">
        <Segmented
          v-model="mode"
          label="操作"
          :options="[
            { value: 'encode', label: '编码' },
            { value: 'decode', label: '解码' }
          ]"
        />
        <label class="flex items-center gap-2 text-xs text-muted-foreground cursor-pointer">
          空格用
          <Switch v-model="usePlus" />
          <span class="font-mono">{{ usePlus ? '+(表单)' : '%20' }}</span>
        </label>
        <Button size="sm" variant="outline" class="h-8 text-sm gap-1" :disabled="!output.text" @click="swap">
          <ArrowDownUp class="size-3.5" />
          结果回填
        </Button>
      </div>
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs">{{ mode === 'encode' ? '待编码文本' : '待解码字符串' }}</Label>
        <Textarea v-model="input" placeholder="在此输入..." class="min-h-[120px] font-mono text-xs resize-y" />
      </div>
      <ResultArea :text="output.text" placeholder="结果" />
      <p v-if="output.error" class="text-xs text-destructive">{{ output.error }}</p>
    </template>
    <!-- URL 解析 -->
    <template v-else>
      <div class="flex flex-col gap-1.5">
        <Label class="text-xs">URL</Label>
        <Textarea v-model="parseInput" placeholder="https://example.com/path?a=1#hash" class="min-h-[70px] font-mono text-xs resize-y" />
      </div>
      <template v-if="parsedUrl.url">
        <div class="rounded-md border border-border divide-y divide-border text-xs">
          <div v-for="f in FIELDS" :key="f.key" class="flex gap-3 px-3 py-1.5">
            <span class="w-16 shrink-0 text-muted-foreground">{{ f.label }}</span>
            <span class="font-mono break-all">{{ (parsedUrl.url[f.key] as string) || '—' }}</span>
          </div>
        </div>
        <div v-if="parsedUrl.url.params.length > 0" class="flex flex-col gap-1.5">
          <Label class="text-xs">查询参数（{{ parsedUrl.url.params.length }} 个）</Label>
          <div class="rounded-md border border-border divide-y divide-border text-xs">
            <div v-for="([k, v], i) in parsedUrl.url.params" :key="i" class="flex gap-3 px-3 py-1.5">
              <span class="font-mono text-primary break-all">{{ k }}</span>
              <span class="font-mono break-all">{{ v }}</span>
            </div>
          </div>
        </div>
        <p v-if="parsedUrl.url.paramError" class="text-xs text-destructive">{{ parsedUrl.url.paramError }}</p>
        <p v-else-if="parsedUrl.url.params.length === 0" class="text-xs text-muted-foreground">无查询参数。</p>
      </template>
      <p v-else-if="!parseInput" class="text-xs text-muted-foreground">输入 URL 查看解析结果。</p>
      <p v-else class="text-xs text-destructive">{{ parsedUrl.error }}</p>
    </template>
  </div>
 </template>
@@ -0,0 +1,121 @@
 <script setup lang="ts">
 import { computed, onMounted, ref, watch } from 'vue'
 import { RefreshCw, Copy } from '@lucide/vue'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { Button } from '@/components/ui/button'
 import { Switch } from '@/components/ui/switch'
 import Segmented from '../components/Segmented.vue'
 import ResultArea from '../components/ResultArea.vue'
 const count = ref('5')
 const version = ref<'v4' | 'v7'>('v4')
 const uppercase = ref(false)
 const noDashes = ref(false)
 // 原始随机 UUID 与格式化后的展示
 const baseUuids = ref<string[]>([])
 const batchCount = computed(() => {
  const n = Math.floor(Number(count.value))
  if (!Number.isFinite(n)) return 5
  return Math.min(Math.max(n || 0, 1), 100)
 })
 function formatUuid(u: string): string {
  let out = uppercase.value ? u.toUpperCase() : u
  if (noDashes.value) out = out.replace(/-/g, '')
  return out
 }
 const uuids = computed(() => baseUuids.value.map(formatUuid))
 /** UUID v4：纯随机 */
 function uuidv4(): string {
  return crypto.randomUUID()
 }
 /** UUID v7：毫秒时间戳前缀（48 bit）+ 随机，时间有序、适合数据库索引 */
 function uuidv7(): string {
  const ts = BigInt(Date.now())
  const b = crypto.getRandomValues(new Uint8Array(16))
  b[0] = Number((ts >> 40n) & 0xffn)
  b[1] = Number((ts >> 32n) & 0xffn)
  b[2] = Number((ts >> 24n) & 0xffn)
  b[3] = Number((ts >> 16n) & 0xffn)
  b[4] = Number((ts >> 8n) & 0xffn)
  b[5] = Number(ts & 0xffn)
  b[6] = (b[6] & 0x0f) | 0x70 // version 7
  b[8] = (b[8] & 0x3f) | 0x80 // variant 10xx
  const hex = Array.from(b, x => x.toString(16).padStart(2, '0')).join('')
  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
 }
 function generate() {
  const gen = version.value === 'v4' ? uuidv4 : uuidv7
  baseUuids.value = Array.from({ length: batchCount.value }, gen)
 }
 const allText = computed(() => uuids.value.join('\n'))
 function copyAll() {
  try {
    void navigator.clipboard.writeText(allText.value)
  } catch {
    /* ignore */
  }
 }
 // 切换版本时立即重新生成
 watch(version, generate)
 onMounted(generate)
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <div class="flex items-center justify-between flex-wrap gap-3">
      <div class="flex items-center gap-4 flex-wrap">
        <div class="flex flex-col gap-1.5">
          <Label class="text-xs">生成数量（1-100）</Label>
          <Input v-model="count" type="number" min="1" max="100" class="w-24 font-mono text-sm" />
        </div>
        <div class="flex flex-col gap-1.5">
          <Label class="text-xs">版本</Label>
          <div class="flex items-center gap-2">
            <Segmented
              v-model="version"
              :options="[
                { value: 'v4', label: 'v4 随机' },
                { value: 'v7', label: 'v7 时间有序' }
              ]"
            />
          </div>
        </div>
      </div>
      <div class="flex items-center gap-4">
        <label class="flex items-center gap-2 text-xs text-muted-foreground cursor-pointer">
          大写
          <Switch v-model="uppercase" />
        </label>
        <label class="flex items-center gap-2 text-xs text-muted-foreground cursor-pointer">
          去除连字符
          <Switch v-model="noDashes" />
        </label>
        <Button size="sm" class="gap-1" @click="generate">
          <RefreshCw class="size-3.5" />
          重新生成
        </Button>
      </div>
    </div>
    <ResultArea :text="allText" label="UUID 列表" placeholder="点击重新生成" />
    <div class="flex items-center gap-2">
      <Button size="sm" variant="outline" class="gap-1" :disabled="!allText" @click="copyAll">
        <Copy class="size-3.5" />
        复制全部（{{ uuids.length }} 个）
      </Button>
      <span class="text-xs text-muted-foreground">{{ version === 'v4' ? 'UUID v4（纯随机）' : 'UUID v7（毫秒时间戳前缀，适合数据库主键索引）' }}</span>
    </div>
  </div>
 </template>
@@ -0,0 +1,77 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import Segmented from '../../components/Segmented.vue'
 import ResultArea from '../../components/ResultArea.vue'
 type Radix = '2' | '8' | '10' | '16'
 const bases: { value: Radix; label: string }[] = [
  { value: '2', label: '二进制(2)' },
  { value: '8', label: '八进制(8)' },
  { value: '10', label: '十进制(10)' },
  { value: '16', label: '十六进制(16)' }
 ]
 const from = ref<Radix>('10')
 const to = ref<Radix>('16')
 const input = ref('')
 const error = ref('')
 const RADIX_MAP: Record<Radix, number> = { '2': 2, '8': 8, '10': 10, '16': 16 }
 /** 按进制精确解析为 BigInt（大数字不丢精度），非法输入抛错 */
 function parseBigInt(s: string, radix: number): bigint {
  const digits = '0123456789abcdef'
  const trimmed = s.trim().toLowerCase()
  const negative = trimmed.startsWith('-')
  const body = trimmed.replace(/^[+-]/, '')
  if (!body) throw new Error('empty')
  let n = 0n
  for (const ch of body) {
    const d = digits.indexOf(ch)
    if (d === -1 || d >= radix) throw new Error('invalid digit')
    n = n * BigInt(radix) + BigInt(d)
  }
  return negative ? -n : n
 }
 const result = computed(() => {
  error.value = ''
  const v = input.value.trim()
  if (!v) return { dec: null, output: '', outputUppercase: '' }
  try {
    const parsed = parseBigInt(v, RADIX_MAP[from.value])
    const out = parsed.toString(RADIX_MAP[to.value])
    return {
      dec: parsed,
      output: out,
      outputUppercase: to.value === '16' ? out.toUpperCase() : out
    }
  } catch {
    error.value = '输入不合法，请确认数字与当前进制匹配（如十六进制仅含 0-9a-f）'
    return { dec: null, output: '', outputUppercase: '' }
  }
 })
 </script>
 <template>
  <div class="flex flex-col gap-4">
    <div class="flex items-center gap-3 flex-wrap">
      <Segmented v-model="from" label="从" :options="bases" />
      <span class="text-xs text-muted-foreground">→</span>
      <Segmented v-model="to" label="到" :options="bases" />
    </div>
    <div class="flex flex-col gap-1.5">
      <Label class="text-xs">输入（{{ from === '2' ? '二进制' : from === '8' ? '八进制' : from === '10' ? '十进制' : '十六进制' }}）</Label>
      <Input v-model="input" placeholder="输入数字" class="font-mono text-sm" />
    </div>
    <ResultArea :text="result.output" label="结果" placeholder="结果" />
    <ResultArea v-if="to === '16' && result.outputUppercase !== result.output" :text="result.outputUppercase" label="大写形式" placeholder="大写形式" />
    <div v-if="result.dec !== null" class="text-xs text-muted-foreground">十进制值：{{ result.dec.toString() }}</div>
    <p v-if="error" class="text-xs text-destructive">{{ error }}</p>
  </div>
 </template>
@@ -0,0 +1,171 @@
 import type { Component } from 'vue'
 import { defineAsyncComponent } from 'vue'
 import {
  FileJson, Binary, Link, Clock, MoveHorizontal, Fingerprint,
  Wand2, KeyRound, CaseSensitive, Hash, Code, GitCompare, Shield,
  Palette, Lock, CalendarClock, Network, Sigma, Replace, Globe
 } from '@lucide/vue'
 import { registerTool, type DevTool } from '../registry'
 /** 工具元数据（与组件解耦，供模块配置生成搜索项） */
 export const TOOLS_META: Array<Omit<DevTool, 'component' | 'icon'>> = [
  {
    id: 'json', name: 'JSON 格式化', category: 'transform',
    description: '格式化 / 压缩 / 校验，支持键排序',
    keywords: ['json', '格式化', '美化', '压缩', '校验', '排序']
  },
  {
    id: 'timestamp', name: '时间戳转换', category: 'transform',
    description: 'Unix 时间戳与日期时间互转，自动识别秒 / 毫秒',
    keywords: ['时间戳', 'timestamp', 'unix', '日期', '时间', '转换', '现在']
  },
  {
    id: 'base', name: '进制转换', category: 'transform',
    description: '二进制 / 八进制 / 十进制 / 十六进制互转',
    keywords: ['进制', '二进制', '十六进制', 'hex', 'bin', 'oct', 'dec', 'base']
  },
  {
    id: 'color', name: '颜色转换器', category: 'transform',
    description: 'HEX / RGB / HSL / HSV / CMYK 互转，明暗梯度',
    keywords: ['颜色', 'color', 'hex', 'rgb', 'hsl', 'hsv', 'cmyk', '调色', '取色']
  },
  {
    id: 'ip', name: 'IP / CIDR 计算', category: 'transform',
    description: '子网划分、掩码换算、IP 与整数互转',
    keywords: ['ip', 'cidr', '子网', '掩码', '网段', '广播', '网络', 'subnet', 'mask']
  },
  {
    id: 'cron', name: 'Cron 表达式', category: 'transform',
    description: '解析 Cron 表达式，预览接下来 6 次执行时间',
    keywords: ['cron', 'crontab', '定时', '计划任务', '表达式', 'schedule']
  },
  {
    id: 'base64', name: 'Base64 转换', category: 'encoding',
    description: '文本与 Base64 互转（支持中文），文件转 Base64 / Data URL',
    keywords: ['base64', '编码', '解码', 'encode', 'decode', 'dataurl', '文件']
  },
  {
    id: 'url', name: 'URL 编解码', category: 'encoding',
    description: 'URL 编码 / 解码，URL 结构解析',
    keywords: ['url', 'encode', 'decode', '编码', '解码', '链接', '解析', '参数', 'query']
  },
  {
    id: 'jwt', name: 'JWT 解码', category: 'encoding',
    description: '本地解析 JWT 的 Header 与 Payload，含过期时间提示',
    keywords: ['jwt', 'token', '解码', 'header', 'payload', '过期', 'exp']
  },
  {
    id: 'escape', name: '转义 / 反转义', category: 'encoding',
    description: 'HTML 实体与 JSON 字符串转义、反转义',
    keywords: ['转义', '反转义', 'html', 'entity', 'json', 'escape']
  },
  {
    id: 'case', name: '大小写 / 命名转换', category: 'text',
    description: 'camel / Pascal / snake / kebab 等命名转换',
    keywords: ['大小写', '命名', 'camel', 'snake', 'kebab', 'pascal', '转换']
  },
  {
    id: 'regex', name: '正则测试', category: 'text',
    description: '在线测试正则表达式，实时匹配、分组查看与替换预览',
    keywords: ['正则', 'regex', '匹配', 'test', 're', '替换']
  },
  {
    id: 'diff', name: '文本对比', category: 'text',
    description: '两段文本逐行差异对比',
    keywords: ['对比', '差异', 'diff', '比较', 'compare']
  },
  {
    id: 'eol', name: '行尾符转换', category: 'text',
    description: 'CRLF / LF / CR 行尾符统一',
    keywords: ['行尾', '换行', 'crlf', 'lf', 'cr', 'eol', '转行']
  },
  {
    id: 'replace', name: '批量查找替换', category: 'text',
    description: '纯文本 / 正则批量替换，支持分组引用',
    keywords: ['替换', '查找', 'replace', '批量', '正则替换']
  },
  {
    id: 'charcount', name: '字符统计', category: 'text',
    description: '字符 / 字节 / 词数 / 行数统计与高频分析',
    keywords: ['统计', '字数', '字符数', '词频', 'count', 'words', '字节数']
  },
  {
    id: 'uuid', name: 'UUID 生成', category: 'generate',
    description: '批量生成 UUID v4 / v7，支持大写与去连字符',
    keywords: ['uuid', 'guid', '生成', '随机', 'id', 'v4', 'v7']
  },
  {
    id: 'hash', name: '哈希计算', category: 'generate',
    description: 'MD5 / SHA-1 / SHA-256 / SHA-384 / SHA-512 与 HMAC，支持文件',
    keywords: ['哈希', 'hash', 'sha', '摘要', 'md5', 'hmac', '文件', '校验']
  },
  {
    id: 'password', name: '密码生成', category: 'generate',
    description: '随机密码批量生成，字符集可选，附熵值评估',
    keywords: ['密码', 'password', '随机', '生成', '安全', 'entropy']
  },
  {
    id: 'httpstatus', name: 'HTTP 速查', category: 'reference',
    description: 'HTTP 状态码与常用 MIME 类型速查',
    keywords: ['http', '状态码', 'status', 'mime', 'content-type', '速查', '429', '404']
  }
 ]
 /** 图标映射（按工具 id） */
 const TOOL_ICONS: Record<string, Component> = {
  json: FileJson,
  timestamp: Clock,
  base: Hash,
  color: Palette,
  ip: Network,
  cron: CalendarClock,
  base64: Binary,
  url: Link,
  jwt: KeyRound,
  escape: Code,
  case: CaseSensitive,
  regex: Wand2,
  diff: GitCompare,
  eol: MoveHorizontal,
  replace: Replace,
  charcount: Sigma,
  uuid: Fingerprint,
  hash: Shield,
  password: Lock,
  httpstatus: Globe
 }
 // 工具组件（懒加载路径映射）
 const TOOL_COMPONENTS: Record<string, () => Promise<{ default: Component }>> = {
  json: () => import('./JsonTools.vue'),
  timestamp: () => import('./TimestampTools.vue'),
  base: () => import('./base/BaseTools.vue'),
  color: () => import('./ColorTools.vue'),
  ip: () => import('./IpTools.vue'),
  cron: () => import('./CronTools.vue'),
  base64: () => import('./Base64Tools.vue'),
  url: () => import('./UrlTools.vue'),
  jwt: () => import('./JwtTools.vue'),
  escape: () => import('./EscapeTools.vue'),
  case: () => import('./CaseTools.vue'),
  regex: () => import('./RegexTools.vue'),
  diff: () => import('./DiffTools.vue'),
  eol: () => import('./EolTools.vue'),
  replace: () => import('./ReplaceTools.vue'),
  charcount: () => import('./CharCountTools.vue'),
  uuid: () => import('./UuidTools.vue'),
  hash: () => import('./HashTools.vue'),
  password: () => import('./PasswordTools.vue'),
  httpstatus: () => import('./HttpStatusTools.vue')
 }
 /** 将所有工具注册进注册表（幂等） */
 export function registerAllTools(): void {
  for (const meta of TOOLS_META) {
    registerTool({
      ...meta,
      icon: TOOL_ICONS[meta.id],
      component: defineAsyncComponent(TOOL_COMPONENTS[meta.id])
    })
  }
 }
@@ -6,7 +6,10 @@ import {
  Camera,
  Activity,
  Download,
-  Command
+  Command,
  Wrench,
  Music,
  Languages
 } from '@lucide/vue'
 /**
@@ -23,7 +26,10 @@ export const moduleIconMap: Record<string, Component> = {
  screenshot: Camera,
  monitor: Activity,
  downloader: Download,
-  quickpanel: Command
+  quickpanel: Command,
  devtools: Wrench,
  music: Music,
  translate: Languages
 }
 /** 获取模块图标组件，未找到时回退到 Settings 图标 */
@@ -8,7 +8,10 @@ import { moduleConfig as screenshot } from './screenshot'
 import { moduleConfig as monitor } from './monitor'
 import { moduleConfig as downloader } from './downloader'
 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,
@@ -17,7 +20,10 @@ const allModules: ModuleConfig[] = [
  monitor,
  downloader,
  quickpanel,
-  settings
+  devtools,
  settings,
  music,
  translate
 ]
 // 启动时注册所有模块
@@ -279,6 +279,7 @@ function fmtFixedValue(v: number | null, item: OsdItem): string {
    case 'temperature':
      return padNum(Math.round(v).toString(), 3) // 0-150 → 3 字符
    case 'power':
      return padNum(v.toFixed(2), 6) // 12.34 / 123.45 → 6 字符（支持三位数功耗）
    case 'voltage':
      return padNum(v.toFixed(2), 5) // 12.34 → 5 字符
    case 'clock':
@@ -0,0 +1,91 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { ChevronDown } from '@lucide/vue'
 import { Button } from '@/components/ui/button'
 import { Checkbox } from '@/components/ui/checkbox'
 import { Label } from '@/components/ui/label'
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
 import { ScrollArea } from '@/components/ui/scroll-area'
 import { sourceName } from './sources'
 const props = defineProps<{
  modelValue: string[]
  /** 可选源（客户端名）列表 */
  options: string[]
 }>()
 const emit = defineEmits<{ 'update:model-value': [string[]] }>()
 const open = ref(false)
 const checked = computed(() => new Set(props.modelValue))
 const toggle = (code: string) => {
  const next = new Set(checked.value)
  if (next.has(code)) next.delete(code)
  else next.add(code)
  emit('update:model-value', [...next])
 }
 const selectAll = () => emit('update:model-value', [...props.options])
 const clearAll = () => emit('update:model-value', [])
 const label = computed(() => {
  if (props.modelValue.length === 0) return '选择搜索源'
  if (props.modelValue.length === 1) return sourceName(props.modelValue[0])
  return `已选 ${props.modelValue.length} 个源`
 })
 </script>
 <template>
  <Popover v-model:open="open">
    <PopoverTrigger as-child>
      <Button variant="outline" size="sm" class="h-9 max-w-56 justify-between font-normal">
        <span class="truncate">{{ label }}</span>
        <ChevronDown class="size-3.5 shrink-0 opacity-50" />
      </Button>
    </PopoverTrigger>
    <PopoverContent class="w-64 p-2" align="start">
      <div class="mb-1 flex items-center justify-between px-1">
        <span class="text-[11px] text-muted-foreground">搜索源</span>
        <div class="flex items-center gap-2">
          <button
            type="button"
            class="text-[11px] text-muted-foreground hover:text-foreground disabled:opacity-40"
            :disabled="modelValue.length === options.length"
            @click="selectAll"
          >
            全选
          </button>
          <button
            type="button"
            class="text-[11px] text-muted-foreground hover:text-foreground disabled:opacity-40"
            :disabled="modelValue.length === 0"
            @click="clearAll"
          >
            清空
          </button>
        </div>
      </div>
      <!-- ScrollArea 的 viewport 为 h-full，需要根节点有确定高度才能滚动 -->
      <ScrollArea class="h-72">
        <div class="space-y-0.5 pr-2">
          <label
            v-for="code in options"
            :key="code"
            class="flex cursor-pointer items-center gap-2 rounded-md px-2 py-1.5 hover:bg-accent/60"
          >
            <Checkbox :model-value="checked.has(code)" @update:model-value="toggle(code)" />
            <Label class="cursor-pointer truncate text-[13px]">{{ sourceName(code) }}</Label>
          </label>
          <p v-if="options.length === 0" class="px-2 py-3 text-[11.5px] text-muted-foreground">
            未获取到可用源，请先在「设置 → 环境与诊断」安装运行时。
          </p>
        </div>
      </ScrollArea>
      <div class="mt-1 flex items-center justify-between border-t px-1 pt-1.5">
        <span class="text-[11px] text-muted-foreground">{{ options.length }} 个可选源</span>
        <span class="text-[11px] text-muted-foreground">已选 {{ modelValue.length }}</span>
      </div>
    </PopoverContent>
  </Popover>
 </template>
@@ -0,0 +1,708 @@
 <script setup lang="ts">
 import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
 import { toast } from 'vue-sonner'
 import {
  Cloud,
  FolderOpen,
  HardDrive,
  ListMusic,
  ListPlus,
  Loader2,
  Music2,
  Pencil,
  Play,
  Plus,
  RefreshCw,
  Search,
  Trash2
 } from '@lucide/vue'
 import { useFeiniuStore, type PlayableItem } from '@/stores/feiniuStore'
 import TrackItem from './TrackItem.vue'
 import PlaylistEditorDialog from './PlaylistEditorDialog.vue'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Empty, EmptyDescription, EmptyMedia, EmptyTitle } from '@/components/ui/empty'
 import { ScrollArea } from '@/components/ui/scroll-area'
 import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle
 } from '@/components/ui/dialog'
 const store = useFeiniuStore()
 /** 曲库视图：飞牛 / 本地 / 歌单 */
 type LibraryView = 'feiniu' | 'local' | 'playlists'
 const view = ref<LibraryView>('feiniu')
 const needsLogin = computed(() => !store.config.loggedIn && !store.activeConn)
 const sourceNav = computed(() => [
  { value: 'feiniu' as const, label: '飞牛曲库', icon: Cloud, count: store.total || store.tracks.length },
  { value: 'local' as const, label: '本地曲库', icon: HardDrive, count: store.localTracks.length },
  { value: 'playlists' as const, label: '我的歌单', icon: ListMusic, count: store.playlists.length }
 ])
 // ===== 曲库搜索：飞牛 track/list 接口**不支持**关键字过滤（实测忽略该参数），
 // 因此搜索框只做**本地筛选**（歌名/歌手/专辑）；输入时自动补齐剩余分页，
 // 保证筛选覆盖全库而不是已加载的前几页。两个视图（飞牛/本地）共用同一个关键字。
 let searchTimer: ReturnType<typeof setTimeout> | undefined
 let searchSeq = 0
 /** 全量补齐进行中：输入防抖与视图切换可能同时触发，用标志位避免并发重复翻页 */
 let fillingAll = false
 /** 本组件已完成挂载初始化：此前不触发补齐，避免与 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.loadRemainingTracks()
  } catch (e) {
    if (seq === searchSeq) toast.error(String(e))
  } finally {
    fillingAll = false
  }
 }
 /**
 * 搜索框输入：仅飞牛曲库需要补齐分页（本地曲库是已全量在内存的数组，输入即筛）。
 * 两个视图共用同一个关键字，但按各自的数据来源决定是否发请求。
 */
 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)))
 }
 function refreshLocal() {
  store.scanLocal().catch((e) => toast.error(String(e)))
 }
 function playFeiniu() {
  // 有筛选时只播放筛选结果
  if (filteredTracks.value.length) store.playQueue(filteredTracks.value, 0)
 }
 function playLocal() {
  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
      // 先把已加载的数据渲染出来，都渲染完了再向 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' }
  )
  watch(
    loadMoreRef,
    (el) => {
      if (!loadMoreObserver) return
      loadMoreObserver.disconnect()
      if (el) loadMoreObserver.observe(el)
    },
    { immediate: true }
  )
 })
 onBeforeUnmount(() => {
  clearTimeout(searchTimer)
  loadMoreObserver?.disconnect()
 })
 // ===== 歌单 =====
 const activePlaylistId = ref('')
 const activePlaylist = computed(() => store.playlists.find((p) => p.id === activePlaylistId.value) || null)
 const createOpen = ref(false)
 const newName = ref('')
 const renameOpen = ref(false)
 const renameValue = ref('')
 /** 编辑歌单音乐（勾选加入 / 批量移出） */
 const editorOpen = ref(false)
 // 切换歌单时关闭编辑器，避免对着已切换的目标继续编辑
 watch(activePlaylistId, () => (editorOpen.value = false))
 // 换视图 / 换关键字 / 换歌单时把增量渲染窗口收回一屏，避免「切回来看到一屏旧内容」
 watch([view, filterKeyword, activePlaylistId], () => {
  renderLimit.value = LIST_STEP
 })
 // 切到歌单视图时自动选中第一个
 watch(
  [view, () => store.playlists.length],
  () => {
    if (view.value !== 'playlists') return
    if (activePlaylistId.value && store.playlists.some((p) => p.id === activePlaylistId.value)) return
    activePlaylistId.value = store.playlists[0]?.id ?? ''
  },
  { immediate: true }
 )
 function createPlaylist() {
  const name = newName.value.trim()
  if (!name) {
    toast.error('请输入歌单名称')
    return
  }
  activePlaylistId.value = store.createPlaylist(name)
  newName.value = ''
  createOpen.value = false
  view.value = 'playlists'
 }
 function openRename() {
  if (!activePlaylist.value) return
  renameValue.value = activePlaylist.value.name
  renameOpen.value = true
 }
 function confirmRename() {
  const name = renameValue.value.trim()
  if (!name || !activePlaylist.value) return
  store.renamePlaylist(activePlaylist.value.id, name)
  renameOpen.value = false
 }
 function removePlaylist() {
  if (!activePlaylist.value) return
  store.deletePlaylist(activePlaylist.value.id)
  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) await store.ensureTracksFresh().catch(() => {})
    // 恢复的是本地视图时自动扫描（标签有缓存，通常很快），否则恢复的筛选无内容可筛
    if (view.value === 'local') void store.scanLocal().catch(() => {})
  } finally {
    // 挂载初始化结束才让「视图 / 关键字变化 → 补齐分页」的监听生效，
    // 避免它与上面的首页请求并发（并发会因列表整体替换而丢页）；
    // 随后按同一串行顺序补一次，覆盖「启动时已带关键字」的情况
    mountedReady = true
    ensureFeiniuFilterCoverage()
  }
 })
 /** 表格表头与 TrackItem 行保持同一条网格 */
 const GRID = { gridTemplateColumns: '28px 36px minmax(0,1fr) 74px 28px' }
 const listEmptyHint = computed(() => {
  if (view.value === 'feiniu') {
    return store.config.loggedIn ? '曲库为空，试试刷新或检查 NAS 曲库目录' : '请先在「设置 → 飞牛音乐连接」登录'
  }
  return '暂无本地音乐，点击「扫描本地曲库」，或到「设置 → 存储与上传」添加本地曲库目录'
 })
 </script>
 <template>
  <div class="flex h-full min-h-0">
    <!-- ===== 左：来源导航 ===== -->
    <aside class="flex w-[168px] shrink-0 flex-col border-r">
      <ScrollArea class="min-h-0 flex-1">
        <div class="flex flex-col p-2">
          <p class="px-2 pb-1.5 pt-0.5 text-[11px] font-medium tracking-wide text-muted-foreground">曲库</p>
          <!-- 来源：选中态与顶部 Tabs 一致（无容器底色，选中项为浮起胶囊） -->
          <div class="flex flex-col gap-0.5">
            <button
              v-for="nav in sourceNav"
              :key="nav.value"
              type="button"
              class="flex h-8 items-center gap-1.5 rounded-md px-2 text-[13px] transition-colors duration-150"
              :class="
                view === nav.value
                  ? 'bg-background font-medium text-foreground shadow-sm ring-1 ring-border'
                  : 'text-muted-foreground hover:bg-accent/60 hover:text-foreground'
              "
              @click="view = nav.value"
            >
              <component :is="nav.icon" class="size-3.5 shrink-0" />
              <span class="min-w-0 flex-1 truncate">{{ nav.label }}</span>
              <!-- 数量始终渲染（无歌曲时显示 0），并固定宽度右对齐，保证数字列竖向对齐 -->
              <span
                class="min-w-[3ch] shrink-0 text-right text-[10.5px] tabular-nums"
                :class="view === nav.value ? 'text-muted-foreground' : 'text-muted-foreground/70'"
              >
                {{ nav.count > 999 ? '999+' : nav.count }}
              </span>
            </button>
          </div>
          <!-- 歌单列表（选中「我的歌单」时展开） -->
          <Transition name="pl-list">
            <div v-if="view === 'playlists'" class="mt-1.5 ml-1.5 flex flex-col gap-0.5 border-l pl-1.5">
              <button
                v-for="p in store.playlists"
                :key="p.id"
                type="button"
                class="flex h-7 items-center gap-1.5 rounded-md px-2 text-left text-[12.5px] transition-colors duration-150"
                :class="
                  activePlaylistId === p.id
                    ? 'bg-background font-medium text-foreground shadow-sm ring-1 ring-border'
                    : 'text-muted-foreground hover:bg-accent/60 hover:text-foreground'
                "
                @click="activePlaylistId = p.id"
              >
                <span class="min-w-0 flex-1 truncate">{{ p.name }}</span>
                <span class="min-w-[3ch] shrink-0 text-right text-[10.5px] tabular-nums">
                  {{ p.items.length > 999 ? '999+' : p.items.length }}
                </span>
              </button>
              <button
                type="button"
                class="flex h-7 items-center gap-1.5 rounded-md px-2 text-[12.5px] text-muted-foreground transition-colors duration-150 hover:bg-accent/60 hover:text-foreground"
                @click="createOpen = true"
              >
                <Plus class="size-3.5 shrink-0" />
                <span class="min-w-0 flex-1 truncate">新建歌单</span>
              </button>
              <p v-if="!store.playlists.length" class="px-2 py-1 text-[11.5px] text-muted-foreground">
                还没有歌单
              </p>
            </div>
          </Transition>
        </div>
      </ScrollArea>
    </aside>
    <!-- ===== 右：内容（key 随来源变化，复用全局 tab-animate 切换动画） ===== -->
    <section :key="view" class="tab-animate flex min-w-0 flex-1 flex-col">
      <!-- 未登录态：**只挡飞牛曲库**。本地曲库与「我的歌单」完全不依赖 NAS 登录，
           此前把它们一起挡掉，等于让「只用发现音乐 + 本地曲库」的用户点进来只看得到登录提示 -->
      <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>
          <EmptyDescription>
            到「设置 → 飞牛音乐连接」添加并登录。本地曲库与「我的歌单」不依赖 NAS，可直接在左侧切换查看。
          </EmptyDescription>
        </Empty>
      </div>
      <template v-else>
        <!-- 工具栏 -->
        <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-[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.loading || store.refreshing"
              @click="refreshFeiniu"
            >
              <RefreshCw :class="store.loading || store.refreshing ? 'size-3.5 animate-spin' : 'size-3.5'" />
              刷新
            </Button>
            <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="!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="ml-1 shrink-0 whitespace-nowrap text-[11.5px] text-muted-foreground">
              <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>
          <template v-else>
            <template v-if="activePlaylist">
              <div class="min-w-0">
                <div class="truncate text-[13px] font-medium">{{ activePlaylist.name }}</div>
                <div class="text-[11.5px] text-muted-foreground">{{ activePlaylist.items.length }} 首</div>
              </div>
              <div class="ml-auto flex items-center gap-1.5">
                <Button variant="outline" size="sm" class="h-8" @click="editorOpen = true">
                  <ListPlus class="size-3.5" />
                  编辑音乐
                </Button>
                <Button
                  variant="ghost"
                  size="icon"
                  class="size-8"
                  aria-label="重命名歌单"
                  @click="openRename"
                >
                  <Pencil class="size-3.5" />
                </Button>
                <Button
                  variant="ghost"
                  size="icon"
                  class="size-8 text-destructive hover:text-destructive"
                  aria-label="删除歌单"
                  @click="removePlaylist"
                >
                  <Trash2 class="size-3.5" />
                </Button>
                <Button size="sm" class="h-8" :disabled="!activePlaylist.items.length" @click="playActivePlaylist">
                  <Play class="size-3.5" /> 播放全部
                </Button>
              </div>
            </template>
            <span v-else class="text-[12.5px] text-muted-foreground">选择左侧歌单查看内容</span>
          </template>
        </header>
        <!-- 列表 -->
        <ScrollArea class="min-h-0 flex-1">
          <div class="px-2 pb-4">
            <!-- 表头 -->
            <div
              v-if="
                (view === 'feiniu' && filteredTracks.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"
              :style="GRID"
            >
              <span class="text-center">#</span>
              <span />
              <span>标题</span>
              <span class="text-right">时长</span>
              <span />
            </div>
            <!-- 飞牛曲库 -->
            <template v-if="view === 'feiniu'">
              <div v-if="store.loading" class="flex items-center justify-center gap-2 py-14 text-[12.5px] text-muted-foreground">
                <Loader2 class="size-4 animate-spin" /> 加载曲库…
              </div>
              <Empty v-else-if="!store.tracks.length">
                <EmptyMedia><Music2 class="size-8 text-muted-foreground" /></EmptyMedia>
                <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 visibleFeiniu"
                  :key="t.guid || i"
                  :item="t"
                  :index="i"
                  :context="filteredTracks"
                  :active="store.current?.guid === t.guid"
                />
              </template>
            </template>
            <!-- 本地曲库 -->
            <template v-else-if="view === 'local'">
              <Empty v-if="!store.localTracks.length && !store.localScanBusy">
                <EmptyMedia><HardDrive class="size-8 text-muted-foreground" /></EmptyMedia>
                <EmptyTitle>暂无本地音乐</EmptyTitle>
                <EmptyDescription>{{ listEmptyHint }}</EmptyDescription>
              </Empty>
              <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 visibleLocal"
                  :key="t.guid || i"
                  :item="t"
                  :index="i"
                  :context="filteredLocalTracks"
                  :active="store.current?.guid === t.guid"
                />
              </template>
            </template>
            <!-- 歌单详情 -->
            <template v-else>
              <template v-if="activePlaylist">
                <Empty v-if="!activePlaylist.items.length">
                  <EmptyMedia><ListMusic class="size-8 text-muted-foreground" /></EmptyMedia>
                  <EmptyTitle>歌单还是空的</EmptyTitle>
                  <EmptyDescription>
                    点击「编辑音乐」从全部音乐里勾选加入，或在曲库列表中通过「⋯」菜单单首添加。
                  </EmptyDescription>
                  <Button size="sm" class="mt-1" @click="editorOpen = true">
                    <ListPlus class="size-3.5" />
                    编辑音乐
                  </Button>
                </Empty>
                <TrackItem
                  v-for="(t, i) in visiblePlaylistItems"
                  :key="`${t.source}:${t.guid}:${i}`"
                  :item="t"
                  :index="i"
                  :context="activePlaylist.items"
                  :playlist-id="activePlaylist.id"
                  :playlist-index="i"
                  :active="store.current?.guid === t.guid"
                  show-source
                />
              </template>
              <Empty v-else>
                <EmptyMedia><ListMusic class="size-8 text-muted-foreground" /></EmptyMedia>
                <EmptyTitle>还没有歌单</EmptyTitle>
                <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>
    </section>
    <!-- 新建歌单 -->
    <Dialog v-model:open="createOpen">
      <DialogContent class="sm:max-w-sm">
        <DialogHeader>
          <DialogTitle>新建歌单</DialogTitle>
          <DialogDescription>歌单保存在本机，可混合飞牛 NAS 与本地曲目。</DialogDescription>
        </DialogHeader>
        <Input v-model="newName" placeholder="歌单名称" @keydown.enter="createPlaylist" />
        <DialogFooter>
          <Button variant="outline" @click="createOpen = false">取消</Button>
          <Button @click="createPlaylist">创建</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
    <!-- 重命名歌单 -->
    <Dialog v-model:open="renameOpen">
      <DialogContent class="sm:max-w-sm">
        <DialogHeader>
          <DialogTitle>重命名歌单</DialogTitle>
        </DialogHeader>
        <Input v-model="renameValue" placeholder="歌单名称" @keydown.enter="confirmRename" />
        <DialogFooter>
          <Button variant="outline" @click="renameOpen = false">取消</Button>
          <Button @click="confirmRename">保存</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
    <!-- 编辑歌单音乐：从全部音乐勾选加入 / 批量移出 -->
    <PlaylistEditorDialog
      v-if="activePlaylist"
      v-model:open="editorOpen"
      :playlist-id="activePlaylist.id"
    />
  </div>
 </template>
 <style scoped>
 /* 歌单子树展开 / 收起 */
 .pl-list-enter-active,
 .pl-list-leave-active {
  transition: opacity 0.18s ease, transform 0.18s ease;
 }
 .pl-list-enter-from,
 .pl-list-leave-to {
  opacity: 0;
  transform: translateY(-6px);
 }
@media (prefers-reduced-motion: reduce) {
  .pl-list-enter-active,
  .pl-list-leave-active {
    transition: none;
  }
 }
 </style>
@@ -0,0 +1,418 @@
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue'
 import { toast } from 'vue-sonner'
 import { Check, HardDrive, Loader2, Music2, Plus, FolderOpen, Minus } from '@lucide/vue'
 import { useFeiniuStore, type PlayableItem } from '@/stores/feiniuStore'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Checkbox } from '@/components/ui/checkbox'
 import { ScrollArea } from '@/components/ui/scroll-area'
 import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs'
 import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle
 } from '@/components/ui/dialog'
 const props = defineProps<{
  open: boolean
  playlistId: string
 }>()
 const emit = defineEmits<{ 'update:open': [value: boolean] }>()
 const store = useFeiniuStore()
 const playlist = computed(() => store.playlists.find((p) => p.id === props.playlistId) || null)
 const itemKey = (t: PlayableItem) => `${t.source}:${t.guid ?? ''}`
 /** 歌单已有曲目 key 集合 */
 const inPlaylistKeys = computed(() => new Set((playlist.value?.items ?? []).map(itemKey)))
 // ===== 状态 =====
 const tab = ref<'all' | 'inPlaylist'>('all')
 const sourceFilter = ref<'all' | 'feiniu' | 'local'>('all')
 const keyword = ref('')
 const checked = ref<Set<string>>(new Set())
 function resetState() {
  tab.value = 'all'
  sourceFilter.value = 'all'
  keyword.value = ''
  checked.value = new Set()
  limit.value = LIMIT
 }
 // 打开时重置并确保曲库有数据可挑
 watch(
  () => props.open,
  async (open) => {
    if (!open) return
    resetState()
    if (store.config.loggedIn && store.tracks.length === 0) {
      store.loadTracks(1).catch((e) => toast.error(String(e)))
    }
  }
 )
 // 切 tab / 切来源时清空选择，避免"看不到的项仍被选中"造成数量对不上
 watch([tab, sourceFilter], () => {
  checked.value = new Set()
  limit.value = LIMIT
 })
 // ===== 数据源 =====
 const allTracks = computed<PlayableItem[]>(() => {
  if (sourceFilter.value === 'feiniu') return store.tracks
  if (sourceFilter.value === 'local') return store.localTracks
  return [...store.tracks, ...store.localTracks]
 })
 const baseList = computed<PlayableItem[]>(() => {
  const list = tab.value === 'inPlaylist' ? playlist.value?.items ?? [] : allTracks.value
  const kw = keyword.value.trim().toLowerCase()
  if (!kw) return list
  return list.filter(
    (t) =>
      t.title.toLowerCase().includes(kw) ||
      t.artistNames.toLowerCase().includes(kw) ||
      (t.album ?? '').toLowerCase().includes(kw)
  )
 })
 // 大列表增量渲染
 const LIMIT = 120
 const limit = ref(LIMIT)
 const visibleList = computed(() => baseList.value.slice(0, limit.value))
 const hasMore = computed(() => baseList.value.length > limit.value)
 watch(baseList, () => (limit.value = LIMIT))
 /** 已在歌单的曲目在「全部音乐」里不可重复勾选 */
 function isAlreadyIn(item: PlayableItem): boolean {
  return tab.value === 'all' && inPlaylistKeys.value.has(itemKey(item))
 }
 function isSelectable(item: PlayableItem): boolean {
  return !isAlreadyIn(item)
 }
 const selectableKeys = computed(() =>
  baseList.value.filter((t) => isSelectable(t)).map(itemKey)
 )
 const allChecked = computed(
  () => selectableKeys.value.length > 0 && selectableKeys.value.every((k) => checked.value.has(k))
 )
 function toggle(key: string) {
  const next = new Set(checked.value)
  if (next.has(key)) next.delete(key)
  else next.add(key)
  checked.value = next
 }
 function toggleAll() {
  checked.value = allChecked.value ? new Set() : new Set(selectableKeys.value)
 }
 const selectedItems = computed(() => {
  const map = new Map<string, PlayableItem>()
  for (const t of baseList.value) map.set(itemKey(t), t)
  for (const t of playlist.value?.items ?? []) map.set(itemKey(t), t)
  const out: PlayableItem[] = []
  for (const k of checked.value) {
    const t = map.get(k)
    if (t) out.push(t)
  }
  return out
 })
 const selectedCount = computed(() => checked.value.size)
 // ===== 执行 =====
 function apply() {
  if (!playlist.value) return
  const n = selectedCount.value
  if (n === 0) return
  if (tab.value === 'all') {
    store.addToPlaylist(playlist.value.id, selectedItems.value)
    toast.success(`已添加 ${n} 首到「${playlist.value.name}」`)
  } else {
    store.removeItemsFromPlaylist(playlist.value.id, [...checked.value])
    toast.success(`已从「${playlist.value.name}」移除 ${n} 首`)
  }
  emit('update:open', false)
 }
 const localEmpty = computed(() => store.localTracks.length === 0)
 async function scanLocal() {
  try {
    await store.scanLocal()
    toast.success(`已扫描到 ${store.localTracks.length} 首本地音乐`)
  } catch (e) {
    toast.error(String(e))
  }
 }
 const durationText = (ms?: number) => (ms ? store.fmtDuration(ms / 1000) : '')
 </script>
 <template>
  <Dialog :open="open" @update:open="(v: boolean) => emit('update:open', v)">
    <DialogContent class="flex max-h-[80vh] flex-col overflow-hidden sm:max-w-2xl">
      <DialogHeader>
        <DialogTitle>编辑歌单 · {{ playlist?.name || '' }}</DialogTitle>
        <DialogDescription>
          从全部音乐里勾选加入歌单，或切换到「已在歌单」批量移出。
        </DialogDescription>
      </DialogHeader>
      <Tabs v-model="tab" class="flex flex-col">
        <div class="flex items-center gap-2">
          <TabsList class="grid w-[220px] shrink-0 grid-cols-2">
            <TabsTrigger value="all" class="gap-1.5">
              <Plus class="size-3.5" />全部音乐
            </TabsTrigger>
            <TabsTrigger value="inPlaylist" class="gap-1.5">
              <Minus class="size-3.5" />已在歌单
              <span class="text-xs text-muted-foreground">({{ playlist?.items.length ?? 0 }})</span>
            </TabsTrigger>
          </TabsList>
          <Input
            v-model="keyword"
            class="h-8 max-w-56"
            placeholder="搜索歌名 / 歌手 / 专辑"
          />
        </div>
        <!-- ===== 全部音乐：来源筛选 ===== -->
        <div v-if="tab === 'all'" class="mt-2 flex items-center gap-1.5">
          <button
            v-for="opt in (['all', 'feiniu', 'local'] as const)"
            :key="opt"
            type="button"
            class="rounded-md border px-2 py-1 text-[11.5px] transition-colors"
            :class="
              sourceFilter === opt
                ? 'border-primary bg-primary/10 text-foreground'
                : 'border-border text-muted-foreground hover:bg-accent/50'
            "
            @click="sourceFilter = opt"
          >
            {{ opt === 'all' ? '全部来源' : opt === 'feiniu' ? '飞牛曲库' : '本地曲库' }}
          </button>
          <span class="ml-1 text-[11.5px] text-muted-foreground">{{ baseList.length }} 首</span>
          <label class="ml-auto flex cursor-pointer items-center gap-1.5 text-[11.5px] text-muted-foreground">
            <Checkbox
              :model-value="allChecked"
              :disabled="selectableKeys.length === 0"
              aria-label="全选当前列表"
              @update:model-value="toggleAll"
            />
            全选当前列表
          </label>
        </div>
        <div v-else class="mt-2 flex items-center gap-2">
          <span class="text-[11.5px] text-muted-foreground">{{ baseList.length }} 首</span>
          <label class="ml-auto flex cursor-pointer items-center gap-1.5 text-[11.5px] text-muted-foreground">
            <Checkbox
              :model-value="allChecked"
              :disabled="selectableKeys.length === 0"
              aria-label="全选当前列表"
              @update:model-value="toggleAll"
            />
            全选当前列表
          </label>
        </div>
        <TabsContent value="all" class="mt-2">
          <ScrollArea class="h-[min(320px,45vh)] rounded-md border">
            <div class="flex flex-col gap-0.5 p-1">
              <!-- 本地曲库未扫描 -->
              <div
                v-if="sourceFilter !== 'feiniu' && localEmpty"
                class="flex items-center gap-2 rounded-md border border-dashed px-3 py-2.5"
              >
                <FolderOpen class="size-4 shrink-0 text-muted-foreground" />
                <span class="text-[12px] text-muted-foreground">本地曲库尚未扫描，扫描后即可一起勾选。</span>
                <Button
                  size="sm"
                  variant="outline"
                  class="ml-auto h-7 shrink-0"
                  :disabled="store.localScanBusy"
                  @click="scanLocal"
                >
                  <Loader2 v-if="store.localScanBusy" class="size-3.5 animate-spin" />
                  <span :class="store.localScanBusy ? 'ml-1.5' : ''">
                    {{ store.localScanBusy ? '扫描中' : '扫描本地' }}
                  </span>
                </Button>
              </div>
              <div
                v-if="store.loading && !store.tracks.length"
                class="flex items-center justify-center gap-2 py-10 text-[12px] text-muted-foreground"
              >
                <Loader2 class="size-4 animate-spin" /> 加载曲库…
              </div>
              <p
                v-else-if="baseList.length === 0"
                class="py-10 text-center text-[12px] text-muted-foreground"
              >
                {{ keyword.trim() ? '没有匹配的曲目' : '没有可添加的曲目' }}
              </p>
              <button
                v-for="item in visibleList"
                :key="itemKey(item)"
                type="button"
                class="flex h-11 items-center gap-3 rounded-md px-2 text-left transition-colors"
                :class="
                  isSelectable(item)
                    ? 'hover:bg-accent/50'
                    : 'cursor-not-allowed opacity-55'
                "
                :disabled="!isSelectable(item)"
                @click="toggle(itemKey(item))"
              >
                <span
                  class="flex size-4 shrink-0 items-center justify-center rounded-[4px] border transition-colors"
                  :class="
                    checked.has(itemKey(item))
                      ? 'border-primary bg-primary text-primary-foreground'
                      : 'border-input'
                  "
                >
                  <Check v-if="checked.has(itemKey(item))" class="size-3" />
                </span>
                <span class="flex size-8 shrink-0 items-center justify-center rounded bg-muted text-muted-foreground">
                  <HardDrive v-if="item.source === 'local'" class="size-3.5" />
                  <Music2 v-else class="size-3.5" />
                </span>
                <span class="min-w-0 flex-1">
                  <span class="block truncate text-[13px]">{{ item.title }}</span>
                  <span class="block truncate text-[11.5px] text-muted-foreground">
                    {{ item.artistNames || '—' }}
                  </span>
                </span>
                <span
                  v-if="isAlreadyIn(item)"
                  class="shrink-0 rounded border border-border px-1.5 py-0.5 text-[10.5px] text-muted-foreground"
                >
                  已加入
                </span>
                <span class="shrink-0 text-[11.5px] tabular-nums text-muted-foreground">
                  {{ durationText(item.durationMs) }}
                </span>
              </button>
              <div class="flex items-center justify-center gap-2 py-2">
                <Button
                  v-if="hasMore"
                  size="sm"
                  variant="ghost"
                  class="text-[11.5px] text-muted-foreground"
                  @click="limit += LIMIT"
                >
                  显示更多（还剩 {{ baseList.length - limit }} 首）
                </Button>
                <Button
                  v-if="sourceFilter !== 'local' && store.hasMoreTracks"
                  size="sm"
                  variant="ghost"
                  class="text-[11.5px] text-muted-foreground"
                  :disabled="store.loadingMore"
                  @click="store.loadMoreTracks()"
                >
                  <Loader2 v-if="store.loadingMore" class="size-3.5 animate-spin" />
                  <span :class="store.loadingMore ? 'ml-1.5' : ''">
                    {{ store.loadingMore ? '加载中' : '继续加载飞牛曲库' }}
                  </span>
                </Button>
              </div>
            </div>
          </ScrollArea>
        </TabsContent>
        <!-- ===== 已在歌单：批量移出 ===== -->
        <TabsContent value="inPlaylist" class="mt-2">
          <ScrollArea class="h-[min(320px,45vh)] rounded-md border">
            <div class="flex flex-col gap-0.5 p-1">
              <p
                v-if="baseList.length === 0"
                class="py-10 text-center text-[12px] text-muted-foreground"
              >
                {{ keyword.trim() ? '没有匹配的曲目' : '这个歌单还没有歌曲' }}
              </p>
              <button
                v-for="item in visibleList"
                :key="itemKey(item)"
                type="button"
                class="flex h-11 items-center gap-3 rounded-md px-2 text-left transition-colors hover:bg-accent/50"
                @click="toggle(itemKey(item))"
              >
                <span
                  class="flex size-4 shrink-0 items-center justify-center rounded-[4px] border transition-colors"
                  :class="
                    checked.has(itemKey(item))
                      ? 'border-destructive bg-destructive text-white'
                      : 'border-input'
                  "
                >
                  <Minus v-if="checked.has(itemKey(item))" class="size-3" />
                </span>
                <span class="flex size-8 shrink-0 items-center justify-center rounded bg-muted text-muted-foreground">
                  <HardDrive v-if="item.source === 'local'" class="size-3.5" />
                  <Music2 v-else class="size-3.5" />
                </span>
                <span class="min-w-0 flex-1">
                  <span class="block truncate text-[13px]">{{ item.title }}</span>
                  <span class="block truncate text-[11.5px] text-muted-foreground">
                    {{ item.artistNames || '—' }}
                  </span>
                </span>
                <span class="shrink-0 text-[11.5px] tabular-nums text-muted-foreground">
                  {{ durationText(item.durationMs) }}
                </span>
              </button>
              <div v-if="hasMore" class="flex justify-center py-2">
                <Button
                  size="sm"
                  variant="ghost"
                  class="text-[11.5px] text-muted-foreground"
                  @click="limit += LIMIT"
                >
                  显示更多（还剩 {{ baseList.length - limit }} 首）
                </Button>
              </div>
            </div>
          </ScrollArea>
        </TabsContent>
      </Tabs>
      <DialogFooter class="items-center gap-2 sm:justify-between">
        <span class="text-[12px] text-muted-foreground">
          已选 <span class="font-medium text-foreground">{{ selectedCount }}</span> 首
        </span>
        <div class="flex items-center gap-2">
          <Button variant="outline" @click="emit('update:open', false)">取消</Button>
          <Button
            :variant="tab === 'inPlaylist' ? 'destructive' : 'default'"
            :disabled="selectedCount === 0"
            @click="apply"
          >
            {{ tab === 'inPlaylist' ? `移除 ${selectedCount} 首` : `添加 ${selectedCount} 首` }}
          </Button>
        </div>
      </DialogFooter>
    </DialogContent>
  </Dialog>
 </template>
@@ -0,0 +1,257 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { toast } from 'vue-sonner'
 import {
  ArrowDown,
  ArrowUp,
  Cloud,
  FolderOpen,
  HardDrive,
  ListPlus,
  MoreHorizontal,
  Music2,
  Play,
  Plus,
  Trash2
 } from '@lucide/vue'
 import type { PlayableItem } from '@/stores/feiniuStore'
 import { useFeiniuStore } from '@/stores/feiniuStore'
 import { Button } from '@/components/ui/button'
 import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger
 } from '@/components/ui/dropdown-menu'
 const props = withDefaults(
  defineProps<{
    item: PlayableItem
    /** 是否为当前播放项 */
    active?: boolean
    /** 列表内序号（从 0 开始） */
    index?: number
    /** 播放上下文：点击播放时以该列表建立队列 */
    context?: PlayableItem[]
    /** 显示专辑列 */
    showAlbum?: boolean
    /** 显示来源标识（歌单等混排列表） */
    showSource?: boolean
    /** 所属歌单 id（提供时可从菜单移除 / 移动） */
    playlistId?: string
    /** 歌单内的序号（用于移除 / 移动） */
    playlistIndex?: number
  }>(),
  { active: false, index: 0, showAlbum: false, showSource: false }
 )
 const store = useFeiniuStore()
 const coverUrl = computed(() => {
  if (props.item.source === 'feiniu' && props.item.coverId && store.mediaPrefix) {
    return `${store.mediaPrefix}/cover?coverId=${encodeURIComponent(props.item.coverId)}&size=64`
  }
  return props.item.coverUrl ?? ''
 })
 const coverFailed = ref(false)
 const durationText = computed(() =>
  store.fmtDuration(props.item.durationMs ? props.item.durationMs / 1000 : undefined)
 )
 /** 本地文件没有时长信息时，退化为展示文件大小 */
 const fallbackText = computed(() => {
  if (props.item.durationMs) return ''
  const n = props.item.size
  if (!n || n <= 0) return ''
  if (n >= 1048576) return `${(n / 1048576).toFixed(1)} MB`
  if (n >= 1024) return `${(n / 1024).toFixed(0)} KB`
  return `${n} B`
 })
 const isCurrent = computed(
  () =>
    props.active ||
    (store.queueIndex >= 0 &&
      store.nowPlaying?.guid === props.item.guid &&
      store.nowPlaying?.source === props.item.source)
 )
 const playlistLength = computed(
  () => (props.playlistId ? store.playlists.find((p) => p.id === props.playlistId)?.items.length ?? 1 : 1)
 )
 function play() {
  store.playItem(props.item, props.context)
 }
 function addToPlaylist(playlistId: string) {
  store.addToPlaylist(playlistId, [props.item])
  toast.success('已加入歌单')
 }
 async function uploadToFeiniu() {
  try {
    await store.uploadLocalTrack(props.item)
    toast.success('已上传到飞牛曲库')
  } catch (e) {
    toast.error(String(e))
  }
 }
 </script>
 <template>
  <div
    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'
    ]"
    @dblclick="play"
  >
    <!-- 序号 / 播放态指示 / 播放按钮。
         行本身不再是 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="transition-opacity group-hover:opacity-0">{{ index + 1 }}</span>
        <button
          type="button"
          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"
        >
          <Play class="size-3.5" />
        </button>
      </template>
    </div>
    <!-- 封面 -->
    <img
      v-if="coverUrl && !coverFailed"
      :src="coverUrl"
      class="size-9 rounded object-cover"
      alt=""
      loading="lazy"
      referrerpolicy="no-referrer"
      @error="coverFailed = true"
    />
    <div v-else class="flex size-9 items-center justify-center rounded bg-muted text-muted-foreground">
      <Music2 class="size-4" />
    </div>
    <!-- 标题 + 元信息 -->
    <div class="min-w-0">
      <div class="flex items-center gap-1.5">
        <span class="truncate text-[13px]" :class="isCurrent ? 'font-medium text-foreground' : ''">
          {{ item.title }}
        </span>
        <span
          v-if="showSource"
          class="shrink-0 text-muted-foreground"
          :title="item.source === 'local' ? '本地文件' : '飞牛 NAS'"
        >
          <HardDrive v-if="item.source === 'local'" class="size-3" />
          <Cloud v-else class="size-3" />
        </span>
      </div>
      <div class="truncate text-[11.5px] text-muted-foreground">{{ item.artistNames || '—' }}</div>
    </div>
    <!-- 专辑 -->
    <div v-if="showAlbum" class="truncate text-[11.5px] text-muted-foreground">
      {{ item.album || '' }}
    </div>
    <!-- 时长（本地无时长时退化为文件大小） -->
    <div class="text-right text-[11.5px] tabular-nums text-muted-foreground">
      <span v-if="item.durationMs">{{ durationText }}</span>
      <span v-else-if="fallbackText" class="text-[11px]">{{ fallbackText }}</span>
      <span v-else>--:--</span>
    </div>
    <!-- 操作菜单 -->
    <DropdownMenu>
      <DropdownMenuTrigger as-child>
        <Button
          size="icon"
          variant="ghost"
          class="size-7 opacity-0 transition-opacity group-hover:opacity-100 data-[state=open]:opacity-100"
          :aria-label="'更多操作：' + item.title"
        >
          <MoreHorizontal class="size-4" />
        </Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end" class="w-48">
        <DropdownMenuLabel class="truncate">{{ item.title }}</DropdownMenuLabel>
        <DropdownMenuSeparator />
        <DropdownMenuItem @click="play">
          <Play class="size-4" /> 播放
        </DropdownMenuItem>
        <DropdownMenuItem @click="store.playNext(item); toast.success('已加入下一首')">
          <ListPlus class="size-4" /> 下一首播放
        </DropdownMenuItem>
        <DropdownMenuItem @click="store.addToQueue(item); toast.success('已加入队列')">
          <Plus class="size-4" /> 加入队列
        </DropdownMenuItem>
        <DropdownMenuSub>
          <DropdownMenuSubTrigger>
            <Plus class="size-4" /> 加入歌单
          </DropdownMenuSubTrigger>
          <DropdownMenuSubContent class="max-h-64 w-48 overflow-y-auto">
            <DropdownMenuItem v-if="store.playlists.length === 0" disabled>还没有歌单</DropdownMenuItem>
            <DropdownMenuItem v-for="p in store.playlists" :key="p.id" @click="addToPlaylist(p.id)">
              {{ p.name }}
            </DropdownMenuItem>
          </DropdownMenuSubContent>
        </DropdownMenuSub>
        <template v-if="item.source === 'local'">
          <DropdownMenuSeparator />
          <DropdownMenuItem
            v-if="store.webdavReady"
            :disabled="store.uploading"
            @click="uploadToFeiniu"
          >
            <Cloud class="size-4" /> 上传到飞牛曲库
          </DropdownMenuItem>
          <!-- 所在目录只是信息，不是动作：用 disabled 的菜单项展示会让人以为点了没反应 -->
          <div class="flex items-center gap-2 px-2 py-1.5 text-[11.5px] text-muted-foreground">
            <FolderOpen class="size-3.5 shrink-0" />
            <span class="truncate" :title="item.dir || ''">{{ item.dir || '未知目录' }}</span>
          </div>
        </template>
        <template v-if="playlistId">
          <DropdownMenuSeparator />
          <DropdownMenuItem
            :disabled="(playlistIndex ?? 0) <= 0"
            @click="store.moveInPlaylist(playlistId, playlistIndex ?? 0, (playlistIndex ?? 0) - 1)"
          >
            <ArrowUp class="size-4" /> 上移
          </DropdownMenuItem>
          <DropdownMenuItem
            :disabled="(playlistIndex ?? 0) >= playlistLength - 1"
            @click="store.moveInPlaylist(playlistId, playlistIndex ?? 0, (playlistIndex ?? 0) + 1)"
          >
            <ArrowDown class="size-4" /> 下移
          </DropdownMenuItem>
          <DropdownMenuItem
            class="text-destructive focus:text-destructive"
            @click="store.removeFromPlaylist(playlistId, playlistIndex ?? 0)"
          >
            <Trash2 class="size-4" /> 从歌单移除
          </DropdownMenuItem>
        </template>
      </DropdownMenuContent>
    </DropdownMenu>
  </div>
 </template>
@@ -0,0 +1,74 @@
 <script setup lang="ts">
 import { computed, onMounted } from 'vue'
 import { toast } from 'vue-sonner'
 import { HardDriveDownload, Loader2, RefreshCw, Trash2 } from '@lucide/vue'
 import { useFeiniuStore } from '@/stores/feiniuStore'
 import { Button } from '@/components/ui/button'
 import { Label } from '@/components/ui/label'
 import { Switch } from '@/components/ui/switch'
 const store = useFeiniuStore()
 /** 开关状态直接由 store.cacheMode 派生，避免与此前一样出现「开关显示关闭但实际在缓存」 */
 const cacheEnabled = computed({
  get: () => store.cacheMode === 'cache',
  set: (v: boolean) => store.setCacheMode(v ? 'cache' : 'stream')
 })
 const usedMb = computed(() => Math.round((store.cacheStatus.usedMb ?? 0) * 10) / 10)
 onMounted(() => {
  void store.ensureCacheStatus()
 })
 async function refresh() {
  await store.ensureCacheStatus()
  toast.success('缓存状态已刷新')
 }
 async function clearAll() {
  await store.clearCache()
  toast.success('缓存已清空')
 }
 </script>
 <template>
  <div class="flex flex-col gap-3">
    <div class="flex items-start justify-between gap-4">
      <div class="min-w-0">
        <div class="flex items-center gap-2">
          <HardDriveDownload class="size-4 text-muted-foreground" />
          <Label class="font-medium">缓存后播放</Label>
        </div>
        <p class="mt-1 text-[11.5px] text-muted-foreground">
          开启后先把 NAS 音频缓存到本机再播放（首播需要等待整首下载完成）；关闭则直连流式播放，
          边下边播、拖动即时生效，但每次都要联网拉取。
        </p>
      </div>
      <Switch v-model="cacheEnabled" class="mt-0.5 shrink-0" />
    </div>
    <div class="flex items-center justify-between gap-4 rounded-lg border bg-card px-3 py-2">
      <div class="flex items-center gap-2 text-[12.5px]">
        <span class="text-muted-foreground">当前占用</span>
        <span class="tabular-nums">{{ usedMb }} MB</span>
        <span class="text-muted-foreground">· {{ store.cacheStatus.count }} 首</span>
        <span class="text-[11.5px] text-muted-foreground/80">（超出上限按 LRU 自动淘汰）</span>
      </div>
      <div class="flex shrink-0 items-center gap-1.5">
        <Button variant="ghost" size="icon" class="size-8" title="刷新" @click="refresh">
          <RefreshCw class="size-3.5" />
        </Button>
        <Button variant="outline" size="sm" class="text-destructive" :disabled="!store.cacheStatus.count" @click="clearAll">
          <Trash2 class="size-3.5" />
          <span class="ml-1.5">清空缓存</span>
        </Button>
      </div>
    </div>
    <p class="flex items-center gap-1.5 text-[11.5px] text-muted-foreground">
      <Loader2 class="size-3" />
      切换缓存模式不会中断当前播放，下一首起按新模式取流。
    </p>
  </div>
 </template>
@@ -0,0 +1,289 @@
 <script setup lang="ts">
 import { onMounted, ref } from 'vue'
 import { toast } from 'vue-sonner'
 import { Check, CircleCheck, Loader2, LogOut, Pencil, Plus, Trash2 } from '@lucide/vue'
 import { useFeiniuStore, type FeiniuConnection } from '@/stores/feiniuStore'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { Switch } from '@/components/ui/switch'
 import { Badge } from '@/components/ui/badge'
 import {
  Dialog,
  DialogContent,
  DialogFooter,
  DialogHeader,
  DialogTitle
 } from '@/components/ui/dialog'
 const store = useFeiniuStore()
 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: '' }
  password.value = ''
  editOpen.value = true
 }
 function editForm(c: FeiniuConnection) {
  // 历史数据里的 frp 等内网转发方式已并入「局域网」
  editing.value = { ...c, kind: c.kind === 'fnconnect' ? 'fnconnect' : 'lan' }
  password.value = ''
  editOpen.value = true
 }
 async function save() {
  if (!editing.value || saving.value) return
  const draft = { ...editing.value }
  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: draft.id || '',
      name: draft.name.trim(),
      kind: draft.kind || 'lan',
      baseUrl: draft.baseUrl?.trim() || '',
      username: draft.username || '',
      accessCode: draft.accessCode || '',
      insecure: !!draft.insecure,
      fnId: draft.fnId?.trim() || '',
      relay: !!draft.relay
    })
    // 先关闭对话框再登录：FnConnect 登录要先探测可达地址（可能数秒），
    // 若等待其完成才关窗，观感就是「已保存但对话框卡住」。
    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() {
  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(
      {
        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))
  } finally {
    testing.value = false
  }
 }
 async function activate(c: FeiniuConnection) {
  await store.activateConnection(c.id)
  toast.success('已切换为激活连接')
 }
 async function logout(c: FeiniuConnection) {
  await store.logout(c.id)
  toast.success('已登出')
 }
 async function remove(c: FeiniuConnection) {
  await store.deleteConnection(c.id)
  toast.success('已删除')
 }
 /** kind → 展示名：局域网涵盖 frp / 内网转发等直连方式，其余为 FnConnect */
 function kindLabel(k: string) {
  return k === 'fnconnect' ? 'FnConnect' : '局域网'
 }
 onMounted(() => store.refreshConnections())
 </script>
 <template>
  <div class="space-y-3">
    <div class="flex items-center justify-between">
      <Label class="text-muted-foreground">飞牛音乐连接</Label>
      <Button variant="outline" size="sm" @click="newForm">
        <Plus class="size-4" /> 新建
      </Button>
    </div>
    <div class="flex flex-col gap-2">
      <div
        v-for="c in store.connections"
        :key="c.id"
        class="flex items-center gap-3 rounded-lg border bg-card px-3 py-2"
      >
        <div class="min-w-0 flex-1">
          <div class="flex items-center gap-2">
            <span class="truncate text-sm font-medium">{{ c.name }}</span>
            <Badge variant="secondary" class="text-[10px]">{{ kindLabel(c.kind) }}</Badge>
            <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.kind === 'fnconnect' && c.relay"> · 中继</template
            ><template v-if="c.username"> · {{ c.username }}</template>
          </div>
        </div>
        <div class="flex shrink-0 items-center gap-1">
          <span v-if="c.loggedIn" class="mr-1 flex items-center gap-1 text-xs text-emerald-600">
            <Check class="size-3.5" /> 已登录
          </span>
          <Button
            v-if="store.activeId !== c.id"
            variant="ghost"
            size="icon"
            class="size-8"
            :title="`设为激活连接（${c.name}）`"
            :aria-label="`设为激活连接 ${c.name}`"
            @click="activate(c)"
          >
            <CircleCheck class="size-4" />
          </Button>
          <Button variant="ghost" size="icon" class="size-8" title="编辑连接" aria-label="编辑连接" @click="editForm(c)">
            <Pencil class="size-4" />
          </Button>
          <Button
            v-if="c.loggedIn"
            variant="ghost"
            size="icon"
            class="size-8"
            title="登出"
            aria-label="登出"
            @click="logout(c)"
          >
            <LogOut class="size-4" />
          </Button>
          <Button
            variant="ghost"
            size="icon"
            class="size-8 text-destructive"
            title="删除连接"
            aria-label="删除连接"
            @click="remove(c)"
          >
            <Trash2 class="size-4" />
          </Button>
        </div>
      </div>
      <p v-if="!store.connections.length" class="text-xs text-muted-foreground">
        还没有连接。新建一个并填写 NAS 地址（局域网 http://192.168.x.x:5666，frp 等内网转发同样填最终访问地址）或 FnConnect fnId。
      </p>
    </div>
    <Dialog v-model:open="editOpen">
      <DialogContent class="sm:max-w-md">
        <DialogHeader>
          <DialogTitle>{{ editing?.id ? '编辑连接' : '新建连接' }}</DialogTitle>
        </DialogHeader>
        <div class="flex flex-col gap-3">
          <div class="space-y-1.5">
            <Label>名称</Label>
            <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', 'fnconnect'] as const)"
                :key="k"
                type="button"
                size="sm"
                :variant="(editing!.kind ?? 'lan') === k ? 'default' : 'outline'"
                @click="editing!.kind = k"
              >
                {{ kindLabel(k) }}
              </Button>
            </div>
          </div>
          <div v-if="editing!.kind === 'fnconnect'" class="space-y-1.5">
            <Label>飞牛 ID</Label>
            <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（frp 填转发后的地址）"
            />
          </div>
          <div class="space-y-1.5">
            <Label>账号</Label>
            <Input v-model="editing!.username" placeholder="飞牛音乐账号" />
          </div>
          <div class="space-y-1.5">
            <Label>密码{{ password ? '' : '（留空则保留已存 token）' }}</Label>
            <Input v-model="password" type="password" placeholder="登录密码" />
          </div>
          <div class="flex items-center justify-between">
            <Label class="text-muted-foreground">忽略 HTTPS 证书校验（自签证书时勾选）</Label>
            <Switch v-model:model-value="editing!.insecure" />
          </div>
        </div>
        <DialogFooter class="gap-2">
          <Button variant="outline" :disabled="testing || saving" @click="test">
            <Loader2 v-if="testing" class="size-4 animate-spin" /> 测试
          </Button>
          <Button :disabled="saving" @click="save">
            <Loader2 v-if="saving" class="size-4 animate-spin" /> 保存
          </Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  </div>
 </template>
@@ -0,0 +1,48 @@
 import type { ModuleConfig } from '@/types/module'
 import type { SearchIndexItem } from '@/stores/searchIndex'
 const searchItems: SearchIndexItem[] = [
  {
    title: '曲库',
    description: '飞牛 NAS 曲库 / 本地曲库 / 自定义歌单，标题栏播放控制',
    keywords: ['音乐', 'music', '曲库', '我的音乐', '飞牛', 'NAS', '歌单', '播放', '本地', '歌词', '队列'],
    tab: 'mymusic'
  },
  {
    title: '发现音乐',
    description: '多平台搜索歌曲并下载（本地 / 飞牛曲库）',
    keywords: ['发现音乐', '搜索', '下载', '聚合', '在线', '网易云', 'qq', '酷狗'],
    tab: 'discover'
  },
  {
    title: '音乐设置',
    description: '飞牛连接、播放缓存、下载目录与 Python 环境检查',
    keywords: ['音乐设置', '飞牛连接', '缓存', '下载目录', '环境', 'python', 'musicdl'],
    tab: 'settings'
  }
 ]
 export const moduleConfig: ModuleConfig = {
  id: 'music',
  name: '音乐',
  icon: 'music',
  description: '飞牛音乐客户端（NAS 曲库 + 本地曲库 + 发现添加）',
  category: 'media',
  defaultEnabled: true,
  loader: () => import('./MusicModule.vue'),
  searchItems,
  lifecycle: {
    onEnable: async () => {
      // 桥接进程按需拉起（首次搜索/环境检测时自动启动），此处无需预启动
    },
    onDisable: () => {
      // 禁用模块时停止桥接进程，释放 Python 进程
      // 直接 invoke 避免模块 index.ts 导入 store 造成循环依赖
      import('@tauri-apps/api/core')
        .then(({ invoke }) => invoke('music_stop_bridge'))
        .catch(() => {})
    }
  },
  // 默认排在「代理」之后、整体第二位（proxy=10、clipboard=20）
  order: 15
 }
@@ -0,0 +1,81 @@
 /**
 * 音乐源（musicdl MusicClient 名）→ 中文展示名映射。
 * 未收录的源回退显示原始客户端名。
 */
 export const SOURCE_NAMES: Record<string, string> = {
  NeteaseMusicClient: '网易云',
  QQMusicClient: 'QQ音乐',
  KugouMusicClient: '酷狗',
  KuwoMusicClient: '酷我',
  MiguMusicClient: '咪咕',
  QianqianMusicClient: '千千',
  BilibiliMusicClient: 'B站音乐',
  SodaMusicClient: '汽水音乐',
  StreetVoiceMusicClient: '街声',
  FiveSingMusicClient: '5SING',
  BodianMusicClient: '波点音乐',
  JooxMusicClient: 'JOOX',
  MyFreeMP3MusicClient: 'MyFreeMP3',
  XiaoBaiMusicClient: '小白音乐',
  JBSouMusicClient: '煎饼搜',
  TuneHubMusicClient: 'TuneHub',
  MituMusicClient: '米兔音乐',
  GequbaoMusicClient: '歌曲宝',
  GequhaiMusicClient: '歌曲海',
  KkwsMusicClient: '开开无损',
  LivePOOMusicClient: '力音',
  LiziYYMusicClient: '梨子音乐',
  MGMP3MusicClient: '木瓜音乐',
  SgogoMusicClient: '搜歌网',
  TwoT58MusicClient: '爱听音乐',
  XiagebaMusicClient: '下歌吧',
  YinyuedaoMusicClient: '音乐岛',
  ZhuolinMusicClient: '音乐解析',
  FiveSongMusicClient: '5Song',
  HTQYYMusicClient: '好听轻音乐',
  ITingWaMusicClient: '听蛙纯音乐',
  XimalayaMusicClient: '喜马拉雅',
  QingtingMusicClient: '蜻蜓FM',
  LizhiMusicClient: '荔枝FM',
  LRTSMusicClient: '懒人听书',
  AppleMusicClient: '苹果音乐',
  ITunesMusicClient: '苹果播客',
  DeezerMusicClient: 'Deezer',
  QobuzMusicClient: 'Qobuz',
  TIDALMusicClient: 'TIDAL',
  SpotifyMusicClient: 'Spotify',
  SoundCloudMusicClient: 'SoundCloud',
  YouTubeMusicClient: '油管音乐',
  SunoMusicClient: 'Suno',
  MOOVMusicClient: '摩音符',
  JamendoMusicClient: '简音乐',
  FMAMusicClient: 'FMA',
  JioSaavnMusicClient: 'JioSaavn',
  OpenGameArtMusicClient: '开源游戏素材',
  WikimediaCommonsMusicClient: '维基共享',
  AudiusMusicClient: 'Audius',
  CCMixterMusicClient: 'ccMixter'
 }
 export function sourceName(code: string): string {
  return SOURCE_NAMES[code] ?? code.replace(/MusicClient$/, '')
 }
 /** 搜索页/设置页展示的常用源（中文平台为主，与已注册源求交后展示） */
 export const PICKER_SOURCES: string[] = [
  'NeteaseMusicClient',
  'QQMusicClient',
  'KugouMusicClient',
  'KuwoMusicClient',
  'MiguMusicClient',
  'QianqianMusicClient',
  'BilibiliMusicClient',
  'SodaMusicClient',
  'StreetVoiceMusicClient',
  'FiveSingMusicClient',
  'BodianMusicClient',
  'MyFreeMP3MusicClient',
  'XiaoBaiMusicClient',
  'JBSouMusicClient',
  'TuneHubMusicClient'
 ]
@@ -1,6 +1,5 @@
 <script setup lang="ts">
 import { ref, computed, onMounted, onUnmounted, nextTick } from 'vue'
 import type { Component } from 'vue'
 import { getCurrentWindow, currentMonitor } from '@tauri-apps/api/window'
 import { LogicalSize } from '@tauri-apps/api/dpi'
 import { emit, listen, type UnlistenFn } from '@tauri-apps/api/event'
@@ -11,7 +10,6 @@ import { commands } from '@/lib/bindings'
 import { save } from '@tauri-apps/plugin-dialog'
 import { toast } from 'vue-sonner'
 import {
  Square, Circle, MoveUpRight, ListOrdered, Pencil, Type, Grid3x3, Highlighter,
  Eraser, Undo2, Redo2, Trash2, Copy, Save, X, Image as ImageIcon,
 } from '@lucide/vue'
 import { Button } from '@/components/ui/button'
@@ -20,43 +18,21 @@ import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover
 import { Slider } from '@/components/ui/slider'
 import { ScrollBar } from '@/components/ui/scroll-area'
 import { ScrollAreaCorner, ScrollAreaRoot, ScrollAreaViewport } from 'reka-ui'
-import { TOOL_KEYS, type CaptureData } from './types'
+import {
  TOOLS, TOOL_KEYS, COLORS, BLOCK_SIZES, ALPHAS, HANDLES,
  type ToolType, type Annotation, type DrawableAnnotation, type Point,
  type RectAnno, type EllipseAnno, type ArrowAnno, type PenAnno, type TextAnno,
  type MosaicAnno, type HighlightAnno, type NumberAnno, type HandleDir,
  type CaptureData,
 } from './types'
 import {
  annoHasColor, annoHasLineWidth, annoBBox, hitTestAnno, hitTestTextZone,
  isAnnoResizable, cloneAnno, applyMove, applyResize, drawSelectionBox,
 } from './annotations'
-// ===== 标注数据结构 =====
+// ===== 标注类型（types.ts 共享，与覆盖层一致） =====
 type ToolType = 'rect' | 'ellipse' | 'arrow' | 'number' | 'pen' | 'text' | 'mosaic' | 'highlight'
-interface Point { x: number; y: number }
+// ===== 工具与选项（types.ts 共享 TOOLS/COLORS 等，与普通截图编辑栏一致） =====
 interface RectAnno { type: 'rect'; x1: number; y1: number; x2: number; y2: number; color: string; lineWidth: number }
 interface EllipseAnno { type: 'ellipse'; x1: number; y1: number; x2: number; y2: number; color: string; lineWidth: number }
 interface ArrowAnno { type: 'arrow'; x1: number; y1: number; x2: number; y2: number; color: string; lineWidth: number }
 interface NumberAnno { type: 'number'; x: number; y: number; n: number; color: string; fontSize: number }
 interface PenAnno { type: 'pen'; points: Point[]; color: string; lineWidth: number }
 interface TextAnno { type: 'text'; x: number; y: number; text: string; color: string; fontSize: number }
 interface MosaicAnno { type: 'mosaic'; x1: number; y1: number; x2: number; y2: number; blockSize: number }
 interface HighlightAnno { type: 'highlight'; x1: number; y1: number; x2: number; y2: number; color: string; alpha: number }
 type Annotation = RectAnno | EllipseAnno | ArrowAnno | NumberAnno | PenAnno | TextAnno | MosaicAnno | HighlightAnno
 /** 可拖拽绘制的标注（不含文字/序号，文字与序号通过点击放置） */
 type DrawableAnnotation = RectAnno | EllipseAnno | ArrowAnno | PenAnno | MosaicAnno | HighlightAnno
 // ===== 工具与选项（与普通截图编辑栏一致） =====
 const TOOLS: { value: ToolType; icon: Component; label: string }[] = [
  { value: 'rect', icon: Square, label: '矩形' },
  { value: 'ellipse', icon: Circle, label: '椭圆' },
  { value: 'arrow', icon: MoveUpRight, label: '箭头' },
  { value: 'number', icon: ListOrdered, label: '序号' },
  { value: 'pen', icon: Pencil, label: '画笔' },
  { value: 'text', icon: Type, label: '文字' },
  { value: 'mosaic', icon: Grid3x3, label: '马赛克' },
  { value: 'highlight', icon: Highlighter, label: '高亮' },
 ]
 /** 与普通截图一致的颜色预设 */
 const COLORS = ['#ef4444', '#f97316', '#eab308', '#22c55e', '#3b82f6', '#a855f7', '#000000', '#ffffff'] as const
 const BLOCK_SIZES = [8, 10, 14] as const
 const ALPHAS = [0.2, 0.4, 0.6] as const
 // ===== 状态 =====
 const canvasRef = ref<HTMLCanvasElement | null>(null)
@@ -89,6 +65,19 @@ let loadUnlisten: UnlistenFn | null = null
 /** 马赛克结果缓存：标注参数不变时跳过重复像素化（长图上拖动其他标注不再卡顿） */
 let mosaicCache: { key: string; canvas: HTMLCanvasElement } | null = null
 /** Canvas 分层：静态层缓存底图 + 已提交标注，动态层只画 draft + 选中框 + 裁剪遮罩。
 *  拖拽/调整标注时每帧只需 drawImage(静态层) + 少量动态元素，长图（数万像素高）不卡顿。 */
 let staticCanvas: HTMLCanvasElement | null = null
 let staticDirty = true
 // 标注选中 / 拖拽 / 调整大小状态（与覆盖层一致）
 const selectedAnnoIdx = ref(-1)
 const draggingAnno = ref(false)
 const resizingAnno = ref(false)
 const annoResizeDir = ref<HandleDir | null>(null)
 const annoDragStart = ref<{ p: Point; orig: Annotation } | null>(null)
 const annoResizeStart = ref<{ p: Point; orig: Annotation } | null>(null)
 // ===== 上下边界裁剪（长图场景，如滚动截图） =====
 /** 保留区上边界（像素，相对图片顶部） */
 const trimTop = ref(0)
@@ -97,32 +86,157 @@ const trimBottom = ref(0)
 /** 正在拖动的裁剪手柄 */
 const trimming = ref<'top' | 'bottom' | null>(null)
-// 文字输入浮层
+// 文字输入浮层（textarea 支持多行）
 const textInputPos = ref<Point | null>(null)
 const textInputValue = ref('')
-const textInputEl = ref<HTMLInputElement | null>(null)
+const textInputEl = ref<HTMLTextAreaElement | null>(null)
 /** 编辑已有文字标注时的索引（-1 = 新建） */
 const editingTextAnnoIdx = ref(-1)
 const fontSizePx = computed(() => currentLineWidth.value * 3 + 14)
 const canUndo = computed(() => annotations.value.length > 0)
 const canRedo = computed(() => redoStack.value.length > 0)
-// ===== 画布重绘 =====
+/** 颜色控件：双用途——选中标注时反映并修改其颜色，否则设置新标注默认色 */
 const effectiveColor = computed<string>({
  get() {
    const i = selectedAnnoIdx.value
    if (i >= 0 && i < annotations.value.length) {
      const a = annotations.value[i]
      if (annoHasColor(a)) return (a as { color: string }).color
    }
    return currentColor.value
  },
  set(v: string) {
    currentColor.value = v
    const i = selectedAnnoIdx.value
    if (i >= 0 && i < annotations.value.length) {
      const a = annotations.value[i]
      if (annoHasColor(a)) {
        (a as { color: string }).color = v
        markDirtyRedraw()
      }
    }
  },
 })
 /** 粗细控件：双用途——选中标注时反映并修改其 lineWidth，否则设置新标注默认粗细 */
 const effectiveLineWidth = computed<number>({
  get() {
    const i = selectedAnnoIdx.value
    if (i >= 0 && i < annotations.value.length) {
      const a = annotations.value[i]
      if (annoHasLineWidth(a)) return (a as { lineWidth: number }).lineWidth
    }
    return currentLineWidth.value
  },
  set(v: number) {
    currentLineWidth.value = v
    const i = selectedAnnoIdx.value
    if (i >= 0 && i < annotations.value.length) {
      const a = annotations.value[i]
      if (annoHasLineWidth(a)) {
        (a as { lineWidth: number }).lineWidth = v
        markDirtyRedraw()
      }
    }
  },
 })
 /** 控件是否可用（颜色/粗细），选中不支持该属性的标注时禁用 */
 const colorEnabled = computed(() => {
  const i = selectedAnnoIdx.value
  if (i < 0 || i >= annotations.value.length) return true
  return annoHasColor(annotations.value[i])
 })
 const lineWidthEnabled = computed(() => {
  const i = selectedAnnoIdx.value
  if (i < 0 || i >= annotations.value.length) return true
  return annoHasLineWidth(annotations.value[i])
 })
 /** 选中标注的 bounding box（画布 1:1 物理坐标，用于手柄定位） */
 const selectedAnnoBBox = computed(() => {
  const i = selectedAnnoIdx.value
  if (i < 0 || i >= annotations.value.length) return null
  return annoBBox(annotations.value[i])
 })
 /** 选中标注是否可调整大小（pen/text/number 仅支持移动） */
 const selectedAnnoResizable = computed(() => {
  const i = selectedAnnoIdx.value
  if (i < 0 || i >= annotations.value.length) return false
  return isAnnoResizable(annotations.value[i])
 })
 /** 文字输入浮层样式（编辑已有文字时用原标注颜色和字号） */
 const textInputStyle = computed(() => {
  const p = textInputPos.value
  if (!p) return {}
  const ei = editingTextAnnoIdx.value
  const anno = ei >= 0 ? annotations.value[ei] : null
  const color = anno && anno.type === 'text' ? anno.color : currentColor.value
  const fs = anno && anno.type === 'text' ? anno.fontSize : fontSizePx.value
  return {
    left: p.x + 'px',
    top: p.y + 'px',
    color,
    fontSize: fs + 'px',
  }
 })
 // ===== 画布重绘（静态层 + 动态层） =====
 /** rAF 节流重绘：鼠标移动事件频率远高于 60fps，合并到下一帧统一重绘 */
 let redrawRaf = 0
 function scheduleRedraw() {
  if (!redrawRaf) {
    redrawRaf = requestAnimationFrame(() => {
      redrawRaf = 0
      redraw()
    })
  }
 }
 /** 标记静态层脏 + rAF 节流重绘（annotations 增删/修改后调用） */
 function markDirtyRedraw() {
  staticDirty = true
  scheduleRedraw()
 }
 /** 重绘静态层（底图 + 已提交标注缓存）。annotations 增删/修改时标记脏。 */
 function redrawStatic() {
  const img = baseImage.value
  if (!img) return
  const canvas = canvasRef.value
  if (!canvas) return
  if (!staticCanvas) staticCanvas = document.createElement('canvas')
  if (staticCanvas.width !== canvas.width || staticCanvas.height !== canvas.height) {
    staticCanvas.width = canvas.width
    staticCanvas.height = canvas.height
  }
  const sctx = staticCanvas.getContext('2d')
  if (!sctx) return
  sctx.clearRect(0, 0, staticCanvas.width, staticCanvas.height)
  // 底图画在静态层：拖动标注时底图零成本复用
  sctx.drawImage(img, 0, 0)
  for (let i = 0; i < annotations.value.length; i++) {
    // 正在编辑的文字标注由 textarea 显示，跳过绘制避免重影
    if (i === editingTextAnnoIdx.value) continue
    drawAnnotation(sctx, annotations.value[i])
  }
  staticDirty = false
 }
 function redraw() {
  const canvas = canvasRef.value
  const img = baseImage.value
  if (!canvas || !img) return
  const ctx = canvas.getContext('2d')
  if (!ctx) return
  if (staticDirty) redrawStatic()
  ctx.clearRect(0, 0, canvas.width, canvas.height)
  // 白色背景填充透明区
  ctx.fillStyle = '#ffffff'
  ctx.fillRect(0, 0, canvas.width, canvas.height)
-  // 底图
+  // 静态层合成（O(1) drawImage，跳过遍历所有标注）
-  ctx.drawImage(img, 0, 0)
+  if (staticCanvas) ctx.drawImage(staticCanvas, 0, 0)
  // 已提交标注
  for (const anno of annotations.value) {
    drawAnnotation(ctx, anno)
  }
  // 进行中的草稿
  if (draft.value) {
    if (draft.value.type === 'mosaic') {
@@ -139,6 +253,11 @@ function redraw() {
    if (top > 0) ctx.fillRect(0, 0, canvas.width, top)
    if (bottom < canvas.height) ctx.fillRect(0, bottom, canvas.width, canvas.height - bottom)
  }
  // 选中标注：绘制虚线边框（手柄用 CSS DOM 定位，便于点击）
  const si = selectedAnnoIdx.value
  if (si >= 0 && si < annotations.value.length) {
    drawSelectionBox(ctx, annoBBox(annotations.value[si]))
  }
 }
 function drawAnnotation(ctx: CanvasRenderingContext2D, anno: Annotation) {
@@ -230,7 +349,10 @@ function drawText(ctx: CanvasRenderingContext2D, a: TextAnno) {
  ctx.font = `${a.fontSize}px sans-serif`
  ctx.fillStyle = a.color
  ctx.textBaseline = 'top'
-  ctx.fillText(a.text, a.x, a.y)
+  const lines = a.text.split('\n')
  lines.forEach((line, i) => {
    ctx.fillText(line, a.x, a.y + i * a.fontSize)
  })
 }
 function drawHighlight(ctx: CanvasRenderingContext2D, a: HighlightAnno) {
@@ -240,36 +362,54 @@ function drawHighlight(ctx: CanvasRenderingContext2D, a: HighlightAnno) {
  ctx.globalAlpha = 1
 }
-/** 对区域做像素化（马赛克）：取块平均色填回。
+/** 马赛克 tmp 画布（复用，避免拖拽中反复创建） */
- *  缓存：同一标注参数（位置/尺寸/块大小）重复 redraw 时直接 drawImage 复用，
+let mosaicTmp: HTMLCanvasElement | null = null
- *  避免长图上每次重绘都重新 getImageData + 像素化。 */
+function getMosaicTmp(): HTMLCanvasElement {
  if (!mosaicTmp) mosaicTmp = document.createElement('canvas')
  return mosaicTmp
 }
 /**
 * 马赛克：从**底图**取区域像素做块平均（与覆盖层一致）。
 * 从底图而非画布取：画布上已绘制的其他标注不会被二次像素化；
 * 且缓存命中时拖动其他标注零像素化开销（长图不卡顿）。
 */
 function applyMosaic(ctx: CanvasRenderingContext2D, a: MosaicAnno) {
-  const canvas = ctx.canvas
+  const img = baseImage.value
  if (!img) return
  const block = Math.max(1, a.blockSize)
-  const sx = Math.max(0, Math.floor(Math.min(a.x1, a.x2)))
+  const x1 = Math.min(a.x1, a.x2)
-  const sy = Math.max(0, Math.floor(Math.min(a.y1, a.y2)))
+  const y1 = Math.min(a.y1, a.y2)
-  const sw = Math.min(canvas.width - sx, Math.floor(Math.abs(a.x2 - a.x1)))
+  const w = Math.abs(a.x2 - a.x1)
-  const sh = Math.min(canvas.height - sy, Math.floor(Math.abs(a.y2 - a.y1)))
+  const h = Math.abs(a.y2 - a.y1)
-  if (sw <= 0 || sh <= 0) return
+  if (w < 1 || h < 1) return
-  const cacheKey = `${sx},${sy},${sw},${sh},${block}`
+  const cw = Math.min(Math.ceil(w), img.naturalWidth - Math.floor(x1))
  const ch = Math.min(Math.ceil(h), img.naturalHeight - Math.floor(y1))
  if (cw < 1 || ch < 1) return
  const cacheKey = `${a.x1},${a.y1},${a.x2},${a.y2},${block}`
  if (mosaicCache?.key === cacheKey) {
-    ctx.drawImage(mosaicCache.canvas, sx, sy)
+    ctx.drawImage(mosaicCache.canvas, Math.floor(x1), Math.floor(y1))
    return
  }
-  const imageData = ctx.getImageData(sx, sy, sw, sh)
+  const tmp = getMosaicTmp()
  tmp.width = cw
  tmp.height = ch
  const tctx = tmp.getContext('2d')
  if (!tctx) return
  tctx.drawImage(img, Math.floor(x1), Math.floor(y1), cw, ch, 0, 0, cw, ch)
  const imageData = tctx.getImageData(0, 0, cw, ch)
  const data = imageData.data
-  for (let by = 0; by < sh; by += block) {
+  for (let by = 0; by < ch; by += block) {
-    for (let bx = 0; bx < sw; bx += block) {
+    for (let bx = 0; bx < cw; bx += block) {
-      let r = 0, g = 0, b = 0, alpha = 0, count = 0
+      let r = 0, g = 0, b = 0, count = 0
-      const maxJ = Math.min(by + block, sh)
+      const maxJ = Math.min(by + block, ch)
-      const maxI = Math.min(bx + block, sw)
+      const maxI = Math.min(bx + block, cw)
      for (let j = by; j < maxJ; j++) {
        for (let i = bx; i < maxI; i++) {
-          const idx = (j * sw + i) * 4
+          const idx = (j * cw + i) * 4
          r += data[idx]
          g += data[idx + 1]
          b += data[idx + 2]
          alpha += data[idx + 3]
          count++
        }
      }
@@ -277,25 +417,25 @@ function applyMosaic(ctx: CanvasRenderingContext2D, a: MosaicAnno) {
      r = Math.round(r / count)
      g = Math.round(g / count)
      b = Math.round(b / count)
      alpha = Math.round(alpha / count)
      for (let j = by; j < maxJ; j++) {
        for (let i = bx; i < maxI; i++) {
-          const idx = (j * sw + i) * 4
+          const idx = (j * cw + i) * 4
          data[idx] = r
          data[idx + 1] = g
          data[idx + 2] = b
-          data[idx + 3] = alpha
+          data[idx + 3] = 255
        }
      }
    }
  }
-  ctx.putImageData(imageData, sx, sy)
+  tctx.putImageData(imageData, 0, 0)
-  // 缓存像素化结果（undo/redo/清空/新图加载时失效）
+  // 缓存结果（undo/redo/清空/新图加载时失效）
  const cached = document.createElement('canvas')
-  cached.width = sw
+  cached.width = cw
-  cached.height = sh
+  cached.height = ch
-  cached.getContext('2d')?.putImageData(imageData, 0, 0)
+  cached.getContext('2d')?.drawImage(tmp, 0, 0)
  mosaicCache = { key: cacheKey, canvas: cached }
  ctx.drawImage(cached, Math.floor(x1), Math.floor(y1))
 }
 /** 马赛克拖拽中的虚线框预览（避免每帧像素化开销） */
@@ -307,23 +447,88 @@ function drawMosaicDraft(ctx: CanvasRenderingContext2D, a: MosaicAnno) {
  ctx.setLineDash([])
 }
-// ===== 鼠标交互 =====
+// ===== 鼠标交互（与覆盖层一致：选中 / 拖拽 / 调整大小 / 绘制） =====
 function getPoint(e: MouseEvent): Point {
  const canvas = canvasRef.value!
  const rect = canvas.getBoundingClientRect()
  const scaleX = canvas.width / rect.width
  const scaleY = canvas.height / rect.height
-  return { x: (e.clientX - rect.left) * scaleX, y: (e.clientY - rect.top) * scaleY }
+  return {
    x: Math.min(canvas.width, Math.max(0, (e.clientX - rect.left) * scaleX)),
    y: Math.min(canvas.height, Math.max(0, (e.clientY - rect.top) * scaleY)),
  }
 }
 /** 标注手柄位置（画布 1:1，物理坐标 = CSS 偏移） */
 function annoHandleStyle(dir: HandleDir) {
  const bb = selectedAnnoBBox.value
  if (!bb) return { display: 'none' }
  let cx = 0
  let cy = 0
  switch (dir) {
    case 'nw': cx = bb.x; cy = bb.y; break
    case 'n': cx = bb.x + bb.w / 2; cy = bb.y; break
    case 'ne': cx = bb.x + bb.w; cy = bb.y; break
    case 'e': cx = bb.x + bb.w; cy = bb.y + bb.h / 2; break
    case 'se': cx = bb.x + bb.w; cy = bb.y + bb.h; break
    case 's': cx = bb.x + bb.w / 2; cy = bb.y + bb.h; break
    case 'sw': cx = bb.x; cy = bb.y + bb.h; break
    case 'w': cx = bb.x; cy = bb.y + bb.h / 2; break
  }
  return { left: cx + 'px', top: cy + 'px' }
 }
 /** 标注手柄按下：进入调整大小模式 */
 function onAnnoHandleMouseDown(dir: HandleDir, e: MouseEvent) {
  if (selectedAnnoIdx.value < 0) return
  e.preventDefault()
  e.stopPropagation()
  const p = getPoint(e)
  const cur = annotations.value[selectedAnnoIdx.value]
  if (!cur) return
  resizingAnno.value = true
  annoResizeDir.value = dir
  annoResizeStart.value = { p: { ...p }, orig: cloneAnno(cur) }
 }
 function onMouseDown(e: MouseEvent) {
  if (!baseImage.value || !loaded.value) return
-  const p = getPoint(e)
+  // 文字工具：阻止 mousedown 默认行为，防止浏览器抢占焦点导致 textarea 立即失焦
  if (currentTool.value === 'text') {
-    startTextInput(p)
+    e.preventDefault()
  }
  const p = getPoint(e)
  // 点击已有标注 → 选中并进入拖拽模式
  const idx = hitTestAnno(annotations.value, p)
  if (idx >= 0) {
    // 先提交未完成的文字输入（点击别处放置/选中时，旧输入框提交）
    if (textInputPos.value) commitText()
    // 文字工具 + 点击文字标注：内容区→编辑，边框区→移动
    if (currentTool.value === 'text' && annotations.value[idx].type === 'text') {
      const zone = hitTestTextZone(annotations.value[idx] as TextAnno, p)
      if (zone === 'core') {
        openTextInput(p, idx)
        return
      }
-  // 序号：点击即放置（自增），不进入拖拽
+      // border → 选中并拖拽（移动），继续往下走
    }
    selectedAnnoIdx.value = idx
    draggingAnno.value = true
    annoDragStart.value = { p: { ...p }, orig: cloneAnno(annotations.value[idx]) }
    markDirtyRedraw()
    return
  }
  // 点击空白处 → 取消选中，开始绘制新标注
  selectedAnnoIdx.value = -1
  beginDraft(p)
 }
 function beginDraft(p: Point) {
  if (currentTool.value === 'text') {
    openTextInput(p)
    return
  }
  // 序号：点击即放置（自增），不进入拖拽；放置后自动选中便于移动
  if (currentTool.value === 'number') {
    annotations.value.push({
      type: 'number',
@@ -335,45 +540,61 @@ function onMouseDown(e: MouseEvent) {
    })
    numberSeq.value++
    redoStack.value = []
-    redraw()
+    selectedAnnoIdx.value = annotations.value.length - 1
    markDirtyRedraw()
    return
  }
  isDrawing.value = true
  const color = currentColor.value
  const lw = currentLineWidth.value
  switch (currentTool.value) {
    case 'rect':
-      draft.value = { type: 'rect', x1: p.x, y1: p.y, x2: p.x, y2: p.y, color: currentColor.value, lineWidth: currentLineWidth.value }
+      draft.value = { type: 'rect', x1: p.x, y1: p.y, x2: p.x, y2: p.y, color, lineWidth: lw }
      break
    case 'ellipse':
-      draft.value = { type: 'ellipse', x1: p.x, y1: p.y, x2: p.x, y2: p.y, color: currentColor.value, lineWidth: currentLineWidth.value }
+      draft.value = { type: 'ellipse', x1: p.x, y1: p.y, x2: p.x, y2: p.y, color, lineWidth: lw }
      break
    case 'arrow':
-      draft.value = { type: 'arrow', x1: p.x, y1: p.y, x2: p.x, y2: p.y, color: currentColor.value, lineWidth: currentLineWidth.value }
+      draft.value = { type: 'arrow', x1: p.x, y1: p.y, x2: p.x, y2: p.y, color, lineWidth: lw }
      break
    case 'pen':
-      draft.value = { type: 'pen', points: [p], color: currentColor.value, lineWidth: currentLineWidth.value }
+      draft.value = { type: 'pen', points: [p], color, lineWidth: lw }
      break
    case 'mosaic':
      draft.value = { type: 'mosaic', x1: p.x, y1: p.y, x2: p.x, y2: p.y, blockSize: blockSize.value }
      break
    case 'highlight':
-      draft.value = { type: 'highlight', x1: p.x, y1: p.y, x2: p.x, y2: p.y, color: currentColor.value, alpha: highlightAlpha.value }
+      draft.value = { type: 'highlight', x1: p.x, y1: p.y, x2: p.x, y2: p.y, color, alpha: highlightAlpha.value }
      break
  }
-  redraw()
+  scheduleRedraw()
 }
 // ===== 画布重绘（rAF 节流） =====
 /** 连续鼠标移动时每帧最多重绘一次，避免 mousemove 高频事件（每帧多次）触发多次全量重绘 */
 let redrawRaf = 0
 function scheduleRedraw() {
  if (redrawRaf) return
  redrawRaf = requestAnimationFrame(() => {
    redrawRaf = 0
    redraw()
  })
 }
 function onMouseMove(e: MouseEvent) {
  if (resizingAnno.value && annoResizeStart.value) {
    // 调整选中标注大小
    const p = getPoint(e)
    const dx = p.x - annoResizeStart.value.p.x
    const dy = p.y - annoResizeStart.value.p.y
    const cur = annotations.value[selectedAnnoIdx.value]
    if (cur && annoResizeDir.value) {
      applyResize(cur, annoResizeStart.value.orig, annoResizeDir.value, dx, dy)
      markDirtyRedraw()
    }
    return
  }
  if (draggingAnno.value && annoDragStart.value) {
    // 移动选中标注
    const p = getPoint(e)
    const dx = p.x - annoDragStart.value.p.x
    const dy = p.y - annoDragStart.value.p.y
    const cur = annotations.value[selectedAnnoIdx.value]
    if (cur) {
      applyMove(cur, annoDragStart.value.orig, dx, dy)
      markDirtyRedraw()
    }
    return
  }
  if (!isDrawing.value || !draft.value) return
  const p = getPoint(e)
  const d = draft.value
@@ -387,6 +608,19 @@ function onMouseMove(e: MouseEvent) {
 }
 function onMouseUp() {
  if (resizingAnno.value) {
    // 调整大小结束
    resizingAnno.value = false
    annoResizeDir.value = null
    annoResizeStart.value = null
    return
  }
  if (draggingAnno.value) {
    // 拖拽结束（点击未移动时保持选中）
    draggingAnno.value = false
    annoDragStart.value = null
    return
  }
  if (!isDrawing.value || !draft.value) return
  const d = draft.value
  // 过滤无效（空）标注
@@ -399,10 +633,14 @@ function onMouseUp() {
  if (valid) {
    annotations.value.push(d)
    redoStack.value = []
    // 自动选中新创建的标注，便于立即调整位置和大小
    selectedAnnoIdx.value = annotations.value.length - 1
  } else {
    selectedAnnoIdx.value = -1
  }
  draft.value = null
  isDrawing.value = false
-  redraw()
+  markDirtyRedraw()
 }
 // ===== 上下边界裁剪拖拽 =====
@@ -422,7 +660,7 @@ function onTrimMove(e: MouseEvent) {
  } else {
    trimBottom.value = Math.max(trimTop.value + 10, Math.min(Math.round(p.y), h))
  }
-  redraw()
+  scheduleRedraw()
 }
 function onTrimUp() {
@@ -431,11 +669,30 @@ function onTrimUp() {
  window.removeEventListener('mouseup', onTrimUp)
 }
-// ===== 文字输入 =====
+// ===== 文字输入（textarea 多行，与覆盖层一致） =====
-function startTextInput(p: Point) {
+function openTextInput(p: Point, editIdx: number = -1) {
-  textInputPos.value = { x: p.x, y: p.y }
+  // 先提交当前未完成的文字（点击别处放置新文字时，旧输入框会失焦）
  commitText()
  if (editIdx >= 0 && editIdx < annotations.value.length) {
    const anno = annotations.value[editIdx]
    if (anno && anno.type === 'text') {
      editingTextAnnoIdx.value = editIdx
      textInputPos.value = { x: anno.x, y: anno.y }
      textInputValue.value = anno.text
      markDirtyRedraw() // 隐藏原文字，由 textarea 显示
      nextTick(() => {
        textInputEl.value?.focus()
        autoResizeTextarea()
      })
      return
    }
  }
  textInputPos.value = p
  textInputValue.value = ''
-  nextTick(() => textInputEl.value?.focus())
+  nextTick(() => {
    textInputEl.value?.focus()
    autoResizeTextarea()
  })
 }
 function commitText() {
@@ -444,6 +701,26 @@ function commitText() {
  textInputPos.value = null
  const value = textInputValue.value.trim()
  textInputValue.value = ''
  const editIdx = editingTextAnnoIdx.value
  editingTextAnnoIdx.value = -1
  // 编辑已有文字标注
  if (editIdx >= 0 && editIdx < annotations.value.length) {
    const anno = annotations.value[editIdx]
    if (anno && anno.type === 'text') {
      if (value) {
        anno.text = value
        selectedAnnoIdx.value = editIdx
      } else {
        // 空文字 → 删除
        annotations.value.splice(editIdx, 1)
        selectedAnnoIdx.value = -1
        redoStack.value = []
      }
      markDirtyRedraw()
    }
    return
  }
  // 新建文字标注
  if (value) {
    annotations.value.push({
      type: 'text',
@@ -454,13 +731,37 @@ function commitText() {
      fontSize: fontSizePx.value,
    })
    redoStack.value = []
-    redraw()
+    // 自动选中新创建的文字
    selectedAnnoIdx.value = annotations.value.length - 1
    markDirtyRedraw()
  }
 }
 function cancelText() {
  textInputPos.value = null
  textInputValue.value = ''
  editingTextAnnoIdx.value = -1
  markDirtyRedraw() // 恢复显示原文字标注
 }
 /** 自动调整 textarea 高度以适应内容 */
 function autoResizeTextarea() {
  const el = textInputEl.value
  if (!el) return
  el.style.height = 'auto'
  el.style.height = el.scrollHeight + 'px'
 }
 // ===== 删除选中标注 =====
 function deleteSelectedAnno() {
  const i = selectedAnnoIdx.value
  if (i < 0 || i >= annotations.value.length) return
  const a = annotations.value[i]
  if (a.type === 'number') numberSeq.value = Math.max(1, numberSeq.value - 1)
  annotations.value.splice(i, 1)
  selectedAnnoIdx.value = -1
  redoStack.value = []
  markDirtyRedraw()
 }
 // ===== 撤销 / 重做 / 清空 =====
@@ -470,8 +771,10 @@ function undo() {
  redoStack.value.push(last)
  // 撤销序号标注后回退序号，避免后续新增序号跳号
  if (last.type === 'number') numberSeq.value = Math.max(1, numberSeq.value - 1)
  // 撤销后选中可能失效，重置
  if (selectedAnnoIdx.value >= annotations.value.length) selectedAnnoIdx.value = -1
  mosaicCache = null
-  redraw()
+  markDirtyRedraw()
 }
 function redo() {
@@ -479,16 +782,18 @@ function redo() {
  const a = redoStack.value.pop()!
  annotations.value.push(a)
  if (a.type === 'number') numberSeq.value = a.n + 1
  selectedAnnoIdx.value = -1
  mosaicCache = null
-  redraw()
+  markDirtyRedraw()
 }
 function clearAll() {
  annotations.value = []
  redoStack.value = []
  numberSeq.value = 1
  selectedAnnoIdx.value = -1
  mosaicCache = null
-  redraw()
+  markDirtyRedraw()
 }
 // ===== 导出 =====
@@ -589,7 +894,16 @@ async function closeWindow() {
  isDrawing.value = false
  annotations.value = []
  redoStack.value = []
  selectedAnnoIdx.value = -1
  draggingAnno.value = false
  resizingAnno.value = false
  annoDragStart.value = null
  annoResizeStart.value = null
  editingTextAnnoIdx.value = -1
  textInputPos.value = null
  mosaicCache = null
  mosaicTmp = null
  staticDirty = true
  if (objectUrl) {
    URL.revokeObjectURL(objectUrl)
    objectUrl = ''
@@ -623,10 +937,10 @@ function onStorageChange(e: StorageEvent) {
  if (e.key === STORAGE_KEYS.appSettings) applyTheme()
 }
-/** 自定义颜色选择：更新 customColor 并设为当前颜色 */
+/** 自定义颜色选择：更新 customColor 并设为当前颜色/选中标注颜色 */
 function onCustomColorPick(color: string) {
  customColor.value = color
-  currentColor.value = color
+  effectiveColor.value = color
 }
 /**
@@ -657,6 +971,17 @@ function onKeyDown(e: KeyboardEvent) {
  // 输入控件（文字标注 / 取色器 / 滑杆）聚焦时不响应快捷键
  const t = e.target as HTMLElement | null
  if (t && (t.tagName === 'INPUT' || t.tagName === 'TEXTAREA' || t.isContentEditable)) return
  // 文字输入浮层激活时：Ctrl+Enter 提交，Esc 取消（普通 Enter 留给 textarea 换行）
  if (textInputPos.value) {
    if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
      e.preventDefault()
      commitText()
    } else if (e.key === 'Escape') {
      e.stopPropagation()
      cancelText()
    }
    return
  }
  const k = e.key.toLowerCase()
  const mod = e.ctrlKey || e.metaKey
  if (mod && !e.shiftKey && k === 'z') {
@@ -679,6 +1004,12 @@ function onKeyDown(e: KeyboardEvent) {
    void saveToFile()
    return
  }
  // Delete/Backspace 删除选中的标注
  if ((e.key === 'Delete' || e.key === 'Backspace') && selectedAnnoIdx.value >= 0) {
    e.preventDefault()
    deleteSelectedAnno()
    return
  }
  if (k === 'enter') {
    e.preventDefault()
    void copyAndClose()
@@ -686,7 +1017,13 @@ function onKeyDown(e: KeyboardEvent) {
  }
  if (k === 'escape') {
    e.preventDefault()
    // 选中状态下 Esc 先取消选中，再次按才关闭窗口（与覆盖层一致）
    if (selectedAnnoIdx.value >= 0) {
      selectedAnnoIdx.value = -1
      markDirtyRedraw()
    } else {
      void closeWindow()
    }
    return
  }
  if (!mod && !e.altKey) {
@@ -723,6 +1060,14 @@ async function loadPendingImage() {
    isDrawing.value = false
    numberSeq.value = 1
    mosaicCache = null
    staticDirty = true
    selectedAnnoIdx.value = -1
    draggingAnno.value = false
    resizingAnno.value = false
    annoDragStart.value = null
    annoResizeStart.value = null
    editingTextAnnoIdx.value = -1
    textInputPos.value = null
    loadError.value = false
    trimTop.value = 0
    trimBottom.value = img.naturalHeight
@@ -825,13 +1170,15 @@ onUnmounted(() => {
      <div class="h-6 w-px bg-border" />
-      <!-- 颜色：当前色 badge + 弹层（自定义取色 + 默认色板），与普通截图一致 -->
+      <!-- 颜色：当前色 badge + 弹层（双用途：选中标注时修改其颜色），与普通截图一致 -->
      <Popover v-model:open="colorPickerOpen">
        <PopoverTrigger as-child>
          <button
            class="color-badge"
-            :style="{ '--swatch-color': currentColor }"
+            :class="{ disabled: !colorEnabled }"
-            :aria-label="'当前颜色 ' + currentColor"
+            :style="{ '--swatch-color': effectiveColor }"
            :aria-label="'当前颜色 ' + effectiveColor"
            :disabled="!colorEnabled"
          />
        </PopoverTrigger>
        <PopoverContent class="w-auto p-3" align="start">
@@ -847,9 +1194,9 @@ onUnmounted(() => {
                <TooltipTrigger as-child>
                  <button
                    class="color-swatch-mini"
-                    :class="{ active: currentColor === c }"
+                    :class="{ active: effectiveColor === c }"
                    :style="{ backgroundColor: c }"
-                    @click="currentColor = c"
+                    @click="effectiveColor = c"
                  />
                </TooltipTrigger>
                <TooltipContent>{{ c }}</TooltipContent>
@@ -859,24 +1206,25 @@ onUnmounted(() => {
        </PopoverContent>
      </Popover>
-      <!-- 粗细 badge + 弹层（Slider），与普通截图一致 -->
+      <!-- 粗细 badge + 弹层（双用途：选中标注时修改其粗细），与普通截图一致 -->
      <Popover v-model:open="widthPickerOpen">
        <PopoverTrigger as-child>
-          <button class="width-badge">{{ currentLineWidth }}</button>
+          <button class="width-badge" :class="{ disabled: !lineWidthEnabled }" :disabled="!lineWidthEnabled">{{ effectiveLineWidth }}</button>
        </PopoverTrigger>
        <PopoverContent class="w-auto p-3" align="start">
          <div class="width-popover">
            <div class="width-popover-header">
              <span>粗细</span>
-              <span class="width-popover-value">{{ currentLineWidth }}</span>
+              <span class="width-popover-value">{{ effectiveLineWidth }}</span>
            </div>
            <Slider
-              :model-value="[currentLineWidth]"
+              :model-value="[effectiveLineWidth]"
              :min="1"
              :max="16"
              :step="1"
              :disabled="!lineWidthEnabled"
              class="width-slider"
-              @update:model-value="(v: number[] | undefined) => { if (v && v.length) currentLineWidth = v[0] }"
+              @update:model-value="(v: number[] | undefined) => { if (v && v.length) effectiveLineWidth = v[0] }"
            />
          </div>
        </PopoverContent>
@@ -1009,7 +1357,7 @@ onUnmounted(() => {
        <canvas
          ref="canvasRef"
          class="block max-w-none select-none"
-          :style="{ cursor: currentTool === 'text' ? 'text' : 'crosshair' }"
+          :style="{ cursor: draggingAnno || resizingAnno ? 'move' : currentTool === 'text' ? 'text' : 'crosshair' }"
          @mousedown="onMouseDown"
        />
        <!-- 上下边界裁剪手柄（拖动调整保留区，导出按此裁切） -->
@@ -1027,25 +1375,31 @@ onUnmounted(() => {
        >
          <span class="trim-grip">下 {{ Math.round(trimBottom) }}</span>
        </div>
-        <input
+        <!-- 选中标注的调整手柄（画布 1:1，物理坐标直接定位；pen/text/number 仅移动不显示） -->
        <template v-if="selectedAnnoIdx >= 0 && selectedAnnoResizable">
          <div
            v-for="dir in HANDLES"
            :key="'anno-h-' + dir"
            class="anno-handle"
            :class="'handle-' + dir"
            :style="annoHandleStyle(dir)"
            @mousedown.stop.prevent="onAnnoHandleMouseDown(dir, $event)"
          />
        </template>
        <!-- 文字输入浮层：textarea 支持多行，Ctrl+Enter 提交 / Esc 取消 / blur 提交 -->
        <textarea
          v-if="textInputPos"
          id="screenshot-editor-text-input"
          ref="textInputEl"
          v-model="textInputValue"
-          class="absolute z-10 bg-transparent outline-none"
+          class="absolute z-10 bg-transparent outline-none resize-none overflow-hidden"
-          :style="{
+          :style="textInputStyle"
-            left: textInputPos.x + 'px',
+          placeholder="输入文字 (Ctrl+Enter 完成)"
-            top: textInputPos.y + 'px',
+          rows="1"
-            color: currentColor,
+          @keydown.enter.ctrl.prevent="commitText"
-            fontSize: fontSizePx + 'px',
+          @keydown.esc.stop.prevent="cancelText"
            fontFamily: 'sans-serif',
            lineHeight: '1',
            padding: '0 2px',
            border: '1px dashed ' + currentColor,
          }"
          placeholder="输入文字"
          @keydown.enter.prevent="commitText"
          @keydown.esc.prevent="cancelText"
          @blur="commitText"
          @input="autoResizeTextarea"
        />
        </div>
      </div>
@@ -1074,6 +1428,48 @@ onUnmounted(() => {
 </template>
 <style scoped>
 /* 文字输入浮层：textarea 多行（与覆盖层 .text-input 一致） */
 #screenshot-editor-text-input {
  position: absolute;
  z-index: 10;
  background: transparent;
  outline: none;
  border: 1px dashed currentColor;
  font-family: sans-serif;
  line-height: 1;
  padding: 0 2px;
  min-width: 20px;
  resize: none;
  overflow: hidden;
  white-space: pre;
  word-break: keep-all;
  box-sizing: border-box;
  height: auto;
 }
 /* 标注调整手柄（与覆盖层 .handle 一致；画布 1:1，物理坐标直接定位） */
 .anno-handle {
  position: absolute;
  width: 9px;
  height: 9px;
  background: #fff;
  border: 2px solid #3b82f6;
  border-radius: 2px;
  transform: translate(-50%, -50%);
  z-index: 15;
 }
 .handle-nw, .handle-se { cursor: nwse-resize; }
 .handle-ne, .handle-sw { cursor: nesw-resize; }
 .handle-n, .handle-s { cursor: ns-resize; }
 .handle-e, .handle-w { cursor: ew-resize; }
 /* badge 禁用态（选中不支持该属性的标注时） */
 .color-badge.disabled, .width-badge.disabled {
  opacity: 0.4;
  cursor: not-allowed;
 }
 .color-badge.disabled:hover { transform: none; }
 /* 上下边界裁剪手柄：跨画布宽度的可拖拽蓝线 + 居中数值标签 */
 .trim-bar {
  position: absolute;
@@ -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'
@@ -20,6 +21,10 @@ import {
  type MosaicAnno, type HighlightAnno, type NumberAnno,
  type ScreenshotBeginPayload,
 } from './types'
 import {
  annoHasColor, annoHasLineWidth, annoBBox, hitTestAnno, hitTestTextZone,
  isAnnoResizable, cloneAnno, applyMove, applyResize, drawSelectionBox,
 } from './annotations'
 // ===== 窗口 / 底图 =====
 const win = getCurrentWindow()
@@ -129,7 +134,6 @@ const resizingAnno = ref(false)
 const annoResizeDir = ref<HandleDir | null>(null)
 const annoDragStart = ref<{ p: Point; orig: Annotation } | null>(null)
 const annoResizeStart = ref<{ p: Point; orig: Annotation } | null>(null)
 let measureCtx: CanvasRenderingContext2D | null = null
 /** Canvas 分层：静态层缓存已提交标注，动态层只画 draft + 选中框。
 *  绘制 draft（画笔/矩形等）时 annotations 不变，只需 drawImage(静态层) + draft，O(1) 合成。 */
@@ -208,18 +212,9 @@ const canUndo = computed(() => annotations.value.length > 0)
 const canRedo = computed(() => redoStack.value.length > 0)
 const fontSizePx = computed(() => currentLineWidth.value * 3 + 14)
-/** 选中标注是否有可变颜色属性 */
+/** 选中标注是否有可变颜色属性 / 粗细概念：见 annotations.ts 共享实现 */
 function annoHasColor(a: Annotation): boolean {
  return a.type !== 'mosaic'
 }
 /** 选中标注是否有粗细概念（lineWidth） */
 function annoHasLineWidth(a: Annotation): boolean {
  return a.type === 'rect' || a.type === 'ellipse' || a.type === 'arrow' || a.type === 'pen'
 }
-/**
+/** 颜色控件：双用途——选中标注时反映并修改其颜色，否则设置新标注默认色 */
 * 颜色控件：双用途——选中标注时反映并修改其颜色，否则设置新标注默认色
 */
 const effectiveColor = computed<string>({
  get() {
    const i = selectedAnnoIdx.value
@@ -819,7 +814,7 @@ function onRegionMouseDown(e: MouseEvent) {
    }
    const p = canvasPoint(e)
    // 点击已有标注 → 选中并进入拖拽模式
-    const idx = hitTestAnno(p)
+    const idx = hitTestAnno(annotations.value, p)
    if (idx >= 0) {
      // 先提交未完成的文字输入（点击别处放置/选中时，旧输入框提交）
      if (textInputPos.value) commitText()
@@ -1333,220 +1328,8 @@ function drawMosaicDraft(ctx: CanvasRenderingContext2D, a: MosaicAnno) {
 }
 // ===== 标注选中 / 编辑 =====
-/** 获取文字测量用的 canvas 上下文（惰性创建一次复用） */
+// 几何 / 命中 / 变换纯函数已抽到 annotations.ts，与编辑器共用，
-function getMeasureCtx(): CanvasRenderingContext2D | null {
+// 保证两处对同一标注数据的选中、拖拽、调整大小行为一致。
  if (!measureCtx) {
    const c = document.createElement('canvas')
    measureCtx = c.getContext('2d')
  }
  return measureCtx
 }
 /** 估算文字宽高（用 ctx.measureText 测宽，多行取最宽行，高 = 行数 × fontSize）
 *  结果缓存：相同 text+fontSize 的测量结果不变，避免 hitTest / annoBBox 重复调用开销 */
 const measureCache = new Map<string, { w: number; h: number }>()
 function measureText(text: string, fontSize: number): { w: number; h: number } {
  const key = `${fontSize}\0${text}`
  const cached = measureCache.get(key)
  if (cached) return cached
  const ctx = getMeasureCtx()
  const lines = text.split('\n')
  let result: { w: number; h: number }
  if (!ctx) {
    const maxLen = Math.max(1, ...lines.map(l => l.length))
    result = { w: fontSize * maxLen * 0.6, h: fontSize * lines.length }
  } else {
    ctx.font = `${fontSize}px sans-serif`
    let maxW = 0
    for (const line of lines) {
      const m = ctx.measureText(line)
      if (m.width > maxW) maxW = m.width
    }
    result = { w: Math.ceil(maxW), h: fontSize * lines.length }
  }
  measureCache.set(key, result)
  return result
 }
 /** 标注 bounding box（物理像素坐标） */
 function annoBBox(anno: Annotation): { x: number; y: number; w: number; h: number } {
  switch (anno.type) {
    case 'rect':
    case 'ellipse':
    case 'mosaic':
    case 'highlight':
    case 'arrow': {
      const x = Math.min(anno.x1, anno.x2)
      const y = Math.min(anno.y1, anno.y2)
      return { x, y, w: Math.abs(anno.x2 - anno.x1), h: Math.abs(anno.y2 - anno.y1) }
    }
    case 'pen': {
      if (anno.points.length === 0) return { x: 0, y: 0, w: 0, h: 0 }
      let minX = Infinity
      let minY = Infinity
      let maxX = -Infinity
      let maxY = -Infinity
      for (const pt of anno.points) {
        if (pt.x < minX) minX = pt.x
        if (pt.y < minY) minY = pt.y
        if (pt.x > maxX) maxX = pt.x
        if (pt.y > maxY) maxY = pt.y
      }
      return { x: minX, y: minY, w: maxX - minX, h: maxY - minY }
    }
    case 'text': {
      const { w, h } = measureText(anno.text, anno.fontSize)
      return { x: anno.x, y: anno.y, w, h }
    }
    case 'number': {
      const r = anno.fontSize / 2
      return { x: anno.x - r, y: anno.y - r, w: anno.fontSize, h: anno.fontSize }
    }
  }
 }
 /** 点到线段的距离 */
 function distToSegment(p: Point, a: Point, b: Point): number {
  const dx = b.x - a.x
  const dy = b.y - a.y
  const len2 = dx * dx + dy * dy
  if (len2 === 0) return Math.hypot(p.x - a.x, p.y - a.y)
  let t = ((p.x - a.x) * dx + (p.y - a.y) * dy) / len2
  t = Math.max(0, Math.min(1, t))
  const cx = a.x + t * dx
  const cy = a.y + t * dy
  return Math.hypot(p.x - cx, p.y - cy)
 }
 /** 文字标注区域检测：core=文字内容区(编辑)，border=边框区(移动)，null=未命中 */
 function hitTestTextZone(anno: TextAnno, p: Point): 'core' | 'border' | null {
  const { w, h } = measureText(anno.text, anno.fontSize)
  const x1 = anno.x, y1 = anno.y
  const x2 = anno.x + w, y2 = anno.y + h
  const pad = 8
  if (p.x < x1 - pad || p.x > x2 + pad || p.y < y1 - pad || p.y > y2 + pad) return null
  if (p.x >= x1 && p.x <= x2 && p.y >= y1 && p.y <= y2) return 'core'
  return 'border'
 }
 /** 点击测试单个标注 */
 function hitTestSingle(anno: Annotation, p: Point): boolean {
  switch (anno.type) {
    case 'rect':
    case 'ellipse':
    case 'mosaic':
    case 'highlight': {
      const x1 = Math.min(anno.x1, anno.x2)
      const y1 = Math.min(anno.y1, anno.y2)
      const x2 = Math.max(anno.x1, anno.x2)
      const y2 = Math.max(anno.y1, anno.y2)
      const pad = Math.max(4, anno.type === 'rect' || anno.type === 'ellipse' ? anno.lineWidth : 2)
      return p.x >= x1 - pad && p.x <= x2 + pad && p.y >= y1 - pad && p.y <= y2 + pad
    }
    case 'arrow':
      return distToSegment(p, { x: anno.x1, y: anno.y1 }, { x: anno.x2, y: anno.y2 }) <= Math.max(6, anno.lineWidth)
    case 'pen': {
      for (let i = 1; i < anno.points.length; i++) {
        if (distToSegment(p, anno.points[i - 1], anno.points[i]) <= Math.max(6, anno.lineWidth)) return true
      }
      return false
    }
    case 'text': {
      return hitTestTextZone(anno, p) !== null
    }
    case 'number': {
      const r = anno.fontSize / 2
      const dx = p.x - anno.x
      const dy = p.y - anno.y
      return dx * dx + dy * dy <= r * r
    }
  }
 }
 /** 点击测试：返回命中的标注索引（-1 未命中），从后往前测试（后画的在上层） */
 function hitTestAnno(p: Point): number {
  for (let i = annotations.value.length - 1; i >= 0; i--) {
    if (hitTestSingle(annotations.value[i], p)) return i
  }
  return -1
 }
 /** 标注是否可调整大小（pen/text/number 仅支持移动） */
 function isAnnoResizable(anno: Annotation): boolean {
  return anno.type === 'rect' || anno.type === 'ellipse' || anno.type === 'arrow' || anno.type === 'mosaic' || anno.type === 'highlight'
 }
 /** 深拷贝标注（用于拖拽/调整大小时保存原始快照） */
 function cloneAnno(a: Annotation): Annotation {
  if (a.type === 'pen') return { ...a, points: a.points.map(pt => ({ ...pt })) }
  return { ...a }
 }
 /** 移动标注：基于原始快照 + 偏移量更新目标标注坐标 */
 function applyMove(target: Annotation, orig: Annotation, dx: number, dy: number) {
  switch (target.type) {
    case 'rect':
    case 'ellipse':
    case 'arrow':
    case 'mosaic':
    case 'highlight': {
      const o = orig as typeof target
      target.x1 = o.x1 + dx
      target.y1 = o.y1 + dy
      target.x2 = o.x2 + dx
      target.y2 = o.y2 + dy
      break
    }
    case 'pen': {
      const o = orig as typeof target
      target.points = o.points.map(pt => ({ x: pt.x + dx, y: pt.y + dy }))
      break
    }
    case 'text':
    case 'number': {
      const o = orig as typeof target
      target.x = o.x + dx
      target.y = o.y + dy
      break
    }
  }
 }
 /** 调整标注大小：根据手柄方向更新对应坐标（仅对可调整大小的标注有效） */
 function applyResize(target: Annotation, orig: Annotation, dir: HandleDir, dx: number, dy: number) {
  switch (target.type) {
    case 'rect':
    case 'ellipse':
    case 'arrow':
    case 'mosaic':
    case 'highlight': {
      const o = orig as typeof target
      let x1 = o.x1
      let y1 = o.y1
      let x2 = o.x2
      let y2 = o.y2
      if (dir.includes('e')) x2 = o.x2 + dx
      if (dir.includes('s')) y2 = o.y2 + dy
      if (dir.includes('w')) x1 = o.x1 + dx
      if (dir.includes('n')) y1 = o.y1 + dy
      target.x1 = x1
      target.y1 = y1
      target.x2 = x2
      target.y2 = y2
      break
    }
  }
 }
 /** 绘制选中标注的虚线边框 */
 function drawSelectionBox(ctx: CanvasRenderingContext2D, bb: { x: number; y: number; w: number; h: number }) {
  const pad = 2
  ctx.strokeStyle = '#3b82f6'
  ctx.lineWidth = 1
  ctx.setLineDash([4, 4])
  ctx.strokeRect(bb.x - pad, bb.y - pad, bb.w + pad * 2, bb.h + pad * 2)
  ctx.setLineDash([])
 }
 // ===== 标注交互 =====
 function beginDraft(e: MouseEvent) {
@@ -1795,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
@@ -1952,10 +1780,19 @@ async function startScroll() {
    width: Math.round(sp.w),
    height: Math.round(sp.h),
  }
  // 覆盖层挖孔（先于会话启动）：Chromium 系浏览器（Edge/Chrome）的遮挡检测会把
  // 被完全覆盖的窗口标记为 occluded 并暂停渲染（页面冻结、抓帧静止）。在选区带处
  // 挖出真孔，目标窗口仅部分被覆盖即可恢复渲染，滚轮与拼接恢复正常。
  // 先挖孔再启动，保证会话首帧与滚轮都发生在解除遮挡之后。
  await commands.screenshotSetScrollHole(region).catch((e) => {
    console.error('[screenshot] 覆盖层挖孔失败', e)
  })
  try {
    await commands.screenshotScrollStart(hwnd, region, true)
  } catch (e) {
    console.error('[screenshot] 滚动截图启动失败', e)
    // 启动失败：回滚挖孔，避免残留空洞
    void commands.screenshotSetScrollHole(null).catch(() => {})
    showScrollToast(String(e))
    return
  }
@@ -1970,6 +1807,8 @@ async function startScroll() {
 function exitScrollMode() {
  scrollMode.value = false
  scrollProgress.value = null
  // 复位覆盖层挖孔（区域在窗口上持续有效，不复位会残留空洞）
  void commands.screenshotSetScrollHole(null).catch(() => {})
 }
 /** 取消滚动会话并退出滚动模式（会话线程回滚窗口、丢弃画布） */
@@ -2102,6 +1941,8 @@ async function beginCapture(payload?: ScreenshotBeginPayload) {
    scrollProgress.value = null
    // 新截图打断进行中的滚动会话 → 取消后台会话（避免残留占用）
    if (wasScrolling) void commands.screenshotScrollCancel().catch(() => {})
    // 复位覆盖层挖孔（无条件：异常路径也可能残留窗口区域，这里兜底清理）
    void commands.screenshotSetScrollHole(null).catch(() => {})
    winHighlight.value = null
    currentHwnd.value = 0
    sel.value = { x: 0, y: 0, w: 0, h: 0 }
@@ -2502,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>
--- a/Show More
+++ b/Show More
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
LFeng	ffa410b399	音乐模块调整	2026-09-12 15:47:16 +08:00
zhongluofeng	d702ed0d31	调整，音乐模块	2026-09-12 11:05:26 +08:00