星弧壁纸使用文档
从第一次导入图片到长期自动运行，按真实界面逐步完成。
页面截图来自当前桌面端，不使用设计稿或示意占位图。
开始之前
星弧壁纸是本地优先的跨平台桌面应用。图片、缩略图、SQLite 数据库、设置和运行日志都保存在本机；当前版本不提供账号、云同步或远程图库托管。
安装与初始设置
安装正式打包版本
建立本地图库
选择第一张壁纸
浏览器预览不能设置系统壁纸。
网页模式只用于调试静态界面和数据请求。文件选择器、壁纸写入、开机启动、Dock 显隐和托盘能力必须在 Tauri 桌面窗口中操作。
本地图库
工作台把图库筛选、批量整理、手动应用和自动切换状态放在同一个页面。大图库使用分页与虚拟网格，只渲染当前可见区域附近的缩略图。
导入与扫描
可以选择多张图片、递归导入文件夹或扫描当前图库目录；不可解码的缩略图不会让原图导入失败。
搜索与排序
按标题、文件名、来源、作者、授权和分辨率搜索，并按更新时间、名称、分辨率或使用次数排序。
收藏与标签
支持收藏限定轮换、自定义标签颜色和多标签 AND 筛选；多选后可批量收藏、取消收藏或删除。
去重与维护
内容哈希用于归并重复索引。删除索引与删除本地文件是两个明确动作，不会混在一起。
在线发现
发现页聚合已启用的公开来源，按关键词、最低分辨率、画面比例和来源偏好筛选。候选入库前可以打开来源页和授权页核对使用条件。
免 Key 来源
Bing、Wikimedia Commons、Openverse、Art Institute of Chicago、Lorem Picsum 等来源可直接按各自公开能力使用。
需要 Key
Unsplash、Pexels、Pixabay、Flickr 等来源需要在“设置 → 在线来源”保存自己的 API Key。
混合来源
按已保存的启停与优先级并发搜索；单个来源失败只记录原因，不阻断其他来源。
下载入库
支持单张、选中、前 6 张或全部入库；下载前按 URL 预去重，落盘后再按内容哈希去重。
在线图片的授权由原始来源决定。星弧壁纸保留作者、来源页、原图地址和 license 信息，但不会替代用户判断具体用途是否符合授权。
自动切换与多屏
先在工作台或设置页选择来源模式、轮换范围、切换间隔和目标显示器，再开启自动切换。来源可选本地、在线或混合；轮换可限定为收藏并避开最近使用过的图片。
| 平台 | 目标 | 实现边界 |
|---|---|---|
| macOS | 主屏 / 全部 / 指定屏幕 | 使用 AppKit 主线程逐屏写入并读回；Space 切换后补偿同步。 |
| Windows | 主屏 / 全部 / 指定屏幕 | 使用 IDesktopWallpaper，写入失败时回滚旧路径和缩放方式。 |
| Linux | 按桌面环境能力 | 支持 GNOME、KDE Plasma、Xfce；其他环境使用显式自定义命令。 |
所有手动、定时、托盘和 Space 补偿写入都严格串行。macOS 不使用 AppleScript，不需要辅助功能或自动化权限；Windows 不申请管理员权限。
运行中心
运行中心先回答“当前是否异常”，再把任务、下载、壁纸历史和系统事件合并成按时间排序的活动流。选择一条记录后，重试、删除、打开来源、重新应用和步骤日志统一出现在右侧详情区。
筛选“需处理”可以集中查看失败下载、系统写入错误和需要人工处理的任务。打开单条记录先看摘要，再展开步骤日志，不需要在多个页面之间来回查找。
设置与备份
开机启动
设置页读取系统真实登录项；写入成功后才保存偏好。调试构建禁止开启，避免重启后加载不存在的开发服务器。
数据库备份
导出和恢复 SQLite 状态，覆盖设置、图库索引、收藏、历史与下载任务；备份不会复制图库原始图片。
脱敏诊断包
在“关于”中主动导出版本、平台、失败摘要和受限日志；不包含数据库、图片文件、密钥、自定义命令或真实用户主目录，也不会自动上传。
缓存维护
查看缩略图、图库和数据库占用，清理孤立缩略图、失效索引、超额在线缓存和旧任务。
来源管理
控制来源启停和优先级，保存自有 API Key，并可添加 JSON、RSS/Atom 或普通网页自定义来源。
恢复默认
重置全部设置并同步关闭系统开机启动，不保留数据库显示关闭但系统仍自动启动的分裂状态。
故障排查
自动切换没有运行
确认自动切换已开启、图库有符合条件的图片、应用仍在托盘运行，再到运行中心查看最近错误。
目标屏幕已断开
设置不会静默改写为主屏。重新连接原屏幕，或在设置中明确选择当前主屏、全部屏幕或新的指定屏幕。
在线搜索没有结果
检查来源是否启用、API Key 是否有效、网络是否可达，并暂时降低最低分辨率或取消画面比例限制。
图片没有缩略图
原图可能仍已成功入库。运行维护任务重新生成缩略图；若格式不受当前平台解码器支持，保留原图并查看诊断。
开机后出现白屏
这通常是调试构建被写入登录项。先关闭开机启动；macOS 可移除当前用户 LaunchAgent，再安装正式打包版本。
需要提交故障信息
先在运行中心确认失败记录，再到设置“关于”导出脱敏诊断包；发送前可解压复核固定清单和日志内容。
Linux 无法设置壁纸
确认桌面环境属于 GNOME、KDE Plasma 或 Xfce；其他环境在设置中填写带 {path}、{uri}、{target} 的自定义命令。