MeowOS-For-R3P2/README.md

# MeowOS for HiBy R3 Pro II

> 把 HiBy R3 Pro II 便携播放器（君正 X1600，MIPS32r2 / mipsel / musl 静态软浮点，480×720，无 GPU 软渲染）变成一个可扩展的「第二系统 + 应用框架」。
> MeowOS 与官方 HibyOS 共存于同一台设备：开机由引导选单二选一；启动后 MeowOS 作为主控层，提供自己的桌面 UI、应用框架、服务管理与系统组件。
>
> 版本：**M2.65（0.7.60）**（版本号单点 = 板上 `/etc/meowos_version`，见「构建」）。
>
> 许可证：Apache-2.0（见 [`LICENSE`](LICENSE)）。本仓库为非官方第三方项目。

---

## 1. 项目简介

**MeowOS 是什么**：一个运行在 HiBy R3 Pro II 上的自制系统与运行时，它提供：

- **双系统共存**：官方 HibyOS 原样保留；开机引导选单决定本次进入哪个系统（MeowOS / HibyOS），两者互斥运行，任一时刻只跑一个。
- **应用框架**：一套 C 应用 SDK（`meow_ui`），第三方 App 用统一控件 / 输入 / 主题 / 字体 / 通知 API 开发，无需自读帧缓冲、自读输入、自管返回——把每个 App 都要踩一遍的坑收口到框架里。
- **系统组件**：状态栏、通知中心、电源菜单、全局左缘返回手势、主界面（应用列表）、设置页、服务管理器、mDNS 广播。
- **进程隔离**：系统 UI 渲染进程与 App 进程相互独立，App 卡死不会冻结整个 UI。

**面向谁**：

- **R3 Pro II 玩家**：刷入后获得可切换的「第二系统」，与官方系统互切使用。
- **开发者**：用 `meow_ui` SDK 编写 MeowAPP，部署到 TF 卡即可热更新，无需重刷固件；也可参与固件 / 框架源码的开发。

**硬件基线（贯穿全文）**

- SoC 君正 X1600；CPU MIPS32r2（little-endian，`mipsel`）；libc musl（**静态**链接，soft-float）。
- 屏幕 **480×720**、24-bit RGB（内部转 RGB565）；**无 GPU**，全部 CPU 软渲染。
- 帧缓冲 `fb0` 为**双缓冲**（虚拟高 1440 = 2×720，显示帧由 `yoffset` 决定，需 `FBIOPAN_DISPLAY` 翻页）。
- 板载存储紧张（`/data` 约 16MB）：所有大件（日志/字库/媒体/应用）一律写 TF 卡，板载只存 KB 级设置。

---

## 2. 核心架构

### 2.1 进程模型（Supervisor 树）——「一个崩不连累全部」

每个系统组件都是一个独立的静态进程（固件 `/usr/bin`，只读 squashfs）：

```
init (rcS)
 ├─ /etc/init.d/S89meow_svcd      开机自启 meow_svcd（服务管理器）
 ├─ /etc/init.d/S90meow_bootmenu  Supervisor / 开机引导选单
 │    ├─（选 MeowOS）拉起 meow_launcherd   ← 系统 UI 渲染宿主
 │    │     └─ 用户点 App → fork/exec MeowAPP + meow_watchdog（每 App 一个）
 │    └─（选 HiByOS）exec hiby_player
 └─ meow_svcd 托管的服务（如 meow_mdns）= 独立子进程
```

- **当前 supervisor = `meow_bootmenu`**：开机引导选单（决定进入哪个系统），并接管关机 / 升级；系统组件由它 / init 逐个拉起。
- **目标架构（设计定案，见 `docs/MEOWOS_SPEC_REF.md` §4，属「系统基建线」）**：新增统一的 `meow_sysui` 系统进程总监，监管 launcher / svcd / mdns / 媒体服务 / MeowPanel——一个进程崩只拉起它，绝不级联、绝不拖垮自身。这是定案与渐进迁移方向，**当前固件仍以 `meow_bootmenu` 为 supervisor**。
- **隔离保证（现已落地）**：系统组件各自独立进程；App 进程与系统 UI 渲染进程独立；svcd 的**每个服务是独立子进程**（服务崩只重启该服务，不拖垮 svcd）。任何 App / 服务崩溃都不冻结系统 UI。

### 2.2 双系统引导（bootmenu）

- `meow_bootmenu`（`/usr/bin/meow_bootmenu`，只读 squashfs）开机绘制轻量选单（fb 绘制 + 触摸/按键），选中后 `exec` 对应系统。
- **boot.default 权威文件 = 板载 `/data/meow_boot_default`**（单值、O_TRUNC、不累积）：`0 = MeowOS`、`1 = HiByOS`。bootmenu 读它决定默认高亮项；`boot.default` 设置变更同步写该文件；`meow.conf` 不再承担 boot_default。
- **双系统互斥**：任一时刻只跑一个。HibyOS 播放器需**开机连续内存**（`sa_hgl_dma` 1.32MB DMA）才能启动，不能"杀+重拉"。因此：
  - **HibyOS → MeowOS**：用热键切换（杀播放器即可，MeowOS 界面不需要 HGL，接管无缝）。
  - **MeowOS → HibyOS**：只能**重启回到选单**（播放器需开机连续内存再次启动）。

### 2.3 launcher —— 系统 UI 渲染宿主

`/usr/bin/meow_launcherd`（源码 `patch_v2/meow_launcherd/`）是 MeowOS 的核心进程，负责渲染**系统级 UI**：

- 状态栏（28px：时钟 / 电量 / WiFi / 蓝牙 / 音量）；
- 通知中心（顶部下滑展开，launcher 渲染，功能见 §2.6）；
- 电源菜单、全局左缘返回手势、全屏提示线；
- 主界面（应用列表）、设置页。

**渲染与 App 进程隔离**：launcher 是系统进程，App 是独立进程。App 卡死/崩溃只影响该 App，系统 UI（状态栏/返回/通知中心）始终可用。

> ⚠️ `meow_launcherd` 本身就是系统进程，**不要远程 kill 它**——否则会整机重启。

### 2.4 SDK（meow_ui）—— App 开发框架

`patch_v2/sdk/` 构建出 **`meow_ui.a`**（mipsel 静态库，内含 `meow_font.o` + `stb_image` 图片解码）。App 只链它 + `libz.a` + `-lpthread`，用 API 写业务，不重复造轮子。

- App **不** `open /dev/fb0`、不 mmap、不 ioctl、不 `open /dev/input/event*`；屏幕/输入由 SDK 在 App 启动时建立、退出时释放。
- 渲染统一走 `back_buf`（RGB565）+ `meow_present(dirty)`：App 画到离屏缓冲区，`meow_ui_flush()` 时才单次原子 blit 到 fb0（等垂直同步 + 脏区，无撕裂、无频闪、不整屏重绘）。
- 分层：绘制层 / 控件层 / 图片层（stb_image 解 PNG/JPEG/BMP）/ 输入层（语义事件）/ 主题 / 字体。

**三层控件模型（Activity 栈 + 控件归属）**——控件严格归属创建它的 Activity，不跨页面共享（根治「跨页残留」：旧按钮已不可见但仍被触摸命中）：

| 层 | 谁负责 | 谁能用 | 生命周期 |
|---|---|---|---|
| **① 页面控件** | 归属唯一 owner Activity | App | 随 Activity 栈；owner 在栈顶（active）才绘制 + 响应触摸 |
| **② App 跨 Activity 控件** | **SDK 托管**（逻辑 + 渲染） | App 可声明使用 | 钉在 App 的 Activity 栈**之上**，跨 Activity 常驻 |
| **③ 系统级控件** | MeowOS / SDK 框架内部 | **仅系统组件，用户 App 禁调用** | 随系统，不开放 |

- **交互命中分流**：③ 系统全局 → ② App 全局 → ① 当前 Activity 页面控件；某层命中即消费，否则落到下一层。
- **系统 UI 归属与进程隔离（核心）**：状态栏 / 通知中心 / 电源菜单 / 全局返回滑条等**系统级组件由系统进程（launcher）渲染，App 进程不渲染系统 UI**；SDK 系统组件 API **仅供系统进程链接调用**，App 拿不到、不可自建悬浮层 / 全局叠加。
- 控件 API：`meow_ui_activity_push/pop`（Activity 栈）、`meow_btn/slider/switch/list_create`、`meow_ui_global_add/remove`（② 层）。对象不随 pop 销毁（复用），弹栈回来自动恢复命中。

### 2.5 服务

- **meow_svcd（服务管理器）**：类 systemd/systemctl，`/usr/bin/meow_svcd`，`etc/init.d/S89meow_svcd` 开机自启。**每个服务 = svcd 的独立子进程**（fork+execv），服务崩只重启它，不拖垮 svcd。
  - **双源 services.d**：板载 `/usr/data/meow/services.d/<name>.conf`（Data 区，拔卡保留，权威优先）+ TF `MeowOS/services.d/<name>.conf`（随卡存在/消失）。同名**板载优先**（TF 被屏蔽 + WARN）。
  - 目录式 `key=value`：`exec`（必填）/`args`/`env`/`enabled`/`restart`/`backoff_ms`/`max_restart`/`trigger`（`boot`/`card-mount`/`wifi-up`，默认 `card-mount`）。
  - 状态机 `DISABLED/STOPPED/RUNNING/STOPPING/FAILED`；CLI（SSH 直呼）：`status` / `reload` / `start|stop|restart <name|all>` / `pid`。
- **meow_mdns（mDNS 应答器，自研）**：`/usr/bin/meow_mdns`，**IPv4-only**（该设备内核无 IPv6，完整 mDNSResponder/SAResponder 均无法运行），应答 `<host>.local` 的 A 记录与 `_ssh._tcp` 的 PTR/SRV/TXT。由 `meow_svcd` 托管（板载 `services.d/mdnsd.conf`，`trigger=boot`）。
  - **hostname = `meowos`**（设置键 `system.hostname`，缺省 `meowos`；`S89meow_svcd` 开机 `sethostname`）→ 即 `meowos.local`。
  - 注：手机热点会丢弃设备→主机的组播应答，`avahi-resolve meowos.local` 在上网热点下会超时（网络层热点隔离，非应答器缺陷），主机可用 DNS 兜底。

### 2.6 通知系统

后端 = 通知存储 + 分发，遵循 **freedesktop.org Desktop Notifications**（`org.freedesktop.Notifications`）标准字段：`app_name` / `replaces_id` / `app_icon` / `summary` / `body` / `actions[]` / `hints{}` / `expire_timeout`，返回通知 id。MeowOS 扩展：`hints` 内 `meow.target_activity`（点击跳转）与 `meow.progress`（进度）。

- **来源**：MeowAPP（原生 IPC `MSG_NOTIFY`）+ 系统事件（抽象为 `app_id=system`，走同一配额）+ 外部桌面 App（D-Bus 桥 `meow_notify_dbus`，规划）。
- **配额**：每 App 最多 **4 个**通知类型（category）；每类型活跃 **≤4**；媒体通知单例（每 App 仅 1 条，可多 App）。系统事件同配额。
- **TTL / 转储**：通知创建 **10s** 后追加写入 TF `MeowOS/notifications/`（CSV 行，滚动保留**最新 10MB**，不被电源事件清）；正常关机先转储再清板载；开机清板载残留 + 清内存表；**无 TF 卡可运行**（仅内存态）。`urgency`（0-3）、`icon`、`progress`（实时进度仅改内存活跃槽，里程碑落盘，不每帧写卡）。
- 通知数据模型补全（SDK→IPC→存储→dump 全链路）：`meow_notify_send` 返回 id、`meow_notify_update_progress`、`urgency`/`icon` 字段。通知中心 UI 由系统进程（launcher）渲染，数据经 IPC 从存储读取。
- **通知中心 UI（系统进程 launcher 渲染，M2.65 已实现）**：顶部下滑展开。含**快捷行 5 chip**〔WiFi / 蓝牙 / 主题 / 亮度 / **电源菜单**——电源菜单 chip 点击唤起**真电源菜单**〕、**勿扰开关**（面板内小 toggle，开=只显示高优先级 `urgency>=2`，设置键 `notify.dnd`）、**通知列表滚动**、**单条通知左滑删除**（跟手、半程可回、过阈值滑出删除）、**一键清除**（与勿扰对称的清除按钮，仅清**非活动**通知，先转储留档再清显示；ongoing / 媒体 / 进度条进行中一律保留）、**面板跟手下拉 / 半程可回**（1:1 跟手、松手 40% 锚定，与行左滑 / 列表滚动 / 左缘返回互斥）、面板/开关带**滑条平移动画**（复用设置页方案）。交互细节见 `NOTIFICATION_SYSTEM.md §9`。

### 2.7 字体系统

- 多字体库在 TF 卡 **`MeowOS/fonts/<family>/<weight>/`**（每套三件套：`font.png` + `font.idx` + `font.json`），由 `font/gen/gen_font.py` 生成（`--weight` 写字重、`--charset` 档位）。
- 字体列表索引 **`MeowOS/config/fonts/index`**：launcher 扫描后落盘（`family,weight,path,label,tier,glyph_count` CSV）；SDK 读该文件枚举字库，**不自行发现**。
- `font.file` 设置键选默认套（缺省 `MeowOS/fonts/default/regular/font.png`）；`font.json` 标 `weight` / `charset`（`common`≈4k / `gbk`≈20k+ / `full`）/ `glyph_count`；缺失件 → 该套跳过 + 日志。
- 字库档位：默认用小字库（`common`≈4k）；App 声明需大字库（`app.json "fonts":"full"`）才加载大字库；`font.load_full` 强制全系统大字库。
- 多字体（`display.multi_font`）：按字符类别（CJK/LATIN/NUM/…）逐字符路由，可各选一套。
- **App 未自带字库 → 跟随系统 `font.file`**：launcher 启动 App 前把当前生效字体注入为 env `MEOW_FONT_PNG`/`MEOW_FONT_IDX`（绝对路径），SDK 优先读 env；无 env 回退卡默认 → 固件内置。SDK `meow_font_has_glyph(cp)` 预判当前字库是否含某码位（缺字回退/提示）。
- 应用自带字库（`MeowAPPs/<pkg>/fonts/<handle>/`，多句柄 `_h` API）为**草案/未实现**；当前 App 只能跟随系统字体。

### 2.8 设置后端

`meow_settings_*`（C API：`get/set` int/str/enum/bool + listener 变更通知）读写**板载 `/usr/data/meow/settings.conf`**（UBIFS，几十行、<10KB），跨换卡/掉卡保留配置。板载只存 KB 级设置；日志/字库/媒体等大件一律 TF 卡（无卡优雅降级）。

贯穿子系统的键（详见 `SYSTEM_SETTINGS.md` / `docs/MEOWOS_SPEC_REF.md`）：开机 `boot.default`、刷新率 `display.refresh_rate`（60/30/15）、亮度 `display.brightness`（clamp ≥ `display.brightness_min`，下限 **1**）、息屏 `display.screen_off_timeout`（默认 30s）、主题 `display.theme_mode`、主机名 `system.hostname`（=meowos）、字体 `font.file`/`display.multi_font`/`font.load_full`、通知配额 `notify.*` 等。

---

## 3. 目录结构

> 标注「入库」= 本仓库已提交；未标注的为**本地构建 / 开发资产**（gitignore 不入库，需本地生成）。

- **`patch_v2/`（入库）**—— MeowOS 核心源码：
  - `bootmenu/`   引导选单 + Supervisor（`meow_bootmenu`）
  - `meow_launcherd/`  launcher（系统 UI 宿主）、`meow_ipc`、`meow_settings`、`meow_font`、`meow_notif`、`meow_card_path.sh`
  - `sdk/`  meow_ui SDK 源码 + `build_sdk.sh`（→ `meow_ui.a`）
  - `hello_app/` 示例 App（`hello.c` + `build_hello.sh`）
  - `meow_svcd/`  服务管理器；`meow_watchdog/`  应用看门狗；`meowpkg/`  包管理；`uinput_tap/`
- **`mips-repo/`（入库）**—— mipsel 交叉编译软件仓库：`bins/`（`meow_mdns` / `mdnsd` 等二进制工具 + `build.sh` + `manifest.md`）、`mpk/`（`.mpk` 应用包）。
- **`docs/`（入库）**—— `MEOWOS_SPEC_REF.md` 权威速查总索引。
- **`font/`（入库）**—— 字形系统：`gen/gen_font.py` 生成器、`meow_font.c/.h` 渲染库、`demo/`、`src/`（字体源文件）。
- **`bootlogos/`（入库）**—— 启动 / 关机 logo。
- **`LICENSE`** —— Apache-2.0。
- **顶层文档（入库）**—— `APPS.md`、`MEOW_APP_SDK.md`、`FRAMEWORK_DESIGN.md`、`SYSTEM_SETTINGS.md`、`NOTIFICATION_SYSTEM.md`、`TF_CARD_LAYOUT.md`、`DEVELOPMENT_PLAN.md`、`GESTURE_BACK_DESIGN.md`、`KEY_CONTROL_DESIGN.md`、`PERF_SCHEDULER.md`、`MEOWOS_API.md`。
- **本地构建资产（gitignore，不入库）**—— `scripts/build/`（固件打包脚本）、`fw_apps/`（固件组装产物）、官方固件基线 rootfs、交叉工具链、本地开发文档、设备密钥等。详见「构建」与「部署」。

---

## 4. 构建

整条构建是 **mipsel-linux-muslsf 静态交叉编译**链，需要本地交叉工具链（`zig-mipsel-cc`，目标 `mips-linux-musl`）+ `mipsel-linux-muslsf` sysroot（这类工具链为本地大件，gitignore 不入库）。

**1. 构建 SDK**（入库脚本）
```sh
patch_v2/sdk/build_sdk.sh        # → patch_v2/sdk/meow_ui.a
```
> 注：SDK 编译期引用 launcher 的 `meow_ipc.h` 共享协议头（`meow_notify_ipc.c` 复用同一份，杜绝两端漂移），属**已知设计**；运行时 App 只链 `meow_ui.a`（含 `meow_font.o`），不会链入 launcher 符号。SDK 库**不进固件**，只随 App 链接。

**2. 构建示例 App**（入库脚本）
```sh
patch_v2/hello_app/build_hello.sh   # 链 meow_ui.a + libz.a + -lpthread → hello（静态 MIPS32r2）
```
产物放 TF 卡 `MeowAPPs/os.meow.hello/`（见「部署」）。

**3. 构建固件（本地流程）**

固件 = 官方 v1.4 固件基线 rootfs + SSH 工具集 + MeowOS 系统组件（`meow_bootmenu` / `meow_launcherd` / `meow_watchdog` / `meow_svcd` / `meow_mdns` + 相关 init 脚本 + `/etc/meowos_version`）。特点：

- 打包脚本 `scripts/build/build_fw_apps_m2NN.sh` 是**本地构建工具（gitignore 不入库）**——本仓库只提交源码与文档，需本地交叉工具链 + 官方固件基线 rootfs 才能复现。
- **rootfs 上限 45,088,768 B（≈45MB）**；产物 `fw_apps/r3proii_m2NN.upt`。
- `/usr/bin` 各组件为静态 MIPS32r2；版本号以 `/etc/meowos_version` 为单点。
- 外围 CLI（curl/socat/tmux/jq/…）已迁 TF 卡 `MeowOS/opt/bin/`（不进固件）；固件**不含** SDK 库（`meow_ui.a` 只随 App 链接），`hiby_player` 保持官方原样。

> 第三方开发者通常**不需要**重打包固件：用 `build_hello.sh` 类似方式构建 SDK App 后直接部署到 TF 卡即可热更新（见「部署」）。

---

## 5. 部署 / 刷机

**刷机（整机刷新 MeowOS 固件）**

- 打包产物名 `r3proii_m2NN.upt`；要刷机时把它**复制为 TF 卡根目录的 `r3proii.upt`**。
- 关机（failsafe）后按住**音量加 + 电源**进入升级模式，从卡根 `r3proii.upt` 升级。避免使用播放器 UI 里那个会卡死的升级按钮。
- 回退：用官方固件重刷，或从 `backups/`（NAND 全量备份，本地）恢复。

**部署 / 热更新 App（无需重刷固件）**

- TF 卡布局见 `TF_CARD_LAYOUT.md`。App 目录 `MeowAPPs/<package>/`（`package` = `app.json` 的 `package`，如 `os.meow.hello`）：`app.json` + 静态 MIPS 二进制 + 资源；数据在 `MeowData/<package>/{data,cache}`。
- **热更新**：把构建产物放入 `MeowAPPs/os.meow.hello/` 即可；launcher 每次打开菜单重扫卡，立即可见。App 二进制/资源在卡上；拔卡会优雅降级（应用列表"未插卡"/字体回退/日志回退内存环），不崩系统。
- 应用日志：`MeowOS/logs/apps/<package>/logs/<ts>_<pid>.log`（每次启动新文件，单文件 2MB 轮转、每 App 总量上限）。包管理 CLI `nyai`（放 `MeowOS/opt/bin/nyai`）：`nyai install <pkg>/<file.mpk>` 等。

**TF 卡目录（关键）**
```
/usr/data/mnt/sd_0/
├── Music/                 # 音乐库
├── MeowData/<pkg>/{data,cache}
├── MeowAPPs/<pkg>/        # 应用（app.json + 二进制 + 资源）
└── MeowOS/
    ├── fonts/<family>/<weight>/   # 多字体库
    ├── config/fonts/index         # 字体列表索引
    ├── notifications/             # 通知转储（10MB 滚动）
    ├── logs/                      # 系统 / 应用日志
    ├── services.d/<name>.conf     # 服务配置（TF 源，与板载双源）
    └── opt/bin/ …                 # 外围工具（nyai/curl/…）
```

---

## 6. 开发 SDK App

### 6.1 app.json

```json
{
  "name": "Hello App",
  "exec": "/usr/data/mnt/sd_0/MeowAPPs/os.meow.hello/hello",
  "package": "os.meow.hello",
  "version": "0.1",
  "author": "whoever"
}
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `name` | ✓ | 列表显示名（v2 仅支持 ASCII） |
| `exec` | ✓ | 可执行文件绝对路径（必须为**静态** MIPS32r2 ELF） |
| `package` | — | 反域名权威 app_id（= 目录名；缺省回退目录名，两者不同 → WARN） |
| `version` / `author` | — | 保留字段 |
| `fullscreen` | — | app 级全屏：状态栏**收合至提示线** + 保留左缘返回 / 顶部提示线 / 下滑通知中心（activity 级用 `route.<id>.fullscreen`） |
| `fonts` | — | 字库档位声明 `"full" | "gbk" | "common"`（默认 `common`≈4k） |

其他扩展（launcher 极简解析、不校验 JSON）：`icon` / `framework` / `immersive` / `route.<id>`（路由表）/ `awake.<id>`（keep_awake）/ `service.<svc>`。应用数上限 8，扫描深度 1 级。

### 6.2 链接与入口

- 链接：`meow_ui.a` + `libz.a` + `-lpthread`（见 `patch_v2/hello_app/build_hello.sh`）。
- 事件循环：`meow_ui_init(&opts)` → 注册控件 → `meow_ui_run(&ev)`（阻塞）；`meow_ui_request_exit()` 退出；`meow_ui_time_ms()` 单调时间（动画用）。

### 6.3 事件回调（meow_ui_events）

| 回调 | 触发 |
|---|---|
| `on_key(keycode, is_down)` | SDK 已消化系统语义的按键；**不要**用它实现「电源 = exit」这类映射 |
| `on_tap(x, y)` | 触摸抬起落点 |
| `on_swipe(dir, dx, dy)` | 左缘返回手势 = `MEOW_SWIPE_LEFT`；中部滑动 = `RIGHT/UP/DOWN` |
| `on_swipe_progress(x_start, dx)` | 左缘返回手势实时进度（SDK 自动画顶部提示条 `meow_ui_swipe_hint`） |
| `on_tick()` | 空闲周期回调（动画 / 时钟） |

返回语义：`on_swipe(LEFT)` 里调用 `meow_ui_request_exit()` 回应用列表，或页内处理不退出。

### 6.4 控件 / 主题 / 字体 / 通知 API

- **控件**：`meow_btn_create` / `meow_slider_create` / `meow_switch_create` / `meow_list_create(count, src, ctx)` + `meow_widget_draw/hit`；`meow_ui_activity_push/pop`（Activity 栈，控件归属当前 Activity）、`meow_ui_global_add/remove`（② 层 App 跨 Activity 全局控件）。
- **图片**：`meow_img_load_file/mem` + `meow_ui_img/scaled/alpha/cover`（stb_image 解 PNG/JPEG/BMP；`cover` = 居中裁方）。
- **IME**：`meow_ui_text_input` / `_async`（仅英文/数字 ASCII，键盘占底部）。
- **主题**：`meow_theme_set_mode(light/dark/auto)` + `meow_theme{bg,fg,accent,dim}`，切换即时生效。
- **字体**：`meow_font_get_available_count/enumerate`（读 `MeowOS/config/fonts/index`）、`meow_font_select_by_id`、`meow_font_has_glyph(cp)`；多字体 `meow_font_config_multifont` / `meow_font_load_slot`。
- **通知**：`meow_notify_register_type(cat)`（每 App ≤4 类）/ `meow_notify_send(const meow_notify*)`（返回 id）/ `meow_notify_cancel(id)` / `meow_notify_update_progress`；常量 `MEOW_NOTIFY_MAX_TYPES=4`、`MEOW_NOTIFY_MAX_PER_TYPE=4`、`MEOW_NOTIFY_MAX_MEDIA=1`。
- **日志**：`meow_log(lvl, fmt, ...)`（`MEOW_LOG_DEBUG/INFO/WARN/ERROR`）→ `MeowOS/logs/apps/<package>/logs/`。

### 6.5 物理键规范（红线）

- **物理按键是系统资源，语义由 MeowOS 统一管理，App 禁止映射。** 任何非系统组件不得把物理键映射为任何行为（如电源→OK/exit、音量→确认/选择、播放→返回）。
- 语义只有一份：**电源 = 息屏 / 亮屏**（长按 = 电源菜单，8s = 强关）；**音量 = 调音量**；**播放 / 上下曲 = 媒体控制**。返回走**触摸**（左缘左滑 / 虚拟返回键），不是物理键。
- App **不读** `/dev/input/event*`、不 open/mmap fb0、不处理物理 keycode；想返回/退出用 `meow_ui_request_exit()` 或左滑。SDK `on_key` 回调只做语义事件，不承载"电源 = exit"类映射。
- 屏幕导航一律走触摸（返回按钮 / 左缘左滑）；任何 MeowOS 界面（含设置页）也不可私自定义按键行为。

### 6.6 Activity 用法（进阶）

- 冷启动跳转 / 逻辑深度由框架按**路由表**解析：`app.json` 扁平行 `route.<id>=path`（如 `route.nowplaying=home;search;nowplaying`），经 env `MEOW_ACTIVITY` / `MEOW_CHAIN` 注入；App 用 `meow_ui_activity_push/pop` 管理栈。详见 `FRAMEWORK_DESIGN.md` / `MEOW_APP_SDK.md`。

---

## 7. 文档索引

| 文档 | 内容 |
|---|---|
| `docs/MEOWOS_SPEC_REF.md` | **权威速查总索引**（首选入口）：路径 / 常量 / 接口 / 约定 + 「已知矛盾 / 待确认」清单 |
| `FRAMEWORK_DESIGN.md` | Activity / 通知 IPC 框架协议（AF_UNIX socket、路由表、导航栈、后台权限、媒体会话、freedesktop/MPRIS/XDG 对齐） |
| `MEOW_APP_SDK.md` | SDK 设计：架构分层、绘制/控件/图片/输入/主题/字体/通知 API、三层控件模型、Activity 栈、动画与性能 |
| `APPS.md` | MeowAPPs 应用规范：目录、`app.json` 字段、生命周期、边界、返回键、`.mpk` 包与 `nyai` |
| `NOTIFICATION_SYSTEM.md` | 通知系统：freedesktop 标准、配额、TTL/转储、存储分层 |
| `SYSTEM_SETTINGS.md` | 设置子系统：统一存储 + `meow_settings_*` C API + 变更通知 + 导入导出 |
| `TF_CARD_LAYOUT.md` | TF 卡目录布局 + 「固件 / 卡」分头原则（拔卡降级） |
| `DEVELOPMENT_PLAN.md` | 路线图与分阶段计划（**部分已过时，以实际进度为准**） |
| `GESTURE_BACK_DESIGN.md` / `KEY_CONTROL_DESIGN.md` / `PERF_SCHEDULER.md` | 左缘返回 / 按键契约与信号 / 帧率调度 |
| `mips-repo/README.md` | mipsel 软件仓库（`bins/` 工具 + `mpk/` 应用包）与 meow_svcd CLI |

> 文档收敛规则：新功能在对应权威文档（`MEOW_APP_SDK.md` / `APPS.md` / `SYSTEM_SETTINGS.md` 等）补小节；新增决策/检查点记录在本地开发文档；过时的一次性设计归档。

---

## 8. 约束 / 硬件

- **无 GPU，全 CPU 软渲染**；480×720 双缓冲（虚拟高 1440、yoffset 翻页）。
- **性能铁律：局部脏区刷新，不整屏重绘**。渲染走 `back_buf` + `meow_present(dirty)`（脏区矩形合并集、相交吸 bbox、超过阈值转全屏、裁可视区）；状态栏时钟 / 格按需局部标脏；等垂直同步 + 单次原子 memcpy。刷新率调度 `display.refresh_rate` 60/30/15 + 自适应降档（连续 12 帧超预算降一档、远低预算升一档）。
- **rootfs 上限 45,088,768 B（≈45MB）**；`/usr/bin` 各组件静态 MIPS32r2。
- **板载存储极小**（`/data` 约 16MB）：只写 KB 级设置（`/usr/data/meow/settings.conf`）；日志 / 字库 / 媒体 / 应用一律写 TF 卡；无卡优雅降级（不崩不死）。
- **mtd 分区**（勿写 NAND）：mtd0=uboot、mtd1=kernel、mtd2=rootfs、mtd3=kernel2、mtd4=rootfs2、mtd5=ota（8M 标记）、mtd6=userdata。
- **安全红线**：不要远程 kill 常驻 `meow_launcherd`（整机重启）；`hiby_player` 只能 SIGSTOP/SIGCONT，严禁 killall / 对其发未注册信号（如 SIGUSR1 导致整机重启）/ 走 `hiby_player.sh`；严禁触碰 NAND / `recovery_all`；播放器不能「杀+重拉」（HGL 连续内存）。
- 本仓库为**非官方第三方项目**，修改并与官方固件共存；刷机有一定的变砖风险（可用官方固件刷回），请自行评估。所有「真机验证」项请以实机为准。