同步移动端工程、设备控制改进与发布资料

移动端相关内容/开发要求/移动端需求.md

@@ -0,0 +1,68 @@
+# 移动端需求
+
+## 1. 产品与范围
+
+名称：奇妙小屏幕。Android 首版为 BLE 控制器，支持 Android 8.0（API 26）以上。连接不要求核桃派已联网，也不要求手机与设备在同一 WiFi。设备、内容、设置为三个一级页面，中文为首版界面语言。
+
+| 稳定编号 | 行为与合格标准 |
+|---|---|
+| MOBILE-PLATFORM | KMP 与 Compose 共享业务、界面；Android 本次交付，iOS 平台实现及发布不在本次范围。 |
+| MOBILE-DISCOVERY | 前台扫描项目 BLE 服务；显示昵称、固定短编号和信号强度；首次点击目标后免系统配对连接。 |
+| MOBILE-IDENTITY | 用设备持久随机 ID 区分设备；设备昵称可改，短编号不变；手机昵称默认型号，可改。蓝牙地址仅作扫描时临时连接句柄。 |
+| MOBILE-CONNECTION | 一机一连接、一设备一控制会话；连接暂停广播，断开恢复；握手无效或超时断开，连接成功以握手完成为准。 |
+| MOBILE-RECONNECT | 前台自动尝试上次设备，失败回到可扫描状态，不改连其他设备；主动断开后本次前台会话不立即反复重连。 |
+| MOBILE-BACKGROUND | 连续后台 30 秒释放 BLE，停止预览和轮询；设备继续原显示；30 秒内返回取消释放；系统杀进程由设备会话超时释放。 |
+| MOBILE-SECURITY | 免连接密码，标准算法自动加密；拒绝无效协议，不承诺鉴别正版 App 或抵抗主动仿制／中间人。无任意 shell 或文件接口。 |
+| MOBILE-STATUS | 设备页展示连接、版本、协议、实际刷新率／帧数／截止丢失／最后错误、资源、网络、电压与保护、性能模式、容量及当前内容；不可用字段显示原因，不伪装为零。 |
+| MOBILE-LIBRARY | 读取用户静态模板、动图、演示内容；名称、类型、静态缩略图、空列表与失效项状态清晰；不编辑、复制、排序或删除内容。 |
+| MOBILE-PLAYBACK | 选择播放；动画暂停／继续、跳转、沿用设备支持的固定倍速；过期资源或播放会话提示刷新，不控制已替换会话。 |
+| MOBILE-DEFAULT | 设置开机默认会保存并立即播放，界面明确说明；失败遵循设备回滚语义，不虚报成功。 |
+| MOBILE-PREVIEW | 相关页可见且已连接时，每 2 秒请求当前逻辑帧，支持手动刷新；最多一个在途预览，命令优先，显示最近成功时间和过期状态。 |
+| MOBILE-WIFI | 由核桃派扫描网络，手机选择或手填隐藏 SSID；输入密码、DHCP／静态 IPv4、立即／下次开机生效；区分保存成功、正在连接、连接失败和实际在线。 |
+| MOBILE-WIFI-SECRET | 不读取设备已存密码；保留密码是明确的“不更改”操作，不把空文本误作清空；本次输入可临时显示，提交后清理，日志和持久缓存不保存。 |
+| MOBILE-SETTINGS | 网络提示、亮度、方向、允许刷新率、性能模式；字段仅提交本次修改，全部值由设备校验和回读确认。 |
+| MOBILE-WEB-COEXIST | 网页和手机并用；最近成功操作生效；手机连接网页短提示加顶栏常驻手机名；初次打开网页也显示当前状态，不伪造新连接提示。 |
+| MOBILE-ERRORS | 权限未授予、蓝牙关闭、设备忙、不兼容、断线、超时、冲突和失败可区分；操作有界结束并恢复控件，保留未提交草稿。 |
+| MOBILE-COMPAT | 协议能力发现及主版本协商；新增可选字段不破坏旧 App；破坏契约的设备改动必须登记移动端影响。 |
+| MOBILE-RELEASE | App 独立版本，首版仅 debug APK；正式签名和后续 App 迭代必须用户明确要求。 |
+| MOBILE-TEST-PRIVACY | 私有测试登记不进 Git；空白示例和脚本可提交；自动测试精确选择授权设备，证据脱敏。 |
+| MOBILE-VISUAL-GATE | 一般前端／BLE 入口改动不要求实屏视觉检查；确需时先暂停询问用户如何启动，未经指示不启动采集或视觉程序，不切换实屏测试图案。 |
+
+MOBILE-RECONNECT／MOBILE-ERRORS 补充：断线清除旧画面、状态、缩略图队列；重新连接从新会话读取。主动断开取消未完成操作，旧连接或旧扫描的迟到回调不得覆盖新连接。业务冲突／内容不存在等正常错误回复不等同于传输失效，不应仅因此断开已经认证的会话。
+
+不在首版：绘画、资源编辑／上传／导出／删除、FRP 配置、OTA 上传、电压校准、应用商店、自动更新、云账户。缩略图与当前帧读取属于控制界面预览，不等于提供图案文件导出。
+
+## 2. 交互规则
+
+- 连接状态始终可见；设备忙不会强行踢掉另一个手机。断开不会清屏、停止动画或改变用户配置。
+- 修改设备昵称需要已连接，修改手机昵称为 App 本地操作并同步当前会话；只显示普通文本，不作身份认证。
+- 设备昵称 1–40 Unicode 字符，手机昵称 1–40 字符；首尾空白去除，拒绝控制字符；设备编号由持久 UUID 前 8 个十六进制字符构成，冲突时显示完整 ID。
+- 模板列表保留设备现有顺序，分页读取；动图采用首帧静态缩略图，空动图不可播放。
+- WiFi 扫描不是由手机代扫，不额外读取手机 WiFi 凭据。首版支持开放网络与个人密码网络，企业 EAP 提示暂不支持；真实硬件支持能力由设备报告。
+- WiFi 切换不得依赖 HTTP 仍可达，进度经 BLE 查询；失败保留可再次修改入口，不自动替用户猜密码。
+- 修改刷新率仅限设备允许的 15、20、30、45、60、80、100 Hz；方向限 0、90、180、270。其他范围沿用设备业务校验并通过协议能力公布。
+
+## 3. 平台差异
+
+| 项目 | Android 本次 | iOS 后续 |
+|---|---|---|
+| UI／业务 | 共享 Compose、状态机、协议模型 | 复用共享模块，按平台适配布局 |
+| BLE | Android BluetoothGatt，串行 GATT 操作 | CoreBluetooth，独立平台实现 |
+| 权限 | API 26–30 扫描定位权限与系统要求；31+ 附近设备扫描／连接权限，不索取后台定位 | Info.plist 蓝牙用途描述，按 iOS 生命周期实现 |
+| 后台 | 30 秒释放为上限目标；进程终止也能由设备释放 | 不假设后台持续运行，策略需未来真机确认 |
+| 构建 | Windows、Android Studio、Gradle、debug APK | macOS／Xcode、签名及真机测试，不声称当前已验证 |
+
+## 4. 更新约束
+
+需求变更先更新本表，再更新详细设计、协议和测试。设备更新不得自动修改 App；影响通信能力、驱动边界或部署行为时必须填写 `跨端兼容与变更记录.md`。首版开发是本次明确授权，不代表后续自动更新授权。
+
+测试编号、执行位置和合格条件见 `../安卓app/如何安卓测试/README.md`。阶段进度不是需求的一部分。
+
+## 2026-09-26 四栏界面修订（替代同编号旧描述）
+- MOBILE-STATUS／PREVIEW：四栏为连接、设备状态、显示内容、设备设置。顶部小字显示设备昵称、代号及实际 WiFi 状态；两处预览统一“设备画面”与右侧手动刷新，正常时不显示刷新频率和确认时间，仅过期提示。删除运行状态和容量详情。
+- MOBILE-DISCOVERY／IDENTITY／RECONNECT：App 按完整 ID 记忆成功连接设备；保存列表长按重命名或忘记。只可重命名当前连接设备，忘记它则断开并取消自动重连。扫描可与已连接会话并行，首次和忘记后的设备只由手动选择连接；自动重连只尝试上次已记忆设备。切换先断开旧会话。
+- MOBILE-LIBRARY：列表使用设备保存的混合顺序；分页顺序变更返回冲突，App 重新读取完整列表。
+- MOBILE-WIFI／SETTINGS：亮度、中文方向；移除 App 刷新率／性能模式入口。WiFi 状态、默认收起的设置、提示秒数依次排列；SSID 右侧扫描，选择自动填入。DHCP 开启自动获取、关闭展开静态参数；仅立即生效，提交前确认。认证错误须有可靠设备原因，不把通用失败写成密码错误。
+- MOBILE-WIFI-SECRET：不回读原密码，“已设置密码”占位，原 SSID 留空保留，替换密码只驻留内存；取消确认不提交。
+- MOBILE-APP-SETTINGS：顶部三点菜单关于／软件设置，关于显示版本、构建编号及北京时间打包日期；手机昵称可离线修改并同步当前会话。
+- MOBILE-TEST-PRIVACY：本 App 调试所需测试权限可通过登记手机 ADB root 直接获取，无需重复询问；所有自动点击使用 root 并依据实时语义位置，禁止无障碍绕过。特殊情况或权限不足必须停止等待用户。视觉和物理门禁不变。

移动端相关内容/开发要求/设备通信协议.md

@@ -0,0 +1,89 @@
+# 奇妙小屏幕 BLE 控制协议 1.0
+
+本文是首版实现契约。Python／Kotlin 加密黄金向量、分片和 Android 13 真实 BLE 已有通过记录；各业务验收范围见测试结果归档，不能据此推断所有场景通过。命令只能进入设备公共业务服务，不调用网页 DOM，不提供 shell、任意路径或原生驱动地址。变化登记到跨端兼容记录。
+
+## 1. GATT 与广播
+
+| 项目 | 固定 UUID／行为 |
+|---|---|
+| Service | `9f57a001-6c31-4c58-bc22-1f728b641001` |
+| RX | `9f57a002-6c31-4c58-bc22-1f728b641001`，Write with response；手机到设备 |
+| TX | `9f57a003-6c31-4c58-bc22-1f728b641001`，Notify；设备到手机 |
+
+使用传统可连接 BLE 广播，包含服务 UUID；扫描响应提供 `QMS-` 加短编号。完整昵称与持久 UUID 在握手后取得并缓存；首次扫描尚无昵称时显示产品名与短编号。改名不改变 ID。持久 UUID 在设备首次启动生成，放 `/var/lib/matrix-screen-controller/mobile/identity.json`，镜像构建不得携带已生成身份。短编号为 UUID 去连字符后的前 8 位，仅展示用。
+
+禁用经典蓝牙配对及不必要的音频／文件传输 profile；GATT 不要求系统 bonding。不能保证其他工具完全无法建立物理连接；保证未完成本协议握手不得执行控制。手机先订阅 TX，再发送握手。连接后停止广播；服务端另外检查并拒绝第二个连接，不以“不广播”代替互斥。
+
+10 秒内未完成握手释放连接。活动会话最多间隔 5 秒发送业务请求或 ping；当前 Android 前台每 2 秒轮询状态，后台释放前每 2 秒 ping。设备连续 20 秒未收到有效消息释放。单次普通命令超时 10 秒，WiFi 扫描 20 秒；耗时切网作为任务立即返回。设备检测断开后目标 5 秒内恢复广播，蓝牙硬件不可用时显示故障并有界退避重试，不阻止显示服务。
+
+## 2. 分片与消息
+
+所有整数使用网络字节序。每条 RX／TX 特征值是一个分片：`magic:uint16=0x514d, wire:uint8=1, kind:uint8, message_id:uint32, index:uint16, count:uint16, total_length:uint32, payload:bytes`。头长 16 字节，payload 上限为 `ATT_MTU - 3 - 16`；必须在 MTU 23 时也可工作，不能强制大 MTU。
+
+kind：1 为 client hello，2 为 server hello，3 为加密记录，4 为握手拒绝。message_id 在当前方向逐条递增，重连归零。每方向仅允许一个重组消息，index 从 0 连续递增，count 与 total_length 必须一致；总消息不超过 65536 字节。重复、乱序、超长、类型未知或 15 秒未完成重组均丢弃并关闭会话，不允许部分消息触发业务。两端操作队列串行；已开始的帧消息完整发完，控制在下一条消息优先，缩略图和预览不得积压。
+
+业务载荷为 UTF-8 JSON 对象。请求：`{"id":"1","method":"status.get","params":{}}`；成功：`{"id":"1","ok":true,"result":{}}`；失败：`{"id":"1","ok":false,"error":{"code":"CONFLICT","message":"内容已改变，请刷新","retryable":false}}`。id 为当前会话递增的十进制字符串，最大 64 字符；服务端只接受新的请求编号，重复编号返回错误而不再次执行变更。连接中断后不得自动重放变更；先回读状态，必要时请用户重试。
+
+通用错误：`BAD_REQUEST`、`NOT_READY`、`BUSY`、`UNSUPPORTED_VERSION`、`UNSUPPORTED_CAPABILITY`、`NOT_FOUND`、`CONFLICT`、`TIMEOUT`、`DEVICE_ERROR`。message 不包含密码、内部路径、命令行、异常堆栈或设备调试身份。握手拒绝只含固定错误码。
+
+## 3. 自动加密
+
+传输上限补充：ServerHello 在未建立会话时一律按 MTU 23 分片。`session.open` 可携带整数 `receive_mtu`（23～517，缺省 23），表示手机当前实际可接收的 ATT MTU；后续下行取该值与 BlueZ 写入回调 MTU 的较小值。此字段只限制分片大小，不影响加密参数。针对实际手机报告 247、BlueZ 回调报告 517 的不一致情况，禁止仅依据 BlueZ 数值发送大通知；断线重置上限为 23。
+
+使用成熟库的 P-256 ECDH、HKDF-SHA256 与 AES-256-GCM，不手写椭圆曲线／AES。客户端和服务端每次连接都生成新的临时密钥和 32 字节随机数，公钥使用 65 字节 SEC1 非压缩编码。JSON 内二进制为标准 Base64，包含必要 padding。
+
+ClientHello 字段：`protocol_major:1, protocol_minor:0, public_key, random`。ServerHello 字段相同。协商拒绝未知主版本，不建立降级明文会话。握手 JSON 不包含手机名称或 WiFi 信息。
+
+设 `C`、`S` 为收到的两个完整原始 hello JSON UTF-8 字节（不重新序列化），`T=SHA256(uint32(len(C)) || C || uint32(len(S)) || S)`。salt 为 `SHA256(client_random || server_random)`，IKM 为 ECDH 共享秘密，info 为 ASCII `QMS-BLE-1` 加 T。HKDF 输出 72 字节：前 32 为 c2s key，接着 32 为 s2c key，最后两个 4 字节分别为 c2s／s2c nonce prefix。
+
+加密记录为 `sequence:uint64 || ciphertext || tag:16bytes`。每方向 sequence 从 0 开始且必须等于期望值；nonce 为该方向 4 字节 prefix 加 sequence；AAD 为 ASCII `QMS-BLE-1`、T、方向字节（c2s=0，s2c=1）和 sequence。序号不回绕；鉴别失败、重放、跳序、非法公钥立即释放会话。会话密钥只存内存，断开销毁。
+
+第一条加密请求必须为 `session.open`，带手机昵称；设备成功回复才算控制会话建立、才通知网页。应用层加密防被动窃听，不认证正版 App，不抵御主动中间人；UUID、昵称和 APK 内置常量都不是认证凭据。
+
+## 4. 业务接口
+
+响应包含协议主次版本与 capabilities。客户端忽略未知可选字段；缺少必需字段为协议错误。不存在某能力时隐藏或禁用相关操作并解释，不猜测默认支持。时间、大小和单位固定在字段名及模型中；不把网页内部 config 整包当作移动端契约。
+
+| method | params | result 与业务边界 |
+|---|---|---|
+| `session.open` | `client_name` | `device_id, device_name, short_id, protocol_major, protocol_minor, capabilities, limits`；名称规则见需求。 |
+| `session.ping` | 空 | `alive:true`；刷新有效会话活跃时间。 |
+| `session.rename` | `client_name` | 回读当前名称并同步网页连接状态。 |
+| `device.rename` | `name` | 更新持久设备昵称，返回身份元数据，不改变 UUID。 |
+| `status.get` | 空 | 当前结构复用设备状态：`state, screen, service, power, resources, network, frp, ui, system, mobile` 等字段；手机使用的路径列于下文。不可用原因沿用各子对象定义，不能假设所有子对象均有 available 字段。 |
+| `storage.get` | 空 | 设备与软件容量统计，复用现有有界缓存，单位 bytes。 |
+| `settings.get` | 空 | 当前设置、可写字段、允许值及设置修订；不得带 WiFi 密码。 |
+| `settings.patch` | `expected_revision, changes` | 仅允许亮度、方向、刷新率、性能模式、网络提示延迟；校验冲突后复用现有业务并回读。 |
+| `wifi.scan` | 空 | `networks:[{ssid,security,signal_percent,connected}], scanned_at_ms`；时间为 Unix 毫秒；同 SSID/安全类型去重取最强信号，隐藏 SSID 用手动输入。 |
+| `wifi.get` | 空 | 已保存配置（不含密码）、`password_configured`、实际连接状态、待生效状态。 |
+| `wifi.set` | `expected_revision, ssid, security, password_action, password?, ipv4_mode, address?, prefix?, gateway?, dns_servers, activation` | password_action 为 keep／replace／none；none 仅开放网络；activation 为 immediate／next_boot；返回配置修订与可选 task_id。 |
+| `task.get` | `task_id` | `state:pending/running/succeeded/failed, stage, error?`；只允许查询本协议产生的有界任务，不提供任意系统任务入口。 |
+| `library.list` | `cursor?, limit` | 默认 20、最大 50；返回库修订、条目和下一游标。条目含 type、id、revision、name、is_demo、playable、thumbnail_revision。翻页库变化返回 CONFLICT。 |
+| `library.thumbnail` | `type,id,revision` | 返回 `mime:image/png, data_base64`，64×64 静态缩略图；动画使用首帧。 |
+| `content.play` | `type,id,revision` | 使用既有内容解析与显示服务；过期拒绝，不能顺便修改默认内容。 |
+| `content.default.get` | 空 | 当前默认内容元数据。 |
+| `content.default.set` | `type,id,revision` | 保存并立即播放；失败按既有默认内容事务回滚，返回最终状态。 |
+| `playback.patch` | `session_id,paused?,position_ms?,speed?` | 操作既有动画会话；过期会话 CONFLICT，速度限设备已有枚举。 |
+| `frame.get` | `known_revision?` | 未变返回 `unchanged:true`；变化返回逻辑 RGB 帧的 PNG Base64、frame_revision、采样时间。不传完整动图。 |
+
+settings 与 wifi 的 revision 为设备生成的不透明字符串，相关状态变化即更新；网页修改也必须更新同一修订。配置检查与提交在公共控制服务内串行执行，防止“检查通过后被另一个客户端覆盖”。错误不得回传旧密码或完整输入。
+
+## 5. 生命周期与兼容
+
+系统状态每 2 秒读取，容量进入设备页时读取，库按进入／刷新读取，缩略图仅为可见项排队且按设备 ID、条目 ID、修订缓存。后台立即停预览，30 秒关闭会话。重新连接获取完整状态，不把本地缓存写回设备。
+
+BLE 只接收白名单方法。旧客户端遇新能力忽略；旧设备缺某能力时客户端明确提示。不兼容主版本停止控制并返回列表。蓝牙关闭、主服务重启、OTA 维护或适配器消失时失效会话不可复用；恢复后重新握手，不恢复旧密钥。
+
+## 6. 契约测试要求
+
+共享固定的测试私钥、hello 原始字节、HKDF 输出、双向密文与分片向量；测试密钥明确仅为公开夹具，不能来自设备。Python 与 Kotlin 双向互验，覆盖 MTU 23、大 MTU、边界分片、非 ASCII 昵称、错误公钥、篡改、重放、断线、库翻页冲突、任务失败和主版本拒绝。接口最终字段模型及黄金向量必须随实现提交，未经测试不能写成协议验收通过。
+
+## 7. 当前状态模型的维护边界
+
+`status.get` 当前复用设备只读状态构造函数，不依赖 REST URL 或网页控件；它仍与设备状态字段存在结构耦合，不能宣称只有驱动改变才需要检查手机兼容。移动端当前使用 `state.animation_playback`（active、session_id、paused、position_ms、total_duration_ms、speed、supported_speeds）；其余状态作为详情展示。任何这些字段的删除、重命名、类型或含义变化必须按协议变更登记，不可随网页重构破坏旧 App。
+
+`frame.get` 变化时提供 sampled_at_ms；unchanged 回复仅有 unchanged 与 frame_revision。App 用本机成功收到回复的时间表示新鲜度，避免设备与手机时钟偏差。缩略图缓存按当前连接隔离、按 type/id/revision 标识；断线清理，不把手机缓存写回设备。
+
+## 2026-09-26 兼容扩展
+library.list 的用户条目遵循设备持久混合顺序，顺序变化影响 library_revision 和游标。演示条目固定在用户条目之前。
+task.get 可附加脱敏 error_code（AUTH_FAILED、NETWORK_UNAVAILABLE、IP_CONFIG_FAILED、UNKNOWN）；旧客户端可忽略。没有可靠原因时用 UNKNOWN。wifi.get 仍不含密码。协议主版本保持 1。

移动端相关内容/开发要求/跨端兼容与变更记录.md

@@ -0,0 +1,54 @@
+# 跨端兼容与变更记录
+
+## 规则
+
+- 设备版本取设备自己的 VERSION，App 版本取 Android 工程独立版本，BLE 协议主次版本独立编号。
+- 主版本相同的兼容新增通过 capabilities 宣告；旧 App 忽略未知可选字段，不发送未知能力命令。
+- 删除／重命名命令、改变单位／含义、强制字段变化或加密线格式改变是破坏兼容；需新的主版本或保留旧版本适配。不能直接让旧 App 错误控制设备。
+- 驱动内部实现变化但对外契约不变，登记“无需 App 更新”和验证依据；不能以“驱动没改”为由忽略业务协议破坏。
+- 没有用户 App 迭代指令时，只记录待办，不擅自修改或发布 App。
+- 每次跨端变更填写：需求编号、设备改动、协议版本、受影响 App、兼容策略、实际验证、待办、是否已有用户 App 授权。
+
+## 当前基线
+
+| 变更 | 状态 | 协议 | 移动端影响 | 授权与验证 |
+|---|---|---|---|---|
+| 首次 BLE 控制器、公共业务层、WiFi 扫描、网页连接提示 | 设计已确认，功能待实施 | 计划 1.0 | 新建 Android 首版，未来 iOS 复用 | 用户已明确授权首版；尚未完成设备与 APK 验收 |
+| 视觉检查门禁 | 文档约束 | 无协议变动 | 普通 UI／BLE 开发不强制实屏；确需视觉检查必须先询问启动方式 | 用户明确要求；适用于本轮及后续 |
+
+## 后续登记模板
+
+2026-09-26，WEB-PERFORMANCE-MODE／DEPLOY-OTA-KERNEL-RECOVERY：设备 REST 的 `/api/ota/status` 增加可选 `kernel_recovery` 状态，`/api/status.system.performance_mode.last_error` 对缺失 cpufreq 给出具体原因；已有字段和 BLE 协议不变。旧 App 忽略新增 REST 字段，无需 App 更新。本轮仅改设备端；本机和实机验证结果以本次交付记录为准。
+
+2026-09-25，MOBILE-RECONNECT／MOBILE-ERRORS：App 增加连接／扫描代次隔离，主动断开取消未完成命令，清理失效画面与状态缓存；轮询收到业务拒绝时保留连接。模拟平台仅编入 commonTest，通过真实分片／RPC 层测试旧回调、传输失败、未完成操作取消后的恢复。协议不变、设备不需更新；本轮首版授权内实施，真机结果另行归档。
+
+2026-09-25，DEVICE-MOBILE-SETTINGS／CONFIG-WIFI：实机静态网络含多个 DNS，nmcli 返回逗号分隔而旧解析仅按换行，读回配置不能直接保存。修复设备 NetworkManager 解析，保持 DNS 数组契约；网页／App 共同受益，协议不变，无需 App 功能升级或另发版本。当前已授权首版联调；需设备部署及原网络重新应用验证，结果见当日归档。
+
+2026-09-25，MOBILE-CONNECTION／MOBILE-RECONNECT：实机日志证实缓存 MTU 回调早于实际交换完成，提前服务发现会停滞；Android 改为等待实际协商值，再启动一次服务发现，保留 2 秒后备启动。设备端、协议线格式与驱动未改变，无需重新部署核桃派。Android 13 的生产 Controller 三页读取、短暂后台保持、30 秒后台释放及前台重连实测通过（115.718 秒）；完整持续复测与 Activity 语义测试继续进行。用户明确授权 root 切换专用手机蓝牙，已关闭并恢复成功。
+
+2026-09-24，MOBILE-RECONNECT／MOBILE-ERRORS：Android 修复内部通信超时被视为主动取消而残留连接状态的问题；GATT 建立失败仅在握手前针对同一设备有限重试。对厂商重复 MTU 回调去重服务发现，接收上限保守限制为请求值 247。设备业务契约与协议版本不变，不重放写命令。用户已授权本轮 App 实现及断线排查；验证状态以测试结果归档为准。
+
+首版联调补充：`session.open.receive_mtu` 为可选字段，缺省 23，声明手机实际接收分片上限。真实环境曾出现 Android MTU=247、BlueZ 回调 MTU=517，导致下行大分片丢失；现采用应用声明与 BlueZ 上限的较小值，ServerHello 固定按 MTU 23 分片。协议主版本保持 1，缺省行为可供未发送此字段的客户端使用。本轮用户已授权 Android 首版修改，Python／Kotlin 同步实现；真实 Android 13 只读会话及断开重连测试通过，尚未最终发布。
+
+```text
+变更日期：
+需求编号：
+设备侧变化：
+协议主次版本及能力：
+受影响的 App 版本：
+兼容策略：
+验证证据（通过／未验证／不适用）：
+移动端待办：
+用户是否明确要求 App 迭代：
+```
+
+### 2026-09-25 验收补充
+
+Android 断线清理与旧扫描回调隔离已通过模拟及 Activity 真机回归；UI 新增预览确认时间／过期提示、开机默认内容回读和临时密码可见开关。沿用既有 frame.get、content.default.get 等接口，设备协议主版本不变。DHCP 不再提交残留静态 DNS。昵称长度文档对齐已实现的 40 字符上限。网页文案生成索引同步，部署清单包含 ui-copy.json，不影响显示驱动。连续 BLE 读取完成后第二次连接出现过状态 62，保留失败记录并改为重新扫描后复测，不宣称根因已证明。
+
+网页 WEB-MOBILE-PRESENCE 修正：首次载入已连接状态仅更新顶栏，不提示新的连接事件；之后检测到会话代数变化才短提示。只改网页事件判断，不改协议、App 或驱动，设备功能时间随本次可部署修复更新。
+
+后续升级安装路径：ota_components 在存在移动端安装脚本时即使没有 FRP 载荷也进入持久系统组件事务，备份并恢复蓝牙配置、项目 drop-in、启用／屏蔽及运行状态；旧日志保持原行为。35 项组件／生命周期本机测试通过；真实完整 OTA 尚未执行，本轮不导出包。协议与 App 无需因此改变。
+
+### 2026-09-26 四栏优化
+用户明确要求 App 迭代。App 0.2.0 / code 3：四栏、设备记忆、中文 WiFi 设置、关于与本地设置；旧记录通过后续握手迁移。设备 library.list 对齐持久顺序，task.get 增加可选 error_code；协议主版本 1，旧 App 忽略新字段。无驱动修改，无新板端依赖，不导出 OTA／IMG。实际验证结果另行归档。