update at 2026-03-18 13:35:19

dash/docs/kindle-voyage-5.13.6-white-screen-handoff-zh.md

@@ -1,22 +1,25 @@
 # Kindle Voyage 5.13.6 白屏/KUAL/SSH 交接文档
 
-本文记录 2026-03-15 这轮 dashboard 调试在后半段进入的异常状态，目标是给下一次接手排障的人一个明确起点，避免继续沿着已经证伪或高风险的路径重复试错。
+本文记录 2026-03-15 到 2026-03-17 这轮 dashboard 调试在后半段进入的异常状态，目标是给下一次接手排障的人一个明确起点，避免继续沿着已经证伪或高风险的路径重复试错。
 
 ## 当前交接状态
 
-截至本次更新时，设备不再处于“完全卡死且无法 SSH”的状态，而是进入了一个更窄的失败场景：
+截至本次更新时，设备已经不再停留在“完全卡死且无法 SSH”的状态，结论也分成了两部分：
 
-- Kindle 已能回到主页
-- `ssh kindle` 已恢复可用
-- 从 `KUAL -> Kindle Dashboard` 进入 dashboard 时，仍会复现白屏
-- 白屏出现时，dashboard 本身往往没有真正接管成功，更像是 `framework/KUAL` 启动链在中途被打断
-- 当前最稳定的恢复路径，仍然是通过 SSH 执行 `./stop.sh`
+- 已修住的：
+  - `calendar -> 主页 -> KUAL -> 回主页` 已能正常工作
+  - `ssh kindle` 已恢复可用
+  - 当前默认架构已切到“保留原生 UI 栈”的 overlay 模式
+- 仍未完全收口的：
+  - 从 `KUAL -> Kindle Dashboard` 进入 dashboard 时，仍出现过白屏
+  - 白屏出现时，dashboard 本身往往没有真正接管成功，更像是 `framework/KUAL` 启动链在中途被打断
 
 补充记录一个当前仍未修住、但边界已经比较清楚的问题：
 
 - 从 `KUAL` 进入 dashboard 后，再尝试回到 dashboard / KUAL 的原生 UI 路径，仍可能落入白屏
 - 这个问题不应再继续归因到背景图、时钟或页面布局
 - 当前更合理的判断，仍然是 `KUAL -> start.sh -> dash.sh` 的切换链路不稳定
+- `2026-03-17` 这轮新增验证还能确认：直接碰 `blanket` 或强拉 `booklet.home`，会进一步触发 `blanket / cvm` 崩溃
 
 这份文档只记录当前交接结论，不再继续尝试修复。
 
@@ -37,9 +40,9 @@ Skipping system suspend, sleeping for 40s instead
 
 所以“点 `Dashboard Debug On` 之后 3 秒就休眠”这个问题，本轮已经修住。
 
-### 2. `dashboard` 模式不是可交互界面
+### 2. 旧架构里，`dashboard` 不是可交互界面
 
-当前实现里，dashboard 启动后会主动停掉 Kindle 的前台 UI：
+旧实现里，dashboard 启动后会主动停掉 Kindle 的前台 UI：
 
 - [dash/src/dash.sh](/Users/gavin/kindle-dash/dash/src/dash.sh#L50) 调用 `stop_framework`
 - [dash/src/dash.sh](/Users/gavin/kindle-dash/dash/src/dash.sh#L51) 停掉 `webreader`
@@ -49,6 +52,12 @@ Skipping system suspend, sleeping for 40s instead
 - 进入 dashboard 之后，不应再期望当前屏幕仍然像普通 Kindle 页面那样可点击
 - 也不应再期待“从 dashboard 直接返回刚才那个 KUAL 页面”
 
+补充：
+
+- 截至 `2026-03-17`，默认实现已经改成 `KEEP_NATIVE_UI_STACK_RUNNING=true`
+- 也就是保留 `framework / webreader` 存活，把 dashboard 当成覆盖显示层
+- 在这条新路径上，`calendar -> 主页 -> KUAL -> 回主页` 已完成实机验证
+
 ### 3. 顶栏遮罩不处理触摸
 
 右上角状态栏遮罩逻辑在：
@@ -60,45 +69,65 @@ Skipping system suspend, sleeping for 40s instead
 - “点不到 KUAL” 不是顶栏遮罩造成的
 - 真正相关的是 `framework/webreader` 被停掉
 
-### 4. `stop.sh` 现在只负责恢复 UI 栈，不负责直接打开 KUAL
+### 4. `stop.sh` 现在分成两种退出路径
 
 当前 [dash/src/stop.sh](/Users/gavin/kindle-dash/dash/src/stop.sh) 已改成：
 
-- 停掉 `dash.sh`
-- 清掉 `preventScreenSaver`
-- 启动 `framework`
-- 启动 `webreader`
+- 默认 overlay 模式：
+  - 停掉 `dash.sh`
+  - 清掉 `preventScreenSaver`
+  - 停掉主题菜单和右下角长按监听
+  - 如果底层当前是 `KUAL`，再通过 `appmgrd stop` 把它正常退回首页
+- 旧架构兼容模式：
+  - 停掉 `dash.sh`
+  - 清掉 `preventScreenSaver`
+  - 停干净 `framework / webreader / cvm`
+  - 再按顺序拉起 `framework`
+  - 等 `cvm` 回来后启动 `webreader`
 
 也就是说它的职责是：
 
-- 让 Kindle 回到“应该可以恢复正常 UI”的状态
+- 让 Kindle 从 dashboard 安全退回原生 UI
 
 不是：
 
 - 直接把 KUAL booklet 弹出来
+- 也不是走实验性的“快切换”
+
+补充：
+
+- 本轮新试过的“快路径”已经撤回
+- 直接碰 `blanket` 或尝试 shell 里强拉 `booklet.home`，都可能把 `blanket / cvm` 打崩
+- 当前 Voyage 5.13.6 仍以稳定恢复优先，快速切换需要改入口架构，不能继续堆在 `stop.sh` 上
 
 补充一点：在白屏恢复过程中，`stop.sh` 已经比旧版稳定很多，但仍存在一种残留状态：
 
 - `framework` 和 `cvm` 已回来了
 - `webreader` 可能还停在 `stop/waiting`
 
-这时手工再执行一次 `start webreader`，主页通常就能回来。
+针对这个问题，`stop.sh` 现在已经补成“循环检查并补拉起 `webreader`，直到连续几次都保持 `start/running`”。
+如果未来仍然遇到个别恢复失败，再把 `/sbin/start webreader` 当作人工兜底，不再作为默认恢复步骤。
 
-### 5. 直接 `booklet run` 的试探命令不安全
+### 5. 直接 `booklet run` 或手动 `blanket unload` 的试探命令不安全
 
-本轮为了验证能否从 shell 里直接拉起主页或 KUAL，试过两类命令：
+本轮为了验证能否从 shell 里直接拉起主页、KUAL，或者手动剥掉前台遮罩，试过几类命令：
 
 ```sh
 lipc-set-prop com.lab126.booklet run "app://com.lab126.booklet.home"
 lipc-set-prop com.lab126.booklet run "com.mobileread.ixtab.kindlelauncher.KualBooklet"
+lipc-set-prop com.lab126.blanket unload splash
+lipc-set-prop com.lab126.blanket unload screensaver
 ```
 
 这条路不稳定，已经触发过 `cvm` 崩溃打包。设备上看到过：
 
 - `/mnt/us/documents/cvm_2886_..._crash_Mar_15_14.14.19_2026.tgz`
 - `/mnt/us/documents/cvm_5551_..._crash_Mar_15_14.18.54_2026.tgz`
+- `/mnt/us/documents/cvm_18914_..._crash_Mar_17_09.16.13_2026.tgz`
+- `/mnt/us/documents/cvm_22294_..._crash_Mar_17_09.21.03_2026.tgz`
+- `/mnt/us/documents/blanket_13032_..._crash_Mar_17_09.10.13_2026.tgz`
 
-因此下次接手时，不要再直接复用这两条命令。
+因此下次接手时，不要再直接复用这些命令，也不要把“先手动卸掉 `blanket` 再看前台会不会回来”当成安全恢复手段。
 
 ### 6. dashboard 本身可以工作，失败更像发生在 KUAL 启动路径
 
@@ -277,7 +306,7 @@ ssh kindle 'cd /mnt/us/dashboard && ./stop.sh'
 如果执行完 `./stop.sh` 后主页仍然没有回来，再补：
 
 ```sh
-ssh kindle 'start webreader'
+ssh kindle '/sbin/start webreader'
 ```
 
 不要从 dashboard 页面直接尝试回 KUAL。
@@ -307,11 +336,45 @@ ssh kindle 'start webreader'
 3. 继续保留 `ssh kindle 'cd /mnt/us/dashboard && DEBUG=true ./start.sh'` 作为唯一已验证稳定的进入方式
 4. 继续保留 `./stop.sh` 作为唯一已验证稳定的退出恢复方式
 
+截至 2026-03-18，这个修复方向已经按最小改动落地到仓库：
+
+1. KUAL 顶层菜单改成 `Kindle Dashboard -> 主题列表`
+2. 具体主题项调用 `/mnt/us/dashboard/launch-theme-from-kual.sh`
+3. `launch-theme-from-kual.sh` 会先切主题，再委托 `/mnt/us/dashboard/launch-from-kual.sh`
+4. `launch-from-kual.sh` 仍会先请求 KUAL 正常退出，并通过 `setsid` 脱离当前会话后启动 `start.sh`
+5. 默认 `KUAL_QUIT_GRACE_SECONDS=0`、`KUAL_LAUNCH_DELAY_SECONDS=0`，不再人为停留在原生首页，尽量做到点击后直接进入 calendar overlay
+6. `start.sh` 的非调试后台启动也额外加上了 `setsid`
+
+### E. 2026-03-17 新架构：保留原生 UI 栈
+
+为解决“长期显示 calendar，同时仍能切回首页/KUAL”，仓库里新增并默认启用了：
+
+- `KEEP_NATIVE_UI_STACK_RUNNING=true`
+
+当前行为是：
+
+- `dash.sh` 启动时不再主动停止 `framework / webreader`
+- `stop.sh` 在该开关打开时，只停止 dashboard 自己，不再重建 `framework / webreader / cvm`
+- dashboard 作为“覆盖显示层 + RTC suspend 调度”运行，而不是“替代原生 UI 的前台”
+- 主题切换入口当前只保留在 KUAL；运行态双翻页键菜单与右下角长按默认关闭
+- 实机已验证：`calendar -> 主页 -> KUAL -> 回主页` 全链路正常
+
+这条路线已经证明比“启动时停掉 framework/webreader”更符合当前需求。
+7. `Dashboard Debug On/Off` 也统一改走同一条 wrapper 启动链
+
+这只能说明“修复方向已经进入代码”，还不能替代真实设备上的交互验收。
+更具体地说，截至 `2026-03-17` 的真机实验结果是：
+
+1. wrapper 已经落地
+2. `stop.sh` 的实验性快切换已经撤回
+3. 当前真正安全的进入方式仍然只有 SSH 前台调试
+4. 当前真正安全的退出方式仍然只有保守恢复版 `./stop.sh`
+
 等 SSH 恢复后，再围绕下面三点做实机验证：
 
 1. KUAL wrapper 是否还能触发 `framework` 被 TERM
 2. `start.sh` 的后台脱离方式是否足够彻底
-3. `stop.sh` 后是否还需要补 `start webreader`
+3. `stop.sh` 后是否还需要补 `/sbin/start webreader`
 
 ## 这轮涉及的关键文件
 
@@ -331,10 +394,10 @@ ssh kindle 'start webreader'
 
 - dashboard 与 Kindle 原生 `framework/KUAL` 的边界切换不稳定
 - `KUAL -> Kindle Dashboard` 这条启动链仍会白屏
-- 直接用 shell 强拉 booklet 会触发前台 Java 崩溃
+- 直接用 shell 强拉 booklet，或手动碰 `blanket`，都会触发前台 `blanket / cvm` 崩溃
 
 因此，当前最重要的不是继续调页面，而是：
 
 1. 保留当前已经可用的 SSH 启动/停止路径
 2. 修住 `KUAL -> Kindle Dashboard` 白屏
-3. 在不再触发 `cvm` 崩溃的前提下，把“进入 dashboard”和“退出 dashboard”都收敛成稳定流程
+3. 在不再触发 `blanket / cvm` 崩溃的前提下，把“进入 dashboard”和“退出 dashboard”都收敛成稳定流程