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.71（0.7.66）（版本号单点 = 板上 /etc/meowos_version，见「构建」）。

许可证：Apache-2.0（见 LICENSE）。本仓库为非官方第三方项目。

---

1. 项目简介

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

• 双系统共存：官方 HibyOS 原样保留；开机引导选单决定本次进入哪个系统（MeowOS / HibyOS），两者互斥运行，任一时刻只跑一个。
• 应用框架：一套 C 应用 SDK（meow_ui），第三方 App 用统一控件 / 输入 / 主题 / 字体 / 通知 API 开发，无需自读帧缓冲、自读输入、自管返回——把每个 App 都要踩一遍的坑收口到框架里。
• 系统组件：状态栏、通知中心、电源菜单、全局左缘返回手势、主界面（应用列表）、设置页、服务管理器、mDNS 广播；系统进程总监 meow_sysui（M2.71）；专项子服务 meow_svc_perf / meow_svc_power（一期在跑）；MeowPanel 外部管理面板。
• 进程隔离：系统 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/S70meow_sysui     系统进程总监（meow_sysui，S70，M2.71 引入；监管 svcd，launcher 由 bootmenu 拥有）
 ├─ /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（launcher 仍由 bootmenu 的 execv 拥有，enabled=0 防双重拉起，移交见后端让位）；meow_mdns 是 svcd 的服务子进程（不双重管理）。配置 sysui.d/ 目录式（复用 services.d 语义），见 patch_v2/meow_sysui/meow_sysui.md 与 docs/MEOWOS_SPEC_REF.md §4。
• 专项子服务（一期在跑，规划见 devdocs/plan/SYSTEM_FRAMEWORK_SERVICES.md）：新增两个 svcd 托管、板载 trigger=boot 的专项子服务——meow_svc_perf（性能 / 系统只读聚合）、meow_svc_power（关机 / 重启 / 升级 / 回 HiBy 系统动作）。launcher 电源菜单与 MeowPanel 改经这些服务 IPC 触发，不再直连 sys_do_reboot/爬 /proc。电源 CLI meow_svc_power <cmd>（root 免鉴权、单一命令、不覆盖系统 shutdown/reboot）。二期补关键 IPC 只接受 os.meow.* 鉴权 + .mpk 打包签名验签。
• 隔离保证（现已落地）：系统组件各自独立进程；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/，14 模块：main_menu/statusbar/settings_page/power_menu/notif_center/app_launcher/fb_compositor/audio/backlight/net/about/font_theme/keys/util + 共享头 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。
• 既有 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。
• 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.* 等。

2.9 系统框架 / 专项服务

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

• meow_svc_perf（性能 / 系统只读聚合）；meow_svc_power（关机 / 重启 / 升级 / 回 HiBy 系统动作）。
• 电源 CLI meow_svc_power <cmd>（root 免鉴权、单一命令、不覆盖系统 shutdown/reboot）：shutdown / reboot（强制回 MeowOS）/ upgrade（写 mtd5）/ set-default-hiby / reboot --hiby + status / screen / dac / battery / reboot-reason / upgrade-status。
• launcher 电源菜单与 MeowPanel 均改为经这些服务 IPC 触发，不再直连 sys_do_reboot / 爬 /proc。
• 二期：关键 IPC 只接受 os.meow.* 鉴权 + .mpk 打包签名验签（防伪造包名，解包验签 / 导出保留签名）。
• 开机默认：权威标记 /data/meow_boot_default（单值 O_TRUNC：0=MeowOS / 1=HiByOS）。

2.10 MeowPanel（外部管理面板）

• 协议：devdocs/plan/MEOWPANEL_PROTOCOL.md（31 端点）。
• 前端：patch_v2/meowpanel/web/（MD3/MIUIx 双主题 + 宝塔式 + 浏览日夜）。
• 外置部署：MeowOS/opt/MeowPanel/ + services.d 经 svcd + sysui 管理，无卡依赖最小化；/usr/bin/nyai 装 .mpk；launcher 的 meow_pkg_export / nyai export 导出 tar.gz（busybox tar + gzip，不需 zip）。

---

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 + meow_launcher_internal.h + build_launcher.sh）、meow_ipc、meow_settings、meow_font、meow_notif、meow_card_path.sh
  • sdk/ meow_ui SDK 源码 + build_sdk.sh（→ meow_ui.a；含统一控件库：widget/theme/activity/global/dialog/ime/img/input/log/notify/sys/vol）
  • hello_app/ 示例 App（hello.c + build_hello.sh）
  • meow_sysui/ 系统进程总监（meow_sysui + S70meow_sysui + meow_sysui.md）
  • meow_svcd/ 服务管理器；meow_watchdog/ 应用看门狗；meowpkg/ 包管理（nyai.c）；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（入库脚本）

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（入库脚本）

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 空=不校验，填了=构建前强校验源文件，不一致即中止）。历史逐版 build_fw_apps_m2NN.sh 保留（本地，方便对照/回退）。这些是本地构建工具（gitignore 不入库）——本仓库只提交源码与文档，需本地交叉工具链 + 官方固件基线 rootfs 才能复现。
• rootfs 上限 45,088,768 B（≈45MB）；产物 fw_apps/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/apps/<package>/logs/<ts>_<pid>.log（每次启动新文件，单文件 2MB 轮转、每 App 总量上限）。包管理 CLI nyai（放 MeowOS/opt/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）；二期加打包签名验签（见 APPS.md）。

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

{
  "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"

其他扩展（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 对齐）；§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 的托管关系
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 连续内存）。
• 本仓库为非官方第三方项目，修改并与官方固件共存；刷机有一定的变砖风险（可用官方固件刷回），请自行评估。所有「真机验证」项请以实机为准。