docs: 仓库文档同步 M6.4(0.8.4)——README 版本行+新能力(SDK 演进批次/锁屏 PIN/面板批2+overview 自校验)；SPEC_REF 补 SDK §3.5 扩展模块速查+system.pin 锁屏键+面板 batch2/UTF-8 加固

2026-09-02 09:12:56 +08:00
1 parent 54e737a4a2
commit 19f7e59927
@@ -3,7 +3,7 @@
 > 把 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、包管理、媒体会话、独占音频服务、网页面板、流媒体客户端的完整第三方系统**。
+> 版本：**M6.4（0.8.4，已自刷验收）**（M6.1→M6.4 全链自刷验收——**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 锁屏输入隔离）+主界面应用名截断；历史：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)）。本仓库为非官方第三方项目。
 >
@@ -79,7 +79,8 @@ init (rcS)
 - **状态栏（统一系统进程渲染）**：由 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（状态栏/返回/通知中心）始终可用。
@@ -115,6 +116,7 @@ init (rcS)
 - **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，ncm 封面 8.28MB→0.78MB）。详见 `MEOW_APP_SDK.md` §5.5/§6.4/§12/§13 与 `docs/MEOWOS_SPEC_REF.md` §3。
 - **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/状态机走新增挂载器。
@@ -181,7 +183,8 @@ init (rcS)
 - **后端**：`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`。
+- **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`。
@@ -13,7 +13,8 @@
 - **主机名**：设置键 `system.hostname`（SET_STR，默认 `meowos`；RFC1035 首标签），`S89meow_svcd` 开机读 settings `sethostname`；供自研 mDNS 应答器公布 `<host>.local` `[SYSTEM_SETTINGS §1][mips-repo/bins/meow_mdns]`
 - `/etc/meowos_version`：版本唯一来源（launcher 运行时 `load_meowos_version` 读；`MEOWOS_VERSION` 宏仅作 dev 占位兜底）`[DEV_NOTES #4]`
 - **`/data/meow_boot_default`：开机默认权威标记（O_TRUNC 单值：`0`=MeowOS / `1`=HiByOS）**。由 launcher `meow_settings_save()` 在保存 `boot.default` 时同步写；bootmenu `set_boot_default_meow()`（写 0）/ launcher `set_boot_default_hiby()`（写 1）同文件同语义；bootmenu 开机读它定默认；init 读入不触发、不反向覆盖；`meow.conf` 不再承担 boot_default `[M2.61 同步修复][README][meow_settings.c][meow_bootmenu.c]`
- `/tmp`：tmpfs，开机清空；开机模式标记 `/tmp/meow_boot_mode`、电源菜单 `/tmp/meow_power_menu{,_active}`、app 沉浸 `/tmp/meowapp_state` `[BOOT_SELECTOR §1][KEY_CONTROL §9][APPS §3.5]`
+- `/tmp`：tmpfs，开机清空；开机模式标记 `/tmp/meow_boot_mode`、电源菜单 `/tmp/meow_power_menu{,_active}`、app 沉浸 `/tmp/meowapp_state`、**锁屏** `/tmp/meow_pin_unlock_once`（一次性解锁恢复口，launcher 锁屏页消费放行一次、重启自消）/`/tmp/meow_pin_locked`（电源菜单「主动锁」标志，重启消失）`[BOOT_SELECTOR §1][KEY_CONTROL §9][APPS §3.5][WORK_STATE 2026-09-02]`
 - **锁屏 PIN（M6.2 起，与面板同源 `system.pin`，规范 `SYSTEM_SETTINGS` 锁屏小节）**：设置键 `system.pin`=`<salt_hex>:<sha256_hex(salt||pin)>`（sha256+salt，格式与面板 `panel.pin` 全等，**绝无明文**；空=未设=锁屏关；`panel.pin` 已设时锁屏接受并首次验证成功后并入本键）+`system.pin_lock_on_wake`（息屏唤醒后锁屏，int 0/1，默认 1=开；开机不锁）+`system.pin_lock_until`（错 PIN 锁定的 epoch 截止戳，持久化防 launcher 重启清零）+`system.pin_fails`（连续错 PIN 计数 0-4，达 5 触发锁定并清零，持久化）。清/改：设置「安全→锁屏 PIN」页——设/改需旧 PIN 一次、**清除免旧 PIN**（物理持机即授权，仅二次确认）、`system.pin_lock_on_wake` 开关；**兜底**：SSH root 删 `system.pin` 键即解锁（无其它后门）。`[SYSTEM_SETTINGS §1][WORK_STATE 2026-09-02]`
 - 日志启动缓冲 `/tmp/meow_boot.log`（256KB 滚动，卡出现后自动迁卡）`[APPS §4.5]`
 - IPC socket：`/usr/data/meow_ipc.sock`（AF_UNIX SOCK_STREAM，0666，backlog 4）`[FRAMEWORK_DESIGN §1][WORK_STATE]`
 - 专项服务 IPC socket：`/usr/data/meow_perf.sock`（meow_svc_perf，收 `MSG_PERF_QUERY→RESULT`）与 `/usr/data/meow_power.sock`（meow_svc_power，收 `MSG_POWER_ACTION→STATUS`），均 0666、可 `--sock`/`MEOW_IPC_{PERF,POWER}_SOCK` 覆盖；power 服务端以 `SO_PEERCRED uid==0` 基础鉴权 `[meow_svc_perf.c][meow_svc_power.c][meow_ipc.h]`
@@ -126,6 +127,18 @@
 - **兼容**：既有 `meow_btn/slider/switch/list_create` 签名一字不改（Options/状态机走新增挂载器）；`meow_ui_theme`/`meow_widget` 结构变化 = **`meow_ui.a` ABI 变化** → 需同步重编 hello（§5.8.8）。
 - **主题增强（§8.1）**：主题 = **顶级风格族 `ui.style`（md3/miuix）× 明暗 `display.theme`（dark/light）** 共同决定「整套配色+控件形态+背景底」；`display.background` 为「style×mode」派生的**可选背景底选项集**（非独立维度）；状态栏图标随 `ui.style` 换集。⚠️ **`miui`/`miuix` 命名待定案（保留，勿拍板）**：`MEOW_APP_SDK §8.1` 用 `miuix`；`SYSTEM_SETTINGS §1` 注明 `meow_settings.c g_defs` 现值 `"md3,miui"`（label "Material You,MIUI"），实现时把 `g_defs` 的 `miui` 对齐为 `miuix`（**MIUIx 未实现，当前仅 md3 生效**）。
 ### 3.5 SDK 扩展模块速查（构造/滚动/动画/i18n/图标库/事件分发/ListView 虚拟化/图片降采样）
 > 权威签名 = `patch_v2/sdk/include/meow_ui_{box,anim,scroll,str,input,widgets,image}.h`；蓝本 `MEOW_APP_SDK.md` §5.5/§6.4/§12/§13。**本批全部追加式 API**——既有 App/签名零改动，`meow_ui.a` 变化需重链四 App（hello/files/ncm/reader）。
 - **§12.1 线性布局 `meow_box`（292，纯布局计算器非控件，opt-in `meow_view_set_layout`）**：`meow_box_new(dir)`（`MEOW_BOX_H/V`）/`_free`/`_set_rect`/`_set_padding`/`_set_gap`/`_set_align(main_align,cross_align)`；子项 `meow_box_add(b,w,size,weight)`/`_add_ex`（WRAP 用 min/preferred+measure 回调）/`_add_sub`（嵌套）；`size`=`MEOW_BOX_FIXED/WEIGHT/WRAP`；`align`=`START/CENTER/END/SPACE_BETWEEN/AROUND/EVENLY`、`cross`=`START/CENTER/END/STRETCH`；求解 `meow_box_arrange(b)` 把子控件 x/y/w/h 写进 `meow_widget`（`meow_widget_set_rect`）。定长 items（≤`MEOW_BOX_MAX_CHILD=24`）+嵌套深度 ≤16 静态栈，arrange 零 malloc。
 - **§12.2 动画基座 `meow_anim`（292）**：`meow_anim_start(const meow_anim_desc*)`（desc：`from/to/duration_ms/ease/update/done/ctx`；start 即 value=from+回调一次 update(0)）/`_cancel`（回调 done(canceled=1)）/`_active`/`_value`/`_set_region(x,y,w,h)`（动画每 tick 只 flush 影响区，不整屏）；`meow_ease`=`LINEAR/OUT/IN_OUT/OVERSHOOT`+`meow_ease_apply(e,t)`；节拍 `meow_anim_tick()`（挂 on_tick / `meow_ui_feed_tick`，无动画零开销）+`meow_anim_count()`；静态池 ≤`MEOW_ANIM_MAX=16`。
 - **§12.3 滚动物理 `meow_scroll`（292）**：`meow_scroll_create(set,max,get,redraw,ctx)`/`meow_scroll_wrap(list,is_listview)`（is_listview：1=W_LISTVIEW /0=W_LIST|LazyColumn|LazyRow，redraw 只 flush 控件视口区）/`_free`/`_track(dy,t_ms)`（跟手+速度采样，内部 set_scroll clamp）+`_fling()`（加权初速+ease-out 推进+边界回弹）/`_stop`/`_velocity`/`_active`/`_offset`/`_set_snap(step)`/`_set_friction(tau_ms，默认180)`。拖动态保持现状不变，fling 由 §12.2 驱动。
 - **§13 字符串资源 / i18n `meow_str_*`（299）**：`meow_str(id)` 按当前 locale 取串（返回静态、**永不 NULL**、未知 id 原样返回 id）/`meow_strf(out,outsz,id,...)`（snprintf 语义）/`meow_str_set_locale(locale)`（切 `"zh_cn"|"en_us"`，即时生效+重载 TF 覆盖表+best-effort 持久化 `ui.locale`）/`meow_str_locale()`。四层取值：TF 覆盖表（`<pkg>/strings/<locale>.txt`）> 内嵌当前语言 > 内嵌内置默认(zh_cn) > 原样 id。热路径零 malloc；id 形如 `域.名`（common.ok / player.pause）。不做复数/BiDi/RTL/动态字回退（当前为「按 locale 取整串」雏形）。
 - **§6.4 事件分发形式化（293，单一仲裁者）**：模态作用域 `meow_ui_modal_begin/end/active/depth`（作用域存在时下层收不到触摸，未命中面板的事件由背板消费恒返回哨兵）；自上而下命中 `meow_ui_hit_topdown(x,y)`/`meow_ui_widget_hit`；手势捕获 `meow_ui_gesture_begin/owner/end`（down 命中即捕获到 up，move/up 只发捕获目标）；唯一焦点 `meow_ui_focus_acquire/release/owner/tap/set_lost_cb`（点外释放+回调+滚动容器转移）。传播矩阵：模态>z 序自顶向下；命中即消费；向下穿透仅当未命中。
 - **§5.5 ListView 虚拟化（295，W_LISTVIEW 扩展层，API 追加式）**：`meow_listview_set_vsource(lv,count_fn,bind_fn,ctx)`（count 每帧实时查、bind 仅在行进视口时调一次；count_fn/bind_fn 均非 NULL 才切 pool 模式，否则回退 src2）；`meow_lv_item{title,subtitle,icon,icon_kind,right,on,enabled,section,user}`；`meow_listview_set_item_renderer(lv,lines,show_icon,show_right)`/`_set_item_tier`（单行 48/双行 56）/`_set_item_draw`（完全自绘覆盖默认 renderer，state=`MEOW_LISTVIEW_ST_{SELECTED,PRESSED,DISABLED}`）；固定池=视口+2 槽，行离开视口不销毁、同 index 命中同槽不重绑；段头 `item->section=1`。
 - **图标库 `sb_icons`（307，Material Symbols Rounded / MD3，单通道 alpha 32×32，生成 `tools/gen_action_icons.py`）**：索引只追加——状态栏 `MEOW_SB_ICON_WIFI=0..BATT_CHG=14` 原样保留；**动作** `MEOW_ICON_SETTINGS=15..MEOW_ICON_HEART=29`（设置/刷新/搜索/播放/暂停/上下曲/返回/关闭/添加/勾选/歌词/列表/下载/收藏），经 `meow_topappbar_set_item_icon(w,idx,MEOW_ICON_*)` 使 W_TOPAPPBAR 动作项画位图（`layout 见 meow_ui_widgets.h`）。
 - **图片降采样 `meow_img_downscale(img,maxdim)`（308）**：把解码图降到 ≤maxdim 边长以省内存（ncm 封面 1448² RGBA 8.28MB→cap≤480px→0.78MB，-7.65MB），返回新 `meow_img*`。
 ---
 ## 4. SDK 之外系统组件
@@ -150,6 +163,7 @@
  - **M2.73 悬垂指针修复（md5 `da6ebc66`）**：`scan_and_reconcile` 用 `*s=tmp` 整体拷贝后，`s->argv[]` 仍指向已销毁的 `tmp` 栈帧 → `execv`/`/proc/pid/cmdline` 错乱。修法：新增 `svc_rebuild_argv(s)`，赋值/`memmove` 左移后把 `s->argv[]` 重定位到 `s->exec`/`s->argbuf` 自身成员（删除一个服务后同 tick 内被拉起不再用错位 argv）。`[meow_svcd.c]`
 - **卡上外部工具 = `MeowOS/opt/`**（`{bin,nyai,sources.list}, lib/, tools/`）：MeowOS 启动时从卡加载，拔卡降级不崩。**`MeowOpt` 已废弃并入此处**；mDNS 已改为自研 `meow_mdns`（固件 `/usr/bin`），不再放卡。`[DEV_NOTES][meow_svcd.md]`。**MeowPanel 本体 = `MeowOS/opt/MeowPanel/`**（后端+前端，svcd 托管 `MeowOS/services.d/meowpanel.conf`，无卡跳过、系统核心不依赖，不进固件；md5 `8108852f`（nyai 路径修复）→ 阶段C 后 新 md5（见 `patch_v2/meowpanel/README.md`），详见 `patch_v2/meowpanel/README.md`）。
 - **MeowPanel（外置 TF 卡 Web 面板，M2.73 已落地，阶段 C 实时画面+遥控已落地）**：单进程 HTTP/JSON 后端（8080）+ 静态托管（`/`→index.html、`/assets/*`）+ `meow_svc_perf`/`meow_svc_power` IPC 客户端（读侧透传 perf 聚合、动作侧经 power）+ `settings.conf` 设置镜像（`key = value` 带空格 + 精确匹配）+ 文件白名单（`MeowOS/Music/MeowData/MeowAPPs/book`，`..` 逃逸→403）+ 应用（`nyai install/export/remove`，包名=`app.json.package`，`nyai` 固件内置 `/usr/bin/nyai` 优先+卡上回退）+ 按键注入（evdev，只音量/电源/播放/上下曲，**禁返回158/主页172/确认28/退出96**）+ 日志（`MeowOS/logs`）。M2.73：系统页「以太网」→「**蓝牙**」栏（无网口有蓝牙）；**OTA 检查升级 bug 已修**（改读 `GET /api/system` 的 `ota`，不再误触 `POST /api/system/ota` 升级）。**M2.78+ 新增**：可选密码鉴权（agent-196，默认关）、通知中心后端 `/api/notifications`（TF 归档环形 200 条）、文件域 4 bug 修复 + 上传 8MB 上限 + 双重白名单（agent-182）**。**M2.84-88 阶段 C**（agent-224）：`/api/screen.jpeg`（fb0 活动帧→自研 JPEG 编码器）+ `/api/input/tap`（坐标注入，本机触摸优先 5s 仲裁）+ 屏幕增量帧 `?delta=1`（8x8 块比对，近静态 27KB→804B，agent-234）+ `/api/notifications` 实时化（优先 IPC 读 launcher 活跃集 source:ipc，agent-234）。**252 新增（2026-09-01）**：`/api/audio`（audiod MSG_AUDIO_QUERY→STATE 只读透传，不在时 available:false）+ 前端「音频」页（5s 轮询只读）与「字体」页（列表/上传进度/导出/409 冲突确认 force 重试）。**⚠️ 鉴权默认关**（内网信任模型；`reboot/shutdown/ota/apps/删除/上传` 危险端点勿暴露公网，power 侧有 `SO_PEERCRED uid==0` 基础校验）。`[patch_v2/meowpanel/][devdocs/plan/MEOWPANEL_PROTOCOL.md]`
 - **面板批2 + 加固（2026-09-02）**：崩溃/日志中心 + 音频路由页 + 音量写经 clamp `vol_max` + 后端补 `reboot_reason`；**JSON 输出 UTF-8 加固**（`sA_str_n` 单遍校验、非法序列换 `?`、IPC 原始 JSON 门禁降级，防任一上游坏字节拖垮整页，d7bf62f）。**overview 自校验纪律**：`/api/overview` 服务端发出前先自查（jv_parse）+ 与浏览器口径对齐的**严格平衡检查**，坏则 dump `/tmp/overview_bad.json` + 500（908fc53/67aa5fc/54e737a）；前端非 JSON 自动回传原始字节到 `/api/debug/report_bad_json`（落 `/tmp/overview_client_bad.txt`，7a40586/524e5d6）；**教训**：后端 `jv_parse` **容忍尾随垃圾**，浏览器 `JSON.parse` **不容忍**——net 块多写一个 `}` 即「Extra data」破页（批2 DNS 并入事故），故自校验必须严格括号/闭合平衡。`[patch_v2/meowpanel/][devdocs/plan/MEOWPANEL_PROTOCOL.md][WORK_STATE 2026-09-02]`
 - **mDNS 应答器 = `meow_mdns`（自研，已拍板替代完整 mdnsd）**：`mips-repo/bins/meow_mdns/`，**IPv4-only**（内核无 IPv6，完整 mDNSResponder/SAResponder 均 `socket(AF_INET6)` 失败），mipsel 静态 ~79KB（md5 b23de7ce）。**进固件 `/usr/bin/meow_mdns`**（不入卡），由 meow_svcd 托管（板载 `/usr/data/meow/services.d/meow_mdns.conf`，`trigger=boot`、root 即可绑 5353/组播，`cap=` 空）。功能：join `224.0.0.251:5353`，应答 `<host>.local` A（wlan0 IPv4）/`_ssh._tcp` PTR/SRV/TXT/`_services._dns-sd` PTR；支持 `MEOW_MDNS_HOST`/`_ADDR`/`_PORT`/`_TTL`/`_CF`/`_QD`/`_MCAST`/`_MIF`/`_DBG`。⚠️ **手机热点隔离**：设备→主机组播被热点丢弃，avahi 只收组播应答 → 该热点下 `avahi-resolve <host>.local` 超时（网络层限制，非应答器缺陷），主机需 DNS 兜底 `[mips-repo/bins/meow_mdns/manifest.md][meow_svcd.md]`。
 - `meow_settings_*`（设置后端，已定）/`meowcli`/`meow_sys_devattr`/`meow_devattr_set` `[MEOWOS_API]`
 - **独占音频守护 `meow_audiod`（M2.90 已落地，规范 `devdocs/plan/AUDIOD_DESIGN.md`）**：板载 `/usr/bin/meow_audiod`，svcd 托管（板载 `services.d/meow_audiod.conf`，trigger=manual；launcher 确认 MeowOS 模式后拉起；**启动门控：mode≠meow → exit(0)，HibyOS 下不存在**）。IPC `/usr/data/meow_audio.sock`（帧层复用 meow_ipc.h，号段 0x00C0-0x00CA：OPEN/OPEN_ACK/WRITE/PAUSE/RESUME/STOP/PREEMPTED/QUERY/STATE/ROUTE/VOLUME）。**独占+抢占**（后开赢，旧流收 PREEMPTED；socket EOF=回收；软混音已否决，留接口位）。**DAC 原生率跟随不做 SRC**；格式归一 S16 直通/S32 升位/mono 复制；切率 mute-重配-恢复。**meow_route 已并入为路由线程并退役独立服务**（⚠️ 退役服务要清板载+TF 双源 conf，否则旧 conf 会双写路由）。**CLI `meow_audio`**（root 免鉴权）：`status`/`tone [freq] [ms] [rate]`（正弦测试音，排查无声不开 App）/`route <0|2|3>`/`vol [0-100]`。SDK 客户端 `meow_audio_open/write/pause/close/query/on_preempt`（`meow_ui_audio.c`，懒连接+EPIPE 标死；无 audiod → -ENOENT 不隐式直开，`MEOW_AUDIO_DIRECT=1` 仅调试）。**M2.91-97 加固批**：①**开机武装 hbc3000 FPGA**（M2.91：路由线程启动无条件写 Output Port Switch 4.4→3/3.5→2/无→4，同值先写 5 强制重烧——根治「未烧 FPGA 时 PCM 第二次 `hbc3000_start` 内核硬挂死」，调查底稿 `devdocs/plan/AUDIO_HANG_INVESTIGATION.md`）②**长流护栏**（M2.93：ring 有界等待/cond timedwait/popen 有界收割/O_NONBLOCK+poll 写/wedge 自救/心跳 watchdog）+**几何收窄 period=1024×4**（M2.94：驱动默认巨 buffer 致桥周期中断稀缺 wedge、播 ~12s 停摆；tonepcm2 矩阵 60s 零 stall 实证）③**音量反转**（M2.95：CS43198 音量寄存器=衰减量，四路统一 `dac=255-pct*255/100`）④**炸耳安全**（M2.96：`dac_vol_mute` 写 255 真静音，旧写 0=最大响度）⑤**电平监控**（261，待 M2.97 固件化：播放线程 ~100ms 窗口整数 RMS/peak dBFS（deci-dB，逐帧判边界，-990=-inf）、`MSG_AUDIO_STATE` 追加 `rms=/peak=/lvlseq=`（ABI 兼容）、流活跃时 1s 节拍写 TF `MeowOS/logs/audio_monitor_<bootts>.log`、CLI `meow_audio monitor [秒]` 文本电平条）。`[patch_v2/meow_audiod/]`