389 lines
65 KiB
Markdown
389 lines
65 KiB
Markdown
# MeowOS for HiBy R3 Pro II
|
||
|
||
> 把 HiBy R3 Pro II 便携播放器（君正 X1600，MIPS32r2 / mipsel / musl 静态软浮点，480×720，无 GPU 软渲染）变成一个可扩展的「第二系统 + 应用框架」。
|
||
> MeowOS 与官方 HibyOS 共存于同一台设备：开机由引导选单二选一；启动后 MeowOS 作为主控层，提供自己的桌面 UI、应用框架、服务管理与系统组件。
|
||
>
|
||
> 版本：**M6.32（0.8.32，已自刷验收）**。M6.19→M6.32 连续十三版推卡自刷验收——**M6.19**：ncm 后台化 UI 叠层/点击穿透+再进 ncm 桌面叠层+播放页新旧 UI 叠层抢刷脏区（软自抑帧移交不完整，恢复边沿强制整帧重画）+PIN 亮屏亮度跳+通知中心封面显歌单封面；**M6.20**：播放页右滑返回+顶部下滑通知中心+状态栏时钟 1s；**M6.21-22**：播放页返回修复（`np_exit` 退出外层主循环）+方向感知手势；**M6.23**：watchdog 亮屏亮度按用户设置恢复；**M6.24**：App 内按电源键锁屏时序；**M6.25**：bootmenu 开机菜单亮度方案 A；**M6.26**：播放页三键命中+媒体卡片体 FOCUS；**M6.27**：netmgrd 流量统计收编（pub_bytes/去 lo）+面板公网流量卡；**M6.28**：收编桌面 Now Playing 双页歌词页+歌词数据源+蓝牙 P1（netmgrd BT_CTL/bt_page）；**M6.29**：播放页任意右滑返回桌面；**M6.30**：收编批5 取色+蓝牙 P2（audiod glibc-dynamic）+面板蓝牙卡；**M6.31**：桌面歌词页封面修复+alsa.conf DEV 自动识别；**M6.32**：重编 meow_ui.a+重链四 App（播放页进度条取色+ncm 列表 gap）+面板透传。M6.10→M6.18：M7 launcher 重写第 1-5 期（M6.10-14：虚拟化宫格/设置页卡顿修复/OOM 通用化/自动切歌根治）+（M6.15）meowpanel jv_free 泄漏修复+（M6.16）Hello demo 滚动卡顿修复+（M6.17）歌词 UI+（M6.18）媒体通知封面+封面分辨率。M6.1→M6.9 全链自刷验收——**M6.1**：netmgrd 期3/powermgr 期2/面板 PIN 鉴权+首页仪表盘/WiFi 录入 UI/服务名统一 meow_*；**M6.2**：锁屏 PIN 全量（`system.pin` 同源面板）+VOL_DOWN×3 框架门控+显示名 name[49]（amsd/launcher UTF-8 整序列截断）；**M6.3**：设置页 5s 修复（309 网络异步步骤机+跳过字体 sha 校验）+310 锁屏三连（输入穿透/解锁状态栏消失/App 死亡残影）；**M6.4**：310 二期 **EVIOCGRAB 锁屏独占触控**（未冻结 App 锁屏输入隔离）+主界面应用名截断；**M6.5**：audiod 315 孤儿会话两段式回收（客户端崩溃/OOM 杀/正常退出后会话完整回收，STATE 回干净无流基线）；**M6.6**：锁屏 310 三期——App 内手动息屏也触发锁屏 + 锁屏脏区全屏不透明底 + 300ms 重铺；**M6.7**：锁屏页自睡（空闲超时自动灭屏，294 遗留补；0.8.7 补刷吸收 fw_content 事故修复——拆分 watchdog+meow_audio 两行）；**M6.8**：310 四轮 锁屏自睡 min(系统息屏,30s)；**M6.9**：netmgrd 期4（SDK 自愿通道/forget/RSSI/AAAA 过滤/iptables 评估）+powermgr 期3（policy/标定工具）固化 + 327 M7.0b launcher 试点（电源菜单/Now Playing 控件化+主题薄壳+i18n 抽串）；历史：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`](LICENSE)）。本仓库为非官方第三方项目。
|
||
> 主仓**公开可克隆**：`https://git.yeij.top/AskaEth/MeowOS-For-R3P2.git`（维护者推送走
|
||
> `ssh://git@git.yeij.top:2222/AskaEth/MeowOS-For-R3P2.git`）。
|
||
> **第三方组件声明（LGPL）**：阅读器 `os.meow.reader` 静态链接 **libmobi（LGPL-3.0）**。
|
||
> 其 NOTICE + GPL-3.0 + LGPL-3.0 全文随 `.mpk` 的 `resources/licenses/` 分发（见
|
||
> `patch_v2/reader_app/NOTICE`、`patch_v2/reader_app/resources/licenses/`）；libmobi 在
|
||
> `build_reader.sh` 锁定 commit `906274205c11944b628da1c553b255acb1af7c55`；替换/重链指引见
|
||
> `patch_v2/reader_app/README_LGPL_RELINK.md`。阅读器自有代码仍为 Apache-2.0（LGPL §1 豁免）。
|
||
>
|
||
> **公开 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 全链路；2026-09-02 批次：真机四连症状（豆腐/歌词一行/封面加载/音量键 SIGKILL）+返回首页竞态 staging+内存瘦身（封面 8.28MB→0.78MB）+流媒体专项六项（档位保真/封面 4xx 不重试/收藏显隐/缓存命名迁移/topbar 位图图标）+三死因闭环（OOM/误杀/歌词栈溢出）+封面链分诊+风控加固（接口 120s 缓存+游客令牌）+**M6.10 批次**（批B UI/批C 播放后台/338 VIP3 档+多歌手/336 根因——每次 audio_out_open 建短连接致 audiod fd 风暴已修；卡上热更 `bef4b0e1`，内存 40→49.2MB OOM 疑 page cache 待真机取证）；**2026-09-03 桌面歌词/取色/蓝牙批**：桌面 Now Playing「播放页⇄歌词页」双页+歌词链路批1-5（SDK `meow_lyric` 通用歌词组件+`meow_lyric_view` 歌词页渲染控件+media 会话歌词数据源 `meow_media_lyric_*`/MSG_META_LYRIC+方向感知手势）+封面双色渐变取色（`meow_img_color`）+ncm 底部 mini 播放栏/播放模式三态+实时播放列表/列表项 8px 外距；**蓝牙 P0/P1/P2**（`aplay -D bluealsa` 真机出声打通/netmgrd BT_CTL 权威收口+launcher 蓝牙子页重做/audiod OUT_BT 输出目标+音量 AVRCP 隔离+alsa.conf DEV 自动识别））。**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）；
|
||
- 电源菜单、全局左缘返回手势、全屏提示线；
|
||
- 主界面（应用列表）、设置页；
|
||
- **锁屏（M6.2 起）**：`lock_screen.c` 4 位 PIN（`system.pin` 同源面板 sha256+salt）+ 息屏唤醒锁 `system.pin_lock_on_wake` + 错 5 锁 5 分钟持久化 + 电源菜单「锁定」（作废一次性绕过标志）+ 设置「安全→锁屏 PIN」页（设/改需旧、清免旧）+ `/tmp/meow_pin_unlock_once` 一次性解锁恢复口；M6.4 起锁屏用 **EVIOCGRAB 独占触控**杜绝输入穿透下层 App。
|
||
|
||
**渲染与 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.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）。
|
||
- **M6.2-6.4 新增（SDK 演进批次，meow_ui.a 逐批重链四 App，API 全部追加式零改动）**：**公共头拆分**（278：`meow_ui.h` 922→67 行伞头 + `include/` 16 子头，API 零改动、`meow_ui.a` md5 不变、三 App 免重链）；**布局/滚动/动画基座**（292：`meow_box` 线性布局纯计算器（固定/weight/wrap/对齐/嵌套，opt-in `meow_view_set_layout`）+ `meow_scroll` 滚动物理（速度采样+fling+边界回弹+snap）+ `meow_anim` 动画基座（静态池≤16+缓动+脏区联动，挂 on_tick 零开销））；**事件分发形式化**（293 §6.4：单一仲裁者——z 序自顶向下命中+模态哨兵+down 捕获+唯一焦点，dialog/sheet/list/scroll 已迁，穿透矩阵 M1-M4 全 PASS）；**ListView 虚拟化**（295 §5.5：vsource count/bind 数据源+固定 item 池（视口+2）+多行富 item+完全自绘钩子）；**字符串资源 i18n**（299 §13：`meow_str`/`meow_strf`/`meow_str_set_locale`，内嵌 zh_cn/en_us 双语+TF 覆盖表+locale 持久化）；**sb_icons 动作图标 + topbar 位图**（307：15 个 MD3 动作图标 `MEOW_ICON_*` + `meow_topappbar_set_item_icon`）；**`meow_img_downscale`**（308：图片降采样 ≤maxdim，流媒体客户端封面 8.28MB→0.78MB）。详见 `MEOW_APP_SDK.md` §5.5/§6.4/§12/§13 与 `docs/MEOWOS_SPEC_REF.md` §3。
|
||
- **M6.5-6.6 新增**：**SDK 矢量字**（316：`meow_ft_*` §10.1——把阅读器 R1/R2 已验证的 FreeType 管线整体上收到 SDK，按需读文件零整载 + glyph LRU 512 + 灰阶 blend565，与位图字库**并存**、App 显式调 `meow_ft_*` 才用，加载失败/无卡自动降级位图（不豆腐不崩）；不调 ft 的 App **链接零增量**（独立 .o + vendor 裁剪构建）；**SDK 演进主体收官**）；**audiod 孤儿会话两段式回收**（315，M6.5：客户端崩溃/OOM 杀（sig=9）/正常退出后会话完整回收，STATE 回干净无流基线）；**流媒体客户端 2026-09-02 批次**：**SIGSEGV 根因**（314：歌词解析栈上 227KB 临时数组 vs 128KB 线程栈→挪堆，真机复现修前 3.7s/修后连播两次过）；**封面链分诊与修复**（317：Referer+桌面 UA 解 403 + webp 魔数内容型先判不解码 + 200 解码失败=源站死对象返 JSON 错误体实锤 + 死链/403/webp 幂等快跳不重试 + 缩略图 `param=300y300`）+**封面死链兜底链**（原 picUrl 失败→web 端 song/detail 免登录重取活链→歌单封面兜底）+**歌词页封面等比居中**（contain，四周主题底，方图不再变形）；**`track/all` 接口验证否决**（318：该接口在服务端不存在，8 形态全业务码 404，维持 detail+song_detail 现状）；**外部接口地图**（319：流媒体客户端外部 API 调研笔记落盘 `devdocs/plan/`）；**风控加固**（320：接口响应 120s 短 TTL 缓存 + 游客 MUSIC_A 匿名令牌 + 死代码清理）。详见 `MEOW_APP_SDK.md` §10.1 与 `docs/MEOWOS_SPEC_REF.md` §3.5。
|
||
- **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`）。
|
||
- **面板批2 + 加固（2026-09-02）**：崩溃/日志中心 + 音频路由页 + 音量写经 clamp `vol_max` + 后端补 `reboot_reason`；**JSON 输出 UTF-8 加固**（`sA_str_n` 单遍校验、非法序列换 `?`、IPC 原始 JSON 门禁降级，防任一上游坏字节拖垮整页）；**overview 自校验纪律**：`/api/overview` 服务端发出前先自查/严格平衡检查（坏则 dump `/tmp/overview_bad.json` + 500），前端非 JSON 自动回传原始字节到 `/api/debug/report_bad_json`（落 `/tmp/overview_client_bad.txt`）；**教训**：后端 `jv_parse` **容忍尾随垃圾**，而浏览器 `JSON.parse` **不容忍**——net 块多写一个 `}` 即「Extra data」破页（batch2 DNS 并入事故），故自校验必须做与浏览器口径对齐的**严格括号/闭合平衡检查**。
|
||
- **⚠️ 鉴权默认关**：内网信任模型（`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**（入库脚本）
|
||
```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 × 明暗 + 背景源）** |
|
||
| `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 连续内存）。
|
||
- 本仓库为**非官方第三方项目**，修改并与官方固件共存；刷机有一定的变砖风险（可用官方固件刷回），请自行评估。所有「真机验证」项请以实机为准。
|