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

2026-03-18 13:35:19 +08:00
parent 192eb1b8d1
commit f9d715157f
72 changed files with 4035 additions and 972 deletions
--- a/dash/docs/kindle-city-location-plan.zh.md
+++ b/dash/docs/kindle-city-location-plan.zh.md
@@ -0,0 +1,220 @@
+# Kindle 市级位置方案
+
+## 背景
+
+当前仓库里的天气位置来源仍在 `calendar/` 前端：
+
+- [calendar/src/lib/weather.ts](/Users/gavin/kindle-dash/calendar/src/lib/weather.ts) 会优先尝试 `navigator.geolocation`
+- 失败时回退到固定默认值 `杭州`
+
+这条路径不适合当前 Kindle 运行架构，原因有两个：
+
+1. Kindle 实机显示的不是一个在设备上实时运行的天气网页，而是先在别处渲染，再同步为背景图。
+2. 如果由 Web 服务器代查 IP 位置，拿到的是服务器公网 IP，对应的是服务器所在城市，不是 Kindle 所在城市。
+
+本方案的目标是：
+
+- 位置精度只要求到“市”颗粒度
+- 位置来源应尽量接近 Kindle 当前网络出口
+- 在 SSH 暂时不可用的情况下，先把方案文档明确下来，后续恢复 SSH 后再实现
+
+## 结论
+
+浏览器网页定位不应继续作为主路径。
+
+推荐改成：
+
+1. Kindle 侧自己请求 GeoIP 接口，获取当前公网 IP 对应的城市、经纬度和时区
+2. 把结果缓存到本地
+3. 天气与相关展示统一读取这份缓存
+4. 当 GeoIP 不可用或结果异常时，回退到 Kindle 侧固定配置的 `city/lat/lon/timezone`
+
+这是一个“市级近似定位”方案，不是 GPS 精确定位方案。
+
+## 为什么 Kindle 侧 GeoIP 可行
+
+GeoIP 的前提是“由目标设备自己发请求”。
+
+对当前项目，正确的请求路径应该是：
+
+```text
+Kindle -> GeoIP 服务 -> 返回 city / lat / lon / timezone
+```
+
+而不是：
+
+```text
+Kindle -> 你的 Web 服务 -> Web 服务代查 GeoIP
+```
+
+后一种方式只会得到 Web 服务所在机房或服务器出口的位置。
+
+如果 Kindle 走家庭 Wi-Fi，且只要求“市级”颗粒度，GeoIP 通常够用。
+如果 Kindle 走手机热点、VPN、代理、企业网络或运营商 NAT，结果可能偏到邻近城市，必须接受这种误差。
+
+## 目标能力
+
+实现后需要具备以下能力：
+
+1. Kindle 联网后，能够自己获取当前网络出口对应的城市信息
+2. 获取结果会写入本地缓存
+3. 断网时仍可继续使用上次缓存
+4. GeoIP 失败时可回退到固定配置
+5. 只需要市级位置，不追求街道级精度
+
+## 推荐数据模型
+
+建议在 Kindle 侧维护一份位置缓存文件。
+
+路径建议：
+
+```text
+/mnt/us/dashboard/local/state/location.env
+```
+
+字段建议：
+
+```text
+LOCATION_SOURCE=geoip
+LOCATION_CITY=杭州
+LOCATION_LAT=30.274084
+LOCATION_LON=120.155070
+LOCATION_TIMEZONE=Asia/Shanghai
+LOCATION_UPDATED_AT=2026-03-17T10:00:00+08:00
+```
+
+同时保留一份固定兜底配置，例如：
+
+```text
+LOCATION_FALLBACK_CITY=杭州
+LOCATION_FALLBACK_LAT=30.274084
+LOCATION_FALLBACK_LON=120.155070
+LOCATION_FALLBACK_TIMEZONE=Asia/Shanghai
+```
+
+## 运行时脚本设计
+
+建议新增 Kindle 侧脚本：
+
+```text
+dash/src/local/location-sync.sh
+```
+
+职责：
+
+1. 检查网络是否可用
+2. 由 Kindle 自己请求 GeoIP 接口
+3. 解析响应中的城市、经纬度、时区
+4. 校验字段是否完整
+5. 写入本地缓存
+6. 失败时保留旧缓存，不要清空已有结果
+
+建议同时新增一个只负责读取并导出环境变量的脚本，例如：
+
+```text
+dash/src/local/location-env.sh
+```
+
+职责：
+
+1. 优先读取新鲜的 GeoIP 缓存
+2. 没有新鲜缓存时读取旧缓存
+3. 缓存不存在或无效时回退到固定配置
+4. 对外输出统一的 `LOCATION_CITY/LAT/LON/TIMEZONE`
+
+## 刷新策略
+
+位置不需要高频刷新。
+
+建议策略：
+
+1. 启动 dashboard 且确认联网后，首次同步一次位置
+2. 每 12 小时或 24 小时刷新一次
+3. 手动切换主题时不强制刷新位置
+4. 天气刷新与位置刷新解耦
+5. 位置同步失败时继续使用现有缓存
+
+## 与现有架构的衔接方式
+
+当前项目是“背景图 + Kindle 本地时钟覆盖”的架构，不是“Kindle 上实时跑完整天气网页”的架构。
+
+因此接入位置数据时，有两条可选路径。
+
+### 路径 A：最小改动路径
+
+保留当前背景图生成方式，但让背景图生成时显式读取 Kindle 侧缓存导出的城市与经纬度。
+
+优点：
+
+- 改动面相对小
+- 仍可复用现有天气卡片布局与导出流程
+
+缺点：
+
+- 需要重新梳理“背景图生成端”如何拿到 Kindle 缓存
+- 如果背景仍在 Mac 侧导出，就必须把 Kindle 缓存同步回 Mac 或转成请求参数
+
+### 路径 B：更符合现状的运行时路径
+
+把“城市文本、天气数据”也逐步下沉到 Kindle 运行时，和本地时钟一样由设备端控制。
+
+优点：
+
+- 位置与天气都由 Kindle 自己决定
+- 不会再混入 Mac 浏览器位置或服务器 IP 位置
+
+缺点：
+
+- 改动更大
+- 需要重新设计天气卡的本地渲染方式
+
+## 当前推荐
+
+短期推荐先做：
+
+1. Kindle 侧 GeoIP 获取
+2. 本地缓存
+3. 固定配置兜底
+
+等 SSH 恢复后，再决定位置数据如何喂给天气展示层。
+
+也就是说，先把“位置来源”稳定下来，再改“展示方式”。
+
+## 实施顺序
+
+建议按下面顺序落地：
+
+1. 新增 `location-sync.sh`
+2. 新增 `location-env.sh`
+3. 在 Kindle 运行时目录中引入固定兜底配置
+4. 在主循环启动阶段接入位置缓存刷新
+5. 让天气读取逻辑改为优先使用 Kindle 侧位置缓存
+6. 最后补文档和手动刷新命令
+
+## 验收标准
+
+实现完成后，至少应满足以下验收条件：
+
+1. Kindle 联网后可生成位置缓存文件
+2. 缓存中至少包含 `city/lat/lon/timezone`
+3. 断网后仍能继续使用旧缓存
+4. GeoIP 失败时会稳定回退到固定城市
+5. 显示出的城市与 Kindle 当前所在城市大体一致
+
+## 注意事项
+
+1. GeoIP 只能提供近似位置，不要当作精确定位
+2. 手机热点、VPN、代理、企业网络都会降低城市准确率
+3. 城市级结果可以用于天气展示，但不适合做严格地理判断
+4. 任何实现都必须保证“失败不影响 dashboard 主循环”
+
+## 现阶段状态
+
+当前仅完成方案设计，尚未开始代码实现。
+
+直接原因是：
+
+- 目前 SSH 还未恢复
+- 设备侧脚本还不能方便地下发、调试和验证
+
+后续等 SSH 恢复后，再按本方案分步实施。
--- a/dash/docs/kindle-voyage-5.13.6-bootstrap-validation-zh.md
+++ b/dash/docs/kindle-voyage-5.13.6-bootstrap-validation-zh.md
@@ -0,0 +1,262 @@
+# Kindle Voyage 5.13.6 Bootstrap 闭环验证清单
+
+## 目标
+
+用一台已经越狱过、同型号同固件的 `Kindle Voyage 5.13.6` 做一次“恢复出厂 -> 重新越狱 -> 安装 KUAL/MRPI/USBNetwork/KTerm -> 打通 SSH -> 显示 dashboard”的闭环验证，确认：
+
+- [bootstrap-new-kindle.sh](/Users/gavin/kindle-dash/bootstrap-new-kindle.sh) 现在的方案是否足够完整
+- 哪些步骤已经可以自动化
+- 哪些步骤仍然必须人工完成
+
+## 重要前提
+
+执行前先确认：
+
+1. 设备型号仍然是 `Kindle Voyage`
+2. 固件版本仍然是 `5.13.6`
+3. 你接受这是破坏性验证
+4. 设备里当前的 `KUAL`、SSH、dashboard、主题配置、日志都会被清掉
+
+如果固件版本不是 `5.13.6`，不要按这份清单执行。
+
+## 重置前准备
+
+### 1. 先备份当前设备侧用户存储
+
+把 Kindle 通过 USB 挂载到 Mac 后，至少备份这些目录：
+
+```text
+/Volumes/Kindle/dashboard
+/Volumes/Kindle/extensions
+/Volumes/Kindle/mrpackages
+/Volumes/Kindle/documents
+```
+
+如果你只想做最小备份，也至少把下面这些拷走：
+
+- `dashboard/`
+- `extensions/`
+- `documents/` 里你关心的 crash 包和日志
+
+### 2. 在 Mac 侧准备 bootstrap 预置
+
+推荐直接用带 KTerm 下载的版本：
+
+```sh
+sh bootstrap-new-kindle.sh prepare-storage --download-kterm --kterm-version latest
+```
+
+如果你不想拉 latest，也可以固定版本：
+
+```sh
+sh bootstrap-new-kindle.sh prepare-storage --download-kterm --kterm-version v2.6
+```
+
+这一步的预期结果：
+
+- Kindle 根目录出现 `Update_hotfix_watchthis_custom.bin`
+- Kindle 根目录出现 `dashboard/`
+- Kindle 根目录出现 `extensions/`
+- Kindle 根目录出现 `mrpackages/`
+- Kindle 根目录出现 `ssh-force-dropbear-22.sh`
+- Kindle 根目录出现 `.demo/KV-5.13.6.zip`
+- Kindle 根目录出现 `.demo/demo.json`
+- Kindle 根目录出现 `.demo/goodreads/`
+- 如果下载了 `KTerm`，`extensions/` 里会直接出现 `kterm/`
+
+做完后安全弹出 Kindle。
+
+## 设备侧执行顺序
+
+### 3. 恢复出厂
+
+在 Kindle 上执行恢复出厂。
+
+恢复后开始首启流程时：
+
+1. 语言只选 `English (United Kingdom)`
+2. 到 Wi‑Fi 页面时，不要真的联网
+3. 进入 demo mode，按 [kindle-voyage-5.13.6-watchthis-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-watchthis-zh.md#L61) 的流程操作
+
+### 4. WatchThis 导入点
+
+必须特别注意：
+
+1. 第一次 `Add Content / Sideload Content` 只能点 `Done`
+2. 不要在第一次导入点接 USB
+3. 真正的 payload 导入点，是隐藏手势返回后，再次进入 `;demo -> Sideload Content`
+
+这里的详细说明看：
+
+- [kindle-voyage-5.13.6-watchthis-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-watchthis-zh.md#L80)
+- [kindle-voyage-5.13.6-watchthis-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-watchthis-zh.md#L100)
+
+因为 bootstrap 已经把 `.demo` payload 预置好了，这一轮不需要你在导入点再手工从 Mac 拷 `KV-5.13.6.zip`。
+
+### 5. 触发越狱并验收
+
+完成 `Get Started` 后，设备会重启并执行越狱脚本。
+
+验收标准：
+
+- Kindle 用户存储根目录出现 `mkk`
+- Kindle 用户存储根目录出现 `libkh`
+- Kindle 用户存储根目录出现 `rp`
+
+如果没有这三个目录，说明这轮 `WatchThis` 没真正落地，不要继续往后做。
+
+### 6. 安装 KUAL / MRPI / USBNetwork / dashboard / KTerm
+
+回到首页后：
+
+1. 搜索 `;log mrpi`
+2. 等 MRPI 跑完
+3. 回首页确认：
+   - 有 `KUAL`
+   - 如果本轮预置了 `KTerm`，应该已经能看到 `KTerm`
+
+然后进入 `KUAL`，先执行：
+
+```text
+Rename OTA Binaries -> Rename
+```
+
+不要先跑 `Kindle Dashboard`。
+
+## Wi‑Fi 和 SSH 验证
+
+### 7. 接回 Wi‑Fi
+
+让 Kindle 连到和 Mac 同一个主 Wi‑Fi。
+
+不要用：
+
+- Guest Wi‑Fi
+- 开了客户端隔离的网络
+
+### 8. 在 KTerm 里拉起 DropBear
+
+打开 `KTerm`，执行：
+
+```sh
+sh /mnt/us/ssh-force-dropbear-22.sh
+/mnt/us/usbnet/bin/lsof -n -P -iTCP:22
+```
+
+验收标准：
+
+应该看到类似：
+
+```text
+dropbear... TCP *:22 (LISTEN)
+```
+
+### 9. 在 Mac 上确认 SSH
+
+回到 Mac：
+
+```sh
+ssh kindle
+```
+
+登录后执行：
+
+```sh
+id
+uname -a
+ps -ef | grep -E 'sshd|dropbear|telnetd' | grep -v grep
+```
+
+验收标准：
+
+- `uid=0(root)`
+- 存在 `dropbearmulti dropbear ... -p 22 ...`
+
+如果这一步失败，按：
+
+- [kindle-voyage-5.13.6-dual-ssh-playbook-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-dual-ssh-playbook-zh.md#L210)
+
+继续排障，不要直接判断 bootstrap 失败。
+
+## Dashboard 闭环验证
+
+### 10. 让 bootstrap 跑后半段
+
+在 Mac 上执行：
+
+```sh
+sh bootstrap-new-kindle.sh post-ssh -t simple -o portrait
+```
+
+预期结果：
+
+- 同步当前 dashboard 运行时
+- 同步主题包
+- 设备立即切到 `simple / portrait`
+- 屏幕出现背景与时钟
+
+如果你还要验证后台常驻主循环，再执行：
+
+```sh
+sh bootstrap-new-kindle.sh post-ssh -t simple -o portrait --start-dashboard
+```
+
+### 11. 抓首张验收图
+
+在 Mac 上执行：
+
+```sh
+sh snapshot.sh -t simple -o portrait
+```
+
+或者如果你不想再切主题，只抓当前画面：
+
+```sh
+sh snapshot.sh --capture-only -b bootstrap-validation
+```
+
+验收标准：
+
+- 本地成功生成 `physical.png`
+- Kindle 上显示 `simple / portrait`
+- 时钟、天气、日历、鸡汤都正常
+
+## 这轮验证要回答的问题
+
+执行完后，明确记录下面 5 个结论：
+
+1. `prepare-storage --download-kterm` 是否足够把 USB 预置做完整
+2. `WatchThis` 是否能在“已有一轮越狱历史”的同机上再次稳定跑通
+3. `;log mrpi` 后，`KUAL / USBNetwork / KTerm / dashboard` 是否都能落地
+4. `KTerm -> ssh-force-dropbear-22.sh -> ssh kindle` 是否仍是最稳入口
+5. `post-ssh` 是否已经能把 dashboard 自动拉到“可见、可抓图”的状态
+
+## 失败时怎么回退
+
+如果中途失败，按这个顺序收敛：
+
+1. 先不要继续改 dashboard 页面代码
+2. 先判断失败落在哪一层：
+   - `WatchThis`
+   - `MRPI`
+   - `KTerm`
+   - `SSH`
+   - `post-ssh`
+3. 如果已经拿到 `KTerm`，优先在本机看进程和端口
+4. 如果已经拿到 `ssh kindle`，优先保留日志和 `/mnt/us/ssh-debug/`
+5. 不要把 `KUAL -> Dashboard -> 再返回 KUAL` 当成验收项
+
+## 推荐实际执行命令
+
+如果你要按最少分支走，直接按这个顺序：
+
+```sh
+sh bootstrap-new-kindle.sh prepare-storage --download-kterm --kterm-version latest
+```
+
+设备侧完成恢复出厂、WatchThis、`;log mrpi`、Wi‑Fi、KTerm 拉起 SSH 后，再执行：
+
+```sh
+sh bootstrap-new-kindle.sh post-ssh -t simple -o portrait --start-dashboard
+sh snapshot.sh --capture-only -b bootstrap-validation
+```
--- a/dash/docs/kindle-voyage-5.13.6-bootstrap-zh.md
+++ b/dash/docs/kindle-voyage-5.13.6-bootstrap-zh.md
@@ -6,6 +6,7 @@

 - 预置 `WatchThis` payload
 - 预置 `KUAL / MRPI / USBNetwork / kindle-dash`
+- 可选预置 `KTerm`
 - 预置 SSH 恢复脚本
 - SSH 打通后自动同步 dashboard、切主题、立即出图

@@ -32,6 +33,48 @@ sh /mnt/us/ssh-force-dropbear-22.sh
 - 尽量把 Mac 侧和文件预置自动化
 - 把设备侧必须手工的动作压到最少

+## KTerm 说明
+
+当前仓库默认不自带 `KTerm` 安装包。
+
+脚本支持两种方式把 `KTerm` 纳入预置：
+
+1. 直接把官方 `KTerm` release 的 `.zip` 放到：
+
+```text
+dash/staging/kterm/kterm-kindle-*.zip
+```
+
+2. 或执行脚本时显式传入：
+
+```sh
+sh bootstrap-new-kindle.sh prepare-storage --kterm-package /绝对路径/kterm-kindle-*.zip
+```
+
+3. 或直接让脚本在 Mac 侧联网下载：
+
+```sh
+sh bootstrap-new-kindle.sh prepare-storage --download-kterm --kterm-version latest
+```
+
+也可以固定版本：
+
+```sh
+sh bootstrap-new-kindle.sh prepare-storage --download-kterm --kterm-version v2.6
+```
+
+如果脚本没有找到 `KTerm` 安装包，它不会报错退出，但会明确提示：
+
+- 本轮只预置 SSH 恢复脚本
+- `KTerm` 仍需手工补装
+
+下载逻辑说明：
+
+- 下载发生在 Mac 侧，不在 Kindle 设备侧进行
+- 下载后的 `.zip` 会缓存到 `dash/staging/kterm/`
+- 对 `Kindle Voyage 5.13.6`，脚本默认优先选择不带 `armhf` 后缀的 `.zip`
+- 预置时会直接解压到 Kindle 的 `extensions/`
+
 ## 脚本模式

 ### 1. `prepare-storage`
@@ -49,6 +92,7 @@ sh bootstrap-new-kindle.sh prepare-storage
 - 把 `Update_hotfix_watchthis_custom.bin` 放到 Kindle 根目录
 - 把 `extensions/`、`mrpackages/`、`dashboard/` 预置到 Kindle
 - 把 `scripts/kindle/*.sh` 拷到 Kindle 根目录，供 `KTerm` 使用
+- 如果检测到 `KTerm` zip，也会一并解压到 `extensions/`

 ### 2. `post-ssh`

@@ -94,14 +138,15 @@ sh bootstrap-new-kindle.sh
 4. 通过 `Get Started` 完成越狱
 5. 搜索 `;log mrpi`
 6. 在 `KUAL` 中先执行 `Rename OTA Binaries -> Rename`
-7. 连上 Wi‑Fi
-8. 打开 `KTerm`，执行：
+7. 如果本轮没有预置 `KTerm`，这里先手工补装 `KTerm`
+8. 连上 Wi‑Fi
+9. 打开 `KTerm`，执行：

 ```sh
 sh /mnt/us/ssh-force-dropbear-22.sh
 ```

-9. 回到 Mac，执行：
+10. 回到 Mac，执行：

 ```sh
 sh bootstrap-new-kindle.sh post-ssh
@@ -113,3 +158,5 @@ sh bootstrap-new-kindle.sh post-ssh
  [kindle-voyage-5.13.6-watchthis-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-watchthis-zh.md)
 - SSH 打通与 KTerm 兜底：
  [kindle-voyage-5.13.6-dual-ssh-playbook-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-dual-ssh-playbook-zh.md)
+- 恢复出厂后的 bootstrap 闭环验证：
+  [kindle-voyage-5.13.6-bootstrap-validation-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-bootstrap-validation-zh.md)
--- a/dash/docs/kindle-voyage-5.13.6-dual-ssh-playbook-zh.md
+++ b/dash/docs/kindle-voyage-5.13.6-dual-ssh-playbook-zh.md
@@ -345,7 +345,6 @@ cat /mnt/us/usbnet/etc/config

 - [scripts/kindle/ssh-collect.sh](/Users/gavin/kindle-dash/scripts/kindle/ssh-collect.sh)
 - [scripts/kindle/ssh-fix-all-keys.sh](/Users/gavin/kindle-dash/scripts/kindle/ssh-fix-all-keys.sh)
- [scripts/kindle/ssh-force-openssh-22.sh](/Users/gavin/kindle-dash/scripts/kindle/ssh-force-openssh-22.sh)
 - [scripts/kindle/ssh-force-dropbear-22.sh](/Users/gavin/kindle-dash/scripts/kindle/ssh-force-dropbear-22.sh)
 - [scripts/kindle/ssh-stop-all.sh](/Users/gavin/kindle-dash/scripts/kindle/ssh-stop-all.sh)

--- a/dash/docs/kindle-voyage-5.13.6-white-screen-handoff-zh.md
+++ b/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”都收敛成稳定流程
--- a/dash/docs/pagepress-theme-menu-plan.zh.md
+++ b/dash/docs/pagepress-theme-menu-plan.zh.md
@@ -4,6 +4,9 @@

 本文是评审方案，不是实机结论。

+补充说明：当前仓库默认已经不启用这套运行态菜单，主题切换入口只保留在 KUAL。
+本文保留为备选方案与历史设计记录，不代表当前默认交互。
+
 当前 Kindle 已掉出 Wi-Fi，SSH 中断，因此这份文档的目标是：

 - 先把“左右同时按下翻页键，呼出主题选择页面”的方案固定下来
@@ -14,7 +17,15 @@

 - Kindle Voyage
 - 固件 5.13.6
- dashboard 运行时会停掉 framework / webreader
+- 当前默认实现为“保留 framework / webreader 的 overlay 模式”
+
+补充：
+
+- 本文很多菜单设计最初建立在“dashboard 会停掉原生 UI 栈”的旧架构上
+- 截至 `2026-03-17`，默认实现已经切到“保留原生 UI 栈”
+- 因此文中提到的 `Return Home`，应以 `stop.sh` 的当前行为为准：
+  - overlay 模式下：停掉 dashboard，并在底层是 KUAL 时把它正常退回首页
+  - 旧架构兼容模式下：保守恢复 `framework / cvm / webreader`

 ## 1. 已确认事实

@@ -85,6 +96,7 @@ echo "mem" >/sys/power/state
 3. 用户通过翻页键在主题列表中移动选中项
 4. 用户再次同时按下左右翻页键，确认并切换主题
 5. 切换完成后，立即刷新背景和时钟
+6. 菜单列表末尾可附带一个“返回首页”动作项，安全退出 dashboard 并恢复 Kindle 首页

 本阶段非目标：

@@ -113,7 +125,16 @@ echo "mem" >/sys/power/state

 - `PageUp`：向上移动
 - `PageDown`：向下移动
- 再次双键同时按下：确认当前主题
+- 再次双键同时按下：确认当前项
+
+同时保留一个触摸兜底入口：
+
+- 右下角长按：直接呼出同一份运行态主题菜单
+
+其中当前项可以是：
+
+- 某个主题：执行主题切换
+- `Return Home`：退出 dashboard，恢复 framework / webreader，回到 Kindle 首页

 这样做的原因：

@@ -221,12 +242,19 @@ Press both keys: apply
 3. 识别到组合键后，本机绘制菜单
 4. 用户确认后，调用现有：
   - `/mnt/us/dashboard/switch-theme.sh <theme-id> [orientation]`
+   - 或 `/mnt/us/dashboard/stop.sh`
 5. `switch-theme.sh` 继续负责：
   - 同步主题配置
   - 拉最新背景
   - 刷新屏幕
   - 重绘时钟

+如果选中的是 `Return Home`，则不走主题切换，而是调用 `stop.sh`：
+
+- 停掉 dashboard 和菜单监听器
+- 恢复 `framework / cvm / webreader`
+- 回到 Kindle 首页
+
 也就是说，菜单服务只负责：

 - 触发
@@ -309,6 +337,7 @@ Press both keys: apply
 export THEME_MENU_ENABLED=true
 export THEME_MENU_EVENT_DEVICE="/dev/input/event2"
 export THEME_MENU_COMBO_WINDOW_SECONDS=0.35
+export THEME_MENU_RUNTIME_DIR="/tmp/kindle-dash-theme-menu"
 ```

 说明：
@@ -320,6 +349,9 @@ export THEME_MENU_COMBO_WINDOW_SECONDS=0.35
  - 后续换机型时可以只改这个
 - `THEME_MENU_COMBO_WINDOW_SECONDS`
  - 组合键判定窗口
+- `THEME_MENU_RUNTIME_DIR`
+  - 菜单服务的临时运行目录
+  - 需要放在支持 FIFO 的文件系统上，Voyage 上应使用 `/tmp`

 ## 9. 风险与限制

@@ -408,8 +440,12 @@ export THEME_MENU_COMBO_WINDOW_SECONDS=0.35
 - 监听 `/dev/input/event2`
 - 用短时间窗口识别 `PageUp + PageDown` 组合键
 - 在运行态下绘制一个 KUAL 风格的文本主题菜单
+- 右下角长按也复用同一份菜单，而不是另起一套触摸 UI
 - 用 `PageUp / PageDown` 导航
 - 再次双键确认
 - 最终复用现有 `switch-theme.sh` 完成主题切换

 这是当前成本最低、最容易恢复、也最适合在 SSH 不稳定阶段先落地评审的方案。
+
+如果菜单需要提供稳定退出入口，也可以在列表末尾追加一个 `Return Home` 动作项。
+实现上应复用 `stop.sh` 的保守恢复链路，而不要直接强拉 `booklet.home`。