tauri-dustdesk: Instructions file for Codex

AI 项目规则

Windows 下的 Tauri 窗口创建

• 不要在同步 Tauri command 或事件 handler 里创建 WebviewWindow / WebviewWindowBuilder。Windows 下这可能导致死锁或应用卡死。
• 任何会创建、销毁、显示、隐藏、移动动态窗口的命令，都应写成 async fn，并把可能阻塞的窗口操作放进 tauri::async_runtime::spawn_blocking(...)。
• 动态桌面卡片窗口必须使用稳定 label，例如 desktop-category-{index}。除非确实需要同一逻辑卡片同时存在多个窗口，否则不要用时间戳或随机 label。
• 桌面卡片和快捷框只是桌面辅助窗口，默认不要设置 always_on_top(true)，也不要在显示时调用 set_always_on_top(true)，否则会遮挡其它软件。
• 桌面卡片、快捷框、合并态桌面框必须保持在普通应用窗口下方。创建和每次 show() 后都要重新设置 set_always_on_bottom(true)，否则 Windows 可能把窗口提升到前台 z-order，导致卡片盖住其它软件。
• 需要接收 Windows 桌面/资源管理器文件拖放的 WebView 窗口，不要隐藏状态创建后再 show()。WebView2 的 OLE DropTarget 可能在隐藏创建时没有注册，导致拖入显示禁止；静态窗口可用“离屏可见”启动，动态桌面卡片应直接 visible(true) 创建。
• Tauri 文件拖放要保持 dragDropEnabled: true，并使用 Tauri 原生 onDragDropEvent 获取系统文件路径。Windows 下不要为了 HTML5 内部拖拽把文件接收窗口改成 dragDropEnabled: false，否则外部桌面快捷方式拖入会拿不到路径。
• 前端监听文件拖放时，WebviewWindow 可能触发 Window 级拖放事件。封装应同时兼容 current window 和 current webview，并对重复事件去重。
• 前端不要在后端确认窗口创建成功前更新“已拆分/已合并”状态。后端应返回实际拆出的分类索引，前端只在成功后持久化状态。
• 拆分时避免每次销毁并重建全部 desktop-category-* 窗口。优先用稳定 label 复用已有窗口并调用显示。
• 谨慎批量创建 WebView。Windows 下每个 Tauri 窗口都会占用 WebView2 / Chromium 资源，一次创建很多窗口会很慢。必须批量创建时，命令保持异步，并考虑分批创建。
• 不要在拆分窗口成功创建前隐藏合并态桌面框，否则用户会看到主卡片消失但没有替代窗口。
• 收纳箱里的项目“移回桌面”不能只从配置中移除路径；必须尽量把文件/快捷方式移动回用户桌面。若桌面已有同名项，应保留桌面原有项，删除收纳目录里的副本，并从分类配置中移除该路径。
• 收纳箱项目必须支持拖出卡片/窗口后移回 Windows 桌面。前端拖出桌面时也要走 restore_item_to_desktop，不要只做浏览器内部拖拽状态。
• 所有会读改写 config.json 的收纳/分类/设置操作必须串行化，不能让多个 spawn_blocking 任务并发 load/modify/save。同样，快捷启动 launch.json 和 Launchers 目录修改也必须串行化，避免连续快速拖拽时后一次保存覆盖前一次，导致文件已移动但配置丢失。
• 加载快照修复分类路径时，除了清理不存在路径，还必须扫描 DesktopOrganizer/<分类名> 下的真实文件并补回对应分类，作为异常中断或并发覆盖后的自愈逻辑。
• 正常退出程序时，必须先原子持久化独立于 config.json 的重启收纳标记，记录待回收项目及其原分类；标记成功落盘后，才将已收纳项目还原到 Windows 桌面。程序启动时必须先恢复 transfer journal，再只依据该独立标记把对应桌面项目收回 DesktopOrganizer/<原分类> 并修复分类配置，不能凭桌面扫描、config.json 或收纳目录扩大自动回收范围。transfer journal 始终是在途物理迁移的权威状态。
• 用户明确执行“一键还原”或单项“移回桌面”时，必须在还原前清除独立重启收纳标记，且不得为这次显式还原重新创建标记，确保后续启动不会自动回收这些项目。
• 快捷启动是复制入口语义，不应因为加入快捷启动而移动桌面或收纳箱文件。快捷启动不支持“拖回桌面”迁移，只支持删除该快捷启动入口，不能删除用户桌面或原始文件。
• 快捷启动项不能作为向 Windows 桌面的拖拽源。图标 <img> 和快捷启动卡片要禁用浏览器默认图片/文本拖拽，避免用户把启动项拖回桌面造成错误语义。
• 快捷启动卡片以 Launchers 目录里的真实入口为准，launch.json 只是缓存/排序记录。加载快照时必须按目录重新校准，目录里不存在的启动项不能继续显示。
• 加入快捷启动时应在 Launchers 目录创建或复制一个入口，删除快捷启动只删除这个入口和缓存记录，不能删除用户桌面或原始文件。
• 不要把 Windows Shell 图标的 base64 持久化写进 launch.json；图标应运行时异步解析，避免配置文件膨胀和启动卡顿。
• 桌面来源的文件、文件夹、快捷方式加入收纳分类时必须使用迁移语义，物理移动到 DesktopOrganizer/<分类名>，桌面与收纳箱之间同一入口只允许存在一份，不能重复保留。
• 分类配置里的路径如果已经不存在，应在加载快照时自动从分类中清理，避免收纳目录清空后卡片里仍显示幽灵项目。
• 获取桌面路径优先使用 Windows Known Folder（包含重定向/OneDrive 桌面和公共桌面），不要只拼 %USERPROFILE%\Desktop。
• 默认数据目录、收纳目录、快捷启动目录应创建在软件安装目录下，分别为 Data、DesktopOrganizer、Launchers。用户自定义目录路径可以继续写入 %APPDATA%\DustDesk 下的路径设置文件用于持久化。