# MeowOS for HiBy R3 Pro II

> 把 HiBy R3 Pro II 便携播放器（君正 X1600，MIPS32r2 / mipsel / musl 静态软浮点，480×720，无 GPU 软渲染）变成一个可扩展的「第二系统 + 应用框架」。
> MeowOS 与官方 HibyOS 共存于同一台设备：开机由引导选单二选一；启动后 MeowOS 作为主控层，提供自己的桌面 UI、应用框架、服务管理与系统组件。
>
> 版本：**M2.88（0.7.83）**（M2.69→M2.88 全链路自刷验收：控件库/主界面 MD3 双布局/M3 导航栈/M5 通知跳转/媒体会话/Now Playing/SDK nav+media 封装/字库启动竞态修复**/M2.84-88**：installed 图标修复+残帧pan加固/物理键EVIOCGKEY双源/签名鉴权 2B/meow_route 音频路由/amsd 二期(picker 契约)/网易云二期(封面·歌词后台·大歌单分页)/MeowPanel 实时画面+遥控+通知实时化/中文拼音 IME）。版本号单点 = 板上 `/etc/meowos_version`，见「构建」。本仓库是一个**自带 SDK、包管理、媒体会话、网页面板、网易云客户端的完整第三方系统**。
>
> 许可证：Apache-2.0（见 [`LICENSE`](LICENSE)）。本仓库为非官方第三方项目。

---

## 1. 项目简介

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

- **双系统共存**：官方 HibyOS 原样保留；开机引导选单决定本次进入哪个系统（MeowOS / HibyOS），两者互斥运行，任一时刻只跑一个。
- **应用框架**：一套 C 应用 SDK（`meow_ui`），第三方 App 用统一控件 / 输入 / 主题 / 字体 / 通知 API 开发，无需自读帧缓冲、自读输入、自管返回——把每个 App 都要踩一遍的坑收口到框架里。
- **系统组件**：状态栏、通知中心、电源菜单、全局左缘返回手势、主界面（应用列表，**MD3 卡片宫格/列表双布局**）、设置页、服务管理器、mDNS 广播；系统进程总监 `meow_sysui`；专项子服务 `meow_svc_perf`（性能/系统只读聚合，含真实 network）与 `meow_svc_power`（关机/重启/升级/回 HiBy，含升级写保护 + dac 真实音量 + 读级鉴权放宽）；系统级崩溃捕获 `meow_crash` + App 崩溃直报；.mpk **Ed25519 签名验签** `meow_verify`（见 §2.9）；MeowPanel 外部管理面板（HTTP/JSON 后端 + Web 前端，支持可选密码鉴权，见 §2.10）。
- **媒体会话 / Now Playing**：`MSG_META`/`MSG_PLAYCTL`（0x72/0x73）媒体会话（最近活跃源，30s 超时回收）+ 通知中心**媒体卡片** + 主界面左滑 **Now Playing 大页**；媒体键路由到最近活跃媒体会话。
- **应用生态**：**网易云 dev.player.ncm**（`core/`：mbedtls+jsmn+qrcodegen+minimp3 ≈438KB；v1 复古 UI：登录二维码/我创建的·我收藏的双页签/搜索/歌单详情/黑胶播放页/设置，ALSA 直开 hw:0,0 播放，登录 803 已通；二期：专辑封面/歌词后台加载/大歌单分页）；外置**系统文件管理器 os.meow.files**；`meow_ui` SDK 配套结构化列表 `W_LISTVIEW`、通用长按、SDK nav/media 封装、视图框架（可嵌套 view + 事件路由 + 绘制期 clip）；App 通知查询/清除 IPC（0x25-27）与**点击通知跳转路由**（route_status）。
- **进程隔离**：系统 UI 渲染进程与 App 进程相互独立，App 卡死不会冻结整个 UI。
- **包管理**：`nyai`（固件内置 `/usr/bin/nyai`）支持 .mpk 安装/升级/导出/列表/索引，走 **version_code 安卓式版本规则**（缺 code 拒装、防降级）+ 签名分级（有签必验、`os.meow.*` 无签拒装、第三方直装告警）+ 导出过滤与体检。

**面向谁**：

- **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/S70meow_sysui     系统进程总监（meow_sysui，S70，M2.71 引入；监管 svcd + launcher，M2.83 起 launcher 移交 sysui）
 ├─ /etc/init.d/S89meow_svcd      开机自启 meow_svcd（服务管理器）
 │    ├─ meow_mdns 及 services.d 服务 = 独立子进程
 │    └─ 专项子服务（一期）= meow_svc_perf / meow_svc_power
 └─ /etc/init.d/S90meow_bootmenu  Supervisor / 开机引导选单
      ├─（选 MeowOS）execv meow_launcherd   ← 系统 UI 渲染宿主
      │     └─ 用户点 App → fork/exec MeowAPP + meow_watchdog（每 App 一个）
      └─（选 HiByOS）exec hiby_player
```

- **进程总监 `meow_sysui`（M2.71 已落地，`/usr/bin/meow_sysui` + `S70meow_sysui`）**：监管系统进程，**一个崩→只拉起它，绝不级联、绝不拖垮自身**。自身最小依赖、不渲染、不承载重逻辑 → 最稳。默认监护 `meow_svcd` + `meow_launcherd`（**M2.83 起 launcher 生命周期移交 sysui**：`sysui.d/launcher.conf` `enabled=1`（restart=always/backoff=3000/max_restart=5）；bootmenu 在 MeowOS 模式让位——sysui 在则不 exec launcher）；`meow_mdns` 是 svcd 的服务子进程（不双重管理）。配置 `sysui.d/` 目录式（复用 services.d 语义），见 `patch_v2/meow_sysui/meow_sysui.md` 与 `docs/MEOWOS_SPEC_REF.md` §4。
- **专项子服务（M2.73 已落地，规划见 `devdocs/plan/SYSTEM_FRAMEWORK_SERVICES.md`）**：新增两个 **svcd 托管、板载 `trigger=boot`** 的专项子服务——`meow_svc_perf`（性能 / 系统只读聚合，含 network）、`meow_svc_power`（关机 / 重启 / 升级 / 回 HiBy 系统动作，含升级写保护 + dac 真实音量）。launcher 电源菜单与 MeowPanel 改经这些服务 IPC 触发，不再直连 `sys_do_reboot`/爬 `/proc`。电源 CLI `meow_svc_power <cmd>`（root 免鉴权、单一命令、不覆盖系统 shutdown/reboot）。**二期已落地**：关键 IPC 只接受 `os.meow.*` 鉴权 + `.mpk` 打包签名验签（agent-185 2A / agent-221 2B）。详见 §2.9。
- **隔离保证（现已落地）**：系统组件各自独立进程；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`是 MeowOS 的核心进程，负责渲染**系统级 UI**。**二进制名不变**（`/usr/bin/meow_launcherd`，bootmenu `LAUNCHER_BIN` 指向它），源码 M2.69 起由单文件 `patch_v2/meow_launcherd/meow_launcherd.c`（9778 行）**拆分为多模块**（`patch_v2/meow_launcherd/`，当前含 `main_menu/statusbar/settings_page/power_menu/notif_center/app_launcher/fb_compositor/audio/backlight/net/about/font_theme/keys/util` + 后期新增 `subpage/wifi_page/bt_page`（蓝牙/WiFi 独立子页）、`now_playing`（Now Playing 大页）、`meow_media`（媒体会话，最近活跃源 + 30s 超时回收）+ 共享头 `meow_launcher_internal.h`；`build_launcher.sh` 列模块）——逻辑更清晰、便于并行开发，行为不变。

负责渲染：

- **状态栏（统一系统进程渲染）**：由 launcher 作为**唯一渲染主体**（主界面与 App 前台用**同一个**状态栏实例，App 不画、不做「样式一样的两套实现」）；右侧 **MD3 图标 + 变量值**（时钟/电量/WiFi/蓝牙/音量，数据源唯一由 launcher 统一喂/取，两边必然一致）；**全屏收合**：状态栏向上收出屏顶、只留提示线，**顶部保留 28px 热区**（仍可下滑通知中心）+ 左缘指示条；随主题 `ui.style` 换图标集。
- 通知中心（顶部下滑展开，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 销毁（复用），弹栈回来自动恢复命中。

**SDK 控件库（统一控件架构，M2.70/M2.71 两批落地，见 `MEOW_APP_SDK.md` §5.8）**：
- **第一批 = 通用基座（M2.70/0.7.65）**：`meow_widget` 基座统一标准控件与自定义画布；`meow_widget_opts`（Modifier 式通用 Options，`meow_widget_set_opts`）；统一状态机 `MEOW_WS_ENABLED/SELECTED/FOCUSED/PRESSED`（`meow_widget_set_state`）；`meow_widget_custom_create`（自定义画布，App 提供 render/hit 回调）；布局 `meow_row/column/box` + `meow_layout_add/arrange` + `spacer`；主题接口 `meow_ui_set_style` / `meow_theme_get`（MD3/MIUIx × 明暗 + 背景全局源）。
- **第二批 = Material 组件子集（M2.71/0.7.66）**：Button 五型（`meow_btn_create_variant`）/ TextField（IME）/ Card / Divider / Badge / Checkbox / Radio / ProgressBar / FAB / TopAppBar / NavigationBar / TabBar / LazyColumn/LazyRow / Dialog / BottomSheet。
- **M2.73 控件库修复（`meow_ui.a` md5 `e8341975`，见 `MEOW_APP_SDK.md` §5.8）**：`W_LIST`（含 LazyColumn/LazyRow）**视口裁剪**——滚动时只绘制落在视口内的行/分隔线/文本，杜绝「行滚出视口把内容画到视口外并标脏上屏」导致的标题栏/底部脏区（SDK 全局生效，非 App 侧）。IME（`meow_ui_ime.c`）：键盘区背景快照/恢复（无残影）、配色走主题、shift 大小写、阻塞 `meow_ui_text_input` 喂 `on_tick`（避免进度条卡死）、OK（回车）= 提交并关闭 / ESC = 取消并关闭、回显条=实时输入回显（非候选/联想，候选框留中文输入法）。渲染：局部刷新不再清底重画单个控件（改 z 栈重画），消除重叠区残留。
- **M2.76+ 新增**：`W_LISTVIEW` **结构化列表控件**（§5.5 A②落地：图标/标题/副标题/右侧操作 arrow·switch·check·more、单选/多选/禁态、行右 1/3 操作区命中、视口裁剪、全语义色）；**通用长按事件** `MEOW_EV_LONG_PRESS`（坐标式 + `meow_ui_set_long_press_cb/ms` opt-in，默认 500ms，移动>12px 取消、长按后抬手抑制 TAP/SWIPE）；**视图框架**（`meow_ui_view.c`：可嵌套容器 + 六生命周期 + `page_push/pop/replace` 包装 activity 栈 + 广播注册表 z 序 + `meow_view_dispatch_event` z 降序子>父命中即消费 + **绘制期通用 clip**`g_clip_stack[16]` 根除越界脏区）；**SDK 级 z 序已并入视图框架**（自动注册 + 子>父 + `set_z(999)` 置顶 + 收敛 live_btn），hello App 层 `d_paint_region` 临时方案退役。
- **M2.82 新增**：SDK **nav/media 封装**——`meow_ui_nav.c`（env 栈初始化 + report/request_exit）、`meow_ui_media.c`（懒连断线重连，meta 上报 + playctl 接收）；SDK 顶部下滑手势→IPC 请求 launcher 展开通知中心（§10.5，App 进程不渲染系统 UI）。
- **M2.84-88 新增**：**amsd 活动管理器**（一期 agent-212 生命周期注册表+`am` CLI，二期 agent-225 路由决策化+**picker 契约** `MSG_PICKER_CALL/RESULT 0x70/71` + `MSG_AMS_START/KILL`）；**签名鉴权 2B**（agent-221 多公钥数组 + v2 签名块）；**meow_route 音频输出路由**自动跟随插孔（agent-220）；**中文拼音 IME**（agent-229 `meow_pinyin.c` 静态表 403 音节+329 词，组合条+候选栏+翻页+中英切换）；**App 内物理音量/媒体键**（agent-226 EVIOCGKEY 位图轮询+120ms 去重）；**开机亮度 stop100 竞态**（agent-230）；**网易云二期**（agent-222 专辑封面/歌词后台/大歌单分页）+ 歌单详情回退（agent-227）；**MeowPanel 阶段 C**（agent-224 实时画面 `/api/screen.jpeg` + 遥控 `/api/input/tap`）+ 通知实时化+屏幕增量帧（agent-234）。
- **M2.80-83 已落地**：M3 导航栈+M5 通知跳转（M2.80）、媒体会话+Now Playing（M2.81）、SDK nav/media 封装（M2.82）、字库启动竞态修复（M2.83）。
- 既有 `meow_btn/slider/switch/list_create` 签名一字不改（向后兼容），Options/状态机走新增挂载器。

### 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`。
  - **M2.73 悬垂指针修复（md5 `da6ebc66`）**：`scan_and_reconcile` 用 `*s=tmp` 整体拷贝后 `s->argv[]` 曾指向已销毁栈帧 → `execv`/`/proc/pid/cmdline` 错乱；新增 `svc_rebuild_argv` 重定位到服务自身 `exec`/`argbuf`（删除服务后同 tick 拉起不再错位）。
- **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`。
  - **M2.78 竞态修复**：无可用 IPv4 不再 `exit(2)`（改内部 2s 等待重试，SIGTERM 可打断）；5s 周期检测掉线/换 IP → 重新 join 组播 + A 记录实时刷新（修 IP 变更还带旧地址）；接口 down 时零应答守卫；`MEOW_MDNS_IF` 落地。
  - 注：手机热点会丢弃设备→主机的组播应答，`avahi-resolve meowos.local` 在上网热点下会超时（网络层热点隔离，非应答器缺陷），主机可用 DNS 兜底。
- **meow_crash（系统级崩溃捕获）**：svcd 服务异常退出上报（AF_UNIX best-effort，不崩 svcd）+ dmesg 增量扫 segfault/oops；落盘 TF `MeowOS/logs/crash_<bootts>.log`（无卡回退 /tmp + 迁移）；CLI `dump`/`tail`；`S89` 预置 `crash.conf`。launcher 另在 `launch_app` waitpid 回收处 **notify_app_crash**（信号杀/非0退出上报，干净 exit 不报）。
- **meow_verify / meow_sign（包签名，二期 2A 最小闭环）**：`meow_verify`（Ed25519 验签 CLI，公钥固化固件，TweetNaCl+SHA256 单文件）；`meow_sign`（宿主 keygen/sign，尾部 180B footer 签名块，私钥仅 `.keys/` 不入库）；nyai 与 launcher `meow_pkg_install` **验签分级**（有签必验 / `os.meow.*` 无签拒装 / 第三方直装告警 / 三重绑定 / 原签存 `.mpk.src` 导出保留）；svc_power IPC 鉴权（SO_PEERCRED→/proc/pid/exe→包名/系统身份 allowlist）。

### 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`。
- **App 前台唤起通知中心（§10.5，M2.82 落地）**：全屏 App 前台时顶部下滑，**App 进程只负责检测手势 + 经 IPC 上报**（`MSG_NOTIF_OPEN=0x28`），launcher **SIGSTOP App → 读回帧 → 叠加渲染通知中心 → 接管输入 → SIGCONT App**（面板内 App 崩溃即关）；`MSG_NOTIF_CLOSE=0x29` 收尾。App 进程不渲染系统 UI。
- **媒体卡片 / Now Playing（M2.81 落地）**：通知中心顶部**媒体卡片**（封面缓存 + 进度 seek + 控制键）；主界面中部/右缘左滑进 **Now Playing 大页**（封面 + 元数据 + 进度 + 控制 + 歌词占位），左缘返回；空态完备。
- **通知查询/清除 IPC（0x25-27）**：`MSG_NOTIFY_QUERY(0x25)`/`MSG_NOTIFY_QUERY_RESULT(0x27)`（活跃通知集 JSON）/`MSG_NOTIFY_DISMISS_ALL(0x26)`（保留媒体/进度/常驻红线）；序列化在主循环单写者做；MeowPanel `/api/notifications` 实时化前置。

### 2.7 字体系统

- 多字体库在 TF 卡 **`MeowOS/fonts/<family>/<weight>/<tier>/`**（**三级目录，M2.78 落地，两级向后兼容**；每套三件套：`font.png` + `font.idx` + `font.json`），由 `font/gen/gen_font.py` 生成（`--weight` 写字重、`--tier` 档位、`--json-name`）。
- **思源黑体 `source_han_sans_cn` 7 字重 10 套已入卡**（common + regular/medium/bold gbk 等）。
- 字体列表索引 **`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`；缺失件 → 该套跳过 + 日志。
- **M2.83 启动竞态修复**：卡就绪（热插拔轮询）后**重扫字库 presets**（开机早扫时卡未挂载只剩默认项，App 大字库声明落空→豆腐块）；扫描根目录不可读且仅默认项时不写 index（防开机覆盖掉卡上既有索引）。
- 字库档位：默认用小字库（`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.*` 等。

### 2.9 系统框架 / 专项服务

把**系统复用功能收敛到系统框架**（`devdocs/plan/SYSTEM_FRAMEWORK_SERVICES.md`，一期已落地）：meow_sysui 派生 → meow_svcd 托管 → IPC。新增两个 **svcd 托管、板载 `trigger=boot`** 的专项子服务：

- **`meow_svc_perf`**（性能 / 系统只读聚合，IPC `/usr/data/meow_perf.sock`，`MSG_PERF_QUERY(0x0050)→MSG_PERF_RESULT(0x0051)`）；**`meow_svc_power`**（关机 / 重启 / 升级 / 回 HiBy 系统动作，IPC `/usr/data/meow_power.sock`，`MSG_POWER_ACTION(0x0060)→MSG_POWER_STATUS(0x0061)`，服务端 `SO_PEERCRED uid==0` 基础鉴权）。**M2.73 已落地**：`meow_svc_perf` 增 **network** 子集（真实 WiFi `wpa_cli`/`ip` + 蓝牙 `hci0`/sysfs + `hostname_local`），并入 SYSTEM 子集输出；`meow_svc_power` **升级写保护**（`upgrade` 写 mtd5 前校验卡根 `r3proii.upt` 存在+可读+常规文件+size>0，失败不写 mtd5/不重启——**只完整性、不签名**，海贝官方固件无签名，签名会挡自刷）与 **`dac status` 读板载 `settings.conf` 的 `audio.volume` 真实值**（弃 amixer dummy）。**M2.78 读级鉴权放宽（agent-189）**：`STATUS`/`BATTERY`/`REBOOT_REASON`/`UPGRADE_STATUS`/`dac status` 读级不再查 uid（任意调用者）；动作级维持 `os.meow.*`/系统身份白名单。**M2.88 签名鉴权 2B（agent-221）**：svc_power 面板身份精确路径绑定（删启发式）。当前 md5：perf `7ea196de`、power `306df962`。
- **电源 CLI `meow_svc_power <cmd>`**（root 免鉴权、单一命令、**不覆盖**系统 shutdown/reboot）：`shutdown` / `reboot[--hiby]`（强制回 MeowOS）/ `upgrade`（写 mtd5，含升级写保护）/ `set-default-meow` / `set-default-hiby` + `status` / `battery` / `reboot-reason` / `upgrade-status` / `screen on|off|timeout<秒>` / `dac on|off|status`。
- launcher 电源菜单与 MeowPanel 均**改为经这些服务 IPC 触发**，不再直连 `sys_do_reboot` / 爬 `/proc`。
- **二期望签鉴权已落地（agent-185 2A / agent-221 2B）**：关键 IPC 只接受 `os.meow.*` 鉴权 + `.mpk` 打包签名验签（防伪造包名，解包验签 / 导出保留签名）；`meow_verify` 多公钥数组 + v2 签名块（含 ts，兼容 v1）+ svc_power 面板身份精确路径绑定（删启发式）。
- **开机默认**：权威标记 `/data/meow_boot_default`（单值 O_TRUNC：`0`=MeowOS / `1`=HiByOS）。

### 2.10 MeowPanel（外部管理面板）

- **定位/部署**：**外置 TF 卡系统组件**（`MeowOS/opt/MeowPanel/` + `MeowOS/services.d/meowpanel.conf`，svcd 托管、无卡跳过、系统核心不依赖），**不进固件**。
- **后端**：`patch_v2/meowpanel/meowpanel.c` 单进程零第三方依赖 C 静态二进制，内嵌 HTTP/JSON 服务器（8080）+ 静态托管（`/`→index.html、`/assets/*`）+ 框架专项服务 IPC 客户端 + `settings.conf` 设置镜像。**读侧透传** `meow_svc_perf` IPC（`/api/{status,perf,system}`，单一权威源，不各自爬 /proc）、**动作侧**经 `meow_svc_power` IPC（`/api/system/{reboot,shutdown,ota}`）。
- **能力**：设置镜像（`settings.conf` 解析 `key = value` 带空格 + 精确匹配，防 `audio.volume` 误配 `audio.volume_max`）、文件管理（白名单 `MeowOS/Music/MeowData/MeowAPPs/book`，`..` 逃逸→403；**目录优先+名称不区分大小写排序、条目上限 1024**；上传 8MB 上限、文件名净化、双重白名单、`read>1MB` 截断）、**通知中心后端**（`/api/notifications` 读 TF 归档环形 200 条 + 单删 + dismiss_all）、应用（`nyai install/export/remove`，包名=`app.json.package`；`nyai` 路径固件内置 `/usr/bin/nyai` 优先+卡上回退）、按键注入（`/dev/input/event*` evdev，只注入音量/电源/播放/上下曲，**禁返回(158)/主页(172)/确认(28)/退出(96)**）、日志（`MeowOS/logs`）。
- **OTA 检查升级 bug 已修**：改读 `GET /api/system` 返回的 `ota` 字段，不再误触 `POST /api/system/ota` 触发升级。
- **M2.78 可选密码鉴权（agent-196，默认关）**：`panel.auth_enabled`(默认0) + `panel.auth_pass`(带盐 sha256 不明文)；token 会话（`/dev/urandom`，TTL 12h，内存+卡持久化，静态屏蔽 session 文件）；未启用零回归，启用后 `/api/*` 全要会话；前端登录页 + 401 回跳 + 设置卡片。
- **⚠️ 鉴权默认关**：内网信任模型（`reboot/shutdown/ota/apps/删除/上传` 等危险端点默认无鉴权，**勿把 8080 暴露到不可信网络**）；`meow_svc_power` 服务端做 `SO_PEERCRED uid==0` 基础校验。
- **前端**：`patch_v2/meowpanel/web/`（MD3/MIUIx 双主题 + 宝塔式 + 浏览日夜）；`/usr/bin/nyai` 装 `.mpk`；launcher 的 `meow_pkg_export` / `nyai export` 导出 tar.gz（busybox tar + gzip，不需 zip）。详见 `patch_v2/meowpanel/README.md`。

---

## 3. 目录结构

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

- **`patch_v2/`（入库）**—— MeowOS 核心源码：
  - `bootmenu/`   引导选单 + Supervisor（`meow_bootmenu`，`LAUNCHER_BIN=/usr/bin/meow_launcherd`）
  - `meow_launcherd/`  launcher（系统 UI 宿主，**多模块**：`main_menu/statusbar/settings_page/power_menu/notif_center/app_launcher/fb_compositor/audio/backlight/net/about/font_theme/keys/util` + `subpage/wifi_page/bt_page`（蓝牙/WiFi 子页）`now_playing`（Now Playing）`meow_media`（媒体会话）`meow_ipc`/`meow_settings`），+ `meow_launcher_internal.h` + `build_launcher.sh`
  - `sdk/`  meow_ui SDK 源码 + `build_sdk.sh`（→ `meow_ui.a`；含**统一控件库**：widget/theme/activity/global/dialog/ime/img/input/log/notify/sys/vol/view（视图框架）draw（绘制 z 序/注册表）nav/media（导航/媒体会话封装））
  - `hello_app/` 示例 App（`app.c` + `ui/{home,full,demo}.c` + `ui/common/chrome.c` + `logic/{notify,state}.c` + `build_hello.sh`）
  - `ncm_app/`  网易云客户端源码（`core/`：mbedtls 裁剪+jsmn+qrcodegen+minimp3；UI v1 + 复古配色；vendor/ 与 out/ gitignore 不入库）
  - `files_app/` 外置系统文件管理器 os.meow.files（app.c + ui/{browser,viewer}.c + ui/common/chrome.c + logic/fsx.c）
  - `meow_sysui/`  系统进程总监（`meow_sysui` + `S70meow_sysui` + `meow_sysui.md`）
  - `meow_svcd/`  服务管理器；`meow_watchdog/`  应用看门狗；`meowpkg/`  包管理（`nyai.c`）；`uinput_tap/`
  - `meow_crash/`  系统级崩溃捕获；`meow_verify/`  `.mpk` Ed25519 验签；`meow_sign/`  宿主签名工具；`meow_svc_perf/`、`meow_svc_power/`  专项子服务；`meowpanel/`  MeowPanel 外置面板后端 + `web/` 前端；`meow_amsd/`  amsd 活动管理器（一期 agent-212 + 二期路由决策/picker 契约 agent-225，设计见 `devdocs/plan/AMSD_DESIGN.md`）；`meow_route/`  音频输出路由自动随插孔（agent-220）
- **`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/` 的 `README.md`/`build_fw_apps.sh`/`fw_content.conf` 已 `git add -f` 入库）**—— 其余（`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` / `meow_sysui` / `nyai` + 相关 init 脚本 + `/etc/meowos_version`）。特点：

- 打包脚本 `scripts/build/build_fw_apps.sh` 是**配置驱动**的通用脚本（`-c fw_content.conf -v <ver> -o <out.upt> [-b <base>]`）：`fw_content.conf` 清单逐条 `src|dst|md5|desc`，**`.upt` 条目 md5 配置化**（`md5` 空=不校验，填了=构建前强校验源文件，不一致即中止）；**改固件内容只改 `fw_content.conf`，不动脚本**。历史逐版 `build_fw_apps_m2NN.sh` 已**删除**（每版复制一个、内部硬编码 md5、且共享 `fw_apps/` 互相清空）。工作区 `fw_apps/build/`（每次重建）与产物归档 `fw_apps/out/` 分离防互清。这些脚本/清单已 `git add -f` 入库（`scripts/build/` 根目录仍 gitignore），其余为**本地构建工具（gitignore 不入库）**——本仓库只提交源码与文档，需本地交叉工具链 + 官方固件基线 rootfs 才能复现。详见 `scripts/build/README.md`。
- **rootfs 上限 45,088,768 B（≈45MB）**；产物归档 `fw_apps/out/r3proii_m2NN.upt`。
- `/usr/bin` 各组件为静态 MIPS32r2；版本号以 `/etc/meowos_version` 为单点（`build_fw_apps.sh -v` 写入）。
- **`.upt` 容器 md5 不可复现**（repack 时间戳），以**内容级 0 diff 回验**为准。
- 外围 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/<package>/<ts>_<pid>.log`（**M2.78 日志目录扁平化**去 `apps/` 嵌套，卡可用时旧 `logs/apps/*` 一次性迁移并入；每次启动新文件，单文件 2MB 轮转、每 App 总量上限）。包管理 CLI `nyai`（固件内置 `/usr/bin/nyai`）：`nyai install <pkg>/<file.mpk>` 等。**`.mpk` = tar.gz**（app.json + 二进制 + 资源，不含 data/cache）；launcher 的 `meow_pkg_export` / `nyai export` 导出 tar.gz（busybox tar + gzip，不需 zip）；**二期签名验签已落地（agent-185）**：`meow_verify` 验签、`meow_sign` 宿主签名、有签必验 / `os.meow.*` 无签拒装 / 第三方直装告警（见 APPS.md）。

**TF 卡目录（关键）**
```
/usr/data/mnt/sd_0/
├── Music/                 # 音乐库
├── MeowData/<pkg>/{data,cache}
├── MeowAPPs/<pkg>/        # 应用（app.json + 二进制 + 资源）
└── MeowOS/
    ├── fonts/<family>/<weight>/<tier>/   # 多字体库（三级，M2.78）
    ├── config/fonts/index         # 字体列表索引（含三级条目）
    ├── notifications/             # 通知转储（10MB 滚动）
    ├── logs/<package>/            # 应用日志（扁平化）；crash_<bootts>.log 崩溃转储
    ├── services.d/<name>.conf     # 服务配置（TF 源，与板载双源）
    └── opt/                       # MeowPanel + 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",
  "version_code": 1,
  "author": "whoever"
}
```

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

其他扩展（launcher 极简解析、不校验 JSON）：`icon` / `framework`（导航栈承载）/ `immersive` / `route.<id>`（路由表，`framework=1` 时看门狗返回发 SIGUSR1）/ `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`；结构化列表 `W_LISTVIEW`（图标/标题/副标题/右侧操作、单选/多选/禁态、视口裁剪）；通用长按 `meow_ui_set_long_press_cb/ms`（`MEOW_EV_LONG_PRESS`）；`meow_ui_activity_push/pop`（Activity 栈，控件归属当前 Activity）、`meow_ui_global_add/remove`（② 层 App 跨 Activity 全局控件）；视图框架 `meow_view`（可嵌套容器 + 生命周期 + `page_push/pop/replace`）。
- **导航 / 媒体会话**：`meow_ui_nav`（env 栈初始化 + report/request_exit，接 M3 导航栈）、`meow_ui_media`（懒连断线重连，`MSG_META` 上报 + `MSG_PLAYCTL` 接收，接媒体会话）。
- **图片**：`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`。查询/清除走 launcher IPC（`MSG_NOTIFY_QUERY(0x25)`/`DISMISS_ALL(0x26)`/`QUERY_RESULT(0x27)`）；点击通知按 `route_status` 跳转。
- **日志**：`meow_log(lvl, fmt, ...)`（`MEOW_LOG_DEBUG/INFO/WARN/ERROR`）→ `MeowOS/logs/<package>/`（M2.78 扁平化）；App 崩溃直报 `meow_crash`（信号杀/非0退出 best-effort 上报）。

### 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 对齐）；§10 进程模型 / 系统 UI 归属 / 专项子服务 |
| `MEOW_APP_SDK.md` | SDK 设计：架构分层、绘制/控件/图片/输入/主题/字体/通知 API、三层控件模型、Activity 栈、动画与性能；**§5.8 控件层架构升级（统一控件/Options/状态机/布局 + Material 子集）、§8.1 主题增强（MD3/MIUIx × 明暗 + 背景源）** |
| `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 |
| `patch_v2/meow_sysui/meow_sysui.md` | 系统进程总监 meow_sysui：监管模型、`sysui.d/` 配置、与 bootmenu/svcd 的托管关系 |
| `patch_v2/meowpanel/README.md` | MeowPanel 外置面板后端：端点实现清单、IPC 对接、设置镜像、白名单、按键注入、**无鉴权风险** |
| `scripts/build/README.md` | 固件打包通用脚本用法：配置驱动、产物归档、踩坑记录 |
| `devdocs/plan/MEOWPANEL_PROTOCOL.md` | MeowPanel 外部管理面板协议（31 端点）（devdocs，gitignored） |
| `devdocs/plan/SYSTEM_FRAMEWORK_SERVICES.md` | 系统框架专项服务（perf/power + 电源 CLI + 二期 `os.meow.*` 鉴权 / .mpk 签名）（devdocs，gitignored） |

> 文档收敛规则：新功能在对应权威文档（`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 标记，写入 `ota:kernel2` 引导 kernel2 自动升级；`meow_svc_power upgrade` 走此）、mtd6=userdata。
- **安全红线**：不要远程 kill 常驻 `meow_launcherd`（整机重启）；`hiby_player` 只能 SIGSTOP/SIGCONT，严禁 killall / 对其发未注册信号（如 SIGUSR1 导致整机重启）/ 走 `hiby_player.sh`；严禁触碰 NAND / `recovery_all`；播放器不能「杀+重拉」（HGL 连续内存）。
- 本仓库为**非官方第三方项目**，修改并与官方固件共存；刷机有一定的变砖风险（可用官方固件刷回），请自行评估。所有「真机验证」项请以实机为准。