MeowOS for HiBy R3 Pro II

把 HiBy R3 Pro II 便携播放器（君正 X1600，MIPS32r2 / mipsel / musl 静态软浮点，480×720，无 GPU 软渲染）变成一个可扩展的「第二系统 + 应用框架」。 MeowOS 与官方 HibyOS 共存于同一台设备：开机由引导选单二选一；启动后 MeowOS 作为主控层，提供自己的桌面 UI、应用框架、服务管理与系统组件。

版本：M6.0（0.8.0，已自刷验收）（M6.1 备料全齐——netmgrd 期3/powermgr 期2/面板 PIN 鉴权+首页仪表盘/WiFi 录入 UI/服务名统一 meow_，待打包自刷；历史：M2.69→M2.96 全链路自刷验收：控件库/主界面 MD3 双布局/M3 导航栈/M5 通知跳转/媒体会话/Now Playing/SDK nav+media 封装/字库启动竞态修复**/M2.84-88**：installed 图标修复+残帧pan加固/物理键EVIOCGKEY双源/签名鉴权 2B/meow_route 音频路由/amsd 二期(picker 契约)/流媒体客户端二期(封面·歌词后台·大歌单分页)/MeowPanel 实时画面+遥控+通知实时化/中文拼音 IME**/M2.89**：开机选单抢屏回归修复+watchdog SIGUSR1 不误杀框架 App+amsd 失联修复+顶部下滑手势分流**/M2.90**：meow_audiod 独占音频守护（AUDIOD_DESIGN，meow_route 并入退役）+MIUIx 顶级主题+流媒体客户端文案中文化+面板字体库 tar.gz 导入导出**/M2.91-96**：audiod 开机武装 hbc3000 FPGA（根治 PCM 启动内核死锁）+svc_power 充电态权威链(mp2731)+amsd 注册自愈（am rescan）/Now Playing 死循环修复+状态栏充电闪电+插孔消抖（三路）/audiod 长流护栏+ALSA 几何收窄 period=1024×4（根治长流停摆）+watchdog 音量存盘毁设置修复/音量反转四路统一（CS43198 寄存器=衰减量，dac=255-pct*255/100）+炸耳安全修复（dac_vol_mute 写 255 真静音）；M6.0-6.1：网络管理服务 meow_netmgrd 期1-3（接口统一层+连接普查三实体+DNS 代理+策略引擎防自锁+WiFi 录入 UI）+功耗管理服务 meow_powermgr 期0-2（查看/功耗分解 top/历史/事件/mp2731 实测充电功率）+MeowPanel 增强（4 位 PIN 鉴权+首页仪表盘/电源页/进程服务页）+服务名统一 meow_（audiod/mdnsd→meow_audiod/meow_mdns））。版本号单点 = 板上 /etc/meowos_version，见「构建」。本仓库是一个自带 SDK、包管理、媒体会话、独占音频服务、网页面板、流媒体客户端的完整第三方系统。

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

公开 SDK 仓（面向第三方开发者）：ssh://git@git.yeij.top:2222/AskaEth/MeowOS-SDK.git（MIT；只含 sdk/（meow_ui）+ examples/hello/ + docs/，自包含可构建，不含系统组件/密钥）。由本仓经 git subtree split 拆出，增量同步见 scripts/publish_sdk.sh。

---

1. 项目简介

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

• 双系统共存：官方 HibyOS 原样保留；开机引导选单决定本次进入哪个系统（MeowOS / HibyOS），两者互斥运行，任一时刻只跑一个。
• 应用框架：一套 C 应用 SDK（meow_ui），第三方 App 用统一控件 / 输入 / 主题 / 字体 / 通知 API 开发，无需自读帧缓冲、自读输入、自管返回——把每个 App 都要踩一遍的坑收口到框架里。
• 系统组件：状态栏、通知中心、电源菜单、全局左缘返回手势、主界面（应用列表，MD3/MIUIx 顶级主题×明暗，卡片宫格/列表双布局）、设置页、服务管理器、mDNS 广播；系统进程总监 meow_sysui；专项子服务 meow_svc_perf（性能/系统只读聚合，含真实 network）与 meow_svc_power（关机/重启/升级/回 HiBy，含升级写保护 + dac 真实音量 + 读级鉴权放宽）；独占音频守护 meow_audiod（M2.90：App 经 SDK meow_audio_* 喂 PCM，守护独占 hw:0,0——DAC 原生率跟随无 SRC、格式归一、4.4/3.5 路由自动跟随插孔、抢占+EOF 回收、CLI status/tone/route/vol，规范 devdocs/plan/AUDIOD_DESIGN.md）；系统级崩溃捕获 meow_crash + App 崩溃直报；.mpk Ed25519 签名验签 meow_verify（见 §2.9）；网络管理服务 meow_netmgrd（M6.0 期1 / M6.1 期3：接口统一层/连接普查三实体/DNS 代理/策略引擎防自锁，HibyOS 只读）与功耗管理服务 meow_powermgr（M6.0 期1 / M6.1 期2：功耗查看/分解/历史/事件，HibyOS 只读）；MeowPanel 外部管理面板（HTTP/JSON 后端 + Web 前端，支持可选密码鉴权 + 4 位 PIN 访问级鉴权 + 首页仪表盘 + 字体库 tar.gz 导入导出，见 §2.10）。
• 媒体会话 / Now Playing：MSG_META/MSG_PLAYCTL（0x72/0x73）媒体会话（最近活跃源，30s 超时回收）+ 通知中心媒体卡片 + 主界面左滑 Now Playing 大页；媒体键路由到最近活跃媒体会话。
• 应用生态：流媒体客户端 dev.player.ncm（core/：mbedtls+jsmn+qrcodegen+minimp3 ≈438KB；复古 UI：登录二维码/我创建的·我收藏的双页签/搜索/歌单详情/黑胶播放页/设置，登录 803 已通；二期：专辑封面/歌词后台加载/大歌单分页；三期：歌单真分页/真实专辑封面/歌词锁修复/搜索接拼音 IME 中文搜索/设置页（音质 5 档+缓存上限+清理缓存）/缓存 LRU 淘汰接生产路径/文案全中文；三期续：歌曲对象瘦身 1324B→608B+256 首滑动窗口（任意长度歌单）/封面与缓冲 UX 修复（消除 worker 忙等 100% CPU）/FLAC 无损（dr_flac）+缓存键=歌曲 ID+音质档位/物理播放键 toggle 全链路）。A2 起音频输出走 meow_audiod（SINK_AUDIOD 默认后端，SDK meow_audio_* 客户端，被抢占回调→暂停；旧 ALSA 直开仅 MEOW_AUDIO_DIRECT=1 调试）；外置系统文件管理器 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_audiod  独占音频守护（M2.90，含路由/格式归一；HibyOS 模式不启动）
 │    ├─ 专项子服务 = meow_svc_perf / meow_svc_power
 │    ├─ meow_netmgrd  网络管理服务（M6.0 期1 / M6.1 期3：接口统一层+连接普查三实体+DNS 代理+策略引擎；HibyOS 只读）
 │    └─ meow_powermgr  功耗管理服务（M6.0 期1 / M6.1 期2：功耗查看/分解 top/历史/事件；HibyOS 只读）
 └─ /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 降序子>父命中即消费 + 绘制期通用 clipg_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.89/90 新增：开机选单抢屏回归修复（sysui S70 早拉 launcher 误入主屏→改怠速等 mode 文件，HibyOS 选单/热键链路恢复）；watchdog SIGUSR1 仅裸沉浸 App + SDK sigusr1 护栏（修框架 App 误杀）；amsd 失联三修（陈旧 revents 丢连接/收发超时/自动重连）；MIUIx 顶级主题（ui.style 一键切换，暖底橙调大圆角）；meow_audiod 独占音频守护（A1 全量，含 SDK 客户端与 meow_audio CLI；meow_route 并入退役）；MeowPanel 字体库 tar.gz 导入/导出 + 文件管理自然排序；流媒体客户端：搜索接拼音 IME、设置页（音质/缓存上限/清理缓存）、缓存 LRU 淘汰接线、文案全中文。
• M2.91-96 新增：audiod 开机武装 hbc3000 FPGA（路由线程启动无条件写 Output Port Switch，根治「未烧 FPGA 时 PCM 第二次 start 内核死锁」）；svc_power 充电态权威链（mp2731-charger/status，修 battery/status 恒 Discharging）+ 状态栏充电闪电图标；amsd 注册自愈（开机早于卡挂载扫空→3s 快重试+30s 合并重扫+am rescan）；Now Playing 死循环修复（空态 100% CPU/卡死）+ NP 页电源键/自动息屏；插孔消抖（4.4/3.5 插拔 ADC 幽灵音量键：launcher/watchdog/SDK 三路 800ms 消抖窗 + ramp 3s 上限）；audiod 长流护栏 + 几何收窄 period=1024×4（根治长流 ~12s 停摆：ring 有界等待/timedwait/popen 有界收割/O_NONBLOCK+poll 写/wedge 自救/心跳 watchdog）；watchdog wd_vol_save O_TRUNC 毁 settings.conf 修复（读改写单键+去重）；音量反转四路统一（CS43198 音量寄存器=衰减量：0 最响/255 静音，launcher/audiod/watchdog/SDK 统一 dac=255-pct*255/100）；炸耳安全修复（dac_vol_mute 旧写 0=最大响度 → 改 255 真静音）；SDK 插孔消抖补齐（meow_ui.a 12cdd5d7）+ 物理播放/暂停键（164) 改发 PLAYCTL cmd=6 toggle + App 前台状态栏音量%实时刷新。
• M6.0-6.1 新增：网络管理服务 meow_netmgrd（期1 接口统一层 WiFi/BT/rfkill/IP/DNS 只读 + 期2 连接普查三实体(app:/svc:/proc:)+DNS 代理 127.0.0.1:53 双行 resolv 零断流 + 期3 策略引擎防自锁（dropbear/wpa_supplicant/udhcpc 等拒 block）/SOCK_DESTROY 真机 no-op→仅 DNS 层生效/面板白名单/WiFi save_config；CLI meow_net，M6.0 期1/M6.1 期3，设计见 devdocs/plan/NETMGR_DESIGN.md）；功耗管理服务 meow_powermgr（期0 调研 current_now/cpufreq 不存在/背光 0-101 + 期1 权威充电链复用/经验模型 14 系数 + 期2 history 30s 环形/top 功耗分解/events/mp2731 current_now 实测充电功率（放电仍 estimated）；CLI meow_power，M6.0 期1/M6.1 期2，设计见 devdocs/plan/POWER_MANAGER_DESIGN.md）；设置页迁 netmgr IPC + WiFi 新网络录入 UI（扫 SSID→IME 输密码→connect，286）；服务名统一 meow_*（S89 迁移 audiod.conf/mdnsd.conf→meow_audiod.conf/meow_mdns.conf，用户定案 cd4e2c2）；MeowPanel 增强（4 位 PIN 访问级鉴权 + 首页仪表盘 /api/overview + 电源/进程服务页 + 系统页补强，PANEL_ENHANCE_PLAN 批1）。
• 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/meow_mdns.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）。
• meow_netmgrd（网络管理服务，M6.0 期1 / M6.1 期3）：/usr/bin/meow_netmgrd（svcd 托管板载 services.d/meow_netmgrd.conf，trigger=boot；HibyOS 只读降级，RSS ≤1MB）。接口统一层（iface 枚举+热插拔 / WiFi wpa_cli 有界收割 / BT hciconfig+bluetoothctl / rfkill / IP 路由 DNS 只读 / udhcpc 续租释放仅 MeowOS）；连接普查（2s /proc/net/{tcp,udp}，inode→pid→三实体 app:<包名>/svc:<服务名>/proc:<comm> 归因）；DNS 代理（127.0.0.1:53，双行 resolv.conf+atexit 恢复+5s 自检，崩溃零断流）；策略引擎（/data/meow/netmgrd/net_policy.conf，防自锁双层：dropbear/wpa_supplicant/udhcpc/netmgrd/svcd/sysui/init 拒 block+加载校验强制复位；SOCK_DESTROY 真机 no-op（内核 4.4 接受不销毁）→ 仅 DNS 层生效，meow_net policy show 明示 enforce=dns_only）。双形态 CLI meow_net（status/iface/wifi/bt/rfkill/apps/conns/top/dns/policy/help）。设计见 devdocs/plan/NETMGR_DESIGN.md。
• meow_powermgr（功耗管理服务，M6.0 期1 / M6.1 期2）：/usr/bin/meow_powermgr（svcd 托管板载 services.d/meow_powermgr.conf，trigger=boot；HibyOS 只读降级）。期0 事实：battery/current_now/cpufreq 不存在→实时功率只能 derived+estimated 双轨、背光量程 0-101（非 255）、mp2731 有 current_now（充电功率可测）、rfkill×4、无 thermal。期1：权威充电态链复用 + 经验模型 14 系数（/data/meow/powermgr/power_model.conf）。期2：history（30s 环形 4h 不落盘）+top（功耗分解）+events（充放电/低电/亮灭屏/背光跳变）+模型细化（WiFi 未关联档/BT rfkill·ACL 档）+ mp2731 current_now 实测充电功率（charge_confidence=measured，放电仍 estimated）。双形态 CLI meow_power（status/estimate/model/history/top/events）。设计见 devdocs/plan/POWER_MANAGER_DESIGN.md。

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 的专项子服务（perf/power 一期；netmgrd/powermgr 二期——网络管理/功耗管理，见 §2.5 服务清单）：

• 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 回跳 + 设置卡片。面板增强（PANEL_ENHANCE_PLAN 批1，2026-09-01 用户定案）：4 位 PIN 访问级鉴权（面板访问即需登录，与未来锁屏同源 system.pin 预留，未设 PIN 首访引导设置、未设前写端点拒绝；token 会话 3 天或重启失效，进程内存）；前端五页：首页仪表盘（/api/overview 聚合）+ 音频电平（rms/peak 只读）+ 电源页只读 + 进程/服务页（svcd/amsd）+ 系统页补强 + 网络健壮性 + PIN 卡；后端只读端点 power/overview/ams/svcd + audio 电平键；音量 clamp vol_max+锥度提示 / 防自锁禁停 / 确认弹窗三红线。详见 devdocs/plan/PANEL_ENHANCE_PLAN.md。
• ⚠️ 鉴权默认关：内网信任模型（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/ 流媒体客户端源码（dev.player.ncm；core/：mbedtls 裁剪+jsmn+qrcodegen+minimp3+dr_flac；UI 复古配色；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/、meow_netmgrd/、meow_powermgr/ 专项子服务（性能/电源动作/网络管理/功耗管理）；meowpanel/ MeowPanel 外置面板后端 + web/ 前端；meow_amsd/ amsd 活动管理器（一期 agent-212 + 二期路由决策/picker 契约 agent-225，设计见 devdocs/plan/AMSD_DESIGN.md）；meow_audiod/ 独占音频守护 + meow_audio CLI（M2.90，规范见 devdocs/plan/AUDIOD_DESIGN.md；meow_route/ 已并入退役，源码保留归档）；tools/ 诊断小工具（sndprobe/tonepcm 等）
• 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（入库脚本）

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 空=不校验，填了=构建前强校验源文件，不一致即中止）；改固件内容只改 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

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

其他扩展（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 × 明暗 + 背景源）
docs/APP_DEV_GUIDE.md	面向第三方开发者的上手指南：环境→最小 App→工程结构→构建打包→签名安装→部署调试→SDK 能力速查→红线→FAQ
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 连续内存）。
• 本仓库为非官方第三方项目，修改并与官方固件共存；刷机有一定的变砖风险（可用官方固件刷回），请自行评估。所有「真机验证」项请以实机为准。