ColorOS MiHome Bridge

0.5.0-preview：把米家已选设备接入 ColorOS 17 控制中心小卡片和设备空间主列表大卡片，支持按设备能力显示开关、亮度、温度和场景快捷控制。状态由米家官方 ControlsProviderService 提供，完整设备控制面板继续可用。

使用

1. 安装 dist/ColorOS-MiHomeBridge-0.5.0-preview.apk。
2. 在 LSPosed 中启用「米家控制中心桥接」，勾选米家 com.xiaomi.smarthome、系统界面 com.android.systemui 和设备空间 com.heytap.mydevices。旧版升级需补勾设备空间。
3. 首次启用或更新后重启手机，让宿主加载新代码。模块不会自行重启手机或系统界面。
4. 打开米家确认登录。在模块中打开「选择设备 / 打开完整面板」，选择米家，保存要显示的设备或手动场景。已经在 0.1.2 保存的选择可以继续使用。
5. 下拉控制中心，在「设备空间」使用卡片。未显示设备空间时，在控制中心编辑页添加。紧凑 2×1 布局显示一台设备，4×1 布局最多显示三台，优先安排可用设备；不可用设备和其余设备可在设备空间主列表或完整面板中查看。

点击设备空间入口，或在模块中点击「打开设备空间」，可在平板、耳机等原有卡片后看到已选米家设备，最多追加 32 台。大卡片显示名称、官方图标、在线状态及状态文字。有开关能力时使用卡片上的原生电源按钮；点击卡片打开快捷控制，支持设备提供的亮度、温度或场景操作，长按进入米家详情。仅有状态的设备直接打开详情。

在「管理设备卡片 / 房间分组」中可隐藏卡片、上移下移、按房间分组或恢复默认。设置按系统用户保存，隐藏不会删除米家收藏；取消不保存变更。房间来自米家设备服务，不能在这里修改所属房间。

控制中心小卡片点击切换开关或执行场景，长按进入米家详情。精细操作可使用米家详情或完整面板。原生方形小卡片以图标展示，名称和状态提供给无障碍服务；矩形小卡片使用原生文字布局。

“添加完整面板快捷入口”是可选的独立快捷开关。设备空间接入不依赖这个开关。

如果卡片或完整面板一直处于连接 / 加载状态，请在「米家 → 应用详情 → 耗电管理」中选择「完全允许后台行为」，再打开一次米家。本机实测系统 Hans 会冻结米家控制服务；放开后台活动后恢复响应。该设置会允许米家后台运行，也可能增加耗电。

在「显示与交互」中可选择米家卡片位于原生设备之前或之后，并选择点击时显示快捷控制、直接切换开关或打开米家详情。已有点击设置会继续沿用；新安装默认显示快捷控制。

本版变化

• 设备服务中断、订阅异常和首次连接超时后自动重连，退避间隔为 1、2、4、8、16 秒；次数耗尽后可手动重新连接。家电控制指令不会重试。
• 暂停、超时和重连期间保留最后的卡片、状态和图标，标记正在重连并禁用控制；关闭桥接、切换用户或确认收藏已空时清除对应缓存。
• 主列表改为状态变化推送与 10 秒心跳，图标按内容指纹确认，无变化时不重复传图；图片绘制、压缩、散列和解码使用有界后台队列。正常退出释放连接，异常退出最多 30 秒释放租约。
• 设置页分别报告设备服务、控制中心小卡片及设备中心的加载版本和连接状态，提供重新连接及推送、心跳、图像计数诊断。
• 新增原生大卡片电源按钮和快捷控制弹窗，支持 Toggle / ToggleRange / Range / Temperature / Stateless 模板；数值按服务提供的范围和步长校验。只在新状态确认后更新开关，避免重复操作和断线后的指令重放。
• 新增隐藏、排序、房间分组；按系统用户保存配置，保留 OPPO 原有卡片和持久化顺序。
• 设备服务从两套原生界面的适配层中独立，单个原生界面适配失败时保留另一界面和后台能力。
• 管理页面等待 LSPosed 设置连接完成再打开，避免冷启动时丢失管理入口请求。

此前版本保留的接入与恢复能力：

• 新接入 MyDevices 原生主列表、设备计数和卡片绑定，保留原有设备在前、米家设备在后的顺序，重复刷新不重复添加。
• 主列表快照校验 Android 提供的真实发送 UID、包名、当前用户和有效时间，设置命令继续使用独立的签名权限。
• 页面暂停释放订阅，异常退出租约自动到期；限制图片和传输总量，图片到达后触发原生卡片重新绑定。
• 从原生设备删除、持久化排序路径中排除米家临时卡片；收藏通过完整面板选择。
• 跨进程回调使用系统 ResultReceiver 基类，避免覆盖安装时旧宿主读不到新版匿名回调类。
• 0.2.2 修复原生设备空间与完整面板切换后收不到状态的问题：同一用户的米家连接使用相同服务回调标识，保留各自的订阅与取消操作。
• 设置请求携带版本和有效时间，修复宿主读取旧开关值导致恢复失败的问题，拒绝过期或旧版本请求。
• 设置页补充后台活动指引，并提示完整恢复后可能需要重新选择米家设备。
• 包含 0.2.1 的长按详情修复，并在发起详情后收起控制中心。
• 接入 ColorOS PanelInfo / PanelDevice 原生数据和卡片绑定路径，按米家已保存的顺序展示；不修改 OPPO 自身的设备收藏。
• 展开面板时建立独立订阅，收起后释放，不抢占完整设备面板的订阅。
• 使用米家提供的设备图标，显示在线 / 不可用、执行中与超时状态。只有收到米家回传的目标状态才确认开关变化。
• 拦截重复操作，锁屏时要求先解锁；切换系统用户后丢弃旧状态和回调。
• 限制传给原生布局的卡片数量，避免超出当前尺寸导致原生布局计算异常。
• 关闭桥接时清除注入的卡片并释放订阅；原生卡片数据仍由系统管理。

适配与验证范围

已验证的一加 15 基线：PLK110_17.0.0.105(CN01)，Android 17 / API 37；SystemUI 17.99.02；设备空间 17.25.10；米家 11.9.625。模块使用 libxposed API 101，在 API 37 及以上尝试加载，提供 API 101 的 102 框架亦可加载。

0.5.0 已覆盖安装并完成最终界面复测，54 项 JVM 测试、70 项宿主方法检查和仓库 CI 通过，Lint 0 错误。实机验证原有 4 台加米家 3 台、隐藏排序与房间分组、关闭重开、配置热更新、自动重连、完整面板切换及最终设置页。24 项 Android 模拟控制检查通过；按用户要求未向真实家电发送控制指令。验证记录见 docs/validation.md。

模块不需要 Home Assistant、账号密码或外部服务器；不读取米家登录凭据，不强制开启锁屏控制。可用功能取决于米家设备服务、当前账号、家庭、地区和设备状态。

恢复

在模块中点击「关闭并恢复本模块的改动」，成功后再从 LSPosed 禁用或卸载。系统禁用米家控制服务时可能清除它的已选设备，重新启用后需要重新选择；本次实机已重新选回原来的三台设备。日常暂停接入可只关闭桥接开关。

• 卡片注入仅存在于 SystemUI 和 MyDevices 内存中，关闭后恢复各自原始列表，不写入 OPPO 的持久化收藏。
• 恢复米家设备服务原来的启用状态。
• 只删除本模块新加的 controls 独立入口，保留其他快捷开关。
• 用户在系统编辑页调整的设备空间尺寸由系统保存，模块不会回写整份控制中心布局。

保留 dist/ColorOS-MiHomeBridge-0.3.0-preview.apk 作为上一稳定预览回退材料。应优先用设置中的关闭开关停用新接入；不要为回退直接卸载并清除数据。

构建

在 GitHub 的 Actions → package → Run workflow 选择 main，会运行测试、使用原签名构建 Release，并将 APK、源码包、SHA-256 和构建信息发布到私有仓库的 Releases。推送与版本对应的 v* 标签也会触发发包，例如 v0.5.0-preview。

发包版本来自 app/build.gradle.kts 的 versionName / versionCode。同一个标签绑定同一提交；代码更新后发新版本时，先递增版本号。重跑同一提交会保留已发布的资产。

签名材料使用仓库 Actions Secrets：ANDROID_SIGNING_KEYSTORE_BASE64、ANDROID_SIGNING_STORE_PASSWORD、ANDROID_SIGNING_KEY_ALIAS、ANDROID_SIGNING_KEY_PASSWORD。云端构建校验原证书并移除临时签名文件，源码包不包含密钥。

build 工作流继续负责普通提交和 PR 的验证，并提供 debug-apk 下载。日常安装使用 package 工作流提供的原签名 Release 包。

需要 JDK 21、Android SDK 37。设置 local.properties 的 sdk.dir，在 PowerShell 中执行：

$env:JAVA_HOME = '你的 JDK 21 路径'
.\scripts\Build.ps1

脚本运行单元测试、Debug Lint 和 Release 构建，复用 .local/signing/ 中的项目专用签名。首次构建会生成密钥；请私下备份整个签名目录。源码包不包含密钥，因此其他人重建的 APK 无法直接覆盖现有签名版本。

检查宿主 APK 接口：

python -X utf8 .\scripts\check_firmware.py --mihome .\MiHome.apk --systemui .\SystemUI.apk --mydevices .\MyDevices.apk --output .\.local\new-signatures.json

这只检查接口定义，不保证其他系统版本兼容。项目不分发米家或系统 APK。

Android 回归测试使用独立的 instrumentation APK，无需 UiAutomation。controls 模式只操作合成模板和本地回调；layout / layout_restore、disable / enable_restore 成对运行以恢复设置；transport_start / transport_finish 分段检查真实传输，避免测试进程在后台被系统冻结。测试 APK 不包含在交付安装包内。

打包源码与更新校验值（需要 Python 3.11+）：

python -X utf8 .\scripts\package_source.py