HeimLink App 使用说明：日志与开发者选项
这一页讲报问题时用得到的功能：设置页的诊断分组、上传日志、导出日志，以及连点版本号解锁的开发者选项（调试工具台、调试桥、控制页更新）和内测包才有的 Debug 页。
报问题时最有用的三步
- 复现问题后马上点右下角的上传按钮，选「最近 15 分钟」，把得到的 6 位上传 ID 写进工单。
- 在设置 → 诊断的「Operator」里填上自己的名字，上传的日志会带上它，开发者一眼能分清是谁的手机。
- 截图时把设置页「诊断」分组的 Env、Build、Protocol 三行带上，或者把版本号一起写进工单。
设置页的诊断分组
所有构建都有
| 项目 | 说明 |
|---|---|
| Env | 这个包的环境：development（开发）、preview（内测）或 production（商店）。 |
| Build | 构建信息：代码来自哪个提交、什么时候打的包。 |
| Protocol | 这个包实现的空中协议版本。设备固件与它不匹配时配对会报「该设备使用的协议版本不受支持」。 |
| Operator | 输入框，填持机人的名字（最长 32 字），会随每条上传的日志一起发出。只存在日志设置里，不影响设备数据。 |
| Debug | 只有开发包和内测包有，进入 Debug 页，见下文。 |
| 导出日志 | 右侧显示当前日志条数和大小。点开选时间范围（最近 1 小时 / 最近 24 小时 / 最近 7 天 / 全部日志），生成一个 JSONL 文件走系统分享菜单，第一行是手机与构建信息。适合用微信直接发给开发者。 |
| 清除日志 | 删掉本机全部日志。 |
上传日志
右下角的悬浮上传按钮
开发包和内测包默认显示这个按钮；商店包默认隐藏，解锁开发者选项后可以打开。点开后按顺序：
- 选时间范围：「最近 15 分钟」（默认高亮）、「最近 1 小时」、「最近 8 小时」、「全部日志」。范围越短越好定位，刚复现完就选 15 分钟。
- 「正在整理日志…」然后「正在上传…」，按钮上会转圈，期间可以继续用 App。
- 「日志已上传」，下面是大写的上传 ID和「复制」按钮，以及这次上传的范围、条数和大小。把 ID 填进工单，开发者用它取日志。
失败时的提示：「所选时间范围内没有日志。」换更长的范围；「所选时间范围的日志超过 50 MiB，请选择更短的时间范围。」；「日志未上传，请检查网络后重试。」点「重试」，不想传了点「放弃」；「文件已到达对象存储，但登记失败，请重新上传。」重新来一次。Debug 页里的「Upload history」能看本机每次上传的 ID、时间和大小。
解锁开发者选项
设置 → 关于 → 版本
连续点「版本」这一行 7 次，两次点击间隔不能超过 3 秒。从第 4 次起会提示「再点 N 次解锁开发者选项。」，解锁后提示「开发者选项已解锁。」，设置页底部出现「开发者选项」和「控制页更新」两个分组。所有构建都能解锁，解锁状态会保存。
开发者选项
三个开关与调试桥
| 项目 | 说明 |
|---|---|
| 显示调试控制台 | 打开后屏幕底部常驻一块黑色的「调试工具台」，见下文。 |
| 显示上传日志按钮 | 控制右下角的悬浮上传按钮显不显示。Debug 页里的「Upload logs」不受影响。 |
| 向调试桥同步日志 | 总开关。还没有地址时打开它会直接弹出扫码；关掉同时清除地址。下面一行小字显示当前地址。 |
| 扫码接入 | 扫电脑上 hldb start 打印的二维码。不是调试桥的码会提示「这不是调试桥的二维码。」。 |
| 手动输入地址 | 填 hldb://IP:端口?token=… 形式的完整地址。 |
| 状态 | 未连接 / 连接中… / 已连接，会话 #N。出错时显示原因：「令牌不匹配，请重新扫码」「调试桥版本更新，请升级 App」「App 版本较新，请到群里下载新版调试桥」。 |
| 断开并清除 | 有地址时才显示，断开并忘掉这个地址。 |
调试桥连上后 App 顶部会出现一个小标记「调试桥：正在同步日志」，日志实时发到电脑，断线重连后自动补齐。调试桥程序由开发者发布到群里，手机和电脑要在同一个 Wi-Fi。
调试工具台
打开「显示调试控制台」后，App 界面被压到上半部分，下半部分是黑底的工具台。顶部一行左边写着「调试工具台」，右边是三个页签；按住这一行上下拖可以改高度，轻点仍然是切页签。
- logs：实时日志流，每行是时间、级别、命名空间、消息，点一行展开完整内容并复制。右上角「Export」分享、「Clear」清空。
- device control：控制指令与设备上报的对账。顶部「当前状态」是设备最近一次上报的各项值，变化的项高亮。列表可按全部 / 控制 / 上报 / 不一致过滤，每条带状态标签：发送中、已确认、不一致、设备拒绝、控制失败、未回报、设备上报。「不一致」表示 App 下发的值和设备回报的值不同，是最该截图的一类。
- ble：蓝牙层的状态区和事件流。每一行的含义与该查什么见 调试工具台 BLE 页签怎么读。
控制页更新
开发者选项解锁后出现的分组
设备控制页是内置在 App 里的网页，这里可以不发新 App 就换一版控制页。App 不会自动检查或安装，只有这里一个入口。
| 项目 | 说明 |
|---|---|
| 渠道 | 点一下在 stable → beta → dev 之间轮换。 |
| 检查更新 | 向服务器查询所选渠道每个控制页的版本，期间显示「正在检查…」。 |
| 每个控制页一行 | 例如「Thermostat (heimlink-thermostat)」，下面是「在用 x · 内置 y · 已下载 z」：在用是现在打开设备页跑的版本，内置是随 App 打包的版本，已下载是之前从服务器装的版本（没有则显示「无」）。再下面一行是检查结果。 |
| 安装 | 只在结果为「渠道版本 x，可安装」时出现。装完显示「已安装 x，下次打开设备页生效」。 |
其它结果：「渠道版本 x，不高于在用版本」表示服务器上的不比现在的新，不会装；「该渠道没有可用的包（HTTP n）」表示这个渠道没发布；「检查失败：…」多为网络问题。
固件通道
与开发者选项的关系
固件升级页的 beta / stable 通道开关，在开发包和内测包里一直可用，默认 beta；商店包默认只用 stable，解锁开发者选项后才出现开关，可以切到 beta 测试未正式发布的固件。详见「固件升级」一页。
Debug 页
设置 → 诊断 → Debug，只有开发包和内测包有
页面顶部写着「Isolated debug tools live here and do not change core device flows.」，工具分三组：
| 分组 | 项目 | 说明 |
|---|---|---|
| HTTP Demos | WebView Local HTTP Demo | 开发用的网页加载演示，测试不用管。 |
| Diagnostics | Logs | 日志查看器：「Share / Copy」分享、「Pause / Resume」暂停刷新、「Refresh」、「Clear」；可按级别（level）和命名空间（ns）过滤，点一条展开完整内容。 |
| Upload logs | 与右下角的上传按钮同一个流程，按钮被隐藏时从这里上传。 | |
| Upload history | 本机的上传记录：上传 ID、时间、范围、条数、大小。 | |
| Error Capture | Trigger uncaught exception | 故意制造三种程序错误，用来验证错误捕获是否正常。测试时不要点，点了会看到错误页或日志里多出一条 App:* 的错误。 |
| Trigger unhandled rejection | ||
| Trigger render error |