update at 2026-03-21 18:44:12

README.md

@@ -13,6 +13,7 @@
 
 - `simple` / `default` 等主题已经接入当前运行链路
 - Kindle 侧采用“低频背景 + 本机时钟重绘”的分层渲染方案
+- 通过 `scripts/sync-layered-clock-to-kindle.sh` 同步主题时，天气背景会优先按 Kindle 当前网络出口位置导出
 - 新机 bootstrap 方案已实现
 - 新机 bootstrap 当前仍是“方案已实现，真机恢复出厂闭环未验证”
 - `launch-from-kual.sh` 与 `setsid` 脱离方案已经落地到代码
@@ -39,6 +40,7 @@
 - 导出 `kindlebg.png`
 - 导出多主题背景包和 `themes.json`
 - 预览不同主题与方向
+- Web 预览页里的天气位置仍优先走浏览器定位；Kindle 实机同步时则优先读取 Kindle 侧 GeoIP 缓存
 
 关键文件：
 
@@ -56,6 +58,15 @@
 - 切换主题、维护运行时主题状态
 - 在需要时拉起主题菜单服务
 
+运行规则：
+
+- 时钟刷新原则：无论 `debug on` 还是 `debug off`，设备侧时钟都按分钟调度刷新一次
+- `debug on`：设备不进入真 suspend，保持常亮，并持续按分钟刷新
+- `debug off`：设备仍按分钟刷新时钟；普通分钟刷新只更新后台缓存，不主动把时钟刷到可视屏幕，刷新后立即回到低功耗调度
+- `debug off` 下短按 `power`：设备进入一个 5 分钟的可视窗口；窗口内时钟仍按分钟刷新，窗口结束后恢复到普通低功耗调度
+- 通过 `KUAL` 启动 dashboard 或切换主题后回到 calendar：同样进入一个 5 分钟的可视窗口，避免用户回来时看到静止时钟
+- 背景图与主题资源保持低频更新；分钟级高频更新只发生在本机时钟区域，不依赖网络
+
 关键文件：
 
 - [dash.sh](/Users/gavin/kindle-dash/dash/src/dash.sh)
@@ -161,6 +172,12 @@ sh bootstrap-new-kindle.sh prepare-storage --download-kterm --kterm-version late
 sh bootstrap-new-kindle.sh post-ssh -t simple -o portrait
 ```
 
+说明：
+
+- `post-ssh` 当前会同步 `dashboard` shell 脚本、`KUAL` 菜单和主题包
+- 它不会回补 `prepare-storage` 阶段预置的原生二进制，例如 `next-wakeup`、`xh`
+- 所以这条路径默认前提仍然是：先跑过 `prepare-storage`
+
 注意：这条新机 bootstrap 方案当前仍未做“真机恢复出厂闭环验证”。
 
 ## 常用命令
@@ -176,6 +193,31 @@ npm run build
 npm run export:themes
 ```
 
+### Web 端定时生成与发布
+
+如果 Web 服务器需要每小时自动生成最新背景图，并把结果放到固定静态目录，使用：
+
+```sh
+sh scripts/publish-calendar-dist.sh --output-dir /path/to/web-root --once
+```
+
+这条命令会：
+
+- 调用 `npm run export:themes` 生成最新 `kindlebg.png`、`themes/<theme>/<orientation>/kindlebg.png`
+- 同步 `calendar/dist/` 整个目录到你指定的 Web 根目录
+
+如果希望常驻运行、每 60 分钟自动重跑一次，去掉 `--once`：
+
+```sh
+sh scripts/publish-calendar-dist.sh --output-dir /path/to/web-root
+```
+
+说明：
+
+- 当前导图依赖 `calendar/scripts/export-kindle-background.swift`，因此这条自动发布链路需要运行在 macOS 上
+- 如果你的线上静态服务器是 Linux，只适合把“发布目录”指到该 Linux 机器挂载出来的目录，或者先在 macOS 上生成后再额外同步
+- Web 服务器应该直接服务这个发布目录，而不是只服务 `vite build` 产出的 HTML；否则 `.png` 路径可能回落成 `index.html`
+
 ### 主题与截图
 
 ```sh
@@ -194,6 +236,10 @@ sh bootstrap-new-kindle.sh prepare-storage --download-kterm --kterm-version late
 sh bootstrap-new-kindle.sh post-ssh -t simple -o portrait
 ```
 
+补充：
+
+- 如果还要执行 `--start-dashboard`，默认同样要求设备上已经有 `prepare-storage` 预置的完整 dashboard 基础运行时
+
 ### SSH 恢复
 
 如果 Kindle 上已经有 `KTerm`，但外部 SSH 不通：
@@ -271,3 +317,6 @@ sh -n snapshot.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` 撤回
+6. Voyage 右上角系统状态栏当前仍可能短暂闪现，顶部遮罩还没有做到完全压住
+7. 天气预报的位置当前使用 Kindle 侧 GeoIP 做“市级近似定位”，结果不保证精确到真实街道或精确城区
+8. 当前架构下，分钟级时钟刷新需要设备被唤醒；而设备一旦被唤醒，屏幕/灯光会一起进入可视态，因此暂时做不到“不亮灯唤醒并肉眼可见更新时钟”