MeowOS for HiBy R3 Pro II

把 R3 Pro II（君正 X1600E，HiBy OS / Linux 4.4）打造成可扩展的"第二系统"：MeowOS 作为主控层，双系统互斥（引导选单），HibyOS 播放器由 MeowOS 托管，MeowAPPs / MeowPanel / Activity 框架持续扩展。

核心文档（先读这些）

总索引（单一来源）：docs/MEOWOS_SPEC_REF.md —— 各路径/接口/功能/约定的权威速查，含「已知矛盾/待确认」清单。

文档	内容
docs/MEOWOS_SPEC_REF.md	权威速查总索引（首选入口；常量/路径照抄原文 + 出处 + 矛盾清单）
devdocs/ANALYSIS.md	主技术档案（本地开发档，gitignore 不入库）：固件逆向、启动链、fb 双缓冲、HGL、一切踩坑与纪律（§ 章节持续累积）
DEVELOPMENT_PLAN.md	路线图与分阶段计划（自身已过时，以实际进度为准；阶段 0 双系统 / A 稳定化 / B 状态栏通知中心 / B2 系统设置 / C MeowPanel / D Activity 框架 / E 网易云）
FRAMEWORK_DESIGN.md	Activity / 通知 IPC 框架协议（IPC、路由表、导航栈、后台权限、媒体会话）
SYSTEM_SETTINGS.md	系统设置子系统设计（统一存储 + C API + 实体 UI + web 复用 + 导入导出）
MEOWOS_API.md	统一 API 蓝本（命名规范、返回码、设置 API、HTTP 映射、扩展指南）
APPS.md	MeowAPPs 应用规范（目录、app.json、生命周期、边界、日志、返回键）
GESTURE_BACK_DESIGN.md / KEY_CONTROL_DESIGN.md / PERF_SCHEDULER.md	左缘返回 / 按键契约与信号 / 帧率调度

一次性/阶段性设计文档（已过时或未实施）移至 devdocs/plan/ 归档（移动不删、保留历史；devdocs/ 为本地开发档，不入库）：BOOT_SELECTOR_DESIGN、CHARGING_SCREEN、MAIN_MD3_PLAN、MD3_UI_SPEC、MEOW_TOUCH_DESIGN、MIGRATION_AC、BLUETOOTH_MANAGER_PLAN、APP_LOG_MANAGER。

文档收敛规则：不再为每个功能新增设计 md；新功能在对应权威文档（MEOW_APP_SDK.md/APPS.md/SYSTEM_SETTINGS.md 等）补小节；新增决策/检查点写 devdocs/DEV_NOTES.md；过时一次性设计进 devdocs/plan/。

当前架构与组件（2026-08-30 快照）

• SDK 统一日志 + 通知（M2.52/53 已落地）：meow_log() 按 app 分目录、每次启动新文件 MeowOS/logs/apps/<app_id>/logs/<ts>_<pid>.log，单文件 2MB 轮转、每 App 总量 50MB 删最旧；通知 API meow_notify_*（4 类型×每类型 4、媒体单例）；#5 SDK↔IPC 桥（meow_notify_ipc.c/.h：app→launcher 中央存储，send/cancel 接入、回填 launcher nid，无 socket 降级不崩）。通知中心 UI / D-Bus 桥 / TF 转储为后续任务。
• TF 卡多字体库（M2.6 字重结构）：MeowOS/fonts/<family>/<weight>/（font.png+font.idx+font.json 三件套），默认 MeowOS/fonts/default/regular；font.file 设置键选默认套（family→字重两级子菜单）；SDK load_font 优先读 env MEOW_FONT_PNG/IDX（launcher 每次 launch_app 注入），app 未自带字库时跟随系统 font.file；≤16 套卡内（防爆）；§5.7 字体管理 + 应用字库（多句柄，草案未实现）。已部署 6 套（思源宋体 / MiSans / GoogleSans / Meslo / 思源黑体 / Ubuntu Mono，<family>/regular，位深 4）。
• 包名/目录安卓化：app.json package（反域名权威 app_id，==目录名，缺省回退目录名）→ 示例 os.meow.hello；目录 MeowAPPs/os.meow.hello；数据 MeowData/<pkg>/{data,cache}。
• meow_svcd 服务管理器（patch_v2/meow_svcd/，mipsel 静态 ~99KB，进固件不入卡）：类 systemd/systemctl，由 supervisor（bootmenu/launcher）fork/exec 托管；读 TF MeowOS/services.d/<name>.conf（目录式 key=value，未知键忽略/前向兼容）；服务=svcd 独立子进程（崩溃隔离：服务挂不影响 svcd/supervisor）；事件触发 boot/card-mount/wifi-up（1s 轮询）；-f 前台便于 supervisor waitpid；状态机 DISABLED/STOPPED/RUNNING/STOPPING/FAILED + CLI。接入 supervisor 启动链未做。
• mDNS 方案A（已拍板）：完整 mdnsd（994KB，mipsel 静态）放 TF MeowOS/opt/mdnsd/mdnsd，由 meow_svcd 托管（需 root/setcap cap_net_bind_service,cap_net_raw 绑 UDP5353+组播 224.0.0.251）；SAResponder（885KB）因"单服务注册型"无法按名访问设备（ingenic.local）被排除。⚠️ 手机热点组播常在客户端间丢失 → mDNS 有风险，主机 DNS 兜底。MeowOpt 已废弃并入 MeowOS/opt（二进制归 MeowOS/opt，拔卡降级不崩）。
• boot 默认→板载：/data/meow_boot_default（O_TRUNC 单值、不递增、权威）；bootmenu 读它定默认；meow.conf 不再承担 boot_default（其 O_APPEND 累积 bug 已修，设备已清）。
• 状态栏 40→28px：SDK MUI_SBAR_H=28（字号 20）+ launcher SB_BAR_H=28/SB_FONT=20；状态栏两条实现（SDK meow_ui_sys_statusbar_render / launcher draw_statusbar）待 MD3 收敛为单一 SDK 全局状态栏（launcher 退役 draw_statusbar 复用 SDK）。
• 键码/阈值修正：MEOW_KEY_PREVIOUS=165（19 是另一码，[A-6] 定案）；左缘返回阈值 65px（[A-4] 90vs65 定案 65）；亮度下限 1（[A-3]）；热键窗口下限 60ms（[A-1]）；日志路径统一 MeowOS/logs（[A-7]）。
• TF 卡资产：包管理 CLI nyai（部署 MeowOS/opt/bin/nyai，同 launcher 包语义）；应用日志 MeowOS/logs/apps/<id>/logs/<ts>_<pid>.log；服务定义 MeowOS/services.d/<name>.conf。
• mips-repo/（宿主侧 mipsel 软件仓库）：交叉编译产物 + build.sh + manifest.md，供后续固件/TF 复用（见「目录速览」）。
• 仓库公开净化：本地 main 单提交，HEAD 敏感 0 命中；devdocs/（本地开发文档 + WORK_STATE/DEV_NOTES）、scripts/build/（固件打包脚本）gitignore 不入库；mips-repo/（mipsel 软件仓库）入库。

目录速览

• patch_v2/ — meow_launcherd（MeowOS 核心）、bootmenu（引导选单）、watchdog、meow_svcd（服务管理器）、sdk（meow_ui SDK）、meowpkg（包管理）；源码与构建脚本
• mips-repo/ — mipsel 交叉编译软件仓库（mdnsd 等：README.md+bin/），供后续固件/TF 复用
• font/ — 预渲染字形系统（gen 生成器、meow_font 渲染库、atlas 产物）
• fw_apps/ — 固件组装产物（.upt 不入库，由 scripts/build/build_fw_apps*.sh 重新打包）
• bootlogos/ — 用户定制启动图/关机 logo
• scripts/build/ — 固件打包脚本 build_fw_apps_m*.sh（本地 gitignore 不入库）
• devdocs/ — 本地开发文档（ANALYSIS / WORK_STATE / DEV_NOTES / OPEN_QUESTIONS / FLASH_SSH / TEST_ON_DEVICE / device_test / plan 归档；gitignore 不入库）
• ssh_keys/, .tools/ — SSH 密钥、交叉工具链（不入库，按需）

构建/刷机

• 固件打包：scripts/build/build_fw_apps_m253.sh（现 M2.53 / 0.7.48；需交叉工具链 zig-mipsel-cc + musl.cc，见 devdocs/ANALYSIS.md 第 10 节）
• 升级锁根：SD 卡根 r3proii.upt（固件由 build_fw_apps*.sh 打包成 .upt 再刷）
• 刷机：failsafe（关机后按住 音量加+电源）从 SD 卡根 r3proii.upt 升级；勿用播放器 UI 卡死的升级按钮
• 组件归属：launcher / bootmenu / watchdog 为固件组件（/usr/bin，只读 squashfs）；/usr/data 下的同名文件仅 dev 手动 exec 快速下发，开机不用。真机验证字体/包名/通知须重打固件 + 刷机 + reboot。
• 回退：官方固件 / backups/（NAND 全量备份）重刷

关键纪律（红线）

• 严禁对 hiby_player 发未注册信号（SIGUSR1 导致整机重启）；不 killall；禁经 hiby_player.sh
• 勿远程 kill meow_launcherd（整机重启）
• 播放器不能"杀+重拉"（HGL 连续内存）；双系统互斥，MeowOS→HibyOS 只能重启
• 日志/字库/媒体等大数据只写 TF 卡；板载只写 KB 级 meow/settings.conf
• 绝对不对挂载点 rm -rf

详见 devdocs/ANALYSIS.md 纪律章节。