我用AI开发了一个ha第三方app(安卓)

此系统有后端，因为有些定制功能，通过ws与ha通信，代码全部由ai完成，由于测试有限，估计有很多未知BUG，感兴趣可以下载，欢迎测试外网访问一定要用https镜像与安装包下载：https://gitee.com/xg520088/sticky-kee

#加载镜像docker load -i  stickykee.tar# 运行docker run -d --name stickynuo \  -p 8080:8080 \  -v <本地路径>:/data \  -e TZ=Asia/Shanghai \  --restart unless-stopped \  stickykee:latest

地图 · 路线规划与到家距离

- **路线规划**：地图页新增「路线」入口，支持驾车 / 骑行 / 公交 / 步行四种方式；以当前位置为起点、家为终点（也可在地图上点选终点），画出路线并显示距离与预计耗时

- **到家距离传感器**（被动）：APP 上报位置时自动计算当前位置到家的直线距离，在 Home Assistant 中自动生成「XX 到家距离」传感器（单位 km）；移动超过 500 米才重新计算，位置不变每 2 小时刷新一次，可直接用于「距家 >X 公里提醒」「接近家自动开灯」等自动化

- **修复后台定位不触发回家自动化**：此前 APP 退后台后位置上报链路被系统冻结，回家触发要等到下次打开 APP；现改为原生后台直接上报设备位置（device_tracker），回程途中即可触发回家 / 离家自动化

- **修复在家规划路线误触发离家自动化**：路线规划起点定位按端区分——APP 端原生卫星定位精度高，定位即上报 HA；Web 端浏览器定位精度差（Wi-Fi 级常漂出家门范围），仅取坐标用于画线、不上报

界面修复

- 修复设置页「消息免打扰」卡片在窄卡内文字竖排的问题

- 修复手机端仪表盘拖拽：卡片拖到某排行尾的空白处现在也能正常插入；手机端新增显式「编辑」按钮（添加卡片等编辑功能此前已有，但编辑入口此前仅在桌面宽度显示）

智家助手 · 语音朗读

- **修复「朗读失败：内置 Edge TTS、服务端 TTS、系统 TTS 均不可用」**：微软于 2026-10-10 更换了免费 Edge TTS 在线接口的鉴权算法，导致「内置 Edge TTS」与「服务端 TTS」两条路线同时被拒（403）。本次已将 APP 内置与服务端同步升级到新鉴权（v2 DRM token），在线朗读恢复可用，音色不变- 系统语音路线不受本次微软变更影响；若此前系统 TTS 在个别机型上不可用，在线引擎恢复后朗读将优先走在线路线

消息通知

- **通知提示音与震动**：新消息通知可自定义提示音与震动，APP 通知渠道升级确保设置在 Android 13+ 生效- **免打扰时段**：设置 → 通知中可配置免打扰时段，时段内新消息仅静默入列，不响铃不震动

智家助手 · 语音朗读

- **切换即试听**：在会话顶部切换「朗读引擎」后立即试读一句测试语音，切换是否生效当场可闻，无需再发消息验证- **失败不再无声**：所有朗读路线（内置 Edge TTS → 服务端 → 系统语音）都失败时，会明确提示具体哪些引擎不可用，便于排查网络或系统 TTS 问题- **修复国产手机系统语音静默失败**：部分 ROM 默认 TTS 引擎初始化失败或缺中文语音时原来无声无息，现在系统语音不可用会自动落到在线引擎朗读

首页仪表盘

- **列数可自定义**：设置 → 个性化 → 仪表盘列数，可选「自动 / 2~6 列」；该设置仅对本设备生效，手机设 3 列、平板设 5 列互不影响- **跨机型显示一致**：不同品牌手机（屏幕密度、「显示大小」设置不同）不再出现一台 3 列、一台 2 列的差异，窄屏统一 3 列，卡片自动等比缩放- **修复卡片边框叠线**：卡片边框不再出现贴边暗带、角部弦线等多余线条

界面细节

- 页面操作提示改为**悬浮抽屉**：从页头下方滑出、数秒自动收起，不再挤压页面内容- 手机端仪表盘**编辑工具条**（导出/导入/智能排版/重置/完成）单行排列，不再换行占两行- 户型图编辑模式提示悬浮化，不占画布空间、不干扰绘制操作

传感器 · 原生统一采集

- **APP 内所有传感器数据改由安卓原生采集并直连服务器上报**：退后台、锁屏、切换应用都不中断（与官方 Home Assistant App 同源思路），纯浏览器环境仍走浏览器采集- 新增传感器项支持：电池、网络、Wi-Fi、环境光、接近感应、位置（含逆地理地址）、公网 IP 等（开发规范见 [传感器原生采集开发规范](传感器原生采集开发规范.md)）- 后台定位权限引导：位置类传感器后台刷新需将定位权限设为「始终允许」，设置页一键跳转

仪表盘

- **布局按 Web / APK 双端分开存储**：同一账号在电脑浏览器和手机 APP 可各自维护一套仪表盘布局，互不覆盖

传感器 · 后台实时上报

- **APP 退后台后传感器仍按间隔实时上报**：常驻保活服务以原生心跳驱动采集，WebView 冻结定时器也不影响- **上报间隔可配置**：设置 → 连接与设备 → 设备传感器，10 秒 ~ 1 小时可选（与官方 App 类似）

稳定性

- **程序被杀自动恢复**：常驻服务被系统清理后自动重启并拉起主界面，恢复连接与上报- **开机自启动**：手机重启后自动恢复常驻服务（小米等国产系统需在系统设置中允许「自启动」）

1. [系统简介](#1-系统简介)2. [登录与账号](#2-登录与账号)3. [手机 APP 使用](#3-手机-app-使用)4. [界面总览](#4-界面总览)5. [首页：智能仪表盘](#5-首页智能仪表盘)6. [地图：家人定位](#6-地图家人定位)7. [户型图：2D / 3D 家](#7-户型图2d--3d-家)8. [设备管理](#8-设备管理)9. [场景与自动化](#9-场景与自动化)10. [消息中心](#10-消息中心)11. [智家助手（HA Assist）](#11-智家助手ha-assist)12. [通知中心](#12-通知中心)13. [设置](#13-设置)14. [常见问题](#14-常见问题)

「糯米」是基于 Home Assistant（以下简称 HA）的智能家居控制中心，提供：- **可视化仪表盘**：自由摆放的智能卡片，设备状态、天气、能耗一眼可见- **户型图**：绘制自家平面图，2D 平面图 / 3D 立体效果自由切换，图上直接控设备- **家人聊天**：家庭成员间发文字、图片、语音，支持一对一与多人语音通话- **智家助手**：自然语言控制家电、问天气、闲聊（对接 HA 内置 Assist）- **家人定位**：地图查看家人位置与到家距离- **多端使用**：电脑浏览器、手机浏览器、Android APP 均可；一套账号通用使用前提：家中已部署 Home Assistant，并由管理员配置好服务器连接。

1. 浏览器打开系统地址（由管理员提供，形如 `http://服务器地址:8080`），进入登录页。2. 输入**用户名 + 密码**登录。3. **保持登录**：勾选后 30 天内打开无需重新登录；在公用设备上请勿勾选。4. 首次部署、系统中还没有任何账号时，第一个注册的账号自动成为**管理员**。5. 忘记密码请联系管理员在「用户管理」中重置。

3.1 安装

Android 手机用户可**直接从服务器下载安装包**，无需向管理员索要 APK：

1. 用手机浏览器（或电脑浏览器下载后传到手机）打开系统地址并登录

2. 进入 **设置 → 系统信息**，在「安卓 App」一栏点**「下载安装包」**

3. 下载完成后点击安装（系统首次安装本应用会提示「未知来源」，按引导允许即可）

4. 安装完成后桌面会出现图标「糯米」

**已安装旧版本的用户**：打开 APP 后进入「设置 → 系统信息」，当服务端版本高于本机时会显示**「发现新版本，立即更新」**，点击即可在应用内完成下载并拉起系统安装器，无需卸载重装（升级不丢失账号与地址簿）。

系统要求：Android 7.0 及以上。

3.2 首次配置服务器地址

首次打开 APP 进入地址配置页：

1. 选择协议：**http://** 或 **https://**（内网一般选 http，公网域名一般选 https）

2. 在输入框填写服务器地址，例如 `192.168.1.100:8080`（**不用**再填 http://，左侧开关已选择）

3. 选择网络类型：**内网**（家里 WiFi）或 **外网**（移动网络/异地）

4. 点「保存并连接」，APP 自动测试并进入系统

也可以点**「自动识别内网服务器」**，APP 会扫描常见网段自动发现家里的服务器。

3.3 内网 + 外网两个地址

建议把内网和外网地址都保存：

- 保存第一个地址后点**「仅保存」**，地址会存入列表，可继续添加另一个

- 两个地址都保存后，APP 会**按当前网络自动选用**：连家里 WiFi 优先走内网（快），用移动数据时走外网

- 所有地址都不可达时，APP 自动回到地址列表

3.4 修改 / 管理地址

进入系统后，在 **设置 → 连接与设备 → 服务器地址** 中点「修改服务器地址（内网/外网地址簿）」，即可回到地址管理页增删改地址，不会触发自动连接。

3.5 权限说明

- **麦克风**：首次发语音消息或语音通话时系统弹窗申请，允许后才能录音

- **定位**：仅在使用「地图位置同步」功能时需要

- **通知**（Android 13+）：用于新消息、语音来电的状态栏提醒，未开启时仅能在应用内看到红点角标；可在「设置 → 系统信息」中补授权

3.6 后台运行与自启动

APP 登录后启动一个**常驻前台服务**（通知栏会出现一条低优先级的常驻通知，属正常现象），用于：

- **后台实时上报**：退到后台 / 锁屏后，已启用的设备传感器仍按设定间隔持续上报

- **断线自动恢复**：APP 进程被系统清理后，服务会自动重启并拉起主界面恢复连接

- **开机自启动**：手机重启后自动恢复常驻服务

为保证以上能力可靠运行，建议在系统设置中一次性完成：

1. **电池优化白名单**：把「糯米」设为不限制后台（首次登录时 APP 会引导跳转）

2. **自启动权限**：小米/OPPO/vivo 等国产系统需在「应用管理 → 糯米 → 自启动」中允许（否则被杀后无法自动恢复）

3. **定位「始终允许」**：位置类传感器后台刷新需要（见 13.1 设备传感器）

登录后进入主界面：- **顶部栏**：系统名称与副标题、当前登录用户、系统在线状态、全屏按钮、通知铃铛、消息气泡（带未读红点）、头像菜单（退出登录）- **主导航**（桌面在顶部、手机在底部）：**首页 · 地图 · 户型图 · 设备 · 场景 · 设置**；能耗总览可从首页卡片进入- 手机端为响应式布局，布局自动适配窄屏。

首页是一块自由画布，上面摆放各类**智能卡片**（天气、设备开关、温湿度、地图定位、能耗等）。

5.1 控制设备

- 直接点击卡片上的开关、按钮即可控制设备，状态实时变化（HA 状态通过 WebSocket 秒级推送，无需刷新页面）

- 点击设备类卡片可打开详情抽屉，查看该设备的全部实体与历史

5.2 添加卡片

1. 点右下角悬浮的**「添加卡片」**按钮，展开卡片面板

2. 卡片按功能分组（灯光、环境、媒体、安防等），选择需要的类型

3. 为卡片绑定对应的 HA 实体、选择尺寸后确认，卡片即出现在画布上

5.3 智能编排

点画布上的**「智能编排」**：系统自动扫描 HA 中可用的实体，一键生成一组排版整齐的设备卡片，免去逐个添加。

5.4 卡片工作室（高级）

卡片支持**完全自定义**：可编辑 HTML / CSS / JavaScript，实时预览效果，适合有动手能力的用户制作专属卡片。

5.5 其他

- 卡片可拖动调整位置；画布内容自动保存

- 支持在不同家庭/服务器之间**导出、导入**卡片布局（导入时会提示绑定实体在本地是否存在）

5.6 显示列数

- 手机等窄屏默认**固定 3 列**，不同品牌、不同「显示大小」设置下显示效果一致，卡片自动等比缩放

- 平板/电脑按屏幕宽度自适应列数

- 想手动控制密度：**设置 → 个性化 → 仪表盘列数**，可选「自动 / 2~6 列」；该设置**仅对本设备生效**（本机 localStorage），换设备互不影响

- 地图上显示**家的位置与范围圈**（来自 HA 的 zone 配置）- 开启了「位置同步」的家庭成员会以头像标记出现在地图上- 点**「更新位置」**可立即上报当前位置（浏览器定位需要 HTTPS 环境；APP 内不受此限制）- 位置同步的开关在「设置 → 连接与设备 → 高德地图 & 位置同步」中配置

在户型图页可以画出真实的家，并在图上控制设备。

7.1 绘制户型

1. 进入编辑模式，选择**地板**工具描出房间/整套户型的地面轮廓

2. 选择**墙面**工具沿轮廓布置墙体，可调整墙厚、高度与材质

3. 可摆放门、窗等构件

7.2 2D / 3D 切换

- **2D**：俯视平面图，适合编辑与查看布局

- **3D**：立体渲染效果，墙面材质实时生效；编辑时支持 2D / 3D 同屏对照

7.3 在户型图上控设备

- 编辑模式下可把设备（灯、空调、传感器等）摆放到房间对应位置

- 退出编辑后，直接点击图上的设备图标即可开关、调节，状态与 HA 实时

**设备**页是所有 HA 设备的总清单：

- 顶部搜索框可按**设备名 / 实体名 / 厂商 / 房间**搜索，也可按类型筛选

- 左侧按房间分组列出设备，点击查看右侧详情：设备信息、全部实体、传感器数值

- 设备别名：可给设备起一个家人易懂的名字（仅在本系统内显示，不影响 HA）

- 未挂载到设备的实体会单独列在下方，可收起

**场景**页分三块：- **预设场景**：读取 HA 中的 scene，点一下即可执行（如「回家模式」「观影模式」）；设备不满足条件时显示「不可用」- **自动化规则**：展示 HA 自动化，可**新建规则**、启用/停用、编辑、删除，并查看每条规则的配置- **最近执行日志**：查看自动化最近的触发记录，方便判断规则是否正常运行

点顶部栏的**消息气泡**打开。消息中心是家庭成员间的沟通工具。

10.1 发送消息

- **文字 / 表情**：输入框直接发送；表情面板按分类浏览，支持最近使用

- **语音消息**：切换到语音模式，**按住说话、松开发送、上滑取消**

- **图片**：点「+」可**拍摄**或从**相册**选择发送

- **设备卡片**：点「+」→「设备」选一个 HA 实体发送，对方收到后可直接在卡片上开关设备（按 entity_id 自动匹配本机设备）

- **仪表盘共享**：点「+」→「共享」把当前首页仪表盘布局发给对方，对方可接受后在本机使用，或拒绝

- **语音通话 / 语音群聊**：点「+」可向当前会话发起一对一通话，或选择多人发起群聊（详见 10.3）

自己发出的文字 / 图片 / 语音消息显示**已读 / 已送达**回执；消息发出后一段时间内可点**撤回**（撤回后双方都看到「xx 撤回了一条消息」）。

10.2 会话与未读

- 会话列表按最近消息排序，有未读时顶部铃铛/气泡显示红点角标

- 打开会话即自动标记已读；停留在聊天页时新消息（包括助手回复）也会自动已读，角标实时清零

10.3 语音通话

- 一对一：在与某位家人的会话中发起语音通话，对方收到来电弹窗，可接听或拒绝

- 多人：支持多人语音通话（建议 6 人以内）

- 通话媒体由**服务器中继转发**（与聊天信令走同一条连接），不依赖 P2P 打洞，因此在内网、跨运营商、对称型 NAT 等环境下都能正常通话——只要本端能连上服务器即可

10.4 聊天安全

所有文字消息、会话列表、历史记录均采用**端到应用的加密传输**（ECDH 协商密钥 + AES-256-GCM），即使在内网 http 环境下抓包也只能看到密文；服务重启后会自动重新协商，无需手动操作。

消息列表最顶部固定为**「智家助手」**（机器人图标），它对接 Home Assistant 内置的 Assist：

- **控设备**：直接说「打开客厅灯」「把空调调到 26 度」

- **问信息**：「今天天气怎么样」「卧室现在多少度」

- **闲聊与多轮对话**：支持上下文，上一句说「打开客厅灯」，接着说「再调亮一点」也能理解

助手回复支持**语音朗读**：每条回复气泡右侧有朗读按钮（喇叭图标），点一下用当前朗读引擎朗读，朗读中再点即停止。会话顶部的**「朗读引擎」**下拉可切换声音：

- **智能选择（推荐）**：由系统自动挑选最合适的引擎

- **内置 Edge TTS**：微软在线语音，音色自然，可选晓晓、云希、晓北（东北）、曉曼（粤语）等多种音色

- **系统 / 浏览器自带**：APK 内走安卓系统 TTS（离线），网页走浏览器 Web Speech API

- **HA TTS 引擎**：使用 Home Assistant 中已配置的 TTS 服务

会话顶部还有**「对话代理」**下拉（仅当 HA 中配置了多个代理时出现）：决定智家助手如何思考与回答，选「自动」优先使用 AI 代理（可闲聊问答），也可手动指定某个内置代理（只能控制设备）。

使用前提：

1. 已在 **设置 → 连接与设备** 配置好 HA 地址与个人 Token

2. HA 中已配置助手（默认 Assist 即可）

助手对话与普通聊天一样加密、可查看历史记录。

点顶部栏的**铃铛**打开，展示来自 Home Assistant 的系统通知（如设备离线、自动化提醒、HA 持久通知等），可单条清除或全部标记已读。

设置页分四个标签（普通用户看到前三个，管理员额外看到「用户管理」）。

13.1 连接与设备

| 配置项 | 说明 |

|---|---|

| 我的 HA Token | 填写个人的 Home Assistant 长期访问令牌；智家助手、代控设备都依赖它。Token 仅本人与管理员可见 |

| 服务器地址（仅 APP） | 回到地址簿管理内网/外网地址 |

| 通话铃声（仅 APP） | 自定义**来电铃声**与**呼叫彩铃**（等待接听时的提示音），走系统铃声音量与媒体互不影响；选「无」可静音 |

| Home Assistant 连接 | HA 实例的添加 / 编辑 / 启用停用 / 切换；每个实例可单独开关「忽略证书验证」（本地自签名 HTTPS 需开启） |

| 高德地图 & 位置同步 | 配置地图显示与本人位置上报开关 |

| 设备列表 | 同步 HA 设备注册表，维护设备别名 |

| 设备传感器 | 查看手机/设备上报的传感器数据；逐项开关启用、设置上报间隔、立即上报（详见下方说明） |

| 浏览器命令 | 类似 browser_mod 的能力：授权系统通知、发送测试通知、模拟黑屏 / 保持亮屏、调节屏幕亮度（视觉遮罩）、接近感应解除黑屏。HA 经事件总线 `stickynuo_command` 向本设备下发通知 / 亮屏 / 亮度 / 媒体 / 服务命令 |

| 系统信息 | 显示**网页版本**与**服务端版本**用于确认部署是否更新；**安卓 App** 一栏可下载安装包（网页端）或一键应用内更新（APK 端）；APK 端另有**通知提醒**开关（未开启时消息 / 来电无法提醒）与**消息免打扰**开关（开启后新消息通知不响铃不震动、仍显示在通知栏，来电提醒不受影响；仅对本手机生效） |

**设备传感器**（点开「设备传感器」卡）：

- **启用项**：按设备能力列出可用传感器（电池电量/充电状态、网络类型/信号制式、Wi-Fi 名称、环境光、接近感应、位置（逆地理地址）、公网 IP、时区、触发原因、App 版本等），逐项开关，**只采集已启用项**。

- **上报间隔**：10 秒 ~ 1 小时。APP 退后台后由常驻服务按该间隔唤醒上报，被系统清理后会自动恢复；网页端为页面前台周期上报。

- **立即上报**：点右上角「立即上报」即时刷新一次。

- **采集方式**：**安卓 App 内所有传感器数据均由原生采集并直连服务器上报**（退后台、锁屏、切换应用都不中断，与官方 App 同源）；纯浏览器环境为浏览器采集降级路径。

- **后台定位权限（仅 APP，原生采集模式可见）**：点「去开启」在系统设置中把定位权限改为「**始终允许**」，否则退后台无法刷新位置类传感器（`geocoded_location`）。

13.2 个性化

- **主题风格**：内置 9 套配色主题，点选即时预览，保存后全局生效

- **自定义主题**：可对整套调色板逐项调色（背景、主色、卡片、文字等），实时预览

- **自定义主色**：在预设主题基础上只改一个强调色

- **字体大小**：全局字号调节

- **仪表盘列数**：首页卡片每行列数（自动 / 2~6 列）；**仅对本设备生效**，不随账号同步

- **图标风格**：切换图标整体样式

- **户型图风格**：户型图的配色与质感

- **动画效果**：开关界面过渡动画

- **语音助手**：助手相关偏好

所有个性化设置跟随账号保存在服务器，换设备登录同样生效（**仪表盘列数除外**，它只保存在本设备）；右上角「重置为默认」可一键还原。

13.3 账户

- **修改密码**：输入旧密码与新密码即可；改密后其他设备需重新登录

- **退出登录**：清除本机登录状态

13.4 用户管理（仅管理员）

- **系统名称**：修改整个系统显示的名字（顶栏、登录页、浏览器标题、默认称呼），最长 20 字，保存后所有用户即时看到

- **用户列表**：查看全部用户、创建新用户、设置/取消管理员、重置密码、删除用户

- 每位用户可单独配置 HA Token 与地图使用策略

**Q：打开后提示「无法连接后端服务」？**检查手机/电脑与服务器是否在同一网络；APP 用户可回到地址列表改用外网地址，或点「自动识别」。**Q：设备状态不更新 / 控制没反应？**进入「设置 → 连接与设备」检查 HA 实例是否在线、个人 Token 是否有效（顶部状态显示「系统正常」才表示与 HA 连通）。**Q：智家助手回复出错或不可用？**确认 HA 地址与 Token 配置正确，且 HA 中已配置 Assist 语音助手；多轮对话异常时可稍后重试（系统会自动开启新会话）。**Q：语音消息/通话没声音？**在系统设置中确认已授予 APP（或浏览器站点）麦克风权限；通话双方都需允许麦克风。**Q：收不到新消息提醒？**保持 APP 在后台运行或浏览器页面开启；打开会话查看后角标会自动清除，仍显示未读时切换一下会话即可。APK 用户若完全无通知，进入「设置 → 系统信息」确认「通知提醒」已开启（Android 13+ 需授予通知权限）。若通知有横幅但**没声音、不震动**：升级 APP 到最新版（v1.4.2 重建了通知渠道），并在系统「设置 → 通知 → 糯米 → 消息通知」里确认音效/震动未被手动关闭；不想被打扰时可打开「消息免打扰」。**Q：新消息提醒太吵，能关掉声音吗？**可以。进入「设置 → 系统信息」打开**「消息免打扰」**：新消息通知不再响铃、不震动，但仍显示在通知栏（点开可见），来电提醒不受影响。该开关只对本手机生效。**Q：APP 退后台后传感器数值（电量、网络等）不刷新？**APK 内传感器由**原生采集并直连服务器上报**，退后台 / 锁屏 / 切换应用均不中断；若仍不刷新，进入「设置 → 连接与设备 → 设备传感器」点「立即上报」验证连通，并在系统设置授予定位「**始终允许**」（位置类传感器后台刷新需要），同时把本应用加入电池优化白名单、允许自启动。**Q：智家助手朗读没声音？**在会话顶部「朗读引擎」切换一下：切换后会**立即试读**，响没响当场可知。全部失败时会有提示说明哪些引擎不可用——内置 Edge TTS 需联网；系统 / 浏览器自带依赖设备已安装 TTS 引擎（部分国产手机默认引擎缺中文语音，建议选「内置 Edge TTS」）；HA TTS 需 HA 中已配置对应服务。APP 退后台后朗读被系统静音属正常限制。**Q：手机上状态栏颜色和主题不一致？**Android APP 的状态栏/导航栏会自动跟随当前主题底色；若异常，升级到最新版 APP 即可。**Q：换了手机如何迁移？**账号、布局、主题、聊天记录都在服务器上。新手机浏览器登录后从「设置 → 系统信息」下载 APP、登录同一账号即可，无需手动迁移。**Q：忘记密码？**联系管理员在「设置 → 用户管理」中重置。

▼▼▼

更多详情内容见原帖...