v1.2.4 | Efficient

---

Release Notes v1.2.4

TL;DR

• 更顺滑的历史滚动与焦点体验
  NSScrollView 滚轮增量映射 + 钳位 + 方向键焦点切换。
  NSScrollView wheel-delta mapping + clamping + keyboard focus switching.
  HistoryListView.swift
• 搜索更快、更精准（支持 lang: / len:）
  分字段匹配（title/text/appName）+ lang:（Beta）/len: 规则。
  Field-based matching (title/text/appName) + lang: (Beta) / len: rules.
  SearchService.swift SearchRuleFilters.swift TokenSearchTextView.swift TopBarView.swift
• 超长文本与 Base64 处理不再“拖后腿”
  Base64 探测/解码后台化 + 快速否决/采样/上限。
  Background Base64 detection/decoding with fast rejects, sampling, and hard caps.
  ClipItemCardView.swift ClipboardItem.swift
• 图片卡片新增文件大小
  文件大小异步计算 + NSCache 缓存，滚动不阻塞。
  Async file-size computation + NSCache caching to avoid scroll stalls.
  ClipItemCardView.swift
• 新增“一键整理/自检”（含可撤回快照）
  一键维护 + 报告弹窗 + 5 分钟可撤回快照。
  One-click maintenance + report sheet + 5-minute rollback snapshot.
  StorageMaintenanceService.swift DeckSQLManager.swift SettingsView.swift StorageMaintenanceReportSheet.swift

新增 / Added

• 图片卡片：文件大小展示
  图片卡片在尺寸下方新增“文件大小”一行；计算中显示“计算中…”，完成后自动刷新。大小计算走异步任务，并用 NSCache 缓存每条记录结果以避免重复计算。
  Image cards now show file size under dimensions; displays “Calculating…” while processing and auto-refreshes when ready. Size is computed asynchronously and cached via NSCache.
  ClipItemCardView.swift
• 搜索规则：lang: / -lang:（Beta）
  支持按代码语言过滤/排除；大小写不敏感、支持 + 多选，并提供常见别名映射（如 js/ts/c#/cpp/yml/md）。规则选择器新增 Beta 标签与性能提示。
  Filter/exclude by detected code language; case-insensitive, supports + multi-select with common aliases (e.g., js/ts/c#/cpp/yml/md). Adds a Beta badge and performance note in the rule picker.
  SearchRuleFilters.swift SearchRulePickerView.swift Localizable.xcstrings
• 设置页：一键整理 / 自检 + 可撤回快照
  新增维护入口与运行态展示、报告弹窗联动，并提供 5 分钟可撤回的快照恢复能力。
  New maintenance entry with progress UI, a report sheet, and a rollback snapshot available for 5 minutes.
  StorageMaintenanceService.swift DeckSQLManager.swift SettingsView.swift StorageMaintenanceReportSheet.swift
• 文件图标缓存
  新增图标缓存机制，减少系统图标查询开销，预览与列表渲染更稳定。
  Adds icon caching to reduce system icon lookups for more stable rendering in lists and previews.
  IconCache.swift PreviewWindowController.swift PreviewOverlayView.swift ClipboardItem.swift ClipboardCardView.swift ClipItemCardView.swift PrivacySettingsView.swift StatisticsView.swift PDFPreviewView.swift
• 设置项：打开面板时隐藏 Dock
  新增设置项「通用 → 行为 → 打开面板时隐藏 Dock」，默认开启；关闭后恢复原行为（Dock 可随鼠标放大）。
  Adds a new setting “General → Behavior → Hide Dock when panel opens”, enabled by default; turning it off restores the original Dock behavior (e.g., magnification on hover).
  SettingsView.swift MainWindowController.swift UserDefaultsManager.swift Localizable.xcstrings

优化 / Improvements

• 历史列表滚动更顺滑
  支持将滚轮“垂直增量”映射为水平滚动，并加入滚动钳位与交互细节优化，浏览大量历史更跟手。
  Smoother history scrolling with vertical-wheel-to-horizontal mapping, clamping, and interaction refinements for large histories.
  HistoryListView.swift
• HistoryList：空 contextTypes 回退 DB 顺序 + 选中项兜底
  当 contextTypes 为空时直接回退到 DB 顺序，避免 orderedItems 与 dataStore.items 共享存储导致的 COW 全量复制；并确保 selectedId 一定落在当前列表内。
  When contextTypes is empty, fall back to DB order to avoid a full-copy COW triggered by shared storage between orderedItems and dataStore.items, and ensure selectedId always resolves within the current list.
  HistoryListView.swift
• 键盘焦点切换更自然
  搜索框聚焦时按下方向键可把焦点移到列表且不清空搜索文本；列表聚焦时按上方向键回到搜索框（无修饰键时生效）。
  Natural focus switching: Down moves focus from search to list without clearing text; Up returns to search (when no modifier keys are held).
  HistoryListView.swift
• 搜索匹配更高效（分字段匹配）
  匹配逻辑按 title/text/appName 分字段处理，exact/regex/fuzzy 分别匹配；避免把大文本拼成单个巨字符串再匹配，降低 CPU 与瞬时内存压力。
  Field-based matching across title/text/appName for exact/regex/fuzzy; avoids concatenating huge strings, reducing CPU and transient memory pressure.
  SearchService.swift
• 语言过滤更稳、更省
  lang: 采用“先套牢前面规则、再二次筛选语言”的顺序；语言检测改走更轻量的检测接口，并引入缓存（含 signature 防误命中）与预热策略。
  lang: now runs after non-language rules narrow candidates; language detection uses a lighter-weight path and adds signature-based caching + warming to reduce redundant work.
  SearchRuleFilters.swift DeckDataStore.swift
• 大文件预览更轻量
  Markdown 文件预览仅读取前 16KB 并提示截断，避免大文件打开导致明显卡顿。
  Markdown previews read only the first 16KB with a truncation hint to avoid stalls on large files.
  LargeTextPreviewView.swift
• 日志与格式化更省分配
  日志改为惰性字符串，并新增线程本地 DeckFormatters 复用 Number/Date/Relative formatter，减少滚动与日志热点的对象创建与格式化开销。
  Lazy logging plus thread-local DeckFormatters reuse Number/Date/Relative formatters to reduce object churn and formatting costs on hot paths.
  AppLogger.swift DeckFormatters.swift
• 图片卡片：Base64 任务轻量预检 + detached 取消处理
  增加极轻量 pre-check，普通文本不再启动 Base64 探测任务；Task.detached 增加取消处理，减少任务雨与无效计算。
  Adds an ultra-light pre-check to avoid spawning Base64 tasks for normal text; adds cancellation handling for Task.detached to reduce task storms and wasted work.
  ClipItemCardView.swift
• 链接预览正则复用缓存
  Link 预览正则复用 RegexCache（含 options），减少重复编译带来的 CPU 抖动。
  Link preview regex now reuses a RegexCache (with options) to avoid repeated compilation and CPU spikes.
  SmartRuleService.swift LinkPreviewCard.swift
• SmartTextService 热路径更轻量
  isLikelyAssetFilename 改为纯字符串判断以避免每次跑正则；裸域名校验改用已缓存的 regex；matches(for:in:) 改为 enumerateMatches 以减少中间数组分配（行为保持一致）。
  Makes SmartTextService hot paths lighter: isLikelyAssetFilename now uses plain string checks instead of regex, bare-domain validation reuses cached regex, and matches(for:in:) uses enumerateMatches to reduce intermediate allocations (no behavior change).
  SmartTextService.swift
• IconCache：分层缓存 + 新增 size API
  拆分 base/sized cache，并新增 icon(forFile:size:)；减少图标取用过程中的 .copy() 分配与重复工作，提升列表/预览渲染的稳定性。
  Splits IconCache into base/sized caches and adds icon(forFile:size:), reducing .copy() allocations and redundant work for more stable list/preview rendering.
  IconCache.swift
• ClipboardItem 热路径进一步降分配
  增加 URL/normalizedFilePaths 缓存；sampleText 与富文本采样改为 index‑limited；文件名提取改走 NSString；PDF/文件图标改用新的 size API。
  Further reduces allocations on ClipboardItem hot paths: caches URL/normalizedFilePaths, makes text/RTF sampling index-limited, extracts filenames via NSString, and routes PDF/file icons through the new size API.
  ClipboardItem.swift IconCache.swift
• ClipboardService：更快的前置判断与轻量缓存
  URL 清理增加快速前置判断；敏感标题加入 0.4s TTL 缓存；身份证采样改 index‑limited；银行卡前缀静态化以减少重复构造。
  Adds faster pre-checks and lightweight caching: quick URL-sanitization guard, 0.4s TTL cache for sensitive-title checks, index-limited ID sampling, and static bank-card prefixes to reduce repeated setup.
  ClipboardService.swift
• Semantic 文本截断更省开销
  semantic text 截断改为 index‑limited，避免长文本处理时的额外扫描与分配。
  Makes semantic-text truncation index-limited to avoid extra scans/allocations on long content.
  SemanticSearchService.swift
• 拖拽图片类型检测更准确（WebP）
  拖拽图片类型检测改用 withUnsafeBytes，提升 WebP 识别准确性并减少不必要的解析开销。
  Improves drag-and-drop image type detection (especially WebP) using withUnsafeBytes, reducing unnecessary parsing overhead.
  ClipItemCardView.swift
• 面板激活期间 Dock 不再抢响应
  在面板 show/hide 时保存/恢复 NSApp.presentationOptions，并临时切换 .hideDock，避免面板激活期间 Dock 响应干扰交互；同时加入延迟隐藏/恢复（scheduleDockSuppression(...)）以避免面板出现瞬间 Dock “闪一下”（系统 .hideDock 本身不支持渐隐动画）。默认：dockHideDelay = -1、dockShowDelay = 0.10。
  Saves/restores NSApp.presentationOptions and temporarily toggles .hideDock during panel show/hide to prevent Dock interactions from interfering while the panel is active; adds delayed hide/restore (scheduleDockSuppression(...)) to avoid a quick Dock “flash” when the panel appears (macOS .hideDock has no fade animation). Defaults: dockHideDelay = -1, dockShowDelay = 0.10.
  MainWindowController.swift
• 剪贴板写入兼容性与内存护栏
  对 unsupported payload 增加总预算/单类型上限并跳过 image，避免内存暴涨；文件粘贴优先写 NSURL（兼容性更好），并保留原有 fallback 路径。
  Adds memory guardrails for unsupported payloads (total budget + per-type caps, skipping images) and prefers writing NSURL for file pastes while keeping the existing fallbacks for compatibility.
  ClipboardService.swift
• 局域网接收数据的硬上限保护
  接收数据先做 30MB 上限拦截，超限直接丢弃并记录，避免异常包拖垮进程内存。
  Adds a hard 30MB cap for incoming data; oversized payloads are dropped and logged to prevent memory blow-ups.
  MultipeerService.swift

变更 / Changes

• 长度规则统一为 len: / -len:
  原 size: 规则调整为 len:（仅数字+比较符）；文本类按长度参与过滤，非文本不排除但会降权排序。
  The old size: rule is renamed to len: (numeric only); text-like items are filtered by length while non-text items are kept but de-ranked.
  SearchRuleFilters.swift TokenSearchTextView.swift TopBarView.swift Localizable.xcstrings
• 长度过滤尽量下推到数据库
  在无关键词场景下减少内存扫描量，提升规则过滤的响应速度与一致性。
  Pushes length filtering down to the database where possible to reduce in-memory scanning and improve responsiveness.
  DeckDataStore.swift
• 横向滚动方向修正
  主要是横向滑动的输入场景下，滚动方向已调整为更符合直觉的表现（如 Magic Mouse 左滑时内容向右移动显示）。
  Horizontal scrolling direction is corrected for more intuitive behavior (e.g., Magic Mouse swipe-left moves content to the right).
  HistoryListView.swift

修复 / Fixes

• Swift 6 编译问题修复
  修复多处并发捕获、主线程隔离访问与缺失 await 导致的编译错误/警告；并对关键路径做“最小侵入”的隔离调整，尽量不改变既有行为。
  Fixes multiple Swift 6 build issues related to concurrency captures, main-actor isolation, and missing await, using minimal-intrusion adjustments to preserve behavior.
  BlobStorage.swift DataExportService.swift DeckDataStore.swift SearchRuleFilters.swift ClipItemCardView.swift StorageMaintenanceService.swift DeckSQLManager.swift
• 超长文本导致的卡顿风险降低
  Base64 探测与解码移出主线程，并加入快速否决与长度上限，减少滚动/搜索场景的掉帧。
  Reduces stalls from extremely long content by moving Base64 checks/decoding off the main thread with fast rejects and hard limits.
  ClipItemCardView.swift ClipboardItem.swift
• 颜色卡片兼容富文本来源
  颜色解析优先从纯文本内容提取并自动 trim，来自 RTF/RTFD 的复制内容也能正确显示色块。
  Color parsing now prefers trimmed plain text, fixing cases where RTF/RTFD sources failed to render the color swatch.
  ClipboardItem.swift
• 剪贴板 URL 清理更保守
  清理 URL 时保留原有粘贴板类型，并新增复制大小上限，降低异常内容带来的风险。
  URL sanitization now preserves original pasteboard types and enforces a copy size limit to reduce risk from abnormal content.
  ClipboardService.swift
• 粘贴失败不再“清空剪贴板”
  paste 失败时恢复原剪贴板快照，避免异常情况下用户剪贴板内容被意外清空。
  Restores the original pasteboard snapshot when paste fails, preventing accidental clipboard clearing.
  ClipboardService.swift
• 维护功能相关稳定性修复
  修复维护流程中的并发隔离访问、SQLite 表达式运算符缺失与压缩流初始化问题。
  Fixes maintenance flow issues including actor-isolation access, missing SQLite expression operators, and compression stream initialization.
  StorageMaintenanceService.swift DeckSQLManager.swift
• 维护快照：过期计时“可取消即返回” + 重活移出 MainActor
  过期倒计时改为取消即返回，避免“取消=立刻过期”的误行为；同时将“扫描缺失文件/删除 blob”等重活从 MainActor 移出，降低维护期间 UI 受影响的概率。
  Make snapshot expiry timers cancel-safe (cancel returns immediately) to avoid “cancel == expire now”; also move missing-file scans and blob deletion work off MainActor to reduce UI impact during maintenance.
  StorageMaintenanceService.swift
• 维护快照：并发隔离修复（4 处）
  在 MainActor 上快照 ClipboardItem 的 id/paths，将文件存在性检查移回后台；Blob 删除改回 MainActor，消除并发隔离相关的 4 处编译错误。
  Fixes 4 concurrency-isolation build errors in maintenance snapshots by snapshotting ClipboardItem id/paths on MainActor, moving file-existence checks back to background work, and running blob deletions on MainActor.
  StorageMaintenanceService.swift
• LAN 日志调用的并发隔离修复
  将 log.warn 放到 MainActor 的 Task 中执行，避免在 nonisolated 上下文直接访问主线程隔离的 logger，消除并发隔离编译报错。
  Runs log.warn inside a MainActor task to avoid accessing the main-actor-isolated logger from a nonisolated context, fixing a concurrency-isolation build error.
  MultipeerService.swift
• 搜索防抖任务不再触发 Swift 6 捕获告警
  搜索防抖 Task 固定在 MainActor 上创建与运行，避免 Swift 6 @Sendable 捕获警告。
  Pins the search debounce Task to MainActor to avoid Swift 6 @Sendable capture warnings.
  DeckViewModel.swift
• 窗口关闭后的清理逻辑主线程化
  关闭窗口后清理过期数据改为 MainActor Task 执行，避免跨隔离访问引发的不稳定行为。
  Runs post-close expired-data cleanup as a MainActor task to avoid cross-isolation access and subtle instability.
  MainWindowController.swift
• Orbit token 目录兜底，避免崩溃
  当 token 目录取不到时回退到 Caches / 临时目录，避免 first! 触发崩溃。
  Adds a fallback to Caches/temporary directories when the token folder is unavailable, preventing a first! crash.
  OrbitBridgeAuth.swift
• 数据库错误监听补齐并正确移除
  补存 .databaseError observer，并在 applicationWillTerminate 里一并移除（含 pause/orbit），避免泄漏与重复回调。
  Adds the missing .databaseError observer and removes all related observers on applicationWillTerminate (including pause/orbit) to avoid leaks and duplicate callbacks.
  AppDelegate.swift
• Debug 预览拼接避免无谓开销
  debug 预览拼接改为 log.isEnabled(.debug) 保护，并新增 isEnabled(_:) 接口，避免在非 debug 场景做字符串拼接与格式化。
  Guards debug preview string building behind log.isEnabled(.debug) and adds an isEnabled(_:) API to avoid unnecessary string formatting when debug logging is off.
  AppLogger.swift DeckDataStore.swift HistoryListView.swift
• 本地化覆盖率问题修复
  补齐缺失翻译并清理无引用 key，提升各语言的完整性与一致性。
  Fixes localization coverage by filling missing translations and removing stale, unreferenced keys.
  Localizable.xcstrings
• 搜索规则解析错位修复（size:/len:）
  规则解析支持 size:/len: 兼容匹配，并返回真实前缀长度，避免 token 解析错位导致的体验问题。
  Rule parsing supports size:/len: compatibility and returns the real prefix length to avoid token offset drift.
  SearchRuleFilters.swift
• 设置页：过期计时“取消即返回”
  UI 侧的过期倒计时逻辑同步改为取消即返回，避免清理/撤回交互中被误触发。
  Mirrors the same cancel-safe expiry timer behavior in the Settings UI to avoid accidental triggers during cleanup/rollback interactions.
  SettingsView.swift

说明 / Notes

• 关于页版权信息
  “关于”页底部版权优先读取 NSHumanReadableCopyright，并保留原文本作为兜底。
  The About page now prefers NSHumanReadableCopyright for the footer, with a fallback to the previous text.
  SettingsView.swift
• lang: 规则为 Beta
  lang: 需要进行语言检测，数据量很大时仍可能带来额外开销；规则选择器已提供提示。
  lang: is Beta and may add overhead on very large datasets due to language detection; the rule picker includes a warning.
  SearchRulePickerView.swift Localizable.xcstrings

升级建议 / Upgrade Notes

• 推荐升级到 v1.2.4
  如果你在历史浏览/搜索时遇到滚动掉帧或卡顿，本版本的优化收益最明显，强烈推荐更新。
  Recommended if you experience scrolling/search stalls.
  HistoryListView.swift SearchService.swift SearchRuleFilters.swift ClipItemCardView.swift AppLogger.swift

---