原生 Android 自动换壁纸应用。
从 Wallhaven 拉取壁纸,支持命运先机时段纯度劫持、关键词 / 跃迁、多 Key 轮换、网络与本地双兜底、桌面锁屏隔离、省电与省流量、定位避让、代理与加速、超级服务保活等。
命名由「镜花水月」相关英译组合而来;包名与内部标识不变。
版本更新记录 → CHANGELOG.md | 图标 → README_ICON.md
应用内 使用说明(首页入口)与本文互补,偏操作向导。
首次安装后,建议按以下顺序完成配置:
- 打开应用首页的权限引导,按需授予通知、图片读取、定位和电池优化豁免权限。系统对后台权限的名称可能因厂商而不同。
- 在「配置」中填写至少一个 Wallhaven API Key,设置换图间隔、目标屏幕、分辨率和纯度筛选。
- 如需在应用被划掉或系统回收后继续运行,开启强制前台服务,并在系统设置中允许自启动和后台运行。
- 点击首页「立即更换」验证网络、壁纸写入和目标屏幕设置。
- 确认运行正常后,再按需要启用关键词、跃迁、兜底、定位避让、省电或省流量策略。
**重要提示:**限制级内容需要有效的 Wallhaven API Key。定位避让、代理、Root/无障碍保活和第三方翻译均属于可选功能,相关权限、密钥、费用和隐私责任由使用者自行承担。
完整的逐步操作说明见 Word 使用说明。
应用将周期换图逻辑运行在独立的 :svc 前台服务进程中;「立即更换」使用一次性的 :manual 服务进程。设备开机或应用更新后,系统接收器会尝试恢复调度。亮屏后应用会等待约 5 分钟,再根据下一次计划时间判断是否需要补换,避免亮屏瞬间重复换图。
| 能力 |
可能需要的系统授权 |
用途 |
| 自动换图与通知 |
通知、前台服务 |
显示运行状态并维持周期任务 |
| 定位避让 |
定位;后台运行时建议「始终允许」 |
判断是否进入避让点及半径 |
| 应用黑名单 |
使用情况访问 |
判断当前前台应用 |
| 后台稳定运行 |
忽略电池优化、自启动、后台运行 |
降低厂商系统回收服务的概率 |
| 本地图片与缓存 |
Android 版本对应的图片读取权限 |
读取本地兜底目录和缓存 |
| 超级服务保活 |
无障碍或 Root(可选) |
按设备能力辅助维持后台进程 |
不同 Android 厂商的授权页面和后台策略差异较大。即使已授予权限,也建议将 MiroFlweat 加入系统的后台保护或自启动白名单。
- 壁纸拉取链路
- 配置项说明(按设置页)
- 首页 / 概览 / 记录 / 通知
- 格式与路径约定
- 构建
- 源码结构
- 声明
强制本地模式?
→ 仅从本地目录(及可选下载缓存)选图
否则
→ Wallhaven(关键词 / 跃迁词 + 多 Key)
→ 失败且开启「网络兜底」→ 自定义兜底 API(可多行依次试)
→ 仍失败且开启「本地兜底」→ 本地目录 / 历史缓存
自动更换还会受:息屏跳过、省电休眠、省流量限制、应用黑名单、定位避让(绿色/极限) 等规则影响。手动「立即更换」通常更宽松(仍可能受部分规则约束)。
以下选项均可在应用 配置 页找到。保存后生效;部分项需对应系统权限。
| 选项 |
可选值 / 范围 |
说明 |
| 更换间隔 |
约 5~180 分钟(滑条) |
两次自动更换的最短间隔。间隔较短时建议开前台服务 |
| 启用纯度筛选 |
开 / 关 |
关:每次在全部合法纯度组合中完全随机。开:用下方三档组合请求 Wallhaven |
| 保守级 |
选中 / 取消 |
对应 Wallhaven SFW(代码位 1xx) |
| 模糊级 |
选中 / 取消 |
对应 Sketchy(x1x) |
| 限制级 |
选中 / 取消 |
对应 NSFW(xx1);未配置 API Key 时不可选 |
| 纯度组合示例 |
010 仅模糊;001 仅限制;011 模糊+限制;101 保守+限制;110 保守+模糊;111 全部 |
多选按位合成三比特代码 |
| 类别 |
仅真人 / 仅动漫 / 真人·动漫轮换 |
Wallhaven 分类过滤 |
| 设置目标 |
仅桌面 / 仅锁屏 / 桌面+锁屏 |
系统壁纸写入目标 |
| 分辨率 |
设备自适应 / 最低约 1500×1500 / 自定义 |
自定义时可填最低宽、高 |
| 强制前台服务 |
开 / 关 |
通知栏常驻,利于保活;划掉后视系统与超级服务是否自启 |
| 息屏时跳过 |
开 / 关 |
灭屏不换;亮屏后再判断是否到期 |
| 忽略电池优化 |
跳转系统页 |
建议允许,减少被杀进程 |
| 加速模式 |
开 / 关(与「网络代理」互斥) |
经内置/配置的中转节点拉取;开启前须阅读并同意安全与隐私声明;可选远程节点 JSON 地址 |
| 方向过滤 |
无过滤 / 横屏过滤(仅竖屏)/ 竖屏过滤(仅横屏) |
过滤横图或竖图 |
| 壁纸铺满方式 |
填充 / 适应 / 居中 / 拉伸 |
填充=等比铺满裁边;适应=完整显示可留边;居中=原图居中;拉伸=变形铺满。修改后可用当前图重设而不重新下载 |
| 桌面锁屏隔离 |
开 / 关 |
开:一轮内两次下载与设置(先桌面后锁屏),关键词逻辑可分离 |
| 省电模式 |
开 / 关 |
未充电且电量低于阈值时休眠不自动换;充电忽略 |
| 省电电量阈值 |
约 5~50% |
仅省电开启时有效 |
| 省流量模式 |
开 / 关 |
按当日写入壁纸缓存的字节量:达档提高自动间隔;很高时当日可停自动换(手动仍可用) |
纯度与运行模式(通知栏切换,可覆盖配置页勾选):
| 模式 |
纯度策略 |
| 普通 |
遵循配置:未开筛选则随机;开启则用勾选组合 |
| 健康 |
锁定仅模糊级(010) |
| 心跳 |
锁定模糊级+限制级(011) |
| 绿色(定位避让区内且开启绿色) |
锁定保守级+模糊级(110);配置页纯度选择只读提示「已被接管」 |
按星期 + 时段自动劫持纯度策略;未命中时恢复通知栏运行模式(普通 / 健康 / 心跳)与主配置。
| 选项 |
说明 |
| 启用命运先机 |
总开关。关则完全不判定规则 |
| 命运先机配置 |
进入独立配置页 |
| 添加命运先机配置 |
弹出编辑卡片 |
| 开始时间 / 结束时间 |
24 小时制时:分;若结束早于开始则视为跨午夜 |
| 生效星期 |
周一~周日,可多选勾选 |
| 先机模式 |
健康模式:锁定模糊级(010)。心跳模式:锁定模糊+限制(011)。用户配置:遵循主设置(未开筛选则随机)。自定义劫持:在卡片内另选保守/模糊/限制组合 |
| 保存配置 |
可自定义配置名称 |
| 启用勾选 |
列表中每条旁勾选,不勾选不生效 |
| 优先级 |
0~999,可重复;数字越小越优先 |
| 置信度 |
整数,默认为 0;同优先级时数字越大越优先。通知强制恢复成功:−1;拒绝强制:+1 |
| 创建 / 修改时间 |
每条显示;同优先级且同置信度时取最近修改(再比创建) |
| 保存全部命运先机修改 |
将列表启用状态、优先级、增删改写回本地 |
| 通知强制恢复 |
命运已劫持时点模式切换 → 询问「是否强制恢复」。「是」:本时段该规则跳过(到结束时间后下周期再生效)+ 置信度−1 + 真正切模式;「否」:继续劫持 + 置信度+1 |
冲突判定顺序:优先级 → 置信度 → 修改/创建时间。
命中时配置页纯度区只读,文案形如:纯度选择已被命运劫持-配置名-(模糊级)。
| 选项 |
说明 |
| Wallhaven API Key |
每行一个;失败自动轮换。限制级等内容通常需要有效 Key |
| PIN 锁定时 |
未解锁不可查看/修改 |
| 选项 |
说明 |
| 启用关键词搜索 |
关则可不带关键词检索(视实现与 API) |
| 关键词列表 |
每行一个;轮换使用 |
| 远程关键词 URL |
拉取 txt 后覆盖或合并(以界面操作为准) |
| 跃迁模式 |
开:Wallhaven 成功后用该图标签覆盖写入跃迁列表;列表非空时搜索优先用跃迁词 |
| 跃迁列表 / 索引 |
与普通关键词分离;首页可预览「下次将用」 |
| 湮灭等相关 |
若界面提供:用过的跃迁词可写入缓存并在提取时排除(以当前版本界面为准) |
| 选项 |
说明 |
| 网络兜底 |
Wallhaven 失败后走自定义兜底 API |
| 兜底 API |
多行 URL;支持 {width} {height};响应可为图片流、单行 URL 或含 path/url 的 JSON |
| 本地兜底 |
网络路径仍失败时从本地目录选图 |
| 强制本地模式 |
不访问网络,只从本地(及可选缓存)换壁纸 |
| 本地兜底目录 |
默认应用私有 files/local_fallback/;可填公共绝对路径 |
| 本地兜底也使用下载缓存 |
从已下载的 wallpapers 缓存选图 |
| 跳过最新 N 张缓存 |
避免总用刚下的几张;N 可调 |
| 选项 |
可选值 / 说明 |
| 启用代理 |
与加速模式互斥;开启且配置有效时本应用请求走代理 |
| 代理类型 |
HTTP / SOCKS5 |
| 服务器 / 端口 / 用户名 / 密码 |
手动单节点 |
| 订阅链接或节点列表 |
URL 或 socks5://host:port#名 等,可导入解析 |
| 节点选择 |
手动选择 / 自动优选(测速) |
| 自动测速间隔 |
约 5~180 分钟(自动优选时) |
| 超级代理(Root) |
仅本应用:Root 启动自定义内核,监听本机端口;非全局 TUN |
| 内核文件 / 配置文件 / 订阅 / 启动参数 / 本地 SOCKS 端口 |
配置优先:已有配置文件 > 订阅生成;端口默认如 17890;可启动/停止内核 |
| 选项 |
说明 |
| 超级服务 |
更换相关逻辑可运行在独立进程 :svc,UI 划掉后仍可能继续 |
| 无障碍 / Root 保活 |
按机型与权限尝试保活;需在系统中授权 |
| 仍建议 |
忽略电池优化、自启动、后台运行(各厂商路径不同) |
| 选项 |
说明 |
| 黑名单包名列表 |
这些应用在前台时休眠、不自动换壁纸 |
| 管理黑名单 |
次级页:已选列表 + 搜索已安装应用 |
| 权限 |
需要「使用情况访问」类权限 |
| 通知 |
可将当前前台应用加入黑名单(通常需确认) |
| 选项 |
说明 |
| 启用定位避让 |
在避让点半径内触发策略 |
| 高德 Web 服务 Key |
地点搜索、逆地理;PIN 锁定时可能隐藏 |
| 触发半径 |
约 5~500 米(管理页滑条) |
| 避让点列表 |
搜索添加、当前位置添加、自定义标签或自动地名 |
| 绿色模式 |
区内锁定纯度「保守级+模糊级」 |
| 极限回退 |
区内仅本地文件换壁纸 |
| 离开所有点半径后 |
恢复进入前的纯度与「强制本地」等状态 |
| 权限 |
Android 10+ 建议定位「始终允许」,否则后台难判定 |
| 选项 |
可选值 / 说明 |
| 遮罩透明度 |
约 0.15~0.85 |
| 卡片透明度 |
约 0~0.7(越高越不透明) |
| 文字颜色 |
白色 / 柔白 / 浅灰 / 暖米 / 浅青 / 浅粉 等预设 |
| 板块美化(全局) |
无 / 液态玻璃 / 高斯模糊 / 雾化 — 各页卡片风格同步 |
| 模式 |
说明 |
| 系统壁纸/莫奈(Auto) |
优先系统壁纸,失败则莫奈取色 |
| API 链接 |
打开时从填写的 API 拉背景图 |
| 本地路径 |
使用本地图片路径 |
| 莫奈取色 |
系统取色风格背景 |
另可配置背景 API URL、本地路径等字段(随模式使用)。
| 选项 |
说明 |
| 翻译提供方 |
关闭 / 谷歌 / 微软 / 腾讯 |
| API Key / Secret / 区域 |
按所选服务填写;不修改实际发给 Wallhaven 的搜索词,仅用于界面或日志展示 |
| 选项 |
说明 |
| 启用 PIN |
锁定后密钥、关键词、兜底 API、翻译密钥、部分备份入口等敏感项不可见 |
| 设置 / 修改 / 解锁 |
PIN 存哈希;进程重启后通常需重新解锁 |
| 选项 |
说明 |
| 导出配置 |
生成 JSON(一般不含 PIN) |
| 从文件恢复 / 粘贴 JSON |
恢复后本机 PIN 策略以当前实现为准(通常保留本机 PIN) |
| 远程配置 URL |
若界面提供:从 URL 拉取配置 |
说明:历史版本曾出现云备份(WebDAV 等),是否保留以当前设置页为准;主路径为本地导出/导入。
| 选项 |
说明 |
| 清空缓存文件 |
清理已下载壁纸缓存等 |
| 清空更换记录 |
清空历史更换列表(与清缓存分开) |
| 开发者 / 运行日志 |
首页连续点击标题约 7 次可开开发者相关;可选写入 files/run.log |
| 功能 |
说明 |
| 自动更换 |
总开关(与设置中 enabled 一致) |
| 立即更换 |
马上执行一轮 |
| 网络探测 |
测 Wallhaven / 兜底连通与延迟 |
| 跃迁关键词 |
预览列表与下次用词 |
| 使用说明 |
应用内完整说明与检查更新等 |
| 功能 |
说明 |
| 上次 / 下次更换时间 |
结合设置与跨进程时钟 |
| 桌面 / 锁屏预览 |
来自最近缓存文件 |
| 服务状态 |
绿运行 / 红关闭 / 黄异常(独立 :svc 进程) |
| 极简模式 |
可只突出概览、弱化其它页(若已开启) |
| 缓存占用、已更换次数 |
统计信息 |
| 字段/操作 |
说明 |
| 来源、类别、纯度、关键词、分辨率、大小 |
单次更换详情 |
| 触发 |
手动 / 定时 / 亮屏补换 / 调度 / 开机 等 |
| 清空记录 / 清空缓存 |
与设置页同类操作 |
| 元素 |
说明 |
| 标题 |
随普通 / 健康 / 心跳模式变化(如 MiroFlweat·健康模式) |
| 正文 |
运行中或休眠原因(定位 / 应用 / 省电) |
| 模式切换按钮 |
普通 → 健康 → 心跳 → 普通…;切换后提示锁定策略文案 |
| 定位避让 / 应用黑名单 |
一般需确认后写入 |
| 立即更换 |
休眠时也可用 |
| 进度 |
下载过程不连续刷百分比,仅开始与结束类状态,减轻卡顿 |
- 默认:
files/local_fallback/(随卸载清除)
- 可填:
/storage/emulated/0/Pictures/Wallpapers 等
- 格式:
jpg / jpeg / png / webp / bmp
# 注释
landscape
anime girl
https://example.com/random?w={width}&h={height}
https://backup.example.com/pic
- Android Studio(建议 AGP 8.7+)、JDK 17、SDK 35
./gradlew assembleDebug
# app/build/outputs/apk/debug/app-debug.apk
./gradlew assembleRelease # 需自备签名
| GitHub Actions |
触发 |
产物 |
build-apk.yml |
push / PR、手动 |
Artifacts debug APK |
release-apk.yml |
标签 v* 或提交说明含「发布」 |
Release 附件 |
app/src/main/java/com/kers/killove/jhsy/
├── domain/ 模型、WallpaperChanger 更换闭环
├── data/ Wallhaven、Room、设置、本地兜底
├── service/ 前台服务、手动更换、保活
├── worker/ WorkManager、开机/亮屏
├── ui/ 首页、设置、记录、使用说明等
└── util/ PIN、定位、备份、跨进程桥接等
个人项目。请遵守 Wallhaven 服务条款并注意图片版权。高德、翻译、代理等第三方服务的密钥与费用由使用者自行承担。
更新记录:CHANGELOG.md