v1.3.0 | Palimpsestic

[yuzeguitarist]

---

Release Notes v1.3.0

TL;DR

• 智能规则能力大升级
  动作类型升级为菜单结构，新增“转换”和“脚本插件”二级菜单，规则保存与执行全面兼容新旧值。
  Smart Rules received a major upgrade, with action types moved to menus and new "Transform" and "Script Plugin" submenus, while save/execute now fully support both new and legacy values.
• 竖版模式正式可用
  支持竖版停靠方向（靠左/靠右），并联动搜索规则弹窗、卡片预览、底部区域和交互布局。
  Vertical mode is now fully available, including left/right docking and coordinated behavior across search rule popup, card preview, bottom area, and overall interactions.
• 插件体系更快更稳
  脚本插件支持热更新、防抖刷新、缓存加速与监听策略优化，减少闪烁和重复重载。
  The plugin system is now faster and more stable, with hot reload, debounced refresh, caching improvements, and optimized watchers to reduce flicker and repeated reloads.
• 导出与数据安全更可靠
  导出改为“临时写入 + 原子替换”，并修复多项迁移/加密/握手/任务清理等高风险问题。
  Export and data safety are now more reliable through "staging write + atomic replace" and fixes for multiple high-risk paths such as migration, encryption, handshake, and task cleanup.
• 预览与计算体验明显优化
  预览改异步，智能计算提速提准，缓存一致性更好，减少卡顿与结果延迟。
  Preview and smart calculation are significantly improved with async preview, faster and more accurate computation, and better cache consistency to reduce lag and stale results.
• UI 交互细节打磨到位
  多图展示、标签菜单、焦点行为、设置页动画、对比度与间距等均有系统性优化。
  UI interaction details were polished end-to-end, including multi-image display, tag menus, focus behavior, settings-page animation, contrast, and spacing.

新增 / Added

• 动作类型新增“转换”二级菜单
  规则编辑时可直接悬停展开转换项并点击选择。
  Added a new "Transform" submenu under action type so users can hover to expand and click specific transforms directly.
  SmartRulesView.swift:889
• 转换动作持久化升级为稳定码
  选择“转换”后会保存为稳定码，避免语言切换导致规则失效，并兼容旧值。
  Transform actions are now persisted with stable codes, preventing breakage after language switches while still supporting legacy values.
  SmartRulesView.swift:971, SmartRuleService.swift:155, DeckDataStore.swift:1151
• 动作菜单新增“脚本插件”二级选择
  可直接选择已安装插件作为规则动作，同时打通模型编码/解析与执行链路。
  Added a "Script Plugin" submenu in action menu, allowing installed plugins to be selected directly with full model encode/decode and execution integration.
  SmartRulesView.swift:814, SmartRuleService.swift:136, DeckDataStore.swift:1136, ScriptPluginService.swift:658
• 新增 ASCII 艺术动画条（6 种场景）
  新增 idle/empty/newCopy/searching/tagSelected/dataRich 场景、字符级过渡、60fps 驱动和动态宽度渲染。
  Added an ASCII animation bar with six scenes, character-level transitions, 60fps timeline driving, and dynamic-width rendering.
  ASCIIArtBarView.swift
• SmartRules 页面新增“使用指南”区块
  增加工作原理、条件说明、动作说明和实用小贴士，降低上手门槛。
  Added a "Usage Guide" block in SmartRules with workflow explanation, condition/action references, and practical tips for easier onboarding.
  SmartRulesView.swift, Localizable.xcstrings
• 新增数据库“立即恢复”能力
  设置页新增“立即恢复”按钮与确认弹窗，满足条件时可手动触发恢复。
  Added an "Immediate Restore" capability with a settings button and confirmation dialog, allowing manual restore when required conditions are met.
  DeckSQLManager.swift:2196, SettingsView.swift:2089, SettingsView.swift:2327, SettingsView.swift:2333, SettingsView.swift:2559, SettingsView.swift:2566
• 新增竖版停靠设置（靠左/靠右）
  竖版模式可自定义停靠方向，并联动规则弹窗与预览窗口自动在外侧展示。
  Added vertical dock-side settings (left/right), with rule popup and preview window automatically placed on the outer side accordingly.
  SettingsView.swift, MainWindowController.swift, MainViewController.swift, SearchRulePickerPanelController.swift, PreviewWindowController.swift, UserDefaultsManager.swift,
  Constants.swift, DeckViewModel.swift
• 脚本插件热更新机制上线
  启动后自动监听插件目录，脚本/manifest/目录变化会自动刷新，且保留手动刷新入口。
  Script plugin hot reload is now live: plugin directories are auto-watched on startup, changes auto-refresh, and manual refresh is still available.
  ScriptPluginService.swift:141, ScriptPluginService.swift:241, ScriptPluginService.swift:555, ScriptPluginService.swift:607, ScriptPluginService.swift:693

Deck × Orbit

• CLI /clip 默认接入智能规则
  默认由规则入口处理，支持继续按参数切回旧直存模式。
  CLI /clip now uses Smart Rules by default, while still allowing parameter-based fallback to legacy direct-save behavior.
  CLIBridgeService.swift:608, CLIBridgeService.swift:629, CLIBridgeService.swift:672
• CLI Bridge 示例与别名说明增强
  增加标签名/标签ID写入、空结果状态检查，并补充 health / last / write 别名示例与放置说明。
  CLI Bridge examples and alias docs were expanded with tag name/id writing, empty-result status checks, and clearer health / last / write alias usage.
  CLIBridgeSettingsView.swift:109, CLIBridgeSettingsView.swift:119, CLIBridgeSettingsView.swift:124, CLIBridgeSettingsView.swift:132, CLIBridgeSettingsView.swift:167
• 脚本插件“创建步骤”文档升级
  引导步骤更详细，示例 manifest/脚本更完整，并新增实测步骤与建议。
  The script-plugin "creation steps" guide is now more complete, with richer manifest/script examples plus a real-test step and recommendations.
  ScriptPluginsSettingsView.swift:17, ScriptPluginsSettingsView.swift:28, ScriptPluginsSettingsView.swift:220, ScriptPluginsSettingsView.swift:224
• Cloudflare 更新代理后端优化
  提升性能、稳定性、实时性、速度和并发能力。
  The Cloudflare update-proxy backend was optimized for better performance, stability, real-time behavior, speed, and concurrency.

优化 / Improvements

• 导出流程改为“临时文件写入 + 原子替换”
  避免中断留下半截 JSON，失败只清理临时文件，不再删用户已有备份。
  Export now uses "staging write + atomic replace" to prevent partial JSON leftovers, and failures only clean temporary files instead of deleting existing user backups.
  DataExportService.swift:108, DataExportService.swift:123, DataExportService.swift:163
• 导出大数据性能优化
  写盘改为缓冲批量写（1MB 阈值），批次从 500 调整为 200，降低内存压力。
  Large-data export performance was improved via buffered batch writes (1MB threshold), and batch size was reduced from 500 to 200 to lower memory pressure.
  DataExportService.swift:180, DataExportService.swift:201
• 导出链路减少重复 IO
  已加载完整数据时避免重复读 blob。
  Reduced duplicate I/O in the export pipeline by avoiding repeated blob reads when full data is already loaded.
  DataExportService.swift:220
• LS/PS 清洗热路径提速
  U+2028/U+2029 常量静态复用，并加入快速预检，命中才替换。
  LS/PS sanitization hot path was accelerated by reusing static U+2028/U+2029 constants and adding a fast pre-check so replacement runs only when needed.
  DataExportService.swift:123, DataExportService.swift:165
• 脚本插件执行性能优化
  增加插件索引、脚本文本缓存、网络授权缓存；执行路径改为缓存优先；仅在需要时计算脚本哈希。
  Script-plugin execution performance was improved with plugin indexing, script-text caching, and network-permission caching; execution now prefers cache, and script hash is computed only when required.
  ScriptPluginService.swift:136, ScriptPluginService.swift:247, ScriptPluginService.swift:730, ScriptPluginService.swift:755, ScriptPluginService.swift:836, ScriptPluginService.swift:937,
  ScriptPluginService.swift:1231, ScriptPluginService.swift:1236, ScriptPluginService.swift:1452
• 预览与即时计算性能优化
  预览中的同步热点改异步，减少主线程压力；关闭即时计算时行为更准确。
  Preview and instant-calculation performance improved by replacing synchronous hotspots with async flow, reducing main-thread pressure and fixing behavior accuracy when instant calc is disabled.
  PreviewOverlayView.swift:16, PreviewOverlayView.swift:103, PreviewWindowController.swift:330, PreviewWindowController.swift:382, PreviewWindowController.swift:461,
  ClipItemCardView.swift:1738, SmartContentCache.swift:276
• 数学识别与计算能力提升
  提升预检效率，支持等式左侧计算、多个/嵌套 sqrt，并优化数字格式化性能。
  Math recognition and calculation were upgraded with faster pre-checks, support for left-side equation evaluation, multiple/nested sqrt, and improved number-formatting performance.
  SmartTextService.swift:1846, SmartTextService.swift:1882, SmartTextService.swift:1928, SmartTextService.swift:1999, SmartTextService.swift:2032
• 智能缓存一致性优化
  OCR/文本更新与设置切换时主动失效缓存，卡片/行视图任务联动文本与开关变化。
  Smart-cache consistency was improved by proactively invalidating cache on OCR/text updates and settings toggles, and by binding card/row tasks to text and switch changes.
  DeckDataStore.swift:1414, SettingsView.swift:1211, ClipItemCardView.swift:42, ClipItemCardView.swift:558, ClipItemRowView.swift:21, ClipItemRowView.swift:104
• 竖版图片显示优化
  图片严格限制在方形区域，按接近方图/宽图/竖图分别处理，避免冲出卡片。
  Vertical-mode image display was refined by strictly constraining images to a square area with separate handling for near-square, wide, and tall images.
  ClipItemRowView.swift:117, ClipItemRowView.swift:173
• 多图展示体验优化
  多图记录仅展示首图，新增数量角标与“还有 N 张图片”提示，并修复预加载跳过问题。
  Multi-image display was improved by showing only the first image, adding count badges and an "N more images" hint, and fixing premature preload skipping.
  ClipItemCardView.swift, Localizable.xcstrings
• 竖版多图信息展示优化
  仅在多图时显示“共 X 张”，放在竖版右侧信息区中间。
  In vertical mode, "Total X images" is now shown only for multi-image items and placed in the middle of the right info area.
  ClipItemRowView.swift:290
• 设置页交互与过渡动画优化
  去掉内容区偏移 hack，切换 tab（点击/键盘）不再带整页动画，过渡更稳。
  Settings-page interactions and transitions were refined by removing the content offset hack and disabling full-page animation on tab switching (click/keyboard).
  SettingsView.swift:184, SettingsView.swift:232, SettingsView.swift:270
• 视觉细节优化
  迁移按钮改 Tonal 风格；textTertiary 对比度提升；标签编辑输入框改为随输入自动延长。
  Visual details were polished with a Tonal migration button style, improved textTertiary contrast, and auto-expanding tag editor input fields.
  NewTagChipView.swift, EditingTagChipView.swift
• 面板重开滚动体验优化
  重新激活时强制回到首项，复用现有平滑滚动逻辑。
  Reopen scrolling experience was improved by forcing selection back to the first item on reactivation while reusing existing smooth-scroll logic.
  HistoryListView.swift:135

变更 / Changes

• 竖版顶部与底部交互逻辑重构
  竖版顶部移除设置/暂停/关闭/反馈；底部区域按队列模式与按钮栏二选一展示。
  Vertical-mode top/bottom interaction logic was reworked: top controls (settings/pause/close/feedback) were removed, and the bottom area now toggles between queue bar and button bar.
  TopBarView.swift:1155, HistoryListView.swift:110, TopBarView.swift:958
• 竖版搜索态布局调整
  搜索聚焦/有输入/规则面板打开时，右侧标签区自动收起，避免布局被撑开。
  Vertical search layout was adjusted so the right tag area auto-collapses when search is focused, has input, or rule panel is open, preventing horizontal stretch.
  TopBarView.swift:18
• 竖版底部高度统一
  按钮区和队列区统一为同一高度，移除偏移补丁，视觉对齐一致。
  Vertical bottom heights were unified: button area and queue area now share the same height, with offset hacks removed for consistent alignment.
  HistoryListView.swift:86, HistoryListView.swift:255, HistoryListView.swift:266
• 竖版搜索框展开宽度调整
  竖版搜索宽度接近吃满可用空间，横版行为不变。
  Expanded search width in vertical mode now nearly fills available space, while horizontal-mode behavior remains unchanged.
  TopBarView.swift:123
• 搜索规则弹窗定位策略调整
  竖版下弹窗改为主面板外侧显示，并加边界保护，不遮挡输入与列表。
  Search-rule popup positioning was adjusted for vertical mode to render outside the main panel with boundary protection, avoiding overlap with input and list.
  SearchRulePickerPanelController.swift:95, SearchRulePickerPanelController.swift:102
• 标签右键菜单改为 NSMenu
  保留编辑/共享分组/删除，并新增颜色圆点选择与状态反馈，点击即持久化。
  Tag right-click menu was migrated to NSMenu, keeping edit/share-group/delete and adding color-dot selection with state feedback and immediate persistence.
  TopBarView.swift:1568
• 打开面板后的初始选中策略调整
  改为优先保证首项选中；已在首项时不重复设置，避免二次闪动感。
  Initial selection after opening panel was adjusted to prioritize the first item, and skip redundant resets when already on first item to avoid secondary flicker.
  HistoryListView.swift:1271
• 自动检查更新改为北京时间 3 次/天
  调整为 04:00 / 12:00 / 20:00。
  Automatic update checks were changed to three runs per day in Beijing time: 04:00, 12:00, and 20:00.
  UpdateCoordinator.swift:18, UpdateCoordinator.swift:80
• 插件监听策略改为“目录/文件分离掩码”
  目录保留 .attrib，文件移除 .attrib，并关闭高频 watcher 日志。
  Plugin watcher strategy now uses separate masks for directories/files: .attrib is kept for directories, removed for files, and high-frequency watcher logs are disabled.
  ScriptPluginService.swift:155, ScriptPluginService.swift:159, ScriptPluginService.swift:634, ScriptPluginService.swift:643
• 监听范围扩展到脚本目录全部一级目录
  新增候选目录收集逻辑，避免新增插件目录初期遗漏刷新。
  Watch scope now includes all first-level script directories via new candidate-directory collection logic, preventing missed refresh for newly created plugin folders.
  ScriptPluginService.swift:681, ScriptPluginService.swift:695

修复 / Fixes

• 清理欢迎页未使用字段与常量
  删除未使用的 tint、icon/iconColor、颜色常量及结构体冗余字段。
  Removed unused fields/constants in Welcome page, including tint, icon/iconColor, and redundant struct fields.
  WelcomeView.swift:22, WelcomeView.swift:49, WelcomeView.swift:102, WelcomeView.swift:514, WelcomeView.swift:606
• 修复异步日志漏写 await 导致的 6 个报错
  已补齐异步调用，恢复编译与运行稳定性。
  Fixed six errors caused by missing await in async logging calls, restoring compile and runtime stability.
  DeckDataStore.swift:1148, DeckDataStore.swift:1176
• 修复规则弹窗数字键映射错误
  不再用连续减法推算，改为固定映射，解决 5/6 错位及 7/8/9/0 无响应问题。
  Fixed numeric key mapping in rule popup by replacing subtraction-based inference with fixed mapping, resolving 5/6 mismatch and no-response on 7/8/9/0.
• 修复搜索框抢焦点问题
  焦点切到 .newTag/.editTag 时，跳过延迟 makeFirstResponder(nil)。
  Fixed search box focus stealing by skipping delayed makeFirstResponder(nil) when focus moves to .newTag/.editTag.
• 修复新标签默认选中问题
  新建标签时先确保拿到焦点，再自动全选“新标签”文字。
  Fixed default selection behavior for new tags by ensuring focus is obtained first, then auto-selecting the "新标签" text.
• 修复粘贴后误吞下一次复制
  改为只在“刚写入那次 changeCount”内跳过，不再无条件吞掉真实复制。
  Fixed accidental swallowing of the next real copy after paste by limiting skip behavior to the exact just-written changeCount.
  ClipboardService.swift:25, ClipboardService.swift:261, ClipboardService.swift:1645
• 修复粘贴失败引发的剪贴板丢失风险
  快照恢复支持更大预算和图片类型，恢复函数返回成功/失败并记录错误。
  Reduced clipboard-loss risk on paste failure by expanding snapshot restore budget/type coverage and returning explicit success/failure with error logs.
  ClipboardService.swift:1469, ClipboardService.swift:1514, ClipboardService.swift:1654
• 修复加密迁移“假成功”问题
  blob 迁移与 blob_path 更新改为强校验，任何一步失败都会整体失败。
  Fixed false-positive success in encryption migration by enforcing strict validation for blob migration and blob_path update, failing as a whole on any step error.
  DeckSQLManager.swift:5403, DeckSQLManager.swift:5425, BlobStorage.swift:178
• 修复解密失败却写成明文状态的问题
  解密分支新增严格检查，解不开直接失败，不再写 is_encrypted=false 假状态。
  Fixed incorrect plaintext state marking after decrypt failure: decryption branch now strictly checks and fails directly without writing fake is_encrypted=false.
  DeckSQLManager.swift:5245, DeckSQLManager.swift:5299
• 修复 DirectConnect authSuccess 阶段绕过
  增加 pendingAuthSuccess 阶段校验，仅在合法阶段接受成功握手。
  Fixed DirectConnect authSuccess phase bypass by adding pendingAuthSuccess state validation and accepting success handshake only in legal phases.
  DirectConnectService.swift:333, DirectConnectService.swift:980, DirectConnectService.swift:1025
• 修复 Multipeer verify_success 绕过
  必须存在活跃验证上下文才接受验证成功。
  Fixed Multipeer verify_success bypass by requiring an active verification context before accepting success.
  MultipeerService.swift:1541
• 修复 Keychain 临时错误误建新密钥
  仅 errSecItemNotFound 才创建新 key，其他错误直接上抛。
  Fixed unintended key regeneration on temporary Keychain errors: only errSecItemNotFound creates a new key, all other errors are returned directly.
  SecurityService.swift:111, SecurityService.swift:145, SecurityService.swift:177
• 修复清空数据后旧任务回写 UI
  clearAllData/clearAll 增加统一取消在飞任务入口。
  Fixed stale task write-backs after data clearing by adding a unified in-flight task cancellation entry for clearAllData/clearAll.
  DeckDataStore.swift:1441, DeckDataStore.swift:1518, DeckDataStore.swift:1721
• 修复 stop() 未清空 streamStore
  已补 streamStore.clearAll()。
  Fixed stop() not clearing streamStore by adding streamStore.clearAll().
  DirectConnectService.swift:275, DirectConnectService.swift:544
• 修复 deleteItemById 链路不完整
  补齐 blob 清理与 totalCount 刷新。
  Fixed incomplete deleteItemById path by adding blob cleanup and totalCount refresh.
  DeckDataStore.swift:1764
• 修复 blob 路径收集漏删风险
  分页从 offset 改 cursor，并补稳定排序 ts desc, id desc。
  Fixed blob-path collection deletion risk by switching pagination from offset to cursor and adding stable sorting (ts desc, id desc).
  DeckDataStore.swift:1809, DeckSQLManager.swift:4378
• 修复编译错误（await 放在 ?? 表达式内）
  改为两步赋值，消除编译失败。
  Fixed compile error from placing await inside ?? expression by splitting into two-step assignment.
  DeckDataStore.swift:1764
• 修复 Cmd+Q 提示文案语义错误
  “光标助手功能”统一改为“队列模式功能”，并补齐多语言。
  Fixed Cmd+Q prompt wording by replacing "Cursor Assistant feature" with "Queue Mode feature" consistently across languages.
  Localizable.xcstrings:25502
• 修复多处潜在崩溃（强解包/异常元素/空屏幕）
  增加类型校验与 guard 兜底，移除 fatalError 风险路径。
  Fixed multiple potential crashes (force unwraps, abnormal elements, empty screen) by adding type checks and guard fallbacks, and removing risky fatalError paths.
  IDEAnchorService.swift:401, OrbitWindow.swift:74, OrbitWindow.swift:102, OrbitWindow.swift:149, OrbitWindow.swift:156, DeckDataStore.swift:1420, MainWindowController.swift:69,
  SettingsWindowController.swift:57, UpdatePromptWindowController.swift:34
• 修复进程管道可能死锁问题
  改为运行时持续读取 stdout/stderr，并在 wait 前正确关闭写端。
  Fixed potential process-pipe deadlocks by continuously reading stdout/stderr during execution and correctly closing write ends before waiting.
  LANFileArchiver.swift:324, IDEAnchorService.swift:575, OrbitInstaller.swift:192
• 修复列表行编译/API 对接问题
  修正 item.colorValue、缩略图生成、智能分析赋值、脚本插件调用与隐写 API 调用。
  Fixed row-view compile/API integration issues, including item.colorValue, thumbnail generation, smart analysis assignment, script-plugin calls, and steganography API usage.
  ClipItemRowView.swift

说明 / Notes

• 本版本文案多语言已补齐
  新增/更新文案覆盖 de/en/fr/ja/ko/zh-Hans/zh-Hant。
  Localization coverage was completed for new/updated strings across de/en/fr/ja/ko/zh-Hans/zh-Hant.
  Localizable.xcstrings:19297, Localizable.xcstrings:22815, Localizable.xcstrings:2944, Localizable.xcstrings:50219, Localizable.xcstrings:55241, Localizable.xcstrings:45788,
  Localizable.xcstrings:45835, Localizable.xcstrings:45882, Localizable.xcstrings:44852, Localizable.xcstrings:44899
• 部分语种文案做了母语化重写
  de/fr/ja/ko 的新增长文案改为更自然表达，脚本设置页长文本改为 NSLocalizedString。
  Some language content was rewritten with native phrasing (de/fr/ja/ko), and long script-settings text now uses NSLocalizedString.
  Localizable.xcstrings, ScriptPluginsSettingsView.swift
• 本稿已完成路径脱敏
  所有位置引用均仅保留 文件名:行号，不含任何绝对路径信息。
  This draft is path-sanitized: all references keep only filename:line without any absolute path information.

兼容性与行为说明 / Compatibility & Behavior Notes

• 规则转换兼容新旧存储值
  transform 同时兼容“稳定码 + 历史旧值”，展示与执行都可回溯兼容。
  Transform rules are compatible with both new stable codes and legacy values in both display and execution paths.
• CLI /clip 保持双行为兼容
  默认走规则；raw=1 或 rules=0 可强制直存；rules=1 可显式开启规则。
  CLI /clip keeps dual behavior compatibility: rules by default, force direct-save with raw=1 or rules=0, and explicit enable via rules=1.
• 插件刷新支持“自动 + 手动”并存
  自动监听持续生效，手动“刷新插件列表”按钮仍保留可用。
  Plugin refresh supports both automatic and manual modes: directory watching remains active, and manual "Refresh Plugin List" is still available.
• “立即恢复”带双重保护
  必须同时满足“自动维护恢复备份已开启 + 恢复备份文件存在”才可执行。
  "Immediate Restore" uses dual safeguards and can run only when auto-maintenance restore backup is enabled and a restore backup file exists.

升级建议 / Upgrade Notes

• 建议升级后优先检查智能规则
  重点确认“转换动作”和“脚本插件动作”在你当前规则集中的展示与执行结果。
  After upgrading, prioritize validation of Smart Rules, especially how "Transform" and "Script Plugin" actions display and execute in your current rule set.
• 若有外部 CLI 依赖旧直存行为
  请在调用端显式加 raw=1 或 rules=0，避免行为变化影响自动化脚本。
  If external CLI workflows depend on legacy direct-save behavior, explicitly pass raw=1 or rules=0 to avoid automation regressions.
• 建议升级后验证竖版布局偏好
  可按使用习惯选择“靠左/靠右停靠”，并确认搜索弹窗与预览窗口位置符合预期。
  After upgrading, verify vertical layout preference (left/right dock) and confirm search popup and preview window positions match expectations.

---

---

This discussion was created from the release v1.3.0 | Palimpsestic.