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 下的路径设置文件用于持久化。
• 收纳目录由用户在设置中选择。选择不在桌面所在磁盘的目录时，必须先提示跨盘收纳大文件会慢并让用户确认；收纳目录与桌面不同盘时，设置页持续显示提示。修改运行目录时，迁移 journal 和写入配置的路径不得带 \\?\ 前缀，并须同步改写重启收纳标记中的旧根路径。
• 切换运行目录前必须先在新目录做写入探测，不可写时直接报错并给出可写目录示例，不得写入迁移 journal；迁移在 rewritten 之前失败必须回滚（删除 journal，不动源目录和配置），后续切换和启动恢复不能卡在同一个失败的 journal 上。
• 运行目录迁移（复制模式）时，新复制的目录项和跨盘收纳一样，暂存复制后只做结构校验（目录结构、条目数、文件大小、修改时间）再不覆盖地原子提交；新复制的单个文件在提交前做一次逐字节比对（含 NTFS 命名流）；目标里已存在的同名文件必须逐字节比对，不能降级为结构校验，否则同大小同时间但内容不同的文件会在清理阶段导致源被删。复制完成后的确认和删除旧项目之前只用快速结构校验，锁定目标项时只用不读数据的句柄（DELETE | FILE_READ_ATTRIBUTES、仅共享读），不要以读数据方式逐个打开刚复制的文件，否则实时防护会逐个扫描。任何校验不一致、目标缺失或类型不同都必须保留源并报错，绝不覆盖目标已有文件。迁移必须通过 dustdesk://runtime-migration-progress 推送进度（scanning / copying / verifying / moving / switching / cleaning / done，约 250 ms 限流、阶段变化立即推送，含字节数、文件数和当前项目），启动时恢复迁移用 lifecycle 进度显示同样文案；进度推送失败不得影响迁移。
• 运行目录迁移开始前必须在 storage 锁内同步恢复 transfer journal（不得把已提交的清理推迟到后台），恢复失败直接报错且不写迁移 journal。迁移结束（成功、回滚或失败）都要广播 dustdesk://desktop-cards-changed，并写诊断日志 runtime_migration_finished（target、mode、elapsed_ms，复制模式带字节数和文件数）。
• 收纳目录、快捷启动目录同卷迁移时，满足前提（同一卷、都不是卷根或 reparse point、互不包含、新根不存在或完全空、恢复后没有残留 transfer journal、旧根第一层及各子文件夹第一层没有 .dustdesk-*.tmp）就用一次不覆盖、不允许复制的原子重命名把整个旧根改成新根，不复制、不清理。迁移 journal 记录 mode（copy / rename，默认 copy）和 renamed（默认 false）；改名成功后先在内存置 renamed 再持久化，此后只能前滚，任何失败都保留 journal 并在下次修改目录或启动时继续，启动恢复遇到失败必须中止。崩溃恢复时 mode=rename, renamed=false 要按磁盘判定：新根只要有内容就视为已改名并前滚（journal 创建时新根必为空），不看旧根；只有旧根有内容且新根为空才重试改名。前滚时旧根若被重建且有内容（改名后进程继续运行时新收纳的项目），必须用复制模式机制不覆盖地合并进新根并结构确认，switch 之后再经结构校验清理旧根；合并未完整成功前不得删除 journal 或旧根中的任何东西。只要 runtime-migration.json 存在，快照修复（repair_category_item_paths、repair_launchers）在 storage 锁内只读跳过，不得清理“不存在”的路径或写 config.json / launch.json。清理旧目录时空的只读文件夹要先去掉只读属性再 remove_dir。改名失败（被占用、拒绝访问等）说明什么都没动，重建新根、改回 copy 模式并走复制。数据目录一律保持复制模式。改名后旧根可能被持有旧路径的窗口重新建成空目录，此时清理阶段不得删除任何东西；读改写 config.json、launch.json 的快照修复必须在 storage 锁内重新打开 AppStore，不能用锁外打开的旧路径。