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/README.md
+++ b/README.md
@@ -0,0 +1,273 @@
+# kindle-dash
+
+一个面向 Kindle Voyage 的低功耗电子墨水仪表盘项目。  
+当前仓库把整条链路都放在一起：
+
+- `calendar/`：在电脑上生成背景图、主题包和前端预览
+- `dash/`：运行在 Kindle 上，负责拉图、渲染时钟、休眠唤醒、主题切换
+- `scripts/`：同步、抓图、SSH 恢复等运维脚本
+- `bootstrap-new-kindle.sh`：新机预置与 SSH 打通后的自动化入口
+- `snapshot.sh`：同步主题、切换主题、抓取 Kindle 实机画面的统一入口
+
+## 当前状态
+
+- `simple` / `default` 等主题已经接入当前运行链路
+- Kindle 侧采用“低频背景 + 本机时钟重绘”的分层渲染方案
+- 新机 bootstrap 方案已实现
+- 新机 bootstrap 当前仍是“方案已实现，真机恢复出厂闭环未验证”
+- `launch-from-kual.sh` 与 `setsid` 脱离方案已经落地到代码
+- 主题入口当前只保留在 `KUAL`；运行态双翻页键菜单与右下角长按默认关闭
+- 但 `KUAL -> Dashboard` 与 `Dashboard -> 原生 UI/KUAL` 的边界切换在 `Kindle Voyage 5.13.6` 上仍不稳定
+
+## 项目目标
+
+这个仓库不是单纯做一个网页，而是把下面几件事收成一套：
+
+1. 在电脑上生成适合 Kindle 分辨率的背景图和主题资源
+2. 把这些资源同步到已越狱的 Kindle
+3. 让 Kindle 在低功耗模式下周期性刷新背景
+4. 在设备本机按分钟重绘时钟，不依赖网络
+5. 提供主题切换、实机截图、SSH 恢复和新机 bootstrap 工具
+
+## 架构概览
+
+### 1. 前端层 `calendar/`
+
+作用：
+
+- 使用 Vue 生成 Kindle 仪表盘布局
+- 导出 `kindlebg.png`
+- 导出多主题背景包和 `themes.json`
+- 预览不同主题与方向
+
+关键文件：
+
+- [App.vue](/Users/gavin/kindle-dash/calendar/src/App.vue)
+- [SimpleDashboard.vue](/Users/gavin/kindle-dash/calendar/src/components/SimpleDashboard.vue)
+- [themes.json](/Users/gavin/kindle-dash/calendar/config/themes.json)
+
+### 2. 设备运行层 `dash/`
+
+作用：
+
+- 在 Kindle 上拉取或读取背景图
+- 根据调度决定刷新还是休眠
+- 在本机用 Lua + FBInk 渲染时钟
+- 切换主题、维护运行时主题状态
+- 在需要时拉起主题菜单服务
+
+关键文件：
+
+- [dash.sh](/Users/gavin/kindle-dash/dash/src/dash.sh)
+- [switch-theme.sh](/Users/gavin/kindle-dash/dash/src/switch-theme.sh)
+- [render-clock.lua](/Users/gavin/kindle-dash/dash/src/local/render-clock.lua)
+- [theme-sync.sh](/Users/gavin/kindle-dash/dash/src/local/theme-sync.sh)
+
+### 3. 运维层 `scripts/`
+
+作用：
+
+- 把当前 runtime 和主题包同步到 Kindle
+- 抓取 Kindle 实机屏幕
+- 恢复 Kindle 侧 SSH
+- 协助 USBNetwork 调试
+
+关键入口：
+
+- [sync-layered-clock-to-kindle.sh](/Users/gavin/kindle-dash/scripts/sync-layered-clock-to-kindle.sh)
+- [capture-kindle-screen.sh](/Users/gavin/kindle-dash/scripts/capture-kindle-screen.sh)
+- [ssh-force-dropbear-22.sh](/Users/gavin/kindle-dash/scripts/kindle/ssh-force-dropbear-22.sh)
+
+## 目录结构
+
+```text
+kindle-dash/
+├── assets/                      前端静态资源
+├── bootstrap-new-kindle.sh      新机预置/后半段自动化入口
+├── snapshot.sh                  同步 + 切主题 + 抓图统一入口
+├── calendar/                    Vue 前端与背景导出
+├── dash/                        Kindle 侧 runtime、KUAL、文档与 staging
+├── scripts/                     同步、抓图、SSH 与网络辅助脚本
+└── tmp/                         本地实机截图和临时产物
+```
+
+## 部署模型
+
+### 已越狱 Kindle
+
+这条路径适合设备已经有 `KUAL`、`USBNetwork`、SSH：
+
+1. 在电脑上构建前端：
+
+```sh
+cd calendar
+npm install
+npm run typecheck
+npm run build
+```
+
+2. 同步到 Kindle：
+
+```sh
+cd /Users/gavin/kindle-dash
+sh scripts/sync-layered-clock-to-kindle.sh kindle
+```
+
+3. 切主题并立即出图：
+
+```sh
+ssh kindle '/mnt/us/dashboard/switch-theme.sh simple portrait'
+```
+
+4. 如需启动 dashboard 主循环：
+
+```sh
+ssh kindle 'cd /mnt/us/dashboard && ./start.sh'
+```
+
+调试或排障时，当前更推荐：
+
+```sh
+ssh kindle 'cd /mnt/us/dashboard && DEBUG=true ./start.sh'
+```
+
+原因：
+
+- 这条路径已实机验证可用
+- 不依赖 `KUAL` 的 UI 切换链路
+- 出问题时可以直接看前台日志
+
+### 新机 / 恢复出厂后 Kindle
+
+这条路径适合 `Kindle Voyage 5.13.6`：
+
+1. USB 挂载后执行预置：
+
+```sh
+sh bootstrap-new-kindle.sh prepare-storage --download-kterm --kterm-version latest
+```
+
+2. 在 Kindle 上完成：
+
+- `WatchThis`
+- `;log mrpi`
+- `Rename OTA Binaries -> Rename`
+- 接回 Wi‑Fi
+- `KTerm` 中执行 `sh /mnt/us/ssh-force-dropbear-22.sh`
+
+3. 回到 Mac，执行后半段：
+
+```sh
+sh bootstrap-new-kindle.sh post-ssh -t simple -o portrait
+```
+
+注意：这条新机 bootstrap 方案当前仍未做“真机恢复出厂闭环验证”。
+
+## 常用命令
+
+### 前端开发
+
+```sh
+cd calendar
+npm install
+npm run dev
+npm run typecheck
+npm run build
+npm run export:themes
+```
+
+### 主题与截图
+
+```sh
+sh snapshot.sh --list
+sh snapshot.sh -t simple
+sh snapshot.sh -t simple -o portrait
+sh snapshot.sh --capture-only -b current-screen
+sh snapshot.sh --date
+```
+
+### 新机 bootstrap
+
+```sh
+sh bootstrap-new-kindle.sh -h
+sh bootstrap-new-kindle.sh prepare-storage --download-kterm --kterm-version latest
+sh bootstrap-new-kindle.sh post-ssh -t simple -o portrait
+```
+
+### SSH 恢复
+
+如果 Kindle 上已经有 `KTerm`，但外部 SSH 不通：
+
+```sh
+sh /mnt/us/ssh-force-dropbear-22.sh
+```
+
+然后在 Mac 上：
+
+```sh
+ssh kindle
+```
+
+## 使用说明
+
+### 日常使用
+
+- Kindle 正常联网时，背景和主题配置可以更新
+- 本机时钟按分钟重绘，不依赖网络
+- 即使远端刷新失败，只要本地还有缓存背景，设备通常还能继续显示旧背景和本机时钟
+
+### 换 Wi‑Fi 后
+
+- 不影响 USB 预置
+- 可能影响 `ssh kindle`
+- 可能影响主题强制同步和远端背景刷新
+- 如果新网络能正常出外网，日常显示通常不受影响
+
+## 验证与验收
+
+当前仓库里可直接运行的校验主要是：
+
+```sh
+cd calendar
+npm run typecheck
+npm run build
+```
+
+以及脚本级别语法检查，例如：
+
+```sh
+sh -n bootstrap-new-kindle.sh
+sh -n snapshot.sh
+```
+
+说明：
+
+- 当前仓库没有可用的 `lint` 脚本
+- 当前仓库没有可用的 `test` 脚本
+
+## 文档索引
+
+推荐按下面顺序看：
+
+1. 根仓库说明：
+   [README.md](/Users/gavin/kindle-dash/README.md)
+2. Kindle runtime 英文原始说明：
+   [dash/README.md](/Users/gavin/kindle-dash/dash/README.md)
+3. Voyage 5.13.6 越狱路径：
+   [kindle-voyage-5.13.6-watchthis-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-watchthis-zh.md)
+4. 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)
+5. Bootstrap 总说明：
+   [kindle-voyage-5.13.6-bootstrap-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-bootstrap-zh.md)
+6. 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)
+7. 白屏/KUAL/SSH 交接：
+   [kindle-voyage-5.13.6-white-screen-handoff-zh.md](/Users/gavin/kindle-dash/dash/docs/kindle-voyage-5.13.6-white-screen-handoff-zh.md)
+
+## 已知限制
+
+1. `WatchThis` / demo / `;log mrpi` 仍然不能完全自动化
+2. `bootstrap-new-kindle.sh` 当前还没有做一次真机恢复出厂闭环验收
+3. `ssh kindle` 依赖当前网络和 IP；换 Wi‑Fi 后可能要重新确认地址或 SSH 配置
+4. `KUAL -> Dashboard` 与 `Dashboard -> 原生 UI/KUAL` 的边界切换在 `Kindle Voyage 5.13.6` 上仍不稳定
+5. `stop.sh` 当前必须走保守恢复路径，实验性的“快速切换”方案已在 `2026-03-17` 撤回